signet-auth 1.0.0-beta.0

package/dist/auth-manager.js

@@ -0,0 +1,262 @@
+import { createDefaultProvider } from './providers/auto-provision.js';
+import { ok, err, isOk } from './core/result.js';
+import { CredentialTypeError, ProviderNotFoundError, } from './core/errors.js';
+/**
+ * Central orchestrator for authentication lifecycle.
+ * All dependencies are injected — no singletons, no global state.
+ *
+ * Flow: validate → refresh → authenticate
+ */
+export class AuthManager {
+    storage;
+    strategies;
+    providers;
+    browserAdapterFactory;
+    browserConfig;
+    logger;
+    constructor(deps) {
+        this.storage = deps.storage;
+        this.strategies = deps.strategyRegistry;
+        this.providers = deps.providerRegistry;
+        this.browserAdapterFactory = deps.browserAdapterFactory;
+        this.browserConfig = deps.browserConfig;
+        this.logger = deps.logger;
+    }
+    /**
+     * Get valid credentials for a provider.
+     * Tries: stored → refresh → authenticate, in that order.
+     */
+    async getCredentials(providerId) {
+        const provider = this.providers.get(providerId);
+        if (!provider)
+            return err(new ProviderNotFoundError(providerId));
+        const strategy = this.strategies.get(provider.strategy, provider.strategyConfig);
+        const key = this.storageKey(provider);
+        // Step 1: Check stored credentials
+        const stored = await this.storage.get(key);
+        if (stored) {
+            const validation = strategy.validate(stored.credential, provider.strategyConfig);
+            if (isOk(validation) && validation.value) {
+                // Check credential type constraints
+                const typeCheck = this.checkCredentialType(provider, stored.credential);
+                if (!isOk(typeCheck))
+                    return typeCheck;
+                return ok(stored.credential);
+            }
+            // Step 2: Try refresh
+            this.logger?.debug(`Credentials for "${providerId}" are invalid, attempting refresh...`);
+            const refreshResult = await strategy.refresh(stored.credential, provider.strategyConfig);
+            if (isOk(refreshResult) && refreshResult.value) {
+                const typeCheck = this.checkCredentialType(provider, refreshResult.value);
+                if (!isOk(typeCheck))
+                    return typeCheck;
+                await this.store(key, provider.strategy, refreshResult.value);
+                return ok(refreshResult.value);
+            }
+        }
+        // Step 3: Full authentication
+        this.logger?.info(`Authenticating with "${providerId}"...`);
+        const context = {
+            browserAdapter: this.browserAdapterFactory(),
+            browserConfig: this.browserConfig,
+            logger: this.logger,
+        };
+        const authResult = await strategy.authenticate(provider, context);
+        if (!isOk(authResult))
+            return authResult;
+        const typeCheck = this.checkCredentialType(provider, authResult.value);
+        if (!isOk(typeCheck))
+            return typeCheck;
+        await this.store(key, provider.strategy, authResult.value);
+        return ok(authResult.value);
+    }
+    /**
+     * Resolve a provider by URL, auto-provisioning a default cookie provider if none matches.
+     */
+    resolveProvider(url) {
+        const existing = this.providers.resolve(url);
+        if (existing)
+            return existing;
+        const provider = createDefaultProvider(url);
+        this.providers.register(provider);
+        this.logger?.info(`Auto-provisioned provider "${provider.id}" for ${url}`);
+        return provider;
+    }
+    /**
+     * Get credentials for a specific provider, resolving by URL.
+     */
+    async getCredentialsByUrl(url) {
+        const provider = this.resolveProvider(url);
+        const result = await this.getCredentials(provider.id);
+        if (!isOk(result))
+            return result;
+        return ok({ provider, credential: result.value });
+    }
+    /**
+     * Force re-authentication, deleting any stored credentials first.
+     */
+    async forceReauth(providerId) {
+        const provider = this.providers.get(providerId);
+        if (provider) {
+            await this.storage.delete(this.storageKey(provider));
+        }
+        return this.getCredentials(providerId);
+    }
+    /**
+     * Store a credential directly (e.g., user-provided API token).
+     */
+    async setCredential(providerId, credential) {
+        const provider = this.providers.get(providerId);
+        if (!provider)
+            return err(new ProviderNotFoundError(providerId));
+        const typeCheck = this.checkCredentialType(provider, credential);
+        if (!isOk(typeCheck))
+            return typeCheck;
+        await this.store(this.storageKey(provider), provider.strategy, credential);
+        return ok(undefined);
+    }
+    /**
+     * Get status for a provider (non-triggering — won't start auth).
+     */
+    async getStatus(providerId) {
+        const provider = this.providers.get(providerId);
+        if (!provider) {
+            return {
+                id: providerId,
+                name: providerId,
+                configured: false,
+                valid: false,
+                strategy: 'unknown',
+            };
+        }
+        const stored = await this.storage.get(this.storageKey(provider));
+        if (!stored) {
+            return {
+                id: provider.id,
+                name: provider.name,
+                configured: true,
+                valid: false,
+                strategy: provider.strategy,
+            };
+        }
+        const strategy = this.strategies.get(provider.strategy, provider.strategyConfig);
+        const validation = strategy.validate(stored.credential, provider.strategyConfig);
+        const valid = isOk(validation) && validation.value;
+        const expiresAt = this.getExpiresAt(stored.credential);
+        const expiresInMinutes = expiresAt
+            ? Math.max(0, Math.round((expiresAt.getTime() - Date.now()) / 60000))
+            : undefined;
+        return {
+            id: provider.id,
+            name: provider.name,
+            configured: true,
+            valid,
+            credentialType: stored.credential.type,
+            strategy: provider.strategy,
+            expiresAt: expiresAt?.toISOString(),
+            expiresInMinutes,
+        };
+    }
+    /**
+     * Get status for all configured providers.
+     */
+    async getAllStatus() {
+        const providers = this.providers.list();
+        return Promise.all(providers.map(p => this.getStatus(p.id)));
+    }
+    /**
+     * Clear stored credentials for a provider.
+     */
+    async clearCredentials(providerId) {
+        const provider = this.providers.get(providerId);
+        const key = provider ? this.storageKey(provider) : providerId;
+        await this.storage.delete(key);
+    }
+    /**
+     * Clear all stored credentials.
+     */
+    async clearAll() {
+        await this.storage.clear();
+    }
+    /**
+     * Apply credentials to an outgoing request (as headers).
+     */
+    applyToRequest(providerId, credential) {
+        const provider = this.providers.get(providerId);
+        if (!provider)
+            return {};
+        const strategy = this.strategies.get(provider.strategy, provider.strategyConfig);
+        return strategy.applyToRequest(credential);
+    }
+    /**
+     * Validate a credential by making a test request to the provider's entry URL.
+     * Returns the HTTP status and whether the response redirects to a login page.
+     */
+    async validateCredential(provider, credential) {
+        if (!provider.entryUrl)
+            return { status: null, isLoginRedirect: false };
+        try {
+            const strategy = this.strategies.get(provider.strategy, provider.strategyConfig);
+            const headers = strategy.applyToRequest(credential);
+            const response = await fetch(provider.entryUrl, {
+                method: 'GET',
+                headers: { ...headers, 'User-Agent': 'signet/1.0' },
+                redirect: 'manual',
+            });
+            const location = response.headers.get('location') ?? '';
+            const loginPatterns = [
+                '/login', '/signin', '/sign-in', '/auth', '/sso', '/oauth',
+                '/adfs/', '/saml/', 'login.microsoftonline.com',
+                'accounts.google.com',
+            ];
+            const isLoginRedirect = response.status >= 300 && response.status < 400
+                && loginPatterns.some(p => location.toLowerCase().includes(p));
+            return { status: response.status, isLoginRedirect };
+        }
+        catch {
+            return { status: null, isLoginRedirect: false };
+        }
+    }
+    /** Expose the provider registry for handlers */
+    get providerRegistry() {
+        return this.providers;
+    }
+    /** Storage key: uses credentialFile if configured, otherwise provider ID. */
+    storageKey(provider) {
+        return provider.credentialFile ?? provider.id;
+    }
+    checkCredentialType(provider, credential) {
+        if (provider.acceptedCredentialTypes &&
+            provider.acceptedCredentialTypes.length > 0 &&
+            !provider.acceptedCredentialTypes.includes(credential.type)) {
+            return err(new CredentialTypeError(provider.id, provider.acceptedCredentialTypes, credential.type));
+        }
+        return ok(undefined);
+    }
+    async store(providerId, strategy, credential) {
+        // Strip transient diagnostics metadata before persisting
+        const { __diagnostics, ...clean } = credential;
+        const stored = {
+            credential: clean,
+            providerId,
+            strategy,
+            updatedAt: new Date().toISOString(),
+        };
+        await this.storage.set(providerId, stored);
+    }
+    getExpiresAt(credential) {
+        switch (credential.type) {
+            case 'bearer':
+                return credential.expiresAt ? new Date(credential.expiresAt) : null;
+            case 'cookie': {
+                // Earliest cookie expiry, or null if all session cookies
+                const expiries = credential.cookies
+                    .filter(c => c.expires > 0)
+                    .map(c => c.expires * 1000);
+                return expiries.length > 0 ? new Date(Math.min(...expiries)) : null;
+            }
+            default:
+                return null;
+        }
+    }
+}

