signet-auth 1.0.0-beta.0

package/dist/browser/flows/hybrid-flow.js

@@ -0,0 +1,104 @@
+import { err } from '../../core/result.js';
+import { BrowserError, BrowserTimeoutError } from '../../core/errors.js';
+import { startHeaderCapture } from './header-capture.js';
+/**
+ * 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 async function runHybridFlow(adapter, options) {
+    const { headlessTimeout, visibleTimeout } = options.browserConfig;
+    // Phase 1: Try headless (unless forceVisible)
+    if (!options.forceVisible) {
+        const headlessResult = await attemptAuth(adapter, {
+            ...options,
+            headless: true,
+            timeout: headlessTimeout,
+        });
+        if (headlessResult.ok)
+            return headlessResult;
+        console.error(`[signet] Headless auth failed: ${headlessResult.error.message}. Switching to visible mode...`);
+    }
+    // Phase 2: Visible mode (user-assisted)
+    console.error('[signet] Please complete login in the browser window...');
+    return await attemptAuth(adapter, {
+        ...options,
+        headless: false,
+        timeout: visibleTimeout,
+    });
+}
+async function attemptAuth(adapter, options) {
+    let session;
+    let headerCleanup;
+    try {
+        const launchOptions = {
+            headless: options.headless,
+            timeout: options.timeout,
+            args: options.browserArgs,
+        };
+        session = await adapter.launch(launchOptions);
+        const page = await session.newPage();
+        // Set up x-header capture before navigation (so we capture all traffic)
+        let xHeaders;
+        if (options.xHeaders && options.xHeaders.length > 0) {
+            const capture = startHeaderCapture(page, options.xHeaders, options.providerDomains ?? []);
+            xHeaders = capture.xHeaders;
+            headerCleanup = capture.cleanup;
+        }
+        // Navigate to entry URL
+        // Strategy can override global waitUntil (e.g. cookie forces 'networkidle')
+        const waitUntil = options.waitUntil ?? options.browserConfig.waitUntil;
+        await page.goto(options.entryUrl, {
+            waitUntil,
+            timeout: options.timeout,
+        });
+        // Brief pause to let any client-side redirects start
+        await new Promise(resolve => setTimeout(resolve, 1500));
+        // Check if already authenticated (cached session/cookies)
+        if (await options.isAuthenticated(page)) {
+            const result = await options.extractCredentials(page, xHeaders, { immediateAuth: true });
+            return result;
+        }
+        // Wait for authentication to complete (polling)
+        const authenticated = await pollForAuth(page, options.isAuthenticated, options.timeout);
+        if (!authenticated) {
+            return err(new BrowserTimeoutError('waiting for authentication', options.timeout));
+        }
+        const result = await options.extractCredentials(page, xHeaders, { immediateAuth: false });
+        return result;
+    }
+    catch (e) {
+        if (e instanceof BrowserTimeoutError) {
+            return err(e);
+        }
+        return err(new BrowserError(e.message));
+    }
+    finally {
+        if (headerCleanup) {
+            headerCleanup();
+        }
+        if (session) {
+            await session.close().catch(() => { });
+        }
+    }
+}
+async function pollForAuth(page, isAuthenticated, timeoutMs) {
+    const pollInterval = 2_000;
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            if (await isAuthenticated(page))
+                return true;
+        }
+        catch {
+            // Page might be navigating — ignore and retry
+        }
+        await new Promise(resolve => setTimeout(resolve, pollInterval));
+    }
+    return false;
+}

package/dist/browser/flows/oauth-consent.flow.d.ts

@@ -0,0 +1,20 @@
+import type { IBrowserPage } from '../../core/interfaces/browser-adapter.js';
+import type { BearerCredential } from '../../core/types.js';
+import type { Result } from '../../core/result.js';
+import { type AuthError } from '../../core/errors.js';
+/**
+ * Extract OAuth tokens from browser localStorage.
+ * Searches for JWT-like strings and validates them against expected audiences.
+ */
+export declare function extractOAuthTokens(page: IBrowserPage, options?: {
+    audiences?: string[];
+    extractRefreshToken?: boolean;
+    /** Max retries to wait for tokens to appear (default: 5, 2s apart) */
+    maxRetries?: number;
+}): Promise<Result<BearerCredential, AuthError>>;
+/**
+ * Check if OAuth tokens (JWTs) exist in browser storage.
+ * Used as a guard to ensure MSAL has finished writing tokens before
+ * the browser is closed.
+ */
+export declare function hasOAuthTokens(page: IBrowserPage, audiences?: string[]): Promise<boolean>;

