signet-auth 1.0.0-beta.0

package/dist/providers/auto-provision.d.ts

@@ -0,0 +1,9 @@
+import type { ProviderConfig } from '../core/types.js';
+/**
+ * Create a default provider config from a URL.
+ * Used for auto-provisioning when no configured provider matches.
+ *
+ * Defaults to cookie strategy (most common for SSO).
+ * Provider ID = hostname, making it deterministic across restarts.
+ */
+export declare function createDefaultProvider(url: string): ProviderConfig;

package/dist/providers/auto-provision.js

@@ -0,0 +1,27 @@
+/**
+ * Create a default provider config from a URL.
+ * Used for auto-provisioning when no configured provider matches.
+ *
+ * Defaults to cookie strategy (most common for SSO).
+ * Provider ID = hostname, making it deterministic across restarts.
+ */
+export function createDefaultProvider(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        // Treat as hostname — try adding https://
+        parsed = new URL(`https://${url}`);
+    }
+    const hostname = parsed.hostname;
+    return {
+        id: hostname,
+        name: hostname,
+        domains: [hostname],
+        entryUrl: `${parsed.protocol}//${parsed.host}/`,
+        strategy: 'cookie',
+        strategyConfig: { strategy: 'cookie' },
+        autoProvisioned: true,
+    };
+}

package/dist/providers/config-loader.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Provider config loader — delegates to the unified config system.
+ *
+ * This module is kept for backward compatibility. New code should use
+ * src/config/loader.ts directly.
+ */
+export { loadConfig } from '../config/loader.js';

package/dist/providers/config-loader.js

@@ -0,0 +1,7 @@
+/**
+ * Provider config loader — delegates to the unified config system.
+ *
+ * This module is kept for backward compatibility. New code should use
+ * src/config/loader.ts directly.
+ */
+export { loadConfig } from '../config/loader.js';

package/dist/providers/provider-registry.d.ts

@@ -0,0 +1,19 @@
+import type { IProviderRegistry } from '../core/interfaces/provider.js';
+import type { ProviderConfig } from '../core/types.js';
+/**
+ * Registry for provider configurations.
+ * Resolves URLs to providers using glob-style domain matching.
+ *
+ * Domain matching rules:
+ * - Exact: "api.example.com" matches only "api.example.com"
+ * - Wildcard: "*.example.com" matches "api.example.com", "www.example.com", etc.
+ * - Exact matches take priority over wildcard matches.
+ */
+export declare class ProviderRegistry implements IProviderRegistry {
+    private providers;
+    constructor(initialProviders?: ProviderConfig[]);
+    resolve(url: string): ProviderConfig | null;
+    get(id: string): ProviderConfig | null;
+    list(): ProviderConfig[];
+    register(provider: ProviderConfig): void;
+}

package/dist/providers/provider-registry.js

@@ -0,0 +1,68 @@
+/**
+ * Registry for provider configurations.
+ * Resolves URLs to providers using glob-style domain matching.
+ *
+ * Domain matching rules:
+ * - Exact: "api.example.com" matches only "api.example.com"
+ * - Wildcard: "*.example.com" matches "api.example.com", "www.example.com", etc.
+ * - Exact matches take priority over wildcard matches.
+ */
+export class ProviderRegistry {
+    providers = new Map();
+    constructor(initialProviders = []) {
+        for (const provider of initialProviders) {
+            this.providers.set(provider.id, provider);
+        }
+    }
+    resolve(url) {
+        let hostname;
+        try {
+            hostname = new URL(url).hostname;
+        }
+        catch {
+            // If URL parsing fails, treat the input as a hostname
+            hostname = url;
+        }
+        // First pass: exact domain match (higher priority)
+        for (const provider of this.providers.values()) {
+            for (const domain of provider.domains) {
+                if (!domain.includes('*') && hostname === domain) {
+                    return provider;
+                }
+            }
+        }
+        // Second pass: glob/wildcard match
+        for (const provider of this.providers.values()) {
+            for (const domain of provider.domains) {
+                if (domain.includes('*') && matchGlob(hostname, domain)) {
+                    return provider;
+                }
+            }
+        }
+        return null;
+    }
+    get(id) {
+        return this.providers.get(id) ?? null;
+    }
+    list() {
+        return Array.from(this.providers.values());
+    }
+    register(provider) {
+        this.providers.set(provider.id, provider);
+    }
+}
+/**
+ * Simple glob matching for domain patterns.
+ * Supports only "*" as a wildcard segment prefix.
+ * Examples:
+ *   "*.example.com" matches "api.example.com", "www.example.com"
+ *   "*.*.example.com" matches "a.b.example.com"
+ */
+function matchGlob(hostname, pattern) {
+    // Convert glob to regex: *.example.com → ^[^.]+\.example\.com$
+    const escaped = pattern
+        .replace(/\./g, '\\.')
+        .replace(/\*/g, '[^.]+');
+    const regex = new RegExp(`^${escaped}$`, 'i');
+    return regex.test(hostname);
+}

