@serfab/cadre-core 0.8.1 → 0.10.0

package/src/types.ts

@@ -1,9 +1,14 @@
 import type { ConnectionGater, Libp2p, PeerId, PrivateKey } from '@libp2p/interface';
 import type { IRawStorage, Libp2pTransports } from '@optimystic/db-p2p';
-import type { IRepo } from '@optimystic/db-core';
+import type { IPeerNetwork, IRepo } from '@optimystic/db-core';
+import type { StrandBackfillConfig } from './strand-backfill.js';
 import type { StrandDatabase } from './strand-database.js';
 import type { SeedTrustPolicy } from './seed-trust-policy.js';
 import type { KeyStore, KeyId } from './key-store.js';
+import type { TrustedOwnerStore, TrustSource } from './trusted-owner-store.js';
+import type { BootstrapPeerStore } from './bootstrap-peer-store.js';
+import type { PushNotifier } from './push-notifier.js';
+import type { RevocableTable } from './control-authorization.js';
 
 /**
  * Extended Libp2p node with the coordinatedRepo attached by db-p2p's
@@ -11,6 +16,14 @@ import type { KeyStore, KeyId } from './key-store.js';
  */
 export interface Libp2pNodeWithRepo extends Libp2p {
   coordinatedRepo: IRepo;
+  /**
+   * The node's key-addressed peer network, attached by db-p2p's factory alongside
+   * `coordinatedRepo` (`libp2p-node-base.ts`). Optional deliberately: the base
+   * factory always assigns it, but it is not part of the upstream node type, so
+   * declaring it required would be a claim this repo cannot enforce. The strand
+   * backfill (`strand-backfill.ts`) logs once and stays inert when it is absent.
+   */
+  keyNetwork?: IPeerNetwork;
 }
 
 /**
@@ -119,8 +132,9 @@ export interface StorageConfig {
    *
    * For React Native, use the appropriate storage from @optimystic/db-p2p-storage-rn:
    * ```typescript
-   * import { RNRawStorage } from '@optimystic/db-p2p-storage-rn';
-   * storage: { provider: (strandId) => new RNRawStorage(strandId) }
+   * import { LevelDBRawStorage } from '@optimystic/db-p2p-storage-rn';
+   * // `db` is an open LevelDB handle (see `openOptimysticRNDb` over `rn-leveldb`)
+   * storage: { provider: (strandId) => new LevelDBRawStorage(openDb(`sereus-${strandId}`)) }
    * ```
    *
    * For in-memory storage (testing):
@@ -138,7 +152,47 @@ export interface StorageConfig {
  */
 export interface NetworkConfig {
   listenAddrs?: string[];
+  /**
+   * Addresses to advertise to peers instead of `listenAddrs` — for a node behind
+   * NAT or a reverse proxy that is reachable at a different address than it binds
+   * (e.g. `mynode.example.com:4001` in front of a `0.0.0.0:4001` listener).
+   *
+   * Accepted (settable in `cadre.yaml`, via `CADRE_ANNOUNCE_ADDRS`, and through the
+   * Docker entrypoint) but **not yet applied**: libp2p only takes announce addresses
+   * at construction (`addresses.announce` / `addresses.appendAnnounce`), and
+   * `@optimystic/db-p2p`'s `NodeOptions` has no field for either — there is nothing
+   * in this repo to wire this into. `CadreNode.start()` warns when this is set,
+   * rather than pretending it works. Unblocked by the `announce-addrs-option`
+   * request filed against `@optimystic/db-p2p`; wiring lands here once this repo's
+   * dependency range moves to a version carrying it.
+   *
+   * Use {@link relayAddrs} for reachability behind NAT today (a reserved relay slot
+   * gives the node a real dialable circuit address), or `inviteAddressResolver` to
+   * substitute a reachable address into invite payloads specifically — neither
+   * changes what this node advertises on the wire, but both cover the operator need
+   * this field cannot yet.
+   */
   announceAddrs?: string[];
+  /**
+   * Circuit-relay servers this node reserves a slot on, so peers can reach it
+   * from behind NAT. Each entry is the relay's DIRECT dial multiaddr ending in
+   * its peerId — `/dns4/relay.example.com/tcp/4001/p2p/12D3KooW…` — with no
+   * `/p2p-circuit` suffix (one is appended for you; an entry that already has
+   * one is passed through unchanged).
+   *
+   * This is sugar for a circuit entry in {@link listenAddrs}: `relay-addrs.ts`
+   * resolves the two into one listen list, and listening on a relay's circuit
+   * addr is what makes libp2p dial it and hold the reservation. A relay named
+   * here therefore also becomes a delegate-announce target, so this node's
+   * strand nodes may reserve on it too (see `delegate-admission.ts`).
+   *
+   * Setting this gives the node a listener even when `listenAddrs` is `[]` —
+   * that is the point of naming a relay, but note that React Native hosts
+   * (`reference-app-rn`'s `cadre-phone.ts`) deliberately do NOT listen, and
+   * must not acquire a listener by accident.
+   *
+   * A malformed entry throws at node start rather than being silently dropped.
+   */
   relayAddrs?: string[];
   /**
    * Enable circuit relay server - allows this node to relay connections for other peers.
@@ -165,7 +219,7 @@ export interface NetworkConfig {
   transports?: Libp2pTransports;
   /**
    * Optional async resolver returning the multiaddrs to embed in invites
-   * (and other authority-address contexts). When unset, `libp2pNode.getMultiaddrs()`
+   * (and other owner-address contexts). When unset, `libp2pNode.getMultiaddrs()`
    * is used. Hosts behind NAT supply this to substitute their DDNS hostname
    * and externally-mapped port — see `@serfab/cadre-host`'s NatService.
    */
@@ -178,6 +232,12 @@ export interface NetworkConfig {
    * Playwright e2e, RN simulators) supply a permissive gater here — e.g.
    * `{ denyDialMultiaddr: () => false }`. See `@optimystic/db-p2p`'s
    * `libp2p-node-base` for the underlying option.
+   *
+   * On the CONTROL node this gater is composed with the built-in membership
+   * admission gate (`membership-connection-gater.ts`): every hook supplied here
+   * is honored unchanged, and on inbound encrypted connections a deny from
+   * either this gater or the membership policy denies. Strand cohort nodes
+   * receive this gater as-is (their peers are legitimately cross-party).
    */
   connectionGater?: ConnectionGater;
   /**
@@ -190,8 +250,8 @@ export interface NetworkConfig {
    */
   controlCohort?: {
     /**
-     * Cap on the number of NON-authority siblings dialed per reconcile pass
-     * (backbone/authority members are always dialed and do not count). Defaults
+     * Cap on the number of NON-owner siblings dialed per reconcile pass
+     * (backbone/owner members are always dialed and do not count). Defaults
      * to {@link DEFAULT_CONTROL_COHORT_TARGET_DEGREE}.
      */
     targetDegree?: number;
@@ -236,6 +296,27 @@ export interface ControlNetworkConfig {
   schemaPath?: string;
 }
 
+/**
+ * Replication-breadth constants, both networks' cluster policies, and the strand
+ * resolver, re-exported so cadre embedders, the SQL plugin and the integration
+ * harness share one definition. Defined in `@serfab/quereus-plugin-sereus`
+ * because that package also creates libp2p nodes and cannot depend on this one.
+ * The control network's breadth is fixed ({@link CONTROL_REPLICATION_BREADTH},
+ * not configurable) and so is its consensus policy ({@link CONTROL_CLUSTER_POLICY}
+ * — notably the super-majority threshold, which it leaves at Optimystic's default
+ * by omission); the strand breadth defaults to
+ * {@link CadreNodeConfig.strandClusterSize} while its policy is the fixed
+ * {@link STRAND_CLUSTER_POLICY}.
+ */
+export {
+  MIN_CLUSTER_SIZE,
+  CONTROL_REPLICATION_BREADTH,
+  CONTROL_CLUSTER_POLICY,
+  DEFAULT_STRAND_CLUSTER_SIZE,
+  STRAND_CLUSTER_POLICY,
+  resolveStrandClusterSize
+} from '@serfab/quereus-plugin-sereus';
+
 /**
  * Main configuration for a CadreNode
  */
@@ -254,10 +335,10 @@ export interface CadreNodeConfig {
    * form). Mutually exclusive with {@link privateKey}. Absent ⇒ legacy behavior
    * (use `privateKey`, else libp2p generates an ephemeral key).
    *
-   * In the single-key reference model the authority signing key is *derived from*
-   * the node identity (see {@link CadreNode.getIdentityAuthorityKey}), so
-   * protecting the identity in a secure enclave protects the authority key too.
-   * A future separate-authority slot (`authorityKeyId`) is anticipated but not
+   * In the single-key reference model the owner signing key is *derived from*
+   * the node identity (see {@link CadreNode.getIdentityOwnerKey}), so
+   * protecting the identity in a secure enclave protects the owner key too.
+   * A future separate-owner slot (`ownerKeyId`) is anticipated but not
    * built here.
    */
   keyStore?: KeyStore;
@@ -280,6 +361,43 @@ export interface CadreNodeConfig {
   /** Network configuration */
   network?: NetworkConfig;
 
+  /**
+   * Number of nodes Optimystic is told a **strand** network's replication cluster
+   * should have, for every strand this node starts. The control network is not
+   * configurable — it always replicates to {@link CONTROL_REPLICATION_BREADTH}
+   * nodes, which is above any party's node count, because every member reads the
+   * whole control database and a member that misses a write may never learn the
+   * fact (see that constant for the full reasoning).
+   *
+   * Every node on the same strand should use the same value: the number bounds the
+   * cohort a member independently derives, and Optimystic's cluster-membership gate
+   * can reject a coordinator's smaller declared set as a downsize against a larger
+   * derived view.
+   *
+   * Frozen when the strand's libp2p node is created; a change takes effect on
+   * restart, not when cadre membership grows. Defaults to
+   * {@link DEFAULT_STRAND_CLUSTER_SIZE} (4 — the smallest breadth whose 0.75
+   * super-majority still commits with one holder offline); anything below
+   * {@link MIN_CLUSTER_SIZE} is rejected before a node is created. The cost of a
+   * small value is replication breadth and reliance on read repair, not commit
+   * correctness — but at 2 that read repair cannot converge, because a lone
+   * corroborator's stale answer is accepted as the cluster's truth.
+   */
+  strandClusterSize?: number;
+
+  /**
+   * Tuning for the strand peer-join block catch-up (see `strand-backfill.ts`):
+   * when a strand's libp2p node connects to a peer this runtime has not yet
+   * caught up, every block in the strand's own raw store is pushed to that peer,
+   * so a machine that joined the strand after blocks were committed still ends
+   * up physically holding them. Applies to every strand this node starts;
+   * strand-only — the control network has its own row-level re-issue queue
+   * (`drainPendingControlReplication`). Omit for the defaults
+   * (`DEFAULT_STRAND_BACKFILL`); `{ enabled: false }` restores the
+   * no-backfill behaviour.
+   */
+  strandBackfill?: StrandBackfillConfig;
+
   /** Hibernation configuration */
   hibernation?: HibernationConfig;
 
@@ -296,25 +414,106 @@ export interface CadreNodeConfig {
 
   /**
    * Node-wide default trust anchor for INBOUND control-network seeds. Forwarded
-   * into every SeedBootstrapService this node constructs (authority, receive-only
+   * into every SeedBootstrapService this node constructs (owner, receive-only
    * listener, and the temp service used by applySeed when no service exists), and
    * used as the service-level default the libp2p seed-protocol handler relies on
-   * (that path has no per-call override seam). Defaults to dbAnchoredTrustPolicy()
-   * inside SeedBootstrapService when unset — a cold-start node then rejects every
-   * seed. A per-call `applySeed(seed, { trustPolicy })` override still wins over
-   * this default for callers that hold out-of-band material (e.g. a pinned key
-   * from a CadreInvite).
+   * (that path has no per-call override seam). Defaults to anchoredTrustPolicy()
+   * inside SeedBootstrapService when unset — a node whose node-local trusted-owner
+   * anchor was never seeded then rejects every seed. A per-call
+   * `applySeed(seed, { trustPolicy })` override still wins over this default for
+   * callers that hold out-of-band material (e.g. a pinned key from a CadreInvite).
    */
   seedTrustPolicy?: SeedTrustPolicy;
 
   /**
-   * Platform push-delivery credentials (FCM and/or APNs). When present, the node
-   * can deliver strand-wake data messages to suspended mobile peers over the
-   * platform push channel — the server fan-out constructs a `PushNotifier` from
-   * this. Absent ⇒ no platform push (control-network push-wake only). Injected
-   * per node by `cadre-host`; `privateKey` fields are secrets and are never logged.
+   * Node-local trusted-owner anchor (see `trusted-owner-store.ts`): the
+   * NON-replicated, per-party record of owner keys established out of band —
+   * the anchor membership/seed trust can rest on, since the replicated
+   * `OwnerKey` table can be polluted by a stranger's self-genesis. Absent ⇒ an
+   * in-memory store is created at start() (ephemeral: anchored trust does not
+   * survive the process).
    */
-  push?: PushCredentials;
+  trustedOwners?: {
+    /**
+     * Injected store instance — e.g. a `FileTrustedOwnerStore` from the
+     * Node-only subpath `@serfab/cadre-core/trusted-owner-store-file`,
+     * persisted in the node's state directory (same injection/isolation pattern
+     * as {@link keyStore}). Its `partyId` must match `controlNetwork.partyId`;
+     * start() fails closed on a mismatch.
+     */
+    store?: TrustedOwnerStore;
+    /**
+     * Owner keys (base64url ed25519) established out of band and seeded into
+     * the store during start(): operator pins (e.g. cadre-cli
+     * `--pin-owner-key` / `CADRE_OWNER_KEYS`) or a `CadreInvite.ownerKeys`
+     * already known at config time. Seeding is idempotent across restarts.
+     */
+    pinnedKeys?: string[];
+    /**
+     * Provenance recorded for {@link pinnedKeys}. Default: 'operator'.
+     * ('genesis' is reserved for the node's own founding key, seeded
+     * internally by `initializeSeedBootstrap`.)
+     */
+    pinnedSource?: Exclude<TrustSource, 'genesis'>;
+  };
+
+  /**
+   * Node-local cold-start bootstrap-peer store (see `bootstrap-peer-store.ts`):
+   * the owner addresses an applied seed nominated, kept so
+   * `reconcileControlCohort`'s cold-start branch can keep retrying a node that
+   * was seeded but never managed to connect. Sibling of {@link trustedOwners} —
+   * same NON-replicated, per-party, injected-backend shape — but nothing here is
+   * trust-bearing: these are dial hints only, and every address is re-bound to
+   * its peer id before the dial. Absent ⇒ an in-memory store is created at
+   * start() (ephemeral: the retry set does not survive the process, and such a
+   * node is stranded permanently if it restarts before connecting).
+   *
+   * The Node CLI, the browser, and React Native all inject a durable backend
+   * today; only NativeScript stays ephemeral, tracked by the
+   * `ns-durable-node-local-stores` ticket (which covers the same gap for
+   * {@link trustedOwners}). A new platform needs no new store class: supply a
+   * `DurableSlot` for the platform's storage and inject
+   * `PersistentBootstrapPeerStore.open(slot, partyId)` /
+   * `PersistentTrustedOwnerStore.open(slot, partyId)`.
+   */
+  bootstrapPeers?: {
+    /**
+     * Injected store instance — e.g. a `FileBootstrapPeerStore` from the
+     * Node-only subpath `@serfab/cadre-core/bootstrap-peer-store-file`, persisted
+     * in the node's state directory (same injection/isolation pattern as
+     * {@link keyStore} / {@link trustedOwners}). Its `partyId` must match
+     * `controlNetwork.partyId`; start() fails closed on a mismatch.
+     */
+    store?: BootstrapPeerStore;
+  };
+
+  /**
+   * Platform push-delivery for suspended mobile peers. When present, the node's
+   * server fan-out can deliver strand-wake data messages over the platform push
+   * channel (FCM/APNs). Absent ⇒ no platform push (control-network push-wake only).
+   *
+   * The `notifier` is **injected**, not constructed here: a Node host builds it
+   * from `@serfab/cadre-core/push-node` (`createPushNotifier(credentials)`) and
+   * passes the instance, so the FCM/APNs modules (`node:crypto`/`node:http2`)
+   * stay out of the cross-platform core graph. Ownership transfers to the node on
+   * injection — `CadreNode.stop` closes the notifier (via `PushFanoutService`),
+   * releasing its APNs HTTP/2 session; a host must NOT also close an injected
+   * notifier itself. `cooldownMs`/`debounceMs` carry the fan-out anti-spam policy.
+   */
+  push?: {
+    /** The Node-constructed push router (see `@serfab/cadre-core/push-node`). */
+    notifier: PushNotifier;
+    /**
+     * Per-`(peer, strand)` minimum gap between push-wakes the fan-out emits.
+     * Default {@link DEFAULT_PUSH_COOLDOWN_MS} (5 min).
+     */
+    cooldownMs?: number;
+    /**
+     * Per-strand burst-coalescing window: a second trigger within it is dropped.
+     * Default {@link DEFAULT_PUSH_DEBOUNCE_MS} (10 s).
+     */
+    debounceMs?: number;
+  };
 }
 
 /**
@@ -347,6 +546,14 @@ export interface StrandInstance {
   status: StrandStatus;
   sAppInfo?: SAppInfo;
 
+  /**
+   * The lifecycle mode this instance's runtime was built with — `bootstrap`
+   * (purely local transactor) or `networked` (cluster transactor). Refreshed on
+   * every runtime (re)build, so a resume that shifts `bootstrap → networked`
+   * updates it. Read-only reporting; drives no behavior.
+   */
+  mode: StrandMode;
+
   /** The libp2p node for this strand (only when active/idle) */
   libp2pNode?: Libp2p;
 
@@ -458,7 +665,7 @@ export interface StrandConfig {
    * published the strand (the responder in formation, the creator in host/solo
    * paths; the same party that calls {@link CadreNode.publishStrand}). The founder
    * runs the one-time membership bootstrap at bring-up (writes `Strand.Header`, and
-   * for a closed strand the founding `Member`+`Authority`). A joiner leaves this
+   * for a closed strand the founding `Member`+`Manager`). A joiner leaves this
    * `false`/unset and writes nothing — it receives those rows via Optimystic sync.
    * Defaults to `false`.
    */
@@ -536,16 +743,6 @@ export interface FormStrandResult {
   memberPrivateKey?: string;
 }
 
-/**
- * Result of validating a strand formation request
- */
-export interface ValidateFormationResult {
-  /** Public key for validating this formation */
-  validationKey: string;
-  /** Signature over the formation approval */
-  validationSignature: string;
-}
-
 /**
  * Disclosure object provided during strand formation.
  * Contains identity and context information from the initiator.
@@ -636,13 +833,60 @@ export interface PeerAddressRecord {
   sig: string;
 }
 
+/**
+ * One `CadreControl.CadrePeer` row as read by `ControlDatabase.queryCadrePeers`:
+ * the addressing columns plus the persisted membership voucher.
+ *
+ * The voucher triple (`stampId`, `vouchOwner`, `vouchSig`) is what
+ * {@link CadreNode.listAuthorizedMembers} re-checks against the node-local
+ * trusted-owner anchor — it is null on a row written before the voucher columns
+ * existed, and all three must be present for the row to be authorizable. Named
+ * (rather than restated inline at each read site) so a future column addition
+ * cannot reach the query without the predicate seeing it.
+ */
+export interface CadrePeerRow {
+  /** libp2p peer ID (base58btc) — the row key. */
+  peerId: string;
+  /** Comma-joined dialable multiaddrs as stored, or null when unpublished. */
+  multiaddr: string | null;
+  /** Single-use anti-replay nonce the voucher signature is bound to. */
+  stampId: string | null;
+  /** ed25519 public key (base64url) of the owner that vouched this row. */
+  vouchOwner: string | null;
+  /** That owner's signature over `digest('CadreControl.CadrePeer', 'vouch', peerId, stampId)`, base64url. */
+  vouchSig: string | null;
+}
+
+/** The voucher-bearing subset of a {@link CadrePeerRow} — what the authorized-membership predicate reads. */
+export type CadrePeerVoucherFields = Pick<CadrePeerRow, 'peerId' | 'stampId' | 'vouchOwner' | 'vouchSig'>;
+
+/**
+ * One `CadreControl.Revocation` tombstone as read by
+ * `ControlDatabase.queryRevocations`: the identity triple plus the `ReissuedAt`
+ * counter an owner bumps (`ControlDatabase.reissueRevocations`) to re-write — and
+ * therefore re-broadcast — a tombstone that committed while the node was alone.
+ */
+export interface RevocationRow {
+  /** Which guarded table's stamp was retired. */
+  tableName: RevocableTable;
+  /** Primary key of the removed row (peer id / key / strand id). */
+  rowKey: string;
+  /** The retired single-use nonce — the tombstone's identity. */
+  stampId: string;
+  /** Monotonic re-issue counter; carries no semantics (see the schema comment). */
+  reissuedAt: number;
+}
+
 /**
  * Outcome of {@link CadreNode.registerSelf}, surfaced so callers (e.g. the CLI
- * `--authority` branch) can log what happened:
- * - `inserted` — the first authority-signed INSERT of this node's `CadrePeer` row.
+ * `--owner` branch) can log what happened:
+ * - `inserted` — the first owner-signed INSERT of this node's `CadrePeer` row.
  * - `refreshed` — a self-signed UPDATE of an existing row (heartbeat / addr change).
- * - `skipped` — nothing written (no self-signing key, or not yet a member with no
- *   authority service to self-insert).
+ *   Also reported when a first publish found its row seated by a concurrent
+ *   `authorizePeer` of this node's own id and fell through to the UPDATE — the write
+ *   really was an UPDATE, even though the caller's intent was a first publish.
+ * - `skipped` — nothing written (no self-signing key, not yet a member with no
+ *   owner service to self-insert, or the row was removed mid-publish).
  */
 export type SelfRegistrationOutcome = 'inserted' | 'refreshed' | 'skipped';
 
@@ -661,7 +905,7 @@ export interface ResolveOpts {
   /**
    * Pluggable trust gate, evaluated after signature + freshness pass. Defaults
    * to {@link currentMemberTrustPolicy} (any existing — therefore
-   * authority-vouched — CadrePeer member is trusted). Inject a stricter policy
+   * owner-vouched — CadrePeer member is trusted). Inject a stricter policy
    * (e.g. from `seed-signerkey-trust-policy`) to reject otherwise-valid records
    * before dialing.
    */
@@ -725,6 +969,21 @@ export interface DeviceTokenRecord {
   sig: string;
 }
 
+/**
+ * A stored `CadreControl.DeviceToken` row: the self-signed
+ * {@link DeviceTokenRecord} plus the row's single-use `StampId` nonce.
+ *
+ * The stamp is deliberately OUTSIDE `DeviceTokenRecord`: the peer's own `Sig`
+ * covers only (peerId, platform, token, updatedAt), while the stamp is bound by
+ * the OWNER's insert/delete approvals. Readers need it to drop a row whose stamp
+ * has been retired into `CadreControl.Revocation` (a token resurrected by an
+ * approval replay on a node that had not yet converged on the tombstone).
+ */
+export interface DeviceTokenRow extends DeviceTokenRecord {
+  /** Single-use authorization nonce; rotates on every (re)insert. */
+  stampId: string;
+}
+
 /**
  * Options for {@link CadreNode.resolveDeviceToken}.
  */
@@ -809,9 +1068,9 @@ export interface SeedPeer {
   peerId: string;
   /** Multiaddrs for connecting to this peer */
   multiaddrs: string[];
-  /** Whether this peer holds an authority key */
-  isAuthority: boolean;
-  /** ed25519 public key (base64url) — present on authority peers for signerKey verification */
+  /** Whether this peer holds an owner key */
+  isOwner: boolean;
+  /** ed25519 public key (base64url) — present on owner peers for signerKey verification */
   publicKey?: string;
 }
 
@@ -826,9 +1085,9 @@ export interface ControlNetworkSeed {
   partyId: string;
   /** Known peers in the cadre */
   peers: SeedPeer[];
-  /** Signature over the seed by an authority key */
+  /** Signature over the seed by an owner key */
   signature: string;
-  /** The authority key that signed this seed */
+  /** The owner key that signed this seed */
   signerKey: string;
 }
 
@@ -841,9 +1100,9 @@ export interface SeedMessage {
   partyId: string;
   /** Known peers in the cadre */
   peers: SeedPeer[];
-  /** Signature by an authority key */
+  /** Signature by an owner key */
   signature: string;
-  /** The authority key that signed this message */
+  /** The owner key that signed this message */
   signerKey: string;
 }
 
@@ -898,6 +1157,14 @@ export interface WakeAck {
 export interface StrandAddrRequest {
   /** The strand whose strand-network address the requester wants to seed from. */
   strandId: string;
+  /**
+   * The derived transport peerId the requester's own strand-`strandId` node
+   * runs as (see `strand-transport-key.ts`). Present → the responder records a
+   * delegate admission grant for it, so its own connection gate (and thus its
+   * circuit-relay server, when it runs one) admits that peerId; absent →
+   * today's behavior exactly. See `delegate-admission.ts` for the trust model.
+   */
+  delegatePeerId?: string;
 }
 
 /**
@@ -935,6 +1202,27 @@ export interface ApplySeedResult {
   peersAdded: number;
   /** Error message if not successful */
   error?: string;
+  /**
+   * Owner-flagged seed peers this apply attempted to dial. Zero when the seed
+   * carried no owner peer with an address, or when the seed was rejected before
+   * the dial loop ran.
+   */
+  ownerDialsAttempted: number;
+  /**
+   * How many of those dials threw. `ownerDialsAttempted > 0 && ownerDialsFailed
+   * === ownerDialsAttempted` means "seeded but stranded": the seed itself was
+   * accepted (`success: true`) but no owner could be reached, so this node has
+   * no connection to bootstrap its control database from. The node retries those
+   * addresses on every control-cohort reconcile pass (see
+   * `CadreNode.dialColdStartBootstrap`), so this is a signal, not a fatal error.
+   *
+   * Zero failures is NOT proof of a live connection: the receiving node's
+   * membership gate denies AFTER the dialer's upgrade completes (see
+   * `createMembershipConnectionGater`), so a dial can resolve and then be torn
+   * down. Treat a non-zero value as certain failure and zero as "no failure
+   * observed".
+   */
+  ownerDialsFailed: number;
 }
 
 // ============================================================================
@@ -953,15 +1241,18 @@ export type NodeTopology = 'public' | 'nat';
 export interface CadreInvite {
   /** Party ID of the cadre */
   partyId: string;
-  /** Multiaddrs to dial the authority */
-  authorityAddrs: string[];
+  /** Multiaddrs to dial the owner */
+  ownerAddrs: string[];
   /**
-   * Authority ed25519 public keys (base64url) of the cadre, carried out-of-band
-   * so a cold-start invitee can pin the trusted authority set before applying
+   * Owner ed25519 public keys (base64url) of the cadre, carried out-of-band
+   * so a cold-start invitee can pin the trusted owner set before applying
    * any seed (the seed itself cannot vouch for its own signer). Populated by
-   * `createInvite` from the issuer's `AuthorityKey` table.
+   * `createInvite` from the issuer's OWN node-local trusted-owner anchor —
+   * not its replicated `OwnerKey` table, because the invitee anchors whatever
+   * arrives here and a stranger's genesis-inserted key must not ride an
+   * otherwise-legitimate invite into a fresh node's anchor.
    */
-  authorityKeys?: string[];
+  ownerKeys?: string[];
   /** Optional invite token for validation */
   token?: string;
   /** Timestamp when invite was created */

package/dist/authority-key.d.ts

@@ -1,41 +0,0 @@
-import type { PrivateKey } from '@libp2p/interface';
-/**
- * A household authority keypair expressed in the base64url Ed25519 form that
- * `@optimystic/quereus-plugin-crypto` (`sign`/`verify`/`getPublicKey`) consumes.
- */
-export interface AuthorityKeyPair {
-    /** 32-byte Ed25519 seed, base64url-encoded — the crypto-plugin private key. */
-    privateKeyB64: string;
-    /** 32-byte Ed25519 public key, base64url-encoded. */
-    publicKeyB64: string;
-}
-/**
- * Bridge a libp2p Ed25519 private key into the base64url keypair used by the
- * control-database authority constraints.
- *
- * libp2p stores an Ed25519 private key as 64 raw bytes: the first 32 are the
- * seed (the actual scalar source), the last 32 are the public key — see
- * `@libp2p/crypto`'s `Ed25519PrivateKey`. `@optimystic/quereus-plugin-crypto`
- * (via `@noble/curves`) treats the 32-byte seed *as* the private key and
- * derives the public key from it with standard Ed25519. The two derivations
- * agree, so the node's peer identity and its authority key are one keypair:
- * `getPublicKey(privateKeyB64)` === `publicKeyB64`.
- *
- * @param privateKey - The node's libp2p Ed25519 private key.
- * @returns The base64url seed/public-key pair for authority operations.
- * @throws If the key is not Ed25519 or the raw bytes aren't the expected length.
- */
-export declare function authorityKeyFromLibp2p(privateKey: PrivateKey): AuthorityKeyPair;
-/**
- * Derive the base64url Ed25519 public key from a base64url 32-byte private seed
- * — the same derivation the seed-bootstrap signer uses internally
- * (`SeedBootstrapService` constructor). Use this to enroll a standalone
- * (non-libp2p) authority key into the control DB via
- * `ControlDatabase.ensureAuthorityKey` before minting an invite, when the
- * authority key is *not* the node's peer identity (so `authorityKeyFromLibp2p`,
- * which needs a libp2p key object, does not apply).
- *
- * @param privateKeyB64 - The base64url-encoded 32-byte Ed25519 seed.
- * @returns The base64url-encoded Ed25519 public key.
- */
-export declare function authorityPublicKeyFromPrivate(privateKeyB64: string): string;

package/dist/authority-key.js

@@ -1,52 +0,0 @@
-import { toString as uint8ArrayToString } from 'uint8arrays';
-import { getPublicKey } from '@optimystic/quereus-plugin-crypto';
-/**
- * Bridge a libp2p Ed25519 private key into the base64url keypair used by the
- * control-database authority constraints.
- *
- * libp2p stores an Ed25519 private key as 64 raw bytes: the first 32 are the
- * seed (the actual scalar source), the last 32 are the public key — see
- * `@libp2p/crypto`'s `Ed25519PrivateKey`. `@optimystic/quereus-plugin-crypto`
- * (via `@noble/curves`) treats the 32-byte seed *as* the private key and
- * derives the public key from it with standard Ed25519. The two derivations
- * agree, so the node's peer identity and its authority key are one keypair:
- * `getPublicKey(privateKeyB64)` === `publicKeyB64`.
- *
- * @param privateKey - The node's libp2p Ed25519 private key.
- * @returns The base64url seed/public-key pair for authority operations.
- * @throws If the key is not Ed25519 or the raw bytes aren't the expected length.
- */
-export function authorityKeyFromLibp2p(privateKey) {
-    if (privateKey.type !== 'Ed25519') {
-        throw new Error(`authorityKeyFromLibp2p requires an Ed25519 key, got ${privateKey.type}`);
-    }
-    const raw = privateKey.raw;
-    if (raw.length !== 64) {
-        throw new Error(`Expected a 64-byte Ed25519 raw private key (seed||public), got ${raw.length} bytes`);
-    }
-    const seed = raw.subarray(0, 32);
-    const publicKeyRaw = privateKey.publicKey.raw;
-    if (publicKeyRaw.length !== 32) {
-        throw new Error(`Expected a 32-byte Ed25519 public key, got ${publicKeyRaw.length} bytes`);
-    }
-    return {
-        privateKeyB64: uint8ArrayToString(seed, 'base64url'),
-        publicKeyB64: uint8ArrayToString(publicKeyRaw, 'base64url'),
-    };
-}
-/**
- * Derive the base64url Ed25519 public key from a base64url 32-byte private seed
- * — the same derivation the seed-bootstrap signer uses internally
- * (`SeedBootstrapService` constructor). Use this to enroll a standalone
- * (non-libp2p) authority key into the control DB via
- * `ControlDatabase.ensureAuthorityKey` before minting an invite, when the
- * authority key is *not* the node's peer identity (so `authorityKeyFromLibp2p`,
- * which needs a libp2p key object, does not apply).
- *
- * @param privateKeyB64 - The base64url-encoded 32-byte Ed25519 seed.
- * @returns The base64url-encoded Ed25519 public key.
- */
-export function authorityPublicKeyFromPrivate(privateKeyB64) {
-    return getPublicKey(privateKeyB64, 'ed25519', 'base64url', 'base64url');
-}
-//# sourceMappingURL=authority-key.js.map

package/dist/authority-key.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"authority-key.js","sourceRoot":"","sources":["../src/authority-key.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AAcjE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,sBAAsB,CAAC,UAAsB;IAC3D,IAAI,UAAU,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CAAC,uDAAuD,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC;IAC5F,CAAC;IAED,MAAM,GAAG,GAAG,UAAU,CAAC,GAAG,CAAC;IAC3B,IAAI,GAAG,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,kEAAkE,GAAG,CAAC,MAAM,QAAQ,CAAC,CAAC;IACxG,CAAC;IAED,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACjC,MAAM,YAAY,GAAG,UAAU,CAAC,SAAS,CAAC,GAAG,CAAC;IAC9C,IAAI,YAAY,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,8CAA8C,YAAY,CAAC,MAAM,QAAQ,CAAC,CAAC;IAC7F,CAAC;IAED,OAAO;QACL,aAAa,EAAE,kBAAkB,CAAC,IAAI,EAAE,WAAW,CAAC;QACpD,YAAY,EAAE,kBAAkB,CAAC,YAAY,EAAE,WAAW,CAAC;KAC5D,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,6BAA6B,CAAC,aAAqB;IACjE,OAAO,YAAY,CAAC,aAAa,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,CAAW,CAAC;AACpF,CAAC"}