@nebulr-group/bridge-cli 0.1.0-beta.0 → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nebulr Group
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -16,28 +16,83 @@ npx @nebulr-group/bridge-cli tenant list
 
 ## Authentication
 
-Set your Bridge API key as an environment variable:
+bridge-cli supports two authentication paths.
+
+### 1. Interactive (recommended for humans + AI agents) — `bridge auth login`
+
+```bash
+bridge auth login
+```
+
+Opens your default browser, runs through a PKCE-secured loopback flow (RFC 8252), and stores a 10-day token at `~/.config/bridge/credentials.json` (mode `0600`). After that, every subsequent `bridge` command picks the token up automatically — no env vars needed.
+
+```bash
+bridge auth status   # show who you're logged in as and when the token expires
+bridge auth logout   # revoke the token and delete the credentials file
+```
+
+#### `bridge auth login` flags
+
+| Flag | Description |
+|------|-------------|
+| `--app <id\|name>` | Pin to a specific app, skipping the picker on the consent screen. |
+| `--label <text>`  | Friendly label stored on the token (default: `bridge-cli`). Useful when listing CLI tokens at `app.thebridge.dev/keys`. |
+| `--no-browser`    | Print the authorization URL instead of opening a browser. Use this on headless boxes or over SSH. |
+
+When the token expires (10 days), the next command fails with a friendly `Token expired. Run `bridge auth login` to re-authenticate.` message.
+
+The credentials file location honors `XDG_CONFIG_HOME`:
+
+```bash
+$XDG_CONFIG_HOME/bridge/credentials.json   # if XDG_CONFIG_HOME is set
+~/.config/bridge/credentials.json          # otherwise
+```
+
+### 2. Service-account / CI — `BRIDGE_API_KEY`
+
+For non-interactive contexts (CI/CD pipelines, Docker images, headless agents) set the API key directly in the environment:
 
 ```bash
 export BRIDGE_API_KEY=<your-api-token>
 ```
 
-Optional configuration:
+If you have logged in via `bridge auth login`, the credentials file always wins — a fresh login takes effect immediately, even when `BRIDGE_API_KEY` is still exported in your shell. `BRIDGE_API_KEY` is only used when no credentials file is present (the typical CI runner shape). To switch back to env-var auth on a developer machine, run `bridge auth logout` first.
+
+Optional configuration (applies to both auth paths):
 
 ```bash
-export BRIDGE_BASE_URL=https://account-api.thebridge.dev  # default
-export BRIDGE_TENANT_ID=<tenant-id>                        # for user commands
-export BRIDGE_DEBUG=true                                   # enable debug logging
+export BRIDGE_BASE_URL=https://api.thebridge.dev   # default
+export BRIDGE_TENANT_ID=<tenant-id>                 # for user commands
+export BRIDGE_DEBUG=true                            # enable debug logging
 ```
 
 ## Usage
 
-All output is JSON by default. AI agents parse it directly; humans can pipe through `jq`.
+All output is JSON by default for management commands. AI agents parse it directly; humans can pipe through `jq`. The `bridge auth status` and `bridge auth login` commands print human-readable text, since their primary audience is a human in a terminal.
 
 ```bash
 bridge <command> <subcommand> [options]
 ```
 
+### Auth (interactive credentials)
+
+```bash
+bridge auth login                # default: open browser, complete PKCE flow
+bridge auth login --app acme     # pin to a specific app
+bridge auth login --label "work laptop"
+bridge auth login --no-browser   # print the URL (headless / SSH)
+bridge auth status               # show current login state
+bridge auth logout               # revoke token + delete local file
+```
+
+### Auth Configuration (app-level — separate from `auth login`)
+
+```bash
+bridge auth config
+bridge auth mfa --enabled true
+bridge auth password-policy --access-token-ttl 3600
+```
+
 ### App
 
 ```bash
@@ -86,14 +141,6 @@ bridge flag toggle --id <flag-id> --enabled true
 bridge flag delete --id <flag-id>
 ```
 
-### Auth Configuration
-
-```bash
-bridge auth config
-bridge auth mfa --enabled true
-bridge auth password-policy --access-token-ttl 3600
-```
-
 ### Branding
 
 ```bash
@@ -176,14 +223,24 @@ bridge guide custom
 }
 ```
 
