@botiverse/porthole 0.2.4 → 0.3.1
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/README.md +17 -11
- package/dist/check/check.d.ts +100 -0
- package/dist/check/check.js +247 -0
- package/dist/check/drivers.d.ts +43 -0
- package/dist/check/drivers.js +181 -0
- package/dist/check/index.d.ts +8 -0
- package/dist/check/index.js +8 -0
- package/dist/check/instrument.d.ts +71 -0
- package/dist/check/instrument.js +84 -0
- package/dist/check/lint.d.ts +21 -0
- package/dist/check/lint.js +131 -0
- package/dist/check/page-source.d.ts +2 -0
- package/dist/check/page-source.js +2 -0
- package/dist/check/page.d.ts +13 -0
- package/dist/check/page.js +170 -0
- package/dist/check/tools.d.ts +61 -0
- package/dist/check/tools.js +140 -0
- package/dist/conformance/host-kit.d.ts +26 -5
- package/dist/conformance/host-kit.js +46 -22
- package/dist/conformance/index.d.ts +1 -1
- package/dist/conformance/reporter.d.ts +14 -0
- package/dist/conformance/reporter.js +28 -0
- package/dist/displays/displays.d.ts +61 -0
- package/dist/displays/displays.js +113 -0
- package/dist/host/client.d.ts +110 -0
- package/dist/host/client.js +274 -0
- package/dist/index.d.ts +4 -0
- package/dist/index.js +6 -0
- package/dist/node/index.d.ts +26 -1
- package/dist/node/index.js +91 -1
- package/dist/react/frame.d.ts +79 -3
- package/dist/react/frame.js +183 -42
- package/dist/react/index.d.ts +2 -1
- package/dist/react/index.js +1 -0
- package/dist/react/view.d.ts +54 -0
- package/dist/react/view.js +151 -0
- package/dist/server/bootstrap.d.ts +27 -0
- package/dist/server/bootstrap.js +63 -0
- package/dist/server/host.d.ts +77 -8
- package/dist/server/host.js +268 -11
- package/dist/server/index.d.ts +4 -2
- package/dist/server/index.js +3 -1
- package/dist/server/pages.d.ts +19 -0
- package/dist/server/pages.js +8 -0
- package/dist/server/proxy.d.ts +24 -0
- package/dist/server/proxy.js +67 -0
- package/dist/server/server.js +14 -1
- package/dist/server/types.d.ts +8 -0
- package/docs/ADOPTING.md +278 -108
- package/docs/DECISIONS.md +280 -0
- package/docs/DESIGN.md +84 -2
- package/examples/app.mjs +82 -78
- package/examples/conformance/page.spec.mjs +23 -0
- package/examples/conformance/playwright.config.mjs +3 -2
- package/examples/conformance/porthole.spec.mjs +6 -3
- package/examples/displays.mjs +21 -0
- package/examples/mcp/server.mjs +121 -0
- package/examples/node/server.mjs +16 -34
- package/examples/workers/worker.mjs +19 -7
- package/package.json +13 -1
- package/src/check/check.ts +386 -0
- package/src/check/drivers.ts +242 -0
- package/src/check/index.ts +22 -0
- package/src/check/instrument.ts +138 -0
- package/src/check/lint.ts +238 -0
- package/src/check/page-source.ts +19 -0
- package/src/check/page.ts +230 -0
- package/src/check/tools.ts +206 -0
- package/src/conformance/host-kit.ts +82 -27
- package/src/conformance/index.ts +1 -0
- package/src/conformance/reporter.ts +38 -0
- package/src/displays/displays.ts +191 -0
- package/src/host/client.ts +395 -0
- package/src/index.ts +25 -0
- package/src/node/index.ts +112 -2
- package/src/react/frame.tsx +271 -57
- package/src/react/index.ts +9 -0
- package/src/react/view.tsx +237 -0
- package/src/server/bootstrap.ts +97 -0
- package/src/server/host.ts +372 -18
- package/src/server/index.ts +11 -1
- package/src/server/pages.ts +28 -0
- package/src/server/proxy.ts +86 -0
- package/src/server/server.ts +26 -2
- package/src/server/types.ts +5 -0
package/docs/DECISIONS.md
CHANGED
|
@@ -1809,3 +1809,283 @@ artifact-only app lacks, two snippet bugs, no word on the page's CSP, two ways t
|
|
|
1809
1809
|
which left the manual wrong), Workers specifics, and local development.
|
|
1810
1810
|
**Revisit when** a second cold adoption (after 0.3) finds friction these don't cover.
|
|
1811
1811
|
|
|
1812
|
+
|
|
1813
|
+
## P072 · 2026-10-12 · Host kit 0.3: the client, the bootstrap and the relay, so adopters stop writing glue · Accepted
|
|
1814
|
+
|
|
1815
|
+
**Decision.** After 0.2.2 the server's content file is policy and little
|
|
1816
|
+
else; the glue moved to the client, the bootstrap and url mode. Ferry still writes about 1,650
|
|
1817
|
+
lines of glue and workarounds, Raft about 450 (notes/porthole-0.3-audit.md). 0.3 adds, all
|
|
1818
|
+
additive:
|
|
1819
|
+
|
|
1820
|
+
1. **`defineDisplays(kinds)`** (core): one registry for every kind an app shows.
|
|
1821
|
+
|
|
1822
|
+
```ts
|
|
1823
|
+
const displays = defineDisplays({
|
|
1824
|
+
widget: { preset: "inlineWidget", options: { capabilities: { sendPrompt: {} } } },
|
|
1825
|
+
page: { preset: "artifact", options: { layout: { kind: "fill" } } },
|
|
1826
|
+
preview:{ preset: "url", options: {} }, // url mode: served only
|
|
1827
|
+
});
|
|
1828
|
+
displays.opaque("widget"); // PortholeConfig
|
|
1829
|
+
displays.served(contentSource); // Record<kind, PortholeConfig> | null, memoized
|
|
1830
|
+
displays.configFor(instance, contentSource | null); // by the document's kind and preset
|
|
1831
|
+
displays.frameSources(contentSource, { authorizeUrl }); // for a CSP built without a ContentHost (Vite, Electron)
|
|
1832
|
+
displays.guideConfig("widget", "served" | "opaque"); // the agent's manual, without real origins
|
|
1833
|
+
```
|
|
1834
|
+
|
|
1835
|
+
`createContentHost({ displays })` and `defineHostConformance({ displays })` take it in place of
|
|
1836
|
+
`configs` and `config(instance)` (both stay).
|
|
1837
|
+
2. **Conventional routes and bootstrap** (/server, /node):
|
|
1838
|
+
- `content.routes(viewerOf, { prefix = "/porthole" })`: `POST frames` (issue), `GET authorize`,
|
|
1839
|
+
`GET meta`, `POST handoff` (item 6), one mount. `entry.authorizeUrl` defaults to
|
|
1840
|
+
`${appOrigins[0]}${prefix}/authorize`.
|
|
1841
|
+
- `GET meta` answers `ContentClientMeta`: `{ served, contentSource, frameSources, health }`.
|
|
1842
|
+
- `issue` answers 201 `{ url, origin, link? }`: `link` is the clean address, where
|
|
1843
|
+
`entry.pathOf(instance)` names the instance's path.
|
|
1844
|
+
- `contentHostFor((env) => options)` on Workers: one host per `env`, a fail-closed 503 naming
|
|
1845
|
+
the problem (logged once), `fetch(request, env)` answering the content domain first.
|
|
1846
|
+
- `nodeServer({ content, app, upgrade?, appSocket? })`: the `http.Server`, the gate started on
|
|
1847
|
+
listen and stopped on close.
|
|
1848
|
+
3. **The client served kit** (core, React):
|
|
1849
|
+
- `portholeClient({ base = "/porthole", headers?, credentials?, displays })`: `meta()`,
|
|
1850
|
+
`subscribe()`, `config(kind)` (served or opaque, null until meta is known), the locator,
|
|
1851
|
+
`link(instance)`, `openInTab(instance)` (a blank tab inside the click, then the link).
|
|
1852
|
+
- React: `<PortholeProvider client>` and `<PortholeView display="page" instance={…}
|
|
1853
|
+
content={…} fallback={({ kind, message, link, retry }) => …} />`, where `kind` is
|
|
1854
|
+
`needs-tab | denied | expired | failed | timeout`, worded as Porthole's pages word them.
|
|
1855
|
+
`usePortholeLink(instance)` gives `{ link, open, copy }`.
|
|
1856
|
+
4. **React ergonomics:** provider `scheme`, `theme` with `themeKey`, `cssVariableTheme(tokens)`,
|
|
1857
|
+
`nonce: "auto"`, `openLink`, `notify` (skin the copy notice), `renderConfirm(request, answer)`
|
|
1858
|
+
(the app draws the dialog; Porthole keeps the gates, the one-at-a-time queue and decline
|
|
1859
|
+
counting); content errors deduplicated per run; `useRunAgain()` for a "run again" button.
|
|
1860
|
+
5. **The url-mode relay kit** (/server, /node): `upstreamHeaders.request/response` (the header
|
|
1861
|
+
rewrite `proxyTo` uses, on `Headers` or raw pairs, WebSockets too); `statusPage(…)` (P070's
|
|
1862
|
+
fallback included); `nodeHost`'s `appSocket` gets the request with Porthole's cookies removed;
|
|
1863
|
+
`content.forget({ scope?, subject? })` drops cached `authorize` answers.
|
|
1864
|
+
6. **Viewer handoff for token-authenticated apps:** `POST handoff`, called by the signed-in app
|
|
1865
|
+
with its own token (`client.handoff()`), sets an `HttpOnly` cookie scoped to the authorize
|
|
1866
|
+
path holding a short-lived viewer key Porthole signs (never the app's token);
|
|
1867
|
+
`entry.handoff: { id(viewer), viewer(id) }` says who a viewer is and turns it back. `entry.spa: { route }` gives the
|
|
1868
|
+
default `signIn` for a single-page app, with `entryTarget(next)` as the open-redirect guard.
|
|
1869
|
+
7. **If cheap:** `health.onServedChange(served)`, deduplicated; `log` also takes a
|
|
1870
|
+
`{ info, warn, error }` logger; `prefixedNames({ w: …, f: … })` for several prefixes; a
|
|
1871
|
+
`location` on a mount, used once before the locator (pre-located frames).
|
|
1872
|
+
|
|
1873
|
+
**Why.** Each item deletes code both apps (or every adopter with that need) wrote the same way,
|
|
1874
|
+
and three of them already drift: Ferry's desktop CSP lacks the authorize route, its copied status
|
|
1875
|
+
page lacks P070's fallback, and clean addresses are computed two ways.
|
|
1876
|
+
**Rejected.** A framework-specific server adapter (Hono, Express): `routes` is a fetch handler
|
|
1877
|
+
any of them mounts in one line.
|
|
1878
|
+
**Decided in review:**
|
|
1879
|
+
- The default prefix is `/porthole`, overridable (`createContentHost({ prefix })`), and `issue`
|
|
1880
|
+
moves under it (`POST /porthole/frames`), so one mount serves frames, authorize, meta and
|
|
1881
|
+
handoff, and an embedding CSP, a dev proxy or a desktop CSP each need one path. Apps move their
|
|
1882
|
+
old routes themselves (`issue(viewerOf)` and `authorize(viewerOf)` still exist for that).
|
|
1883
|
+
- The handoff cookie lasts 10 minutes, refreshed whenever the app's page loads or regains focus
|
|
1884
|
+
(`portholeClient({ handoff: true })`, at most every 30 s); an expired one costs only a quiet
|
|
1885
|
+
trip through the app's sign-in route. The POST needs the app's own credential (`viewerOf` must
|
|
1886
|
+
name a viewer) and is refused from another origin (`Origin`, or `Sec-Fetch-Site` where there is
|
|
1887
|
+
no `Origin`), so no other site can set or clear it. The key is Porthole-signed (HMAC under the
|
|
1888
|
+
secret, apart from session keys), names the viewer's id and its expiry, and the cookie is
|
|
1889
|
+
`HttpOnly`, `SameSite=Lax`, scoped to the prefix path (`__Secure-` on https). It is no
|
|
1890
|
+
credential for the app's API, unlike the app's token stored in a cookie (which Ferry did), which
|
|
1891
|
+
would ride on every request to the app origin, for as long as the token lives.
|
|
1892
|
+
- Item 7: `health.onServedChange` and logger adapters only.
|
|
1893
|
+
|
|
1894
|
+
**Measured.** The example app on the new routes and client passes the whole suite on three
|
|
1895
|
+
engines; `PortholeView`, its fallback and `renderConfirm` run in the React spec.
|
|
1896
|
+
|
|
1897
|
+
## P073 · 2026-10-12 · The agent's side: check a page before people see it; tools with names and schemas · Accepted
|
|
1898
|
+
|
|
1899
|
+
**Decision.** Today an agent learns its page broke only after a person
|
|
1900
|
+
looked (Ferry, at its next turn, at most 5 errors) or never (Raft). Porthole already has the
|
|
1901
|
+
parts: the shell's error capture, the conformance harness's `launch` at a width and a scheme, and
|
|
1902
|
+
a browser check behind every line of the manual. 0.3 exposes them:
|
|
1903
|
+
|
|
1904
|
+
1. **`lintContent(config, content): Finding[]`** (core, pure, any runtime): what can be told
|
|
1905
|
+
without running it, worded as the manual words it, each rule tied to the manual's limit id:
|
|
1906
|
+
over `maxBytes`; a document where a fragment is shown (or the reverse); `document.write`;
|
|
1907
|
+
nested frames and plugins; `navigator.clipboard` and `execCommand("copy")` (use `copyText`);
|
|
1908
|
+
`alert`/`confirm`/`prompt`; a `<form>` that submits; hosts outside egress in `src`, `href`,
|
|
1909
|
+
`fetch` and imports; an unpinned library (`@latest`, a range); `position: fixed` in a flow
|
|
1910
|
+
layout; `target=_blank` without `openLink`. `{ rule, severity, message, line? }`.
|
|
1911
|
+
2. **`checkPage(options): Promise<CheckReport>`** (`@botiverse/porthole/check`): runs the content
|
|
1912
|
+
in the real sandbox (the harness, the production CSP) at each width and scheme (defaults from
|
|
1913
|
+
the config: the manual's phone and desktop widths, light and dark unless the config is
|
|
1914
|
+
unthemed), and reports per run: errors (thrown, rejected, "Blocked by the sandbox"), CSP
|
|
1915
|
+
blocks, failed loads, `console.error`/`warn`, the height and whether the limit clips it,
|
|
1916
|
+
horizontal overflow, optional screenshots; plus `lint`, `ok` and one agent-readable `text`.
|
|
1917
|
+
Drivers: `playwrightDriver(browser)` (Node), and `cdpDriver(session)` over any CDP session
|
|
1918
|
+
(Puppeteer's, or `@cloudflare/puppeteer`'s on Cloudflare Browser Rendering), so a Worker can
|
|
1919
|
+
check too. The harness ships as a string module, so no file system is needed.
|
|
1920
|
+
3. **Tool definitions** (core): `showTool(config)`, `guideTool(config)`, `checkTool(config)`, each
|
|
1921
|
+
`{ name, description, inputSchema }` (JSON Schema; names from `guide.toolName` and
|
|
1922
|
+
`guideToolName`, the topics an enum of the built-in and the config's own); `answerGuide(config,
|
|
1923
|
+
args)` validates and answers; `guideChanges(from, to)`, the notice for the agent when a display
|
|
1924
|
+
kind flips between served and opaque (null when the manual doesn't change). An MCP server
|
|
1925
|
+
example in `examples/mcp/` wires show, guide and check.
|
|
1926
|
+
4. **The manual's own examples pass the check:** a test runs `checkPage` on every
|
|
1927
|
+
`GUIDE_EXAMPLES` entry under every preset, at the manual's widths, in light and dark
|
|
1928
|
+
(OBJECTIVES criterion 5).
|
|
1929
|
+
|
|
1930
|
+
**Why.** It is the one change that improves what agents make rather than what hosts write, and
|
|
1931
|
+
both apps asked for errors to reach the agent before a person does.
|
|
1932
|
+
**Rejected.** Running content on the host's server without a browser (jsdom and the like): it
|
|
1933
|
+
doesn't apply CSP, layout or the sandbox, so it would pass pages that break.
|
|
1934
|
+
**Decided in review:**
|
|
1935
|
+
- The show tool refuses by default (`admitContent`, `refuseOn: "error"`), but only on a narrow
|
|
1936
|
+
set of deterministic errors that would certainly fail or be cut: over the size limit, a whole
|
|
1937
|
+
document where a fragment goes when it can't be taken as its body, nested frames and plugins,
|
|
1938
|
+
`document.write`. Everything heuristic is a warning returned with the result. A host sets the
|
|
1939
|
+
policy (`refuseOn: "never"`). A refusal says exactly what to change, and to call the tool again.
|
|
1940
|
+
- Contrast: later.
|
|
1941
|
+
- `checkPage` must work where the host has no browser: an agent on a person's machine lints
|
|
1942
|
+
locally and sends the check to its server (or uses Playwright where installed); a Worker uses
|
|
1943
|
+
Browser Rendering through `cdpDriver`, with the check page's script imported
|
|
1944
|
+
(`@botiverse/porthole/check/page`). The report's text is short enough for an agent's context:
|
|
1945
|
+
each problem once, with where it happened, at most 8 (`maxProblems`), the rest counted.
|
|
1946
|
+
|
|
1947
|
+
**How it runs.** The check page (bundled from `src/check/page.ts`) is served at a fixed origin
|
|
1948
|
+
the driver answers itself (`https://porthole-check.invalid`: the shell needs a real host origin),
|
|
1949
|
+
mounts the content with `createHost` under its own CSP, opaque (a served config's content with the
|
|
1950
|
+
same CSP; an MCP Apps view as a page with its egress), and puts a small script first in the
|
|
1951
|
+
content that reports errors, rejections, CSP blocks, failed loads, `console.error`/`warn` and the
|
|
1952
|
+
document's width to the page by `postMessage`. Height comes from the display's own resize events.
|
|
1953
|
+
|
|
1954
|
+
**Measured.** Every `GUIDE_EXAMPLES` entry passes under the inline, artifact, whole-page viewer
|
|
1955
|
+
and MCP Apps presets at the manual's widths in light and dark, on three engines
|
|
1956
|
+
(`leak/check.spec.ts`); a broken widget is told each problem once; the CDP driver runs on
|
|
1957
|
+
Chromium.
|
|
1958
|
+
|
|
1959
|
+
## P074 · 2026-10-12 · 0.3.1: sign-in behind a proxy, pages checked as they run, and what 0.3.0's adopters had to guess · Accepted
|
|
1960
|
+
|
|
1961
|
+
**Decision.** 0.3.1 fixes what Ferry's and Raft Artifacts' adoptions of 0.3.0 and a second cold
|
|
1962
|
+
adoption (from the package alone) hit. Additions only.
|
|
1963
|
+
1. **Sign-in comes back to the app as it is reached.** `signIn`'s `returnTo` and `entry.spa`'s
|
|
1964
|
+
`next` are `authorizeUrl` (by default `<first app origin>/porthole/authorize`) with the
|
|
1965
|
+
request's query, its state. Before, they were the request's own URL, which behind a TLS edge
|
|
1966
|
+
(`http://`) or a dev proxy (`localhost:5173`, a rewritten Host) names an origin that isn't the
|
|
1967
|
+
app's, so `entryTarget` refused it and the person stayed on the sign-in.
|
|
1968
|
+
2. **`renderConfirm` gets `redirect()`** beside `accept` and `decline`: the call answers
|
|
1969
|
+
`"redirected"` (the core's existing answer for "the person took it elsewhere": edited the
|
|
1970
|
+
prompt first). It doesn't go, and neither counts toward muting the display nor resets the
|
|
1971
|
+
count. `ConfirmActions` is exported.
|
|
1972
|
+
3. **`nodeServer`'s `content` may be a function** giving the host once it exists (null until
|
|
1973
|
+
then): a host whose content domain names the port `listen(0)` chose. Until it gives one, every
|
|
1974
|
+
request and upgrade is the app's; the host is started once, when first given while listening,
|
|
1975
|
+
and closed with the server.
|
|
1976
|
+
4. **A served config is checked served.** `checkPage` ran every config opaque, so for a served
|
|
1977
|
+
page it reported what people never see (`document.cookie` throwing in an opaque frame) and
|
|
1978
|
+
missed what they do (the CSP block the throw stopped short of). Now, where the driver can serve
|
|
1979
|
+
(`CheckSession.serve`, both shipped drivers), the check runs Porthole's own `createServer`
|
|
1980
|
+
in process (a random secret; the check page, `https://porthole-check.invalid`, its only host
|
|
1981
|
+
origin), and the driver answers a reserved content domain (`*.porthole-check-content.invalid`)
|
|
1982
|
+
from it, so the content gets an origin of its own, the served CSP in headers, the shell,
|
|
1983
|
+
storage and cookies; each run a new origin. Nothing reaches the app's server or the network
|
|
1984
|
+
for those names. Opaque configs, MCP Apps views and drivers without `serve` run opaque as
|
|
1985
|
+
before. **One numbering:** each inline script is named (`//# sourceURL=porthole-script-<n>`)
|
|
1986
|
+
and its first line recorded, so a runtime error's line is the content's own line, as lint
|
|
1987
|
+
numbers it (it was the line within the script).
|
|
1988
|
+
5. **Conformance says why it skipped:** `@botiverse/porthole/conformance/reporter`, beside the
|
|
1989
|
+
list reporter, prints each skipped case's reason after the run (an inapplicable probe names the
|
|
1990
|
+
page's directive). The example config uses it; ADOPTING's snippet has it and `fullyParallel`.
|
|
1991
|
+
6. **A missing secret is named:** `createContentHost` without one throws "needs a secret: at
|
|
1992
|
+
least 32 random bytes (set PORTHOLE_SECRET; npx porthole secret makes one)" (it threw a
|
|
1993
|
+
`TypeError` from inside the HMAC); a short one says the same. Like any setting it refuses, it
|
|
1994
|
+
is a lasting "misconfigured" instead under the health gate's fallback (P066), and
|
|
1995
|
+
`contentHostFor` answers its 503 with the text. Content off (`domain: ""`) needs no secret.
|
|
1996
|
+
7. **The examples follow the recommended path:** Node on `nodeServer`, Workers on
|
|
1997
|
+
`contentHostFor`; `examples/app.mjs` gives the host's options and a handler that takes the
|
|
1998
|
+
host. ADOPTING says when the other path is right: `nodeHost` for an app that keeps its own
|
|
1999
|
+
server, `createContentHost` at module scope for settings fixed at build time.
|
|
2000
|
+
8. **ADOPTING says how a page without a bundler loads Porthole:** the package's `dist/` served at
|
|
2001
|
+
a path, an import map with the page's nonce, and the display kinds served as a module made
|
|
2002
|
+
from the same object the server's `defineDisplays` gets.
|
|
2003
|
+
9. **`entryTarget(next, authorizeUrl, { app: true })`** also takes a path or address on the app's
|
|
2004
|
+
own origin (one leading slash, no backslash, `http(s)` only, the origin checked once resolved),
|
|
2005
|
+
returned absolute: one open-redirect guard for a sign-in that goes back to a page or to a
|
|
2006
|
+
frame's content. Without the option it is the authorize route only, as before. ADOPTING and
|
|
2007
|
+
the doc comment state the default authorize URL.
|
|
2008
|
+
|
|
2009
|
+
10. **Configs that declare host functions can be checked (#8).** The check page mounted with no
|
|
2010
|
+
handlers, so `mount` threw "No handler for the declared capabilities" before content ran,
|
|
2011
|
+
and `checkTool` on a widget config with `sendPrompt` couldn't run at all. Now the check page
|
|
2012
|
+
answers every declared host function as a host that declines (its `confirm` says no; each
|
|
2013
|
+
handler answers no: `false`, nothing, or a refused tool call or read) and reports each call
|
|
2014
|
+
the host sees (`run.calls`): one a host's gates refuse whatever the person says (no click, bad
|
|
2015
|
+
arguments, not offered, too often) is a problem; one a person or host may decline is a note.
|
|
2016
|
+
A global the shell refuses itself (`sendPrompt` with no click) rejects in the content, which
|
|
2017
|
+
the check reports as the error it is. The manual's examples are now checked under presets
|
|
2018
|
+
that declare every host function too, opaque, served and MCP Apps.
|
|
2019
|
+
|
|
2020
|
+
From Raft Artifacts' adoption of 0.3.0 (its workarounds grew from 14 lines to 34 for these):
|
|
2021
|
+
|
|
2022
|
+
11. **`entry.pathOf` may be async** (`Awaitable`, given the request too): a clean path that needs a
|
|
2023
|
+
lookup (`/` for a page's current version) comes from the database. Where it fails, the frame
|
|
2024
|
+
is issued without a link rather than refused. `link`, `usePortholeLink` and `openInTab` were
|
|
2025
|
+
async already.
|
|
2026
|
+
12. **The runner's `contentSource` may be a function**, asked when a case needs a config: the
|
|
2027
|
+
test server's port isn't known when the spec file loads.
|
|
2028
|
+
13. **`conformanceProjects(devices, { use, launchOptions })`**: `use` adds to every project's;
|
|
2029
|
+
`launchOptions` per engine (a system Chromium's `executablePath` and `args`, where Playwright
|
|
2030
|
+
has no build: arm64 Linux) merges with Porthole's own, Firefox's preferences with the ones its
|
|
2031
|
+
probes need.
|
|
2032
|
+
14. **`PortholeView` renders on the server** what the client's meta says: the frame's placeholder
|
|
2033
|
+
or the fallback, from `portholeClient({ meta })`. Its server snapshot was null, so an SSR'd
|
|
2034
|
+
page (and its tests) had nothing until hydration.
|
|
2035
|
+
15. **`CdpSession` is documented as the least the driver uses**, and a type test holds that
|
|
2036
|
+
Playwright's `CDPSession` and Puppeteer's (as it declares itself, generic over the protocol)
|
|
2037
|
+
are taken with no cast. Checked against Raft's own `@cloudflare/puppeteer` and TypeScript
|
|
2038
|
+
5.9 settings, 0.3.0's type took both already: its cast can simply go.
|
|
2039
|
+
|
|
2040
|
+
From Ferry, after 0.3.0:
|
|
2041
|
+
|
|
2042
|
+
16. **`portholeClient`'s functions are declared `this: void`**, so they pass bare
|
|
2043
|
+
(`useSyncExternalStore(porthole.subscribe, porthole.meta)`) under type-aware lint's
|
|
2044
|
+
`unbound-method`, and none reads `this` (`openInTab` called `this.link`). Method syntax with
|
|
2045
|
+
`this: void` rather than function properties keeps `PortholeClient<"a" | "b">` assignable to
|
|
2046
|
+
`PortholeClient` (the provider's), as methods' parameters are.
|
|
2047
|
+
17. **No content domain is a host with `domain: null`**, the supported setup for a self-hosted app
|
|
2048
|
+
without one: no secret needed, and `/porthole/meta` answers `{ served: false }`, so pages show
|
|
2049
|
+
opaque rather than pending. ADOPTING says so.
|
|
2050
|
+
18. **A provider's scheme flip or new `themeKey` re-themes its frames in place (#9).** The
|
|
2051
|
+
provider's context value is renewed with its scheme, theme and themeKey, and two effects were
|
|
2052
|
+
keyed on it: `PortholeFrame`'s registry effect (whose cleanup let the frame go, so it was made
|
|
2053
|
+
again) and the mount effect. Every display was destroyed and made again: widgets lost their
|
|
2054
|
+
state, url-mode previews reloaded. Both now depend only on the provider's stable parts (the
|
|
2055
|
+
registry, heights, handlers, confirm, locator, nonce, hostInfo by value), and read the scheme
|
|
2056
|
+
and theme when used; flips go through `setTheme`, a new themeKey through `refreshTheme`, and a
|
|
2057
|
+
new theme function (tokens passed inline) through `refreshTheme` where its values changed.
|
|
2058
|
+
|
|
2059
|
+
**Risks.**
|
|
2060
|
+
- Item 9 widens what a guard accepts, on request. Bounded by `test/kit03.test.ts`: `//host`,
|
|
2061
|
+
`/\host`, a tab inside the slashes, `\\host`, another scheme, a look-alike host, `javascript:`
|
|
2062
|
+
and `data:` are all null.
|
|
2063
|
+
- Item 3 sends every request to the app until the host exists, the content domain's included.
|
|
2064
|
+
Nothing names that domain before the host does (its port is the one just chosen); an app whose
|
|
2065
|
+
DNS already points the content domain at it makes the host before it listens.
|
|
2066
|
+
- Item 1 trusts `authorizeUrl`, which the app sets (or its first app origin); the request can no
|
|
2067
|
+
longer choose where sign-in comes back to, which is narrower than before.
|
|
2068
|
+
|
|
2069
|
+
**Why.** Each item was a workaround or a wrong guess: Ferry's sign-in stayed put behind its dev
|
|
2070
|
+
proxy and a TLS edge; an app's own dialog couldn't answer "edit first" without a decline that
|
|
2071
|
+
counts; an app that makes its host after its server starts had to drop to `nodeHost`; an agent told
|
|
2072
|
+
to fix line 6 of a served page's runtime error edited the wrong line, for an error people never see;
|
|
2073
|
+
`[1.connect]` showed as a bare "-"; a forgotten secret crashed inside the HMAC; Ferry's widget
|
|
2074
|
+
config couldn't be checked at all (#8); the cold adopter had to choose between the guide's path and
|
|
2075
|
+
the examples', read `examples/app.mjs` to load the browser modules, and read `client.js` to learn
|
|
2076
|
+
`entryTarget` refused `/`; Raft Artifacts' workarounds for items 11 to 15 had grown to 34 lines;
|
|
2077
|
+
Ferry's type-aware lint refused the client's functions passed bare, it made no host at all without a
|
|
2078
|
+
content domain, leaving displays pending, and every theme flip made its displays again (#9).
|
|
2079
|
+
**Measured.** `test/kit03.test.ts` (a proxied authorize request, the SPA `next`, the lazy
|
|
2080
|
+
`nodeServer`, the secret, `entryTarget`, an async `pathOf`, the client's functions taken bare and
|
|
2081
|
+
linted, no content domain); the prod-shape profile signs in through its TLS edge with the kit app
|
|
2082
|
+
reached as `http` behind it (failing before item 1); `leak/react.spec.ts` (four redirects, never
|
|
2083
|
+
muted, no prompt sent); `leak/check.spec.ts` (a served page: no cookie error, the connect block
|
|
2084
|
+
reported, errors on their file lines, on both drivers; every host function declared: the manual's
|
|
2085
|
+
examples pass, and a widget's calls on load are answered and reported, opaque and served);
|
|
2086
|
+
`test/check.test.ts` (the calls' words, the CDP session types); `test/conformance-options.test.ts`;
|
|
2087
|
+
`test/react-ssr.test.ts` (failing before item 14); `leak/react.spec.ts`'s flips of the provider's
|
|
2088
|
+
scheme and themeKey keep each frame element, its window and its page, opaque, served and url
|
|
2089
|
+
(failing before item 18); the examples' unit tests and their conformance run on three engines.
|
|
2090
|
+
**Revisit when** a driver that can't intercept requests needs served checks (it would need a
|
|
2091
|
+
real content domain).
|
package/docs/DESIGN.md
CHANGED
|
@@ -437,7 +437,10 @@ a link sent to someone with access.
|
|
|
437
437
|
frame, never the sign-in**: a plain page asking for a new tab (`blocked: sign-in`). No
|
|
438
438
|
access: the app's refusal on a tab (`refusal(status, request, entry)`; nothing returned:
|
|
439
439
|
Porthole's page), a plain page in a frame; never content. Both hooks get the address decoded
|
|
440
|
-
(`EntryContext`: label, scope, path, clean URL, the instance, framed).
|
|
440
|
+
(`EntryContext`: label, scope, path, clean URL, the instance, framed). `returnTo` (and
|
|
441
|
+
`entry.spa`'s `next`) is `authorizeUrl` with the request's query: the app as it is reached,
|
|
442
|
+
never the request's own URL, whose scheme and host behind a TLS edge or a dev proxy are
|
|
443
|
+
another's (P074).
|
|
441
444
|
3. Granted, a 302 back to `/__porthole/entry?code=…`: a one-time code (60 s), bound to the
|
|
442
445
|
label, the path and the nonce. The content origin redeems it only on that label and only with
|
|
443
446
|
the nonce's cookie, sets the session (bound to the path) and 303s to the clean address. The
|
|
@@ -489,7 +492,11 @@ The tests are located in the app's own spec file, at the `defineHostConformance`
|
|
|
489
492
|
addresses may be async (an app publishes a test page on demand and returns its real instance,
|
|
490
493
|
which the issue endpoint then gets); `entry.unknown` lists addresses that name nothing, each of
|
|
491
494
|
which must be a 404 on the content domain. `hostConformance(options)` gives the hosts for an app
|
|
492
|
-
that registers the cases itself.
|
|
495
|
+
that registers the cases itself. Playwright's list and line reporters show a skipped case without
|
|
496
|
+
its reason; `@botiverse/porthole/conformance/reporter` prints each reason after the run (P074).
|
|
497
|
+
`contentSource` may be a function, asked per case (a port known only once the server runs), and
|
|
498
|
+
`conformanceProjects` merges an app's own `use` and per-engine `launchOptions` (a system
|
|
499
|
+
browser) with Porthole's (P074).
|
|
493
500
|
|
|
494
501
|
**Prod shape** (`ops/prod-shape/`, `ops/prod-shape/run.sh`). Docker compose: Caddy's internal
|
|
495
502
|
CA serving `app.test`, `*.content.test` (same-site siblings, as in production without a Public
|
|
@@ -509,6 +516,81 @@ package carries these docs (`docs/`), and `/server` exports the types an app's c
|
|
|
509
516
|
renamed, so there is no compat module. `FrameBlock` gains `sign-in`; `ContentDomain.name` takes
|
|
510
517
|
a `Naming` (any function still fits).
|
|
511
518
|
|
|
519
|
+
### The host kit 0.3: the client, the bootstrap, the relay (P072)
|
|
520
|
+
|
|
521
|
+
What both adopters still wrote after 0.2 moves into Porthole (ADOPTING.md is the walk-through):
|
|
522
|
+
- **`defineDisplays(kinds)`** (core): each kind's preset and options once; opaque and served
|
|
523
|
+
configs (memoized per content source), the kind an instance names, frame sources and the
|
|
524
|
+
`frame-src` directive without a server, and a served kind's config for the manual without a real
|
|
525
|
+
origin. `createContentHost({ displays })` and the conformance runner take it.
|
|
526
|
+
- **`content.routes(viewerOf)`** (/server): one mount under `/porthole` (`prefix`): `POST frames`
|
|
527
|
+
(`issue`, answering `link`, the clean address, where `entry.pathOf` names the path, which it
|
|
528
|
+
may look up: a promise, P074), `GET
|
|
529
|
+
authorize` (its URL now the default `entry.authorizeUrl`), `GET meta` (`ContentClientMeta`:
|
|
530
|
+
served, content source, frame sources, health) and `POST`/`DELETE handoff`.
|
|
531
|
+
`contentHostFor(build)` gives one host per Workers `env`, failing closed with a plain 503;
|
|
532
|
+
`nodeServer({ content, app })` is the whole Node server (`content` may be a function giving the
|
|
533
|
+
host once made, P074). A missing or short secret throws, naming `PORTHOLE_SECRET`.
|
|
534
|
+
- **The client:** `portholeClient({ displays, base, headers, credentials, handoff })` is the
|
|
535
|
+
locator and knows each kind's config from the meta (null until known), links, `openInTab`
|
|
536
|
+
(a tab opened in the click, then sent to the address), the handoff, and `entryTarget` (the
|
|
537
|
+
authorize route only; with `{ app: true }` also a path or address on the app's origin, P074).
|
|
538
|
+
`frameFallback(outcome)` words what to offer when a frame shows nothing (`needs-tab`,
|
|
539
|
+
`denied`, `expired`, `failed`, `timeout`). React: `PortholeView` (a display by kind, served or
|
|
540
|
+
opaque, with its fallback), `usePortholeLink`, and the provider's shared `scheme`, `theme`
|
|
541
|
+
(`cssVariableTheme`), `nonce: "auto"`, `handlers`, `openLink`, `notify` and `renderConfirm`
|
|
542
|
+
(`accept`, `decline`, and `redirect`: `"redirected"`, which doesn't count toward muting, P074).
|
|
543
|
+
A flip of the provider's scheme or a new themeKey re-themes running frames in place: no effect
|
|
544
|
+
that makes a display depends on the context value those renew (#9, P074).
|
|
545
|
+
- **The viewer handoff** for a page that holds a token: `POST /porthole/handoff` with the app's
|
|
546
|
+
own credential, from the app's own page, sets a 10-minute `HttpOnly` cookie scoped to the
|
|
547
|
+
prefix holding a Porthole-signed key (the viewer's id and expiry), which the authorize route
|
|
548
|
+
reads when `viewerOf` knows no one. `entry.spa` signs a person in through the app's own route.
|
|
549
|
+
- **The url-mode relay kit:** `upstreamHeaders` (the header rewrite `proxyTo` makes, for any
|
|
550
|
+
transport, WebSockets too), `statusPage` (the frame-status page with its script under its hash),
|
|
551
|
+
`nodeHost`'s `appSocket` without Porthole's cookies, `content.forget()` for cached `authorize`
|
|
552
|
+
answers.
|
|
553
|
+
- **Server:** `health.onServedChange(served)`, once per flip; `log` takes a `{ info, warn, error }`
|
|
554
|
+
logger.
|
|
555
|
+
|
|
556
|
+
### The agent's side: lint, check, tools (P073)
|
|
557
|
+
|
|
558
|
+
- **`lintContent(config, content)`** (core, pure): what can be told without running it, each
|
|
559
|
+
finding worded for the agent with its line. Errors only for what certainly fails or is cut:
|
|
560
|
+
over the size, a document where a fragment goes that has no body, nested frames and plugins,
|
|
561
|
+
`document.write`. Warnings for the rest: a document sent as a widget (taken as its body,
|
|
562
|
+
`fragmentOf`), the clipboard, dialogs, forms, hosts outside egress, unpinned CDN libraries,
|
|
563
|
+
`position: fixed` in a flow layout, new windows without `openLink`.
|
|
564
|
+
- **`admitContent(config, content, { refuseOn })`**: the show tool's gate. It refuses errors by
|
|
565
|
+
default with a text that says what to change; otherwise it shows the content (a widget's
|
|
566
|
+
document taken as its body) and returns the warnings as a note.
|
|
567
|
+
- **`checkPage({ config, content, driver })`** (`/check`): the content in the real sandbox at each
|
|
568
|
+
width and scheme (defaults: the manual's phone and desktop widths, light and dark unless
|
|
569
|
+
unthemed). The check page (`src/check/page.ts`, bundled and shipped as `/check/page`) is served
|
|
570
|
+
by the driver at a fixed origin (`https://porthole-check.invalid`), mounts the content with a
|
|
571
|
+
small instrument first in it, and hears errors, rejections, CSP blocks, failed loads, the
|
|
572
|
+
console and the document's width by `postMessage`; heights come from the display's resize
|
|
573
|
+
events. A served config runs served (P074): the driver also answers a reserved content domain
|
|
574
|
+
(`*.porthole-check-content.invalid`) with an in-process `createServer` (a random secret, the
|
|
575
|
+
check page as its only host origin), so the content gets its own origin, the served CSP in
|
|
576
|
+
headers, the shell, storage and cookies, each run on a new origin; an opaque config, an MCP
|
|
577
|
+
Apps view (as a page with the view's egress) and a driver without `serve` run opaque. Each
|
|
578
|
+
inline script is named (`//# sourceURL=porthole-script-<n>`) and its first line recorded, so an
|
|
579
|
+
error's line is the content's own line, as lint numbers it. Every host function the config
|
|
580
|
+
declares is answered as a host that declines (`confirm` says no; each handler answers no), and
|
|
581
|
+
each call the host sees is reported (`run.calls`): refused by a gate whatever the person says (no
|
|
582
|
+
click, bad arguments, too often) a problem, declined or answered a note. A global the shell
|
|
583
|
+
refuses itself without a click (`sendPrompt`) rejects in the content, so it shows as an error. The report's `text` names each
|
|
584
|
+
problem once, with where it happened, at most 8. Drivers: `playwrightDriver(browser)` (requests
|
|
585
|
+
answered by `page.route`), and `cdpDriver(open)` over any CDP session (`Fetch` interception;
|
|
586
|
+
Cloudflare Browser Rendering from a Worker).
|
|
587
|
+
- **Tools:** `showTool`, `guideTool`, `checkTool` give `{ name, description, inputSchema }` from
|
|
588
|
+
the config; `answerGuide` answers the guide tool; `guideChanges(from, to)` is the notice when a
|
|
589
|
+
kind flips between served and opaque. `examples/mcp/server.mjs` wires them over MCP.
|
|
590
|
+
- **The manual's examples pass the check:** `leak/check.spec.ts` runs every `GUIDE_EXAMPLES`
|
|
591
|
+
entry under each preset at the manual's widths in light and dark, on three engines (OBJECTIVES
|
|
592
|
+
criterion 5).
|
|
593
|
+
|
|
512
594
|
### Protocol adapters
|
|
513
595
|
|
|
514
596
|
The core ships the adapter for the MCP Apps subset its own shell speaks
|