@mostra/protocol 0.10.0 → 0.11.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 (55) hide show
  1. package/dist/browser.d.ts +42 -0
  2. package/dist/browser.d.ts.map +1 -1
  3. package/dist/browser.js +29 -1
  4. package/dist/browser.js.map +1 -1
  5. package/dist/diagnostics/codes/action.d.ts +1 -1
  6. package/dist/diagnostics/codes/action.d.ts.map +1 -1
  7. package/dist/diagnostics/codes/action.js +12 -1
  8. package/dist/diagnostics/codes/action.js.map +1 -1
  9. package/dist/diagnostics/codes/remote.d.ts +1 -1
  10. package/dist/diagnostics/codes/remote.d.ts.map +1 -1
  11. package/dist/diagnostics/codes/remote.js +78 -1
  12. package/dist/diagnostics/codes/remote.js.map +1 -1
  13. package/dist/diagnostics/codes/submit.d.ts +1 -1
  14. package/dist/diagnostics/codes/submit.d.ts.map +1 -1
  15. package/dist/diagnostics/codes/submit.js +12 -1
  16. package/dist/diagnostics/codes/submit.js.map +1 -1
  17. package/dist/index.d.ts +5 -2
  18. package/dist/index.js +4 -1
  19. package/dist/interaction.d.ts +5 -0
  20. package/dist/interaction.d.ts.map +1 -1
  21. package/dist/interaction.js +2 -1
  22. package/dist/interaction.js.map +1 -1
  23. package/dist/methods/artifact/pause.d.ts +33 -0
  24. package/dist/methods/artifact/pause.d.ts.map +1 -0
  25. package/dist/methods/artifact/pause.js +33 -0
  26. package/dist/methods/artifact/pause.js.map +1 -0
  27. package/dist/methods/index.d.ts.map +1 -1
  28. package/dist/methods/index.js +7 -1
  29. package/dist/methods/index.js.map +1 -1
  30. package/dist/methods/port/relay-author.d.ts +28 -0
  31. package/dist/methods/port/relay-author.d.ts.map +1 -0
  32. package/dist/methods/port/relay-author.js +42 -0
  33. package/dist/methods/port/relay-author.js.map +1 -0
  34. package/dist/methods/remote/link.d.ts +40 -0
  35. package/dist/methods/remote/link.d.ts.map +1 -0
  36. package/dist/methods/remote/link.js +40 -0
  37. package/dist/methods/remote/link.js.map +1 -0
  38. package/dist/operator.d.ts +464 -0
  39. package/dist/operator.d.ts.map +1 -0
  40. package/dist/operator.js +134 -0
  41. package/dist/operator.js.map +1 -0
  42. package/package.json +11 -1
  43. package/schemas/protocol.draft-07.json +259 -0
  44. package/schemas/protocol.schema.json +259 -0
  45. package/src/browser.ts +64 -0
  46. package/src/diagnostics/codes/action.ts +12 -0
  47. package/src/diagnostics/codes/remote.ts +84 -0
  48. package/src/diagnostics/codes/submit.ts +12 -0
  49. package/src/index.ts +19 -0
  50. package/src/interaction.ts +6 -0
  51. package/src/methods/artifact/pause.ts +59 -0
  52. package/src/methods/index.ts +6 -0
  53. package/src/methods/port/relay-author.ts +57 -0
  54. package/src/methods/remote/link.ts +65 -0
  55. package/src/operator.ts +621 -0
