@wtfalch/auth 0.31.0 → 0.33.0

package/dist/desktop.js

@@ -1,4 +1,11 @@
-import { createCipheriv, createDecipheriv, createHash, hkdfSync, randomBytes, randomUUID, timingSafeEqual, } from 'node:crypto';
+import { randomUUID } from 'node:crypto';
+import { declaredWithin, readBounded } from './body.js';
+import { clearCookie, digest, setCookie, withCookies } from './cookies.js';
+import { newNonce, open, pairingCode, same, seal, sealKey } from './desktop-crypto.js';
+import { NO_STORE } from './util.js';
+export { createMemoryDesktopHandoffStore, } from './desktop-store.js';
+export { DESKTOP_HANDOFFS_TABLE_SQL, createPostgresDesktopHandoffStore, } from './desktop-store-postgres.js';
+export { checkDesktopHandoffStore } from './desktop-store-contract.js';
 export class DesktopHandoffError extends Error {
     status;
     code;
@@ -16,167 +23,9 @@ const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const SAFE_REASON = /^[a-z_]{1,20}$/;
 /** Same shape `@wtfalch/desktop`'s `cookieHandoff({ scheme })` requires. */
 const SCHEME = /^[a-z][a-z0-9+.-]*$/;
+/** Where the handler is mounted. */
+const BASE = '/auth/desktop';
 const APP_ID = /^[a-z][a-z0-9-]*$/;
-const HINT = /^[^\s@<>]{1,64}@[^\s@<>]{1,190}$/;
-const NO_STORE = { 'Cache-Control': 'no-store' };
-const digest = (value) => createHash('sha256').update(value).digest('base64url');
-const newNonce = () => randomBytes(32).toString('base64url');
-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.
- */
-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. */
-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. */
-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.
- */
-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)}`;
-}
-/**
- * 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, callerHash: _caller, ...row } = entry;
-        return {
-            row,
-            live: expiresAt > Date.now(),
-            pollOk: lastPoll === null || lastPoll < Date.now() - pollGapMs,
-        };
-    };
-    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 polled(_tx, id) {
-            const entry = rows.get(id);
-            if (entry)
-                entry.lastPoll = Date.now();
-        },
-    };
-}
 /** Fail-open on purpose, for an app with nothing further to check; see `DesktopHandoffConfig.admit`. */
 const alwaysAdmit = async (user) => ({ ok: true, user: { id: user.id } });
 export function createDesktopHandoff({ auth, appUrl, secret, appId, scheme, store, admit = alwaysAdmit, onError, clientAddressHeader = 'cf-connecting-ip', maxStartsPerCaller = 8, }) {
@@ -200,7 +49,8 @@ export function createDesktopHandoff({ auth, appUrl, secret, appId, scheme, stor
             response.headers.append('Set-Cookie', cookie);
         return response;
     };
-    const browserCookie = (value) => `${cookieName}=${value}; Path=/; HttpOnly; SameSite=Lax; Max-Age=${value ? 300 : 0}${secure ? '; Secure' : ''}`;
+    const browserCookie = (value) => (value ? setCookie(cookieName, value, 300, secure) : clearCookie(cookieName, secure)).header;
+    const errorPage = (reason, cookies = []) => redirect(`${BASE}/error?reason=${reason}`, cookies);
     const reasonOf = (error) => error instanceof DesktopHandoffError ? error.code : 'unavailable';
     /** Tells the host about a failure nobody planned for; a throwing hook never changes the answer. */
     function report(step, error) {
@@ -224,15 +74,19 @@ export function createDesktopHandoff({ auth, appUrl, secret, appId, scheme, stor
         }
         catch (error) {
             report(step, error);
-            return redirect(`/auth/desktop/error?reason=${reasonOf(error)}`);
+            return errorPage(reasonOf(error));
         }
     }
     /** A digest of the caller's address; null when the trusted header is absent (those callers share one bucket). */
-    function callerOf(request) {
+    async function callerOf(request) {
         const value = request.headers.get(clientAddressHeader)?.trim();
         return value ? digest(value) : null;
     }
-    /** The id and nonce the browser holds; the row is the only place either is checked. */
+    /**
+     * The id and nonce the browser holds; the row is the only place either is checked. Not
+     * `cookieFrom`: that takes the first cookie of the name, and this refuses a request that
+     * carries the name twice.
+     */
     function browserOf(cookieHeader) {
         const values = (cookieHeader ?? '')
             .split(';')
@@ -243,6 +97,8 @@ export function createDesktopHandoff({ auth, appUrl, secret, appId, scheme, stor
             throw fail(401, 'browser_required');
         return { id, nonce };
     }
+    /** Whether `nonce` is the one this row was started with. */
+    const holds = async (row, nonce) => same(row.browserHash, await digest(nonce));
     /** The row this browser started, locked: it must exist, be unexpired, and carry this browser's nonce. */
     async function browserRow(tx, cookieHeader) {
         const browser = browserOf(cookieHeader);
@@ -251,29 +107,113 @@ export function createDesktopHandoff({ auth, appUrl, secret, appId, scheme, stor
             throw fail(404, 'not_found');
         if (!found.live)
             throw fail(410, 'expired');
-        if (!found.row.browserHash || !same(found.row.browserHash, digest(browser.nonce)))
+        if (!(await holds(found.row, browser.nonce)))
             throw fail(403, 'browser_mismatch');
         return found.row;
     }
+    /**
+     * Stricter than `isSameOrigin` on purpose: these POSTs come from the page this
+     * handler served, so the browser always sends `Origin`; `Sec-Fetch-Site` alone is not accepted.
+     */
     function sameOrigin(request) {
         if (request.headers.get('origin') !== origin)
             throw fail(403, 'origin');
     }
-    const withoutSession = (cookieHeader) => (cookieHeader ?? '')
-        .split(';')
-        .map((part) => part.trim())
-        .filter((part) => part && !part.startsWith(`${auth.sessionCookieName}=`))
-        .join('; ');
+    const withoutSession = (cookieHeader) => withCookies(cookieHeader, [clearCookie(auth.sessionCookieName, secure)]);
+    /** The form body as text, read through the bounded reader: larger than 4096 bytes is refused, declared or not. */
+    async function formBody(request) {
+        const text = await readBounded(request, 4096);
+        if (text === null)
+            throw fail(413, 'body_too_large');
+        return text;
+    }
     async function formRevision(request) {
-        const value = (await request.formData().catch(() => null))?.get('revision');
-        if (typeof value !== 'string' || !UUID.test(value))
+        const form = request.headers.get('content-type')?.split(';')[0]?.trim().toLowerCase();
+        const text = await formBody(request);
+        const value = form === 'application/x-www-form-urlencoded'
+            ? new URLSearchParams(text).getAll('revision')
+            : [];
+        if (value.length !== 1 || !UUID.test(value[0]))
             throw fail(400, 'invalid_request');
-        return value;
+        return value[0];
     }
-    /** A body is read only when its length is declared and within `max`: a missing length is refused too. */
-    function bodyWithin(request, max) {
-        const length = request.headers.get('content-length');
-        return length !== null && /^\d{1,9}$/.test(length) && Number(length) <= max;
+    /** The shell trades its verifier for the cookie, once. No browser cookie involved. */
+    async function redeem(input) {
+        try {
+            const { id, verifier } = (input ?? {});
+            if (typeof id !== 'string' ||
+                !UUID.test(id) ||
+                typeof verifier !== 'string' ||
+                !OPAQUE.test(verifier))
+                throw fail(400, 'invalid_request');
+            const verifierDigest = await digest(verifier);
+            // Step one: check the verifier, stamp the attempt, and let go of the row. A refusal after
+            // the stamp is returned, not thrown, so the stamp (or the delete of an expired row) commits.
+            const claimed = await store.transaction(async (tx) => {
+                const found = await store.lock(tx, id);
+                if (!found)
+                    throw fail(404, 'not_found');
+                const { row } = found;
+                if (!same(row.challenge, verifierDigest))
+                    throw fail(403, 'invalid_verifier');
+                if (!found.live) {
+                    await store.remove(tx, row.id);
+                    return { error: fail(410, 'expired') };
+                }
+                if (!(await store.stampPoll(tx, row.id)))
+                    throw fail(429, 'too_fast');
+                if (row.status !== 'approved')
+                    return { error: fail(409, 'not_approved') };
+                return { id: row.id, payload: row.payload, subject: row.subject };
+            });
+            if ('error' in claimed)
+                throw claimed.error;
+            // Step two, with no lock held: `readCookie` is not local. It verifies the id token and
+            // may fetch the issuer's signing keys.
+            let payload;
+            try {
+                payload = JSON.parse(open(key, aad(claimed.id), claimed.payload));
+            }
+            catch {
+                throw fail(500, 'payload_invalid');
+            }
+            const verified = await auth.readCookie(payload.value, { refresh: false }).catch(() => {
+                throw fail(503, 'unavailable');
+            });
+            const admitted = verified.user ? await admit(verified.user) : null;
+            if (!admitted?.ok || admitted.user.id !== claimed.subject)
+                throw fail(401, 'identity_expired');
+            // Step three: lock again and take the row. Whoever deletes it first wins.
+            await store.transaction(async (tx) => {
+                const found = await store.lock(tx, claimed.id);
+                if (!found)
+                    throw fail(404, 'not_found');
+                if (found.row.status !== 'approved')
+                    throw fail(409, 'not_approved');
+                if (!found.live)
+                    throw fail(410, 'expired');
+                await store.remove(tx, claimed.id);
+            });
+            const { name, value, secure: cookieSecure, maxAge } = payload;
+            return Response.json({
+                cookies: [
+                    {
+                        name,
+                        value,
+                        path: '/',
+                        httpOnly: true,
+                        secure: cookieSecure,
+                        sameSite: 'lax',
+                        maxAge,
+                    },
+                ],
+            }, { headers: NO_STORE });
+        }
+        catch (error) {
+            report('redeem', error);
+            const status = error instanceof DesktopHandoffError ? error.status : 503;
+            return Response.json({ error: reasonOf(error) }, { status, headers: NO_STORE });
+        }
     }
     return {
         /** The cookie name, for the one place a test or a route needs to read it. */
@@ -284,10 +224,16 @@ export function createDesktopHandoff({ auth, appUrl, secret, appId, scheme, stor
             const challenge = params.get('challenge');
             if (params.getAll('challenge').length !== 1 || !challenge || !OPAQUE.test(challenge))
                 throw fail(400, 'invalid_challenge');
+            // The SDK reads `prompt` and `login_hint` from the request it is given (it drops a
+            // `login_hint` that is not an email address), and wants a navigation.
+            const forwarded = new URLSearchParams();
+            if (params.get('prompt') === 'select_account')
+                forwarded.set('prompt', 'select_account');
             const hint = params.get('login_hint');
-            const prompt = params.get('prompt') === 'select_account' ? '?prompt=select_account' : '';
-            // The SDK reads only `prompt` from the request it is given, and wants a navigation.
-            const started = await auth.start(new Request(`${origin}/auth/desktop/start${prompt}`, {
+            if (hint)
+                forwarded.set('login_hint', hint);
+            const query = forwarded.size ? `?${forwarded}` : '';
+            const started = await auth.start(new Request(`${origin}${BASE}/start${query}`, {
                 headers: { accept: 'text/html', 'sec-fetch-mode': 'navigate' },
             }));
             const location = started.headers.get('location');
@@ -295,17 +241,14 @@ export function createDesktopHandoff({ auth, appUrl, secret, appId, scheme, stor
             const state = target?.searchParams.get('state');
             if (!target || !state)
                 throw fail(503, 'unavailable');
-            // The SDK does not forward `login_hint`; the issuer's authorize URL takes it as a plain parameter.
-            if (hint && hint.length <= 254 && HINT.test(hint))
-                target.searchParams.set('login_hint', hint);
             const id = randomUUID();
             const nonce = newNonce();
             const admitted = await store.admit({
                 id,
                 challenge,
-                browserHash: digest(nonce),
-                stateHash: digest(state),
-                callerHash: callerOf(request),
+                browserHash: await digest(nonce),
+                stateHash: await digest(state),
+                callerHash: await callerOf(request),
             }, { perCaller: maxStartsPerCaller });
             if (!admitted)
                 throw fail(429, 'capacity');
@@ -320,12 +263,13 @@ export function createDesktopHandoff({ auth, appUrl, secret, appId, scheme, stor
             const url = new URL(request.url);
             // Three steps, and no transaction open across the issuer's answer: validate and let go,
             // ask the issuer, then lock again and apply only if the row is still waiting.
+            const states = url.searchParams.getAll('state');
+            const stateDigest = states.length === 1 ? await digest(states[0]) : null;
             await store.transaction(async (tx) => {
                 const row = await browserRow(tx, cookieHeader);
                 if (row.status !== 'started')
                     throw fail(409, 'step_changed');
-                const states = url.searchParams.getAll('state');
-                if (states.length !== 1 || !row.stateHash || !same(row.stateHash, digest(states[0])))
+                if (stateDigest === null || !same(row.stateHash, stateDigest))
                     throw fail(409, 'state_mismatch');
             });
             // Behind a proxy `request.url` can carry an internal host; the path and query are what the browser asked for.
@@ -340,7 +284,7 @@ export function createDesktopHandoff({ auth, appUrl, secret, appId, scheme, stor
             if (!cookie || !user) {
                 // No write: the row (and the binding cookie) stay for a valid callback that may still be running.
                 const reason = new URL(result.location, origin).searchParams.get('auth_error');
-                return redirect(`/auth/desktop/error?reason=${reason && SAFE_REASON.test(reason) ? reason : 'failed'}`, cleared);
+                return errorPage(reason && SAFE_REASON.test(reason) ? reason : 'failed', cleared);
             }
             // Refused here, not at the first request with the cookie: the shell is never handed a
             // session the app would turn away. `admit` runs under the row's lock, so two concurrent
@@ -352,7 +296,7 @@ export function createDesktopHandoff({ auth, appUrl, secret, appId, scheme, stor
                     throw fail(409, 'step_changed');
                 const admission = await admit(user);
                 if (!admission.ok)
-                    return redirect(`/auth/desktop/error?reason=${SAFE_REASON.test(admission.reason) ? admission.reason : 'denied'}`, cleared);
+                    return errorPage(SAFE_REASON.test(admission.reason) ? admission.reason : 'denied', cleared);
                 const payload = {
                     name: cookie.name,
                     value: cookie.value,
@@ -366,7 +310,7 @@ export function createDesktopHandoff({ auth, appUrl, secret, appId, scheme, stor
                     email: user.email,
                     revision: randomUUID(),
                 });
-                return redirect('/auth/desktop/confirm', cleared);
+                return redirect(`${BASE}/confirm`, cleared);
             });
         }),
         /**
@@ -387,9 +331,7 @@ export function createDesktopHandoff({ auth, appUrl, secret, appId, scheme, stor
                         code: null,
                         returnUrl: null,
                     };
-                if (!found.live ||
-                    !found.row.browserHash ||
-                    !same(found.row.browserHash, digest(browser.nonce)))
+                if (!found.live || !(await holds(found.row, browser.nonce)))
                     return null;
                 const { id, status, email, revision, challenge } = found.row;
                 return {
@@ -401,128 +343,56 @@ export function createDesktopHandoff({ auth, appUrl, secret, appId, scheme, stor
                     returnUrl: status === 'approved' ? returnUrl(id) : null,
                 };
             }
-            catch {
-                return null;
+            catch (error) {
+                // A cookie that does not open or match is a refusal: signed out. A store or issuer
+                // failure is not, and must not look like one: log what is safe to log and let it rise.
+                if (error instanceof DesktopHandoffError)
+                    return null;
+                console.error('desktop handoff current failed', error instanceof Error ? error.name : 'unknown');
+                throw error;
             }
         },
         /** POST /auth/desktop/approve: the person confirms the account the page showed. */
         approve: (request) => page('approve', async () => {
             sameOrigin(request);
-            if (!bodyWithin(request, 4096))
-                throw fail(413, 'body_too_large');
             const seen = await formRevision(request);
             return store.transaction(async (tx) => {
                 const row = await browserRow(tx, request.headers.get('cookie'));
-                if (row.status !== 'completed' || !row.revision || !same(row.revision, seen))
+                if (row.status !== 'completed' || !same(row.revision, seen))
                     throw fail(409, 'step_changed');
                 await store.patch(tx, row.id, { status: 'approved' });
-                return redirect('/auth/desktop/done');
+                return redirect(`${BASE}/done`);
             });
         }),
         /** POST /auth/desktop/cancel: ends the sign-in and deletes its row. */
         cancel: (request) => page('cancel', async () => {
             sameOrigin(request);
-            if (!bodyWithin(request, 4096))
-                throw fail(413, 'body_too_large');
+            await formBody(request);
             return store.transaction(async (tx) => {
                 const row = await browserRow(tx, request.headers.get('cookie'));
                 await store.remove(tx, row.id);
-                return redirect('/auth/desktop/error?reason=cancelled', [browserCookie('')]);
+                return errorPage('cancelled', [browserCookie('')]);
             });
         }),
         /** POST /auth/desktop/redeem, with the body still unread: refuses one that is not small and declared. */
         async redeemRequest(request) {
             const json = request.headers.get('content-type')?.split(';')[0]?.trim() === 'application/json';
-            if (!bodyWithin(request, 1024))
+            if (!declaredWithin(request, 1024))
                 return Response.json({ error: 'body_too_large' }, { status: 413, headers: NO_STORE });
             let input = null;
             try {
-                if (json)
-                    input = JSON.parse(await request.text());
+                const text = json ? await readBounded(request, 1024) : null;
+                if (text === null && json)
+                    return Response.json({ error: 'body_too_large' }, { status: 413, headers: NO_STORE });
+                if (text !== null)
+                    input = JSON.parse(text);
             }
             catch {
                 // Not JSON: `input` stays null, and `redeem` refuses it as `invalid_request`.
                 input = null;
             }
-            return this.redeem(input);
-        },
-        /** The shell trades its verifier for the cookie, once. No browser cookie involved. */
-        async redeem(input) {
-            try {
-                const { id, verifier } = (input ?? {});
-                if (typeof id !== 'string' ||
-                    !UUID.test(id) ||
-                    typeof verifier !== 'string' ||
-                    !OPAQUE.test(verifier))
-                    throw fail(400, 'invalid_request');
-                // Step one: check the verifier, stamp the attempt, and let go of the row. A refusal after
-                // the stamp is returned, not thrown, so the stamp (or the delete of an expired row) commits.
-                const claimed = await store.transaction(async (tx) => {
-                    const found = await store.lock(tx, id);
-                    if (!found)
-                        throw fail(404, 'not_found');
-                    const { row } = found;
-                    if (!same(row.challenge, digest(verifier)))
-                        throw fail(403, 'invalid_verifier');
-                    if (!found.live) {
-                        await store.remove(tx, row.id);
-                        return { error: fail(410, 'expired') };
-                    }
-                    if (!found.pollOk)
-                        throw fail(429, 'too_fast');
-                    await store.polled(tx, row.id);
-                    if (row.status !== 'approved' || !row.payload)
-                        return { error: fail(409, 'not_approved') };
-                    return { id: row.id, payload: row.payload, subject: row.subject };
-                });
-                if ('error' in claimed)
-                    throw claimed.error;
-                // Step two, with no lock held: `readCookie` is not local. It verifies the id token and
-                // may fetch the issuer's signing keys.
-                let payload;
-                try {
-                    payload = JSON.parse(open(key, aad(claimed.id), claimed.payload));
-                }
-                catch {
-                    throw fail(500, 'payload_invalid');
-                }
-                const verified = await auth.readCookie(payload.value, { refresh: false }).catch(() => {
-                    throw fail(503, 'unavailable');
-                });
-                const admitted = verified.user ? await admit(verified.user) : null;
-                if (!admitted?.ok || admitted.user.id !== claimed.subject)
-                    throw fail(401, 'identity_expired');
-                // Step three: lock again and take the row. Whoever deletes it first wins.
-                await store.transaction(async (tx) => {
-                    const found = await store.lock(tx, claimed.id);
-                    if (!found)
-                        throw fail(404, 'not_found');
-                    if (found.row.status !== 'approved')
-                        throw fail(409, 'not_approved');
-                    if (!found.live)
-                        throw fail(410, 'expired');
-                    await store.remove(tx, claimed.id);
-                });
-                const { name, value, secure: cookieSecure, maxAge } = payload;
-                return Response.json({
-                    cookies: [
-                        {
-                            name,
-                            value,
-                            path: '/',
-                            httpOnly: true,
-                            secure: cookieSecure,
-                            sameSite: 'lax',
-                            maxAge,
-                        },
-                    ],
-                }, { headers: NO_STORE });
-            }
-            catch (error) {
-                report('redeem', error);
-                const status = error instanceof DesktopHandoffError ? error.status : 503;
-                return Response.json({ error: reasonOf(error) }, { status, headers: NO_STORE });
-            }
+            return redeem(input);
         },
+        redeem,
     };
 }

package/dist/index.d.ts

@@ -7,3 +7,4 @@ export type { PersonIdentity, PersonTokenConfig, PersonTokenOutcome, PersonToken
 export { BrokerError, type PeoplePage, type Person } from './broker.js';
 export { AuthError, type AuthErrorReason, ORG_CLAIM } from './oidc.js';
 export { safeLoginHint, safeNextPath } from './redirect.js';
+export { PREVIEW_CHECK_PATH, PREVIEW_COOKIE, PREVIEW_PATH, type PreviewRoutes, type PreviewRoutesOptions, createPreviewRoutes, } from './preview.js';

package/dist/index.js

@@ -3,3 +3,4 @@ export { DesktopHandoffError, } from './desktop.js';
 export { BrokerError } from './broker.js';
 export { AuthError, ORG_CLAIM } from './oidc.js';
 export { safeLoginHint, safeNextPath } from './redirect.js';
+export { PREVIEW_CHECK_PATH, PREVIEW_COOKIE, PREVIEW_PATH, createPreviewRoutes, } from './preview.js';

package/dist/preview.d.ts

@@ -0,0 +1,28 @@
+import type { Auth, User } from './auth.js';
+/** The cookie that selects the idle slot at the balancer. */
+export declare const PREVIEW_COOKIE = "bg_preview";
+/** Where the balancer's forwardAuth asks whether the request may see the idle slot. */
+export declare const PREVIEW_CHECK_PATH = "/api/foundry/preview-check";
+/** Where the app sets (POST) and clears (DELETE) the preview cookie. */
+export declare const PREVIEW_PATH = "/api/foundry/preview";
+export interface PreviewRoutesOptions {
+    /**
+     * The app's auth instance. The session is read through it (without
+     * refreshing, since these routes set no session cookie), and the app's origin
+     * and the cookie's `Secure` rule come from its `appUrl`, read on the first
+     * request so importing this module at build time needs no environment.
+     */
+    auth: Pick<Auth, 'read' | 'appOrigin' | 'cookiesSecure'>;
+    /** Whether this session holds `releases:preview` in the app's production authz. */
+    mayPreview: (user: User) => Promise<boolean>;
+}
+export interface PreviewRoutes {
+    /** GET `PREVIEW_CHECK_PATH`: 200 allowed, 401 no session, 403 otherwise. */
+    check: (request: Request) => Promise<Response>;
+    /** POST `PREVIEW_PATH`: same-origin, same check, then sets the cookie (204). */
+    set: (request: Request) => Promise<Response>;
+    /** DELETE `PREVIEW_PATH`: same-origin, clears the cookie (204). */
+    clear: (request: Request) => Promise<Response>;
+}
+/** Route handlers for the idle preview: the check the balancer calls, and the cookie the person sets and clears. */
+export declare function createPreviewRoutes(options: PreviewRoutesOptions): PreviewRoutes;