@mostra/protocol 0.1.0 → 0.2.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.
@@ -4,6 +4,381 @@
4
4
  "x-mostra-revisions": {
5
5
  "host-protocol": "2026-10-10"
6
6
  },
7
+ "x-mostra-methods": {
8
+ "artifact/create": {
9
+ "direction": "client-to-instance",
10
+ "mutating": true,
11
+ "params": {
12
+ "$ref": "#/$defs/ArtifactCreateParams"
13
+ },
14
+ "result": {
15
+ "$ref": "#/$defs/ArtifactCreateResult"
16
+ }
17
+ },
18
+ "artifact/get": {
19
+ "direction": "client-to-instance",
20
+ "mutating": false,
21
+ "params": {
22
+ "$ref": "#/$defs/ArtifactGetParams"
23
+ },
24
+ "result": {
25
+ "$ref": "#/$defs/ArtifactDetail"
26
+ }
27
+ },
28
+ "artifact/list": {
29
+ "direction": "client-to-instance",
30
+ "mutating": false,
31
+ "params": {
32
+ "$ref": "#/$defs/ArtifactListParams"
33
+ },
34
+ "result": {
35
+ "$ref": "#/$defs/ArtifactListResult"
36
+ }
37
+ },
38
+ "artifact/publish": {
39
+ "direction": "client-to-instance",
40
+ "mutating": true,
41
+ "params": {
42
+ "$ref": "#/$defs/ArtifactPublishParams"
43
+ },
44
+ "result": {
45
+ "$ref": "#/$defs/PublishReceipt"
46
+ }
47
+ },
48
+ "artifact/verify": {
49
+ "direction": "client-to-instance",
50
+ "mutating": false,
51
+ "params": {
52
+ "$ref": "#/$defs/ArtifactVerifyParams"
53
+ },
54
+ "result": {
55
+ "$ref": "#/$defs/VerifyVerdict"
56
+ }
57
+ },
58
+ "deps/add": {
59
+ "direction": "client-to-instance",
60
+ "mutating": true,
61
+ "params": {
62
+ "$ref": "#/$defs/DepsAddParams"
63
+ },
64
+ "result": {
65
+ "$ref": "#/$defs/DepsAddResult"
66
+ }
67
+ },
68
+ "dev/start": {
69
+ "direction": "client-to-instance",
70
+ "mutating": true,
71
+ "params": {
72
+ "$ref": "#/$defs/DevStartParams"
73
+ },
74
+ "result": {
75
+ "$ref": "#/$defs/DevStartResult"
76
+ }
77
+ },
78
+ "dev/stop": {
79
+ "direction": "client-to-instance",
80
+ "mutating": true,
81
+ "params": {
82
+ "$ref": "#/$defs/DevStopParams"
83
+ },
84
+ "result": {
85
+ "$ref": "#/$defs/DevStopResult"
86
+ }
87
+ },
88
+ "events/ack": {
89
+ "direction": "client-to-instance",
90
+ "mutating": true,
91
+ "params": {
92
+ "$ref": "#/$defs/EventsAckParams"
93
+ },
94
+ "result": {
95
+ "$ref": "#/$defs/EventsAckResult"
96
+ }
97
+ },
98
+ "events/read": {
99
+ "direction": "client-to-instance",
100
+ "mutating": false,
101
+ "params": {
102
+ "$ref": "#/$defs/EventsReadParams"
103
+ },
104
+ "result": {
105
+ "$ref": "#/$defs/EventsReadResult"
106
+ }
107
+ },
108
+ "events/subscribe": {
109
+ "direction": "client-to-instance",
110
+ "mutating": false,
111
+ "params": {
112
+ "$ref": "#/$defs/EventsSubscribeParams"
113
+ },
114
+ "result": {
115
+ "$ref": "#/$defs/EventsSubscribeResult"
116
+ }
117
+ },
118
+ "events/unsubscribe": {
119
+ "direction": "client-to-instance",
120
+ "mutating": false,
121
+ "params": {
122
+ "$ref": "#/$defs/EventsUnsubscribeParams"
123
+ },
124
+ "result": {
125
+ "$ref": "#/$defs/EventsUnsubscribeResult"
126
+ }
127
+ },
128
+ "gc/run": {
129
+ "direction": "client-to-instance",
130
+ "mutating": true,
131
+ "params": {
132
+ "$ref": "#/$defs/GcRunParams"
133
+ },
134
+ "result": {
135
+ "$ref": "#/$defs/GcRunResult"
136
+ }
137
+ },
138
+ "instance/check": {
139
+ "direction": "client-to-instance",
140
+ "mutating": false,
141
+ "params": {
142
+ "$ref": "#/$defs/InstanceCheckParams"
143
+ },
144
+ "result": {
145
+ "$ref": "#/$defs/InstanceCheckResult"
146
+ }
147
+ },
148
+ "instance/status": {
149
+ "direction": "client-to-instance",
150
+ "mutating": false,
151
+ "params": {
152
+ "$ref": "#/$defs/InstanceStatusParams"
153
+ },
154
+ "result": {
155
+ "$ref": "#/$defs/InstanceStatusResult"
156
+ }
157
+ },
158
+ "live/push": {
159
+ "direction": "client-to-instance",
160
+ "mutating": true,
161
+ "params": {
162
+ "$ref": "#/$defs/LivePushParams"
163
+ },
164
+ "result": {
165
+ "$ref": "#/$defs/LivePushResult"
166
+ }
167
+ },
168
+ "mostra/initialize": {
169
+ "direction": "client-to-instance",
170
+ "mutating": false,
171
+ "params": {
172
+ "$ref": "#/$defs/MostraInitializeParams"
173
+ },
174
+ "result": {
175
+ "$ref": "#/$defs/MostraInitializeResult"
176
+ }
177
+ },
178
+ "mostra/shutdown": {
179
+ "direction": "client-to-instance",
180
+ "mutating": false,
181
+ "params": {
182
+ "$ref": "#/$defs/MostraShutdownParams"
183
+ },
184
+ "result": {
185
+ "$ref": "#/$defs/MostraShutdownResult"
186
+ }
187
+ },
188
+ "port/drafts.mirror": {
189
+ "direction": "instance-to-host",
190
+ "mutating": false,
191
+ "params": {
192
+ "$ref": "#/$defs/DraftMirror"
193
+ },
194
+ "result": {}
195
+ },
196
+ "port/identity.resolve": {
197
+ "direction": "instance-to-host",
198
+ "mutating": false,
199
+ "params": {
200
+ "$ref": "#/$defs/PortIdentityResolveParams"
201
+ },
202
+ "result": {
203
+ "$ref": "#/$defs/PortIdentityResolveResult"
204
+ }
205
+ },
206
+ "port/secrets.get": {
207
+ "direction": "instance-to-host",
208
+ "mutating": false,
209
+ "params": {
210
+ "$ref": "#/$defs/PortSecretsGetParams"
211
+ },
212
+ "result": {
213
+ "$ref": "#/$defs/PortSecretsGetResult"
214
+ }
215
+ },
216
+ "port/submissions.deliver": {
217
+ "direction": "instance-to-host",
218
+ "mutating": false,
219
+ "params": {
220
+ "$ref": "#/$defs/SubmissionEnvelope"
221
+ },
222
+ "result": {
223
+ "$ref": "#/$defs/PortSubmissionsDeliverResult"
224
+ }
225
+ },
226
+ "port/trustedControls.activated": {
227
+ "direction": "instance-to-host",
228
+ "mutating": false,
229
+ "params": {
230
+ "$ref": "#/$defs/PortTrustedControlsActivatedParams"
231
+ },
232
+ "result": {}
233
+ },
234
+ "port/trustedControls.policy": {
235
+ "direction": "instance-to-host",
236
+ "mutating": false,
237
+ "params": {
238
+ "$ref": "#/$defs/PortTrustedControlsPolicyParams"
239
+ },
240
+ "result": {
241
+ "$ref": "#/$defs/ControlsPolicy"
242
+ }
243
+ },
244
+ "results/get": {
245
+ "direction": "client-to-instance",
246
+ "mutating": false,
247
+ "params": {
248
+ "$ref": "#/$defs/ResultsGetParams"
249
+ },
250
+ "result": {
251
+ "$ref": "#/$defs/ResultsGetResult"
252
+ }
253
+ },
254
+ "secret/delete": {
255
+ "direction": "client-to-instance",
256
+ "mutating": false,
257
+ "params": {
258
+ "$ref": "#/$defs/SecretDeleteParams"
259
+ },
260
+ "result": {
261
+ "$ref": "#/$defs/SecretDeleteResult"
262
+ }
263
+ },
264
+ "secret/list": {
265
+ "direction": "client-to-instance",
266
+ "mutating": false,
267
+ "params": {
268
+ "$ref": "#/$defs/SecretListParams"
269
+ },
270
+ "result": {
271
+ "$ref": "#/$defs/SecretListResult"
272
+ }
273
+ },
274
+ "secret/set": {
275
+ "direction": "client-to-instance",
276
+ "mutating": false,
277
+ "params": {
278
+ "$ref": "#/$defs/SecretSetParams"
279
+ },
280
+ "result": {
281
+ "$ref": "#/$defs/SecretEntry"
282
+ }
283
+ },
284
+ "state/get": {
285
+ "direction": "client-to-instance",
286
+ "mutating": false,
287
+ "params": {
288
+ "$ref": "#/$defs/StateGetParams"
289
+ },
290
+ "result": {
291
+ "$ref": "#/$defs/StateGetResult"
292
+ }
293
+ },
294
+ "state/patch": {
295
+ "direction": "client-to-instance",
296
+ "mutating": true,
297
+ "params": {
298
+ "$ref": "#/$defs/StatePatchParams"
299
+ },
300
+ "result": {
301
+ "$ref": "#/$defs/MutationResult"
302
+ }
303
+ },
304
+ "view/default": {
305
+ "direction": "client-to-instance",
306
+ "mutating": true,
307
+ "params": {
308
+ "$ref": "#/$defs/ViewDefaultParams"
309
+ },
310
+ "result": {
311
+ "$ref": "#/$defs/CapabilityLink"
312
+ }
313
+ },
314
+ "view/launch": {
315
+ "direction": "client-to-instance",
316
+ "mutating": true,
317
+ "params": {
318
+ "$ref": "#/$defs/ViewLaunchParams"
319
+ },
320
+ "result": {
321
+ "$ref": "#/$defs/ViewLaunchResult"
322
+ }
323
+ },
324
+ "view/revoke": {
325
+ "direction": "client-to-instance",
326
+ "mutating": true,
327
+ "params": {
328
+ "$ref": "#/$defs/ViewRevokeParams"
329
+ },
330
+ "result": {
331
+ "$ref": "#/$defs/ViewRevokeResult"
332
+ }
333
+ },
334
+ "view/rotate": {
335
+ "direction": "client-to-instance",
336
+ "mutating": true,
337
+ "params": {
338
+ "$ref": "#/$defs/ViewRotateParams"
339
+ },
340
+ "result": {
341
+ "$ref": "#/$defs/CapabilityLink"
342
+ }
343
+ },
344
+ "view/url": {
345
+ "direction": "client-to-instance",
346
+ "mutating": true,
347
+ "params": {
348
+ "$ref": "#/$defs/ViewUrlParams"
349
+ },
350
+ "result": {
351
+ "$ref": "#/$defs/CapabilityLink"
352
+ }
353
+ },
354
+ "wait": {
355
+ "direction": "client-to-instance",
356
+ "mutating": false,
357
+ "params": {
358
+ "$ref": "#/$defs/WaitParams"
359
+ },
360
+ "result": {
361
+ "$ref": "#/$defs/WaitResult"
362
+ }
363
+ }
364
+ },
365
+ "x-mostra-notifications": {
366
+ "artifact/progress": {
367
+ "params": {
368
+ "$ref": "#/$defs/ArtifactProgressParams"
369
+ }
370
+ },
371
+ "dev/notify": {
372
+ "params": {
373
+ "$ref": "#/$defs/DevNotifyParams"
374
+ }
375
+ },
376
+ "events/notify": {
377
+ "params": {
378
+ "$ref": "#/$defs/EventsNotifyParams"
379
+ }
380
+ }
381
+ },
7
382
  "$defs": {
8
383
  "ActionError": {
9
384
  "type": "object",
@@ -2890,6 +3265,44 @@
2890
3265
  ],
2891
3266
  "description": "A long-poll answer: the cursor, the events after the asked one, and a snapshot."
2892
3267
  },
