@botiverse/porthole 0.14.5 → 0.14.6

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 +53 -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 +140 -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 +6 -1
  40. package/dist/server/pages.d.ts +32 -0
  41. package/dist/server/pages.js +82 -6
  42. package/dist/server/server.js +140 -11
  43. package/dist/server/types.d.ts +15 -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 +57 -4
  47. package/docs/DECISIONS.md +198 -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 +175 -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 +6 -1
  73. package/src/server/pages.ts +101 -6
  74. package/src/server/server.ts +186 -19
  75. package/src/server/types.ts +16 -1
  76. package/src/transport/post-message.ts +1 -9
@@ -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,12 @@ 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").
77
+ export { doorResponse, doorStatusResponse, type DoorOptions } from "./pages.ts";
73
78
  // A nested page (P111): Porthole's shell at the framed address, the page and its files below the
74
79
  // sealed prefix, all on the shell's own label (P114, `nestedLabelOf`). `/server` serves them for a
75
80
  // config with `nested`; a content Worker of its own answers the same (docs/ADOPTING.md, "Nested
@@ -1,3 +1,4 @@
1
+ import { DOOR_SANDBOX_TOKENS } from "../compile/policy.ts";
1
2
  import { FRAME_STATUS_METHOD } from "../isolation/types.ts";
2
3
  import type { FrameBlock } from "../host/types.ts";
3
4
  import { base64url, sha256, utf8 } from "./crypto.ts";
@@ -142,15 +143,16 @@ export function enterPage(
142
143
  return new Response(body, { status: 200, headers });
143
144
  }
144
145
 
