@wtfalch/auth 0.32.0 → 0.34.0

package/dist/cookies.d.ts

@@ -19,6 +19,10 @@ export interface TransactionPayload extends JWTPayload {
     nx: string;
     /** The leg was a silent pass (`prompt=none`): an error coming back falls back to interactive sign-in. */
     sl?: true;
+    /** A fresh sign-in started by `startFreshSignIn`: the auth request this transaction belongs to. */
+    ar?: string;
+    /** The passkey challenge's session id, set by `startFreshPasskey`. */
+    fp?: string;
 }
 export interface CookieAttributes {
     path: '/';
@@ -78,6 +82,9 @@ export declare function linkCookieName(options: ResolvedOptions): string;
 export declare function sealLink(options: ResolvedOptions, payload: Omit<LinkPayload, keyof JWTPayload>): Promise<SetCookie>;
 export declare function openLink(options: ResolvedOptions, value: string | undefined): Promise<LinkPayload | null>;
 export declare function clearLink(options: ResolvedOptions): SetCookie;
+/** The header that makes the browser drop the cookie `name`. */
+export declare function clearCookie(name: string, secure: boolean): SetCookie;
+/** Builds the header. A `maxAge` of 0 or less is the clearing form; callers clear through `clearCookie`. */
 export declare function setCookie(name: string, value: string, maxAge: number, secure: boolean): SetCookie;
 export declare function cookieFrom(header: string | null, name: string): string | undefined;
 /** The Cookie header with these cookies replaced or removed, for a proxy to forward. */

package/dist/cookies.js

@@ -51,7 +51,7 @@ export async function openSession(options, value) {
     return payload && typeof payload.idt === 'string' ? payload : null;
 }
 export function clearSession(options) {
-    return setCookie(sessionCookieName(options), '', 0, options.secure);
+    return clearCookie(sessionCookieName(options), options.secure);
 }
 /** The namespace session cookie: a random handle to a server record, nothing else. */
 export async function sealHandle(options, sid) {
@@ -96,7 +96,7 @@ export async function openTransaction(options, value) {
         : null;
 }
 export function clearTransaction(options) {
-    return setCookie(transactionCookieName(options), '', 0, options.secure);
+    return clearCookie(transactionCookieName(options), options.secure);
 }
 export function silentCookieName(options) {
     return options.secure ? `__Host-${SILENT}` : SILENT;
@@ -126,7 +126,7 @@ export async function openQrTransaction(options, value) {
     return payload && typeof payload.dc === 'string' ? payload : null;
 }
 export function clearQrTransaction(options) {
-    return setCookie(qrTransactionCookieName(options), '', 0, options.secure);
+    return clearCookie(qrTransactionCookieName(options), options.secure);
 }
 export function linkCookieName(options) {
     return options.secure ? `__Host-${LINK}` : LINK;
@@ -145,7 +145,7 @@ export async function openLink(options, value) {
         : null;
 }
 export function clearLink(options) {
-    return setCookie(linkCookieName(options), '', 0, options.secure);
+    return clearCookie(linkCookieName(options), options.secure);
 }
 // A different audience also prevents old static consumers from accepting a
 // namespace cookie. Hashing keeps the encrypted session below browser limits.
@@ -186,6 +186,11 @@ async function open(options, kind, value) {
         return null;
     }
 }
+/** The header that makes the browser drop the cookie `name`. */
+export function clearCookie(name, secure) {
+    return setCookie(name, '', 0, secure);
+}
+/** Builds the header. A `maxAge` of 0 or less is the clearing form; callers clear through `clearCookie`. */
 export function setCookie(name, value, maxAge, secure) {
     const parts = [`${name}=${value}`, 'Path=/', 'HttpOnly', 'SameSite=Lax'];
     if (maxAge > 0) {

package/dist/desktop-crypto.d.ts

@@ -0,0 +1,26 @@
+export declare const newNonce: () => string;
+export declare function same(a: string, b: string): boolean;
+/**
+ * The key that seals a payload, derived from the cookie secret the app
+ * already holds, so no new secret exists. The fixed label keeps it apart
+ * from every other use of that secret. It is not the label Boule and Archon
+ * used (`boule-desktop-handoff`, `archon-desktop-handoff`): a row sealed under
+ * the old label fails to open here, so a sign-in in flight when an app cuts
+ * over to this handler ends in `payload_invalid`. The window is the row's
+ * lifetime, five minutes.
+ */
+export declare function sealKey(secret: string): Buffer;
+/** AES-256-GCM. `aad` is authenticated, not secret: it ties the ciphertext to one row and one origin. */
+export declare function seal(key: Buffer, aad: string, plaintext: string): string;
+/** Throws when the ciphertext, the tag or the `aad` is not what `seal` was given. */
+export declare function open(key: Buffer, aad: string, sealed: string): string;
+/**
+ * The code the browser and the shell each derive from the challenge, so the
+ * person can see both belong to one sign-in: the first 30 bits of
+ * sha256("boule-desktop-pair:" + challenge), 5 bits each, shown as `ABC-DEF`.
+ * The label is fixed text, not this app's id: it is shared with
+ * `@wtfalch/desktop`'s `login.mjs`, which derives the same code
+ * independently of which app it is signing into. Changing it breaks pairing
+ * for every shell already built against it.
+ */
+export declare function pairingCode(challenge: string): string;

package/dist/desktop-crypto.js

@@ -0,0 +1,62 @@
+import { createCipheriv, createDecipheriv, createHash, hkdfSync, randomBytes, timingSafeEqual, } from 'node:crypto';
+/*
+ * The handoff's crypto, apart from its store and its handler. It uses
+ * `node:crypto` on purpose: the sealed payload's format (`iv|tag|ciphertext`,
+ * AES-256-GCM) is what rows already in an app's store hold, and `cookies.ts`'s
+ * jose sealing is another format. Only the `./desktop`
+ * entry imports this file, so the root entry stays free of `node:crypto`.
+ */
+export const newNonce = () => randomBytes(32).toString('base64url');
+export function same(a, b) {
+    const x = Buffer.from(a);
+    const y = Buffer.from(b);
+    return x.length === y.length && timingSafeEqual(x, y);
+}
+/**
+ * The key that seals a payload, derived from the cookie secret the app
+ * already holds, so no new secret exists. The fixed label keeps it apart
+ * from every other use of that secret. It is not the label Boule and Archon
+ * used (`boule-desktop-handoff`, `archon-desktop-handoff`): a row sealed under
+ * the old label fails to open here, so a sign-in in flight when an app cuts
+ * over to this handler ends in `payload_invalid`. The window is the row's
+ * lifetime, five minutes.
+ */
+export function sealKey(secret) {
+    return Buffer.from(hkdfSync('sha256', secret, Buffer.alloc(0), 'wtfalch-auth-desktop-handoff', 32));
+}
+/** AES-256-GCM. `aad` is authenticated, not secret: it ties the ciphertext to one row and one origin. */
+export function seal(key, aad, plaintext) {
+    const iv = randomBytes(12);
+    const cipher = createCipheriv('aes-256-gcm', key, iv);
+    cipher.setAAD(Buffer.from(aad));
+    const data = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    return Buffer.concat([iv, cipher.getAuthTag(), data]).toString('base64url');
+}
+/** Throws when the ciphertext, the tag or the `aad` is not what `seal` was given. */
+export function open(key, aad, sealed) {
+    const data = Buffer.from(sealed, 'base64url');
+    const decipher = createDecipheriv('aes-256-gcm', key, data.subarray(0, 12));
+    decipher.setAAD(Buffer.from(aad));
+    decipher.setAuthTag(data.subarray(12, 28));
+    return Buffer.concat([decipher.update(data.subarray(28)), decipher.final()]).toString('utf8');
+}
+const CROCKFORD = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+/**
+ * The code the browser and the shell each derive from the challenge, so the
+ * person can see both belong to one sign-in: the first 30 bits of
+ * sha256("boule-desktop-pair:" + challenge), 5 bits each, shown as `ABC-DEF`.
+ * The label is fixed text, not this app's id: it is shared with
+ * `@wtfalch/desktop`'s `login.mjs`, which derives the same code
+ * independently of which app it is signing into. Changing it breaks pairing
+ * for every shell already built against it.
+ */
+export function pairingCode(challenge) {
+    const bits = createHash('sha256')
+        .update(`boule-desktop-pair:${challenge}`)
+        .digest()
+        .readUInt32BE(0);
+    let code = '';
+    for (let i = 0; i < 6; i++)
+        code += CROCKFORD[(bits >>> (27 - 5 * i)) & 31];
+    return `${code.slice(0, 3)}-${code.slice(3)}`;
+}

package/dist/desktop-store-contract.d.ts

@@ -0,0 +1,13 @@
+import type { DesktopHandoffStore } from './desktop-store.js';
+/**
+ * Checks a `DesktopHandoffStore` against the contract the handler relies on and
+ * cannot check itself: `admit`'s per-caller cap, `lock`'s exclusivity, the
+ * one-a-second `stampPoll` and a row's round trip through `patch` and
+ * `remove`. Run it against any store, the Postgres one included, with a
+ * function that makes a fresh store over an empty table (a store with
+ * `capacity` of at least 4 rows and the default poll gap). It throws an Error
+ * naming the broken rule, and uses no test framework.
+ *
+ * It does not check the store's total capacity, which is the store's own.
+ */
+export declare function checkDesktopHandoffStore(create: () => DesktopHandoffStore | Promise<DesktopHandoffStore>): Promise<void>;

package/dist/desktop-store-contract.js

@@ -0,0 +1,106 @@
+/**
+ * Checks a `DesktopHandoffStore` against the contract the handler relies on and
+ * cannot check itself: `admit`'s per-caller cap, `lock`'s exclusivity, the
+ * one-a-second `stampPoll` and a row's round trip through `patch` and
+ * `remove`. Run it against any store, the Postgres one included, with a
+ * function that makes a fresh store over an empty table (a store with
+ * `capacity` of at least 4 rows and the default poll gap). It throws an Error
+ * naming the broken rule, and uses no test framework.
+ *
+ * It does not check the store's total capacity, which is the store's own.
+ */
+export async function checkDesktopHandoffStore(create) {
+    const ensure = (ok, rule) => {
+        if (!ok)
+            throw new Error(`DesktopHandoffStore contract broken: ${rule}`);
+    };
+    let n = 0;
+    const row = (callerHash) => {
+        n += 1;
+        const id = `00000000-0000-4000-8000-${String(n).padStart(12, '0')}`;
+        return {
+            id,
+            challenge: `c${n}`.padEnd(43, 'x'),
+            browserHash: `b${n}`,
+            stateHash: `s${n}`,
+            callerHash,
+        };
+    };
+    // admit: the cap is per caller, and callers with no address share one bucket.
+    const capped = await create();
+    const limits = { perCaller: 2 };
+    ensure(await capped.admit(row('a'), limits), 'admit refused the first start of a caller');
+    ensure(await capped.admit(row('a'), limits), 'admit refused a start below perCaller');
+    ensure(!(await capped.admit(row('a'), limits)), 'admit ignored the per-caller cap');
+    ensure(await capped.admit(row('b'), limits), 'admit let one caller fill the store for another');
+    ensure(await capped.admit(row(null), limits), 'admit refused the first start with no address');
+    ensure(await capped.admit(row(null), limits), 'admit refused a null-caller start below perCaller');
+    ensure(!(await capped.admit(row(null), limits)), 'null callers do not share one bucket');
+    // admit: a removed row frees its slot.
+    const mine = row('c');
+    const slots = await create();
+    ensure(await slots.admit(mine, { perCaller: 1 }), 'admit refused a first start');
+    ensure(!(await slots.admit(row('c'), { perCaller: 1 })), 'admit ignored a cap of 1');
+    await slots.transaction((tx) => slots.remove(tx, mine.id));
+    ensure(await slots.admit(row('c'), { perCaller: 1 }), 'remove did not free the caller slot');
+    // lock: a second caller waits until the first transaction ends.
+    const locked = await create();
+    const target = row('d');
+    ensure(await locked.admit(target, { perCaller: 8 }), 'admit refused a first start');
+    const order = [];
+    let holding;
+    const held = new Promise((resolve) => {
+        holding = resolve;
+    });
+    const first = locked.transaction(async (tx) => {
+        ensure((await locked.lock(tx, target.id)) !== undefined, 'lock did not find the row');
+        holding();
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        order.push('first ends');
+    });
+    await held;
+    const second = locked.transaction(async (tx) => {
+        await locked.lock(tx, target.id);
+        order.push('second locked');
+    });
+    await Promise.all([first, second]);
+    ensure(order.join() === 'first ends,second locked', 'lock is not exclusive: a second caller got the row while the first transaction was open');
+    // stampPoll: one stamp a gap, answered true then false.
+    const polled = await create();
+    const stamped = row('e');
+    ensure(await polled.admit(stamped, { perCaller: 8 }), 'admit refused a first start');
+    const stamps = await polled.transaction(async (tx) => [
+        await polled.stampPoll(tx, stamped.id),
+        await polled.stampPoll(tx, stamped.id),
+    ]);
+    ensure(stamps[0] === true, 'stampPoll refused the first attempt on a row');
+    ensure(stamps[1] === false, 'stampPoll allowed a second attempt inside the gap');
+    // patch and read: a row keeps what was written and reads back as its status says.
+    const patched = await create();
+    const target2 = row('f');
+    ensure(await patched.admit(target2, { perCaller: 8 }), 'admit refused a first start');
+    const started = await patched.read(target2.id);
+    ensure(started?.row.status === 'started' && started.row.payload === null && started.live, 'a new row did not read back as a live started row');
+    const revision = '11111111-1111-4111-8111-111111111111';
+    await patched.transaction(async (tx) => {
+        await patched.patch(tx, target2.id, {
+            status: 'completed',
+            payload: 'sealed',
+            subject: 'user-1',
+            email: null,
+            revision,
+        });
+        await patched.patch(tx, target2.id, { status: 'approved' });
+    });
+    const approved = (await patched.read(target2.id))?.row;
+    ensure(approved?.status === 'approved' &&
+        approved.payload === 'sealed' &&
+        approved.subject === 'user-1' &&
+        approved.email === null &&
+        approved.revision === revision &&
+        approved.challenge === target2.challenge &&
+        approved.browserHash === target2.browserHash &&
+        approved.stateHash === target2.stateHash, 'patch did not keep what it wrote');
+    await patched.transaction((tx) => patched.remove(tx, target2.id));
+    ensure((await patched.read(target2.id)) === undefined, 'remove left the row');
+}

package/dist/desktop-store-postgres.d.ts

@@ -0,0 +1,40 @@
+import type { DesktopHandoffStore } from './desktop-store.js';
+/** Runs one statement; `$1`, `$2`... in `text` are `values`. Resolves to the rows, empty for a statement that returns none. */
+export interface DesktopHandoffQuery {
+    query(text: string, values: readonly unknown[]): Promise<readonly Record<string, unknown>[]>;
+}
+/**
+ * What the app gives `createPostgresDesktopHandoffStore`. `transaction` runs
+ * `fn` on one connection inside one transaction: it commits when `fn` returns
+ * and rolls back when `fn` throws. The `tx` it hands over runs its statements
+ * in that transaction.
+ */
+export interface DesktopHandoffSqlClient extends DesktopHandoffQuery {
+    transaction<T>(fn: (tx: DesktopHandoffQuery) => Promise<T>): Promise<T>;
+}
+export interface PostgresDesktopHandoffStoreOptions {
+    /** 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;
+}
+/**
+ * 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 declare const DESKTOP_HANDOFFS_TABLE_SQL = "CREATE TABLE IF NOT EXISTS desktop_handoffs (\n  id            uuid PRIMARY KEY,\n  challenge     text NOT NULL CHECK (length(challenge) = 43),\n  browser_hash  text,\n  state_hash    text,\n  caller_hash   text,\n  status        text NOT NULL CHECK (status IN ('started', 'completed', 'approved', 'cancelled', 'redeemed')),\n  payload       text,\n  subject       text,\n  email         text,\n  revision      uuid,\n  created_at    timestamptz NOT NULL DEFAULT clock_timestamp(),\n  expires_at    timestamptz NOT NULL DEFAULT clock_timestamp() + interval '5 minutes',\n  last_poll     timestamptz,\n  CONSTRAINT desktop_handoffs_payload_check\n    CHECK ((status IN ('completed', 'approved')) = (payload IS NOT NULL))\n);\n\nCREATE INDEX IF NOT EXISTS desktop_handoffs_expires_at_idx ON desktop_handoffs (expires_at);\n";
+/**
+ * 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 declare function createPostgresDesktopHandoffStore(client: DesktopHandoffSqlClient, options?: PostgresDesktopHandoffStoreOptions): DesktopHandoffStore;

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