3268
+ "PortIdentityResolveParams": {
3269
+ "type": "object",
3270
+ "properties": {
3271
+ "artifactId": {
3272
+ "$ref": "#/$defs/ArtifactId"
3273
+ },
3274
+ "via": {
3275
+ "type": "string",
3276
+ "minLength": 1
3277
+ },
3278
+ "headers": {
3279
+ "type": "object",
3280
+ "propertyNames": {
3281
+ "type": "string"
3282
+ },
3283
+ "additionalProperties": {
3284
+ "type": "string"
3285
+ }
3286
+ }
3287
+ },
3288
+ "required": [
3289
+ "artifactId",
3290
+ "via",
3291
+ "headers"
3292
+ ],
3293
+ "description": "A browser opening a link without a viewer: the artifact, how the request arrived and its headers (no cookies, no Mostra headers)."
3294
+ },
3295
+ "PortIdentityResolveResult": {
3296
+ "anyOf": [
3297
+ {
3298
+ "$ref": "#/$defs/ViewerSpec"
3299
+ },
3300
+ {
3301
+ "type": "null"
3302
+ }
3303
+ ],
3304
+ "description": "The person the session acts for, by the host's stable key, or null for the default."
3305
+ },
2893
3306
  "PortName": {
2894
3307
  "type": "string",
2895
3308
  "pattern": "^[a-z][a-zA-Z0-9]*$",
@@ -20,6 +20,7 @@ export const hostDiagnosticCodes = [
20
20
  "MOSTRA_HOST_SUBSCRIPTION_UNKNOWN",
21
21
  "MOSTRA_HOST_NOTIFICATION_UNSUPPORTED",
22
22
  "MOSTRA_HOST_MESSAGE_TOO_LARGE",
23
+ "MOSTRA_HOST_IDENTITY_UNAVAILABLE",
23
24
  // gen:codes
24
25
  ] as const;
25
26
 
@@ -193,5 +194,16 @@ export const hostDiagnostics: AreaCatalog<HostDiagnosticCode> = {
193
194
  fix: "Read less per request (`events/read` with a smaller `limit`, `results/get` for one submission), and keep artifacts' values within the field and document limits.",
194
195
  },
195
196
  },
