@juspay/neurolink 9.14.0 → 9.15.0

package/dist/lib/auth/tokenStore.js

@@ -0,0 +1,522 @@
+/**
+ * NeuroLink OAuth Token Store
+ *
+ * Secure storage for OAuth tokens with encoding support and multi-provider capability.
+ * Stores tokens in the user's home directory with restrictive permissions.
+ *
+ * Features:
+ * - Multi-provider token storage in a single tokens.json file
+ * - Secure file storage with 0o600 permissions
+ * - Token expiration checking with configurable buffer
+ * - Simple XOR-based obfuscation (not encryption, but not plaintext)
+ * - Automatic token refresh via configurable refresher functions
+ * - Cross-platform support (Unix/macOS/Windows)
+ */
+import { promises as fs } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import { createHash } from "crypto";
+import { logger } from "../utils/logger.js";
+import { TokenStoreError } from "../types/errors.js";
+// Re-export for backward compatibility
+export { TokenStoreError } from "../types/errors.js";
+const { readFile, writeFile, mkdir, unlink, access, chmod, rename } = fs;
+// =============================================================================
+// TOKEN STORE CLASS
+// =============================================================================
+/**
+ * Secure token storage for OAuth tokens with multi-provider support
+ *
+ * Provides persistent storage for OAuth tokens with:
+ * - Multi-provider support in a single file
+ * - Secure file permissions (0o600)
+ * - Optional obfuscation/encoding
+ * - Token expiration checking with buffer
+ * - Automatic token refresh via configurable refreshers
+ *
+ * @example
+ * ```typescript
+ * const store = new TokenStore();
+ *
+ * // Save tokens for a provider
+ * await store.saveTokens("anthropic", {
+ *   accessToken: "sk-...",
+ *   refreshToken: "rt-...",
+ *   expiresAt: Date.now() + 3600000,
+ *   tokenType: "Bearer",
+ * });
+ *
+ * // Set up automatic refresh
+ * store.setTokenRefresher("anthropic", async (refreshToken) => {
+ *   // Call OAuth refresh endpoint
+ *   return newTokens;
+ * });
+ *
+ * // Get a valid token (auto-refreshes if needed)
+ * const token = await store.getValidToken("anthropic");
+ * ```
+ */
+export class TokenStore {
+    static STORAGE_VERSION = "2.0";
+    static NEUROLINK_DIR = ".neurolink";
+    static TOKEN_FILE = "tokens.json";
+    static FILE_PERMISSIONS = 0o600;
+    static DIR_PERMISSIONS = 0o700;
+    /** Default expiration buffer: 5 minutes */
+    static DEFAULT_EXPIRY_BUFFER_MS = 5 * 60 * 1000;
+    storagePath;
+    encryptionEnabled;
+    encryptionKey;
+    tokenRefreshers = new Map();
+    /**
+     * Creates a new TokenStore instance
+     *
+     * @param options - Configuration options
+     * @param options.encryptionEnabled - Whether to enable token obfuscation (default: true)
+     * @param options.customStoragePath - Override the default storage path
+     */
+    constructor(options = {}) {
+        const { encryptionEnabled = true, customStoragePath } = options;
+        this.encryptionEnabled = encryptionEnabled;
+        this.encryptionKey = this.deriveEncryptionKey();
+        if (customStoragePath) {
+            this.storagePath = customStoragePath;
+        }
+        else {
+            this.storagePath = join(homedir(), TokenStore.NEUROLINK_DIR, TokenStore.TOKEN_FILE);
+        }
+    }
+    // ===========================================================================
+    // PUBLIC METHODS
+    // ===========================================================================
+    /**
+     * Gets the path where tokens are stored
+     *
+     * @returns The absolute path to the token storage file
+     */
+    getStoragePath() {
+        return this.storagePath;
+    }
+    /**
+     * Saves OAuth tokens for a specific provider
+     *
+     * @param provider - The provider name (e.g., "anthropic", "openai")
+     * @param tokens - The OAuth tokens to save
+     * @throws TokenStoreError if storage fails
+     */
+    async saveTokens(provider, tokens) {
+        // Validate tokens before saving
+        this.validateTokens(tokens);
+        const storageDir = join(this.storagePath, "..");
+        await this.ensureDirectory(storageDir);
+        // Load existing data or create new
+        let storageData;
+        try {
+            storageData = await this.loadStorageData();
+        }
+        catch (error) {
+            if (error instanceof TokenStoreError && error.code === "NOT_FOUND") {
+                // Create new storage structure
+                storageData = {
+                    version: TokenStore.STORAGE_VERSION,
+                    lastModified: Date.now(),
+                    providers: {},
+                };
+            }
+            else {
+                throw error;
+            }
+        }
+        // Update provider tokens
+        storageData.providers[provider] = {
+            tokens,
+            createdAt: Date.now(),
+            lastAccessed: Date.now(),
+        };
+        storageData.lastModified = Date.now();
+        try {
+            const content = this.encryptionEnabled
+                ? this.obfuscate(JSON.stringify(storageData))
+                : JSON.stringify(storageData, null, 2);
+            // Write to temporary file first for atomic operation
+            const tempPath = `${this.storagePath}.tmp`;
+            await writeFile(tempPath, content, "utf-8");
+            // Set restrictive permissions before moving to final location
+            await chmod(tempPath, TokenStore.FILE_PERMISSIONS);
+            // Rename to final location (atomic on most filesystems)
+            await fs.rename(tempPath, this.storagePath);
+            logger.debug("OAuth tokens saved successfully", {
+                provider,
+                path: this.storagePath,
+                encrypted: this.encryptionEnabled,
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            logger.error("Failed to save OAuth tokens", {
+                provider,
+                error: errorMessage,
+            });
+            throw new TokenStoreError(`Failed to save tokens for ${provider}: ${errorMessage}`, "STORAGE_ERROR");
+        }
+    }
+    /**
+     * Loads stored OAuth tokens for a specific provider
+     *
+     * @param provider - The provider name (e.g., "anthropic", "openai")
+     * @returns The stored tokens, or null if not found
+     * @throws TokenStoreError if reading fails (other than file not found)
+     */
+    async loadTokens(provider) {
+        try {
+            const storageData = await this.loadStorageData();
+            const providerData = storageData.providers[provider];
+            if (!providerData) {
+                logger.debug("No stored tokens found for provider", { provider });
+                return null;
+            }
+            // Update last accessed time
+            providerData.lastAccessed = Date.now();
+            await this.saveStorageData(storageData);
+            logger.debug("OAuth tokens retrieved successfully", {
+                provider,
+                expiresAt: new Date(providerData.tokens.expiresAt).toISOString(),
+                isExpired: this.isTokenExpired(providerData.tokens),
+            });
+            return providerData.tokens;
+        }
+        catch (error) {
+            if (error instanceof TokenStoreError && error.code === "NOT_FOUND") {
+                return null;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Clears stored tokens for a specific provider
+     *
+     * @param provider - The provider name (e.g., "anthropic", "openai")
+     * @throws TokenStoreError if deletion fails
+     */
+    async clearTokens(provider) {
+        try {
+            const storageData = await this.loadStorageData();
+            if (!storageData.providers[provider]) {
+                logger.debug("No tokens to clear for provider", { provider });
+                return;
+            }
+            delete storageData.providers[provider];
+            storageData.lastModified = Date.now();
+            // If no more providers, delete the file entirely
+            if (Object.keys(storageData.providers).length === 0) {
+                await this.deleteStorageFile();
+            }
+            else {
+                await this.saveStorageData(storageData);
+            }
+            logger.info("OAuth tokens cleared successfully", { provider });
+        }
+        catch (error) {
+            if (error instanceof TokenStoreError && error.code === "NOT_FOUND") {
+                logger.debug("No tokens to clear for provider", { provider });
+                return;
+            }
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            logger.error("Failed to clear OAuth tokens", {
+                provider,
+                error: errorMessage,
+            });
+            throw new TokenStoreError(`Failed to clear tokens for ${provider}: ${errorMessage}`, "STORAGE_ERROR");
+        }
+    }
+    /**
+     * Checks if the given tokens are expired
+     *
+     * @param tokens - The OAuth tokens to check
+     * @param bufferMs - Buffer time in milliseconds before actual expiration (default: 5 minutes)
+     * @returns true if token is expired or will expire within buffer time
+     */
+    isTokenExpired(tokens, bufferMs = TokenStore.DEFAULT_EXPIRY_BUFFER_MS) {
+        const now = Date.now();
+        return tokens.expiresAt - bufferMs <= now;
+    }
+    /**
+     * Gets a valid access token for a provider, refreshing if needed
+     *
+     * If the stored token is expired or about to expire, and a refresher
+     * function has been set, it will automatically refresh the token.
+     *
+     * @param provider - The provider name (e.g., "anthropic", "openai")
+     * @returns The valid access token, or null if not available
+     * @throws TokenStoreError if refresh fails
+     */
+    async getValidToken(provider) {
+        const tokens = await this.loadTokens(provider);
+        if (!tokens) {
+            logger.debug("No tokens found for provider", { provider });
+            return null;
+        }
+        // Check if token is expired or about to expire
+        if (this.isTokenExpired(tokens)) {
+            logger.debug("Token expired or expiring soon", {
+                provider,
+                expiresAt: new Date(tokens.expiresAt).toISOString(),
+            });
+            // Try to refresh if a refresher is configured
+            const refresher = this.tokenRefreshers.get(provider);
+            if (refresher && tokens.refreshToken) {
+                try {
+                    logger.info("Refreshing expired token", { provider });
+                    const newTokens = await refresher(tokens.refreshToken);
+                    // Save the new tokens
+                    await this.saveTokens(provider, newTokens);
+                    logger.info("Token refreshed successfully", { provider });
+                    return newTokens.accessToken;
+                }
+                catch (error) {
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    logger.error("Failed to refresh token", {
+                        provider,
+                        error: errorMessage,
+                    });
+                    throw new TokenStoreError(`Failed to refresh token for ${provider}: ${errorMessage}`, "REFRESH_ERROR");
+                }
+            }
+            else {
+                logger.debug("No refresher configured or no refresh token available", {
+                    provider,
+                    hasRefresher: !!refresher,
+                    hasRefreshToken: !!tokens.refreshToken,
+                });
+                return null;
+            }
+        }
+        return tokens.accessToken;
+    }
+    /**
+     * Sets the token refresher function for a provider
+     *
+     * The refresher function will be called automatically when getValidToken
+     * detects that the stored token is expired or about to expire.
+     *
+     * @param provider - The provider name (e.g., "anthropic", "openai")
+     * @param refresher - Function that takes a refresh token and returns new tokens
+     */
+    setTokenRefresher(provider, refresher) {
+        this.tokenRefreshers.set(provider, refresher);
+        logger.debug("Token refresher set for provider", { provider });
+    }
+    /**
+     * Removes the token refresher function for a provider
+     *
+     * @param provider - The provider name (e.g., "anthropic", "openai")
+     */
+    clearTokenRefresher(provider) {
+        this.tokenRefreshers.delete(provider);
+        logger.debug("Token refresher cleared for provider", { provider });
+    }
+    /**
+     * Checks if tokens exist for a specific provider
+     *
+     * @param provider - The provider name (e.g., "anthropic", "openai")
+     * @returns true if tokens are stored for the provider
+     */
+    async hasTokens(provider) {
+        try {
+            const tokens = await this.loadTokens(provider);
+            return tokens !== null;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Lists all providers that have stored tokens
+     *
+     * @returns Array of provider names
+     */
+    async listProviders() {
+        try {
+            const storageData = await this.loadStorageData();
+            return Object.keys(storageData.providers);
+        }
+        catch (error) {
+            if (error instanceof TokenStoreError && error.code === "NOT_FOUND") {
+                return [];
+            }
+            throw error;
+        }
+    }
+    /**
+     * Clears all stored tokens for all providers
+     *
+     * @throws TokenStoreError if deletion fails
+     */
+    async clearAllTokens() {
+        await this.deleteStorageFile();
+        logger.info("All OAuth tokens cleared");
+    }
+    // ===========================================================================
+    // PRIVATE HELPER METHODS
+    // ===========================================================================
+    /**
+     * Loads the storage data from file
+     */
+    async loadStorageData() {
+        try {
+            await access(this.storagePath);
+        }
+        catch {
+            // File doesn't exist, return empty storage
+            throw new TokenStoreError("Token storage file not found", "NOT_FOUND");
+        }
+        try {
+            const content = await readFile(this.storagePath, "utf-8");
+            let storageData;
+            if (this.encryptionEnabled) {
+                const decrypted = this.deobfuscate(content);
+                storageData = JSON.parse(decrypted);
+            }
+            else {
+                storageData = JSON.parse(content);
+            }
+            // Validate storage data structure
+            if (!storageData.providers || !storageData.version) {
+                throw new TokenStoreError("Invalid token storage format", "VALIDATION_ERROR");
+            }
+            return storageData;
+        }
+        catch (error) {
+            if (error instanceof TokenStoreError) {
+                throw error;
+            }
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            logger.error("Failed to read token storage", { error: errorMessage });
+            throw new TokenStoreError(`Failed to read token storage: ${errorMessage}`, "STORAGE_ERROR");
+        }
+    }
+    /**
+     * Saves storage data to file
+     */
+    async saveStorageData(data) {
+        try {
+            const content = this.encryptionEnabled
+                ? this.obfuscate(JSON.stringify(data))
+                : JSON.stringify(data, null, 2);
+            const tmpPath = `${this.storagePath}.tmp`;
+            await writeFile(tmpPath, content, "utf-8");
+            await chmod(tmpPath, TokenStore.FILE_PERMISSIONS);
+            await rename(tmpPath, this.storagePath);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            throw new TokenStoreError(`Failed to save token storage: ${errorMessage}`, "STORAGE_ERROR");
+        }
+    }
+    /**
+     * Deletes the storage file
+     */
+    async deleteStorageFile() {
+        try {
+            await access(this.storagePath);
+            await unlink(this.storagePath);
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                // File doesn't exist, nothing to delete
+                return;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Validates token structure
+     */
+    validateTokens(tokens) {
+        if (!tokens.accessToken || typeof tokens.accessToken !== "string") {
+            throw new TokenStoreError("Invalid access token: must be a non-empty string", "VALIDATION_ERROR");
+        }
+        if (tokens.refreshToken !== undefined &&
+            typeof tokens.refreshToken !== "string") {
+            throw new TokenStoreError("Invalid refresh token: must be a string when provided", "VALIDATION_ERROR");
+        }
+        if (typeof tokens.expiresAt !== "number" || tokens.expiresAt <= 0) {
+            throw new TokenStoreError("Invalid expiresAt: must be a positive number", "VALIDATION_ERROR");
+        }
+        if (!tokens.tokenType || typeof tokens.tokenType !== "string") {
+            throw new TokenStoreError("Invalid token type: must be a non-empty string", "VALIDATION_ERROR");
+        }
+    }
+    /**
+     * Ensures the storage directory exists with proper permissions
+     */
+    async ensureDirectory(dirPath) {
+        try {
+            await mkdir(dirPath, {
+                recursive: true,
+                mode: TokenStore.DIR_PERMISSIONS,
+            });
+        }
+        catch {
+            // Directory might already exist, try to set permissions
+            try {
+                await chmod(dirPath, TokenStore.DIR_PERMISSIONS);
+            }
+            catch {
+                // Ignore permission errors on existing directories
+            }
+        }
+    }
+    /**
+     * Derives an encoding key from machine-specific information
+     * This provides basic obfuscation - for production use, consider
+     * using proper encryption with a user-provided key or system keychain
+     */
+    deriveEncryptionKey() {
+        const machineInfo = `${homedir()}-neurolink-token-store`;
+        return createHash("sha256").update(machineInfo).digest("hex");
+    }
+    /**
+     * Simple XOR-based obfuscation
+     * Note: This is NOT cryptographically secure, just basic obfuscation
+     * For production use, consider using node:crypto with proper encryption
+     */
+    obfuscate(data) {
+        const key = this.encryptionKey;
+        let result = "";
+        for (let i = 0; i < data.length; i++) {
+            const charCode = data.charCodeAt(i) ^ key.charCodeAt(i % key.length);
+            result += String.fromCharCode(charCode);
+        }
+        // Encode as base64 for safe storage
+        return Buffer.from(result, "binary").toString("base64");
+    }
+    /**
+     * Reverses the XOR obfuscation
+     */
+    deobfuscate(data) {
+        const key = this.encryptionKey;
+        // Decode from base64
+        const decoded = Buffer.from(data, "base64").toString("binary");
+        let result = "";
+        for (let i = 0; i < decoded.length; i++) {
+            const charCode = decoded.charCodeAt(i) ^ key.charCodeAt(i % key.length);
+            result += String.fromCharCode(charCode);
+        }
+        return result;
+    }
+}
+// =============================================================================
+// SINGLETON INSTANCE
+// =============================================================================
+/**
+ * Default token store singleton instance
+ * Uses default configuration with encryption enabled
+ */
+export const tokenStore = new TokenStore();
+/**
+ * Alias for backward compatibility
+ * @deprecated Use tokenStore instead
+ */
+export const defaultTokenStore = tokenStore;
+//# sourceMappingURL=tokenStore.js.map

package/dist/lib/constants/enums.d.ts

@@ -486,3 +486,23 @@ export declare enum ErrorSeverity {
     HIGH = "high",
     CRITICAL = "critical"
 }
+/**
+ * Beta features available for Anthropic API
+ *
+ * @description Beta feature flags that can be enabled for enhanced functionality:
+ * - CLAUDE_CODE: Claude Code beta features for development workflows
+ * - INTERLEAVED_THINKING: Enables interleaved thinking in responses
+ * - FINE_GRAINED_STREAMING: Fine-grained tool streaming for better UX
+ */
+export declare enum AnthropicBetaFeature {
+    CLAUDE_CODE = "claude-code-20250219",
+    INTERLEAVED_THINKING = "interleaved-thinking-2025-05-14",
+    FINE_GRAINED_STREAMING = "fine-grained-tool-streaming-2025-05-14"
+}
+/**
+ * Buffer time in milliseconds before token expiry to trigger refresh
+ *
+ * @description Tokens are refreshed 5 minutes before expiry to prevent
+ * authentication failures during ongoing operations
+ */
+export declare const TOKEN_EXPIRY_BUFFER_MS: number;

package/dist/lib/constants/enums.js

@@ -656,4 +656,34 @@ export var ErrorSeverity;
     ErrorSeverity["HIGH"] = "high";
     ErrorSeverity["CRITICAL"] = "critical";
 })(ErrorSeverity || (ErrorSeverity = {}));
+// ============================================================================
+// CLAUDE SUBSCRIPTION ENUMS
+// ============================================================================
+// Note: ClaudeSubscriptionTier and AnthropicAuthMethod are defined as type
+// aliases in types/subscriptionTypes.ts (canonical definitions).
+// The type aliases support all 6 tier values: free, pro, max, max_5, max_20, api.
+/**
+ * Beta features available for Anthropic API
+ *
+ * @description Beta feature flags that can be enabled for enhanced functionality:
+ * - CLAUDE_CODE: Claude Code beta features for development workflows
+ * - INTERLEAVED_THINKING: Enables interleaved thinking in responses
+ * - FINE_GRAINED_STREAMING: Fine-grained tool streaming for better UX
+ */
+export var AnthropicBetaFeature;
+(function (AnthropicBetaFeature) {
+    AnthropicBetaFeature["CLAUDE_CODE"] = "claude-code-20250219";
+    AnthropicBetaFeature["INTERLEAVED_THINKING"] = "interleaved-thinking-2025-05-14";
+    AnthropicBetaFeature["FINE_GRAINED_STREAMING"] = "fine-grained-tool-streaming-2025-05-14";
+})(AnthropicBetaFeature || (AnthropicBetaFeature = {}));
+// ============================================================================
+// ANTHROPIC OAUTH CONSTANTS
+// ============================================================================
+/**
+ * Buffer time in milliseconds before token expiry to trigger refresh
+ *
+ * @description Tokens are refreshed 5 minutes before expiry to prevent
+ * authentication failures during ongoing operations
+ */
+export const TOKEN_EXPIRY_BUFFER_MS = 5 * 60 * 1000; // 5 minutes
 //# sourceMappingURL=enums.js.map

package/dist/lib/constants/index.d.ts

@@ -187,6 +187,8 @@ export declare const CONSTANTS_METADATA: {
     readonly VERSION: "1.0.0";
     readonly LAST_UPDATED: "2025-01-27";
     readonly TOTAL_CONSTANTS: 300;
-    readonly CATEGORIES: readonly ["timeouts", "retry", "performance", "tokens"];
+    readonly CATEGORIES: readonly ["timeouts", "retry", "performance", "tokens", "enums"];
     readonly COMPATIBILITY: "backward_compatible";
 };
+export { AIProviderName, OpenRouterModels, BedrockModels, OpenAIModels, AzureOpenAIModels, VertexModels, GoogleAIModels, AnthropicModels, MistralModels, OllamaModels, LiteLLMModels, HuggingFaceModels, SageMakerModels, APIVersions, ErrorCategory, ErrorSeverity, AnthropicBetaFeature, TOKEN_EXPIRY_BUFFER_MS, } from "./enums.js";
+export type { ClaudeSubscriptionTier, AnthropicAuthMethod, } from "../types/subscriptionTypes.js";

package/dist/lib/constants/index.js

@@ -190,7 +190,17 @@ export const CONSTANTS_METADATA = {
     VERSION: "1.0.0",
     LAST_UPDATED: "2025-01-27",
     TOTAL_CONSTANTS: 300,
-    CATEGORIES: ["timeouts", "retry", "performance", "tokens"],
+    CATEGORIES: ["timeouts", "retry", "performance", "tokens", "enums"],
     COMPATIBILITY: "backward_compatible",
 };
+// ===== ENUMS =====
+export { 
+// Provider and Model Enums
+AIProviderName, OpenRouterModels, BedrockModels, OpenAIModels, AzureOpenAIModels, VertexModels, GoogleAIModels, AnthropicModels, MistralModels, OllamaModels, LiteLLMModels, HuggingFaceModels, SageMakerModels, APIVersions, 
+// Error Enums
+ErrorCategory, ErrorSeverity, 
+// Claude Subscription Enums
+AnthropicBetaFeature, 
+// OAuth Constants
+TOKEN_EXPIRY_BUFFER_MS, } from "./enums.js";
 //# sourceMappingURL=index.js.map

package/dist/lib/index.d.ts

@@ -192,7 +192,7 @@ export declare function createBestAIProvider(requestedProvider?: string, modelNa
  * ```
  */
 export { CircuitBreakerManager, calculateExpiresAt, createMCPServer, createOAuthProviderFromConfig, DEFAULT_HTTP_RETRY_CONFIG, DEFAULT_RATE_LIMIT_CONFIG, executeMCP, FileTokenStorage, getMCPStats, getServerInfo, globalCircuitBreakerManager, globalRateLimiterManager, HTTPRateLimiter, InMemoryTokenStorage, initializeMCPEcosystem, isRetryableHTTPError, isRetryableStatusCode, isTokenExpired, listMCPs, MCPCircuitBreaker, mcpLogger, NeuroLinkOAuthProvider, RateLimiterManager, validateServerTools, validateTool as validateMCPTool, withHTTPRetry, } from "./mcp/index.js";
-export type { AuthorizationUrlResult, DiscoveredMcp, HTTPRetryConfig, MCPOAuthConfig, McpMetadata, OAuthClientInformation, OAuthTokens, RateLimitConfig, TokenExchangeRequest, TokenStorage, } from "./types/mcpTypes.js";
+export type { AuthorizationUrlResult, DiscoveredMcp, HTTPRetryConfig, MCPOAuthConfig, McpMetadata, OAuthClientInformation, OAuthTokens as McpOAuthTokens, RateLimitConfig, TokenExchangeRequest, TokenStorage, } from "./types/mcpTypes.js";
 export type { ExecutionContext, ToolExecutionResult, ToolInfo, } from "./types/tools.js";
 export type { LogLevel } from "./types/utilities.js";
 export { logger } from "./utils/logger.js";