@bom-pi/core 0.2.4 → 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 +2 -2
- package/src/cloud-connector.ts +411 -10
- package/src/cloud-wss-transport.ts +116 -10
- package/src/device-ceremony.ts +445 -16
- package/src/relay-boundary.ts +63 -1
package/package.json
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@bom-pi/core",
|
|
3
|
-
"version": "0.2.
|
|
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.
|
|
8
|
+
"@bom-pi/protocol": "^0.1.2"
|
|
9
9
|
},
|
|
10
10
|
"exports": {
|
|
11
11
|
"./cloud-connector.ts": "./src/cloud-connector.ts",
|
package/src/cloud-connector.ts
CHANGED
|
@@ -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:
|
|
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
|
-
|
|
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
|
|
891
|
-
*
|
|
892
|
-
*
|
|
893
|
-
*
|
|
894
|
-
*
|
|
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;
|