@botiverse/porthole 0.14.5 → 0.14.7

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.
Files changed (76) hide show
  1. package/CHANGELOG.md +66 -0
  2. package/dist/check/page-source.js +1 -1
  3. package/dist/check/page.js +5 -1
  4. package/dist/compile/policy.d.ts +6 -0
  5. package/dist/compile/policy.js +6 -0
  6. package/dist/conformance/entry.d.ts +25 -6
  7. package/dist/conformance/entry.js +69 -18
  8. package/dist/conformance/harness/page.d.ts +12 -0
  9. package/dist/conformance/harness/page.js +95 -51
  10. package/dist/conformance/harness-source.js +1 -1
  11. package/dist/conformance/host-kit.js +39 -13
  12. package/dist/conformance/served.js +148 -0
  13. package/dist/files/paths.d.ts +2 -2
  14. package/dist/files/paths.js +12 -2
  15. package/dist/host/client.d.ts +8 -0
  16. package/dist/host/client.js +47 -17
  17. package/dist/host/create-host.d.ts +10 -0
  18. package/dist/host/create-host.js +124 -10
  19. package/dist/host/door.d.ts +41 -0
  20. package/dist/host/door.js +55 -0
  21. package/dist/host/locate.js +2 -0
  22. package/dist/host/locator.d.ts +55 -3
  23. package/dist/host/locator.js +152 -42
  24. package/dist/host/outcome.d.ts +54 -1
  25. package/dist/host/outcome.js +33 -8
  26. package/dist/host/types.d.ts +10 -2
  27. package/dist/isolation/served.d.ts +1 -1
  28. package/dist/isolation/served.js +35 -0
  29. package/dist/isolation/types.d.ts +20 -2
  30. package/dist/isolation/types.js +2 -0
  31. package/dist/platform/types.d.ts +22 -0
  32. package/dist/platform/web.js +55 -12
  33. package/dist/react/view.d.ts +13 -0
  34. package/dist/react/view.js +101 -2
  35. package/dist/server/files.d.ts +11 -0
  36. package/dist/server/files.js +26 -4
  37. package/dist/server/host.js +106 -28
  38. package/dist/server/index.d.ts +2 -1
  39. package/dist/server/index.js +7 -1
  40. package/dist/server/pages.d.ts +32 -0
  41. package/dist/server/pages.js +82 -6
  42. package/dist/server/server.js +194 -16
  43. package/dist/server/types.d.ts +38 -1
  44. package/dist/transport/post-message.d.ts +1 -9
  45. package/dist/transport/post-message.js +2 -8
  46. package/docs/ADOPTING.md +73 -4
  47. package/docs/DECISIONS.md +245 -0
  48. package/docs/DESIGN.md +24 -18
  49. package/docs/THREAT_MODEL.md +79 -13
  50. package/package.json +1 -1
  51. package/src/check/page.ts +6 -1
  52. package/src/compile/policy.ts +7 -0
  53. package/src/conformance/entry.ts +129 -24
  54. package/src/conformance/harness/page.ts +112 -49
  55. package/src/conformance/host-kit.ts +53 -16
  56. package/src/conformance/served.ts +184 -0
  57. package/src/files/paths.ts +11 -2
  58. package/src/host/client.ts +59 -22
  59. package/src/host/create-host.ts +144 -18
  60. package/src/host/door.ts +97 -0
  61. package/src/host/locate.ts +2 -0
  62. package/src/host/locator.ts +208 -57
  63. package/src/host/outcome.ts +41 -9
  64. package/src/host/types.ts +10 -2
  65. package/src/isolation/served.ts +40 -1
  66. package/src/isolation/types.ts +19 -2
  67. package/src/platform/types.ts +21 -0
  68. package/src/platform/web.ts +55 -20
  69. package/src/react/view.tsx +149 -2
  70. package/src/server/files.ts +37 -5
  71. package/src/server/host.ts +131 -46
  72. package/src/server/index.ts +7 -1
  73. package/src/server/pages.ts +101 -6
  74. package/src/server/server.ts +266 -32
  75. package/src/server/types.ts +41 -1
  76. package/src/transport/post-message.ts +1 -9
