@bom-pi/core 0.2.5 → 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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bom-pi/core",
3
- "version": "0.2.5",
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",
@@ -352,7 +352,12 @@ export type BootVerifyOutcome =
352
352
  | {
353
353
  outcome: "quarantined";
354
354
  reason: "removed" | "superseded" | "refused" | "unreachable" | "unsupported";
355
- };
355
+ }
356
+ /** ADR-19 hardening (fleet race): the entry this verify started with was REPLACED while
357
+ * the answer was in flight (a ceremony won the boot race). The verify is moot: nothing was
358
+ * erased, no cleanup was queued, and the connector now lives on the ceremony's credential —
359
+ * callers must treat the lane as owned by that ceremony and touch nothing. */
360
+ | { outcome: "overtaken" };
356
361
 
357
362
  export type BackoffOptions = {
358
363
  baseMs?: number;
@@ -1697,6 +1702,33 @@ export class CloudConnector {
1697
1702
 
1698
1703
  const entry = this.requireEntry();
1699
1704
 
1705
+ // ADR-19 hardening (fleet race 2026-11-15): every destructive decision below may act
1706
+ // ONLY on the exact entry this verify started with — same membership ref AND same
1707
+ // credential epoch. If a ceremony replaced the entry while an answer was in flight,
1708
+ // this verify is MOOT: no erase, no cleanup intent, no displacement, no adoption.
1709
+ // (The serialization chain makes the swap invisible to this body today; the guard
1710
+ // keeps the invariant local and true under any future refactor that splits it.)
1711
+ const verifiedRef: MemberRef = { ...entry.membership };
1712
+ const verifiedEpoch = entry.credentialEpoch;
1713
+
1714
+ const stillTheVerifiedEntry = (): boolean => {
1715
+ const current = this.snapshot.entry;
1716
+
1717
+ return (
1718
+ current !== null &&
1719
+ current.credentialEpoch === verifiedEpoch &&
1720
+ refsEqual(current.membership, verifiedRef)
1721
+ );
1722
+ };
1723
+
1724
+ const overtaken = (): { outcome: "overtaken" } => {
1725
+ this.lastFailure =
1726
+ "boot verify moot: the stored entry was replaced by a fresh ceremony while the answer was in flight";
1727
+ this.lastBootVerify = { outcome: "overtaken" };
1728
+
1729
+ return this.lastBootVerify;
1730
+ };
1731
+
1700
1732
  // R1: a pending intent for THIS exact ref wins over any anchor — the structural rule
1701
1733
  // "a credential and its own pending cleanup may not coexist" must hold here too.
1702
1734
  if (
@@ -1704,6 +1736,10 @@ export class CloudConnector {
1704
1736
  refsEqual(pending.membership, entry.membership),
1705
1737
  )
1706
1738
  ) {
1739
+ if (!stillTheVerifiedEntry()) {
1740
+ return overtaken();
1741
+ }
1742
+
1707
1743
  await this.quarantineStoredEntry();
1708
1744
  this.lastBootVerify = { outcome: "quarantined", reason: "refused" };
1709
1745
 
@@ -1711,6 +1747,10 @@ export class CloudConnector {
1711
1747
  }
1712
1748
 
1713
1749
  if (entry.credentialExpiresAt <= this.saneNow()) {
1750
+ if (!stillTheVerifiedEntry()) {
1751
+ return overtaken();
1752
+ }
1753
+
1714
1754
  await this.quarantineStoredEntry();
1715
1755
  this.lastBootVerify = { outcome: "quarantined", reason: "refused" };
1716
1756
 
@@ -1739,6 +1779,11 @@ export class CloudConnector {
1739
1779
  ),
1740
1780
  deadline,
1741
1781
  );
1782
+
1783
+ if (!stillTheVerifiedEntry()) {
1784
+ return overtaken();
1785
+ }
1786
+
1742
1787
  const outcome = await this.adoptVerifiedCredential(entry, verified);
1743
1788
 
1744
1789
  this.lastBootVerify = outcome;
@@ -1749,6 +1794,10 @@ export class CloudConnector {
1749
1794
  // already rotated the credential — the honest terminal state, NOT a quarantine
1750
1795
  // (queueing a cleanup here would delete the member row the REAL machine holds).
1751
1796
  if (error instanceof EndpointError && error.status === 409) {
1797
+ if (!stillTheVerifiedEntry()) {
1798
+ return overtaken();
1799
+ }
1800
+
1752
1801
  await this.markDisplaced();
1753
1802
  this.lastBootVerify = { outcome: "quarantined", reason: "superseded" };
1754
1803
 
@@ -1767,6 +1816,11 @@ export class CloudConnector {
1767
1816
  this.lastFailure = `boot verify failed (${reason}): ${
1768
1817
  error instanceof Error ? error.message : String(error)
1769
1818
  }`;
1819
+
1820
+ if (!stillTheVerifiedEntry()) {
1821
+ return overtaken();
1822
+ }
1823
+
1770
1824
  await this.quarantineStoredEntry();
1771
1825
  this.lastBootVerify = { outcome: "quarantined", reason };
1772
1826
 
@@ -1862,6 +1916,25 @@ export class CloudConnector {
1862
1916
  }
1863
1917
  : null;
1864
1918
 
1919
+ // ADR-19 hardening (review 2026-11-15): the receipt verifier above is an AWAIT — the
1920
+ // only reason the entry cannot change across it today is the outer serialize chain.
1921
+ // Keep the invariant LOCAL: re-check that the entry is still the exact one this verify
1922
+ // started with (same ref + credential epoch) immediately BEFORE the durable write. A
1923
+ // mismatch aborts the adoption — nothing written, nothing queued — and the throw lands
1924
+ // in the caller's fail-closed catch, whose own changed-entry guard maps it to a silent
1925
+ // "overtaken" (a ceremony owns the connector now).
1926
+ const current = this.snapshot.entry;
1927
+
1928
+ if (
1929
+ current === null ||
1930
+ current.credentialEpoch !== entry.credentialEpoch ||
1931
+ !refsEqual(current.membership, entry.membership)
1932
+ ) {
1933
+ throw new ConnectorStateError(
1934
+ "Boot verify moot: the stored entry changed while the rotation receipt was being verified; nothing adopted",
1935
+ );
1936
+ }
1937
+
1865
1938
  // R3: the anchored boot creates no intent, ever — and it adopts nothing else either: same
1866
1939
  // ref, same identity, only the credential material moves.
1867
1940
  const next: ConnectorSnapshot = {
@@ -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) {