@serfab/cadre-core 0.9.0 → 0.10.0

package/dist/seed-bootstrap.d.ts

@@ -1,7 +1,8 @@
 import type { Libp2p } from '@libp2p/interface';
-import type { ControlNetworkSeed, SeedAckMessage, AuthorizePeerOptions, ApplySeedResult, AddDroneOptions, AddPhoneOptions, DroneInitResult, InviteResult, CadreInvite, PeerAddressRecord, DeviceTokenRecord } from './types.js';
+import type { ControlNetworkSeed, SeedAckMessage, AuthorizePeerOptions, ApplySeedResult, AddDroneOptions, AddPhoneOptions, DroneInitResult, InviteResult, CadreInvite, PeerAddressRecord, DeviceTokenRecord, RevocationRow } from './types.js';
 import type { ControlDatabase } from './control-database.js';
 import { type SeedTrustPolicy } from './seed-trust-policy.js';
+import type { TrustedOwnerStore } from './trusted-owner-store.js';
 /** Protocol ID for seed delivery */
 export declare const SEED_PROTOCOL = "/sereus/seed/1.0.0";
 /**
@@ -53,9 +54,9 @@ export interface SeedBootstrapConfig {
     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
+     * `signerKey` should be trusted, against the receiver's anchored owner
+     * keys (NOT the seed body). Defaults to `anchoredTrustPolicy()`, which
+     * rejects any signer not already in {@link trustedOwners}. An enrollment
      * caller can pass a per-seed override to `applySeed` instead.
      *
      * A `CadreNode` forwards its node-wide `CadreNodeConfig.seedTrustPolicy` here
@@ -63,6 +64,19 @@ export interface SeedBootstrapConfig {
      * since a network-delivered seed has no per-call override.
      */
     trustPolicy?: SeedTrustPolicy;
+    /**
+     * The node-local, NON-replicated trusted-owner anchor. Supplies
+     * `SeedTrustContext.knownOwnerKeys` for every {@link applySeed}, and receives
+     * a key accepted via a pin/TOFU (see `SeedTrustDecision.anchorAs`).
+     *
+     * Deliberately NOT `ControlDatabase.getOwnerKeys()`: the replicated
+     * `OwnerKey` table is pollutable — any connecting node can genesis-insert its
+     * own key and let it replicate — so a seed signed by a stranger's self-issued
+     * owner key would pass a table-anchored check. A `CadreNode` passes its
+     * `getTrustedOwnerStore()` here. Unset (e.g. a directly-constructed service in
+     * a test) means an EMPTY anchor: only a pinned/TOFU policy can accept a seed.
+     */
+    trustedOwners?: TrustedOwnerStore;
     /**
      * 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
@@ -75,6 +89,15 @@ export interface SeedBootstrapConfig {
      * returned without applying any seed.
      */
     maxConcurrentSeeds?: number;
+    /**
+     * Time {@link SeedBootstrapService.deliverSeed} waits for the whole exchange —
+     * dial, write, ack read — before aborting (ms). Defaults to
+     * {@link DEFAULT_SEED_DELIVER_TIMEOUT_MS}. Bounds the SENDER against a seed
+     * target that accepts the stream and then never replies; the target is a
+     * not-yet-trusted node during onboarding, so this is the more exposed
+     * direction than the receiver knobs above.
+     */
+    seedDeliverTimeoutMs?: number;
 }
 /**
  * Event callbacks for seed-related events
@@ -82,8 +105,15 @@ export interface SeedBootstrapConfig {
 export interface SeedEventCallbacks {
     /** Called when a seed is received via the protocol */
     onSeedReceived?: (partyId: string, peerId: string) => void;
-    /** Called when a seed is successfully applied */
-    onSeedApplied?: (partyId: string, peersAdded: number) => void;
+    /**
+     * Called when a seed is successfully applied.
+     *
+     * `seed` is the applied seed itself: the inbound protocol handler applies it
+     * INSIDE the service, so this callback is the only seam through which a
+     * `CadreNode` sees a wire-delivered seed's contents — which it needs to
+     * retain the owner-flagged peers as cold-start bootstrap dial targets.
+     */
+    onSeedApplied?: (partyId: string, peersAdded: number, seed: ControlNetworkSeed) => void;
     /** Called when seed application fails */
     onSeedError?: (partyId: string, error: string) => void;
 }
