@botiverse/porthole 0.14.18 → 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,5 +1,5 @@
1
1
  import { compile } from "../compile/compile.js";
2
- import { framedByProblem, hostOriginProblem, maybeSameSite, originMatchesSource, parseOrigin, } from "../isolation/served.js";
2
+ import { framedByProblem, includesOrigin, hostOriginProblem, maybeSameSite, originMatchesSource, parseOrigin, } from "../isolation/served.js";
3
3
  import { DOOR_PATH, } from "../isolation/types.js";
4
4
  import { sandboxProxyDocument } from "../mcp/proxy.js";
5
5
  import { base32, createKeys, newTicket, ticketId } from "./keys.js";
@@ -79,6 +79,8 @@ const DEFAULT_SESSION_SECONDS = 3_600;
79
79
  const MAX_SESSION_SECONDS = 30 * 24 * 3_600;
80
80
  /** Browsers keep a cookie of up to 4 KB, name and attributes included. */
81
81
  const MAX_COOKIE_BYTES = 3_800;
82
+ /** Who may frame an embed session's answers (P143): any page. That session's alone. */
83
+ const EMBED_ANCESTORS = "*";
82
84
  /** A host (and port) as it compares: lowercase, no trailing dot, no default port. */
83
85
  function normalHost(value, protocol) {
84
86
  const host = value
@@ -325,7 +327,7 @@ export function createServer(options) {
325
327
  if (problem !== null) {
326
328
  throw new TypeError(`framedBy: ${problem}`);
327
329
  }
328
- if (options.hostOrigins.includes(origin)) {
330
+ if (includesOrigin(options.hostOrigins, origin)) {
329
331
  throw new TypeError(`framedBy: ${origin} is a host origin already: framedBy names an ancestor that never talks to a frame`);
330
332
  }
331
333
  const parsed = parseOrigin(origin);
@@ -335,13 +337,21 @@ export function createServer(options) {
335
337
  maybeSameSite(parsed.host, sampleHost)) {
336
338
  throw new TypeError(`framedBy: ${origin} may be the same site as the content domain ${domain}: serve content from a registrable domain the host uses for nothing else`);
337
339
  }
338
- if (!framedBy.includes(origin)) {
340
+ if (!includesOrigin(framedBy, origin)) {
339
341
  framedBy.push(origin);
340
342
  }
341
343
  }
342
344
  // Who may be an ancestor of a frame served here: the host origins, then the outer pages' (P141).
343
345
  // Every frame's `frame-ancestors` is this; whom a frame hears and tells is `hostOrigins` alone.
344
346
  const frameAncestors = [...options.hostOrigins, ...framedBy].join(" ");
347
+ // Embed grants (P143): taken only where the host opted in. Off, a session or sealed address
348
+ // that says it is one opens nothing.
349
+ if (options.embeds !== undefined && typeof options.embeds !== "boolean") {
350
+ throw new TypeError("embeds is true or false");
351
+ }
352
+ const embeds = options.embeds === true;
353
+ /** Who may frame an access's answers: any page for an embed session (P143), else the list. */
354
+ const ancestorsFor = (access) => access.embed === true ? EMBED_ANCESTORS : frameAncestors;
345
355
  let authorizeUrl = null;
346
356
  if (options.entry !== undefined) {
347
357
  try {
@@ -359,8 +369,13 @@ export function createServer(options) {
359
369
  compiled.set(name, compile(config));
360
370
  }
361
371
  const tickets = options.tickets ?? memoryTicketStore();
362
- /** A page saying why there is nothing to show, told to the host too (its reason, P040). */
363
- const page = (status, title, detail, method, reason = status === 404 ? "not-found" : status === 502 ? "upstream" : "error", code) => statusPage(status, title, detail, frameAncestors, method, reason, options.hostOrigins, code);
372
+ /**
373
+ * A page saying why there is nothing to show, told to the host too (its reason, P040). An embed
374
+ * session's (P143, `embed`): framed by any page, and told to no one (it names no host).
375
+ */
376
+ const page = (status, title, detail, method, reason = status === 404 ? "not-found" : status === 502 ? "upstream" : "error", code, embed = false) => embed
377
+ ? statusPage(status, title, detail, EMBED_ANCESTORS, method, reason, [], code)
378
+ : statusPage(status, title, detail, frameAncestors, method, reason, options.hostOrigins, code);
364
379
  /**
365
380
  * The host's check on a request its cookie (or ticket) let in (P050): null to go on, or the
366
381
  * page saying it's denied. Answers are reused only for the host's own `ttlSeconds`.
@@ -369,7 +384,7 @@ export function createServer(options) {
369
384
  const refused = await refusalOf(request, access);
370
385
  return refused === null
371
386
  ? null
372
- : page(403, "You can't open this anymore", "The app that showed it no longer lets you see it here.", request.method.toUpperCase(), "denied", refused.code);
387
+ : page(403, "You can't open this anymore", "The app that showed it no longer lets you see it here.", request.method.toUpperCase(), "denied", refused.code, access.embed === true);
373
388
  }
374
389
  /** The host's check (P050): null to go on, or its refusal and the host's code, if a good one. */
375
390
  async function refusalOf(request, access) {
@@ -381,6 +396,8 @@ export function createServer(options) {
381
396
  access.viewer,
382
397
  access.subject ?? null,
383
398
  access.expiresAt,
399
+ // An embed session's answer is its own (P143): never reused for another session.
400
+ ...(access.embed === true ? ["embed"] : []),
384
401
  ]);
385
402
  const at = Date.now();
386
403
  let answer = authorizeTtl > 0 ? answers.get(key) : undefined;
@@ -393,6 +410,7 @@ export function createServer(options) {
393
410
  viewer: access.viewer,
394
411
  anonymous: access.anonymous === true,
395
412
  ...(access.subject === undefined ? {} : { subject: access.subject }),
413
+ ...(access.embed === true ? { embed: true } : {}),
396
414
  request,
397
415
  });
398
416
  }
@@ -475,13 +493,15 @@ export function createServer(options) {
475
493
  }
476
494
  }
477
495
  }
478
- async function documentOf(instance) {
496
+ async function documentOf(instance,
497
+ /** An embed session's (P143): its shell's plan names no host. */
498
+ embed = false) {
479
499
  const { document } = instance;
480
500
  const config = compiledFor(instance);
481
501
  if (config === null) {
482
502
  return null;
483
503
  }
484
- const origins = options.hostOrigins;
504
+ const origins = embed ? [] : options.hostOrigins;
485
505
  switch (document.kind) {
486
506
  case "shell":
487
507
  return {
@@ -529,6 +549,14 @@ export function createServer(options) {
529
549
  * Porthole strips from an app's requests and answers is wider (`isPortholeCookie`).
530
550
  */
531
551
  const ourCookie = (name) => name.startsWith(secure ? "__Host-porthole-" : "porthole-");
552
+ /**
553
+ * A session's cookie name, by its instance's key: an embed session's (P143) is a name of its own
554
+ * (`e-<key>`), so it never takes the place of another session of the same instance, which the
555
+ * same browser may hold where it partitions no cookies, and is never read as one.
556
+ */
557
+ const sessionName = (key, embed) => cookieName(embed ? `e-${key}` : key);
558
+ /** Whether a verified session says it is an embed session (P143), checked: `m` is 1 or absent. */
559
+ const embedOf = (session) => session.m === undefined ? false : session.m === 1 ? true : null;
532
560
  /**
533
561
  * The cookie a taken ticket buys: this origin only (`__Host-` over https), never readable by the
534
562
  * content (`HttpOnly`). In a frame it is a third party's: `SameSite=None`, partitioned by the
@@ -537,6 +565,7 @@ export function createServer(options) {
537
565
  */
538
566
  function sessionCookie(request, record, at = {}) {
539
567
  const sessionSeconds = record.sessionSeconds ?? DEFAULT_SESSION_SECONDS;
568
+ const embed = record.embed === true;
540
569
  const session = {
541
570
  i: record.instance,
542
571
  w: record.viewer,
@@ -546,9 +575,10 @@ export function createServer(options) {
546
575
  ...(at.p === undefined ? {} : { p: at.p }),
547
576
  ...(at.b === undefined ? {} : { b: at.b }),
548
577
  ...(at.k === undefined ? {} : { k: at.k }),
578
+ ...(embed ? { m: 1 } : {}),
549
579
  };
550
580
  return [
551
- `${cookieName(keys.instanceKey(record.instance))}=${keys.sign(session)}`,
581
+ `${sessionName(keys.instanceKey(record.instance), embed)}=${keys.sign(session)}`,
552
582
  "Path=/",
553
583
  "HttpOnly",
554
584
  `Max-Age=${sessionSeconds}`,
@@ -596,7 +626,10 @@ export function createServer(options) {
596
626
  function accessOf(request, label, key) {
597
627
  let best = null;
598
628
  for (const [name, value] of cookiesOf(request)) {
599
- if (!(key === null ? ourCookie(name) : name === cookieName(key))) {
629
+ // An embed session (P143) only by its own name, for an instance's document, where embeds
630
+ // are on; every other session by the instance's name (or, for an app, any of ours).
631
+ const embedName = key !== null && embeds && name === sessionName(key, true);
632
+ if (!(embedName || (key === null ? ourCookie(name) : name === sessionName(key, false)))) {
600
633
  continue;
601
634
  }
602
635
  const session = keys.verify(value);
@@ -604,7 +637,8 @@ export function createServer(options) {
604
637
  typeof session.w !== "string" ||
605
638
  typeof session.x !== "number" ||
606
639
  session.x <= Date.now() ||
607
- (session.s !== undefined && typeof session.s !== "string")) {
640
+ (session.s !== undefined && typeof session.s !== "string") ||
641
+ embedOf(session) !== embedName) {
608
642
  continue;
609
643
  }
610
644
  let instance;
@@ -625,7 +659,11 @@ export function createServer(options) {
625
659
  (key === null ? instance.document.kind !== "external" : keys.instanceKey(instance) !== key)) {
626
660
  continue;
627
661
  }
628
- if (best === null || session.x > best.expiresAt) {
662
+ // Any other session before an embed session (P143), then the latest to end: where a browser
663
+ // holds both (it partitions no cookies), the other session is never changed by it.
664
+ if (best === null ||
665
+ (best.embed === true && !embedName) ||
666
+ ((best.embed === true) === embedName && session.x > best.expiresAt)) {
629
667
  best = {
630
668
  instance,
631
669
  viewer: session.w,
@@ -633,6 +671,7 @@ export function createServer(options) {
633
671
  expiresAt: session.x,
634
672
  ...(session.a === 1 ? { anonymous: true } : {}),
635
673
  ...(typeof session.s === "string" ? { subject: session.s } : {}),
674
+ ...(embedName ? { embed: true } : {}),
636
675
  };
637
676
  }
638
677
  }
@@ -657,7 +696,9 @@ export function createServer(options) {
657
696
  const base = typeof session.b === "string" && BASE.test(session.b) ? session.b : null;
658
697
  const under = base !== null && pathname.startsWith(base);
659
698
  const atBase = base !== null && `${pathname}/` === base;
660
- if ((session.p !== pathname && !under && !atBase) ||
699
+ // A clean address is never an embed session's (P143): only an entry code opens one.
700
+ if (embedOf(session) !== false ||
701
+ (session.p !== pathname && !under && !atBase) ||
661
702
  typeof session.w !== "string" ||
662
703
  typeof session.x !== "number" ||
663
704
  session.x <= Date.now() ||
@@ -759,6 +800,11 @@ export function createServer(options) {
759
800
  return null;
760
801
  }
761
802
  const open = session.x > now || (session.e > now && ownLoad(request));
803
+ // An embed session's address (P143) opens only where embeds are on.
804
+ const embed = embedOf(session);
805
+ if (embed === null || (embed && !embeds)) {
806
+ return null;
807
+ }
762
808
  let instance;
763
809
  try {
764
810
  instance = cleanInstance(session.i);
@@ -783,8 +829,29 @@ export function createServer(options) {
783
829
  expiresAt: session.e,
784
830
  ...(session.a === 1 ? { anonymous: true } : {}),
785
831
  ...(typeof session.s === "string" ? { subject: session.s } : {}),
832
+ ...(embed ? { embed: true } : {}),
786
833
  };
787
834
  }
835
+ /**
836
+ * Whether a sealed address that no longer opens was an embed session's of this origin (P143):
837
+ * sealed by this server (so its `m` is this server's word), where embeds are on. Its ended
838
+ * access is then said where its frame is, below any page.
839
+ */
840
+ async function sealedEmbed(label, token) {
841
+ if (!embeds) {
842
+ return false;
843
+ }
844
+ const session = await keys.unseal(token);
845
+ if (!isRecord(session) || embedOf(session) !== true) {
846
+ return false;
847
+ }
848
+ try {
849
+ return labelFor(cleanInstance(session.i)) === label;
850
+ }
851
+ catch {
852
+ return false;
853
+ }
854
+ }
788
855
  /**
789
856
  * A file set's file in a frame (P083): the sealed access in its path opens it, once it holds
790
857
  * for this origin and the host's check lets it in; every path under it is the same version's.
@@ -799,6 +866,7 @@ export function createServer(options) {
799
866
  e: access.expiresAt,
800
867
  ...(access.anonymous === true ? { a: 1 } : {}),
801
868
  ...(access.subject === undefined ? {} : { s: access.subject }),
869
+ ...(access.embed === true ? { m: 1 } : {}),
802
870
  });
803
871
  return { base: `${FILES_PREFIX}${token}/`, expires };
804
872
  }
@@ -821,6 +889,10 @@ export function createServer(options) {
821
889
  }
822
890
  const access = await sealedAccess(request, label, token);
823
891
  if (access === null) {
892
+ // An embed session's ended access (P143): where its frame is, below any page, told no one.
893
+ if (await sealedEmbed(label, token)) {
894
+ return page(401, "This has ended", "Content here opens for a while. Open it again from the page that showed it.", method, "session", undefined, true);
895
+ }
824
896
  // In a nested page's frame (P111) its shell frames it and hears it, on this origin; a
825
897
  // config without nesting never frames this address but at the host.
826
898
  return statusPage(401, "This has ended", "Content here opens for a while. Open it again from the app that showed it.", nestedAncestors(origin, frameAncestors), method, "session", [...options.hostOrigins, origin]);
@@ -830,16 +902,16 @@ export function createServer(options) {
830
902
  const blob = SEALED_ASSET.exec(rest)?.[1];
831
903
  if (blob !== undefined) {
832
904
  // A nested page loads no assets (its config refuses them): none on its shell's label (P114).
905
+ const none = () => page(404, "Not found", "This address names no content.", method, undefined, undefined, access.embed === true);
833
906
  if (options.assets === undefined || isNestedLabel(label)) {
834
- return page(404, "Not found", "This address names no content.", method);
907
+ return none();
835
908
  }
836
- return ((await assetFor(request, label, access, blob)) ??
837
- page(404, "Not found", "This address names no content.", method));
909
+ return (await assetFor(request, label, access, blob)) ?? none();
838
910
  }
839
911
  if (rest === RENEW_PATH) {
840
912
  // Only the page itself renews its address, while its session lasts and the host lets it.
841
913
  if (method !== "GET" || !ownLoad(request)) {
842
- return page(403, "Not allowed", "Only the page renews its own address.", method);
914
+ return page(403, "Not allowed", "Only the page renews its own address.", method, undefined, undefined, access.embed === true);
843
915
  }
844
916
  const refusal = await denied(request, access);
845
917
  if (refusal !== null) {
@@ -851,7 +923,7 @@ export function createServer(options) {
851
923
  "cache-control": "no-store",
852
924
  "x-content-type-options": "nosniff",
853
925
  "cross-origin-resource-policy": "same-origin",
854
- "content-security-policy": `${INERT_FILE_CSP}; frame-ancestors ${frameAncestors}`,
926
+ "content-security-policy": `${INERT_FILE_CSP}; frame-ancestors ${ancestorsFor(access)}`,
855
927
  "referrer-policy": "no-referrer",
856
928
  },
857
929
  });
@@ -878,9 +950,11 @@ export function createServer(options) {
878
950
  const record = method === "GET" ? await take(url.searchParams.get("ticket"), label) : null;
879
951
  // An entry code opens its clean address alone, through its own browser's nonce (P068, P114).
880
952
  // A door's ticket is the door's alone (P125): here it is no ticket.
953
+ // An embed grant's ticket (P143) opens only where embeds are on.
881
954
  if (record !== null &&
882
955
  record.entry === undefined &&
883
956
  record.door !== true &&
957
+ (record.embed !== true || embeds) &&
884
958
  record.instance.document.kind !== "external" &&
885
959
  keys.instanceKey(record.instance) === key) {
886
960
  cookie = sessionCookie(request, record);
@@ -891,6 +965,7 @@ export function createServer(options) {
891
965
  expiresAt: Date.now() + (record.sessionSeconds ?? DEFAULT_SESSION_SECONDS) * 1_000,
892
966
  ...(record.anonymous === true ? { anonymous: true } : {}),
893
967
  ...(record.subject === undefined ? {} : { subject: record.subject }),
968
+ ...(record.embed === true ? { embed: true } : {}),
894
969
  };
895
970
  }
896
971
  access ??= accessOf(request, label, key);
@@ -927,6 +1002,7 @@ export function createServer(options) {
927
1002
  record = method === "GET" ? await take(url.searchParams.get("ticket"), label) : null;
928
1003
  if (record === null ||
929
1004
  record.door !== true ||
1005
+ record.embed === true ||
930
1006
  record.entry !== undefined ||
931
1007
  record.instance.document.kind === "external" ||
932
1008
  keys.instanceKey(record.instance) !== key ||
@@ -992,21 +1068,24 @@ export function createServer(options) {
992
1068
  if (refusal !== null) {
993
1069
  return refusal;
994
1070
  }
995
- const served = await documentOf(access.instance);
1071
+ // An embed session (P143): every answer below framed by any page, its documents hostless.
1072
+ const embed = access.embed === true;
1073
+ const missing = () => page(404, "Not found", "This page, or this version of it, doesn't exist.", method, undefined, undefined, embed);
1074
+ const served = await documentOf(access.instance, embed);
996
1075
  if (served === null) {
997
- return page(404, "Not found", "This page, or this version of it, doesn't exist.", method);
1076
+ return missing();
998
1077
  }
999
1078
  // A frame's document opens at its file set's entry, which is a page (P125, P124-2): a set
1000
1079
  // stored before that was checked shows Porthole's word, never an inert file that says nothing.
1001
1080
  if ("files" in served && at === undefined && !entryIsPage(served.files)) {
1002
- return page(404, "Not found", "This page, or this version of it, doesn't exist.", method);
1081
+ return missing();
1003
1082
  }
1004
1083
  // A page below a base (P125) names a file set's page: for one page alone, nothing; for a set,
1005
1084
  // the page the frame opens at (its entry, or the page it was issued for) must be one of its
1006
1085
  // pages. The door asks the same (`serveDoor`), so both say `not-found` alike.
1007
1086
  if (at === undefined &&
1008
1087
  ("files" in served ? ticketPage(served.files, pageAt) === null : pageAt !== undefined)) {
1009
- return page(404, "Not found", "This page, or this version of it, doesn't exist.", method);
1088
+ return missing();
1010
1089
  }
1011
1090
  // A nested page (P111): the address the host frames (a ticket's, a cookie's, an entered
1012
1091
  // one's) answers Porthole's shell, which frames the page at its sealed files' address; only
@@ -1052,13 +1131,19 @@ export function createServer(options) {
1052
1131
  }
1053
1132
  return shell;
1054
1133
  }
1055
- // Below the sealed prefix, a nested page and its files are framed by its shell too.
1056
- const ancestors = nested ? nestedAncestors(access.origin, frameAncestors) : frameAncestors;
1134
+ // Below the sealed prefix, a nested page and its files are framed by its shell too. An embed
1135
+ // session is never nested (`issue`): its answers are framed by any page (P143).
1136
+ const ancestors = nested
1137
+ ? nestedAncestors(access.origin, frameAncestors)
1138
+ : ancestorsFor(access);
1139
+ // Whom its pages hear and tell: the host origins, or no one for an embed session (P143).
1140
+ const hostOrigins = embed ? [] : options.hostOrigins;
1057
1141
  if ("files" in served) {
1058
1142
  if (at !== undefined) {
1059
1143
  // A page's own frames (P128): its files below the base are framed by its own pages too,
1060
- // on this origin (`frame-ancestors` names every ancestor). Never another origin's.
1061
- const own = served.compiled.config.nestedFrames === "own";
1144
+ // on this origin (`frame-ancestors` names every ancestor). Never another origin's. Any
1145
+ // page already frames an embed session's (P143).
1146
+ const own = served.compiled.config.nestedFrames === "own" && !embed;
1062
1147
  return serveFile({
1063
1148
  request,
1064
1149
  set: served.files,
@@ -1069,7 +1154,7 @@ export function createServer(options) {
1069
1154
  pinned: at.pinned,
1070
1155
  source: at.source,
1071
1156
  compiled: served.compiled,
1072
- hostOrigins: options.hostOrigins,
1157
+ hostOrigins,
1073
1158
  frameAncestors: own ? `${access.origin} ${ancestors}` : ancestors,
1074
1159
  ...versionOf(access.instance),
1075
1160
  });
@@ -1088,15 +1173,15 @@ export function createServer(options) {
1088
1173
  pinned: true,
1089
1174
  source: `${access.origin}${FILES_PREFIX}`,
1090
1175
  compiled: served.compiled,
1091
- hostOrigins: options.hostOrigins,
1092
- frameAncestors,
1176
+ hostOrigins,
1177
+ frameAncestors: ancestors,
1093
1178
  ticket: { expires: sealed.expires, ...(pageAt === undefined ? {} : { page: pageAt }) },
1094
1179
  ...versionOf(access.instance),
1095
1180
  });
1096
1181
  }
1097
1182
  // One page at a file set's base (P081): its base is the page, nothing under it is.
1098
1183
  if (at !== undefined && at.rest !== "") {
1099
- return page(404, "Not found", "This page, or this version of it, doesn't exist.", method);
1184
+ return missing();
1100
1185
  }
1101
1186
  // A page that may use its artifact's assets loads them from its own origin (P089); every
1102
1187
  // served page carries its frame's sandbox, a tab of its own included (P099).
@@ -1212,7 +1297,12 @@ export function createServer(options) {
1212
1297
  if (refusal !== null) {
1213
1298
  return refusal;
1214
1299
  }
1215
- return serveAsset({ request, asset, frameAncestors, code: runsAsCode(asset, access) });
1300
+ return serveAsset({
1301
+ request,
1302
+ asset,
1303
+ frameAncestors: ancestorsFor(access),
1304
+ code: runsAsCode(asset, access),
1305
+ });
1216
1306
  }
1217
1307
  /**
1218
1308
  * Whether a code-typed asset goes out as code (P089, P103): only where it was trusted when it
@@ -1267,17 +1357,23 @@ export function createServer(options) {
1267
1357
  continue;
1268
1358
  }
1269
1359
  const session = keys.verify(value);
1360
+ // An embed session (P143) only where embeds are on, and only by its own name.
1361
+ const embed = isRecord(session) ? embedOf(session) : null;
1270
1362
  if (!isRecord(session) ||
1271
1363
  typeof session.w !== "string" ||
1272
1364
  typeof session.x !== "number" ||
1273
1365
  session.x <= Date.now() ||
1274
- (session.s !== undefined && typeof session.s !== "string")) {
1366
+ (session.s !== undefined && typeof session.s !== "string") ||
1367
+ embed === null ||
1368
+ (embed && !embeds)) {
1275
1369
  continue;
1276
1370
  }
1277
1371
  let instance;
1278
1372
  try {
1279
1373
  instance = cleanInstance(session.i);
1280
- if (instance.document.kind !== "artifact" || labelFor(instance) !== label) {
1374
+ if (instance.document.kind !== "artifact" ||
1375
+ labelFor(instance) !== label ||
1376
+ (embed && name !== sessionName(keys.instanceKey(instance), true))) {
1281
1377
  continue;
1282
1378
  }
1283
1379
  }
@@ -1291,9 +1387,11 @@ export function createServer(options) {
1291
1387
  expiresAt: session.x,
1292
1388
  ...(session.a === 1 ? { anonymous: true } : {}),
1293
1389
  ...(typeof session.s === "string" ? { subject: session.s } : {}),
1390
+ ...(embed ? { embed: true } : {}),
1294
1391
  });
1295
1392
  }
1296
- return found.sort((a, b) => b.expiresAt - a.expiresAt);
1393
+ // Any other session before an embed session (P143), then the latest first.
1394
+ return found.sort((a, b) => Number(a.embed === true) - Number(b.embed === true) || b.expiresAt - a.expiresAt);
1297
1395
  }
1298
1396
  /**
1299
1397
  * A clean address without a cookie for it (P068): off to the host's authorize route with a
@@ -1546,6 +1644,26 @@ export function createServer(options) {
1546
1644
  /** A grant, checked for an instance (`issue`'s rules, and `doorAnswer`'s, P126). */
1547
1645
  function checkGrant(clean, grant) {
1548
1646
  const anonymous = grant.anonymous === true;
1647
+ // An embedded document (P143): a public page with no host, which any page may frame. Only
1648
+ // where the host opted in, and only as narrow as that: anonymous, no level, no user, an
1649
+ // artifact's page that isn't nested.
1650
+ // Read as given: a host's grant is checked here, not trusted to its type.
1651
+ const asked = grant.embed;
1652
+ const embed = asked !== undefined;
1653
+ if (embed) {
1654
+ if (asked !== true) {
1655
+ throw new TypeError("A grant's embed is true or absent");
1656
+ }
1657
+ if (!embeds) {
1658
+ throw new TypeError("An embed grant needs the server's opt-in (embeds: true): every page could frame it (P143)");
1659
+ }
1660
+ if (!anonymous || grant.level !== undefined || grant.user !== undefined) {
1661
+ throw new TypeError("An embed grant is anonymous, with no viewer, level or user: it has no host to give them to (P143)");
1662
+ }
1663
+ if (clean.document.kind !== "artifact" || compiledFor(clean)?.config.nested === true) {
1664
+ throw new TypeError("An embed grant opens an artifact's page that isn't nested: never a url-mode app, a served shell, the sandbox proxy or a nested display (P143)");
1665
+ }
1666
+ }
1549
1667
  if (anonymous) {
1550
1668
  if (grant.viewer !== undefined) {
1551
1669
  throw new TypeError("An anonymous grant names no viewer");
@@ -1563,7 +1681,7 @@ export function createServer(options) {
1563
1681
  (typeof grant.subject !== "string" || grant.subject.length > SUBJECT_MAX)) {
1564
1682
  throw new TypeError(`A grant's subject is a string of at most ${SUBJECT_MAX} characters`);
1565
1683
  }
1566
- return { anonymous, viewer: anonymous ? "" : (grant.viewer ?? "") };
1684
+ return { anonymous, viewer: anonymous ? "" : (grant.viewer ?? ""), embed };
1567
1685
  }
1568
1686
  /** How long a grant's session lasts, checked (`sessionSeconds`). */
1569
1687
  const sessionOf = (grant) => seconds(grant.sessionSeconds, DEFAULT_SESSION_SECONDS, MAX_SESSION_SECONDS, "sessionSeconds");
@@ -1573,7 +1691,10 @@ export function createServer(options) {
1573
1691
  below) {
1574
1692
  const clean = cleanInstance(instance);
1575
1693
  check(clean);
1576
- const { anonymous, viewer } = checkGrant(clean, grant);
1694
+ const { anonymous, viewer, embed } = checkGrant(clean, grant);
1695
+ if (embed && entry !== undefined) {
1696
+ throw new TypeError("An embed grant opens a frame, never a clean address (redirect entry is for a tab, P143)");
1697
+ }
1577
1698
  const ttl = seconds(grant.ttlSeconds, DEFAULT_TICKET_SECONDS, MAX_TICKET_SECONDS, "ttlSeconds");
1578
1699
  const sessionSeconds = sessionOf(grant);
1579
1700
  const key = keys.instanceKey(clean);
@@ -1587,8 +1708,9 @@ export function createServer(options) {
1587
1708
  ...(entry?.base === undefined
1588
1709
  ? {}
1589
1710
  : { b: entry.base, ...(entry.pinned === true ? { k: 1 } : {}) }),
1711
+ ...(embed ? { m: 1 } : {}),
1590
1712
  });
1591
- if (cookieName(key).length + probe.length + 120 > MAX_COOKIE_BYTES) {
1713
+ if (sessionName(key, embed).length + probe.length + 120 > MAX_COOKIE_BYTES) {
1592
1714
  throw new TypeError("This instance is too large to carry in a cookie (fewer origins?)");
1593
1715
  }
1594
1716
  const ticket = newTicket();
@@ -1601,11 +1723,13 @@ export function createServer(options) {
1601
1723
  ...(grant.subject === undefined ? {} : { subject: grant.subject }),
1602
1724
  ...(entry === undefined ? {} : { entry }),
1603
1725
  ...(below === undefined ? {} : { page: below }),
1726
+ ...(embed ? { embed: true } : {}),
1604
1727
  };
1605
1728
  await tickets.put(ticketId(ticket), record);
1606
1729
  // A frame on its scope's origin has a door (P125): its ticket, for the same grant and as long.
1730
+ // An embed grant's has none (P143): a door tells a host how loading went, and there is none.
1607
1731
  let door = null;
1608
- if (entry === undefined && hasDoor(clean)) {
1732
+ if (entry === undefined && !embed && hasDoor(clean)) {
1609
1733
  door = newTicket();
1610
1734
  await tickets.put(ticketId(door), { ...record, door: true });
1611
1735
  }
@@ -1681,7 +1805,8 @@ export function createServer(options) {
1681
1805
  return {
1682
1806
  url: `${origin}${path}`,
1683
1807
  origin,
1684
- reports: true,
1808
+ // An embed session's pages tell no one how loading went (P143): they name no host.
1809
+ reports: grant.embed !== true,
1685
1810
  ...(viewer ? { viewer } : {}),
1686
1811
  // Its door (P125): the host frames it first, and takes its word alone.
1687
1812
  ...(door === null ? {} : { door: { url: `${origin}${DOOR_PATH}${key}?ticket=${door}` } }),
@@ -1698,7 +1823,10 @@ export function createServer(options) {
1698
1823
  if (below !== undefined && (!isPageRest(below) || clean.document.kind !== "artifact")) {
1699
1824
  throw new TypeError("A frame's page is a relative path below an artifact's files (no . or ..)");
1700
1825
  }
1701
- const { anonymous, viewer } = checkGrant(clean, grant);
1826
+ const { anonymous, viewer, embed } = checkGrant(clean, grant);
1827
+ if (embed) {
1828
+ throw new TypeError("An embed grant has no door (P143): a door tells a host how loading went, and there is none");
1829
+ }
1702
1830
  const sessionSeconds = sessionOf(grant);
1703
1831
  const origin = originOfLabel(labelFor(clean));
1704
1832
  return answerDoor(request ?? new Request(`${origin}${DOOR_PATH}${keys.instanceKey(clean)}`), {
@@ -75,6 +75,17 @@ export type Grant = ({
75
75
  readonly id: string;
76
76
  readonly name?: string;
77
77
  };
78
+ /**
79
+ * An embedded document (P143): a public page that any site may frame, with no host. Only where
80
+ * the server opted in (`ServerOptions.embeds`), only with `anonymous: true` and no `level` or
81
+ * `user`, and only for an artifact's page that isn't nested (never a url-mode app, a served shell,
82
+ * the sandbox proxy or a nested display); anything else throws at `issue`. Carried signed in the
83
+ * session (and in a frame's sealed files' address), so it is never added to a session or taken
84
+ * from one. Every answer of such a session says `frame-ancestors *` (no other session's changes),
85
+ * its shell's plan names no host (it asks no host, hears none and tells no parent anything; the
86
+ * bridge never runs), and `issue` mints no door.
87
+ */
88
+ readonly embed?: true;
78
89
  };
79
90
  export interface TicketRecord {
80
91
  readonly instance: InstanceRef;
@@ -110,6 +121,8 @@ export interface TicketRecord {
110
121
  * content's address; the door takes no other.
111
122
  */
112
123
  readonly door?: true;
124
+ /** An embed grant's (P143): the session it buys is an embed session. */
125
+ readonly embed?: true;
113
126
  }
114
127
  /** Where tickets live between `issue` and their one use. Default: in memory (one process). */
115
128
  export interface TicketStore {
@@ -214,6 +227,11 @@ export interface Access {
214
227
  readonly origin: string;
215
228
  /** When the cookie stops being good, epoch milliseconds. */
216
229
  readonly expiresAt: number;
230
+ /**
231
+ * An embed session's (P143, `Grant.embed`): its answers may be framed by any page, and its
232
+ * documents name no host. Absent for every other session.
233
+ */
234
+ readonly embed?: true;
217
235
  }
218
236
  /**
219
237
  * Answers a url-mode app's request once `/server` has checked its access: the host's way to the
@@ -228,6 +246,11 @@ export interface AuthorizeRequest {
228
246
  readonly viewer: string;
229
247
  readonly anonymous: boolean;
230
248
  readonly subject?: string;
249
+ /**
250
+ * Whether the session is an embed session (P143, `Grant.embed`): absent for every other, so a
251
+ * host's check can hold an embed subject to embed sessions alone.
252
+ */
253
+ readonly embed?: true;
231
254
  /** The request itself (its path, method; never its Porthole cookie's value). */
232
255
  readonly request: Request;
233
256
  }
@@ -266,6 +289,13 @@ export interface ServerOptions {
266
289
  * (`http://` on loopback), none a host origin, none the content domain's site. Default none.
267
290
  */
268
291
  readonly framedBy?: readonly string[];
292
+ /**
293
+ * Whether `issue` takes an embed grant (P143, `Grant.embed`): a public artifact page that any
294
+ * site may frame, with no host. Default false: an embed grant throws, and a session or sealed
295
+ * address that says it is one opens nothing. Only an embed session's answers say
296
+ * `frame-ancestors *`; every other answer is as without it, byte for byte.
297
+ */
298
+ readonly embeds?: boolean;
269
299
  /**
270
300
  * The configs a served shell or page is served under, by the name a `ServedDocument` gives
271
301
  * (an artifact defaults to `artifact`, the MCP Apps sandbox proxy to `mcpApp`).
@@ -157,8 +157,9 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
157
157
  const getAttribute = Element.prototype.getAttribute;
158
158
  const listenOn = EventTarget.prototype.addEventListener;
159
159
  const post = window.parent.postMessage.bind(window.parent);
160
- // Read once: content can replace window.parent (it is [Replaceable]), never what was read.
161
- const framed = window.parent !== window;
160
+ // Read once: content can replace window.parent (it is [Replaceable]), never what was read. A
161
+ // hostless plan (P143) tells no parent anything.
162
+ const framed = window.parent !== window && !hostless;
162
163
  const tell = (method, params) => {
163
164
  if (framed) {
164
165
  post({ jsonrpc: "2.0", method, params }, "*");
@@ -255,7 +255,8 @@ export const FIND_RUNTIME = String.raw `if (declared("find")) {
255
255
  const time = () => callOf(clock, Date, []);
256
256
  // Read once: content can replace window.parent (it is [Replaceable]), never what was read.
257
257
  const parentWindow = window.parent;
258
- const framed = parentWindow !== window;
258
+ // A hostless plan (P143) tells no parent anything.
259
+ const framed = parentWindow !== window && !hostless;
259
260
  const postIn = parentWindow.postMessage;
260
261
  const post = (message) => callOf(postIn, parentWindow, [message, "*"]);
261
262
  // Whose shortcut it is: Cmd on Apple's platforms, Ctrl elsewhere (read before content runs).