@stdiobus/workers-registry 1.4.14 → 1.5.0-beta.2

package/out/tsc/workers-registry/registry-launcher/src/auth/session.test.d.ts

@@ -0,0 +1 @@
+export {};

package/out/tsc/workers-registry/registry-launcher/src/auth/state.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Minimum number of random bytes for state parameter.
+ * 32 bytes provides 256 bits of entropy for CSRF protection.
+ */
+export declare const STATE_MIN_BYTES = 32;
+/**
+ * Generate a cryptographically secure state parameter.
+ *
+ * Generates at least 32 bytes of cryptographic randomness using
+ * Node.js crypto.randomBytes, then encodes as base64url without padding.
+ *
+ * @returns Base64url-encoded random bytes (at least 32 bytes)
+ */
+export declare function generateState(): string;
+/**
+ * Validate a returned state parameter against the expected value.
+ *
+ * Uses constant-time comparison to prevent timing attacks.
+ * Returns false for missing, empty, or mismatched state parameters.
+ * Never throws exceptions - always returns boolean.
+ *
+ * @param expected - The original state parameter
+ * @param received - The state parameter from the callback
+ * @returns True if the states match exactly, false otherwise
+ */
+export declare function validateState(expected: string | null | undefined, received: string | null | undefined): boolean;

package/out/tsc/workers-registry/registry-launcher/src/auth/state.property.test.d.ts

@@ -0,0 +1 @@
+export {};

package/out/tsc/workers-registry/registry-launcher/src/auth/state.test.d.ts

@@ -0,0 +1 @@
+export {};

package/out/tsc/workers-registry/registry-launcher/src/auth/storage/credential-store.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Main credential store facade.
+ *
+ * Selects the best available storage backend (keychain > encrypted file > memory).
+ * Provides a unified interface for credential storage regardless of the underlying backend.
+ *
+ * @module storage/credential-store
+ */
+import type { AuthProviderId, StorageBackendType, StoredCredentials } from '../types.js';
+import type { ICredentialStore } from './types.js';
+/**
+ * Options for creating a credential store.
+ */
+export interface CredentialStoreOptions {
+    /** Preferred storage backend (overrides automatic selection) */
+    preferredBackend?: StorageBackendType;
+    /** Custom path for encrypted file storage */
+    encryptedFilePath?: string;
+}
+/**
+ * Credential store implementation.
+ *
+ * Automatically selects the best available storage backend:
+ * 1. Keychain (most secure, OS-level protection)
+ * 2. Encrypted file (secure, portable)
+ * 3. Memory (testing only, not persistent)
+ *
+ * The backend selection happens lazily on first use.
+ */
+export declare class CredentialStore implements ICredentialStore {
+    private backend;
+    private backendInitialized;
+    private readonly options;
+    /**
+     * Create a new credential store.
+     * @param options - Configuration options
+     */
+    constructor(options?: CredentialStoreOptions);
+    /**
+     * Initialize the storage backend.
+     * Selects the best available backend based on system capabilities.
+     */
+    private initializeBackend;
+    /**
+     * Create a specific backend by type.
+     */
+    private createBackend;
+    /**
+     * Get the initialized backend.
+     */
+    private getBackend;
+    /**
+     * Store credentials for a provider.
+     * @param providerId - The provider identifier
+     * @param credentials - The credentials to store
+     */
+    store(providerId: AuthProviderId, credentials: StoredCredentials): Promise<void>;
+    /**
+     * Retrieve credentials for a provider.
+     * @param providerId - The provider identifier
+     * @returns The stored credentials or null if not found
+     */
+    retrieve(providerId: AuthProviderId): Promise<StoredCredentials | null>;
+    /**
+     * Delete credentials for a provider.
+     * @param providerId - The provider identifier
+     */
+    delete(providerId: AuthProviderId): Promise<void>;
+    /**
+     * Delete all stored credentials.
+     */
+    deleteAll(): Promise<void>;
+    /**
+     * List all providers with stored credentials.
+     * @returns Array of provider identifiers
+     */
+    listProviders(): Promise<AuthProviderId[]>;
+    /**
+     * Get the active storage backend type.
+     * @returns The backend type currently in use
+     */
+    getBackendType(): StorageBackendType;
+    /**
+     * Check if the store has been initialized.
+     * @returns True if a backend has been selected
+     */
+    isInitialized(): boolean;
+    /**
+     * Force re-initialization of the backend.
+     * Useful for testing or when system capabilities change.
+     */
+    reinitialize(): Promise<void>;
+}
+/**
+ * Create a credential store with default options.
+ * @returns A new credential store instance
+ */
+export declare function createCredentialStore(options?: CredentialStoreOptions): CredentialStore;

