@serfab/cadre-core 1.16.0 → 1.17.0

package/dist/seed-bootstrap.js

@@ -1,16 +1,18 @@
 import debug from 'debug';
 import { toString as uint8ArrayToString, fromString as uint8ArrayFromString } from 'uint8arrays';
-import { digest, sign, verify, getPublicKey } from '@optimystic/quereus-plugin-crypto';
+import { digest, verify } from '@optimystic/quereus-plugin-crypto';
 import { multiaddr } from '@multiformats/multiaddr';
 import { peerIdFromString } from '@libp2p/peer-id';
 import { withDeadline, exchangeFrame, readStreamToEnd, replyAndClose } from './control-stream.js';
 import { dialPeerAddrs, SelfRelayOnlyError, PeerUnreachableError, DEFAULT_PEER_DIAL_BUDGET, withTrailingPeerId, } from './peer-dial.js';
 import { relayedRequestBudgetMs } from './link-budget.js';
-import { generateStampId } from './control-database.js';
+import { generateStampId, ownerKeyLabel } from './control-database.js';
 import { canonicalJson } from './canonical-json.js';
 import { deviceTokenAddDigest } from './peer-authorization.js';
 import { ed25519PublicKeyB64FromPeerId } from './ed25519-key.js';
 import { anchoredTrustPolicy, } from './seed-trust-policy.js';
+import { withinOwnerApproval } from './owner-signer.js';
+import { namedOwnerKey } from './owner-keys.js';
 const log = debug('sereus:cadre:seed-bootstrap');
 /** Protocol ID for seed delivery */
 export const SEED_PROTOCOL = '/sereus/seed/1.0.0';
@@ -70,8 +72,15 @@ export function canonicalSeedPayload(seed) {
 export function seedDigest(seed) {
     return digest([canonicalSeedPayload(seed)], 'sha256', 'base64url');
 }
+/** Add `relayAddr` to the entry for `selfPeerId` in `peers`, when that entry exists and lacks it. */
+function addSelfRelayAddr(peers, selfPeerId, relayAddr) {
+    const self = peers.find((peer) => peer.peerId === selfPeerId);
+    if (self && !self.multiaddrs.includes(relayAddr)) {
+        self.multiaddrs.push(relayAddr);
+    }
+}
 /**
- * An {@link ApplySeedResult} for a seed refused before the owner-dial loop ran,
+ * An {@link ApplySeedResult} for a seed refused before the dial loop ran,
  * so the dial counters read zero rather than being absent.
  */
 function seedRejected(error, code) {
@@ -80,8 +89,8 @@ function seedRejected(error, code) {
         peersAdded: 0,
         error,
         ...(code !== undefined ? { code } : {}),
-        ownerDialsAttempted: 0,
-        ownerDialsFailed: 0,
+        preferredDialsAttempted: 0,
+        preferredDialsFailed: 0,
     };
 }
 /**
@@ -162,13 +171,6 @@ export class SeedBootstrapService {
         this.maxConcurrentSeeds = config.maxConcurrentSeeds ?? DEFAULT_MAX_CONCURRENT_SEEDS;
         this.seedDeliverTimeoutMs = config.seedDeliverTimeoutMs ?? relayedRequestBudgetMs(config.linkRoundTripMs);
         this.dialBudget = config.dialBudget ?? DEFAULT_PEER_DIAL_BUDGET;
-        // Derive public key from private key if not provided
-        if (config.ownerPrivateKey && !config.ownerPublicKey) {
-            this.ownerPublicKey = getPublicKey(config.ownerPrivateKey, 'ed25519', 'base64url', 'base64url');
-        }
-        else {
-            this.ownerPublicKey = config.ownerPublicKey ?? null;
-        }
         log('SeedBootstrapService created for party: %s', config.partyId);
     }
     /**
@@ -179,22 +181,25 @@ export class SeedBootstrapService {
         this.eventCallbacks = callbacks;
     }
     /**
-     * Whether this service holds an owner private key, i.e. can produce the
-     * owner signatures that gate `CadrePeer` / `DeviceToken` inserts, deletes,
-     * and re-authorizations. A seed-listener-only service (`enableSeedListener`,
-     * no owner key) returns false: it can receive/apply seeds but cannot author
-     * or re-issue owner writes. Used by the write-while-alone re-replication
-     * drain to skip owner work on a non-owner node.
+     * Whether this service holds an owner signer, i.e. can produce the owner signatures that
+     * gate `CadrePeer` / `DeviceToken` inserts, deletes, and re-authorizations. A
+     * seed-listener-only service (`enableSeedListener`, no signer) 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() {
-        return !!this.config.ownerPrivateKey;
+        return this.config.ownerSigner !== undefined;
+    }
+    /** The owner signer this service was built with, or null for a listener-only service. */
+    get ownerSigner() {
+        return this.config.ownerSigner ?? null;
     }
     /**
      * 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
+     * (`CadreNode.useOwnerSigner`, `enableSeedListener`) own that handler and leave
      * it on. The throwaway temp service CadreNode builds in `applySeed` passes
      * `false`: it only needs the stored `libp2pNode` / `controlDatabase` for
      * dialing and known-key lookup, and must NOT bind a discarded closure to the
@@ -226,8 +231,11 @@ export class SeedBootstrapService {
      * `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.
+     *
+     * @param sign - The signature function of an owner approval the caller already holds, so a
+     *   multi-step action asks once; omitted, this write asks for its own approval.
      */
-    async authorizePeer(options) {
+    async authorizePeer(options, sign) {
         const { peerId, multiaddrs } = options;
         log('Authorizing peer: %s', peerId);
         // CadrePeer.Multiaddr stores a comma-joined list; use '' when no addrs provided.
@@ -239,7 +247,7 @@ export class SeedBootstrapService {
             updatedAt: Date.now(),
             sig: null,
             profile: null,
-        });
+        }, `Add the machine ${peerId} to the cadre`, sign);
         log('Peer %s authorized successfully', peerId);
     }
     /**
@@ -255,7 +263,7 @@ export class SeedBootstrapService {
      *   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.
      */
