@wtfalch/auth 0.31.0 → 0.33.0

package/README.md

@@ -293,9 +293,43 @@ at `/auth/desktop/redeem`.
   whoever the issuer signed in, with no further check. It fails open: an app
   that needs an organisation, second-factor or linked-principal check and leaves
   `admit` out gets no warning. Pass the check explicitly.
+- **The store.** A multi-replica app passes its Postgres client to
+  `createPostgresDesktopHandoffStore(client, { capacity, ttlMs, pollGapMs })`
+  and runs `DESKTOP_HANDOFFS_TABLE_SQL` once in a migration. The client is two
+  methods, so any driver fits: `query(text, values)` resolves to the rows, and
+  `transaction(fn)` runs `fn` with the same `query` shape on one connection,
+  committing when `fn` returns and rolling back when it throws. With `pg`:
+
+  ```ts
+  const client: DesktopHandoffSqlClient = {
+    query: async (text, values) => (await pool.query(text, [...values])).rows,
+    async transaction(fn) {
+      const connection = await pool.connect();
+      try {
+        await connection.query('BEGIN');
+        const result = await fn({
+          query: async (text, values) => (await connection.query(text, [...values])).rows,
+        });
+        await connection.query('COMMIT');
+        return result;
+      } catch (error) {
+        await connection.query('ROLLBACK');
+        throw error;
+      } finally {
+        connection.release();
+      }
+    },
+  };
+  ```
+
+  The table is Boule's and Archon's `desktop_handoffs` with a `caller_hash text`
+  column; an app that has the table without it runs
+  `ALTER TABLE desktop_handoffs ADD COLUMN IF NOT EXISTS caller_hash text`. Test
+  any store, this one included, with `checkDesktopHandoffStore`.
 - **The store must lock.** `lock(tx, id)` is `SELECT ... FOR UPDATE` in a real
   store. The memory store locks per row; a store that only reads lets two
-  concurrent redeems both get the cookie.
+  concurrent redeems both get the cookie. `createMemoryDesktopHandoffStore`
+  serves one process only.
 - **Rate-limit `/auth/desktop/start` at the edge too.** The handler caps open
   sign-ins per caller (`maxStartsPerCaller`, default 8, keyed on the address in
   `clientAddressHeader`, default `cf-connecting-ip`) under the store's total
@@ -433,6 +467,74 @@ A phone that is already signed in can also approve a new device from a QR
 code, the issuer's OAuth device grant opted into per namespace binding with
 `qrSignIn: true`, through `startQrSignIn` and `pollQrSignIn`.
 
