@vybestack/llxprt-code-auth 0.10.0-nightly.260613.1adad3b34

package/dist/src/keyring-token-store.js

@@ -0,0 +1,391 @@
+/**
+ * @license
+ * Copyright 2025 Vybestack LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Keyring-backed OAuth token storage implementing the TokenStore interface.
+ *
+ * Delegates credential CRUD to ISecureStore (injected via DI) and uses
+ * filesystem-based advisory locks for refresh concurrency control.
+ *
+ * @plan PLAN-20260213-KEYRINGTOKENSTORE.P06, PLAN-20260608-ISSUE1586.P09
+ * @requirement R1.1, R1.2, R1.3, REQ-AUTH-001.1
+ */
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { OAuthTokenSchema, } from './types.js';
+// ─── Constants ───────────────────────────────────────────────────────────────
+/** @internal */
+const _SERVICE_NAME = 'llxprt-code-oauth';
+void _SERVICE_NAME;
+// Allow email-style bucket names (e.g., user@example.com) while keeping filenames safe.
+// @fix issue1439 - relaxed from /^[a-zA-Z0-9_-]+$/ to allow '.' and '@'
+const NAME_REGEX = /^[a-zA-Z0-9._@-]{1,64}$/;
+const DEFAULT_BUCKET = 'default';
+const DEFAULT_LOCK_WAIT_MS = 10_000;
+const DEFAULT_STALE_THRESHOLD_MS = 30_000;
+const LOCK_POLL_INTERVAL_MS = 100;
+const LOCK_WRITE_GRACE_MS = 750;
+/** Lazily resolved to avoid crashing when homedir() is undefined at import time. */
+let _lockDir;
+function getLockDir() {
+    // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- intentional falsy coalescing
+    if (!_lockDir) {
+        _lockDir = join(homedir(), '.llxprt', 'oauth', 'locks');
+    }
+    return _lockDir;
+}
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+// ─── KeyringTokenStore Class ─────────────────────────────────────────────────
+/**
+ * Keyring-backed token store with filesystem advisory locks.
+ *
+ * @internal **DO NOT instantiate directly in consumer code.**
+ * Use `createTokenStore()` from `credential-store-factory.ts` instead.
+ *
+ * @plan PLAN-20260213-KEYRINGTOKENSTORE.P06, PLAN-20260608-ISSUE1586.P11
+ * @plan PLAN-20250214-CREDPROXY.P36
+ */
+export class KeyringTokenStore {
+    static NO_OP_LOGGER = {
+        debug: () => { },
+        error: () => { },
+        warn: () => { },
+        log: () => { },
+    };
+    secureStore;
+    logger;
+    lockDir;
+    constructor(options) {
+        if (!options?.secureStore) {
+            throw new Error('KeyringTokenStore requires an ISecureStore instance. ' +
+                'Use createKeyringTokenStore() from core.');
+        }
+        this.secureStore = options.secureStore;
+        this.logger = options.logger ?? KeyringTokenStore.NO_OP_LOGGER;
+        this.lockDir = options.lockDir ?? getLockDir();
+    }
+    validateName(name, label) {
+        if (!NAME_REGEX.test(name)) {
+            throw new Error(`Invalid ${label} name: "${name}". Allowed: letters, numbers, dashes, underscores, dots, @ (1-64 chars).`);
+        }
+    }
+    accountKey(provider, bucket) {
+        const resolvedBucket = bucket ?? DEFAULT_BUCKET;
+        this.validateName(provider, 'provider');
+        this.validateName(resolvedBucket, 'bucket');
+        return `${provider}:${resolvedBucket}`;
+    }
+    /**
+     * Non-cryptographic FNV-1a hash for debug log identifiers.
+     */
+    hashIdentifier(key) {
+        let h = 0x811c9dc5;
+        for (let i = 0; i < key.length; i++) {
+            h ^= key.charCodeAt(i);
+            h = Math.imul(h, 0x01000193);
+        }
+        return (h >>> 0).toString(16).padStart(8, '0');
+    }
+    lockFilePath(provider, bucket) {
+        const resolved = bucket ?? DEFAULT_BUCKET;
+        if (resolved === DEFAULT_BUCKET) {
+            return join(this.lockDir, `${provider}-refresh.lock`);
+        }
+        return join(this.lockDir, `${provider}-${resolved}-refresh.lock`);
+    }
+    authLockFilePath(provider, bucket) {
+        const resolved = bucket ?? DEFAULT_BUCKET;
+        if (resolved === DEFAULT_BUCKET) {
+            return join(this.lockDir, `${provider}-auth.lock`);
+        }
+        return join(this.lockDir, `${provider}-${resolved}-auth.lock`);
+    }
+    /**
+     * Ensures the lock directory exists.
+     */
+    async ensureLockDir() {
+        await fs.mkdir(this.lockDir, { recursive: true, mode: 0o700 });
+    }
+    /**
+     * Shared lock acquisition logic used by both refresh and auth locks.
+     */
+    async acquireLock(lockPath, waitMs, staleMs) {
+        const startTime = Date.now();
+        await this.ensureLockDir();
+        this.logger.debug(`[acquireLock] wait=${waitMs} stale=${staleMs} poll=${LOCK_POLL_INTERVAL_MS}`);
+        // eslint-disable-next-line sonarjs/too-many-break-or-continue-in-loop -- lock acquisition loop
+        while (Date.now() - startTime < waitMs) {
+            const createResult = await this.tryCreateLock(lockPath);
+            if (createResult === 'acquired') {
+                return true;
+            }
+            const checkResult = await this.checkExistingLock(lockPath, staleMs);
+            if (checkResult === 'retry') {
+                await sleep(LOCK_POLL_INTERVAL_MS);
+                continue;
+            }
+            if (checkResult === 'stale_broken') {
+                continue;
+            }
+            await sleep(LOCK_POLL_INTERVAL_MS);
+        }
+        return false;
+    }
+    async tryCreateLock(lockPath) {
+        let createdLockInfo = null;
+        try {
+            const lockInfo = { pid: process.pid, timestamp: Date.now() };
+            await fs.writeFile(lockPath, JSON.stringify(lockInfo), {
+                flag: 'wx',
+                mode: 0o600,
+            });
+            createdLockInfo = lockInfo;
+            try {
+                const content = await fs.readFile(lockPath, 'utf8');
+                const existing = JSON.parse(content);
+                // eslint-disable-next-line sonarjs/nested-control-flow -- lock verification
+                if (existing.pid === createdLockInfo.pid &&
+                    existing.timestamp === createdLockInfo.timestamp) {
+                    return 'acquired';
+                }
+            }
+            catch {
+                // Lock file disappeared or is unreadable
+            }
+        }
+        catch (writeError) {
+            const err = writeError;
+            if (err.code !== 'EEXIST') {
+                throw writeError;
+            }
+        }
+        return 'exists';
+    }
+    async checkExistingLock(lockPath, staleMs) {
+        try {
+            const content = await fs.readFile(lockPath, 'utf8');
+            const existing = JSON.parse(content);
+            const lockAge = Date.now() - existing.timestamp;
+            const hasValidPid = typeof existing.pid === 'number' &&
+                Number.isInteger(existing.pid) &&
+                existing.pid > 0;
+            const isRecentInFlightWrite = !hasValidPid && lockAge <= LOCK_WRITE_GRACE_MS;
+            if (isRecentInFlightWrite) {
+                return 'retry';
+            }
+            if (lockAge > staleMs) {
+                // eslint-disable-next-line sonarjs/nested-control-flow -- stale lock cleanup
+                try {
+                    await fs.unlink(lockPath);
+                }
+                catch {
+                    // Ignore ENOENT
+                }
+                return 'stale_broken';
+            }
+            return 'fresh';
+        }
+        catch {
+            try {
+                const stat = await fs.stat(lockPath);
+                const fileAge = Date.now() - stat.mtimeMs;
+                if (fileAge <= LOCK_WRITE_GRACE_MS) {
+                    return 'retry';
+                }
+            }
+            catch {
+                // Ignore stat errors
+            }
+            try {
+                await fs.unlink(lockPath);
+            }
+            catch {
+                // Ignore ENOENT
+            }
+            return 'stale_broken';
+        }
+    }
+    async releaseLock(lockPath) {
+        try {
+            await fs.unlink(lockPath);
+        }
+        catch (error) {
+            const err = error;
+            if (err.code !== 'ENOENT') {
+                throw error;
+            }
+        }
+    }
+    /**
+     * Validates and persists an OAuth token to ISecureStore.
+     */
+    async saveToken(provider, token, bucket) {
+        const key = this.accountKey(provider, bucket);
+        this.logger.debug(`[saveToken] [${this.hashIdentifier(key)}] type=${token.token_type}`);
+        const validatedToken = OAuthTokenSchema.passthrough().parse(token);
+        const serialized = JSON.stringify(validatedToken);
+        await this.secureStore.set(key, serialized);
+    }
+    /**
+     * Retrieves and validates an OAuth token from ISecureStore.
+     */
+    async getToken(provider, bucket) {
+        const key = this.accountKey(provider, bucket);
+        this.logger.debug(`[getToken] [${this.hashIdentifier(key)}]`);
+        let raw;
+        try {
+            raw = await this.secureStore.get(key);
+        }
+        catch (error) {
+            const ssError = error;
+            if ('code' in ssError && ssError.code === 'CORRUPT') {
+                this.logger.warn(`Corrupt token envelope for [${this.hashIdentifier(key)}]: ${ssError.message}`);
+                return null;
+            }
+            throw error;
+        }
+        if (raw === null) {
+            return null;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (parseError) {
+            const msg = parseError instanceof Error ? parseError.message : String(parseError);
+            this.logger.warn(`Corrupt token JSON for [${this.hashIdentifier(key)}]: ${msg}`);
+            return null;
+        }
+        try {
+            return OAuthTokenSchema.passthrough().parse(parsed);
+        }
+        catch (zodError) {
+            const msg = zodError instanceof Error ? zodError.message : String(zodError);
+            this.logger.warn(`Invalid token schema for [${this.hashIdentifier(key)}]: ${msg}`);
+            return null;
+        }
+    }
+    /**
+     * Removes a token from ISecureStore. Best-effort — errors are swallowed.
+     */
+    async removeToken(provider, bucket) {
+        const key = this.accountKey(provider, bucket);
+        this.logger.debug(`[removeToken] [${this.hashIdentifier(key)}]`);
+        try {
+            await this.secureStore.delete(key);
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            this.logger.warn(`Failed to remove token for [${this.hashIdentifier(key)}]: ${msg}`);
+        }
+    }
+    /**
+     * Lists all unique provider names from ISecureStore keys.
+     */
+    async listProviders() {
+        this.logger.debug(`[listProviders]`);
+        try {
+            const allKeys = await this.secureStore.list();
+            const providerSet = new Set();
+            for (const key of allKeys) {
+                if (key.includes(':')) {
+                    const provider = key.split(':')[0];
+                    providerSet.add(provider);
+                }
+            }
+            return Array.from(providerSet).sort();
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            this.logger.warn(`Failed to list providers: ${msg}`);
+            return [];
+        }
+    }
+    /**
+     * Lists all bucket names for a given provider.
+     */
+    async listBuckets(provider) {
+        this.validateName(provider, 'provider');
+        try {
+            const allKeys = await this.secureStore.list();
+            const prefix = `${provider}:`;
+            const buckets = [];
+            for (const key of allKeys) {
+                if (key.startsWith(prefix)) {
+                    const bucket = key.substring(prefix.length);
+                    buckets.push(bucket);
+                }
+            }
+            return buckets.sort();
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            this.logger.warn(`Failed to list buckets for [${this.hashIdentifier(provider + ':')}]: ${msg}`);
+            return [];
+        }
+    }
+    /**
+     * Returns placeholder bucket statistics if a token exists for the given bucket.
+     */
+    async getBucketStats(provider, bucket) {
+        const token = await this.getToken(provider, bucket);
+        if (token === null) {
+            return null;
+        }
+        return {
+            bucket,
+            requestCount: 0,
+            percentage: 0,
+            lastUsed: undefined,
+        };
+    }
+    /**
+     * Acquires a filesystem-based advisory lock for token refresh.
+     */
+    async acquireRefreshLock(provider, options) {
+        this.validateName(provider, 'provider');
+        if (options?.bucket)
+            this.validateName(options.bucket, 'bucket');
+        const lockPath = this.lockFilePath(provider, options?.bucket);
+        const waitMs = options?.waitMs ?? DEFAULT_LOCK_WAIT_MS;
+        const staleMs = options?.staleMs ?? DEFAULT_STALE_THRESHOLD_MS;
+        return this.acquireLock(lockPath, waitMs, staleMs);
+    }
+    /**
+     * Releases a filesystem-based advisory lock. Idempotent.
+     */
+    async releaseRefreshLock(provider, bucket) {
+        this.validateName(provider, 'provider');
+        if (bucket)
+            this.validateName(bucket, 'bucket');
+        const lockPath = this.lockFilePath(provider, bucket);
+        return this.releaseLock(lockPath);
+    }
+    /**
+     * Acquires a filesystem-based advisory lock for interactive authentication.
+     */
+    async acquireAuthLock(provider, options) {
+        this.validateName(provider, 'provider');
+        if (options?.bucket)
+            this.validateName(options.bucket, 'bucket');
+        const lockPath = this.authLockFilePath(provider, options?.bucket);
+        const waitMs = options?.waitMs ?? 60_000;
+        const staleMs = options?.staleMs ?? 360_000;
+        return this.acquireLock(lockPath, waitMs, staleMs);
+    }
+    /**
+     * Releases the auth lock for a provider. Idempotent.
+     */
+    async releaseAuthLock(provider, bucket) {
+        this.validateName(provider, 'provider');
+        if (bucket)
+            this.validateName(bucket, 'bucket');
+        const lockPath = this.authLockFilePath(provider, bucket);
+        return this.releaseLock(lockPath);
+    }
+}
+//# sourceMappingURL=keyring-token-store.js.map

package/dist/src/keyring-token-store.js.map

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

package/dist/src/oauth-errors.d.ts

@@ -0,0 +1,173 @@
+/**
+ * @license
+ * Copyright 2025 Vybestack LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * OAuth Error Handling System
+ *
+ * Provides comprehensive error classification, user-friendly messaging,
+ * and recovery mechanisms for OAuth providers.
+ */
+/**
+ * OAuth error categories for classification and handling
+ */
+export declare enum OAuthErrorCategory {
+    /** User must take action (re-authenticate, grant permissions) */
+    USER_ACTION_REQUIRED = "user_action_required",
+    /** Network or temporary service issues that can be retried */
+    TRANSIENT = "transient",
+    /** System issues (file permissions, storage problems) */
+    SYSTEM = "system",
+    /** Critical security or data corruption issues */
+    CRITICAL = "critical",
+    /** Configuration or setup problems */
+    CONFIGURATION = "configuration"
+}
+/**
+ * Specific OAuth error types with detailed classification
+ */
+export declare enum OAuthErrorType {
+    AUTHENTICATION_REQUIRED = "authentication_required",
+    AUTHORIZATION_EXPIRED = "authorization_expired",
+    INSUFFICIENT_PERMISSIONS = "insufficient_permissions",
+    USER_CANCELLED = "user_cancelled",
+    INVALID_CREDENTIALS = "invalid_credentials",
+    NETWORK_ERROR = "network_error",
+    SERVICE_UNAVAILABLE = "service_unavailable",
+    RATE_LIMITED = "rate_limited",
+    TIMEOUT = "timeout",
+    STORAGE_ERROR = "storage_error",
+    FILE_PERMISSIONS = "file_permissions",
+    CORRUPTED_DATA = "corrupted_data",
+    SECURITY_VIOLATION = "security_violation",
+    MALFORMED_TOKEN = "malformed_token",
+    INVALID_CLIENT_ID = "invalid_client_id",
+    INVALID_ENDPOINT = "invalid_endpoint",
+    MISSING_CONFIGURATION = "missing_configuration",
+    UNKNOWN = "unknown"
+}
+/**
+ * Retry strategy configuration
+ */
+export interface RetryConfig {
+    /** Maximum number of retry attempts */
+    maxAttempts: number;
+    /** Base delay between retries in milliseconds */
+    baseDelayMs: number;
+    /** Multiplier for exponential backoff */
+    backoffMultiplier: number;
+    /** Maximum delay between retries in milliseconds */
+    maxDelayMs: number;
+    /** Whether to add random jitter to delays */
+    jitter: boolean;
+}
+/**
+ * Default retry configuration for transient errors
+ */
+export declare const DEFAULT_RETRY_CONFIG: RetryConfig;
+/**
+ * Comprehensive OAuth error with classification and user guidance
+ */
+export declare class OAuthError extends Error {
+    readonly category: OAuthErrorCategory;
+    readonly type: OAuthErrorType;
+    readonly provider: string;
+    readonly userMessage: string;
+    readonly actionRequired: string | null;
+    readonly isRetryable: boolean;
+    readonly retryAfterMs: number | null;
+    readonly technicalDetails: Record<string, unknown>;
+    readonly originalError: Error | null;
+    constructor(type: OAuthErrorType, provider: string, message: string, options?: {
+        userMessage?: string;
+        actionRequired?: string;
+        retryAfterMs?: number;
+        technicalDetails?: Record<string, unknown>;
+        originalError?: Error;
+        cause?: Error;
+    });
+    /**
+     * Categorizes error type into handling categories
+     */
+    private categorizeError;
+    /**
+     * Determines if error type is retryable
+     */
+    private determineRetryability;
+    /**
+     * Generates user-friendly error message
+     */
+    private generateUserMessage;
+    /**
+     * Generates actionable guidance for users
+     */
+    private generateActionRequired;
+    /**
+     * Creates a sanitized version of the error for logging
+     */
+    toLogEntry(): Record<string, unknown>;
+}
+/**
+ * Error factory for common OAuth error scenarios
+ */
+export declare class OAuthErrorFactory {
+    /**
+     * Creates an authentication required error
+     */
+    static authenticationRequired(provider: string, details?: Record<string, unknown>): OAuthError;
+    /**
+     * Creates an expired authorization error
+     */
+    static authorizationExpired(provider: string, details?: Record<string, unknown>): OAuthError;
+    /**
+     * Creates a network error with retry capability
+     */
+    static networkError(provider: string, originalError?: Error, details?: Record<string, unknown>): OAuthError;
+    /**
+     * Creates a rate limited error with specific retry delay
+     */
+    static rateLimited(provider: string, retryAfterSeconds?: number, details?: Record<string, unknown>): OAuthError;
+    /**
+     * Creates a storage error
+     */
+    static storageError(provider: string, originalError?: Error, details?: Record<string, unknown>): OAuthError;
+    /**
+     * Creates a corrupted data error
+     */
+    static corruptedData(provider: string, details?: Record<string, unknown>): OAuthError;
+    /**
+     * Creates an error from an unknown error, attempting classification
+     */
+    static fromUnknown(provider: string, error: unknown, context?: string): OAuthError;
+}
+/**
+ * Retry handler with exponential backoff and jitter
+ */
+export declare class RetryHandler {
+    private config;
+    constructor(config?: RetryConfig);
+    /**
+     * Executes operation with retry logic for transient errors
+     */
+    executeWithRetry<T>(operation: () => Promise<T>, provider: string, context?: string): Promise<T>;
+    /**
+     * Sleep utility
+     */
+    private sleep;
+}
+/**
+ * Graceful error handler for OAuth operations
+ */
+export declare class GracefulErrorHandler {
+    private retryHandler;
+    constructor(retryHandler?: RetryHandler);
+    /**
+     * Handles errors gracefully, providing fallback behavior when possible
+     */
+    handleGracefully<T>(operation: () => Promise<T>, fallback: T | (() => T | Promise<T>), provider: string, context?: string): Promise<T>;
+    /**
+     * Wraps a method to handle errors gracefully with logging
+     */
+    wrapMethod<TArgs extends unknown[], TReturn>(method: (...args: TArgs) => Promise<TReturn>, provider: string, methodName: string, fallback?: TReturn | ((...args: TArgs) => TReturn | Promise<TReturn>)): (...args: TArgs) => Promise<TReturn>;
+}