npm - @fink-andreas/pi-linear-tools - Versions diffs - 0.1.0 → 0.2.0 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (15) hide show

package/CHANGELOG.md +20 -1
package/README.md +18 -2
package/extensions/pi-linear-tools.js +454 -109
package/package.json +4 -2
package/src/auth/callback-server.js +337 -0
package/src/auth/index.js +246 -0
package/src/auth/oauth.js +281 -0
package/src/auth/pkce.js +111 -0
package/src/auth/token-refresh.js +210 -0
package/src/auth/token-store.js +415 -0
package/src/cli.js +232 -59
package/src/handlers.js +7 -2
package/src/linear-client.js +36 -6
package/src/linear.js +13 -1
package/src/settings.js +107 -6

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@fink-andreas/pi-linear-tools",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Pi extension with Linear SDK tools and configuration commands",
   "type": "module",
   "engines": {
@@ -28,6 +28,7 @@
   "scripts": {
     "start": "node index.js",
     "test": "node tests/test-package-manifest.js && node tests/test-extension-registration.js && node tests/test-settings.js && node tests/test-assignee-update.js && node tests/test-full-assignee-flow.js",
+    "dev:sync-local-extension": "node scripts/dev-sync-local-extension.mjs",
     "release:check": "npm test && npm pack --dry-run"
   },
   "keywords": [
@@ -44,6 +45,7 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@linear/sdk": "^75.0.0"
+    "@linear/sdk": "^75.0.0",
+    "keytar": "^7.9.0"
   }
 }

package/src/auth/callback-server.js ADDED Viewed