package/dist/storage/cached-storage.d.ts

@@ -0,0 +1,24 @@
+import type { IStorage } from '../core/interfaces/storage.js';
+import type { StoredCredential, StoredEntry } from '../core/types.js';
+/**
+ * Decorator that adds a TTL cache over any IStorage implementation.
+ * Reads are cached; writes invalidate the cache for the affected key.
+ *
+ * Usage:
+ *   const storage = new CachedStorage(new DirectoryStorage(dir), { ttlMs: 5000 });
+ */
+export declare class CachedStorage implements IStorage {
+    private readonly inner;
+    private readonly options;
+    private cache;
+    private listCache;
+    constructor(inner: IStorage, options?: {
+        ttlMs: number;
+    });
+    get(providerId: string): Promise<StoredCredential | null>;
+    set(providerId: string, credential: StoredCredential): Promise<void>;
+    delete(providerId: string): Promise<void>;
+    list(): Promise<StoredEntry[]>;
+    clear(): Promise<void>;
+    private invalidate;
+}

package/dist/storage/cached-storage.js

@@ -0,0 +1,57 @@
+/**
+ * Decorator that adds a TTL cache over any IStorage implementation.
+ * Reads are cached; writes invalidate the cache for the affected key.
+ *
+ * Usage:
+ *   const storage = new CachedStorage(new DirectoryStorage(dir), { ttlMs: 5000 });
+ */
+export class CachedStorage {
+    inner;
+    options;
+    cache = new Map();
+    listCache = null;
+    constructor(inner, options = { ttlMs: 5000 }) {
+        this.inner = inner;
+        this.options = options;
+    }
+    async get(providerId) {
+        const cached = this.cache.get(providerId);
+        if (cached && Date.now() < cached.expiresAt) {
+            return cached.value;
+        }
+        const value = await this.inner.get(providerId);
+        this.cache.set(providerId, {
+            value,
+            expiresAt: Date.now() + this.options.ttlMs,
+        });
+        return value;
+    }
+    async set(providerId, credential) {
+        this.invalidate(providerId);
+        await this.inner.set(providerId, credential);
+    }
+    async delete(providerId) {
+        this.invalidate(providerId);
+        await this.inner.delete(providerId);
+    }
+    async list() {
+        if (this.listCache && Date.now() < this.listCache.expiresAt) {
+            return this.listCache.entries;
+        }
+        const entries = await this.inner.list();
+        this.listCache = {
+            entries,
+            expiresAt: Date.now() + this.options.ttlMs,
+        };
+        return entries;
+    }
+    async clear() {
+        this.cache.clear();
+        this.listCache = null;
+        await this.inner.clear();
+    }
+    invalidate(providerId) {
+        this.cache.delete(providerId);
+        this.listCache = null;
+    }
+}

package/dist/storage/directory-storage.d.ts

@@ -0,0 +1,25 @@
+import type { IStorage } from '../core/interfaces/storage.js';
+import type { StoredCredential, StoredEntry } from '../core/types.js';
+/**
+ * Per-provider directory-based storage.
+ * Each provider's credentials are stored in a separate JSON file
+ * under the configured directory: `{dirPath}/{sanitizedProviderId}.json`.
+ *
+ * Uses per-file advisory locking via `proper-lockfile` and atomic writes
+ * (write to tmp + rename) for safe concurrent access.
+ */
+export declare class DirectoryStorage implements IStorage {
+    private readonly dirPath;
+    constructor(dirPath: string);
+    get(providerId: string): Promise<StoredCredential | null>;
+    set(providerId: string, credential: StoredCredential): Promise<void>;
+    delete(providerId: string): Promise<void>;
+    list(): Promise<StoredEntry[]>;
+    clear(): Promise<void>;
+    private filePathFor;
+    private ensureDir;
+    private readFile;
+    private toStoredCredential;
+    private atomicWrite;
+    private withLock;
+}

