@serfab/cadre-core 1.13.0 → 1.14.0

package/src/peer-authorization.ts

@@ -1,18 +1,27 @@
 import debug from 'debug';
 import { digest, verify } from '@optimystic/quereus-plugin-crypto';
-import { controlAuthorizationFields } from './control-authorization.js';
-import type { ControlAction, ControlDomain, RevocableTable } from './control-authorization.js';
+import { controlAuthorizationFields, unboundAuthorizationFields, cadreInviteRowFields } from './control-authorization.js';
+import type { BoundControlDomain, CadreInviteSignedFields, ControlAction, RevocableTable, UnboundControlDomain } from './control-authorization.js';
+import { ed25519PublicKeyB64FromPeerId } from './ed25519-key.js';
+import type { CadreInviteRow, CadreInviteUsageRow, CadrePeerVoucherFields, OwnerKeyRow, RevocationRow } from './types.js';
 
 const log = debug('sereus:cadre:peer-authorization');
 
 /**
- * base64url SHA-256 digest over the shared domain-tagged field vector (see
+ * base64url SHA-256 digest over the shared domain-tagged, party-bound field vector (see
  * control-authorization.ts). The base64url twin of
  * control-database.ts:buildAuthorizationMessage (which returns the same digest as raw
  * bytes): sign either encoding with input encoding to match and the signed bytes agree.
+ * `partyId` is the party the verifier is configured for: a stored proof minted for
+ * another party fails here exactly as it fails the schema's `party_id()`-bound check.
  */