-    async insertSelfPeerRecord(record) {
+    async insertSelfPeerRecord(record, sign) {
         return await this.insertCadrePeerRow({
             peerId: record.peerId,
             publicKey: record.publicKey,
@@ -263,30 +271,27 @@ export class SeedBootstrapService {
             updatedAt: record.updatedAt,
             sig: record.sig,
             profile: record.profile,
-        });
+        }, 'Publish this machine\'s own address record', sign);
     }
     /**
-     * Shared owner-signed `CadrePeer` INSERT — the row fields and the owner-key
+     * Shared owner-signed `CadrePeer` INSERT — the row fields and the owner-signer
      * 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).
+     * The DB check precedes the owner-signer check here, matching the order this method has
+     * always surfaced them.
      *
      * @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.
      */
-    async insertCadrePeerRow(row) {
-        if (!this.controlDatabase) {
-            throw new Error('Control database not initialized');
-        }
-        const ownerKey = this.requireOwnerPublicKey();
-        return await this.controlDatabase.insertCadrePeer(row, ownerKey, message => this.signMessageBytes(message));
+    async insertCadrePeerRow(row, action, sign) {
+        const controlDatabase = this.requireControlDatabase();
+        const ownerKey = this.requireOwnerSigner().publicKey;
+        return await this.withOwnerSign(action, sign, (approved) => controlDatabase.insertCadrePeer(row, ownerKey, approved));
     }
     /**
      * Owner-signed INSERT of a peer's OWN self-signed `DeviceToken` row.
@@ -305,17 +310,17 @@ export class SeedBootstrapService {
      * fresh signature — unaffected by the cleared row's retired stamp
      * (`DeviceToken.NotRevoked`).
      */
-    async insertSelfDeviceToken(record) {
+    async insertSelfDeviceToken(record, sign) {
+        const ownerKey = this.requireOwnerSigner().publicKey;
+        const controlDatabase = this.requireControlDatabase();
         const stampId = generateStampId(record.peerId);
-        const signature = this.signDigest(deviceTokenAddDigest(this.config.partyId, { ...record, stampId }));
-        if (!this.controlDatabase) {
-            throw new Error('Control database not initialized');
-        }
-        await this.controlDatabase.execWrite(`
+        const digestBytes = uint8ArrayFromString(deviceTokenAddDigest(this.config.partyId, { ...record, stampId }), 'base64url');
+        const signature = await this.withOwnerSign('Publish this machine\'s push token', sign, (approved) => approved(digestBytes));
+        await controlDatabase.execWrite(`
       insert into CadreControl.DeviceToken (PeerId, Platform, Token, UpdatedAt, Sig, StampId)
         with context OwnerKey = ?, Signature = ?
         values (?, ?, ?, ?, ?, ?)
-    `, [this.ownerPublicKey, signature, record.peerId, record.platform, record.token, record.updatedAt, record.sig, stampId], 'device-token-insert');
+    `, [ownerKey, signature, record.peerId, record.platform, record.token, record.updatedAt, record.sig, stampId], 'device-token-insert');
         log('Device token inserted (owner-signed): %s', record.peerId);
     }
     /**
@@ -336,66 +341,44 @@ export class SeedBootstrapService {
      * 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
+     * owner-signer precondition; a no-op on an already-absent row is the shared body's
      * behavior, and unlike {@link removePeer} nothing here rides on it.
      */
-    async deleteDeviceToken(peerId) {
-        // Fail fast on a keyless service BEFORE the DB read, so a non-owner gets the
-        // owner-key error rather than a silent no-op on an absent row.
-        const ownerKey = this.requireOwnerPublicKey();
-        if (!this.controlDatabase) {
-            throw new Error('Control database not initialized');
-        }
-        await this.controlDatabase.deleteDeviceToken(peerId, ownerKey, message => this.signMessageBytes(message));
+    async deleteDeviceToken(peerId, sign) {
+        // Fail fast on a signerless service BEFORE the DB read, so a non-owner gets the
+        // owner-signer error rather than a silent no-op on an absent row.
+        const ownerKey = this.requireOwnerSigner().publicKey;
+        const controlDatabase = this.requireControlDatabase();
+        await this.withOwnerSign(`Clear the push token of ${peerId}`, sign, (approved) => controlDatabase.deleteDeviceToken(peerId, ownerKey, approved));
     }
     /**
-     * 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.
+     * Return the configured owner signer, 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
+     * signerless 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.
      */
-    requireOwnerPrivateKey() {
-        if (!this.config.ownerPrivateKey) {
-            throw new Error('Owner private key required to authorize peers');
+    requireOwnerSigner() {
+        if (!this.config.ownerSigner) {
+            throw new Error('Owner signer required to authorize peers');
         }
-        return this.config.ownerPrivateKey;
+        return this.config.ownerSigner;
     }
-    /**
-     * 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.
-     */
-    requireOwnerPublicKey() {
-        this.requireOwnerPrivateKey();
-        if (!this.ownerPublicKey) {
-            throw new Error('Owner public key required to authorize peers');
+    /** The control database {@link initialize} attached, or a throw. */
+    requireControlDatabase() {
+        if (!this.controlDatabase) {
+            throw new Error('Control database not initialized');
         }
-        return this.ownerPublicKey;
-    }
-    /**
-     * Sign a base64url digest with the owner key (ed25519). The single place the
-     * 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.
-     */
-    signDigest(digestB64url) {
-        return sign(digestB64url, this.requireOwnerPrivateKey(), 'ed25519', 'base64url', 'base64url', 'base64url');
+        return this.controlDatabase;
     }
     /**
-     * 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".
+     * Run `body` with an owner signature function: the caller's `sign` when it passes one (a
+     * `CadreNode` action already inside its approval), otherwise one approval of this service's
+     * signer for `action`, the plain-words description a prompting signer shows.
      */
-    signMessageBytes(message) {
-        return this.signDigest(uint8ArrayToString(message, 'base64url'));
+    async withOwnerSign(action, sign, body) {
+        return await withinOwnerApproval(this.requireOwnerSigner(), { partyId: this.config.partyId, action }, sign, body);
     }
     /**
      * Remove a peer from the cadre by owner signature.
@@ -419,16 +402,14 @@ export class SeedBootstrapService {
      * 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).
+     * owner-signer precondition and the absent-row gate the notify depends on (below).
      */
-    async removePeer(peerId) {
-        // Fail fast on a keyless service BEFORE any DB read: a non-owner cannot sign the
-        // remove digest, and this precedence (owner key, then control DB) is what the
+    async removePeer(peerId, sign) {
+        // Fail fast on a signerless service BEFORE any DB read: a non-owner cannot sign the
+        // remove digest, and this precedence (owner signer, then control DB) is what the
         // unit contract asserts.
-        const ownerKey = this.requireOwnerPublicKey();
-        if (!this.controlDatabase) {
-            throw new Error('Control database not initialized');
-        }
+        const ownerKey = this.requireOwnerSigner().publicKey;
+        const controlDatabase = this.requireControlDatabase();
         // This absent-row gate must stay OUTSIDE the delete, even though the delete repeats it
         // internally: deleteCadrePeer's membership notify fires whenever its body resolves,
         // with no idea whether the body wrote anything, so delegating an absent peer would
@@ -436,74 +417,69 @@ export class SeedBootstrapService {
         // NOTE: deleteCadrePeer re-reads the StampId, so a peer removed by another writer
         // between the two reads no-ops silently yet still notifies. Narrow concurrent-removal
         // window only — the common "already absent" case is caught here.
-        const stampId = await this.controlDatabase.queryCadrePeerStampId(peerId);
+        const stampId = await controlDatabase.queryCadrePeerStampId(peerId);
         if (stampId === null) {
             log('removePeer: no CadrePeer row for %s (already absent)', peerId);
             return;
         }
         log('Removing peer: %s', peerId);
-        await this.controlDatabase.deleteCadrePeer(peerId, ownerKey, message => this.signMessageBytes(message));
+        await this.withOwnerSign(`Remove the machine ${peerId} from the cadre`, sign, (approved) => controlDatabase.deleteCadrePeer(peerId, ownerKey, approved));
         log('Peer %s removed successfully (stamp retired)', peerId);
     }
     /**
-     * Seat `ownerPublicKey` as a further owner, signed by this service's owner key. The
+     * Seat `ownerPublicKey` as a further owner, signed by this service's owner signer. The
      * liveness check, the stamp, the signature and the membership notify are
-     * {@link ControlDatabase.insertOwnerKeyVouched}'s; what stays here is the owner-key
+     * {@link ControlDatabase.insertOwnerKeyVouched}'s; what stays here is the owner-signer
      * precondition, checked before any read (see {@link removePeer}).
      *
+     * @param label - the user's name for the key, bound into the signature
+     *   ({@link ControlDatabase.insertOwnerKey} has the rule).
      * @returns `true` when the row was seated, `false` when the key is already a live owner.
      */
-    async addOwner(ownerPublicKey) {
-        const ownerKey = this.requireOwnerPublicKey();
-        if (!this.controlDatabase) {
-            throw new Error('Control database not initialized');
-        }
-        return await this.controlDatabase.insertOwnerKeyVouched(ownerPublicKey, ownerKey, message => this.signMessageBytes(message));
+    async addOwner(ownerPublicKey, label, sign) {
+        const ownerKey = this.requireOwnerSigner().publicKey;
+        const controlDatabase = this.requireControlDatabase();
+        // Checked before the approval opens, so a label the row would refuse never prompts the user.
+        const storedLabel = ownerKeyLabel(label);
+        return await this.withOwnerSign(`Add owner key ${namedOwnerKey(ownerPublicKey, storedLabel)}`, sign, (approved) => controlDatabase.insertOwnerKeyVouched(ownerPublicKey, ownerKey, approved, storedLabel));
     }
     /**
-     * Remove `ownerPublicKey` from the owners, signed by this service's owner key: the delete
+     * Remove `ownerPublicKey` from the owners, signed by this service's owner signer: the delete
      * and its `Revocation` tombstone in one transaction. The by-name refusals (self-removal,
      * the last owner), the digests and the membership notify are
-     * {@link ControlDatabase.deleteOwnerKey}'s; what stays here is the owner-key precondition,
+     * {@link ControlDatabase.deleteOwnerKey}'s; what stays here is the owner-signer precondition,
      * checked before any read (see {@link removePeer}).
      *
      * @returns `true` when the row was removed, `false` when the key is not a live owner here.
      */
-    async removeOwner(ownerPublicKey) {
-        const ownerKey = this.requireOwnerPublicKey();
-        if (!this.controlDatabase) {
-            throw new Error('Control database not initialized');
-        }
-        return await this.controlDatabase.deleteOwnerKey(ownerPublicKey, ownerKey, message => this.signMessageBytes(message));
+    async removeOwner(ownerPublicKey, sign) {
+        const ownerKey = this.requireOwnerSigner().publicKey;
+        const controlDatabase = this.requireControlDatabase();
+        return await this.withOwnerSign(`Remove owner key ${ownerPublicKey}`, sign, (approved) => controlDatabase.deleteOwnerKey(ownerPublicKey, ownerKey, approved));
     }
     /**
-     * Re-vouch another owner's row under this service's owner key, so it stands on a remaining
+     * Re-vouch another owner's row under this service's owner signer, so it stands on a remaining
      * owner's signature before the owner that added it is removed
-     * ({@link ControlDatabase.revouchOwnerKey}; for `CadreNode.removeMachine` only). What stays
-     * here is the owner-key precondition, checked before any read (see {@link removePeer}).
+     * ({@link ControlDatabase.revouchOwnerKey}; for `CadreNode.removeOwner` only). What stays
+     * here is the owner-signer precondition, checked before any read (see {@link removePeer}).
      *
      * @returns `true` when the row was re-vouched, `false` when the key is not a live owner here.
      */
-    async revouchOwner(ownerPublicKey) {
-        const ownerKey = this.requireOwnerPublicKey();
-        if (!this.controlDatabase) {
-            throw new Error('Control database not initialized');
-        }
-        return await this.controlDatabase.revouchOwnerKey(ownerPublicKey, ownerKey, message => this.signMessageBytes(message));
+    async revouchOwner(ownerPublicKey, sign) {
+        const ownerKey = this.requireOwnerSigner().publicKey;
+        const controlDatabase = this.requireControlDatabase();
+        return await this.withOwnerSign(`Re-vouch owner key ${ownerPublicKey}`, sign, (approved) => controlDatabase.revouchOwnerKey(ownerPublicKey, ownerKey, approved));
     }
     /**
-     * Remove a machine completely, signed by this service's owner key: its `CadrePeer` row, its
-     * `OwnerKey` row when `target.ownerKey` names one, its `DeviceToken` row, and the
-     * withdrawal of every invitation in `target.inviteKeys`, all in one transaction
-     * ({@link ControlDatabase.removeMachine}). What stays here is the owner-key precondition,
-     * checked before any read (see {@link removePeer}).
+     * Remove a machine completely, signed by this service's owner signer: its `CadrePeer` row, its
+     * `DeviceToken` row, and the withdrawal of every invitation in `target.inviteKeys`, all in one
+     * transaction ({@link ControlDatabase.removeMachine}). What stays here is the owner-signer
+     * precondition, checked before any read (see {@link removePeer}).
      */
-    async removeMachine(target) {
-        const ownerKey = this.requireOwnerPublicKey();
-        if (!this.controlDatabase) {
-            throw new Error('Control database not initialized');
-        }
-        return await this.controlDatabase.removeMachine(target, ownerKey, message => this.signMessageBytes(message));
+    async removeMachine(target, sign) {
+        const ownerKey = this.requireOwnerSigner().publicKey;
+        const controlDatabase = this.requireControlDatabase();
+        return await this.withOwnerSign(`Remove the machine ${target.peerId} from the cadre`, sign, (approved) => controlDatabase.removeMachine(target, ownerKey, approved));
     }
     /**
      * Owner "re-touch" of an existing `CadrePeer` membership row: bump `UpdatedAt` and
@@ -514,23 +490,21 @@ export class SeedBootstrapService {
      *
      * 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.
+     * `VouchOwner` to this node's owner key. What stays here is the owner-signer 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.
-     * @throws if no owner private key is configured (a non-owner cannot
+     * @throws if no owner signer is configured (a non-owner cannot
      *   re-sign another peer's row) or the control database is not initialized.
      */
-    async reauthorizePeer(peerId, updatedAt) {
-        // Fail fast on a keyless service before any DB read (see removePeer): a non-owner
+    async reauthorizePeer(peerId, updatedAt, sign) {
+        // Fail fast on a signerless service before any DB read (see removePeer): a non-owner
         // cannot re-sign the voucher, and must not silently no-op on an absent row.
-        const ownerKey = this.requireOwnerPublicKey();
-        if (!this.controlDatabase) {
-            throw new Error('Control database not initialized');
-        }
-        const retouched = await this.controlDatabase.reauthorizeCadrePeer(peerId, updatedAt, ownerKey, message => this.signMessageBytes(message));
+        const ownerKey = this.requireOwnerSigner().publicKey;
+        const controlDatabase = this.requireControlDatabase();
+        const retouched = await this.withOwnerSign(`Re-issue the membership of ${peerId}`, sign, (approved) => controlDatabase.reauthorizeCadrePeer(peerId, updatedAt, ownerKey, approved));
         if (!retouched) {
             log('reauthorizePeer: no CadrePeer row for %s (nothing to re-touch)', peerId);
             return;
@@ -547,81 +521,115 @@ export class SeedBootstrapService {
      *
      * The signatures, the single transaction, and the strictly-monotonic
      * `reissuedAt` contract are {@link ControlDatabase.reissueRevocations}'s. What
-     * stays here is the owner-key precondition.
+     * stays here is the owner-signer 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
+     * @throws if no owner signer is configured or the control database is not
      *   initialized.
      */
-    async reissueRevocations(rows, reissuedAt) {
-        // Fail fast on a keyless service before any DB work (see removePeer): a
+    async reissueRevocations(rows, reissuedAt, sign) {
+        // Fail fast on a signerless service before any DB work (see removePeer): a
         // non-owner cannot sign the reissue digests.
-        const ownerKey = this.requireOwnerPublicKey();
-        if (!this.controlDatabase) {
-            throw new Error('Control database not initialized');
-        }
-        return this.controlDatabase.reissueRevocations(rows, reissuedAt, ownerKey, message => this.signMessageBytes(message));
+        const ownerKey = this.requireOwnerSigner().publicKey;
+        const controlDatabase = this.requireControlDatabase();
+        return await this.withOwnerSign(`Re-send ${rows.length} removal record(s) to the cadre`, sign, (approved) => controlDatabase.reissueRevocations(rows, reissuedAt, ownerKey, approved));
     }
     /**
      * Owner filing of the singleton `Revocation` ledger marker, so the table is never a
      * never-written block that the storage layer re-consults on every read.
      *
      * The signature, the insert-if-absent guard and the `'already-open'` mapping are
-     * {@link ControlDatabase.openRevocationLedger}'s. What stays here is the owner-key
+     * {@link ControlDatabase.openRevocationLedger}'s. What stays here is the owner-signer
      * precondition.
      *
-     * @throws if no owner private key is configured or the control database is not
+     * @throws if no owner signer is configured or the control database is not
      *   initialized.
      */
-    async openRevocationLedger() {
-        // Fail fast on a keyless service before any DB work (see removePeer): a
+    async openRevocationLedger(sign) {
+        // Fail fast on a signerless service before any DB work (see removePeer): a
         // non-owner cannot sign the marker's append digest.
-        const ownerKey = this.requireOwnerPublicKey();
-        if (!this.controlDatabase) {
-            throw new Error('Control database not initialized');
-        }
-        return this.controlDatabase.openRevocationLedger(ownerKey, message => this.signMessageBytes(message));
+        const ownerKey = this.requireOwnerSigner().publicKey;
+        const controlDatabase = this.requireControlDatabase();
+        return await this.withOwnerSign('Open the cadre\'s removal ledger', sign, (approved) => controlDatabase.openRevocationLedger(ownerKey, approved));
     }
     /**
      * Owner-signed INSERT of a `CadreInvite` row — an invitation any member machine can redeem
      * on this owner's behalf ({@link ControlDatabase.insertCadreInvite}). The keypair mint, the
      * expiry and use-count defaults, and the bundle the holder receives are
-     * `CadreNode.createCadreInvitation`'s; what stays here is the owner-key precondition and
-     * the signature, as {@link insertSelfDeviceToken} keeps them for device tokens.
+     * `CadreNode.createCadreInvitation`'s; what stays here is the owner-signer precondition and
+     * the approval, as {@link insertSelfDeviceToken} keeps them for device tokens.
      *
      * @returns the row as stored, which the invitation bundle carries verbatim.
-     * @throws if no owner private key is configured or the control database is not initialized.
+     * @throws if no owner signer is configured or the control database is not initialized.
      */
-    async insertCadreInvite(invite) {
-        // Fail fast on a keyless service before any DB work (see removePeer).
-        const ownerKey = this.requireOwnerPublicKey();
-        if (!this.controlDatabase) {
-            throw new Error('Control database not initialized');
-        }
-        return await this.controlDatabase.insertCadreInvite(invite, ownerKey, message => this.signMessageBytes(message));
+    async insertCadreInvite(invite, sign) {
+        // Fail fast on a signerless service before any DB work (see removePeer).
+        const ownerKey = this.requireOwnerSigner().publicKey;
+        const controlDatabase = this.requireControlDatabase();
+        return await this.withOwnerSign('Create a machine invitation to the cadre', sign, (approved) => controlDatabase.insertCadreInvite(invite, ownerKey, approved));
     }
     /**
      * Owner-signed WITHDRAWAL of a `CadreInvite`: the `Revocation` tombstone over its stamp, with
      * the row kept ({@link ControlDatabase.withdrawCadreInvite}). What stays here is the
-     * owner-key precondition.
+     * owner-signer precondition.
      *
      * @returns `true` when this call filed the tombstone, `false` when the row is absent here or
      *   already withdrawn.
-     * @throws if no owner private key is configured or the control database is not initialized.
+     * @throws if no owner signer is configured or the control database is not initialized.
      */
-    async withdrawCadreInvite(key) {
-        const ownerKey = this.requireOwnerPublicKey();
-        if (!this.controlDatabase) {
-            throw new Error('Control database not initialized');
-        }
-        return await this.controlDatabase.withdrawCadreInvite(key, ownerKey, message => this.signMessageBytes(message));
+    async withdrawCadreInvite(key, sign) {
+        const ownerKey = this.requireOwnerSigner().publicKey;
+        const controlDatabase = this.requireControlDatabase();
+        return await this.withOwnerSign(`Withdraw the cadre invitation ${key}`, sign, (approved) => controlDatabase.withdrawCadreInvite(key, ownerKey, approved));
+    }
+    /**
+     * Owner-signed INSERT of an `OwnerGrant` row — a grant of ownership any member machine can
+     * redeem on this owner's behalf ({@link ControlDatabase.insertOwnerGrant}). The keypair mint,
+     * the lifetime default and the bundle the holder receives are `CadreNode.createOwnerGrant`'s;
+     * what stays here is the owner-signer precondition and the approval, as for
+     * {@link insertCadreInvite}. The label is checked before the approval opens, so one the row
+     * would refuse never prompts the user.
+     *
+     * @returns the row as stored, which the grant bundle carries verbatim.
+     * @throws if no owner signer is configured, the control database is not initialized, or the label is too long.
+     */
+    async insertOwnerGrant(grant, sign) {
+        const ownerKey = this.requireOwnerSigner().publicKey;
+        const controlDatabase = this.requireControlDatabase();
+        const label = ownerKeyLabel(grant.label);
+        const named = label === null ? 'an owner grant' : `the owner grant "${label}"`;
+        return await this.withOwnerSign(`Create ${named}: whoever holds it can become an owner of the cadre`, sign, (approved) => controlDatabase.insertOwnerGrant({ ...grant, label }, ownerKey, approved));
+    }
+    /**
+     * Owner-signed WITHDRAWAL of an `OwnerGrant`: the `Revocation` tombstone over its stamp, with
+     * the row kept ({@link ControlDatabase.withdrawOwnerGrant}). What stays here is the
+     * owner-signer precondition.
+     *
+     * @returns `true` when this call filed the tombstone, `false` when the row is absent here or
+     *   already withdrawn.
+     * @throws if no owner signer is configured or the control database is not initialized.
+     */
+    async withdrawOwnerGrant(key, sign) {
+        const ownerKey = this.requireOwnerSigner().publicKey;
+        const controlDatabase = this.requireControlDatabase();
+        return await this.withOwnerSign(`Withdraw the owner grant ${key}`, sign, (approved) => controlDatabase.withdrawOwnerGrant(key, ownerKey, approved));
     }
     /**
      * Create a seed from the current control network state.
-     * The seed contains peer information and is signed by an owner.
+     * The seed contains peer information and is signed by an owner; its `signerKey` is the
+     * owner signer's key.
      */
-    async createSeed() {
-        if (!this.config.ownerPrivateKey || !this.ownerPublicKey) {
+    async createSeed(sign) {
+        return await this.mintSeed(sign, null);
+    }
+    /**
+     * {@link createSeed}, with `selfRelayAddr` added to this node's own peer entry before the
+     * seed is signed: the signature covers every address ({@link seedDigest}), so nothing may
+     * be added after it.
+     */
+    async mintSeed(sign, selfRelayAddr) {
+        const signer = this.config.ownerSigner;
+        if (!signer) {
             throw new Error('Owner key required to create seeds');
         }
         if (!this.controlDatabase || !this.libp2pNode) {
@@ -629,18 +637,23 @@ export class SeedBootstrapService {
         }
         log('Creating seed for party: %s', this.config.partyId);
         // Query all peers from the control database
-        const peers = await this.queryPeers();
+        const selfPeerId = this.libp2pNode.peerId.toString();
+        const peers = await this.queryPeers(selfPeerId);
+        if (selfRelayAddr !== null) {
+            addSelfRelayAddr(peers, selfPeerId, selfRelayAddr);
+        }
         // Create the seed data (without signature)
         const seedData = {
             partyId: this.config.partyId,
             peers,
         };
         // Sign the seed over its canonical byte representation
-        const signature = sign(seedDigest(seedData), this.config.ownerPrivateKey, 'ed25519', 'base64url', 'base64url', 'base64url');
+        const digestBytes = uint8ArrayFromString(seedDigest(seedData), 'base64url');
+        const signature = await this.withOwnerSign('Mint a seed for a machine joining the cadre', sign, (approved) => approved(digestBytes));
         const seed = {
             ...seedData,
             signature,
-            signerKey: this.ownerPublicKey,
+            signerKey: signer.publicKey,
         };
         log('Created seed with %d peers', peers.length);
         return seed;
@@ -652,9 +665,8 @@ export class SeedBootstrapService {
      * `signerKey` that does NOT come from the seed body: the receiver's
      * 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.
+     * `SeedTrustPolicy`. A forged self-signed seed does not pass, 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
@@ -670,12 +682,12 @@ export class SeedBootstrapService {
         if (!merged.success) {
             return merged;
         }
-        return { ...merged, ...await this.dialSeedOwners(seed) };
+        return { ...merged, ...await this.dialPreferredPeers(seed) };
     }
     /**
      * The first half of {@link applySeed}: check the signature and the signer's trust, then merge
      * the seed's peer addresses into the peer store. Every rejection happens here, so this result is
-     * what the inbound handler acks with; the owner dials that follow cannot change it.
+     * what the inbound handler acks with; the dials that follow cannot change it.
      */
     async verifyAndMergeSeed(seed, options) {
         if (!this.libp2pNode) {
@@ -709,7 +721,7 @@ export class SeedBootstrapService {
             partyId: seed.partyId,
             signerKey: seed.signerKey,
             knownOwnerKeys,
-            // Optional-chained like `dialSeedOwners`: partial libp2p handles (unit-test doubles)
+            // Optional-chained like `dialPreferredPeers`: partial libp2p handles (unit-test doubles)
             // omit `peerId`. A real node always has one, and a proof bound to a real peer id can
             // only fail against '' — the safe direction.
             localPeerId: this.libp2pNode.peerId?.toString() ?? '',
@@ -723,54 +735,55 @@ export class SeedBootstrapService {
         await this.anchorAcceptedSigner(seed.signerKey, decision);
         const peersAdded = await mergeSeedPeers(this.libp2pNode, seed.peers);
         log('Merged seed: %d peers added', peersAdded);
-        return { success: true, peersAdded, ownerDialsAttempted: 0, ownerDialsFailed: 0 };
+        return { success: true, peersAdded, preferredDialsAttempted: 0, preferredDialsFailed: 0 };
     }
     /**
-     * The second half of {@link applySeed}: dial the seed's owner peers to establish connections.
+     * The second half of {@link applySeed}: dial the seed's preferred peers (`SeedPeer.preferred`:
+     * the machine that minted it and every always-on machine) to establish connections.
      *
-     * Best-effort and COUNTED: an owner that is momentarily down leaves this node seeded but
+     * Best-effort and COUNTED: a peer that is momentarily down leaves this node seeded but
      * unconnected, which the caller can only see if the outcome is reported (see
-     * `ApplySeedResult.ownerDialsFailed`). Recovery is not this loop's job —
+     * `ApplySeedResult.preferredDialsFailed`). Recovery is not this loop's job —
      * `CadreNode.dialColdStartBootstrap` retries these same addresses on every control-cohort
      * reconcile pass until the control database has siblings.
      *
      * The inbound handler runs this AFTER it has acked and closed the stream
-     * ({@link handleSeedStream}), because an unreachable owner can take `dialBudget.totalMs`.
+     * ({@link handleSeedStream}), because an unreachable peer can take `dialBudget.totalMs`.
      */
-    async dialSeedOwners(seed) {
+    async dialPreferredPeers(seed) {
         const node = this.libp2pNode;
         if (!node) {
-            log('Seed service shut down before its owner dials; none attempted');
-            return { ownerDialsAttempted: 0, ownerDialsFailed: 0 };
+            log('Seed service shut down before its dials; none attempted');
+            return { preferredDialsAttempted: 0, preferredDialsFailed: 0 };
         }
-        // `createSeed` projects every non-revoked CadrePeer row, so an owner applying
-        // a seed minted after it joined finds ITSELF in the owner list. Dialing self always
-        // throws, which would report a healthy owner as "seeded but stranded".
+        // `createSeed` projects every non-revoked CadrePeer row, so a preferred machine applying
+        // a seed minted after it joined finds ITSELF in the list. Dialing self always throws,
+        // which would report a healthy node as "seeded but stranded".
         // Optional-chained: partial libp2p handles (unit-test doubles) omit `peerId`,
         // and an undefined self simply matches nothing.
-        // Every one of an owner's addresses is a candidate, each on its own time limit
-        // (`dialPeerAddrs`), so an owner whose first address never answers neither
+        // Every one of a peer's addresses is a candidate, each on its own time limit
+        // (`dialPeerAddrs`), so a peer whose first address never answers neither
         // stalls seed application nor goes undialed at its other addresses. The seed's
-        // addresses carry no peer id; the dial binds each to the owner's.
+        // addresses carry no peer id; the dial binds each to the peer's.
         const selfPeerId = node.peerId?.toString();
-        let ownerDialsAttempted = 0;
-        let ownerDialsFailed = 0;
-        for (const peer of seed.peers.filter(p => p.isOwner)) {
+        let preferredDialsAttempted = 0;
+        let preferredDialsFailed = 0;
+        for (const peer of seed.peers.filter(p => p.preferred)) {
             if (peer.multiaddrs.length === 0 || peer.peerId === selfPeerId) {
                 continue;
             }
-            ownerDialsAttempted++;
+            preferredDialsAttempted++;
             try {
                 const addrs = parseDialAddrs(peer.multiaddrs);
-                log('Dialing owner peer: %s (%d addr(s))', peer.peerId, addrs.length);
-                await dialPeerAddrs(node, peer.peerId, addrs, this.dialBudget, `Owner dial of ${peer.peerId}`);
+                log('Dialing preferred seed peer: %s (%d addr(s))', peer.peerId, addrs.length);
+                await dialPeerAddrs(node, peer.peerId, addrs, this.dialBudget, `Seed dial of ${peer.peerId}`);
             }
             catch (error) {
-                // Counted even when the owner reaches us only through our own relay: this node is still
-                // not connected to it, and `ownerDialsFailed` is how the caller learns that.
-                ownerDialsFailed++;
+                // Counted even when the peer reaches us only through our own relay: this node is still
+                // not connected to it, and `preferredDialsFailed` is how the caller learns that.
+                preferredDialsFailed++;
                 if (error instanceof SelfRelayOnlyError) {
-                    log('Owner peer %s is reachable only by relaying through this node; waiting for it to reconnect', peer.peerId);
+                    log('Seed peer %s is reachable only by relaying through this node; waiting for it to reconnect', peer.peerId);
                 }
                 else {
                     log('Failed to dial peer %s: %o', peer.peerId, error);
@@ -778,8 +791,8 @@ export class SeedBootstrapService {
                 // Continue - not all peers need to be reachable
             }
         }
-        log('Dialed seed owners: %d/%d owner dial(s) failed', ownerDialsFailed, ownerDialsAttempted);
-        return { ownerDialsAttempted, ownerDialsFailed };
+        log('Dialed preferred seed peers: %d/%d dial(s) failed', preferredDialsFailed, preferredDialsAttempted);
+        return { preferredDialsAttempted, preferredDialsFailed };
     }
     /**
      * Persist a signer that a pin/TOFU accepted into the node-local anchor, so a
@@ -883,7 +896,7 @@ export class SeedBootstrapService {
         }
         const peerId = peerIdFromString(target.peerId);
         const addrs = deliveryDialAddrs(target.peerId, target.multiaddrs);
-        await mergeSeedPeers(node, [{ peerId: target.peerId, multiaddrs: target.multiaddrs, isOwner: false }]);
+        await mergeSeedPeers(node, [{ peerId: target.peerId, multiaddrs: target.multiaddrs, preferred: false }]);
         if (addrs.length === 0) {
             return (signal) => node.dialProtocol(peerId, SEED_PROTOCOL, { signal });
         }
@@ -984,16 +997,16 @@ export class SeedBootstrapService {
         }
     }
     /**
-     * The peers a seed carries: the control database's own projection
+     * The peers a seed `minterPeerId` mints carries: the control database's own projection
      * ({@link ControlDatabase.querySeedPeers}, shared with the cadre invitation redemption
-     * reply), which reads through the revocation filter and flags owners from the replicated
-     * `OwnerKey` table — a dial hint, not a trust decision (the NOTE at `projectSeedPeers`).
+     * reply), which reads through the revocation filter and marks the minter and every
+     * always-on machine preferred — a dial hint, not a trust decision.
      */
-    async queryPeers() {
+    async queryPeers(minterPeerId) {
         if (!this.controlDatabase) {
             return [];
         }
-        return await this.controlDatabase.querySeedPeers();
+        return await this.controlDatabase.querySeedPeers(minterPeerId);
     }
     /**
      * Register the seed protocol handler. The inbound closure just delegates to
@@ -1009,14 +1022,14 @@ export class SeedBootstrapService {
     }
     /**
      * Read one inbound seed frame, verify and merge it, write the ack and close the
-     * stream, then dial the seed's owners.
+     * stream, then dial the seed's preferred peers.
      *
-     * The ack and the close come BEFORE the owner dials: an unreachable owner can hold
+     * The ack and the close come BEFORE those dials: an unreachable peer can hold
      * a dial for `dialBudget.totalMs` (86 s at the default declared link), which is not
      * link time and does not belong inside the sender's delivery deadline. The close is
      * what releases the sender, which reads the ack to end-of-stream. The stream stays
      * counted in {@link activeStreams} through the dials, so {@link maxConcurrentSeeds}
-     * still bounds concurrent owner-dial phases.
+     * still bounds concurrent dial phases.
      *
      * Hardened against a buggy/compromised own-cadre node: a concurrency cap (over
      * {@link maxConcurrentSeeds}, reply without applying), a read timeout (a peer
@@ -1045,7 +1058,7 @@ export class SeedBootstrapService {
             acked = true;
             await replyAndClose(stream, { accepted: merged.success, reason: merged.error, code: merged.code }, 'Seed');
             if (merged.success) {
-                await this.dialSeedOwners(seed);
+                await this.dialPreferredPeers(seed);
                 this.eventCallbacks.onSeedApplied?.(seed.partyId, merged.peersAdded, seed);
             }
             else {
@@ -1117,16 +1130,20 @@ export class SeedBootstrapService {
      * does not listen. Call `CadreNode.reconcileControlCohort()` after delivering
      * the seed to dial at once.
      *
+     * The vouch and the seed are one owner approval.
+     *
      * @param options - Drone peer info from provider API
      * @returns Seed and encoded seed for drone initialization
      */
-    async addDrone(options) {
+    async addDrone(options, sign) {
         const { dronePeerId, droneMultiaddrs } = options;
         log('Adding drone: %s', dronePeerId);
-        // 1. Authorize the new drone peer
-        await this.authorizePeer({ peerId: dronePeerId, multiaddrs: droneMultiaddrs });
-        // 2. Create seed with current state
-        const seed = await this.createSeed();
+        const seed = await this.withOwnerSign(`Add the machine ${dronePeerId} to the cadre`, sign, async (approved) => {
+            // 1. Authorize the new drone peer
+            await this.authorizePeer({ peerId: dronePeerId, multiaddrs: droneMultiaddrs }, approved);
+            // 2. Create seed with current state
+            return await this.createSeed(approved);
+        });
         // 3. Encode for transport
         const encodedSeed = this.encodeSeed(seed);
         log('Drone %s added, seed created with %d peers', dronePeerId, seed.peers.length);
@@ -1139,25 +1156,20 @@ export class SeedBootstrapService {
      * 1. Authorizes the new phone peer
      * 2. Creates a seed with relay addresses for dialing
      *
+     * The vouch and the seed are one owner approval.
+     *
      * @param phonePeerId - Peer ID of the new phone
      * @returns Seed with relay addresses for out-of-band delivery
      */
-    async addPhoneWithRelay(phonePeerId) {
+    async addPhoneWithRelay(phonePeerId, sign) {
         log('Adding phone with relay: %s', phonePeerId);
-        // 1. Authorize the new phone peer (no multiaddrs - NAT'd)
-        await this.authorizePeer({ peerId: phonePeerId });
-        // 2. Get relay address for this node
         const relayAddr = await this.getRelayAddress();
-        // 3. Create seed - will include our relay address if available
-        const seed = await this.createSeed();
-        // If we have a relay address, make sure it's in our peer entry
-        if (relayAddr && this.libp2pNode) {
-            const ourPeerId = this.libp2pNode.peerId.toString();
-            const ourPeer = seed.peers.find(p => p.peerId === ourPeerId);
-            if (ourPeer && !ourPeer.multiaddrs.includes(relayAddr)) {
-                ourPeer.multiaddrs.push(relayAddr);
-            }
-        }
+        const seed = await this.withOwnerSign(`Add the phone ${phonePeerId} to the cadre`, sign, async (approved) => {
+            // 1. Authorize the new phone peer (no multiaddrs - NAT'd)
+            await this.authorizePeer({ peerId: phonePeerId }, approved);
+            // 2. Create seed - with our relay address in our own entry, when we have one
+            return await this.mintSeed(approved, relayAddr);
+        });
         const encodedSeed = this.encodeSeed(seed);
         log('Phone %s added with relay, seed created', phonePeerId);
         return { seed, encodedSeed };