@botiverse/porthole 0.0.1 → 0.1.1

package/LICENSE

@@ -0,0 +1,217 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+
+   Copyright 2026 Botiverse
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/bridge/bridge.d.ts

@@ -0,0 +1,39 @@
+import { type CapabilityName } from "../config/capabilities.ts";
+import type { PortholeConfig } from "../config/schema.ts";
+import type { CapabilityHandlers, Confirm, HostFunctionBridge, Refusal } from "./types.ts";
+/**
+ * The host-function bridge: every capability call from a frame passes here, and nowhere else
+ * reaches a host handler. In order: declared → arguments well formed → not muted → within its
+ * rate → a user gesture, if gated so → a person's confirmation, if gated so → the handler.
+ */
+export type BridgeEvent = {
+    readonly type: "resize";
+    readonly height: number;
+    readonly width?: number;
+} | {
+    readonly type: "error";
+    readonly message: string;
+} | {
+    readonly type: "refused";
+    readonly capability: CapabilityName;
+    readonly refusal: Refusal;
+} | {
+    readonly type: "muted";
+};
+export interface BridgeOptions {
+    readonly config: PortholeConfig;
+    readonly display: {
+        readonly id: string;
+        readonly title: string;
+    };
+    readonly handlers: CapabilityHandlers;
+    readonly confirm?: Confirm;
+    /** Whether the embedding page has user activation now; undefined where it can't tell. */
+    readonly userActivation?: () => boolean | undefined;
+    readonly onEvent: (event: BridgeEvent) => void;
+    /** The clock, in milliseconds (tests pass their own). */
+    readonly now?: () => number;
+}
+/** An http(s) URL without credentials in it (`https://bank.example@evil.example` reads as a lie). */
+export declare function linkTarget(value: unknown): string | null;
+export declare function createBridge(options: BridgeOptions): HostFunctionBridge;

package/dist/bridge/bridge.js

