@mostra/protocol 0.6.2 → 0.8.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.
Files changed (73) hide show
  1. package/dist/actions.d.ts +12 -0
  2. package/dist/actions.d.ts.map +1 -1
  3. package/dist/actions.js.map +1 -1
  4. package/dist/bridge.d.ts +25 -0
  5. package/dist/bridge.d.ts.map +1 -1
  6. package/dist/bridge.js +32 -2
  7. package/dist/bridge.js.map +1 -1
  8. package/dist/browser.d.ts +76 -0
  9. package/dist/browser.d.ts.map +1 -1
  10. package/dist/browser.js +45 -2
  11. package/dist/browser.js.map +1 -1
  12. package/dist/diagnostics/codes/hygiene.d.ts +1 -1
  13. package/dist/diagnostics/codes/hygiene.d.ts.map +1 -1
  14. package/dist/diagnostics/codes/hygiene.js +12 -1
  15. package/dist/diagnostics/codes/hygiene.js.map +1 -1
  16. package/dist/diagnostics/codes/index.d.ts +3 -2
  17. package/dist/diagnostics/codes/index.d.ts.map +1 -1
  18. package/dist/diagnostics/codes/index.js +3 -1
  19. package/dist/diagnostics/codes/index.js.map +1 -1
  20. package/dist/diagnostics/codes/share.d.ts +8 -0
  21. package/dist/diagnostics/codes/share.d.ts.map +1 -0
  22. package/dist/diagnostics/codes/share.js +88 -0
  23. package/dist/diagnostics/codes/share.js.map +1 -0
  24. package/dist/hygiene.d.ts.map +1 -1
  25. package/dist/hygiene.js +2 -1
  26. package/dist/hygiene.js.map +1 -1
  27. package/dist/ids.d.ts +5 -1
  28. package/dist/ids.d.ts.map +1 -1
  29. package/dist/ids.js +3 -1
  30. package/dist/ids.js.map +1 -1
  31. package/dist/index.d.ts +10 -5
  32. package/dist/index.js +9 -4
  33. package/dist/methods/index.d.ts.map +1 -1
  34. package/dist/methods/index.js +9 -1
  35. package/dist/methods/index.js.map +1 -1
  36. package/dist/methods/instance/status.d.ts +24 -0
  37. package/dist/methods/instance/status.d.ts.map +1 -1
  38. package/dist/methods/instance/status.js +11 -2
  39. package/dist/methods/instance/status.js.map +1 -1
  40. package/dist/methods/port/addressing-external-base.d.ts +52 -0
  41. package/dist/methods/port/addressing-external-base.d.ts.map +1 -0
  42. package/dist/methods/port/addressing-external-base.js +61 -0
  43. package/dist/methods/port/addressing-external-base.js.map +1 -0
  44. package/dist/methods/share/list.d.ts +23 -0
  45. package/dist/methods/share/list.d.ts.map +1 -0
  46. package/dist/methods/share/list.js +29 -0
  47. package/dist/methods/share/list.js.map +1 -0
  48. package/dist/methods/share/start.d.ts +96 -0
  49. package/dist/methods/share/start.d.ts.map +1 -0
  50. package/dist/methods/share/start.js +73 -0
  51. package/dist/methods/share/start.js.map +1 -0
  52. package/dist/methods/share/stop.d.ts +29 -0
  53. package/dist/methods/share/stop.d.ts.map +1 -0
  54. package/dist/methods/share/stop.js +32 -0
  55. package/dist/methods/share/stop.js.map +1 -0
  56. package/package.json +2 -2
  57. package/schemas/protocol.draft-07.json +535 -0
  58. package/schemas/protocol.schema.json +507 -0
  59. package/src/actions.ts +12 -0
  60. package/src/bridge.ts +49 -0
  61. package/src/browser.ts +118 -0
  62. package/src/diagnostics/codes/hygiene.ts +12 -0
  63. package/src/diagnostics/codes/index.ts +6 -2
  64. package/src/diagnostics/codes/share.ts +100 -0
  65. package/src/hygiene.ts +1 -0
  66. package/src/ids.ts +9 -1
  67. package/src/index.ts +39 -0
  68. package/src/methods/index.ts +8 -0
  69. package/src/methods/instance/status.ts +38 -0
  70. package/src/methods/port/addressing-external-base.ts +113 -0
  71. package/src/methods/share/list.ts +42 -0
  72. package/src/methods/share/start.ts +150 -0
  73. package/src/methods/share/stop.ts +50 -0
package/src/browser.ts CHANGED
@@ -231,6 +231,12 @@ export interface FrameTicket extends ViewContext {
231
231
  * shell says so, and it is never a published version.
232
232
  */
233
233
  readonly devPreview?: true;
234
+ /**
235
+ * `worker` when the shell and the artifact are two sites (a Cloudflare quick tunnel, a host's
236
+ * addresses on two hosts): the frame enters through the bootstrap page and a service worker
237
+ * (D70, D158 item 5). Absent: cookie mode.
238
+ */
239
+ readonly mode?: "worker";
234
240
  }
235
241
 