@@ -0,0 +1,337 @@
+/**
+ * Local HTTP callback server for OAuth 2.0 authorization flow
+ *
+ * Creates an ephemeral HTTP server on localhost to receive the OAuth callback
+ * from Linear after user authorization.
+ */
+import http from 'node:http';
+import { URL } from 'node:url';
+import { debug, warn, error as logError } from '../logger.js';
+// Default callback server configuration
+const SERVER_CONFIG = {
+  port: 34711,
+  host: '127.0.0.1', // Bind to localhost only for security
+  timeout: 5 * 60 * 1000, // 5 minutes
+};
+/**
+ * HTML page to show on successful authentication
+ */
+const SUCCESS_HTML = `
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Authentication Successful</title>
+    <style>
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, sans-serif;
+            display: flex;
+            justify-content: center;
+            align-items: center;
+            height: 100vh;
+            margin: 0;
+            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+            color: white;
+        }
+        .container {
+            text-align: center;
+            padding: 40px;
+            background: rgba(255, 255, 255, 0.1);
+            border-radius: 12px;
+            backdrop-filter: blur(10px);
+            box-shadow: 0 8px 32px rgba(0, 0, 0, 0.1);
+        }
+        h1 {
+            margin: 0 0 16px 0;
+            font-size: 32px;
+        }
+        p {
+            font-size: 18px;
+            opacity: 0.9;
+            margin: 0;
+        }
+        .icon {
+            font-size: 64px;
+            margin-bottom: 24px;
+        }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <div class="icon">✓</div>
+        <h1>Authentication Successful</h1>
+        <p>You may safely close this window and return to your terminal.</p>
+    </div>
+</body>
+</html>
+`;
+/**
+ * HTML page to show on authentication error
+ */
+const ERROR_HTML = (errorMessage) => `
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Authentication Failed</title>
+    <style>
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, sans-serif;
+            display: flex;
+            justify-content: center;
+            align-items: center;
+            height: 100vh;
+            margin: 0;
+            background: linear-gradient(135deg, #f093fb 0%, #f5576c 100%);
+            color: white;
+        }
+        .container {
+            text-align: center;
+            padding: 40px;
+            background: rgba(255, 255, 255, 0.1);
+            border-radius: 12px;
+            backdrop-filter: blur(10px);
+            box-shadow: 0 8px 32px rgba(0, 0, 0, 0.1);
+            max-width: 500px;
+        }
+        h1 {
+            margin: 0 0 16px 0;
+            font-size: 32px;
+        }
+        p {
+            font-size: 18px;
+            opacity: 0.9;
+            margin: 0 0 24px 0;
+        }
+        .error {
+            background: rgba(0, 0, 0, 0.2);
+            padding: 16px;
+            border-radius: 8px;
+            font-family: monospace;
+            font-size: 14px;
+            word-break: break-all;
+        }
+        .icon {
+            font-size: 64px;
+            margin-bottom: 24px;
+        }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <div class="icon">✕</div>
+        <h1>Authentication Failed</h1>
+        <p>An error occurred during authentication:</p>
+        <div class="error">${errorMessage}</div>
+    </div>
+</body>
+</html>
+`;
+/**
+ * Start callback server and wait for OAuth callback
+ *
+ * @param {object} options - Server options
+ * @param {string} options.expectedState - Expected state parameter (for CSRF validation)
+ * @param {number} [options.port] - Port to listen on (default: 34711)
+ * @param {number} [options.timeout] - Timeout in milliseconds (default: 5 minutes)
+ * @param {AbortSignal} [options.signal] - Optional abort signal to cancel waiting
+ * @returns {Promise<object>} Callback result with code and state
+ * @throws {Error} If callback fails, times out, state validation fails, or is aborted
+ */
+export async function waitForCallback({
+  expectedState,
+  port = SERVER_CONFIG.port,
+  timeout = SERVER_CONFIG.timeout,
+  signal,
+}) {
+  debug('Starting callback server', { port, expectedState });
+  return new Promise((resolve, reject) => {
+    let server;
+    let timeoutId;
+    let settled = false;
+    const cleanup = () => {
+      clearTimeout(timeoutId);
+      if (signal) {
+        signal.removeEventListener('abort', abortHandler);
+      }
+    };
+    const fail = (err) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(err);
+    };
+    const succeed = (value) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve(value);
+    };
+    // Create timeout handler
+    const timeoutHandler = () => {
+      debug('Callback server timeout');
+      if (server) {
+        server.close();
+      }
+      fail(new Error('OAuth callback timed out. Please try again.'));
+    };
+    const abortHandler = () => {
+      debug('Callback server aborted by caller');
+      if (server) {
+        server.close();
+      }
+      fail(new Error('OAuth authentication was cancelled.'));
+    };
+    if (signal?.aborted) {
+      abortHandler();
+      return;
+    }
+    if (signal) {
+      signal.addEventListener('abort', abortHandler, { once: true });
+    }
+    // Start timeout
+    timeoutId = setTimeout(timeoutHandler, timeout);
+    // Create HTTP server
+    server = http.createServer((req, res) => {
+      const parsedUrl = new URL(req.url, `http://${req.headers.host}`);
+      debug('Received request', { path: parsedUrl.pathname });
+      // Only handle the callback path
+      if (parsedUrl.pathname === '/callback') {
+        const code = parsedUrl.searchParams.get('code');
+        const state = parsedUrl.searchParams.get('state');
+        const error = parsedUrl.searchParams.get('error');
+        const errorDescription = parsedUrl.searchParams.get(
+          'error_description'
+        );
+        // Check for OAuth error
+        if (error) {
+          debug('OAuth error received', {
+            error,
+            errorDescription,
+          });
+          res.writeHead(400, { 'Content-Type': 'text/html' });
+          res.end(
+            ERROR_HTML(
+              errorDescription || error || 'Unknown OAuth error'
+            )
+          );
+          server.close();
+          fail(new Error(`OAuth error: ${errorDescription || error}`));
+          return;
+        }
+        // Check for authorization code
+        if (!code) {
+          debug('Missing authorization code');
+          res.writeHead(400, { 'Content-Type': 'text/html' });
+          res.end(ERROR_HTML('Missing authorization code in callback'));
+          server.close();
+          fail(new Error('Missing authorization code in callback'));
+          return;
+        }
+        // Validate state parameter (CSRF protection)
+        if (!state || state !== expectedState) {
+          debug('State validation failed', {
+            received: state,
+            expected: expectedState,
+          });
+          res.writeHead(400, { 'Content-Type': 'text/html' });
+          res.end(
+            ERROR_HTML('Security error: State mismatch. Possible CSRF attack.')
+          );
+          server.close();
+          fail(
+            new Error('State validation failed. Possible CSRF attack.')
+          );
+          return;
+        }
+        // Success!
+        debug('OAuth callback successful', { hasCode: !!code });
+        res.writeHead(200, { 'Content-Type': 'text/html' });
+        res.end(SUCCESS_HTML);
+        // Close server after a short delay to ensure response is sent
+        setTimeout(() => {
+          server.close();
+        }, 100);
+        succeed({ code, state });
+      } else {
+        // Return 404 for other paths
+        res.writeHead(404, { 'Content-Type': 'text/plain' });
+        res.end('Not Found');
+      }
+    });
+    // Handle server errors
+    server.on('error', (err) => {
+      logError('Callback server error', {
+        error: err.message,
+        code: err.code,
+      });
+      if (err.code === 'EADDRINUSE') {
+        fail(
+          new Error(
+            `Port ${port} is already in use. Please check if another process is using it.`
+          )
+        );
+      } else if (err.code === 'EACCES') {
+        fail(
+          new Error(
+            `Permission denied to bind to port ${port}. Try a different port.`
+          )
+        );
+      } else {
+        fail(new Error(`Failed to start callback server: ${err.message}`));
+      }
+    });
+    // Start listening
+    server.listen(port, SERVER_CONFIG.host, () => {
+      debug('Callback server listening', {
+        host: SERVER_CONFIG.host,
+        port,
+      });
+    });
+  });
+}
+/**
+ * Get callback URL for OAuth authorization
+ *
+ * @param {number} [port] - Port number (default: 34711)
+ * @returns {string} Full callback URL
+ */
+export function getCallbackUrl(port = SERVER_CONFIG.port) {
+  return `http://localhost:${port}/callback`;
+}