package/dist/browser/flows/oauth-consent.flow.js

@@ -0,0 +1,170 @@
+import { ok, err } from '../../core/result.js';
+import { BrowserError } from '../../core/errors.js';
+import { decodeJwt } from '../../utils/jwt.js';
+const EXPIRY_BUFFER_MS = 60_000; // 1 minute buffer
+/** Returns true if the JWT payload has a valid (non-expired) exp claim. */
+function isTokenValid(payload) {
+    if (!payload?.exp)
+        return false;
+    return payload.exp * 1000 > Date.now() + EXPIRY_BUFFER_MS;
+}
+/**
+ * Extract OAuth tokens from browser localStorage.
+ * Searches for JWT-like strings and validates them against expected audiences.
+ */
+export async function extractOAuthTokens(page, options) {
+    const maxRetries = options?.maxRetries ?? 5;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        const result = await tryExtractTokens(page, options);
+        if (result.ok)
+            return result;
+        // If this isn't the last attempt, wait and retry (MSAL may still be writing tokens)
+        if (attempt < maxRetries) {
+            await new Promise(resolve => setTimeout(resolve, 2000));
+        }
+        else {
+            return result; // Return the last error
+        }
+    }
+    return err(new BrowserError('Token extraction exhausted all retries.'));
+}
+/**
+ * Check if OAuth tokens (JWTs) exist in browser storage.
+ * Used as a guard to ensure MSAL has finished writing tokens before
+ * the browser is closed.
+ */
+export async function hasOAuthTokens(page, audiences) {
+    try {
+        const storage = await page.evaluate(() => {
+            const entries = {};
+            for (let i = 0; i < localStorage.length; i++) {
+                const key = localStorage.key(i);
+                if (key)
+                    entries['local:' + key] = localStorage.getItem(key) ?? '';
+            }
+            for (let i = 0; i < sessionStorage.length; i++) {
+                const key = sessionStorage.key(i);
+                if (key)
+                    entries['session:' + key] = sessionStorage.getItem(key) ?? '';
+            }
+            return entries;
+        });
+        const jwtRegex = /eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g;
+        const tokens = [];
+        for (const value of Object.values(storage)) {
+            const matches = value.match(jwtRegex);
+            if (matches)
+                tokens.push(...matches);
+        }
+        if (tokens.length === 0)
+            return false;
+        for (const token of tokens) {
+            const payload = decodeJwt(token);
+            if (!payload || !isTokenValid(payload))
+                continue;
+            if (audiences && audiences.length > 0) {
+                const aud = Array.isArray(payload.aud) ? payload.aud : [payload.aud];
+                if (audiences.some(a => aud.includes(a)))
+                    return true;
+            }
+            else {
+                return true;
+            }
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+async function tryExtractTokens(page, options) {
+    try {
+        // Extract all entries from both localStorage and sessionStorage
+        const storage = await page.evaluate(() => {
+            const entries = {};
+            // Check localStorage
+            for (let i = 0; i < localStorage.length; i++) {
+                const key = localStorage.key(i);
+                if (key)
+                    entries['local:' + key] = localStorage.getItem(key) ?? '';
+            }
+            // Check sessionStorage
+            for (let i = 0; i < sessionStorage.length; i++) {
+                const key = sessionStorage.key(i);
+                if (key)
+                    entries['session:' + key] = sessionStorage.getItem(key) ?? '';
+            }
+            return entries;
+        });
+        // Find JWTs in localStorage values
+        const jwtRegex = /eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g;
+        const tokens = [];
+        for (const value of Object.values(storage)) {
+            const matches = value.match(jwtRegex);
+            if (matches)
+                tokens.push(...matches);
+        }
+        if (tokens.length === 0) {
+            return err(new BrowserError('No OAuth tokens found in browser localStorage.'));
+        }
+        // Find the best matching token: must be non-expired, match audience if specified,
+        // and prefer the one with the latest expiry.
+        let bestToken;
+        let bestPayload;
+        for (const token of tokens) {
+            const payload = decodeJwt(token);
+            if (!payload || !isTokenValid(payload))
+                continue;
+            if (options?.audiences && options.audiences.length > 0) {
+                const aud = Array.isArray(payload.aud) ? payload.aud : [payload.aud];
+                if (!options.audiences.some(a => aud.includes(a)))
+                    continue;
+            }
+            // Prefer the token with the latest expiry
+            if (!bestPayload || (payload.exp ?? 0) > (bestPayload.exp ?? 0)) {
+                bestToken = token;
+                bestPayload = payload;
+            }
+        }
+        if (!bestToken) {
+            return err(new BrowserError(`No valid (non-expired) token matching audiences [${options?.audiences?.join(', ')}] found. ` +
+                `Found ${tokens.length} token(s) in storage.`));
+        }
+        // Extract refresh token (MSAL format: keys containing "refreshtoken")
+        let refreshToken;
+        if (options?.extractRefreshToken) {
+            for (const [rawKey, value] of Object.entries(storage)) {
+                // Strip the 'local:' or 'session:' prefix for key matching
+                const key = rawKey.replace(/^(local|session):/, '');
+                if (key.toLowerCase().includes('refreshtoken')) {
+                    try {
+                        const parsed = JSON.parse(value);
+                        if (parsed.secret) {
+                            refreshToken = parsed.secret;
+                            break;
+                        }
+                    }
+                    catch {
+                        // Not JSON — skip
+                    }
+                }
+            }
+        }
+        const expiresAt = bestPayload?.exp
+            ? new Date(bestPayload.exp * 1000).toISOString()
+            : undefined;
+        const credential = {
+            type: 'bearer',
+            accessToken: bestToken,
+            refreshToken,
+            expiresAt,
+            scopes: bestPayload?.scp
+                ? String(bestPayload.scp).split(' ')
+                : undefined,
+        };
+        return ok(credential);
+    }
+    catch (e) {
+        return err(new BrowserError(`Token extraction failed: ${e.message}`));
+    }
+}

package/dist/cli/commands/doctor.d.ts

@@ -0,0 +1,6 @@
+/**
+ * sig doctor — Environment diagnostics.
+ * Runs a series of checks and reports pass/fail for each.
+ * Does NOT take deps (can run before config is fully wired).
+ */
+export declare function runDoctor(positionals: string[], flags: Record<string, string | boolean>): Promise<void>;

package/dist/cli/commands/doctor.js

@@ -0,0 +1,263 @@
+/**
+ * sig doctor — Environment diagnostics.
+ * Runs a series of checks and reports pass/fail for each.
+ * Does NOT take deps (can run before config is fully wired).
+ */
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+import { getConfigPath, loadConfig } from '../../config/loader.js';
+import { isOk } from '../../core/result.js';
+const PASS = '\u2713'; // ✓
+const FAIL = '\u2717'; // ✗
+function printResults(results) {
+    let failures = 0;
+    for (const r of results) {
+        if (r.ok) {
+            const detail = r.detail ? ` (${r.detail})` : '';
+            console.log(`  ${PASS} ${r.label}${detail}`);
+        }
+        else {
+            failures++;
+            console.log(`  ${FAIL} ${r.label}`);
+            if (r.hint) {
+                console.log(`    \u2192 ${r.hint}`);
+            }
+        }
+    }
+    console.log('');
+    if (failures === 0) {
+        console.log('All checks passed.');
+    }
+    else {
+        console.log(`${failures} issue${failures > 1 ? 's' : ''} found.`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Individual checks
+// ---------------------------------------------------------------------------
+function checkConfigExists() {
+    const configPath = getConfigPath();
+    const exists = fs.existsSync(configPath);
+    return {
+        label: 'Config file exists',
+        ok: exists,
+        detail: exists ? configPath.replace(os.homedir(), '~') : undefined,
+        hint: exists ? undefined : 'Run "sig init" to create ~/.signet/config.yaml',
+    };
+}
+async function checkConfigValid() {
+    const configResult = await loadConfig();
+    if (!isOk(configResult)) {
+        return {
+            label: 'Config is valid',
+            ok: false,
+            hint: configResult.error.message,
+        };
+    }
+    return {
+        label: 'Config is valid',
+        ok: true,
+        config: configResult.value,
+    };
+}
+async function checkCredentialsDir(config) {
+    if (!config) {
+        return {
+            label: 'Credentials directory exists',
+            ok: false,
+            hint: 'Fix config first',
+        };
+    }
+    const dir = config.storage.credentialsDir.replace(/^~/, os.homedir());
+    try {
+        await fsp.access(dir, fs.constants.R_OK | fs.constants.W_OK);
+        return {
+            label: 'Credentials directory exists',
+            ok: true,
+            detail: config.storage.credentialsDir,
+        };
+    }
+    catch {
+        return {
+            label: 'Credentials directory exists',
+            ok: false,
+            hint: `Directory not found or not writable: ${config.storage.credentialsDir}`,
+        };
+    }
+}
+async function checkBrowserDataDir(config) {
+    if (!config) {
+        return {
+            label: 'Browser data directory exists',
+            ok: false,
+            hint: 'Fix config first',
+        };
+    }
+    const dir = config.browser.browserDataDir.replace(/^~/, os.homedir());
+    const exists = fs.existsSync(dir);
+    return {
+        label: 'Browser data directory exists',
+        ok: exists,
+        detail: exists ? config.browser.browserDataDir : undefined,
+        hint: exists ? undefined : `Directory not found: ${config.browser.browserDataDir}`,
+    };
+}
+function findChannelBrowser(channel) {
+    const platform = process.platform;
+    // Check common browser locations based on channel and platform
+    if (platform === 'darwin') {
+        const apps = {
+            chrome: '/Applications/Google Chrome.app',
+            msedge: '/Applications/Microsoft Edge.app',
+            chromium: '/Applications/Chromium.app',
+        };
+        if (apps[channel])
+            return fs.existsSync(apps[channel]);
+    }
+    if (platform === 'linux') {
+        const bins = {
+            chrome: 'google-chrome',
+            msedge: 'microsoft-edge',
+            chromium: 'chromium',
+        };
+        if (bins[channel]) {
+            try {
+                execSync(`which ${bins[channel]}`, { stdio: 'ignore' });
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }
+    }
+    return false;
+}
+async function checkBrowserAvailable(config) {
+    if (!config) {
+        return {
+            label: 'Browser available',
+            ok: false,
+            hint: 'Fix config first',
+        };
+    }
+    const channel = config.browser.channel;
+    try {
+        // Verify playwright-core is importable
+        await import('playwright-core');
+        // Check if the channel browser is installed on the system
+        const found = findChannelBrowser(channel);
+        if (found) {
+            return {
+                label: 'Browser available',
+                ok: true,
+                detail: channel,
+            };
+        }
+        // Fallback: if we can't detect by channel but playwright-core is available, report cautiously
+        return {
+            label: 'Browser available',
+            ok: true,
+            detail: `${channel} (playwright-core loaded, browser not verified)`,
+        };
+    }
+    catch {
+        return {
+            label: 'Browser available',
+            ok: false,
+            hint: 'playwright-core not installed. Run "npm install playwright-core".',
+        };
+    }
+}
+function checkNodeVersion() {
+    const version = process.version;
+    const match = version.match(/^v(\d+)/);
+    const major = match ? parseInt(match[1], 10) : 0;
+    return {
+        label: 'Node.js version',
+        ok: major >= 18,
+        detail: version,
+        hint: major < 18 ? `Node.js >= 18 is required. Current: ${version}` : undefined,
+    };
+}
+async function checkStoredCredentials(config) {
+    if (!config) {
+        return {
+            label: 'Stored credentials',
+            ok: true,
+            detail: 'skipped (no config)',
+        };
+    }
+    const dir = config.storage.credentialsDir.replace(/^~/, os.homedir());
+    try {
+        const files = await fsp.readdir(dir);
+        const jsonFiles = files.filter(f => f.endsWith('.json') && !f.endsWith('.lock'));
+        const total = jsonFiles.length;
+        // Check for expired credentials by reading each file
+        let expired = 0;
+        for (const file of jsonFiles) {
+            try {
+                const content = await fsp.readFile(path.join(dir, file), 'utf-8');
+                const data = JSON.parse(content);
+                const cred = data?.credential;
+                if (cred?.type === 'bearer' && cred?.token) {
+                    try {
+                        const { isJwtExpired } = await import('../../utils/jwt.js');
+                        if (isJwtExpired(cred.token))
+                            expired++;
+                    }
+                    catch {
+                        // JWT decode failed, skip
+                    }
+                }
+            }
+            catch {
+                // Skip unreadable files
+            }
+        }
+        const detail = expired > 0
+            ? `${total} stored credential${total !== 1 ? 's' : ''} (${expired} expired)`
+            : `${total} stored credential${total !== 1 ? 's' : ''}`;
+        return {
+            label: 'Stored credentials',
+            ok: true,
+            detail,
+        };
+    }
+    catch {
+        return {
+            label: 'Stored credentials',
+            ok: true,
+            detail: '0 stored credentials',
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Main command
+// ---------------------------------------------------------------------------
+export async function runDoctor(positionals, flags) {
+    const results = [];
+    // a. Config file exists
+    results.push(checkConfigExists());
+    // b. Config is valid
+    const configCheck = await checkConfigValid();
+    results.push(configCheck);
+    const config = configCheck.config;
+    // c. Credentials directory
+    results.push(await checkCredentialsDir(config));
+    // d. Browser data directory
+    results.push(await checkBrowserDataDir(config));
+    // e. Browser available
+    results.push(await checkBrowserAvailable(config));
+    // f. Node.js version
+    results.push(checkNodeVersion());
+    // g. Stored credentials
+    results.push(await checkStoredCredentials(config));
+    printResults(results);
+    const hasFailures = results.some(r => !r.ok);
+    if (hasFailures) {
+        process.exitCode = 1;
+    }
+}

package/dist/cli/commands/get.d.ts

@@ -0,0 +1,2 @@
+import type { AuthDeps } from '../../deps.js';
+export declare function runGet(positionals: string[], flags: Record<string, string | boolean>, deps: AuthDeps): Promise<void>;

package/dist/cli/commands/get.js

@@ -0,0 +1,83 @@
+import { isOk } from '../../core/result.js';
+import { formatJson, formatCredentialHeaders } from '../formatters.js';
+const PRIMARY_HEADERS = ['cookie', 'authorization'];
+export async function runGet(positionals, flags, deps) {
+    const target = positionals[0];
+    if (!target) {
+        process.stderr.write('Usage: sig get <provider|url>\n');
+        process.exitCode = 1;
+        return;
+    }
+    const isUrl = target.startsWith('http://') || target.startsWith('https://');
+    let providerId;
+    let credential;
+    if (isUrl) {
+        const result = await deps.authManager.getCredentialsByUrl(target);
+        if (!isOk(result)) {
+            process.stderr.write(`Error: ${result.error.message}\n`);
+            process.exitCode = result.error.code === 'PROVIDER_NOT_FOUND' ? 2 : 3;
+            return;
+        }
+        providerId = result.value.provider.id;
+        credential = result.value.credential;
+    }
+    else {
+        const provider = deps.authManager.providerRegistry.get(target);
+        if (!provider) {
+            process.stderr.write(`Error: No provider found with ID "${target}".\n`);
+            process.exitCode = 2;
+            return;
+        }
+        providerId = provider.id;
+        const result = await deps.authManager.getCredentials(providerId);
+        if (!isOk(result)) {
+            process.stderr.write(`Error: ${result.error.message}\n`);
+            process.exitCode = result.error.code === 'CREDENTIAL_NOT_FOUND' ? 3 : 1;
+            return;
+        }
+        credential = result.value;
+    }
+    const headers = deps.authManager.applyToRequest(providerId, credential);
+    const entries = Object.entries(headers);
+    if (entries.length === 0) {
+        process.stderr.write(`Error: No credential headers produced for "${providerId}".\n`);
+        process.exitCode = 3;
+        return;
+    }
+    const primaryEntry = entries.find(([name]) => PRIMARY_HEADERS.includes(name.toLowerCase()))
+        ?? entries[0];
+    const [primaryHeaderName, primaryHeaderValue] = primaryEntry;
+    const xHeaders = {};
+    for (const [name, value] of entries) {
+        if (name !== primaryHeaderName) {
+            xHeaders[name] = value;
+        }
+    }
+    const format = flags.format ?? 'json';
+    switch (format) {
+        case 'json': {
+            const output = {
+                provider: providerId,
+                credential: primaryHeaderValue,
+                headerName: primaryHeaderName,
+                type: credential.type,
+            };
+            if (Object.keys(xHeaders).length > 0)
+                output.xHeaders = xHeaders;
+            process.stdout.write(formatJson(output) + '\n');
+            break;
+        }
+        case 'header': {
+            process.stdout.write(formatCredentialHeaders(headers) + '\n');
+            break;
+        }
+        case 'value': {
+            process.stdout.write(primaryHeaderValue + '\n');
+            break;
+        }
+        default: {
+            process.stderr.write(`Unknown format: ${format}\n`);
+            process.exitCode = 1;
+        }
+    }
+}

package/dist/cli/commands/init.d.ts

@@ -0,0 +1,6 @@
+/**
+ * sig init — Interactive setup command.
+ * Creates ~/.signet/config.yaml with sensible defaults.
+ * Does NOT take deps (runs before config exists).
+ */
+export declare function runInit(positionals: string[], flags: Record<string, string | boolean>): Promise<void>;