236
242
  /** The Zod schema of the `FrameTicket` type. */
@@ -250,12 +256,124 @@ export const FrameTicket: z.ZodType<FrameTicket> = z
250
256
  pinned: z.boolean(),
251
257
  serverParked: z.literal(true).exactOptional(),
252
258
  devPreview: z.literal(true).exactOptional(),
259
+ mode: z.literal("worker").exactOptional(),
253
260
  })
254
261
  .register(wireRegistry, {
255
262
  id: "FrameTicket",
256
263
  description: "A frame ticket: the view it opens, where to load it, and the view's controls.",
257
264
  });
258
265
 
266
+ // ── Frame sessions in worker mode (WP-13, D70, D158 item 5) ───────────────────────────────
267
+
268
+ /**
269
+ * The header Mostra's service worker adds to every same-origin request of a worker-mode frame:
270
+ * its frame session's secret, which no cookie can carry across sites.
271
+ */
272
+ export const FRAME_SESSION_HEADER = "x-mostra-frame";
273
+
274
+ /**
275
+ * `POST /_mostra/enter` on the artifact's origin: the bootstrap page exchanges the shell's
276
+ * single-use frame ticket, from `/_mostra/enter#t=…`, for a worker-mode frame session.
277
+ */
278
+ export interface EnterRequest {
279
+ /** The frame ticket. */
280
+ readonly ticket: string;
281
+ }
282
+
283
+ /** The Zod schema of the `EnterRequest` type. */
284
+ export const EnterRequest: z.ZodType<EnterRequest> = z
285
+ .object({ ticket: z.string().min(1).max(64) })
286
+ .register(wireRegistry, { id: "EnterRequest", description: "A frame ticket to exchange." });
287
+
288
+ /** The answer to `EnterRequest`. */
289
+ export interface EnterResult {
290
+ /** The frame session's secret, which the service worker sends as `X-Mostra-Frame`. */
291
+ readonly session: string;
292
+ /** The shell's origin: the only page the bootstrap reports to. */
293
+ readonly shellOrigin: string;
294
+ }
295
+
296
+ /** The Zod schema of the `EnterResult` type. */
297
+ export const EnterResult: z.ZodType<EnterResult> = z
298
+ .object({ session: z.string().min(1), shellOrigin: z.string().min(1) })
299
+ .register(wireRegistry, {
300
+ id: "EnterResult",
301
+ description: "A worker-mode frame session's secret and the shell's origin.",
302
+ });
303
+
304
+ /**
305
+ * `POST /_mostra/v/{rev}/ticket`: a single-use ticket that opens one event stream, long poll or
306
+ * WebSocket of this session without it (`?ticket=`), so the request can bypass the service
307
+ * worker (VERIFIED_FACTS: Firefox stalls on endless responses a worker passes on).
308
+ */
309
+ export interface StreamTicketRequest {
310
+ /** What it opens: `stream` (events and polls, the default) or `socket` (a WebSocket). */
311
+ readonly purpose?: "stream" | "socket";
312
+ }
313
+
314
+ /** The Zod schema of the `StreamTicketRequest` type. */
315
+ export const StreamTicketRequest: z.ZodType<StreamTicketRequest> = z
316
+ .object({ purpose: z.enum(["stream", "socket"]).exactOptional() })
317
+ .register(wireRegistry, { id: "StreamTicketRequest" });
318
+
319
+ /** The answer to a `StreamTicketRequest`. */
320
+ export interface StreamTicket {
321
+ /** The ticket: 130 bits, single-use. */
322
+ readonly ticket: string;
323
+ /** When it stops working, 60 s after it was minted. */
324
+ readonly expiresAt: string;
325
+ }
326
+
327
+ /** The Zod schema of the `StreamTicket` type. */
328
+ export const StreamTicket: z.ZodType<StreamTicket> = z
329
+ .object({ ticket: z.string().min(1), expiresAt: z.iso.datetime() })
330
+ .register(wireRegistry, {
331
+ id: "StreamTicket",
332
+ description: "A single-use ticket for one stream, poll or WebSocket.",
333
+ });
334
+
335
+ /**
336
+ * `GET /_mostra/session` on the artifact's origin: the frame session's facts for same-origin code.
337
+ */
338
+ export interface FrameSessionFacts {
339
+ /** The CSRF token every mutation sends as `X-Mostra-CSRF`. */
340
+ readonly csrf: string;
341
+ /** The artifact the frame shows. */
342
+ readonly artifactId: string;
343
+ /** The shell's exact origin: the bridge's only peer. */
344
+ readonly shellOrigin: string;
345
+ /** The link's scopes. */
346
+ readonly scopes: readonly string[];
347
+ /** The viewer the page acts as (WP-07). */
348
+ readonly viewer?: Viewer;
349
+ /** The version the frame session entered. */
350
+ readonly version?: VersionRef;
351
+ /** How the frame authenticates (D70): absent means `cookie`. */
352
+ readonly mode?: "cookie" | "worker";
353
+ /**
354
+ * `false` where event streams don't pass (a Cloudflare quick tunnel holds responses back until
355
+ * they end): the page long-polls from the start (D47). Absent means streams pass.
356
+ */
357
+ readonly streams?: boolean;
358
+ }
359
+
360
+ /** The Zod schema of the `FrameSessionFacts` type. */
361
+ export const FrameSessionFacts: z.ZodType<FrameSessionFacts> = z
362
+ .object({
363
+ csrf: z.string().min(1),
364
+ artifactId: ArtifactId.schema,
365
+ shellOrigin: z.string().min(1),
366
+ scopes: z.array(z.string()).readonly(),
367
+ viewer: Viewer.exactOptional(),
368
+ version: VersionRef.exactOptional(),
369
+ mode: z.enum(["cookie", "worker"]).exactOptional(),
370
+ streams: z.boolean().exactOptional(),
371
+ })
372
+ .register(wireRegistry, {
373
+ id: "FrameSessionFacts",
374
+ description: "A frame session's CSRF token, shell origin, scopes, viewer, version and mode.",
375
+ });
376
+
259
377
  // ── The shell's own routes (WP-07, on the shell origin) ──────────────────────────────────
