@serfab/cadre-core 0.6.0 → 0.8.1

package/dist/seed-bootstrap.js

@@ -3,24 +3,96 @@ import { toString as uint8ArrayToString, fromString as uint8ArrayFromString } fr
 import { digest, sign, verify, getPublicKey } from '@optimystic/quereus-plugin-crypto';
 import { multiaddr } from '@multiformats/multiaddr';
 import { peerIdFromString } from '@libp2p/peer-id';
+import { writeFrame, readStreamToEnd } from './control-stream.js';
+import { canonicalJson } from './canonical-json.js';
+import { peerAuthorizationDigest } from './peer-authorization.js';
+import { dbAnchoredTrustPolicy, } from './seed-trust-policy.js';
 const log = debug('sereus:cadre:seed-bootstrap');
 /** Protocol ID for seed delivery */
 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 = 10000;
+/** 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, maxLength = MAX_SEED_SIZE) {
+    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 `AuthorityKey.Key` representation (and
+ * `authorityKeyFromLibp2p().publicKeyB64`). Returns null for a non-Ed25519
+ * id, a missing embedded key, or any parse failure — callers treat null as
+ * "not an authority" rather than throwing.
+ */
+export function ed25519PublicKeyB64FromPeerId(peerId) {
+    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) {
+    return canonicalJson({ partyId: seed.partyId, peers: seed.peers });
+}
 /**
  * SeedBootstrapService handles control network seed generation and delivery.
  *
  * 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 {
     constructor(config) {
         this.libp2pNode = null;
         this.controlDatabase = null;
+        /** In-flight inbound seed streams, used to enforce {@link maxConcurrentSeeds}. */
+        this.activeStreams = 0;
         this.eventCallbacks = {};
         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, 'ed25519', 'base64url', 'base64url');
@@ -38,41 +110,216 @@ export class SeedBootstrapService {
         this.eventCallbacks = callbacks;
     }
     /**
-     * Initialize the service with libp2p node and control database
+     * Whether this service holds an authority private key, i.e. can produce the
+     * authority signatures that gate `CadrePeer` / `DeviceToken` inserts, deletes,
+     * and re-authorizations. A seed-listener-only service (`enableSeedListener`,
+     * no authority key) returns false: it can receive/apply seeds but cannot author
+     * or re-issue authority writes. Used by the write-while-alone re-replication
+     * drain to skip authority work on a non-authority node.
      */
