@bom-pi/core 0.2.6 → 0.2.8

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 +167 -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.8",
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,42 @@ 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"]),
288
+ // Owner parity batch (2026-11-16, the owner's word: the paired console is the whole console —
289
+ // not a viewer): the session-lifecycle and message-box writes a local console has. Create a
290
+ // session on the looked-at machine, configure it (model, thinking, cwd — the "move"), run
291
+ // and stop a shell task of its own, carry the typing signal, and manage the queued message
292
+ // (withdraw it, or move it between steer and follow-up). Effect rows the ADR kept for their
293
+ // own review stay out exactly as before; these are the local console's own everyday writes.
294
+ familyRow("app-data:session-create", "sessions-admin", ["POST"]),
295
+ familyRow("app-data:conversation-configure", "sessions-admin", ["POST"]),
296
+ familyRow("app-data:conversation-shell-start", "conversation-run", ["POST"]),
297
+ familyRow("app-data:conversation-shell-stop", "conversation-run", ["POST"]),
298
+ familyRow("app-data:conversation-typing-set", "conversation-run", ["POST"]),
299
+ familyRow("app-data:conversation-submission-withdraw", "conversation-run", ["POST"]),
300
+ familyRow("app-data:conversation-submission-move", "conversation-run", ["POST"]),
261
301
  ];
262
302
 
263
303
  /** Machine-readable, bounded policy denials (SEC-14 typed verdicts). None of these names
@@ -377,24 +417,40 @@ export type RelaySurfaceName =
377
417
  | "spend-summary"
378
418
  | "running-list"
379
419
  | "subagents-board-read"
380
- | "event-poll";
420
+ | "event-poll"
421
+ | "conversation-submit"
422
+ | "approval-answer"
423
+ | "conversation-abort"
424
+ | "conversation-fork"
425
+ | "session-update"
426
+ | "settings-set"
427
+ | "people-set-access"
428
+ | "people-remove"
429
+ | "session-create"
430
+ | "conversation-configure"
431
+ | "conversation-shell-start"
432
+ | "conversation-shell-stop"
433
+ | "conversation-typing-set"
434
+ | "conversation-submission-withdraw"
435
+ | "conversation-submission-move";
381
436
 
382
437
  /** The frozen M4 v1 admitted surface (the canned pilot lane's set): exactly the two
383
438
  * 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"],
439
+ const ADMITTED_SURFACES = new Map<string, RelaySurfaceAdmission>([
440
+ ["app-data:session-status", { surface: "session-status", method: "GET" }],
441
+ ["app-data:session-ping", { surface: "session-ping", method: "GET" }],
387
442
  ]);
388
443
 
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";
444
+ /** D3 backend gap (2): the family-by-family WIDENED surface for the remote
445
+ * (secure) lane — one explicit row per family operation of the 12 PARITY families'
446
+ * read/view subset (GET) and, from W4, the reviewed write families (POST), deny-first:
447
+ * nothing is admitted that is not an exact (audience, method) row here, every unlisted
448
+ * family stays out, and every row is off the §11 negative lists (asserted by test).
449
+ * This table is INERT until a boundary is constructed with surfaceSet "remote-v2";
394
450
  * the default boundary keeps the v1 two. */
