npm - @unifiedmemory/cli - Versions diffs - 1.3.11 → 1.3.13 - Mend

@unifiedmemory/cli 1.3.11 → 1.3.13

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 (14) hide show

package/.env.example +8 -0
package/CHANGELOG.md +20 -0
package/README.md +12 -0
package/commands/login.js +106 -9
package/commands/org.js +135 -9
package/index.js +14 -1
package/lib/config.js +11 -1
package/package.json +1 -1
package/tests/fixtures/token-missing-org-claims.json +20 -0
package/tests/fixtures/token-no-sid-has-original.json +20 -0
package/tests/fixtures/token-with-org-claims.json +25 -0
package/tests/mocks/clerk-api.mock.js +77 -0
package/tests/unit/token-refresh.test.js +304 -0
package/tests/unit/token-validation.test.js +367 -0

package/.env.example CHANGED Viewed

@@ -37,6 +37,14 @@
 # REDIRECT_URI=http://localhost:3333/callback
 # PORT=3333
+# ============================================
+# OAuth Success Page Link
+# ============================================
+# Optional website link shown on the OAuth success page
+# Users can visit this URL to manage their account or subscription
+# Default: https://unifiedmemory.ai/oauth/callback
+# OAUTH_SUCCESS_URL=https://unifiedmemory.ai/oauth/callback
 # ============================================
 # Clerk Client Secret (Optional)
 # ============================================

package/CHANGELOG.md CHANGED Viewed

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
+## [1.3.12] - 2026-01-21
+### Fixed
+- **Organization mismatch error in MCP server** - JWT tokens now properly include org claims
+  - **Root cause**: When `getOrgScopedToken()` failed during login, the fallback path lost the session ID needed for recovery
+  - **commands/login.js**: Fallback now preserves `originalSid` in auth.json, enabling automatic recovery on next API call
+  - **commands/org.js**: `um org switch` now gets org-scoped token instead of just updating selected org
+  - This fixes 401 MISMATCH errors when the gateway reads org from JWT but finds no `o.o_id` claim
+### Added
+- **`um org fix` command** - Manual recovery for broken org tokens
+  - Diagnoses token state and attempts to get org-scoped JWT
+  - Tries OAuth refresh to obtain session ID if missing
+  - Provides clear error messages with recovery steps
+  - Usage: Run `um org fix` if MCP server fails with org mismatch errors
+## [1.3.11] - 2026-01-20
 ### Changed
 - **lib/config.js** - Embedded production defaults for zero-configuration installation

package/README.md CHANGED Viewed

@@ -113,6 +113,18 @@ Switch between your organizations or personal account.
 um org switch
 ```
+### `um org fix`
+Fix organization token if API calls fail with org mismatch errors.
+```bash
+um org fix
+```
+This command diagnoses and repairs tokens that are missing organization claims. Use it when:
+- MCP server returns 401 MISMATCH errors
+- `um status` shows an org selected but API calls fail
+- After switching organizations if token update failed
 ### `um note create`
 Manually save a note to your vault (useful for capturing important context).

package/commands/login.js CHANGED Viewed

@@ -143,15 +143,100 @@ export async function login() {
           // Debug: Log the token response structure
           console.log(chalk.gray('\nToken response keys:'), Object.keys(tokenData));
-          // Send success response to browser first
+          // Send success response to browser
           res.writeHead(200, { 'Content-Type': 'text/html' });
           res.end(`