+`bridge auth login`, `bridge auth logout`, and `bridge auth status` print plain text (they're the only commands aimed primarily at humans).
+
 ## Exit Codes
 
 | Code | Meaning |
 |------|---------|
 | 0 | Success |
-| 1 | Client error (4xx) |
+| 1 | Client error (4xx), or `bridge auth login` failed/cancelled |
 | 2 | Server error (5xx) |
-| 3 | Configuration error (missing API key, etc.) |
+| 3 | Configuration error (missing API key, expired credentials, etc.) |
+
+## Security notes
+
+- `bridge auth login` uses RFC 8252 loopback PKCE — the loopback URL is always `http://127.0.0.1:<random-port>/callback` (never `localhost`, to avoid DNS spoofing).
+- The loopback HTTP server handles a single request, then closes — no port stays bound.
+- The CSRF `state` parameter is verified on the callback before the code is exchanged.
+- The credentials file is written with mode `0600` (owner-only). Its parent directory is created with mode `0700`.
+- The CLI never logs the JWT or the PKCE `code_verifier`.
 
 ## Development
 
@@ -197,6 +254,6 @@ npm run build
 # Run locally
 node bridge-cli/dist/bin.js --help
 
-# Package
-npm run package
+# Test
+npm test
 ```

package/dist/auth/api-client.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Thin client for the bridge-api `/v1/auth/cli/*` endpoints.
+ *
+ * - `exchangeCode(...)` calls `POST /v1/auth/cli/token` with `{code, code_verifier}`.
+ * - `revokeToken(...)` calls `POST /v1/auth/cli/revoke` with `x-api-key: <jwt>`.
+ *
+ * Errors come back RFC-style as `{ error, error_description }`. We translate
+ * the common cases to friendly messages so end-users don't see RFC tags.
+ *
+ * The CLI authenticates as `x-api-key: <jwt>` (NOT `Authorization: Bearer`) —
+ * see TBP-111 contract notes.
+ */
+export interface CliTokenExchangeResponse {
+    api_token: string;
+    expires_at: string;
+    app: {
+        id: string;
+        name: string;
+    };
+    user: {
+        id: string;
+        email: string;
+    };
+}
+export interface CliApiClientOptions {
+    /** Base URL of bridge-api, e.g. `https://api.thebridge.dev`. No trailing slash. */
+    baseUrl: string;
+    /** Used for diagnostics; do NOT log secrets. */
+    debug?: boolean;
+    /** Override fetch (for tests). Defaults to the global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+export declare class CliAuthApiError extends Error {
+    /** RFC error code returned by bridge-api (`invalid_request`, `invalid_grant`, ...). */
+    readonly code: string;
+    readonly status: number;
+    constructor(code: string, message: string, status: number);
+}
+export declare function createCliApiClient(options: CliApiClientOptions): {
+    exchangeCode: (args: {
+        code: string;
+        codeVerifier: string;
+    }) => Promise<CliTokenExchangeResponse>;
+    revokeToken: (token: string) => Promise<{
+        revoked: boolean;
+    }>;
+};
+//# sourceMappingURL=api-client.d.ts.map

package/dist/auth/api-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../../src/auth/api-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAClC,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CACrC;AAED,MAAM,WAAW,mBAAmB;IAClC,mFAAmF;IACnF,OAAO,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,kEAAkE;IAClE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,qBAAa,eAAgB,SAAQ,KAAK;IACxC,uFAAuF;IACvF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBACZ,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAM1D;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB;yBAU3B;QAChC,IAAI,EAAE,MAAM,CAAC;QACb,YAAY,EAAE,MAAM,CAAC;KACtB,KAAG,OAAO,CAAC,wBAAwB,CAAC;yBA+BH,MAAM,KAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;EA2BzE"}

package/dist/auth/api-client.js

@@ -0,0 +1,109 @@
+/**
+ * Thin client for the bridge-api `/v1/auth/cli/*` endpoints.
+ *
+ * - `exchangeCode(...)` calls `POST /v1/auth/cli/token` with `{code, code_verifier}`.
+ * - `revokeToken(...)` calls `POST /v1/auth/cli/revoke` with `x-api-key: <jwt>`.
+ *
+ * Errors come back RFC-style as `{ error, error_description }`. We translate
+ * the common cases to friendly messages so end-users don't see RFC tags.
+ *
+ * The CLI authenticates as `x-api-key: <jwt>` (NOT `Authorization: Bearer`) —
+ * see TBP-111 contract notes.
+ */
+export class CliAuthApiError extends Error {
+    /** RFC error code returned by bridge-api (`invalid_request`, `invalid_grant`, ...). */
+    code;
+    status;
+    constructor(code, message, status) {
+        super(message);
+        this.name = 'CliAuthApiError';
+        this.code = code;
+        this.status = status;
+    }
+}
+export function createCliApiClient(options) {
+    const baseUrl = options.baseUrl.replace(/\/$/, '');
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    if (typeof fetchImpl !== 'function') {
+        throw new Error('No global `fetch` is available. Run bridge-cli on Node.js >= 18.');
+    }
+    async function exchangeCode(args) {
+        const url = `${baseUrl}/v1/auth/cli/token`;
+        const res = await fetchImpl(url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({
+                code: args.code,
+                code_verifier: args.codeVerifier,
+            }),
+        });
+        if (!res.ok) {
+            throw await translateError(res);
+        }
+        const body = (await res.json());
+        if (!body || typeof body.api_token !== 'string') {
+            throw new CliAuthApiError('invalid_response', 'Bridge API returned an unexpected response from /v1/auth/cli/token.', res.status);
+        }
+        return body;
+    }
+    /**
+     * Best-effort revoke. The CLI uses self-revoke (token is identified by the
+     * `x-api-key` it sends). 401 means the token is already gone — treat as
+     * success.
+     */
+    async function revokeToken(token) {
+        const url = `${baseUrl}/v1/auth/cli/revoke`;
+        let res;
+        try {
+            res = await fetchImpl(url, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    'x-api-key': token,
+                },
+                body: '{}',
+            });
+        }
+        catch (err) {
+            // Network failure — caller can still delete the local file.
+            throw new CliAuthApiError('network_error', `Could not reach bridge-api to revoke token: ${err instanceof Error ? err.message : String(err)}`, 0);
+        }
+        if (res.ok)
+            return { revoked: true };
+        if (res.status === 401)
+            return { revoked: true }; // already revoked / expired
+        throw await translateError(res);
+    }
+    return { exchangeCode, revokeToken };
+}
+async function translateError(res) {
+    let raw;
+    try {
+        raw = await res.json();
+    }
+    catch {
+        return new CliAuthApiError('http_error', `Bridge API returned HTTP ${res.status}.`, res.status);
+    }
+    const obj = (raw && typeof raw === 'object' ? raw : {});
+    const code = typeof obj.error === 'string' ? obj.error : 'http_error';
+    const desc = typeof obj.error_description === 'string' ? obj.error_description : undefined;
+    let friendly;
+    switch (code) {
+        case 'invalid_request':
+            friendly = desc ?? 'The login request was rejected as malformed.';
+            break;
+        case 'invalid_grant':
+            friendly = 'The authorization code has already been used or is invalid. Please run `bridge auth login` again.';
+            break;
+        case 'expired_grant':
+            friendly = 'The authorization code expired before it could be exchanged. Please run `bridge auth login` again.';
+            break;
+        case 'access_denied':
+            friendly = 'Login cancelled.';
+            break;
+        default:
+            friendly = desc ?? `Bridge API returned HTTP ${res.status}.`;
+    }
+    return new CliAuthApiError(code, friendly, res.status);
+}
+//# sourceMappingURL=api-client.js.map

