@levr-one/auth 1.0.0

package/dist/token-watcher.js

@@ -0,0 +1,185 @@
+/**
+ * TokenWatcher - Self-Healing Token Management
+ *
+ * Watches the token file for changes and notifies subscribers.
+ * This enables MCP servers to auto-recover when:
+ * - Tokens appear after startup (user runs authorize)
+ * - Tokens are refreshed externally
+ * - Token file is fixed after corruption
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { loadTokens, getTokenFilePath, getTqDir } from './token-store.js';
+const DEFAULT_OPTIONS = {
+    pollInterval: 30000, // 30 seconds
+    expirationWarningMinutes: 5,
+};
+/**
+ * TokenWatcher for self-healing token management
+ *
+ * Usage:
+ * ```typescript
+ * const watcher = new TokenWatcher();
+ * watcher.onTokenChange((tokens) => {
+ *   if (tokens) {
+ *     console.log('Tokens available:', tokens.expiresAt > Date.now() ? 'valid' : 'expired');
+ *   } else {
+ *     console.log('No tokens available');
+ *   }
+ * });
+ * watcher.start();
+ * ```
+ */
+export class TokenWatcher {
+    watcher = null;
+    pollInterval = null;
+    lastTokens = null;
+    lastTokensJson = '';
+    callbacks = new Set();
+    options;
+    isRunning = false;
+    constructor(options) {
+        this.options = { ...DEFAULT_OPTIONS, ...options };
+    }
+    /**
+     * Start watching for token changes
+     */
+    start() {
+        if (this.isRunning) {
+            return;
+        }
+        this.isRunning = true;
+        const tokenFilePath = getTokenFilePath();
+        const tqDir = getTqDir();
+        // Ensure directory exists for watching
+        if (!fs.existsSync(tqDir)) {
+            try {
+                fs.mkdirSync(tqDir, { recursive: true, mode: 0o700 });
+            }
+            catch {
+                console.error('[tq-oauth] Failed to create .tq directory for watching');
+            }
+        }
+        // Watch the directory (not the file) because the file may not exist yet
+        // and fs.watch on a non-existent file fails
+        try {
+            this.watcher = fs.watch(tqDir, (eventType, filename) => {
+                if (filename === path.basename(tokenFilePath)) {
+                    this.checkTokens();
+                }
+            });
+            this.watcher.on('error', (error) => {
+                console.error('[tq-oauth] Watch error:', error);
+                // Continue with polling as fallback
+            });
+        }
+        catch (error) {
+            console.error('[tq-oauth] Failed to start file watcher:', error);
+            // Continue with polling as fallback
+        }
+        // Also poll periodically (backup if fs.watch misses events)
+        // unref so timer doesn't keep the process alive
+        this.pollInterval = setInterval(() => {
+            this.checkTokens();
+        }, this.options.pollInterval);
+        this.pollInterval.unref();
+        // Initial check
+        this.checkTokens();
+    }
+    /**
+     * Stop watching for token changes
+     */
+    stop() {
+        this.isRunning = false;
+        if (this.watcher) {
+            this.watcher.close();
+            this.watcher = null;
+        }
+        if (this.pollInterval) {
+            clearInterval(this.pollInterval);
+            this.pollInterval = null;
+        }
+    }
+    /**
+     * Register a callback for token changes
+     */
+    onTokenChange(callback) {
+        this.callbacks.add(callback);
+        // Immediately notify with current state if watcher is running
+        if (this.isRunning) {
+            callback(this.lastTokens);
+        }
+    }
+    /**
+     * Remove a token change callback
+     */
+    offTokenChange(callback) {
+        this.callbacks.delete(callback);
+    }
+    /**
+     * Get current tokens (synchronous)
+     */
+    getCurrentTokens() {
+        return this.lastTokens;
+    }
+    /**
+     * Get current auth status based on tokens
+     */
+    getAuthStatus() {
+        if (!this.lastTokens) {
+            return 'missing';
+        }
+        const now = Date.now();
+        const warningThreshold = this.options.expirationWarningMinutes * 60 * 1000;
+        if (now >= this.lastTokens.expiresAt) {
+            return 'expired';
+        }
+        if (this.lastTokens.expiresAt - now < warningThreshold) {
+            // Expiring soon - could trigger proactive refresh
+            return 'expired';
+        }
+        return 'ok';
+    }
+    /**
+     * Check if tokens are valid (not expired)
+     */
+    isTokenValid() {
+        return this.getAuthStatus() === 'ok';
+    }
+    /**
+     * Force a token check (useful after manual refresh)
+     */
+    forceCheck() {
+        this.checkTokens();
+    }
+    /**
+     * Internal: Check tokens and notify if changed
+     */
+    checkTokens() {
+        const tokens = loadTokens();
+        const tokensJson = tokens ? JSON.stringify(tokens) : '';
+        // Only notify if tokens actually changed
+        if (tokensJson !== this.lastTokensJson) {
+            this.lastTokens = tokens;
+            this.lastTokensJson = tokensJson;
+            // Log state change
+            if (tokens) {
+                const status = this.getAuthStatus();
+                console.error(`[tq-oauth] Token change detected, status: ${status}`);
+            }
+            else {
+                console.error('[tq-oauth] Token file cleared or missing');
+            }
+            // Notify all callbacks
+            this.callbacks.forEach((cb) => {
+                try {
+                    cb(tokens);
+                }
+                catch (error) {
+                    console.error('[tq-oauth] Error in token change callback:', error);
+                }
+            });
+        }
+    }
+}
+//# sourceMappingURL=token-watcher.js.map

