@botiverse/porthole 0.1.1 → 0.1.2

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

package/dist/server/types.d.ts

@@ -10,11 +10,41 @@ export interface ContentDomain {
     /** `http` only for `localhost`. */
     readonly scheme: "https" | "http";
     readonly port?: number;
+    /**
+     * The label under `domain` a storage scope is served on (P047). Default: 24 base32 characters
+     * keyed from the scope with the server's secret (stable, not guessable). A host's own (flat
+     * names like `a-<id>`) must return one lowercase DNS label, the same for the same scope, a
+     * different one for a different scope, and never a `reserved` one.
+     */
+    readonly name?: (scope: string) => string;
+    /**
+     * Labels this server never serves or names (another server's namespace under the same domain,
+     * `f` for `<instance>.f.<domain>`, or `www`). Requests for them get null (the host's routes).
+     */
+    readonly reserved?: readonly string[];
 }
-/** Who may open an instance, decided by the host before it calls `issue`. */
-export interface Grant {
+/**
+ * Who may open an instance, decided by the host before it calls `issue`: a viewer the host
+ * knows, or (a public link) nobody in particular. Porthole never interprets either: identity and
+ * authorization policy are the host's (P050).
+ */
+export type Grant = ({
     /** The host's id for the viewer: recorded with the ticket, never shown to content. */
     readonly viewer: string;
+    readonly anonymous?: never;
+} | {
+    /**
+     * A public link: no viewer (P046). Only for documents (a shell, an artifact version, the
+     * sandbox proxy), never for a url-mode app.
+     */
+    readonly anonymous: true;
+    readonly viewer?: never;
+}) & {
+    /**
+     * The host's own opaque claim, carried in the ticket and the session cookie and handed back to
+     * `authorize` on every request (a session id, a share id). At most 512 characters.
+     */
+    readonly subject?: string;
     /** How long the ticket is good for, seconds (default 60). */
     readonly ttlSeconds?: number;
     /**
@@ -22,10 +52,13 @@ export interface Grant {
      * url-mode app's every request, rides on.
      */
     readonly sessionSeconds?: number;
-}
+};
 export interface TicketRecord {
     readonly instance: InstanceRef;
+    /** The grant's viewer; "" for an anonymous grant. */
     readonly viewer: string;
+    readonly anonymous?: boolean;
+    readonly subject?: string;
     /** Epoch milliseconds. */
     readonly expiresAt: number;
     /** The grant's `sessionSeconds`, if it set one. */
@@ -46,7 +79,11 @@ export interface ArtifactStore {
 /** What a request's cookie lets in: one instance, for one viewer, on one origin, until a time. */
 export interface Access {
     readonly instance: InstanceRef;
+    /** The grant's viewer; "" for an anonymous one. */
     readonly viewer: string;
+    readonly anonymous?: boolean;
+    /** The grant's opaque subject, if it had one. */
+    readonly subject?: string;
     /** The content origin the access is for. */
     readonly origin: string;
     /** When the cookie stops being good, epoch milliseconds. */
@@ -58,6 +95,37 @@ export interface Access {
  * Porthole's cookie; the answer gets `frame-ancestors` added, and loses any cookie named as ours.
  */
 export type Upstream = (request: Request, access: Access) => Response | Promise<Response>;
+/** What `authorize` is asked about: a request the cookie (or ticket) let in. */
+export interface AuthorizeRequest {
+    readonly scope: string;
+    readonly instance: InstanceRef;
+    readonly viewer: string;
+    readonly anonymous: boolean;
+    readonly subject?: string;
+    /** The request itself (its path, method; never its Porthole cookie's value). */
+    readonly request: Request;
+}
+/** The host's answer: let it in, or not (with a short reason code for the host's own UI). */
+export type AuthorizeAnswer = {
+    readonly allow: true;
+} | {
+    readonly allow: false;
+    /** A short code (`revoked`, `left-workspace`): lowercase letters, digits and dashes. */
+    readonly code?: string;
+};
+/**
+ * The host's check on every request its cookie lets in (P050): revocation, membership,
+ * liveness. Porthole calls it after the cookie (or ticket) verifies and before anything of the
+ * content is served; a deny is a 403 page that tells the host why (`blocked: denied`).
+ */
+export interface Authorizer {
+    check(request: AuthorizeRequest): AuthorizeAnswer | Promise<AuthorizeAnswer>;
+    /**
+     * How long an answer may be reused for the same session and scope, seconds. Default 0: asked
+     * on every request. A host opts into a short time for apps with many requests.
+     */
+    readonly ttlSeconds?: number;
+}
 export interface ServerOptions {
     readonly content: ContentDomain;
     /** At least 32 random bytes: keys the labels and signs tickets and cookies. */
@@ -73,6 +141,8 @@ export interface ServerOptions {
     readonly tickets?: TicketStore;
     /** Url mode: where an external instance's requests go once let in. Absent: nothing serves them. */
     readonly upstream?: Upstream;
+    /** The host's per-request check (P050). Absent: a good cookie is enough until it ends. */
+    readonly authorize?: Authorizer;
 }
 export interface PortholeServer {
     /**
@@ -88,8 +158,9 @@ export interface PortholeServer {
      */
     issue(instance: InstanceRef, grant: Grant): Promise<FrameLocation>;
     /**
-     * The access a request's cookie carries for a url-mode app on the request's origin, or null:
-     * for a host's own WebSocket upgrade path, which a fetch-style handler can't take.
+     * The access a request's cookie carries for a url-mode app on the request's origin, or null
+     * (no good cookie, or the host's check denies it): for a host's own WebSocket upgrade path,
+     * which a fetch-style handler can't take.
      */
     access(request: Request): Promise<Access | null>;
     /** The frame source every content origin matches (`https://*.example-usercontent.com`). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botiverse/porthole",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "A host-side sandbox for agent-made HTML: isolation, egress hardening, a themed shell, gated host functions, and the agent manual, from one config.",
   "license": "Apache-2.0",
   "files": [
@@ -41,6 +41,7 @@
     "@types/react": "19.3.0",
     "@types/react-dom": "19.3.0",
     "esbuild": "0.28.2",
+    "miniflare": "4.20260730.0",
     "react": "19.3.0",
     "react-dom": "19.3.0",
     "typescript": "7.0.2"

package/src/compile/policy.ts

@@ -100,10 +100,11 @@ export function sandboxTokens(config: PortholeConfig): string[] {
 
 /**
  * The frame's `allow` attribute (Permissions Policy). Empty: no camera, microphone, geolocation,
- * clipboard, fullscreen or other powerful feature is delegated to the frame.
+ * clipboard, fullscreen or other powerful feature is delegated to the frame; a url-mode config
+ * may delegate clipboard writes and full screen to the app's own origin (P049).
  */
-export function allowAttribute(_config: PortholeConfig): string {
-  return "";
+export function allowAttribute(config: PortholeConfig): string {
+  return config.mode === "url" ? (config.permissions ?? []).join("; ") : "";
 }
 
 /**

package/src/config/schema.ts

@@ -116,6 +116,14 @@ export const URL_SANDBOX_EXTRAS = [
 
 export type UrlSandboxExtra = (typeof URL_SANDBOX_EXTRAS)[number];
 
+/**
+ * Powerful features a url-mode frame may be delegated, by the host's choice (P049): writing the
+ * clipboard (a "copy" button in the person's app) and going full screen. Nothing for other modes.
+ */
+export const URL_PERMISSIONS = ["clipboard-write", "fullscreen"] as const;
+
+export type UrlPermission = (typeof URL_PERMISSIONS)[number];
+
 /** Where the host shows the content, for the manual's size rules. */
 export interface LayoutConfig {
   /** The narrowest the frame ever is (a small phone). */
@@ -165,4 +173,6 @@ export interface PortholeConfig {
   readonly embedder: EmbedderConfig;
   /** Url mode only: sandbox tokens added to its baseline (`URL_SANDBOX_EXTRAS`). */
   readonly sandbox?: readonly UrlSandboxExtra[];
+  /** Url mode only: features delegated to the frame (`URL_PERMISSIONS`); none by default. */
+  readonly permissions?: readonly UrlPermission[];
 }

package/src/config/validate.ts

@@ -1,5 +1,5 @@
 import { CAPABILITY_NAMES, isCapabilityName, type Gate } from "./capabilities.ts";
-import { URL_SANDBOX_EXTRAS, type PortholeConfig } from "./schema.ts";
+import { URL_PERMISSIONS, URL_SANDBOX_EXTRAS, type PortholeConfig } from "./schema.ts";
 
 /**
  * Checks a config before anything is derived from it. Every string that ends up in a CSP, an
@@ -130,6 +130,7 @@ export function validateConfig(input: unknown): PortholeConfig {
       "contentOrigins",
       "embedder",
       "sandbox",
+      "permissions",
     ],
     "config",
   );
@@ -314,5 +315,19 @@ export function validateConfig(input: unknown): PortholeConfig {
     });
   }
 
+  if (config.permissions !== undefined) {
+    if (config.mode !== "url") {
+      fail("config.permissions", "only url mode may be delegated features");
+    }
+    if (!Array.isArray(config.permissions)) {
+      fail("config.permissions", "must be an array of features");
+    }
+    (config.permissions as unknown[]).forEach((feature, index) => {
+      if (!(URL_PERMISSIONS as readonly unknown[]).includes(feature)) {
+        fail(`config.permissions[${index}]`, `must be one of ${URL_PERMISSIONS.join(", ")}`);
+      }
+    });
+  }
+
   return input as PortholeConfig;
 }