package/dist/auth/api-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-client.js","sourceRoot":"","sources":["../../src/auth/api-client.ts"],"names":[],"mappings":"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"}

package/dist/auth/browser-open.d.ts

@@ -0,0 +1,12 @@
+export interface OpenBrowserResult {
+    ok: boolean;
+    /** Short reason the launch failed (only set when `ok === false`). */
+    reason?: string;
+}
+/**
+ * Attempts to open `url` in the user's default browser. Resolves to
+ * `{ ok: true }` on success, `{ ok: false, reason }` on failure (caller
+ * should print the URL and ask the user to open it manually).
+ */
+export declare function openBrowser(url: string): Promise<OpenBrowserResult>;
+//# sourceMappingURL=browser-open.d.ts.map

package/dist/auth/browser-open.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-open.d.ts","sourceRoot":"","sources":["../../src/auth/browser-open.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,OAAO,CAAC;IACZ,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA6DzE"}

package/dist/auth/browser-open.js

@@ -0,0 +1,82 @@
+/**
+ * Cross-platform default-browser opener.
+ *
+ * Uses `child_process.spawn` to invoke the platform's "open this URL" command:
+ *   - macOS:   `open <url>`
+ *   - Windows: `cmd /c start "" <url>`   (the empty `""` is the window title;
+ *              omitting it makes `start` interpret the URL as the title)
+ *   - Linux:   `xdg-open <url>`          (most desktops; requires xdg-utils)
+ *
+ * Returns `false` if the spawn fails or the command exits non-zero, so callers
+ * can fall back to printing the URL.
+ *
+ * Implemented directly on `child_process` to avoid a heavyweight dependency
+ * for what is ~30 lines of platform detection.
+ */
+import { spawn } from 'node:child_process';
+/**
+ * Attempts to open `url` in the user's default browser. Resolves to
+ * `{ ok: true }` on success, `{ ok: false, reason }` on failure (caller
+ * should print the URL and ask the user to open it manually).
+ */
+export async function openBrowser(url) {
+    const platform = process.platform;
+    let command;
+    let args;
+    if (platform === 'darwin') {
+        command = 'open';
+        args = [url];
+    }
+    else if (platform === 'win32') {
+        // `cmd /c start "" <url>` — empty quoted string is the (ignored) window title.
+        command = 'cmd';
+        args = ['/c', 'start', '""', url];
+    }
+    else {
+        // Treat anything else (linux, freebsd, etc.) as xdg-open.
+        command = 'xdg-open';
+        args = [url];
+    }
+    return new Promise((resolve) => {
+        let child;
+        try {
+            child = spawn(command, args, {
+                stdio: 'ignore',
+                // detached so the browser process lives independently of the CLI.
+                // unref() so the CLI can exit without waiting for the browser to close.
+                detached: true,
+            });
+        }
+        catch (err) {
+            resolve({ ok: false, reason: err instanceof Error ? err.message : String(err) });
+            return;
+        }
+        let settled = false;
+        const settle = (r) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(r);
+        };
+        child.on('error', (err) => {
+            settle({ ok: false, reason: err.message });
+        });
+        child.on('exit', (code) => {
+            if (code === 0 || code === null) {
+                settle({ ok: true });
+            }
+            else {
+                settle({ ok: false, reason: `${command} exited with code ${code}` });
+            }
+        });
+        // Don't block CLI shutdown waiting on the browser process.
+        child.unref?.();
+        // Most platforms exit (or detach) within a fraction of a second. If we
+        // don't hear back in 2s we optimistically declare success — at worst the
+        // browser opened but the parent process hung. The user only sees a
+        // problem if no callback ever arrives, and the loopback timeout handles
+        // that case.
+        setTimeout(() => settle({ ok: true }), 2000).unref?.();
+    });
+}
+//# sourceMappingURL=browser-open.js.map

