@serfab/cadre-core 1.16.0 → 1.18.0

package/README.md

@@ -149,8 +149,9 @@ const { seed, encodedSeed } = await node.addDrone({ dronePeerId, droneMultiaddrs
 
 // The new machine starts with it: `cadre start --seed <encodedSeed> --pin-owner-key <owner key>`
 
-// Dial the drone now from the addresses addDrone kept (a drone cannot dial a
-// phone); otherwise the next reconcile pass, about every 15 s, does it
+// Await the dial of the drone from the addresses addDrone kept (a drone cannot
+// dial a phone); the row insert starts a pass that dials it anyway, about 50 ms
+// later, and retries a failed dial after 15 s, 30 s, 60 s, then every 2 minutes
 await node.reconcileControlCohort();
 ```
 
@@ -194,7 +195,7 @@ The main entry point for cadre participation.
 | `publishStrand(id, type?, memberKey?)` | Owner-signed `Strand` row insert — makes the strand visible cadre-wide. Idempotent: a live row with the same `(Type, MemberPrivateKey)` is returned unwritten; different content on the same id throws. Prefer `foundStrand` when creating a strand |
 | `unpublishStrand(id)` | Owner-signed party-wide removal — deletes this party's `Strand` row; every node stops the strand. Destroys a closed strand's `MemberPrivateKey` |
 | `getEnrollmentService()` | Access peer enrollment API |
-| `isOwner()` | Whether this node can act as an owner of its cadre: its identity key is wired for signing and enrolled in `OwnerKey`. The gate the owner-only flows (`createCadreInvitation`, `claimNode`, `rentNode`) share with the apps |
+| `isOwner()` | Whether this node can act as an owner of its cadre: an owner key is wired for signing (`useOwnerSigner`) and is a live `OwnerKey` row; never the node's identity key. The gate the owner-only flows (`createCadreInvitation`, `createOwnerGrant`, `claimNode`, `rentNode`) share with the apps |
 | `invitationReach()` | Where a device could redeem an invitation minted now from, judged on the other members' addresses (`anywhere`, `local-network`, `issuer-only`), without minting one; `rentNode` chooses its join path by it |
 
 ### Events

package/dist/bootstrap-peer-store-file.js

@@ -2,7 +2,7 @@
  * Node-only file-backed {@link BootstrapPeerStore}: one JSON file per party under
  * a configured directory (the node's state directory — `cadre-cli` passes
  * `ResolvedConfig.nodeStateDir`), holding the node-local, non-replicated dial
- * targets learned out of band (a seed's owner peers, and nodes this node added).
+ * targets learned out of band (a seed's preferred peers, and nodes this node added).
  *
  * Nothing but the file itself lives here: the envelope, load policy, per-entry
  * validation (shape only — never signatures; see the `bootstrap-peer-store.ts`

package/dist/bootstrap-peer-store.d.ts

@@ -1,6 +1,6 @@
 import { type DurableSlot } from './node-local-snapshot.js';
 /**
- * One retained dial target learned out of band: an owner peer a seed nominated,
+ * One retained dial target learned out of band: a preferred peer a seed nominated,
  * or a node this node added.
  */
 export interface BootstrapPeerEntry {

package/dist/bootstrap-peer-store.js

@@ -3,10 +3,10 @@
  * out of band, kept so it can dial those peers when nothing better is known.
  * Two sources feed it:
  *
- *  - **A seed's owner peers.** A newcomer applies a signed seed nominating the
- *    party's owner machines and the addresses they answer on.
- *    `SeedBootstrapService.applySeed` dials those owners exactly once,
- *    best-effort; when that dial fails (owner briefly down, relay reservation not
+ *  - **A seed's preferred peers.** A newcomer applies a signed seed nominating
+ *    the machine that minted it and the party's always-on machines, with the
+ *    addresses they answer on. `SeedBootstrapService.applySeed` dials those peers
+ *    exactly once, best-effort; when that dial fails (peer briefly down, relay reservation not
  *    up, not yet vouched) the node has an empty `CadrePeer` table and no
  *    connection, and `CadreNode.reconcileControlCohort`'s cold-start branch is
  *    the only way back — it re-dials these retained addresses every pass.

package/dist/cadre-invite-protocol.d.ts

@@ -8,27 +8,29 @@
  * ownership) through `ControlDatabase.redeemCadreInvite`, and answers with the party id,
  * the row and dial hints. The owner that minted the invitation need not be online.
  *
- * Same shape as the seed and wake protocols: one length-prefixed JSON frame each way over
- * the shared primitives in `control-stream.ts`. Stranger-facing by design — the device is
- * not a member when it dials — so the connection gate admits a stranger while a live
- * invitation exists (`membership-connection-gater.ts`), and the handler's own trust
- * decision is the proof of possession: nothing touches the database for a caller that
- * cannot prove it holds the invitation and is the identity it names.
+ * The exchange shape — one frame each way, the member's hardening and admission of the
+ * device, the device's address-by-address dialing in passes — is `member-redemption.ts`'s,
+ * shared with the owner-grant protocol; this module supplies the invitation's bundle, request,
+ * checks, writes and refusal codes. Stranger-facing by design — the device is not a member
+ * when it dials — so the connection gate admits a stranger while a live invitation exists
+ * (`membership-connection-gater.ts`), and the handler's own trust decision is the proof of
+ * possession: nothing touches the database for a caller that cannot prove it holds the
+ * invitation and is the identity it names.
  *
  * The seed protocol is left untouched so `SeedMessage` can grow independently.
  */
 import type { Libp2p } from '@libp2p/interface';
-import { type ControlStream } from './control-stream.js';
 import { type ControlDatabase } from './control-database.js';
-import type { CadreInviteRow, CadreJoinProgress, SeedPeer } from './types.js';
+import { MemberRedemptionHandler, type MemberRedemption, type MemberRedemptionHandlerOptions, type RedemptionAddressOutcome, type RedemptionRejection } from './member-redemption.js';
+import type { CadreInviteRow, CadreJoinProgress, PeerAddressRecord, SeedPeer } from './types.js';
 /** Protocol id for cadre invitation redemption (parallel to `/sereus/seed/1.0.0`). */
 export declare const CADRE_INVITE_PROTOCOL = "/sereus/cadre-invite/1.0.0";
 /**
  * What an owner hands out (QR, paste, link) and a device redeems. An invitation is an
  * ed25519 keypair: the row holds the public half, `invitePrivateKey` is the proof of
  * possession, and whoever holds this bundle can redeem it — treat it as a bearer
- * credential for the row's lifetime (an untargeted owner-granting one defaults to a
- * 15-minute expiry for that reason).
+ * credential for the row's lifetime. It admits a machine and grants nothing else; an owner
+ * grant (`owner-grant-protocol.ts`) is the credential that makes a key an owner.
  *
  * Carrying the signed row is what makes redemption work at a member that has not received
  * the row by replication: the member seats it from the bundle under its stored issuer
@@ -60,7 +62,8 @@ export interface CadreInvitation {
 /**
  * Encode a bundle for out-of-band delivery: {@link CADRE_INVITATION_PREFIX}, then base64url
  * over JSON. The prefix lets an app tell an invitation from a join request
- * (`cadre-join-request.ts`) and name the mistake when one is pasted for the other.
+ * (`cadre-join-request.ts`) or an owner grant (`owner-grant-protocol.ts`) and name the mistake
+ * when one is pasted for the other.
  */
 export declare function encodeCadreInvitation(invitation: CadreInvitation): string;
 /**
@@ -69,21 +72,31 @@ export declare function encodeCadreInvitation(invitation: CadreInvitation): stri
  * without a node (a settings screen that wants to show which cadre an invitation joins) can
  * decode one.
  *
- * @throws on a join request, a string without the prefix or that is not base64url JSON after
- *   it, or one that decodes to another shape or version.
+ * @throws on an owner key, an owner grant or a join request, a string without the prefix or
+ *   that is not base64url JSON after it, or one that decodes to another shape or version.
  */
 export declare function decodeCadreInvitation(encoded: string): CadreInvitation;
+/**
+ * The device's own address record as a request carries it: a {@link PeerAddressRecord} without
+ * the peer id, which the connection gives, and the key, which is the request's `peerKey`.
+ */
+export type RedeemSelfRecord = Pick<PeerAddressRecord, 'addrs' | 'updatedAt' | 'profile' | 'sig'>;
 /** Device → member: one frame, the whole redemption. */
 export interface CadreInviteRedeemRequest {
-    v: 1;
+    v: 2;
     /** The cadre the device believes it is joining; a machine serving another party refuses by name. */
     partyId: string;
     /** The owner-signed row from the bundle. */
     invite: CadreInviteRow;
     /** The device's ed25519 public key, base64url; must be the key behind the connecting peer id. */
     peerKey: string;
-    /** The device's dialable addresses; empty for a phone. Stored on its `CadrePeer` row. */
-    multiaddrs: string[];
+    /**
+     * The device's own address record for its `CadrePeer` row, self-signed for the invitation's
+     * party as `CadreNode.registerSelf` signs it (`signPeerRecord`); `addrs` is empty for a phone.
+     * The member stores `addrs` and, when the signature verifies over them, the rest of the
+     * record too ({@link admittedRecord}), so the device's first publish is its admission.
+     */
+    record: RedeemSelfRecord;
     /** Single-use nonce the device minted (`generateStampId`); both signatures cover it. */
     usageStampId: string;
     /** By `invitePrivateKey` over the `'redeem'` digest. */
@@ -112,7 +125,7 @@ export type CadreInviteRejectionCode =
  | 'party-mismatch'
 /** The member is at its cap on concurrent redemptions. */
  | 'busy'
-/** The write failed transiently (the write retry gave up); nothing was recorded. */
+/** The write failed transiently (the write retry gave up), or the member has not synced the invitation row the cadre holds; nothing was recorded. */
  | 'conflict'
 /**
  * An unexpected member-side failure, or a request frame the member could not read (timed
@@ -137,8 +150,9 @@ export interface CadreInviteRedeemReply {
     invite?: CadreInviteRow;
     /**
      * Dial hints for the rest of the cadre, unsigned: the member's own projection of its
-     * `CadrePeer` rows (`ControlDatabase.querySeedPeers`). `isOwner` is a dial hint only, as
-     * the seed's NOTE says; the device derives trust from its anchor, never from this.
+     * `CadrePeer` rows (`ControlDatabase.querySeedPeers`), the answering member and every
+     * always-on machine marked `preferred`. The device derives trust from its anchor, never
+     * from this.
      */
     peers?: SeedPeer[];
 }
@@ -149,6 +163,8 @@ export interface CadreInviteAccepted extends CadreInviteRedeemReply {
     invite: CadreInviteRow;
     peers: SeedPeer[];
 }
+/** A refusal as the member sends it: a code, a reason, nothing else. */
+type CadreInviteRejection = RedemptionRejection<CadreInviteRejectionCode>;
 /**
  * A member answered and refused. `code` is `'unrecognized'` when the frame carried none this
  * build knows (the two machines may run different versions), and such a refusal counts as
@@ -161,12 +177,8 @@ export declare class CadreInviteRejectedError extends Error {
     /** Both arguments come straight off the wire, so neither is trusted to have its declared type. */
     constructor(code: unknown, reason: unknown);
 }
-/** What one address the bundle named came to. */
-export interface CadreInviteAddressOutcome {
-    addr: string;
-    /** A dial or exchange failure, or a retryable {@link CadreInviteRejectedError}. */
-    error: Error;
-}
+/** What one address the bundle named came to; the owner-grant redemption reports the same shape. */
+export type CadreInviteAddressOutcome = RedemptionAddressOutcome;
 /**
  * Every address the bundle names was tried and none accepted: each failed to dial, answered
  * malformed, or refused retryably. Always retryable; `outcomes` says what each address did.
@@ -207,8 +219,12 @@ export interface RedeemSigner {
  * (invitation key, `usageStampId`, device key) for the invitation's party. The same bytes
  * the schema verifies at the member (`cadreInviteRedeemMessage` / `cadreInviteConsentMessage`),
  * whose own `party_id()` must therefore be the party the bundle names.
+ *
+ * @param record - the device's address record, already signed for the invitation's party over
+ *   sanitized addresses ({@link sanitizeAddrs}); copied in unchanged, since the signature
+ *   covers the exact list.
  */
-export declare function signRedeemRequest(invitation: CadreInvitation, signer: RedeemSigner, usageStampId: string, multiaddrs: string[]): CadreInviteRedeemRequest;
+export declare function signRedeemRequest(invitation: CadreInvitation, signer: RedeemSigner, usageStampId: string, record: RedeemSelfRecord): CadreInviteRedeemRequest;
 /**
  * The device's check on an acceptance: the same party, the same invitation key, and a row
  * signed by an issuer the device pinned from the bundle. Throws
@@ -222,100 +238,40 @@ export declare function signRedeemRequest(invitation: CadreInvitation, signer: R
  */
 export declare function verifyRedeemReply(reply: CadreInviteAccepted, invitation: CadreInvitation, isTrustedIssuer: (ownerKey: string) => boolean): void;
 /** The control-database surface a redemption needs; a `ControlDatabase` satisfies it. */
-export type CadreInviteStore = Pick<ControlDatabase, 'seatCadreInvite' | 'isCadreInviteLive' | 'redeemCadreInvite' | 'querySeedPeers'>;
-export interface CadreInviteHandlerOptions {
-    /** This member's party id; a request for another party is refused by name. */
-    partyId: string;
+export type CadreInviteStore = Pick<ControlDatabase, 'queryCadreInvite' | 'seatCadreInvite' | 'isCadreInviteLive' | 'redeemCadreInvite' | 'querySeedPeers'>;
+export interface CadreInviteHandlerOptions extends MemberRedemptionHandlerOptions {
+    /** This member's peer id: the reply's peer list marks it preferred, since the device just reached it. */
+    peerId: string;
     store: CadreInviteStore;
-    /**
-     * Push this member's control store to the device, resolving once the push has finished, and
-     * keep the device counted in this member's control write cohort until the returned release
-     * is called. Called after the request verified and before the row is seated and the
-     * admission is written; the handler releases once both have settled. Absent, the writes go
-     * ahead with the device neither caught up nor in the cohort, so it does not hold them; see
-     * `admitDeviceIfLive`.
-     */
-    admitDevice?: (peerId: string) => Promise<() => void>;
-    /** Time to wait for the request frame; default {@link DEFAULT_REDEEM_READ_TIMEOUT_MS}. */
-    redeemReadTimeoutMs?: number;
-    /** Cap on concurrent inbound redemptions; default {@link DEFAULT_MAX_CONCURRENT_REDEMPTIONS}. */
-    maxConcurrentRedemptions?: number;
 }
 /**
- * Member side: registers the handler and drives each inbound stream through the checks in
- * cost order — shape, connecting identity, both signatures, target device — so no database
- * work happens for a stranger that cannot prove anything, then admits the device to this
- * member's control replication (`admitDevice`), seats the row and redeems.
- * Hardened as the seed handler is: a concurrency cap (over it, `busy`) and a read timeout.
- *
- * Registered only by a started `CadreNode`, after its control database is up, like the
- * formation responder; nothing here is reachable on a node without one.
+ * Member side of the invitation protocol (`MemberRedemptionHandler` has the shape): after the
+ * request's shape, it checks the party, the connecting identity (an ed25519 peer id is an
+ * identity multihash of the very key, and this is the only layer that can check the pair),
+ * both signatures and a targeted invitation's device, then seats the row from the bundle when
+ * this member holds none and redeems. An issuer this member does not know as an owner is the
+ * one retryable refusal left: the device tries the next address, which may hold the issuer's row.
  */
-export declare class CadreInviteHandler {
-    private readonly options;
-    private readonly readTimeoutMs;
-    private readonly maxConcurrent;
-    private readonly registered;
-    private active;
+export declare class CadreInviteHandler extends MemberRedemptionHandler<CadreInviteRedeemRequest, CadreInviteRedeemReply, CadreInviteRow> {
+    private readonly peerId;
+    private readonly store;
+    protected readonly busyRefusal: RedemptionRejection<"busy">;
+    protected readonly internalRefusal: RedemptionRejection<"internal">;
+    protected readonly malformedRefusal: RedemptionRejection<"invite-invalid">;
     constructor(options: CadreInviteHandlerOptions);
-    /** In-flight inbound redemptions. */
-    get activeCount(): number;
-    /**
-     * Register on `node`; rejects when libp2p refuses the registration. `runOnLimitedConnection`
-     * because a phone redeems through a relay, whose connection libp2p marks limited; the
-     * exchange is two small frames, well inside any relay's cap.
-     */
-    register(node: Libp2p, protocolId?: string): Promise<void>;
-    unregister(node: Libp2p, protocolId?: string): Promise<void>;
+    protected isWellFormedRequest(value: unknown): value is CadreInviteRedeemRequest;
+    protected checkRequest(request: CadreInviteRedeemRequest, remotePeerId: string): CadreInviteRejection | null;
+    protected readHeld(request: CadreInviteRedeemRequest): Promise<CadreInviteRow | null>;
+    protected isLive(request: CadreInviteRedeemRequest, held: CadreInviteRow | null): Promise<boolean>;
     /**
-     * One inbound redemption: read the frame, decide, reply, close. Public as the seam the
-     * protocol spec drives directly; `remotePeerId` is the connection's authenticated peer.
+     * The two writes — the seat (its own transaction), only when this member holds no row, and
+     * the redemption — each answered by name when it fails. The held row is carried into the
+     * redemption so it is not read again in the write lock; after a fresh seat nothing is carried
+     * and the redemption reads the row it seated, since the bundle's copy is the requester's.
      */
-    handleStream(stream: ControlStream, remotePeerId: string): Promise<void>;
-    /**
-     * Read the request frame to EOF, bounded and size-capped; JSON only, shape is `decide`'s.
-     * Throws on a frame that cannot be read, which {@link handleStream} answers `internal`:
-     * a read timeout or a cut frame proves nothing about the invitation, so the device must
-     * stay free to try the next address.
-     */
-    private readRequest;
-    private decide;
-    /**
-     * The checks that cost no database work, in order: shape, party, connecting identity (an
-     * ed25519 peer id is an identity multihash of the very key, and this is the only layer that
-     * can check the pair), both signatures, and a targeted invitation's device.
-     */
-    private checkRequest;
-    /**
-     * Admit the device to this member's control replication (see {@link admitDeviceIfLive}),
-     * seat the row from the bundle (its own transaction; a no-op when held), then redeem. The
-     * admission comes first because the seat is already a write the device takes part in. An
-     * issuer this member does not know as an owner is the one retryable refusal left: the device
-     * tries the next address, which may hold the issuer's row.
-     */
-    private seatAndRedeem;
-    /** {@link seatAndRedeem}'s two writes, each answered by name when it fails. */
-    private seatAndRedeemAdmitted;
-    /**
-     * Admit the device to this member's control replication before the first write of the
-     * exchange (the seat, when this member does not hold the row; otherwise the admission), and
-     * resolve to the release that ends the admission. The device is not a member until the
-     * admission is written, so only this puts it in this member's control write cohort, and it
-     * must be there to hold the rows that admit it. It is pushed the control store first,
-     * because a cohort node with no base revision of a block refuses a commit to it; a member
-     * alone with the device would then have half its cohort refusing, and the write would tear
-     * instead of committing.
-     *
-     * Only for an invitation still live here, judged on the row this member holds or, before
-     * the seat, on the bundle's copy once its issuer signature verifies
-     * (`ControlDatabase.isCadreInviteLive`): the holder of a withdrawn, expired or spent one,
-     * or of a forged copy naming a real owner, is refused without being sent anything. The
-     * retry of an admission already written can read as spent too and is sent nothing; it
-     * needs nothing, since the device is a member and the ordinary catch-up reaches it.
-     * Best-effort: a failed check or push is logged and the writes go ahead without the device
-     * admitted, then commit or are answered retryably.
-     */
-    private admitDeviceIfLive;
+    protected redeemAdmitted(request: CadreInviteRedeemRequest, remotePeerId: string, held: CadreInviteRow | null): Promise<CadreInviteRedeemReply>;
+    /** Seat the bundle's copy of the row; a refusal answered by name, or null once it is held. */
+    private seat;
     /** Dial hints are an optimization; a failed read costs the device its hints, not its membership. */
     private peersBestEffort;
 }
@@ -326,11 +282,7 @@ export interface RedeemAtMembersOptions {
     request: CadreInviteRedeemRequest;
     /** Is this owner key one the device pinned from the bundle? The reply check's input. */
     isTrustedIssuer: (ownerKey: string) => boolean;
-    /**
-     * This machine's declared link round trip (`NetworkConfig.linkRoundTripMs`), from which
-     * the per-address deadline derives: a dial that may need a relay plus one request
-     * (`relayedRequestBudgetMs`, 28.5 s at the default declaration), as seed delivery's is.
-     */
+    /** See `MemberRedemptionOptions.linkRoundTripMs`. */
     linkRoundTripMs?: number;
     /** Per-address deadline override; default derived from `linkRoundTripMs`. */
     addressBudgetMs?: number;
@@ -339,21 +291,14 @@ export interface RedeemAtMembersOptions {
     signal?: AbortSignal;
 }
 /** What a successful redemption yields the device. */
-export interface CadreInviteRedemption {
-    reply: CadreInviteAccepted;
-    /** The answering member's peer id, from the address's trailing `/p2p/`; null when it named none. */
-    memberPeerId: string | null;
-    /** The address that answered. */
-    memberAddr: string;
-}
+export type CadreInviteRedemption = MemberRedemption<CadreInviteAccepted>;
 /**
  * Device side: try the bundle's addresses one at a time, each under its own deadline, and
- * stop at the first acceptance or the first final refusal. A dial failure, a malformed
- * reply or a retryable refusal moves to the next address.
- *
- * Every address gets the SAME request, with one `usageStampId`: `CadreInviteUsage` is keyed
- * by it, so a member the device gave up on that was still committing cannot admit it twice,
- * and a retry at the next member after a dropped reply is answered as already a member.
+ * stop at the first acceptance or the first final refusal (`dialRedemption` in
+ * `member-redemption.ts`). Every address gets the SAME request, with one `usageStampId`:
+ * `CadreInviteUsage` is keyed by it, so a member the device gave up on that was still
+ * committing cannot admit it twice, and a retry at the next member after a dropped reply is
+ * answered as already a member.
  *
  * @throws {CadreInviteRejectedError} on a final refusal (its `retryable` is false).
  * @throws {CadreInviteReplyInvalidError} on an acceptance that fails {@link verifyRedeemReply}.
@@ -368,16 +313,10 @@ export interface RedeemInPassesOptions extends RedeemAtMembersOptions {
     onProgress?: (progress: CadreJoinProgress) => void;
 }
 /**
- * Device side, in passes: one {@link redeemAtMembers} pass over the bundle's addresses, or,
- * with `waitForMember`, as many as it takes, pausing between them (5 s after the first,
- * doubling to 60 s, never past the invitation's expiry). Every pass sends the same signed
- * request, so a member that admitted the device on a pass whose reply was lost answers a later
- * pass as already a member, with no second usage row.
- *
- * A wait ends at the first acceptance, at a final refusal or an invalid reply (thrown as
- * {@link redeemAtMembers} throws them), when the invitation expires by this device's clock
- * (thrown as the `invite-spent` refusal a member would give), when `signal` aborts (its reason
- * thrown), and when `node` stops. A bundle that names no address has nothing to wait for and
- * throws at once.
+ * Device side, in passes (`dialRedemptionInPasses` in `member-redemption.ts`): one
+ * {@link redeemAtMembers} pass, or, with `waitForMember`, as many as it takes, pausing between
+ * them and never past the invitation's expiry, which by this device's clock is thrown as the
+ * `invite-spent` refusal a member would give.
  */
 export declare function redeemInPasses(node: Libp2p, options: RedeemInPassesOptions): Promise<CadreInviteRedemption>;
+export {};