@@ -0,0 +1,198 @@
+import { capabilitySpec, } from "../config/capabilities.js";
+import { effectiveGates } from "../compile/policy.js";
+const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const MAX_URL = 4_096;
+/** An http(s) URL without credentials in it (`https://bank.example@evil.example` reads as a lie). */
+export function linkTarget(value) {
+    if (typeof value !== "string" || value.length === 0 || value.length > MAX_URL) {
+        return null;
+    }
+    let url;
+    try {
+        url = new URL(value.trim());
+    }
+    catch {
+        return null;
+    }
+    if ((url.protocol !== "https:" && url.protocol !== "http:") ||
+        url.username !== "" ||
+        url.password !== "") {
+        return null;
+    }
+    return url.href;
+}
+const VALIDATORS = {
+    sendPrompt: (args, config) => {
+        const text = isRecord(args) ? args.text : undefined;
+        return typeof text === "string" &&
+            text.trim() !== "" &&
+            text.length <= config.limits.maxPromptChars
+            ? { text }
+            : null;
+    },
+    openLink: (args) => {
+        const url = linkTarget(isRecord(args) ? args.url : undefined);
+        return url === null ? null : { url };
+    },
+    downloadFile: (args) => {
+        const contents = isRecord(args) ? args.contents : undefined;
+        return Array.isArray(contents) && contents.length > 0 && contents.length <= 100
+            ? { contents }
+            : null;
+    },
+    callTool: (args) => {
+        if (!isRecord(args) ||
+            typeof args.name !== "string" ||
+            args.name === "" ||
+            args.name.length > 256) {
+            return null;
+        }
+        const given = args.arguments ?? {};
+        return isRecord(given) ? { name: args.name, arguments: given } : null;
+    },
+    readData: (args) => {
+        const uri = isRecord(args) ? args.uri : undefined;
+        return typeof uri === "string" && uri !== "" && uri.length <= MAX_URL ? { uri } : null;
+    },
+    setModelContext: (args) => {
+        if (!isRecord(args)) {
+            return null;
+        }
+        const { content, structuredContent } = args;
+        if ((content !== undefined && !Array.isArray(content)) ||
+            (structuredContent !== undefined && !isRecord(structuredContent))) {
+            return null;
+        }
+        return {
+            ...(content === undefined ? {} : { content }),
+            ...(structuredContent === undefined ? {} : { structuredContent }),
+        };
+    },
+    reportError: (args) => {
+        const message = isRecord(args) ? args.message : undefined;
+        return typeof message === "string" && message !== ""
+            ? { message: message.slice(0, 2_000) }
+            : null;
+    },
+    resize: (args) => {
+        if (!isRecord(args) ||
+            typeof args.height !== "number" ||
+            !Number.isFinite(args.height) ||
+            args.height < 0) {
+            return null;
+        }
+        const width = args.width;
+        return typeof width === "number" && Number.isFinite(width) && width >= 0
+            ? { height: args.height, width }
+            : { height: args.height };
+    },
+};
+export function createBridge(options) {
+    const { config, display, handlers, onEvent } = options;
+    const now = options.now ?? (() => Date.now());
+    const calls = new Map();
+    let declines = 0;
+    let muted = false;
+    const refuse = (capability, refusal, message) => {
+        onEvent({ type: "refused", capability, refusal });
+        return { ok: false, refusal, ...(message === undefined ? {} : { message }) };
+    };
+    const withinRate = (capability, perMinute) => {
+        const at = now();
+        const recent = (calls.get(capability) ?? []).filter((time) => at - time < 60_000);
+        if (recent.length >= perMinute) {
+            calls.set(capability, recent);
+            return false;
+        }
+        recent.push(at);
+        calls.set(capability, recent);
+        return true;
+    };
+    return {
+        declared: (capability) => config.capabilities[capability] !== undefined,
+        async call(capability, raw, callOptions) {
+            if (config.capabilities[capability] === undefined) {
+                return refuse(capability, "not-declared");
+            }
+            const args = VALIDATORS[capability](raw, config);
+            if (args === null) {
+                return refuse(capability, "invalid");
+            }
+            const gates = effectiveGates(config, capability);
+            const confirms = gates.includes("confirm");
+            if (confirms && muted) {
+                return refuse(capability, "muted");
+            }
+            for (const gate of gates) {
+                if (typeof gate === "object" && !withinRate(capability, gate.rateLimit.perMinute)) {
+                    return refuse(capability, "rate-limited");
+                }
+            }
+            if (gates.includes("user-activation")) {
+                const activated = callOptions?.userActivated ?? options.userActivation?.();
+                if (activated === false) {
+                    return refuse(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 = null;
+            const run = () => (effect ??= perform(capability, args));
+            if (confirms) {
+                if (options.confirm === undefined) {
+                    return refuse(capability, "no-confirm");
+                }
+                let answer = false;
+                try {
+                    answer = await options.confirm({ capability, args, display }, () => void run());
+                }
+                catch {
+                    answer = effect === null ? false : "accepted";
+                }
+                if (effect === null && answer !== true && answer !== "accepted") {
+                    if (answer === "redirected") {
+                        return refuse(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;
+                        onEvent({ type: "muted" });
+                    }
+                    return refuse(capability, "declined");
+                }
+                declines = 0;
+            }
+            return run();
+        },
+    };
+    async function perform(capability, args) {
+        {
+            if (capabilitySpec(capability).served === "event") {
+                if (capability === "resize") {
+                    const size = args;
+                    onEvent({ type: "resize", ...size });
+                }
+                else {
+                    onEvent({ type: "error", message: args.message });
+                }
+                return { ok: true, value: undefined };
+            }
+            const handler = handlers[capability];
+            if (handler === undefined) {
+                return refuse(capability, "not-declared");
+            }
+            try {
+                const value = await handler(args, {
+                    displayId: display.id,
+                    title: display.title,
+                    capability,
+                });
+                return { ok: true, value };
+            }
+            catch (error) {
+                return refuse(capability, "failed", error instanceof Error ? error.message : String(error));
+            }
+        }
+    }
+}

package/dist/bridge/types.d.ts

@@ -0,0 +1,83 @@
+import type { CapabilityArgs, CapabilityName, CapabilityResults, HandledCapability } from "../config/capabilities.ts";
+/**
+ * The host-function bridge (ARCHITECTURE § Framework layer): carries a capability call from the
+ * frame to the host's handler and its result back, checking at the boundary that the capability
+ * is declared, that its arguments are well formed, and that every gate passes, in that order.
+ * Adapters decode protocol messages into calls; the bridge alone decides whether they run.
+ */
+/** Which display a call came from. */
+export interface CallContext {
+    readonly displayId: string;
+    /** The display's title, as the host gave it (never the content's words). */
+    readonly title: string;
+    readonly capability: CapabilityName;
+}
+export type CapabilityHandler<N extends CapabilityName> = (args: CapabilityArgs[N], context: CallContext) => CapabilityResults[N] | Promise<CapabilityResults[N]>;
+/** The host's handlers: one for each declared capability served by a handler. */
+export type CapabilityHandlers = {
+    readonly [N in HandledCapability]?: CapabilityHandler<N>;
+};
+/** What a person is asked to confirm: the call's whole effect, not a summary the content chose. */
+export type ConfirmRequest = {
+    [N in CapabilityName]: {
+        readonly capability: N;
+        readonly args: CapabilityArgs[N];
+        readonly display: {
+            readonly id: string;
+            readonly title: string;
+        };
+    };
+}[CapabilityName];
+/**
+ * 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 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 = 
+/** The config doesn't declare it. */
+"not-declared"
+/** Its arguments were malformed (an `openLink` that isn't http(s), an empty prompt). */
+ | "invalid"
+/** It needed a user gesture and had none. */
+ | "no-user-activation"
+/** It needed a confirmation and there is no `confirm` function. */
+ | "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"
+/** The host's handler threw or rejected. */
+ | "failed";
+export type CallOutcome<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly refusal: Refusal;
+    readonly message?: string;
+};
+/** What adapters call; one per display. */
+export interface HostFunctionBridge {
+    /** Validates `args` for `capability`, applies its gates, then runs the host's handler. */
+    call<N extends CapabilityName>(capability: N, args: unknown, options?: {
+        readonly userActivated?: boolean;
+    }): Promise<CallOutcome<CapabilityResults[N]>>;
+    declared(capability: CapabilityName): boolean;
+}

package/dist/bridge/types.js

@@ -0,0 +1 @@
+export {};

package/dist/compile/compile.d.ts

@@ -0,0 +1,35 @@
+import type { PortholeConfig } from "../config/schema.ts";
+import { type GuideTopic } from "../guide/guide.ts";
+import { type ShellDocumentOptions } from "../shell/document.ts";
+import { type ShellPlan } from "../shell/plan.ts";
+import { type CspDirective } from "./policy.ts";
+/**
+ * Everything derived from one config (PRINCIPLE 3): the frame's policies, the shell's wiring and
+ * document, and the agent manual and tool description. Compiled together from a validated config,
+ * so they cannot disagree; the agreement test checks that they don't.
+ */
+export interface CompiledConfig {
+    readonly config: PortholeConfig;
+    /** The frame's CSP, directive by directive; empty in url mode (the app sends its own). */
+    readonly cspDirectives: readonly CspDirective[];
+    /** The frame's CSP: in the shell's `<meta>`, or a served document's header. */
+    readonly csp: string;
+    /** The frame's `sandbox` attribute. */
+    readonly sandbox: string;
+    /** The frame's `allow` attribute (Permissions Policy). */
+    readonly allow: string;
+    /** The frame's `referrerpolicy` attribute. */
+    readonly referrerPolicy: "no-referrer";
+    /** The `frame-src` sources the embedding page must allow (see `embedderCsp`). */
+    readonly embedderFrameSources: readonly string[];
+    /** What the shell wires; null in url mode, which has no shell. */
+    readonly shell: ShellPlan | null;
+    /** The frame's document: the policy, the base styles and the shell's runtime. */
+    shellDocument(options: ShellDocumentOptions): string;
+    /** The agent manual for `topics` (every built-in topic by default). */
+    guide(topics?: readonly GuideTopic[]): string;
+    /** The description of the host's show tool. */
+    toolDescription(): string;
+}
+/** Validates `config` and derives everything from it. Throws a `ConfigError` on a bad config. */
+export declare function compile(config: PortholeConfig): CompiledConfig;

package/dist/compile/compile.js

@@ -0,0 +1,30 @@
+import { validateConfig } from "../config/validate.js";
+import { generateGuide, generateToolDescription } from "../guide/guide.js";
+import { shellDocument } from "../shell/document.js";
+import { shellPlan } from "../shell/plan.js";
+import { allowAttribute, embedderFrameSources, frameCspDirectives, sandboxTokens, serializeCsp, } from "./policy.js";
+/** Validates `config` and derives everything from it. Throws a `ConfigError` on a bad config. */
+export function compile(config) {
+    validateConfig(config);
+    const cspDirectives = frameCspDirectives(config);
+    const csp = serializeCsp(cspDirectives);
+    const shell = shellPlan(config);
+    return {
+        config,
+        cspDirectives,
+        csp,
+        sandbox: sandboxTokens(config).join(" "),
+        allow: allowAttribute(config),
+        referrerPolicy: "no-referrer",
+        embedderFrameSources: embedderFrameSources(config),
+        shell,
+        shellDocument: (options) => {
+            if (shell === null) {
+                throw new TypeError("url mode has no shell: the frame loads the app's own document");
+            }
+            return shellDocument(shell, csp, options);
+        },
+        guide: (topics) => generateGuide(config, topics),
+        toolDescription: () => generateToolDescription(config),
+    };
+}

package/dist/compile/policy.d.ts

@@ -0,0 +1,55 @@
+import { type CapabilityName, type Gate } from "../config/capabilities.ts";
+import type { EgressConfig, PortholeConfig } from "../config/schema.ts";
+/**
+ * The frame's policies, derived from the config: its CSP (in the shell's `<meta>` for opaque
+ * frames, in headers for served ones), its `sandbox` and `allow` attributes, and the `frame-src`
+ * the EMBEDDING page must send. Pure, so a test can tie each source back to the config.
+ */
+/** A CSP directive: its name, then its sources. */
+export type CspDirective = readonly [name: string, ...sources: string[]];
+export type EgressKind = keyof EgressConfig;
+/** The capabilities a config declares, in vocabulary order. */
+export declare function declaredCapabilities(config: PortholeConfig): CapabilityName[];
+/** The gates a declared capability runs under: its own, else the vocabulary's defaults. */
+export declare function effectiveGates(config: PortholeConfig, name: CapabilityName): readonly Gate[];
+/** The origins content may reach for `kind`: the base allowlist plus every declared capability's. */
+export declare function egressOrigins(config: PortholeConfig, kind: EgressKind): string[];
+/** Every origin content may reach, of any kind. */
+export declare function allEgressOrigins(config: PortholeConfig): string[];
+/**
+ * The frame's CSP directives. Closed by default: `default-src 'none'`, and each kind opened only
+ * to the config's origins. Inline code runs (agent content is inline), so the walls are origin
+ * isolation and egress, not script provenance. No `'self'` anywhere: an opaque frame has nothing
+ * of its own to load, and its `'self'` may be the embedding page's origin. Empty for url mode,
+ * whose app serves its own policy.
+ */
+export declare function frameCspDirectives(config: PortholeConfig): CspDirective[];
+export declare function serializeCsp(directives: readonly CspDirective[]): string;
+/**
+ * The frame's `sandbox` tokens. Opaque: scripts only, so the frame is an opaque origin and gets
+ * no forms, popups, downloads, modals or top navigation. Domain: its own origin as well, which is
+ * safe only because that origin is a separate site from the host's (the mount refuses one that
+ * isn't). External (url mode): what a running web app needs to work on its own origin.
+ */
+export declare 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.
+ */
+export declare function allowAttribute(_config: PortholeConfig): string;
+/**
+ * The `frame-src` sources the EMBEDDING page must allow, and nothing else: a frame's own CSP can't
+ * stop it navigating itself to an external URL with data in the query, but the embedding page's
+ * `frame-src` governs every navigation of its frames, including self-initiated ones. `srcdoc`
+ * frames need no source (measured: they load under `frame-src 'none'`), so opaque content gets
+ * none, and can't navigate its frame even to the host's own origin (P033); served and external
+ * content adds its own origins, and a host its own frames (`'self'` only if it names it).
+ */
+export declare 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. 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 declare function embedderCsp(configs: readonly PortholeConfig[]): string;