@serfab/cadre-core 0.12.0 → 0.13.0

package/dist/strand-network-config.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Derive the per-STRAND-node view of the machine's one `NetworkConfig`.
+ *
+ * A cadre machine runs one **control** libp2p node plus one more libp2p node per
+ * strand, and every one of them is built from the SAME operator-written
+ * `NetworkConfig` block. Two of its fields describe a single endpoint on the host
+ * and therefore cannot be inherited literally by a second node on that host:
+ *
+ * - **`listenAddrs` with a fixed port.** `cadre-cli`'s example config ships
+ *   `/ip4/0.0.0.0/tcp/4001`. The control node binds it first; every strand node
+ *   then tries to bind the same port and fails with `EADDRINUSE`, so a machine
+ *   configured with a fixed port could not start any strand at all.
+ * - **`announceAddrs` / `appendAnnounceAddrs`.** Any concrete announce entry names
+ *   a port, and that port is the CONTROL node's. A strand node advertising it
+ *   sends peers to the control node — and `announceAddrs` REPLACES the advertised
+ *   set (see `announce-addrs.ts`), so that wrong address would be the ONLY thing
+ *   the strand node publishes.
+ *
+ * The reachability model this rests on: **a strand node is not separately dialable
+ * at a published fixed address.** It is reached through (a) its ephemeral direct
+ * listener plus the addresses peers observe for it, and (b) circuit relay —
+ * `network.relayAddrs` resolves to per-relay `<relay>/p2p-circuit` listen entries
+ * that strand nodes DO inherit correctly, because the port inside such an entry is
+ * the relay's, not a local bind (`relay-addrs.ts`).
+ *
+ * Everything else in `NetworkConfig` — `relayAddrs`, `transports`,
+ * `connectionGater`, `enableRelay` — is inherited by the caller; this module
+ * only owns the two host-endpoint fields above. One caveat on `connectionGater`:
+ * an OPEN strand's node gets it unchanged, while a CLOSED strand's node composes
+ * revoked-peer denial onto it in `strand-instance-manager.ts` (every supplied
+ * hook still honored — see `strand-revocation-enforcer.ts`).
+ *
+ * It does carry one non-address option out with them: the WebSocket transport switch
+ * a `/ws` listen entry implies (`relay-addrs.ts` → `resolveTransportOptions`). That is
+ * DERIVED from the listen entries rather than inherited, so it has to be computed
+ * wherever they are, and a strand node whose listen entries reached libp2p without it
+ * would bind no WebSocket listener and report nothing.
+ */
+import type { NetworkConfig } from './types.js';
+/**
+ * The address-shaped `createLibp2pNode` options a strand node gets, ready to spread
+ * into the rest of its options.
+ *
+ * There is deliberately no announce field here: a strand node announces NOTHING the
+ * operator configured, only what libp2p derives for it (its own listeners, observed
+ * addresses, and any `/p2p-circuit` address a relay reservation earns).
+ *
+ * NOTE: accepted tradeoff — a hosted deployment that wants a strand node reachable
+ * at its own published public port has no way to say so; the announce config is
+ * dropped for strand nodes wholesale rather than per-strand. Nothing needs that
+ * today, and the alternative is a per-strand network-config surface. Revisit if a
+ * hosted or reverse-proxy deployment ever needs direct-dialable strand nodes.
+ */
+export interface StrandNodeAddrs {
+    /**
+     * Listen entries for this strand node, or `undefined` when the operator
+     * configured neither `listenAddrs` nor `relayAddrs` — in which case the caller
+     * omits the option and inherits `@optimystic/db-p2p`'s own default.
+     */
+    listenAddrs?: string[];
+    /**
+     * The WebSocket transport switch those listen entries imply, present only when one
+     * of them names WebSocket (`relay-addrs.ts` → `resolveTransportOptions`). Not an
+     * address — it is deliberately `0` and nothing binds it — but it lives here because
+     * it is derived from, and must travel with, the listen entries above. Without it a
+     * `/ws` strand listen entry binds nothing and libp2p reports nothing.
+     */
+    wsPort?: number;
+}
+/**
+ * The strand-node view of `network`: the control node's resolved listen entries with
+ * every fixed direct port rewritten to an ephemeral one, and no announce fields.
+ *
+ * Validation is unchanged and still fail-fast — `resolveListenAddrs` throws here on a
+ * malformed `relayAddrs` entry exactly as it does for the control node.
+ *
+ * NOTE: announce entries are no longer validated on this path at all; the CONTROL
+ * node's own build (`cadre-node.ts`) is the only thing that parses them, and it runs
+ * before any strand starts, so a typo still refuses node start today. That is an
+ * ORDERING guarantee, not a structural one. Revisit if a strand node is ever built
+ * before the control node's libp2p options are resolved — a malformed announce entry
+ * would then go unreported until the control node's own build.
+ */
+export declare function strandNodeAddrs(network: NetworkConfig | undefined): StrandNodeAddrs;