+## Workspaces for your app's customers
+
+An app with `workspaces` on its entry gets `WORKSPACES_URL`, `WORKSPACES_API_KEY`
+and `AUTH_ORGANIZATION_ID`. `@wtfalch/auth/workspaces` calls the broker with them.
+The app keeps the current workspace id itself; this one holds it in a cookie.
+
+```ts
+import { cookies } from 'next/headers';
+import { workspaces, WorkspacesError } from '@wtfalch/auth/workspaces';
+import { auth } from './auth'; // your createAuth() instance
+
+const ws = workspaces(); // throws at once if an env value is missing
+
+export async function currentWorkspace(request: Request) {
+  const { user } = await auth.read(request);
+  if (!user) return null;
+  const id = (await cookies()).get('workspace')?.value;
+  const role = id ? await ws.access(id, user) : null; // never trust the cookie alone
+  return id && role ? { id, role } : null;
+}
+
+export async function createWorkspace(request: Request, name: string) {
+  const { user } = await auth.read(request);
+  if (!user) throw new Error('Sign in first.');
+  const made = await ws.create({ name, owner: user });
+  (await cookies()).set('workspace', made.id, { httpOnly: true, sameSite: 'lax', secure: true });
+  return made;
+}
+
+export async function inviteBy(request: Request, id: string, email: string) {
+  const { user } = await auth.read(request);
+  if (!user) throw new Error('Sign in first.');
+  try {
+    await ws.invite(id, { email, role: 'member', actor: user }); // the broker mails the link
+  } catch (error) {
+    if (error instanceof WorkspacesError && error.status === 403) return 'Only an owner can invite.';
+    throw error;
+  }
+}
+// On the page behind `inviteUrl?token=`: await ws.accept(token, user) -> { workspaceId, role }
+
+// Any member: who is in the workspace -> [{ sub, email, name, role }] (name is null; email is '' only for a creator from before this existed)
+await ws.members(id, user);
+// Owner only:
+await ws.invitations(id, user); // pending -> [{ id, email, role, createdAt, expiresAt }]
+await ws.revokeInvitation(id, invitationId, user); // the emailed link stops working
+await ws.rename(id, 'New name', user);
+await ws.archive(id, user); // leaves listFor; every later call on it fails with status 410
+```
+
+## Preview routes
+
+For apps on live/idle releases. The balancer sends a request with the `bg_preview=1` cookie to the idle slot, after asking the live slot whether the person may see it.
+
+```ts
+import { createPreviewRoutes } from '@wtfalch/auth';
+
+export const preview = createPreviewRoutes({
+  auth, // the app's own `createAuth(...)` instance
+  mayPreview: (user) => canPreview(user), // `releases:preview` in the app's production authz
+});
+// GET    /api/foundry/preview-check -> preview.check  (200, 401 no session, 403 otherwise)
+// POST   /api/foundry/preview       -> preview.set    (204 and the cookie, same-origin only)
+// DELETE /api/foundry/preview       -> preview.clear  (204, same-origin only, no permission needed)
+```
+
+Answers carry no body and `cache-control: no-store`. A reader or permission check that throws answers 403 and logs one fixed line with the error name only. The session is read through `auth` (without refreshing), and the trusted origin and the cookie's `Secure` rule come from its `appUrl`, never from the request. They are read on the first request, so `next build` importing this module with no environment set does not throw. A request from another origin is refused with 403 and no log line. `PREVIEW_COOKIE`, `PREVIEW_CHECK_PATH` and `PREVIEW_PATH` are exported too.
+
 ## Documentation
 
 `docs/adopting.md` in [wtfalch/auth](https://github.com/wtfalch/auth) covers a

package/dist/auth.d.ts

@@ -195,6 +195,10 @@ export interface QrPollResult {
 }
 export interface Auth {
     readonly sessionCookieName: string;
+    /** The app's own origin, from `appUrl`. Read on first use, so it throws only if `appUrl` is missing or malformed. */
+    readonly appOrigin: string;
+    /** Whether this app's cookies carry `Secure`: true when `appUrl` is https. The same rule the session cookie uses. */
+    readonly cookiesSecure: boolean;
     /** GET {basePath}/start?next=&intent= : begins the OIDC flow; the issuer sends the browser to {basePath}/login?authRequest= */
     start(request: Request): Promise<Response>;
     /** GET {basePath}/callback */

package/dist/auth.js

@@ -1,12 +1,13 @@
 import * as client from 'openid-client';
+import { declaredWithin, readBounded } from './body.js';
 import { Broker, BrokerError } from './broker.js';
 import { resolveOptions, } from './config.js';
 import { clearQrTransaction, clearSession, clearTransaction, cookieFrom, openQrTransaction, openRecord, openSession, openSilent, openTransaction, qrTransactionCookieName, sealQrTransaction, sealSession, sealSilent, sealTransaction, sessionCookieName, silentCookieName, transactionCookieName, } from './cookies.js';
 import { namespaceSessions } from './namespace-session.js';
 import { AuthError, ORG_CLAIM, Oidc, isOAuthRefusal, rejected, scopeFor, } from './oidc.js';
 import { pollDeviceToken, requestDeviceAuthorization } from './qr.js';
-import { safeLoginHint, safeNextPath } from './redirect.js';
-import { expiryOf, issuedAtOf, recheckSeconds, timeoutSignal } from './util.js';
+import { isSameOrigin, safeLoginHint, safeNextPath } from './redirect.js';
+import { NO_STORE, expiryOf, issuedAtOf, recheckSeconds, timeoutSignal } from './util.js';
 export function createAuth(input) {
     // Resolved on first use so `next build`, which imports every route module, needs none of the values set.
     let resolved = null;
@@ -142,11 +143,11 @@ export function createAuth(input) {
         const type = request.headers.get('content-type')?.split(';')[0]?.trim().toLowerCase();
         if (type !== 'application/x-www-form-urlencoded')
             return new Response('Unsupported Media Type', { status: 415 });
-        const length = request.headers.get('content-length');
-        if (length === null || !/^\d{1,9}$/.test(length) || Number(length) > START_BODY_MAX)
+        if (!declaredWithin(request, START_BODY_MAX))
             return new Response('Payload Too Large', { status: 413 });
-        const text = await request.text();
-        if (text.length > START_BODY_MAX)
+        // The declared length is a hint; the read itself stops at the cap.
+        const text = await readBounded(request, START_BODY_MAX);
+        if (text === null)
             return new Response('Payload Too Large', { status: 413 });
         return new URLSearchParams(text);
     };
@@ -1032,6 +1033,12 @@ export function createAuth(input) {
         get sessionCookieName() {
             return sessionCookieName(options());
         },
+        get appOrigin() {
+            return options().appUrl.origin;
+        },
+        get cookiesSecure() {
+            return options().secure;
+        },
         start,
         callback,
         complete,
@@ -1087,38 +1094,8 @@ function redirect(location, cookies, status = 302) {
         headers.append('Set-Cookie', cookie.header);
     return new Response(null, { status, headers });
 }
-const NO_STORE = { 'Cache-Control': 'no-store' };
 /** A logout token is a few hundred bytes; this is generous and still small. */
 const BACKCHANNEL_LOGOUT_MAX_BODY_BYTES = 16 * 1024;
-/** The request body as text, or null when it is larger than `max` bytes. Stops reading at the cap. */
-async function readBounded(request, max) {
-    const declared = Number(request.headers.get('content-length'));
-    if (Number.isFinite(declared) && declared > max)
-        return null;
-    if (!request.body)
-        return '';
-    const reader = request.body.getReader();
-    const chunks = [];
-    let size = 0;
-    for (;;) {
-        const { done, value } = await reader.read();
-        if (done)
-            break;
-        size += value.byteLength;
-        if (size > max) {
-            await reader.cancel();
-            return null;
-        }
-        chunks.push(value);
-    }
-    const bytes = new Uint8Array(size);
-    let offset = 0;
-    for (const chunk of chunks) {
-        bytes.set(chunk, offset);
-        offset += chunk.byteLength;
-    }
-    return new TextDecoder().decode(bytes);
-}
 /** A back-channel logout endpoint's 400 error body, per OpenID Connect Back-Channel Logout 1.0 §2.6. */
 function backchannelLogoutError(error, description, status = 400) {
     return new Response(JSON.stringify({ error, error_description: description }), {
@@ -1210,12 +1187,6 @@ function isNavigation(request) {
         return false;
     return !request.headers.has('rsc') && !request.headers.has('next-action');
 }
-function isSameOrigin(request, origin) {
-    const from = request.headers.get('origin');
-    if (from)
-        return from === origin;
-    return request.headers.get('sec-fetch-site') === 'same-origin';
-}
 // Never says whether the address exists, so neither can the app.
 async function quietly(act) {
     try {

package/dist/body.d.ts

@@ -0,0 +1,5 @@
+/** Bounded request bodies: the one place the package decides how much of a request it will read. */
+/** True when the request declares a plain decimal length of at most `max`. A missing or odd length is refused too. */
+export declare function declaredWithin(request: Request, max: number): boolean;
+/** The request body as text, or null when it is larger than `max` bytes. Stops reading at the cap. */
+export declare function readBounded(request: Request, max: number): Promise<string | null>;

package/dist/body.js

@@ -0,0 +1,35 @@
+/** Bounded request bodies: the one place the package decides how much of a request it will read. */
+/** True when the request declares a plain decimal length of at most `max`. A missing or odd length is refused too. */
+export function declaredWithin(request, max) {
+    const length = request.headers.get('content-length');
+    return length !== null && /^\d{1,9}$/.test(length) && Number(length) <= max;
+}
+/** The request body as text, or null when it is larger than `max` bytes. Stops reading at the cap. */
+export async function readBounded(request, max) {
+    const declared = Number(request.headers.get('content-length'));
+    if (Number.isFinite(declared) && declared > max)
+        return null;
+    if (!request.body)
+        return '';
+    const reader = request.body.getReader();
+    const chunks = [];
+    let size = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        size += value.byteLength;
+        if (size > max) {
+            await reader.cancel();
+            return null;
+        }
+        chunks.push(value);
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return new TextDecoder().decode(bytes);
+}

package/dist/cookies.d.ts

@@ -78,6 +78,10 @@ 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. */
 export declare function withCookies(header: string | null, updates: SetCookie[]): string;

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,7 +186,12 @@ async function open(options, kind, value) {
         return null;
     }
 }
-function setCookie(name, value, maxAge, secure) {
+/** 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) {
         parts.push(`Max-Age=${maxAge}`);

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;