@@ -0,0 +1,42 @@
1
+ import { wireRegistry } from "../../wire-registry.js";
2
+ import { defineMethod } from "../../method.js";
3
+ import * as z from "zod";
4
+ //#region src/methods/port/relay-author.ts
5
+ /**
6
+ * What remote MCP may ask an owner instance to do for it (INTERFACES §18.8, D165 item 5): the
7
+ * authoring methods of the host protocol, and the owner's workspace (`McpWorkspace`, its root and
8
+ * its artifacts' files) and verify's screenshots, which only that machine holds.
9
+ */
10
+ const RELAY_AUTHOR_METHODS = [
11
+ "artifact/create",
12
+ "artifact/verify",
13
+ "artifact/publish",
14
+ "artifact/get",
15
+ "workspace/root",
16
+ "workspace/allocate",
17
+ "workspace/read",
18
+ "workspace/apply",
19
+ "verify/screenshot"
20
+ ];
21
+ const params = z.object({
22
+ method: z.enum(RELAY_AUTHOR_METHODS),
23
+ params: z.unknown()
24
+ }).register(wireRegistry, { id: "PortRelayAuthorParams" });
25
+ const result = z.unknown().register(wireRegistry, { id: "PortRelayAuthorResult" });
26
+ /**
27
+ * `port/relay.author`: the remote MCP server relays an authoring step to the account's default
28
+ * owner instance (D165 item 5), which runs it in its own workspace, builder and `verify`, and
29
+ * answers its result or its diagnostic. A publish through it also hosts the version on the server
30
+ * that asked and answers the hosted link. Workspace paths stay inside the owner's workspace.
31
+ */
32
+ const portRelayAuthorMethod = defineMethod({
33
+ method: "port/relay.author",
34
+ direction: "instance-to-host",
35
+ mutating: true,
36
+ params,
37
+ result
38
+ });
39
+ //#endregion
40
+ export { RELAY_AUTHOR_METHODS, portRelayAuthorMethod };
41
+
42
+ //# sourceMappingURL=relay-author.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"relay-author.js","names":[],"sources":["../../../src/methods/port/relay-author.ts"],"sourcesContent":["import * as z from \"zod\";\nimport { defineMethod, type MethodDefinition } from \"../../method.ts\";\nimport { wireRegistry } from \"../../wire-registry.ts\";\n\n/**\n * What remote MCP may ask an owner instance to do for it (INTERFACES §18.8, D165 item 5): the\n * authoring methods of the host protocol, and the owner's workspace (`McpWorkspace`, its root and\n * its artifacts' files) and verify's screenshots, which only that machine holds.\n */\nexport const RELAY_AUTHOR_METHODS = [\n \"artifact/create\",\n \"artifact/verify\",\n \"artifact/publish\",\n \"artifact/get\",\n \"workspace/root\",\n \"workspace/allocate\",\n \"workspace/read\",\n \"workspace/apply\",\n \"verify/screenshot\",\n] as const;\n\n/** One of {@link RELAY_AUTHOR_METHODS}. */\nexport type RelayAuthorMethod = (typeof RELAY_AUTHOR_METHODS)[number];\n\n/** The params of `port/relay.author` (INTERFACES §18.3). */\nexport interface PortRelayAuthorParams {\n /** What to do on the owner instance. */\n readonly method: RelayAuthorMethod;\n /** Its params: the host protocol method's, or the workspace operation's. */\n readonly params: unknown;\n}\n\n/** The result of `port/relay.author`: the method's own result. */\nexport type PortRelayAuthorResult = unknown;\n\nconst params: z.ZodType<PortRelayAuthorParams> = z\n .object({ method: z.enum(RELAY_AUTHOR_METHODS), params: z.unknown() })\n .register(wireRegistry, { id: \"PortRelayAuthorParams\" });\n\nconst result: z.ZodType<PortRelayAuthorResult> = z\n .unknown()\n .register(wireRegistry, { id: \"PortRelayAuthorResult\" });\n\n/**\n * `port/relay.author`: the remote MCP server relays an authoring step to the account's default\n * owner instance (D165 item 5), which runs it in its own workspace, builder and `verify`, and\n * answers its result or its diagnostic. A publish through it also hosts the version on the server\n * that asked and answers the hosted link. Workspace paths stay inside the owner's workspace.\n */\nexport const portRelayAuthorMethod: MethodDefinition<PortRelayAuthorParams, PortRelayAuthorResult> =\n defineMethod({\n method: \"port/relay.author\",\n direction: \"instance-to-host\",\n mutating: true,\n params,\n result,\n });\n"],"mappings":";;;;;;;;;AASA,MAAa,uBAAuB;CAClC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF;AAgBA,MAAM,SAA2C,EAC9C,OAAO;CAAE,QAAQ,EAAE,KAAK,oBAAoB;CAAG,QAAQ,EAAE,QAAQ;AAAE,CAAC,CAAC,CACrE,SAAS,cAAc,EAAE,IAAI,wBAAwB,CAAC;AAEzD,MAAM,SAA2C,EAC9C,QAAQ,CAAC,CACT,SAAS,cAAc,EAAE,IAAI,wBAAwB,CAAC;;;;;;;AAQzD,MAAa,wBACX,aAAa;CACX,QAAQ;CACR,WAAW;CACX,UAAU;CACV;CACA;AACF,CAAC"}
@@ -0,0 +1,40 @@
1
+ import { MethodDefinition } from "../../method.js";
2
+ import { ServerOrigin } from "../../remote.js";
3
+ //#region src/methods/remote/link.d.ts
4
+ /** The params of `remote/link` (INTERFACES §18.2). */
5
+ export interface RemoteLinkParams {
6
+ /** The server's API origin. */
7
+ readonly server: ServerOrigin;
8
+ /**
9
+ * A credential the server's operator issued for an account (`accounts.authenticate`, §18.6), in
10
+ * place of a person's sign-in: a program runs an always-on owner instance with it. Kept in the
11
+ * home, owner-only, like a refresh token; never logged.
12
+ */
13
+ readonly key: string;
14
+ /** Makes this instance the account's default: the one chat-host authoring goes to (D165 item 1b). */
15
+ readonly default?: boolean;
16
+ }
17
+ /** The result of `remote/link`: this home is linked to the server for the key's account. */
18
+ export interface RemoteLinkResult {
19
+ /** The server linked to. */
20
+ readonly server: ServerOrigin;
21
+ /** The account the key is the operator's credential for. */
22
+ readonly account: {
23
+ readonly id: string;
24
+ readonly name?: string;
25
+ };
26
+ /** This home's instance link on that server (`lnk_…`), one per key's subject. */
27
+ readonly instanceId: string;
28
+ /** Whether this instance is the account's default. */
29
+ readonly default: boolean;
30
+ }
31
+ /**
32
+ * `remote/link`: links this home to a remote server with a key its operator issued for an account,
33
+ * in place of `remote/login`'s device grant, so a program can run an always-on owner instance
34
+ * (WP-30, D167). Linking again with a key is idempotent by nature, so it takes no `requestId`: the
35
+ * ledger never records the key's digest. A key the server doesn't admit is
36
+ * `MOSTRA_REMOTE_LOGIN_FAILED`.
37
+ */
38
+ export declare const remoteLinkMethod: MethodDefinition<RemoteLinkParams, RemoteLinkResult>;
39
+ //#endregion
40
+ //# sourceMappingURL=link.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"link.d.ts","names":[],"sources":["../../../src/methods/remote/link.ts"],"mappings":";;;;iBAMiB;;WAEN,QAAQ;;;;;;WAMR;;WAEA;;;iBAIM;;WAEN,QAAQ;;WAER;aAAoB;aAAqB;;;WAEzC;;WAEA;;;;;;;;;qBA8BE,kBAAkB,iBAAiB,kBAAkB"}
@@ -0,0 +1,40 @@
1
+ import { wireRegistry } from "../../wire-registry.js";
2
+ import { defineMethod } from "../../method.js";
3
+ import { ServerOrigin } from "../../remote.js";
4
+ import * as z from "zod";
5
+ //#region src/methods/remote/link.ts
6
+ const params = z.object({
7
+ server: ServerOrigin,
8
+ key: z.string().min(20).max(512),
9
+ default: z.boolean().exactOptional()
10
+ }).register(wireRegistry, { id: "RemoteLinkParams" });
11
+ const result = z.object({
12
+ server: ServerOrigin,
13
+ account: z.object({
14
+ id: z.string(),
15
+ name: z.string().exactOptional()
16
+ }),
17
+ instanceId: z.string(),
18
+ default: z.boolean()
19
+ }).register(wireRegistry, {
20
+ id: "RemoteLinkResult",
21
+ description: "A home linked to a remote server with an operator-issued key."
22
+ });
23
+ /**
24
+ * `remote/link`: links this home to a remote server with a key its operator issued for an account,
25
+ * in place of `remote/login`'s device grant, so a program can run an always-on owner instance
26
+ * (WP-30, D167). Linking again with a key is idempotent by nature, so it takes no `requestId`: the
27
+ * ledger never records the key's digest. A key the server doesn't admit is
28
+ * `MOSTRA_REMOTE_LOGIN_FAILED`.
29
+ */
30
+ const remoteLinkMethod = defineMethod({
31
+ method: "remote/link",
32
+ direction: "client-to-instance",
33
+ mutating: false,
34
+ params,
35
+ result
36
+ });
37
+ //#endregion
38
+ export { remoteLinkMethod };
39
+
40
+ //# sourceMappingURL=link.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"link.js","names":[],"sources":["../../../src/methods/remote/link.ts"],"sourcesContent":["import * as z from \"zod\";\nimport { defineMethod, type MethodDefinition } from \"../../method.ts\";\nimport { ServerOrigin } from \"../../remote.ts\";\nimport { wireRegistry } from \"../../wire-registry.ts\";\n\n/** The params of `remote/link` (INTERFACES §18.2). */\nexport interface RemoteLinkParams {\n /** The server's API origin. */\n readonly server: ServerOrigin;\n /**\n * A credential the server's operator issued for an account (`accounts.authenticate`, §18.6), in\n * place of a person's sign-in: a program runs an always-on owner instance with it. Kept in the\n * home, owner-only, like a refresh token; never logged.\n */\n readonly key: string;\n /** Makes this instance the account's default: the one chat-host authoring goes to (D165 item 1b). */\n readonly default?: boolean;\n}\n\n/** The result of `remote/link`: this home is linked to the server for the key's account. */\nexport interface RemoteLinkResult {\n /** The server linked to. */\n readonly server: ServerOrigin;\n /** The account the key is the operator's credential for. */\n readonly account: { readonly id: string; readonly name?: string };\n /** This home's instance link on that server (`lnk_…`), one per key's subject. */\n readonly instanceId: string;\n /** Whether this instance is the account's default. */\n readonly default: boolean;\n}\n\nconst params: z.ZodType<RemoteLinkParams> = z\n .object({\n server: ServerOrigin,\n key: z.string().min(20).max(512),\n default: z.boolean().exactOptional(),\n })\n .register(wireRegistry, { id: \"RemoteLinkParams\" });\n\nconst result: z.ZodType<RemoteLinkResult> = z\n .object({\n server: ServerOrigin,\n account: z.object({ id: z.string(), name: z.string().exactOptional() }),\n instanceId: z.string(),\n default: z.boolean(),\n })\n .register(wireRegistry, {\n id: \"RemoteLinkResult\",\n description: \"A home linked to a remote server with an operator-issued key.\",\n });\n\n/**\n * `remote/link`: links this home to a remote server with a key its operator issued for an account,\n * in place of `remote/login`'s device grant, so a program can run an always-on owner instance\n * (WP-30, D167). Linking again with a key is idempotent by nature, so it takes no `requestId`: the\n * ledger never records the key's digest. A key the server doesn't admit is\n * `MOSTRA_REMOTE_LOGIN_FAILED`.\n */\nexport const remoteLinkMethod: MethodDefinition<RemoteLinkParams, RemoteLinkResult> = defineMethod({\n method: \"remote/link\",\n direction: \"client-to-instance\",\n mutating: false,\n params,\n result,\n});\n"],"mappings":";;;;;AA+BA,MAAM,SAAsC,EACzC,OAAO;CACN,QAAQ;CACR,KAAK,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,GAAG;CAC/B,SAAS,EAAE,QAAQ,CAAC,CAAC,cAAc;AACrC,CAAC,CAAC,CACD,SAAS,cAAc,EAAE,IAAI,mBAAmB,CAAC;AAEpD,MAAM,SAAsC,EACzC,OAAO;CACN,QAAQ;CACR,SAAS,EAAE,OAAO;EAAE,IAAI,EAAE,OAAO;EAAG,MAAM,EAAE,OAAO,CAAC,CAAC,cAAc;CAAE,CAAC;CACtE,YAAY,EAAE,OAAO;CACrB,SAAS,EAAE,QAAQ;AACrB,CAAC,CAAC,CACD,SAAS,cAAc;CACtB,IAAI;CACJ,aAAa;AACf,CAAC;;;;;;;;AASH,MAAa,mBAAyE,aAAa;CACjG,QAAQ;CACR,WAAW;CACX,UAAU;CACV;CACA;AACF,CAAC"}
@@ -0,0 +1,464 @@
1
+ import * as z from "zod";
2
+ //#region src/operator.d.ts
3
+ /** The operator boundary's own revision, which a module may check (additive within it). */
4
+ export declare const OPERATOR_REVISION = "2026-11-08";
5
+ /** How long the server waits for each port, in milliseconds, before it acts as if none answered. */
6
+ export declare const OPERATOR_TIME_LIMITS: {
7
+ readonly limits: number;
8
+ readonly policy: number;
9
+ readonly routing: number;
10
+ readonly identity: number;
11
+ readonly accounts: number;
12
+ readonly authenticate: number;
13
+ readonly pushed: number;
14
+ readonly outbound: number;
15
+ };
16
+ /**
17
+ * An operation `limits.check` judges. When the operator doesn't answer in time, `share`,
18
+ * `version.push`, `link` and authoring fail closed, and `view`, `submit` and draft writes proceed,
19
+ * so nothing a person typed is lost (D165 item 9).
20
+ */
21
+ export type LimitOperation = "share" | "version.push" | "link" | "view" | "submit" | "run" | "run.wait" | "call" | "mcp.call" | "storage";
22
+ /** What `limits.check` is asked. */
23
+ export interface LimitQuery {
24
+ /** The account the operation counts against. */
25
+ readonly account: string;
26
+ /** The account's hosted home. */
27
+ readonly home: string;
28
+ /** The artifact, for operations on one. */
29
+ readonly artifact?: string;
30
+ /** The artifact's hosted route, for operations on one (WP-30). */
31
+ readonly routeId?: string;
32
+ /** What is asked for. */
33
+ readonly operation: LimitOperation;
34
+ /** How much: bytes for `storage` and `version.push`, else 1. */
35
+ readonly quantity?: number;
36
+ }
37
+ /** How long the server may keep an answer instead of asking again, in milliseconds (WP-30). */
38
+ export interface Cacheable {
39
+ /** Absent or 0: ask again next time. */
40
+ readonly cacheForMs?: number;
41
+ }
42
+ /** `limits.check`'s answer. */
43
+ export type LimitAnswer = ({
44
+ readonly allowed: true;
45
+ } & Cacheable) | ({
46
+ readonly allowed: false;
47
+ /** A diagnostic code of the operator's (the server answers `MOSTRA_REMOTE_LIMIT_REACHED`). */
48
+ readonly code: string;
49
+ /** Shown as text to whoever was refused. */
50
+ readonly message: string;
51
+ readonly retryAfterMs?: number;
52
+ } & Cacheable);
53
+ /** The schema the server checks `limits.check`'s answer against. */
54
+ export declare const LimitAnswer: z.ZodType<LimitAnswer>;
55
+ /** A counter's name (INTERFACES §18.6). */
56
+ export type MeterName = "views" | "submissions" | "requests" | "bytes.stored" | "bytes.egress" | "relay.messages" | "mcp.calls" | "home.activeSeconds" | (string & {});
57
+ /**
58
+ * One counter of a batch. `views` carry `viewerKey`, a monthly pseudonymous key (an HMAC under a
59
+ * key the server rotates each month), never an identity: per account for a signed-in viewer, per
60
+ * viewer for a link minted with one, and per route for an anonymous viewer, since the shell gives
61
+ * each route a different key and none spans routes (HY-08). `mcp.calls` carry `client`, the MCP
62
+ * client's `clientInfo` name (D148).
63
+ */
64
+ export interface MeterCounter {
65
+ /** What is counted. */
66
+ readonly name: MeterName;
67
+ /** The account it counts against. */
68
+ readonly account: string;
69
+ /** The account's hosted home. */
70
+ readonly home?: string;
71
+ /** The artifact, for counters of one. */
72
+ readonly artifactId?: string;
73
+ /** The artifact's hosted route, for counters of one. */
74
+ readonly routeId?: string;
75
+ /** How much in the batch's window: a count, bytes or seconds. */
76
+ readonly value: number;
77
+ /** What tells counters of one name apart (`viewerKey`, `client`). */
78
+ readonly dimensions?: Readonly<Record<string, string>>;
79
+ }
80
+ /** What `metering.record` receives, at least once, idempotent by `batchId`. */
81
+ export interface MeterBatch {
82
+ /** Stable across retries: a batch delivered twice is the same batch. */
83
+ readonly batchId: string;
84
+ /** Where the window the counters cover starts. */
85
+ readonly from: string;
86
+ /** Where it ends. */
87
+ readonly to: string;
88
+ /** The counters, one per name, account, route and dimensions. */
89
+ readonly counters: readonly MeterCounter[];
90
+ }
91
+ /**
92
+ * Who an identity provider says signed in (INTERFACES §18.5). `facts` carries what a provider
93
+ * tells beyond that (GitHub's account age, `createdAt`), for an operator's policy.
94
+ */
95
+ export interface SignInIdentity {
96
+ /** The provider's ID (`IdentityProvider.id`). */
97
+ readonly provider: string;
98
+ /** The provider's own stable ID for the person. */
99
+ readonly subject: string;
100
+ /** The person's email address, when the provider gives one. */
101
+ readonly email?: string;
102
+ /** Whether the provider verified `email`. */
103
+ readonly emailVerified?: boolean;
104
+ /** The display name the provider gives. */
105
+ readonly name?: string;
106
+ /** What else the provider tells (an account's age as `createdAt`). */
107
+ readonly facts?: Readonly<Record<string, unknown>>;
108
+ }
109
+ /** The schema the server checks a provider's `SignInIdentity` against. */
110
+ export declare const SignInIdentity: z.ZodType<SignInIdentity>;
111
+ /** PKCE for one sign-in at a provider: the server makes it; the provider sends `challenge`. */
112
+ export interface SignInPkce {
113
+ /** The S256 challenge the provider's authorization request carries. */
114
+ readonly challenge: string;
115
+ /** Always S256. */
116
+ readonly method: "S256";
117
+ /** The verifier the provider's code exchange sends. */
118
+ readonly verifier: string;
119
+ }
120
+ /** What a provider's `authorize` and `callback` are told about the sign-in in progress. */
121
+ export interface SignInContext {
122
+ /** The provider's return address on the API origin: `<apiOrigin>/signin/<id>/callback`. */
123
+ readonly redirectUri: string;
124
+ /** A fresh value an OpenID Connect provider binds its ID token to. */
125
+ readonly nonce: string;
126
+ }
127
+ /**
128
+ * An identity provider behind the sign-in port (D165 item 8): the built-in OpenID Connect and
129
+ * GitHub adapters, a development one for tests, or one an operator module supplies.
130
+ */
131
+ export interface IdentityProvider {
132
+ /** Lower-case letters, digits and hyphens, at most 32: part of its callback's path. */
133
+ readonly id: string;
134
+ /** What the sign-in page calls it ("GitHub"). */
135
+ readonly label: string;
136
+ /** Where to send the person: the provider's authorization URL with `state` and PKCE. */
137
+ authorize(state: string, pkce: SignInPkce, context: SignInContext): string | Promise<string>;
138
+ /**
139
+ * The person the provider names on return, from its callback's query (each parameter once; a
140
+ * repeated one is refused before this is called). The server has already
141
+ * checked `state`; the provider exchanges the code (with `pkce.verifier`) and checks what it
142
+ * gets. Throws when sign-in failed.
143
+ */
144
+ callback(params: Readonly<Record<string, string>>, context: SignInContext & {
145
+ readonly state: string;
146
+ readonly pkce: SignInPkce;
147
+ }): Promise<SignInIdentity>;
148
+ }
149
+ /**
150
+ * `accounts.resolve`'s answer: the account (`status` `suspended` refuses sign-in), a **first
151
+ * sign-in step** on the operator's origin, or a refusal shown as text.
152
+ *
153
+ * A step: the server sends the person to `step.url` with `mostra_return` added, an address on the
154
+ * API origin (`/signin/return?step=<handle>`). The handle is single-use, lasts 15 minutes and is
155
+ * bound to the browser that started the sign-in (a `__Host-` cookie on the API origin, never on a
156
+ * user-content domain), so it can't be replayed or swapped. When the person comes back the server
157
+ * calls `resolve` again with the same identity and `context.steps` one higher; at most three steps
158
+ * per sign-in (WP-30, D167).
159
+ */
160
+ export type AccountResolution = {
161
+ readonly account: string;
162
+ readonly name?: string;
163
+ readonly status: "active" | "suspended";
164
+ } | {
165
+ readonly step: {
166
+ readonly url: string;
167
+ };
168
+ } | {
169
+ readonly refused: {
170
+ readonly message: string;
171
+ };
172
+ };
173
+ /** The schema the server checks `accounts.resolve`'s answer against. */
174
+ export declare const AccountResolution: z.ZodType<AccountResolution>;
175
+ /** Where an operator-issued credential was presented (D165 item 9, Opus review of WP-28). */
176
+ export type CredentialResource = "host" | "mcp" | "files";
177
+ /**
178
+ * `accounts.authenticate`'s answer for a credential the operator issued, or `null`. `subject`
179
+ * names the credential stably (a service key's ID): a binding with it is one owner instance link
180
+ * of the account, kept per subject, so a program can run an always-on owner instance.
181
+ */
182
+ export interface AuthenticatedCredential {
183
+ /** The account the credential acts for. */
184
+ readonly account: string;
185
+ /** What it may do: `mostra` for everything a sign-in may. */
186
+ readonly scope: readonly string[];
187
+ /** The credential's own stable name, which keys its instance link. */
188
+ readonly subject?: string;
189
+ }
190
+ /** The schema the server checks `accounts.authenticate`'s answer against. */
191
+ export declare const AuthenticatedCredential: z.ZodType<AuthenticatedCredential | null>;
192
+ /** A report from the shell's report control (`POST /a/{routeId}/_mostra/report`). */
193
+ export interface AbuseReport {
194
+ /** The reported route. */
195
+ readonly routeId: string;
196
+ /** The route's label. */
197
+ readonly label: string;
198
+ /** The artifact's own ID (as its manifest names it). */
199
+ readonly artifactId: string;
200
+ /** The hosted home. */
201
+ readonly home: string;
202
+ /** The version the reporter saw, when the shell knew it. */
203
+ readonly versionId?: string;
204
+ /** The reason the reporter chose. */
205
+ readonly reason: string;
206
+ /** What the reporter wrote, as text. */
207
+ readonly detail?: string;
208
+ /** When the report was made. */
209
+ readonly at: string;
210
+ }
211
+ /** What `abuse.pushed` receives after each version push, with read access to its client files. */
212
+ export interface PushedVersion {
213
+ /** The route the version was pushed to. */
214
+ readonly routeId: string;
215
+ /** The route's label. */
216
+ readonly label: string;
217
+ /** The artifact's own ID (as its manifest names it). */
218
+ readonly artifactId: string;
219
+ /** The hosted home. */
220
+ readonly home: string;
221
+ /** The pushed version. */
222
+ readonly versionId: string;
223
+ /** The version's `manifest.json`, parsed. */
224
+ readonly manifest: unknown;
225
+ /** Every client file's path (`client/…`). */
226
+ readonly files: readonly string[];
227
+ /** A client file's bytes, by its path in the listing. */
228
+ read(path: string): Promise<Uint8Array>;
229
+ }
230
+ /** `abuse.pushed`'s answer: quarantine the version, or nothing. */
231
+ export type PushedAnswer = {
232
+ readonly quarantine?: {
233
+ readonly reason: string;
234
+ };
235
+ } | undefined;
236
+ /** The schema the server checks `abuse.pushed`'s answer against. */
237
+ export declare const PushedAnswer: z.ZodType<PushedAnswer>;
238
+ /** What `policy.link` is asked about one link of one route. */
239
+ export interface LinkQuery {
240
+ /** The account that owns the route. */
241
+ readonly account: string;
242
+ /** Its hosted home. */
243
+ readonly home: string;
244
+ /** The route. */
245
+ readonly routeId: string;
246
+ /** The artifact's own ID (as its manifest names it). */
247
+ readonly artifactId: string;
248
+ /** The link, once it exists. */
249
+ readonly tokenId?: string;
250
+ }
251
+ /**
252
+ * Per link and artifact (D161): an interstitial before the page, the longest link lifetime and an
253
+ * idle expiry (durations such as `7d`), the after-submit line, the footer's wording (it can't be
254
+ * hidden on a public link), and the made-with mark.
255
+ */
256
+ export interface LinkPolicy extends Cacheable {
257
+ /** A page the shell shows before the artifact, once per browser and link; its message as text. */
258
+ readonly interstitial?: {
259
+ readonly kind: string;
260
+ readonly message?: string;
261
+ };
262
+ /** The longest a link may live from when it was minted. */
263
+ readonly maxTtl?: string;
264
+ /** A link unused for this long expires. */
265
+ readonly idleExpiry?: string;
266
+ /** The line after "Your answer was sent.", as text. */
267
+ readonly afterSubmit?: string;
268
+ /** The footer's wording in place of "Never enter passwords", as text. */
269
+ readonly footer?: string;
270
+ /** Whether the made-with mark shows, and where it links. */
271
+ readonly madeWith?: {
272
+ readonly show: boolean;
273
+ readonly href?: string;
274
+ };
275
+ }
276
+ /** The schema the server checks `policy.link`'s answer against. */
277
+ export declare const LinkPolicy: z.ZodType<LinkPolicy>;
278
+ /**
279
+ * How Mostra behaves in one chat host (D160): how a page renders there (an MCP App resource, or
280
+ * the hosted link), and what a reached limit may say (`limit-reached` only, or the operator's
281
+ * message).
282
+ */
283
+ export interface ChatHostPolicy {
284
+ /** `app`: through the MCP Apps resource; `link`: the hosted link only. */
285
+ readonly render?: "app" | "link";
286
+ /** What a reached limit may say there. */
287
+ readonly quota?: "limit-reached" | "message";
288
+ }
289
+ /** The schema of the `ChatHostPolicy` type, for configuration and `policy.chatHost`. */
290
+ export declare const ChatHostPolicy: z.ZodType<ChatHostPolicy>;
291
+ /**
292
+ * `routing.resolve`'s answer for an exact `Host` the server doesn't serve by itself (any host but
293
+ * a configured user-content domain's apex and its routes' labels):
294
+ *
295
+ * - `shell`: the host shows the hosted shell (`/a/<routeId>`) for one home's routes, whose frames
296
+ * are served on `<route label>.<domain>`. `domain` is a configured user-content domain, or one
297
+ * the operator supplies (an organization's own, whose TLS the operator's edge terminates for the
298
+ * host and every label under `domain`); the server serves those labels once the host is
299
+ * recorded, without asking again.
300
+ * - `route`: the host shows the shell of one route only (`/a/<routeId>`), with its frames on its
301
+ * label under the active domain: a chosen, readable name.
302
+ * - `null`: nothing is served (421).
303
+ *
304
+ * A host the operator supplies is recorded like the server's own labels, bound to its home
305
+ * forever: never issued to another home, so no origin's storage passes between tenants (D165).
306
+ */
307
+ export type RoutingAnswer = ({
308
+ readonly shell: {
309
+ readonly domain: string;
310
+ readonly home: string;
311
+ };
312
+ } & Cacheable) | ({
313
+ readonly route: {
314
+ readonly home: string;
315
+ readonly routeId: string;
316
+ };
317
+ } & Cacheable) | null;
318
+ /** The schema the server checks `routing.resolve`'s answer against. */
319
+ export declare const RoutingAnswer: z.ZodType<RoutingAnswer>;
320
+ /** The schema of `routing.linkHost`'s answer: a shell host, or `null` for the active domain. */
321
+ export declare const LinkHost: z.ZodType<string | null>;
322
+ /** The kind of an outbound event. */
323
+ export type OperatorEventKind = "submission.accepted" | "version.pushed" | "run.ended" | "roster.completed" | (string & {});
324
+ /**
325
+ * One outbound event, delivered at least once with a stable `eventId`. `payload`:
326
+ * `submission.accepted` carries the submission's `Results` (INTERFACES §8, the `Results` type of `@mostra/protocol`); `version.pushed`
327
+ * `{ versionId, number }`; `run.ended` `{ runId, action, status }`; `roster.completed` is WP-31's.
328
+ * `label` is the route's label, so an operator running several servers behind one front learns
329
+ * which serves which label (WP-30).
330
+ */
331
+ export interface OperatorEvent {
332
+ /** Stable across retries. */
333
+ readonly eventId: string;
334
+ /** What happened. */
335
+ readonly kind: OperatorEventKind;
336
+ /** The account that owns the route. */
337
+ readonly account: string;
338
+ /** Its hosted home. */
339
+ readonly home: string;
340
+ /** The route. */
341
+ readonly routeId: string;
342
+ /** The route's label. */
343
+ readonly label: string;
344
+ /** The artifact's own ID (as its manifest names it). */
345
+ readonly artifactId: string;
346
+ /** When it happened. */
347
+ readonly at: string;
348
+ /** What the kind carries. */
349
+ readonly payload: unknown;
350
+ }
351
+ /** The ports an operator module implements; each is optional, with the default named. */
352
+ export interface OperatorPorts {
353
+ /** Allows or refuses an operation for an account. Default: allow. */
354
+ readonly limits?: {
355
+ check(q: LimitQuery): Promise<LimitAnswer>;
356
+ };
357
+ /** Counters in batches, at least once. Default: discard. */
358
+ readonly metering?: {
359
+ record(batch: MeterBatch): Promise<void>;
360
+ };
361
+ /**
362
+ * Identity providers beside the configured ones, asked at each sign-in so the set can change
363
+ * while the server runs (WP-30). Default: none.
364
+ */
365
+ readonly identity?: {
366
+ providers(): Promise<readonly IdentityProvider[]> | readonly IdentityProvider[];
367
+ };
368
+ /**
369
+ * Sign-in identities to accounts, a first sign-in step, and credentials the operator issued.
370
+ * Default: the server's own accounts, no step, no outside credential.
371
+ */
372
+ readonly accounts?: {
373
+ resolve(identity: SignInIdentity, context: {
374
+ readonly steps: number;
375
+ }): Promise<AccountResolution>;
376
+ authenticate?(bearer: string, context: {
377
+ readonly resource: CredentialResource;
378
+ }): Promise<AuthenticatedCredential | null>;
379
+ status?(account: string): Promise<"active" | "suspended">;
380
+ };
381
+ /** Reports and the after-push hook. Default: nothing. */
382
+ readonly abuse?: {
383
+ report(r: AbuseReport): Promise<void>;
384
+ pushed?(v: PushedVersion): Promise<PushedAnswer>;
385
+ };
386
+ /** Per link and per chat host. Default: nothing beyond configuration. */
387
+ readonly policy?: {
388
+ link(q: LinkQuery): Promise<LinkPolicy>;
389
+ chatHost?(client: {
390
+ readonly name: string;
391
+ readonly redirectHost?: string;
392
+ }): Promise<ChatHostPolicy | null>;
393
+ };
394
+ /**
395
+ * Hosts the operator supplies, and the host a new link is minted on. Default: the server's own
396
+ * labels, and links on the active domain.
397
+ */
398
+ readonly routing?: {
399
+ resolve(host: string): Promise<RoutingAnswer>;
400
+ /**
401
+ * The shell host a new link of this route is minted on (one `resolve` answers `shell` or
402
+ * `route` for), or `null` for the active domain (WP-30). A link keeps the host it was minted
403
+ * on (D137).
404
+ */
405
+ linkHost?(q: {
406
+ readonly account: string;
407
+ readonly home: string;
408
+ readonly routeId: string;
409
+ }): Promise<string | null>;
410
+ };
411
+ /** Outbound events, at least once with stable IDs. Default: discard. */
412
+ readonly events?: {
413
+ deliver(e: OperatorEvent): Promise<void>;
414
+ };
415
+ /** Reserved for WP-31 (D121, D165 item 16); no mailer ships. */
416
+ readonly invitations?: unknown;
417
+ }
418
+ /** A hosted route, or one version of it: what the handle's quarantine and release act on. */
419
+ export type RouteTarget = {
420
+ readonly routeId: string;
421
+ } | {
422
+ readonly routeId: string;
423
+ readonly versionId: string;
424
+ };
425
+ /**
426
+ * What the server gives its operator module (INTERFACES §18.6). Every target names a hosted route.
427
+ * Each call is durable when it resolves.
428
+ */
429
+ export interface ServerHandle {
430
+ /** The operator boundary's revision this server speaks. */
431
+ readonly revision: string;
432
+ /** The server's API origin. */
433
+ readonly apiOrigin: string;
434
+ /** A neutral "under review" page from the shell; data kept; `release` restores it. */
435
+ quarantine(target: RouteTarget, reason: string): Promise<void>;
436
+ /** Ends a quarantine. */
437
+ release(target: RouteTarget): Promise<void>;
438
+ /** Views keep working; submissions and relayed actions are refused; only the operator resumes. */
439
+ pause(routeId: string, reason: string): Promise<void>;
440
+ /** Ends an operator's pause (and an owner's, too). */
441
+ resume(routeId: string): Promise<void>;
442
+ /** Refuses the home's bindings, pushes, links and pages until `resumeHome`. */
443
+ suspendHome(home: string, reason: string): Promise<void>;
444
+ /** Ends a suspension. */
445
+ resumeHome(home: string): Promise<void>;
446
+ /** Revokes every link of a route; answers how many were live. */
447
+ revokeLinks(routeId: string): Promise<number>;
448
+ /** Revokes one link (410 from then on). */
449
+ revokeLink(tokenId: string): Promise<void>;
450
+ /** Closes the home and refuses to reopen it, to move it between data directories. */
451
+ drainHome(home: string): Promise<void>;
452
+ /** Serves a drained home again. */
453
+ releaseHome(home: string): Promise<void>;
454
+ /** A restore from a backup: rotates the home's incarnation before it serves anything. */
455
+ restored(home: string): Promise<void>;
456
+ /** Deletion: explicit, never part of another action. The route's label is never issued again. */
457
+ remove(routeId: string): Promise<void>;
458
+ }
459
+ /** An operator module's default export. */
460
+ export type OperatorModule = (server: ServerHandle) => OperatorPorts | Promise<OperatorPorts>;
461
+ /** Types an operator module's default export; returns it unchanged. */
462
+ export declare function defineOperator(module: OperatorModule): OperatorModule;
463
+ //#endregion
464
+ //# sourceMappingURL=operator.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"operator.d.ts","names":[],"sources":["../src/operator.ts"],"mappings":"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"}