package/dist/browser/adapters/playwright.adapter.d.ts

@@ -0,0 +1,14 @@
+import type { IBrowserAdapter, IBrowserSession } from "../../core/interfaces/browser-adapter.js";
+import type { BrowserLaunchOptions } from "../../core/types.js";
+import type { BrowserConfig } from "../../config/schema.js";
+/**
+ * Playwright-based browser adapter.
+ * Uses playwright-core (no bundled browsers) — requires a system Chrome/Chromium/Edge.
+ * Defaults to system Chrome (channel: 'chrome') when no explicit browser is configured.
+ */
+export declare class PlaywrightAdapter implements IBrowserAdapter {
+    private readonly browserConfig;
+    readonly name = "playwright";
+    constructor(browserConfig: BrowserConfig);
+    launch(options: BrowserLaunchOptions): Promise<IBrowserSession>;
+}

package/dist/browser/adapters/playwright.adapter.js

@@ -0,0 +1,188 @@
+import os from "node:os";
+import path from "node:path";
+import { BrowserLaunchError } from "../../core/errors.js";
+function expandHome(p) {
+    if (p.startsWith("~/") || p === "~") {
+        return path.join(os.homedir(), p.slice(1));
+    }
+    return p;
+}
+/**
+ * Playwright-based browser adapter.
+ * Uses playwright-core (no bundled browsers) — requires a system Chrome/Chromium/Edge.
+ * Defaults to system Chrome (channel: 'chrome') when no explicit browser is configured.
+ */
+export class PlaywrightAdapter {
+    browserConfig;
+    name = "playwright";
+    constructor(browserConfig) {
+        this.browserConfig = browserConfig;
+    }
+    async launch(options) {
+        const { browserDataDir, channel } = this.browserConfig;
+        let pw;
+        try {
+            pw = await import("playwright-core");
+        }
+        catch {
+            throw new BrowserLaunchError("playwright-core is not available. Run: npm install playwright-core");
+        }
+        try {
+            const context = await pw.chromium.launchPersistentContext(expandHome(browserDataDir), {
+                channel: channel,
+                headless: options.headless ?? true,
+                timeout: options.timeout,
+                args: options.args,
+            });
+            return new PlaywrightSession(context);
+        }
+        catch (e) {
+            const msg = e.message;
+            const hint = msg.includes("executable") || msg.includes("Failed to launch")
+                ? `${msg}. Ensure a system browser is installed, or check browser.channel in ~/.signet/config.yaml.`
+                : msg;
+            throw new BrowserLaunchError(hint);
+        }
+    }
+}
+class PlaywrightSession {
+    context;
+    constructor(context) {
+        this.context = context;
+    }
+    async newPage() {
+        const page = await this.context.newPage();
+        return new PlaywrightPage(page, this.context);
+    }
+    async pages() {
+        return this.context.pages().map((p) => new PlaywrightPage(p, this.context));
+    }
+    async close() {
+        try {
+            await this.context.close();
+        }
+        catch {
+            // Suppress close errors
+        }
+    }
+    isConnected() {
+        return true; // Persistent context doesn't expose isConnected
+    }
+}
+class PlaywrightPage {
+    page;
+    context;
+    constructor(page, context) {
+        this.page = page;
+        this.context = context;
+    }
+    async goto(url, options) {
+        await this.page.goto(url, {
+            waitUntil: options?.waitUntil,
+            timeout: options?.timeout,
+        });
+    }
+    url() {
+        return this.page.url();
+    }
+    async waitForUrl(pattern, options) {
+        await this.page.waitForURL(pattern, options);
+    }
+    async waitForNavigation(options) {
+        await this.page.waitForLoadState("networkidle", options);
+    }
+    async waitForLoadState(state) {
+        await this.page.waitForLoadState(state);
+    }
+    async fill(selector, value) {
+        await this.page.locator(selector).fill(value);
+    }
+    async click(selector, options) {
+        await this.page.locator(selector).click({ timeout: options?.timeout });
+    }
+    async type(selector, text, options) {
+        await this.page
+            .locator(selector)
+            .pressSequentially(text, { delay: options?.delay });
+    }
+    async waitForSelector(selector, options) {
+        await this.page.locator(selector).waitFor({
+            timeout: options?.timeout,
+            state: options?.state,
+        });
+    }
+    async cookies(urls) {
+        const rawCookies = await this.context.cookies(urls);
+        return rawCookies.map((c) => ({
+            name: c.name,
+            value: c.value,
+            domain: c.domain,
+            path: c.path,
+            expires: c.expires,
+            httpOnly: c.httpOnly,
+            secure: c.secure,
+            sameSite: c.sameSite === "Strict"
+                ? "Strict"
+                : c.sameSite === "Lax"
+                    ? "Lax"
+                    : c.sameSite === "None"
+                        ? "None"
+                        : undefined,
+        }));
+    }
+    async evaluate(fn) {
+        if (typeof fn === "string") {
+            return (await this.page.evaluate(fn));
+        }
+        return await this.page.evaluate(fn);
+    }
+    async evaluateWithArg(fn, arg) {
+        return await this.page.evaluate(fn, arg);
+    }
+    async screenshot(options) {
+        return Buffer.from(await this.page.screenshot(options));
+    }
+    async content() {
+        return await this.page.content();
+    }
+    async title() {
+        return await this.page.title();
+    }
+    async close() {
+        if (!this.page.isClosed()) {
+            await this.page.close();
+        }
+    }
+    isClosed() {
+        return this.page.isClosed();
+    }
+    onClose(handler) {
+        this.page.on("close", handler);
+    }
+    onRequest(handler) {
+        const listener = (req) => {
+            handler({
+                url: req.url(),
+                method: req.method(),
+                headers: req.headers(),
+            });
+        };
+        this.page.on("request", listener);
+        return () => {
+            this.page.off("request", listener);
+        };
+    }
+    onResponse(handler) {
+        const listener = (res) => {
+            handler({
+                url: res.url(),
+                status: res.status(),
+                headers: res.headers(),
+            });
+        };
+        this.page.on("response", listener);
+        return () => {
+            this.page.off("response", listener);
+        };
+    }
+}