260
378
 
261
379
  /**
@@ -20,6 +20,7 @@ export const hygieneDiagnosticCodes = [
20
20
  "MOSTRA_HYGIENE_NOT_SERVED",
21
21
  "MOSTRA_HYGIENE_SESSION_CONFLICT",
22
22
  "MOSTRA_HYGIENE_HEADERS_TOO_LARGE",
23
+ "MOSTRA_HYGIENE_FRAME_SESSION",
23
24
  // gen:codes
24
25
  ] as const;
25
26
 
@@ -171,5 +172,16 @@ export const hygieneDiagnostics: AreaCatalog<HygieneDiagnosticCode> = {
171
172
  fix: "Open the artifact's link again. If it keeps happening, find the page that sets the cookies: it runs on this host.",
172
173
  },
173
174
  },
175
+ MOSTRA_HYGIENE_FRAME_SESSION: {
176
+ severity: "error",
177
+ phase: "hygiene",
178
+ title: "Frame session couldn't start",
179
+ hint: "Open the artifact's tailnet or Funnel link, or this link in a normal window of another browser.",
180
+ docs: {
181
+ explanation:
182
+ "Where the shell and the artifact are two sites (a Cloudflare quick tunnel, or a host's addresses on two hosts), the artifact's frame can't use a cookie: it enters through a bootstrap page that installs Mostra's service worker at `/`, which signs every request of the frame (worker mode, D70). Mostra reports this code when that can't happen: the browser offers the frame no service worker (a private window, a setting that blocks third-party storage), refuses to install it, or the gateway refused the frame's entry. The client runtime reports it too when the artifact's own code registers another service worker at `/`, which would replace Mostra's and end the frame's session.",
183
+ fix: "Open the artifact through a tailnet or Funnel share, where the frame uses a cookie, or in a browser window that allows service workers in frames. An artifact that needs its own service worker registers it at a narrower scope than `/`.",
184
+ },
185
+ },
174
186
  // gen:entries
175
187
  };
@@ -8,7 +8,6 @@ import { type A11yDiagnosticCode, a11yDiagnostics } from "./a11y.ts";
8
8
  import { type ActionDiagnosticCode, actionDiagnostics } from "./action.ts";
9
9
  import { type ArtifactDiagnosticCode, artifactDiagnostics } from "./artifact.ts";
10
10
  import { type BuildDiagnosticCode, buildDiagnostics } from "./build.ts";
11
- // gen:area-imports
12
11
  import { type CliDiagnosticCode, cliDiagnostics } from "./cli.ts";
13
12
  import { type ConsoleDiagnosticCode, consoleDiagnostics } from "./console.ts";
14
13
  import { type DepDiagnosticCode, depDiagnostics } from "./dep.ts";
@@ -25,6 +24,8 @@ import { type PublishDiagnosticCode, publishDiagnostics } from "./publish.ts";
25
24
  import { type RegressionDiagnosticCode, regressionDiagnostics } from "./regression.ts";
26
25
  import { type RuntimeDiagnosticCode, runtimeDiagnostics } from "./runtime.ts";
27
26
  import { type SecretDiagnosticCode, secretDiagnostics } from "./secret.ts";
27
+ // gen:area-imports
28
+ import { type ShareDiagnosticCode, shareDiagnostics } from "./share.ts";
28
29
  import { type SmokeDiagnosticCode, smokeDiagnostics } from "./smoke.ts";
29
30
  import { type SubmitDiagnosticCode, submitDiagnostics } from "./submit.ts";
30
31
  import { type TargetDiagnosticCode, targetDiagnostics } from "./target.ts";
@@ -35,7 +36,6 @@ export { type A11yDiagnosticCode, a11yDiagnosticCodes } from "./a11y.ts";
35
36
  export { type ActionDiagnosticCode, actionDiagnosticCodes } from "./action.ts";
36
37
  export { type ArtifactDiagnosticCode, artifactDiagnosticCodes } from "./artifact.ts";
37
38
  export { type BuildDiagnosticCode, buildDiagnosticCodes } from "./build.ts";
38
- // gen:area-exports
39
39
  export { type CliDiagnosticCode, cliDiagnosticCodes } from "./cli.ts";
40
40
  export { type ConsoleDiagnosticCode, consoleDiagnosticCodes } from "./console.ts";
41
41
  export { type DepDiagnosticCode, depDiagnosticCodes } from "./dep.ts";
@@ -52,6 +52,8 @@ export { type PublishDiagnosticCode, publishDiagnosticCodes } from "./publish.ts
52
52
  export { type RegressionDiagnosticCode, regressionDiagnosticCodes } from "./regression.ts";
53
53
  export { type RuntimeDiagnosticCode, runtimeDiagnosticCodes } from "./runtime.ts";
54
54
  export { type SecretDiagnosticCode, secretDiagnosticCodes } from "./secret.ts";
55
+ // gen:area-exports
56
+ export { type ShareDiagnosticCode, shareDiagnosticCodes } from "./share.ts";
55
57
  export { type SmokeDiagnosticCode, smokeDiagnosticCodes } from "./smoke.ts";
56
58
  export { type SubmitDiagnosticCode, submitDiagnosticCodes } from "./submit.ts";
57
59
  export { type TargetDiagnosticCode, targetDiagnosticCodes } from "./target.ts";
@@ -61,6 +63,7 @@ export { type VerifyDiagnosticCode, verifyDiagnosticCodes } from "./verify.ts";
61
63
  /** Every code in the catalog. Codes are semver surface and are never removed (AX-03). */
