@serfab/cadre-core 0.7.1 → 0.9.0

package/src/seed-bootstrap.ts

@@ -1,20 +1,10 @@
 import debug from 'debug';
 import { toString as uint8ArrayToString, fromString as uint8ArrayFromString } from 'uint8arrays';
 import { digest, sign, verify, getPublicKey } from '@optimystic/quereus-plugin-crypto';
-import type { Libp2p, PeerId, Connection } from '@libp2p/interface';
+import type { Libp2p, Connection } from '@libp2p/interface';
 import { multiaddr } from '@multiformats/multiaddr';
-import type { Multiaddr } from '@multiformats/multiaddr';
 import { peerIdFromString } from '@libp2p/peer-id';
-
-/**
- * Minimal libp2p stream surface compatible with libp2p 3.x.
- * In libp2p 3.x, streams are AsyncIterable for reading and use send() for writing.
- */
-interface LibP2PStream extends AsyncIterable<Uint8Array> {
-  send(data: Uint8Array): boolean;
-  close(): Promise<void>;
-  abort(err: Error): void;
-}
+import { type ControlStream, writeFrame, readStreamToEnd } from './control-stream.js';
 import type {
   ControlNetworkSeed,
   SeedPeer,
@@ -22,14 +12,22 @@ import type {
   SeedAckMessage,
   AuthorizePeerOptions,
   ApplySeedResult,
-  SignedTransaction,
   AddDroneOptions,
   AddPhoneOptions,
   DroneInitResult,
   InviteResult,
-  CadreInvite
+  CadreInvite,
+  PeerAddressRecord,
+  DeviceTokenRecord
 } from './types.js';
 import type { ControlDatabase } from './control-database.js';
+import { generateStampId } from './control-database.js';
+import { canonicalJson } from './canonical-json.js';
+import { peerAuthorizationDigest, cadrePeerVoucherDigest, cadrePeerRemoveDigest } from './peer-authorization.js';
+import {
+  type SeedTrustPolicy,
+  dbAnchoredTrustPolicy,
+} from './seed-trust-policy.js';
 
 const log = debug('sereus:cadre:seed-bootstrap');
 
@@ -39,16 +37,85 @@ export const SEED_PROTOCOL = '/sereus/seed/1.0.0';
 /** Maximum seed message size (1MB) */
 const MAX_SEED_SIZE = 1024 * 1024;
 
+/** Default time the receiver waits for an inbound seed frame before aborting (ms). */
+const DEFAULT_SEED_READ_TIMEOUT_MS = 10_000;
+
+/** Default cap on concurrent inbound seed streams a single peer can pin open. */
+const DEFAULT_MAX_CONCURRENT_SEEDS = 100;
+
+/**
+ * Decode a 4-byte big-endian length-prefixed frame; returns the body bytes.
+ *
+ * Guards every parse site against malformed input: a buffer too short to hold
+ * the prefix, a declared length exceeding `maxLength`, and a declared length
+ * exceeding the bytes actually present. Returns a view (`subarray`, no copy) —
+ * the body is handed straight to `TextDecoder`.
+ */
+export function decodeLengthPrefixedFrame(data: Uint8Array, maxLength = MAX_SEED_SIZE): Uint8Array {
+  if (data.length < 4) {
+    throw new Error(`Seed frame too short: ${data.length} bytes, need ≥4 for length prefix`);
+  }
+  // Pass the full (buffer, byteOffset, byteLength) triple so the read is correct
+  // even for a non-zero-offset view, not just the fresh zero-offset arrays
+  // current callers pass.
+  const length = new DataView(data.buffer, data.byteOffset, data.byteLength).getUint32(0, false);
+  const available = data.length - 4;
+  if (length > maxLength) {
+    throw new Error(`Seed frame declares length ${length} exceeding max ${maxLength}`);
+  }
+  if (length > available) {
+    throw new Error(`Seed frame declares length ${length} but only ${available} body bytes present`);
+  }
+  return data.subarray(4, 4 + length);
+}
+
+/**
+ * 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.
+ */
+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;
+  }
+}
+
+/**
+ * Canonical byte representation of the authenticated seed fields.
+ *
+ * Routes both the creator (`createSeed`) and the verifier
+ * (`validateSeedSignature`) through one builder so the signed bytes are
+ * identical regardless of key insertion order. `canonicalJson` sorts keys and
+ * drops `undefined`, so the signed payload is exactly `{ partyId, peers }` —
+ * the fields the producer actually emits.
+ */
+export function canonicalSeedPayload(
+  seed: Pick<ControlNetworkSeed, 'partyId' | 'peers'>
+): string {
+  return canonicalJson({ partyId: seed.partyId, peers: seed.peers });
+}
+
 /**
  * Configuration for the SeedBootstrapService
  */
 export interface SeedBootstrapConfig {
   /** Party ID for this cadre */
   partyId: string;
-  /** Authority private key for signing seeds and peer authorizations (base64url) */
-  authorityPrivateKey?: string;
-  /** Authority public key (base64url) - derived from private key if not provided */
-  authorityPublicKey?: string;
+  /** Owner private key for signing seeds and peer authorizations (base64url) */
+  ownerPrivateKey?: string;
+  /** Owner public key (base64url) - derived from private key if not provided */
+  ownerPublicKey?: string;
   /**
    * Optional async resolver returning the multiaddrs to embed in invites.
    * When unset, `libp2pNode.getMultiaddrs()` is used. Hosts behind NAT supply
@@ -56,6 +123,30 @@ export interface SeedBootstrapConfig {
    * DDNS hostname and externally-mapped port.
    */
   inviteAddressResolver?: () => Promise<string[]>;
+  /**
+   * Trust anchor for incoming seeds. Decides whether a signature-verified
+   * `signerKey` should be trusted, against the receiver's known owner
+   * keys (NOT the seed body). Defaults to `dbAnchoredTrustPolicy()`, which
+   * rejects any signer not already in the `OwnerKey` table. An enrollment
+   * caller can pass a per-seed override to `applySeed` instead.
+   *
+   * A `CadreNode` forwards its node-wide `CadreNodeConfig.seedTrustPolicy` here
+   * — that is the only seam the inbound libp2p seed-protocol handler can use,
+   * since a network-delivered seed has no per-call override.
+   */
+  trustPolicy?: SeedTrustPolicy;
+  /**
+   * Time the inbound seed handler waits for the seed frame before aborting the
+   * read (ms). Defaults to {@link DEFAULT_SEED_READ_TIMEOUT_MS}. Bounds a
+   * buggy/compromised own-cadre node that opens a stream and never half-closes.
+   */
+  seedReadTimeoutMs?: number;
+  /**
+   * Cap on concurrent inbound seed streams (defaults to
+   * {@link DEFAULT_MAX_CONCURRENT_SEEDS}). Over the cap, a non-accepting ack is
+   * returned without applying any seed.
+   */
+  maxConcurrentSeeds?: number;
 }
 
 /**
@@ -75,28 +166,36 @@ export interface SeedEventCallbacks {
  *
  * Seeds solve the cold-start problem: new nodes need control data to validate
  * connections, but can't get data without connecting first. Seeds pre-populate
- * the new node's cache with peer information and optionally transactions.
+ * the new node's cache with peer information.
  */
 export class SeedBootstrapService {
   private readonly config: SeedBootstrapConfig;
   private libp2pNode: Libp2p | null = null;
   private controlDatabase: ControlDatabase | null = null;
-  private readonly authorityPublicKey: string | null;
+  private readonly ownerPublicKey: string | null;
+  private readonly trustPolicy: SeedTrustPolicy;
+  private readonly seedReadTimeoutMs: number;
+  private readonly maxConcurrentSeeds: number;
+  /** In-flight inbound seed streams, used to enforce {@link maxConcurrentSeeds}. */
+  private activeStreams = 0;
   private eventCallbacks: SeedEventCallbacks = {};
 
   constructor(config: SeedBootstrapConfig) {
     this.config = config;
+    this.trustPolicy = config.trustPolicy ?? dbAnchoredTrustPolicy();
+    this.seedReadTimeoutMs = config.seedReadTimeoutMs ?? DEFAULT_SEED_READ_TIMEOUT_MS;
+    this.maxConcurrentSeeds = config.maxConcurrentSeeds ?? DEFAULT_MAX_CONCURRENT_SEEDS;
 
     // Derive public key from private key if not provided
-    if (config.authorityPrivateKey && !config.authorityPublicKey) {
-      this.authorityPublicKey = getPublicKey(
-        config.authorityPrivateKey,
+    if (config.ownerPrivateKey && !config.ownerPublicKey) {
+      this.ownerPublicKey = getPublicKey(
+        config.ownerPrivateKey,
         'ed25519',
         'base64url',
         'base64url'
       ) as string;
     } else {
-      this.authorityPublicKey = config.authorityPublicKey ?? null;
+      this.ownerPublicKey = config.ownerPublicKey ?? null;
     }
 
     log('SeedBootstrapService created for party: %s', config.partyId);
@@ -111,105 +210,319 @@ export class SeedBootstrapService {
   }
 
   /**
-   * Initialize the service with libp2p node and control database
+   * Whether this service holds an owner private key, i.e. can produce the
+   * owner signatures that gate `CadrePeer` / `DeviceToken` inserts, deletes,
+   * and re-authorizations. A seed-listener-only service (`enableSeedListener`,
+   * no owner key) returns false: it can receive/apply seeds but cannot author
+   * or re-issue owner writes. Used by the write-while-alone re-replication
+   * drain to skip owner work on a non-owner node.
+   */
+  canAuthorize(): boolean {
+    return !!this.config.ownerPrivateKey;
+  }
+
+  /**
+   * Initialize the service with libp2p node and control database.
+   *
+   * `registerHandler` (default true) gates registration of the shared inbound
+   * `/sereus/seed/1.0.0` handler on `libp2pNode`. Persistent services
+   * (`initializeSeedBootstrap`, `enableSeedListener`) own that handler and leave
+   * it on. The throwaway temp services CadreNode builds in `applySeed` /
+   * `dialInvite` pass `false`: they only need the stored `libp2pNode` /
+   * `controlDatabase` for dialing and known-key lookup, and must NOT bind a
+   * discarded closure to the shared node (a handler leak, and a second
+   * `handle()` of the same protocol throws `DuplicateProtocolHandlerError`).
    */
-  initialize(libp2pNode: Libp2p, controlDatabase: ControlDatabase): void {
+  initialize(
+    libp2pNode: Libp2p,
+    controlDatabase: ControlDatabase,
+    options?: { registerHandler?: boolean }
+  ): void {
     this.libp2pNode = libp2pNode;
     this.controlDatabase = controlDatabase;
-    
-    // Register the seed protocol handler
-    this.registerProtocolHandler();
-    
+
+    // Register the seed protocol handler unless the caller opted out (temp services).
+    if (options?.registerHandler ?? true) {
+      this.registerProtocolHandler();
+    }
+
     log('SeedBootstrapService initialized');
   }
 
   /**
    * Authorize a new peer to join the cadre.
-   * Signs the peer ID with the authority key and inserts into CadrePeer table.
+   * Signs the peer ID with the owner key and inserts into CadrePeer table.
+   *
+   * The owner vouches the `PublicKey <-> PeerId` binding: rather than trust a
+   * caller-supplied key, the binding is enforced by construction — `PublicKey` is
+   * DERIVED from the (Ed25519) `peerId`. A non-Ed25519 peer id yields a null
+   * `PublicKey`, and such a row can never be self-updated (it has no key to
+   * verify against), which is correct. The row is inserted with a fresh
+   * `UpdatedAt` but no self-signature (`Sig` null) — the owner cannot produce
+   * the peer's self-signature, so the peer must self-publish (see
+   * {@link CadreNode.registerSelf}) before the row resolves.
    */
   async authorizePeer(options: AuthorizePeerOptions): Promise<void> {
     const { peerId, multiaddrs } = options;
-    
-    if (!this.config.authorityPrivateKey) {
-      throw new Error('Authority private key required to authorize peers');
-    }
-    
+    log('Authorizing peer: %s', peerId);
+    // CadrePeer.Multiaddr stores a comma-joined list; use '' when no addrs provided.
+    const multiaddrStr = multiaddrs?.length ? multiaddrs.join(',') : '';
+    await this.insertCadrePeerRow({
+      peerId,
+      publicKey: ed25519PublicKeyB64FromPeerId(peerId),
+      multiaddr: multiaddrStr,
+      updatedAt: Date.now(),
+      sig: null,
+    });
+    log('Peer %s authorized successfully', peerId);
+  }
+
+  /**
+   * Owner-signed INSERT of this node's OWN self-signed address record.
+   *
+   * Used by {@link CadreNode.registerSelf} when the node is not yet a member and
+   * is its own owner (it holds the owner key): the row is owner-signed
+   * (satisfying `AuthorizedInsert`) AND carries a valid self-`Sig`, so it resolves
+   * immediately without a follow-up self-update.
+   */
+  async insertSelfPeerRecord(record: PeerAddressRecord): Promise<void> {
+    await this.insertCadrePeerRow({
+      peerId: record.peerId,
+      publicKey: record.publicKey,
+      multiaddr: record.addrs.join(','),
+      updatedAt: record.updatedAt,
+      sig: record.sig,
+    });
+  }
+
+  /**
+   * Shared owner-signed `CadrePeer` INSERT. Mints a fresh single-use `StampId`
+   * and signs the voucher digest `digest(peerId, stampId)` ({@link cadrePeerVoucherDigest})
+   * with the owner key (satisfying `AuthorizedInsert`), then writes the full record
+   * row with the vouching (owner, signature) persisted into VouchOwner/VouchSig.
+   * The owner signature does NOT cover the address columns — those are vouched only
+   * as far as the owner asserts them, and a peer's own `Sig` (when present) is what
+   * makes the row resolvable.
+   */
+  private async insertCadrePeerRow(row: {
+    peerId: string;
+    publicKey: string | null;
+    multiaddr: string;
+    updatedAt: number;
+    sig: string | null;
+  }): Promise<void> {
     if (!this.controlDatabase) {
       throw new Error('Control database not initialized');
     }
-    
-    log('Authorizing peer: %s', peerId);
-    
-    // Sign the peer ID with the authority key
-    const peerIdDigest = digest(peerId, 'sha256', 'utf8', 'base64url') as string;
-    const signature = sign(
-      peerIdDigest,
-      this.config.authorityPrivateKey,
-      'ed25519',
-      'base64url',
-      'base64url',
-      'base64url'
-    ) as string;
-    
-    // Insert into CadrePeer table with authority context
+    // Fresh single-use nonce; the voucher signs digest(peerId, stampId) so a captured
+    // insert can't be replayed (StampId is unique) and can't be repurposed as a delete
+    // (which signs a distinct 'remove'-scoped digest).
+    // NOTE: StampId uniqueness only blocks insert-replay while the row (or its StampId)
+    // is still present — a delete frees the StampId, so a captured authorized insert could
+    // be replayed to re-add a peer the owner had removed (a revocation bypass). Fully
+    // subsumed by the connection gater (ticket 6): with no outsider write there is no
+    // replay at all. If that gate ever proves insufficient, bind inserts to a persistent
+    // per-peer sequence / tombstone instead of a row-scoped nonce.
+    const stampId = generateStampId(row.peerId);
+    const signature = this.signDigest(cadrePeerVoucherDigest(row.peerId, stampId));
     const db = this.controlDatabase.getDatabase();
-    // CadrePeer.Multiaddr is NOT NULL; use empty string when no addrs provided
-    const multiaddrStr = multiaddrs?.length ? multiaddrs.join(',') : '';
-
+    // Persist the vouching (owner, signature) onto the row (VouchOwner/VouchSig)
+    // — identical to the context pair, which the AuthorizedInsert constraint binds — so a
+    // reader can later re-check the voucher against its node-local trusted-owner anchor.
     await db.exec(`
-      insert into CadreControl.CadrePeer (PeerId, Multiaddr)
-        with context AuthorityKey = ?, Signature = ?
-        values (?, ?)
-    `, [this.authorityPublicKey, signature, peerId, multiaddrStr]);
-
-    log('Peer %s authorized successfully', peerId);
+      insert into CadreControl.CadrePeer (PeerId, PublicKey, Multiaddr, UpdatedAt, Sig, StampId, VouchOwner, VouchSig)
+        with context OwnerKey = ?, Signature = ?
+        values (?, ?, ?, ?, ?, ?, ?, ?)
+    `, [this.ownerPublicKey, signature, row.peerId, row.publicKey, row.multiaddr, row.updatedAt, row.sig, stampId, this.ownerPublicKey, signature]);
   }
 
   /**
-   * Remove a peer from the cadre by authority signature.
+   * Owner-signed INSERT of a peer's OWN self-signed `DeviceToken` row.
    *
-   * The constraint over CadrePeer's `check on insert, delete` validates a
-   * signature over `digest(old.PeerId, 'sha256', 'utf8')` by an authority
-   * key. We use the same digest pattern as authorizePeer.
+   * Counterpart to {@link insertSelfPeerRecord} for the device-token registry: the
+   * row is owner-signed (satisfying `DeviceToken.AuthorizedInsert`, which vouches
+   * membership exactly as `CadrePeer.AuthorizedInsert` does) AND carries the peer's
+   * own self-`Sig` over the token payload. The owner signature covers only the
+   * PeerId — it does NOT vouch the token contents; the peer's `Sig` (verified at
+   * resolve time against the bound `CadrePeer.PublicKey`) is what makes the row
+   * resolvable. Used by {@link CadreNode.registerDeviceToken} for the first publish
+   * when the node is its own owner.
    */
-  async removePeer(peerId: string): Promise<void> {
-    if (!this.config.authorityPrivateKey) {
-      throw new Error('Authority private key required to remove peers');
+  async insertSelfDeviceToken(record: DeviceTokenRecord): Promise<void> {
+    const signature = this.signPeerAuthorization(record.peerId);
+    if (!this.controlDatabase) {
+      throw new Error('Control database not initialized');
     }
+    const db = this.controlDatabase.getDatabase();
+    await db.exec(`
+      insert into CadreControl.DeviceToken (PeerId, Platform, Token, UpdatedAt, Sig)
+        with context OwnerKey = ?, Signature = ?
+        values (?, ?, ?, ?, ?)
+    `, [this.ownerPublicKey, signature, record.peerId, record.platform, record.token, record.updatedAt, record.sig]);
+    log('Device token inserted (owner-signed): %s', record.peerId);
+  }
 
+  /**
+   * Owner-signed DELETE of a peer's `DeviceToken` row (logout / token
+   * invalidation). The `DeviceToken.AuthorizedInsert` constraint gates both insert
+   * AND delete on an owner signature over `digest(old.PeerId)`, so — like
+   * {@link removePeer} for `CadrePeer` — clearing a token requires the owner key.
+   */
+  async deleteDeviceToken(peerId: string): Promise<void> {
+    const signature = this.signPeerAuthorization(peerId);
     if (!this.controlDatabase) {
       throw new Error('Control database not initialized');
     }
+    const db = this.controlDatabase.getDatabase();
+    await db.exec(`
+      delete from CadreControl.DeviceToken
+        with context OwnerKey = ?, Signature = ?
+        where PeerId = ?
+    `, [this.ownerPublicKey, signature, peerId]);
+    log('Device token removed (owner-signed): %s', peerId);
+  }
 
-    log('Removing peer: %s', peerId);
+  /**
+   * Sign a peer ID with the owner key for a `CadrePeer` / `DeviceToken`
+   * insert-or-delete. The signed bytes come from the shared
+   * {@link peerAuthorizationDigest} helper so the offline `cadre enroll register`
+   * verifier checks the exact same construction. Throws if no owner key is set.
+   */
+  private signPeerAuthorization(peerId: string): string {
+    return this.signDigest(peerAuthorizationDigest(peerId));
+  }
 
-    const peerIdDigest = digest(peerId, 'sha256', 'utf8', 'base64url') as string;
-    const signature = sign(
-      peerIdDigest,
-      this.config.authorityPrivateKey,
+  /**
+   * Return the configured owner private key, or throw if none is set. The single
+   * precondition gate for every owner-signed write. {@link removePeer} /
+   * {@link reauthorizePeer} read the row's `StampId` from the DB BEFORE they sign, so
+   * they call this up front — otherwise a keyless service would either surface the
+   * wrong "Control database not initialized" error or, worse, silently no-op when the
+   * target row is absent (the early `stampId === null` return) instead of rejecting.
+   */
+  private requireOwnerPrivateKey(): string {
+    if (!this.config.ownerPrivateKey) {
+      throw new Error('Owner private key required to authorize peers');
+    }
+    return this.config.ownerPrivateKey;
+  }
+
+  /**
+   * Sign a base64url digest with the owner key (ed25519). The single place the
+   * owner private key is applied; callers pass the canonical digest for the specific
+   * action ({@link cadrePeerVoucherDigest} / {@link cadrePeerRemoveDigest} /
+   * {@link peerAuthorizationDigest}). Throws if no owner key is set.
+   */
+  private signDigest(digestB64url: string): string {
+    return sign(
+      digestB64url,
+      this.requireOwnerPrivateKey(),
       'ed25519',
       'base64url',
       'base64url',
       'base64url'
     ) as string;
+  }
+
+  /**
+   * Remove a peer from the cadre by owner signature.
+   *
+   * The `CadrePeer.AuthorizedDelete` (`check on delete`) constraint validates a
+   * signature over the DISTINCT 'remove'-scoped digest `digest(old.PeerId, old.StampId,
+   * 'remove')` ({@link cadrePeerRemoveDigest}) by an owner key — deliberately NOT the
+   * insert voucher digest, so the row's stored `VouchSig` can never be replayed to delete.
+   */
+  async removePeer(peerId: string): Promise<void> {
+    // Fail fast on a keyless service BEFORE any DB read: a non-owner cannot sign the
+    // remove digest, and this precedence (owner key, then control DB) is what the
+    // unit contract asserts.
+    this.requireOwnerPrivateKey();
+    if (!this.controlDatabase) {
+      throw new Error('Control database not initialized');
+    }
+    // Delete is authorized by a signature over a DISTINCT 'remove'-scoped digest bound to
+    // the row's CURRENT StampId — so the row's stored voucher (a signature over the
+    // voucher digest) can never be replayed to authorize a delete.
+    const stampId = await this.controlDatabase.queryCadrePeerStampId(peerId);
+    if (stampId === null) {
+      log('removePeer: no CadrePeer row for %s (already absent)', peerId);
+      return;
+    }
+    const signature = this.signDigest(cadrePeerRemoveDigest(peerId, stampId));
+
+    log('Removing peer: %s', peerId);
 
     const db = this.controlDatabase.getDatabase();
     await db.exec(`
       delete from CadreControl.CadrePeer
-        with context AuthorityKey = ?, Signature = ?
+        with context OwnerKey = ?, Signature = ?
         where PeerId = ?
-    `, [this.authorityPublicKey, signature, peerId]);
+    `, [this.ownerPublicKey, signature, peerId]);
 
     log('Peer %s removed successfully', peerId);
   }
 
+  /**
+   * Owner "re-touch" of an existing `CadrePeer` membership row: bump
+   * `UpdatedAt` under the owner branch of `CadrePeer.AuthorizedUpdate` (a
+   * signature over `digest(peerId)` — the same construction {@link authorizePeer}
+   * uses) so the row is re-emitted as a fresh, broadcasting transaction.
+   *
+   * This is the write-while-alone re-replication primitive
+   * (`control-write-ensure-replicated`): a membership row that committed
+   * local-only (its block's cluster ≤1 at insert) is pushed to the cohort once it
+   * grows, by re-issuing this monotonic bump. It is an UPDATE (not the original
+   * INSERT) because the row already exists locally; a re-INSERT would hit the
+   * `PeerId` PK. Only the freshness stamp changes — `PublicKey` / `Multiaddr` /
+   * `Sig` are left intact — so it is safe over a row whose peer has not
+   * self-published (`Sig` null); the caller must skip a row that already carries a
+   * self-`Sig` (that row is the owning peer's to refresh, and bumping `UpdatedAt`
+   * without re-signing would invalidate its self-signature).
+   *
+   * @param peerId - the membership row to re-touch.
+   * @param updatedAt - the strictly-increasing freshness stamp to write.
+   * @throws if no owner private key is configured (a non-owner cannot
+   *   re-sign another peer's row) or the control database is not initialized.
+   */
+  async reauthorizePeer(peerId: string, updatedAt: number): Promise<void> {
+    // Fail fast on a keyless service before any DB read (see removePeer): a non-owner
+    // cannot re-sign the voucher, and must not silently no-op on an absent row.
+    this.requireOwnerPrivateKey();
+    if (!this.controlDatabase) {
+      throw new Error('Control database not initialized');
+    }
+    // The owner branch of AuthorizedUpdate verifies a voucher over digest(PeerId,
+    // StampId) and re-binds VouchOwner/VouchSig. Sign over the row's CURRENT StampId
+    // (unchanged by this re-touch) and re-set the voucher columns so the branch passes.
+    // NOTE: this rebinds VouchOwner to THIS node's owner key. Benign today — the
+    // write-while-alone drain only re-touches rows this node itself authored. If a future
+    // path lets one owner re-touch a row a DIFFERENT owner vouched, the voucher
+    // silently flips to this owner; that only matters once ticket-4's predicate checks
+    // VouchOwner against a node-local anchor, and only if the two owners differ in
+    // anchor membership.
+    const stampId = await this.controlDatabase.queryCadrePeerStampId(peerId);
+    if (stampId === null) {
+      log('reauthorizePeer: no CadrePeer row for %s (nothing to re-touch)', peerId);
+      return;
+    }
+    const signature = this.signDigest(cadrePeerVoucherDigest(peerId, stampId));
+    const db = this.controlDatabase.getDatabase();
+    await db.exec(`
+      update CadreControl.CadrePeer
+        with context OwnerKey = ?, Signature = ?
+        set UpdatedAt = ?, VouchOwner = ?, VouchSig = ?
+        where PeerId = ?
+    `, [this.ownerPublicKey, signature, updatedAt, this.ownerPublicKey, signature, peerId]);
+    log('Peer %s re-authorized (UpdatedAt=%d) for write-while-alone re-replication', peerId, updatedAt);
+  }
+
   /**
    * Create a seed from the current control network state.
-   * The seed contains peer information and is signed by an authority.
+   * The seed contains peer information and is signed by an owner.
    */
   async createSeed(): Promise<ControlNetworkSeed> {
-    if (!this.config.authorityPrivateKey || !this.authorityPublicKey) {
-      throw new Error('Authority key required to create seeds');
+    if (!this.config.ownerPrivateKey || !this.ownerPublicKey) {
+      throw new Error('Owner key required to create seeds');
     }
     
     if (!this.controlDatabase || !this.libp2pNode) {
@@ -227,12 +540,12 @@ export class SeedBootstrapService {
       peers,
     };
     
-    // Sign the seed
-    const seedJson = JSON.stringify(seedData);
-    const seedDigest = digest(seedJson, 'sha256', 'utf8', 'base64url') as string;
+    // Sign the seed over its canonical byte representation
+    const seedJson = canonicalSeedPayload(seedData);
+    const seedDigest = digest([seedJson], 'sha256', 'base64url') as string;
     const signature = sign(
       seedDigest,
-      this.config.authorityPrivateKey,
+      this.config.ownerPrivateKey,
       'ed25519',
       'base64url',
       'base64url',
@@ -242,7 +555,7 @@ export class SeedBootstrapService {
     const seed: ControlNetworkSeed = {
       ...seedData,
       signature,
-      signerKey: this.authorityPublicKey,
+      signerKey: this.ownerPublicKey,
     };
     
     log('Created seed with %d peers', peers.length);
@@ -251,9 +564,23 @@ export class SeedBootstrapService {
 
   /**
    * Apply a seed to populate the peer cache and enable connections.
-   * Validates the seed signature before applying.
+   *
+   * Validates the seed signature, then evaluates a trust anchor for the
+   * `signerKey` that does NOT come from the seed body: the receiver's
+   * `OwnerKey` table (DB-anchored), optionally augmented by pinned keys or
+   * TOFU via the configured/overriding `SeedTrustPolicy`. A forged
+   * self-asserting seed — one that merely lists its own signer as an owner
+   * peer — no longer passes.
+   *
+   * @param seed - The seed to apply (already transport-decoded).
+   * @param options.trustPolicy - Per-call policy override (e.g. a
+   *   `pinnedKeyTrustPolicy` derived from a `CadreInvite`) used instead of the
+   *   service-configured default for this seed only.
    */
-  async applySeed(seed: ControlNetworkSeed): Promise<ApplySeedResult> {
+  async applySeed(
+    seed: ControlNetworkSeed,
+    options?: { trustPolicy?: SeedTrustPolicy }
+  ): Promise<ApplySeedResult> {
     if (!this.libp2pNode) {
       return { success: false, peersAdded: 0, error: 'Service not initialized' };
     }
@@ -265,12 +592,24 @@ export class SeedBootstrapService {
       return { success: false, peersAdded: 0, error: 'Invalid seed signature' };
     }
 
-    // Verify the signer's key matches an authority peer's public key
-    const signerIsAuthority = seed.peers.some(
-      p => p.isAuthority && p.publicKey === seed.signerKey
-    );
-    if (!signerIsAuthority) {
-      return { success: false, peersAdded: 0, error: 'Signer key does not match any authority peer' };
+    // Evaluate the trust anchor for the signer key. The known-owner set is
+    // sourced from the receiver's control DB, never from the seed itself; a
+    // cold-start node with no DB and no override therefore sees an empty set.
+    const knownOwnerKeys = this.controlDatabase
+      ? await this.controlDatabase.getOwnerKeys()
+      : new Set<string>();
+    const policy = options?.trustPolicy ?? this.trustPolicy;
+    const decision = await policy.evaluate({
+      partyId: seed.partyId,
+      signerKey: seed.signerKey,
+      knownOwnerKeys,
+    });
+    if (!decision.trusted) {
+      return {
+        success: false,
+        peersAdded: 0,
+        error: decision.reason ?? 'Signer key not trusted by trust policy',
+      };
     }
 
     let peersAdded = 0;
@@ -295,13 +634,13 @@ export class SeedBootstrapService {
       }
     }
 
-    // Dial authority peers to establish connections
-    for (const peer of seed.peers.filter(p => p.isAuthority)) {
+    // Dial owner peers to establish connections
+    for (const peer of seed.peers.filter(p => p.isOwner)) {
       try {
         if (peer.multiaddrs.length > 0) {
           const addr = multiaddr(peer.multiaddrs[0]);
 
-          log('Dialing authority peer: %s', peer.peerId);
+          log('Dialing owner peer: %s', peer.peerId);
           await this.libp2pNode.dial(addr);
         }
       } catch (error) {
@@ -345,26 +684,18 @@ export class SeedBootstrapService {
 
     // Dial the target and open a stream
     const rawStream = await this.libp2pNode.dialProtocol(addr, SEED_PROTOCOL);
-    const stream = rawStream as unknown as LibP2PStream;
+    const stream = rawStream as unknown as ControlStream;
 
     try {
-      // Send the seed message
+      // Send the seed message as one length-prefixed frame (shared writer).
       const message: SeedMessage = {
         partyId: seed.partyId,
         peers: seed.peers,
-        transactions: seed.transactions,
         signature: seed.signature,
         signerKey: seed.signerKey,
       };
 
-      const messageBytes = new TextEncoder().encode(JSON.stringify(message));
-
-      // Write length-prefixed message using libp2p 3.x send() API
-      const lengthBytes = new Uint8Array(4);
-      new DataView(lengthBytes.buffer).setUint32(0, messageBytes.length, false);
-
-      stream.send(lengthBytes);
-      stream.send(messageBytes);
+      writeFrame(stream, message);
 
       // In libp2p v3.x, close() closes the write end only (signals EOF),
       // while the read end remains open for receiving the ack.
@@ -385,8 +716,8 @@ export class SeedBootstrapService {
       }
 
       // Parse length-prefixed response
-      const responseLength = new DataView(responseData.buffer, responseData.byteOffset).getUint32(0, false);
-      const responseJson = new TextDecoder().decode(responseData.slice(4, 4 + responseLength));
+      const responseBody = decodeLengthPrefixedFrame(responseData);
+      const responseJson = new TextDecoder().decode(responseBody);
       const ack = JSON.parse(responseJson) as SeedAckMessage;
 
       log('Seed delivery response: accepted=%s', ack.accepted);
@@ -420,15 +751,11 @@ export class SeedBootstrapService {
    */
   validateSeedSignature(seed: ControlNetworkSeed): boolean {
     try {
-      // Reconstruct the signed data (seed without signature fields)
-      const seedData = {
-        partyId: seed.partyId,
-        peers: seed.peers,
-        ...(seed.transactions ? { transactions: seed.transactions } : {}),
-      };
-
-      const seedJson = JSON.stringify(seedData);
-      const seedDigest = digest(seedJson, 'sha256', 'utf8', 'base64url') as string;
+      // Reconstruct the signed bytes via the shared canonical payload builder so
+      // verification is independent of key order. The payload is the fixed
+      // `{ partyId, peers }` the producer emits.
+      const seedJson = canonicalSeedPayload(seed);
+      const seedDigest = digest([seedJson], 'sha256', 'base64url') as string;
 
       return verify(
         seedDigest,
@@ -447,34 +774,39 @@ export class SeedBootstrapService {
 
   /**
    * Query peers from the control database.
+   *
+   * Owner identity is sourced from the `OwnerKey` table, not from the
+   * transport peer ID. An Ed25519 libp2p PeerId embeds its public key (identity
+   * multihash), so each peer's ed25519 key is derivable from its `PeerId`; a
+   * peer is an owner iff that derived key is in the `OwnerKey` set.
+   * This makes any owner node markable — not just the local one — and ties
+   * `isOwner` to the control table rather than to `peerId === self`.
    */
   private async queryPeers(): Promise<SeedPeer[]> {
     if (!this.controlDatabase) {
       return [];
     }
 
+    const ownerKeys = await this.controlDatabase.getOwnerKeys();
     const db = this.controlDatabase.getDatabase();
     const peers: SeedPeer[] = [];
 
-    // First, get all authority keys
-    const authorityKeys = new Set<string>();
-    for await (const row of db.eval('select Key from CadreControl.AuthorityKey')) {
-      authorityKeys.add(row.Key as string);
-    }
-
     // Query CadrePeer table
     for await (const row of db.eval('select PeerId, Multiaddr from CadreControl.CadrePeer')) {
       const peerId = row.PeerId as string;
       const multiaddr = row.Multiaddr as string | null;
 
-      // Mark peer as authority if it matches the service's own peer ID
-      const isAuthority = peerId === this.libp2pNode?.peerId.toString();
+      // Derive the peer's ed25519 key from its PeerId; a non-Ed25519 peer or an
+      // unparsable id yields null and is treated as a non-owner rather than
+      // failing the whole seed creation.
+      const pubKeyB64 = ed25519PublicKeyB64FromPeerId(peerId);
+      const isOwner = pubKeyB64 !== null && ownerKeys.has(pubKeyB64);
 
       peers.push({
         peerId,
         multiaddrs: multiaddr ? multiaddr.split(',') : [],
-        isAuthority,
-        ...(isAuthority && this.authorityPublicKey ? { publicKey: this.authorityPublicKey } : {}),
+        isOwner,
+        ...(isOwner ? { publicKey: pubKeyB64 } : {}),
       });
     }
 
@@ -482,105 +814,106 @@ export class SeedBootstrapService {
   }
 
   /**
-   * Register the seed protocol handler.
+   * Register the seed protocol handler. The inbound closure just delegates to
+   * {@link handleSeedStream} — extracted as a method so it has a unit-test seam
+   * (mirroring wake's `handleStream`) the inline closure never had.
    */
   private registerProtocolHandler(): void {
     if (!this.libp2pNode) return;
 
-    this.libp2pNode.handle(SEED_PROTOCOL, async (rawStream: unknown, rawConnection: unknown) => {
-      const stream = rawStream as LibP2PStream;
+    void this.libp2pNode.handle(SEED_PROTOCOL, async (rawStream: unknown, rawConnection: unknown) => {
       const remotePeerId = (rawConnection as Connection).remotePeer.toString();
-      log('Incoming seed delivery from: %s', remotePeerId);
+      await this.handleSeedStream(rawStream as ControlStream, remotePeerId);
+    });
+
+    log('Registered seed protocol handler: %s', SEED_PROTOCOL);
+  }
+
+  /**
+   * Read one inbound seed frame, apply it, and write the ack.
+   *
+   * Hardened against a buggy/compromised own-cadre node: a concurrency cap (over
+   * {@link maxConcurrentSeeds}, reply without applying), a read timeout (a peer
+   * that never half-closes is aborted inside `readStreamToEnd`), and the existing
+   * malformed/oversized-frame guard — all reported as a non-accepting
+   * {@link SeedAckMessage} rather than a dropped/hung stream.
+   */
+  private async handleSeedStream(stream: ControlStream, remotePeerId: string): Promise<void> {
+    log('Incoming seed delivery from: %s', remotePeerId);
 
+    if (this.activeStreams >= this.maxConcurrentSeeds) {
+      log('Rejecting seed from %s: %d concurrent streams at cap %d', remotePeerId, this.activeStreams, this.maxConcurrentSeeds);
+      const ack: SeedAckMessage = { accepted: false, reason: 'Too many concurrent seed deliveries' };
       try {
-        // Read the seed message (stream is AsyncIterable in libp2p 3.x)
-        const chunks: Uint8Array[] = [];
-        let totalLength = 0;
-
-        for await (const chunk of stream) {
-          const bytes = chunk instanceof Uint8Array ? chunk : (chunk as { subarray(): Uint8Array }).subarray();
-          chunks.push(bytes);
-          totalLength += bytes.length;
-          if (totalLength > MAX_SEED_SIZE) {
-            throw new Error('Seed message too large');
-          }
-        }
+        writeFrame(stream, ack);
+      } catch {
+        // Ignore send errors on the reject path.
+      }
+      try {
+        await stream.close();
+      } catch {
+        // Ignore close errors.
+      }
+      return;
+    }
 
-        const data = new Uint8Array(totalLength);
-        let offset = 0;
-        for (const chunk of chunks) {
-          data.set(chunk, offset);
-          offset += chunk.length;
-        }
+    this.activeStreams++;
+    try {
+      // Read the seed frame to EOF (bounded + size-capped), then decode it.
+      const data = await readStreamToEnd(stream, {
+        maxBytes: MAX_SEED_SIZE,
+        timeoutMs: this.seedReadTimeoutMs,
+        label: 'Seed',
+      });
 
-        // Parse length-prefixed message
-        const messageLength = new DataView(data.buffer, data.byteOffset).getUint32(0, false);
-        const messageJson = new TextDecoder().decode(data.slice(4, 4 + messageLength));
-        const message = JSON.parse(messageJson) as SeedMessage;
-
-        // Emit seed received event
-        this.eventCallbacks.onSeedReceived?.(message.partyId, remotePeerId);
-
-        // Convert to seed and apply
-        const seed: ControlNetworkSeed = {
-          partyId: message.partyId,
-          peers: message.peers,
-          transactions: message.transactions,
-          signature: message.signature,
-          signerKey: message.signerKey,
-        };
-
-        const result = await this.applySeed(seed);
-
-        // Emit appropriate event based on result
-        if (result.success) {
-          this.eventCallbacks.onSeedApplied?.(seed.partyId, result.peersAdded);
-        } else {
-          this.eventCallbacks.onSeedError?.(seed.partyId, result.error ?? 'Unknown error');
-        }
+      const messageBody = decodeLengthPrefixedFrame(data);
+      const messageJson = new TextDecoder().decode(messageBody);
+      const message = JSON.parse(messageJson) as SeedMessage;
 
-        // Send acknowledgment using libp2p 3.x send() API
-        const ack: SeedAckMessage = {
-          accepted: result.success,
-          reason: result.error,
-        };
+      // Emit seed received event
+      this.eventCallbacks.onSeedReceived?.(message.partyId, remotePeerId);
 
-        const ackBytes = new TextEncoder().encode(JSON.stringify(ack));
-        const lengthBytes = new Uint8Array(4);
-        new DataView(lengthBytes.buffer).setUint32(0, ackBytes.length, false);
+      // Convert to seed and apply
+      const seed: ControlNetworkSeed = {
+        partyId: message.partyId,
+        peers: message.peers,
+        signature: message.signature,
+        signerKey: message.signerKey,
+      };
 
-        stream.send(lengthBytes);
-        stream.send(ackBytes);
+      const result = await this.applySeed(seed);
 
-      } catch (error) {
-        log('Error handling seed delivery: %o', error);
-        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-
-        // Emit error event
-        this.eventCallbacks.onSeedError?.(this.config.partyId, errorMessage);
-
-        // Send error acknowledgment
-        const ack: SeedAckMessage = {
-          accepted: false,
-          reason: errorMessage,
-        };
-
-        const ackBytes = new TextEncoder().encode(JSON.stringify(ack));
-        const lengthBytes = new Uint8Array(4);
-        new DataView(lengthBytes.buffer).setUint32(0, ackBytes.length, false);
-
-        try {
-          stream.send(lengthBytes);
-          stream.send(ackBytes);
-        } catch {
-          // Ignore send errors
-        }
-      } finally {
-        await stream.close();
+      // Emit appropriate event based on result
+      if (result.success) {
+        this.eventCallbacks.onSeedApplied?.(seed.partyId, result.peersAdded);
+      } else {
+        this.eventCallbacks.onSeedError?.(seed.partyId, result.error ?? 'Unknown error');
       }
-    });
 
-    log('Registered seed protocol handler: %s', SEED_PROTOCOL);
+      const ack: SeedAckMessage = { accepted: result.success, reason: result.error };
+      writeFrame(stream, ack);
+    } catch (error) {
+      log('Error handling seed delivery: %o', error);
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+
+      // Emit error event
+      this.eventCallbacks.onSeedError?.(this.config.partyId, errorMessage);
+
+      // Send error acknowledgment (best-effort on the still-open write side).
+      const ack: SeedAckMessage = { accepted: false, reason: errorMessage };
+      try {
+        writeFrame(stream, ack);
+      } catch {
+        // Ignore send errors
+      }
+    } finally {
+      this.activeStreams--;
+      try {
+        await stream.close();
+      } catch {
+        // Ignore close errors.
+      }
+    }
   }
 
   /**
@@ -652,22 +985,29 @@ export class SeedBootstrapService {
     // configured (typically by `@serfab/cadre-host`'s NatService), it takes
     // priority — it may substitute a DDNS hostname and externally-mapped
     // port for the raw LAN multiaddrs libp2p reports.
-    let authorityAddrs: string[];
+    let ownerAddrs: string[];
     if (this.config.inviteAddressResolver) {
       try {
-        authorityAddrs = await this.config.inviteAddressResolver();
+        ownerAddrs = await this.config.inviteAddressResolver();
       } catch (err) {
         log('inviteAddressResolver threw, falling back to libp2pNode.getMultiaddrs(): %o', err);
-        authorityAddrs = this.libp2pNode.getMultiaddrs().map(a => a.toString());
+        ownerAddrs = this.libp2pNode.getMultiaddrs().map(a => a.toString());
       }
     } else {
-      authorityAddrs = this.libp2pNode.getMultiaddrs().map(a => a.toString());
+      ownerAddrs = this.libp2pNode.getMultiaddrs().map(a => a.toString());
     }
 
+    // Carry the cadre's owner keys out-of-band so a cold-start invitee can
+    // pin the trusted owner set before applying any seed.
+    const ownerKeys = this.controlDatabase
+      ? Array.from(await this.controlDatabase.getOwnerKeys())
+      : [];
+
     const now = Date.now();
     const invite: CadreInvite = {
       partyId: this.config.partyId,
-      authorityAddrs,
+      ownerAddrs,
+      ownerKeys: ownerKeys.length ? ownerKeys : undefined,
       token,
       createdAt: now,
       expiresAt: expiresIn ? now + expiresIn : undefined,
@@ -675,7 +1015,7 @@ export class SeedBootstrapService {
 
     const encodedInvite = this.encodeInvite(invite);
 
-    log('Invite created with %d authority addresses', authorityAddrs.length);
+    log('Invite created with %d owner addresses, %d owner keys', ownerAddrs.length, ownerKeys.length);
 
     return { invite, encodedInvite };
   }
@@ -769,11 +1109,11 @@ export class SeedBootstrapService {
   }
 
   /**
-   * Dial an authority from an invite.
-   * Use this on a phone after receiving an invite to connect to the authority.
+   * Dial an owner from an invite.
+   * Use this on a phone after receiving an invite to connect to the owner.
    *
    * @param invite - The invite received out-of-band
-   * @returns Connection to the authority
+   * @returns Connection to the owner
    */
   async dialInvite(invite: CadreInvite): Promise<void> {
     if (!this.libp2pNode) {
@@ -785,15 +1125,15 @@ export class SeedBootstrapService {
       throw new Error('Invite has expired');
     }
 
-    log('Dialing invite authority with %d addresses', invite.authorityAddrs.length);
+    log('Dialing invite owner with %d addresses', invite.ownerAddrs.length);
 
-    // Try each authority address until one succeeds
+    // Try each owner address until one succeeds
     let lastError: Error | null = null;
-    for (const addrStr of invite.authorityAddrs) {
+    for (const addrStr of invite.ownerAddrs) {
       try {
         const addr = multiaddr(addrStr);
         await this.libp2pNode.dial(addr);
-        log('Connected to authority at: %s', addrStr);
+        log('Connected to owner at: %s', addrStr);
         return;
       } catch (error) {
         lastError = error instanceof Error ? error : new Error(String(error));
@@ -801,7 +1141,7 @@ export class SeedBootstrapService {
       }
     }
 
-    throw lastError ?? new Error('No authority addresses available');
+    throw lastError ?? new Error('No owner addresses available');
   }
 }