@fink-andreas/pi-linear-tools 0.1.0 → 0.2.1

package/src/auth/oauth.js

@@ -0,0 +1,281 @@
+/**
+ * OAuth 2.0 client for Linear authentication
+ *
+ * Implements OAuth 2.0 Authorization Code flow with PKCE for Linear.
+ * Uses public client mode (no client_secret).
+ */
+
+import { debug, warn, error as logError } from '../logger.js';
+
+// OAuth configuration
+const OAUTH_CONFIG = {
+  // Linear OAuth endpoints
+  authUrl: 'https://linear.app/oauth/authorize',
+  tokenUrl: 'https://api.linear.app/oauth/token',
+  revokeUrl: 'https://api.linear.app/oauth/revoke',
+
+  // Client configuration
+  clientId: 'a3e177176c6697611367f1a2405d4a34',
+  redirectUri: 'http://localhost:34711/callback',
+
+  // OAuth scopes - minimal required scopes
+  scopes: ['read', 'issues:create', 'comments:create'],
+
+  // Prompt consent to allow workspace reselection
+  prompt: 'consent',
+};
+
+/**
+ * Build the OAuth authorization URL
+ *
+ * @param {object} params - OAuth parameters
+ * @param {string} params.challenge - PKCE code challenge
+ * @param {string} params.state - CSRF state parameter
+ * @param {string} [params.redirectUri] - Optional override for redirect URI
+ * @param {string} [params.scopes] - Optional override for scopes
+ * @returns {string} Complete authorization URL
+ */
+export function buildAuthorizationUrl({
+  challenge,
+  state,
+  redirectUri = OAUTH_CONFIG.redirectUri,
+  scopes = OAUTH_CONFIG.scopes,
+}) {
+  const url = new URL(OAUTH_CONFIG.authUrl);
+
+  // Required OAuth parameters
+  url.searchParams.append('client_id', OAUTH_CONFIG.clientId);
+  url.searchParams.append('redirect_uri', redirectUri);
+  url.searchParams.append('response_type', 'code');
+  url.searchParams.append('scope', scopes.join(' '));
+
+  // PKCE parameters
+  url.searchParams.append('code_challenge', challenge);
+  url.searchParams.append('code_challenge_method', 'S256');
+
+  // Security parameters
+  url.searchParams.append('state', state);
+
+  // Force consent screen (allows workspace selection)
+  url.searchParams.append('prompt', OAUTH_CONFIG.prompt);
+
+  debug('Built authorization URL', {
+    url: url.toString(),
+    clientId: OAUTH_CONFIG.clientId,
+    redirectUri,
+    scopes: scopes.join(' '),
+  });
+
+  return url.toString();
+}
+
+/**
+ * Exchange authorization code for access token
+ *
+ * @param {object} params - Token exchange parameters
+ * @param {string} params.code - Authorization code from callback
+ * @param {string} params.verifier - PKCE code verifier
+ * @param {string} [params.redirectUri] - Optional override for redirect URI
+ * @returns {Promise<object>} Token response with access_token, refresh_token, expires_in, scope
+ */
+export async function exchangeCodeForToken({
+  code,
+  verifier,
+  redirectUri = OAUTH_CONFIG.redirectUri,
+}) {
+  debug('Exchanging code for token', { redirectUri });
+
+  // Build request body (form-urlencoded as required by OAuth spec)
+  const body = new URLSearchParams({
+    grant_type: 'authorization_code',
+    code: code,
+    redirect_uri: redirectUri,
+    client_id: OAUTH_CONFIG.clientId,
+    code_verifier: verifier,
+  });
+
+  try {
+    const response = await fetch(OAUTH_CONFIG.tokenUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        'Accept': 'application/json',
+      },
+      body: body.toString(),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      logError('Token exchange failed', {
+        status: response.status,
+        statusText: response.statusText,
+        response: errorText,
+      });
+
+      throw new Error(
+        `Token exchange failed: ${response.status} ${response.statusText}`
+      );
+    }
+
+    const data = await response.json();
+
+    debug('Token exchange successful', {
+      hasAccessToken: !!data.access_token,
+      hasRefreshToken: !!data.refresh_token,
+      expiresIn: data.expires_in,
+      scope: data.scope,
+    });
+
+    // Validate required fields
+    if (!data.access_token) {
+      throw new Error('Token response missing access_token');
+    }
+
+    if (!data.refresh_token) {
+      throw new Error('Token response missing refresh_token');
+    }
+
+    if (!data.expires_in) {
+      throw new Error('Token response missing expires_in');
+    }
+
+    return data;
+  } catch (error) {
+    logError('Token exchange error', {
+      error: error.message,
+      stack: error.stack,
+    });
+    throw error;
+  }
+}
+
+/**
+ * Refresh access token using refresh token
+ *
+ * @param {string} refreshToken - Refresh token from initial token response
+ * @returns {Promise<object>} New token response with access_token, refresh_token, expires_in, scope
+ */
+export async function refreshAccessToken(refreshToken) {
+  debug('Refreshing access token');
+
+  const body = new URLSearchParams({
+    grant_type: 'refresh_token',
+    refresh_token: refreshToken,
+    client_id: OAUTH_CONFIG.clientId,
+  });
+
+  try {
+    const response = await fetch(OAUTH_CONFIG.tokenUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        'Accept': 'application/json',
+      },
+      body: body.toString(),
+    });
+
+    if (!response.ok) {
+      const errorData = await response.json().catch(() => ({}));
+
+      debug('Token refresh failed', {
+        status: response.status,
+        error: errorData.error,
+        errorDescription: errorData.error_description,
+      });
+
+      // Handle specific OAuth errors
+      if (errorData.error === 'invalid_grant') {
+        // Refresh token expired or revoked
+        throw new Error(
+          'invalid_grant: Refresh token expired or revoked. Please re-authenticate.'
+        );
+      }
+
+      throw new Error(
+        `Token refresh failed: ${response.status} ${response.statusText}`
+      );
+    }
+
+    const data = await response.json();
+
+    debug('Token refresh successful', {
+      hasAccessToken: !!data.access_token,
+      hasRefreshToken: !!data.refresh_token,
+      expiresIn: data.expires_in,
+    });
+
+    // Validate required fields
+    if (!data.access_token) {
+      throw new Error('Refresh response missing access_token');
+    }
+
+    if (!data.refresh_token) {
+      throw new Error('Refresh response missing refresh_token');
+    }
+
+    if (!data.expires_in) {
+      throw new Error('Refresh response missing expires_in');
+    }
+
+    return data;
+  } catch (error) {
+    logError('Token refresh error', {
+      error: error.message,
+      stack: error.stack,
+    });
+    throw error;
+  }
+}
+
+/**
+ * Revoke a token (access or refresh token)
+ *
+ * @param {string} token - Token to revoke
+ * @param {string} [tokenTypeHint] - Optional hint: 'access_token' or 'refresh_token'
+ * @returns {Promise<void>}
+ */
+export async function revokeToken(token, tokenTypeHint) {
+  debug('Revoking token', { hasTokenHint: !!tokenTypeHint });
+
+  const body = new URLSearchParams({
+    token: token,
+    client_id: OAUTH_CONFIG.clientId,
+  });
+
+  if (tokenTypeHint) {
+    body.append('token_type_hint', tokenTypeHint);
+  }
+
+  try {
+    const response = await fetch(OAUTH_CONFIG.revokeUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+      },
+      body: body.toString(),
+    });
+
+    if (!response.ok) {
+      warn('Token revocation failed', {
+        status: response.status,
+        statusText: response.statusText,
+      });
+      // Don't throw - revocation is best-effort
+      return;
+    }
+
+    debug('Token revoked successfully');
+  } catch (error) {
+    warn('Token revocation error', { error: error.message });
+    // Don't throw - revocation is best-effort
+  }
+}
+
+/**
+ * Get OAuth configuration
+ *
+ * @returns {object} OAuth configuration object
+ */
+export function getOAuthConfig() {
+  return { ...OAUTH_CONFIG };
+}