62
64
  export type KnownDiagnosticCode =
63
65
  // gen:area-codes
66
+ | ShareDiagnosticCode
64
67
  | CliDiagnosticCode
65
68
  | RegressionDiagnosticCode
66
69
  | SmokeDiagnosticCode
@@ -90,6 +93,7 @@ export type KnownDiagnosticCode =
90
93
  /** Every cataloged code with its severity, phase, title, default hint and docs text. */
91
94
  export const diagnosticCatalog: Readonly<Record<KnownDiagnosticCode, DiagnosticSpec>> = {
92
95
  // gen:area-spreads
96
+ ...shareDiagnostics,
93
97
  ...cliDiagnostics,
94
98
  ...regressionDiagnostics,
95
99
  ...smokeDiagnostics,
@@ -0,0 +1,100 @@
1
+ /**
2
+ * Diagnostic codes of the SHARE area.
3
+ */
4
+ import type { AreaCatalog } from "../spec.ts";
5
+
6
+ /** The codes of the SHARE area, in the order they were added. */
7
+ export const shareDiagnosticCodes = [
8
+ "MOSTRA_SHARE_TOOL_MISSING",
9
+ "MOSTRA_SHARE_TOOL_NOT_READY",
10
+ "MOSTRA_SHARE_NOT_ENABLED",
11
+ "MOSTRA_SHARE_PORTS_EXHAUSTED",
12
+ "MOSTRA_SHARE_TUNNEL_FAILED",
13
+ "MOSTRA_SHARE_NOT_FOUND",
14
+ "MOSTRA_SHARE_TTL_INVALID",
15
+ // gen:codes
16
+ ] as const;
17
+
18
+ /** The codes of the SHARE area. */
19
+ export type ShareDiagnosticCode = (typeof shareDiagnosticCodes)[number];
20
+
21
+ /** The SHARE area's catalog entries. */
22
+ export const shareDiagnostics: AreaCatalog<ShareDiagnosticCode> = {
23
+ MOSTRA_SHARE_TOOL_MISSING: {
24
+ severity: "error",
25
+ phase: "host",
26
+ title: "Sharing tool not installed",
27
+ hint: "Install the tool the message names, then run the share again.",
28
+ docs: {
29
+ explanation:
30
+ "A share drives a tunnel tool installed on this machine: `tailscale` for tailnet and Funnel shares, `cloudflared` for Cloudflare quick tunnels. Mostra never bundles or downloads them; it found none where it looks (`PATH`, the tool's usual install locations, or `MOSTRA_TAILSCALE` and `MOSTRA_CLOUDFLARED`). The message says how to install it on this system.",
31
+ fix: "Install the tool (Tailscale from tailscale.com/download, `cloudflared` from Cloudflare's downloads or a package manager), or point `MOSTRA_TAILSCALE` or `MOSTRA_CLOUDFLARED` at it, then share again.",
32
+ },
33
+ },
34
+ MOSTRA_SHARE_TOOL_NOT_READY: {
35
+ severity: "error",
36
+ phase: "host",
37
+ title: "Sharing tool not ready",
38
+ hint: "Do what the message says to the tool, then run the share again.",
39
+ docs: {
40
+ explanation:
41
+ "The tunnel tool is installed but can't serve yet: Tailscale isn't running or isn't signed in to a tailnet, or `cloudflared` exited before it opened a tunnel. The message quotes what the tool reported.",
42
+ fix: "Start Tailscale and sign in (`tailscale up`), or check that `cloudflared` runs and this machine reaches Cloudflare, then share again.",
43
+ },
44
+ },
45
+ MOSTRA_SHARE_NOT_ENABLED: {
46
+ severity: "error",
47
+ phase: "host",
48
+ title: "Sharing not enabled on the tailnet",
49
+ hint: "Open the address in the message as the tailnet's admin to turn the feature on, then run the share again.",
50
+ docs: {
51
+ explanation:
52
+ "Tailscale Serve needs HTTPS certificates turned on for the tailnet, and Funnel needs the Funnel permission for this device. Tailscale refused the share and gave an address where an admin of the tailnet turns the feature on; the message carries it.",
53
+ fix: "Open the address as an admin of the tailnet and approve, then share again. Without admin rights, ask the tailnet's admin, or share publicly through a Cloudflare quick tunnel (`mostra share <artifact> --public`).",
54
+ },
55
+ },
56
+ MOSTRA_SHARE_PORTS_EXHAUSTED: {
57
+ severity: "error",
58
+ phase: "host",
59
+ title: "No tunnel port free",
60
+ hint: "Stop a share you no longer need (`mostra share list`, then `mostra share stop <share>`), or share through a Cloudflare quick tunnel.",
61
+ docs: {
62
+ explanation:
63
+ "Tailscale Funnel listens only on ports 443, 8443 and 10000 of a device: Mostra gives 443 to the shell and the other two to one artifact each, so at most two artifacts are shared through Funnel at once. A port is also unavailable when this device's own Serve or Funnel configuration already uses it.",
64
+ fix: "Stop one of the Funnel shares, free the port in Tailscale's own configuration, or share this artifact through a Cloudflare quick tunnel.",
65
+ },
66
+ },
67
+ MOSTRA_SHARE_TUNNEL_FAILED: {
68
+ severity: "error",
69
+ phase: "host",
70
+ title: "Tunnel failed",
71
+ hint: "Run the share again; if it fails the same way, check the tool's message and this machine's network.",
72
+ docs: {
73
+ explanation:
74
+ "The tunnel tool started but didn't serve within its time, or stopped: the message quotes what it reported. A share whose tunnel ends and can't be set up again stops, and `mostra share list` shows why; a Cloudflare quick tunnel can't keep its address, so its share ends with it.",
75
+ fix: "Share again for a new link. A tailnet or Funnel share keeps its address across restarts of its tunnel; a Cloudflare quick tunnel gets a new one each time.",
76
+ },
77
+ },
78
+ MOSTRA_SHARE_NOT_FOUND: {
79
+ severity: "error",
80
+ phase: "host",
81
+ title: "Unknown share",
82
+ hint: "List the home's shares with `mostra share list` and name one of them.",
83
+ docs: {
84
+ explanation: "No share of this home has the ID given, or the artifact has no share.",
85
+ fix: "Use a share ID from `mostra share list`.",
86
+ },
87
+ },
88
+ MOSTRA_SHARE_TTL_INVALID: {
89
+ severity: "error",
90
+ phase: "host",
91
+ title: "Share lifetime refused",
92
+ hint: "Give a public share a lifetime of at most 7 days, such as `--ttl 24h`.",
93
+ docs: {
94
+ explanation:
95
+ "A public share (Funnel or Cloudflare) admits anyone holding its link, so it lasts 1 hour unless `ttl` says otherwise, and at most 7 days. Tailnet shares have no limit.",
96
+ fix: "Use a `ttl` of 7 days or less, and share again when it ends, or share inside the tailnet.",
97
+ },
98
+ },
99
+ // gen:entries
100
+ };
package/src/hygiene.ts CHANGED
@@ -76,6 +76,7 @@ const STATUS: Readonly<Record<HygieneDiagnosticCode, number>> = {
76
76
  MOSTRA_HYGIENE_NOT_SERVED: 404,
77
77
  MOSTRA_HYGIENE_SESSION_CONFLICT: 409,
78
78
  MOSTRA_HYGIENE_HEADERS_TOO_LARGE: 431,
79
+ MOSTRA_HYGIENE_FRAME_SESSION: 403,
79
80
  };
80
81
 
81
82
  /** Builds a refusal with the status the code's HTTP mapping gives (FAILURE_MODEL §8). */
package/src/ids.ts CHANGED
@@ -28,7 +28,8 @@ export type IdPrefix =
28
28
  | "thr"
29
29
  | "cmt"
30
30
  | "tok"
31
- | "mut";
31
+ | "mut"
32
+ | "shr";
32
33
 
33
34
  /**
34
35
  * A branded ID string. The brand exists only at the type level, so an `Id<"art">` is a plain
@@ -242,6 +243,13 @@ export const MutationId: GeneratedIdKind<"mut"> = generated(
242
243
  defineKind("mut", "mutation", "ulid", "MutationId"),
243
244
  );
244
245
 
246
+ /** A share ID (`shr_` + ULID): one share of an artifact through a tunnel (D158). */
247
+ export type ShareId = Id<"shr">;
248
+ /** Share IDs. */
249
+ export const ShareId: GeneratedIdKind<"shr"> = generated(
250
+ defineKind("shr", "share", "ulid", "ShareId"),
251
+ );
252
+
245
253
  /**
246
254
  * An event cursor: the decimal string of a home-wide event position (INTERFACES §1). Decimal
247
255
  * strings keep 64-bit positions exact in JavaScript.
package/src/index.ts CHANGED
@@ -66,11 +66,14 @@ export {
66
66
  type FieldRegistration,
67
67
  type FieldsParams,
68
68
  type FlushResult,
69
+ type FrameSessionFailedParams,
69
70
  MCP_APPS_PROTOCOL_VERSION,
70
71
  mostraControlsRequest,
71
72
  mostraFieldFocus,
72
73
  mostraFields,
73
74
  mostraFlush,
75
+ mostraFrameSessionEntered,
76
+ mostraFrameSessionFailed,
74
77
  mostraPage,
75
78
  mostraReady,
76
79
  mostraVersionAvailable,
@@ -92,8 +95,12 @@ export {
92
95
  ChooseRequest,
93
96
  type DeliveryTarget,
94
97
  DocumentSnapshot,
98
+ EnterRequest,
99
+ EnterResult,
95
100
  FieldsRequest,
96
101
  FollowRequest,
102
+ FRAME_SESSION_HEADER,
103
+ FrameSessionFacts,
97
104
  FrameTicket,
98
105
  OrphanedField,
99
106
  PollResult,
@@ -103,6 +110,8 @@ export {
103
110
  SIGNAL_PAYLOAD_MAX_BYTES,
104
111
  SignalRequest,
105
112
  StreamSnapshot,
113
+ StreamTicket,
114
+ StreamTicketRequest,
106
115
  SubmitRequest,
107
116
  VersionRef,
108
117
  ViewContext,
@@ -178,9 +187,11 @@ export {
178
187
  regressionDiagnosticCodes,
179
188
  runtimeDiagnosticCodes,
180
189
  type SecretDiagnosticCode,
190
+ type ShareDiagnosticCode,
181
191
  type SmokeDiagnosticCode,
182
192
  type SubmitDiagnosticCode,
183
193
  secretDiagnosticCodes,
194
+ shareDiagnosticCodes,
184
195
  smokeDiagnosticCodes,
185
196
  submitDiagnosticCodes,
186
197
  type TargetDiagnosticCode,
@@ -233,6 +244,7 @@ export {
233
244
  type IdPrefix,
234
245
  MutationId,
235
246
  RunId,
247
+ ShareId,
236
248
  SubmissionId,
237
249
  ThreadId,
238
250
  TokenId,
@@ -370,6 +382,7 @@ export {
370
382
  export {
371
383
  ChildProcessStatus,
372
384
  DeliveryCounts,
385
+ type FaceStatus,
373
386
  GatewayStatus,
374
387
  type InstanceStatusParams,
375
388
  type InstanceStatusResult,
@@ -395,6 +408,13 @@ export {
395
408
  type MostraShutdownResult,
396
409
  mostraShutdownMethod,
397
410
  } from "./methods/mostra/shutdown.ts";
411
+ export {
412
+ ExternalBase,
413
+ OriginString,
414
+ type PortAddressingExternalBaseParams,
415
+ type PortAddressingExternalBaseResult,
416
+ portAddressingExternalBaseMethod,
417
+ } from "./methods/port/addressing-external-base.ts";
398
418
  export {
399
419
  DraftMirror,
400
420
  type DraftsMirrorResult,
@@ -448,6 +468,25 @@ export {
448
468
  type SecretSetResult,
449
469
  secretSetMethod,
450
470
  } from "./methods/secret/set.ts";
471
+ export {
472
+ type ShareListParams,
473
+ type ShareListResult,
474
+ shareListMethod,
475
+ } from "./methods/share/list.ts";
476
+ export {
477
+ PUBLIC_SHARE_DEFAULT_TTL,
478
+ PUBLIC_SHARE_MAX_TTL_MS,
479
+ Share,
480
+ type ShareStartParams,
481
+ type ShareStartResult,
482
+ ShareVia,
483
+ shareStartMethod,
484
+ } from "./methods/share/start.ts";
485
+ export {
486
+ type ShareStopParams,
487
+ type ShareStopResult,
488
+ shareStopMethod,
489
+ } from "./methods/share/stop.ts";
451
490
  export { type StateGetParams, type StateGetResult, stateGetMethod } from "./methods/state/get.ts";
452
491
  export {
453
492
  type StatePatchParams,
@@ -22,6 +22,7 @@ import { instanceStatusMethod } from "./instance/status.ts";
22
22
  import { livePushMethod } from "./live/push.ts";
23
23
  import { mostraInitializeMethod } from "./mostra/initialize.ts";
24
24
  import { mostraShutdownMethod } from "./mostra/shutdown.ts";
25
+ import { portAddressingExternalBaseMethod } from "./port/addressing-external-base.ts";
25
26
  import { portDraftsMirrorMethod } from "./port/drafts-mirror.ts";
26
27
  import { portIdentityResolveMethod } from "./port/identity-resolve.ts";
27
28
  import { portSecretsGetMethod } from "./port/secrets-get.ts";
@@ -32,6 +33,9 @@ import { resultsGetMethod } from "./results/get.ts";
32
33
  import { secretDeleteMethod } from "./secret/delete.ts";
33
34
  import { secretListMethod } from "./secret/list.ts";
34
35
  import { secretSetMethod } from "./secret/set.ts";
36
+ import { shareListMethod } from "./share/list.ts";
37
+ import { shareStartMethod } from "./share/start.ts";
38
+ import { shareStopMethod } from "./share/stop.ts";
35
39
  import { stateGetMethod } from "./state/get.ts";
36
40
  import { statePatchMethod } from "./state/patch.ts";
37
41
  import { viewDefaultMethod } from "./view/default.ts";
@@ -80,6 +84,10 @@ export const hostMethods: readonly AnyMethod[] = [
80
84
  devStartMethod,
81
85
  devStopMethod,
82
86
  portIdentityResolveMethod,
87
+ shareStartMethod,
88
+ shareStopMethod,
89
+ shareListMethod,
90
+ portAddressingExternalBaseMethod,
83
91
  // gen:methods
84
92
  ];
85
93
 
@@ -2,6 +2,7 @@ import * as z from "zod";
2
2
  import { defineMethod, type MethodDefinition } from "../../method.ts";
3
3
  import { wireRegistry } from "../../wire-registry.ts";
4
4
  import { InstanceInfo } from "../mostra/initialize.ts";
5
+ import { Share } from "../share/start.ts";
5
6
 
6
7
  /** The params of `instance/status` (INTERFACES §6): none. */
7
8
  export type InstanceStatusParams = Record<string, never>;
@@ -26,6 +27,25 @@ export interface GatewayStatus {
26
27
  readonly shell: string;
27
28
  /** The artifact origins it is serving now, one per opened artifact. */
28
29
  readonly artifacts: readonly { readonly artifactId: string; readonly origin: string }[];
30
+ /**
31
+ * The gateway's external addresses (D158 item 1): a share's tunnel addresses and a host's
32
+ * external bases, each a listener of its own on loopback (WP-13).
33
+ */
34
+ readonly faces?: readonly FaceStatus[];
35
+ }
36
+
37
+ /** One external address of the gateway (D158 item 1). */
38
+ export interface FaceStatus {
39
+ /** The origin browsers use. */
40
+ readonly origin: string;
41
+ /** The loopback origin the tunnel or the host forwards it to. */
42
+ readonly local: string;
43
+ /** Which listener it fronts: the shell, or one artifact's frame. */
44
+ readonly listener: "shell" | "artifact";
45
+ /** The artifact, for an artifact's face. */
46
+ readonly artifactId?: string;
47
+ /** Who keeps it: a share's tunnel (`tailnet`, `funnel`, `cloudflare`) or a host (`host`). */
48
+ readonly by: "tailnet" | "funnel" | "cloudflare" | "host" | (string & {});
29
49
  }
30
50
 
31
51
  /**
@@ -51,6 +71,11 @@ export interface InstanceStatusResult {
51
71
  readonly workers?: readonly WorkerStatus[];
52
72
  /** When the daemon exits for lack of work, if it will (WP-08, RT-08); absent: it won't. */
53
73
  readonly idleExitAt?: string;
74
+ /**
75
+ * The active shares (WP-13, D158), which keep a daemon from its idle exit. Their `url` is left
76
+ * out here, since status is printed where a link's secret mustn't appear: `share/list` gives it.
77
+ */
78
+ readonly shares?: readonly Share[];
54
79
  }
