@botiverse/porthole 0.1.0 → 0.1.2

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/dist/shell/document.d.ts

@@ -2,8 +2,9 @@ import type { ShellPlan } from "./plan.ts";
 export interface ShellDocumentOptions {
     /**
      * The origins the shell takes messages from: the embedding page's own (`location.origin`), or
-     * every host origin a served document may be embedded by. Exact origins, no wildcards. The
-     * sender must also be the frame's parent.
+     * every host origin a served document may be embedded by. Exact origins of any scheme (a
+     * desktop app's own, `ferry://app`), no wildcards, never "null". The sender must also be the
+     * frame's parent.
      */
     readonly origins: readonly string[];
     /** The frame document's title (for assistive technology inside the frame). */

package/dist/shell/document.js

@@ -1,5 +1,5 @@
+import { hostOriginProblem } from "../isolation/served.js";
 import { SHELL_RUNTIME } from "./runtime.js";
-const EXACT_ORIGIN = /^(https?:\/\/[a-z0-9.-]+(:\d{1,5})?|https?:\/\/\[::1\](:\d{1,5})?)$/u;
 const escapeAttribute = (value) => value.replace(/&/gu, "&amp;").replace(/"/gu, "&quot;").replace(/</gu, "&lt;");
 const escapeText = (value) => value.replace(/&/gu, "&amp;").replace(/</gu, "&lt;").replace(/>/gu, "&gt;");
 /** JSON that is safe inside a `<script>`: no `</script>`, no `<!--`. */
@@ -47,8 +47,9 @@ body {
  */
 export function shellDocument(plan, csp, options) {
     for (const origin of options.origins) {
-        if (!EXACT_ORIGIN.test(origin)) {
-            throw new TypeError(`shellDocument: ${JSON.stringify(origin)} is not an exact origin`);
+        const problem = hostOriginProblem(origin);
+        if (problem !== null) {
+            throw new TypeError(`shellDocument: ${problem}`);
         }
     }
     const runtime = SHELL_RUNTIME.replace("__PLAN__", () => scriptJson({

package/dist/shell/plan.d.ts

@@ -26,6 +26,8 @@ export interface ShellPlan {
     readonly themeVariables: readonly string[];
     /** The window event fired after a theme change. */
     readonly themeEvent: string;
+    /** Whether a whole document takes the person's scheme: when it declares it, or always. */
+    readonly themeDocuments: "declared" | "always";
     /** `memory`: an opaque origin has no storage, so a map stands in for the frame's life. */
     readonly storage: "memory" | "native";
     readonly maxErrorReports: number;

package/dist/shell/plan.js

@@ -26,6 +26,7 @@ export function shellPlan(config) {
         globals,
         themeVariables: Object.keys(config.theme.variables),
         themeEvent: config.theme.event,
+        themeDocuments: config.theme.documents ?? "declared",
         storage: config.isolation === "opaque" ? "memory" : "native",
         maxErrorReports: config.limits.maxErrorReports,
         maxPromptChars: config.limits.maxPromptChars,

package/dist/shell/runtime.js

@@ -487,6 +487,21 @@ export const SHELL_RUNTIME = String.raw `(() => {
     window.dispatchEvent(new Event("load"));
   };
 
+  // A fragment takes the person's scheme; a whole document only if it declares that it supports
+  // both (or the config says always), else it shows as its author styled it (P039).
+  let lastContext = null;
+  let themed = plan.content !== "document";
+  const schemeFollows = () => {
+    const root = document.documentElement;
+    const theme = lastContext && lastContext.theme;
+    if (themed && (theme === "light" || theme === "dark")) {
+      root.style.colorScheme = theme;
+      root.setAttribute("data-theme", theme);
+    } else {
+      root.style.removeProperty("color-scheme");
+      root.removeAttribute("data-theme");
+    }
+  };
   // A whole document, parsed inert (no scripts run, no declarative shadow roots built), guarded,
   // imported in place of the shell's, then its scripts run in order. The theme on the root stays.
   const renderDocument = async (html) => {
@@ -502,6 +517,9 @@ export const SHELL_RUNTIME = String.raw `(() => {
     document.head.replaceChildren(...Array.from(parsed.head.childNodes, (node) => document.importNode(node, true)));
     document.body.replaceWith(document.importNode(parsed.body, true));
     root = null;
+    const declaredScheme = parsed.querySelector('meta[name="color-scheme" i]');
+    themed = plan.themeDocuments === "always" || (declaredScheme !== null && /\bdark\b/i.test(declaredScheme.getAttribute("content") || ""));
+    schemeFollows();
     await runScripts(scripts);
     announceLoaded();
   };
@@ -554,10 +572,8 @@ export const SHELL_RUNTIME = String.raw `(() => {
         }
       }
     }
-    if (context.theme === "light" || context.theme === "dark") {
-      document.documentElement.style.colorScheme = context.theme;
-      document.documentElement.setAttribute("data-theme", context.theme);
-    }
+    lastContext = context;
+    schemeFollows();
     window.dispatchEvent(new CustomEvent(plan.themeEvent, { detail: { theme: context.theme } }));
   };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botiverse/porthole",
-  "version": "0.1.0",
+  "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,24 +41,17 @@
     "@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"
   },
   "peerDependencies": {
-    "@modelcontextprotocol/ext-apps": ">=2.0.0",
-    "@playwright/test": ">=1.63.0",
     "react": ">=19"
   },
   "peerDependenciesMeta": {
-    "@playwright/test": {
-      "optional": true
-    },
     "react": {
       "optional": true
-    },
-    "@modelcontextprotocol/ext-apps": {
-      "optional": true
     }
   },
   "engines": {

package/src/bridge/bridge.ts

@@ -11,6 +11,7 @@ import type {
   CapabilityHandler,
   CapabilityHandlers,
   Confirm,
+  ConfirmAnswer,
   ConfirmRequest,
   HostFunctionBridge,
   Refusal,
@@ -204,17 +205,28 @@ export function createBridge(options: BridgeOptions): HostFunctionBridge {
           return refuse<Result>(capability, "no-user-activation");
         }
       }
+      // The effect, run once: when the person's "yes" calls `proceed` (inside its own click, so an
+      // effect that needs a gesture gets one), or after `confirm` resolves accepted.
+      let effect: Promise<CallOutcome<Result>> | null = null;
+      const run = (): Promise<CallOutcome<Result>> => (effect ??= perform(capability, args));
       if (confirms) {
         if (options.confirm === undefined) {
           return refuse<Result>(capability, "no-confirm");
         }
-        let accepted = false;
+        let answer: ConfirmAnswer = false;
         try {
-          accepted = await options.confirm({ capability, args, display } as ConfirmRequest);
+          answer = await options.confirm(
+            { capability, args, display } as ConfirmRequest,
+            () => void run(),
+          );
         } catch {
-          accepted = false;
+          answer = effect === null ? false : "accepted";
         }
-        if (!accepted) {
+        if (effect === null && answer !== true && answer !== "accepted") {
+          if (answer === "redirected") {
+            return refuse<Result>(capability, "redirected");
+          }
+          // Declines in a row mute the display; a yes starts the count again.
           declines += 1;
           if (declines >= config.limits.declinesBeforeMute && !muted) {
             muted = true;
@@ -222,8 +234,18 @@ export function createBridge(options: BridgeOptions): HostFunctionBridge {
           }
           return refuse<Result>(capability, "declined");
         }
+        declines = 0;
       }
+      return run();
+    },
+  };
 
+  async function perform<N extends CapabilityName>(
+    capability: N,
+    args: CapabilityArgs[N],
+  ): Promise<CallOutcome<CapabilityResults[N]>> {
+    type Result = CapabilityResults[N];
+    {
       if (capabilitySpec(capability).served === "event") {
         if (capability === "resize") {
           const size = args as CapabilityArgs["resize"];
@@ -251,6 +273,6 @@ export function createBridge(options: BridgeOptions): HostFunctionBridge {
           error instanceof Error ? error.message : String(error),
         );
       }
-    },
-  };
+    }
+  }
 }

package/src/bridge/types.ts

@@ -38,10 +38,26 @@ export type ConfirmRequest = {
 }[CapabilityName];
 
 /**
- * Asks a person. Resolves true only if they accept. The host's UI, or the React binding's default
- * dialog; drawn outside the frame, never inside it.
+ * What the person chose. `true`/`"accepted"`: the call goes. `false`/`"declined"`: it doesn't,
+ * and the decline counts toward muting the display. `"redirected"`: it doesn't go, but the person
+ * took it elsewhere (edited the prompt first, say), so it neither counts as a decline nor resets
+ * the count. The host decides which its UI's choices are.
  */
-export type Confirm = (request: ConfirmRequest) => Promise<boolean>;
+export type ConfirmAnswer = boolean | "accepted" | "declined" | "redirected";
+
+/**
+ * Runs the call's effect now, inside the caller's own gesture, and counts as accepted. A host
+ * whose effect needs the person's gesture (opening a window) calls it from the click handler of
+ * its own "yes" button, rather than resolving the promise and letting the effect run after.
+ */
+export type Proceed = () => void;
+
+/**
+ * Asks a person. Resolves with their answer. The host's UI, or the React binding's default
+ * dialog; drawn outside the frame, never inside it. `proceed` (optional to use) runs the effect
+ * within the "yes" click itself.
+ */
+export type Confirm = (request: ConfirmRequest, proceed: Proceed) => Promise<ConfirmAnswer>;
 
 /** Why a call didn't run. */
 export type Refusal =
@@ -55,6 +71,8 @@ export type Refusal =
   | "no-confirm"
   /** The person declined. */
   | "declined"
+  /** The person took it elsewhere (edited it first): not sent, not counted as a decline. */
+  | "redirected"
   /** The display was muted after too many declines (until it runs again). */
   | "muted"
   | "rate-limited"

package/src/compile/policy.ts

@@ -93,16 +93,18 @@ export function sandboxTokens(config: PortholeConfig): string[] {
     case "domain":
       return ["allow-scripts", "allow-same-origin"];
     case "external":
-      return ["allow-scripts", "allow-same-origin", "allow-forms"];
+      // The host may add a documented few (popups, modals, downloads), never top navigation.
+      return ["allow-scripts", "allow-same-origin", "allow-forms", ...(config.sandbox ?? [])];
   }
 }
 
 /**
  * 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("; ") : "";
 }
 
 /**
@@ -119,15 +121,11 @@ export function embedderFrameSources(config: PortholeConfig): string[] {
 
 /**
  * The CSP the embedding page sends (a header, or the host's own document's policy), for every kind
- * of display it shows. It sets no `default-src`: it restricts frames only, leaving the host's own
- * scripts, styles and fetches to the host's policy. `child-src` repeats `frame-src` for engines
- * that read frames from it.
+ * of display it shows. Frames only: no `default-src`, so the host's own scripts, styles and
+ * fetches stay its policy's; and no `child-src`, which the host's workers would fall back to (every
+ * engine Porthole supports reads frames from `frame-src`, P038).
  */
 export function embedderCsp(configs: readonly PortholeConfig[]): string {
   const sources = unique(configs.flatMap(embedderFrameSources));
-  const all = sources.length === 0 ? ["'none'"] : sources;
-  return serializeCsp([
-    ["frame-src", ...all],
-    ["child-src", ...all],
-  ]);
+  return serializeCsp([["frame-src", ...(sources.length === 0 ? ["'none'"] : sources)]]);
 }

package/src/config/schema.ts

@@ -71,6 +71,13 @@ export interface ThemeConfig {
   readonly variables: Readonly<Record<string, ThemeValue>>;
   /** The window event the shell fires after the theme changed, for code that must redraw. */
   readonly event: string;
+  /**
+   * Whether a whole document (an artifact page) takes the person's light or dark scheme:
+   * `declared` (default): only a page that declares it supports both
+   * (`<meta name="color-scheme" content="light dark">`); any other page shows as its author
+   * styled it, in light. `always`: every page. The variables are there either way.
+   */
+  readonly documents?: "declared" | "always";
 }
 
 export interface Limits {
@@ -88,8 +95,35 @@ export interface Limits {
   readonly maxPromptChars: number;
   /** The most errors one run of a display reports. */
   readonly maxErrorReports: number;
+  /**
+   * How long a display may take to load before its outcome is a timeout (ms). Optional; 15 s
+   * when absent.
+   */
+  readonly loadTimeoutMs?: number;
 }
 
+/**
+ * Sandbox tokens a url-mode frame may add to its baseline, by the host's choice (P037): a
+ * person's own running app (a dev server's preview) may need popups (an OAuth flow), modals and
+ * downloads. Never top navigation, and nothing for other modes.
+ */
+export const URL_SANDBOX_EXTRAS = [
+  "allow-popups",
+  "allow-popups-to-escape-sandbox",
+  "allow-modals",
+  "allow-downloads",
+] as const;
+
+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). */
@@ -137,4 +171,8 @@ export interface PortholeConfig {
    */
   readonly contentOrigins: readonly string[];
   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 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
@@ -30,24 +30,30 @@ const HOST =
  * every subdomain) and an optional port, nothing else. Insecure schemes only for loopback names.
  */
 export function isOriginSource(value: unknown): value is string {
+  return originSourceProblem(value) === null;
+}
+
+/** Why `value` isn't an origin source Porthole accepts, in words to act on; null if it is. */
+export function originSourceProblem(value: unknown): string | null {
+  const shape = "is not an origin (scheme://host[:port], lowercase, no path)";
   if (typeof value !== "string" || value.length > 253 + 16) {
-    return false;
+    return `${JSON.stringify(value)} ${shape}`;
   }
   const match = /^(https|http|wss|ws):\/\/([^/:]+|\[::1\])(:(\d{1,5}))?$/u.exec(value);
   if (match === null) {
-    return false;
+    return `${JSON.stringify(value)} ${shape}`;
   }
   const [, scheme, host = "", , port] = match;
   if (port !== undefined && (Number(port) < 1 || Number(port) > 65_535)) {
-    return false;
+    return `${JSON.stringify(value)} has no valid port`;
   }
   if (host !== "[::1]" && !HOST.test(host)) {
-    return false;
+    return `${JSON.stringify(value)} ${shape}`;
   }
   if ((scheme === "http" || scheme === "ws") && !LOOPBACK.test(host.replace(/^\*\./u, "x."))) {
-    return false;
+    return `${JSON.stringify(value)} uses ${scheme} off loopback: ${scheme} is allowed only for localhost, *.localhost, 127.0.0.1 and [::1] (loopback development); use ${scheme === "http" ? "https" : "wss"}`;
   }
-  return true;
+  return null;
 }
 
 const fail = (path: string, message: string): never => {
@@ -78,11 +84,9 @@ function sources(value: unknown, path: string): void {
     return;
   }
   value.forEach((source, index) => {
-    if (!isOriginSource(source)) {
-      fail(
-        `${path}[${index}]`,
-        `${JSON.stringify(source)} is not an origin (scheme://host[:port], lowercase, no path)`,
-      );
+    const problem = originSourceProblem(source);
+    if (problem !== null) {
+      fail(`${path}[${index}]`, problem);
     }
   });
 }
@@ -125,6 +129,8 @@ export function validateConfig(input: unknown): PortholeConfig {
       "guide",
       "contentOrigins",
       "embedder",
+      "sandbox",
+      "permissions",
     ],
     "config",
   );
@@ -173,7 +179,14 @@ export function validateConfig(input: unknown): PortholeConfig {
   }
 
   const theme = object(config.theme, "config.theme");
-  only(theme, ["variables", "event"], "config.theme");
+  only(theme, ["variables", "event", "documents"], "config.theme");
+  if (
+    theme.documents !== undefined &&
+    theme.documents !== "declared" &&
+    theme.documents !== "always"
+  ) {
+    fail("config.theme.documents", 'must be "declared" or "always"');
+  }
   const variables = object(theme.variables, "config.theme.variables");
   for (const [name, value] of Object.entries(variables)) {
     const path = `config.theme.variables[${JSON.stringify(name)}]`;
@@ -212,10 +225,13 @@ export function validateConfig(input: unknown): PortholeConfig {
     "maxPromptChars",
     "maxErrorReports",
   ];
-  only(limits, limitNames, "config.limits");
+  only(limits, [...limitNames, "loadTimeoutMs"], "config.limits");
   for (const name of limitNames) {
     positive(limits[name], `config.limits.${name}`);
   }
+  if (limits.loadTimeoutMs !== undefined) {
+    positive(limits.loadTimeoutMs, "config.limits.loadTimeoutMs", 600_000);
+  }
   if ((limits.minHeightPx as number) > (limits.maxHeightPx as number)) {
     fail("config.limits.minHeightPx", "must not exceed maxHeightPx");
   }
@@ -280,5 +296,38 @@ export function validateConfig(input: unknown): PortholeConfig {
     "config.embedder.frameSrc",
   );
 
+  if (config.sandbox !== undefined) {
+    if (config.mode !== "url") {
+      fail("config.sandbox", "only url mode may add sandbox tokens");
+    }
+    if (!Array.isArray(config.sandbox)) {
+      fail("config.sandbox", "must be an array of sandbox tokens");
+    }
+    (config.sandbox as unknown[]).forEach((token, index) => {
+      if (!(URL_SANDBOX_EXTRAS as readonly unknown[]).includes(token)) {
+        fail(
+          `config.sandbox[${index}]`,
+          /top-navigation|same-origin/u.test(String(token))
+            ? `${JSON.stringify(token)} is never granted (P037)`
+            : `must be one of ${URL_SANDBOX_EXTRAS.join(", ")}`,
+        );
+      }
+    });
+  }
+
+  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;
 }