package/dist/strand-network-config.js

@@ -0,0 +1,136 @@
+/**
+ * Derive the per-STRAND-node view of the machine's one `NetworkConfig`.
+ *
+ * A cadre machine runs one **control** libp2p node plus one more libp2p node per
+ * strand, and every one of them is built from the SAME operator-written
+ * `NetworkConfig` block. Two of its fields describe a single endpoint on the host
+ * and therefore cannot be inherited literally by a second node on that host:
+ *
+ * - **`listenAddrs` with a fixed port.** `cadre-cli`'s example config ships
+ *   `/ip4/0.0.0.0/tcp/4001`. The control node binds it first; every strand node
+ *   then tries to bind the same port and fails with `EADDRINUSE`, so a machine
+ *   configured with a fixed port could not start any strand at all.
+ * - **`announceAddrs` / `appendAnnounceAddrs`.** Any concrete announce entry names
+ *   a port, and that port is the CONTROL node's. A strand node advertising it
+ *   sends peers to the control node — and `announceAddrs` REPLACES the advertised
+ *   set (see `announce-addrs.ts`), so that wrong address would be the ONLY thing
+ *   the strand node publishes.
+ *
+ * The reachability model this rests on: **a strand node is not separately dialable
+ * at a published fixed address.** It is reached through (a) its ephemeral direct
+ * listener plus the addresses peers observe for it, and (b) circuit relay —
+ * `network.relayAddrs` resolves to per-relay `<relay>/p2p-circuit` listen entries
+ * that strand nodes DO inherit correctly, because the port inside such an entry is
+ * the relay's, not a local bind (`relay-addrs.ts`).
+ *
+ * Everything else in `NetworkConfig` — `relayAddrs`, `transports`,
+ * `connectionGater`, `enableRelay` — is inherited by the caller; this module
+ * only owns the two host-endpoint fields above. One caveat on `connectionGater`:
+ * an OPEN strand's node gets it unchanged, while a CLOSED strand's node composes
+ * revoked-peer denial onto it in `strand-instance-manager.ts` (every supplied
+ * hook still honored — see `strand-revocation-enforcer.ts`).
+ *
+ * It does carry one non-address option out with them: the WebSocket transport switch
+ * a `/ws` listen entry implies (`relay-addrs.ts` → `resolveTransportOptions`). That is
+ * DERIVED from the listen entries rather than inherited, so it has to be computed
+ * wherever they are, and a strand node whose listen entries reached libp2p without it
+ * would bind no WebSocket listener and report nothing.
+ */
+import { multiaddr } from '@multiformats/multiaddr';
+import { resolveListenAddrs, resolveTransportOptions } from './relay-addrs.js';
+/**
+ * The strand-node view of `network`: the control node's resolved listen entries with
+ * every fixed direct port rewritten to an ephemeral one, and no announce fields.
+ *
+ * Validation is unchanged and still fail-fast — `resolveListenAddrs` throws here on a
+ * malformed `relayAddrs` entry exactly as it does for the control node.
+ *
+ * NOTE: announce entries are no longer validated on this path at all; the CONTROL
+ * node's own build (`cadre-node.ts`) is the only thing that parses them, and it runs
+ * before any strand starts, so a typo still refuses node start today. That is an
+ * ORDERING guarantee, not a structural one. Revisit if a strand node is ever built
+ * before the control node's libp2p options are resolved — a malformed announce entry
+ * would then go unreported until the control node's own build.
+ */
+export function strandNodeAddrs(network) {
+    // The default `'configured'` relay route, deliberately NOT the control node's
+    // `'search'` route: nothing drives an explicit reservation for a strand node, so a
+    // bare `/p2p-circuit` search entry would register a pending reservation nobody fills
+    // and leave every NAT'd strand node undialable. See `relay-addrs.ts`.
+    const listenAddrs = resolveListenAddrs(network);
+    if (!listenAddrs) {
+        return {};
+    }
+    // An explicitly empty `listenAddrs` (the React Native "cannot listen" case) stays
+    // empty — rewriting must never resurrect a direct listener that was opted out of.
+    const rewritten = dedupe(listenAddrs.map(ephemeralPortListenAddr));
+    // Classified AFTER the ephemeral rewrite, so the check reads what this strand node
+    // will actually bind. Zeroing a port cannot change an entry's transport — only the
+    // `tcp`/`udp` component's value moves — so `/ip4/0.0.0.0/tcp/4002/ws` still resolves
+    // to WebSocket as `/ip4/0.0.0.0/tcp/0/ws`.
+    return { listenAddrs: rewritten, ...resolveTransportOptions(network, rewritten) };
+}
+/**
+ * One listen entry with its fixed direct port rewritten to `0`, so the OS assigns a
+ * free one per node. Interface and transport choices are preserved — `/ws`, a
+ * specific-interface bind, a `/udp/…/quic-v1` stack — since only the port is
+ * contended.
+ *
+ * Passed through UNCHANGED when there is nothing to rewrite, so the operator's exact
+ * string survives rather than being round-tripped through the multiaddr normalizer:
+ *
+ * - a circuit entry (`…/p2p-circuit`), whose embedded port belongs to the RELAY and
+ *   is not a local bind at all;
+ * - a port that is already `0`, or an entry that names no port;
+ * - an unparsable entry — libp2p reports a bad listen addr itself, and this helper
+ *   only ever narrows a port.
+ */
+function ephemeralPortListenAddr(listenAddr) {
+    let components;
+    try {
+        components = multiaddr(listenAddr).getComponents();
+    }
+    catch {
+        return listenAddr;
+    }
+    if (components.some((c) => c.name === 'p2p-circuit')) {
+        return listenAddr;
+    }
+    if (!components.some(isFixedPort)) {
+        return listenAddr;
+    }
+    return multiaddr(components.map(withEphemeralPort)).toString();
+}
+/** A `tcp`/`udp` component naming a port the OS did not choose. */
+function isFixedPort(component) {
+    return (component.name === 'tcp' || component.name === 'udp')
+        && component.value !== undefined
+        && component.value !== '0';
+}
+/**
+ * `component` with its port zeroed, or unchanged when it is not a fixed port.
+ *
+ * Rebuilt field-by-field rather than spread: a parsed component may carry a `bytes`
+ * cache, and `componentsToBytes` PREFERS that cache over `value` — a spread would
+ * re-encode the old port.
+ */
+function withEphemeralPort(component) {
+    return isFixedPort(component)
+        ? { code: component.code, name: component.name, value: '0' }
+        : component;
+}
+/**
+ * Exact-string dedupe, first occurrence wins — matching `relay-addrs.ts`. Entries
+ * that differed only by port collapse into one after the rewrite, and libp2p would
+ * otherwise try to bind the same ephemeral-port entry twice.
+ *
+ * NOTE: an operator who writes two fixed ports on the same interface and transport
+ * (`/ip4/0.0.0.0/tcp/4001` and `…/tcp/4002`) gets ONE strand listener, not two, since
+ * the two entries are identical once zeroed. Intended — the ports were the only thing
+ * distinguishing them and neither survives. Revisit if a deployment ever needs a
+ * strand node to hold a fixed count of direct listeners.
+ */
+function dedupe(addrs) {
+    return [...new Set(addrs)];
+}
+//# sourceMappingURL=strand-network-config.js.map