197
+ MOSTRA_HOST_IDENTITY_UNAVAILABLE: {
198
+ severity: "error",
199
+ phase: "host",
200
+ title: "The host that identifies viewers didn't answer",
201
+ hint: "Start the host that serves this home's identity port, then open the link again.",
202
+ docs: {
203
+ explanation:
204
+ "A host registered the `identity` port, so it decides who opens this home's links. When a link minted without a viewer was opened, that host failed, didn't answer within 5 seconds, gave an answer its schema refuses, or is expected (it lists `identity` in `HomeConfig.ports`) but not connected. Mostra refuses the link rather than let the session act as someone else.",
205
+ fix: "Start or reconnect the host, then open the link again. A link minted with `view/url`'s `viewer` names its person itself and never needs the port. To return the home to Mostra's own identity, have the host register without the port and clear its expected ports (`HomeConfig.ports: []`).",
206
+ },
207
+ },
196
208
  // gen:entries
197
209
  };
package/src/index.ts CHANGED
@@ -280,9 +280,11 @@ export {
280
280
  } from "./manifest.ts";
281
281
  export {
282
282
  type AnyMethod,
283
+ type AnyNotification,
283
284
  defineMethod,
284
285
  type MethodDefinition,
285
286
  type MethodDirection,
287
+ type NotificationDefinition,
286
288
  } from "./method.ts";
