@wtfalch/auth 0.32.0 → 0.33.0

package/dist/desktop-store-postgres.js

@@ -0,0 +1,133 @@
+/**
+ * The table, for a new app to run once in its migrations. Boule's and
+ * Archon's tables are this table already, except that Archon's lacks
+ * `caller_hash` (`ALTER TABLE desktop_handoffs ADD COLUMN IF NOT EXISTS
+ * caller_hash text`).
+ *
+ * The CHECK on `payload` keeps a sealed cookie from outliving `completed` and
+ * `approved`, so a cancelled, redeemed or abandoned row never holds a
+ * credential. The runtime role needs SELECT, INSERT, UPDATE and DELETE.
+ */
+export const DESKTOP_HANDOFFS_TABLE_SQL = `CREATE TABLE IF NOT EXISTS desktop_handoffs (
+  id            uuid PRIMARY KEY,
+  challenge     text NOT NULL CHECK (length(challenge) = 43),
+  browser_hash  text,
+  state_hash    text,
+  caller_hash   text,
+  status        text NOT NULL CHECK (status IN ('started', 'completed', 'approved', 'cancelled', 'redeemed')),
+  payload       text,
+  subject       text,
+  email         text,
+  revision      uuid,
+  created_at    timestamptz NOT NULL DEFAULT clock_timestamp(),
+  expires_at    timestamptz NOT NULL DEFAULT clock_timestamp() + interval '5 minutes',
+  last_poll     timestamptz,
+  CONSTRAINT desktop_handoffs_payload_check
+    CHECK ((status IN ('completed', 'approved')) = (payload IS NOT NULL))
+);
+
+CREATE INDEX IF NOT EXISTS desktop_handoffs_expires_at_idx ON desktop_handoffs (expires_at);
+`;
+/** The key Boule's and Archon's own stores took, so an app mid-cutover still serialises against its old build. */
+const ADMIT_LOCK = 7400194;
+const COLUMNS = `id, status, challenge, browser_hash, state_hash, payload, subject, email, revision,
+  expires_at > clock_timestamp() AS live`;
+const positive = (name, value) => {
+    if (!Number.isFinite(value) || value < 1)
+        throw new Error(`createPostgresDesktopHandoffStore: ${name} must be a positive number`);
+    return value;
+};
+const text = (value) => (typeof value === 'string' ? value : null);
+/**
+ * The row as the handler's types promise it. A row the handler never writes (a
+ * status outside the three, or a result missing from a `completed` row) is
+ * refused by name; no column value goes into the message.
+ */
+function found(record) {
+    if (!record)
+        return undefined;
+    const id = text(record.id);
+    const challenge = text(record.challenge);
+    const browserHash = text(record.browser_hash);
+    const stateHash = text(record.state_hash);
+    if (id === null || challenge === null || browserHash === null || stateHash === null)
+        throw new Error('desktop_handoffs row is missing a column the handler writes at start');
+    const base = { id, challenge, browserHash, stateHash };
+    const status = record.status;
+    let row;
+    if (status === 'started') {
+        row = { ...base, status, payload: null, subject: null, email: null, revision: null };
+    }
+    else if (status === 'completed' || status === 'approved') {
+        const payload = text(record.payload);
+        const subject = text(record.subject);
+        const revision = text(record.revision);
+        if (payload === null || subject === null || revision === null)
+            throw new Error('desktop_handoffs row has no result for its status');
+        row = { ...base, status, payload, subject, email: text(record.email), revision };
+    }
+    else {
+        throw new Error('desktop_handoffs row has a status the handler does not write');
+    }
+    return { row, live: record.live === true };
+}
+/**
+ * Prunes, counts and inserts under one advisory lock, so two starts cannot both
+ * take the last slot of the total or of a caller's bucket. `lock` is
+ * `SELECT ... FOR UPDATE`, held to the end of the transaction; `live` and the
+ * poll gap come from the database's clock, read after any wait for a lock.
+ */
+export function createPostgresDesktopHandoffStore(client, options = {}) {
+    const capacity = positive('capacity', options.capacity ?? 128);
+    const ttlMs = positive('ttlMs', options.ttlMs ?? 5 * 60 * 1000);
+    const pollGapMs = options.pollGapMs ?? 1000;
+    if (!Number.isFinite(pollGapMs))
+        throw new Error('createPostgresDesktopHandoffStore: pollGapMs must be a number');
+    /** `tx` is what `client.transaction` handed `fn`, passed back through the handler. */
+    const run = (tx, sql, values) => tx.query(sql, values);
+    return {
+        admit: (row, limits) => client.transaction(async (tx) => {
+            await tx.query('SELECT pg_advisory_xact_lock($1)', [ADMIT_LOCK]);
+            await tx.query('DELETE FROM desktop_handoffs WHERE expires_at <= clock_timestamp()', []);
+            const [counts] = await tx.query(`SELECT count(*)::int AS live,
+                  (count(*) FILTER (WHERE caller_hash IS NOT DISTINCT FROM $1))::int AS mine
+             FROM desktop_handoffs`, [row.callerHash]);
+            if (Number(counts?.live) >= capacity || Number(counts?.mine) >= limits.perCaller)
+                return false;
+            await tx.query(`INSERT INTO desktop_handoffs
+             (id, challenge, browser_hash, state_hash, caller_hash, status, expires_at)
+           VALUES ($1, $2, $3, $4, $5, 'started', clock_timestamp() + $6 * interval '1 millisecond')`, [row.id, row.challenge, row.browserHash, row.stateHash, row.callerHash, ttlMs]);
+            return true;
+        }),
+        transaction: (fn) => client.transaction((tx) => fn(tx)),
+        async lock(tx, id) {
+            const [record] = await run(tx, `SELECT ${COLUMNS} FROM desktop_handoffs WHERE id = $1 FOR UPDATE`, [id]);
+            return found(record);
+        },
+        async read(id) {
+            const [record] = await client.query(`SELECT ${COLUMNS} FROM desktop_handoffs WHERE id = $1`, [
+                id,
+            ]);
+            return found(record);
+        },
+        async patch(tx, id, set) {
+            if (set.status === 'approved') {
+                await run(tx, 'UPDATE desktop_handoffs SET status = $2 WHERE id = $1', [id, set.status]);
+                return;
+            }
+            await run(tx, `UPDATE desktop_handoffs
+            SET status = $2, payload = $3, subject = $4, email = $5, revision = $6
+          WHERE id = $1`, [id, set.status, set.payload, set.subject, set.email, set.revision]);
+        },
+        async remove(tx, id) {
+            await run(tx, 'DELETE FROM desktop_handoffs WHERE id = $1', [id]);
+        },
+        async stampPoll(tx, id) {
+            const stamped = await run(tx, `UPDATE desktop_handoffs SET last_poll = clock_timestamp()
+          WHERE id = $1
+            AND (last_poll IS NULL OR last_poll < clock_timestamp() - $2 * interval '1 millisecond')
+        RETURNING id`, [id, pollGapMs]);
+            return stamped.length === 1;
+        },
+    };
+}