package/dist/storage/directory-storage.js

@@ -0,0 +1,184 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import lockfile from 'proper-lockfile';
+import { StorageError } from '../core/errors.js';
+/**
+ * Convert a provider ID into a human-readable, filesystem-safe filename.
+ * Replaces unsafe characters with underscores.
+ */
+function sanitizeId(providerId) {
+    return providerId.replace(/[^a-zA-Z0-9._-]/g, '_');
+}
+/**
+ * Per-provider directory-based storage.
+ * Each provider's credentials are stored in a separate JSON file
+ * under the configured directory: `{dirPath}/{sanitizedProviderId}.json`.
+ *
+ * Uses per-file advisory locking via `proper-lockfile` and atomic writes
+ * (write to tmp + rename) for safe concurrent access.
+ */
+export class DirectoryStorage {
+    dirPath;
+    constructor(dirPath) {
+        this.dirPath = dirPath;
+    }
+    async get(providerId) {
+        const filePath = this.filePathFor(providerId);
+        try {
+            const data = await this.readFile(filePath);
+            return this.toStoredCredential(data);
+        }
+        catch (e) {
+            if (e.code === 'ENOENT') {
+                return null;
+            }
+            throw new StorageError('read', e.message);
+        }
+    }
+    async set(providerId, credential) {
+        const filePath = this.filePathFor(providerId);
+        await this.ensureDir();
+        const data = {
+            version: 1,
+            providerId,
+            credential: credential.credential,
+            strategy: credential.strategy,
+            updatedAt: credential.updatedAt,
+            ...(credential.metadata ? { metadata: credential.metadata } : {}),
+        };
+        await this.withLock(filePath, async () => {
+            await this.atomicWrite(filePath, data);
+        });
+    }
+    async delete(providerId) {
+        const filePath = this.filePathFor(providerId);
+        try {
+            await fs.unlink(filePath);
+        }
+        catch (e) {
+            if (e.code === 'ENOENT') {
+                return; // No-op if not found
+            }
+            throw new StorageError('delete', e.message);
+        }
+    }
+    async list() {
+        let files;
+        try {
+            files = await fs.readdir(this.dirPath);
+        }
+        catch (e) {
+            if (e.code === 'ENOENT') {
+                return [];
+            }
+            throw new StorageError('list', e.message);
+        }
+        const entries = [];
+        for (const file of files) {
+            if (!file.endsWith('.json'))
+                continue;
+            const filePath = path.join(this.dirPath, file);
+            try {
+                const data = await this.readFile(filePath);
+                entries.push({
+                    providerId: data.providerId,
+                    strategy: data.strategy,
+                    updatedAt: data.updatedAt,
+                    credentialType: data.credential.type,
+                });
+            }
+            catch {
+                // Skip files that can't be read or parsed
+                continue;
+            }
+        }
+        return entries;
+    }
+    async clear() {
+        let files;
+        try {
+            files = await fs.readdir(this.dirPath);
+        }
+        catch (e) {
+            if (e.code === 'ENOENT') {
+                return;
+            }
+            throw new StorageError('clear', e.message);
+        }
+        for (const file of files) {
+            if (!file.endsWith('.json'))
+                continue;
+            const filePath = path.join(this.dirPath, file);
+            try {
+                await fs.unlink(filePath);
+            }
+            catch (e) {
+                if (e.code !== 'ENOENT') {
+                    throw new StorageError('clear', e.message);
+                }
+            }
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    filePathFor(providerId) {
+        return path.join(this.dirPath, `${sanitizeId(providerId)}.json`);
+    }
+    async ensureDir() {
+        await fs.mkdir(this.dirPath, { recursive: true });
+    }
+    async readFile(filePath) {
+        const content = await fs.readFile(filePath, 'utf-8');
+        const data = JSON.parse(content);
+        if (!data.version || !data.providerId || !data.credential) {
+            throw new StorageError('read', `Invalid provider file: ${filePath}`);
+        }
+        return data;
+    }
+    toStoredCredential(data) {
+        return {
+            credential: data.credential,
+            providerId: data.providerId,
+            strategy: data.strategy,
+            updatedAt: data.updatedAt,
+            ...(data.metadata ? { metadata: data.metadata } : {}),
+        };
+    }
+    async atomicWrite(filePath, data) {
+        try {
+            const content = JSON.stringify(data, null, 2);
+            const tmpPath = `${filePath}.tmp.${process.pid}`;
+            await fs.writeFile(tmpPath, content, 'utf-8');
+            await fs.rename(tmpPath, filePath);
+        }
+        catch (e) {
+            throw new StorageError('write', e.message);
+        }
+    }
+    async withLock(filePath, fn) {
+        await this.ensureDir();
+        // Use a separate .lock file so we never create dummy credential files
+        const lockPath = `${filePath}.lock`;
+        await fs.writeFile(lockPath, '', { flag: 'a' });
+        let release;
+        try {
+            release = await lockfile.lock(lockPath, {
+                retries: { retries: 5, minTimeout: 100, maxTimeout: 1000 },
+                stale: 10000,
+            });
+            return await fn();
+        }
+        catch (e) {
+            if (e.message?.includes('ELOCKED')) {
+                throw new StorageError('lock', 'Could not acquire file lock. Another process may be writing.');
+            }
+            throw e;
+        }
+        finally {
+            if (release) {
+                await release().catch(() => { });
+            }
+        }
+    }
+}

package/dist/storage/memory-storage.d.ts

@@ -0,0 +1,14 @@
+import type { IStorage } from '../core/interfaces/storage.js';
+import type { StoredCredential, StoredEntry } from '../core/types.js';
+/**
+ * In-memory storage implementation for testing.
+ * No persistence — data is lost when the process exits.
+ */
+export declare class MemoryStorage implements IStorage {
+    private store;
+    get(providerId: string): Promise<StoredCredential | null>;
+    set(providerId: string, credential: StoredCredential): Promise<void>;
+    delete(providerId: string): Promise<void>;
+    list(): Promise<StoredEntry[]>;
+    clear(): Promise<void>;
+}

package/dist/storage/memory-storage.js

@@ -0,0 +1,27 @@
+/**
+ * In-memory storage implementation for testing.
+ * No persistence — data is lost when the process exits.
+ */
+export class MemoryStorage {
+    store = new Map();
+    async get(providerId) {
+        return this.store.get(providerId) ?? null;
+    }
+    async set(providerId, credential) {
+        this.store.set(providerId, credential);
+    }
+    async delete(providerId) {
+        this.store.delete(providerId);
+    }
+    async list() {
+        return Array.from(this.store.entries()).map(([providerId, stored]) => ({
+            providerId,
+            strategy: stored.strategy,
+            updatedAt: stored.updatedAt,
+            credentialType: stored.credential.type,
+        }));
+    }
+    async clear() {
+        this.store.clear();
+    }
+}

package/dist/strategies/api-token.strategy.d.ts

@@ -0,0 +1,6 @@
+import type { IAuthStrategy, IAuthStrategyFactory } from '../core/interfaces/auth-strategy.js';
+import type { StrategyConfig } from '../config/schema.js';
+export declare class ApiTokenStrategyFactory implements IAuthStrategyFactory {
+    readonly name = "api-token";
+    create(config: StrategyConfig): IAuthStrategy;
+}

package/dist/strategies/api-token.strategy.js

@@ -0,0 +1,63 @@
+import { ok, err } from '../core/result.js';
+import { ManualSetupRequired } from '../core/errors.js';
+import { decodeJwt } from '../utils/jwt.js';
+const DEFAULT_HEADER_NAME = 'Authorization';
+const DEFAULT_HEADER_PREFIX = 'Bearer';
+const DEFAULT_SETUP_INSTRUCTIONS = 'Please provide an API token or Personal Access Token.';
+/**
+ * Static API token strategy.
+ * User provides the token manually — no browser automation needed.
+ * Optionally checks JWT expiry if the token is a JWT.
+ */
+class ApiTokenStrategy {
+    headerName;
+    headerPrefix;
+    setupInstructions;
+    constructor(config) {
+        this.headerName = config.headerName ?? DEFAULT_HEADER_NAME;
+        this.headerPrefix = config.headerPrefix ?? DEFAULT_HEADER_PREFIX;
+        this.setupInstructions = config.setupInstructions ?? DEFAULT_SETUP_INSTRUCTIONS;
+    }
+    validate(credential) {
+        if (credential.type !== 'api-key') {
+            return ok(false);
+        }
+        if (!credential.key || credential.key.trim() === '') {
+            return ok(false);
+        }
+        // If the key looks like a JWT, check its expiry
+        const jwt = decodeJwt(credential.key);
+        if (jwt?.exp) {
+            const expiresAtMs = jwt.exp * 1000;
+            if (Date.now() >= expiresAtMs) {
+                return ok(false);
+            }
+        }
+        return ok(true);
+    }
+    async authenticate(provider) {
+        // API tokens cannot be obtained automatically — user must provide them.
+        return err(new ManualSetupRequired(provider.id, this.setupInstructions));
+    }
+    async refresh() {
+        // Static tokens cannot be refreshed
+        return ok(null);
+    }
+    applyToRequest(credential) {
+        if (credential.type !== 'api-key')
+            return {};
+        const value = this.headerPrefix
+            ? `${this.headerPrefix} ${credential.key}`
+            : credential.key;
+        return { [this.headerName]: value };
+    }
+}
+export class ApiTokenStrategyFactory {
+    name = 'api-token';
+    create(config) {
+        if (config.strategy !== 'api-token') {
+            throw new Error(`ApiTokenStrategyFactory received wrong config type: ${config.strategy}`);
+        }
+        return new ApiTokenStrategy(config);
+    }
+}

package/dist/strategies/basic-auth.strategy.d.ts

@@ -0,0 +1,6 @@
+import type { IAuthStrategy, IAuthStrategyFactory } from '../core/interfaces/auth-strategy.js';
+import type { StrategyConfig } from '../config/schema.js';
+export declare class BasicAuthStrategyFactory implements IAuthStrategyFactory {
+    readonly name = "basic";
+    create(config: StrategyConfig): IAuthStrategy;
+}

package/dist/strategies/basic-auth.strategy.js

@@ -0,0 +1,41 @@
+import { ok, err } from '../core/result.js';
+import { ManualSetupRequired } from '../core/errors.js';
+/**
+ * Basic authentication strategy.
+ * User provides username + password — no browser automation needed.
+ * Produces an Authorization: Basic <base64> header.
+ */
+class BasicAuthStrategy {
+    setupInstructions;
+    constructor(config) {
+        this.setupInstructions = config.setupInstructions;
+    }
+    validate(credential) {
+        if (credential.type !== 'basic')
+            return ok(false);
+        return ok(credential.username.length > 0 && credential.password.length > 0);
+    }
+    async authenticate(provider) {
+        return err(new ManualSetupRequired(provider.id, this.setupInstructions ??
+            provider.setupInstructions ??
+            'Please provide username and password for basic authentication.'));
+    }
+    async refresh() {
+        return ok(null);
+    }
+    applyToRequest(credential) {
+        if (credential.type !== 'basic')
+            return {};
+        const encoded = Buffer.from(`${credential.username}:${credential.password}`).toString('base64');
+        return { Authorization: `Basic ${encoded}` };
+    }
+}
+export class BasicAuthStrategyFactory {
+    name = 'basic';
+    create(config) {
+        if (config.strategy !== 'basic') {
+            throw new Error(`BasicAuthStrategyFactory received wrong config type: ${config.strategy}`);
+        }
+        return new BasicAuthStrategy(config);
+    }
+}

package/dist/strategies/cookie.strategy.d.ts

@@ -0,0 +1,6 @@
+import type { IAuthStrategy, IAuthStrategyFactory } from '../core/interfaces/auth-strategy.js';
+import type { StrategyConfig } from '../config/schema.js';
+export declare class CookieStrategyFactory implements IAuthStrategyFactory {
+    readonly name = "cookie";
+    create(config: StrategyConfig): IAuthStrategy;
+}