395
451
  export const RELAY_REMOTE_SURFACE_V2: readonly {
396
452
  audience: string;
397
- method: "GET";
453
+ method: "GET" | "POST";
398
454
  surface: RelaySurfaceName;
399
455
  /** The row's answer carries money as integer cents: the wire's canonical value is a
400
456
  * nonnegative safe integer, and usage costs are USD floats. The funnel row converts
@@ -499,13 +555,101 @@ export const RELAY_REMOTE_SURFACE_V2: readonly {
499
555
  },
500
556
  // ADR-20 wave 3 (the stream lane, as the approved batch's poll option — the W3 packet's
501
557
  // §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.
558
+ // GET-only like every read row; the ring's answer carries no money and its `full` rides 0/1.
503
559
  { audience: "app-data:event-poll", method: "GET", surface: "event-poll" },
560
+ // ADR-20 wave 4, run control (the looked-at machine's run is steerable from here): three
561
+ // POST rows, one per registry operation the family owns — submit into the session, answer
562
+ // its tool approval, abort the run. Each row is an exact (audience, method) pair like every
563
+ // other: the read rows above stay GET and refuse a POST, these refuse a GET, and nothing
564
+ // about the §11 deny-list moved (approval-path/credential audiences deny by category
565
+ // before this table is ever consulted). The bodies ride the same sealed lane and its
566
+ // single-frame bound (`MAX_RELAY_REQUEST_BODY_B64`); the answers carry no money.
567
+ {
568
+ audience: "app-data:conversation-submit",
569
+ method: "POST",
570
+ surface: "conversation-submit",
571
+ },
572
+ { audience: "app-data:approval-answer", method: "POST", surface: "approval-answer" },
573
+ {
574
+ audience: "app-data:conversation-abort",
575
+ method: "POST",
576
+ surface: "conversation-abort",
577
+ },
578
+ // ADR-20 wave 4, family 2 (session admin): two more POST rows — fork a session of the
579
+ // looked-at machine (the operation answers the NEW conversation's id) and update one
580
+ // (rename, or the archived flag that puts it away and brings it back). Exact pairs like
581
+ // every row; the bodies ride the same sealed lane and its single-frame bound; the answers
582
+ // carry no money. Move (cwd) and hard delete have no typed operation to point at — recorded
583
+ // gaps in the wave's ledger, refused here until a reviewed row exists for them.
584
+ {
585
+ audience: "app-data:conversation-fork",
586
+ method: "POST",
587
+ surface: "conversation-fork",
588
+ },
589
+ { audience: "app-data:session-update", method: "POST", surface: "session-update" },
590
+ // ADR-20 wave 4, family 3 (catalog): three more POST rows — one setting of the looked-at
591
+ // machine changed at a time, a person's access changed, a person removed. Exact pairs like
592
+ // every row; the bodies ride the same sealed lane and its single-frame bound; the answers
593
+ // carry no money (settings-set/people-remove answer {ok}, people-set-access the people list).
594
+ // The providers half of the family has no typed operation to point at — a recorded gap in the
595
+ // wave's ledger, refused here until a reviewed row exists for it.
596
+ { audience: "app-data:settings-set", method: "POST", surface: "settings-set" },
597
+ {
598
+ audience: "app-data:people-set-access",
599
+ method: "POST",
600
+ surface: "people-set-access",
601
+ },
602
+ { audience: "app-data:people-remove", method: "POST", surface: "people-remove" },
603
+ // Owner parity batch (2026-11-16): the local console's own session-lifecycle and message-box
604
+ // writes, so a paired console is the whole console. Exact pairs like every row; the bodies
605
+ // ride the same sealed lane and its single-frame bound; the answers carry no money
606
+ // (session-create answers the new session's id, the rest {ok}).
607
+ { audience: "app-data:session-create", method: "POST", surface: "session-create" },
608
+ {
609
+ audience: "app-data:conversation-configure",
610
+ method: "POST",
611
+ surface: "conversation-configure",
612
+ },
613
+ {
614
+ audience: "app-data:conversation-shell-start",
615
+ method: "POST",
616
+ surface: "conversation-shell-start",
617
+ },
618
+ {
619
+ audience: "app-data:conversation-shell-stop",
620
+ method: "POST",
621
+ surface: "conversation-shell-stop",
622
+ },
623
+ {
624
+ audience: "app-data:conversation-typing-set",
625
+ method: "POST",
626
+ surface: "conversation-typing-set",
627
+ },
628
+ {
629
+ audience: "app-data:conversation-submission-withdraw",
630
+ method: "POST",
631
+ surface: "conversation-submission-withdraw",
632
+ },
633
+ {
634
+ audience: "app-data:conversation-submission-move",
635
+ method: "POST",
636
+ surface: "conversation-submission-move",
637
+ },
504
638
  ];
505
639
 
506
- const REMOTE_V2_SURFACES = new Map<string, RelaySurfaceName>([
640
+ /** One admitted surface row as the classification maps carry it: the family's own name and
641
+ * the ONE method its row declares. Method admission is per row (W4): a widened write row
642
+ * admits its POST and refuses the GET, a read row the reverse — never a name-only match. */
643
+ interface RelaySurfaceAdmission {
644
+ readonly surface: RelaySurfaceName;
645
+ readonly method: "GET" | "POST";
646
+ }
647
+
648
+ const REMOTE_V2_SURFACES = new Map<string, RelaySurfaceAdmission>([
507
649
  ...ADMITTED_SURFACES,
508
- ...RELAY_REMOTE_SURFACE_V2.map((row) => [row.audience, row.surface] as const),
650
+ ...RELAY_REMOTE_SURFACE_V2.map(
651
+ (row) => [row.audience, { surface: row.surface, method: row.method }] as const,
652
+ ),
509
653
  ]);
510
654
 
511
655
  /** The named (a)–(d) category for an audience, or null when the audience is not on the
@@ -538,7 +682,7 @@ export type RelaySurfaceVerdict =
538
682
  export function classifyRelayedRequest(
539
683
  audience: string,
540
684
  method: "GET" | "POST",
541
- surfaces: ReadonlyMap<string, RelaySurfaceName> = ADMITTED_SURFACES,
685
+ surfaces: ReadonlyMap<string, RelaySurfaceAdmission> = ADMITTED_SURFACES,
542
686
  ): RelaySurfaceVerdict {
543
687
  // §11 negative-list first, regardless of method: an approval/credential/extension
544
688
  // audience carries its named category even as a write — the category is the security
@@ -550,14 +694,13 @@ export function classifyRelayedRequest(
550
694
  return { admitted: false, denial: category };
551
695
  }
552
696
 
553
- if (method !== "GET") {
554
- return { admitted: false, denial: "not-admitted" };
555
- }
556
-
557
- const surface = surfaces.get(audience);
697
+ // Method admission is the row's own (W4): a POST is admitted exactly where a widened row
698
+ // declares one, never by name alone — a read row still refuses a POST and a write row a
699
+ // GET, so the exact (audience, method) pair is what admits, fail-closed either way.
700
+ const admission = surfaces.get(audience);
558
701
 
559
- if (surface !== undefined) {
560
- return { admitted: true, surface };
702
+ if (admission !== undefined && admission.method === method) {
703
+ return { admitted: true, surface: admission.surface };
561
704
  }
562
705
 
563
706
  return { admitted: false, denial: "not-admitted" };
@@ -672,7 +815,7 @@ export interface RelayBoundaryOptions {
672
815
 
673
816
  export class RelayBoundary {
674
817
  private readonly now: () => number;
675
- private readonly surfaces: ReadonlyMap<string, RelaySurfaceName>;
818
+ private readonly surfaces: ReadonlyMap<string, RelaySurfaceAdmission>;
676
819
  private readonly ledger: RelayLedgerReads;
677
820
 
678
821
  constructor(options: RelayBoundaryOptions) {