package/dist/desktop-store.d.ts

@@ -0,0 +1,130 @@
+export type DesktopHandoffStatus = 'started' | 'completed' | 'approved';
+interface DesktopHandoffBase {
+    id: string;
+    challenge: string;
+    /** Digest of the browser nonce; `admit` always writes it. */
+    browserHash: string;
+    /** Digest of the issuer `state`; `admit` always writes it. */
+    stateHash: string;
+}
+/**
+ * A row by its status. `started` holds no result yet; `completed` and
+ * `approved` hold the sealed session cookie and who it is for, so reading
+ * `status` proves the fields.
+ */
+export type DesktopHandoffRow = (DesktopHandoffBase & {
+    status: 'started';
+    payload: null;
+    subject: null;
+    email: null;
+    revision: null;
+}) | (DesktopHandoffBase & {
+    status: 'completed' | 'approved';
+    payload: string;
+    subject: string;
+    email: string | null;
+    revision: string;
+});
+/** What `patch` writes: the callback's result, or the person's confirmation. */
+export type DesktopHandoffPatch = {
+    status: 'completed';
+    payload: string;
+    subject: string;
+    email: string | null;
+    revision: string;
+} | {
+    status: 'approved';
+};
+export interface DesktopHandoffFound {
+    row: DesktopHandoffRow;
+    /** The store's own clock decides this, read after any wait for a lock. */
+    live: boolean;
+}
+/**
+ * What `transaction` hands its function, and the other methods take back. It
+ * is the store's own and opaque to the handler.
+ */
+export type DesktopHandoffTx = object;
+/**
+ * The handoff's row store. `createPostgresDesktopHandoffStore` is the shared
+ * one over Postgres; `createMemoryDesktopHandoffStore` serves one process. An
+ * app with another database implements this interface over its own table.
+ *
+ * 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.
+ *
+ * `admit` carries the per-caller cap the same way (see its contract). Run
+ * `checkDesktopHandoffStore` against any store in its tests.
+ */
+export interface DesktopHandoffStore {
+    /**
+     * Prunes expired rows, then inserts a `started` row if there is room, and
+     * answers whether it did. The contract, which the handler relies on and
+     * cannot check (`checkDesktopHandoffStore` does):
+     *
+     * - Per-caller cap: it inserts only when fewer than `limits.perCaller`
+     *   unexpired rows already carry the same `callerHash`. `callerHash` is a
+     *   digest of the caller's address, null when the request carried none; null
+     *   callers share one bucket. The cap is what stops one address filling the
+     *   store (the unauthenticated `/start` is otherwise a capacity DoS), so a
+     *   store that ignores `limits` fails open.
+     * - Total capacity: it refuses when the store's own total of unexpired rows
+     *   is at its capacity, whoever asks.
+     * - Atomic: the count and the insert are one step. In SQL that is one
+     *   transaction that first takes a lock that serialises admissions (for
+     *   example `SELECT ... FOR UPDATE` on the rows of this `callerHash`, or an
+     *   advisory lock), so two concurrent starts cannot both pass at
+     *   `perCaller - 1`.
+     * - False means refused; it never throws for a full store.
+     */
+    admit(row: {
+        id: string;
+        challenge: string;
+        browserHash: string;
+        stateHash: string;
+        callerHash: string | null;
+    }, limits: {
+        perCaller: number;
+    }): Promise<boolean>;
+    /**
+     * Runs `fn` in one database transaction: it commits when `fn` returns and
+     * rolls back when `fn` throws. The handler depends on both halves. A redeem
+     * that refuses after stamping the attempt (`stampPoll`) or deleting an expired
+     * row RETURNS its error from `fn` instead of throwing, so the stamp and the
+     * delete commit; the handler throws it only after the transaction ended. A
+     * store that commits on a throw loses nothing but lets a half-done step
+     * persist; a store that rolls back on a return lets a guesser skip the
+     * one-a-second limit. (The memory store has no rollback: its writes apply at
+     * once, which is why the handler never relies on one.)
+     */
+    transaction<T>(fn: (tx: DesktopHandoffTx) => 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: DesktopHandoffTx, 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: DesktopHandoffTx, id: string, set: DesktopHandoffPatch): Promise<void>;
+    /** Deletes the row: a sign-in that ended holds no payload, email or subject, and frees its slot. */
+    remove(tx: DesktopHandoffTx, id: string): Promise<void>;
+    /**
+     * Stamps a redeem attempt if the last one is at least the store's poll gap
+     * (one second) old, by the store's own clock, and answers whether it did.
+     * False means too soon: nothing was written.
+     */
+    stampPoll(tx: DesktopHandoffTx, id: string): Promise<boolean>;
+}
+/**
+ * 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 `stampPoll` allows between two redeem attempts on the same row. Defaults to 1 second. */
+    pollGapMs?: number;
+}): DesktopHandoffStore;
+export {};