package/dist/strand-network-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"strand-network-config.js","sourceRoot":"","sources":["../src/strand-network-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,EAAE,SAAS,EAAkB,MAAM,yBAAyB,CAAC;AACpE,OAAO,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAkC/E;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,eAAe,CAAC,OAAkC;IAChE,8EAA8E;IAC9E,mFAAmF;IACnF,qFAAqF;IACrF,sEAAsE;IACtE,MAAM,WAAW,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAChD,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,kFAAkF;IAClF,kFAAkF;IAClF,MAAM,SAAS,GAAG,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC,CAAC;IACnE,mFAAmF;IACnF,mFAAmF;IACnF,qFAAqF;IACrF,2CAA2C;IAC3C,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,GAAG,uBAAuB,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,CAAC;AACpF,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAS,uBAAuB,CAAC,UAAkB;IACjD,IAAI,UAAuB,CAAC;IAC5B,IAAI,CAAC;QACH,UAAU,GAAG,SAAS,CAAC,UAAU,CAAC,CAAC,aAAa,EAAE,CAAC;IACrD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,UAAU,CAAC;IACpB,CAAC;IACD,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,aAAa,CAAC,EAAE,CAAC;QACrD,OAAO,UAAU,CAAC;IACpB,CAAC;IACD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;QAClC,OAAO,UAAU,CAAC;IACpB,CAAC;IACD,OAAO,SAAS,CAAC,UAAU,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;AACjE,CAAC;AAED,mEAAmE;AACnE,SAAS,WAAW,CAAC,SAAoB;IACvC,OAAO,CAAC,SAAS,CAAC,IAAI,KAAK,KAAK,IAAI,SAAS,CAAC,IAAI,KAAK,KAAK,CAAC;WACxD,SAAS,CAAC,KAAK,KAAK,SAAS;WAC7B,SAAS,CAAC,KAAK,KAAK,GAAG,CAAC;AAC/B,CAAC;AAED;;;;;;GAMG;AACH,SAAS,iBAAiB,CAAC,SAAoB;IAC7C,OAAO,WAAW,CAAC,SAAS,CAAC;QAC3B,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE;QAC5D,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,MAAM,CAAC,KAAwB;IACtC,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;AAC7B,CAAC"}

