@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.
@@ -69,6 +69,7 @@ import {
69
69
  type RelayCloseReason,
70
70
  type RelayOpenClaim,
71
71
  type StoredCleanupRequest,
72
+ type VerifiedCredential,
72
73
  } from "./cloud-connector.ts";
73
74
 
74
75
  // REL-13: the cloud-receipt domain literal is single-sourced in
@@ -79,8 +80,12 @@ const TYPE_CONTROL = "control";
79
80
  const TYPE_DATA = "data";
80
81
  const METHOD_AUTHENTICATE = "authenticate";
81
82
  const METHOD_CLEANUP = "cleanup";
83
+ /** ADR-19: the boot verify + credential-rotation RPC on the same §6 session. */
84
+ const METHOD_VERIFY = "verify";
82
85
  const METHOD_PAIR_OFFER = "pair-offer";
83
86
  const METHOD_PAIR_REDEEM = "pair-redeem";
87
+ /** ADR-22: the read-only offer fetch for `b-accept --code` (never consumes a code). */
88
+ const METHOD_PAIR_LOOKUP = "pair-lookup";
84
89
  /** X → daemon delivered control request (§7 prepare/provisional over the live connector). */
85
90
  const METHOD_PAIR_DELIVER = "pair-deliver";
86
91
  /** M4 lane B3 relay methods: capability probe, channel open, cooperative teardown. */
@@ -627,10 +632,13 @@ export class CloudWssTransport implements CloudTransport, CloudEndpoint, RelayCa
627
632
 
628
633
  /* ------------- D2 SEC-13: the multichannel (mux) relay surface (additive) ------------- */
629
634
 
630
- /** The per-connection mux capability: probed once with the authenticated {mux:1}
635
+ /** The per-connection mux capability: probed with the authenticated {mux:1}
631
636
  * relay-caps; an old cloud (or any probe failure) reads null and every mux open fails
632
637
  * closed with a static error — exactly the legacy fail-closed pattern, no relay-open
633
- * frame ever leaves for a cloud that did not advertise mux. */
638
+ * frame ever leaves for a cloud that did not advertise mux. Only a VERIFIED advertisement
639
+ * is cached (ADR-19): a probe that raced the session's authenticate (403) must not poison
640
+ * the whole transport — the next open simply probes again, bounded by the initiator's
641
+ * own backoff. */
634
642
  async relayMuxCaps(): Promise<{ maxChannels: number } | null> {
635
643
  if (this.muxCapsValue !== undefined) {
636
644
  return this.muxCapsValue;
@@ -643,8 +651,6 @@ export class CloudWssTransport implements CloudTransport, CloudEndpoint, RelayCa
643
651
  try {
644
652
  caps = await this.rpc(METHOD_RELAY_CAPS, { d: { mux: 1 } });
645
653
  } catch {
646
- this.muxCapsValue = null;
647
-
648
654
  return null;
649
655
  }
650
656
 
@@ -993,10 +999,14 @@ export class CloudWssTransport implements CloudTransport, CloudEndpoint, RelayCa
993
999
  }
994
1000
 
995
1001
  /** §6/§14: requester/target status; an approved request also yields a fresh one-use
996
- * X-signed pickup challenge for the requester. */
997
- async pairStatus(
998
- requestId: string,
999
- ): Promise<{ view: { [key: string]: CanonicalValue }; challengeReceipt: string | null }> {
1002
+ * X-signed pickup challenge for the requester, and the target of a terminally-decided
1003
+ * request gets X's signed decision evidence (D2 recovery). */
1004
+ async pairStatus(requestId: string): Promise<{
1005
+ view: { [key: string]: CanonicalValue };
1006
+ challengeReceipt: string | null;
1007
+ decisionReceipt: string | null;
1008
+ decisionBytes: Uint8Array | null;
1009
+ }> {
1000
1010
  const result = await this.rpc("pair-status", { r: requestId });
1001
1011
  const shaped = isPlainObject(result) ? result : null;
1002
1012
 
@@ -1005,8 +1015,18 @@ export class CloudWssTransport implements CloudTransport, CloudEndpoint, RelayCa
1005
1015
  }
1006
1016
 
1007
1017
  const challenge = typeof shaped.c === "string" && shaped.c.length > 0 ? shaped.c : null;
1018
+ const decisionReceipt =
1019
+ typeof shaped.d === "string" && shaped.d.length > 0 ? shaped.d : null;
1020
+ const decisionBytes =
1021
+ typeof shaped.b === "string" && shaped.b.length > 0
1022
+ ? (Buffer.from(shaped.b, "base64url") as Uint8Array)
1023
+ : null;
1008
1024
 
1009
- return { view: shaped.view, challengeReceipt: challenge };
1025
+ if ((decisionReceipt === null) !== (decisionBytes === null)) {
1026
+ throw new EndpointError(503, "Malformed pair status result from cloud");
1027
+ }
1028
+
1029
+ return { view: shaped.view, challengeReceipt: challenge, decisionReceipt, decisionBytes };
1010
1030
  }
1011
1031
 
1012
1032
  /** §4.2/§14: the requester's sealed relation-credential pickup relayed through A. */
@@ -1103,6 +1123,25 @@ export class CloudWssTransport implements CloudTransport, CloudEndpoint, RelayCa
1103
1123
  };
1104
1124
  }
1105
1125
 