-            <html>
-              <body style="font-family: system-ui; padding: 2rem; text-align: center;">
-                <h1 style="color: #10B981;">✅ Authentication Successful!</h1>
-                <p>You have successfully authenticated with Clerk.</p>
-                <p>You can close this window and return to the CLI.</p>
-                <script>setTimeout(() => window.close(), 3000);</script>
+            <!DOCTYPE html>
+            <html lang="en">
+              <head>
+                <meta charset="UTF-8">
+                <meta name="viewport" content="width=device-width, initial-scale=1.0">
+                <title>Login Successful</title>
+                <link rel="preconnect" href="https://fonts.googleapis.com">
+                <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+                <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
+                <style>
+                  * {
+                    margin: 0;
+                    padding: 0;
+                    box-sizing: border-box;
+                  }
+                  body {
+                    font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+                    background: hsl(220, 30%, 8%);
+                    color: hsl(0, 0%, 100%);
+                    min-height: 100vh;
+                    display: flex;
+                    align-items: center;
+                    justify-content: center;
+                    padding: 2rem;
+                  }
+                  .card {
+                    background: hsl(220, 25%, 12%);
+                    border: 1px solid hsl(220, 20%, 20%);
+                    border-radius: 0.5rem;
+                    padding: 2rem;
+                    text-align: center;
+                    max-width: 32rem;
+                    width: 100%;
+                  }
+                  .logo {
+                    width: 64px;
+                    height: 64px;
+                    margin: 0 auto 1.5rem;
+                    display: block;
+                  }
+                  h1 {
+                    font-size: 1.875rem;
+                    font-weight: 700;
+                    margin-bottom: 0.5rem;
+                    color: hsl(0, 0%, 100%);
+                  }
+                  .description {
+                    font-size: 1.125rem;
+                    color: hsl(0, 0%, 65%);
+                    margin-bottom: 1.5rem;
+                  }
+                  .message {
+                    color: hsl(0, 0%, 65%);
+                    line-height: 1.6;
+                  }
+                  .optional-link {
+                    margin-top: 2rem;
+                    padding-top: 1.5rem;
+                    border-top: 1px solid hsl(220, 20%, 20%);
+                    font-size: 0.8125rem;
+                    color: hsl(0, 0%, 50%);
+                    line-height: 1.5;
+                  }
+                  .optional-link a {
+                    color: hsl(0, 0%, 55%);
+                    text-decoration: none;
+                    border-bottom: 1px solid transparent;
+                    transition: border-color 0.2s;
+                  }
+                  .optional-link a:hover {
+                    border-bottom-color: hsl(0, 0%, 55%);
+                  }
+                </style>
+              </head>
+              <body>
+                <div class="card">
+                  <img src="https://unifiedmemory.ai/images/theme/axolotl-logo.png" alt="UnifiedMemory.ai Logo" class="logo" />
+                  <h1>Login Successful</h1>
+                  <p class="description">Your authentication is complete.</p>
+                  <p class="message">You may now close this tab and return to the terminal to continue using the CLI.</p>
+                  <div class="optional-link">
+                    You can manage your account or subscription on the web at<br>
+                    <a href="https://unifiedmemory.ai/account">unifiedmemory.ai</a>
+                  </div>
+                </div>
+                <script>
+                  // Auto-close window after 10 seconds
+                  setTimeout(() => {
+                    window.close();
+                  }, 10000);
+                </script>
               </body>
             </html>
           `);
@@ -243,12 +328,24 @@ export async function login() {
                     console.error(chalk.yellow('\n⚠️  Failed to get org-scoped token:'), error.message);
                     console.log(chalk.gray('   Continuing with original token (may have limited org access)'));
-                    // Fall back to updating selected org without new token
-                    updateSelectedOrg(selectedOrg);
+                    // Save token with selectedOrg AND originalSid for recovery
+                    // This allows token-validation.js to retry getting org-scoped token later
+                    saveToken({
+                      accessToken: tokenData.access_token,
+                      idToken: tokenData.id_token,
+                      refresh_token: tokenData.refresh_token,
+                      tokenType: 'Bearer',
+                      expiresIn: tokenData.expires_in,
+                      receivedAt: Date.now(),
+                      decoded: decoded,
+                      selectedOrg: selectedOrg,
+                      originalSid: decoded.sid  // Preserve session ID for recovery
+                    });
                     console.log(chalk.green(`\n✅ Using organization context: ${chalk.bold(selectedOrg.name)}`));
                     console.log(chalk.gray(`   Organization ID: ${selectedOrg.id}`));
                     console.log(chalk.gray(`   Your role: ${selectedOrg.role}`));
+                    console.log(chalk.yellow('   ⚠️  Token lacks org claims - recovery will be attempted on next use'));
                   }
                 } else {
                   console.log(chalk.green('\n✅ Using personal account context'));

package/commands/org.js CHANGED Viewed

@@ -1,7 +1,9 @@
 import chalk from 'chalk';
-import { updateSelectedOrg, getSelectedOrg } from '../lib/token-storage.js';
+import { updateSelectedOrg, getSelectedOrg, saveToken, getToken } from '../lib/token-storage.js';
 import { loadAndRefreshToken } from '../lib/token-validation.js';
-import { getUserOrganizations, getOrganizationsFromToken } from '../lib/clerk-api.js';
+import { refreshAccessToken } from '../lib/token-refresh.js';
+import { getUserOrganizations, getOrganizationsFromToken, getOrgScopedToken } from '../lib/clerk-api.js';
+import { parseJWT } from '../lib/jwt-utils.js';
 import { promptOrganizationSelection, displayOrganizationSelection } from '../lib/org-selection-ui.js';
 /**
@@ -46,15 +48,50 @@ export async function switchOrg() {
   // Prompt user to select
   const selectedOrg = await promptOrganizationSelection(memberships, currentOrg);
-  // Update selected organization
-  updateSelectedOrg(selectedOrg);
-  // Display result (with "Switched to" instead of "Selected")
+  // Update selected organization with org-scoped token
   if (selectedOrg) {
-    console.log(chalk.green(`\n✅ Switched to organization: ${chalk.bold(selectedOrg.name)}`));
-    console.log(chalk.gray(`   Organization ID: ${selectedOrg.id}`));
-    console.log(chalk.gray(`   Your role: ${selectedOrg.role}`));
+    try {
+      // Get session ID from current token
+      const sessionId = tokenData.decoded?.sid || tokenData.originalSid;
+      const currentToken = tokenData.idToken || tokenData.accessToken;
+      if (sessionId) {
+        console.log(chalk.cyan('\n🔄 Getting organization-scoped token...'));
+        const orgToken = await getOrgScopedToken(sessionId, selectedOrg.id, currentToken);
+        // Update with org-scoped token
+        saveToken({
+          ...tokenData,
+          idToken: orgToken.jwt,
+          decoded: parseJWT(orgToken.jwt),
+          selectedOrg: selectedOrg,
+          originalSid: sessionId
+        });
+        console.log(chalk.green(`\n✅ Switched to organization: ${chalk.bold(selectedOrg.name)}`));
+        console.log(chalk.gray(`   Organization ID: ${selectedOrg.id}`));
+        console.log(chalk.gray(`   Your role: ${selectedOrg.role}`));
+        console.log(chalk.gray('   ✓ Token updated with organization context'));
+      } else {
+        // Fall back to just updating selectedOrg (recovery will try later)
+        updateSelectedOrg(selectedOrg);
+        console.log(chalk.green(`\n✅ Switched to organization: ${chalk.bold(selectedOrg.name)}`));
+        console.log(chalk.gray(`   Organization ID: ${selectedOrg.id}`));
+        console.log(chalk.gray(`   Your role: ${selectedOrg.role}`));
+        console.log(chalk.yellow('   ⚠️  No session ID available - token lacks org claims'));
+        console.log(chalk.gray('   Try: um login'));
+      }
+    } catch (error) {
+      console.error(chalk.yellow(`\n⚠️  Failed to get org-scoped token: ${error.message}`));
+      updateSelectedOrg(selectedOrg);
+      console.log(chalk.green(`\n✅ Switched to organization: ${chalk.bold(selectedOrg.name)}`));
+      console.log(chalk.gray(`   Organization ID: ${selectedOrg.id}`));
+      console.log(chalk.gray(`   Your role: ${selectedOrg.role}`));
+      console.log(chalk.gray('   Saved org selection, but token may need refresh'));
+      console.log(chalk.gray('   Try: um org fix'));
+    }
   } else {
+    updateSelectedOrg(null);
     console.log(chalk.green('\n✅ Switched to personal account context'));
   }
@@ -80,3 +117,92 @@ export async function showOrg() {
   console.log(chalk.gray('\nRun `um org switch` to change organization\n'));
 }
+/**
+ * Fix organization token if API calls fail with org mismatch
+ * Attempts to get org-scoped token for the currently selected organization
+ */
+export async function fixOrg() {
+  const tokenData = getToken();
+  if (!tokenData) {
+    console.error(chalk.red('❌ Not authenticated. Run: um login'));
+    return;
+  }
+  if (!tokenData.selectedOrg) {
+    console.error(chalk.yellow('⚠️  No organization selected. Run: um org switch'));
+    return;
+  }
+  console.log(chalk.blue('\n🔧 Organization Token Fix\n'));
+  console.log(chalk.gray(`  Selected org: ${tokenData.selectedOrg.name}`));
+  console.log(chalk.gray(`  Org ID: ${tokenData.selectedOrg.id}`));
+  // Check if already has org claims
+  if (tokenData.decoded?.o?.o_id) {
+    console.log(chalk.green('\n✓ Token already has organization claims'));
+    console.log(chalk.gray(`  Org in token: ${tokenData.decoded.o.o_id}`));
+    if (tokenData.decoded.o.o_id === tokenData.selectedOrg.id) {
+      console.log(chalk.green('  ✓ Org matches selected organization'));
+    } else {
+      console.log(chalk.yellow('  ⚠️  Org mismatch - token has different org than selected'));
+      console.log(chalk.gray('  Run: um org switch'));
+    }
+    return;
+  }
+  console.log(chalk.yellow('\n⚠️  Token missing org claims. Attempting fix...'));
+  // Try to get session ID
+  let sessionId = tokenData.decoded?.sid || tokenData.originalSid;
+  let currentToken = tokenData.idToken || tokenData.accessToken;
+  // If no sessionId, try OAuth refresh first
+  if (!sessionId && tokenData.refresh_token) {
+    console.log(chalk.gray('  Refreshing token to obtain session ID...'));
+    try {
+      const refreshed = await refreshAccessToken(tokenData);
+      sessionId = refreshed.decoded?.sid;
+      currentToken = refreshed.idToken || refreshed.accessToken;
+      if (sessionId) {
+        console.log(chalk.gray('  ✓ Got session ID from refresh'));
+      }
+    } catch (error) {
+      console.error(chalk.red(`  Refresh failed: ${error.message}`));
+    }
+  }
+  if (!sessionId) {
+    console.error(chalk.red('\n❌ Cannot obtain session ID'));
+    console.log(chalk.gray('  The token does not contain a session ID needed for org-scoped tokens.'));
+    console.log(chalk.gray('  Run: um login'));
+    return;
+  }
+  // Get org-scoped token
+  try {
+    console.log(chalk.cyan('\n🔄 Getting organization-scoped token...'));
+    const orgToken = await getOrgScopedToken(
+      sessionId,
+      tokenData.selectedOrg.id,
+      currentToken
+    );
+    const decoded = parseJWT(orgToken.jwt);
+    saveToken({
+      ...tokenData,
+      idToken: orgToken.jwt,
+      decoded: decoded,
+      originalSid: sessionId
+    });
+    console.log(chalk.green('\n✅ Token fixed with organization claims'));
+    console.log(chalk.gray(`  Org: ${tokenData.selectedOrg.name}`));
+    console.log(chalk.gray(`  Org ID in token: ${decoded?.o?.o_id || 'N/A'}`));
+  } catch (error) {
+    console.error(chalk.red(`\n❌ Failed to get org token: ${error.message}`));
+    console.log(chalk.gray('\nYou may need to run: um login'));
+  }
+}

package/index.js CHANGED Viewed

@@ -9,7 +9,7 @@ import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import { login } from './commands/login.js';
 import { init } from './commands/init.js';
-import { switchOrg, showOrg } from './commands/org.js';
+import { switchOrg, showOrg, fixOrg } from './commands/org.js';
 import { record } from './commands/record.js';
 import { config } from './lib/config.js';
 import { getSelectedOrg } from './lib/token-storage.js';
@@ -160,6 +160,19 @@ orgCommand
     }
   });
+orgCommand
+  .command('fix')
+  .description('Fix organization token if API calls fail with org mismatch')
+  .action(async () => {
+    try {
+      await fixOrg();
+      process.exit(0);
+    } catch (error) {
+      console.error(chalk.red('Failed to fix organization token:'), error.message);
+      process.exit(1);
+    }
+  });
 // MCP server commands
 const mcpCommand = program
   .command('mcp')

package/lib/config.js CHANGED Viewed

@@ -19,7 +19,10 @@ export const config = {
   // OAuth flow configuration (localhost defaults for callback server)
   redirectUri: process.env.REDIRECT_URI || 'http://localhost:3333/callback',
-  port: parseInt(process.env.PORT || '3333', 10)
+  port: parseInt(process.env.PORT || '3333', 10),
+  // OAuth success page configuration (optional website link for account management)
+  oauthSuccessUrl: process.env.OAUTH_SUCCESS_URL || 'https://unifiedmemory.ai/oauth/callback'
 };
 // Validation function - validates configuration values
@@ -41,5 +44,12 @@ export function validateConfig() {
     throw new Error('CLERK_CLIENT_ID cannot be empty');
   }
+  // Validate oauthSuccessUrl format if provided
+  try {
+    new URL(config.oauthSuccessUrl);
+  } catch (e) {
+    throw new Error(`OAUTH_SUCCESS_URL must be a valid URL (got: ${config.oauthSuccessUrl})`);
+  }
   return true;
 }

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@unifiedmemory/cli",
-  "version": "1.3.11",
+  "version": "1.3.13",
   "description": "UnifiedMemory CLI - AI code assistant integration",
   "main": "index.js",
   "type": "module",

package/tests/fixtures/token-missing-org-claims.json ADDED Viewed

@@ -0,0 +1,20 @@
+{
+  "accessToken": "mock_access_token",
+  "idToken": "mock_id_token_no_org",
+  "refresh_token": "mock_refresh_token",
+  "tokenType": "Bearer",
+  "expiresIn": 3600,
+  "receivedAt": 1700000000000,
+  "decoded": {
+    "sub": "user_123456789",
+    "email": "test@test.com",
+    "exp": 9999999999,
+    "iat": 1600000000,
+    "sid": "sess_123456789"
+  },
+  "selectedOrg": {
+    "id": "org_456789012",
+    "name": "Test Organization",
+    "role": "admin"
+  }
+}

package/tests/fixtures/token-no-sid-has-original.json ADDED Viewed

@@ -0,0 +1,20 @@
+{
+  "accessToken": "mock_access_token",
+  "idToken": "mock_id_token_org_scoped",
+  "refresh_token": "mock_refresh_token",
+  "tokenType": "Bearer",
+  "expiresIn": 3600,
+  "receivedAt": 1700000000000,
+  "decoded": {
+    "sub": "user_123456789",
+    "email": "test@test.com",
+    "exp": 9999999999,
+    "iat": 1600000000
+  },
+  "selectedOrg": {
+    "id": "org_456789012",
+    "name": "Test Organization",
+    "role": "admin"
+  },
+  "originalSid": "sess_original_123"
+}

package/tests/fixtures/token-with-org-claims.json ADDED Viewed

@@ -0,0 +1,25 @@
+{
+  "accessToken": "mock_access_token",
+  "idToken": "mock_id_token_with_org",
+  "refresh_token": "mock_refresh_token",
+  "tokenType": "Bearer",
+  "expiresIn": 3600,
+  "receivedAt": 1700000000000,
+  "decoded": {
+    "sub": "user_123456789",
+    "email": "test@test.com",
+    "exp": 9999999999,
+    "iat": 1600000000,
+    "sid": "sess_123456789",
+    "o": {
+      "o_id": "org_456789012",
+      "o_role": "admin"
+    }
+  },
+  "selectedOrg": {
+    "id": "org_456789012",
+    "name": "Test Organization",
+    "role": "admin"
+  },
+  "originalSid": "sess_123456789"
+}

package/tests/mocks/clerk-api.mock.js ADDED Viewed

@@ -0,0 +1,77 @@
+/**
+ * Mock for lib/clerk-api.js
+ *
+ * Provides mock implementations of Clerk API functions
+ * for testing token refresh and recovery functionality.
+ */
+import { vi } from 'vitest';
+/**
+ * Creates a configurable mock for lib/clerk-api.js
+ * @param {Object} options - Configuration options
+ * @param {Object} options.orgToken - Response for getOrgScopedToken
+ * @param {Array} options.orgs - List of organizations for getUserOrganizations
+ * @returns {Object} Mock clerk-api functions
+ */
+export function createClerkApiMock(options = {}) {
+  const defaultOrgToken = {
+    jwt: 'mock_org_scoped_jwt',
+    object: 'token'
+  };
+  return {
+    getOrgScopedToken: vi.fn().mockResolvedValue(options.orgToken || defaultOrgToken),
+    getUserOrganizations: vi.fn().mockResolvedValue(options.orgs || []),
+    getOrganizationsFromToken: vi.fn().mockReturnValue(options.orgs || []),
+  };
+}
+/**
+ * Pre-configured mock for successful org token retrieval
+ */
+export const successfulOrgTokenMock = createClerkApiMock({
+  orgToken: {
+    jwt: 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyXzEyMyIsIm8iOnsib19pZCI6Im9yZ180NTYifX0.sig',
+    object: 'token'
+  }
+});
+/**
+ * Creates a mock that fails when getting org-scoped token
+ * @param {string} errorMessage - Error message to throw
+ * @returns {Object} Mock clerk-api functions that fail
+ */
+export function createFailingOrgTokenMock(errorMessage = 'Failed to get org token') {
+  return {
+    getOrgScopedToken: vi.fn().mockRejectedValue(new Error(errorMessage)),
+    getUserOrganizations: vi.fn().mockResolvedValue([]),
+    getOrganizationsFromToken: vi.fn().mockReturnValue([]),
+  };
+}
+/**
+ * Creates a mock with custom org token response containing decoded claims
+ * @param {Object} decodedClaims - Claims to include in the mock JWT
+ * @returns {Object} Mock clerk-api functions
+ */
+export function createOrgTokenMockWithClaims(decodedClaims = {}) {
+  // Create a simple mock JWT structure (not cryptographically valid, but parseable)
+  const header = Buffer.from(JSON.stringify({ alg: 'RS256', typ: 'JWT' })).toString('base64url');
+  const payload = Buffer.from(JSON.stringify({
+    sub: 'user_123',
+    exp: Math.floor(Date.now() / 1000) + 3600,
+    o: { o_id: 'org_456', o_role: 'admin' },
+    ...decodedClaims
+  })).toString('base64url');
+  const signature = 'mock_signature';
+  const mockJwt = `${header}.${payload}.${signature}`;
+  return createClerkApiMock({
+    orgToken: {
+      jwt: mockJwt,
+      object: 'token'
+    }
+  });
+}

package/tests/unit/token-refresh.test.js ADDED Viewed

@@ -0,0 +1,304 @@
+/**
+ * Unit tests for lib/token-refresh.js
+ *
+ * Tests token expiration checking and OAuth refresh functionality.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+// Mock the dependencies before importing the module
+vi.mock('../../lib/config.js', () => ({
+  config: {
+    clerkDomain: 'clerk.test.com',
+    clerkClientId: 'test_client_id',
+    clerkClientSecret: 'test_client_secret',
+  }
+}));
+vi.mock('../../lib/token-storage.js', () => ({
+  getToken: vi.fn(),
+  saveToken: vi.fn(),
+}));
+vi.mock('../../lib/jwt-utils.js', () => ({
+  parseJWT: vi.fn((jwt) => {
+    // Return mock decoded payload
+    if (jwt === 'new_id_token_with_sid') {
+      return {
+        sub: 'user_123',
+        exp: Math.floor(Date.now() / 1000) + 3600,
+        sid: 'sess_new_123',
+      };
+    }
+    if (jwt === 'org_scoped_jwt') {
+      return {
+        sub: 'user_123',
+        exp: Math.floor(Date.now() / 1000) + 3600,
+        o: { o_id: 'org_456' },
+      };
+    }
+    return {
+      sub: 'user_123',
+      exp: Math.floor(Date.now() / 1000) + 3600,
+    };
+  }),
+}));
+vi.mock('../../lib/clerk-api.js', () => ({
+  getOrgScopedToken: vi.fn().mockResolvedValue({
+    jwt: 'org_scoped_jwt',
+    object: 'token',
+  }),
+}));
+// Import after mocking
+import { isTokenExpired, refreshAccessToken } from '../../lib/token-refresh.js';
+import { saveToken } from '../../lib/token-storage.js';
+import { getOrgScopedToken } from '../../lib/clerk-api.js';
+describe('isTokenExpired', () => {
+  it('returns true for null tokenData', () => {
+    expect(isTokenExpired(null)).toBe(true);
+  });
+  it('returns true for undefined tokenData', () => {
+    expect(isTokenExpired(undefined)).toBe(true);
+  });
+  it('returns true for empty object', () => {
+    expect(isTokenExpired({})).toBe(true);
+  });
+  it('returns true for missing decoded field', () => {
+    expect(isTokenExpired({ accessToken: 'test' })).toBe(true);
+  });
+  it('returns true for missing exp in decoded', () => {
+    expect(isTokenExpired({ decoded: { sub: 'user_123' } })).toBe(true);
+  });
+  it('returns true when token is already expired', () => {
+    const exp = Math.floor(Date.now() / 1000) - 60; // 1 minute ago
+    expect(isTokenExpired({ decoded: { exp } })).toBe(true);
+  });
+  it('returns true when within 5-minute expiry buffer', () => {
+    const exp = Math.floor(Date.now() / 1000) + 120; // 2 minutes from now
+    expect(isTokenExpired({ decoded: { exp } })).toBe(true);
+  });
+  it('returns true when exactly at 5-minute buffer', () => {
+    const exp = Math.floor(Date.now() / 1000) + 300; // exactly 5 minutes from now
+    expect(isTokenExpired({ decoded: { exp } })).toBe(true);
+  });
+  it('returns false when more than 5 minutes remaining', () => {
+    const exp = Math.floor(Date.now() / 1000) + 600; // 10 minutes from now
+    expect(isTokenExpired({ decoded: { exp } })).toBe(false);
+  });
+  it('returns false when 6 minutes remaining', () => {
+    const exp = Math.floor(Date.now() / 1000) + 360; // 6 minutes from now
+    expect(isTokenExpired({ decoded: { exp } })).toBe(false);
+  });
+  it('returns false for far future expiration', () => {
+    const exp = 9999999999; // Far future
+    expect(isTokenExpired({ decoded: { exp } })).toBe(false);
+  });
+});
+describe('refreshAccessToken', () => {
+  const originalFetch = global.fetch;
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+  afterEach(() => {
+    global.fetch = originalFetch;
+  });
+  it('throws error when no refresh_token', async () => {
+    await expect(refreshAccessToken({})).rejects.toThrow('No refresh token available');
+  });
+  it('throws error when refresh_token is undefined', async () => {
+    await expect(refreshAccessToken({ refresh_token: undefined })).rejects.toThrow('No refresh token available');
+  });
+  it('calls OAuth endpoint with correct parameters', async () => {
+    global.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve({
+        access_token: 'new_access_token',
+        id_token: 'new_id_token',
+        refresh_token: 'new_refresh_token',
+        token_type: 'Bearer',
+        expires_in: 3600,
+      }),
+    });
+    await refreshAccessToken({ refresh_token: 'rt_123' });
+    expect(global.fetch).toHaveBeenCalledWith(
+      'https://clerk.test.com/oauth/token',
+      expect.objectContaining({
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      })
+    );
+    // Verify the body contains correct params
+    const callArgs = global.fetch.mock.calls[0];
+    const body = callArgs[1].body;
+    expect(body.get('grant_type')).toBe('refresh_token');
+    expect(body.get('refresh_token')).toBe('rt_123');
+    expect(body.get('client_id')).toBe('test_client_id');
+  });
+  it('saves refreshed token to storage', async () => {
+    global.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve({
+        access_token: 'new_access_token',
+        id_token: 'new_id_token',
+        refresh_token: 'new_refresh_token',
+        token_type: 'Bearer',
+        expires_in: 3600,
+      }),
+    });
+    await refreshAccessToken({ refresh_token: 'rt_123' });
+    expect(saveToken).toHaveBeenCalledWith(
+      expect.objectContaining({
+        accessToken: 'new_access_token',
+        idToken: expect.any(String),
+        tokenType: 'Bearer',
+        refresh_token: 'new_refresh_token',
+      })
+    );
+  });
+  it('preserves selectedOrg in refreshed token', async () => {
+    global.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve({
+        access_token: 'new_access_token',
+        id_token: 'new_id_token',
+        refresh_token: 'new_refresh_token',
+        token_type: 'Bearer',
+        expires_in: 3600,
+      }),
+    });
+    const selectedOrg = { id: 'org_456', name: 'Test Org', role: 'admin' };
+    await refreshAccessToken({ refresh_token: 'rt_123', selectedOrg });
+    expect(saveToken).toHaveBeenCalledWith(
+      expect.objectContaining({
+        selectedOrg: selectedOrg,
+      })
+    );
+  });
+  it('gets org-scoped token when selectedOrg exists and refreshed token has sid', async () => {
+    global.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve({
+        access_token: 'new_access_token',
+        id_token: 'new_id_token_with_sid',
+        refresh_token: 'new_refresh_token',
+        token_type: 'Bearer',
+        expires_in: 3600,
+      }),
+    });
+    const selectedOrg = { id: 'org_456', name: 'Test Org', role: 'admin' };
+    await refreshAccessToken({ refresh_token: 'rt_123', selectedOrg });
+    expect(getOrgScopedToken).toHaveBeenCalledWith(
+      'sess_new_123',
+      'org_456',
+      'new_id_token_with_sid'
+    );
+  });
+  it('continues with base token when getOrgScopedToken fails', async () => {
+    global.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve({
+        access_token: 'new_access_token',
+        id_token: 'new_id_token_with_sid',
+        refresh_token: 'new_refresh_token',
+        token_type: 'Bearer',
+        expires_in: 3600,
+      }),
+    });
+    // Make getOrgScopedToken fail
+    vi.mocked(getOrgScopedToken).mockRejectedValueOnce(new Error('API error'));
+    const selectedOrg = { id: 'org_456', name: 'Test Org', role: 'admin' };
+    // Should not throw - continues with base token
+    const result = await refreshAccessToken({ refresh_token: 'rt_123', selectedOrg });
+    expect(result).toBeDefined();
+    expect(result.idToken).toBe('new_id_token_with_sid'); // Falls back to base token
+  });
+  it('throws error when OAuth refresh fails with 400', async () => {
+    global.fetch = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 400,
+      text: () => Promise.resolve(JSON.stringify({
+        error: 'invalid_grant',
+        error_description: 'Refresh token expired',
+      })),
+    });
+    await expect(refreshAccessToken({ refresh_token: 'bad_rt' }))
+      .rejects.toThrow('Token refresh failed');
+  });
+  it('throws error when OAuth refresh fails with 401', async () => {
+    global.fetch = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 401,
+      text: () => Promise.resolve('Unauthorized'),
+    });
+    await expect(refreshAccessToken({ refresh_token: 'bad_rt' }))
+      .rejects.toThrow('Token refresh failed');
+  });
+  it('throws error when network fails', async () => {
+    global.fetch = vi.fn().mockRejectedValue(new Error('Network error'));
+    await expect(refreshAccessToken({ refresh_token: 'rt_123' }))
+      .rejects.toThrow('Token refresh failed');
+  });
+  it('uses existing refresh_token if new one not provided', async () => {
+    global.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve({
+        access_token: 'new_access_token',
+        id_token: 'new_id_token',
+        // No refresh_token in response
+        token_type: 'Bearer',
+        expires_in: 3600,
+      }),
+    });
+    await refreshAccessToken({ refresh_token: 'original_rt' });
+    expect(saveToken).toHaveBeenCalledWith(
+      expect.objectContaining({
+        refresh_token: 'original_rt', // Should preserve original
+      })
+    );
+  });
+});

package/tests/unit/token-validation.test.js ADDED Viewed

@@ -0,0 +1,367 @@
+/**
+ * Unit tests for lib/token-validation.js
+ *
+ * Tests token loading, expiration checking, and org claims recovery.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+// Mock dependencies - using factory functions to avoid hoisting issues
+vi.mock('../../lib/token-storage.js', () => ({
+  getToken: vi.fn(),
+  saveToken: vi.fn(),
+}));
+vi.mock('../../lib/token-refresh.js', () => ({
+  isTokenExpired: vi.fn(),
+  refreshAccessToken: vi.fn(),
+}));
+vi.mock('../../lib/clerk-api.js', () => ({
+  getOrgScopedToken: vi.fn(),
+}));
+vi.mock('../../lib/jwt-utils.js', () => ({
+  parseJWT: vi.fn(),
+}));
+vi.mock('../../lib/config.js', () => ({
+  config: {
+    clerkDomain: 'clerk.test.com',
+    clerkClientId: 'test_client_id',
+    clerkClientSecret: 'test_client_secret',
+  },
+}));
+// Import after mocking
+import { loadAndRefreshToken } from '../../lib/token-validation.js';
+import { getToken, saveToken } from '../../lib/token-storage.js';
+import { isTokenExpired, refreshAccessToken } from '../../lib/token-refresh.js';
+import { getOrgScopedToken } from '../../lib/clerk-api.js';
+import { parseJWT } from '../../lib/jwt-utils.js';
+describe('loadAndRefreshToken', () => {
+  const futureExp = Math.floor(Date.now() / 1000) + 3600;
+  beforeEach(() => {
+    vi.clearAllMocks();
+    // Default: token not expired
+    vi.mocked(isTokenExpired).mockReturnValue(false);
+  });
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+  describe('when not authenticated', () => {
+    it('throws error when requireAuth=true and no token', async () => {
+      vi.mocked(getToken).mockReturnValue(null);
+      await expect(loadAndRefreshToken(true))
+        .rejects.toThrow('Not authenticated');
+    });
+    it('throws error when requireAuth not specified (defaults to true) and no token', async () => {
+      vi.mocked(getToken).mockReturnValue(null);
+      await expect(loadAndRefreshToken())
+        .rejects.toThrow('Not authenticated');
+    });
+    it('returns null when requireAuth=false and no token', async () => {
+      vi.mocked(getToken).mockReturnValue(null);
+      const result = await loadAndRefreshToken(false);
+      expect(result).toBeNull();
+    });
+  });
+  describe('token expiration handling', () => {
+    it('refreshes token when expired', async () => {
+      const expiredToken = {
+        idToken: 'expired_token',
+        decoded: { exp: Math.floor(Date.now() / 1000) - 3600 },
+        refresh_token: 'rt_123',
+      };
+      vi.mocked(getToken).mockReturnValue(expiredToken);
+      vi.mocked(isTokenExpired).mockReturnValue(true);
+      const refreshedToken = {
+        idToken: 'new_token',
+        decoded: { exp: futureExp },
+        refresh_token: 'rt_new',
+      };
+      vi.mocked(refreshAccessToken).mockResolvedValue(refreshedToken);
+      const result = await loadAndRefreshToken();
+      expect(refreshAccessToken).toHaveBeenCalledWith(expiredToken);
+      expect(result).toEqual(refreshedToken);
+    });
+    it('throws when expired with no refresh_token', async () => {
+      const expiredToken = {
+        idToken: 'expired_token',
+        decoded: { exp: Math.floor(Date.now() / 1000) - 3600 },
+        // No refresh_token
+      };
+      vi.mocked(getToken).mockReturnValue(expiredToken);
+      vi.mocked(isTokenExpired).mockReturnValue(true);
+      await expect(loadAndRefreshToken())
+        .rejects.toThrow('no refresh token');
+    });
+    it('throws when refresh fails', async () => {
+      const expiredToken = {
+        idToken: 'expired_token',
+        decoded: { exp: Math.floor(Date.now() / 1000) - 3600 },
+        refresh_token: 'rt_123',
+      };
+      vi.mocked(getToken).mockReturnValue(expiredToken);
+      vi.mocked(isTokenExpired).mockReturnValue(true);
+      vi.mocked(refreshAccessToken).mockRejectedValue(new Error('Refresh failed'));
+      await expect(loadAndRefreshToken())
+        .rejects.toThrow('refresh failed');
+    });
+  });
+  describe('org claims recovery', () => {
+    it('recovers using decoded.sid when org claims missing', async () => {
+      const tokenMissingOrgClaims = {
+        idToken: 'token_no_org',
+        decoded: { exp: futureExp, sid: 'sess_123' },
+        selectedOrg: { id: 'org_456', name: 'Test Org' },
+      };
+      vi.mocked(getToken).mockReturnValue(tokenMissingOrgClaims);
+      vi.mocked(getOrgScopedToken).mockResolvedValue({
+        jwt: 'org_scoped_jwt',
+      });
+      vi.mocked(parseJWT).mockReturnValue({
+        exp: futureExp,
+        o: { o_id: 'org_456' },
+      });
+      await loadAndRefreshToken();
+      expect(getOrgScopedToken).toHaveBeenCalledWith(
+        'sess_123',
+        'org_456',
+        'token_no_org'
+      );
+      expect(saveToken).toHaveBeenCalled();
+    });
+    it('recovers using originalSid when decoded.sid is missing', async () => {
+      const tokenWithOriginalSid = {
+        idToken: 'token_org_scoped',
+        decoded: { exp: futureExp }, // No sid - org-scoped token
+        selectedOrg: { id: 'org_456', name: 'Test Org' },
+        originalSid: 'sess_original',
+      };
+      vi.mocked(getToken).mockReturnValue(tokenWithOriginalSid);
+      vi.mocked(getOrgScopedToken).mockResolvedValue({
+        jwt: 'new_org_scoped_jwt',
+      });
+      vi.mocked(parseJWT).mockReturnValue({
+        exp: futureExp,
+        o: { o_id: 'org_456' },
+      });
+      await loadAndRefreshToken();
+      expect(getOrgScopedToken).toHaveBeenCalledWith(
+        'sess_original',
+        'org_456',
+        'token_org_scoped'
+      );
+    });
+    it('skips recovery when token already has org claims', async () => {
+      const tokenWithOrgClaims = {
+        idToken: 'complete_token',
+        decoded: { exp: futureExp, o: { o_id: 'org_456' } },
+        selectedOrg: { id: 'org_456', name: 'Test Org' },
+      };
+      vi.mocked(getToken).mockReturnValue(tokenWithOrgClaims);
+      const result = await loadAndRefreshToken();
+      expect(getOrgScopedToken).not.toHaveBeenCalled();
+      expect(result.decoded.o).toBeDefined();
+    });
+    it('skips recovery when no selectedOrg (personal account)', async () => {
+      const personalToken = {
+        idToken: 'personal_token',
+        decoded: { exp: futureExp, sid: 'sess_123' },
+        // No selectedOrg - personal account
+      };
+      vi.mocked(getToken).mockReturnValue(personalToken);
+      await loadAndRefreshToken();
+      expect(getOrgScopedToken).not.toHaveBeenCalled();
+    });
+    it('skips recovery when selectedOrg has no id', async () => {
+      const tokenWithEmptyOrg = {
+        idToken: 'token_empty_org',
+        decoded: { exp: futureExp, sid: 'sess_123' },
+        selectedOrg: {}, // Empty org object
+      };
+      vi.mocked(getToken).mockReturnValue(tokenWithEmptyOrg);
+      await loadAndRefreshToken();
+      expect(getOrgScopedToken).not.toHaveBeenCalled();
+    });
+    it('continues gracefully when recovery fails', async () => {
+      const brokenToken = {
+        idToken: 'broken_token',
+        decoded: { exp: futureExp, sid: 'sess_123' },
+        selectedOrg: { id: 'org_456', name: 'Test Org' },
+      };
+      vi.mocked(getToken).mockReturnValue(brokenToken);
+      vi.mocked(getOrgScopedToken).mockRejectedValue(new Error('API error'));
+      // Should not throw, just log warning and return token
+      const result = await loadAndRefreshToken();
+      expect(result).toBeDefined();
+      expect(result.idToken).toBe('broken_token');
+    });
+    it('saves updated token after successful recovery', async () => {
+      const tokenMissingOrgClaims = {
+        idToken: 'token_no_org',
+        decoded: { exp: futureExp, sid: 'sess_123' },
+        selectedOrg: { id: 'org_456', name: 'Test Org' },
+        refresh_token: 'rt_123',
+      };
+      vi.mocked(getToken).mockReturnValue(tokenMissingOrgClaims);
+      vi.mocked(getOrgScopedToken).mockResolvedValue({
+        jwt: 'org_scoped_jwt',
+      });
+      vi.mocked(parseJWT).mockReturnValue({
+        exp: futureExp,
+        o: { o_id: 'org_456' },
+      });
+      await loadAndRefreshToken();
+      expect(saveToken).toHaveBeenCalledWith(
+        expect.objectContaining({
+          idToken: 'org_scoped_jwt',
+        })
+      );
+    });
+  });
+  describe('OAuth refresh fallback for missing sid', () => {
+    const originalFetch = global.fetch;
+    afterEach(() => {
+      global.fetch = originalFetch;
+    });
+    it('attempts OAuth refresh when no sid/originalSid but has refresh_token', async () => {
+      const tokenNoSid = {
+        idToken: 'token_no_sid',
+        decoded: { exp: futureExp }, // No sid
+        selectedOrg: { id: 'org_456', name: 'Test Org' },
+        refresh_token: 'rt_123',
+        // No originalSid either
+      };
+      vi.mocked(getToken).mockReturnValue(tokenNoSid);
+      // Mock fetch for OAuth refresh
+      global.fetch = vi.fn().mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve({
+          access_token: 'new_at',
+          id_token: 'new_idt_with_sid',
+          refresh_token: 'new_rt',
+        }),
+      });
+      // parseJWT returns token with sid after refresh
+      vi.mocked(parseJWT)
+        .mockReturnValueOnce({ exp: futureExp, sid: 'sess_new' }) // First call: parse refreshed token
+        .mockReturnValueOnce({ exp: futureExp, o: { o_id: 'org_456' } }); // Second call: parse org-scoped token
+      vi.mocked(getOrgScopedToken).mockResolvedValue({
+        jwt: 'org_scoped_jwt_after_refresh',
+      });
+      await loadAndRefreshToken();
+      expect(global.fetch).toHaveBeenCalledWith(
+        expect.stringContaining('/oauth/token'),
+        expect.any(Object)
+      );
+    });
+    it('continues without org token when OAuth refresh fails', async () => {
+      const tokenNoSid = {
+        idToken: 'token_no_sid',
+        decoded: { exp: futureExp },
+        selectedOrg: { id: 'org_456', name: 'Test Org' },
+        refresh_token: 'rt_123',
+      };
+      vi.mocked(getToken).mockReturnValue(tokenNoSid);
+      // Mock fetch to fail
+      global.fetch = vi.fn().mockResolvedValue({
+        ok: false,
+        status: 400,
+      });
+      // Should not throw, just return token as-is
+      const result = await loadAndRefreshToken();
+      expect(result).toBeDefined();
+      expect(result.idToken).toBe('token_no_sid');
+    });
+    it('logs warning when no recovery path available', async () => {
+      const fullyBrokenToken = {
+        idToken: 'broken_token',
+        decoded: { exp: futureExp },
+        selectedOrg: { id: 'org_456', name: 'Test Org' },
+        // No sid, no originalSid, no refresh_token
+      };
+      vi.mocked(getToken).mockReturnValue(fullyBrokenToken);
+      // Spy on console.error
+      const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+      const result = await loadAndRefreshToken();
+      // Should still return token (API calls may fail later)
+      expect(result).toBeDefined();
+      // Should have logged warning about missing session ID
+      expect(consoleSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Could not obtain session ID')
+      );
+      consoleSpy.mockRestore();
+    });
+  });
+});