@serfab/cadre-core 1.13.0 → 1.14.0

package/src/control-stream.ts

@@ -35,6 +35,10 @@ export interface ControlStream extends AsyncIterable<Uint8Array> {
   send(data: Uint8Array): boolean;
   close(): Promise<void>;
   abort(err: Error): void;
+  /** Whether the remote has half-closed its write end (`'closed'`); absent on test doubles. */
+  readonly remoteWriteStatus?: string;
+  /** Bytes received and not yet read; absent on test doubles. */
+  readonly readBufferLength?: number;
 }
 
 /** Write a JSON object as a single 4-byte big-endian length-prefixed frame. */
@@ -206,16 +210,31 @@ export function readStreamToEnd(
   return Promise.race([readLoop, timeout]).finally(() => clearTimeout(timer));
 }
 
-/** Accumulate every chunk to EOF, rejecting once the running total exceeds `maxBytes`. */
+/**
+ * Accumulate every chunk to EOF, rejecting once the running total exceeds `maxBytes`.
+ *
+ * A remote that half-closed before this read began has already sent everything it will,
+ * so the read ends once those buffered bytes are in. Its own end-of-stream cannot be
+ * waited for: libp2p 3.3.11's stream iterator ends on the one-shot `remoteCloseWrite`
+ * event, and an iterator attached after it fired never ends. That happens to any handler
+ * that awaits before reading, as the control-protocol guard's live membership check makes
+ * the wake and strand-addr handlers do.
+ */
 async function collect(stream: ControlStream, maxBytes: number, label: string): Promise<Uint8Array> {
   const chunks: Uint8Array[] = [];
   let total = 0;
-  for await (const chunk of stream) {
-    const bytes = toBytes(chunk);
-    chunks.push(bytes);
-    total += bytes.length;
-    if (total > maxBytes) {
-      throw new Error(`${label} message too large: ${total} bytes exceeds max ${maxBytes}`);
+  const alreadySent = stream.remoteWriteStatus === 'closed' ? (stream.readBufferLength ?? 0) : undefined;
+  if (alreadySent !== 0) {
+    for await (const chunk of stream) {
+      const bytes = toBytes(chunk);
+      chunks.push(bytes);
+      total += bytes.length;
+      if (total > maxBytes) {
+        throw new Error(`${label} message too large: ${total} bytes exceeds max ${maxBytes}`);
+      }
+      if (alreadySent !== undefined && total >= alreadySent) {
+        break;
+      }
     }
   }
 

package/src/delegate-admission.ts

@@ -21,7 +21,7 @@
  * granted delegate is admitted outright, never drawing on the small
  * unauthorized-reservation budget that unplaced peers share
  * (`membership-connection-gater.ts` → "The relay-reservation seam") and never
- * racing its not-reserving connection deadline. The fail-closed per-stream gate
+ * put on the provisional connection deadline. The fail-closed per-stream gate
  * (`authorizeInboundControlStream`) never honors a grant, so a delegate gets
  * the connection and its reservation (all a circuit-relay `hop` needs) and
  * nothing more.

package/src/device-token.ts

@@ -9,15 +9,16 @@
  * encoding, so no field split is ambiguous even with an opaque platform token. It
  * is intentionally NOT JSON-canonicalized (deterministic across node/browser/RN,
  * no key ordering) and is reconstructable inside the `DeviceToken.AuthorizedUpdate`
- * SQL constraint from the row's own columns:
+ * SQL constraint from the row's own columns and the node-local `party_id()`:
  *
- *   digest('CadreControl.DeviceToken', 'publish',
+ *   digest('CadreControl.DeviceToken', 'publish', party_id(),
  *          new.PeerId, new.Platform, new.Token, cast(new.UpdatedAt as text))
  *
  * Keep {@link deviceTokenSignedPayload} and that constraint byte-for-byte in sync.
  * The `'publish'` action tag marks this as a peer's SELF-signed record (signed with
  * the peer's own key, not an owner key) and keeps it disjoint from every
- * owner-signed digest.
+ * owner-signed digest; the party id keeps a record published into one party's table
+ * from verifying in another's (peer-record.ts says why a node uses its own party).
  *
  * Unlike a peer-address record, a device-token record carries NO public key: the
  * signature is verified against the `CadrePeer.PublicKey` bound to the same PeerId
@@ -34,10 +35,11 @@ import type { DeviceTokenRecord, PushPlatform } from './types.js';
  * `DeviceToken.AuthorizedUpdate` constraint exactly; both sides take the default
  * base64url output of a single `digest(...)`, which round-trips cleanly.
  */
-export function deviceTokenSignedPayload(record: Omit<DeviceTokenRecord, 'sig'>): string {
+export function deviceTokenSignedPayload(partyId: string, record: Omit<DeviceTokenRecord, 'sig'>): string {
   const fields = controlAuthorizationFields(
     'CadreControl.DeviceToken',
     'publish',
+    partyId,
     [record.peerId, record.platform, record.token, String(record.updatedAt)]
   );
   return digest(fields, 'sha256', 'base64url') as string;
@@ -47,14 +49,16 @@ export function deviceTokenSignedPayload(record: Omit<DeviceTokenRecord, 'sig'>)
  * Sign a device-token record with the ed25519 private key behind its `peerId`.
  * Returns a fully-populated {@link DeviceTokenRecord}.
  *
+ * @param partyId - the party whose `DeviceToken` table the record is published into
  * @param fields - the record fields to sign
  * @param privateKeyB64 - base64url ed25519 seed (see `ed25519KeyPairFromLibp2p`)
  */
 export function signDeviceTokenRecord(
+  partyId: string,
   fields: Omit<DeviceTokenRecord, 'sig'>,
   privateKeyB64: string
 ): DeviceTokenRecord {
-  const payloadDigest = deviceTokenSignedPayload(fields);
+  const payloadDigest = deviceTokenSignedPayload(partyId, fields);
   const sig = sign(
     payloadDigest,
     privateKeyB64,
@@ -68,15 +72,15 @@ export function signDeviceTokenRecord(
 
 /**
  * Verify a record's self-signature against the `CadrePeer.PublicKey` (base64url)
- * bound to its `peerId`. Reconstructs the signed bytes from the record exactly as
- * {@link signDeviceTokenRecord} produced them. Returns false on a missing key/sig or
- * any verification failure.
+ * bound to its `peerId`, for `partyId`. Reconstructs the signed bytes from the record
+ * exactly as {@link signDeviceTokenRecord} produced them. Returns false on a missing
+ * key/sig or any verification failure.
  */
-export function verifyDeviceTokenSignature(record: DeviceTokenRecord, publicKeyB64: string): boolean {
+export function verifyDeviceTokenSignature(partyId: string, record: DeviceTokenRecord, publicKeyB64: string): boolean {
   if (!publicKeyB64 || !record.sig) {
     return false;
   }
-  const payloadDigest = deviceTokenSignedPayload(record);
+  const payloadDigest = deviceTokenSignedPayload(partyId, record);
   return verify(
     payloadDigest,
     record.sig,

package/src/ed25519-key.ts

@@ -1,5 +1,6 @@
 import { toString as uint8ArrayToString, fromString as uint8ArrayFromString } from 'uint8arrays';
 import { getPublicKey } from '@optimystic/quereus-plugin-crypto';
+import { peerIdFromString } from '@libp2p/peer-id';
 import type { PrivateKey } from '@libp2p/interface';
 
 /**
@@ -68,12 +69,38 @@ export function ed25519PublicKeyFromPrivate(privateKeyB64: string): string {
   return getPublicKey(privateKeyB64, 'ed25519', 'base64url', 'base64url') as string;
 }
 
+/**
+ * Derive the base64url ed25519 public key embedded in an Ed25519 libp2p PeerId.
+ *
+ * An Ed25519 PeerId is an identity multihash of the public key, so
+ * `peerIdFromString(id).publicKey.raw` is the 32-byte ed25519 key whose
+ * base64url form matches the `OwnerKey.Key` representation (and
+ * `ed25519KeyPairFromLibp2p().publicKeyB64`). Returns null for a non-Ed25519
+ * id, a missing embedded key, or any parse failure — callers treat null as
+ * "not an owner" rather than throwing.
+ *
+ * Lives here, beside the other key bridges, so the lightweight verifiers in
+ * `peer-authorization.ts` can check a stored `PeerKey` against a row's `PeerId`
+ * without importing the seed-bootstrap runtime.
+ */
+export function ed25519PublicKeyB64FromPeerId(peerId: string): string | null {
+  try {
+    const parsed = peerIdFromString(peerId);
+    if (parsed.type !== 'Ed25519' || !parsed.publicKey) {
+      return null;
+    }
+    return uint8ArrayToString(parsed.publicKey.raw, 'base64url');
+  } catch {
+    return null;
+  }
+}
+
 /** Longest rejected key value echoed back in an error — a real key is 43 base64url chars. */
 const REJECTED_VALUE_ECHO_LIMIT = 64;
 
 /**
  * Render a rejected value for an error message, capped: owner keys now reach this check
- * from remote-supplied fields (a `CadreInvite`'s `ownerKeys`, a donation request's
+ * from remote-supplied fields (a cadre invitation's `ownerKeys`, a donation request's
  * `ownerKeys`), so an unbounded echo would let a peer turn one junk string into a
  * megabyte of log line.
  */

package/src/index.ts

@@ -5,10 +5,10 @@ export * from './types.js';
 export { canonicalJson } from './canonical-json.js';
 
 // Main CadreNode class
-export { CadreNode } from './cadre-node.js';
+export { CadreNode, OWNER_INVITATION_DEFAULT_TTL_MS, CADRE_INVITATION_DEFAULT_TTL_MS } from './cadre-node.js';
 
 // Control database
-export { ControlDatabase, MissingHostStrandError, buildAuthorizationMessage, formationVouchMessage, formationConsentMessage, REAPABLE_TABLES, type ReapableTable, type ControlDatabaseConfig, type ControlTable, type RevocableTable, type FormationUsageResult, type MembershipChangeListener, type GuardedDeleteListener, type ControlWriteAbandonedListener, type RevokedRowRef } from './control-database.js';
+export { ControlDatabase, MissingHostStrandError, InvitationExhaustedError, CadreInviteIssuerUnknownError, buildAuthorizationMessage, registerPartyIdFunction, formationVouchMessage, formationConsentMessage, cadreInviteAddMessage, cadreInviteRedeemMessage, cadreInviteConsentMessage, projectSeedPeers, REAPABLE_TABLES, type ReapableTable, type ControlDatabaseConfig, type ControlTable, type RevocableTable, type FormationUsageResult, type MembershipChangeListener, type GuardedDeleteListener, type ControlWriteAbandonedListener, type RevokedRowRef } from './control-database.js';
 
 // Bounded retry for transient control-write failures (classifier + loop behind
 // ControlDatabase.lockedWithRetry; exported so the integration package can drive the
@@ -45,10 +45,10 @@ export type {
 } from './control-retry.js';
 
 // Control-plane authorization field vector (the domain/action tagging every signer shares)
-export { controlAuthorizationFields, type ControlDomain, type ControlAction } from './control-authorization.js';
+export { controlAuthorizationFields, unboundAuthorizationFields, cadreInviteRowFields, type ControlDomain, type BoundControlDomain, type UnboundControlDomain, type ControlAction, type CadreInviteSignedFields } from './control-authorization.js';
 
 // Ed25519 key bridge (libp2p Ed25519 -> base64url keypair)
-export { ed25519KeyPairFromLibp2p, ed25519PublicKeyFromPrivate, requireEd25519PublicKeyB64, type Ed25519KeyPair } from './ed25519-key.js';
+export { ed25519KeyPairFromLibp2p, ed25519PublicKeyFromPrivate, ed25519PublicKeyB64FromPeerId, requireEd25519PublicKeyB64, type Ed25519KeyPair } from './ed25519-key.js';
 
 // Pluggable key store (backend-agnostic identity/owner key material seam).
 // Dependency-free: the interface, error, default slot id, and in-memory backend
@@ -362,7 +362,8 @@ export {
 export {
   SeedBootstrapService,
   SEED_PROTOCOL,
-  ed25519PublicKeyB64FromPeerId,
+  mergeSeedPeers,
+  seedDigest,
   type SeedBootstrapConfig,
   type SeedEventCallbacks
 } from './seed-bootstrap.js';
@@ -375,12 +376,27 @@ export {
   deviceTokenAddDigest,
   deviceTokenRemoveDigest,
   formationConsentDigest,
+  cadreInviteAddDigest,
+  cadreInviteRedeemDigest,
+  cadreInviteConsentDigest,
+  ownerKeyAddDigest,
   verifyPeerAuthorization,
   verifyCadrePeerVoucher,
+  verifyOwnerKeyVoucher,
+  verifyRevocationSigner,
   verifyFormationConsent,
+  verifyInvitationAdmission,
+  verifyInvitationOwnerAdmission,
+  verifyCadreInviteRow,
+  verifyCadreInviteRedemption,
   type DeviceTokenAuthorizedRow
 } from './peer-authorization.js';
 
+// How the trusted-owner anchor follows the replicated OwnerKey table along verifiable
+// chains: the pure derivation rule `CadreNode.syncOwnerAnchor` applies on every membership
+// refresh (owner-anchor-sync.ts).
+export { deriveOwnerAnchor, type OwnerAnchorInputs, type OwnerAnchorDerivation } from './owner-anchor-sync.js';
+
 // Strand Wake (control-network push-wake protocol)
 export {
   StrandWakeService,
@@ -469,6 +485,7 @@ export {
 export {
   dialPeerAddrs,
   SelfRelayOnlyError,
+  PeerUnreachableError,
   tryAddrsInTurn,
   directBeforeRelayed,
   DEFAULT_CONTROL_COHORT_DIAL_TIMEOUT_MS,
@@ -508,11 +525,35 @@ export {
   anchoredTrustPolicy,
   pinnedKeyTrustPolicy,
   tofuTrustPolicy,
+  claimSecretTrustPolicy,
   type SeedTrustPolicy,
   type SeedTrustContext,
-  type SeedTrustDecision
+  type SeedTrustDecision,
+  type ClaimSecretTrustPolicyOptions
 } from './seed-trust-policy.js';
 
+// Claim proof: how a brand-new node's first seed proves its sender holds the node's
+// one-time claim secret. The owner side builds the proof over `seedDigest` (exported
+// with the seed bootstrap above); `claimSecretTrustPolicy` verifies it.
+// `ClaimRefusedError` is what `CadreNode.claimNode` throws when the node said no;
+// `PeerUnreachableError` (exported with the peer dial above) when it was never reached.
+export {
+  parseClaimSecret,
+  claimProof,
+  verifyClaimProof,
+  ClaimRefusedError,
+  CLAIM_SECRET_BYTES
+} from './claim-proof.js';
+
+// The claim payload: the node's peer id, addresses and claim secret as the text a host
+// shows as a QR code and a phone scans (`CadreNode.claimNode` takes the decoded form).
+export {
+  encodeNodeClaimPayload,
+  decodeNodeClaimPayload,
+  NODE_CLAIM_PAYLOAD_PREFIX,
+  type NodeClaimPayload
+} from './node-claim-payload.js';
+
 // Schema Verification
 export {
   signSchema,
@@ -553,6 +594,35 @@ export {
   type FormationRejectionCode
 } from './strand-formation-rejection.js';
 export { formationDeadlines, type FormationDeadlines } from './strand-formation-deadlines.js';
+// Cadre invitation redemption transport: the bundle an owner hands out, the wire messages, the
+// member-side handler and the device-side dialer, and how a redemption fails
+export {
+  CadreInviteHandler,
+  redeemAtMembers,
+  signRedeemRequest,
+  verifyRedeemReply,
+  encodeCadreInvitation,
+  decodeCadreInvitation,
+  isWellFormedCadreInviteRow,
+  sanitizeAddrs,
+  CadreInviteRejectedError,
+  CadreInviteUnreachableError,
+  CadreInviteReplyInvalidError,
+  CADRE_INVITE_PROTOCOL,
+  CADRE_INVITE_REJECTION_RETRYABLE,
+  isCadreInviteRejectionCode,
+  type CadreInvitation,
+  type CadreInviteRedeemRequest,
+  type CadreInviteRedeemReply,
+  type CadreInviteAccepted,
+  type CadreInviteRejectionCode,
+  type CadreInviteAddressOutcome,
+  type CadreInviteHandlerOptions,
+  type CadreInviteStore,
+  type RedeemAtMembersOptions,
+  type RedeemSigner,
+  type CadreInviteRedemption
+} from './cadre-invite-protocol.js';
 // The pending-join retry loop behind CadreNode.requestJoin (PendingJoinStatus is in types.ts)
 export { PENDING_JOIN_POLL_MS, PENDING_JOIN_MAX_BACKOFF_MS, MAX_PENDING_JOIN_MS } from './pending-join-runner.js';
 
@@ -569,13 +639,17 @@ export {
   type StrandFormationManagerOptions
 } from './strand-formation-manager.js';
 
+// Control-network per-stream protocol guard (which peers may open which protocol)
+export {
+  controlProtocolClasses,
+  type ControlProtocolClass
+} from './control-protocol-guard.js';
+
 // Control-network inbound connection gate (membership defense-in-depth)
 export {
   createMembershipConnectionGater,
-  STRANGER_OPEN_PROTOCOLS,
-  DEFAULT_ENROLLMENT_WINDOW_MS,
-  RELAY_ADMISSION_RESERVE_DEADLINE_MS,
-  RELAY_ADMISSION_CLOSE_TIMEOUT_MS,
+  PROVISIONAL_ADMISSION_DEADLINE_MS,
+  PROVISIONAL_ADMISSION_CLOSE_TIMEOUT_MS,
   MAX_UNAUTHORIZED_RELAY_RESERVATIONS,
   UnauthorizedReservationBudget,
   type InboundAdmissionPolicy,

package/src/link-budget.ts

@@ -73,9 +73,7 @@
  * Every row that opens a relayed connection counts opening the relay connection too
  * ({@link RELAYED_DIAL_ROUND_TRIPS}), because a dialer cannot know beforehand whether it holds
  * one, and a budget that is too short fails as silently as an absent peer. The
- * reservation-request row is {@link RELAY_RESERVE_REQUEST_ROUND_TRIPS}, which also sizes how long
- * a party-run relay waits for a stranger's reservation ({@link relayAdmissionReserveDeadlineMs}).
- * The commit row is a measurement of a whole write, not a count of exchanges; its doc comment
+ * reservation-request row is {@link RELAY_RESERVE_REQUEST_ROUND_TRIPS}. The commit row is a measurement of a whole write, not a count of exchanges; its doc comment
  * ({@link COMMIT_ROUND_TRIPS}) holds the figures and says when to re-measure it.
  *
  * **Measured** 2026-09-26, one Windows machine, loopback dedicated relay: a relayed dial over a
@@ -198,10 +196,10 @@
  *   the host derives its provisioning budget from its own, so a joiner declaring a faster
  *   link than the host gives up on a reply the host is still entitled to send. Declare the
  *   same link on every machine of a party.
- *   Relay admission too: a party-run relay derives how long a stranger has to ask for a
- *   reservation from ITS declaration ({@link relayAdmissionReserveDeadlineMs}), so a relay
- *   declaring a faster link than a client closes that client's connection before its request
- *   arrives.
+ *   Provisional admission too: a member derives how long it keeps a connection from a peer it
+ *   cannot place from ITS declaration ({@link relayedRequestBudgetMs}), so a member declaring a
+ *   faster link than a redeeming device can close that device's connection while the device is
+ *   still waiting on its redemption.
  */
 
 import { resolveLinkDeadlines, type Libp2pConnectionTimeouts, type RpcDeadlineDefaults } from '@optimystic/db-p2p';
@@ -261,20 +259,19 @@ export const RELAY_DIAL_ROUND_TRIPS = 1;
 export const RELAYED_DIAL_ROUND_TRIPS = RELAY_DIAL_ROUND_TRIPS + CIRCUIT_DIAL_ROUND_TRIPS;
 
 /**
- * Link round trips from the moment a party-run relay admits a stranger's connection for relay
- * use to the moment that stranger's RESERVE request reaches it. libp2p's reservation store
- * (`@libp2p/circuit-relay-v2`'s `addRelay`) opens the hop stream the instant its dial resolves,
- * without waiting for identify, so:
+ * Link round trips from the moment a relay accepts a client's connection to the moment that
+ * client's RESERVE request reaches it. libp2p's reservation store (`@libp2p/circuit-relay-v2`'s
+ * `addRelay`) opens the hop stream the instant its dial resolves, without waiting for identify,
+ * so:
  *
  * 1. The client's last Noise handshake message and its hop-stream open arrive at the relay
- *    together. The relay's gate runs on the handshake message (and arms the reserve deadline),
- *    then the relay answers the protocol negotiation.
+ *    together. A party-run relay's gate runs on the handshake message, then the relay answers
+ *    the protocol negotiation.
  * 2. The answer reaches the client and the client's RESERVE request reaches the relay: one round
  *    trip on the client-to-relay hop, which is the whole link round trip when all of the link's
  *    delay is on the client's own hop (a phone on a congested mobile link).
  *
- * The relay's decision on that request is local time, not link time;
- * {@link relayAdmissionReserveDeadlineMs} adds it separately.
+ * The relay's decision on that request is local time, not link time.
  */
 export const RELAY_RESERVE_REQUEST_ROUND_TRIPS = 1;
 
@@ -511,23 +508,6 @@ export function relayReservationBudgetMs(linkRoundTripMs?: number): number {
 	return RELAY_RESERVATION_ROUND_TRIPS * resolveLinkRoundTripMs(linkRoundTripMs) + 2 * ADMISSION_DECISION_TIMEOUT_MS;
 }
 
-/**
- * How long a party-run relay keeps a connection it admitted only for relay use
- * (`membership-connection-gater.ts`'s `'admit-for-relay'`) before closing it, unless a
- * reservation is admitted on it first: {@link RELAY_RESERVE_REQUEST_ROUND_TRIPS} at the declared
- * link round trip, plus one {@link ADMISSION_DECISION_TIMEOUT_MS} for the relay's own decision on
- * the reservation (`denyInboundRelayReservation`), which disarms the timer only once it settles.
- * 3 500 + 2 000 = 5 500 ms at the default declaration.
- *
- * The declaration is the RELAY's own, because the relay is the machine that decides.
- *
- * What it costs, against the fixed 5 000 ms it replaced: a stranger that connects and never
- * reserves holds a mute connection 0.5 s longer at the default declaration.
- */
-export function relayAdmissionReserveDeadlineMs(linkRoundTripMs?: number): number {
-	return RELAY_RESERVE_REQUEST_ROUND_TRIPS * resolveLinkRoundTripMs(linkRoundTripMs) + ADMISSION_DECISION_TIMEOUT_MS;
-}
-
 /**
  * Deadline for one request and its answer over a circuit that is already open —
  * {@link CIRCUIT_REQUEST_ROUND_TRIPS} at the declared link round trip, plus `transferAllowanceMs`
@@ -549,6 +529,10 @@ export function circuitRequestBudgetMs(
  *
  * No transfer allowance, unlike {@link circuitRequestBudgetMs}: the requests this bounds are a few
  * hundred bytes to a few KB, so their bytes cost nothing a round trip does not already cover.
+ *
+ * A control node also keeps a connection it admitted provisionally this long, at its own
+ * declaration, because a cadre invitation redemption is bounded by this budget on the device's
+ * side (`membership-connection-gater.ts`, `PROVISIONAL_ADMISSION_DEADLINE_MS`).
  */
 export function relayedRequestBudgetMs(linkRoundTripMs?: number): number {
 	return relayedDialBudgetMs(linkRoundTripMs) + CIRCUIT_REQUEST_ROUND_TRIPS * resolveLinkRoundTripMs(linkRoundTripMs);