@mostra/runtime 0.11.0 → 0.13.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 (50) hide show
  1. package/dist/bin.js +930 -458
  2. package/dist/bin.js.map +1 -1
  3. package/dist/index.js +1 -1
  4. package/dist/{instance-DCiUHvgZ.js → instance-D5gh-sMM.js} +1231 -46
  5. package/dist/instance-D5gh-sMM.js.map +1 -0
  6. package/dist/reference/cli.md +112 -2
  7. package/dist/reference/diagnostics.json +29 -2
  8. package/dist/reference/errors/MOSTRA_REMOTE_QUEUE_FULL.md +2 -2
  9. package/dist/reference/errors/MOSTRA_TEAM_PRESENCE_RATE_LIMITED.md +23 -0
  10. package/dist/reference/errors/MOSTRA_TEAM_ROSTER_POLICY.md +23 -0
  11. package/dist/reference/errors/MOSTRA_TEAM_ROSTER_TOO_LARGE.md +23 -0
  12. package/dist/reference/self-hosting.md +1 -1
  13. package/dist/skill/SKILL.md +5 -3
  14. package/dist/skill/references/answers.md +3 -1
  15. package/dist/skill/references/mcp.md +2 -2
  16. package/dist/skill/references/teams.md +78 -0
  17. package/package.json +6 -6
  18. package/src/actions/index.ts +5 -2
  19. package/src/gateway/actions.ts +6 -1
  20. package/src/gateway/browser.ts +84 -1
  21. package/src/gateway/capabilities.ts +5 -1
  22. package/src/gateway/index.ts +43 -1
  23. package/src/gateway/team.ts +181 -0
  24. package/src/instance/index.ts +2 -1
  25. package/src/interaction/ephemeral.ts +21 -0
  26. package/src/interaction/events.ts +17 -0
  27. package/src/interaction/index.ts +265 -20
  28. package/src/interaction/roster.ts +585 -0
  29. package/src/interaction/team.ts +426 -0
  30. package/src/interaction/wait.ts +150 -0
  31. package/src/ledger/migrations.ts +44 -0
  32. package/src/link/hosted.ts +14 -3
  33. package/src/link/manager.ts +31 -1
  34. package/src/server/api.ts +1 -1
  35. package/src/server/auth.ts +83 -16
  36. package/src/server/authorize.ts +27 -4
  37. package/src/server/config.ts +53 -0
  38. package/src/server/directory.ts +73 -0
  39. package/src/server/feed.ts +89 -3
  40. package/src/server/hosted-pages.ts +19 -6
  41. package/src/server/hosted.ts +108 -49
  42. package/src/server/index.ts +72 -15
  43. package/src/server/metering.ts +117 -12
  44. package/src/server/operator.ts +87 -28
  45. package/src/server/providers.ts +61 -9
  46. package/src/server/relay.ts +258 -107
  47. package/src/share/index.ts +50 -2
  48. package/src/verify/index.ts +7 -0
  49. package/src/verify/runner.ts +5 -1
  50. package/dist/instance-DCiUHvgZ.js.map +0 -1
@@ -5,9 +5,10 @@
5
5
  * schemas; a call that throws, times out or answers what the schema refuses counts as no answer,
6
6
  * and each port's caller says what no answer means (`limits`: operations that create fail closed,
7
7
  * viewer input proceeds; `routing`: nothing is served; `policy`: nothing is added). Outbound
8
- * deliveries (`metering`, `events`) are kept in the directory's `outbound` table and retried with
9
- * backoff until the operator takes them, at least once and idempotent by their IDs, across
10
- * restarts.
8
+ * deliveries (`metering`, `events`, `invitations`) are kept in the directory's `outbound` table and
9
+ * retried with backoff until the operator takes them, at least once and idempotent by their IDs,
10
+ * across restarts. An invitation is kept by its link's token and handed over with the link built
11
+ * then, so the queue never holds a capability secret (D168).
11
12
  *
12
13
  * Without an operator module every port is its no-op default, and this module does nothing but
13
14
  * answer "allowed".