@@ -102,6 +132,7 @@ export declare class SeedBootstrapService {
     private readonly trustPolicy;
     private readonly seedReadTimeoutMs;
     private readonly maxConcurrentSeeds;
+    private readonly seedDeliverTimeoutMs;
     /** In-flight inbound seed streams, used to enforce {@link maxConcurrentSeeds}. */
     private activeStreams;
     private eventCallbacks;
@@ -137,7 +168,7 @@ export declare class SeedBootstrapService {
     }): void;
     /**
      * Authorize a new peer to join the cadre.
-     * Signs the peer ID with the owner key and inserts into CadrePeer table.
+     * Signs a membership voucher 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
@@ -156,45 +187,70 @@ export declare class SeedBootstrapService {
      * 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.
-     */
-    insertSelfPeerRecord(record: PeerAddressRecord): Promise<void>;
-    /**
-     * 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.
+     *
+     * @returns `true` when this call seated the row, `false` when a concurrent writer
+     *   (e.g. an {@link authorizePeer} of this node's own id) had already seated it —
+     *   in which case the row in the database is NOT this record and carries whatever
+     *   `Sig` that writer had, so the caller must self-update to publish its signature.
+     */
+    insertSelfPeerRecord(record: PeerAddressRecord): Promise<boolean>;
+    /**
+     * Shared owner-signed `CadrePeer` INSERT — the row fields and the owner-key
+     * precondition; the stamp mint, voucher signature, write lock, existence check and
+     * membership notify are all {@link ControlDatabase.insertCadrePeer}'s (see there for
+     * the anti-replay and insert-race rationale). No `CadrePeer` write may bypass that
+     * method: the write is what admits the peer's traffic.
+     *
+     * The DB check precedes the owner-key check here, matching the order this method has
+     * always surfaced them (the owner-key error used to come out of the signer, after the
+     * DB check).
+     *
+     * @returns `true` when this call performed the INSERT, `false` when the row was
+     *   already seated by a concurrent writer. The loser needs to know: an authorize seats
+     *   a row with a null `Sig`, so a self-publish that lost the race must fall through to
+     *   a self-update or its record never lands.
      */
     private insertCadrePeerRow;
     /**
      * Owner-signed INSERT of a peer's OWN self-signed `DeviceToken` row.
      *
      * 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
+     * row is owner-signed (satisfying `DeviceToken.AuthorizedInsert` via the
+     * 'add'-tagged digest, {@link deviceTokenAddDigest}) AND carries the peer's
+     * own self-`Sig` over the token payload. The owner signature covers the WHOLE row
+     * (every column, ending in a freshly minted single-use `StampId`) — but covering the
+     * token contents is not the same as vouching them: 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.
+     *
+     * The stamp is per-INSERT, so a re-register after a clear mints a fresh one and a
+     * fresh signature — unaffected by the cleared row's retired stamp
+     * (`DeviceToken.NotRevoked`).
      */
     insertSelfDeviceToken(record: DeviceTokenRecord): Promise<void>;
     /**
      * 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.
+     * invalidation). The `DeviceToken.AuthorizedDelete` constraint validates an owner
+     * signature over the 'remove'-tagged digest bound to the STORED row's
+     * (PeerId, StampId) — deliberately distinct from the insert digest, so a captured
+     * insert approval can never be replayed to clear a token. Like {@link removePeer}
+     * for `CadrePeer`, clearing a token requires the owner key.
+     *
+     * The delete and the `Revocation` tombstone retiring the row's `StampId` commit in
+     * ONE transaction — `DeviceToken.RevocationRecorded` refuses a bare delete, and
+     * without the tombstone the stamp would free up and the never-expiring insert
+     * approval (which the cleared device holds a copy of) would re-seat the token. The
+     * tombstone carries its OWN owner signature: retiring a stamp permanently forecloses
+     * that row, so it is an owner action in its own right.
+     *
+     * Both digests, the stamp read, and the transaction come from
+     * {@link ControlDatabase.deleteDeviceToken} — one shared implementation across
+     * `CadrePeer` / `DeviceToken` / `Strand` / `ValidationKey`. What stays here is the
+     * owner-key precondition; a no-op on an already-absent row is the shared body's
+     * behavior, and unlike {@link removePeer} nothing here rides on it.
      */
     deleteDeviceToken(peerId: string): Promise<void>;
-    /**
-     * 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;
     /**
      * Return the configured owner private key, or throw if none is set. The single
      * precondition gate for every owner-signed write. {@link removePeer} /
@@ -204,38 +260,68 @@ export declare class SeedBootstrapService {
      * target row is absent (the early `stampId === null` return) instead of rejecting.
      */
     private requireOwnerPrivateKey;
