@serfab/cadre-core 1.9.0 → 1.11.0

package/dist/cadre-node.d.ts

@@ -1,6 +1,6 @@
 import type { Libp2p, PeerId } from '@libp2p/interface';
 import type { Multiaddr } from '@multiformats/multiaddr';
-import type { CadreNodeConfig, StrandInstance, StrandRow, StrandConfig, FoundStrandConfig, FoundStrandResult, SAppConfig, CadreNodeEvents, ControlNetworkSeed, ApplySeedResult, AddDroneOptions, AddPhoneOptions, DroneInitResult, InviteResult, CadreInvite, OpenInvitation, FormStrandResult, StrandFormationDisclosure, StrandMembershipInvite, ResolveOpts, SelfRegistrationOutcome, ServiceWakeResult, PushPlatform, DeviceTokenRecord, ResolveDeviceTokenOpts } from './types.js';
+import type { CadreNodeConfig, StrandInstance, StrandRow, StrandConfig, FoundStrandConfig, FoundStrandResult, SAppConfig, CadreNodeEvents, ControlNetworkSeed, ApplySeedResult, AddDroneOptions, AddPhoneOptions, DroneInitResult, InviteResult, CadreInvite, OpenInvitation, FormStrandResult, StrandFormationDisclosure, StrandMembershipInvite, ResolveOpts, SelfRegistrationOutcome, ServiceWakeResult, PushPlatform, DeviceTokenRecord, ResolveDeviceTokenOpts, PendingJoinStatus } from './types.js';
 import { type Ed25519KeyPair } from './ed25519-key.js';
 import { type TrustedOwnerStore, type TrustSource } from './trusted-owner-store.js';
 import { type BootstrapPeerStore } from './bootstrap-peer-store.js';
