Linear OAuth tokens expire after 24h - missing proper refresh token flow implementation

[gudzenkov]

Problem Description

Linear OAuth access tokens expire after 24 hours, but Cyrus does not implement the proper refresh token flow as documented in the Linear OAuth 2.0 documentation. This causes authentication failures and requires manual re-authorization daily.

Current Behavior

• Linear OAuth tokens (LINEAR_OAUTH_TOKEN) expire after 24 hours
• When tokens expire, Cyrus fails with authentication errors
• Users must manually re-authorize to continue using Cyrus
• No automatic refresh token mechanism is implemented

Expected Behavior

According to Linear's OAuth documentation, Cyrus should:

1. Store the refresh_token received during initial authorization
2. When receiving a 401 error or detecting token expiration, automatically use the refresh token to obtain a new access token
3. Update the stored access token with the new one
4. Continue operations without user intervention

Steps to Reproduce

1. Set up self-hosted Cyrus App with Linear OAuth authentication
2. Deploy CloudFlare Worker Proxy
3. Run local Cyrus CLI, authorize with Linear OAuth
4. Wait 24 hours for the token to expire
5. Attempt to run Cyrus with the expired token
6. Observe authentication failure requiring manual re-authorization

EdgeWorker error: Error: Linear authentication failed for Portfolio. The Linear OAuth token may have expired or been revoked. Please re-authenticate with Linear to obtain a new token.
    at WebhookTransport.registerWebhook (file:///opt/cyrus/packages/ndjson-client/dist/transports/WebhookTransport.js:137:39)
    at process.processTicksAndRejections (node:internal/process/task_queues:105:5) {
  code: 'LINEAR_AUTH_FAILED',
  isAuthError: true
}

❌ Linear authentication failed for repository: sandbox
   Workspace: 18544a12-e52c-4e40-81e1-766e0c46650e
   Error: Linear authentication failed for Portfolio. The Linear OAuth token may have expired or been revoked. Please re-authenticate with Linear to obtain a new token.

   To fix this issue:
   1. Run: cyrus refresh-token
   2. Complete the OAuth flow in your browser
   3. The configuration will be automatically updated

❌ Failed to start edge application: Failed to connect any repositories. Please check your configuration and Linear tokens.

Technical Details

The Linear API refresh token flow requires:

POST https://api.linear.app/oauth/token
Content-Type: application/json

{
  "grant_type": "refresh_token",
  "refresh_token": "<stored_refresh_token>",
  "client_id": "<client_id>",
  "client_secret": "<client_secret>"
}

Impact

• Daily manual re-authorization disrupts automated workflows
• Breaks continuous integration/deployment pipelines
• Reduces the reliability of Cyrus as an automation tool

Related Issues

• Cyrus shutting down with authentication errors from linear #265: Authentication errors from Linear (symptom but not root cause)
• PR Improve Linear token error handling and centralize config location #85: Added cyrus refresh-token command but doesn't implement automatic refresh flow

Suggested Solution

Implement automatic refresh token handling:

1. Store refresh tokens securely alongside access tokens
2. Implement token refresh logic before API calls or on 401 responses
3. Automatically retry failed requests after token refresh
4. Only require user re-authorization if refresh token is invalid/expired

[gudzenkov]

Additional Technical Context

Proxy Mode Token Storage

The proxy-worker does store both tokens in Cloudflare KV:

• KV Namespace: OAUTH_TOKENS
• Storage: Both accessToken and refreshToken are encrypted and stored
• Gap: KVOAuthStorage.refreshToken() method exists but throws "Token refresh not yet implemented"

Direct Mode Token Storage

Only stores linearToken (access token) in .cyrus/config.json - completely ignores refresh token (see #286)

OAuth Flow Duplication

The OAuth authorization flow is duplicated in:

• apps/proxy-worker/src/services/OAuthService.ts (proxy mode)
• packages/edge-worker/src/SharedApplicationServer.ts (direct mode)

This duplication leads to inconsistent token handling between modes.

Updated Suggested Solution

1. Create shared OAuth core package to eliminate duplication and ensure consistent token handling
2. For Proxy Mode: Implement the existing refreshToken method in KVOAuthStorage
3. For Direct Mode: Add refresh token storage and implement secure token management
4. Common: Implement automatic token refresh on 401 responses using Linear's refresh token endpoint
5. Architecture: Move OAuth logic to a shared package to maintain consistency across deployment modes

[Connoropolous]

are you self hosting? are you using the cloudflare approach to self hosting?

we havent yet configured for the refresh tokens, only recently linear introduced them. you can resolve the issue in the short run, until we implement it, by disabling the refresh tokens option on the Linear app you have set up and configured, if youve done that and are self-hosting.

[gudzenkov]

@Connoropolous
Yes, self-hosting with CloudFlare proxy, while preparing cloud deployment with direct mode.

I was actually writing Specs and got a draft PR to address this.
I'd love to collaborate on this. How do you manage Roadmap and Architecture Design decisions?

[gudzenkov]

OAuth 2.0 Refresh Token - Acceptance Criteria

Shared OAuth Package

• Core Library: Extract OAuth logic to packages/linear-oauth shared by proxy and edge
• Storage Interface: Implement pluggable storage adapter (KV for proxy, encrypted file for edge)
• Refresh Logic: Share token refresh implementation between both modes
• Error Handling: Unified OAuth error codes and retry logic

Proxy Worker

• Token Refresh: Implement /oauth/refresh endpoint that exchanges refresh_token for new access_token
• Authentication: Endpoint /oauth/refresh requires Authorization: Bearer {edge_token} header
• Auto-Refresh: Detect expired tokens (<5 min remaining) and refresh automatically
• Storage: Store refresh & access tokens separate in encrypted KV with specific expiration for each
• Error Handling: Return 401 when refresh fails, requiring re-auth

Edge Worker (Proxy Mode)

• 401 Detection: Catch Linear API 401 errors and request token refresh from proxy
• Authentication: Authorize with Proxy /oauth/refresh endpoint with Bearer edge_token
• Auto-Retry: Retry failed requests with refreshed token from proxy
• Shared Token Update: Update all repos using same token without disconnecting webhooks
• Fallback: Switch to direct mode refresh if proxy unavailable

Edge Worker (Direct Mode)

• 401 Detection: Catch Linear API 401 errors and refresh locally using stored refresh_token
• Auto-Retry: Retry failed requests with refreshed token
• Token Storage: Store tokens in encrypted file or in-memory, never in plaintext config.json
• Fallback: Notify user when refresh fails and pause affected repos

CLI

• Mode-Aware Refresh: cyrus refresh-token uses proxy in proxy mode, edge endpoint in direct mode
• Authentication: Obtain and save edge_token from Proxy during initial setup
• Smart Deduplication: Refresh each unique token only once, update all repos using it
• Browser Fallback: Open browser only when programmatic refresh fails
• Secure Storage: Never write tokens to config.json, use secure storage

Integration

• E2E Flow: 401 error → refresh token → update storage → retry request
• Performance: Complete refresh within 3 seconds
• Security: Encrypt tokens in storage and transit
• Monitoring: Log all refresh attempts with outcome

Migration

• Token Detection: Identify existing plain tokens in config.json on startup
• Secure Migration: Move tokens to environment variables or secure storage
• Backward Compatibility: Support both old and new storage during transition period
• User Consent: Prompt before migrating existing tokens

[Connoropolous]

@gudzenkov thanks for stepping up to contribute!

So far we've done ad-hoc code review of submitted PRs but Id like to build up the visible roadmap management and contribution process.

I am coming back from some time off. will review your proposal above and offer a tentative sign off on a direction!
expect within 24 hours