package/dist/auth/browser-open.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-open.js","sourceRoot":"","sources":["../../src/auth/browser-open.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAQ3C;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,GAAW;IAC3C,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;IAClC,IAAI,OAAe,CAAC;IACpB,IAAI,IAAc,CAAC;IAEnB,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC1B,OAAO,GAAG,MAAM,CAAC;QACjB,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACf,CAAC;SAAM,IAAI,QAAQ,KAAK,OAAO,EAAE,CAAC;QAChC,+EAA+E;QAC/E,OAAO,GAAG,KAAK,CAAC;QAChB,IAAI,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;IACpC,CAAC;SAAM,CAAC;QACN,0DAA0D;QAC1D,OAAO,GAAG,UAAU,CAAC;QACrB,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACf,CAAC;IAED,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,IAAI,KAAK,CAAC;QACV,IAAI,CAAC;YACH,KAAK,GAAG,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE;gBAC3B,KAAK,EAAE,QAAQ;gBACf,kEAAkE;gBAClE,wEAAwE;gBACxE,QAAQ,EAAE,IAAI;aACf,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACjF,OAAO;QACT,CAAC;QAED,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,MAAM,MAAM,GAAG,CAAC,CAAoB,EAAE,EAAE;YACtC,IAAI,OAAO;gBAAE,OAAO;YACpB,OAAO,GAAG,IAAI,CAAC;YACf,OAAO,CAAC,CAAC,CAAC,CAAC;QACb,CAAC,CAAC;QAEF,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;YACxB,MAAM,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;QAC7C,CAAC,CAAC,CAAC;QAEH,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;YACxB,IAAI,IAAI,KAAK,CAAC,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;gBAChC,MAAM,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;YACvB,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,qBAAqB,IAAI,EAAE,EAAE,CAAC,CAAC;YACvE,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,2DAA2D;QAC3D,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;QAEhB,uEAAuE;QACvE,yEAAyE;QACzE,mEAAmE;QACnE,wEAAwE;QACxE,aAAa;QACb,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC;IACzD,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/auth/loopback.d.ts