55
80
 
56
81
  /** One artifact version's worker (RT-03, D62). */
@@ -127,6 +152,18 @@ export const GatewayStatus: z.ZodType<GatewayStatus> = z
127
152
  bind: z.string(),
128
153
  shell: z.string(),
129
154
  artifacts: z.array(z.object({ artifactId: z.string(), origin: z.string() })).readonly(),
155
+ faces: z
156
+ .array(
157
+ z.object({
158
+ origin: z.string(),
159
+ local: z.string(),
160
+ listener: z.enum(["shell", "artifact"]),
161
+ artifactId: z.string().exactOptional(),
162
+ by: z.string(),
163
+ }),
164
+ )
165
+ .readonly()
166
+ .exactOptional(),
130
167
  })
131
168
  .register(wireRegistry, { id: "GatewayStatus", description: "Where the gateway listens." });
132
169
 
@@ -158,6 +195,7 @@ const result: z.ZodType<InstanceStatusResult> = z
158
195
  deliveries: z.array(DeliveryCounts).readonly().exactOptional(),
159
196
  workers: z.array(WorkerStatus).readonly().exactOptional(),
160
197
  idleExitAt: z.string().exactOptional(),
198
+ shares: z.array(Share).readonly().exactOptional(),
161
199
  })
162
200
  .register(wireRegistry, { id: "InstanceStatusResult" });