287
289
  export {
288
290
  type ArtifactCreateParams,
@@ -357,7 +359,7 @@ export {
357
359
  type GcVersion,
358
360
  gcRunMethod,
359
361
  } from "./methods/gc/run.ts";
360
- export { hostMethods } from "./methods/index.ts";
362
+ export { hostMethods, hostNotifications } from "./methods/index.ts";
361
363
  export {
362
364
  type InstanceCheck,
363
365
  type InstanceCheckParams,
@@ -397,6 +399,12 @@ export {
397
399
  type DraftsMirrorResult,
398
400
  portDraftsMirrorMethod,
399
401
  } from "./methods/port/drafts-mirror.ts";
402
+ export {
403
+ type IdentityVia,
404
+ type PortIdentityResolveParams,
405
+ type PortIdentityResolveResult,
406
+ portIdentityResolveMethod,
407
+ } from "./methods/port/identity-resolve.ts";
400
408
  export {
401
409
  type PortSecretsGetParams,
402
410
  type PortSecretsGetResult,
package/src/method.ts CHANGED
@@ -40,3 +40,17 @@ export function defineMethod<Params, Result>(
40
40
  }
41
41
  return definition;
42
42
  }
43
+
44
+ /**
45
+ * One notification of the host protocol: a message without an answer, sent by the instance to a
46
+ * client that accepted it in `mostra/initialize` (`ClientCapabilities.notifications`).
47
+ */
48
+ export interface NotificationDefinition<Params> {
49
+ /** The JSON-RPC method name, such as `events/notify`. */
50
+ readonly method: string;
51
+ /** The schema of its `params`. */
52
+ readonly params: z.ZodType<Params>;
53
+ }
54
+
55
+ /** A notification of any params type. */
56
+ export type AnyNotification = NotificationDefinition<unknown>;
@@ -2,18 +2,19 @@
2
2
  * Every host protocol method this package defines. `pnpm gen protocol-method` adds entries at the
3
3
  * markers; the method itself lives in its own module under `methods/<group>/`.
4
4
  */
5
- import type { AnyMethod } from "../method.ts";
5
+ import type { AnyMethod, AnyNotification } from "../method.ts";
6
+ import { ARTIFACT_PROGRESS, ArtifactProgressParams } from "../verify.ts";
6
7
  import { artifactCreateMethod } from "./artifact/create.ts";
7
8
  import { artifactGetMethod } from "./artifact/get.ts";
8
9
  import { artifactListMethod } from "./artifact/list.ts";
9
10
  import { artifactPublishMethod } from "./artifact/publish.ts";
10
11
  import { artifactVerifyMethod } from "./artifact/verify.ts";
11
12
  import { depsAddMethod } from "./deps/add.ts";
12
- import { devStartMethod } from "./dev/start.ts";
13
+ import { DEV_NOTIFY, DevNotifyParams, devStartMethod } from "./dev/start.ts";
13
14
  import { devStopMethod } from "./dev/stop.ts";
14
15
  import { eventsAckMethod } from "./events/ack.ts";
15
16
  import { eventsReadMethod } from "./events/read.ts";
16
- import { eventsSubscribeMethod } from "./events/subscribe.ts";
17
+ import { EVENTS_NOTIFY, EventsNotifyParams, eventsSubscribeMethod } from "./events/subscribe.ts";
17
18
  import { eventsUnsubscribeMethod } from "./events/unsubscribe.ts";
18
19
  import { gcRunMethod } from "./gc/run.ts";
19
20
  import { instanceCheckMethod } from "./instance/check.ts";
@@ -22,6 +23,7 @@ import { livePushMethod } from "./live/push.ts";
22
23
  import { mostraInitializeMethod } from "./mostra/initialize.ts";
23
24
  import { mostraShutdownMethod } from "./mostra/shutdown.ts";
24
25
  import { portDraftsMirrorMethod } from "./port/drafts-mirror.ts";
26
+ import { portIdentityResolveMethod } from "./port/identity-resolve.ts";
25
27
  import { portSecretsGetMethod } from "./port/secrets-get.ts";
26
28
  import { portSubmissionsDeliverMethod } from "./port/submissions-deliver.ts";
27
29
  import { portTrustedControlsActivatedMethod } from "./port/trusted-controls-activated.ts";
@@ -77,5 +79,13 @@ export const hostMethods: readonly AnyMethod[] = [
77
79
  instanceCheckMethod,
78
80
  devStartMethod,
79
81
  devStopMethod,
82
+ portIdentityResolveMethod,
80
83
  // gen:methods
81
84
  ];
85
+
86
+ /** Every notification the instance sends to its clients (INTERFACES §6). */
87
+ export const hostNotifications: readonly AnyNotification[] = [
88
+ { method: EVENTS_NOTIFY, params: EventsNotifyParams as AnyNotification["params"] },
89
+ { method: ARTIFACT_PROGRESS, params: ArtifactProgressParams as AnyNotification["params"] },
90
+ { method: DEV_NOTIFY, params: DevNotifyParams as AnyNotification["params"] },
91
+ ];
@@ -43,7 +43,7 @@ export const CLI_CLIENT_NAME = "mostra-cli";
43
43
 
44
44
  /** The client that opens a connection. */
45
45
  export interface ClientInfo {
46
- /** The client's name, for logs and status (`mostra-cli`, `jcode`). */
46
+ /** The client's name, for logs and status (`mostra-cli`, `my-host`). */
47
47
  readonly name: string;
48
48
  /** The client's own version. */
49
49
  readonly version: string;
@@ -0,0 +1,67 @@
1
+ import * as z from "zod";
2
+ import { ArtifactId } from "../../ids.ts";
3
+ import { ViewerSpec } from "../../interaction.ts";
4
+ import { defineMethod, type MethodDefinition } from "../../method.ts";
5
+ import { wireRegistry } from "../../wire-registry.ts";
6
+
7
+ /**
8
+ * How a browser's request reached the gateway (D143 item 2): `local` on the gateway's own
9
+ * address; `tailnet` through Tailscale Serve and `token` through a public share, where the link is
10
+ * all that identifies the viewer (both WP-13). An open string on the wire, so a host meets a newer
11
+ * value instead of a refusal.
12
+ */
13
+ export type IdentityVia = "local" | "tailnet" | "token" | (string & {});
14
+
15
+ /** The params of `port/identity.resolve` (INTERFACES §7, D143 item 2). */
16
+ export interface PortIdentityResolveParams {
17
+ /** The artifact whose link is being opened. */
18
+ readonly artifactId: string;
19
+ /** How the request reached the gateway. */
20
+ readonly via: IdentityVia;
21
+ /**
22
+ * The request's headers, names in lower case, without `cookie` and without Mostra's own
23
+ * `x-mostra-*` headers: what a host's proxy or tunnel added (an identity header) is here.
24
+ */
25
+ readonly headers: Readonly<Record<string, string>>;
26
+ }
27
+
28
+ /**
29
+ * The result of `port/identity.resolve`: the person, as the host's stable key and display name
30
+ * (one viewer of kind `host` per `ref`), or `null` for the standalone default.
31
+ */
32
+ export type PortIdentityResolveResult = ViewerSpec | null;
33
+
34
+ const params: z.ZodType<PortIdentityResolveParams> = z
35
+ .object({
36
+ artifactId: ArtifactId.schema,
37
+ via: z.string().min(1),
38
+ headers: z.record(z.string(), z.string()),
39
+ })
40
+ .register(wireRegistry, {
41
+ id: "PortIdentityResolveParams",
42
+ description:
43
+ "A browser opening a link without a viewer: the artifact, how the request arrived and its headers (no cookies, no Mostra headers).",
44
+ });
45
+
46
+ const result: z.ZodType<PortIdentityResolveResult> = ViewerSpec.nullable().register(wireRegistry, {
47
+ id: "PortIdentityResolveResult",
48
+ description:
49
+ "The person the session acts for, by the host's stable key, or null for the default.",
50
+ });
51
+
52
+ /**
53
+ * `port/identity.resolve`: Mostra asks the host that registered the `identity` port who a browser
54
+ * is when it opens a link minted without a viewer (D143 item 2), with 5 seconds to answer. A
55
+ * failure, a timeout or an answer the schema refuses refuses the link's exchange with
56
+ * `MOSTRA_HOST_IDENTITY_UNAVAILABLE`; it never falls back to another person.
57
+ */
58
+ export const portIdentityResolveMethod: MethodDefinition<
59
+ PortIdentityResolveParams,
60
+ PortIdentityResolveResult
61
+ > = defineMethod({
62
+ method: "port/identity.resolve",
63
+ direction: "instance-to-host",
64
+ mutating: false,
65
+ params,
66
+ result,
67
+ });