@botiverse/porthole 0.15.2 → 0.16.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +89 -0
- package/dist/bridge/bridge.d.ts +1 -8
- package/dist/bridge/bridge.js +0 -7
- package/dist/check/page-source.js +1 -1
- package/dist/check/page.js +1 -1
- package/dist/compile/policy.d.ts +0 -7
- package/dist/compile/policy.js +1 -10
- package/dist/config/capabilities.d.ts +8 -14
- package/dist/config/capabilities.js +4 -5
- package/dist/config/schema.d.ts +2 -13
- package/dist/config/validate.js +0 -24
- package/dist/conformance/behavior.js +26 -37
- package/dist/conformance/clipboard.js +47 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/displays/displays.js +1 -3
- package/dist/guide/limits.js +1 -1
- package/dist/guide/runtime.js +1 -1
- package/dist/host/create-host.d.ts +1 -1
- package/dist/host/create-host.js +6 -51
- package/dist/host/door.d.ts +1 -1
- package/dist/host/locate.d.ts +1 -1
- package/dist/host/locate.js +2 -2
- package/dist/host/outcome.d.ts +5 -12
- package/dist/host/outcome.js +8 -16
- package/dist/host/types.d.ts +6 -22
- package/dist/index.d.ts +2 -4
- package/dist/index.js +2 -4
- package/dist/isolation/served.d.ts +9 -14
- package/dist/isolation/served.js +17 -31
- package/dist/isolation/types.d.ts +2 -19
- package/dist/isolation/types.js +0 -17
- package/dist/platform/focus-field.d.ts +11 -0
- package/dist/platform/focus-field.js +18 -0
- package/dist/platform/types.d.ts +6 -22
- package/dist/platform/web.js +8 -98
- package/dist/presets/presets.d.ts +0 -2
- package/dist/presets/presets.js +0 -1
- package/dist/react/frame.d.ts +0 -8
- package/dist/react/frame.js +0 -4
- package/dist/runtime/contract.d.ts +2 -2
- package/dist/runtime/contract.js +2 -2
- package/dist/runtime/types.generated.js +6 -6
- package/dist/server/files.js +7 -23
- package/dist/server/host.d.ts +1 -1
- package/dist/server/index.d.ts +1 -1
- package/dist/server/index.js +4 -6
- package/dist/server/naming.js +1 -1
- package/dist/server/pages.d.ts +9 -2
- package/dist/server/pages.js +28 -8
- package/dist/server/server.js +28 -166
- package/dist/server/types.d.ts +7 -7
- package/dist/shell/plan.js +2 -2
- package/dist/shell/runtime.js +1 -9
- package/docs/ADOPTING.md +42 -135
- package/docs/ARCHITECTURE.md +0 -33
- package/docs/DECISIONS.md +296 -9
- package/docs/DESIGN.md +27 -50
- package/docs/THREAT_MODEL.md +140 -242
- package/package.json +1 -1
- package/src/bridge/bridge.ts +1 -17
- package/src/check/page.ts +1 -1
- package/src/compile/policy.ts +1 -11
- package/src/config/capabilities.ts +8 -14
- package/src/config/schema.ts +2 -13
- package/src/config/validate.ts +0 -28
- package/src/conformance/behavior.ts +50 -52
- package/src/conformance/clipboard.ts +56 -1
- package/src/displays/displays.ts +1 -3
- package/src/guide/limits.ts +1 -1
- package/src/guide/runtime.ts +1 -1
- package/src/host/create-host.ts +6 -52
- package/src/host/door.ts +1 -1
- package/src/host/locate.ts +2 -2
- package/src/host/outcome.ts +8 -21
- package/src/host/types.ts +6 -20
- package/src/index.ts +2 -4
- package/src/isolation/served.ts +18 -37
- package/src/isolation/types.ts +2 -24
- package/src/platform/focus-field.ts +18 -0
- package/src/platform/types.ts +6 -21
- package/src/platform/web.ts +8 -116
- package/src/presets/presets.ts +0 -3
- package/src/react/frame.tsx +0 -10
- package/src/runtime/contract.ts +4 -4
- package/src/runtime/types.generated.ts +6 -6
- package/src/server/files.ts +4 -19
- package/src/server/host.ts +1 -1
- package/src/server/index.ts +4 -16
- package/src/server/naming.ts +1 -1
- package/src/server/pages.ts +38 -12
- package/src/server/server.ts +29 -189
- package/src/server/types.ts +7 -7
- package/src/shell/plan.ts +2 -2
- package/src/shell/runtime.ts +1 -9
- package/types/runtime/v1/artifact.d.ts +2 -3
- package/types/runtime/v1/assets.d.ts +1 -1
- package/types/runtime/v1/chat.d.ts +2 -2
- package/types/runtime/v1/comments.d.ts +1 -1
- package/types/runtime/v1/downloads.d.ts +2 -2
- package/types/runtime/v1/links.d.ts +2 -2
- package/dist/platform/focus-guard.d.ts +0 -252
- package/dist/platform/focus-guard.js +0 -764
- package/dist/server/nested.d.ts +0 -66
- package/dist/server/nested.js +0 -120
- package/dist/shell/frame.d.ts +0 -28
- package/dist/shell/frame.js +0 -338
- package/src/platform/focus-guard.ts +0 -999
- package/src/server/nested.ts +0 -156
- package/src/shell/frame.ts +0 -371
|
@@ -3,16 +3,16 @@
|
|
|
3
3
|
// contract every capability shares).
|
|
4
4
|
export const RUNTIME_TYPES: Readonly<Record<string, Readonly<Record<string, string>>>> = {
|
|
5
5
|
"1": {
|
|
6
|
-
"artifact": "// Porthole capability runtime, contract 1: artifact (this artifact itself). Declare it: { artifact: {} }.\n// Use it when the page is the record: a checklist, a plan, a document someone edits in place.\n\ninterface PortholeArtifactFile {\n readonly path: string;\n readonly size: number;\n readonly sha256: string;\n}\n\ninterface PortholeArtifactVersion {\n /** The version's id: what a publish names as its base. */\n readonly version: string;\n readonly number?: number;\n /** The page it opens at (\"index.html\"). */\n readonly entry: string;\n readonly files: readonly PortholeArtifactFile[];\n}\n\ninterface PortholeArtifactPublish {\n /** The version you read and changed (from get()). If it moved, publish rejects with conflict. */\n readonly base: string;\n /**\n * A patch on base's files, by path: text, bytes (a Blob, an ArrayBuffer, a typed array), or\n * null to remove one; files not named are kept. A page sends its whole document, as it should\n * be served. At most 255 files.\n */\n readonly files: Readonly<Record<string, string | Blob | ArrayBuffer | ArrayBufferView | null>>;\n readonly entry?: string;\n /** At most 60 characters. */\n readonly label?: string;\n /** At most 500 characters. */\n readonly note?: string;\n}\n\ninterface PortholeArtifact {\n /** The current version and its files (fetch a file by its relative path). Level: view. */\n get(): Promise<PortholeArtifactVersion>;\n /**\n * Publishes a new version of this artifact
|
|
7
|
-
"assets": "// Porthole capability runtime, contract 1: assets (the artifact's asset library). Declare it: { assets: {} }.\n// Assets live outside every version, at \"/_blob/<id>\" on the page's own origin: keep that url (or\n// the id) in your data, and show it with assets.url(id). Images, media and fonts load; scripts and\n// stylesheets only where the app lets only admins upload, and only those an admin added. Not for\n// files that version with the page: publish those with it.\n\ninterface PortholeAsset {\n /** 32 hex characters. */\n readonly id: string;\n /** \"/_blob/<id>\": use it as given. */\n readonly url: string;\n readonly name: string;\n /** Porthole's type for the name's extension. */\n readonly type: string;\n readonly size: number;\n}\n\ninterface PortholeAssets {\n /** The library, people's uploads through the page included. Level: view. */\n list(): Promise<readonly PortholeAsset[]>;\n /**\n * Adds a file (a File from an <input type=\"file\">, a Blob, bytes) under its name (a File's own,\n * or options.name): an image, media, a font, a PDF, text or data, never HTML; a script or a\n * stylesheet only where uploads are the admins'. The app may ask the person first. Level: admin,\n * unless the app lets people who interact upload.\n */\n upload(\n file: Blob | ArrayBuffer | ArrayBufferView,\n options?: { readonly name?: string },\n ): Promise<PortholeAsset>;\n /**\n * The address that loads an asset in this page now: put it in src or href when you show it.\n * Store the id (or \"/_blob/<id>\"), never this: it carries this page's access. A \"/_blob/<id>\"\n * written in the page loads too, except in some browsers' frames (Safari's); this always does.\n */\n url(id: string): string;\n /** Removes one
|
|
8
|
-
"chat": "// Porthole capability runtime, contract 1: chat. Declare it: { chat: {} }.\n\ninterface PortholeChat {\n /**\n * Sends text to the agent as the person's message (\"explain this point\")
|
|
6
|
+
"artifact": "// Porthole capability runtime, contract 1: artifact (this artifact itself). Declare it: { artifact: {} }.\n// Use it when the page is the record: a checklist, a plan, a document someone edits in place.\n\ninterface PortholeArtifactFile {\n readonly path: string;\n readonly size: number;\n readonly sha256: string;\n}\n\ninterface PortholeArtifactVersion {\n /** The version's id: what a publish names as its base. */\n readonly version: string;\n readonly number?: number;\n /** The page it opens at (\"index.html\"). */\n readonly entry: string;\n readonly files: readonly PortholeArtifactFile[];\n}\n\ninterface PortholeArtifactPublish {\n /** The version you read and changed (from get()). If it moved, publish rejects with conflict. */\n readonly base: string;\n /**\n * A patch on base's files, by path: text, bytes (a Blob, an ArrayBuffer, a typed array), or\n * null to remove one; files not named are kept. A page sends its whole document, as it should\n * be served. At most 255 files.\n */\n readonly files: Readonly<Record<string, string | Blob | ArrayBuffer | ArrayBufferView | null>>;\n readonly entry?: string;\n /** At most 60 characters. */\n readonly label?: string;\n /** At most 500 characters. */\n readonly note?: string;\n}\n\ninterface PortholeArtifact {\n /** The current version and its files (fetch a file by its relative path). Level: view. */\n get(): Promise<PortholeArtifactVersion>;\n /**\n * Publishes a new version of this artifact; the app asks the person first. The page can't\n * change what it declares. On conflict: get() again, merge, publish again. Level: admin.\n */\n publish(\n change: PortholeArtifactPublish,\n ): Promise<{ readonly version: string; readonly number?: number }>;\n}\n\ninterface PortholeCapabilities {\n artifact: PortholeArtifact;\n}\n",
|
|
7
|
+
"assets": "// Porthole capability runtime, contract 1: assets (the artifact's asset library). Declare it: { assets: {} }.\n// Assets live outside every version, at \"/_blob/<id>\" on the page's own origin: keep that url (or\n// the id) in your data, and show it with assets.url(id). Images, media and fonts load; scripts and\n// stylesheets only where the app lets only admins upload, and only those an admin added. Not for\n// files that version with the page: publish those with it.\n\ninterface PortholeAsset {\n /** 32 hex characters. */\n readonly id: string;\n /** \"/_blob/<id>\": use it as given. */\n readonly url: string;\n readonly name: string;\n /** Porthole's type for the name's extension. */\n readonly type: string;\n readonly size: number;\n}\n\ninterface PortholeAssets {\n /** The library, people's uploads through the page included. Level: view. */\n list(): Promise<readonly PortholeAsset[]>;\n /**\n * Adds a file (a File from an <input type=\"file\">, a Blob, bytes) under its name (a File's own,\n * or options.name): an image, media, a font, a PDF, text or data, never HTML; a script or a\n * stylesheet only where uploads are the admins'. The app may ask the person first. Level: admin,\n * unless the app lets people who interact upload.\n */\n upload(\n file: Blob | ArrayBuffer | ArrayBufferView,\n options?: { readonly name?: string },\n ): Promise<PortholeAsset>;\n /**\n * The address that loads an asset in this page now: put it in src or href when you show it.\n * Store the id (or \"/_blob/<id>\"), never this: it carries this page's access. A \"/_blob/<id>\"\n * written in the page loads too, except in some browsers' frames (Safari's); this always does.\n */\n url(id: string): string;\n /** Removes one; the app asks the person first. Level: admin. */\n delete(id: string): Promise<boolean>;\n}\n\ninterface PortholeCapabilities {\n assets: PortholeAssets;\n}\n",
|
|
8
|
+
"chat": "// Porthole capability runtime, contract 1: chat. Declare it: { chat: {} }.\n\ninterface PortholeChat {\n /**\n * Sends text to the agent as the person's message (\"explain this point\"); the app asks them\n * first. Resolves true if it was sent. Level: interact.\n */\n send(text: string): Promise<boolean>;\n}\n\ninterface PortholeCapabilities {\n chat: PortholeChat;\n}\n",
|
|
9
9
|
"clipboard": "// Porthole capability runtime, contract 1: clipboard. Built in: never declare it.\n\ninterface PortholeClipboard {\n /**\n * Copies text to the person's clipboard (at most 20,000 characters); the app shows them what\n * was copied. Nothing else in the page can write the clipboard. Call it from a click.\n * Resolves true if it was copied. Level: view.\n */\n copy(text: string): Promise<boolean>;\n}\n\ninterface PortholeCapabilities {\n clipboard: PortholeClipboard;\n}\n",
|
|
10
|
-
"comments": "// Porthole capability runtime, contract 1: comments. Built in: never declare it.\n\n/** Where a comment goes, in the page's own words. */\ninterface PortholeCommentAnchor {\n /** A stable name the page chose: \"slide-3\", \"refs/a.md#L12\" (at most 256 characters). */\n readonly name: string;\n /** What the app shows for it (at most 200; what a person can't see is taken out). */\n readonly label?: string;\n /** The text the comment is about (at most 2,000; what a person can't see is taken out). */\n readonly quote?: string;\n}\n\n/** How the composer opens. */\ninterface PortholeCommentOptions {\n /**\n * Text the composer starts with (at most 2,000 characters): a draft the person edits, posts\n * or discards in the app. It is never posted without them. Visible text only: new lines and\n * tabs are fine (at most 32 blanks in a row, two blank lines in a row), and so are U+200C and\n * U+200D between two letters or marks (Persian, the Indic scripts); a draft with zero-width\n * characters, a joiner anywhere else (an emoji joined with U+200D too; ❤️ is fine), bidi or tag\n * characters, or a line or paragraph separator (U+2028, U+2029) is refused.\n */\n readonly draft?: string;\n}\n\ninterface PortholeComments {\n /**\n * Opens the app's comment composer at the anchor (a name alone is { name }), starting with\n * `options.draft` if given. The person writes and posts it in the app. Resolves true if the\n * composer opened, false if it didn't (the app may refuse while the person is writing).\n * Write-only: a page never reads comments.
|
|
10
|
+
"comments": "// Porthole capability runtime, contract 1: comments. Built in: never declare it.\n\n/** Where a comment goes, in the page's own words. */\ninterface PortholeCommentAnchor {\n /** A stable name the page chose: \"slide-3\", \"refs/a.md#L12\" (at most 256 characters). */\n readonly name: string;\n /** What the app shows for it (at most 200; what a person can't see is taken out). */\n readonly label?: string;\n /** The text the comment is about (at most 2,000; what a person can't see is taken out). */\n readonly quote?: string;\n}\n\n/** How the composer opens. */\ninterface PortholeCommentOptions {\n /**\n * Text the composer starts with (at most 2,000 characters): a draft the person edits, posts\n * or discards in the app. It is never posted without them. Visible text only: new lines and\n * tabs are fine (at most 32 blanks in a row, two blank lines in a row), and so are U+200C and\n * U+200D between two letters or marks (Persian, the Indic scripts); a draft with zero-width\n * characters, a joiner anywhere else (an emoji joined with U+200D too; ❤️ is fine), bidi or tag\n * characters, or a line or paragraph separator (U+2028, U+2029) is refused.\n */\n readonly draft?: string;\n}\n\ninterface PortholeComments {\n /**\n * Opens the app's comment composer at the anchor (a name alone is { name }), starting with\n * `options.draft` if given. The person writes and posts it in the app. Resolves true if the\n * composer opened, false if it didn't (the app may refuse while the person is writing).\n * Write-only: a page never reads comments. Level: view.\n */\n open(anchor: PortholeCommentAnchor | string, options?: PortholeCommentOptions): Promise<boolean>;\n}\n\ninterface PortholeCapabilities {\n comments: PortholeComments;\n}\n",
|
|
11
11
|
"context": "// Porthole capability runtime, contract 1: context. Declare it: { context: {} }.\n\ninterface PortholeContextUpdate {\n /**\n * MCP text blocks only: [{ type: \"text\", text: \"…\" }]. Visible characters only, here and in\n * structuredContent: no zero-width or bidi controls, variation selectors, tag or private-use\n * characters, or controls other than new lines and tabs (refused), but the selectors and\n * joiners inside real emoji (☀️, 👨👩👧, 1️⃣), and a joiner or non-joiner between two letters of\n * a script it shapes (Arabic, Persian, the Indic scripts, Myanmar…).\n */\n readonly content?: readonly unknown[];\n /** Plain JSON. With the text, at most 20,000 characters. */\n readonly structuredContent?: Record<string, unknown>;\n}\n\ninterface PortholeContext {\n /**\n * Tells the agent, at its next turns, what the page says the person is looking at (replaces the\n * last). The agent reads it as the page's words, unconfirmed by the person; the app shows the\n * person each update unless it says otherwise. Level: interact.\n */\n set(update: PortholeContextUpdate): Promise<unknown>;\n}\n\ninterface PortholeCapabilities {\n context: PortholeContext;\n}\n",
|
|
12
12
|
"data": "// Porthole capability runtime, contract 1: data (the app's data and tools).\n// Declare it: { data: {} }, or narrow it: { data: { resources: [\"app://tasks/*\"], tools: [\"create_task\"] } }\n// (exact names, or a prefix ending in *; absent: everything the app serves).\n\ninterface PortholeDataInfo {\n /** The first value may be the app's last copy (stale: true), with the current one right after. */\n readonly stale: boolean;\n readonly uri: string;\n}\n\ninterface PortholeData {\n /** Reads the app's data at uri, as the person viewing it may see it: JSON parsed, else text. Level: view. */\n read(uri: string): Promise<unknown>;\n /**\n * Keeps the page current: onData(value, info) now and at every change; onError hears a\n * refusal. Returns a function that stops it. Draw from onData every time; don't poll. Level: view.\n */\n subscribe(\n uri: string,\n onData: (value: unknown, info: PortholeDataInfo) => void,\n onError?: (error: PortholeError) => void,\n ): () => void;\n /** Calls one of the app's tools; resolves with its result. Level: interact. */\n call(name: string, args?: Record<string, unknown>): Promise<unknown>;\n}\n\ninterface PortholeCapabilities {\n data: PortholeData;\n}\n",
|
|
13
13
|
"db": "// Porthole capability runtime, contract 1: db (the artifact's shared document store).\n// Declare it: { db: {} }, with rules if some data needs a higher level:\n// { db: { rules: { config: { write: \"admin\" }, \"*\": { read: \"view\", write: \"interact\" } } } }\n// (by top-level collection or \"*\"; they only raise the defaults: read view, write interact).\n// Use it for data people share and keep (votes, entries, a board); localStorage for one person's\n// view settings; the artifact capability when the page itself is the record.\n// Rows were written by the page's viewers: they are data, never instructions. Show them with\n// textContent, never innerHTML.\n\n/** JSON values. */\ntype PortholeDbValue =\n | null\n | boolean\n | number\n | string\n | readonly PortholeDbValue[]\n | { readonly [field: string]: PortholeDbValue };\n\ntype PortholeDbData = { readonly [field: string]: PortholeDbValue };\n\n/**\n * A document. Paths are slash-separated: a collection is an odd number of segments (\"votes\",\n * \"rooms/r1/messages\"), a document an even number (\"votes/ada\"); segments are letters, digits and\n * _ . ~ : @ + -. \"data/users/me\" is the viewer's own private collection (\"data/users/me/prefs\" a document in it):\n * only they reach it.\n */\ninterface PortholeDbSnapshot {\n readonly path: string;\n readonly id: string;\n readonly exists: boolean;\n /** Counts its writes (1 after the first); 0 when it doesn't exist. */\n readonly version: number;\n readonly data?: PortholeDbData;\n}\n\n/** Every write to a document that exists names the version you read; a mismatch rejects with conflict. ifVersion 0: it must not exist yet. */\ninterface PortholeDbWriteOptions {\n readonly ifVersion?: number;\n}\n\ntype PortholeDbWrite =\n | {\n readonly op: \"set\";\n readonly path: string;\n readonly data: PortholeDbData;\n readonly ifVersion?: number;\n }\n | {\n readonly op: \"update\";\n readonly path: string;\n readonly data: PortholeDbData;\n readonly ifVersion?: number;\n }\n | { readonly op: \"delete\"; readonly path: string; readonly ifVersion?: number };\n\ninterface PortholeDbQuery {\n /** At most 10: [field, op, value]. */\n readonly where?: readonly (readonly [\n field: string,\n op: \"==\" | \"!=\" | \"<\" | \"<=\" | \">\" | \">=\" | \"in\" | \"array-contains\",\n value: PortholeDbValue,\n ])[];\n readonly orderBy?: { readonly field: string; readonly direction?: \"asc\" | \"desc\" };\n /** 1 to 500. */\n readonly limit?: number;\n}\n\ninterface PortholeDb {\n /** Level: view. */\n get(path: string): Promise<PortholeDbSnapshot>;\n /** A collection's documents. Level: view. */\n query(\n collection: string,\n query?: PortholeDbQuery,\n ): Promise<{ readonly docs: readonly PortholeDbSnapshot[] }>;\n /** Writes a whole document (at most 1 MiB of JSON). Level: interact. */\n set(\n path: string,\n data: PortholeDbData,\n options?: PortholeDbWriteOptions,\n ): Promise<{ readonly version: number }>;\n /** Merges fields over a document's. Level: interact. */\n update(\n path: string,\n data: PortholeDbData,\n options?: PortholeDbWriteOptions,\n ): Promise<{ readonly version: number }>;\n /** Level: interact. */\n delete(path: string, options?: PortholeDbWriteOptions): Promise<null>;\n /**\n * Up to 50 writes to different documents, all or none. Each write's new version (null for a\n * delete). Each write at its own level.\n */\n batch(\n writes: readonly PortholeDbWrite[],\n ): Promise<{ readonly versions: readonly (number | null)[] }>;\n /**\n * Follows a document (a snapshot) or a collection ({ docs }) now and at every change. Returns a\n * function that stops it. Draw from onData; don't poll. Level: view.\n */\n onSnapshot(\n path: string,\n onData: (state: PortholeDbSnapshot | { readonly docs: readonly PortholeDbSnapshot[] }) => void,\n onError?: (error: PortholeError) => void,\n ): () => void;\n}\n\ninterface PortholeCapabilities {\n db: PortholeDb;\n}\n",
|
|
14
|
-
"downloads": "// Porthole capability runtime, contract 1: downloads. Built in: never declare it.\n\n/** A file to hand the person: its name, and its text or bytes. */\ninterface PortholeDownload {\n /** A file name, no slashes: \"report.csv\". Its extension gives its type unless `type` says. */\n readonly name: string;\n readonly type?: string;\n readonly text?: string;\n readonly data?: Blob | ArrayBuffer | ArrayBufferView;\n}\n\ninterface PortholeDownloads {\n /**\n * Hands the person a file to save (<a download> and script-driven saves don't work here)
|
|
15
|
-
"links": "// Porthole capability runtime, contract 1: links. Built in: never declare it.\n\ninterface PortholeLinks {\n /**\n * Opens an http(s) link outside the page (a click on an <a href> does the same)
|
|
14
|
+
"downloads": "// Porthole capability runtime, contract 1: downloads. Built in: never declare it.\n\n/** A file to hand the person: its name, and its text or bytes. */\ninterface PortholeDownload {\n /** A file name, no slashes: \"report.csv\". Its extension gives its type unless `type` says. */\n readonly name: string;\n readonly type?: string;\n readonly text?: string;\n readonly data?: Blob | ArrayBuffer | ArrayBufferView;\n}\n\ninterface PortholeDownloads {\n /**\n * Hands the person a file to save (<a download> and script-driven saves don't work here);\n * the app asks them first. Resolves true if the download started. Level: view.\n */\n save(file: PortholeDownload): Promise<boolean>;\n}\n\ninterface PortholeCapabilities {\n downloads: PortholeDownloads;\n}\n",
|
|
15
|
+
"links": "// Porthole capability runtime, contract 1: links. Built in: never declare it.\n\ninterface PortholeLinks {\n /**\n * Opens an http(s) link outside the page (a click on an <a href> does the same); the app asks\n * the person first. Resolves true if it opened. Level: view.\n */\n open(url: string): Promise<boolean>;\n}\n\ninterface PortholeCapabilities {\n links: PortholeLinks;\n}\n",
|
|
16
16
|
"porthole": "// Porthole capability runtime, contract 1: the call contract (how a page reaches any capability).\n\n/**\n * Why a call was refused: branch on it; show `message` (a sentence for the person) where the\n * result would be. Never retry in a loop.\n * - consent_required: the person hasn't allowed it yet.\n * - denied: the person said no.\n * - rate_limited: too many calls this minute.\n * - not_allowed: not available here (some places show the page without it).\n * - failed: the app tried and couldn't.\n * - forbidden: this person may see the page but not do this (their level).\n * - conflict: what you change moved since you read it: read it again, then write.\n * - too_large: past a limit.\n */\ntype PortholeErrorCode =\n | \"consent_required\"\n | \"denied\"\n | \"rate_limited\"\n | \"not_allowed\"\n | \"failed\"\n | \"forbidden\"\n | \"conflict\"\n | \"too_large\";\n\n/** What every capability method rejects with. */\ninterface PortholeError extends Error {\n readonly code: PortholeErrorCode;\n}\n\n/** Each capability's namespace, by the name `use` takes (each capability's own file adds its own). */\ninterface PortholeCapabilities {}\n\ninterface PortholeRuntime {\n /**\n * The capability's namespace, frozen; or null when it isn't there for this page: the app\n * doesn't offer it, the page didn't declare it, or no app is showing the page (a tab, a\n * preview). The reasons are indistinguishable: draw the page without it. `use` never rejects;\n * permission problems come when you call a method (a rejected promise, `PortholeError`).\n */\n use<N extends keyof PortholeCapabilities>(name: N): Promise<PortholeCapabilities[N] | null>;\n}\n\n/** The page's one global. Nothing else is added to `window`. */\ndeclare const porthole: PortholeRuntime;\n",
|
|
17
17
|
"user": "// Porthole capability runtime, contract 1: user. Declare it: { user: {} }.\n\n/** Who is viewing, as the app says. */\ninterface PortholeUserInfo {\n /** The app's id for this person (whose data \"data/users/me\" is), or null if it gives none. */\n readonly id: string | null;\n readonly name: string | null;\n /** What they may do here: view < interact < admin < owner. */\n readonly level: \"view\" | \"interact\" | \"admin\" | \"owner\";\n}\n\ninterface PortholeUser {\n /** Level: view. */\n get(): Promise<PortholeUserInfo>;\n}\n\ninterface PortholeCapabilities {\n user: PortholeUser;\n}\n",
|
|
18
18
|
},
|
package/src/server/files.ts
CHANGED
|
@@ -12,7 +12,6 @@ import { DEFAULT_ENTRY, lookupFile, requestFilePath, type FileLookup } from "../
|
|
|
12
12
|
import { fileTypeOf } from "../files/types.ts";
|
|
13
13
|
import { isCodeAsset } from "../runtime/requests.ts";
|
|
14
14
|
import { sha256, utf8 } from "./crypto.ts";
|
|
15
|
-
import { NESTED_FILE_HEADERS, nestedFileCsp } from "./nested.ts";
|
|
16
15
|
import type { FileBody, StoredAsset, StoredFiles } from "./types.ts";
|
|
17
16
|
|
|
18
17
|
/**
|
|
@@ -260,8 +259,6 @@ export async function serveFile(serving: FileServing): Promise<Response> {
|
|
|
260
259
|
return nothing(serving, 404, method);
|
|
261
260
|
}
|
|
262
261
|
const { type, role } = fileTypeOf(found.path);
|
|
263
|
-
// A nested page (P111): in its shell's child, an opaque origin.
|
|
264
|
-
const nested = serving.compiled.config.nested === true;
|
|
265
262
|
// In a frame, the version's files are at a sealed address (P083), which their own loads of the
|
|
266
263
|
// artifact's assets carry as their `Referer` (P091): to this origin only, never another.
|
|
267
264
|
const referrer =
|
|
@@ -283,13 +280,8 @@ export async function serveFile(serving: FileServing): Promise<Response> {
|
|
|
283
280
|
// A page and a script (a worker's policy is its script's) get the page's CSP, a page with its
|
|
284
281
|
// frame's sandbox, on a tab of its own too (P099); anything else runs nothing when opened on
|
|
285
282
|
// its own.
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
// origin. Pages run their scripts, opaque; anything else runs nothing (a file's is inert already,
|
|
289
|
-
// a script's gets one too).
|
|
290
|
-
const csp = nested
|
|
291
|
-
? nestedFileCsp(role, directives)
|
|
292
|
-
: role === "file"
|
|
283
|
+
const csp =
|
|
284
|
+
role === "file"
|
|
293
285
|
? INERT_FILE_CSP
|
|
294
286
|
: role === "page"
|
|
295
287
|
? servedDocumentCsp(serving.compiled.config, directives)
|
|
@@ -309,8 +301,7 @@ export async function serveFile(serving: FileServing): Promise<Response> {
|
|
|
309
301
|
if (role === "page") {
|
|
310
302
|
// Every page of the set in the shell (P081): its hardening, its host functions, its theme.
|
|
311
303
|
const html = serving.compiled.shellDocument({
|
|
312
|
-
|
|
313
|
-
origins: nested ? [serving.origin] : serving.hostOrigins,
|
|
304
|
+
origins: serving.hostOrigins,
|
|
314
305
|
document: await textOf(body),
|
|
315
306
|
cspMeta: false,
|
|
316
307
|
...(referrer === "same-origin" ? { referrer } : {}),
|
|
@@ -350,14 +341,8 @@ export async function serveFile(serving: FileServing): Promise<Response> {
|
|
|
350
341
|
serving.pinned ? `private, max-age=${YEAR}, immutable` : "private, no-cache",
|
|
351
342
|
);
|
|
352
343
|
// Only this origin's own pages load it: no other content origin (a sibling, same-site without
|
|
353
|
-
// the public suffix list) can embed it with the viewer's cookie.
|
|
354
|
-
// opaque, and its files carry their access in their path, never a cookie (P111).
|
|
344
|
+
// the public suffix list) can embed it with the viewer's cookie.
|
|
355
345
|
headers.set("cross-origin-resource-policy", "same-origin");
|
|
356
|
-
if (nested) {
|
|
357
|
-
for (const [name, value] of Object.entries(NESTED_FILE_HEADERS)) {
|
|
358
|
-
headers.set(name, value);
|
|
359
|
-
}
|
|
360
|
-
}
|
|
361
346
|
headers.set("accept-ranges", "bytes");
|
|
362
347
|
if (role === "file" && type === "application/octet-stream") {
|
|
363
348
|
headers.set("content-disposition", "attachment");
|
package/src/server/host.ts
CHANGED
|
@@ -113,7 +113,7 @@ export interface ContentHostOptions<V> {
|
|
|
113
113
|
/**
|
|
114
114
|
* Origins of an outer page that frame the app itself (P141): each may be an ancestor of every frame
|
|
115
115
|
* the app shows, above an app origin's page, so it is in every `frame-ancestors` Porthole sends
|
|
116
|
-
* (content,
|
|
116
|
+
* (content, doors, status and entry pages, the authorize route's pages) after
|
|
117
117
|
* `appOrigins`, and nowhere else. Never an origin a frame hears or tells, never an app origin for
|
|
118
118
|
* redirect entry or the handoff; the app's own page must still be the frame's parent. Exact https
|
|
119
119
|
* origins (`http://` on loopback), none an app origin, none the content domain's site. The app's
|
package/src/server/index.ts
CHANGED
|
@@ -70,27 +70,15 @@ export {
|
|
|
70
70
|
type D1StatementLike,
|
|
71
71
|
} from "./tickets.ts";
|
|
72
72
|
export { DOOR_PATH, FRAME_STATUS_METHOD } from "../isolation/types.ts";
|
|
73
|
-
// A served display's door (P125): `/server` serves it for a shell, a page
|
|
73
|
+
// A served display's door (P125): `/server` serves it for a shell, a page and the
|
|
74
74
|
// sandbox proxy; a content Worker of a host's own answers the same at `DOOR_PATH<key>`, after
|
|
75
75
|
// taking the door's own ticket (`TicketRecord.door`) and running the checks its content's address
|
|
76
76
|
// runs (docs/ADOPTING.md, "The door"). A host that signs its own tickets answers it with
|
|
77
77
|
// `PortholeServer.doorAnswer` once it has admitted the request itself (P126).
|
|
78
78
|
export { doorResponse, doorStatusResponse, type DoorOptions } from "./pages.ts";
|
|
79
|
-
//
|
|
80
|
-
//
|
|
81
|
-
|
|
82
|
-
// pages").
|
|
83
|
-
export {
|
|
84
|
-
isNestedLabel,
|
|
85
|
-
NESTED_FILE_HEADERS,
|
|
86
|
-
NESTED_FILES_PREFIX,
|
|
87
|
-
nestedAncestors,
|
|
88
|
-
nestedFileCsp,
|
|
89
|
-
nestedLabelOf,
|
|
90
|
-
nestedShellCsp,
|
|
91
|
-
nestedShellResponse,
|
|
92
|
-
PORTHOLE_LABEL_PREFIX,
|
|
93
|
-
} from "./nested.ts";
|
|
79
|
+
// Labels that start so are Porthole's own (its health label; until 0.16.0 a nested page's shell's,
|
|
80
|
+
// P114): no host's naming makes one.
|
|
81
|
+
export { PORTHOLE_LABEL_PREFIX } from "../isolation/served.ts";
|
|
94
82
|
export { isHostLabel, prefixedName, type Naming } from "./naming.ts";
|
|
95
83
|
// The page an app serves in conformance test mode (P071).
|
|
96
84
|
export { conformancePage } from "../conformance/page.ts";
|
package/src/server/naming.ts
CHANGED
|
@@ -42,7 +42,7 @@ export function prefixedName(prefix: string): Naming & {
|
|
|
42
42
|
"A name prefix is a lowercase letter, then letters or digits, then '-' (a-)",
|
|
43
43
|
);
|
|
44
44
|
}
|
|
45
|
-
// Porthole's own labels
|
|
45
|
+
// Porthole's own labels are never a scope's.
|
|
46
46
|
if (prefix === "porthole-") {
|
|
47
47
|
throw new TypeError("The name prefix porthole- is Porthole's own: choose another (a-)");
|
|
48
48
|
}
|
package/src/server/pages.ts
CHANGED
|
@@ -1,5 +1,10 @@
|
|
|
1
1
|
import { DOOR_SANDBOX_TOKENS } from "../compile/policy.ts";
|
|
2
|
-
import {
|
|
2
|
+
import {
|
|
3
|
+
framedByProblem,
|
|
4
|
+
hostOriginProblem,
|
|
5
|
+
includesOrigin,
|
|
6
|
+
normalOrigin,
|
|
7
|
+
} from "../isolation/served.ts";
|
|
3
8
|
import { FRAME_STATUS_METHOD } from "../isolation/types.ts";
|
|
4
9
|
import type { FrameBlock } from "../host/types.ts";
|
|
5
10
|
import { base64url, sha256, utf8 } from "./crypto.ts";
|
|
@@ -32,8 +37,23 @@ const isStrict = (frameAncestors: string, hostOrigins: readonly string[]): boole
|
|
|
32
37
|
const strictParent = (strict: boolean): string => (strict ? ' data-porthole-strict-parent=""' : "");
|
|
33
38
|
|
|
34
39
|
/**
|
|
35
|
-
*
|
|
36
|
-
* into a header)
|
|
40
|
+
* The host origins a helper was given, each checked as a config's are (`hostOriginProblem`, P145):
|
|
41
|
+
* they go into a header (`frame-ancestors`) and into the page's own list of whom it tells, and a
|
|
42
|
+
* content Worker of a host's own passes them here itself. `who` names the helper in the error.
|
|
43
|
+
*/
|
|
44
|
+
export function checkHostOrigins(who: string, hostOrigins: readonly string[]): void {
|
|
45
|
+
for (const origin of hostOrigins) {
|
|
46
|
+
const problem = hostOriginProblem(origin);
|
|
47
|
+
if (problem !== null) {
|
|
48
|
+
throw new TypeError(`${who}: hostOrigins: ${problem}`);
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
/**
|
|
54
|
+
* Who may frame a page: the host origins, then a host's `framedBy` (P141), each `framedBy`
|
|
55
|
+
* checked here (they go into a header); the host origins by whoever was given them (a config's by
|
|
56
|
+
* `createServer`, a helper's by `checkHostOrigins`).
|
|
37
57
|
*/
|
|
38
58
|
export function ancestorsOf(
|
|
39
59
|
hostOrigins: readonly string[],
|
|
@@ -289,14 +309,19 @@ export interface EmbedPage {
|
|
|
289
309
|
|
|
290
310
|
/** Whom a page tells, and who may frame it: the host origins' (P141), or an embed's (P143). */
|
|
291
311
|
const framingOf = (
|
|
312
|
+
who: string,
|
|
292
313
|
options: HostedPage | EmbedPage,
|
|
293
|
-
): { readonly hosts: readonly string[]; readonly ancestors: string } =>
|
|
294
|
-
options.embed === true
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
314
|
+
): { readonly hosts: readonly string[]; readonly ancestors: string } => {
|
|
315
|
+
if (options.embed === true) {
|
|
316
|
+
return { hosts: [], ancestors: "*" };
|
|
317
|
+
}
|
|
318
|
+
// Checked here too: with `frameAncestors` given, `ancestorsOf` never sees them.
|
|
319
|
+
checkHostOrigins(who, options.hostOrigins);
|
|
320
|
+
return {
|
|
321
|
+
hosts: options.hostOrigins,
|
|
322
|
+
ancestors: options.frameAncestors ?? ancestorsOf(options.hostOrigins, options.framedBy),
|
|
323
|
+
};
|
|
324
|
+
};
|
|
300
325
|
|
|
301
326
|
/**
|
|
302
327
|
* A page saying why a frame shows nothing, for a relay of the app's own (P072): told to the page
|
|
@@ -314,7 +339,7 @@ export function statusPageOf(
|
|
|
314
339
|
readonly method?: string;
|
|
315
340
|
} & (HostedPage | EmbedPage),
|
|
316
341
|
): Response {
|
|
317
|
-
const { hosts, ancestors } = framingOf(options);
|
|
342
|
+
const { hosts, ancestors } = framingOf("statusPage", options);
|
|
318
343
|
return appStatusPage(
|
|
319
344
|
options.status,
|
|
320
345
|
options.title,
|
|
@@ -372,6 +397,7 @@ export interface DoorOptions {
|
|
|
372
397
|
* own ticket was taken and the checks the content's address runs passed for the same grant.
|
|
373
398
|
*/
|
|
374
399
|
export function doorResponse(options: DoorOptions): Response {
|
|
400
|
+
checkHostOrigins("doorResponse", options.hostOrigins);
|
|
375
401
|
const hosts = escape(JSON.stringify(options.hostOrigins));
|
|
376
402
|
const ancestors = options.frameAncestors ?? ancestorsOf(options.hostOrigins, options.framedBy);
|
|
377
403
|
const strict = isStrict(ancestors, options.hostOrigins);
|
|
@@ -401,7 +427,7 @@ export function doorStatusResponse(
|
|
|
401
427
|
},
|
|
402
428
|
): Response {
|
|
403
429
|
const { status, reason, code } = options;
|
|
404
|
-
const framing = framingOf(options);
|
|
430
|
+
const framing = framingOf("doorStatusResponse", options);
|
|
405
431
|
const hosts = escape(JSON.stringify(framing.hosts));
|
|
406
432
|
const ancestors = framing.ancestors;
|
|
407
433
|
const strict = isStrict(ancestors, framing.hosts);
|