163
201
 
@@ -0,0 +1,113 @@
1
+ import * as z from "zod";
2
+ import { ArtifactId } from "../../ids.ts";
3
+ import { defineMethod, type MethodDefinition } from "../../method.ts";
4
+ import { wireRegistry } from "../../wire-registry.ts";
5
+
6
+ /**
7
+ * An origin as browsers write it (`https://host.example`, `http://host:8080`): a scheme, a lower
8
+ * case host and a port only when it isn't the scheme's default, with no path, query or fragment.
9
+ */
10
+ export const OriginString: z.ZodType<string> = z
11
+ .string()
12
+ .max(2048)
13
+ .regex(originPattern(), {
14
+ message: "An origin: http: or https:, a lower case host and a port only when not the default.",
15
+ })
16
+ .register(wireRegistry, {
17
+ id: "OriginString",
18
+ description: "A web origin: scheme, host and a port only when it isn't the default.",
19
+ });
20
+
21
+ /**
22
+ * An origin exactly as browsers serialize one, as one regular expression, so JSON Schema and the
23
+ * Rust crate check what Zod checks: a lower case DNS name or bracketed IPv6 literal, a port of 1
24
+ * to 65535, and never the scheme's default port written out.
25
+ */
26
+ function originPattern(): RegExp {
27
+ const label = "[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?";
28
+ const host = `(?:${label}(?:\\.${label})*|\\[[0-9a-f:.]+\\])`;
29
+ const port =
30
+ "(?:[1-9][0-9]{0,3}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5])";
31
+ return new RegExp(`^(?!http://[^/]*:80$)(?!https://[^/]*:443$)https?://${host}(?::${port})?$`);
32
+ }
33
+
34
+ /** The params of `port/addressing.externalBase` (INTERFACES §7, D158 item 6). */
35
+ export interface PortAddressingExternalBaseParams {
36
+ /** The artifact whose links or frame this address serves. */
37
+ readonly artifactId: string;
38
+ /**
39
+ * Which of Mostra's listeners the address fronts: `shell` for the artifact's links (the shell
40
+ * that opens them), `artifact` for the artifact's own frame.
41
+ */
42
+ readonly listener: "shell" | "artifact";
43
+ /**
44
+ * The loopback origin the host forwards this address to, such as `http://127.0.0.1:23456`: a
45
+ * port leased for this face, the same across restarts while the face exists.
46
+ */
47
+ readonly local: string;
48
+ }
49
+
50
+ /**
51
+ * The host's answer: the origin browsers use for this listener, and optionally how the artifact's
52
+ * frame authenticates there (`worker` by default whenever the shell's and the artifact's hosts
53
+ * differ, D70); `null` when the host offers no external address, so links stay on loopback.
54
+ */
55
+ export type PortAddressingExternalBaseResult = ExternalBase | null;
56
+
57
+ const params: z.ZodType<PortAddressingExternalBaseParams> = z
58
+ .object({
59
+ artifactId: ArtifactId.schema,
60
+ listener: z.enum(["shell", "artifact"]),
61
+ local: z.string().min(1),
62
+ })
63
+ .register(wireRegistry, {
64
+ id: "PortAddressingExternalBaseParams",
65
+ description:
66
+ "Which listener of which artifact needs an external address, and where it listens.",
67
+ });
68
+
69
+ /** One external address a host gives a listener (D158 item 6). */
70
+ export interface ExternalBase {
71
+ /** The origin browsers use for the listener, such as `https://host.example.com`. */
72
+ readonly origin: string;
73
+ /**
74
+ * How the frame authenticates there (D70): `cookie` where the shell and the artifact are one
75
+ * site, `worker` where they are two. Absent: `cookie` for one host name, `worker` for two.
76
+ */
77
+ readonly mode?: "cookie" | "worker";
78
+ }
79
+
80
+ /** The schema of the `ExternalBase` type. */
81
+ export const ExternalBase: z.ZodType<ExternalBase> = z
82
+ .object({ origin: OriginString, mode: z.enum(["cookie", "worker"]).exactOptional() })
83
+ .register(wireRegistry, {
84
+ id: "ExternalBase",
85
+ description: "The origin browsers use for a listener, and how its frame authenticates there.",
86
+ });
87
+
88
+ const result: z.ZodType<PortAddressingExternalBaseResult> = ExternalBase.nullable().register(
89
+ wireRegistry,
90
+ {
91
+ id: "PortAddressingExternalBaseResult",
92
+ description: "The external origin a host gives a listener, or null for loopback.",
93
+ },
94
+ );
95
+
96
+ /**
97
+ * `port/addressing.externalBase`: Mostra asks the host that registered the `addressing` port for
98
+ * the external address of one of its listeners (HO-10, D158 item 6), with 5 seconds to answer,
99
+ * when it mints a link for an artifact and when the shell at such an address opens the artifact's
100
+ * frame. The answer joins the Host allowlist and the links Mostra mints; `null`, or another
101
+ * origin, withdraws the address given before, whose links stop working. A host that fails or
102
+ * answers something the schema refuses leaves links on loopback.
103
+ */
104
+ export const portAddressingExternalBaseMethod: MethodDefinition<
105
+ PortAddressingExternalBaseParams,
106
+ PortAddressingExternalBaseResult
107
+ > = defineMethod({
108
+ method: "port/addressing.externalBase",
109
+ direction: "instance-to-host",
110
+ mutating: false,
111
+ params,
112
+ result,
113
+ });