-function taggedDigest(domain: ControlDomain, action: ControlAction, rowFields: string[]): string {
-  return digest(controlAuthorizationFields(domain, action, rowFields), 'sha256', 'base64url') as string;
+function taggedDigest(domain: BoundControlDomain, action: ControlAction, partyId: string, rowFields: string[]): string {
+  return digest(controlAuthorizationFields(domain, action, partyId, rowFields), 'sha256', 'base64url') as string;
+}
+
+/** {@link taggedDigest} for the two party-free digests (`UnboundControlDomain`). */
+function unboundTaggedDigest(domain: UnboundControlDomain, action: ControlAction, rowFields: string[]): string {
+  return digest(unboundAuthorizationFields(domain, action, rowFields), 'sha256', 'base64url') as string;
 }
 
 /**
@@ -27,7 +36,7 @@ function taggedDigest(domain: ControlDomain, action: ControlAction, rowFields: s
  * here and both move together.
  */
 export function peerAuthorizationDigest(peerId: string): string {
-  return taggedDigest('Cadre.Enrollment', 'vouch', [peerId]);
+  return unboundTaggedDigest('Cadre.Enrollment', 'vouch', [peerId]);
 }
 
 /**
@@ -54,7 +63,7 @@ export interface DeviceTokenAuthorizedRow {
 /**
  * Canonical digest an owner signs to authorize a `DeviceToken` INSERT — the WHOLE row,
  * ending in its single-use `StampId` nonce. SQL mirror:
- * `digest('CadreControl.DeviceToken', 'add', new.PeerId, new.Platform, new.Token,
+ * `digest('CadreControl.DeviceToken', 'add', party_id(), new.PeerId, new.Platform, new.Token,
  * coalesce(cast(new.UpdatedAt as text), ''), coalesce(new.Sig, ''), new.StampId)` in
  * `DeviceToken.AuthorizedInsert`.
  *
@@ -70,8 +79,8 @@ export interface DeviceTokenAuthorizedRow {
  * Distinct from {@link deviceTokenRemoveDigest} so a captured insert approval can never
  * be replayed to delete the token, and vice versa.
  */
-export function deviceTokenAddDigest(row: DeviceTokenAuthorizedRow): string {
-  return taggedDigest('CadreControl.DeviceToken', 'add', [
+export function deviceTokenAddDigest(partyId: string, row: DeviceTokenAuthorizedRow): string {
+  return taggedDigest('CadreControl.DeviceToken', 'add', partyId, [
     row.peerId,
     row.platform,
     row.token,
@@ -84,7 +93,7 @@ export function deviceTokenAddDigest(row: DeviceTokenAuthorizedRow): string {
 /**
  * Canonical digest an owner signs to authorize a `DeviceToken` DELETE, bound to the
  * STORED row's (PeerId, StampId). SQL mirror:
- * `digest('CadreControl.DeviceToken', 'remove', old.PeerId, old.StampId)` in
+ * `digest('CadreControl.DeviceToken', 'remove', party_id(), old.PeerId, old.StampId)` in
  * `DeviceToken.AuthorizedDelete`.
  *
  * A narrower vector than {@link deviceTokenAddDigest} on purpose (the same split
@@ -92,8 +101,8 @@ export function deviceTokenAddDigest(row: DeviceTokenAuthorizedRow): string {
  * cannot be re-cut into an insert approval, and it is dead the moment the stamp it
  * names is tombstoned.
  */
-export function deviceTokenRemoveDigest(peerId: string, stampId: string): string {
-  return taggedDigest('CadreControl.DeviceToken', 'remove', [peerId, stampId]);
+export function deviceTokenRemoveDigest(partyId: string, peerId: string, stampId: string): string {
+  return taggedDigest('CadreControl.DeviceToken', 'remove', partyId, [peerId, stampId]);
 }
 
 /**
@@ -107,10 +116,10 @@ export function deviceTokenRemoveDigest(peerId: string, stampId: string): string
  * a delete. The domain tag keeps the stored, replicated `VouchSig` useless against
  * every OTHER table's rules.
  *
- * SQL mirror: `digest('CadreControl.CadrePeer', 'vouch', new.PeerId, new.StampId)`.
+ * SQL mirror: `digest('CadreControl.CadrePeer', 'vouch', party_id(), new.PeerId, new.StampId)`.
  */
-export function cadrePeerVoucherDigest(peerId: string, stampId: string): string {
-  return taggedDigest('CadreControl.CadrePeer', 'vouch', [peerId, stampId]);
+export function cadrePeerVoucherDigest(partyId: string, peerId: string, stampId: string): string {
+  return taggedDigest('CadreControl.CadrePeer', 'vouch', partyId, [peerId, stampId]);
 }
 
 /**
@@ -122,10 +131,10 @@ export function cadrePeerVoucherDigest(peerId: string, stampId: string): string
  * delete lands, because a re-added row carries a FRESH `StampId` (the removed row's
  * stamp is retired into `CadreControl.Revocation` and never reused).
  *
- * SQL mirror: `digest('CadreControl.CadrePeer', 'remove', old.PeerId, old.StampId)`.
+ * SQL mirror: `digest('CadreControl.CadrePeer', 'remove', party_id(), old.PeerId, old.StampId)`.
  */
-export function cadrePeerRemoveDigest(peerId: string, stampId: string): string {
-  return taggedDigest('CadreControl.CadrePeer', 'remove', [peerId, stampId]);
+export function cadrePeerRemoveDigest(partyId: string, peerId: string, stampId: string): string {
+  return taggedDigest('CadreControl.CadrePeer', 'remove', partyId, [peerId, stampId]);
 }
 
 /**
@@ -134,7 +143,7 @@ export function cadrePeerRemoveDigest(peerId: string, stampId: string): string {
  * (the removed row's primary key: OwnerKey.Key / ValidationKey.Key /
  * CadrePeer.PeerId / DeviceToken.PeerId / Strand.Id) as which row was retired.
  * SQL mirror:
- * `digest('CadreControl.Revocation', 'remove', new.TableName, new.RowKey, new.StampId)`
+ * `digest('CadreControl.Revocation', 'remove', party_id(), new.TableName, new.RowKey, new.StampId)`
  * in `Revocation.Authorized`.
  *
  * Its own `'CadreControl.Revocation'` domain tag makes it disjoint from the
@@ -143,8 +152,48 @@ export function cadrePeerRemoveDigest(peerId: string, stampId: string): string {
  * this tombstone accompanies — a removal signature is not a retirement
  * signature and cannot be replayed as one.
  */
-export function revocationDigest(tableName: RevocableTable, rowKey: string, stampId: string): string {
-  return taggedDigest('CadreControl.Revocation', 'remove', [tableName, rowKey, stampId]);
+export function revocationDigest(partyId: string, tableName: RevocableTable, rowKey: string, stampId: string): string {
+  return taggedDigest('CadreControl.Revocation', 'remove', partyId, [tableName, rowKey, stampId]);
+}
+
+/**
+ * Does a `Revocation` row's stored signer pair (`SignerKey` / `SignerSig`) verify over the
+ * tombstone's own triple, for `partyId`? The read-side mirror of `Revocation.Authorized`,
+ * for a node that received the row by replication and must decide whether to honour it.
+ * Whether `row.signerKey` is an owner this node trusts is the caller's question, as for
+ * {@link verifyCadrePeerVoucher}. Never throws: a malformed row verifies as `false`.
+ */
+export function verifyRevocationSigner(partyId: string, row: RevocationRow): boolean {
+  try {
+    return verifyB64(revocationDigest(partyId, row.tableName, row.rowKey, row.stampId), row.signerSig, row.signerKey);
+  } catch (error) {
+    log('verifyRevocationSigner failed: %o', error);
+    return false;
+  }
+}
+
+/**
+ * Canonical digest an owner signs to seat a further `OwnerKey` row — the signed-add branch
+ * of `OwnerKey.Authorized`, which stores the pair as `VouchOwner` / `VouchSig`. SQL mirror:
+ * `digest('CadreControl.OwnerKey', 'add', party_id(), new.Key, new.StampId)`. The removal
+ * digest needs no builder here: it is the generic guarded `'remove'` digest over (Key, StampId).
+ */
+export function ownerKeyAddDigest(partyId: string, key: string, stampId: string): string {
+  return taggedDigest('CadreControl.OwnerKey', 'add', partyId, [key, stampId]);
+}
+
+/**
+ * Does an owner-signed `OwnerKey` row's stored voucher verify — `vouchSig` by `vouchOwner`
+ * over {@link ownerKeyAddDigest} for (`partyId`, `key`, `stampId`)? Whether `vouchOwner` is
+ * anchored is the caller's question, as for {@link verifyCadrePeerVoucher}. Never throws.
+ */
+export function verifyOwnerKeyVoucher(partyId: string, key: string, stampId: string, vouchOwner: string, vouchSig: string): boolean {
+  try {
+    return verifyB64(ownerKeyAddDigest(partyId, key, stampId), vouchSig, vouchOwner);
+  } catch (error) {
+    log('verifyOwnerKeyVoucher failed: %o', error);
+    return false;
+  }
 }
 
 /**
@@ -184,12 +233,13 @@ export function verifyPeerAuthorization(
 
 /**
  * Verify that `signature` is a valid owner ed25519 signature over the
- * `CadrePeer` voucher digest for (`peerId`, `stampId`) — the read-side mirror
- * of the voucher {@link ControlDatabase.insertCadrePeer} signs and persists into
+ * `CadrePeer` voucher digest for (`partyId`, `peerId`, `stampId`) — the read-side
+ * mirror of the voucher {@link ControlDatabase.insertCadrePeer} signs and persists into
  * `VouchOwner`/`VouchSig` (see {@link cadrePeerVoucherDigest}).
  *
  * A `true` result means the holder of `ownerPublicKey` vouched THIS membership
- * row (the peer id bound to the row's single-use `StampId` nonce). It says
+ * row (the peer id bound to the row's single-use `StampId` nonce) in THIS party: a
+ * voucher copied from another party's table that shares the owner key fails. It says
  * nothing about whether that owner key is itself trustworthy — the caller must
  * separately check the key against the node-local trusted-owner anchor
  * (`TrustedOwnerStore`), never the replicated `OwnerKey` table.
@@ -199,6 +249,7 @@ export function verifyPeerAuthorization(
  * resolves to `false`, logged at debug.
  */
 export function verifyCadrePeerVoucher(
+  partyId: string,
   peerId: string,
   stampId: string,
   ownerPublicKey: string,
@@ -206,7 +257,7 @@ export function verifyCadrePeerVoucher(
 ): boolean {
   try {
     return verify(
-      cadrePeerVoucherDigest(peerId, stampId),
+      cadrePeerVoucherDigest(partyId, peerId, stampId),
       signature,
       ownerPublicKey,
       'ed25519',
@@ -224,14 +275,14 @@ export function verifyCadrePeerVoucher(
  * Canonical digest a JOINING peer signs to consent to ONE `FormationUsage`
  * redemption — the read-side mirror of `formationConsentMessage` in
  * control-database.ts, base64url-encoded instead of raw bytes (see
- * {@link taggedDigest}). That doc comment carries the field-vector rationale
- * (notably why `strandId` is not signed); the two vectors must not drift, which
- * peer-authorization.spec.ts pins by signing one form and verifying the other.
+ * {@link unboundTaggedDigest}). That doc comment carries the field-vector rationale
+ * (notably why neither `strandId` nor the party id is signed); the two vectors must not
+ * drift, which peer-authorization.spec.ts pins by signing one form and verifying the other.
  */
 export function formationConsentDigest(
   token: string, usageStampId: string, peerKey: string, disclosure: string
 ): string {
-  return taggedDigest('CadreControl.FormationUsage', 'consent', [token, usageStampId, peerKey, disclosure]);
+  return unboundTaggedDigest('CadreControl.FormationUsage', 'consent', [token, usageStampId, peerKey, disclosure]);
 }
 
 /**
@@ -257,3 +308,181 @@ export function verifyFormationConsent(row: {
     return false;
   }
 }
+
+/**
+ * Canonical digest an owner signs to seat a `CadreInvite` row — the read-side mirror
+ * of `cadreInviteAddMessage` in control-database.ts, base64url instead of raw bytes
+ * (see {@link taggedDigest}). The whole row is bound, nullable columns as `''` and
+ * `ExpiresAt` in its stored canonical form, through the one field builder both sides
+ * share (`cadreInviteRowFields`). SQL mirror: `CadreInvite.AuthorizedInsert`.
+ */
+export function cadreInviteAddDigest(partyId: string, row: CadreInviteSignedFields): string {
+  return taggedDigest('CadreControl.CadreInvite', 'add', partyId, cadreInviteRowFields(row));
+}
+
+/**
+ * Canonical digest the HOLDER of a `CadreInvite`'s private key signs to redeem it once:
+ * proof of possession, verified against the invitation key itself
+ * (`CadreInviteUsage.InvitePossessed`). Binds the redemption's single-use nonce and the
+ * device being admitted, so one redemption cannot be re-presented for another device
+ * or another use. Mirror of `cadreInviteRedeemMessage` in control-database.ts.
+ */
+export function cadreInviteRedeemDigest(partyId: string, inviteKey: string, usageStampId: string, peerKey: string): string {
+  return taggedDigest('CadreControl.CadreInviteUsage', 'redeem', partyId, [inviteKey, usageStampId, peerKey]);
+}
+
+/**
+ * Canonical digest the DEVICE signs to consent to being admitted by one redemption
+ * (`CadreInviteUsage.PeerConsented`), over the same fields as
+ * {@link cadreInviteRedeemDigest} under a distinct action tag, so the holder's and
+ * the device's signatures are never interchangeable. Mirror of
+ * `cadreInviteConsentMessage` in control-database.ts.
+ */
+export function cadreInviteConsentDigest(partyId: string, inviteKey: string, usageStampId: string, peerKey: string): string {
+  return taggedDigest('CadreControl.CadreInviteUsage', 'consent', partyId, [inviteKey, usageStampId, peerKey]);
+}
+
+/** ed25519 verify over a base64url digest, with the siblings' never-throws contract left to the caller. */
+function verifyB64(digestB64: string, signature: string, publicKey: string): boolean {
+  return verify(digestB64, signature, publicKey, 'ed25519', 'base64url', 'base64url', 'base64url');
+}
+
+/**
+ * Does a `CadreInvite` row carry a valid `'add'` signature by its own `issuerKey`, for
+ * `partyId`? The redeeming device runs this over the row a member replies with, after
+ * checking the issuer against its pinned owner keys and the reply's party against the
+ * invitation's, and a member over a bundle's copy it does not hold yet
+ * (`ControlDatabase.isCadreInviteLive`); whether that issuer IS an owner is the caller's question.
+ * Never throws: a malformed row verifies as `false`.
+ */
+export function verifyCadreInviteRow(partyId: string, invite: CadreInviteRow): boolean {
+  try {
+    return verifyB64(cadreInviteAddDigest(partyId, invite), invite.issuerSig, invite.issuerKey);
+  } catch (error) {
+    log('verifyCadreInviteRow failed: %o', error);
+    return false;
+  }
+}
+
+/**
+ * The two signatures a redemption carries, checked before any database work: the holder's
+ * `'redeem'` signature with the invitation key, and the device's `'consent'` signature with
+ * its own key, both over (`inviteKey`, `usageStampId`, `peerKey`). The pre-check twin of
+ * `CadreInviteUsage.InvitePossessed` / `PeerConsented`, as `verifyFormationConsent` is for
+ * formation: the schema stays the authority, this turns a bad signature into a clean
+ * refusal instead of a constraint failure at commit. Never throws.
+ */
+export function verifyCadreInviteRedemption(
+  partyId: string,
+  fields: { inviteKey: string; usageStampId: string; peerKey: string },
+  inviteSig: string,
+  peerSig: string,
+): boolean {
+  try {
+    return verifyB64(cadreInviteRedeemDigest(partyId, fields.inviteKey, fields.usageStampId, fields.peerKey), inviteSig, fields.inviteKey)
+      && verifyB64(cadreInviteConsentDigest(partyId, fields.inviteKey, fields.usageStampId, fields.peerKey), peerSig, fields.peerKey);
+  } catch (error) {
+    log('verifyCadreInviteRedemption failed: %o', error);
+    return false;
+  }
+}
+
+/**
+ * The links of an invitation admission that do not depend on WHICH table's row was
+ * admitted — shared by {@link verifyInvitationAdmission} (`CadrePeer`) and
+ * {@link verifyInvitationOwnerAdmission} (`OwnerKey`), which differ only in the row
+ * columns the usage must name and, for an owner row, in `grantsOwner`. The chain is
+ *
+ *   row --vouchUsage--> usage --inviteKey--> invitation --issuerKey--> anchored owner
+ *
+ * and every link here is verified: the issuer is anchored (`isAnchored`) and is the row's
+ * `vouchOwner`; the usage names this invitation and is the row's `vouchUsage`; a targeted
+ * invitation names the redeeming device; the stored `peerKey` really is the key behind the
+ * usage's `peerId` (the schema cannot unwrap a multihash, so a writer could assert any
+ * pair); the invitation's stored `'add'` signature verifies over the row rebuilt from its
+ * columns; the holder's `'redeem'` signature verifies with the invitation key and the
+ * device's `'consent'` signature with its own key. All three signatures are judged for
+ * `partyId`. Throws on malformed input; the two callers turn that into `false`.
+ */
+function verifyAdmissionChain(
+  partyId: string,
+  vouchOwner: string,
+  vouchUsage: string,
+  usage: CadreInviteUsageRow,
+  invite: CadreInviteRow,
+  isAnchored: (ownerKey: string) => boolean,
+): boolean {
+  return isAnchored(vouchOwner)
+    && invite.issuerKey === vouchOwner
+    && usage.usageStampId === vouchUsage
+    && usage.inviteKey === invite.key
+    && (invite.peerId === null || invite.peerId === usage.peerId)
+    && ed25519PublicKeyB64FromPeerId(usage.peerId) === usage.peerKey
+    && verifyB64(cadreInviteAddDigest(partyId, invite), invite.issuerSig, invite.issuerKey)
+    && verifyB64(cadreInviteRedeemDigest(partyId, invite.key, usage.usageStampId, usage.peerKey), usage.inviteSig, invite.key)
+    && verifyB64(cadreInviteConsentDigest(partyId, invite.key, usage.usageStampId, usage.peerKey), usage.peerSig, usage.peerKey);
+}
+
+/**
+ * Is an invitation-admitted `CadrePeer` row (`vouchSig` null, `vouchUsage` set) a
+ * member this node should trust? The read-side mirror of the consent branch of
+ * `CadrePeer.AuthorizedInsert`, re-checked against THIS node's anchor because the
+ * replicated `OwnerKey` table can be polluted. The usage must name this peer id and this
+ * exact row incarnation (`peerStampId`); every other link is {@link verifyAdmissionChain}.
+ *
+ * Expiry, use count and withdrawal are deliberately NOT re-checked: they were conditions
+ * at redemption (`CadreInviteUsage.Authorized`), and membership persists until an owner
+ * removes the row — exactly as an owner-vouched row's membership does. Keeping a device
+ * out is removing its row AND withdrawing the invitation.
+ *
+ * Returns a boolean and never throws (the siblings' contract): malformed input or any
+ * crypto failure resolves to `false`, logged at debug.
+ */
+export function verifyInvitationAdmission(
+  partyId: string,
+  row: CadrePeerVoucherFields,
+  usage: CadreInviteUsageRow,
+  invite: CadreInviteRow,
+  isAnchored: (ownerKey: string) => boolean,
+): boolean {
+  try {
+    return row.stampId !== null
+      && row.vouchOwner !== null
+      && row.vouchUsage !== null
+      && usage.peerStampId === row.stampId
+      && usage.peerId === row.peerId
+      && verifyAdmissionChain(partyId, row.vouchOwner, row.vouchUsage, usage, invite, isAnchored);
+  } catch (error) {
+    log('verifyInvitationAdmission failed: %o', error);
+    return false;
+  }
+}
+
+/**
+ * Is an invitation-admitted `OwnerKey` row (`vouchSig` null, `vouchUsage` set) an owner
+ * this node should derive into its anchor? The read-side mirror of the consent branch of
+ * `OwnerKey.Authorized` (`owner-anchor-sync.ts` → `deriveOwnerAnchor`): the invitation
+ * must grant ownership, and the usage must name this key (`peerKey`) and this exact row
+ * incarnation (`ownerStampId`); every other link is {@link verifyAdmissionChain}. Same
+ * never-throws contract and the same deliberate omissions as
+ * {@link verifyInvitationAdmission}.
+ */
+export function verifyInvitationOwnerAdmission(
+  partyId: string,
+  row: OwnerKeyRow,
+  usage: CadreInviteUsageRow,
+  invite: CadreInviteRow,
+  isAnchored: (ownerKey: string) => boolean,
+): boolean {
+  try {
+    return row.vouchOwner !== null
+      && row.vouchUsage !== null
+      && invite.grantsOwner
+      && usage.peerKey === row.key
+      && usage.ownerStampId === row.stampId
+      && verifyAdmissionChain(partyId, row.vouchOwner, row.vouchUsage, usage, invite, isAnchored);
+  } catch (error) {
+    log('verifyInvitationOwnerAdmission failed: %o', error);
+    return false;
+  }
+}

package/src/peer-dial.ts

@@ -144,6 +144,22 @@ export class SelfRelayOnlyError extends Error {
 	}
 }
 
+/**
+ * No connection to the peer formed, so nothing was sent to it. `cause` is what the dial threw:
+ * {@link dialPeerAddrs}'s error naming every address and why it failed, or a
+ * {@link SelfRelayOnlyError}.
+ *
+ * Kept apart from failures after a connection formed so a caller can tell "this device could not
+ * reach the peer" from "the peer was reached and then something else failed" without reading
+ * libp2p's error text. `SeedBootstrapService.deliverSeed` throws it, and so `CadreNode.claimNode`.
+ */
+export class PeerUnreachableError extends Error {
+	constructor(readonly peerId: string, cause: unknown) {
+		super(`Could not reach ${peerId}: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+		this.name = 'PeerUnreachableError';
+	}
+}
+
 /** One candidate's outcome, kept so the thrown error can name every attempt. */
 interface AddrAttemptFailure {
 	addr: Multiaddr;
@@ -310,6 +326,11 @@ function allAttemptsFailed(label: string, failures: AddrAttemptFailure[]): Error
 	return new Error(`${label} failed for all ${failures.length} candidate addresses: ${detail}`, { cause: failures[0].error });
 }
 
-function nextMacrotask(): Promise<void> {
+/**
+ * Yield one macrotask: libp2p's dial queue drops an aborted job only on the next turn, so a
+ * dialer that moves on to another address after an abort waits this long first. Shared with
+ * the cadre invitation dialer (`cadre-invite-protocol.ts`).
+ */
+export function nextMacrotask(): Promise<void> {
 	return new Promise((resolve) => setTimeout(resolve, 0));
 }

package/src/peer-join-backfill.ts

@@ -315,10 +315,16 @@ export class PeerJoinBackfill {
   private readonly createPushClient: (peerId: PeerId) => PeerJoinBackfillPushClient;
   private started = false;
   private stopped = false;
-  /** Peers fully caught up this runtime (never retried until the runtime is rebuilt). */
+  /**
+   * Peers fully caught up this runtime (never rescheduled until the runtime is rebuilt; only
+   * {@link forceCatchUpPeer} pushes to one again).
+   */
   private readonly done = new Set<string>();
-  /** Peers with a catch-up currently running (suppresses concurrent duplicates). */
-  private readonly inFlight = new Set<string>();
+  /**
+   * Peers with a catch-up currently running, each with that run (suppresses concurrent
+   * duplicates; {@link forceCatchUpPeer} waits on the run).
+   */
+  private readonly inFlight = new Map<string, Promise<PeerJoinBackfillResult>>();
   /**
    * Peers whose (re-)schedule arrived while their OWN run was in flight, replayed once
    * that run finishes. Load-bearing for the gated path: the gate's authorization check is
@@ -464,7 +470,53 @@ export class PeerJoinBackfill {
     if (this.stopped || this.done.has(key) || this.inFlight.has(key)) {
       return emptyResult();
     }
-    this.inFlight.add(key);
+    return await this.trackRun(peerId);
+  }
+
+  /**
+   * Run one peer's catch-up now and wait for it, whatever this instance remembers about the
+   * peer: wait out a run already in flight for it, then push the whole store again even when
+   * the peer is memoized as caught up. Never rejects; an all-zero result only when stopped.
+   *
+   * For a caller that must know the peer holds this store before it proceeds, where
+   * {@link catchUpPeer}'s empty answer would hide a run that was denied (a `peer:identify`
+   * run can pass the gate a moment before the caller authorized the peer) or a memo older
+   * than the commits since.
+   */
+  async forceCatchUpPeer(peerId: PeerId): Promise<PeerJoinBackfillResult> {
+    const key = peerId.toString();
+    for (let pending = this.inFlight.get(key); pending; pending = this.inFlight.get(key)) {
+      await pending;
+    }
+    if (this.stopped) {
+      return emptyResult();
+    }
+    return await this.trackRun(peerId);
+  }
+
+  /**
+   * Register one run in {@link inFlight} before its first await, so no second run for the
+   * peer can start beside it, and replay a schedule that arrived while it ran.
+   */
+  private async trackRun(peerId: PeerId): Promise<PeerJoinBackfillResult> {
+    const key = peerId.toString();
+    const run = this.settleRun(peerId);
+    this.inFlight.set(key, run);
+    try {
+      return await run;
+    } finally {
+      this.inFlight.delete(key);
+      // Replay a schedule that arrived mid-run. `schedulePeer` re-checks `done`, so a run
+      // that finished clean re-arms nothing; a denied or failed one gets its retry.
+      if (this.rearmAfterFlight.delete(key)) {
+        this.schedulePeer(peerId);
+      }
+    }
+  }
+
+  /** One run and what follows from its outcome: the memo, or a backoff re-arm. Never rejects. */
+  private async settleRun(peerId: PeerId): Promise<PeerJoinBackfillResult> {
+    const key = peerId.toString();
     try {
       const { result, clean, pushFailed } = await this.runCatchUp(peerId);
       // NOTE: a run that hit `maxBlocks` is still "clean" and still memoizes the peer, so
@@ -496,13 +548,6 @@ export class PeerJoinBackfill {
       // metadata reads too — a backfill fault must never surface through a libp2p event.
       log('[%s] catch-up peer=%s failed: %o', this.deps.label, key, error);
       return emptyResult();
-    } finally {
-      this.inFlight.delete(key);
-      // Replay a schedule that arrived mid-run. `schedulePeer` re-checks `done`, so a run
-      // that finished clean re-arms nothing; a denied or failed one gets its retry.
-      if (this.rearmAfterFlight.delete(key)) {
-        this.schedulePeer(peerId);
-      }
     }
   }
 

package/src/peer-record.ts

@@ -8,15 +8,17 @@
  * multi-field encoding, so no field split is ambiguous. It is intentionally NOT
  * JSON-canonicalized (deterministic across node/browser/RN, no key ordering)
  * and — crucially — is reconstructable inside the `CadrePeer.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.CadrePeer', 'publish',
+ *   digest('CadreControl.CadrePeer', 'publish', party_id(),
  *          new.PeerId, new.Multiaddr, cast(new.UpdatedAt as text))
  *
  * Keep {@link peerRecordSignedPayload} 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.
+ * every owner-signed digest; the party id keeps a record published into one
+ * party's table from verifying in another's. A node signs and verifies with its
+ * own party: these records come only from its own party's control database.
  *
  * `publicKey` is deliberately excluded from the payload — it is the key the
  * signature is verified *with* (so a signature already commits to exactly one
@@ -51,12 +53,13 @@ const SIGNALING_PREFIX = '/p2p-circuit';
  * base64url output of a single `digest(...)`, which round-trips cleanly (unlike
  * concatenating several base64url digests).
  *
+ * @param partyId - the party whose `CadrePeer` table the record is published into
  * @param peerId - base58btc libp2p peer id (the row key)
  * @param multiaddr - the comma-joined `Multiaddr` string EXACTLY as stored
  * @param updatedAt - epoch-ms freshness stamp
  */
-export function peerRecordSignedPayload(peerId: string, multiaddr: string, updatedAt: number): string {
-  const fields = controlAuthorizationFields('CadreControl.CadrePeer', 'publish', [peerId, multiaddr, String(updatedAt)]);
+export function peerRecordSignedPayload(partyId: string, peerId: string, multiaddr: string, updatedAt: number): string {
+  const fields = controlAuthorizationFields('CadreControl.CadrePeer', 'publish', partyId, [peerId, multiaddr, String(updatedAt)]);
   return digest(fields, 'sha256', 'base64url') as string;
 }
 
@@ -65,14 +68,16 @@ export function peerRecordSignedPayload(peerId: string, multiaddr: string, updat
  * Returns a fully-populated {@link PeerAddressRecord} (the `addrs` order is
  * preserved and is the order signed over).
  *
+ * @param partyId - the party whose `CadrePeer` table the record is published into
  * @param fields - the record fields to sign (signaling addr first by convention)
  * @param privateKeyB64 - base64url ed25519 seed (see `ed25519KeyPairFromLibp2p`)
  */
 export function signPeerRecord(
+  partyId: string,
   fields: { peerId: string; publicKey: string; addrs: string[]; updatedAt: number },
   privateKeyB64: string
 ): PeerAddressRecord {
-  const payloadDigest = peerRecordSignedPayload(fields.peerId, fields.addrs.join(','), fields.updatedAt);
+  const payloadDigest = peerRecordSignedPayload(partyId, fields.peerId, fields.addrs.join(','), fields.updatedAt);
   const sig = sign(
     payloadDigest,
     privateKeyB64,
@@ -85,15 +90,15 @@ export function signPeerRecord(
 }
 
 /**
- * Verify a record's self-signature against its own `publicKey`. Reconstructs the
- * signed bytes from the record exactly as {@link signPeerRecord} produced them.
- * Returns false on a missing key/sig or any verification failure.
+ * Verify a record's self-signature against its own `publicKey`, for `partyId`.
+ * Reconstructs the signed bytes from the record exactly as {@link signPeerRecord}
+ * produced them. Returns false on a missing key/sig or any verification failure.
  */
-export function verifyPeerRecordSignature(record: PeerAddressRecord): boolean {
+export function verifyPeerRecordSignature(partyId: string, record: PeerAddressRecord): boolean {
   if (!record.publicKey || !record.sig) {
     return false;
   }
-  const payloadDigest = peerRecordSignedPayload(record.peerId, record.addrs.join(','), record.updatedAt);
+  const payloadDigest = peerRecordSignedPayload(partyId, record.peerId, record.addrs.join(','), record.updatedAt);
   return verify(
     payloadDigest,
     record.sig,