@wtfalch/auth 0.30.0 → 0.31.0

package/dist/desktop.d.ts

@@ -0,0 +1,199 @@
+import type { Auth, User } from './auth.js';
+/**
+ * The native sign-in handoff for a desktop or mobile shell, mounted under
+ * `/auth/desktop/*`. Merged from Boule's and Archon's own copies
+ * (`src/lib/desktop-handoff`), which a shell (`@wtfalch/desktop`'s
+ * `cookieHandoff` strategy, or a mobile shell of its own) talks to the same
+ * way regardless of which app it signs into.
+ *
+ * The shell opens `/auth/desktop/start` in the system browser; the issuer
+ * signs the person in; the person confirms in the browser; the shell trades
+ * its verifier for the session cookie, once, at `/auth/desktop/redeem`.
+ *
+ * A row carries the cookie from the callback to the redeem, sealed, and never
+ * reaches the browser: the callback sets no session cookie, so the browser's
+ * own session in the app is untouched.
+ *
+ *   started    /start ran; waiting for the issuer's callback
+ *   completed  the callback verified the person; the cookie is sealed in the row
+ *   approved   the person confirmed in the browser that started it
+ *
+ * A sign-in that ends (redeemed, cancelled, expired when asked about) has its
+ * row deleted, so the store never represents those as a status. A failed
+ * callback deletes nothing: a replayed callback fails at the issuer while the
+ * first one may still be succeeding, so the row just expires.
+ *
+ * Every state-changing step is one transaction on a locked row, and the
+ * store's own clock decides expiry. Nothing here logs a cookie, a verifier, a
+ * nonce or a payload.
+ *
+ * The store is the app's: this package never connects to a database it does
+ * not own. `createMemoryDesktopHandoffStore` is enough for a single-instance
+ * server and for tests; a multi-replica app supplies its own, backed by
+ * whatever table it migrates.
+ */
+export type DesktopHandoffAuth = Pick<Auth, 'sessionCookieName' | 'start' | 'complete' | 'readCookie'>;
+export declare class DesktopHandoffError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string);
+}
+export type DesktopHandoffStatus = 'started' | 'completed' | 'approved';
+export interface DesktopHandoffRow {
+    id: string;
+    status: DesktopHandoffStatus;
+    challenge: string;
+    browserHash: string | null;
+    stateHash: string | null;
+    payload: string | null;
+    subject: string | null;
+    email: string | null;
+    revision: string | null;
+}
+export interface DesktopHandoffFound {
+    row: DesktopHandoffRow;
+    /** The store's own clock decides this, read after any wait for a lock. */
+    live: boolean;
+    /** Whether a redeem attempt may be stamped now: at most one a second per row. */
+    pollOk: boolean;
+}
+/**
+ * The handoff's row store. The app's own, not this package's: an app
+ * migrates one table and implements this interface over it.
+ *
+ * A real store must make `lock` exclusive: inside `transaction`, `lock` is
+ * `SELECT ... FOR UPDATE` on the row, held until the transaction ends. The
+ * handler's one-use guarantee (a redeem returns the cookie once, a callback
+ * admits once) rests on two concurrent callers on one row taking turns. A store
+ * whose `lock` is a plain read lets both pass, and both get the cookie.
+ */
+export interface DesktopHandoffStore<Tx = unknown> {
+    /**
+     * Prunes expired rows, then inserts a `started` row if there is room: fewer
+     * than `perCaller` unexpired rows with the same `callerHash`, and the store's
+     * own total below its capacity. False when either limit is reached.
+     * `callerHash` is a digest of the caller's address, null when the request
+     * carried none; null callers share one bucket.
+     */
+    admit(row: {
+        id: string;
+        challenge: string;
+        browserHash: string;
+        stateHash: string;
+        callerHash: string | null;
+    }, limits: {
+        perCaller: number;
+    }): Promise<boolean>;
+    transaction<T>(fn: (tx: Tx) => Promise<T>): Promise<T>;
+    /** The row, locked until the transaction ends (`SELECT ... FOR UPDATE`). A second caller waits for the first to finish. */
+    lock(tx: Tx, id: string): Promise<DesktopHandoffFound | undefined>;
+    /** The row without a lock, for a page that only shows it. */
+    read(id: string): Promise<DesktopHandoffFound | undefined>;
+    patch(tx: Tx, id: string, set: Partial<DesktopHandoffRow>): Promise<void>;
+    /** Deletes the row: a sign-in that ended holds no payload, email or subject, and frees its slot. */
+    remove(tx: Tx, id: string): Promise<void>;
+    /** Stamps a redeem attempt, which `pollOk` reads. */
+    polled(tx: Tx, id: string): Promise<void>;
+}
+/**
+ * One process only. For tests and a single-instance development server: two
+ * replicas with separate memory stores do not share rows.
+ */
+export declare function createMemoryDesktopHandoffStore(options?: {
+    /** At most this many unexpired rows exist at once; a start beyond it is refused. Defaults to 128. */
+    capacity?: number;
+    /** How long a row lives after `admit`. Defaults to 5 minutes. */
+    ttlMs?: number;
+    /** The minimum gap `pollOk` allows between two redeem attempts on the same row. Defaults to 1 second. */
+    pollGapMs?: number;
+}): DesktopHandoffStore;
+/**
+ * What the admission hook answers before a session is handed to the shell.
+ * Boule's and Archon's copies differed here: Boule handed over whoever the
+ * issuer signed in, unchanged; Archon asked a further question first --
+ * organisation membership, a second factor, a link to another principal --
+ * and refused otherwise. Archon's is the stricter of the two, so it is the
+ * one this handler keeps a hook for; the default (`alwaysAdmit`) reproduces
+ * Boule's own behaviour for an app that has nothing further to check.
+ */
+export type DesktopHandoffAdmit = (user: User) => Promise<{
+    ok: true;
+    user: {
+        id: string;
+    };
+} | {
+    ok: false;
+    reason: string;
+}>;
+export interface DesktopHandoffCurrent {
+    id: string;
+    status: DesktopHandoffStatus | 'gone';
+    email: string | null;
+    revision: string | null;
+    code: string | null;
+    /**
+     * `${scheme}://auth/done?id=<id>`, once the sign-in is approved; null
+     * otherwise. Built only from this handler's own configured `scheme` --
+     * never from the request -- so a shell can only ever be handed back its
+     * own scheme.
+     */
+    returnUrl: string | null;
+}
+export interface DesktopHandoffConfig<Tx = unknown> {
+    /** The SDK instance the browser side signs in with: a second `createAuth`, its `basePath` moved to `/auth/desktop`, registered at the issuer next to the app's own callback. */
+    auth: DesktopHandoffAuth;
+    /** The app's own origin. */
+    appUrl: string;
+    /** The app's cookie secret. The handoff payload is sealed with a key derived from it, so no secret of its own is needed. */
+    secret: string;
+    /** Names this app in the browser-binding cookie (`<appId>_desktop`); lowercase letters, digits and hyphens, starting with a letter. */
+    appId: string;
+    /** The shell's own return scheme (`cookieHandoff({ scheme })` in `@wtfalch/desktop`, or a mobile shell's own); lowercase letters, digits, `+`, `.` and `-`, starting with a letter. The app's config, never the request, decides this. */
+    scheme: string;
+    store: DesktopHandoffStore<Tx>;
+    /**
+     * Defaults to `alwaysAdmit`, which admits whoever the issuer signed in,
+     * unchanged (Boule's own behaviour). That is fail-open: an app that needs an
+     * organisation, second-factor or linked-principal check and leaves this out
+     * is not warned by the type system. Pass the check explicitly.
+     */
+    admit?: DesktopHandoffAdmit;
+    /**
+     * Called when a step fails for a reason the handler did not expect (a store or
+     * issuer outage, a bug), where the browser sees only `unavailable`. It gets a
+     * fixed step name, the reason shown to the caller and the error's class name:
+     * never the error message, a cookie, a verifier or a payload. Log it and alert on it.
+     */
+    onError?: (event: DesktopHandoffErrorEvent) => void;
+    /** The request header that carries the caller's address, set by the trusted ingress. Defaults to `cf-connecting-ip`. */
+    clientAddressHeader?: string;
+    /** At most this many open sign-ins per caller address; the store's capacity stays the ceiling. Defaults to 8. */
+    maxStartsPerCaller?: number;
+}
+export interface DesktopHandoffErrorEvent {
+    step: 'start' | 'callback' | 'approve' | 'cancel' | 'redeem';
+    reason: string;
+    errorName: string;
+}
+export declare function createDesktopHandoff<Tx = unknown>({ auth, appUrl, secret, appId, scheme, store, admit, onError, clientAddressHeader, maxStartsPerCaller, }: DesktopHandoffConfig<Tx>): {
+    /** The cookie name, for the one place a test or a route needs to read it. */
+    cookieName: string;
+    /** GET /auth/desktop/start */
+    start: (request: Request) => Promise<Response>;
+    /** GET /auth/desktop/callback: where the issuer sends the browser. Sets no session cookie. */
+    callback: (request: Request) => Promise<Response>;
+    /**
+     * What the confirm and done pages show, for the browser that holds the cookie; null for any
+     * other. A row that is gone (redeemed or cancelled rows are deleted) answers `gone` to the
+     * browser that held its binding, which is how the done page still says the app is signed in.
+     */
+    current(cookieHeader: string | null): Promise<DesktopHandoffCurrent | null>;
+    /** POST /auth/desktop/approve: the person confirms the account the page showed. */
+    approve: (request: Request) => Promise<Response>;
+    /** POST /auth/desktop/cancel: ends the sign-in and deletes its row. */
+    cancel: (request: Request) => Promise<Response>;
+    /** POST /auth/desktop/redeem, with the body still unread: refuses one that is not small and declared. */
+    redeemRequest(request: Request): Promise<Response>;
+    /** The shell trades its verifier for the cookie, once. No browser cookie involved. */
+    redeem(input: unknown): Promise<Response>;
+};