@serfab/cadre-core 1.13.0 → 1.14.0

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

@@ -0,0 +1,348 @@
+/**
+ * Cadre invitation redemption transport: `/sereus/cadre-invite/1.0.0`.
+ *
+ * A device holding a cadre invitation (an owner-signed `CadreInvite` row plus the private
+ * half of the invitation keypair, see {@link CadreInvitation}) dials ANY member machine the
+ * invitation names and proves possession; the member seats the row if it does not hold it
+ * yet, writes the device's `CadrePeer` row (and `OwnerKey` row, when the invitation grants
+ * 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 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, 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).
+ *
+ * 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
+ * signature. The row's own signature covers every column, so a bundle whose row was
+ * altered cannot be seated anywhere.
+ */
+export interface CadreInvitation {
+    v: 1;
+    /** The cadre the invitation joins; a device refuses one for another party. */
+    partyId: string;
+    /** The invitation's ed25519 seed, base64url: the proof of possession. */
+    invitePrivateKey: string;
+    /** The owner-signed row exactly as issued (`ControlDatabase.insertCadreInvite`). */
+    invite: CadreInviteRow;
+    /**
+     * The issuer's anchored owner keys. The redeeming device pins them before it dials
+     * (`CadreNode.trustOwnerKeys`) and checks the member's reply against them. Sourced from
+     * the issuer's node-local anchor only, never the replicated `OwnerKey` table, for the
+     * reason the seed invite gives: the device anchors whatever arrives here.
+     */
+    ownerKeys: string[];
+    /**
+     * Multiaddrs ending in `/p2p/<peerId>`: the issuer's own first, then up to
+     * `INVITATION_SIBLING_MACHINES` other members (`invitation-bootstrap.ts`). The device
+     * tries them in order.
+     */
+    members: string[];
+}
+/** Encode a bundle for out-of-band delivery: base64url over JSON, as seeds and open invitations are. */
+export declare function encodeCadreInvitation(invitation: CadreInvitation): string;
+/**
+ * Decode a bundle, refusing anything that is not a well-formed version-1
+ * {@link CadreInvitation}. Standalone so a client without a node (a settings screen that
+ * wants to show which cadre an invitation joins) can decode one.
+ *
+ * @throws on a string that is not base64url JSON, or decodes to another shape or version.
+ */
+export declare function decodeCadreInvitation(encoded: string): CadreInvitation;
+/** Device → member: one frame, the whole redemption. */
+export interface CadreInviteRedeemRequest {
+    v: 1;
+    /** 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[];
+    /** Single-use nonce the device minted (`generateStampId`); both signatures cover it. */
+    usageStampId: string;
+    /** By `invitePrivateKey` over the `'redeem'` digest. */
+    inviteSig: string;
+    /** By the device's identity key over the `'consent'` digest. */
+    peerSig: string;
+}
+/**
+ * Why a member refused a redemption. Retryability is {@link CADRE_INVITE_REJECTION_RETRYABLE}'s;
+ * a retryable code moves the device to the next address the bundle names.
+ */
+export type CadreInviteRejectionCode = 
+/**
+ * The issuer's `OwnerKey` row is not on this member (not replicated yet), or the issuer was
+ * removed; the member cannot tell which, so the device tries the next address.
+ */
+'issuer-unknown'
+/**
+ * A signature does not verify, the peer key is not the connecting identity, the request or
+ * the row is malformed, or the invitation names another device.
+ */
+ | 'invite-invalid'
+/** Expired, withdrawn, exhausted, or issued by a key that is no longer an owner here. */
+ | 'invite-spent'
+/** This machine serves another cadre than the one the invitation names. */
+ | 'party-mismatch'
+/** The member is at its cap on concurrent redemptions. */
+ | 'busy'
+/** The write failed transiently (the write retry gave up); nothing was recorded. */
+ | 'conflict'
+/**
+ * An unexpected member-side failure, or a request frame the member could not read (timed
+ * out, oversized, not JSON): nothing was proved either way, so the device tries the next
+ * address, as the formation responder's `internal` is read.
+ */
+ | 'internal';
+/** Which refusals are worth repeating at the next address — the one place that says so. */
+export declare const CADRE_INVITE_REJECTION_RETRYABLE: Readonly<Record<CadreInviteRejectionCode, boolean>>;
+/** Is `value` a code this build knows? Own keys only, so a peer's `'constructor'` does not pass. */
+export declare function isCadreInviteRejectionCode(value: unknown): value is CadreInviteRejectionCode;
+/** Member → device. */
+export interface CadreInviteRedeemReply {
+    accepted: boolean;
+    /** Present iff `!accepted`. */
+    code?: CadreInviteRejectionCode;
+    /** Human-facing text; present iff `!accepted`. */
+    reason?: string;
+    /** The member's party id; present iff `accepted`. */
+    partyId?: string;
+    /** The invitation row as this member holds it; present iff `accepted`. */
+    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.
+     */
+    peers?: SeedPeer[];
+}
+/** An accepting reply, every optional field present. */
+export interface CadreInviteAccepted extends CadreInviteRedeemReply {
+    accepted: true;
+    partyId: string;
+    invite: CadreInviteRow;
+    peers: SeedPeer[];
+}
+/**
+ * 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
+ * retryable: trying the next address on an unknown answer is safe, giving up is not.
+ */
+export declare class CadreInviteRejectedError extends Error {
+    readonly code: CadreInviteRejectionCode | 'unrecognized';
+    readonly reason: string;
+    readonly retryable: boolean;
+    /** 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;
+}
+/**
+ * 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.
+ */
+export declare class CadreInviteUnreachableError extends Error {
+    readonly outcomes: readonly CadreInviteAddressOutcome[];
+    readonly retryable = true;
+    constructor(outcomes: readonly CadreInviteAddressOutcome[]);
+}
+/**
+ * A member accepted but its reply does not check out: another party id, another invitation
+ * key, or a row not signed by one of the pinned owner keys. Final: a machine that answers
+ * like this is not a member of the cadre the invitation names, and the row it wrote (if any)
+ * is in a database the device will never trust.
+ */
+export declare class CadreInviteReplyInvalidError extends Error {
+    readonly retryable = false;
+    constructor(message: string);
+}
+/** Is `value` a {@link CadreInviteRow} with every column in its stored form and bounded? */
+export declare function isWellFormedCadreInviteRow(value: unknown): value is CadreInviteRow;
+/**
+ * Keep only parsable, distinct multiaddr strings, capped at {@link MAX_ADDRS}, order kept.
+ * Applied on both sides: the member bounds what it stores on the device's row, the device
+ * bounds what it merges into its peer store. A malformed entry is skipped, not fatal.
+ */
+export declare function sanitizeAddrs(addrs: unknown): string[];
+/** What the device signs with: its identity keypair in the crypto plugin's base64url form. */
+export interface RedeemSigner {
+    /** The device's ed25519 public key, base64url — the key behind its peer id. */
+    peerKey: string;
+    /** The device's ed25519 seed, base64url. */
+    peerPrivateKey: string;
+}
+/**
+ * Build and sign the request for `invitation`: the holder's `'redeem'` signature with the
+ * invitation's private key and the device's `'consent'` signature with its own, both over
+ * (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.
+ */
+export declare function signRedeemRequest(invitation: CadreInvitation, signer: RedeemSigner, usageStampId: string, multiaddrs: string[]): 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
+ * {@link CadreInviteReplyInvalidError} naming the first failure.
+ *
+ * What it proves is bounded: the request already carried the owner-signed row, so a machine
+ * that is not a member can echo it. The check catches a reply for another party or
+ * invitation and a row the pinned owners never signed; whether the answering machine is a
+ * member is settled afterwards, when the device syncs the control database and judges every
+ * row against its anchor (`CadreNode.listAuthorizedMembers`).
+ */
+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;
+    store: CadreInviteStore;
+    /**
+     * Push this member's control store to the device and resolve once the push has finished,
+     * called after the request verified and before the row is seated and the admission is
+     * written. Absent, the writes go ahead with the device holding nothing; see
+     * `catchUpDeviceIfLive` for why that tears on a member alone with the device.
+     */
+    catchUpDevice?: (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 hands the device the control
+ * store (`catchUpDevice`), 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.
+ */
+export declare class CadreInviteHandler {
+    private readonly options;
+    private readonly readTimeoutMs;
+    private readonly maxConcurrent;
+    private readonly registered;
+    private active;
+    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>;
+    /**
+     * 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.
+     */
+    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;
+    /**
+     * Hand the device this member's control store, seat the row from the bundle (its own
+     * transaction; a no-op when held), then redeem. The push comes first because the seat is
+     * already a write the device takes part in (see {@link catchUpDeviceIfLive}). 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;
+    /**
+     * Push this member's control store to the device before the first write of the exchange
+     * (the seat, when this member does not hold the row; otherwise the admission). The device
+     * joined this member's control write cohort when it connected, and a cohort node with no
+     * base revision of a block refuses a commit to it; a member alone with the device then has
+     * half its cohort refusing, and the write tears instead of committing. With the store in
+     * hand the device holds the write too.
+     *
+     * 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, then commit or are
+     * answered retryably.
+     */
+    private catchUpDeviceIfLive;
+    /** Dial hints are an optimization; a failed read costs the device its hints, not its membership. */
+    private peersBestEffort;
+}
+export interface RedeemAtMembersOptions {
+    /** The bundle: its `members` are dialed in order. */
+    invitation: CadreInvitation;
+    /** The signed request ({@link signRedeemRequest}); the same one goes to every address. */
+    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.
+     */
+    linkRoundTripMs?: number;
+    /** Per-address deadline override; default derived from `linkRoundTripMs`. */
+    addressBudgetMs?: number;
+    protocolId?: string;
+}
+/** 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;
+}
+/**
+ * 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.
+ *
+ * @throws {CadreInviteRejectedError} on a final refusal (its `retryable` is false).
+ * @throws {CadreInviteReplyInvalidError} on an acceptance that fails {@link verifyRedeemReply}.
+ * @throws {CadreInviteUnreachableError} when every address was tried and none accepted.
+ */
+export declare function redeemAtMembers(node: Libp2p, options: RedeemAtMembersOptions): Promise<CadreInviteRedemption>;