@mostra/runtime 0.6.1 → 0.7.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.
@@ -6,6 +6,7 @@
6
6
  * theirs, WP-22), and every response leaves with the base headers.
7
7
  */
8
8
  import { createServer, type IncomingMessage, type Server } from "node:http";
9
+ import type { Socket } from "node:net";
9
10
  import type { Duplex } from "node:stream";
10
11
  import { getRequestListener } from "@hono/node-server";
11
12
  import {
@@ -29,6 +30,15 @@ import { refuse } from "./routes.ts";
29
30
  */
30
31
  export const MAX_HEADER_SIZE: number = 1024 * 1024;
31
32
 
33
+ /**
34
+ * How long a listener keeps an idle connection open: longer than browsers keep theirs (Chromium
35
+ * 300 s, Firefox 115 s), so the browser reuses its connections and closes them itself (D157 item
36
+ * 2). Node's default, 5 s, made the gateway close first, and each connection it closed stayed in
37
+ * TIME_WAIT on its side, where Chromium's random local ports on Windows collided with it and
38
+ * failed the connect at once with `ERR_NO_BUFFER_SPACE` (#66).
39
+ */
40
+ export const KEEP_ALIVE_MS: number = 305_000;
41
+
32
42
  /** A listener: its server and its Hono app. */
33
43
  export interface Listener {
34
44
  readonly server: Server;
@@ -114,6 +124,53 @@ function headersTooLarge(socket: Duplex): void {
114
124
  });
115
125
  }
116
126
 