package/out/tsc/workers-registry/registry-launcher/src/auth/storage/credential-store.test.d.ts

@@ -0,0 +1 @@
+export {};

package/out/tsc/workers-registry/registry-launcher/src/auth/storage/encrypted-file-backend.d.ts

@@ -0,0 +1,101 @@
+import type { AuthProviderId, StorageBackendType, StoredCredentials } from '../types.js';
+import type { IStorageBackend } from './types.js';
+/**
+ * Custom error for credential store corruption.
+ */
+export declare class CredentialStoreCorruptedError extends Error {
+    readonly cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+/**
+ * Encrypted file storage backend implementation.
+ *
+ * Uses AES-256-GCM encryption with a key derived from:
+ * - Random salt (stored with file, unique per file)
+ * - Machine-specific entropy (hostname, username)
+ *
+ * This provides both uniqueness (random salt) and machine binding (entropy).
+ *
+ * Requirements: 5.2, 5.3
+ */
+export declare class EncryptedFileBackend implements IStorageBackend {
+    readonly type: StorageBackendType;
+    /** Cached encryption key (derived once per instance, per salt) */
+    private encryptionKey;
+    /** Cached salt from current file */
+    private currentSalt;
+    /** Path to the credentials file */
+    private readonly filePath;
+    /** Path to the config directory */
+    private readonly configDir;
+    /**
+     * Create a new EncryptedFileBackend instance.
+     * @param customPath - Optional custom path for the credentials file (for testing)
+     */
+    constructor(customPath?: string);
+    /**
+     * Check if the backend is available.
+     * Tests if the config directory is writable.
+     * @returns True if the file system is writable
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Store credentials for a provider.
+     * @param providerId - The provider identifier
+     * @param credentials - The credentials to store
+     */
+    store(providerId: AuthProviderId, credentials: StoredCredentials): Promise<void>;
+    /**
+     * Retrieve credentials for a provider.
+     * @param providerId - The provider identifier
+     * @returns The stored credentials or null if not found
+     */
+    retrieve(providerId: AuthProviderId): Promise<StoredCredentials | null>;
+    /**
+     * Delete credentials for a provider.
+     * @param providerId - The provider identifier
+     */
+    delete(providerId: AuthProviderId): Promise<void>;
+    /**
+     * Delete all stored credentials.
+     */
+    deleteAll(): Promise<void>;
+    /**
+     * List all providers with stored credentials.
+     * @returns Array of provider IDs that have stored credentials
+     */
+    listProviders(): Promise<AuthProviderId[]>;
+    /**
+     * Derive the encryption key from salt and machine-specific entropy.
+     * Uses PBKDF2 with random salt + hostname + username.
+     * @param salt - The random salt (32 bytes)
+     * @returns The derived 256-bit encryption key
+     */
+    private deriveKey;
+    /**
+     * Encrypt data using AES-256-GCM.
+     * @param plaintext - The data to encrypt
+     * @param salt - The salt to use for key derivation
+     * @returns Buffer containing Salt + IV + Auth Tag + Ciphertext
+     */
+    private encrypt;
+    /**
+     * Decrypt data using AES-256-GCM.
+     * @param data - Buffer containing Salt + IV + Auth Tag + Ciphertext
+     * @returns The decrypted plaintext
+     * @throws CredentialStoreCorruptedError if decryption fails
+     */
+    private decrypt;
+    /**
+     * Load the credentials store from the encrypted file.
+     * @returns The decrypted credentials store
+     * @throws CredentialStoreCorruptedError if the file exists but cannot be decrypted
+     */
+    private loadStore;
+    /**
+     * Save the credentials store to the encrypted file.
+     * Sets restrictive file permissions (0600 - owner read/write only).
+     * @param store - The credentials store to save
+     */
+    private saveStore;
+}

package/out/tsc/workers-registry/registry-launcher/src/auth/storage/encrypted-file-backend.test.d.ts

@@ -0,0 +1 @@
+export {};

package/out/tsc/workers-registry/registry-launcher/src/auth/storage/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Storage module exports.
+ *
+ * @module storage
+ */
+export type { ICredentialStore, IStorageBackend } from './types.js';
+export { CredentialStore, createCredentialStore } from './credential-store.js';
+export type { CredentialStoreOptions } from './credential-store.js';
+export { MemoryBackend } from './memory-backend.js';
+export { EncryptedFileBackend, CredentialStoreCorruptedError } from './encrypted-file-backend.js';
+export { KeychainBackend } from './keychain-backend.js';
+export type { KeytarModule } from './keychain-backend.js';

package/out/tsc/workers-registry/registry-launcher/src/auth/storage/keychain-backend.d.ts

@@ -0,0 +1,80 @@
+/**
+ * OS keychain storage backend.
+ *
+ * Uses macOS Keychain, Windows Credential Manager, or Linux Secret Service
+ * via the keytar package for secure credential storage.
+ *
+ * @module storage/keychain-backend
+ */
+import type { AuthProviderId, StorageBackendType, StoredCredentials } from '../types.js';
+import type { IStorageBackend } from './types.js';
+/**
+ * Keytar module interface (subset of keytar API we use).
+ */
+export interface KeytarModule {
+    setPassword(service: string, account: string, password: string): Promise<void>;
+    getPassword(service: string, account: string): Promise<string | null>;
+    deletePassword(service: string, account: string): Promise<boolean>;
+    findCredentials(service: string): Promise<Array<{
+        account: string;
+        password: string;
+    }>>;
+}
+/**
+ * Keychain storage backend implementation.
+ *
+ * Uses the system keychain for secure credential storage:
+ * - macOS: Keychain Access
+ * - Windows: Credential Manager
+ * - Linux: Secret Service (libsecret)
+ *
+ * Handles keychain unavailability gracefully by returning false from isAvailable().
+ */
+export declare class KeychainBackend implements IStorageBackend {
+    readonly type: StorageBackendType;
+    private keytar;
+    private keytarLoadAttempted;
+    private keytarLoadError;
+    /**
+     * Lazily load keytar module.
+     * Uses dynamic import to handle cases where keytar is not installed.
+     */
+    private loadKeytar;
+    /**
+     * Get account name for a provider.
+     */
+    private getAccountName;
+    /**
+     * Check if the keychain backend is available on this system.
+     * Returns false if keytar is not installed or keychain access fails.
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Store credentials for a provider in the system keychain.
+     */
+    store(providerId: AuthProviderId, credentials: StoredCredentials): Promise<void>;
+    /**
+     * Retrieve credentials for a provider from the system keychain.
+     */
+    retrieve(providerId: AuthProviderId): Promise<StoredCredentials | null>;
+    /**
+     * Delete credentials for a provider from the system keychain.
+     */
+    delete(providerId: AuthProviderId): Promise<void>;
+    /**
+     * Delete all stored credentials from the system keychain.
+     */
+    deleteAll(): Promise<void>;
+    /**
+     * List all providers with stored credentials.
+     */
+    listProviders(): Promise<AuthProviderId[]>;
+    /**
+     * Add a provider to the internal providers list.
+     */
+    private addToProvidersList;
+    /**
+     * Remove a provider from the internal providers list.
+     */
+    private removeFromProvidersList;
+}

package/out/tsc/workers-registry/registry-launcher/src/auth/storage/keychain-backend.test.d.ts

@@ -0,0 +1 @@
+export {};

package/out/tsc/workers-registry/registry-launcher/src/auth/storage/memory-backend.d.ts

@@ -0,0 +1,54 @@
+/**
+ * In-memory storage backend for testing.
+ *
+ * This backend stores credentials in a Map and is primarily intended
+ * for testing purposes. All operations are synchronous but return
+ * Promises for interface compatibility with other backends.
+ *
+ * @module storage/memory-backend
+ */
+import type { AuthProviderId, StorageBackendType, StoredCredentials } from '../types.js';
+import type { IStorageBackend } from './types.js';
+/**
+ * In-memory storage backend implementation.
+ *
+ * Uses a Map<AuthProviderId, StoredCredentials> for storage.
+ * This backend is always available and is primarily used for testing.
+ */
+export declare class MemoryBackend implements IStorageBackend {
+    readonly type: StorageBackendType;
+    /** Internal storage map */
+    private readonly storage;
+    /**
+     * Check if the backend is available.
+     * Memory backend is always available.
+     * @returns Always resolves to true
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Store credentials for a provider.
+     * @param providerId - The provider identifier
+     * @param credentials - The credentials to store
+     */
+    store(providerId: AuthProviderId, credentials: StoredCredentials): Promise<void>;
+    /**
+     * Retrieve credentials for a provider.
+     * @param providerId - The provider identifier
+     * @returns The stored credentials or null if not found
+     */
+    retrieve(providerId: AuthProviderId): Promise<StoredCredentials | null>;
+    /**
+     * Delete credentials for a provider.
+     * @param providerId - The provider identifier
+     */
+    delete(providerId: AuthProviderId): Promise<void>;
+    /**
+     * Delete all stored credentials.
+     */
+    deleteAll(): Promise<void>;
+    /**
+     * List all providers with stored credentials.
+     * @returns Array of provider IDs that have stored credentials
+     */
+    listProviders(): Promise<AuthProviderId[]>;
+}

package/out/tsc/workers-registry/registry-launcher/src/auth/storage/storage.property.test.d.ts

@@ -0,0 +1 @@
+export {};

package/out/tsc/workers-registry/registry-launcher/src/auth/storage/types.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Storage interface definitions.
+ *
+ * @module storage/types
+ */
+import type { AuthProviderId, StorageBackendType, StoredCredentials } from '../types.js';
+/**
+ * Low-level storage backend interface.
+ * Implemented by keychain, encrypted file, and memory backends.
+ */
+export interface IStorageBackend {
+    /** Backend type identifier */
+    readonly type: StorageBackendType;
+    /** Check if the backend is available on this system */
+    isAvailable(): Promise<boolean>;
+    /** Store credentials for a provider */
+    store(providerId: AuthProviderId, credentials: StoredCredentials): Promise<void>;
+    /** Retrieve credentials for a provider */
+    retrieve(providerId: AuthProviderId): Promise<StoredCredentials | null>;
+    /** Delete credentials for a provider */
+    delete(providerId: AuthProviderId): Promise<void>;
+    /** Delete all stored credentials */
+    deleteAll(): Promise<void>;
+    /** List all providers with stored credentials */
+    listProviders(): Promise<AuthProviderId[]>;
+}
+/**
+ * Secure credential storage interface.
+ * Facade that selects the best available backend.
+ */
+export interface ICredentialStore {
+    /** Store credentials for a provider */
+    store(providerId: AuthProviderId, credentials: StoredCredentials): Promise<void>;
+    /** Retrieve credentials for a provider */
+    retrieve(providerId: AuthProviderId): Promise<StoredCredentials | null>;
+    /** Delete credentials for a provider */
+    delete(providerId: AuthProviderId): Promise<void>;
+    /** Delete all stored credentials */
+    deleteAll(): Promise<void>;
+    /** List all providers with stored credentials */
+    listProviders(): Promise<AuthProviderId[]>;
+    /** Get the active storage backend type */
+    getBackendType(): StorageBackendType;
+}

package/out/tsc/workers-registry/registry-launcher/src/auth/token-manager.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Token lifecycle management.
+ *
+ * Handles token storage, refresh, and expiration.
+ * Implements proactive token refresh and concurrent refresh serialization.
+ *
+ * @module token-manager
+ */
+import type { AuthProviderId, TokenResponse, TokenStatus } from './types.js';
+import type { ICredentialStore } from './storage/types.js';
+import type { IAuthProvider } from './providers/types.js';
+/**
+ * Default token refresh threshold in milliseconds (5 minutes).
+ * Tokens will be proactively refreshed when they expire within this threshold.
+ */
+export declare const DEFAULT_REFRESH_THRESHOLD_MS: number;
+/**
+ * Token lifecycle management interface.
+ */
+export interface ITokenManager {
+    /** Get a valid access token, refreshing if necessary */
+    getAccessToken(providerId: AuthProviderId): Promise<string | null>;
+    /** Store new tokens from an OAuth response */
+    storeTokens(providerId: AuthProviderId, tokens: TokenResponse): Promise<void>;
+    /** Check if tokens exist and are valid for a provider */
+    hasValidTokens(providerId: AuthProviderId): Promise<boolean>;
+    /** Force refresh tokens for a provider */
+    forceRefresh(providerId: AuthProviderId): Promise<string | null>;
+    /** Clear tokens for a provider (triggers re-auth) */
+    clearTokens(providerId: AuthProviderId): Promise<void>;
+    /** Get token status for all providers */
+    getStatus(): Promise<Map<AuthProviderId, TokenStatus>>;
+}
+/**
+ * Provider resolver function type.
+ * Used to get provider instances for token refresh operations.
+ */
+export type ProviderResolver = (providerId: AuthProviderId) => IAuthProvider | null;
+/**
+ * Options for creating a token manager.
+ */
+export interface TokenManagerOptions {
+    /** Credential store for persisting tokens */
+    credentialStore: ICredentialStore;
+    /** Function to resolve provider instances */
+    providerResolver: ProviderResolver;
+    /** Token refresh threshold in milliseconds (default: 5 minutes) */
+    refreshThresholdMs?: number;
+}
+/**
+ * Token manager implementation.
+ *
+ * Manages token lifecycle including:
+ * - Proactive token refresh when tokens are near expiration
+ * - Concurrent refresh serialization (only one refresh per provider at a time)
+ * - Automatic credential cleanup on refresh failure
+ * - Refresh token rotation handling
+ */
+export declare class TokenManager implements ITokenManager {
+    private readonly credentialStore;
+    private readonly providerResolver;
+    private readonly refreshThresholdMs;
+    /**
+     * Map of provider IDs to pending refresh promises.
+     * Used to serialize concurrent refresh requests.
+     */
+    private readonly pendingRefreshes;
+    /**
+     * Create a new token manager.
+     * @param options - Configuration options
+     */
+    constructor(options: TokenManagerOptions);
+    /**
+     * Get a valid access token, refreshing if necessary.
+     *
+     * If the token is within the refresh threshold of expiration, it will be
+     * proactively refreshed before returning.
+     *
+     * @param providerId - The provider identifier
+     * @returns The access token or null if not available
+     */
+    getAccessToken(providerId: AuthProviderId): Promise<string | null>;
+    /**
+     * Store new tokens from an OAuth response.
+     *
+     * Converts the token response to stored credentials format and persists them.
+     * Preserves the existing refresh token if the new response doesn't include one
+     * (some providers only return refresh tokens on initial auth, not on refresh).
+     *
+     * @param providerId - The provider identifier
+     * @param tokens - The token response from the OAuth provider
+     */
+    storeTokens(providerId: AuthProviderId, tokens: TokenResponse): Promise<void>;
+    /**
+     * Check if tokens exist and are valid for a provider.
+     *
+     * A token is considered valid if:
+     * - Credentials exist for the provider
+     * - The access token is not expired
+     *
+     * @param providerId - The provider identifier
+     * @returns True if valid tokens exist
+     */
+    hasValidTokens(providerId: AuthProviderId): Promise<boolean>;
+    /**
+     * Force refresh tokens for a provider.
+     *
+     * Unlike getAccessToken, this always attempts a refresh regardless of
+     * the current token's expiration status.
+     *
+     * @param providerId - The provider identifier
+     * @returns The new access token or null if refresh failed
+     */
+    forceRefresh(providerId: AuthProviderId): Promise<string | null>;
+    /**
+     * Clear tokens for a provider.
+     *
+     * This triggers re-authentication on the next token request.
+     *
+     * @param providerId - The provider identifier
+     */
+    clearTokens(providerId: AuthProviderId): Promise<void>;
+    /**
+     * Get token status for all providers.
+     *
+     * @returns Map of provider IDs to their token status
+     */
+    getStatus(): Promise<Map<AuthProviderId, TokenStatus>>;
+    /**
+     * Check if credentials are expired.
+     *
+     * @param credentials - The stored credentials
+     * @returns True if the token is expired
+     */
+    private isExpired;
+    /**
+     * Check if credentials should be proactively refreshed.
+     *
+     * Returns true if the token will expire within the refresh threshold.
+     *
+     * @param credentials - The stored credentials
+     * @returns True if the token should be refreshed
+     */
+    private shouldRefresh;
+    /**
+     * Internal token refresh implementation with concurrent request serialization.
+     *
+     * Ensures only one refresh operation occurs at a time per provider.
+     * If a refresh is already in progress, returns the pending promise.
+     *
+     * @param providerId - The provider identifier
+     * @param credentials - The current stored credentials
+     * @returns The new access token or null if refresh failed
+     */
+    private refreshTokenInternal;
+    /**
+     * Execute the actual token refresh operation.
+     *
+     * @param providerId - The provider identifier
+     * @param refreshToken - The refresh token to use
+     * @returns The new access token or null if refresh failed
+     */
+    private executeRefresh;
+}
+/**
+ * Create a token manager with the given options.
+ *
+ * @param options - Configuration options
+ * @returns A new token manager instance
+ */
+export declare function createTokenManager(options: TokenManagerOptions): TokenManager;

package/out/tsc/workers-registry/registry-launcher/src/auth/token-manager.property.test.d.ts

@@ -0,0 +1 @@
+export {};

package/out/tsc/workers-registry/registry-launcher/src/auth/token-manager.test.d.ts

@@ -0,0 +1 @@
+export {};