package/src/auth/pkce.js

@@ -0,0 +1,111 @@
+/**
+ * PKCE (Proof Key for Code Exchange) helpers for OAuth 2.0
+ *
+ * Implements the PKCE extension as specified in RFC 7636.
+ * Used for secure OAuth authentication without client_secret (public client).
+ */
+
+import crypto from 'node:crypto';
+import { debug } from '../logger.js';
+
+/**
+ * Generate a random code verifier for PKCE
+ *
+ * The code verifier must be:
+ * - High-entropy cryptographically random
+ * - Between 43 and 128 characters
+ * - Containing only alphanumeric characters and '-', '.', '_', '~'
+ *
+ * @returns {string} Base64URL-encoded code verifier
+ */
+export function generateCodeVerifier() {
+  // Generate 32 bytes of cryptographically secure random data
+  // Base64URL encoding results in ~43 characters
+  const verifier = crypto.randomBytes(32).toString('base64url');
+
+  debug('Generated code verifier', { length: verifier.length });
+
+  return verifier;
+}
+
+/**
+ * Generate a code challenge from the verifier
+ *
+ * Uses SHA-256 hash as specified in PKCE with S256 method.
+ *
+ * @param {string} verifier - The code verifier generated by generateCodeVerifier()
+ * @returns {string} Base64URL-encoded code challenge
+ */
+export function generateCodeChallenge(verifier) {
+  const challenge = crypto
+    .createHash('sha256')
+    .update(verifier)
+    .digest('base64url');
+
+  debug('Generated code challenge', { challengeLength: challenge.length });
+
+  return challenge;
+}
+
+/**
+ * Generate a cryptographically random state parameter
+ *
+ * The state parameter is used for CSRF protection during OAuth flow.
+ * Must be unique per authentication session.
+ *
+ * @returns {string} Hex-encoded random state
+ */
+export function generateState() {
+  // Generate 16 bytes of random data (32 hex characters)
+  const state = crypto.randomBytes(16).toString('hex');
+
+  debug('Generated state parameter', { state });
+
+  return state;
+}
+
+/**
+ * Validate state parameter matches expected value
+ *
+ * @param {string} receivedState - State received from OAuth callback
+ * @param {string} expectedState - State generated at start of flow
+ * @returns {boolean} True if states match, false otherwise
+ */
+export function validateState(receivedState, expectedState) {
+  const isValid = receivedState === expectedState;
+
+  if (!isValid) {
+    debug('State validation failed', {
+      received: receivedState,
+      expected: expectedState,
+    });
+  } else {
+    debug('State validation successful');
+  }
+
+  return isValid;
+}
+
+/**
+ * Generate all PKCE parameters for OAuth flow
+ *
+ * Convenience function that generates all required PKCE parameters.
+ *
+ * @returns {object} Object containing verifier, challenge, and state
+ * @returns {string} returns.verifier - Code verifier
+ * @returns {string} returns.challenge - Code challenge
+ * @returns {string} returns.state - State parameter
+ */
+export function generatePkceParams() {
+  const verifier = generateCodeVerifier();
+  const challenge = generateCodeChallenge(verifier);
+  const state = generateState();
+
+  debug('Generated PKCE parameters', {
+    verifierLength: verifier.length,
+    challengeLength: challenge.length,
+    stateLength: state.length,
+  });
+
+  return { verifier, challenge, state };
+}

