@skrr-ai/auth-core 0.1.2

package/dist/esm/loginLocalhost.js

@@ -0,0 +1,355 @@
+/**
+ * loginLocalhost.ts — local 127.0.0.1 callback server for the PKCE
+ * authorization-code login flow (Phase H.0,
+ * docs/daemon-auth-roadmap.md).
+ *
+ * The CLI starts this server on an ephemeral port BEFORE opening the
+ * browser to the consent page. After the user approves on
+ * `app.oversky.ai/auth/cli`, the OverSky server 302s the browser to
+ * `http://127.0.0.1:<port>/callback?code=...&state=...`. We accept
+ * exactly that one redirect (single-use, validated state, reject every
+ * other path/method/payload), hand the auth code back to the caller,
+ * close the server, and the caller proceeds to PKCE token exchange.
+ *
+ * API shape — handle pattern:
+ *
+ *   const handle = await startLocalCallback({ state });
+ *   // handle.redirectUri is bound and known synchronously; pass it to
+ *   // /cli-init so the server can validate + embed it in the consent
+ *   // page's redirect.
+ *   await postCliInit({ redirect_uri: handle.redirectUri, state, ... });
+ *   openBrowser(authUrl);
+ *   const { code } = await handle.waitForCallback();
+ *
+ * The split avoids the awkward "we need redirectUri before the
+ * callback arrives but the same Promise resolves with the code" tangle
+ * — the redirectUri is hot the moment listen() succeeds, the callback
+ * promise resolves much later when the user approves.
+ *
+ * Security model:
+ *   - 127.0.0.1 only — never 0.0.0.0. A daemon binding 0.0.0.0 lets
+ *     any device on the LAN snag the auth code by hitting the callback
+ *     URL on the developer's machine before the legitimate browser
+ *     does. Numeric host (not "localhost") to avoid a DNS resolver
+ *     surprise routing the lookup off-loopback.
+ *   - State validation with timingSafeEqual via `pkce.safeEqual`. The
+ *     state is generated by the CLI and bound into both the consent
+ *     page request and the callback URL. A redirect that does not
+ *     echo the exact state is rejected with no detail leaked to the
+ *     page — attacker cannot tell "missing" from "wrong".
+ *   - Single-use: the first valid callback resolves the promise and
+ *     immediately closes the server. Any further requests during
+ *     teardown receive a generic 503 from the closing socket.
+ *   - Reject non-GET (405) and unknown paths (404) so a probing
+ *     request can't deduce the server's purpose from differential
+ *     responses.
+ *   - No user-controlled data in any HTML response — static templates
+ *     only. Defense vs reflected-XSS via a malicious
+ *     `error_description` value an attacker might inject.
+ *   - Structured error classes so the caller branches correctly:
+ *       BindError       → fall back to a different port or device-code
+ *       TimeoutError    → fall back to device-code with explanation
+ *       StateMismatchError → likely attack; fail loudly, do not retry
+ *       DeniedError     → user declined; surface clearly, do not retry
+ *       MalformedCallbackError → server bug or rogue extension;
+ *                         surface for diagnosis
+ *       (CANCELLED)     → caller invoked handle.close() before the
+ *                         callback arrived
+ *
+ * The server and timeout DO keep the event loop alive — that's the
+ * whole point: this module is invoked from a top-level CLI command
+ * that needs to block on the user clicking approve. Ctrl-C in the
+ * CLI sends SIGINT, which interrupts the caller's await and triggers
+ * normal shutdown logic (which should call handle.close()). Setting
+ * server.unref() here would let isolated CLI invocations exit before
+ * the callback arrives.
+ */
+import http from 'node:http';
+import { safeEqual } from './pkce.js';
+import { getAuthLogger } from './runtime.js';
+/** Callback path — hardcoded; caller MUST construct redirectUri to match. */
+const CALLBACK_PATH = '/callback';
+/** Default total wait (ms) for the callback. Matches consent-page UX. */
+export const DEFAULT_LOGIN_TIMEOUT_MS = 2 * 60 * 1000;
+// ---------------------------------------------------------------------
+// Structured errors — caller branches on these
+// ---------------------------------------------------------------------
+export class LocalCallbackError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'LocalCallbackError';
+        this.code = code;
+    }
+}
+export class LocalCallbackBindError extends LocalCallbackError {
+    port;
+    cause;
+    constructor(port, cause) {
+        super('BIND_FAILED', `Failed to bind localhost callback on port ${port}: ${cause?.message ?? 'unknown error'}`);
+        this.name = 'LocalCallbackBindError';
+        this.port = port;
+        this.cause = cause;
+    }
+}
+export class LocalCallbackTimeoutError extends LocalCallbackError {
+    timeoutMs;
+    constructor(timeoutMs) {
+        super('TIMEOUT', `No callback received within ${timeoutMs} ms`);
+        this.name = 'LocalCallbackTimeoutError';
+        this.timeoutMs = timeoutMs;
+    }
+}
+export class LocalCallbackStateMismatchError extends LocalCallbackError {
+    constructor() {
+        super('STATE_MISMATCH', 'Callback state did not match the expected value — rejecting (possible attack)');
+        this.name = 'LocalCallbackStateMismatchError';
+    }
+}
+export class LocalCallbackDeniedError extends LocalCallbackError {
+    serverError;
+    constructor(serverError, description) {
+        super('DENIED', description ? `${serverError}: ${description}` : serverError);
+        this.name = 'LocalCallbackDeniedError';
+        this.serverError = serverError;
+    }
+}
+export class LocalCallbackMalformedError extends LocalCallbackError {
+    constructor(reason) {
+        super('MALFORMED', `Malformed callback: ${reason}`);
+        this.name = 'LocalCallbackMalformedError';
+    }
+}
+// ---------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------
+/**
+ * Start the local 127.0.0.1 callback server. Binds synchronously
+ * (await'd via the listen handshake) and returns a handle whose
+ * `redirectUri` is immediately usable. The caller drives the rest of
+ * the flow and awaits `waitForCallback()` when ready.
+ *
+ * Throws `LocalCallbackBindError` if the bind fails (caller decides
+ * whether to retry on a different port or fall back to device-code).
+ */
+export async function startLocalCallback(opts) {
+    const log = getAuthLogger();
+    const port = opts.port ?? 0;
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_LOGIN_TIMEOUT_MS;
+    const expectedState = opts.state;
+    // P1 #5 (multica-convergence) — host/bindAddr split. Defaults preserve the
+    // pre-change security posture (127.0.0.1 for both). Any deviation is
+    // logged prominently because it widens the callback blast radius.
+    const urlHost = typeof opts.host === 'string' && opts.host.length > 0 ? opts.host : '127.0.0.1';
+    const bindAddr = typeof opts.bindAddr === 'string' && opts.bindAddr.length > 0 ? opts.bindAddr : urlHost;
+    const isLoopback = (h) => h === '127.0.0.1' || h === '::1' || h === 'localhost';
+    if (!isLoopback(bindAddr)) {
+        log.warn(`[loginLocalhost] non-loopback bind ${bindAddr} — any device reaching this interface ` +
+            'can race the callback. Only use on trusted networks.');
+    }
+    if (typeof expectedState !== 'string' || expectedState.length === 0) {
+        throw new LocalCallbackError('BAD_OPTIONS', 'startLocalCallback: state is required');
+    }
+    if (typeof timeoutMs !== 'number' || !Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        throw new LocalCallbackError('BAD_OPTIONS', `startLocalCallback: invalid timeoutMs=${timeoutMs}`);
+    }
+    // Wire the callback promise up front so the request handler can
+    // settle it without referencing the outer Promise constructor.
+    let settled = false;
+    let resolveCallback;
+    let rejectCallback;
+    const callbackPromise = new Promise((resolve, reject) => {
+        resolveCallback = resolve;
+        rejectCallback = reject;
+    });
+    let timer = null;
+    // Populated after listen() succeeds — every code path that reads
+    // `redirectUri` runs strictly after that resolution.
+    let redirectUri = '';
+    const tearDown = () => {
+        if (timer) {
+            clearTimeout(timer);
+            timer = null;
+        }
+        try {
+            // Drop any keep-alive sockets a misbehaving extension may have
+            // opened — without this, server.close() waits indefinitely for
+            // them to idle out. Available since Node 18.2; we require >=20.
+            server.closeAllConnections?.();
+        }
+        catch {
+            /* ignore */
+        }
+        try {
+            server.close();
+        }
+        catch {
+            /* ignore */
+        }
+    };
+    const settle = (err, result) => {
+        if (settled)
+            return;
+        settled = true;
+        tearDown();
+        if (err)
+            rejectCallback(err);
+        else if (result)
+            resolveCallback(result);
+    };
+    const server = http.createServer((req, res) => {
+        // Reject anything except GET /callback. Bodies are deliberately
+        // generic — never reveal which check failed (purpose-disclosure
+        // resistance); attacker probing the port shouldn't learn it's a
+        // PKCE callback server vs. some other localhost service.
+        if (req.method !== 'GET') {
+            res.writeHead(405, { 'Content-Type': 'text/plain', Allow: 'GET' });
+            res.end('Method not allowed');
+            return;
+        }
+        // Parse with an explicit base — never trust the Host header.
+        const reqUrl = new URL(req.url || '/', 'http://127.0.0.1');
+        if (reqUrl.pathname !== CALLBACK_PATH) {
+            res.writeHead(404, { 'Content-Type': 'text/plain' });
+            res.end('Not found');
+            return;
+        }
+        // Authorization-server error path: ?error=access_denied[&error_description=...]
+        // The error_description is attacker-controllable in principle, so
+        // never echo it into HTML — we serve a static page and surface
+        // the structured detail only via the rejected promise + log.
+        const oauthError = reqUrl.searchParams.get('error');
+        if (oauthError) {
+            const desc = reqUrl.searchParams.get('error_description') ?? undefined;
+            res.writeHead(400, { 'Content-Type': 'text/html; charset=utf-8' });
+            res.end(declinedHtml());
+            log.warn(`[loginLocalhost] authorization server returned error=${oauthError} ` +
+                (desc ? `description=${desc}` : ''));
+            settle(new LocalCallbackDeniedError(oauthError, desc));
+            return;
+        }
+        const code = reqUrl.searchParams.get('code');
+        const returnedState = reqUrl.searchParams.get('state');
+        if (!code || !returnedState) {
+            res.writeHead(400, { 'Content-Type': 'text/html; charset=utf-8' });
+            res.end(genericFailureHtml());
+            settle(new LocalCallbackMalformedError('missing code or state'));
+            return;
+        }
+        if (!safeEqual(returnedState, expectedState)) {
+            // Generic 400 body — do NOT distinguish "missing" from "wrong"
+            // on the page. Logged separately for ops triage.
+            res.writeHead(400, { 'Content-Type': 'text/html; charset=utf-8' });
+            res.end(genericFailureHtml());
+            log.warn('[loginLocalhost] state mismatch on callback — rejecting');
+            settle(new LocalCallbackStateMismatchError());
+            return;
+        }
+        // Happy path.
+        res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+        res.end(successHtml());
+        settle(null, { code, state: returnedState, redirectUri });
+    });
+    // Bind. Use a one-shot 'error' listener that's removed on success so
+    // post-bind socket errors flow through the server-level handler set
+    // up below.
+    await new Promise((resolve, reject) => {
+        const onListenError = (err) => {
+            reject(new LocalCallbackBindError(port, err));
+        };
+        server.once('error', onListenError);
+        server.listen(port, bindAddr, () => {
+            server.removeListener('error', onListenError);
+            resolve();
+        });
+    });
+    const addr = server.address();
+    if (!addr || typeof addr === 'string') {
+        try {
+            server.close();
+        }
+        catch {
+            /* ignore */
+        }
+        throw new LocalCallbackBindError(port, new Error('server.address() returned non-AddressInfo after listen'));
+    }
+    // IPv6 literal hosts need brackets in the URL form.
+    const hostInUrl = urlHost.includes(':') && !urlHost.startsWith('[') ? `[${urlHost}]` : urlHost;
+    redirectUri = `http://${hostInUrl}:${addr.port}${CALLBACK_PATH}`;
+    log.debug?.(`[loginLocalhost] listening on ${redirectUri}`);
+    // Post-bind error handler — socket errors etc. Once we've settled the
+    // happy path, swallow further errors quietly so a delayed
+    // ECONNRESET from a closed-tab keep-alive can't blow up the process.
+    server.on('error', (err) => {
+        if (settled)
+            return;
+        log.warn(`[loginLocalhost] post-bind server error: ${err.message}`);
+        settle(new LocalCallbackError('SERVER_ERROR', err.message));
+    });
+    timer = setTimeout(() => {
+        settle(new LocalCallbackTimeoutError(timeoutMs));
+    }, timeoutMs);
+    // Deliberately NOT calling server.unref() / timer.unref(). The
+    // whole point of this server is to keep the parent process alive
+    // while waiting for the user to click approve in the browser; if
+    // nothing else in the CLI is ref'd (we may be deep in an isolated
+    // login command), an unref'd server would let the event loop exit
+    // before the callback ever arrives. Ctrl-C handles teardown via
+    // SIGINT, which interrupts the await in the caller and lets normal
+    // shutdown logic invoke handle.close().
+    return {
+        redirectUri,
+        waitForCallback: () => callbackPromise,
+        close: () => {
+            settle(new LocalCallbackError('CANCELLED', 'callback wait cancelled by caller'));
+        },
+    };
+}
+// ---------------------------------------------------------------------
+// Static HTML responses — no user-controlled fields anywhere.
+// ---------------------------------------------------------------------
+function htmlShell(title, accent, headline, body) {
+    // Single inline template — keeps the binary self-contained (no
+    // bundled assets) and survives offline/firewalled environments.
+    return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>${title}</title>
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <style>
+    body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif;
+           background: #0b0d12; color: #f4f6fb; margin: 0; min-height: 100vh;
+           display: grid; place-items: center; }
+    .card { max-width: 24rem; padding: 2rem; text-align: center; }
+    h1 { font-size: 1.4rem; margin: 0 0 0.5rem 0; font-weight: 600; }
+    p  { margin: 0; color: #94a3b8; line-height: 1.5; font-size: 0.95rem; }
+    .badge { width: 56px; height: 56px; margin: 0 auto 1.25rem; border-radius: 50%;
+             background: ${accent}; display: grid; place-items: center; }
+    .badge svg { width: 28px; height: 28px; stroke: white; stroke-width: 3; fill: none;
+                 stroke-linecap: round; stroke-linejoin: round; }
+  </style>
+</head>
+<body>
+  <div class="card">
+    ${headline}
+    <p>${body}</p>
+  </div>
+</body>
+</html>`;
+}
+function successHtml() {
+    const headline = `<div class="badge"><svg viewBox="0 0 24 24"><path d="M5 13l4 4L19 7"/></svg></div>
+    <h1>Authorized</h1>`;
+    return htmlShell('OverSky — Authorized', '#10b981', headline, 'You can close this tab and return to your terminal.');
+}
+function declinedHtml() {
+    const headline = `<div class="badge" style="background:#64748b"><svg viewBox="0 0 24 24"><path d="M6 6l12 12M18 6L6 18"/></svg></div>
+    <h1>Authorization declined</h1>`;
+    return htmlShell('OverSky — Authorization declined', '#64748b', headline, 'You can close this tab. Run the CLI command again to retry.');
+}
+function genericFailureHtml() {
+    const headline = `<div class="badge" style="background:#ef4444"><svg viewBox="0 0 24 24"><path d="M12 8v4M12 16h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z"/></svg></div>
+    <h1>Authorization error</h1>`;
+    return htmlShell('OverSky — Authorization error', '#ef4444', headline, 'Something went wrong. You can close this tab and retry from the terminal.');
+}

package/dist/esm/loginWithLocalhost.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Caller-injected browser opener. Daemon side wraps platform-specific
+ * commands (`open`, `xdg-open`, `rundll32 url.dll,FileProtocolHandler`)
+ * in this signature. Failure to open the browser is non-fatal — we
+ * always print the URL to stdout as well, so a user with a broken
+ * default browser association can copy/paste.
+ */
+export type BrowserOpener = (url: string) => void | Promise<void>;
+export interface LoginWithLocalhostOptions {
+    /** Server API base URL — e.g. https://api.oversky.ai or http://localhost:3080. */
+    serverUrl: string;
+    /**
+     * Scope to request. Maps directly to DaemonRefreshSession.scope on
+     * the issued refresh token (Phase F). 'daemon' for the long-running
+     * tool-executor; 'cli' for short-lived REST-only operations.
+     */
+    scope?: 'daemon' | 'cli';
+    /**
+     * User-facing label for the device. Surfaced on the consent page so
+     * the user can confirm they're authorizing the right machine.
+     * Defaults to a generic label if omitted.
+     */
+    deviceName?: string;
+    /**
+     * Daemon ID to bind the issued refresh token to. Same role as the
+     * `daemonId` parameter on the device-code init endpoint. Without it,
+     * the server falls back to a synthesized ID and the first refresh
+     * rotation may fail (the C1 incident pattern from device-code).
+     */
+    daemonId?: string;
+    /**
+     * Port for the local callback. 0 = ephemeral. Pin via
+     * `OVERSKY_LOGIN_PORT` for firewall-allowlisted environments.
+     */
+    port?: number;
+    /**
+     * P1 #5 (multica-convergence) — override the host that appears in
+     * `redirectUri`. Defaults to `'127.0.0.1'`. Use only when the
+     * browser is on a different machine than the CLI (LAN scenario).
+     * A warning is logged when non-loopback.
+     */
+    host?: string;
+    /**
+     * Bind-address override (paired with `host`). Defaults to `host`
+     * value. Use `0.0.0.0` to listen on all interfaces when pairing with
+     * a LAN-reachable `host` IP.
+     */
+    bindAddr?: string;
+    /** Total timeout (ms) the local server waits for the callback. */
+    timeoutMs?: number;
+    /** Caller-injected browser opener. */
+    openBrowser: BrowserOpener;
+    /**
+     * fetch override for tests. Defaults to `globalThis.fetch` (Node 20+).
+     * Tests can swap in a mock that drives the local callback directly
+     * instead of needing a real server.
+     */
+    fetchImpl?: typeof fetch;
+    /**
+     * If provided, called once with the authUrl AFTER the local server
+     * is bound but BEFORE the browser is opened. Lets the CLI print the
+     * URL up front (so a user whose browser fails to open can still
+     * paste it). Non-fatal — exceptions are caught and logged.
+     */
+    onAuthUrl?: (authUrl: string) => void;
+}
+export interface LoginWithLocalhostResult {
+    /**
+     * Access token (JWT). Optional after Stage-E #1 step 4: daemon-scope
+     * logins ship `opaqueAccessToken` only and omit `token` because the
+     * daemon-JWT substrate has been retired. CLI / web logins still
+     * receive a JWT here.
+     */
+    token?: string;
+    /** Access token expiry (ms epoch), if the server returned one. */
+    expiresAt?: number;
+    /** Rotating refresh token, if issued (Phase E). */
+    refreshToken?: string;
+    /** Refresh token expiry (ms epoch), if issued. */
+    refreshExpiresAt?: number;
+    /** Daemon ID the refresh token is bound to (server may have synthesized). */
+    daemonId?: string;
+    /** Echo of the scope of the issued tokens. */
+    scope?: 'daemon' | 'cli' | 'web';
+    /**
+     * Stage-E #1 — opaque `osk_dmn_*` daemon access token co-issued with
+     * the JWT for daemon-scope login. Optional during the dark-ship
+     * migration:
+     *   - undefined  → server didn't co-issue (older API, non-daemon
+     *                  scope, or kill switch on). Caller stores JWT only.
+     *   - string     → caller MUST persist via
+     *                  `saveToken(..., { opaqueAccessToken: result.opaqueAccessToken })`
+     *                  so the next handshake prefers it over the JWT.
+     *
+     * Closes the "fresh login pre-first-refresh" 1h blind spot. Without
+     * this, a freshly-logged-in daemon would auth via JWT until its
+     * first refresh response (~1h) co-issued an opaque, then switch
+     * over. With this, the daemon presents opaque from the very first
+     * post-login WS handshake.
+     *
+     * NEVER null on this surface — login responses don't carry the
+     * "explicitly clear" semantic that refresh responses do. A null
+     * field on the wire is treated as undefined (field absent).
+     */
+    opaqueAccessToken?: string;
+}
+/**
+ * /cli-init failed. `code` distinguishes the failure mode so the
+ * caller can branch (FEATURE_DISABLED → fall back to device-code; the
+ * rest → surface to user).
+ */
+export declare class LoginInitError extends Error {
+    readonly code: 'FEATURE_DISABLED' | 'BAD_REQUEST' | 'RATE_LIMITED' | 'SERVER_ERROR' | 'NETWORK_ERROR' | 'MALFORMED_RESPONSE';
+    readonly status?: number;
+    readonly responseBody?: string;
+    constructor(code: LoginInitError['code'], message: string, status?: number, body?: string);
+}
+/** /cli-token-exchange failed. */
+export declare class LoginExchangeError extends Error {
+    readonly code: 'INVALID_GRANT' | 'BAD_REQUEST' | 'SERVER_ERROR' | 'NETWORK_ERROR' | 'MALFORMED_RESPONSE';
+    readonly status?: number;
+    readonly responseBody?: string;
+    constructor(code: LoginExchangeError['code'], message: string, status?: number, body?: string);
+}
+/**
+ * Run the full PKCE-via-localhost login flow. See file header for the
+ * step-by-step. Throws structured errors on every failure path. The
+ * local callback server is always torn down before this function
+ * returns or throws.
+ */
+export declare function loginWithLocalhost(opts: LoginWithLocalhostOptions): Promise<LoginWithLocalhostResult>;