package/dist/desktop-store.js

@@ -0,0 +1,111 @@
+/*
+ * The handoff's row store: the interface a store implements over a table, and a
+ * memory implementation for one process. `createPostgresDesktopHandoffStore`
+ * (desktop-store-postgres.ts) is the shared Postgres one.
+ * `checkDesktopHandoffStore` (desktop-store-contract.ts) runs the contract below
+ * against any store.
+ */
+/**
+ * One process only. For tests and a single-instance development server: two
+ * replicas with separate memory stores do not share rows.
+ */
+export function createMemoryDesktopHandoffStore(options) {
+    const capacity = options?.capacity ?? 128;
+    const ttlMs = options?.ttlMs ?? 5 * 60 * 1000;
+    const pollGapMs = options?.pollGapMs ?? 1000;
+    const rows = new Map();
+    /** Per row id, the end of the line of transactions waiting for it. */
+    const lineEnds = new Map();
+    async function acquire(tx, id) {
+        if (tx.held.has(id))
+            return;
+        const before = lineEnds.get(id) ?? Promise.resolve();
+        let release;
+        const turn = new Promise((resolve) => {
+            release = resolve;
+        });
+        const end = before.then(() => turn);
+        lineEnds.set(id, end);
+        await before;
+        tx.held.set(id, () => {
+            if (lineEnds.get(id) === end)
+                lineEnds.delete(id);
+            release();
+        });
+    }
+    const sweep = () => {
+        const now = Date.now();
+        for (const [id, entry] of rows)
+            if (entry.expiresAt <= now)
+                rows.delete(id);
+    };
+    const found = (entry) => {
+        const { expiresAt, lastPoll: _poll, callerHash: _caller, ...row } = entry;
+        return { row, live: expiresAt > Date.now() };
+    };
+    return {
+        async admit(row, limits) {
+            sweep();
+            if (rows.size >= capacity)
+                return false;
+            let mine = 0;
+            for (const entry of rows.values())
+                if (entry.callerHash === row.callerHash)
+                    mine++;
+            if (mine >= limits.perCaller)
+                return false;
+            rows.set(row.id, {
+                id: row.id,
+                status: 'started',
+                challenge: row.challenge,
+                browserHash: row.browserHash,
+                stateHash: row.stateHash,
+                payload: null,
+                subject: null,
+                email: null,
+                revision: null,
+                expiresAt: Date.now() + ttlMs,
+                lastPoll: null,
+                callerHash: row.callerHash,
+            });
+            return true;
+        },
+        async transaction(fn) {
+            const tx = { held: new Map() };
+            try {
+                return await fn(tx);
+            }
+            finally {
+                for (const release of tx.held.values())
+                    release();
+            }
+        },
+        async lock(tx, id) {
+            await acquire(tx, id);
+            const entry = rows.get(id);
+            return entry ? found(entry) : undefined;
+        },
+        async read(id) {
+            const entry = rows.get(id);
+            return entry ? found(entry) : undefined;
+        },
+        async patch(_tx, id, set) {
+            const entry = rows.get(id);
+            if (entry)
+                Object.assign(entry, set);
+        },
+        async remove(_tx, id) {
+            rows.delete(id);
+        },
+        async stampPoll(_tx, id) {
+            const entry = rows.get(id);
+            if (!entry)
+                return false;
+            const now = Date.now();
+            if (entry.lastPoll !== null && entry.lastPoll >= now - pollGapMs)
+                return false;
+            entry.lastPoll = now;
+            return true;
+        },
+    };
+}