@@ -1,6 +1,6 @@
1
+ import { DOOR_SANDBOX_TOKENS } from "../compile/policy.ts";
1
2
  import type { ColorScheme } from "../config/schema.ts";
2
3
  import {
3
- FRAME_STATUS_METHOD,
4
4
  SHELL_BEAT_METHOD,
5
5
  SHELL_LOOK_METHOD,
6
6
  SHELL_METHOD_PREFIX,
@@ -9,14 +9,7 @@ import {
9
9
  import { postMessageTransport } from "../transport/post-message.ts";
10
10
  import { focusGuard, type FocusGuard, type FocusTake } from "./focus-guard.ts";
11
11
  import type { Transport } from "../transport/types.ts";
12
- import type { PlatformHost, Surface, SurfaceSpec } from "./types.ts";
13
-
14
- /** A frame-status message (`porthole/notifications/frame-status`), by its method alone. */
15
- const isFrameStatus = (data: unknown): boolean =>
16
- data !== null &&
17
- typeof data === "object" &&
18
- (data as { jsonrpc?: unknown }).jsonrpc === "2.0" &&
19
- (data as { method?: unknown }).method === FRAME_STATUS_METHOD;
12
+ import type { DoorSurface, PlatformHost, Surface, SurfaceSpec } from "./types.ts";
20
13
 
21
14
  /** A shell's own message (P111), by its namespace. */
22
15
  const isShellWord = (data: unknown): data is { method: string; params?: unknown } =>
@@ -139,17 +132,10 @@ export const webPlatform: PlatformHost = {
139
132
  const guard = focusGuard(view);
140
133
  const taken = new Set<(take: FocusTake) => void>();
141
134
  const nested = spec.nested === true && spec.source.kind === "url";
142
- // A served frame may pass through the host's own pages (a redirect entry's, P068): what they
143
- // say of the frame's status is heard too, and nothing else from there.
144
- const own = view.origin;
145
- const opened = postMessageTransport(
146
- () => frame.contentWindow,
147
- origin,
148
- view,
149
- origin === "null" || own === "null" || own === origin
150
- ? undefined
151
- : { origin: own, accept: isFrameStatus },
152
- );
135
+ // A frame is heard from its own window and its located origin alone: never the host's own
136
+ // origin (P125 removed P068's in-frame pages and the channel that heard them), so no page of
137
+ // the host's own can speak for a frame either.
138
+ const opened = postMessageTransport(() => frame.contentWindow, origin, view);
153
139
  const unguard = guard.add(
154
140
  frame,
155
141
  (take) => {
@@ -227,4 +213,53 @@ export const webPlatform: PlatformHost = {
227
213
  },
228
214
  };
229
215
  },
216
+ /**
217
+ * A served display's door (P125): hidden (no size, `visibility: hidden`, which still runs its
218
+ * script and fires its load on all three engines), out of focus and of the accessibility tree,
219
+ * sandboxed with scripts alone, no `allow`, no name. Nothing but its frame status is heard from
220
+ * it, from its window and the opaque origin alone; the focus guard, the bridge and annotations
221
+ * never see it.
222
+ */
223
+ createDoor(container: HTMLElement, spec: { readonly url: string }): DoorSurface {
224
+ // oxlint-disable-next-line react/iframe-missing-sandbox -- set from the door's list, next
225
+ const frame = container.ownerDocument.createElement("iframe");
226
+ frame.setAttribute("sandbox", DOOR_SANDBOX_TOKENS.join(" "));
227
+ frame.setAttribute("allow", "");
228
+ frame.setAttribute("referrerpolicy", "no-referrer");
229
+ frame.setAttribute("aria-hidden", "true");
230
+ frame.setAttribute("tabindex", "-1");
231
+ frame.setAttribute("inert", "");
232
+ frame.setAttribute("loading", "eager");
233
+ frame.dataset.portholeDoor = "";
234
+ Object.assign(frame.style, {
235
+ display: "block",
236
+ width: "0",
237
+ height: "0",
238
+ border: "0",
239
+ visibility: "hidden",
240
+ });
241
+ frame.src = spec.url;
242
+ const loaded = new Set<() => void>();
243
+ frame.addEventListener("load", () => {
244
+ for (const listener of loaded) {
245
+ listener();
246
+ }
247
+ });
248
+ container.append(frame);
249
+ const view = container.ownerDocument.defaultView ?? window;
250
+ const transport = postMessageTransport(() => frame.contentWindow, "null", view);
251
+ return {
252
+ transport,
253
+ element: frame,
254
+ onLoad(listener) {
255
+ loaded.add(listener);
256
+ return () => loaded.delete(listener);
257
+ },
258
+ destroy() {
259
+ loaded.clear();
260
+ transport.close();
261
+ frame.remove();
262
+ },
263
+ };
264
+ },
230
265
  };
@@ -3,6 +3,7 @@ import {
3
3
  useContext,
4
4
  useEffect,
5
5
  useImperativeHandle,
6
+ useMemo,
6
7
  useRef,
7
8
  useState,
8
9
  useSyncExternalStore,
@@ -11,8 +12,10 @@ import {
11
12
  } from "react";
12
13
  import type { ColorScheme } from "../config/schema.ts";
13
14
  import { frameFallback, type FrameFallback, type PortholeClient } from "../host/client.ts";
15
+ import { oneShot } from "../host/locator.ts";
16
+ import { originMatchesSource } from "../isolation/served.ts";
14
17
  import type { FrameOutcome } from "../host/types.ts";
15
- import type { InstanceRef } from "../isolation/types.ts";
18
+ import type { FrameLocation, InstanceRef } from "../isolation/types.ts";
16
19
  import {
17
20
  PortholeFrame,
18
21
  PortholeContext,
@@ -49,6 +52,13 @@ export interface PortholeViewProps extends Omit<
49
52
  * back in its confirmations only, never sent to the frame (P077).
50
53
  */
51
54
  readonly instance?: InstanceRef;
55
+ /**
56
+ * A clean address to show instead of an instance (P125): resolved through the client
57
+ * (`client.resolve`) before any frame. What it names is framed through its issued location (a
58
+ * door, a ticket); signed out, denied or not found, the fallback is drawn from that answer, and
59
+ * no frame is made. A clean address is never framed itself.
60
+ */
61
+ readonly address?: string;
52
62
  /**
53
63
  * The content: a served shell's to draw, and what an opaque frame shows while frames aren't
54
64
  * served (a stored page's HTML). Without it, a served-only display shows the fallback then.
@@ -96,9 +106,146 @@ function DefaultFallback({ title, message, link }: PortholeFallbackProps): React
96
106
  }
97
107
 
98
108
  export function PortholeView(props: PortholeViewProps): ReactElement | null {
109
+ return props.address !== undefined && props.instance === undefined ? (
110
+ <AddressView {...props} address={props.address} />
111
+ ) : (
112
+ <InstanceView {...props} />
113
+ );
114
+ }
115
+
116
+ /**
117
+ * Whether `address` may be offered as a fallback's "open in a new tab": a clean address on the
118
+ * served content domain (`contentSource`, its scheme and port), not Porthole's own paths. Anything
119
+ * else (another site, a typo the server answered 404 for elsewhere) gets no link.
120
+ */
121
+ export function tabLinkOf(
122
+ address: string,
123
+ contentSource: string | null | undefined,
124
+ ): string | null {
125
+ if (contentSource === null || contentSource === undefined) {
126
+ return null;
127
+ }
128
+ try {
129
+ const url = new URL(address);
130
+ return originMatchesSource(url.origin, contentSource) &&
131
+ !url.pathname.startsWith("/__porthole/")
132
+ ? url.href
133
+ : null;
134
+ } catch {
135
+ return null;
136
+ }
137
+ }
138
+
139
+ /** A clean address's view (P125): resolved first; its instance's view, or the answer's fallback. */
140
+ function AddressView(props: PortholeViewProps & { readonly address: string }): ReactElement | null {
141
+ const client = useClient();
142
+ const page = useContext(PortholeContext);
143
+ const meta = useMeta(client);
144
+ const { address, fallback, pending, onOutcome } = props;
145
+ const [state, setState] = useState<
146
+ | { readonly kind: "resolving" }
147
+ | {
148
+ readonly kind: "instance";
149
+ readonly instance: InstanceRef;
150
+ readonly location: FrameLocation;
151
+ }
152
+ | { readonly kind: "refused"; readonly said: FrameFallback }
153
+ >({ kind: "resolving" });
154
+ const [generation, setGeneration] = useState(0);
155
+ const retry = useCallback(() => setGeneration((each) => each + 1), []);
156
+ useEffect(() => {
157
+ const controller = new AbortController();
158
+ setState({ kind: "resolving" });
159
+ client.resolve(address, controller.signal).then(
160
+ (resolved) => {
161
+ if (controller.signal.aborted) {
162
+ return;
163
+ }
164
+ if ("outcome" in resolved) {
165
+ onOutcome?.(resolved.outcome);
166
+ const said = frameFallback(resolved.outcome);
167
+ setState(
168
+ said === null
169
+ ? {
170
+ kind: "refused",
171
+ said: { kind: "failed", title: "This can't be shown now", message: "" },
172
+ }
173
+ : { kind: "refused", said },
174
+ );
175
+ return;
176
+ }
177
+ setState({ kind: "instance", instance: resolved.instance, location: resolved.location });
178
+ },
179
+ () => {
180
+ if (controller.signal.aborted) {
181
+ return;
182
+ }
183
+ const outcome: FrameOutcome = { state: "blocked", reason: "locate" };
184
+ onOutcome?.(outcome);
185
+ setState({
186
+ kind: "refused",
187
+ said: frameFallback(outcome) ?? {
188
+ kind: "failed",
189
+ title: "This can't be shown now",
190
+ message: "",
191
+ },
192
+ });
193
+ },
194
+ );
195
+ return () => controller.abort();
196
+ // The address and a retry decide; a new onOutcome doesn't resolve it again.
197
+ // oxlint-disable-next-line react-hooks/exhaustive-deps
198
+ }, [client, address, generation]);
199
+ // This view's own locator (P125): its frame's first run takes the location it resolved, once;
200
+ // every later run issues afresh. No other view of the instance can take it.
201
+ const located = state.kind === "instance" ? state.location : null;
202
+ const own = useMemo(() => {
203
+ if (located === null) {
204
+ return null;
205
+ }
206
+ const locator = oneShot(located, { locate: (each, signal) => client.locate(each, signal) });
207
+ return {
208
+ ...page,
209
+ locate: (each: InstanceRef, signal?: AbortSignal) => locator.locate(each, signal),
210
+ };
211
+ }, [page, located, client]);
212
+ if (state.kind === "resolving") {
213
+ return <>{pending ?? null}</>;
214
+ }
215
+ if (state.kind === "refused") {
216
+ // The clean address is the "open in a new tab" only where it is one: on the content domain.
217
+ return (
218
+ <>
219
+ {(fallback ?? DefaultFallback)({
220
+ ...state.said,
221
+ link: tabLinkOf(address, meta?.contentSource),
222
+ retry,
223
+ })}
224
+ </>
225
+ );
226
+ }
227
+ const { address: _address, ...rest } = props;
228
+ return (
229
+ <PortholeContext.Provider value={own ?? page}>
230
+ <InstanceView {...rest} instance={state.instance} />
231
+ </PortholeContext.Provider>
232
+ );
233
+ }
234
+
235
+ function InstanceView(props: PortholeViewProps): ReactElement | null {
99
236
  const client = useClient();
100
237
  const meta = useMeta(client);
101
- const { display, instance, content, fallback, pending, onOutcome, ref, ...frame } = props;
238
+ const {
239
+ display,
240
+ instance,
241
+ content,
242
+ fallback,
243
+ pending,
244
+ onOutcome,
245
+ ref,
246
+ address: _address,
247
+ ...frame
248
+ } = props;
102
249
  // The view's handle (P118) is there while the view is, a fallback drawn or not: its calls reach
103
250
  // the frame's display when one runs, and do nothing otherwise.
104
251
  const shown = useRef<PortholeFrameHandle>(null);
@@ -45,7 +45,14 @@ export interface FileServing {
45
45
  * moves the frame to the entry's own address under `base` before anything loads, and renews
46
46
  * that address before it ends (`expires`, epoch ms).
47
47
  */
48
- readonly ticket?: { readonly expires: number };
48
+ readonly ticket?: {
49
+ readonly expires: number;
50
+ /**
51
+ * A page below the base the ticket was issued for (P125: a clean address's file, resolved
52
+ * through `issue`), opened instead of the entry (`ticketPage`).
53
+ */
54
+ readonly page?: string;
55
+ };
49
56
  /** The artifact version the set is, which its pages name in their notices to the host (P098). */
50
57
  readonly artifact?: { readonly id: string; readonly version: string };
51
58
  }
@@ -175,6 +182,33 @@ function nothing(serving: FileServing, status: 403 | 404 | 405, method: string):
175
182
  });
176
183
  }
177
184
 
185
+ /**
186
+ * The page a ticket opens in a set (P081, P125): its entry, or the page below the base it was
187
+ * issued for, found as a navigation finds it (`dir/` its index, `name` its `.html`); null when
188
+ * that is no page of the set. The door asks the same (`serveDoor`), so both say `not-found` alike.
189
+ */
190
+ export function ticketPage(set: StoredFiles, page?: string): string | null {
191
+ const has = (each: string): boolean => Object.hasOwn(set.files, each);
192
+ const entry = set.entry ?? DEFAULT_ENTRY;
193
+ if (page === undefined || page === "") {
194
+ return has(entry) ? entry : null;
195
+ }
196
+ const path = requestFilePath(page);
197
+ if (path === null) {
198
+ return null;
199
+ }
200
+ let found = lookupFile(has, path, { entry, navigation: false });
201
+ if (found.kind === "redirect") {
202
+ found = lookupFile(has, found.to, { entry, navigation: false });
203
+ }
204
+ return found.kind === "file" && found.status === 200 && fileTypeOf(found.path).role === "page"
205
+ ? found.path
206
+ : null;
207
+ }
208
+
209
+ const ticketLookup = (path: string | null): FileLookup =>
210
+ path === null ? { kind: "none" } : { kind: "file", path, status: 200 };
211
+
178
212
  export async function serveFile(serving: FileServing): Promise<Response> {
179
213
  const { request, set } = serving;
180
214
  const method = request.method.toUpperCase();
@@ -197,9 +231,7 @@ export async function serveFile(serving: FileServing): Promise<Response> {
197
231
  const entryPath = set.entry ?? DEFAULT_ENTRY;
198
232
  const found: FileLookup =
199
233
  serving.ticket !== undefined
200
- ? has(entryPath)
201
- ? { kind: "file", path: entryPath, status: 200 }
202
- : { kind: "none" }
234
+ ? ticketLookup(ticketPage(set, serving.ticket.page))
203
235
  : lookupFile(has, path, {
204
236
  ...(set.entry === undefined ? {} : { entry: set.entry }),
205
237
  ...(set.spa === undefined ? {} : { spa: set.spa }),
@@ -282,7 +314,7 @@ export async function serveFile(serving: FileServing): Promise<Response> {
282
314
  ...(serving.ticket === undefined
283
315
  ? {}
284
316
  : {
285
- address: `${base}${found.path.includes("/") ? encodePath(found.path) : ""}`,
317
+ address: `${base}${found.path === entryPath && !found.path.includes("/") ? "" : encodePath(found.path)}`,
286
318
  expires: serving.ticket.expires,
287
319
  }),
288
320
  ...(serving.artifact === undefined ? {} : { set: serving.artifact }),
@@ -12,7 +12,7 @@ import {
12
12
  } from "./domain.ts";
13
13
  import { reservedLabels, type Naming } from "./naming.ts";
14
14
  import { peerAddress } from "./peer.ts";
15
- import { appStatusPage } from "./pages.ts";
15
+ import { appStatusPage, tabOnlyPage } from "./pages.ts";
16
16
  import { createServer } from "./server.ts";
17
17
  import type {
18
18
  Access,
@@ -825,6 +825,30 @@ export function createContentHost<V>(options: ContentHostOptions<V>): ContentHos
825
825
 
826
826
  // Issues per key per minute, in this process.
827
827
  const issued = new Map<string, number[]>();
828
+ /**
829
+ * What a clean address names (P068, P125): its label's scope (the naming's `scopeOf`) and what
830
+ * `entry.at` answers for its path, for this viewer. One mapping for a tab (`authorize`) and for a
831
+ * frame (`issue` given `{ address }`), so a frame shows what the address's tab would.
832
+ */
833
+ const entryAt = async (
834
+ label: string,
835
+ pathname: string,
836
+ viewer: V | null,
837
+ request: Request,
838
+ ): Promise<{
839
+ readonly scope: string | null;
840
+ readonly answer: InstanceRef | FileAddress | null;
841
+ }> => {
842
+ const scope = options.name?.scopeOf?.(label) ?? null;
843
+ const at = options.entry?.at;
844
+ const answer =
845
+ scope === null || at === undefined
846
+ ? null
847
+ : ((await at(scope, new URL(pathname, "https://x.invalid").pathname, viewer, request)) ??
848
+ null);
849
+ return { scope, answer };
850
+ };
851
+
828
852
  const withinRate = (key: string): boolean => {
829
853
  const limit = options.rateLimit;
830
854
  if (limit === undefined) {
@@ -1038,6 +1062,10 @@ export function createContentHost<V>(options: ContentHostOptions<V>): ContentHos
1038
1062
  } catch {
1039
1063
  return refusal(400, "bad-json", "The body is JSON: { instance }");
1040
1064
  }
1065
+ // A clean address (P125): what it names, as its tab would open it, issued for a frame.
1066
+ if (isRecord(body) && body.instance === undefined && body.address !== undefined) {
1067
+ return issueAddress(body.address, viewer, request);
1068
+ }
1041
1069
  const proposal = isRecord(body) ? body.instance : undefined;
1042
1070
  if (
1043
1071
  !isRecord(proposal) ||
@@ -1062,25 +1090,99 @@ export function createContentHost<V>(options: ContentHostOptions<V>): ContentHos
1062
1090
  ? refusal(401, "unauthenticated", "Sign in to see this")
1063
1091
  : refusal(403, "forbidden", "You can't see this");
1064
1092
  }
1065
- let location: FrameLocation;
1066
- try {
1067
- location = await server.issue(instance, grant);
1068
- } catch (error) {
1069
- return refusal(409, "refused", error instanceof Error ? error.message : String(error));
1093
+ return issuedFor(instance, grant, request);
1094
+ } catch {
1095
+ return refusal(500, "failed", "The app's policy failed");
1096
+ }
1097
+ };
1098
+
1099
+ /** A location issued for what the host's access granted, with its clean address. */
1100
+ async function issuedFor(
1101
+ instance: InstanceRef,
1102
+ grant: Grant,
1103
+ request: Request,
1104
+ more: { readonly page?: string; readonly resolved?: boolean } = {},
1105
+ ): Promise<Response> {
1106
+ let location: FrameLocation;
1107
+ try {
1108
+ location = await server!.issue(
1109
+ instance,
1110
+ grant,
1111
+ more.page === undefined ? undefined : { page: more.page },
1112
+ );
1113
+ } catch (error) {
1114
+ return refusal(409, "refused", error instanceof Error ? error.message : String(error));
1115
+ }
1116
+ // The clean address, where the app says the instance's path (P072, P074).
1117
+ let link: string | null = null;
1118
+ try {
1119
+ const path = (await options.entry?.pathOf?.(instance, request)) ?? null;
1120
+ link = path === null ? null : server!.urlOf(instance.scope, path);
1121
+ } catch {
1122
+ link = null;
1123
+ }
1124
+ return json(201, {
1125
+ ...location,
1126
+ ...(link === null ? {} : { link }),
1127
+ // What a clean address named (P125): the instance its later frames are issued for.
1128
+ ...(more.resolved === true ? { instance } : {}),
1129
+ });
1130
+ }
1131
+
1132
+ /**
1133
+ * A clean address asked about for a frame (P125): resolved as its tab's authorize would
1134
+ * resolve it (`entry.at`, then the host's access), and answered before any frame: a location
1135
+ * with its door, or the same refusal the tab would get (401 signed out, 403 no access, 404
1136
+ * nothing there). Never a redirect, never a page: the host shows its fallback from this.
1137
+ */
1138
+ async function issueAddress(
1139
+ given: unknown,
1140
+ viewer: V | null,
1141
+ request: Request,
1142
+ ): Promise<Response> {
1143
+ let url: URL;
1144
+ try {
1145
+ if (typeof given !== "string" || given.length > 4_096) {
1146
+ throw new TypeError("not an address");
1070
1147
  }
1071
- // The clean address, where the app says the instance's path (P072, P074).
1072
- let link: string | null = null;
1073
- try {
1074
- const path = (await options.entry?.pathOf?.(instance, request)) ?? null;
1075
- link = path === null ? null : server.urlOf(instance.scope, path);
1076
- } catch {
1077
- link = null;
1148
+ url = new URL(given);
1149
+ } catch {
1150
+ return refusal(400, "bad-request", "The body is { address: <a clean address> }");
1151
+ }
1152
+ const label = domain?.labelOf(url.host) ?? null;
1153
+ if (
1154
+ options.entry === undefined ||
1155
+ domain === null ||
1156
+ label === null ||
1157
+ domain.originOf(label) !== url.origin ||
1158
+ url.pathname.startsWith("/__porthole/")
1159
+ ) {
1160
+ return refusal(404, "not-found", "That address names nothing here");
1161
+ }
1162
+ try {
1163
+ const { answer } = await entryAt(label, `${url.pathname}${url.search}`, viewer, request);
1164
+ const address = answer !== null && isFileAddress(answer) ? answer : null;
1165
+ const instance = address === null ? (answer as InstanceRef | null) : address.instance;
1166
+ if (instance === null) {
1167
+ return refusal(404, "not-found", "That address names nothing here");
1168
+ }
1169
+ const grant = await options.access(instance, viewer, request);
1170
+ if (grant === null) {
1171
+ return viewer === null
1172
+ ? refusal(401, "unauthenticated", "Sign in to see this")
1173
+ : refusal(403, "forbidden", "You can't see this");
1078
1174
  }
1079
- return json(201, link === null ? location : { ...location, link });
1175
+ // A file set's address below its version (P081): the frame opens at that page.
1176
+ const page =
1177
+ address?.file !== undefined && address.file !== "" ? address.file : undefined;
1178
+ return await issuedFor(instance, grant, request, {
1179
+ ...(page === undefined ? {} : { page }),
1180
+ resolved: true,
1181
+ });
1080
1182
  } catch {
1081
1183
  return refusal(500, "failed", "The app's policy failed");
1082
1184
  }
1083
- };
1185
+ }
1084
1186
  },
1085
1187
 
1086
1188
  meta: () => ({
@@ -1231,20 +1333,19 @@ export function createContentHost<V>(options: ContentHostOptions<V>): ContentHos
1231
1333
  if (state === null) {
1232
1334
  return appPage(400, "This link isn't valid", "Open the address again.", "error", method);
1233
1335
  }
1336
+ // Redirect entry is for a tab alone (P125): asked in a frame, it never shows the app's
1337
+ // sign-in or refusal there, and says nothing to the page that frames it.
1234
1338
  const dest = request.headers.get("sec-fetch-dest");
1235
- const framed = dest === null ? state.framed : dest !== "document";
1339
+ if (dest === "iframe" || dest === "frame") {
1340
+ return tabOnlyPage(options.appOrigins.join(" "), method);
1341
+ }
1236
1342
  const clean = `${domain.originOf(state.label)}${state.path}`;
1237
1343
  if (state.expired) {
1238
- return appPage(
1239
- 401,
1240
- "This took too long",
1241
- "Open the address again.",
1242
- "session",
1243
- method,
1244
- framed ? undefined : { href: clean, text: "Open it again" },
1245
- );
1344
+ return appPage(401, "This took too long", "Open the address again.", "session", method, {
1345
+ href: clean,
1346
+ text: "Open it again",
1347
+ });
1246
1348
  }
1247
- const scope = options.name?.scopeOf?.(state.label) ?? null;
1248
1349
  let viewer: V | null;
1249
1350
  try {
1250
1351
  viewer = (await viewerOf(request)) ?? (await handedOver(request));
@@ -1258,15 +1359,7 @@ export function createContentHost<V>(options: ContentHostOptions<V>): ContentHos
1258
1359
  );
1259
1360
  }
1260
1361
  try {
1261
- const answer =
1262
- scope === null
1263
- ? null
1264
- : ((await entry.at(
1265
- scope,
1266
- new URL(state.path, "https://x.invalid").pathname,
1267
- viewer,
1268
- request,
1269
- )) ?? null);
1362
+ const { scope, answer } = await entryAt(state.label, state.path, viewer, request);
1270
1363
  // A file set's address (P081) names its instance and where its version lives.
1271
1364
  const address = answer !== null && isFileAddress(answer) ? answer : null;
1272
1365
  const instance = address === null ? (answer as InstanceRef | null) : address.instance;
@@ -1278,23 +1371,15 @@ export function createContentHost<V>(options: ContentHostOptions<V>): ContentHos
1278
1371
  path: state.path,
1279
1372
  url: clean,
1280
1373
  instance,
1281
- framed,
1374
+ // A frame never gets here since P125: kept for the hooks' type.
1375
+ framed: false,
1282
1376
  };
1283
1377
  if (instance === null || grant === null) {
1284
1378
  if (viewer === null) {
1285
- // The app's sign-in never shows in a frame: the person opens a tab for it.
1286
- return framed
1287
- ? appPage(
1288
- 401,
1289
- "Open this in a new tab to sign in",
1290
- "Signing in doesn't work inside a frame.",
1291
- "sign-in",
1292
- method,
1293
- )
1294
- : await signInWith(entry, request, context);
1379
+ return await signInWith(entry, request, context);
1295
1380
  }
1296
1381
  const status = instance === null ? 404 : 403;
1297
- const own = framed ? null : await entry.refusal?.(status, request, context);
1382
+ const own = await entry.refusal?.(status, request, context);
1298
1383
  if (own !== null && own !== undefined) {
1299
1384
  return own;
1300
1385
  }
@@ -69,7 +69,13 @@ export {
69
69
  type D1Like,
70
70
  type D1StatementLike,
71
71
  } from "./tickets.ts";
72
- export { FRAME_STATUS_METHOD } from "../isolation/types.ts";
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 that isn't nested and the
74
+ // sandbox proxy; a content Worker of a host's own answers the same at `DOOR_PATH<key>`, after
75
+ // taking the door's own ticket (`TicketRecord.door`) and running the checks its content's address
76
+ // runs (docs/ADOPTING.md, "The door"). A host that signs its own tickets answers it with
77
+ // `PortholeServer.doorAnswer` once it has admitted the request itself (P126).
78
+ export { doorResponse, doorStatusResponse, type DoorOptions } from "./pages.ts";
73
79
  // A nested page (P111): Porthole's shell at the framed address, the page and its files below the
74
80
  // sealed prefix, all on the shell's own label (P114, `nestedLabelOf`). `/server` serves them for a
75
81
  // config with `nested`; a content Worker of its own answers the same (docs/ADOPTING.md, "Nested