package/dist/strand-revocation-enforcer.d.ts

@@ -0,0 +1,392 @@
+/**
+ * Strand revoked-peer enforcement: a per-strand deny gate that refuses the
+ * network nodes of a REMOVED party, so removal means "we stop talking to you"
+ * rather than only deleting a row.
+ *
+ * ## The deny set is revocation-keyed, never membership-keyed
+ *
+ * A strand node maintains a materialized in-memory set of revoked peer ids:
+ * every `Strand.MemberPeer.PeerId` whose `MemberKey` has no live `Strand.Member`
+ * row. `MemberPeer.MemberExists` runs on insert, so an orphaned binding can only
+ * mean "this member existed and was removed" — it is exactly the durable,
+ * replicated record of a removed party's machines. Everything NOT in the set is
+ * admitted. Deliberate consequences:
+ *
+ * - **Open strands are untouched.** `Member`/`MemberPeer` carry `OnlyClosed`
+ *   checks, so an open strand has no rows and the set is empty — and
+ *   `StrandInstanceManager` additionally skips arming this enforcer entirely for
+ *   `Type !== 'c'`, so an open strand does not even poll.
+ * - **A joining party mid-admission is admitted** (it has no orphaned binding).
+ *   An allowlist ("only peers bound to live members") was considered and
+ *   rejected: a joiner's first membership writes must travel through the very
+ *   cohort an allowlist would close to it — the same mutual-denial trap the
+ *   control network's gater doc describes (`membership-connection-gater.ts`),
+ *   with no enrollment window to carve out. A deny-list on positive evidence
+ *   has no such trap.
+ * - **Stale-view failure direction: fail-open.** A remaining member that has not
+ *   yet replicated the revocation keeps serving the removed party until the
+ *   tombstoned state arrives — bounded by replication, consistent with
+ *   "revocation is forward-looking". The opposite error (denying a legitimate
+ *   member) is only reachable for a revoked-then-re-admitted party at a node
+ *   that saw the revoke but not the re-add; the re-add gives the member key a
+ *   live `Member` row again, which removes its peers from the deny set as the
+ *   row replicates — self-healing, and the re-adding manager's own node updates
+ *   first, so the heal never depends on talking to the peer being wrongly denied.
+ * - **Orphaned `MemberPeer` rows are load-bearing**: they ARE the deny record —
+ *   the `Strand.Revocation` tombstone keeps only the stamp, not the peer id — so
+ *   nothing here (or anywhere) tombstones or auto-cleans them at revocation.
+ *   The manager-cleanup path (`removeMemberPeer`'s manager branch) stays as the
+ *   only way to clear a wrongly-registered binding, and clearing an orphan
+ *   forgets the denial (the NOTE at that branch says so).
+ *
+ * ## Removal cuts LIVE sessions too — the refresh IS the teardown seam
+ *
+ * Refusing NEW connections only half-honors "no longer be answered to or
+ * communicated with": a long-lived strand connection may never re-dial, so
+ * without teardown a removed party keeps whatever session it already holds.
+ * There is no push notification to hang teardown off — a REPLICATED revocation
+ * arrives with no change event (the strand database has no reactive
+ * subscription; `StrandWatcher` polls for the same reason), and a LOCAL
+ * `revokeMember`/`leaveStrand` writes through a bare `Database` handle this
+ * runtime never sees — so teardown rides the snapshot refresh itself, with
+ * `refresh()` exposed for immediacy
+ * (`StrandInstanceManager.refreshRevocationEnforcement` →
+ * `CadreNode.refreshRevocationEnforcement`).
+ *
+ * The sweep is driven by MEMBERSHIP in the deny set, never by an
+ * entered-the-set diff: every refresh hangs up every currently-connected
+ * revoked peer, so a resume, a crashed refresh, or a connection established
+ * between two refreshes cannot leave a session standing (a diff would be a
+ * strict subset of this, so none is kept). A peer with no open connection is
+ * simply not swept, and a failed `hangUp` is logged, never thrown — the next
+ * refresh retries it. `hangUp` closes DIRECT and RELAYED connections alike, and
+ * on a strand node running the relay server it also drops any reservation the
+ * revoked peer holds there (a reservation dies with its connection — see the
+ * relay-seam doc in `membership-connection-gater.ts`).
+ *
+ * Teardown is also what stops OUTBOUND traffic. The gate is one-directional —
+ * `authorizeStream` judges streams the revoked peer opens to US — so nothing
+ * else prevents this node from pushing over an already-open connection, which
+ * `PeerJoinBackfill` does for that connection's whole life. Closing the
+ * connection stops both directions at once, which is why no separate outbound
+ * gate exists.
+ *
+ * If this node's OWN peer id is in the set, it was itself removed (or it left —
+ * a voluntary departure files the same tombstone). Nothing is torn down for
+ * that: the other side's gate already refuses us, and every other revoked peer
+ * is still swept. Instead `onSelfRevoked` fires ONCE per entry into the set
+ * (re-armed if the party is re-admitted, so a second removal signals again),
+ * which `CadreNode` surfaces as `strand:revoked` so the embedding app decides
+ * what to do — this module never stops or leaves a strand on its own.
+ * Best-effort by nature: a removed party learns only if the tombstone
+ * replicated to it before the cut.
+ *
+ * ## What transfers from the control gater (`membership-connection-gater.ts`)
+ *
+ * Transfers: the two-layer shape (fail-closed per-stream gate as PRIMARY, an
+ * opportunistic connection-level deny on top), the synchronous in-memory
+ * snapshot judged by the stream gate (a live DB read inside a gate deadlocks —
+ * the same argument as the control node's `authorizeInboundControlStream`), the
+ * fail-open-on-error/timeout posture for the connection hooks
+ * (`decideWithinDeadline`, reused as-is), and the "compose over the caller's
+ * gater, every base hook preserved" mechanics.
+ *
+ * Does NOT transfer — the relay-reservation seam (`'admit-for-relay'` + the
+ * unauthorized budget). That machinery exists because the control gate denies on
+ * ABSENCE of placement, where a member whose row is in flight is
+ * indistinguishable from an outsider and a wrong reservation deny is
+ * unrecoverable. This gate denies on POSITIVE revocation evidence, so a
+ * reservation deny is never that kind of wrong answer; the one stale-wrong case
+ * (a missed re-add) heals via replication as above. `denyInboundRelayReservation`
+ * here is therefore a plain "deny iff revoked" — no budget, no admit-for-relay
+ * verdict, no reserve deadline.
+ *
+ * Does NOT transfer — the bring-up quiet period. A strand node's DB bring-up
+ * NEEDS its cross-party cohort connections; this enforcer simply starts with an
+ * empty snapshot (admit everything) until its first successful read — the same
+ * fail-open posture as everywhere else here.
+ *
+ * Does NOT transfer — every stranger carve-out (enrollment window, formation
+ * window, delegate grants). None of those protocols exist on a strand node.
+ *
+ * Unlike the control stream gate, no empty-snapshot carve-out is needed: an
+ * empty deny set means "nothing revoked", which correctly admits everyone — the
+ * deny-list shape makes the cold-start case and the steady case the same code
+ * path.
+ */
+import type { ConnectionGater, PeerId } from '@libp2p/interface';
+import type { Database } from '@quereus/quereus';
+/**
+ * Default cadence of the deny-set refresh. Bounded staleness is the accepted
+ * failure direction (see the module doc's stale-view paragraph); 30 s keeps a
+ * revoked peer's post-replication admit window in the same order as the
+ * replication delay itself. Overridable via
+ * {@link StrandRevocationEnforcementConfig.pollIntervalMs}.
+ */
+export declare const DEFAULT_REVOCATION_POLL_INTERVAL_MS = 30000;
+/**
+ * Embedder tuning for the strand revoked-peer gate, threaded from
+ * `CadreNodeConfig.strandRevocationEnforcement` to
+ * `StartStrandConfig.revocationEnforcement` the way the backfill knob is.
+ */
+export interface StrandRevocationEnforcementConfig {
+    /**
+     * Default true. False disarms the gate entirely for this node's strands —
+     * the pre-existing behaviour (a removed party's peers keep being served).
+     */
+    enabled?: boolean;
+    /** Deny-set refresh cadence, ms. Default {@link DEFAULT_REVOCATION_POLL_INTERVAL_MS}. */
+    pollIntervalMs?: number;
+}
+/** One `Strand.MemberPeer` row, as the deny-set derivation consumes it. */
+export interface StrandMemberPeerBinding {
+    memberKey: string;
+    peerId: string;
+}
+/** The membership rows one deny-set derivation reads. */
+export interface StrandRevocationRows {
+    /** Every live `Strand.Member.Key`. */
+    memberKeys: ReadonlySet<string>;
+    /** Every `Strand.MemberPeer` row (live-membered and orphaned alike). */
+    bindings: readonly StrandMemberPeerBinding[];
+}
+/**
+ * Timer seam so the refresh cadence is testable without fake timers — the
+ * injectable-clock idiom of `UnauthorizedReservationBudget`'s `now` argument,
+ * shaped for an interval-driven component. The default schedules a real
+ * interval and unrefs it so an armed enforcer never holds a process open.
+ */
+export interface RevocationRefreshScheduler {
+    setInterval(fn: () => void, ms: number): unknown;
+    clearInterval(handle: unknown): void;
+}
+/**
+ * The minimum of a libp2p node the teardown sweep needs: who WE are, what is
+ * open, and how to close it. Deliberately not the node itself, so the sweep
+ * unit-tests against a three-property stub; `Libp2p` (hence
+ * `Libp2pNodeWithRepo`) satisfies it structurally, which is what
+ * `StrandInstanceManager` passes.
+ */
+export interface StrandRevocationNetwork {
+    /** This node's own peer id — how the enforcer recognizes ITSELF in the deny set. */
+    readonly peerId: PeerId;
+    /** Every open connection. Only `remotePeer` is read — and reused as the hangUp target. */
+    getConnections(): readonly {
+        readonly remotePeer: PeerId;
+    }[];
+    /** Close every connection to `peer`: direct, relayed, and any reservation riding one. */
+    hangUp(peer: PeerId): Promise<void>;
+}
+export interface StrandRevocationEnforcerDeps {
+    /** Log tag naming which strand this enforcer serves (the strand id). */
+    label: string;
+    /**
+     * Read the membership rows the deny set is derived from. Injectable so the
+     * enforcer unit-tests without a strand database; production wires
+     * {@link readStrandRevocationRows} over the strand's live DB. A throw or
+     * rejection KEEPS the previous snapshot (never clears it) — the control
+     * model, `refreshAuthorizedControlPeers`.
+     */
+    readRows: () => Promise<StrandRevocationRows>;
+    /**
+     * Handle on the strand's libp2p node for the teardown sweep, read LAZILY on
+     * every sweep — never captured. It has to be: the enforcer is constructed
+     * BEFORE the node (the node's options embed the enforcer's predicates), and
+     * the node is dropped again on quiesce. Omit it, or return undefined, and the
+     * gate still refuses new connections — only teardown of OPEN ones is skipped.
+     */
+    getNetwork?: () => StrandRevocationNetwork | undefined;
+    /**
+     * Called ONCE each time this node's own peer id ENTERS the deny set — i.e.
+     * this node's party was removed from the strand, or left it. Not re-fired
+     * while it stays there; re-armed if the party is re-admitted, so a second
+     * removal signals again. Wired by `StrandInstanceManager` through to
+     * `CadreNode`'s `strand:revoked` event. A resume rebuilds the enforcer, so a
+     * still-revoked strand also legitimately re-fires once per resume. A throw is
+     * logged and swallowed — an embedder's handler must not derail the sweep.
+     */
+    onSelfRevoked?: () => void;
+    /** Timer seam; omit for real (unref'd) intervals. */
+    scheduler?: RevocationRefreshScheduler;
+}
+/**
+ * Read the deny-set inputs from a strand database: full-scan
+ * `Strand.MemberPeer` and `Strand.Member`, to be joined in JavaScript by the
+ * enforcer. Scan-and-filter, never seek — the composite-PK point-lookup
+ * unreliability documented at `scanMemberPeers` in `strand-membership-writer.ts`
+ * applies, so correctness depends only on each scan returning a superset of the
+ * live rows.
+ *
+ * **Scan order is load-bearing, and it is BINDINGS FIRST.** The two scans are
+ * separate reads with nothing holding them to one snapshot, so a write that
+ * lands between them is seen by the second scan and not the first. A member
+ * joins as `Member` row then `MemberPeer` row (`MemberExists` forces that
+ * order), so reading `Member` first would let a join that commits mid-read
+ * produce a binding whose member key is absent from the key set — a brand-new
+ * member classified as REVOKED, the one fail-CLOSED outcome this module exists
+ * to avoid. Reading bindings first inverts the skew: the new binding is simply
+ * not in the older bindings snapshot, so the joiner is unclassified and
+ * admitted, and a revocation that lands mid-read is still seen (the key is
+ * missing from the NEWER key scan). Every skew window then resolves fail-open,
+ * matching the module doc.
+ *
+ * NOTE: two whole-table scans per refresh (default every 30 s per closed
+ * strand). Fine at strand scale (a handful of members and bindings); if
+ * membership churn ever makes these tables large, the fix is a reliable
+ * filtered read — which needs the networked point-lookup gap closed
+ * (`debt-composite-pk-point-lookup-unreliable-untracked`) — not a bigger scan.
+ */
+export declare function readStrandRevocationRows(db: Database): Promise<StrandRevocationRows>;
+/**
+ * The per-strand revoked-peer deny set and the synchronous predicates over it.
+ *
+ * Lifecycle mirrors `PeerJoinBackfill`: created in
+ * `StrandInstanceManager.buildStrandRuntime` (closed strands only), started
+ * after the strand database initializes, stopped and dropped in
+ * `releaseRuntime` — so quiesce → resume rebuilds it with a fresh snapshot.
+ * The snapshot starts EMPTY (admit everything) and repopulates on the first
+ * successful read; a revoked peer therefore gets a short admit window per
+ * resume at the connection level. Accepted: fail-open posture, and resume is
+ * never blocked on a refresh.
+ */
+export declare class StrandRevocationEnforcer {
+    private readonly deps;
+    /** The materialized deny set — peer ids with an orphaned binding and no live one. */
+    private revokedPeerIds;
+    private readonly scheduler;
+    private readonly pollIntervalMs;
+    /** Tail of the refresh chain — what serializes refreshes (no two reads in flight). */
+    private refreshTail;
+    private refreshing;
+    private intervalHandle;
+    private started;
+    private stopped;
+    /** Latch for the one-shot self-revocation signal — see {@link StrandRevocationEnforcerDeps.onSelfRevoked}. */
+    private selfRevokedSignaled;
+    constructor(deps: StrandRevocationEnforcerDeps, config?: StrandRevocationEnforcementConfig);
+    /** Number of peers currently denied — test/diagnostic surface. */
+    get revokedCount(): number;
+    /** Kick an immediate refresh (not awaited — bring-up never blocks on it) and arm the poll. */
+    start(): void;
+    /** Disarm the poll; a read already in flight completes but its result is discarded. */
+    stop(): void;
+    /**
+     * Refresh the deny set now. Never rejects. Serialized: concurrent calls chain,
+     * so no two reads overlap, and each explicit call gets a read that STARTS
+     * after the call (an on-demand refresh after a revocation commit observes that
+     * commit). A failed or slow read keeps the previous snapshot — never clears it.
+     */
+    refresh(): Promise<void>;
+    /**
+     * Is `remotePeerId` positively revoked in the current snapshot? Synchronous by
+     * design — this is judged inside libp2p gates where an await against the DB
+     * would deadlock (the control stream gate's argument).
+     */
+    isRevoked(remotePeerId: string): boolean;
+    /**
+     * The fail-closed PRIMARY layer: the per-stream predicate wired as
+     * `createLibp2pNode({ authorizeInboundStream })`, gating all four
+     * `/optimystic/strand-<id>/{repo,cluster,sync,block-transfer}` protocols.
+     * Also what catches a revoked peer arriving over a RELAYED connection, or
+     * over a connection admitted before the revocation replicated here.
+     */
+    authorizeStream(remotePeerId: string, _protocol: string): boolean;
+    /**
+     * One serialized snapshot rebuild; contains every failure (contract: never rejects).
+     *
+     * NOTE: nothing here carries a deadline — a `readRows` or a `hangUp` that never
+     * settles wedges the refresh chain, which freezes the deny set (the poll skips
+     * while `refreshing`, and every later `refresh()` chains behind the stuck one).
+     * Both are bounded in practice (Quereus reads settle; libp2p's connection close
+     * has its own timeout). If a strand is ever seen with a stale deny set and no
+     * refresh log line, wrap both awaits in a timeout rather than hunting further.
+     */
+    private doRefresh;
+    /**
+     * Close what is already OPEN to the peers of `revoked` — the teardown half of
+     * enforcement (module doc: "Removal cuts LIVE sessions too"). Never rejects:
+     * every failure is contained, so the refresh loop survives and simply retries
+     * on the next tick.
+     *
+     * `revoked` is passed IN rather than read off the field, so the sweep judges
+     * the exact snapshot its own refresh produced; likewise the connection list is
+     * enumerated once, before any await, so a peer re-admitted mid-sweep is at
+     * worst hung up once and reconnects.
+     *
+     * NOTE: dropping the revoked peer from the strand's Optimystic cohort needs no
+     * separate action — machines quiesce strands routinely and the remaining cohort
+     * keeps committing, so an unreachable cohort peer is already tolerated, and
+     * `denyDialPeer` makes the exclusion fast (a local refusal, not a dial timeout).
+     * Two residual facts, both accepted: the removed node keeps every block it had
+     * already replicated (revocation is forward-looking), and a block whose only
+     * holders were the removed party's machines can be unavailable to the rest
+     * until repair.
+     *
+     * NOTE: post-removal commit latency is real and MEASURED, not hypothetical. On
+     * the two-parties-by-two-machines fixture in
+     * `integration-tests/src/scenarios/strand-removal-cuts-network.integration.ts`
+     * the remaining cohort's FIRST write after a cut fails repeatedly with
+     * `BlockUnavailableError: … (peers-unreachable)` before it commits — three or
+     * four failures, 3.5-4.3 s, over four runs — because the cohort still listed
+     * the removed party's now unreachable machines and had to downsize to the
+     * live holders first. It
+     * recovers on its own, so this is a latency cost, not a defect, and it is
+     * stated for app authors in `docs/strands.md` → Removing Members. If it ever
+     * stops recovering — a write that never commits, or `cluster-fetch:no-quorum` —
+     * that is an upstream (Optimystic) conversation, not a workaround here.
+     */
+    private tearDownRevoked;
+    /** The lazily-read network handle; an accessor that throws costs this pass only. */
+    private resolveNetwork;
+    /** One hangUp, contained: a stopping node or an already-closed connection is not an error here. */
+    private hangUpRevoked;
+    /**
+     * Latch {@link StrandRevocationEnforcerDeps.onSelfRevoked} to the TRANSITION
+     * into the revoked state: fired once on entry, and re-armed the moment this
+     * node is out of the set again — a manager can re-admit a party it removed
+     * (a fresh `Member` row makes the orphaned bindings live again), and a second
+     * removal has to be reported like the first.
+     */
+    private trackSelfRevoked;
+}
+/** The one capability the gater composition needs from the enforcer. */
+export type StrandRevocationJudge = Pick<StrandRevocationEnforcer, 'isRevoked'>;
+/**
+ * Build a closed strand's connection gater: the caller-supplied gater (if any)
+ * with revoked-peer denial composed onto three hooks. The opportunistic
+ * SECONDARY layer — the per-stream gate above is the fail-closed primary.
+ *
+ *  - `denyInboundEncryptedConnection`: deny iff revoked, so a removed party's
+ *    node is refused before any protocol negotiation.
+ *  - `denyDialPeer`: deny iff revoked — the owner ruling covers "communicated
+ *    with", not just "answered to", and refusing the dial locally is instant,
+ *    which keeps Optimystic from wasting a dial timeout on a peer this node
+ *    will not talk to anyway.
+ *  - `denyInboundRelayReservation`: deny iff revoked — matters when the strand
+ *    node runs the relay server (the storage-profile default), where admitting
+ *    the reservation would let a removed party keep using this node's
+ *    forwarding capacity.
+ *
+ * Composition semantics: every hook of `base` is preserved as-is; on the three
+ * composed hooks a deny from EITHER the base gater or the revocation check
+ * denies, and an error (or a decision slower than `decisionTimeoutMs`) in
+ * either is fail-open — the base error admits through to the revocation check,
+ * a revocation-check error admits outright, and the fail-closed stream gate
+ * still stands behind both. The deadline is belt-and-braces: the snapshot read
+ * is synchronous.
+ *
+ * NOTE: accepted tradeoff — swallowing a BASE hook's throw diverges from
+ * `createMembershipConnectionGater`, which lets it propagate to libp2p (a
+ * fail-closed outcome there). Uniform fail-open was chosen for this module so
+ * every hook has one failure direction, and it was the shape the plan specified;
+ * the cost is that an embedder gater which throws is silently admitted here
+ * while the same gater passed raw to an OPEN strand would refuse. Loud in the
+ * log either way. Revisit if an embedder ever ships a gater whose throw is a
+ * meaningful deny, or if the two gaters are unified.
+ *
+ * NOTE: `base` is spread, so a gater passed as a CLASS INSTANCE would lose its
+ * prototype methods — same caveat as `createMembershipConnectionGater`; every
+ * caller in this repo supplies a plain object (the RN/web permissive gaters,
+ * e.g. `{ denyDialMultiaddr: () => false }`, keep working unchanged).
+ */
+export declare function createRevocationConnectionGater(enforcer: StrandRevocationJudge, base?: ConnectionGater, decisionTimeoutMs?: number): ConnectionGater;