package/dist/token-watcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-watcher.js","sourceRoot":"","sources":["../src/token-watcher.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Shared types for OAuth token management
+ */
+/**
+ * Token response from OAuth server.
+ *
+ * `user` is present on non-refresh grants (authorization_code, device_code,
+ * password) and absent on refresh_token responses — `setTokens()` uses
+ * `user?.workspace_id` to decide whether to persist workspace state.
+ *
+ * The backend also returns a `workspaces` array alongside `user` on initial
+ * grants, but tq-oauth does not cache that list locally (membership can
+ * change between sessions, and `tq:workspace` always fetches a fresh list
+ * from `/v1/auth/sites`). Callers that need the live workspace list should
+ * call the auth sites endpoint directly.
+ */
+export interface TokenResponse {
+    access_token: string;
+    token_type: string;
+    expires_in: number;
+    refresh_token: string;
+    scope: string;
+    user?: {
+        workspace_id: string;
+    };
+}
+/**
+ * Structure for stored tokens
+ */
+export interface StoredTokens {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: number;
+    /** Backend URL this token was issued for (for environment mismatch detection) */
+    apiBaseUrl?: string;
+}
+/**
+ * OAuth client configuration
+ */
+export interface OAuthConfig {
+    /** OAuth authorization server URL (e.g., http://localhost:8080) */
+    authServerUrl: string;
+    /** Registered OAuth client ID */
+    clientId: string;
+    /** Local callback port for receiving authorization code */
+    redirectPort: number;
+    /** Requested OAuth scopes */
+    scopes: string[];
+}
+/**
+ * Device authorization response from POST /v1/oauth/device/authorize
+ * @see https://datatracker.ietf.org/doc/html/rfc8628
+ */
+export interface DeviceAuthorizationResponse {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete: string;
+    expires_in: number;
+    interval: number;
+}
+/**
+ * Authentication status for self-healing
+ */
+export type AuthStatus = 'ok' | 'expired' | 'missing' | 'refreshing' | 'error';
+/**
+ * Callback for token change events
+ */
+export type TokenChangeCallback = (tokens: StoredTokens | null) => void;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,mEAAmE;IACnE,aAAa,EAAE,MAAM,CAAC;IACtB,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,2DAA2D;IAC3D,YAAY,EAAE,MAAM,CAAC;IACrB,6BAA6B;IAC7B,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,2BAA2B;IAC1C,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,yBAAyB,EAAE,MAAM,CAAC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,SAAS,GAAG,SAAS,GAAG,YAAY,GAAG,OAAO,CAAC;AAE/E;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,KAAK,IAAI,CAAC"}

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * Shared types for OAuth token management
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/workspace-store.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Disk-backed workspace state at ~/.tq/workspace.json
+ * Follows the same atomic-write pattern as token-store.ts
+ */
+/**
+ * Identity cache shape. Persisted to ~/.tq/workspace.json alongside the
+ * existing { workspace_id } single field. All fields are required for a
+ * complete identity record — partial files are treated as a cache miss.
+ *
+ * Cache is hint-only: it is consumed for MCP `instructions` and for
+ * `get_context` display. It MUST NOT be used in any security check.
+ */
+export interface IdentityCache {
+    workspace_id: string;
+    user_id: string;
+    user_email: string;
+    user_name: string;
+    role: string;
+}
+/**
+ * Load persisted workspace ID from disk
+ * @returns workspace_id or null if missing/corrupt
+ */
+export declare function loadWorkspace(): string | null;
+/**
+ * Save workspace ID to disk with atomic write
+ */
+export declare function saveWorkspace(workspaceId: string): void;
+/**
+ * Load the full identity cache from disk.
+ *
+ * Reads ~/.tq/workspace.json and returns a typed `IdentityCache` only when
+ * all five required fields are present and are strings. Returns `null` for:
+ *  - missing file
+ *  - malformed JSON
+ *  - legacy single-field shape (`{ workspace_id }` only)
+ *  - any field present but not a string
+ *
+ * Never throws — graceful degradation is mandatory because callers wire this
+ * into startup paths and watcher callbacks.
+ */
+export declare function loadIdentityCache(): IdentityCache | null;
+/**
+ * Save the full identity cache to disk with atomic write.
+ *
+ * Single writer pattern: `saveWorkspace` writes only `{ workspace_id }`;
+ * `saveIdentityCache` is the only path that writes the five-field shape.
+ * After the first identity-aware save, the file always contains all five
+ * fields. Same `.tmp` + `renameSync` pattern as `saveWorkspace`.
+ */
+export declare function saveIdentityCache(data: IdentityCache): void;
+/**
+ * Clear persisted workspace (e.g. on env switch or login)
+ */
+export declare function clearWorkspace(): void;
+/**
+ * Get workspace file path (for debugging)
+ */
+export declare function getWorkspaceFilePath(): string;
+//# sourceMappingURL=workspace-store.d.ts.map