+    /**
+     * The owner PUBLIC key that rides in every owner-signed write's context, non-null.
+     *
+     * The field is nullable because a read-only service carries no owner key at all, but the
+     * constructor derives the public key whenever `ownerPrivateKey` is set — so gating on
+     * {@link requireOwnerPrivateKey} first makes the pair inseparable and the second throw
+     * unreachable. Callers that must reject a keyless service BEFORE any DB read use this as
+     * their first line and get the owner-key precondition for free.
+     */
+    private requireOwnerPublicKey;
     /**
      * 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.
+     * owner private key is applied; callers pass the canonical domain-tagged digest for
+     * the specific action ({@link deviceTokenAddDigest}), or the raw-bytes form via
+     * {@link signMessageBytes}. Throws if no owner key is set.
      */
     private signDigest;
+    /**
+     * Adapt the control database's raw-bytes `signMessage` callback (every guarded delete
+     * takes one) to {@link signDigest}'s base64url-string form. Both encodings hash to the
+     * same signed bytes (`sign` decodes its base64url input), so a signature minted here
+     * satisfies the same schema CHECK as one from the callers that sign the bytes directly — see
+     * `control-revocation-replay.spec.ts`'s "raw-bytes and digest-string signers agree".
+     */
+    private signMessageBytes;
     /**
      * 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.
+     * signature over the DISTINCT 'remove'-tagged digest
+     * `digest('CadreControl.CadrePeer', 'remove', old.PeerId, old.StampId)` by an owner
+     * key — deliberately NOT the insert voucher digest, so the row's stored `VouchSig` can
+     * never be replayed to delete.
+     *
+     * The delete and the `Revocation` tombstone retiring the row's `StampId` commit in ONE
+     * transaction — `CadrePeer.RevocationRecorded` refuses a bare delete, and without the
+     * tombstone the stamp would free up and the original admission approval (which never
+     * expires, and which the removed peer holds a copy of) would re-seat the row.
+     *
+     * The tombstone is separately owner-signed (satisfying `Revocation.Authorized`):
+     * retiring a stamp evicts that peer party-wide and permanently forecloses re-admitting
+     * the row, so it is an owner action in its own right, not a side effect the delete's
+     * signature covers.
+     *
+     * Both digests, the stamp read, the transaction, and the post-commit membership notify
+     * come from {@link ControlDatabase.deleteCadrePeer} — one shared implementation across
+     * `CadrePeer` / `DeviceToken` / `Strand` / `ValidationKey`. What stays here is the
+     * owner-key precondition and the absent-row gate the notify depends on (below).
      */
     removePeer(peerId: string): Promise<void>;
     /**
-     * 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).
+     * Owner "re-touch" of an existing `CadrePeer` membership row: bump `UpdatedAt` and
+     * re-vouch the row so it 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.
+     *
+     * The stamp read, the voucher signature, the write lock and the membership notify are
+     * {@link ControlDatabase.reauthorizeCadrePeer}'s — including the caveat that it rebinds
+     * `VouchOwner` to this node's owner key. What stays here is the owner-key precondition.
+     *
+     * A no-op (no throw, no notify) when the row does not exist.
      *
      * @param peerId - the membership row to re-touch.
      * @param updatedAt - the strictly-increasing freshness stamp to write.
@@ -243,6 +329,23 @@ export declare class SeedBootstrapService {
      *   re-sign another peer's row) or the control database is not initialized.
      */
     reauthorizePeer(peerId: string, updatedAt: number): Promise<void>;
