@botiverse/porthole 0.1.1 → 0.1.3

package/dist/server/index.d.ts

@@ -9,12 +9,18 @@
  *
  * and calls `issue` from its own authenticated API when a viewer opens served content.
  *
+ * Runs on any runtime with web-standard `Request`/`Response` and `crypto.getRandomValues`: Node,
+ * Cloudflare Workers (no `nodejs_compat` needed), Deno, Bun (P044). On Workers, keep tickets in D1
+ * (`d1TicketStore`, P045).
+ *
  * Origins: each storage scope gets `<label>.<domain>`, the label keyed from the scope by the
- * secret (stable, DNS-safe, not guessable from the scope). The domain is a registrable domain the
+ * secret (stable, DNS-safe, not guessable from the scope), or a host's own flat name
+ * (`content.name`, `prefixedName("a-")` for `a-<id>`), with other servers' namespaces reserved (P047). The domain is a registrable domain the
  * host uses for nothing else, so no content origin is ever same-site with the host. Documents go
  * out with their CSP (from the config) plus `frame-ancestors` (the host origins) in headers.
  *
- * Tickets: `issue` mints a one-time ticket for an instance and a viewer, good for a short time;
+ * Tickets: `issue` mints a one-time ticket for an instance and a viewer (or anonymously, for a
+ * public link, P046), good for a short time;
  * the frame's first request carries it, and the content origin takes it (once). A served document
  * comes back in that same answer, with a cookie of that origin only (`__Host-`, `Secure`,
  * `HttpOnly`, `SameSite=None; Partitioned` in a frame) for what follows; a url-mode app's ticket
@@ -22,6 +28,8 @@
  * content without a valid ticket or cookie gets nothing of the content.
  */
 export { createServer } from "./server.ts";
-export { memoryTicketStore } from "./tickets.ts";
+export { d1TicketSchema, d1TicketStore, memoryTicketStore, type D1Like, type D1StatementLike, } from "./tickets.ts";
+export { FRAME_STATUS_METHOD } from "../isolation/types.ts";
+export { isHostLabel, prefixedName } from "./naming.ts";
 export { proxyTo, type ProxyOptions } from "./proxy.ts";
-export type { Access, ArtifactStore, ContentDomain, Grant, PortholeServer, ServerOptions, TicketRecord, TicketStore, Upstream, } from "./types.ts";
+export type { Access, ArtifactStore, AuthorizeAnswer, AuthorizeRequest, Authorizer, ContentDomain, Grant, PortholeServer, ServerOptions, TicketRecord, TicketStore, Upstream, } from "./types.ts";

package/dist/server/index.js

@@ -9,12 +9,18 @@
  *
  * and calls `issue` from its own authenticated API when a viewer opens served content.
  *
+ * Runs on any runtime with web-standard `Request`/`Response` and `crypto.getRandomValues`: Node,
+ * Cloudflare Workers (no `nodejs_compat` needed), Deno, Bun (P044). On Workers, keep tickets in D1
+ * (`d1TicketStore`, P045).
+ *
  * Origins: each storage scope gets `<label>.<domain>`, the label keyed from the scope by the
- * secret (stable, DNS-safe, not guessable from the scope). The domain is a registrable domain the
+ * secret (stable, DNS-safe, not guessable from the scope), or a host's own flat name
+ * (`content.name`, `prefixedName("a-")` for `a-<id>`), with other servers' namespaces reserved (P047). The domain is a registrable domain the
  * host uses for nothing else, so no content origin is ever same-site with the host. Documents go
  * out with their CSP (from the config) plus `frame-ancestors` (the host origins) in headers.
  *
- * Tickets: `issue` mints a one-time ticket for an instance and a viewer, good for a short time;
+ * Tickets: `issue` mints a one-time ticket for an instance and a viewer (or anonymously, for a
+ * public link, P046), good for a short time;
  * the frame's first request carries it, and the content origin takes it (once). A served document
  * comes back in that same answer, with a cookie of that origin only (`__Host-`, `Secure`,
  * `HttpOnly`, `SameSite=None; Partitioned` in a frame) for what follows; a url-mode app's ticket
@@ -22,5 +28,7 @@
  * content without a valid ticket or cookie gets nothing of the content.
  */
 export { createServer } from "./server.js";
-export { memoryTicketStore } from "./tickets.js";
+export { d1TicketSchema, d1TicketStore, memoryTicketStore, } from "./tickets.js";
+export { FRAME_STATUS_METHOD } from "../isolation/types.js";
+export { isHostLabel, prefixedName } from "./naming.js";
 export { proxyTo } from "./proxy.js";

package/dist/server/keys.js