1126
+ /** ADR-22: fetches the live offer plus its §4.2 registration proof for a code WITHOUT
1127
+ * consuming it — the `b-accept --code` pre-read. The caller re-verifies every signed
1128
+ * binding before redeeming (`verifyOfferForAcceptByCode`); the cloud is never trusted for
1129
+ * offer content. Typed cloud refusals surface here with the cloud's own status (404
1130
+ * unknown code, 410 expired-or-consumed). */
1131
+ async lookupPairOffer(code: string): Promise<{
1132
+ offer: { [key: string]: CanonicalValue };
1133
+ registration: { [key: string]: CanonicalValue };
1134
+ }> {
1135
+ const result = await this.rpc(METHOD_PAIR_LOOKUP, { c: code });
1136
+ const shaped = isPlainObject(result) ? result : null;
1137
+
1138
+ if (shaped === null || !isPlainObject(shaped.o) || !isPlainObject(shaped.p)) {
1139
+ throw new EndpointError(503, "Malformed pair lookup result from cloud");
1140
+ }
1141
+
1142
+ return { offer: shaped.o, registration: shaped.p };
1143
+ }
1144
+
1106
1145
  /** Count of inbound frames refused locally (unknown type, malformed, oversize, stray id). */
1107
1146
  refusedFrameCount(): number {
1108
1147
  return this.refusedFrames;
@@ -1377,6 +1416,53 @@ export class CloudWssTransport implements CloudTransport, CloudEndpoint, RelayCa
1377
1416
  return result;
1378
1417
  }
1379
1418
 
1419
+ /** ADR-19 boot verify + credential rotation: the membership credential + a nonce-fresh
1420
+ * identity proof; the answer carries the SAME membership ref, the ROTATED credential and
1421
+ * the X-signed receipt that admits it. It never authenticates this session — the caller
1422
+ * reconnects (or reconciles) with the rotated credential afterwards. */
1423
+ async verify(
1424
+ ref: MemberRef,
1425
+ credential: string,
1426
+ credentialEpoch: number,
1427
+ proof: ConnectorProof,
1428
+ ): Promise<VerifiedCredential> {
1429
+ if (typeof credential !== "string" || credential.length === 0) {
1430
+ throw new ConnectorStateError("Cloud verify requires the membership credential");
1431
+ }
1432
+
1433
+ const result = await this.rpc(METHOD_VERIFY, {
1434
+ ref: refToWire(ref),
1435
+ c: credential,
1436
+ e: credentialEpoch,
1437
+ p: proofToWire(proof),
1438
+ });
1439
+ const body = isPlainObject(result) ? result : null;
1440
+ const refBody = body !== null && isPlainObject(body.ref) ? body.ref : null;
1441
+ const confirmed = refBody === null ? null : wireToRef(refBody);
1442
+
1443
+ if (
1444
+ confirmed === null ||
1445
+ body === null ||
1446
+ !boundedString(body.c, 1024) ||
1447
+ typeof body.e !== "number" ||
1448
+ !Number.isSafeInteger(body.e) ||
1449
+ body.e < 1 ||
1450
+ typeof body.x !== "number" ||
1451
+ !Number.isSafeInteger(body.x) ||
1452
+ !boundedString(body.receipt, MAX_CONTROL_BYTES)
1453
+ ) {
1454
+ throw new EndpointError(503, "Malformed verify result from cloud");
1455
+ }
1456
+
1457
+ return {
1458
+ membership: confirmed,
1459
+ credential: body.c,
1460
+ credentialEpoch: body.e,
1461
+ credentialExpiresAt: body.x,
1462
+ receipt: body.receipt,
1463
+ };
1464
+ }
1465
+
1380
1466
  private requireOpenSocket(): WebSocket {
1381
1467
  const ws = this.ws;
1382
1468
 
@@ -1964,6 +2050,13 @@ export function pinnedCloudReceiptVerifier(input: {
1964
2050
  "requestHash",
1965
2051
  "requestNonce",
1966
2052
  "fingerprint",
2053
+ // ADR-19 boot-verify receipts: the rotation binds the presented epoch and
2054
+ // the new credential's epoch/hash/expiry, and echoes X's §13 pin.
2055
+ "fromCredentialEpoch",
2056
+ "credentialEpoch",
2057
+ "credentialHash",
2058
+ "expiresAt",
2059
+ "signer",
1967
2060
  ],
1968
2061
  ) ||
1969
2062
  typeof signature !== "string" ||
@@ -2002,7 +2095,20 @@ export function pinnedCloudReceiptVerifier(input: {
2002
2095
  return null;
2003
2096
  }
2004
2097
 
2005
- return { action: payload.action };
2098
+ // ADR-19: a boot-verify receipt must bind this rotation exactly when the caller
2099
+ // asked for those bindings (the connector always does); anything else never verifies.
2100
+ if (expected.credentialRotation !== undefined) {
2101
+ if (
2102
+ payload.fromCredentialEpoch !== expected.credentialRotation.fromEpoch ||
2103
+ payload.credentialEpoch !== expected.credentialRotation.toEpoch ||
2104
+ payload.credentialHash !== expected.credentialRotation.credentialHash ||
2105
+ payload.expiresAt !== expected.credentialRotation.expiresAt
2106
+ ) {
2107
+ return null;
2108
+ }
2109
+ }
2110
+
2111
+ return { action: payload.action, payload };
2006
2112
  } catch {
2007
2113
  return null;
2008
2114
  }