@@ -84,6 +84,15 @@ export declare class CadreNode implements SAppIdLookup {
     private enrollmentService;
     private seedBootstrapService;
     private strandSolicitationService;
+    /**
+     * The service whose formation handler is registered on the control node. Trails
+     * {@link strandSolicitationService} while {@link initializeStrandSolicitation} swaps a new
+     * one in: the field is set at once so concurrent callers reuse it, the handler only when
+     * its queued swap runs.
+     */
+    private registeredSolicitation;
+    /** Tail of the queued formation-handler swaps ({@link swapFormationResponder}). */
+    private solicitationSwaps;
     private strandWakeService;
     /**
      * Control-network strand-address responder. Answers a co-cadre sibling's
@@ -382,6 +391,20 @@ export declare class CadreNode implements SAppIdLookup {
      * `unpublishStrand` / `forgetJoinedStrand` as {@link formationStrandAddrs} is.
      */
     private readonly pendingMembershipInvites;
+    /**
+     * Invite keys of the membership invitations this process has staged, by
+     * {@link adoptFormationMembershipInvite} or from a `joined` `PendingJoin` row
+     * ({@link stageMembershipInvitesFromPendingJoins}), so one the reconciler has settled is not
+     * staged again by the next pending-join pass. Same lifetime as
+     * {@link pendingMembershipInvites}: a restarted process stages each live one once more, and the
+     * reconciler settles it again (spent, or the party already seated).
+     */
+    private readonly stagedMembershipInviteKeys;
+    /**
+     * The pending-join retry loop (`pending-join-runner.ts`): built by {@link start}, stopped by
+     * {@link cleanup}. It acts only while this machine is an enrolled owner.
+     */
+    private pendingJoinRunner;
     /**
      * Founder launches refused because the strand was founded before the per-party
      * identity split (`PreSplitStrandIdentityError`), keyed by strandId. Read by
@@ -589,23 +612,6 @@ export declare class CadreNode implements SAppIdLookup {
     private controlConnectionOpenHandler;
     /** `connection:close` listener re-arming the growth edge (teardown in {@link stopRecordRefresh}). */
     private controlConnectionCloseHandler;
-    /**
-     * Hooks `globalThis.RTCPeerConnection` to observe whether ICE selected a TURN
-     * relay candidate for each WebRTC session. Installed in {@link start}, disposed
-     * in {@link cleanup}; inert on Node.js (no `RTCPeerConnection`).
-     */
-    private readonly turnTracker;
-    /**
-     * Peer IDs whose current WebRTC connection was observed to be TURN-relayed.
-     * Populated by {@link handleTurnConnectionOpen} (drains the tracker queue on a
-     * `/webrtc` `connection:open`), cleared per-peer on `connection:close`. Read by
-     * {@link getConnectionPaths} to promote `webrtc` → `webrtc-turn` (relayed).
-     */
-    private turnRelayedPeers;
-    /** `connection:open` listener feeding TURN detection (teardown in {@link stopRecordRefresh}). */
-    private turnConnectionOpenHandler;
-    /** `connection:close` listener clearing a peer's TURN flag (teardown in {@link stopRecordRefresh}). */
-    private turnConnectionCloseHandler;
     constructor(config: CadreNodeConfig);
     /**
      * SAppIdLookup implementation - get sAppId for a strand: the claiming config's, else
@@ -966,11 +972,9 @@ export declare class CadreNode implements SAppIdLookup {
      *     `StrandSolicitationService.hasOutstandingInvitation`). A formation
      *     initiator is another party's peer by design and its token is only
      *     checkable inside the protocol, so the gate asks the coarser question
-     *     "does this node expect a stranger at all?". Merely REGISTERING the
-     *     responder ({@link initializeStrandSolicitation}) no longer suspends
-     *     stranger denial — eager registration (as `reference-app-rn` does at
-     *     bring-up) and `formStrand`'s lazy initialization both leave the gate
-     *     armed, because neither mints an invitation.
+     *     "does this node expect a stranger at all?". REGISTERING the responder
+     *     does not suspend stranger denial: every node registers one at
+     *     {@link start}, and registering mints no invitation.
      *
      * Ordering is semantically free (the checks are OR'd) but decides who pays:
      * checks 1-3 are in-memory, 4/5 share one control-DB read, and only a peer
@@ -1002,6 +1006,11 @@ export declare class CadreNode implements SAppIdLookup {
      * layer is fail-open behind `ADMISSION_DECISION_TIMEOUT_MS`, so the live
      * read is safe here — unlike the per-stream gate, which must consult the
      * materialized {@link authorizedControlPeers} snapshot instead.
+     * NOTE: check 6 adds a second control read (`hasOutstandingFormationInvite`) for a
+     * stranger with no locally minted invitation in play, on every node now that every
+     * node runs the responder — a relay-enabled storage node included. If stranger
+     * connections to such a node ever arrive fast enough for that read to show, cache
+     * the answer for a few seconds.
      * NOTE: on a relay-DISABLED node, a sibling whose membership row has not yet
      * replicated here is denied until the row converges (typically via the
      * owner); either side's next outbound reconcile dial (outbound is never
@@ -1344,6 +1353,12 @@ export declare class CadreNode implements SAppIdLookup {
      * handling, is what keeps a mixed list from taking a whole peer offline.
      */
     resolvePeerAddrs(peerId: string, opts?: ResolveOpts): Promise<Multiaddr[]>;
+    /**
+     * {@link resolvePeerAddrs} with the record's `UpdatedAt` kept beside the addresses, for a
+     * caller that ranks peers by how recently they published. `null` wherever that returns `[]`
+     * for a failed gate.
+     */
+    private resolvePeerRecord;
     /**
      * Guarantee every address handed to a control-network dial terminates in
      * `/p2p/<peerId>`, with no duplicates — the invariant every dial path
@@ -1537,15 +1552,18 @@ export declare class CadreNode implements SAppIdLookup {
      *
      * The list may name transports this node cannot dial (a lent node reports TCP
      * and `/ws` addresses to a phone that dials WebSockets only). That needs no
-     * filtering here: libp2p's dial queue (`calculateMultiaddrs`, libp2p 3.1.3)
+     * filtering here: libp2p's dial queue (`calculateMultiaddrs`, libp2p 3.3.11)
      * rejects an address no transport can dial before touching the network, so
      * such an address costs a log line.
      *
      * The list is NOT handed to one `dial()`. libp2p tries a multi-address dial's
-     * addresses one after another under a single deadline, with no limit per
-     * address, and sorts loopback addresses last — so one or two addresses that
-     * never answer used up the whole deadline before the address that worked was
-     * tried. {@link dialPeerAddrs} dials each address on its own time limit instead.
+     * addresses one after another under a single deadline, and sorts loopback
+     * addresses last — so one or two addresses that never answer use up most of
+     * the deadline before the address that works is tried. libp2p 3.3's
+     * per-address `addressDialTimeout` does not prevent that: cadre sizes it for a
+     * cold relayed open through two admission decisions (`optimysticDialLimits`,
+     * 39 s at the default declared link).
+     * {@link dialPeerAddrs} dials each address on its own time limit instead.
      */
     private resolveControlDialAddrs;
     /**
@@ -1817,16 +1835,6 @@ export declare class CadreNode implements SAppIdLookup {
      * Idempotent.
      */
     private wireControlConnectionListeners;
-    /**
-     * On a control connection opening: if it is a WebRTC connection, drain the TURN
-     * tracker for the just-settled ICE verdict and, when it relayed, mark the peer
-     * so {@link getConnectionPaths} classifies it `webrtc-turn` (relayed). The
-     * settlement↔open correlation is timing-based and best-effort; an unknown
-     * verdict degrades to not-relayed. Never throws to the event loop.
-     */
-    private handleTurnConnectionOpen;
-    /** On a control connection closing, drop any TURN-relayed flag for its peer. */
-    private handleTurnConnectionClose;
     /**
      * Publish (or refresh) this node's own self-signed `DeviceToken` row so a server
      * peer can resolve its FCM/APNs push token from its PeerId alone. Mirrors
@@ -2613,9 +2621,9 @@ export declare class CadreNode implements SAppIdLookup {
      * caller runs the drive regardless).
      *
      * NOTE: against a relay that is DOWN this hook costs up to two strand-addr
-     * timeouts (dial by peer id, then by addr; 23 s each at the default declared link round trip)
+     * timeouts (dial by peer id, then by addr; 28.5 s each at the default declared link round trip)
      * before the reservation drive even starts, so one failed re-drive holds the supervisor
-     * `driving` for those 46 s plus the drive's own deadline — 64 s at the default, and longer on
+     * `driving` for those 57 s plus the drive's own deadline — 75 s at the default, and longer on
      * a host that declared a slower one (`link-budget.ts`).
      * Bounded and harmless while the relay is unreachable anyway; if recovery
      * latency after a relay comes back ever matters, skip the announce when the
@@ -3435,32 +3443,128 @@ export declare class CadreNode implements SAppIdLookup {
      */
     dialInvite(invite: CadreInvite): Promise<void>;
     /**
-     * Initialize the strand solicitation service.
-     * This enables forming strands with other parties via open invitations.
+     * Replace this node's strand solicitation service — the formation responder every node
+     * installs at {@link start}, and the initiator side of {@link formStrand}. Optional: call it
+     * only to customize the responder (an approver, a provisioner, formation deadlines). The
+     * new service's handler replaces the previous one's on the control node, and invitations
+     * the previous service minted stay outstanding.
+     *
+     * Without `options.formationUsageRecorder`, tokens are checked against this party's
+     * replicated `FormationInvite`/`FormationUsage` rows ({@link ControlFormationUsageRecorder}).
+     * A responder that accepts every token is reachable only by constructing
+     * {@link StrandSolicitationService} directly.
      *
      * @param options - Configuration for the solicitation service
      */
     initializeStrandSolicitation(options?: StrandSolicitationServiceOptions): Promise<void>;
     /**
-     * Get the strand solicitation service (for advanced use)
+     * Answer formation from start. Log-and-continue: a node that cannot is still useful, and
+     * {@link createOpenInvitation} / {@link formStrand} install the responder when it is missing.
+     */
+    private installDefaultFormationResponder;
+    /**
+     * Move the control node's formation handler from the registered service to `service`.
+     * Queued by {@link initializeStrandSolicitation} so swaps run one at a time: libp2p allows
+     * one handler per protocol id, and two overlapping swaps would each find the other's
+     * handler in the way. A failed swap registers the previous service again, points
+     * {@link strandSolicitationService} back at it unless a later call has replaced it, and
+     * rethrows.
+     *
+     * NOTE: same stray-handler caveat as {@link installSeedBootstrapService} — a failed
+     * peer-store merge leaves the formation handler registered, so the restore below (and a
+     * retry) rejects as a duplicate.
+     */
+    private swapFormationResponder;
+    /**
+     * Get the strand solicitation service (for advanced use). Non-null on a started node unless
+     * the install at {@link start} failed.
      */
     getStrandSolicitationService(): StrandSolicitationService | null;
     /**
      * Create an open invitation for others to form strands with this party.
      *
+     * The invitation's bootstrap list names this machine first (it is the one most likely to
+     * run the host strand), then a few of the party's other machines
+     * ({@link siblingInvitationAddrs}), so a joiner can still form while this one is offline.
+     *
      * @param sAppId - The sApp to use for formed strands
      * @param expirationMs - How long the invitation is valid (ms from now)
      * @returns The open invitation to share out-of-band
+     * @throws when neither this machine nor any other machine of the party has an address
      */
     createOpenInvitation(sAppId: string, expirationMs?: number): Promise<OpenInvitation>;
     /**
-     * Form a strand with a responder via an open invitation.
+     * Addresses of the party's other machines for an invitation's bootstrap list
+     * ({@link selectInvitationSiblingAddrs} picks which). The source is each authorized
+     * member's signed `CadrePeer` record ({@link resolvePeerRecord}), so a machine whose record
+     * is missing, stale or untrusted is left out; live connections only order them.
+     *
+     * Best-effort: a failed read leaves the invitation naming this machine alone, which is what
+     * it named before siblings were added.
+     */
+    private siblingInvitationAddrs;
+    /**
+     * Form a strand with a responder via an open invitation: one attempt, from this machine, with
+     * nothing recorded party-wide. {@link requestJoin} is the path that keeps trying.
      *
      * @param invitation - The open invitation received out-of-band
      * @param disclosure - Identity/context information to share with the responder
      * @returns The member key and strand info if successful
+     * @throws `FormationRejectedError` or `FormationUnreachableError` when the formation fails, and
+     *   `FormationPostApprovalError` when it was approved and a step on this machine then failed
      */
     formStrand(invitation: OpenInvitation, disclosure?: StrandFormationDisclosure): Promise<FormStrandResult>;
+    /**
+     * Ask to join through `invitation` and have the party keep trying until the join works, the
+     * invitation is used up or expires, or the request is dismissed: across restarts, and from
+     * any owner machine of the party (`docs/strands.md` → "Joining while the inviter is
+     * offline"). Records a party-wide `PendingJoin` row, runs one attempt on this machine at
+     * once, and returns the status after it: `'joined'` when the inviter answered yes, `'waiting'`
+     * when it was unreachable or not ready, `'failed'` when it refused for good.
+     *
+     * Asking again for an invitation whose request is still pending adopts that request as it
+     * is; asking again after it finished starts a fresh one. Later changes arrive as
+     * `pendingJoin:changed`. A joined strand is offered through `strand:discovered` like any
+     * {@link formStrand} join. Do not also call {@link formStrand} with the same invitation:
+     * nothing coordinates the two, and one of them gets `token-spent`.
+     *
+     * @throws on a machine that is not an enrolled owner (the row is owner-signed), and on an
+     *   invitation already past its expiration
+     */
+    requestJoin(invitation: OpenInvitation, disclosure?: StrandFormationDisclosure): Promise<PendingJoinStatus>;
+    /**
+     * Every join asked for with {@link requestJoin} and not dismissed, pending or finished, as this
+     * machine sees it (see `PendingJoinStatus` for which states are machine-local).
+     */
+    listPendingJoins(): Promise<PendingJoinStatus[]>;
+    /**
+     * Remove a join request party-wide. On a pending request this cancels it: every owner machine
+     * stops at its next read, and an attempt already running does not record its outcome (a join
+     * it made stays on that machine, as any {@link formStrand} join does). Owner machines only.
+     * Resolves `false` when there was no such request.
+     */
+    dismissPendingJoin(id: string): Promise<boolean>;
+    private requirePendingJoins;
+    /** This machine's owner key and signer for an owner-signed control write, or a throw carrying `refusal`. */
+    private requireOwnerSigner;
+    /**
+     * Write a join request's row, or adopt the party's existing row for the same invitation: a
+     * pending one as it is, a finished one replaced by `requested` (the user asked again).
+     */
+    private recordJoinRequest;
+    /** Build and start the pending-join retry loop over this node (see {@link pendingJoinRunner}). */
+    private startPendingJoinRunner;
+    /** The invitation a `PendingJoin` row stores. A failure names the row, never the invitation, which is a bearer credential. */
+    private pendingJoinInvitation;
+    private pendingJoinSAppId;
+    /**
+     * Stage the membership invitation of each `joined` row this process has not staged yet, so a
+     * closed strand joined on another owner machine is seated by whichever machine launches it
+     * first; the party key it admits is the replicated `StrandPartyKey` row the finishing machine
+     * seated. A strand that already has an invitation staged keeps it, for the reconciler to
+     * settle first.
+     */
+    private stageMembershipInvitesFromPendingJoins;
     /**
      * Remember the strand a formation just joined (see {@link joinedStrandStore}), so it
      * is re-offered after a restart even when the app is killed before its `addStrand`, and