@@ -21,6 +22,7 @@ import {
21
22
  ChatHostPolicy as ChatHostPolicySchema,
22
23
  type CredentialResource,
23
24
  type IdentityProvider,
25
+ type Invitation,
24
26
  LimitAnswer,
25
27
  type LimitQuery,
26
28
  LinkHost,
@@ -70,6 +72,7 @@ export interface Operator {
70
72
  readonly linkHost: boolean;
71
73
  readonly events: boolean;
72
74
  readonly identity: boolean;
75
+ readonly invitations: boolean;
73
76
  };
74
77
  limit(q: LimitQuery): Promise<LimitVerdict>;
75
78
  linkPolicy(q: LinkQuery): Promise<LinkPolicy>;
@@ -95,7 +98,8 @@ export interface Operator {
95
98
  enqueue(
96
99
  item:
97
100
  | { readonly port: "events"; readonly event: OperatorEvent }
98
- | { readonly port: "metering"; readonly batch: MeterBatch },
101
+ | { readonly port: "metering"; readonly batch: MeterBatch }
102
+ | { readonly port: "invitations"; readonly invitation: QueuedInvitation },
99
103
  ): void;
100
104
  /** Delivers what waits now (tests; the dispatcher does it on its own). */
101
105
  flush(): Promise<void>;
@@ -112,8 +116,20 @@ export interface OperatorOptions {
112
116
  readonly now?: () => number;
113
117
  /** How often the outbound dispatcher looks for work; tests shorten it. */
114
118
  readonly dispatchMs?: number;
119
+ /**
120
+ * A personal link's URL, built from its token when an invitation is handed over (D168), or
121
+ * `undefined` when the link no longer works (revoked, expired, replaced): the queue never holds
122
+ * the URL, whose fragment is the link's secret.
123
+ */
124
+ readonly invitationLink?: (
125
+ home: string,
126
+ tokenId: string,
127
+ ) => Promise<{ readonly url: string; readonly expiresAt?: string } | undefined>;
115
128
  }
116
129
 
130
+ /** An invitation as the outbound queue keeps it: its link's token, never the link (D168). */
131
+ export type QueuedInvitation = Omit<Invitation, "url" | "expiresAt"> & { readonly tokenId: string };
132
+
117
133
  function configInvalid(message: string): RpcError {
118
134
  return new RpcError(createDiagnostic("MOSTRA_REMOTE_CONFIG_INVALID", { message }));
119
135
  }
@@ -234,11 +250,34 @@ export async function loadOperator(options: OperatorOptions): Promise<Operator>
234
250
  }): Promise<void> => {
235
251
  const payload = JSON.parse(row.payload_json) as unknown;
236
252
  try {
237
- await within(OPERATOR_TIME_LIMITS.outbound, () =>
238
- row.port === "events"
239
- ? ports.events?.deliver(payload as OperatorEvent)
240
- : ports.metering?.record(payload as MeterBatch),
241
- );
253
+ if (row.port === "invitations") {
254
+ const { tokenId, ...invitation } = payload as QueuedInvitation;
255
+ // Building the link opens its home: bounded like the hand-over, so a home that hangs
256
+ // can't stall the dispatcher (Opus review 4).
257
+ const link = await within(OPERATOR_TIME_LIMITS.outbound, () =>
258
+ options.invitationLink?.(invitation.home, tokenId),
259
+ );
260
+ if (link === undefined) {
261
+ // The link stopped working before it was handed over: inviting with it would mail a
262
+ // dead link, and a later one gets an invitation of its own.
263
+ directory.write((db) => db.run("DELETE FROM outbound WHERE id = ?", row.id));
264
+ log.info("operator.invitation_dropped", { invitationId: invitation.invitationId });
265
+ return;
266
+ }
267
+ await within(OPERATOR_TIME_LIMITS.outbound, () =>
268
+ ports.invitations?.send({
269
+ ...invitation,
270
+ url: link.url,
271
+ ...(link.expiresAt !== undefined ? { expiresAt: link.expiresAt } : {}),
272
+ }),
273
+ );
274
+ } else {
275
+ await within(OPERATOR_TIME_LIMITS.outbound, () =>
276
+ row.port === "events"
277
+ ? ports.events?.deliver(payload as OperatorEvent)
278
+ : ports.metering?.record(payload as MeterBatch),
279
+ );
280
+ }
242
281
  directory.write((db) => db.run("DELETE FROM outbound WHERE id = ?", row.id));
243
282
  } catch (error) {
244
283
  const delay = Math.min(OUTBOUND_MAX_BACKOFF_MS, 1_000 * 2 ** Math.min(row.attempts, 20));
@@ -263,23 +302,31 @@ export async function loadOperator(options: OperatorOptions): Promise<Operator>
263
302
  await Promise.resolve();
264
303
  try {
265
304
  for (;;) {
266
- // The oldest rows of each port, due or not: a port whose oldest delivery waits for its
267
- // retry waits whole, so an operator sees a home's events in the order they happened.
268
- const rows = directory.read((db) =>
269
- (["events", "metering"] as const).flatMap((port) =>
270
- db.all<{
271
- id: string;
272
- port: string;
273
- payload_json: string;
274
- attempts: number;
275
- next_attempt_at: string;
276
- }>(
305
+ // The oldest rows of each ordered port, due or not: a port whose oldest delivery waits
306
+ // for its retry waits whole, so an operator sees a home's events in the order they
307
+ // happened. Invitations have no order: each waits for its own retry and none holds
308
+ // another back, so one home that can't build its links never stops the server's
309
+ // other invitations (Opus review 4).
310
+ const due = new Date(now()).toISOString();
311
+ type Row = {
312
+ id: string;
313
+ port: string;
314
+ payload_json: string;
315
+ attempts: number;
316
+ next_attempt_at: string;
317
+ };
318
+ const rows = directory.read((db) => [
319
+ ...(["events", "metering"] as const).flatMap((port) =>
320
+ db.all<Row>(
277
321
  "SELECT id, port, payload_json, attempts, next_attempt_at FROM outbound WHERE port = ? ORDER BY rowid LIMIT 50",
278
322
  port,
279
323
  ),
280
324
  ),
281
- );
282
- const due = new Date(now()).toISOString();
325
+ ...db.all<Row>(
326
+ "SELECT id, port, payload_json, attempts, next_attempt_at FROM outbound WHERE port = 'invitations' AND next_attempt_at <= ? ORDER BY rowid LIMIT 50",
327
+ due,
328
+ ),
329
+ ]);
283
330
  if (rows.every((row) => row.next_attempt_at > due)) return;
284
331
  const blocked = new Set<string>();
285
332
  let delivered = 0;
@@ -294,8 +341,9 @@ export async function loadOperator(options: OperatorOptions): Promise<Operator>
294
341
  const still = directory.read((db) =>
295
342
  db.get<{ attempts: number }>("SELECT attempts FROM outbound WHERE id = ?", row.id),
296
343
  );
297
- if (still && still.attempts > before) blocked.add(row.port);
298
- else delivered += 1;
344
+ if (still && still.attempts > before) {
345
+ if (row.port !== "invitations") blocked.add(row.port);
346
+ } else delivered += 1;
299
347
  }
300
348
  if (delivered === 0) return;
301
349
  }
@@ -306,7 +354,7 @@ export async function loadOperator(options: OperatorOptions): Promise<Operator>
306
354
  return dispatching;
307
355
  };
308
356
  const timer =
309
- ports.events || ports.metering
357
+ ports.events || ports.metering || ports.invitations
310
358
  ? setInterval(() => void dispatch(), options.dispatchMs ?? 1_000)
311
359
  : undefined;
312
360
  timer?.unref();
@@ -324,6 +372,7 @@ export async function loadOperator(options: OperatorOptions): Promise<Operator>
324
372
  linkHost: typeof ports.routing?.linkHost === "function",
325
373
  events: typeof ports.events?.deliver === "function",
326
374
  identity: typeof ports.identity?.providers === "function",
375
+ invitations: typeof ports.invitations?.send === "function",
327
376
  };
328
377
 
329
378
  return {
@@ -474,9 +523,19 @@ export async function loadOperator(options: OperatorOptions): Promise<Operator>
474
523
  },
475
524
 
476
525
  enqueue(item) {
477
- if (item.port === "events" ? !has.events : !has.metering) return;
478
- const id = item.port === "events" ? item.event.eventId : item.batch.batchId;
479
- const payload = item.port === "events" ? item.event : item.batch;
526
+ if (!has[item.port]) return;
527
+ const id =
528
+ item.port === "events"
529
+ ? item.event.eventId
530
+ : item.port === "metering"
531
+ ? item.batch.batchId
532
+ : item.invitation.invitationId;
533
+ const payload =
534
+ item.port === "events"
535
+ ? item.event
536
+ : item.port === "metering"
537
+ ? item.batch
538
+ : item.invitation;
480
539
  directory.write((db) =>
481
540
  db.run(
482
541
  "INSERT OR IGNORE INTO outbound (id, port, payload_json, attempts, next_attempt_at) VALUES (?, ?, ?, 0, ?)",
@@ -5,9 +5,10 @@
5
5
  *
6
6
  * - `oidc`: any OpenID Connect provider, by its issuer's discovery document; the authorization
7
7
  * code flow with PKCE (S256) and a nonce, and the ID token checked (signature, issuer, audience,
8
- * expiry, nonce) by `openid-client`.
8
+ * expiry, nonce) by `openid-client`; the claims its entry names (`claims`) go into `facts`.
9
9
  * - `github`: GitHub's OAuth web flow with PKCE, then `GET /user` for the account's stable ID, its
10
- * login and name, and its age (`facts.createdAt`) for an operator's policy.
10
+ * login and name, and for an operator's policy its age (`facts.createdAt`) and public counts
11
+ * (`facts.publicRepos`, `publicGists`, `followers`).
11
12
  * - `development`: a page that asks for a name and trusts it, for tests and a self-hoster's first
12
13
  * run; its names are never shown as verified.
13
14
  *
@@ -24,7 +25,7 @@ import type {
24
25
  } from "@mostra/protocol/operator";
25
26
  import * as oidc from "openid-client";
26
27
  import type { Environment, Log } from "../log.ts";
27
- import type { IdentityProviderConfig } from "./config.ts";
28
+ import { configuredVerifier, type IdentityProviderConfig } from "./config.ts";
28
29
 
29
30
  /** How long a provider's discovery, token exchange or user lookup may take. */
30
31
  const PROVIDER_TIMEOUT_MS = 8_000;
@@ -36,11 +37,17 @@ const GITHUB = {
36
37
  user: "https://api.github.com/user",
37
38
  } as const;
38
39
 
39
- /** A built-in provider: the port's shape, and whether its names are verified. */
40
+ /** A built-in provider: the port's shape, its kind, and its verifier (all but `development`). */
40
41
  export interface BuiltInProvider extends IdentityProvider {
41
42
  readonly kind: IdentityProviderConfig["kind"];
42
- /** Whether the names it gives are verified by someone (all but `development`). */
43
- readonly verifies: boolean;
43
+ }
44
+
45
+ /** The `verifies` of a configured provider: the label its verified names carry, if any. */
46
+ function verifiesOf(config: IdentityProviderConfig): {
47
+ readonly verifies?: { readonly label: string };
48
+ } {
49
+ const label = configuredVerifier(config);
50
+ return label === undefined ? {} : { verifies: { label } };
44
51
  }
45
52
 
46
53
  function invalid(message: string): RpcError {
@@ -69,6 +76,36 @@ async function timedFetch(url: string, init: RequestInit): Promise<Response> {
69
76
  return fetch(url, { ...init, signal: AbortSignal.timeout(PROVIDER_TIMEOUT_MS) });
70
77
  }
71
78
 
79
+ /** The longest a chosen claim's value may be, as JSON: a policy reads names, not documents. */
80
+ const CLAIM_MAX = 4_096;
81
+
82
+ /**
83
+ * The ID token's claims a configuration chose (`claims`), as `facts` under their own names: each
84
+ * one present whose value is JSON of at most 4 KiB (MT-03). A claim the token doesn't carry is left
85
+ * out; with none chosen, nothing is added.
86
+ */
87
+ function chosen(
88
+ claims: Readonly<Record<string, unknown>>,
89
+ names: readonly string[] | undefined,
90
+ ): { readonly facts: Record<string, unknown> } | undefined {
91
+ if (names === undefined) return undefined;
92
+ const facts: Record<string, unknown> = {};
93
+ for (const name of names) {
94
+ if (!Object.hasOwn(claims, name)) continue;
95
+ const value = claims[name];
96
+ const text = JSON.stringify(value);
97
+ if (text === undefined || text.length > CLAIM_MAX) continue;
98
+ // A key of its own, whatever the name (`__proto__` would set the prototype by assignment).
99
+ Object.defineProperty(facts, name, {
100
+ value: JSON.parse(text) as unknown,
101
+ enumerable: true,
102
+ writable: true,
103
+ configurable: true,
104
+ });
105
+ }
106
+ return Object.keys(facts).length > 0 ? { facts } : undefined;
107
+ }
108
+
72
109
  /** The OpenID Connect adapter. Discovery happens at the first sign-in and is kept. */
73
110
  function oidcProvider(config: IdentityProviderConfig, env: Environment): BuiltInProvider {
74
111
  if (config.issuer === undefined || config.clientId === undefined) {
@@ -106,7 +143,7 @@ function oidcProvider(config: IdentityProviderConfig, env: Environment): BuiltIn
106
143
  id: config.id,
107
144
  label: config.label ?? config.id,
108
145
  kind: "oidc",
109
- verifies: true,
146
+ ...verifiesOf(config),
110
147
  async authorize(state: string, pkce: SignInPkce, context: SignInContext) {
111
148
  const url = oidc.buildAuthorizationUrl(await configuration(), {
112
149
  redirect_uri: context.redirectUri,
@@ -143,12 +180,18 @@ function oidcProvider(config: IdentityProviderConfig, env: Environment): BuiltIn
143
180
  ? { emailVerified: claims["email_verified"] }
144
181
  : {}),
145
182
  ...(name !== undefined ? { name } : {}),
183
+ ...(chosen(claims, config.claims) ?? {}),
146
184
  };
147
185
  return identity;
148
186
  },
149
187
  };
150
188
  }
151
189
 
190
+ /** A count GitHub gave, under its name in `facts`: a non-negative integer, or nothing. */
191
+ function count(name: string, value: unknown): Record<string, number> {
192
+ return Number.isSafeInteger(value) && (value as number) >= 0 ? { [name]: value as number } : {};
193
+ }
194
+
152
195
  /** The GitHub adapter: an OAuth app's web flow with PKCE (VERIFIED_FACTS, WP-30). */
153
196
  function githubProvider(config: IdentityProviderConfig, env: Environment): BuiltInProvider {
154
197
  if (config.clientId === undefined) {
@@ -169,7 +212,7 @@ function githubProvider(config: IdentityProviderConfig, env: Environment): Built
169
212
  id: config.id,
170
213
  label: config.label ?? "GitHub",
171
214
  kind: "github",
172
- verifies: true,
215
+ ...verifiesOf(config),
173
216
  authorize(state, pkce, context) {
174
217
  const url = new URL(endpoints.authorize);
175
218
  url.searchParams.set("client_id", config.clientId as string);
@@ -221,6 +264,9 @@ function githubProvider(config: IdentityProviderConfig, env: Environment): Built
221
264
  name?: string | null;
222
265
  email?: string | null;
223
266
  created_at?: string;
267
+ public_repos?: number;
268
+ public_gists?: number;
269
+ followers?: number;
224
270
  };
225
271
  if (!user.ok || typeof found.id !== "number") {
226
272
  throw new Error(`GitHub's user lookup failed (${user.status}).`);
@@ -231,9 +277,16 @@ function githubProvider(config: IdentityProviderConfig, env: Environment): Built
231
277
  subject: String(found.id),
232
278
  ...(typeof found.email === "string" ? { email: found.email } : {}),
233
279
  name: found.name ?? found.login ?? String(found.id),
280
+ // What the same answer tells an operator's policy (an account's age and its public
281
+ // counts, so a fresh, empty account is told from an established one with no other
282
+ // request inside `accounts.resolve`'s time limit, MT-03); a count GitHub didn't give is
283
+ // left out rather than guessed.
234
284
  facts: {
235
285
  login: found.login ?? null,
236
286
  ...(found.created_at !== undefined ? { createdAt: found.created_at } : {}),
287
+ ...count("publicRepos", found.public_repos),
288
+ ...count("publicGists", found.public_gists),
289
+ ...count("followers", found.followers),
237
290
  },
238
291
  };
239
292
  },
@@ -249,7 +302,6 @@ function developmentProvider(config: IdentityProviderConfig, apiOrigin: string):
249
302
  id: config.id,
250
303
  label: config.label ?? "Development sign-in",
251
304
  kind: "development",
252
- verifies: false,
253
305
  authorize(state) {
254
306
  const url = new URL(`${apiOrigin}/signin/${config.id}/name`);
255
307
  url.searchParams.set("state", state);