@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 +1 -1
- package/src/cloud-connector.ts +74 -1
- package/src/relay-boundary.ts +112 -24
package/package.json
CHANGED
package/src/cloud-connector.ts
CHANGED
|
@@ -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 = {
|
package/src/relay-boundary.ts
CHANGED
|
@@ -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 = (
|
|
203
|
+
const familyRow = (
|
|
204
|
+
audience: string,
|
|
205
|
+
caps: string,
|
|
206
|
+
methods: readonly ("GET" | "POST")[] = ["GET"],
|
|
207
|
+
) => ({
|
|
204
208
|
audience,
|
|
205
|
-
methods
|
|
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,
|
|
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
|
|
390
|
-
* (secure) lane — one explicit
|
|
391
|
-
* read
|
|
392
|
-
*
|
|
393
|
-
*
|
|
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
|
-
|
|
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(
|
|
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,
|
|
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
|
-
|
|
554
|
-
|
|
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 (
|
|
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,
|
|
763
|
+
private readonly surfaces: ReadonlyMap<string, RelaySurfaceAdmission>;
|
|
676
764
|
private readonly ledger: RelayLedgerReads;
|
|
677
765
|
|
|
678
766
|
constructor(options: RelayBoundaryOptions) {
|