@serfab/cadre-core 0.8.1 → 0.9.0

package/dist/seed-bootstrap.d.ts

@@ -18,10 +18,10 @@ export declare function decodeLengthPrefixedFrame(data: Uint8Array, maxLength?:
  *
  * 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
+ * base64url form matches the `OwnerKey.Key` representation (and
+ * `ed25519KeyPairFromLibp2p().publicKeyB64`). Returns null for a non-Ed25519
  * id, a missing embedded key, or any parse failure — callers treat null as
- * "not an authority" rather than throwing.
+ * "not an owner" rather than throwing.
  */
 export declare function ed25519PublicKeyB64FromPeerId(peerId: string): string | null;
 /**
@@ -40,10 +40,10 @@ export declare function canonicalSeedPayload(seed: Pick<ControlNetworkSeed, 'par
 export interface SeedBootstrapConfig {
     /** Party ID for this cadre */
     partyId: string;
-    /** Authority private key for signing seeds and peer authorizations (base64url) */
-    authorityPrivateKey?: string;
-    /** Authority public key (base64url) - derived from private key if not provided */
-    authorityPublicKey?: string;
+    /** Owner private key for signing seeds and peer authorizations (base64url) */
+    ownerPrivateKey?: string;
+    /** Owner public key (base64url) - derived from private key if not provided */
+    ownerPublicKey?: string;
     /**
      * Optional async resolver returning the multiaddrs to embed in invites.
      * When unset, `libp2pNode.getMultiaddrs()` is used. Hosts behind NAT supply
@@ -53,9 +53,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 authority
+     * `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 `AuthorityKey` table. An enrollment
+     * rejects any signer not already in the `OwnerKey` table. An enrollment
      * caller can pass a per-seed override to `applySeed` instead.
      *
      * A `CadreNode` forwards its node-wide `CadreNodeConfig.seedTrustPolicy` here
@@ -98,7 +98,7 @@ export declare class SeedBootstrapService {
     private readonly config;
     private libp2pNode;
     private controlDatabase;
-    private readonly authorityPublicKey;
+    private readonly ownerPublicKey;
     private readonly trustPolicy;
     private readonly seedReadTimeoutMs;
     private readonly maxConcurrentSeeds;
@@ -112,12 +112,12 @@ export declare class SeedBootstrapService {
      */
     setEventCallbacks(callbacks: SeedEventCallbacks): void;
     /**
-     * Whether this service holds an authority private key, i.e. can produce the
-     * authority signatures that gate `CadrePeer` / `DeviceToken` inserts, deletes,
+     * Whether this service holds an owner private key, i.e. can produce the
+     * owner signatures that gate `CadrePeer` / `DeviceToken` inserts, deletes,
      * and re-authorizations. A seed-listener-only service (`enableSeedListener`,
-     * no 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.
+     * no owner key) returns false: it can receive/apply seeds but cannot author
+     * or re-issue owner writes. Used by the write-while-alone re-replication
+     * drain to skip owner work on a non-owner node.
      */
     canAuthorize(): boolean;
     /**
@@ -137,73 +137,92 @@ export declare class SeedBootstrapService {
     }): void;
     /**
      * Authorize a new peer to join the cadre.
-     * Signs the peer ID with the authority key and inserts into CadrePeer table.
+     * Signs the peer ID with the owner key and inserts into CadrePeer table.
      *
-     * The authority vouches the `PublicKey <-> PeerId` binding: rather than trust a
+     * The owner vouches the `PublicKey <-> PeerId` binding: rather than trust a
      * caller-supplied key, the binding is enforced by construction — `PublicKey` is
      * DERIVED from the (Ed25519) `peerId`. A non-Ed25519 peer id yields a null
      * `PublicKey`, and such a row can never be self-updated (it has no key to
      * verify against), which is correct. The row is inserted with a fresh
-     * `UpdatedAt` but no self-signature (`Sig` null) — the authority cannot produce
+     * `UpdatedAt` but no self-signature (`Sig` null) — the owner cannot produce
      * the peer's self-signature, so the peer must self-publish (see
      * {@link CadreNode.registerSelf}) before the row resolves.
      */
     authorizePeer(options: AuthorizePeerOptions): Promise<void>;
     /**
-     * Authority-signed INSERT of this node's OWN self-signed address record.
+     * Owner-signed INSERT of this node's OWN self-signed address record.
      *
      * Used by {@link CadreNode.registerSelf} when the node is not yet a member and
-     * is its own authority (it holds the authority key): the row is authority-signed
+     * 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 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.
+     * Shared owner-signed `CadrePeer` INSERT. Mints a fresh single-use `StampId`
+     * and signs the voucher digest `digest(peerId, stampId)` ({@link cadrePeerVoucherDigest})
+     * with the owner key (satisfying `AuthorizedInsert`), then writes the full record
+     * row with the vouching (owner, signature) persisted into VouchOwner/VouchSig.
+     * The owner signature does NOT cover the address columns — those are vouched only
+     * as far as the owner asserts them, and a peer's own `Sig` (when present) is what
+     * makes the row resolvable.
      */
     private insertCadrePeerRow;
     /**
-     * Authority-signed INSERT of a peer's OWN self-signed `DeviceToken` row.
+     * Owner-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
+     * 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 authority signature covers only the
+     * own self-`Sig` over the token payload. The owner signature covers only the
      * PeerId — it does NOT vouch the token contents; the peer's `Sig` (verified at
      * resolve time against the bound `CadrePeer.PublicKey`) is what makes the row
      * resolvable. Used by {@link CadreNode.registerDeviceToken} for the first publish
-     * when the node is its own authority.
+     * when the node is its own owner.
      */
     insertSelfDeviceToken(record: DeviceTokenRecord): Promise<void>;
     /**
-     * Authority-signed DELETE of a peer's `DeviceToken` row (logout / token
+     * Owner-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.
+     * AND delete on an owner signature over `digest(old.PeerId)`, so — like
+     * {@link removePeer} for `CadrePeer` — clearing a token requires the owner key.
      */
     deleteDeviceToken(peerId: string): Promise<void>;
     /**
-     * Sign a peer ID with the authority key for a `CadrePeer` / `DeviceToken`
+     * 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 authority key is set.
+     * verifier checks the exact same construction. Throws if no owner key is set.
      */
     private signPeerAuthorization;
     /**
-     * Remove a peer from the cadre by authority signature.
+     * Return the configured owner private key, or throw if none is set. The single
+     * precondition gate for every owner-signed write. {@link removePeer} /
+     * {@link reauthorizePeer} read the row's `StampId` from the DB BEFORE they sign, so
+     * they call this up front — otherwise a keyless service would either surface the
+     * wrong "Control database not initialized" error or, worse, silently no-op when the
+     * target row is absent (the early `stampId === null` return) instead of rejecting.
+     */
+    private requireOwnerPrivateKey;
+    /**
+     * Sign a base64url digest with the owner key (ed25519). The single place the
+     * owner private key is applied; callers pass the canonical digest for the specific
+     * action ({@link cadrePeerVoucherDigest} / {@link cadrePeerRemoveDigest} /
+     * {@link peerAuthorizationDigest}). Throws if no owner key is set.
+     */
+    private signDigest;
+    /**
+     * Remove a peer from the cadre by owner 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.
+     * 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.
      */
     removePeer(peerId: string): Promise<void>;
     /**
-     * Authority "re-touch" of an existing `CadrePeer` membership row: bump
-     * `UpdatedAt` under the authority branch of `CadrePeer.AuthorizedUpdate` (a
+     * 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.
      *
@@ -220,13 +239,13 @@ export declare class SeedBootstrapService {
      *
      * @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
+     * @throws if no owner private key is configured (a non-owner cannot
      *   re-sign another peer's row) or the control database is not initialized.
      */
     reauthorizePeer(peerId: string, updatedAt: number): Promise<void>;
     /**
      * Create a seed from the current control network state.
-     * The seed contains peer information and is signed by an authority.
+     * The seed contains peer information and is signed by an owner.
      */
     createSeed(): Promise<ControlNetworkSeed>;
     /**
@@ -234,9 +253,9 @@ 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
-     * `AuthorityKey` table (DB-anchored), optionally augmented by pinned keys or
+     * `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 authority
+     * self-asserting seed — one that merely lists its own signer as an owner
      * peer — no longer passes.
      *
      * @param seed - The seed to apply (already transport-decoded).
@@ -271,12 +290,12 @@ export declare class SeedBootstrapService {
     /**
      * Query peers from the control database.
      *
-     * Authority identity is sourced from the `AuthorityKey` table, not from the
+     * Owner identity is sourced from the `OwnerKey` table, not from the
      * transport peer ID. An Ed25519 libp2p PeerId embeds its public key (identity
      * multihash), so each peer's ed25519 key is derivable from its `PeerId`; a
-     * peer is an 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`.
+     * peer is an owner iff that derived key is in the `OwnerKey` set.
+     * This makes any owner node markable — not just the local one — and ties
+     * `isOwner` to the control table rather than to `peerId === self`.
      */
     private queryPeers;
     /**
@@ -357,11 +376,11 @@ export declare class SeedBootstrapService {
      */
     decodeInvite(encoded: string): CadreInvite;
     /**
-     * Dial an authority from an invite.
-     * Use this on a phone after receiving an invite to connect to the authority.
+     * Dial an owner from an invite.
+     * Use this on a phone after receiving an invite to connect to the owner.
      *
      * @param invite - The invite received out-of-band
-     * @returns Connection to the authority
+     * @returns Connection to the owner
      */
     dialInvite(invite: CadreInvite): Promise<void>;
 }