@bom-pi/core 0.2.6 → 0.2.7

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 (2) hide show
  1. package/package.json +1 -1
  2. package/src/relay-boundary.ts +112 -24
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bom-pi/core",
3
- "version": "0.2.6",
3
+ "version": "0.2.7",
4
4
  "description": "Core pairing machinery for Bom Pi: ceremonies, transports, durable stores",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -200,9 +200,13 @@ export interface RelayOperationPolicyEntry {
200
200
  * session. Adding an entry is a reviewed act with its own negative tests (SEC-12); no
201
201
  * wildcards, no free-string allowlists. */
202
202
  /** One widened row's caps vocabulary: bounded, static names — the family's read view. */
203
- const familyRow = (audience: string, caps: string) => ({
203
+ const familyRow = (
204
+ audience: string,
205
+ caps: string,
206
+ methods: readonly ("GET" | "POST")[] = ["GET"],
207
+ ) => ({
204
208
  audience,
205
- methods: ["GET"] as const,
209
+ methods,
206
210
  principalClass: "remote-session" as const,
207
211
  caps: [caps] as readonly string[],
208
212
  actorField: "actor" as const,
@@ -258,6 +262,29 @@ export const RELAY_OPERATION_POLICY: readonly RelayOperationPolicyEntry[] = [
258
262
  // (REL-6 shape: cursor + replay window + the honest snapshot signal), one GET row served
259
263
  // by the ring (`relay-event-ring.ts`) through the same single-sourced funnel rows.
260
264
  familyRow("app-data:event-poll", "events-view"),
265
+ // ADR-20 wave 4, family 1 of 3 (run control): the writes that steer a run on the looked-at
266
+ // machine — submit a message into its session, answer that session's tool approval, abort
267
+ // the run. POST-only rows, same discipline as every row: exact-pair against the registry's
268
+ // own operations, remote-session principal, explicit verified actor; the session-admin and
269
+ // catalog families and the whole §11 deny-list stay out until their own reviewed rows.
270
+ familyRow("app-data:conversation-submit", "conversation-run", ["POST"]),
271
+ familyRow("app-data:approval-answer", "conversation-run", ["POST"]),
272
+ familyRow("app-data:conversation-abort", "conversation-run", ["POST"]),
273
+ // ADR-20 wave 4, family 2 of 3 (session admin): fork a session of the looked-at machine,
274
+ // rename it, put it away or bring it back (the archived flag `updateSession` owns). The
275
+ // family's move (cwd) and hard-delete halves have no op of their own — configure is a
276
+ // wider write than "move" and the bundle archive/delete routes are untyped — so they stay
277
+ // out as recorded gaps, refusing naming the host, until their own reviewed rows exist.
278
+ familyRow("app-data:conversation-fork", "sessions-admin", ["POST"]),
279
+ familyRow("app-data:session-update", "sessions-admin", ["POST"]),
280
+ // ADR-20 wave 4, family 3 of 3 (catalog): the owner's own settings and people writes on the
281
+ // looked-at machine — one setting at a time (the op's own rule), a person's access, a person
282
+ // removed. The family's providers half has NO typed operation to exact-pair against (the
283
+ // raw /api routes only, and login/logout is credential territory by §11), so it stays out as
284
+ // a recorded gap, refusing naming the host, until an op exists for a later wave to review.
285
+ familyRow("app-data:settings-set", "catalog-admin", ["POST"]),
286
+ familyRow("app-data:people-set-access", "catalog-admin", ["POST"]),
287
+ familyRow("app-data:people-remove", "catalog-admin", ["POST"]),
261
288
  ];
262
289
 
263
290
  /** Machine-readable, bounded policy denials (SEC-14 typed verdicts). None of these names
@@ -377,24 +404,33 @@ export type RelaySurfaceName =
377
404
  | "spend-summary"
378
405
  | "running-list"
379
406
  | "subagents-board-read"
380
- | "event-poll";
407
+ | "event-poll"
408
+ | "conversation-submit"
409
+ | "approval-answer"
410
+ | "conversation-abort"
411
+ | "conversation-fork"
412
+ | "session-update"
413
+ | "settings-set"
414
+ | "people-set-access"
415
+ | "people-remove";
381
416
 
382
417
  /** The frozen M4 v1 admitted surface (the canned pilot lane's set): exactly the two
383
418
  * read-only session operations. Byte-identical default for every existing consumer. */
384
- const ADMITTED_SURFACES = new Map<string, RelaySurfaceName>([
385
- ["app-data:session-status", "session-status"],
386
- ["app-data:session-ping", "session-ping"],
419
+ const ADMITTED_SURFACES = new Map<string, RelaySurfaceAdmission>([
420
+ ["app-data:session-status", { surface: "session-status", method: "GET" }],
421
+ ["app-data:session-ping", { surface: "session-ping", method: "GET" }],
387
422
  ]);
388
423
 
389
- /** D3 backend gap (2): the family-by-family WIDENED read/view surface for the remote
390
- * (secure) lane — one explicit GET row per family operation of the 12 PARITY families'
391
- * read-only subset, deny-first: nothing is admitted that is not an exact row here, every
392
- * effect/write family stays out, and every row is off the §11 negative lists (asserted by
393
- * test). This table is INERT until a boundary is constructed with surfaceSet "remote-v2";
424
+ /** D3 backend gap (2): the family-by-family WIDENED surface for the remote
425
+ * (secure) lane — one explicit row per family operation of the 12 PARITY families'
426
+ * read/view subset (GET) and, from W4, the reviewed write families (POST), deny-first:
427
+ * nothing is admitted that is not an exact (audience, method) row here, every unlisted
428
+ * family stays out, and every row is off the §11 negative lists (asserted by test).
429
+ * This table is INERT until a boundary is constructed with surfaceSet "remote-v2";
394
430
  * the default boundary keeps the v1 two. */
395
431
  export const RELAY_REMOTE_SURFACE_V2: readonly {
396
432
  audience: string;
397
- method: "GET";
433
+ method: "GET" | "POST";
398
434
  surface: RelaySurfaceName;
399
435
  /** The row's answer carries money as integer cents: the wire's canonical value is a
400
436
  * nonnegative safe integer, and usage costs are USD floats. The funnel row converts
@@ -499,13 +535,66 @@ export const RELAY_REMOTE_SURFACE_V2: readonly {
499
535
  },
500
536
  // ADR-20 wave 3 (the stream lane, as the approved batch's poll option — the W3 packet's
501
537
  // §1 choice): the event poll the lane runs over the existing request/response channel.
502
- // GET-only like every row; the ring's answer carries no money and its `full` rides 0/1.
538
+ // GET-only like every read row; the ring's answer carries no money and its `full` rides 0/1.
503
539
  { audience: "app-data:event-poll", method: "GET", surface: "event-poll" },
540
+ // ADR-20 wave 4, run control (the looked-at machine's run is steerable from here): three
541
+ // POST rows, one per registry operation the family owns — submit into the session, answer
542
+ // its tool approval, abort the run. Each row is an exact (audience, method) pair like every
543
+ // other: the read rows above stay GET and refuse a POST, these refuse a GET, and nothing
544
+ // about the §11 deny-list moved (approval-path/credential audiences deny by category
545
+ // before this table is ever consulted). The bodies ride the same sealed lane and its
546
+ // single-frame bound (`MAX_RELAY_REQUEST_BODY_B64`); the answers carry no money.
547
+ {
548
+ audience: "app-data:conversation-submit",
549
+ method: "POST",
550
+ surface: "conversation-submit",
551
+ },
552
+ { audience: "app-data:approval-answer", method: "POST", surface: "approval-answer" },
553
+ {
554
+ audience: "app-data:conversation-abort",
555
+ method: "POST",
556
+ surface: "conversation-abort",
557
+ },
558
+ // ADR-20 wave 4, family 2 (session admin): two more POST rows — fork a session of the
559
+ // looked-at machine (the operation answers the NEW conversation's id) and update one
560
+ // (rename, or the archived flag that puts it away and brings it back). Exact pairs like
561
+ // every row; the bodies ride the same sealed lane and its single-frame bound; the answers
562
+ // carry no money. Move (cwd) and hard delete have no typed operation to point at — recorded
563
+ // gaps in the wave's ledger, refused here until a reviewed row exists for them.
564
+ {
565
+ audience: "app-data:conversation-fork",
566
+ method: "POST",
567
+ surface: "conversation-fork",
568
+ },
569
+ { audience: "app-data:session-update", method: "POST", surface: "session-update" },
570
+ // ADR-20 wave 4, family 3 (catalog): three more POST rows — one setting of the looked-at
571
+ // machine changed at a time, a person's access changed, a person removed. Exact pairs like
572
+ // every row; the bodies ride the same sealed lane and its single-frame bound; the answers
573
+ // carry no money (settings-set/people-remove answer {ok}, people-set-access the people list).
574
+ // The providers half of the family has no typed operation to point at — a recorded gap in the
575
+ // wave's ledger, refused here until a reviewed row exists for it.
576
+ { audience: "app-data:settings-set", method: "POST", surface: "settings-set" },
577
+ {
578
+ audience: "app-data:people-set-access",
579
+ method: "POST",
580
+ surface: "people-set-access",
581
+ },
582
+ { audience: "app-data:people-remove", method: "POST", surface: "people-remove" },
504
583
  ];
505
584
 
506
- const REMOTE_V2_SURFACES = new Map<string, RelaySurfaceName>([
585
+ /** One admitted surface row as the classification maps carry it: the family's own name and
586
+ * the ONE method its row declares. Method admission is per row (W4): a widened write row
587
+ * admits its POST and refuses the GET, a read row the reverse — never a name-only match. */
588
+ interface RelaySurfaceAdmission {
589
+ readonly surface: RelaySurfaceName;
590
+ readonly method: "GET" | "POST";
591
+ }
592
+
593
+ const REMOTE_V2_SURFACES = new Map<string, RelaySurfaceAdmission>([
507
594
  ...ADMITTED_SURFACES,
508
- ...RELAY_REMOTE_SURFACE_V2.map((row) => [row.audience, row.surface] as const),
595
+ ...RELAY_REMOTE_SURFACE_V2.map(
596
+ (row) => [row.audience, { surface: row.surface, method: row.method }] as const,
597
+ ),
509
598
  ]);
510
599
 
511
600
  /** The named (a)–(d) category for an audience, or null when the audience is not on the
@@ -538,7 +627,7 @@ export type RelaySurfaceVerdict =
538
627
  export function classifyRelayedRequest(
539
628
  audience: string,
540
629
  method: "GET" | "POST",
541
- surfaces: ReadonlyMap<string, RelaySurfaceName> = ADMITTED_SURFACES,
630
+ surfaces: ReadonlyMap<string, RelaySurfaceAdmission> = ADMITTED_SURFACES,
542
631
  ): RelaySurfaceVerdict {
543
632
  // §11 negative-list first, regardless of method: an approval/credential/extension
544
633
  // audience carries its named category even as a write — the category is the security
@@ -550,14 +639,13 @@ export function classifyRelayedRequest(
550
639
  return { admitted: false, denial: category };
551
640
  }
552
641
 
553
- if (method !== "GET") {
554
- return { admitted: false, denial: "not-admitted" };
555
- }
556
-
557
- const surface = surfaces.get(audience);
642
+ // Method admission is the row's own (W4): a POST is admitted exactly where a widened row
643
+ // declares one, never by name alone — a read row still refuses a POST and a write row a
644
+ // GET, so the exact (audience, method) pair is what admits, fail-closed either way.
645
+ const admission = surfaces.get(audience);
558
646
 
559
- if (surface !== undefined) {
560
- return { admitted: true, surface };
647
+ if (admission !== undefined && admission.method === method) {
648
+ return { admitted: true, surface: admission.surface };
561
649
  }
562
650
 
563
651
  return { admitted: false, denial: "not-admitted" };
@@ -672,7 +760,7 @@ export interface RelayBoundaryOptions {
672
760
 
673
761
  export class RelayBoundary {
674
762
  private readonly now: () => number;
675
- private readonly surfaces: ReadonlyMap<string, RelaySurfaceName>;
763
+ private readonly surfaces: ReadonlyMap<string, RelaySurfaceAdmission>;
676
764
  private readonly ledger: RelayLedgerReads;
677
765
 
678
766
  constructor(options: RelayBoundaryOptions) {