package/dist/workspace-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-store.d.ts","sourceRoot":"","sources":["../src/workspace-store.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAqCH;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,MAAM,GAAG,IAAI,CAc7C;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAEvD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,IAAI,aAAa,GAAG,IAAI,CAmCxD;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CAQ3D;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,IAAI,CASrC;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C"}

package/dist/workspace-store.js

@@ -0,0 +1,147 @@
+/**
+ * Disk-backed workspace state at ~/.tq/workspace.json
+ * Follows the same atomic-write pattern as token-store.ts
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getTqDir } from './token-store.js';
+const WORKSPACE_FILE = 'workspace.json';
+function getWorkspacePath() {
+    return path.join(getTqDir(), WORKSPACE_FILE);
+}
+/**
+ * Atomically write `payload` as JSON to `~/.tq/workspace.json`.
+ * Ensures the ~/.tq directory exists with 0o700, writes to `*.tmp` with
+ * 0o600, then renames over the target. Errors are logged, never thrown.
+ */
+function writeWorkspaceJsonAtomic(payload) {
+    try {
+        const tqDir = getTqDir();
+        if (!fs.existsSync(tqDir)) {
+            fs.mkdirSync(tqDir, { recursive: true, mode: 0o700 });
+        }
+        const filePath = getWorkspacePath();
+        const tempPath = filePath + '.tmp';
+        fs.writeFileSync(tempPath, JSON.stringify(payload, null, 2), {
+            mode: 0o600,
+        });
+        fs.renameSync(tempPath, filePath);
+    }
+    catch (error) {
+        console.error('[tq-oauth] Failed to write workspace.json:', error);
+    }
+}
+/**
+ * Load persisted workspace ID from disk
+ * @returns workspace_id or null if missing/corrupt
+ */
+export function loadWorkspace() {
+    try {
+        const filePath = getWorkspacePath();
+        if (fs.existsSync(filePath)) {
+            const content = fs.readFileSync(filePath, 'utf-8');
+            const data = JSON.parse(content);
+            if (data.workspace_id && typeof data.workspace_id === 'string') {
+                return data.workspace_id;
+            }
+        }
+    }
+    catch (error) {
+        console.error('[tq-oauth] Failed to load workspace:', error);
+    }
+    return null;
+}
+/**
+ * Save workspace ID to disk with atomic write
+ */
+export function saveWorkspace(workspaceId) {
+    writeWorkspaceJsonAtomic({ workspace_id: workspaceId });
+}
+/**
+ * Load the full identity cache from disk.
+ *
+ * Reads ~/.tq/workspace.json and returns a typed `IdentityCache` only when
+ * all five required fields are present and are strings. Returns `null` for:
+ *  - missing file
+ *  - malformed JSON
+ *  - legacy single-field shape (`{ workspace_id }` only)
+ *  - any field present but not a string
+ *
+ * Never throws — graceful degradation is mandatory because callers wire this
+ * into startup paths and watcher callbacks.
+ */
+export function loadIdentityCache() {
+    try {
+        const filePath = getWorkspacePath();
+        if (!fs.existsSync(filePath))
+            return null;
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const data = JSON.parse(content);
+        // `typeof [] === 'object'` — explicitly reject arrays so property
+        // access on a parsed JSON array (`[0]`, `[1]`...) cannot accidentally
+        // satisfy the per-field checks below.
+        if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+            return null;
+        }
+        const keys = [
+            'workspace_id',
+            'user_id',
+            'user_email',
+            'user_name',
+            'role',
+        ];
+        for (const key of keys) {
+            const value = data[key];
+            if (typeof value !== 'string')
+                return null;
+        }
+        return {
+            workspace_id: data.workspace_id,
+            user_id: data.user_id,
+            user_email: data.user_email,
+            user_name: data.user_name,
+            role: data.role,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Save the full identity cache to disk with atomic write.
+ *
+ * Single writer pattern: `saveWorkspace` writes only `{ workspace_id }`;
+ * `saveIdentityCache` is the only path that writes the five-field shape.
+ * After the first identity-aware save, the file always contains all five
+ * fields. Same `.tmp` + `renameSync` pattern as `saveWorkspace`.
+ */
+export function saveIdentityCache(data) {
+    writeWorkspaceJsonAtomic({
+        workspace_id: data.workspace_id,
+        user_id: data.user_id,
+        user_email: data.user_email,
+        user_name: data.user_name,
+        role: data.role,
+    });
+}
+/**
+ * Clear persisted workspace (e.g. on env switch or login)
+ */
+export function clearWorkspace() {
+    try {
+        const filePath = getWorkspacePath();
+        if (fs.existsSync(filePath)) {
+            fs.unlinkSync(filePath);
+        }
+    }
+    catch (error) {
+        console.error('[tq-oauth] Failed to clear workspace:', error);
+    }
+}
+/**
+ * Get workspace file path (for debugging)
+ */
+export function getWorkspaceFilePath() {
+    return getWorkspacePath();
+}
+//# sourceMappingURL=workspace-store.js.map

package/dist/workspace-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-store.js","sourceRoot":"","sources":["../src/workspace-store.ts"],"names":[],"mappings":"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"}

package/dist/workspace-store.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=workspace-store.test.d.ts.map

package/dist/workspace-store.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-store.test.d.ts","sourceRoot":"","sources":["../src/workspace-store.test.ts"],"names":[],"mappings":""}

package/dist/workspace-store.test.js

@@ -0,0 +1,169 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+// Mutable ref so the mock can read the current tmpDir
+const state = vi.hoisted(() => ({ tmpDir: '' }));
+// Mock os.homedir() so token-store's module-level TQ_DIR uses our temp dir
+vi.mock('os', async (importOriginal) => {
+    const original = await importOriginal();
+    return { ...original, homedir: () => state.tmpDir };
+});
+// Re-import each test so module-level constants re-evaluate
+let loadWorkspace;
+let saveWorkspace;
+let clearWorkspace;
+let getWorkspaceFilePath;
+let loadIdentityCache;
+let saveIdentityCache;
+beforeEach(async () => {
+    state.tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tq-ws-test-'));
+    vi.resetModules();
+    const mod = await import('./workspace-store.js');
+    loadWorkspace = mod.loadWorkspace;
+    saveWorkspace = mod.saveWorkspace;
+    clearWorkspace = mod.clearWorkspace;
+    getWorkspaceFilePath = mod.getWorkspaceFilePath;
+    loadIdentityCache = mod.loadIdentityCache;
+    saveIdentityCache = mod.saveIdentityCache;
+});
+afterEach(() => {
+    fs.rmSync(state.tmpDir, { recursive: true, force: true });
+});
+describe('getWorkspaceFilePath', () => {
+    it('returns path to workspace.json', () => {
+        expect(getWorkspaceFilePath()).toBe(path.join(state.tmpDir, '.tq', 'workspace.json'));
+    });
+});
+describe('loadWorkspace', () => {
+    it('returns null when no file exists', () => {
+        expect(loadWorkspace()).toBeNull();
+    });
+    it('returns null for malformed JSON', () => {
+        const tqDir = path.join(state.tmpDir, '.tq');
+        fs.mkdirSync(tqDir, { recursive: true });
+        fs.writeFileSync(path.join(tqDir, 'workspace.json'), 'not-json');
+        expect(loadWorkspace()).toBeNull();
+    });
+    it('returns null for missing workspace_id field', () => {
+        const tqDir = path.join(state.tmpDir, '.tq');
+        fs.mkdirSync(tqDir, { recursive: true });
+        fs.writeFileSync(path.join(tqDir, 'workspace.json'), JSON.stringify({ other: 'field' }));
+        expect(loadWorkspace()).toBeNull();
+    });
+});
+describe('saveWorkspace + loadWorkspace roundtrip', () => {
+    it('saves and loads workspace_id correctly', () => {
+        saveWorkspace('ws-123');
+        const loaded = loadWorkspace();
+        expect(loaded).toBe('ws-123');
+    });
+    it('creates ~/.tq directory if missing', () => {
+        expect(fs.existsSync(path.join(state.tmpDir, '.tq'))).toBe(false);
+        saveWorkspace('ws-123');
+        expect(fs.existsSync(path.join(state.tmpDir, '.tq'))).toBe(true);
+    });
+    it('overwrites existing workspace', () => {
+        saveWorkspace('ws-123');
+        saveWorkspace('ws-456');
+        const loaded = loadWorkspace();
+        expect(loaded).toBe('ws-456');
+    });
+    it('uses atomic write (temp file + rename)', () => {
+        saveWorkspace('ws-123');
+        // Verify the temp file was cleaned up (renamed to final)
+        const tmpFile = getWorkspaceFilePath() + '.tmp';
+        expect(fs.existsSync(tmpFile)).toBe(false);
+        expect(fs.existsSync(getWorkspaceFilePath())).toBe(true);
+    });
+});
+describe('clearWorkspace', () => {
+    it('removes the workspace file', () => {
+        saveWorkspace('ws-123');
+        expect(loadWorkspace()).toBe('ws-123');
+        clearWorkspace();
+        expect(loadWorkspace()).toBeNull();
+    });
+    it('does not throw when no file exists', () => {
+        expect(() => clearWorkspace()).not.toThrow();
+    });
+});
+describe('saveIdentityCache + loadIdentityCache roundtrip', () => {
+    const sample = {
+        workspace_id: 'ws-1',
+        user_id: 'u-1',
+        user_email: 'james@bitmodern.com',
+        user_name: 'James Pitts',
+        role: 'owner',
+    };
+    it('saves and loads all 5 fields', () => {
+        saveIdentityCache(sample);
+        expect(loadIdentityCache()).toEqual(sample);
+    });
+    it('overwrites prior identity cache', () => {
+        saveIdentityCache(sample);
+        saveIdentityCache({ ...sample, workspace_id: 'ws-2', role: 'admin' });
+        expect(loadIdentityCache()).toEqual({
+            ...sample,
+            workspace_id: 'ws-2',
+            role: 'admin',
+        });
+    });
+    it('uses atomic write (temp file cleaned up)', () => {
+        saveIdentityCache(sample);
+        const tmpFile = getWorkspaceFilePath() + '.tmp';
+        expect(fs.existsSync(tmpFile)).toBe(false);
+        expect(fs.existsSync(getWorkspaceFilePath())).toBe(true);
+    });
+    it('saveWorkspace remains backward-compatible: still loads via loadWorkspace', () => {
+        saveIdentityCache(sample);
+        expect(loadWorkspace()).toBe('ws-1');
+    });
+});
+describe('loadIdentityCache', () => {
+    it('returns null when file does not exist', () => {
+        expect(loadIdentityCache()).toBeNull();
+    });
+    it('returns null for legacy single-field shape (workspace_id only)', () => {
+        saveWorkspace('ws-legacy');
+        // saveWorkspace writes only { workspace_id } — identity fields missing
+        expect(loadIdentityCache()).toBeNull();
+    });
+    it('returns null when any identity field is missing', () => {
+        const tqDir = path.join(state.tmpDir, '.tq');
+        fs.mkdirSync(tqDir, { recursive: true });
+        fs.writeFileSync(path.join(tqDir, 'workspace.json'), JSON.stringify({
+            workspace_id: 'ws-1',
+            user_id: 'u-1',
+            user_email: 'a@b.com',
+            // user_name missing
+            role: 'owner',
+        }));
+        expect(loadIdentityCache()).toBeNull();
+    });
+    it('returns null when a field is present but not a string', () => {
+        const tqDir = path.join(state.tmpDir, '.tq');
+        fs.mkdirSync(tqDir, { recursive: true });
+        fs.writeFileSync(path.join(tqDir, 'workspace.json'), JSON.stringify({
+            workspace_id: 'ws-1',
+            user_id: 'u-1',
+            user_email: 'a@b.com',
+            user_name: null,
+            role: 'owner',
+        }));
+        expect(loadIdentityCache()).toBeNull();
+    });
+    it('returns null for malformed JSON', () => {
+        const tqDir = path.join(state.tmpDir, '.tq');
+        fs.mkdirSync(tqDir, { recursive: true });
+        fs.writeFileSync(path.join(tqDir, 'workspace.json'), 'not-json');
+        expect(loadIdentityCache()).toBeNull();
+    });
+    it('returns null when the JSON root is an array (not an object)', () => {
+        const tqDir = path.join(state.tmpDir, '.tq');
+        fs.mkdirSync(tqDir, { recursive: true });
+        fs.writeFileSync(path.join(tqDir, 'workspace.json'), JSON.stringify(['workspace_id', 'user_id', 'a@b.com', 'A', 'owner']));
+        expect(loadIdentityCache()).toBeNull();
+    });
+});
+//# sourceMappingURL=workspace-store.test.js.map