@@ -1,4 +1,4 @@
-import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { base64url, fromBase64url, fromUtf8, hmacSha256, randomBytes, sha256, timingSafeEqual, utf8, } from "./crypto.js";
 /**
  * The server's secrets, derived from the one it is given: one key per use, so a value made for
  * one (a label) can never stand in for another (a cookie's signature).
@@ -23,7 +23,6 @@ export function base32(bytes) {
     }
     return out;
 }
-const base64url = (bytes) => Buffer.from(bytes).toString("base64url");
 /** JSON with object keys in a fixed order, so equal values always serialize alike. */
 export function canonicalJson(value) {
     if (Array.isArray(value)) {
@@ -41,16 +40,16 @@ export function createKeys(secret) {
     if (secret.byteLength < 32) {
         throw new TypeError("The server's secret must be at least 32 random bytes");
     }
-    const derive = (use) => createHmac("sha256", secret).update(`porthole/${use}`).digest();
+    const derive = (use) => hmacSha256(secret, utf8(`porthole/${use}`));
     const labelKey = derive("label");
     const instanceKey = derive("instance");
     const signKey = derive("session");
-    const mac = (key, text) => createHmac("sha256", key).update(text).digest();
+    const mac = (key, text) => hmacSha256(key, utf8(text));
     return {
         label: (scope) => base32(mac(labelKey, scope).subarray(0, 15)),
         instanceKey: (instance) => base32(mac(instanceKey, canonicalJson(instance)).subarray(0, 10)),
         sign: (value) => {
-            const payload = Buffer.from(JSON.stringify(value)).toString("base64url");
+            const payload = base64url(utf8(JSON.stringify(value)));
             return `${payload}.${base64url(mac(signKey, payload))}`;
         },
         verify: (token) => {
@@ -59,12 +58,16 @@ export function createKeys(secret) {
                 return null;
             }
             const expected = mac(signKey, payload);
-            const given = Buffer.from(signature, "base64url");
-            if (given.length !== expected.length || !timingSafeEqual(given, expected)) {
+            const given = fromBase64url(signature);
+            if (given === null || !timingSafeEqual(given, expected)) {
+                return null;
+            }
+            const bytes = fromBase64url(payload);
+            if (bytes === null) {
                 return null;
             }
             try {
-                return JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+                return JSON.parse(fromUtf8(bytes));
             }
             catch {
                 return null;
@@ -75,4 +78,4 @@ export function createKeys(secret) {
 /** A fresh one-time ticket: 160 random bits. */
 export const newTicket = () => `pt_${base32(randomBytes(20))}`;
 /** What a ticket is stored under: its hash, so a leaked store holds no usable ticket. */
-export const ticketId = (ticket) => createHash("sha256").update(ticket).digest("base64url");
+export const ticketId = (ticket) => base64url(sha256(utf8(ticket)));

package/dist/server/naming.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Names for content origins a host chooses itself (P047): flat labels like `a-<id>` under a
+ * shared content domain, next to other servers' namespaces (`<instance>.f.<domain>`).
+ */
+/**
+ * Whether a label is one a host may name a content origin with: one lowercase DNS label, and not
+ * of the form IDNA reserves (`xn--`, any `??--`), so a name never displays as something else.
+ */
+export declare function isHostLabel(label: unknown): label is string;
+/**
+ * A naming for `content.name` that puts each scope on `<prefix><scope>` (`prefixedName("a-")`:
+ * scope `k3x9` is served on `a-k3x9.<domain>`). One-to-one, so no two scopes share an origin, and
+ * no name it makes is a reserved one or a keyed default (those have no hyphen). Scopes must
+ * already be label-safe (lowercase letters, digits, inner hyphens); anything else throws rather
+ * than being folded into another scope's name.
+ */
+export declare function prefixedName(prefix: string): (scope: string) => string;

package/dist/server/naming.js

@@ -0,0 +1,34 @@
+/**
+ * Names for content origins a host chooses itself (P047): flat labels like `a-<id>` under a
+ * shared content domain, next to other servers' namespaces (`<instance>.f.<domain>`).
+ */
+/** One lowercase DNS label (a-z 0-9 -, at most 63, no hyphen at either end). */
+const DNS_LABEL = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/u;
+/**
+ * Whether a label is one a host may name a content origin with: one lowercase DNS label, and not
+ * of the form IDNA reserves (`xn--`, any `??--`), so a name never displays as something else.
+ */
+export function isHostLabel(label) {
+    return typeof label === "string" && DNS_LABEL.test(label) && label.slice(2, 4) !== "--";
+}
+const PREFIX = /^[a-z][a-z0-9]{0,15}-$/u;
+const ID = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/u;
+/**
+ * A naming for `content.name` that puts each scope on `<prefix><scope>` (`prefixedName("a-")`:
+ * scope `k3x9` is served on `a-k3x9.<domain>`). One-to-one, so no two scopes share an origin, and
+ * no name it makes is a reserved one or a keyed default (those have no hyphen). Scopes must
+ * already be label-safe (lowercase letters, digits, inner hyphens); anything else throws rather
+ * than being folded into another scope's name.
+ */
+export function prefixedName(prefix) {
+    if (!PREFIX.test(prefix)) {
+        throw new TypeError("A name prefix is a lowercase letter, then letters or digits, then '-' (a-)");
+    }
+    return (scope) => {
+        const label = `${prefix}${scope}`;
+        if (!ID.test(scope) || !isHostLabel(label)) {
+            throw new TypeError(`Scope ${JSON.stringify(scope)} can't be named under ${prefix}: lowercase letters, digits and inner hyphens, ${63 - prefix.length} at most`);
+        }
+        return label;
+    };
+}

package/dist/server/pages.d.ts

@@ -6,6 +6,6 @@ export declare const ENTER_SCRIPT_PATH = "/__porthole/enter.js";
 export declare const SESSION_PATH = "/__porthole/session";
 /** The pages' scripts, by path: served with the pages' own policy in mind (`script-src 'self'`). */
 export declare function pageScript(pathname: string): Response | null;
-export declare function statusPage(status: number, title: string, detail: string, frameAncestors: string, method?: string, reason?: FrameBlock, hostOrigins?: readonly string[]): Response;
+export declare function statusPage(status: number, title: string, detail: string, frameAncestors: string, method?: string, reason?: FrameBlock, hostOrigins?: readonly string[], code?: string): Response;
 /** The page a framed app is entered through (its answer also sets the session cookie). */
 export declare function enterPage(target: string, frameAncestors: string, hostOrigins: readonly string[], cookie: string): Response;

package/dist/server/pages.js

@@ -20,12 +20,14 @@ const STATUS_SCRIPT = `(() => {
   if (main === null) return;
   const hosts = JSON.parse(main.dataset.portholeHosts || "[]");
   ${say()}
-  say({ state: "blocked", reason: main.dataset.portholeReason || "error", status: Number(main.dataset.portholeStatus) });
+  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 goes on to the app, or says it
- * is blocked and why.
+ * 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]");
@@ -38,6 +40,12 @@ const ENTER_SCRIPT = `(async () => {
     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;
   }
@@ -70,8 +78,8 @@ const pageHeaders = (frameAncestors, connect) => ({
     "referrer-policy": "no-referrer",
     "x-content-type-options": "nosniff",
 });
-export function statusPage(status, title, detail, frameAncestors, method = "GET", reason = "error", hostOrigins = []) {
-    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)}" data-porthole-hosts="${escape(JSON.stringify(hostOrigins))}"><h1>${escape(title)}</h1><p>${escape(detail)}</p></main><script src="${STATUS_SCRIPT_PATH}"></script></body></html>`;
+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: pageHeaders(frameAncestors, false),

package/dist/server/server.js

@@ -2,6 +2,7 @@ import { compile } from "../compile/compile.js";
 import { hostOriginProblem, maybeSameSite, originMatchesSource, parseOrigin, } from "../isolation/served.js";
 import { sandboxProxyDocument } from "../mcp/proxy.js";
 import { createKeys, newTicket, ticketId } from "./keys.js";
+import { isHostLabel } from "./naming.js";
 import { enterPage, pageScript, SESSION_PATH, statusPage } from "./pages.js";
 import { memoryTicketStore } from "./tickets.js";
 /**
@@ -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,6 +174,12 @@ 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");
     }
@@ -177,7 +206,54 @@ export function createServer(options) {
     }
     const tickets = options.tickets ?? memoryTicketStore();
     /** 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") => statusPage(status, title, detail, frameAncestors, method, reason, options.hostOrigins);
+    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);
@@ -271,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 [
@@ -294,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;
@@ -304,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;
@@ -325,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;
@@ -359,12 +452,18 @@ 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, "session");
         }
+        const refusal = await denied(request, access);
+        if (refusal !== null) {
+            return refusal;
+        }
         const served = await documentOf(access.instance);
         if (served === null) {
             return page(404, "Not found", "This page, or this version of it, doesn't exist.", method);
@@ -384,6 +483,16 @@ export function createServer(options) {
         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.", 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
@@ -440,6 +549,10 @@ export function createServer(options) {
         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, "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);
         }
@@ -463,34 +576,62 @@ 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}`;
@@ -498,7 +639,11 @@ export function createServer(options) {
         },
         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);
@@ -508,7 +653,7 @@ 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) {
@@ -520,10 +665,9 @@ export function createServer(options) {
                 }
                 if (url.pathname === SESSION_PATH) {
                     // Whether this request's cookie opens its origin's app: the entry page asks.
-                    return new Response(null, {
-                        status: accessOf(request, label, null) === null ? 401 : 204,
-                        headers: { "cache-control": "no-store" },
-                    });
+                    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) {

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