package/src/auth/index.js ADDED Viewed

@@ -0,0 +1,246 @@
+/**
+ * OAuth 2.0 authentication orchestrator for pi-linear-tools
+ *
+ * Orchestrates the complete OAuth flow including PKCE generation,
+ * local callback server, token exchange, and storage.
+ */
+import { generatePkceParams } from './pkce.js';
+import { buildAuthorizationUrl, exchangeCodeForToken } from './oauth.js';
+import { waitForCallback } from './callback-server.js';
+import { storeTokens, getTokens, clearTokens, hasValidTokens } from './token-store.js';
+import { getValidAccessToken } from './token-refresh.js';
+import { debug, info, warn, error as logError } from '../logger.js';
+function parseManualCallbackInput(rawInput) {
+  const value = String(rawInput || '').trim();
+  if (!value) return null;
+  if (value.startsWith('http://') || value.startsWith('https://')) {
+    const parsed = new URL(value);
+    return {
+      code: parsed.searchParams.get('code'),
+      state: parsed.searchParams.get('state'),
+    };
+  }
+  if (value.includes('code=')) {
+    const parsed = new URL(value.startsWith('?') ? `http://localhost/${value}` : `http://localhost/?${value}`);
+    return {
+      code: parsed.searchParams.get('code'),
+      state: parsed.searchParams.get('state'),
+    };
+  }
+  return { code: value, state: null };
+}
+/**
+ * Perform the complete OAuth authentication flow
+ *
+ * This function:
+ * 1. Generates PKCE parameters
+ * 2. Starts a local callback server
+ * 3. Opens the browser with the authorization URL
+ * 4. Waits for the callback
+ * 5. Exchanges the authorization code for tokens
+ * 6. Stores the tokens securely
+ *
+ * @param {object} options - Authentication options
+ * @param {Function} [options.openBrowser] - Function to open browser (default: use 'open' package)
+ * @param {number} [options.port] - Port for callback server (default: 34711)
+ * @param {number} [options.timeout] - Timeout for callback in milliseconds (default: 5 minutes)
+ * @param {Function} [options.onAuthorizationUrl] - Optional callback invoked with the authorization URL
+ * @param {Function} [options.manualCodeInput] - Optional async callback for manual callback URL/code input
+ * @returns {Promise<object>} Authentication result with tokens
+ * @throws {Error} If authentication fails
+ */
+export async function authenticate({
+  openBrowser,
+  port = 34711,
+  timeout = 5 * 60 * 1000,
+  onAuthorizationUrl,
+  manualCodeInput,
+} = {}) {
+  debug('Starting OAuth authentication flow', { port, timeout });
+  try {
+    // Step 1: Generate PKCE parameters
+    const pkceParams = generatePkceParams();
+    debug('Generated PKCE parameters', {
+      challengeLength: pkceParams.challenge.length,
+      stateLength: pkceParams.state.length,
+    });
+    // Step 2: Build authorization URL
+    const authUrl = buildAuthorizationUrl({
+      challenge: pkceParams.challenge,
+      state: pkceParams.state,
+      redirectUri: `http://localhost:${port}/callback`,
+    });
+    debug('Built authorization URL');
+    const abortController = new AbortController();
+    // Step 3: Start callback server (this will wait for the callback)
+    const callbackPromise = waitForCallback({
+      expectedState: pkceParams.state,
+      port,
+      timeout,
+      signal: abortController.signal,
+    });
+    if (typeof onAuthorizationUrl === 'function') {
+      await onAuthorizationUrl(authUrl);
+    }
+    let shouldPromptManual = false;
+    // Step 4: Open browser with authorization URL
+    if (openBrowser) {
+      await openBrowser(authUrl);
+      info('Opening browser for authentication...');
+    } else {
+      // Default: use 'open' package if available
+      try {
+        const { default: open } = await import('open');
+        await open(authUrl);
+        info('Opening browser for authentication...');
+      } catch (error) {
+        warn('Failed to open browser automatically', { error: error.message });
+        if (typeof onAuthorizationUrl !== 'function') {
+          info('Please open the following URL in your browser:');
+          console.log(authUrl);
+        }
+        shouldPromptManual = true;
+      }
+    }
+    // Step 5: Wait for callback (or optional manual input fallback)
+    info('Waiting for authentication callback...');
+    let callback;
+    if (typeof manualCodeInput === 'function' && shouldPromptManual) {
+      const manualPromise = (async () => {
+        const raw = await manualCodeInput({ authUrl, expectedState: pkceParams.state, port });
+        const parsed = parseManualCallbackInput(raw);
+        if (!parsed || !parsed.code) {
+          throw new Error('OAuth authentication cancelled by user.');
+        }
+        if (parsed.state && parsed.state !== pkceParams.state) {
+          throw new Error('State validation failed. Possible CSRF attack.');
+        }
+        return { code: parsed.code, state: parsed.state || pkceParams.state };
+      })();
+      callback = await Promise.race([callbackPromise, manualPromise]);
+      abortController.abort();
+    } else {
+      callback = await callbackPromise;
+    }
+    debug('Received callback', { hasCode: !!callback.code });
+    // Step 6: Exchange code for tokens
+    info('Exchanging authorization code for tokens...');
+    const tokenResponse = await exchangeCodeForToken({
+      code: callback.code,
+      verifier: pkceParams.verifier,
+      redirectUri: `http://localhost:${port}/callback`,
+    });
+    debug('Token exchange successful');
+    // Step 7: Store tokens securely
+    const expiresAt = Date.now() + tokenResponse.expires_in * 1000;
+    const tokens = {
+      accessToken: tokenResponse.access_token,
+      refreshToken: tokenResponse.refresh_token,
+      expiresAt: expiresAt,
+      scope: tokenResponse.scope ? tokenResponse.scope.split(' ') : [],
+      tokenType: tokenResponse.token_type || 'Bearer',
+    };
+    await storeTokens(tokens);
+    debug('Tokens stored successfully');
+    info('Authentication successful!');
+    info(`Token expires at: ${new Date(expiresAt).toISOString()}`);
+    return tokens;
+  } catch (error) {
+    logError('OAuth authentication failed', {
+      error: error.message,
+      stack: error.stack,
+    });
+    throw error;
+  }
+}
+/**
+ * Get a valid access token, refreshing if necessary
+ *
+ * @returns {Promise<string|null>} Valid access token or null if not authenticated
+ */
+export async function getAccessToken() {
+  return getValidAccessToken(getTokens);
+}
+/**
+ * Check if the user is authenticated
+ *
+ * @returns {Promise<boolean>} True if authenticated with valid tokens
+ */
+export async function isAuthenticated() {
+  return hasValidTokens();
+}
+/**
+ * Get authentication status
+ *
+ * @returns {Promise<object|null>} Authentication status or null if not authenticated
+ */
+export async function getAuthStatus() {
+  const tokens = await getTokens();
+  if (!tokens) {
+    return null;
+  }
+  const now = Date.now();
+  const isExpired = now >= tokens.expiresAt;
+  return {
+    authenticated: !isExpired,
+    expiresAt: new Date(tokens.expiresAt).toISOString(),
+    expiresIn: Math.max(0, tokens.expiresAt - now),
+    scopes: tokens.scope,
+  };
+}
+/**
+ * Logout (clear stored tokens)
+ *
+ * @returns {Promise<void>}
+ */
+export async function logout() {
+  info('Logging out...');
+  await clearTokens();
+  info('Logged out successfully');
+}
+/**
+ * Re-authenticate (logout and then authenticate)
+ *
+ * @param {object} options - Authentication options (passed to authenticate())
+ * @returns {Promise<object>} Authentication result with tokens
+ */
+export async function reAuthenticate(options) {
+  info('Re-authenticating...');
+  await logout();
+  return authenticate(options);
+}