127
+ /**
128
+ * Records every connection and request of a listener in the supervisor's log: its arrival and its
129
+ * end, whether it was answered, with the time between them and the client's port, so a request a
130
+ * browser saw go unanswered shows whether it ever reached the gateway (#66). Only a request's
131
+ * method and path are kept, never its query (a frame ticket travels there) or its headers; a test
132
+ * switch (`MOSTRA_TEST_REQUEST_LOG`), since a long-lived daemon would log every asset it serves.
133
+ */
134
+ function traceRequests(server: Server, log: Log, origin: () => string): void {
135
+ server.on("connection", (socket: Socket) => {
136
+ const opened = Date.now();
137
+ const client = socket.remotePort;
138
+ log.info("gateway.connection", { origin: origin(), client });
139
+ socket.once("close", (hadError: boolean) =>
140
+ log.info("gateway.connection_closed", {
141
+ origin: origin(),
142
+ client,
143
+ ms: Date.now() - opened,
144
+ read: socket.bytesRead,
145
+ written: socket.bytesWritten,
146
+ ...(hadError ? { hadError } : {}),
147
+ }),
148
+ );
149
+ });
150
+ server.prependListener("request", (incoming: IncomingMessage, outgoing) => {
151
+ const started = Date.now();
152
+ const fields = {
153
+ origin: origin(),
154
+ client: incoming.socket.remotePort,
155
+ method: incoming.method,
156
+ path: (incoming.url ?? "").replace(/[?#].*$/s, ""),
157
+ };
158
+ log.info("gateway.request", fields);
159
+ // `finished`: the whole answer was handed to the connection. A stream (events, a long poll)
160
+ // the browser leaves ends unfinished with its headers sent; a request that got nothing ends
161
+ // with neither.
162
+ outgoing.once("close", () =>
163
+ log.info("gateway.request_closed", {
164
+ ...fields,
165
+ status: outgoing.statusCode,
166
+ headersSent: outgoing.headersSent,
167
+ finished: outgoing.writableFinished,
168
+ ms: Date.now() - started,
169
+ }),
170
+ );
171
+ });
172
+ }
173
+
117
174
  /** Creates a listener whose routes `configure` mounts; the server isn't bound yet. */
118
175
  export function createListener(options: {
119
176
  readonly policy: () => RequestPolicy;
@@ -129,6 +186,8 @@ export function createListener(options: {
129
186
  socket: Duplex,
130
187
  head: Buffer,
131
188
  ) => Refusal | undefined;
189
+ /** Logs every connection and request ({@link traceRequests}): tests only. */
190
+ readonly traceRequests?: boolean;
132
191
  }): Listener {
133
192
  const app = new Hono<HttpEnv>();
134
193
  options.configure(app);
@@ -194,6 +253,7 @@ export function createListener(options: {
194
253
  }
195
254
  void listener(incoming, outgoing);
196
255
  });
256
+ if (options.traceRequests) traceRequests(server, options.log, () => options.policy().origin);
197
257
  // A client that sends something Node can't parse gets a 400 and its connection closed.
198
258
  server.on("clientError", (error: NodeJS.ErrnoException, socket) => {
199
259
  if (refusedSockets.has(socket)) return;
@@ -239,6 +299,9 @@ export function createListener(options: {
239
299
  });
240
300
  server.headersTimeout = 30_000;
241
301
  server.requestTimeout = 120_000;
302
+ // An idle connection waits for its next request without these two limits, which count from a
303
+ // request's first byte.
304
+ server.keepAliveTimeout = KEEP_ALIVE_MS;
242
305
 
243
306
  return {
244
307
  server,
@@ -7,7 +7,9 @@
7
7
  * 1. the `Origin` and content type its intent needs (`checkRequest`; the envelope was checked
8
8
  * before routing);
9
9
  * 2. the rate limit, on token paths;
10
- * 3. the session, bound to this origin, with a live token (401, 410);
10
+ * 3. the session, bound to this origin, with a live token (401, 410): its cookie in cookie mode,
11
+ * its frame header in worker mode (D70), or a single-use stream ticket on stream routes
12
+ * (D158 item 5);
11
13
  * 4. the session's CSRF token, on mutations;
12
14
  * 5. the scope.
13
15
  *
@@ -17,6 +19,7 @@
17
19
  import {
18
20
  type CapabilityScope,
19
21
  checkRequest,
22
+ FRAME_SESSION_HEADER,
20
23
  type Refusal,
21
24
  type RequestIntent,
22
25
  type RequestPolicy,
@@ -50,6 +53,11 @@ export interface RouteSpec {
50
53
  * action scope; the handler checks the exact function (D96).
51
54
  */
52
55
  readonly scope?: (params: Readonly<Record<string, string>>) => CapabilityScope | "any-action";
56
+ /**
57
+ * An event stream (SSE): refused on a face streams don't pass, and in worker mode without a
58
+ * ticket, so the page long-polls instead (D158 item 5).
59
+ */
60
+ readonly sse?: true;
53
61
  /** Serves the request. Absent: declared for a later package, answered with 501. */
54
62
  readonly handler?: (context: RouteContext) => Response | Promise<Response>;
55
63
  }
@@ -64,6 +72,8 @@ export interface RouteContext {
64
72
  readonly session?: ResolvedSession;
65
73
  /** Whether the client is navigating (answer with HTML rather than JSON). */
66
74
  readonly document: boolean;
75
+ /** The address of the connection's peer: on a face, the tunnel's own process (D158 item 2). */
76
+ readonly remote: string | undefined;
67
77
  }
68
78
 
69
79
  /** What a listener contributes to every route's checks. */
@@ -78,6 +88,13 @@ export interface ListenerChecks {
78
88
  readonly frameAncestors: () => string;
79
89
  /** The artifact a request is for: fixed on an artifact's listener, from the path on the shell. */
80
90
  readonly artifactOf: (params: Readonly<Record<string, string>>) => string | undefined;
91
+ /**
92
+ * How this listener's sessions authenticate (D70): `cookie` (the default), or `worker`, where a
93
+ * frame's service worker sends the session's secret as `X-Mostra-Frame`.
94
+ */
95
+ readonly mode?: () => "cookie" | "worker";
96
+ /** Whether event streams pass to this listener's browsers; `false` behind a quick tunnel. */
97
+ readonly streams?: () => boolean;
81
98
  }
82
99
 
83
100
  /** Logs a refusal without any of the request's capability material, and answers it. */
@@ -148,14 +165,41 @@ export function mount(
148
165
  const limited = checks.capabilities.limited(artifactId);
149
166
  if (limited) return refuse(checks, limited, meta);
150
167
  }
151
- // 3. The session.
168
+ // 3. The session: a stream ticket on a stream route, else the cookie, or the frame header
169
+ // in worker mode. An event stream only passes where streams do, and in worker mode only
170
+ // with a ticket: a stream through the service worker stalls in Firefox (VERIFIED_FACTS).
171
+ const mode = checks.mode?.() ?? "cookie";
172
+ const ticket = route.intent === "stream" ? url.searchParams.get("ticket") : null;
173
+ if (route.sse && (checks.streams?.() === false || (mode === "worker" && ticket === null))) {
174
+ return refuse(
175
+ checks,
176
+ refusal(
177
+ "MOSTRA_HYGIENE_NOT_SERVED",
178
+ checks.streams?.() === false
179
+ ? "Event streams don't pass this address; long-poll instead (events/poll)."
180
+ : "A worker-mode frame opens its event stream with a ticket; long-poll instead.",
181
+ 503,
182
+ ),
183
+ meta,
184
+ );
185
+ }
152
186
  let session: ResolvedSession | undefined;
153
187
  if (route.auth === "session" && artifactId !== undefined) {
154
- const resolved = checks.capabilities.session(
155
- cookieValues(request.headers.get("cookie"), checks.cookieName()),
156
- policy.origin,
157
- artifactId,
158
- );
188
+ const resolved =
189
+ ticket !== null
190
+ ? checks.capabilities.redeemStreamTicket(ticket, policy.origin, artifactId, "stream")
191
+ : mode === "worker"
192
+ ? checks.capabilities.session(
193
+ [request.headers.get(FRAME_SESSION_HEADER) ?? ""],
194
+ policy.origin,
195
+ artifactId,
196
+ "worker",
197
+ )
198
+ : checks.capabilities.session(
199
+ cookieValues(request.headers.get("cookie"), checks.cookieName()),
200
+ policy.origin,
201
+ artifactId,
202
+ );
159
203
  if (isRefusal(resolved)) return refuse(checks, resolved, meta);
160
204
  session = resolved;
161
205
  // 4. The CSRF token of this session.
@@ -189,6 +233,7 @@ export function mount(
189
233
  artifactId,
190
234
  ...(session ? { session } : {}),
191
235
  document,
236
+ remote: incoming.socket.remoteAddress,
192
237
  });
193
238
  };
194
239
  if (route.method === "GET") app.get(route.path, handle);
@@ -0,0 +1,204 @@
1
+ /**
2
+ * Worker-mode frame sessions (D70, D158 item 5): where the shell and the artifact are two sites,
3
+ * no cookie reaches the artifact's frame (VERIFIED_FACTS, cross-site frames). The frame enters
4
+ * through a bootstrap page instead: it exchanges the shell's single-use ticket for a frame
5
+ * session, installs Mostra's service worker at `/`, and enters the version, whose every
6
+ * same-origin request then carries the session in a header. Event streams, polls and WebSockets
7
+ * bypass the worker with single-use tickets, since Firefox stalls on endless responses a worker
8
+ * passes on.
9
+ *
10
+ * This module holds the two documents the browser runs: the bootstrap page and the worker. Both
11
+ * are plain scripts with no imports, served by the gateway from the artifact's origin.
12
+ */
13
+ import { FRAME_SESSION_HEADER } from "@mostra/protocol";
14
+
15
+ /** Where the service worker is served; its registration's scope is `/`. */
16
+ export const SERVICE_WORKER_PATH = "/_mostra/sw.js";
17
+
18
+ /** The IndexedDB the frame session's secret is kept in, per artifact origin and top-level site. */
19
+ const DB = "mostra-frame";
20
+
21
+ /**
22
+ * The service worker (D70): it adds the frame session's header to every same-origin request but
23
+ * its own script, the bootstrap's, and ticketed ones (`?ticket=`: streams, polls and sockets),
24
+ * and keeps the secret in IndexedDB, since a browser stops idle workers and their memory goes.
25
+ * A request a header can't be added to as made (a `no-cors` script or image, a navigation) is
26
+ * sent again as a same-origin request, which carries it.
27
+ */
28
+ export const SERVICE_WORKER_SOURCE: string = `// Mostra's frame-session worker (D70). It signs this origin's requests for the artifact's frame.
29
+ "use strict";
30
+ const HEADER = ${JSON.stringify(FRAME_SESSION_HEADER)};
31
+ const DB = ${JSON.stringify(DB)};
32
+ const STORE = "session";
33
+ let secret;
34
+ function store(mode, act) {
35
+ return new Promise((resolve, reject) => {
36
+ const open = indexedDB.open(DB, 1);
37
+ open.onupgradeneeded = () => open.result.createObjectStore(STORE);
38
+ open.onerror = () => reject(open.error);
39
+ open.onsuccess = () => {
40
+ const db = open.result;
41
+ const tx = db.transaction(STORE, mode);
42
+ const request = act(tx.objectStore(STORE));
43
+ tx.oncomplete = () => { db.close(); resolve(request.result); };
44
+ tx.onerror = tx.onabort = () => { db.close(); reject(tx.error); };
45
+ };
46
+ });
47
+ }
48
+ async function current() {
49
+ if (secret === undefined) {
50
+ try { secret = await store("readonly", (s) => s.get("secret")); } catch { secret = undefined; }
51
+ }
52
+ return secret;
53
+ }
54
+ self.addEventListener("install", () => { self.skipWaiting(); });
55
+ self.addEventListener("activate", (event) => { event.waitUntil(self.clients.claim()); });
56
+ self.addEventListener("message", (event) => {
57
+ const data = event.data;
58
+ if (!data || data.type !== "mostra/frame-session" || typeof data.secret !== "string") return;
59
+ secret = data.secret;
60
+ const port = event.ports[0];
61
+ event.waitUntil(
62
+ store("readwrite", (s) => s.put(data.secret, "secret")).then(
63
+ () => port && port.postMessage({ ok: true }),
64
+ (error) => port && port.postMessage({ ok: false, message: String(error) }),
65
+ ),
66
+ );
67
+ });
68
+ self.addEventListener("fetch", (event) => {
69
+ const request = event.request;
70
+ const url = new URL(request.url);
71
+ if (url.origin !== self.location.origin) return;
72
+ if (url.pathname === ${JSON.stringify(SERVICE_WORKER_PATH)} || url.pathname === "/_mostra/enter") return;
73
+ if (url.searchParams.has("ticket")) return;
74
+ event.respondWith(signed(request));
75
+ });
76
+ async function signed(request) {
77
+ const value = await current();
78
+ if (!value) return fetch(request);
79
+ const headers = new Headers(request.headers);
80
+ headers.set(HEADER, value);
81
+ const navigate = request.mode === "navigate";
82
+ // Sent on, a navigation is an ordinary request: the gateway learns it was one from this header.
83
+ if (navigate) headers.set("x-mostra-navigation", "1");
84
+ const init = {
85
+ method: request.method,
86
+ headers,
87
+ mode: navigate || request.mode === "no-cors" ? "same-origin" : request.mode,
88
+ credentials: request.credentials,
89
+ cache: request.cache === "only-if-cached" ? "default" : request.cache,
90
+ redirect: navigate ? "manual" : request.redirect,
91
+ referrerPolicy: request.referrerPolicy,
92
+ integrity: request.integrity,
93
+ keepalive: request.keepalive,
94
+ signal: request.signal,
95
+ };
96
+ if (request.method !== "GET" && request.method !== "HEAD") init.body = await request.arrayBuffer();
97
+ return fetch(new Request(request.url, init));
98
+ }
99
+ `;
100
+
101
+ /**
102
+ * The bootstrap page at `/_mostra/enter#t=<ticket>` (D70): it takes the ticket from the fragment
103
+ * (so no server, log or `Referer` sees it), exchanges it at `POST /_mostra/enter` (sending the
104
+ * session it kept, so a frame that re-enters keeps its session and switches version), installs
105
+ * the worker at `/`, hands it the secret, tells the shell (`mostra/frameSession.entered`) and
106
+ * enters the version at `/`. Whatever stops it is reported to the shell as
107
+ * `mostra/frameSession.failed` with `MOSTRA_HYGIENE_FRAME_SESSION`.
108
+ */
109
+ export const BOOTSTRAP_PAGE: string = `<!doctype html>
110
+ <html lang="en">
111
+ <head>
112
+ <meta charset="utf-8">
113
+ <meta name="referrer" content="no-referrer">
114
+ <meta name="viewport" content="width=device-width, initial-scale=1">
115
+ <title>Mostra</title>
116
+ <style>body{font-family:system-ui,sans-serif;margin:0;min-height:100vh;display:flex;justify-content:center;align-items:center;padding:2rem;text-align:center;color-scheme:light dark;opacity:.8}</style>
117
+ </head>
118
+ <body>
119
+ <script>
120
+ (async () => {
121
+ "use strict";
122
+ const HEADER = ${JSON.stringify(FRAME_SESSION_HEADER)};
123
+ let shell = "*";
124
+ const fail = (reason, message) => {
125
+ document.body.textContent = message;
126
+ parent.postMessage(
127
+ { jsonrpc: "2.0", method: "mostra/frameSession.failed",
128
+ params: { code: "MOSTRA_HYGIENE_FRAME_SESSION", reason, message } },
129
+ shell,
130
+ );
131
+ };
132
+ const kept = () => new Promise((resolve) => {
133
+ try {
134
+ const open = indexedDB.open(${JSON.stringify(DB)}, 1);
135
+ open.onupgradeneeded = () => open.result.createObjectStore("session");
136
+ open.onerror = () => resolve(undefined);
137
+ open.onsuccess = () => {
138
+ const db = open.result;
139
+ try {
140
+ const read = db.transaction("session", "readonly").objectStore("session").get("secret");
141
+ read.onsuccess = () => { db.close(); resolve(typeof read.result === "string" ? read.result : undefined); };
142
+ read.onerror = () => { db.close(); resolve(undefined); };
143
+ } catch { db.close(); resolve(undefined); }
144
+ };
145
+ } catch { resolve(undefined); }
146
+ });
147
+ const ticket = new URLSearchParams(location.hash.slice(1)).get("t");
148
+ history.replaceState(null, "", location.pathname);
149
+ if (!ticket) return fail("refused", "This frame was opened without a ticket.");
150
+ if (!("serviceWorker" in navigator) || typeof indexedDB === "undefined") {
151
+ return fail("unsupported", "This browser offers the artifact's frame no service worker here, which this link needs.");
152
+ }
153
+ let answer;
154
+ try {
155
+ const previous = await kept();
156
+ const response = await fetch("/_mostra/enter", {
157
+ method: "POST",
158
+ credentials: "omit",
159
+ cache: "no-store",
160
+ headers: { "content-type": "application/json", ...(previous ? { [HEADER]: previous } : {}) },
161
+ body: JSON.stringify({ ticket }),
162
+ });
163
+ answer = await response.json().catch(() => ({}));
164
+ if (!response.ok) return fail("refused", answer.message || "The frame's entry was refused.");
165
+ } catch (error) {
166
+ return fail("refused", "The frame couldn't reach Mostra: " + error);
167
+ }
168
+ shell = answer.shellOrigin;
169
+ try {
170
+ const found = await navigator.serviceWorker.getRegistration("/");
171
+ const script = found && (found.active || found.waiting || found.installing);
172
+ if (script && new URL(script.scriptURL).pathname !== ${JSON.stringify(SERVICE_WORKER_PATH)}) {
173
+ console.warn("Mostra replaced another service worker at / on this origin: a worker-mode frame needs its own there (MOSTRA_HYGIENE_FRAME_SESSION).");
174
+ }
175
+ const registration = await navigator.serviceWorker.register(${JSON.stringify(SERVICE_WORKER_PATH)}, { scope: "/", updateViaCache: "none" });
176
+ const worker = registration.installing || registration.waiting || registration.active;
177
+ if (!worker) throw new Error("no worker");
178
+ if (worker.state !== "activated") {
179
+ await new Promise((resolve, reject) => {
180
+ const timer = setTimeout(() => reject(new Error("the worker didn't activate in 20 s")), 20000);
181
+ worker.addEventListener("statechange", () => {
182
+ if (worker.state === "activated") { clearTimeout(timer); resolve(); }
183
+ if (worker.state === "redundant") { clearTimeout(timer); reject(new Error("the worker was replaced")); }
184
+ });
185
+ });
186
+ }
187
+ const stored = await new Promise((resolve) => {
188
+ const channel = new MessageChannel();
189
+ const timer = setTimeout(() => resolve({ ok: false, message: "no answer" }), 10000);
190
+ channel.port1.onmessage = (event) => { clearTimeout(timer); resolve(event.data); };
191
+ worker.postMessage({ type: "mostra/frame-session", secret: answer.session }, [channel.port2]);
192
+ });
193
+ if (!stored || !stored.ok) throw new Error(stored && stored.message);
194
+ } catch (error) {
195
+ return fail("blocked", "This browser didn't let the artifact's frame install the service worker this link needs (" + error + ").");
196
+ }
197
+ // The shell waits for the page from here: this page's own load wasn't the page's.
198
+ parent.postMessage({ jsonrpc: "2.0", method: "mostra/frameSession.entered", params: {} }, shell);
199
+ location.replace("/");
200
+ })();
201
+ </script>
202
+ </body>
203
+ </html>
204
+ `;
@@ -24,6 +24,7 @@ import {
24
24
  type JsonRpcParams,
25
25
  type MostraInitializeResult,
26
26
  type PortTrustedControlsActivatedParams,
27
+ portAddressingExternalBaseMethod,
27
28
  portIdentityResolveMethod,
28
29
  portSecretsGetMethod,
29
30
  portTrustedControlsActivatedMethod,
@@ -100,6 +101,7 @@ import {
100
101
  import { openRegistry } from "../registry/index.ts";
101
102
  import { openSecrets, secretMethods } from "../secrets/index.ts";
102
103
  import { hasLoginService, type IdleWatch, watchIdle } from "../service/index.ts";
104
+ import { createShares, type Shares, shareCacheDir } from "../share/index.ts";
103
105
  import {
104
106
  collectVerifyCaches,
105
107
  createRunnerClient,
@@ -216,8 +218,12 @@ export const SUPPORTED_PORTS: readonly string[] = [
216
218
  "drafts",
217
219
  "trustedControls",
218
220
  "secrets",
221
+ "addressing",
219
222
  ];
220
223
 
224
+ /** How long a host's `addressing` port has to answer: a page or a minted link waits (D158). */
225
+ const ADDRESSING_TIMEOUT_MS = 5_000;
226
+
221
227
  /**
222
228
  * Starts an instance for a home (RT-06): the platform gate, then the home's lock, migrations,
223
229
  * reaping, the socket and `instance.json`. A daemon starter that finds the home owned attaches
@@ -423,6 +429,8 @@ async function assemble(home: OwnedHome, options: StartInstanceOptions): Promise
423
429
  // Tests move the gateway's clock to check link lifetimes (LL-05, HY-03).
424
430
  now: () => Date.now() + clockOffset,
425
431
  shellOrigin: () => gateway.shellOrigin(),
432
+ // Launch tickets only for links whose shell address the gateway serves now (D158).
433
+ servesShell: (origin) => gateway.servesShell(origin),
426
434
  });
427
435
  // The interaction core (WP-06): drafts, state, submissions, the outbox, events and waits. Its
428
436
  // host connections are the protocol server's, built below.
@@ -611,9 +619,14 @@ async function assemble(home: OwnedHome, options: StartInstanceOptions): Promise
611
619
  const shellDir = locateShell(environment);
612
620
  if (shellDir === undefined)
613
621
  log.warn("gateway.shell_missing", { code: "MOSTRA_ENV_SHELL_MISSING" });
622
+ const traceRequests = Boolean(environment["MOSTRA_TEST_REQUEST_LOG"]);
623
+ if (traceRequests) log.warn("instance.test_request_log", {});
624
+ // Shares run the local fakes instead of Tailscale and cloudflared (tests and the kit only).
625
+ if (environment["MOSTRA_TEST_TUNNELS"]) log.warn("instance.test_tunnels", {});
614
626
  const gateway: Gateway = createGateway({
615
627
  ledger: home.ledger,
616
628
  log,
629
+ ...(traceRequests ? { traceRequests } : {}),
617
630
  addressing,
618
631
  capabilities,
619
632
  artifacts: {
@@ -665,6 +678,40 @@ async function assemble(home: OwnedHome, options: StartInstanceOptions): Promise
665
678
  IDENTITY_TIMEOUT_MS,
666
679
  ),
667
680
  }),
681
+ // A host's external addresses for an artifact's links and frame (HO-10, D158 item 6).
682
+ externalBase: {
683
+ registered: () => server.registrants("addressing").length > 0,
684
+ ask: async (input) => {
685
+ const registrant = server.registrants("addressing").at(-1);
686
+ if (!registrant) return { kind: "away" };
687
+ try {
688
+ const answer = await server.callSession(
689
+ registrant.session,
690
+ portAddressingExternalBaseMethod.method,
691
+ input as unknown as JsonRpcParams,
692
+ ADDRESSING_TIMEOUT_MS,
693
+ );
694
+ const parsed = portAddressingExternalBaseMethod.result.safeParse(answer);
695
+ if (!parsed.success) {
696
+ log.warn("gateway.addressing_invalid", {
697
+ owner: registrant.owner,
698
+ artifactId: input.artifactId,
699
+ });
700
+ return { kind: "failed" };
701
+ }
702
+ return parsed.data === null
703
+ ? { kind: "none" }
704
+ : { kind: "base", base: parsed.data, owner: registrant.owner };
705
+ } catch (error) {
706
+ log.warn("gateway.addressing_failed", {
707
+ owner: registrant.owner,
708
+ artifactId: input.artifactId,
709
+ error: (error as Error).message,
710
+ });
711
+ return { kind: "failed" };
712
+ }
713
+ },
714
+ },
668
715
  activated: (event) => {
669
716
  // Best effort and never retried, like draft mirrors (D105, D108): the change is durable.
670
717
  for (const registrant of server.registrants("trustedControls")) {
@@ -691,6 +738,26 @@ async function assemble(home: OwnedHome, options: StartInstanceOptions): Promise
691
738
  }
692
739
  },
693
740
  });
741
+ // Shares (WP-13, D158): tunnels to the gateway's faces, each with a link of its own.
742
+ const shares: Shares = createShares({
743
+ ledger: home.ledger,
744
+ log,
745
+ gateway,
746
+ capabilities,
747
+ interaction,
748
+ artifacts: { get: (ref) => registry.get(canonicalRef(ref)) },
749
+ processes: manager,
750
+ environment,
751
+ toolEnvironment: artifactEnvironment(environment),
752
+ cacheDir: shareCacheDir(home.path),
753
+ now: () => Date.now() + clockOffset,
754
+ ...(environment["MOSTRA_TEST_SHARE_PROBE_MS"] !== undefined
755
+ ? { probeMs: Number(environment["MOSTRA_TEST_SHARE_PROBE_MS"]) }
756
+ : {}),
757
+ ...(environment["MOSTRA_TEST_SHARE_SWEEP_MS"] !== undefined
758
+ ? { sweepMs: Number(environment["MOSTRA_TEST_SHARE_SWEEP_MS"]) }
759
+ : {}),
760
+ });
694
761
  let gatewayStarted = false;
695
762
  let idle: IdleWatch | undefined;
696
763
  const info: InstanceInfo = {
@@ -782,6 +849,7 @@ async function assemble(home: OwnedHome, options: StartInstanceOptions): Promise
782
849
  }),
783
850
  ...dev.methods(),
784
851
  ...gateway.methods(),
852
+ ...shares.methods(),
785
853
  ...interaction.methods(),
786
854
  ...secretMethods(secrets, (ref) => registry.get(canonicalRef(ref)).id),
787
855
  ...gcMethods(
@@ -816,8 +884,10 @@ async function assemble(home: OwnedHome, options: StartInstanceOptions): Promise
816
884
  artifactId,
817
885
  origin,
818
886
  })),
887
+ faces: [...gateway.faces()],
819
888
  }
820
889
  : undefined,
890
+ shares: () => shares.active(),
821
891
  deliveries: () => interaction.deliveries(),
822
892
  workers: () => pool.status(),
823
893
  idleExitAt: () => idle?.exitAt(),
@@ -853,6 +923,7 @@ async function assemble(home: OwnedHome, options: StartInstanceOptions): Promise
853
923
  // the answers already sent (the `mostra/shutdown` reply among them) before it exits.
854
924
  await server.close();
855
925
  await dev.stopAll();
926
+ await shares.close();
856
927
  await gateway.close();
857
928
  await pool.stopAll();
858
929
  await runner?.close();
@@ -902,6 +973,8 @@ async function assemble(home: OwnedHome, options: StartInstanceOptions): Promise
902
973
  interaction.start();
903
974
  // Producers that `always` run, and those hosts subscribe to, start now (LL-04).
904
975
  live.start();
976
+ // Tailnet and Funnel shares come back; what can't continue ends, with its reason (D158).
977
+ void shares.recover().catch((error: unknown) => log.error("share.recover_failed", { error }));
905
978
  home.publish(options.mode, server.socketPath ?? home.socketPath);
906
979
  // A host-spawned instance marks its home as a host's (D140 item 4).
907
980
  if (options.mode === "host" && markHostConfigured(home.path, "mostra-runtime host"))
@@ -932,6 +1005,8 @@ async function assemble(home: OwnedHome, options: StartInstanceOptions): Promise
932
1005
  producers: live.activity(),
933
1006
  subscriptions: interaction.subscriptionCount(),
934
1007
  devSessions: dev.count(),
1008
+ // An active share keeps a daemon from its idle exit (D133, WP-13).
1009
+ shares: shares.count(),
935
1010
  // A home with a login service is always-on, whoever started its daemon (D133).
936
1011
  loginService: hasLoginService(home.path, environment) ? 1 : 0,
937
1012
  }),
@@ -91,7 +91,9 @@ import {
91
91
  viewControls,
92
92
  viewer,
93
93
  viewerForHost,
94
+ viewerForLink,
94
95
  viewerForSpec,
96
+ viewerForTailnet,
95
97
  viewFor,
96
98
  } from "./viewers.ts";
97
99
  import { waitFor } from "./wait.ts";
@@ -157,6 +159,10 @@ export interface Interaction {
157
159
  viewerForSpec(db: LedgerDb, spec: ViewerSpec): string;
158
160
  /** The viewer a host's identity port named (D143 item 2), in a transaction of its own. */
159
161
  viewerForHost(spec: ViewerSpec): string;
162
+ /** A tailnet person by login (D158 item 2), in a transaction of its own. */
163
+ viewerForTailnet(spec: ViewerSpec): string;
164
+ /** A link's own viewer, for a tunnel visitor nobody named (D158 item 2). */
165
+ viewerForLink(tokenId: string, name: string): string;
160
166
  /** Records a frame load of a version (D104), with the controls in force (D108); returns its ID. */
161
167
  openView(input: {
162
168
  readonly artifactId: string;
@@ -504,6 +510,8 @@ export function createInteraction(options: InteractionOptions): Interaction {
504
510
  viewer: (viewerId) => ledger.read((db) => viewer(db, viewerId)),
505
511
  viewerForSpec,
506
512
  viewerForHost: (spec) => ledger.write((db) => viewerForHost(db, spec)),
513
+ viewerForTailnet: (spec) => ledger.write((db) => viewerForTailnet(db, spec)),
514
+ viewerForLink: (tokenId, name) => ledger.write((db) => viewerForLink(db, tokenId, name)),
507
515
  openView(input) {
508
516
  return ledger.write((db) => openView(db, input));
509
517
  },
@@ -54,7 +54,9 @@ function viewerOf(row: ViewerRow): Viewer {
54
54
  id: row.id,
55
55
  kind: row.kind,
56
56
  ...(row.name !== null ? { name: row.name } : {}),
57
- ...(row.kind === "token" || row.kind === "host" ? { ref: row.external_ref } : {}),
57
+ ...(row.kind === "token" || row.kind === "host" || row.kind === "tailnet"
58
+ ? { ref: row.external_ref }
59
+ : {}),
58
60
  };
59
61
  }
60
62
 
@@ -91,7 +93,24 @@ export function viewerForHost(db: LedgerDb, spec: ViewerSpec): string {
91
93
  return viewerByRef(db, "host", spec);
92
94
  }
93
95
 
94
- function viewerByRef(db: LedgerDb, kind: "token" | "host", spec: ViewerSpec): string {
96
+ /**
97
+ * A tailnet person (D158 item 2): one viewer of kind `tailnet` per Tailscale login, named by the
98
+ * display name Tailscale Serve sends.
99
+ */
100
+ export function viewerForTailnet(db: LedgerDb, spec: ViewerSpec): string {
101
+ return viewerByRef(db, "tailnet", spec);
102
+ }
103
+
104
+ /**
105
+ * A link's own viewer (D158 item 2): whoever opens a link over a tunnel without being named (a
106
+ * public share, a tagged tailnet device) acts as one viewer per link, never as the home's local
107
+ * user, so a visitor's answers never mix into the owner's draft.
108
+ */
109
+ export function viewerForLink(db: LedgerDb, tokenId: string, name: string): string {
110
+ return viewerByRef(db, "token", { ref: `link:${tokenId}`, name });
111
+ }
112
+
113
+ function viewerByRef(db: LedgerDb, kind: "token" | "host" | "tailnet", spec: ViewerSpec): string {
95
114
  const found = db.get<ViewerRow>(
96
115
  "SELECT * FROM viewer WHERE kind = ? AND external_ref = ?",
97
116
  kind,