package/dist/desktop.d.ts

@@ -1,4 +1,8 @@
 import type { Auth, User } from './auth.js';
+import type { DesktopHandoffStatus, DesktopHandoffStore } from './desktop-store.js';
+export { type DesktopHandoffFound, type DesktopHandoffPatch, type DesktopHandoffRow, type DesktopHandoffStatus, type DesktopHandoffStore, type DesktopHandoffTx, createMemoryDesktopHandoffStore, } from './desktop-store.js';
+export { DESKTOP_HANDOFFS_TABLE_SQL, type DesktopHandoffQuery, type DesktopHandoffSqlClient, type PostgresDesktopHandoffStoreOptions, createPostgresDesktopHandoffStore, } from './desktop-store-postgres.js';
+export { checkDesktopHandoffStore } from './desktop-store-contract.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
@@ -29,8 +33,9 @@ import type { Auth, User } from './auth.js';
  *
  * 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.
+ * server and for tests; a multi-replica app passes its Postgres client to
+ * `createPostgresDesktopHandoffStore` over the table it migrates
+ * (`DESKTOP_HANDOFFS_TABLE_SQL`).
  */
 export type DesktopHandoffAuth = Pick<Auth, 'sessionCookieName' | 'start' | 'complete' | 'readCookie'>;
 export declare class DesktopHandoffError extends Error {
@@ -38,75 +43,6 @@ export declare class DesktopHandoffError extends Error {
     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
@@ -139,7 +75,7 @@ export interface DesktopHandoffCurrent {
      */
     returnUrl: string | null;
 }
-export interface DesktopHandoffConfig<Tx = unknown> {
+export interface DesktopHandoffConfig {
     /** 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. */
@@ -150,7 +86,7 @@ export interface DesktopHandoffConfig<Tx = unknown> {
     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>;
+    store: DesktopHandoffStore;
     /**
      * Defaults to `alwaysAdmit`, which admits whoever the issuer signed in,
      * unchanged (Boule's own behaviour). That is fail-open: an app that needs an
@@ -175,7 +111,7 @@ export interface DesktopHandoffErrorEvent {
     reason: string;
     errorName: string;
 }
-export declare function createDesktopHandoff<Tx = unknown>({ auth, appUrl, secret, appId, scheme, store, admit, onError, clientAddressHeader, maxStartsPerCaller, }: DesktopHandoffConfig<Tx>): {
+export declare function createDesktopHandoff({ auth, appUrl, secret, appId, scheme, store, admit, onError, clientAddressHeader, maxStartsPerCaller, }: DesktopHandoffConfig): {
     /** The cookie name, for the one place a test or a route needs to read it. */
     cookieName: string;
     /** GET /auth/desktop/start */
@@ -194,6 +130,5 @@ export declare function createDesktopHandoff<Tx = unknown>({ auth, appUrl, secre
     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>;
+    redeem: (input: unknown) => Promise<Response>;
 };