-    initialize(libp2pNode, controlDatabase) {
+    canAuthorize() {
+        return !!this.config.authorityPrivateKey;
+    }
+    /**
+     * 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, controlDatabase, options) {
         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.
+     *
+     * The authority 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 authority cannot produce
+     * the peer's self-signature, so the peer must self-publish (see
+     * {@link CadreNode.registerSelf}) before the row resolves.
      */
     async authorizePeer(options) {
         const { peerId, multiaddrs } = options;
+        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);
+    }
+    /**
+     * Authority-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 authority (it holds the authority key): the row is authority-signed
+     * (satisfying `AuthorizedInsert`) AND carries a valid self-`Sig`, so it resolves
+     * immediately without a follow-up self-update.
+     */
+    async insertSelfPeerRecord(record) {
+        await this.insertCadrePeerRow({
+            peerId: record.peerId,
+            publicKey: record.publicKey,
+            multiaddr: record.addrs.join(','),
+            updatedAt: record.updatedAt,
+            sig: record.sig,
+        });
+    }
+    /**
+     * Shared authority-signed `CadrePeer` INSERT. Signs `digest(peerId)` with the
+     * authority key (satisfying `AuthorizedInsert`) and writes the full record
+     * row. The authority signature does NOT cover the address columns — those are
+     * vouched only as far as the authority asserts them, and a peer's own `Sig`
+     * (when present) is what makes the row resolvable.
+     */
+    async insertCadrePeerRow(row) {
+        const signature = this.signPeerAuthorization(row.peerId);
+        if (!this.controlDatabase) {
+            throw new Error('Control database not initialized');
+        }
+        const db = this.controlDatabase.getDatabase();
+        await db.exec(`
+      insert into CadreControl.CadrePeer (PeerId, PublicKey, Multiaddr, UpdatedAt, Sig)
+        with context AuthorityKey = ?, Signature = ?
+        values (?, ?, ?, ?, ?)
+    `, [this.authorityPublicKey, signature, row.peerId, row.publicKey, row.multiaddr, row.updatedAt, row.sig]);
+    }
+    /**
+     * Authority-signed INSERT of a peer's OWN self-signed `DeviceToken` row.
+     *
+     * Counterpart to {@link insertSelfPeerRecord} for the device-token registry: the
+     * row is authority-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 authority 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 authority.
+     */
+    async insertSelfDeviceToken(record) {
+        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 AuthorityKey = ?, Signature = ?
+        values (?, ?, ?, ?, ?)
+    `, [this.authorityPublicKey, signature, record.peerId, record.platform, record.token, record.updatedAt, record.sig]);
+        log('Device token inserted (authority-signed): %s', record.peerId);
+    }
+    /**
+     * Authority-signed DELETE of a peer's `DeviceToken` row (logout / token
+     * invalidation). The `DeviceToken.AuthorizedInsert` constraint gates both insert
+     * AND delete on an authority signature over `digest(old.PeerId)`, so — like
+     * {@link removePeer} for `CadrePeer` — clearing a token requires the authority key.
+     */
+    async deleteDeviceToken(peerId) {
+        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 AuthorityKey = ?, Signature = ?
+        where PeerId = ?
+    `, [this.authorityPublicKey, signature, peerId]);
+        log('Device token removed (authority-signed): %s', peerId);
+    }
+    /**
+     * Sign a peer ID with the authority 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 authority key is set.
+     */
+    signPeerAuthorization(peerId) {
         if (!this.config.authorityPrivateKey) {
             throw new Error('Authority private key required to authorize peers');
         }
+        return sign(peerAuthorizationDigest(peerId), this.config.authorityPrivateKey, 'ed25519', 'base64url', 'base64url', 'base64url');
+    }
+    /**
+     * Remove a peer from the cadre by authority signature.
+     *
+     * The constraint over CadrePeer's `check on insert, delete` validates a
+     * signature over `digest(old.PeerId)` by an authority key. We use the same
+     * digest pattern as authorizePeer.
+     */
+    async removePeer(peerId) {
+        // Same canonical digest as the authorizing INSERT (see peerAuthorizationDigest);
+        // also validates the authority key is present before touching the database.
+        const signature = this.signPeerAuthorization(peerId);
+        if (!this.controlDatabase) {
+            throw new Error('Control database not initialized');
+        }
+        log('Removing peer: %s', peerId);
+        const db = this.controlDatabase.getDatabase();
+        await db.exec(`
+      delete from CadreControl.CadrePeer
+        with context AuthorityKey = ?, Signature = ?
+        where PeerId = ?
+    `, [this.authorityPublicKey, signature, peerId]);
+        log('Peer %s removed successfully', peerId);
+    }
+    /**
+     * Authority "re-touch" of an existing `CadrePeer` membership row: bump
+     * `UpdatedAt` under the authority 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 authority private key is configured (a non-authority cannot
+     *   re-sign another peer's row) or the control database is not initialized.
+     */
+    async reauthorizePeer(peerId, updatedAt) {
+        // Reuses the exact digest authorizePeer signs (peerAuthorizationDigest), which
+        // the authority branch of AuthorizedUpdate verifies; throws if no authority key.
+        const signature = this.signPeerAuthorization(peerId);
         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');
-        const signature = sign(peerIdDigest, this.config.authorityPrivateKey, 'ed25519', 'base64url', 'base64url', 'base64url');
-        // Insert into CadrePeer table with authority context
         const db = this.controlDatabase.getDatabase();
-        // CadrePeer.Multiaddr is NOT NULL; use empty string when no addrs provided
-        const multiaddrStr = multiaddrs?.length ? multiaddrs.join(',') : '';
         await db.exec(`
-      insert into CadreControl.CadrePeer (PeerId, Multiaddr)
+      update CadreControl.CadrePeer
         with context AuthorityKey = ?, Signature = ?
-        values (?, ?)
-    `, [this.authorityPublicKey, signature, peerId, multiaddrStr]);
-        log('Peer %s authorized successfully', peerId);
+        set UpdatedAt = ?
+        where PeerId = ?
+    `, [this.authorityPublicKey, signature, updatedAt, 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.
@@ -93,9 +340,9 @@ export class SeedBootstrapService {
             partyId: this.config.partyId,
             peers,
         };
-        // Sign the seed
-        const seedJson = JSON.stringify(seedData);
-        const seedDigest = digest(seedJson, 'sha256', 'utf8', 'base64url');
+        // Sign the seed over its canonical byte representation
+        const seedJson = canonicalSeedPayload(seedData);
+        const seedDigest = digest([seedJson], 'sha256', 'base64url');
         const signature = sign(seedDigest, this.config.authorityPrivateKey, 'ed25519', 'base64url', 'base64url', 'base64url');
         const seed = {
             ...seedData,
@@ -107,9 +354,20 @@ 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
+     * `AuthorityKey` 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 authority
+     * 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) {
+    async applySeed(seed, options) {
         if (!this.libp2pNode) {
             return { success: false, peersAdded: 0, error: 'Service not initialized' };
         }
@@ -118,10 +376,24 @@ export class SeedBootstrapService {
         if (!this.validateSeedSignature(seed)) {
             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-authority 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 knownAuthorityKeys = this.controlDatabase
+            ? await this.controlDatabase.getAuthorityKeys()
+            : new Set();
+        const policy = options?.trustPolicy ?? this.trustPolicy;
+        const decision = await policy.evaluate({
+            partyId: seed.partyId,
+            signerKey: seed.signerKey,
+            knownAuthorityKeys,
+        });
+        if (!decision.trusted) {
+            return {
+                success: false,
+                peersAdded: 0,
+                error: decision.reason ?? 'Signer key not trusted by trust policy',
+            };
         }
         let peersAdded = 0;
         // Add peers to the peer store
@@ -187,20 +459,14 @@ export class SeedBootstrapService {
         const rawStream = await this.libp2pNode.dialProtocol(addr, SEED_PROTOCOL);
         const stream = rawStream;
         try {
-            // Send the seed message
+            // Send the seed message as one length-prefixed frame (shared writer).
             const message = {
                 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.
             await stream.close();
@@ -217,8 +483,8 @@ export class SeedBootstrapService {
                 offset += chunk.length;
             }
             // 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);
             log('Seed delivery response: accepted=%s', ack.accepted);
             return ack;
@@ -246,14 +512,11 @@ export class SeedBootstrapService {
      */
     validateSeedSignature(seed) {
         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');
+            // 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');
             return verify(seedDigest, seed.signature, seed.signerKey, 'ed25519', 'base64url', 'base64url', 'base64url');
         }
         catch (error) {
@@ -263,120 +526,135 @@ export class SeedBootstrapService {
     }
     /**
      * Query peers from the control database.
+     *
+     * Authority identity is sourced from the `AuthorityKey` 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 authority iff that derived key is in the `AuthorityKey` set.
+     * This makes any authority node markable — not just the local one — and ties
+     * `isAuthority` to the control table rather than to `peerId === self`.
      */
     async queryPeers() {
         if (!this.controlDatabase) {
             return [];
         }
+        const authorityKeys = await this.controlDatabase.getAuthorityKeys();
         const db = this.controlDatabase.getDatabase();
         const peers = [];
-        // First, get all authority keys
-        const authorityKeys = new Set();
-        for await (const row of db.eval('select Key from CadreControl.AuthorityKey')) {
-            authorityKeys.add(row.Key);
-        }
         // Query CadrePeer table
         for await (const row of db.eval('select PeerId, Multiaddr from CadreControl.CadrePeer')) {
             const peerId = row.PeerId;
             const multiaddr = row.Multiaddr;
-            // 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-authority rather than
+            // failing the whole seed creation.
+            const pubKeyB64 = ed25519PublicKeyB64FromPeerId(peerId);
+            const isAuthority = pubKeyB64 !== null && authorityKeys.has(pubKeyB64);
             peers.push({
                 peerId,
                 multiaddrs: multiaddr ? multiaddr.split(',') : [],
                 isAuthority,
-                ...(isAuthority && this.authorityPublicKey ? { publicKey: this.authorityPublicKey } : {}),
+                ...(isAuthority ? { publicKey: pubKeyB64 } : {}),
             });
         }
         return peers;
     }
     /**
-     * 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.
      */
     registerProtocolHandler() {
         if (!this.libp2pNode)
             return;
-        this.libp2pNode.handle(SEED_PROTOCOL, async (rawStream, rawConnection) => {
-            const stream = rawStream;
+        void this.libp2pNode.handle(SEED_PROTOCOL, async (rawStream, rawConnection) => {
             const remotePeerId = rawConnection.remotePeer.toString();
-            log('Incoming seed delivery from: %s', remotePeerId);
+            await this.handleSeedStream(rawStream, 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.
+     */
+    async handleSeedStream(stream, remotePeerId) {
+        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 = { accepted: false, reason: 'Too many concurrent seed deliveries' };
             try {
-                // Read the seed message (stream is AsyncIterable in libp2p 3.x)
-                const chunks = [];
-                let totalLength = 0;
-                for await (const chunk of stream) {
-                    const bytes = chunk instanceof Uint8Array ? chunk : chunk.subarray();
-                    chunks.push(bytes);
-                    totalLength += bytes.length;
-                    if (totalLength > MAX_SEED_SIZE) {
-                        throw new Error('Seed message too large');
-                    }
-                }
-                const data = new Uint8Array(totalLength);
-                let offset = 0;
-                for (const chunk of chunks) {
-                    data.set(chunk, offset);
-                    offset += chunk.length;
-                }
-                // 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);
-                // Emit seed received event
-                this.eventCallbacks.onSeedReceived?.(message.partyId, remotePeerId);
-                // Convert to seed and apply
-                const seed = {
-                    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');
-                }
-                // Send acknowledgment using libp2p 3.x send() API
-                const ack = {
-                    accepted: result.success,
-                    reason: result.error,
-                };
-                const ackBytes = new TextEncoder().encode(JSON.stringify(ack));
-                const lengthBytes = new Uint8Array(4);
-                new DataView(lengthBytes.buffer).setUint32(0, ackBytes.length, false);
-                stream.send(lengthBytes);
-                stream.send(ackBytes);
+                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
-                const ack = {
-                    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
-                }
+            catch {
+                // Ignore send errors on the reject path.
             }
-            finally {
+            try {
                 await stream.close();
             }
-        });
-        log('Registered seed protocol handler: %s', SEED_PROTOCOL);
+            catch {
+                // Ignore close errors.
+            }
+            return;
+        }
+        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',
+            });
+            const messageBody = decodeLengthPrefixedFrame(data);
+            const messageJson = new TextDecoder().decode(messageBody);
+            const message = JSON.parse(messageJson);
+            // Emit seed received event
+            this.eventCallbacks.onSeedReceived?.(message.partyId, remotePeerId);
+            // Convert to seed and apply
+            const seed = {
+                partyId: message.partyId,
+                peers: message.peers,
+                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 ack = { 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 = { accepted: false, reason: errorMessage };
+            try {
+                writeFrame(stream, ack);
+            }
+            catch {
+                // Ignore send errors
+            }
+        }
+        finally {
+            this.activeStreams--;
+            try {
+                await stream.close();
+            }
+            catch {
+                // Ignore close errors.
+            }
+        }
     }
     /**
      * Shutdown the service.
@@ -432,19 +710,39 @@ export class SeedBootstrapService {
             throw new Error('Service not initialized');
         }
         log('Creating invite for phone');
-        // Get this node's dialable addresses
-        const addrs = this.libp2pNode.getMultiaddrs();
-        const authorityAddrs = addrs.map(a => a.toString());
+        // Get this node's dialable addresses. When an inviteAddressResolver is
+        // 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;
+        if (this.config.inviteAddressResolver) {
+            try {
+                authorityAddrs = await this.config.inviteAddressResolver();
+            }
+            catch (err) {
+                log('inviteAddressResolver threw, falling back to libp2pNode.getMultiaddrs(): %o', err);
+                authorityAddrs = this.libp2pNode.getMultiaddrs().map(a => a.toString());
+            }
+        }
+        else {
+            authorityAddrs = this.libp2pNode.getMultiaddrs().map(a => a.toString());
+        }
+        // Carry the cadre's authority keys out-of-band so a cold-start invitee can
+        // pin the trusted authority set before applying any seed.
+        const authorityKeys = this.controlDatabase
+            ? Array.from(await this.controlDatabase.getAuthorityKeys())
+            : [];
         const now = Date.now();
         const invite = {
             partyId: this.config.partyId,
             authorityAddrs,
+            authorityKeys: authorityKeys.length ? authorityKeys : undefined,
             token,
             createdAt: now,
             expiresAt: expiresIn ? now + expiresIn : undefined,
         };
         const encodedInvite = this.encodeInvite(invite);
-        log('Invite created with %d authority addresses', authorityAddrs.length);
+        log('Invite created with %d authority addresses, %d authority keys', authorityAddrs.length, authorityKeys.length);
         return { invite, encodedInvite };
     }
     /**