+    /**
+     * Owner re-issue of a batch of `Revocation` tombstones: bump each row's
+     * `ReissuedAt` so the storage layer re-broadcasts a tombstone that committed
+     * while the node was alone. The delete-while-alone counterpart of
+     * {@link reauthorizePeer} — a removed row cannot be re-touched (it is gone),
+     * but its tombstone can, and every membership read treats a retired stamp as
+     * absent.
+     *
+     * The signatures, the single transaction, and the strictly-monotonic
+     * `reissuedAt` contract are {@link ControlDatabase.reissueRevocations}'s. What
+     * stays here is the owner-key precondition.
+     *
+     * @returns how many tombstones were re-issued (`rows.length` on success).
+     * @throws if no owner private key is configured or the control database is not
+     *   initialized.
+     */
+    reissueRevocations(rows: readonly RevocationRow[], reissuedAt: number): Promise<number>;
     /**
      * Create a seed from the current control network state.
      * The seed contains peer information and is signed by an owner.
@@ -253,10 +356,15 @@ export declare class SeedBootstrapService {
      *
      * 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.
+     * node-local {@link SeedBootstrapConfig.trustedOwners} anchor, 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, and neither does one signed
+     * by a key a stranger genesis-inserted into the replicated `OwnerKey` table.
+     *
+     * A key accepted via a pin/TOFU is persisted into the anchor (the policy says
+     * so via `SeedTrustDecision.anchorAs`), so the next seed from that owner is
+     * anchored without re-supplying the invite.
      *
      * @param seed - The seed to apply (already transport-decoded).
      * @param options.trustPolicy - Per-call policy override (e.g. a
@@ -266,6 +374,26 @@ export declare class SeedBootstrapService {
     applySeed(seed: ControlNetworkSeed, options?: {
         trustPolicy?: SeedTrustPolicy;
     }): Promise<ApplySeedResult>;
+    /**
+     * Persist a signer that a pin/TOFU accepted into the node-local anchor, so a
+     * later seed from the same owner is anchored without re-supplying the invite
+     * or re-prompting. Only the policy decides this happens (`anchorAs` is unset
+     * when the key was already anchored, so a plain re-apply writes nothing) and
+     * `trust()` is idempotent, keeping the original provenance for a known key.
+     *
+     * Failure to PERSIST does not fail the seed: `trust()` reflects the key in the
+     * in-memory anchor synchronously, so this seed and the rest of the session are
+     * unaffected — only durability across a restart is lost, and that is logged.
+     *
+     * NOTE: anchoring a key can flip `CadrePeer` rows ALREADY present from
+     * unauthorized to authorized, which the write-driven membership-gate refresh
+     * (`ControlDatabase.mutateCadrePeer`) cannot see — no row was written. Every
+     * anchor mutation today rides seed application, and both seed paths refresh the
+     * gate explicitly afterwards (`CadreNode.applySeed`, `onSeedApplied`). If some
+     * future path anchors an owner OUTSIDE seed application, it owes the same
+     * `CadreNode.refreshMembershipGate()` — or the anchor needs its own hub.
+     */
+    private anchorAcceptedSigner;
     /**
      * Encode a seed for out-of-band delivery (e.g., QR code, copy/paste).
      */
@@ -276,8 +404,37 @@ export declare class SeedBootstrapService {
     decodeSeed(encoded: string): ControlNetworkSeed;
     /**
      * Deliver a seed directly to a peer via the /sereus/seed/1.0.0 protocol.
+     *
+     * Sender hardening: the whole exchange — dial, write, ack read — is bounded by
+     * {@link seedDeliverTimeoutMs}, and the ack is capped at {@link MAX_SEED_SIZE}.
+     * The target is a NOT-YET-TRUSTED node the instigator chose to dial during
+     * onboarding, so an unbounded read here is strictly more exposed than the
+     * membership-gated receiver paths: without the bound a target that accepts the
+     * stream and never replies parks this call forever, and one that streams
+     * arbitrary bytes as a fake ack exhausts memory.
      */
     deliverSeed(targetMultiaddr: string, seed: ControlNetworkSeed): Promise<SeedAckMessage>;
+    /**
+     * Open one stream to the target, send the seed frame, half-close, and read the ack.
+     *
+     * `signal` is the deadline from {@link deliverSeed}: it goes to `dialProtocol` so
+     * a timeout during connect aborts the dial, and into {@link exchangeFrame} so a
+     * timeout after the stream is open resets it — releasing the otherwise unbounded
+     * ack-read.
+     *
+     * Deliberately NOT `runOnLimitedConnection`: a wake sets it because a wake is a
+     * tiny frame over a relay, whereas a seed is up to 1MB and this delivery path
+     * does not dial relay addresses today. Changing that is a separate decision.
+     */
+    private sendSeed;
+    /**
+     * Read the ack frame a delivery target writes back, bounded by
+     * {@link seedDeliverTimeoutMs} and capped at {@link MAX_SEED_SIZE} — an
+     * untrusted target must not be able to stream unlimited bytes as a fake ack.
+     * Decoding runs inside {@link exchangeFrame}'s `try`, so a malformed or
+     * non-JSON ack resets the stream rather than leaking it.
+     */
+    private readSeedAck;
     /**
      * Get this node's circuit relay address for inclusion in seeds.
      * Returns null if no relay address is available.
@@ -296,6 +453,14 @@ export declare class SeedBootstrapService {
      * 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`.
+     *
+     * NOTE: this is the one owner lookup deliberately left on the REPLICATED
+     * table rather than the node-local anchor. `SeedPeer.isOwner` is a dial hint
+     * — the receiver dials owner-flagged peers first — not a trust decision, and
+     * the receiver re-derives real trust from its own anchor. So a polluted table
+     * costs at most a wasted dial, while anchoring here would silently drop
+     * legitimate co-owners this node never pinned. If `isOwner` ever gates
+     * anything the receiver TRUSTS, move it to the anchor.
      */
     private queryPeers;
     /**