package/dist/browser/flows/form-login.flow.d.ts

@@ -0,0 +1,6 @@
+import type { IBrowserPage } from '../../core/interfaces/browser-adapter.js';
+/**
+ * Detect and check for common login form patterns.
+ * Returns true if the page appears to be a login page.
+ */
+export declare function isLoginPage(page: IBrowserPage): Promise<boolean>;

package/dist/browser/flows/form-login.flow.js

@@ -0,0 +1,35 @@
+/**
+ * Detect and check for common login form patterns.
+ * Returns true if the page appears to be a login page.
+ */
+export async function isLoginPage(page) {
+    try {
+        const url = page.url().toLowerCase();
+        const loginUrlPatterns = [
+            '/login', '/signin', '/sign-in', '/auth', '/sso', '/oauth',
+            '/adfs/', '/saml/',
+            'login.microsoftonline.com', 'accounts.google.com',
+        ];
+        if (loginUrlPatterns.some(p => url.includes(p)))
+            return true;
+        // Check for common form elements
+        const hasLoginForm = await page.evaluate(() => {
+            const inputs = document.querySelectorAll('input');
+            let hasPassword = false;
+            let hasEmail = false;
+            for (const input of inputs) {
+                const type = input.type.toLowerCase();
+                const name = (input.name || input.id || '').toLowerCase();
+                if (type === 'password')
+                    hasPassword = true;
+                if (type === 'email' || name.includes('email') || name.includes('user'))
+                    hasEmail = true;
+            }
+            return hasPassword || hasEmail;
+        });
+        return hasLoginForm;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/browser/flows/header-capture.d.ts

@@ -0,0 +1,23 @@
+import type { IBrowserPage } from '../../core/interfaces/browser-adapter.js';
+import type { XHeaderConfig } from '../../core/types.js';
+export interface HeaderCaptureResult {
+    /** Captured headers (keyed by original config name, values last-write-wins) */
+    xHeaders: Record<string, string>;
+    /** Call to remove network listeners */
+    cleanup: () => void;
+}
+/**
+ * Start capturing HTTP headers from browser network traffic.
+ *
+ * - Static values are populated immediately.
+ * - Dynamic values are captured via onRequest/onResponse listeners.
+ * - Filters by providerDomains and optional urlPattern per config entry.
+ * - Header name matching is case-insensitive.
+ * - Gracefully degrades if the page doesn't support onRequest/onResponse.
+ *
+ * @param page           Browser page to observe
+ * @param configs        Header capture configurations
+ * @param providerDomains  Domains belonging to the provider (used as URL filter)
+ * @returns xHeaders record and a cleanup function
+ */
+export declare function startHeaderCapture(page: IBrowserPage, configs: XHeaderConfig[], providerDomains: string[]): HeaderCaptureResult;

package/dist/browser/flows/header-capture.js

@@ -0,0 +1,104 @@
+/**
+ * Start capturing HTTP headers from browser network traffic.
+ *
+ * - Static values are populated immediately.
+ * - Dynamic values are captured via onRequest/onResponse listeners.
+ * - Filters by providerDomains and optional urlPattern per config entry.
+ * - Header name matching is case-insensitive.
+ * - Gracefully degrades if the page doesn't support onRequest/onResponse.
+ *
+ * @param page           Browser page to observe
+ * @param configs        Header capture configurations
+ * @param providerDomains  Domains belonging to the provider (used as URL filter)
+ * @returns xHeaders record and a cleanup function
+ */
+export function startHeaderCapture(page, configs, providerDomains) {
+    const xHeaders = {};
+    const cleanups = [];
+    // Separate static vs dynamic configs
+    const dynamicConfigs = [];
+    for (const cfg of configs) {
+        if (cfg.staticValue !== undefined) {
+            xHeaders[cfg.name] = cfg.staticValue;
+        }
+        else {
+            dynamicConfigs.push(cfg);
+        }
+    }
+    // If no dynamic configs or page doesn't support interception, return early
+    if (dynamicConfigs.length === 0) {
+        return { xHeaders, cleanup: () => { } };
+    }
+    // Build a set of request-source and response-source configs
+    const requestConfigs = dynamicConfigs.filter(c => !c.source || c.source === 'request');
+    const responseConfigs = dynamicConfigs.filter(c => !c.source || c.source === 'response');
+    // Helper: check if a URL matches the provider domains and optional urlPattern
+    function matchesUrl(url, urlPattern) {
+        // Must match at least one provider domain
+        let domainMatch = false;
+        try {
+            const parsed = new URL(url);
+            for (const domain of providerDomains) {
+                // Support wildcard domains like *.example.com
+                if (domain.startsWith('*.')) {
+                    const suffix = domain.slice(1); // .example.com
+                    if (parsed.hostname.endsWith(suffix) || parsed.hostname === domain.slice(2)) {
+                        domainMatch = true;
+                        break;
+                    }
+                }
+                else if (parsed.hostname === domain) {
+                    domainMatch = true;
+                    break;
+                }
+            }
+        }
+        catch {
+            return false;
+        }
+        if (!domainMatch)
+            return false;
+        // Optional urlPattern filter (simple substring match on full URL)
+        if (urlPattern) {
+            return url.includes(urlPattern);
+        }
+        return true;
+    }
+    // Helper: extract matching headers from a headers record
+    function extractHeaders(configs, url, headers) {
+        for (const cfg of configs) {
+            if (!matchesUrl(url, cfg.urlPattern))
+                continue;
+            // Case-insensitive header lookup
+            const lowerName = cfg.name.toLowerCase();
+            for (const [key, value] of Object.entries(headers)) {
+                if (key.toLowerCase() === lowerName) {
+                    xHeaders[cfg.name] = value;
+                    break;
+                }
+            }
+        }
+    }
+    // Set up request listener
+    if (requestConfigs.length > 0 && page.onRequest) {
+        const unsub = page.onRequest((req) => {
+            extractHeaders(requestConfigs, req.url, req.headers);
+        });
+        cleanups.push(unsub);
+    }
+    // Set up response listener
+    if (responseConfigs.length > 0 && page.onResponse) {
+        const unsub = page.onResponse((res) => {
+            extractHeaders(responseConfigs, res.url, res.headers);
+        });
+        cleanups.push(unsub);
+    }
+    return {
+        xHeaders,
+        cleanup: () => {
+            for (const fn of cleanups) {
+                fn();
+            }
+        },
+    };
+}

package/dist/browser/flows/hybrid-flow.d.ts

@@ -0,0 +1,37 @@
+import type { IBrowserAdapter, IBrowserPage } from '../../core/interfaces/browser-adapter.js';
+import type { XHeaderConfig } from '../../core/types.js';
+import type { BrowserConfig } from '../../config/schema.js';
+import type { Result } from '../../core/result.js';
+import { type AuthError } from '../../core/errors.js';
+export interface HybridFlowOptions {
+    entryUrl: string;
+    /** Called on each page to check if auth is complete */
+    isAuthenticated: (page: IBrowserPage) => Promise<boolean>;
+    /** Called once auth is detected to extract credentials */
+    extractCredentials: (page: IBrowserPage, xHeaders?: Record<string, string>, meta?: {
+        immediateAuth: boolean;
+    }) => Promise<Result<unknown, AuthError>>;
+    /** Global browser config (timeouts, waitUntil defaults) */
+    browserConfig: BrowserConfig;
+    /** Skip headless, go straight to visible (from provider config) */
+    forceVisible?: boolean;
+    /** Strategy-specific waitUntil override (e.g. cookie strategy uses 'networkidle') */
+    waitUntil?: 'load' | 'networkidle' | 'domcontentloaded' | 'commit';
+    /** Custom browser launch args */
+    browserArgs?: string[];
+    /** X-header configs — extra HTTP headers to capture during browser auth */
+    xHeaders?: XHeaderConfig[];
+    /** Provider domains used for filtering x-header capture */
+    providerDomains?: string[];
+}
+/**
+ * Hybrid browser flow: headless → visible fallback.
+ *
+ * 1. Tries headless browser first (fast, no user interaction)
+ * 2. If headless fails (timeout, CAPTCHA, cert dialog), switches to visible
+ * 3. In visible mode, waits for user to complete login manually
+ * 4. Extracts credentials once authenticated
+ *
+ * This flow is adapter-agnostic — works with any IBrowserAdapter.
+ */
+export declare function runHybridFlow<T>(adapter: IBrowserAdapter, options: HybridFlowOptions): Promise<Result<T, AuthError>>;