@botiverse/porthole 0.1.0 → 0.1.2

package/dist/server/pages.js

@@ -1,20 +1,94 @@
+import { FRAME_STATUS_METHOD } from "../isolation/types.js";
 /**
- * The server's own pages on a content origin: why it shows nothing of the content. Plain, no
- * script, framable only by the host origins, never cached. Their words are the host-agnostic
- * mechanism's; a host that wants its own wording serves its own page in front.
+ * The server's own pages on a content origin: why it shows nothing of the content, and the page a
+ * framed app is entered through. Plain, framable only by the host origins, never cached. Each tells
+ * the page that frames it how loading went (`porthole/notifications/frame-status`, P040), posted to
+ * the host origins only, so a host can show its own fallback ("Open in a new tab"). Their words are
+ * the host-agnostic mechanism's; a host that wants its own wording serves its own page in front.
  */
 const escape = (text) => text.replace(/[&<>"']/gu, (char) => `&#${char.charCodeAt(0)};`);
 const STYLE = ":root{color-scheme:light dark;font-family:system-ui,sans-serif}body{margin:0;min-height:100vh;display:grid;place-items:center;background:Canvas;color:CanvasText}main{max-width:420px;padding:24px}h1{font-size:17px;margin:0 0 8px}p{margin:0;opacity:.75;line-height:1.5}";
-export function statusPage(status, title, detail, frameAncestors, method = "GET") {
-    const body = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${escape(title)}</title><style>${STYLE}</style></head><body><main data-porthole-status="${status}"><h1>${escape(title)}</h1><p>${escape(detail)}</p></main></body></html>`;
+/** Where the pages' scripts are served, on every content origin. */
+export const STATUS_SCRIPT_PATH = "/__porthole/status.js";
+export const ENTER_SCRIPT_PATH = "/__porthole/enter.js";
+/** Answers 204 when the request carries a good session for its origin's app, 401 otherwise. */
+export const SESSION_PATH = "/__porthole/session";
+const say = () => `const say = (params) => { if (window.parent === window) return; for (const origin of hosts) window.parent.postMessage({ jsonrpc: "2.0", method: ${JSON.stringify(FRAME_STATUS_METHOD)}, params }, origin); };`;
+/** Tells the host the page is blocked, and why (from the page's data attributes). */
+const STATUS_SCRIPT = `(() => {
+  const main = document.querySelector("[data-porthole-status]");
+  if (main === null) return;
+  const hosts = JSON.parse(main.dataset.portholeHosts || "[]");
+  ${say()}
+  const blocked = { state: "blocked", reason: main.dataset.portholeReason || "error", status: Number(main.dataset.portholeStatus) };
+  if (main.dataset.portholeCode) blocked.code = main.dataset.portholeCode;
+  say(blocked);
+})();`;
+/**
+ * Enters a framed app: says so, checks that the browser kept the session cookie this page's own
+ * answer set (WebKit keeps none in a cross-site frame, P025), then, once this page has loaded,
+ * goes on to the app, or says it is blocked and why.
+ */
+const ENTER_SCRIPT = `(async () => {
+  const main = document.querySelector("[data-porthole-enter]");
+  if (main === null) return;
+  const hosts = JSON.parse(main.dataset.portholeHosts || "[]");
+  ${say()}
+  say({ state: "entering" });
+  let kept = false;
+  try {
+    kept = (await fetch(${JSON.stringify(SESSION_PATH)}, { credentials: "same-origin", cache: "no-store" })).ok;
+  } catch (_) {}
+  if (kept) {
+    // The host counts this page's load, then the app's (P040): leave only once this page has
+    // loaded, or a fast answer would leave first and its load would never be seen.
+    if (document.readyState !== "complete") {
+      await new Promise((resolve) => addEventListener("load", resolve, { once: true }));
+    }
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    location.replace(main.dataset.portholeTarget || "/");
+    return;
+  }
+  say({ state: "blocked", reason: "cookies", status: 401 });
+  main.querySelector("h1").textContent = "Open this app in a new tab";
+  main.querySelector("p").textContent = "This browser keeps no sign-in for it inside a frame.";
+})();`;
+/** The pages' scripts, by path: served with the pages' own policy in mind (`script-src 'self'`). */
+export function pageScript(pathname) {
+    const body = pathname === STATUS_SCRIPT_PATH
+        ? STATUS_SCRIPT
+        : pathname === ENTER_SCRIPT_PATH
+            ? ENTER_SCRIPT
+            : null;
+    return body === null
+        ? null
+        : new Response(body, {
+            headers: {
+                "content-type": "text/javascript; charset=utf-8",
+                "cache-control": "no-store",
+                "x-content-type-options": "nosniff",
+            },
+        });
+}
+const policy = (frameAncestors, connect) => `default-src 'none'; style-src 'unsafe-inline'; script-src 'self'; ${connect ? "connect-src 'self'; " : ""}base-uri 'none'; form-action 'none'; frame-ancestors ${frameAncestors}`;
+const pageHeaders = (frameAncestors, connect) => ({
+    "content-type": "text/html; charset=utf-8",
+    "cache-control": "no-store",
+    "content-security-policy": policy(frameAncestors, connect),
+    "referrer-policy": "no-referrer",
+    "x-content-type-options": "nosniff",
+});
+export function statusPage(status, title, detail, frameAncestors, method = "GET", reason = "error", hostOrigins = [], code) {
+    const body = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${escape(title)}</title><style>${STYLE}</style></head><body><main data-porthole-status="${status}" data-porthole-reason="${escape(reason)}"${code === undefined ? "" : ` data-porthole-code="${escape(code)}"`} data-porthole-hosts="${escape(JSON.stringify(hostOrigins))}"><h1>${escape(title)}</h1><p>${escape(detail)}</p></main><script src="${STATUS_SCRIPT_PATH}"></script></body></html>`;
     return new Response(method === "HEAD" ? null : body, {
         status,
-        headers: {
-            "content-type": "text/html; charset=utf-8",
-            "cache-control": "no-store",
-            "content-security-policy": `default-src 'none'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'; frame-ancestors ${frameAncestors}`,
-            "referrer-policy": "no-referrer",
-            "x-content-type-options": "nosniff",
-        },
+        headers: pageHeaders(frameAncestors, false),
     });
 }
+/** The page a framed app is entered through (its answer also sets the session cookie). */
+export function enterPage(target, frameAncestors, hostOrigins, cookie) {
+    const body = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Opening the app</title><style>${STYLE}</style></head><body><main data-porthole-enter="" data-porthole-target="${escape(target)}" data-porthole-hosts="${escape(JSON.stringify(hostOrigins))}"><h1>Opening the app…</h1><p></p></main><script src="${ENTER_SCRIPT_PATH}"></script></body></html>`;
+    const headers = new Headers(pageHeaders(frameAncestors, true));
+    headers.set("set-cookie", cookie);
+    return new Response(body, { status: 200, headers });
+}

package/dist/server/server.js

@@ -1,8 +1,9 @@
 import { compile } from "../compile/compile.js";
-import { isExactOrigin, maybeSameSite, originMatchesSource, parseOrigin, } from "../isolation/served.js";
+import { hostOriginProblem, maybeSameSite, originMatchesSource, parseOrigin, } from "../isolation/served.js";
 import { sandboxProxyDocument } from "../mcp/proxy.js";
 import { createKeys, newTicket, ticketId } from "./keys.js";
-import { statusPage } from "./pages.js";
+import { isHostLabel } from "./naming.js";
+import { enterPage, pageScript, SESSION_PATH, statusPage } from "./pages.js";
 import { memoryTicketStore } from "./tickets.js";
 /**
  * Paths on a content origin. Porthole's own live under `/__porthole/`; on a url-mode app's origin
@@ -14,6 +15,9 @@ const DOCUMENT_PATH = /^\/__porthole\/d\/([a-z2-7]{16})$/u;
 /** Where a url-mode app's ticket is taken, before the app's own landing path. */
 const ENTER_PATH = "/__porthole/enter";
 const LABEL = /^[a-z2-7]{24}$/u;
+/** A host's opaque subject and reason codes. */
+const SUBJECT_MAX = 512;
+const CODE = /^[a-z0-9-]{1,40}$/u;
 const DNS_NAME = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$/u;
 const NAME = /^[A-Za-z0-9._:-]{1,200}$/u;
 const DEFAULT_TICKET_SECONDS = 60;
@@ -144,6 +148,25 @@ export function createServer(options) {
         throw new TypeError("content.port must be a port number");
     }
     const keys = createKeys(options.secret);
+    const reserved = new Set(content.reserved ?? []);
+    for (const label of reserved) {
+        if (!isHostLabel(label)) {
+            throw new TypeError(`content.reserved: ${JSON.stringify(label)} is not a lowercase DNS label`);
+        }
+    }
+    /** The label a scope is served on: the host's naming, checked, or the keyed default. */
+    const nameOf = (scope) => {
+        if (content.name === undefined) {
+            return keys.label(scope);
+        }
+        const label = content.name(scope);
+        if (!isHostLabel(label) || reserved.has(label)) {
+            throw new TypeError(`content.name gave ${JSON.stringify(label)} for a scope: it must be one lowercase DNS label (a-z 0-9 -, at most 63, not xn--), not reserved`);
+        }
+        return label;
+    };
+    /** Whether a request's label may be one this server named. */
+    const ours = (label) => !reserved.has(label) && (content.name === undefined ? LABEL.test(label) : isHostLabel(label));
     const secure = content.scheme === "https";
     const defaultPort = secure ? 443 : 80;
     const portPart = content.port === undefined || content.port === defaultPort ? "" : `:${content.port}`;
@@ -151,13 +174,24 @@ export function createServer(options) {
     const contentSource = `${content.scheme}://*.${domain}${portPart}`;
     const sampleHost = `${keys.label("")}.${domain}`;
     const sampleOrigin = originOfLabel(keys.label(""));
+    const authorize = options.authorize;
+    const authorizeTtl = authorize?.ttlSeconds ?? 0;
+    if (!Number.isInteger(authorizeTtl) || authorizeTtl < 0 || authorizeTtl > 300) {
+        throw new TypeError("authorize.ttlSeconds must be an integer from 0 to 300");
+    }
+    const answers = new Map();
     if (options.hostOrigins.length === 0) {
         throw new TypeError("hostOrigins must name the origins that embed content");
     }
     for (const origin of options.hostOrigins) {
-        const parsed = isExactOrigin(origin) ? parseOrigin(origin) : null;
+        const problem = hostOriginProblem(origin);
+        if (problem !== null) {
+            throw new TypeError(`hostOrigins: ${problem}`);
+        }
+        // A desktop app's own scheme (ferry://app) is never the same site as web content.
+        const parsed = parseOrigin(origin);
         if (parsed === null) {
-            throw new TypeError(`hostOrigins: ${JSON.stringify(origin)} is not an exact origin`);
+            continue;
         }
         if (parsed.host === domain ||
             parsed.host.endsWith(`.${domain}`) ||
@@ -171,7 +205,55 @@ export function createServer(options) {
         compiled.set(name, compile(config));
     }
     const tickets = options.tickets ?? memoryTicketStore();
-    const page = (status, title, detail, method) => statusPage(status, title, detail, frameAncestors, method);
+    /** A page saying why there is nothing to show, told to the host too (its reason, P040). */
+    const page = (status, title, detail, method, reason = status === 404 ? "not-found" : status === 502 ? "upstream" : "error", code) => statusPage(status, title, detail, frameAncestors, method, reason, options.hostOrigins, code);
+    /**
+     * The host's check on a request its cookie (or ticket) let in (P050): null to go on, or the
+     * page saying it's denied. Answers are reused only for the host's own `ttlSeconds`.
+     */
+    async function denied(request, access) {
+        if (authorize === undefined) {
+            return null;
+        }
+        const key = JSON.stringify([
+            keys.instanceKey(access.instance),
+            access.viewer,
+            access.subject ?? null,
+            access.expiresAt,
+        ]);
+        const at = Date.now();
+        let answer = authorizeTtl > 0 ? answers.get(key) : undefined;
+        if (answer === undefined || answer.until <= at) {
+            let given;
+            try {
+                given = await authorize.check({
+                    scope: access.instance.scope,
+                    instance: access.instance,
+                    viewer: access.viewer,
+                    anonymous: access.anonymous === true,
+                    ...(access.subject === undefined ? {} : { subject: access.subject }),
+                    request,
+                });
+            }
+            catch {
+                given = { allow: false };
+            }
+            answer = { answer: given, until: at + authorizeTtl * 1_000 };
+            if (authorizeTtl > 0) {
+                if (answers.size > 10_000) {
+                    answers.clear();
+                }
+                answers.set(key, answer);
+            }
+        }
+        // Only an explicit allow lets the request on: anything else the check gives is a deny.
+        const given = answer.answer;
+        if (given?.allow === true) {
+            return null;
+        }
+        const code = typeof given?.code === "string" && CODE.test(given.code) ? given.code : undefined;
+        return page(403, "You can't open this anymore", "The app that showed it no longer lets you see it here.", request.method.toUpperCase(), "denied", code);
+    }
     /** The config a served document is served under, checked to fit it and this server. */
     function configFor(name, kind) {
         const each = compiled.get(name);
@@ -265,6 +347,8 @@ export function createServer(options) {
             i: record.instance,
             w: record.viewer,
             x: Date.now() + sessionSeconds * 1_000,
+            ...(record.anonymous === true ? { a: 1 } : {}),
+            ...(record.subject === undefined ? {} : { s: record.subject }),
         };
         const framed = request.headers.get("sec-fetch-dest") !== "document";
         return [
@@ -288,7 +372,8 @@ export function createServer(options) {
             if (!isRecord(session) ||
                 typeof session.w !== "string" ||
                 typeof session.x !== "number" ||
-                session.x <= Date.now()) {
+                session.x <= Date.now() ||
+                (session.s !== undefined && typeof session.s !== "string")) {
                 continue;
             }
             let instance;
@@ -298,12 +383,26 @@ export function createServer(options) {
             catch {
                 continue;
             }
-            if (keys.label(instance.scope) !== label ||
+            let named;
+            try {
+                named = nameOf(instance.scope);
+            }
+            catch {
+                continue;
+            }
+            if (named !== label ||
                 (key === null ? instance.document.kind !== "external" : keys.instanceKey(instance) !== key)) {
                 continue;
             }
             if (best === null || session.x > best.expiresAt) {
-                best = { instance, viewer: session.w, origin: originOfLabel(label), expiresAt: session.x };
+                best = {
+                    instance,
+                    viewer: session.w,
+                    origin: originOfLabel(label),
+                    expiresAt: session.x,
+                    ...(session.a === 1 ? { anonymous: true } : {}),
+                    ...(typeof session.s === "string" ? { subject: session.s } : {}),
+                };
             }
         }
         return best;
@@ -319,7 +418,7 @@ export function createServer(options) {
         }
         try {
             const instance = cleanInstance(record.instance);
-            return keys.label(instance.scope) === label ? { ...record, instance } : null;
+            return nameOf(instance.scope) === label ? { ...record, instance } : null;
         }
         catch {
             return null;
@@ -353,11 +452,17 @@ export function createServer(options) {
                 viewer: record.viewer,
                 origin: originOfLabel(label),
                 expiresAt: Date.now() + (record.sessionSeconds ?? DEFAULT_SESSION_SECONDS) * 1_000,
+                ...(record.anonymous === true ? { anonymous: true } : {}),
+                ...(record.subject === undefined ? {} : { subject: record.subject }),
             };
         }
         access ??= accessOf(request, label, key);
         if (access === null) {
-            return page(401, "This link has been used", "Content here opens once per link. Open it again from the app that showed it.", method);
+            return page(401, "This link has been used", "Content here opens once per link. Open it again from the app that showed it.", method, "session");
+        }
+        const refusal = await denied(request, access);
+        if (refusal !== null) {
+            return refusal;
         }
         const served = await documentOf(access.instance);
         if (served === null) {
@@ -376,13 +481,30 @@ export function createServer(options) {
         }
         const record = await take(url.searchParams.get("ticket"), label);
         if (record === null || record.instance.document.kind !== "external") {
-            return page(403, "This link has been used", "A link into an app works once, for a short time. Open it again from the app that showed it.");
+            return page(403, "This link has been used", "A link into an app works once, for a short time. Open it again from the app that showed it.", method, "session");
+        }
+        const refusal = await denied(request, {
+            instance: record.instance,
+            viewer: record.viewer,
+            origin: originOfLabel(label),
+            expiresAt: record.expiresAt,
+            ...(record.subject === undefined ? {} : { subject: record.subject }),
+        });
+        if (refusal !== null) {
+            return refusal;
         }
         const target = new URL(record.instance.document.url);
+        const landing = `${target.pathname}${target.search}${target.hash}`;
+        // In a frame, a page enters the app: it can tell whether the browser kept the cookie (and tell
+        // the host), where a redirect would leave a frame without one showing a refusal. On a tab of
+        // its own, a redirect.
+        if (request.headers.get("sec-fetch-dest") !== "document") {
+            return enterPage(landing, frameAncestors, options.hostOrigins, sessionCookie(request, record));
+        }
         return new Response(null, {
             status: 303,
             headers: {
-                location: `${target.pathname}${target.search}${target.hash}`,
+                location: landing,
                 "set-cookie": sessionCookie(request, record),
                 "cache-control": "no-store",
                 "referrer-policy": "no-referrer",
@@ -425,7 +547,11 @@ export function createServer(options) {
         const method = request.method.toUpperCase();
         const access = accessOf(request, label, null);
         if (access === null) {
-            return page(401, "Open this from the app", "This address shows an app only to the people the app opens it for.", method);
+            return page(401, "Open this from the app", "This address shows an app only to the people the app opens it for.", method, "session");
+        }
+        const refusal = await denied(request, access);
+        if (refusal !== null) {
+            return refusal;
         }
         if (options.upstream === undefined) {
             return page(502, "Nothing serves this app", "The server has no upstream for apps.", method);
@@ -450,42 +576,74 @@ export function createServer(options) {
         if (host !== domain && !host.endsWith(`.${domain}`)) {
             return null;
         }
-        return { url, label: host.slice(0, Math.max(0, host.length - domain.length - 1)) };
+        const label = host.slice(0, Math.max(0, host.length - domain.length - 1));
+        // A reserved label is another server's namespace (`f` for `<x>.f.<domain>`): it and the names
+        // under it go to the host's own routes. Any other deeper name is ours to refuse.
+        if (reserved.has(label.split(".").at(-1) ?? "")) {
+            return null;
+        }
+        return { url, label };
     }
     return {
         contentSource,
-        originFor: (scope) => originOfLabel(keys.label(scope)),
+        originFor: (scope) => originOfLabel(nameOf(scope)),
         async issue(instance, grant) {
             const clean = cleanInstance(instance);
             check(clean);
-            if (typeof grant.viewer !== "string" ||
+            const anonymous = grant.anonymous === true;
+            if (anonymous) {
+                if (grant.viewer !== undefined) {
+                    throw new TypeError("An anonymous grant names no viewer");
+                }
+                if (clean.document.kind === "external") {
+                    throw new TypeError("A url-mode app is never opened anonymously (P046)");
+                }
+            }
+            else if (typeof grant.viewer !== "string" ||
                 grant.viewer.length === 0 ||
                 grant.viewer.length > 512) {
-                throw new TypeError("A grant's viewer is 1 to 512 characters");
+                throw new TypeError("A grant's viewer is 1 to 512 characters (or the grant is anonymous)");
+            }
+            if (grant.subject !== undefined &&
+                (typeof grant.subject !== "string" || grant.subject.length > SUBJECT_MAX)) {
+                throw new TypeError(`A grant's subject is a string of at most ${SUBJECT_MAX} characters`);
             }
             const ttl = seconds(grant.ttlSeconds, DEFAULT_TICKET_SECONDS, MAX_TICKET_SECONDS, "ttlSeconds");
             const sessionSeconds = seconds(grant.sessionSeconds, DEFAULT_SESSION_SECONDS, MAX_SESSION_SECONDS, "sessionSeconds");
             const key = keys.instanceKey(clean);
-            const probe = keys.sign({ i: clean, w: grant.viewer, x: Number.MAX_SAFE_INTEGER });
+            const viewer = anonymous ? "" : grant.viewer;
+            const probe = keys.sign({
+                i: clean,
+                w: viewer,
+                x: Number.MAX_SAFE_INTEGER,
+                ...(anonymous ? { a: 1 } : {}),
+                ...(grant.subject === undefined ? {} : { s: grant.subject }),
+            });
             if (cookieName(key).length + probe.length + 120 > MAX_COOKIE_BYTES) {
                 throw new TypeError("This instance is too large to carry in a cookie (fewer origins?)");
             }
             const ticket = newTicket();
             await tickets.put(ticketId(ticket), {
                 instance: clean,
-                viewer: grant.viewer,
+                viewer,
                 expiresAt: Date.now() + ttl * 1_000,
                 ...(grant.sessionSeconds === undefined ? {} : { sessionSeconds }),
+                ...(anonymous ? { anonymous: true } : {}),
+                ...(grant.subject === undefined ? {} : { subject: grant.subject }),
             });
-            const origin = originOfLabel(keys.label(clean.scope));
+            const origin = originOfLabel(nameOf(clean.scope));
             const path = clean.document.kind === "external"
                 ? `${ENTER_PATH}?ticket=${ticket}`
                 : `${PREFIX}d/${key}?ticket=${ticket}`;
-            return { url: `${origin}${path}`, origin };
+            return { url: `${origin}${path}`, origin, reports: true };
         },
         async access(request) {
             const at = labelOf(request);
-            return at === null || !LABEL.test(at.label) ? null : accessOf(request, at.label, null);
+            if (at === null || !ours(at.label)) {
+                return null;
+            }
+            const access = accessOf(request, at.label, null);
+            return access === null || (await denied(request, access)) !== null ? null : access;
         },
         async handle(request) {
             const at = labelOf(request);
@@ -495,12 +653,22 @@ export function createServer(options) {
             const { url, label } = at;
             const method = request.method.toUpperCase();
             try {
-                if (!LABEL.test(label)) {
+                if (!ours(label)) {
                     return page(404, "Nothing here", "This address names no content.", method);
                 }
                 if (url.pathname === ENTER_PATH) {
                     return await enter(request, url, label);
                 }
+                const script = pageScript(url.pathname);
+                if (script !== null) {
+                    return script;
+                }
+                if (url.pathname === SESSION_PATH) {
+                    // Whether this request's cookie opens its origin's app: the entry page asks.
+                    const access = accessOf(request, label, null);
+                    const status = access === null ? 401 : (await denied(request, access)) === null ? 204 : 403;
+                    return new Response(null, { status, headers: { "cache-control": "no-store" } });
+                }
                 const document = DOCUMENT_PATH.exec(url.pathname);
                 if (document?.[1] !== undefined) {
                     return await serveDocument(request, url, label, document[1]);

package/dist/server/tickets.d.ts

@@ -6,3 +6,27 @@ import type { TicketStore } from "./types.ts";
 export declare function memoryTicketStore(options?: {
     readonly now?: () => number;
 }): TicketStore;
+/**
+ * The part of a Cloudflare D1 database (or any SQLite-like binding with the same shape) the ticket
+ * store uses: a prepared statement, bound, run or read once.
+ */
+export interface D1Like {
+    prepare(query: string): D1StatementLike;
+}
+export interface D1StatementLike {
+    bind(...values: unknown[]): D1StatementLike;
+    run(): Promise<unknown>;
+    first<T = Record<string, unknown>>(): Promise<T | null>;
+}
+/** The table a D1 ticket store needs (run once, as a migration). */
+export declare function d1TicketSchema(table?: string): string;
+/**
+ * Tickets in a D1 database (P045): shared by every Worker isolate, and taken once by an atomic
+ * `DELETE … RETURNING` (one statement on D1's single primary, so two requests racing for a ticket
+ * can't both get it). Expired tickets are swept as new ones go in. Workers KV is no place for
+ * tickets: it is eventually consistent, so a ticket read in two places could be used twice.
+ */
+export declare function d1TicketStore(db: D1Like, options?: {
+    readonly table?: string;
+    readonly now?: () => number;
+}): TicketStore;

package/dist/server/tickets.js

@@ -26,3 +26,49 @@ export function memoryTicketStore(options = {}) {
         },
     };
 }
+const TABLE = /^[a-z_][a-z0-9_]{0,62}$/u;
+/** The table a D1 ticket store needs (run once, as a migration). */
+export function d1TicketSchema(table = "porthole_tickets") {
+    if (!TABLE.test(table)) {
+        throw new TypeError("A ticket table is named with a-z 0-9 _");
+    }
+    return `CREATE TABLE IF NOT EXISTS ${table} (id TEXT PRIMARY KEY, record TEXT NOT NULL, expires_at INTEGER NOT NULL);
+CREATE INDEX IF NOT EXISTS ${table}_expires_at ON ${table} (expires_at);`;
+}
+/**
+ * Tickets in a D1 database (P045): shared by every Worker isolate, and taken once by an atomic
+ * `DELETE … RETURNING` (one statement on D1's single primary, so two requests racing for a ticket
+ * can't both get it). Expired tickets are swept as new ones go in. Workers KV is no place for
+ * tickets: it is eventually consistent, so a ticket read in two places could be used twice.
+ */
+export function d1TicketStore(db, options = {}) {
+    const table = options.table ?? "porthole_tickets";
+    if (!TABLE.test(table)) {
+        throw new TypeError("A ticket table is named with a-z 0-9 _");
+    }
+    const now = options.now ?? Date.now;
+    return {
+        async put(id, record) {
+            await db.prepare(`DELETE FROM ${table} WHERE expires_at <= ?`).bind(now()).run();
+            await db
+                .prepare(`INSERT INTO ${table} (id, record, expires_at) VALUES (?, ?, ?)`)
+                .bind(id, JSON.stringify(record), record.expiresAt)
+                .run();
+        },
+        async take(id) {
+            const row = await db
+                .prepare(`DELETE FROM ${table} WHERE id = ? RETURNING record, expires_at`)
+                .bind(id)
+                .first();
+            if (row === null || row.expires_at <= now()) {
+                return null;
+            }
+            try {
+                return JSON.parse(row.record);
+            }
+            catch {
+                return null;
+            }
+        },
+    };
+}