@bom-pi/core 0.2.3 → 0.2.5

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,11 +1,11 @@
1
1
  {
2
2
  "name": "@bom-pi/core",
3
- "version": "0.2.3",
3
+ "version": "0.2.5",
4
4
  "description": "Core pairing machinery for Bom Pi: ceremonies, transports, durable stores",
5
5
  "type": "module",
6
6
  "license": "MIT",
7
7
  "dependencies": {
8
- "@bom-pi/protocol": "^0.1.1"
8
+ "@bom-pi/protocol": "^0.1.2"
9
9
  },
10
10
  "exports": {
11
11
  "./cloud-connector.ts": "./src/cloud-connector.ts",
@@ -1,6 +1,18 @@
1
1
  /** Candidate v1 pinned outbound cloud-connector workers (one per joined cloud): reconcile, backoff, removal, cleanup. Inert transports only; no listener, application relay, agent adapter or service activation is implemented here.
2
2
  * §4.1/§16 cleanup invariant: the signed secret-free deletion request is durably stored AT REST in the same atomic write that erases the credential; retries present those stored bytes plus a fresh cleanup-only proof; storage failures seal fail-closed and a memory-only seal honestly discloses that no restart safety guarantee exists (no independent boot gate).
3
- * §16 restart fail-closed default: there is no trusted rollback/boot gate, so EVERY credential loaded from disk at open() is quarantined before any use — erased in the same atomic write that durably stores a fresh signed cleanup intent for its membership. A stored credential is never adopted as fresh, repair/reconcile can never resume it, and there is deliberately no `allowRestored` bypass. The only admission path is enroll(): an X-signed approval receipt verified against the PINNED cloud key (exact issuance bindings, replay-rejected request IDs, §16 cleanup-capacity reservation), installed in one durable write. Consequent impact, stated plainly: after every restart the membership is disabled locally and application work requires a fresh cloud-admin-approved enrollment, while cleanup delivery and local removal keep working without any credential.
3
+ * §16 restart fail-closed default: EXCEPT for ADR-19's single owner-approved deviation, EVERY
4
+ * credential loaded from disk at open() is quarantined before any use — erased in the same atomic
5
+ * write that durably stores a fresh signed cleanup intent for its membership. A stored credential
6
+ * is never adopted as fresh, repair/reconcile can never resume it, and there is deliberately no
7
+ * `allowRestored` bypass. The ADR-19 deviation is narrower than it sounds and still cloud-gated:
8
+ * a stored credential is USED only after the pinned cloud VERIFIED it live (nonce-fresh proof,
9
+ * X-signed receipt against the pinned key) and handed back a FRESH rotated credential bound to the
10
+ * SAME membership ref — so the authority the disk carries never crosses the gap, the row keeps its
11
+ * id/epoch (the relation binding and the §13 pin survive), and the moment the cloud does not
12
+ * answer, or says removed/superseded/wrong, the connector falls back to TODAY's quarantine and the
13
+ * one owner click. The only admission path for a NEW membership is still enroll(): an X-signed
14
+ * approval receipt verified against the PINNED cloud key (exact issuance bindings, replay-rejected
15
+ * request IDs, §16 cleanup-capacity reservation), installed in one durable write.
4
16
  * §16 never-deletion: pending cleanup intents are a DURABLE LIST, not a single slot — a new cancellation is never refused because an older signed intent is still unacknowledged; every intent is preserved across restart and delivered/acked individually. */
5
17
  import {
6
18
  createHash,
@@ -158,6 +170,15 @@ export type ReceiptExpectation = {
158
170
  /** P7 F-5: when set, the receipt must name exactly this fingerprint (removal receipts are
159
171
  * prover-bound; a receipt about someone else's ref never verifies). */
160
172
  fingerprint?: string;
173
+ /** ADR-19: when set, the receipt must be a boot-verify ROTATION binding exactly these
174
+ * facts — the epoch this boot presented, the rotated epoch, the new credential's hash and
175
+ * expiry. A receipt that does not carry all four, exactly, never verifies. */
176
+ credentialRotation?: {
177
+ fromEpoch: number;
178
+ toEpoch: number;
179
+ credentialHash: string;
180
+ expiresAt: number;
181
+ };
161
182
  };
162
183
 
163
184
  /**
@@ -169,7 +190,7 @@ export type ReceiptExpectation = {
169
190
  export type ReceiptVerifier = (
170
191
  receipt: string,
171
192
  expected: ReceiptExpectation,
172
- ) => Promise<{ action: string } | null>;
193
+ ) => Promise<{ action: string; payload?: Record<string, CanonicalValue> } | null>;
173
194
 
174
195
  export const failClosedReceiptVerifier: ReceiptVerifier = async () => null;
175
196
 
@@ -187,8 +208,34 @@ export interface CloudEndpoint {
187
208
  /** Cleanup-only deletion: presents the STORED signed request bytes verbatim plus a fresh
188
209
  * cleanup-only proof; identity-signed, no bearer credential; deletion-only, never enrollment. */
189
210
  cleanup(old: MemberRef, stored: StoredCleanupRequest, proof: ConnectorProof): Promise<string>;
211
+ /** ADR-19 (owner-decided): boot membership VERIFY + credential ROTATION — the one lane that lets
212
+ * a restart KEEP what the owner already approved instead of quarantining it into a click.
213
+ *
214
+ * Optional BY DESIGN. A pinned cloud (or a test wiring) that does not offer it is an old cloud:
215
+ * `open()` then degrades to today's boot quarantine with a typed reason (ADR-19 R8, the same
216
+ * capability-detect discipline the relay lane uses), never a silent "keep". An implementation
217
+ * must only ever answer for the exact ref it was asked about, must never create a membership,
218
+ * grant, signer pin or identity change, and must return an X-signed receipt binding the exact
219
+ * ref, the presented credential epoch, the new epoch, the new credential hash and expiry — the
220
+ * connector refuses to adopt a rotated credential it cannot check against the PINNED key. */
221
+ verify?(
222
+ ref: MemberRef,
223
+ credential: string,
224
+ credentialEpoch: number,
225
+ proof: ConnectorProof,
226
+ ): Promise<VerifiedCredential>;
190
227
  }
191
228
 
229
+ /** ADR-19 boot-verify answer: the SAME membership ref (the row is kept, only the credential moves),
230
+ * the rotated credential and the X-signed receipt that admits it. */
231
+ export type VerifiedCredential = {
232
+ membership: MemberRef;
233
+ credential: string;
234
+ credentialEpoch: number;
235
+ credentialExpiresAt: number;
236
+ receipt: string;
237
+ };
238
+
192
239
  /** §11 relay close reasons — the fixed, bounded vocabulary X may put on the wire. Duplicated
193
240
  * literal of apps/bom-cloud/server/connect-wss.ts RELAY_CLOSE_REASONS (packages must not import
194
241
  * apps; the leader owns single-sourcing this constant). */
@@ -261,7 +308,19 @@ export class EndpointError extends Error {
261
308
  }
262
309
 
263
310
  export type ConnectorStatus =
264
- "fresh" | "ready" | "retrying" | "removed" | "expired" | "sealed" | "stopped";
311
+ | "fresh"
312
+ | "ready"
313
+ | "retrying"
314
+ | "removed"
315
+ | "expired"
316
+ | "sealed"
317
+ /** ADR-19 §2.3: the cloud said this record's credential was SUPERSEDED by a newer verified
318
+ * boot of the same identity (a copied/restored disk). The dead credential is kept (it is
319
+ * authority for nothing), no cleanup intent is queued — revoking the live member here would
320
+ * kill the machine that legitimately holds it — and every lane stays inert until the owner
321
+ * acts. Honest, typed, never silent. */
322
+ | "displaced"
323
+ | "stopped";
265
324
 
266
325
  export type ReconcileResult =
267
326
  | { outcome: "ready"; generation: number }
@@ -274,12 +333,27 @@ export type ConnectorOptions = {
274
333
  transportFactory: () => CloudTransport;
275
334
  endpointFactory: (transport: CloudTransport) => CloudEndpoint;
276
335
  receiptVerifier?: ReceiptVerifier;
336
+ /** ADR-19 (owner-decided, 2026-11-14): the boot anchor. When TRUE, open() does NOT
337
+ * quarantine a stored credential; it holds it INERT and a later verifyStoredMembership()
338
+ * decides — X-verified live → adopt the rotated credential; removed / superseded /
339
+ * unreachable-within-the-window → TODAY's quarantine. Default FALSE (the §16 fail-closed
340
+ * default keeps exact pre-ADR behaviour for every wiring that does not ask for the anchor). */
341
+ verifiedAnchor?: boolean;
277
342
  now?: () => number;
278
343
  random?: (length: number) => Uint8Array;
279
344
  sleep?: (ms: number) => Promise<void>;
280
345
  backoff?: BackoffOptions;
281
346
  };
282
347
 
348
+ /** ADR-19 §8: what a boot verify decided, published for the daemon's status surface. Secret-free
349
+ * (the rotated credential is never part of it). */
350
+ export type BootVerifyOutcome =
351
+ | { outcome: "verified"; membership: MemberRef; credentialEpoch: number }
352
+ | {
353
+ outcome: "quarantined";
354
+ reason: "removed" | "superseded" | "refused" | "unreachable" | "unsupported";
355
+ };
356
+
283
357
  export type BackoffOptions = {
284
358
  baseMs?: number;
285
359
  capMs?: number;
@@ -856,6 +930,16 @@ export class CloudConnector {
856
930
  private readonly random: (length: number) => Uint8Array;
857
931
  private readonly sleep: (ms: number) => Promise<void>;
858
932
  private readonly backoffOptions: BackoffOptions;
933
+ /** ADR-19: the owner-approved boot anchor flag (see ConnectorOptions). */
934
+ private readonly verifiedAnchor: boolean;
935
+ /** ADR-19 §8: the last boot-verify decision, published through sanitizedState()/describe(). */
936
+ private lastBootVerify: BootVerifyOutcome | null = null;
937
+ /** ADR-19 §2.4: X's §13 pin as echoed by the last verified receipt (read-only). */
938
+ private verifiedSignerPin: {
939
+ signerFingerprint: string;
940
+ signerEpoch: number;
941
+ signerPublicKeySpki: string;
942
+ } | null = null;
859
943
 
860
944
  private constructor(options: ConnectorOptions, snapshot: ConnectorSnapshot) {
861
945
  this.pinned = { ...options.pinned };
@@ -874,6 +958,7 @@ export class CloudConnector {
874
958
  this.random = options.random ?? ((length: number) => randomBytes(length));
875
959
  this.sleep = options.sleep ?? ((ms: number) => new Promise((r) => setTimeout(r, ms)));
876
960
  this.backoffOptions = options.backoff ?? {};
961
+ this.verifiedAnchor = options.verifiedAnchor === true;
877
962
  this.snapshot = snapshot;
878
963
  // An opened record that says "credential erased, cleanup pending" is honestly "removed",
879
964
  // never "fresh" (§16 wording; reconcile/delivery resume from the stored state). A record
@@ -887,11 +972,15 @@ export class CloudConnector {
887
972
  }
888
973
 
889
974
  /** Opens one pinned cloud connector. A fresh store is initialized; a stale/mismatched record
890
- * is refused; and ANY stored credential is quarantined before the connector is returned: it is
891
- * erased in the same atomic write that durably stores a fresh signed cleanup intent for its
892
- * membership (§16 fail-closed restart default — there is no trusted boot gate, so persisted
893
- * credentials are never trusted across restart). Re-admission requires a fresh authenticated
894
- * enroll(); cleanup delivery and removal keep working without any credential. */
975
+ * is refused. ANY stored credential is quarantined before the connector is returned — UNLESS
976
+ * the ADR-19 anchor was asked for (verifiedAnchor), in which case the credential is KEPT ON
977
+ * DISK BUT HELD INERT: `status` stays "fresh" only so the anchor path can run, no lane may
978
+ * use the credential, and verifyStoredMembership() decides within its bounded window —
979
+ * X-verified live ⇒ adopt the ROTATED credential in one durable write (same membership ref,
980
+ * relation binding and §13 pin untouched); removed/superseded/refused/unreachable/old-cloud ⇒
981
+ * today's quarantine exactly (erase + signed cleanup intent + re-enroll click, ADR-19 §2.3).
982
+ * Re-admission of a NEW membership always requires a fresh authenticated enroll(); cleanup
983
+ * delivery and removal keep working without any credential. */
895
984
  static async open(options: ConnectorOptions): Promise<CloudConnector> {
896
985
  validPinned(options.pinned);
897
986
 
@@ -939,10 +1028,20 @@ export class CloudConnector {
939
1028
  const snapshot = migrateSnapshot(structuredClone(stored), options.pinned, identity);
940
1029
  const connector = new CloudConnector(options, snapshot);
941
1030
 
942
- if (snapshot.entry !== null) {
1031
+ if (snapshot.entry !== null && !connector.verifiedAnchor) {
943
1032
  await connector.quarantineStoredEntry();
944
1033
  }
945
1034
 
1035
+ if (snapshot.entry !== null && connector.verifiedAnchor) {
1036
+ // ADR-19 §2.1: the anchor holds the credential INERT. The record still says "has a
1037
+ // credential", so nothing else may read it as adoptable: this flag is the difference
1038
+ // between "kept, pending cloud verify" and "fresh from a ceremony". reconcile()
1039
+ // and every other credential lane refuses while it is set (and while a copy stands
1040
+ // displaced): the stored credential never authenticates anywhere until
1041
+ // verifyStoredMembership() replaces it with a rotated, receipt-verified one.
1042
+ connector.quarantinedAtBoot = true;
1043
+ }
1044
+
946
1045
  return connector;
947
1046
  }
948
1047
 
@@ -972,8 +1071,13 @@ export class CloudConnector {
972
1071
  /** The ceremony-adopted pinned cloud key (base64url SPKI) or null — never a secret. */
973
1072
  pinnedCloudPublicSpki: string | null;
974
1073
  cleanupAcknowledged: boolean;
975
- /** True when open() quarantined a credential loaded from disk (§16 restart default). */
1074
+ /** True when open() quarantined a credential loaded from disk (§16 restart default), or
1075
+ * when the ADR-19 anchor is HOLDING a stored credential inert pending its boot verify
1076
+ * (same meaning for every reader: the stored credential is not usable as-is). */
976
1077
  quarantinedAtBoot: boolean;
1078
+ /** ADR-19 §8: the last boot-verify decision ("verified" ⇔ the current credential was
1079
+ * admitted through the X-verified rotation lane), or null when no verify ran this boot. */
1080
+ bootVerify: BootVerifyOutcome | null;
977
1081
  /** "durable"/"memory-only" while sealed; "none" otherwise (§16 honesty surface). */
978
1082
  seal: "none" | "durable" | "memory-only";
979
1083
  lastFailure: string | null;
@@ -995,6 +1099,7 @@ export class CloudConnector {
995
1099
  pinnedCloudPublicSpki: this.snapshot.pinnedCloudPublicSpki,
996
1100
  cleanupAcknowledged: this.cleanupAcknowledged,
997
1101
  quarantinedAtBoot: this.quarantinedAtBoot,
1102
+ bootVerify: this.lastBootVerify === null ? null : { ...this.lastBootVerify },
998
1103
  seal:
999
1104
  this.statusValue === "sealed"
1000
1105
  ? this.sealMemoryOnly
@@ -1005,6 +1110,26 @@ export class CloudConnector {
1005
1110
  };
1006
1111
  }
1007
1112
 
1113
+ /** ADR-19 §2.4: the §13 signer pin X echoed inside the last VERIFIED boot-verify receipt, or
1114
+ * null when the last verify was not "verified" or X holds no pin. Read-only facts for the
1115
+ * daemon's `signer-changed` honesty — the connector never pins anything itself. */
1116
+ lastVerifiedSignerPin(): {
1117
+ signerFingerprint: string;
1118
+ signerEpoch: number;
1119
+ signerPublicKeySpki: string;
1120
+ } | null {
1121
+ return this.verifiedSignerPin === null ? null : { ...this.verifiedSignerPin };
1122
+ }
1123
+
1124
+ /** ADR-19: true while the anchor holds a stored credential INERT pending its boot verify
1125
+ * (verifiedAnchor boot + a credential on disk + not yet adopted). False for every other
1126
+ * connector: a ceremony-fresh credential, a quarantined/removed store, or an anchor that
1127
+ * already adopted its rotation. This is the ONE flag callers gate the anchor path on — a
1128
+ * live membership in the SAME process is not a boot and must take the ordinary lanes. */
1129
+ get bootAnchorPending(): boolean {
1130
+ return this.verifiedAnchor && this.quarantinedAtBoot && this.snapshot.entry !== null;
1131
+ }
1132
+
1008
1133
  /** §4.1/§8 owner-visible status wording: never claims "erased everywhere" before the final ACK,
1009
1134
  * and never hides that a boot quarantine disabled the stored credential. */
1010
1135
  describe(): string {
@@ -1016,6 +1141,10 @@ export class CloudConnector {
1016
1141
  return this.sealMemoryOnly ? prefix : "fail-closed: storage recovery required";
1017
1142
  }
1018
1143
 
1144
+ if (this.statusValue === "displaced") {
1145
+ return "displaced: a newer boot of this identity holds the live credential; this record is inert — remove it and re-enroll, or revoke the member at the cloud";
1146
+ }
1147
+
1019
1148
  if (this.statusValue === "expired") {
1020
1149
  return "credential expired; fresh enrollment required";
1021
1150
  }
@@ -1289,6 +1418,25 @@ export class CloudConnector {
1289
1418
  this.failSealed();
1290
1419
  }
1291
1420
 
1421
+ // ADR-19 §2.1: an INERT credential never authenticates — not through this lane and
1422
+ // not through any future one. While the boot anchor HOLDS a stored credential
1423
+ // (quarantinedAtBoot with the entry still present) or while a superseded copy stands
1424
+ // displaced, reconcile is a refusal, not a re-check by the caller: the only way back
1425
+ // is verifyStoredMembership() adopting a rotated, receipt-verified credential (which
1426
+ // clears the marker) or today's §16 quarantine erasing the entry. A §16 boot that
1427
+ // ALREADY erased the credential has nothing inert to guard — it keeps its honest
1428
+ // pre-ADR behavior (requireEntry()'s refusal below), byte for byte.
1429
+ if (
1430
+ (this.quarantinedAtBoot && this.snapshot.entry !== null) ||
1431
+ this.statusValue === "displaced"
1432
+ ) {
1433
+ throw new ConnectorStateError(
1434
+ this.statusValue === "displaced"
1435
+ ? "Displaced credential copy: superseded by a newer boot; removal or re-enrollment required"
1436
+ : "Boot anchor pending: stored credential is inert until verifyStoredMembership()",
1437
+ );
1438
+ }
1439
+
1292
1440
  const entry = this.requireEntry();
1293
1441
 
1294
1442
  if (entry.credentialExpiresAt <= this.saneNow()) {
@@ -1517,6 +1665,252 @@ export class CloudConnector {
1517
1665
  this.statusValue = "removed";
1518
1666
  }
1519
1667
 
1668
+ /**
1669
+ * ADR-19 §2 (owner-decided, one wave: anchor + rotation): the boot decision for a stored
1670
+ * credential the anchor held inert. BOUNDED (wall clock, stop()-cancellable): opens a
1671
+ * verify-only transport, presents the stored credential + a nonce-fresh identity proof, and
1672
+ * lets the cloud decide:
1673
+ *
1674
+ * - `live` → adopt the ROTATED credential the cloud returned, in ONE durable write, after its
1675
+ * X-signed receipt verified against the pinned key and bound exactly this ref, this boot's
1676
+ * PRESENTED epoch and the new epoch/hash/expiry. The membership ref never changes (the
1677
+ * relation binding and the §13 pin survive the restart); NO cleanup intent is created (R3);
1678
+ * an undelivered intent for an OLDER ref stays undisturbed and still delivers later (R2/R4).
1679
+ * - removed/superseded/refused/no answer in the window/old cloud without the lane → TODAY's
1680
+ * quarantine, exactly: erase + signed cleanup intent, re-enroll click (R1 checked BEFORE
1681
+ * anything: a pending intent for THIS ref anchors nothing — it delivers instead).
1682
+ *
1683
+ * Clock-rollback-irrelevant by construction (R5/T4): there is NO cached anchor — every boot
1684
+ * asks, the answer is consumed once, and the adopted credential is always one the cloud
1685
+ * minted AFTER this boot.
1686
+ */
1687
+ async verifyStoredMembership(options?: {
1688
+ /** Wall-clock bound in ms (default 60 000, ADR-19 §2.3). Elapsed time, not a clock verdict. */
1689
+ timeoutMs?: number;
1690
+ }): Promise<BootVerifyOutcome> {
1691
+ const deadline = Date.now() + (options?.timeoutMs ?? 60_000);
1692
+
1693
+ return this.serialize(async () => {
1694
+ if (this.snapshot.sealed || this.statusValue === "sealed") {
1695
+ this.failSealed();
1696
+ }
1697
+
1698
+ const entry = this.requireEntry();
1699
+
1700
+ // R1: a pending intent for THIS exact ref wins over any anchor — the structural rule
1701
+ // "a credential and its own pending cleanup may not coexist" must hold here too.
1702
+ if (
1703
+ this.snapshot.pendingCleanups.some((pending) =>
1704
+ refsEqual(pending.membership, entry.membership),
1705
+ )
1706
+ ) {
1707
+ await this.quarantineStoredEntry();
1708
+ this.lastBootVerify = { outcome: "quarantined", reason: "refused" };
1709
+
1710
+ return this.lastBootVerify;
1711
+ }
1712
+
1713
+ if (entry.credentialExpiresAt <= this.saneNow()) {
1714
+ await this.quarantineStoredEntry();
1715
+ this.lastBootVerify = { outcome: "quarantined", reason: "refused" };
1716
+
1717
+ return this.lastBootVerify;
1718
+ }
1719
+
1720
+ let transport: CloudTransport | null = null;
1721
+
1722
+ try {
1723
+ transport = this.transportFactory();
1724
+ await transport.open();
1725
+
1726
+ const endpoint = this.endpointFactory(transport);
1727
+
1728
+ if (typeof endpoint.verify !== "function") {
1729
+ // R8 mixed fleet: an old cloud without the lane degrades to TODAY's boot, typed.
1730
+ throw new EndpointError(503, "verify lane unsupported by the pinned cloud");
1731
+ }
1732
+
1733
+ const verified = await this.raceDeadline(
1734
+ endpoint.verify(
1735
+ entry.membership,
1736
+ entry.credential,
1737
+ entry.credentialEpoch,
1738
+ this.makeProof("connector"),
1739
+ ),
1740
+ deadline,
1741
+ );
1742
+ const outcome = await this.adoptVerifiedCredential(entry, verified);
1743
+
1744
+ this.lastBootVerify = outcome;
1745
+
1746
+ return outcome;
1747
+ } catch (error) {
1748
+ // ADR-19 §2.3 displacement: the cloud says a NEWER verified boot of this identity
1749
+ // already rotated the credential — the honest terminal state, NOT a quarantine
1750
+ // (queueing a cleanup here would delete the member row the REAL machine holds).
1751
+ if (error instanceof EndpointError && error.status === 409) {
1752
+ await this.markDisplaced();
1753
+ this.lastBootVerify = { outcome: "quarantined", reason: "superseded" };
1754
+
1755
+ return this.lastBootVerify;
1756
+ }
1757
+
1758
+ const reason: "removed" | "superseded" | "refused" | "unreachable" | "unsupported" =
1759
+ error instanceof EndpointError && error.status === 410
1760
+ ? "removed"
1761
+ : error instanceof EndpointError && error.status === 409
1762
+ ? "superseded"
1763
+ : error instanceof EndpointError && error.status === 503
1764
+ ? "unsupported"
1765
+ : "refused";
1766
+
1767
+ this.lastFailure = `boot verify failed (${reason}): ${
1768
+ error instanceof Error ? error.message : String(error)
1769
+ }`;
1770
+ await this.quarantineStoredEntry();
1771
+ this.lastBootVerify = { outcome: "quarantined", reason };
1772
+
1773
+ return this.lastBootVerify;
1774
+ } finally {
1775
+ if (transport !== null) {
1776
+ await safeClose(transport);
1777
+ }
1778
+ }
1779
+ });
1780
+ }
1781
+
1782
+ /** Rejects ("unreachable") when the wall-clock deadline passes first; resolves otherwise. */
1783
+ private raceDeadline<T>(promise: Promise<T>, deadline: number): Promise<T> {
1784
+ return new Promise<T>((resolve, reject) => {
1785
+ const timer = setTimeout(
1786
+ () => {
1787
+ reject(new EndpointError(503, "boot verify window elapsed (unreachable)"));
1788
+ },
1789
+ Math.max(0, deadline - Date.now()),
1790
+ );
1791
+
1792
+ promise.then(
1793
+ (value) => {
1794
+ clearTimeout(timer);
1795
+ resolve(value);
1796
+ },
1797
+ (error) => {
1798
+ clearTimeout(timer);
1799
+ reject(error);
1800
+ },
1801
+ );
1802
+ });
1803
+ }
1804
+
1805
+ /** Verifies the rotation receipt against the pinned key and adopts the rotated credential in
1806
+ * ONE durable write. The ref must be EXACTLY the stored one (the row never moves); the
1807
+ * receipt must bind this boot's presented epoch and the new epoch/hash/expiry. */
1808
+ private async adoptVerifiedCredential(
1809
+ entry: CloudEntry,
1810
+ verified: VerifiedCredential,
1811
+ ): Promise<BootVerifyOutcome> {
1812
+ if (
1813
+ !validRef(verified.membership) ||
1814
+ !refsEqual(verified.membership, entry.membership) ||
1815
+ typeof verified.credential !== "string" ||
1816
+ verified.credential.length === 0 ||
1817
+ verified.credential.length > 1024 ||
1818
+ !Number.isSafeInteger(verified.credentialEpoch) ||
1819
+ verified.credentialEpoch < 1 ||
1820
+ !Number.isSafeInteger(verified.credentialExpiresAt) ||
1821
+ verified.credentialExpiresAt <= this.saneNow() ||
1822
+ typeof verified.receipt !== "string"
1823
+ ) {
1824
+ throw new ConnectorStateError("Malformed boot-verify answer from cloud");
1825
+ }
1826
+
1827
+ const check = await this.receiptVerifier(verified.receipt, {
1828
+ cloudId: this.pinned.cloudId,
1829
+ membership: { id: entry.membership.id, epoch: entry.membership.epoch },
1830
+ acceptedActions: ["verified"],
1831
+ fingerprint: this.identityFingerprint,
1832
+ credentialRotation: {
1833
+ fromEpoch: entry.credentialEpoch,
1834
+ toEpoch: verified.credentialEpoch,
1835
+ credentialHash: sha256Hex(Buffer.from(verified.credential, "utf8")),
1836
+ expiresAt: verified.credentialExpiresAt,
1837
+ },
1838
+ });
1839
+
1840
+ if (check === null) {
1841
+ throw new ConnectorStateError(
1842
+ "Boot-verify receipt did not verify against the pinned cloud key; credential retained for quarantine",
1843
+ );
1844
+ }
1845
+
1846
+ // §2.4: remember X's pin ONLY from a receipt that just verified (secret-free facts).
1847
+ const signer = (check.payload?.signer ?? null) as {
1848
+ signerFingerprint?: unknown;
1849
+ signerEpoch?: unknown;
1850
+ signerPublicKeySpki?: unknown;
1851
+ } | null;
1852
+
1853
+ this.verifiedSignerPin =
1854
+ signer !== null &&
1855
+ typeof signer.signerFingerprint === "string" &&
1856
+ typeof signer.signerEpoch === "number" &&
1857
+ typeof signer.signerPublicKeySpki === "string"
1858
+ ? {
1859
+ signerFingerprint: signer.signerFingerprint,
1860
+ signerEpoch: signer.signerEpoch,
1861
+ signerPublicKeySpki: signer.signerPublicKeySpki,
1862
+ }
1863
+ : null;
1864
+
1865
+ // R3: the anchored boot creates no intent, ever — and it adopts nothing else either: same
1866
+ // ref, same identity, only the credential material moves.
1867
+ const next: ConnectorSnapshot = {
1868
+ ...structuredClone(this.snapshot),
1869
+ entry: {
1870
+ membership: { ...entry.membership },
1871
+ credentialEpoch: verified.credentialEpoch,
1872
+ credential: verified.credential,
1873
+ credentialExpiresAt: verified.credentialExpiresAt,
1874
+ },
1875
+ pendingCleanups: [...this.snapshot.pendingCleanups],
1876
+ sealed: false,
1877
+ };
1878
+
1879
+ await this.store.write(next);
1880
+
1881
+ this.snapshot = next;
1882
+ this.quarantinedAtBoot = false;
1883
+ this.sealMemoryOnly = false;
1884
+ this.uncertainRemovalWrite = false;
1885
+ this.statusValue = "fresh";
1886
+ this.lastFailure = null;
1887
+
1888
+ return {
1889
+ outcome: "verified",
1890
+ membership: { ...entry.membership },
1891
+ credentialEpoch: verified.credentialEpoch,
1892
+ };
1893
+ }
1894
+
1895
+ /** ADR-19 §2: the pinned cloud answered that this record's credential was SUPERSEDED by a
1896
+ * newer verified boot of the same identity (a copied or restored disk). The dead credential is
1897
+ * kept as authority for nothing, no cleanup intent is queued — deleting the member at X here
1898
+ * would kill the machine that legitimately holds the live credential — and every lane stays
1899
+ * inert until the owner acts (revoke at X, or remove locally and re-enroll). */
1900
+ async markDisplaced(): Promise<void> {
1901
+ this.statusValue = "displaced";
1902
+ this.lastFailure =
1903
+ "displaced: a newer verified boot holds this membership's live credential";
1904
+
1905
+ if (this.transport !== null) {
1906
+ const transport = this.transport;
1907
+
1908
+ this.transport = null;
1909
+ await safeClose(transport);
1910
+ this.resolveDisconnect();
1911
+ }
1912
+ }
1913
+
1520
1914
  /**
1521
1915
  * Local `cloud remove` (§4.1): close the connector first, then atomically erase the credential
1522
1916
  * while appending the SIGNED secret-free pending cleanup request to the durable intent list
@@ -1668,6 +2062,13 @@ export class CloudConnector {
1668
2062
  this.sealMemoryOnly = false;
1669
2063
  this.cleanupAcknowledged = false;
1670
2064
 
2065
+ // The boot marker describes the DISK credential this process found at open() — held
2066
+ // inert (anchor) or quarantined (§16). A ceremony just REPLACED it with a fresh,
2067
+ // receipt-verified credential, so the marker must clear here: leaving it set kept
2068
+ // reconcile() fail-closed forever and hung the ceremony's connect watch (the
2069
+ // §16-quarantine-then-fresh-enroll lane — wiring test 5 regression).
2070
+ this.quarantinedAtBoot = false;
2071
+
1671
2072
  // Any live connection authenticated the PREVIOUS credential; force a fresh reconcile.
1672
2073
  if (this.transport !== null) {
1673
2074
  const transport = this.transport;