package/src/auth/token-refresh.js

@@ -0,0 +1,210 @@
+/**
+ * Token refresh manager with single-flight locking
+ *
+ * Manages OAuth token refresh with protection against race conditions.
+ * Uses a Promise-based lock to ensure only one refresh happens at a time.
+ */
+
+import { refreshAccessToken } from './oauth.js';
+import { storeTokens, clearTokens } from './token-store.js';
+import { debug, warn, error as logError } from '../logger.js';
+
+/**
+ * Token refresh manager class
+ *
+ * Implements single-flight locking to prevent concurrent refresh attempts
+ * that could invalidate tokens due to Linear's refresh token rotation.
+ */
+class TokenRefreshManager {
+  constructor() {
+    /** @type {boolean} Is a refresh currently in progress? */
+    this.isRefreshing = false;
+
+    /** @type {Promise<string>|null} The current refresh promise */
+    this.refreshPromise = null;
+  }
+
+  /**
+   * Refresh the access token using the refresh token
+   *
+   * Implements single-flight locking: if a refresh is already in progress,
+   * this method will wait for the existing refresh to complete and return
+   * the new access token.
+   *
+   * @param {string} refreshToken - The refresh token to use
+   * @returns {Promise<string>} New access token
+   * @throws {Error} If refresh fails
+   */
+  async refresh(refreshToken) {
+    // If a refresh is already in progress, wait for it
+    if (this.isRefreshing && this.refreshPromise) {
+      debug('Refresh already in progress, waiting for existing refresh');
+      try {
+        return await this.refreshPromise;
+      } catch (error) {
+        // If the existing refresh failed, throw the error
+        throw error;
+      }
+    }
+
+    // Start a new refresh
+    this.isRefreshing = true;
+
+    this.refreshPromise = (async () => {
+      try {
+        debug('Starting token refresh');
+
+        // Call Linear's token endpoint
+        const tokenResponse = await refreshAccessToken(refreshToken);
+
+        // Calculate expiry timestamp
+        const expiresAt = Date.now() + tokenResponse.expires_in * 1000;
+
+        // Store new tokens atomically
+        const newTokens = {
+          accessToken: tokenResponse.access_token,
+          refreshToken: tokenResponse.refresh_token,
+          expiresAt: expiresAt,
+          scope: tokenResponse.scope ? tokenResponse.scope.split(' ') : [],
+          tokenType: tokenResponse.token_type || 'Bearer',
+        };
+
+        await storeTokens(newTokens);
+
+        debug('Token refresh successful', {
+          expiresAt: new Date(expiresAt).toISOString(),
+        });
+
+        return newTokens.accessToken;
+      } catch (error) {
+        logError('Token refresh failed', {
+          error: error.message,
+          stack: error.stack,
+        });
+
+        // Handle invalid_grant error - refresh token expired or revoked
+        if (error.message.includes('invalid_grant')) {
+          warn('Refresh token expired or revoked, clearing tokens');
+          await clearTokens();
+        }
+
+        throw error;
+      } finally {
+        // Reset the lock
+        this.isRefreshing = false;
+        this.refreshPromise = null;
+      }
+    })();
+
+    return this.refreshPromise;
+  }
+
+  /**
+   * Check if a refresh is currently in progress
+   *
+   * @returns {boolean} True if a refresh is in progress
+   */
+  isRefreshInProgress() {
+    return this.isRefreshing;
+  }
+
+  /**
+   * Reset the refresh manager state
+   *
+   * This is mainly for testing purposes.
+   */
+  reset() {
+    debug('Resetting token refresh manager');
+    this.isRefreshing = false;
+    this.refreshPromise = null;
+  }
+}
+
+// Create singleton instance
+const refreshManager = new TokenRefreshManager();
+
+/**
+ * Refresh the access token using the refresh token
+ *
+ * This function uses a singleton TokenRefreshManager to ensure
+ * single-flight locking across all calls.
+ *
+ * @param {string} refreshToken - The refresh token to use
+ * @returns {Promise<string>} New access token
+ * @throws {Error} If refresh fails
+ */
+export async function refreshTokens(refreshToken) {
+  return refreshManager.refresh(refreshToken);
+}
+
+/**
+ * Check if a token refresh is currently in progress
+ *
+ * @returns {boolean} True if a refresh is in progress
+ */
+export function isRefreshing() {
+  return refreshManager.isRefreshInProgress();
+}
+
+/**
+ * Reset the token refresh manager
+ *
+ * This is mainly for testing purposes.
+ */
+export function resetRefreshManager() {
+  refreshManager.reset();
+}
+
+/**
+ * Get a valid access token, refreshing if necessary
+ *
+ * This is a convenience function that combines token retrieval
+ * and refresh logic.
+ *
+ * @param {Function} getTokensFn - Function to retrieve current tokens
+ * @param {number} [bufferSeconds=60] - Seconds before expiry to trigger refresh
+ * @returns {Promise<string|null>} Valid access token or null if not available
+ */
+export async function getValidAccessToken(
+  getTokensFn,
+  bufferSeconds = 60
+) {
+  // Get current tokens
+  const tokens = await getTokensFn();
+
+  if (!tokens) {
+    debug('No tokens available');
+    return null;
+  }
+
+  const now = Date.now();
+  const bufferMs = bufferSeconds * 1000;
+  const expiresAt = tokens.expiresAt;
+
+  // Check if token is still valid (with buffer)
+  if (now < expiresAt - bufferMs) {
+    debug('Token is still valid', {
+      expiresAt: new Date(expiresAt).toISOString(),
+      now: new Date(now).toISOString(),
+      bufferSeconds,
+    });
+    return tokens.accessToken;
+  }
+
+  // Token needs refresh
+  debug('Token needs refresh', {
+    expiresAt: new Date(expiresAt).toISOString(),
+    now: new Date(now).toISOString(),
+    bufferSeconds,
+  });
+
+  try {
+    const newAccessToken = await refreshTokens(tokens.refreshToken);
+    return newAccessToken;
+  } catch (error) {
+    logError('Failed to get valid access token', {
+      error: error.message,
+    });
+    return null;
+  }
+}