@serfab/cadre-core 0.8.1 → 0.9.0

package/README.md

@@ -126,9 +126,9 @@ Adding a new device to your cadre uses the Seed Bootstrap API:
 // On the new device: generate identity
 const enrollment = new EnrollmentService();
 const { peerId, privateKey } = await enrollment.createCadrePeer();
-// Store privateKey securely, send peerId + multiaddrs to authority
+// Store privateKey securely, send peerId + multiaddrs to owner
 
-// On authority device: authorize the new peer and create seed
+// On owner device: authorize the new peer and create seed
 await node.authorizePeer(newDevicePeerId, newDeviceMultiaddrs);
 const seed = await node.createSeed();
 

package/dist/cadre-node.d.ts

@@ -1,7 +1,7 @@
 import type { Libp2p, PeerId } from '@libp2p/interface';
 import type { Multiaddr } from '@multiformats/multiaddr';
 import type { CadreNodeConfig, StrandInstance, StrandConfig, SAppConfig, CadreNodeEvents, ControlNetworkSeed, ApplySeedResult, AddDroneOptions, AddPhoneOptions, DroneInitResult, InviteResult, CadreInvite, OpenInvitation, FormStrandResult, StrandFormationDisclosure, ResolveOpts, SelfRegistrationOutcome, ServiceWakeResult, PushPlatform, DeviceTokenRecord, ResolveDeviceTokenOpts } from './types.js';
-import { type AuthorityKeyPair } from './authority-key.js';
+import { type Ed25519KeyPair } from './ed25519-key.js';
 import { type SAppIdLookup } from './strand-watcher.js';
 import { EnrollmentService } from './enrollment.js';
 import { ControlDatabase } from './control-database.js';
