@wtfalch/auth 0.32.0 → 0.34.0

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>;
 };