@@ -0,0 +1,63 @@
+export interface LoopbackResult {
+    code: string;
+    state: string;
+}
+export interface RunLoopbackOptions {
+    /** The CSRF state the caller generated; must match what the IdP echoes. */
+    expectedState: string;
+    /**
+     * If set, the loopback responds 302 → this URL on success instead of
+     * rendering the inline HTML. Used to bounce the browser to a hosted,
+     * branded "you can close this tab" page on cloud-views.
+     * Falls back to inline HTML if not provided.
+     */
+    successRedirectUrl?: string;
+    /** Body of the success page rendered to the browser when no redirect URL is set. */
+    successHtml?: string;
+    /** Total time (ms) we'll wait for the redirect before giving up. */
+    timeoutMs?: number;
+}
+export interface StartedLoopback {
+    /** The redirect URI to pass to the IdP, e.g. `http://127.0.0.1:54321/callback`. */
+    redirectUri: string;
+    /** Resolves with the verified `{ code, state }` once the redirect arrives. */
+    result: Promise<LoopbackResult>;
+    /** Force-close the server (e.g. on Ctrl-C or a token-exchange failure). */
+    close: () => void;
+}
+/**
+ * Parses the loopback callback URL to extract `code`, `state`, `error`, and
+ * `error_description` query parameters.
+ *
+ * Exposed for unit testing.
+ */
+export declare function parseCallbackUrl(rawUrl: string): {
+    code?: string;
+    state?: string;
+    error?: string;
+    errorDescription?: string;
+    pathname: string;
+};
+/**
+ * Validates a parsed callback against the expected CSRF state. Returns the
+ * verified `{code, state}` or throws a friendly error.
+ */
+export declare function verifyCallback(parsed: ReturnType<typeof parseCallbackUrl>, expectedState: string): LoopbackResult;
+/**
+ * Boots the single-shot loopback listener on a random ephemeral port.
+ *
+ * Returns immediately with `{ redirectUri, result }`. The caller passes
+ * `redirectUri` to the IdP, then awaits `result` for the verified `{code, state}`.
+ *
+ * The server:
+ *  - Closes itself after the first GET to `/callback` completes its response.
+ *  - Closes itself if the token-exchange caller invokes `close()` (e.g. on a
+ *    later failure that wants to abort the wait).
+ *  - Times out after `timeoutMs` (default 5 minutes).
+ */
+export declare function startLoopback(opts: RunLoopbackOptions): Promise<StartedLoopback>;
+export declare class LoopbackError extends Error {
+    readonly kind: string;
+    constructor(message: string, kind: string);
+}
+//# sourceMappingURL=loopback.d.ts.map

package/dist/auth/loopback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loopback.d.ts","sourceRoot":"","sources":["../../src/auth/loopback.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,2EAA2E;IAC3E,aAAa,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,oFAAoF;IACpF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,mFAAmF;IACnF,WAAW,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,MAAM,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;IAChC,2EAA2E;IAC3E,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAyHD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;CAClB,CAUA;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,UAAU,CAAC,OAAO,gBAAgB,CAAC,EAC3C,aAAa,EAAE,MAAM,GACpB,cAAc,CAkBhB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,eAAe,CAAC,CAiGtF;AAED,qBAAa,aAAc,SAAQ,KAAK;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBACV,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAK1C"}