@@ -26,7 +26,7 @@ export declare class CadreNode implements SAppIdLookup {
      * The resolved node identity key, set once by {@link resolveIdentityKey}
      * during {@link start} (from `config.keyStore`, else `config.privateKey`).
      * Left undefined when neither is configured — libp2p then generates an
-     * ephemeral key internally and there is no exposed authority key. Every
+     * ephemeral key internally and there is no exposed owner key. Every
      * identity-dependent path (control node creation, self-record signing, strand
      * launch) reads this resolved field, never `config.privateKey` directly.
      */
@@ -49,9 +49,9 @@ export declare class CadreNode implements SAppIdLookup {
     private strandAddrService;
     /**
      * Server-side push-wake fan-out. Constructed by {@link start} only when
-     * `config.push` (FCM/APNs credentials) is present — without it the node behaves
-     * exactly as before (no notifier, no fan-out). Owns who/when to wake
-     * hibernating mobile peers on strand activity.
+     * `config.push` (an injected `PushNotifier` + policy) is present — without it
+     * the node behaves exactly as before (no notifier, no fan-out). Owns who/when
+     * to wake hibernating mobile peers on strand activity.
      */
     private pushFanoutService;
     /** Backing field for the {@link running} / {@link isRunning} getters. */
@@ -101,13 +101,13 @@ export declare class CadreNode implements SAppIdLookup {
     private reconcileControlCohortInFlight;
     /**
      * Single-flight guard for {@link registerSelf}. Concurrent callers (the explicit
-     * CLI `--authority` publish, the 1s startup timer, the TTL heartbeat, and the
+     * CLI `--owner` publish, the 1s startup timer, the TTL heartbeat, and the
      * address-change listener) share one in-flight publish so two of them can never
      * both read "no row yet" and race a duplicate INSERT (a `CadrePeer` PK conflict).
      */
     private registerSelfInFlight;
     /**
-     * Re-replication queue for authority control writes that committed while this
+     * Re-replication queue for owner control writes that committed while this
      * node was alone — `controlNode.getConnections().length === 0` at write time
      * means the Optimystic commit was local-only (the block's cluster was ≤1) and
      * never broadcast. Maps the affected subject peerId → the write to re-issue once
@@ -121,7 +121,7 @@ export declare class CadreNode implements SAppIdLookup {
     /** This node's own `DeviceToken` self-write committed local-only (re-touched on growth). */
     private pendingSelfDeviceWrite;
     /**
-     * Guards the one-shot, first-cohort-growth reconstruction: an authority re-touches
+     * Guards the one-shot, first-cohort-growth reconstruction: an owner re-touches
      * every membership row it may have authored that could be unreplicated (covering
      * writes made before this process started, which the in-memory queue cannot know).
      * Set true after the first drain so later passes only drain the in-memory queue.
@@ -218,6 +218,19 @@ export declare class CadreNode implements SAppIdLookup {
      * Start the cadre node
      */
     start(): Promise<void>;
+    /**
+     * Build the server-side push-wake fan-out over an injected {@link PushNotifier}.
+     *
+     * The notifier reaches for `node:http2`/`node:crypto`, so the cross-platform
+     * core never constructs it — the Node host builds it from
+     * `@serfab/cadre-core/push-node` and passes the instance in
+     * `CadreNodeConfig.push`. This node owns that instance's lifecycle from here:
+     * {@link cleanup} closes the fan-out, which closes the notifier (freeing the
+     * APNs HTTP/2 session). Every other primitive the fan-out needs (member
+     * enumeration, participation, direct dial, token resolve/expire) is an
+     * import-clean closure over this node.
+     */
+    private buildPushFanout;
     /**
      * Stop the cadre node
      */
@@ -253,7 +266,7 @@ export declare class CadreNode implements SAppIdLookup {
     /**
      * Schedule the node's initial self-record publish + ongoing refresh shortly
      * after start (non-blocking). {@link registerSelf} is idempotent and safely
-     * no-ops when it cannot yet sign/insert (e.g. authority key not installed),
+     * no-ops when it cannot yet sign/insert (e.g. owner key not installed),
      * so the timer is harmless even when registration only becomes possible later.
      */
     private scheduleSelfRegistration;
@@ -266,10 +279,10 @@ export declare class CadreNode implements SAppIdLookup {
      *   (signaling/`p2p-circuit` first), signed with the ed25519 key behind its
      *   PeerId (the resolved node identity from `keyStore`/`config.privateKey`).
      * - If the row already exists: a self-signed UPDATE bumping `UpdatedAt`.
-     * - If not, and the node is its own authority: an authority-signed INSERT that
+     * - If not, and the node is its own owner: an owner-signed INSERT that
      *   also carries the self-signature.
-     * - Otherwise: logs and returns (a non-authority node with no row yet must
-     *   wait for an authority to insert it; it can then self-refresh).
+     * - Otherwise: logs and returns (a non-owner node with no row yet must
+     *   wait for an owner to insert it; it can then self-refresh).
      *
      * Safe to call repeatedly (heartbeat / address-change driven); each successful
      * publish strictly increases `UpdatedAt`. Concurrent calls are collapsed into a
@@ -291,23 +304,23 @@ export declare class CadreNode implements SAppIdLookup {
      */
     private getSelfSigningKey;
     /**
-     * The authority keypair (base64url Ed25519) derived from this node's resolved
-     * identity key. In the single-key reference model the authority signing key is
-     * *derived from* the node identity (see {@link authorityKeyFromLibp2p}), so the
+     * The owner keypair (base64url Ed25519) derived from this node's resolved
+     * identity key. In the single-key reference model the owner signing key is
+     * *derived from* the node identity (see {@link ed25519KeyPairFromLibp2p}), so the
      * same key material protected in a secure enclave backs both.
      *
-     * Exposed so the hosting app retains control of authority genesis: cadre-core
+     * Exposed so the hosting app retains control of owner genesis: cadre-core
      * resolves + protects the identity, then the app sources this pair to drive
-     * `ensureAuthorityKey(pub)` + `initializeSeedBootstrap(priv)` itself — cadre-core
-     * never silently runs genesis. A future separate-authority slot would return a
+     * `ensureOwnerKey(pub)` + `initializeSeedBootstrap(priv)` itself — cadre-core
+     * never silently runs genesis. A future separate-owner slot would return a
      * distinct key here instead of the identity-derived one.
      *
-     * @returns The base64url seed/public-key authority pair.
+     * @returns The base64url seed/public-key owner pair.
      * @throws If called before {@link start} has resolved the identity, or when the
      *   node runs on an ephemeral libp2p key (no `keyStore`/`privateKey` configured),
      *   since that key is internal to libp2p and not exposed.
      */
-    getIdentityAuthorityKey(): AuthorityKeyPair;
+    getIdentityOwnerKey(): Ed25519KeyPair;
     /**
      * Collect this node's current dialable addresses for publication, signaling
      * (`/p2p-circuit`) first. Prefers the best invite/NAT-resolved set and folds
@@ -366,7 +379,7 @@ export declare class CadreNode implements SAppIdLookup {
      *
      * A per-peer failure (NAT, offline, relay down, connection-gater denial) is
      * logged and swallowed so one unreachable sibling never aborts the pass —
-     * exactly like {@link SeedBootstrapService.applySeed}'s authority-dial loop. A
+     * exactly like {@link SeedBootstrapService.applySeed}'s owner-dial loop. A
      * failed dial is simply retried on the next pass.
      */
     private dialControlSibling;
@@ -398,7 +411,7 @@ export declare class CadreNode implements SAppIdLookup {
      */
     private committedAlone;
     /**
-     * Record (or clear) a just-committed authority membership write in the
+     * Record (or clear) a just-committed owner membership write in the
      * write-while-alone re-replication queue. If the control node had no connections
      * at commit, the Optimystic write was local-only and must be re-issued once the
      * cohort grows; otherwise the write replicated and any stale queue entry for this
@@ -432,28 +445,28 @@ export declare class CadreNode implements SAppIdLookup {
     private retouchSelfDeviceToken;
     /**
      * One-shot, first-cohort-growth reconstruction of the write-while-alone queue for
-     * an AUTHORITY node: re-touch every membership row that may be an unreplicated
-     * authority insert. A row is a candidate iff it is not self (handled by
+     * an OWNER node: re-touch every membership row that may be an unreplicated
+     * owner insert. A row is a candidate iff it is not self (handled by
      * {@link registerSelf}), is not already tracked in the in-memory queue (handled by
      * {@link drainPendingPeerWrites}), and carries no self-`Sig` yet (an
-     * authority-authored row the peer has not self-published — the only kind safe to
+     * owner-authored row the peer has not self-published — the only kind safe to
      * bump without invalidating a self-signature). O(rows) on the small control
-     * tables; safe to over-apply (a monotonic authority bump on an already-replicated
+     * tables; safe to over-apply (a monotonic owner bump on an already-replicated
      * row is a no-op-equivalent).
      *
-     * A node with no authority private key skips this entirely — it cannot re-sign
+     * A node with no owner private key skips this entirely — it cannot re-sign
      * rows for other peers, and rows it merely holds are not its to re-issue. DELETEs
      * cannot be reconstructed here (a removed row leaves no local trace and the schema
      * carries no tombstone) — see the delete-path note in {@link drainPendingPeerWrites}.
      */
     private reconstructAuthoredMembership;
     /**
-     * Drain the in-session write-while-alone queue: re-issue each pending authority
+     * Drain the in-session write-while-alone queue: re-issue each pending owner
      * membership write now that the cohort can broadcast it. Sequential (no fan-out)
      * to avoid a thundering re-touch; an entry is cleared only on success, so a
      * failure (or a still-alone re-commit) leaves it queued for the next growth.
      *
-     * - `authorize`: re-issue as an idempotent monotonic authority UPDATE
+     * - `authorize`: re-issue as an idempotent monotonic owner UPDATE
      *   ({@link reissuePeerAuthorize}). Skipped (and cleared) if the row vanished
      *   (raced a delete) or now carries a self-`Sig` (the peer self-published and owns
      *   its republish).
@@ -466,9 +479,9 @@ export declare class CadreNode implements SAppIdLookup {
      */
     private drainPendingPeerWrites;
     /**
-     * Re-issue an authority membership row as a monotonic authority UPDATE: bump
+     * Re-issue an owner membership row as a monotonic owner UPDATE: bump
      * `UpdatedAt` strictly above the stored value (and the wall clock) and re-sign via
-     * the authority branch of `CadrePeer.AuthorizedUpdate`. The row already exists
+     * the owner branch of `CadrePeer.AuthorizedUpdate`. The row already exists
      * locally (it committed there, just local-only), so this is an UPDATE, not the
      * original INSERT.
      */
@@ -508,11 +521,11 @@ export declare class CadreNode implements SAppIdLookup {
      *   for any member — the `AuthorizedUpdate` self-branch verifies the new `Sig`
      *   against the bound `CadrePeer.PublicKey`). Platform/Token may change here
      *   (rotation / platform switch / reinstall are all normal self-updates).
-     * - If not, and the node holds an authority service: an authority-signed INSERT
+     * - If not, and the node holds an owner service: an owner-signed INSERT
      *   that also carries the self-signature.
      * - Otherwise: throws. Like `CadrePeer`, the first `DeviceToken` row requires an
-     *   authority signature; a non-authority peer (e.g. a phone) must have its row
-     *   seeded by an authority — typically the server it enrolled with — before it
+     *   owner signature; a non-owner peer (e.g. a phone) must have its row
+     *   seeded by an owner — typically the server it enrolled with — before it
      *   can self-refresh. (Establishing that phone→server registration handshake is
      *   the downstream "RN registration" ticket; this node only owns the cadre-core
      *   write path.)
@@ -523,7 +536,7 @@ export declare class CadreNode implements SAppIdLookup {
      * @param platform - `'fcm'` (Android/Firebase) or `'apns'` (Apple).
      * @param token - the opaque platform device/registration token.
      * @throws if the node is not started, exposes no self-signing key, or has no
-     *   existing row and no authority service to self-insert.
+     *   existing row and no owner service to self-insert.
      */
     registerDeviceToken(platform: PushPlatform, token: string): Promise<void>;
     /**
@@ -548,11 +561,11 @@ export declare class CadreNode implements SAppIdLookup {
     /**
      * Delete this node's own `DeviceToken` row (logout / token invalidation). No-op
      * when no row exists. Like {@link registerDeviceToken}'s first insert, the delete
-     * is gated on an authority signature (`DeviceToken.AuthorizedInsert` covers insert
-     * AND delete), so it requires this node's authority service; a non-authority peer
-     * must route the clear through its authority (downstream RN registration path).
+     * is gated on an owner signature (`DeviceToken.AuthorizedInsert` covers insert
+     * AND delete), so it requires this node's owner service; a non-owner peer
+     * must route the clear through its owner (downstream RN registration path).
      *
-     * @throws if the node is not started, or a row exists but no authority service is
+     * @throws if the node is not started, or a row exists but no owner service is
      *   available to sign the delete.
      */
     clearDeviceToken(): Promise<void>;
@@ -561,10 +574,10 @@ export declare class CadreNode implements SAppIdLookup {
      * unregistered during a push-wake fan-out. Unlike {@link clearDeviceToken}
      * (self-only — it hardcodes the local peerId), this takes an arbitrary peerId.
      *
-     * - When this node holds an authority seed service, it deletes the row
-     *   (`deleteDeviceToken` is authority-gated and accepts any peerId), so the peer
+     * - When this node holds an owner seed service, it deletes the row
+     *   (`deleteDeviceToken` is owner-gated and accepts any peerId), so the peer
      *   is not retried until it re-registers.
-     * - When this node is NOT an authority it cannot delete the row, so it only logs
+     * - When this node is NOT an owner it cannot delete the row, so it only logs
      *   that a re-registration is needed. The fan-out's own in-memory dead-token set
      *   is what actually stops re-pushing to the dead token this process — see
      *   {@link PushFanoutService}. That set is acceptably lossy across restarts (a
@@ -663,19 +676,19 @@ export declare class CadreNode implements SAppIdLookup {
     addStrand(config: StrandConfig): Promise<StrandInstance>;
     /**
      * Publish a strand row to the shared control database under this node's own
-     * authority identity, so other cadre members discover it via control-network
+     * owner identity, so other cadre members discover it via control-network
      * sync (their {@link StrandWatcher} fires `strand:discovered`).
      *
-     * This is the authority-signed `Strand` INSERT that {@link addStrand}
+     * This is the owner-signed `Strand` INSERT that {@link addStrand}
      * deliberately omits: `addStrand` only starts the LOCAL strand instance,
      * whereas publishing makes the strand visible cadre-wide. A typical creator
      * does both (start locally + publish); a discovering peer only does
      * `addStrand` (the row already exists).
      *
      * The insert is signed with the ed25519 key behind this node's PeerId — which
-     * {@link authorityKeyFromLibp2p} also exposes as the node's authority keypair,
-     * so peer identity and authority key are one and the same. That key must be
-     * enrolled in `AuthorityKey` (e.g. via {@link ControlDatabase.ensureAuthorityKey}
+     * {@link ed25519KeyPairFromLibp2p} also exposes as the node's owner keypair,
+     * so peer identity and owner key are one and the same. That key must be
+     * enrolled in `OwnerKey` (e.g. via {@link ControlDatabase.ensureOwnerKey}
      * at genesis) or the schema's `Strand.Authorized` constraint rejects the write.
      * Failing loudly here is intentional: a silently-unpublished strand would run
      * as a local-only island that no peer could ever discover or join.
@@ -684,12 +697,12 @@ export declare class CadreNode implements SAppIdLookup {
      *   {@link addStrand}).
      * @param type - `'o'` for open (default) or `'c'` for closed.
      * @param memberPrivateKey - Optional membership key for a closed strand.
-     * @throws if the node is not started, exposes no authority signing key, or the
+     * @throws if the node is not started, exposes no owner signing key, or the
      *   control DB rejects the (unauthorized) insert.
      */
     publishStrand(strandId: string, type?: 'o' | 'c', memberPrivateKey?: string): Promise<void>;
     /**
-     * Publish an authority-signed `FormationInvite` (open-invitation token) to the
+     * Publish an owner-signed `FormationInvite` (open-invitation token) to the
      * shared control database, so a later {@link formStrand} redemption can be
      * validated against it (the consent branch of `Strand.Authorized`).
      *
@@ -700,8 +713,8 @@ export declare class CadreNode implements SAppIdLookup {
      * from this row. A host minting a closed-strand invite does both (mint +
      * publish), exactly as the integration harness's `createInvitation` does.
      *
-     * Signs with the same self-authority key as {@link publishStrand} (the ed25519
-     * key behind this node's PeerId, which must be an enrolled `AuthorityKey`).
+     * Signs with the same self-owner key as {@link publishStrand} (the ed25519
+     * key behind this node's PeerId, which must be an enrolled `OwnerKey`).
      * Throws loudly if the node isn't started or exposes no signing key.
      *
      * @param token - Invitation token (the `FormationInvite` primary key); use the
@@ -841,12 +854,12 @@ export declare class CadreNode implements SAppIdLookup {
      */
     getSAppConfig(strandId: string): SAppConfig | undefined;
     /**
-     * Initialize the seed bootstrap service with an authority key.
+     * Initialize the seed bootstrap service with an owner key.
      * Must be called before using seed-related methods that require signing.
      *
-     * @param authorityPrivateKey - The authority's private key (base64url encoded)
+     * @param ownerPrivateKey - The owner's private key (base64url encoded)
      */
-    initializeSeedBootstrap(authorityPrivateKey: string): void;
+    initializeSeedBootstrap(ownerPrivateKey: string): void;
     /**
      * Push the multiaddrs that future invites should advertise. Pass `null` to
      * revert to the libp2p-reported addresses (the default). The host calls this
@@ -867,8 +880,35 @@ export declare class CadreNode implements SAppIdLookup {
     }>>;
     /**
      * Probe whether a given peer is a `CadrePeer` member.
+     *
+     * This is the ADDRESSABLE surface ("do I have a dialable address record for this
+     * peer") — it includes this node's own self-published row. Address resolution and
+     * push fan-out use this. The trust-facing gate is {@link isAuthorizedMember}.
      */
     isMember(peerId: string): Promise<boolean>;
+    /**
+     * Enumerate the party's AUTHORIZED members — the trust-facing set, distinct from
+     * the addressable set ({@link listMembers}). Excludes this node itself: a node
+     * publishes its own `CadrePeer` address row so its dialable address rides in seeds,
+     * but "self" is not a peer this node authorized. The control-network wake and
+     * strand-address gates consult this set, NOT the addressable one.
+     *
+     * NOTE: this is the addressable set minus self for now. The real trust predicate
+     * (voucher recorded on the row ∈ node-local trusted-owner anchor, signature
+     * verified) lands with the `membership-node-local-owner-anchor` /
+     * `membership-authorized-predicate-and-gates` tickets; keeping the filter in this one
+     * method means that change touches a single place.
+     */
+    listAuthorizedMembers(): Promise<Array<{
+        peerId: string;
+        multiaddr: string | null;
+    }>>;
+    /**
+     * Probe whether a given peer is an AUTHORIZED party member (see
+     * {@link listAuthorizedMembers}) — the gate the control-network wake and
+     * strand-address responders consult, NOT {@link isMember} (the addressable surface).
+     */
+    isAuthorizedMember(peerId: string): Promise<boolean>;
     /**
      * Push-wake a hibernating cadre peer over the control network.
      *
@@ -887,8 +927,8 @@ export declare class CadreNode implements SAppIdLookup {
     pushWake(targetPeerId: string, strandId: string, reason?: string): Promise<WakeAck>;
     /**
      * Enable the seed listener for receiving seeds via the /sereus/seed/1.0.0 protocol.
-     * This is for drone nodes that need to receive seeds without being an authority.
-     * Does not require an authority key.
+     * This is for drone nodes that need to receive seeds without being an owner.
+     * Does not require an owner key.
      */
     enableSeedListener(): void;
     /**
@@ -897,7 +937,7 @@ export declare class CadreNode implements SAppIdLookup {
     getSeedBootstrapService(): SeedBootstrapService | null;
     /**
      * 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.
      *
      * @param peerId - The peer ID to authorize
      * @param multiaddrs - Optional multiaddrs for the peer
@@ -905,14 +945,14 @@ export declare class CadreNode implements SAppIdLookup {
     authorizePeer(peerId: string, multiaddrs?: string[]): Promise<void>;
     /**
      * Remove a previously-authorized peer from the cadre.
-     * Signs the peer ID with the authority key and deletes the CadrePeer row.
+     * Signs the peer ID with the owner key and deletes the CadrePeer row.
      *
      * @param peerId - The peer ID to remove
      */
     removePeer(peerId: string): 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>;
     /**
@@ -921,7 +961,7 @@ export declare class CadreNode implements SAppIdLookup {
      * Validates the seed signature, then evaluates a trust anchor for the signer
      * key (see `SeedTrustPolicy`). An enrollment caller can pass a per-seed
      * `trustPolicy` override — e.g. a `pinnedKeyTrustPolicy` built from a
-     * `CadreInvite.authorityKeys` — so a cold-start node can accept its first
+     * `CadreInvite.ownerKeys` — so a cold-start node can accept its first
      * seed without reconfiguring the service.
      */
     applySeed(seed: ControlNetworkSeed, options?: {
@@ -976,7 +1016,7 @@ export declare class CadreNode implements SAppIdLookup {
      */
     decodeInvite(encoded: string): CadreInvite;
     /**
-     * Dial an authority from an invite (for phone joining via invite).
+     * Dial an owner from an invite (for phone joining via invite).
      */
     dialInvite(invite: CadreInvite): Promise<void>;
     /**