145
- /** The status script's hash, for a page that carries it inline (`script-src 'sha256-…'`). */
146
- let statusHash: string | null = null;
147
- const hashOfStatus = (): string => {
148
- statusHash ??= base64url(sha256(utf8(STATUS_SCRIPT)))
146
+ /** A script's hash, for a page that carries it inline (`script-src 'sha256-…'`). */
147
+ const hashOf = (script: string): string => {
148
+ const hash = base64url(sha256(utf8(script)))
149
149
  .replace(/-/gu, "+")
150
150
  .replace(/_/gu, "/");
151
- const padding = (4 - (statusHash.length % 4)) % 4;
152
- return `'sha256-${statusHash}${"=".repeat(padding)}'`;
151
+ const padding = (4 - (hash.length % 4)) % 4;
152
+ return `'sha256-${hash}${"=".repeat(padding)}'`;
153
153
  };
154
+ let statusHash: string | null = null;
155
+ const hashOfStatus = (): string => (statusHash ??= hashOf(STATUS_SCRIPT));
154
156
 
155
157
  /**
156
158
  * A redirect entry's page on the app's own origin (P068): why it shows nothing, told to the page
@@ -212,3 +214,96 @@ export function statusPageOf(options: {
212
214
  options.method,
213
215
  );
214
216
  }
217
+
218
+ /** A door's word that its display may be framed (P125), from the page's data attributes. */
219
+ const DOOR_SCRIPT = `(() => {
220
+ const main = document.querySelector("[data-porthole-door]");
221
+ if (main === null) return;
222
+ const hosts = JSON.parse(main.dataset.portholeHosts || "[]");
223
+ ${say()}
224
+ say({ state: "open" });
225
+ })();`;
226
+ let doorHash: string | null = null;
227
+ const hashOfDoor = (): string => (doorHash ??= hashOf(DOOR_SCRIPT));
228
+
229
+ /**
230
+ * A door's headers (P125): its one script by its hash (an opaque document has no `'self'` to load
231
+ * one from), nothing else loads, sandboxed with scripts alone in its header too (opaque on a tab, and
232
+ * in a frame whose attribute a host's own platform forgot), framed by the host origins, never
233
+ * cached, never sent on, no cookie.
234
+ */
235
+ const doorHeaders = (script: string, frameAncestors: string): Headers =>
236
+ new Headers({
237
+ "content-type": "text/html; charset=utf-8",
238
+ "cache-control": "no-store",
239
+ "content-security-policy": `default-src 'none'; script-src ${script}; base-uri 'none'; form-action 'none'; sandbox ${DOOR_SANDBOX_TOKENS.join(" ")}; frame-ancestors ${frameAncestors}`,
240
+ "referrer-policy": "no-referrer",
241
+ "x-content-type-options": "nosniff",
242
+ "x-robots-tag": "noindex, nofollow",
243
+ });
244
+
245
+ /** What a door is given: the host origins it tells, and who may frame it (default, those). */
246
+ export interface DoorOptions {
247
+ readonly hostOrigins: readonly string[];
248
+ readonly frameAncestors?: string;
249
+ readonly method?: string;
250
+ }
251
+
252
+ /**
253
+ * A door that opens (P125): its display may be framed. It says `open` to the page that frames it,
254
+ * at each web host origin and (a desktop scheme among them) to its parent (P070), once, as it
255
+ * parses. For a content Worker of a host's own: answer it at `DOOR_PATH<key>` only once the door's
256
+ * own ticket was taken and the checks the content's address runs passed for the same grant.
257
+ */
258
+ export function doorResponse(options: DoorOptions): Response {
259
+ const hosts = escape(JSON.stringify(options.hostOrigins));
260
+ const body = `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>Opening</title></head><body><main data-porthole-door="" data-porthole-hosts="${hosts}"></main><script>${DOOR_SCRIPT}</script></body></html>`;
261
+ return new Response(options.method?.toUpperCase() === "HEAD" ? null : body, {
262
+ status: 200,
263
+ headers: doorHeaders(hashOfDoor(), options.frameAncestors ?? options.hostOrigins.join(" ")),
264
+ });
265
+ }
266
+
267
+ /**
268
+ * A door that doesn't open (P125): why, said `blocked` to the page that frames it, as a content
269
+ * origin's status page says it (`session` 401: no ticket, or one used, ended, or not a door's of
270
+ * this instance on this origin; `denied` 403 with the host's code; `not-found` 404: no document, or
271
+ * a file set whose entry isn't a page; `error` 500).
272
+ */
273
+ export function doorStatusResponse(
274
+ options: DoorOptions & {
275
+ readonly status: number;
276
+ readonly reason: FrameBlock;
277
+ readonly code?: string;
278
+ },
279
+ ): Response {
280
+ const { status, reason, code } = options;
281
+ const hosts = escape(JSON.stringify(options.hostOrigins));
282
+ const body = `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>Not shown</title></head><body><main data-porthole-status="${status}" data-porthole-reason="${escape(reason)}"${code === undefined ? "" : ` data-porthole-code="${escape(code)}"`} data-porthole-hosts="${hosts}"></main><script>${STATUS_SCRIPT}</script></body></html>`;
283
+ return new Response(options.method?.toUpperCase() === "HEAD" ? null : body, {
284
+ status,
285
+ headers: doorHeaders(hashOfStatus(), options.frameAncestors ?? options.hostOrigins.join(" ")),
286
+ });
287
+ }
288
+
289
+ /**
290
+ * What a clean address answers in a frame (P125): a clean address is for a tab of its own, so in a
291
+ * frame it never goes to the app (no authorize, no sign-in, no refusal page of the app's) and says
292
+ * nothing to the page that frames it: no script at all, under the status pages' policy without
293
+ * `script-src` (so `default-src 'none'` forbids every script), framed by the host origins only. A
294
+ * host frames what a clean address names by resolving it through `issue` (`client.resolve`).
295
+ */
296
+ export function tabOnlyPage(frameAncestors: string, method = "GET"): Response {
297
+ const body = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Open this in a new tab</title><style>${STYLE}</style></head><body><main data-porthole-tab-only=""><h1>Open this in a new tab</h1><p>This address opens in a tab of its own, not inside a frame.</p></main></body></html>`;
298
+ return new Response(method.toUpperCase() === "HEAD" ? null : body, {
299
+ status: 403,
300
+ headers: {
301
+ "content-type": "text/html; charset=utf-8",
302
+ "cache-control": "no-store",
303
+ "content-security-policy": `default-src 'none'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'; frame-ancestors ${frameAncestors}`,
304
+ "referrer-policy": "no-referrer",
305
+ "x-content-type-options": "nosniff",
306
+ "x-robots-tag": "noindex, nofollow",
307
+ },
308
+ });
309
+ }