@optimystic/db-p2p 0.16.3 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optimystic/db-p2p",
-  "version": "0.16.3",
+  "version": "0.17.0",
   "type": "module",
   "description": "P2P database functionality for Optimystic",
   "main": "dist/src/index.js",
@@ -81,7 +81,7 @@
     "@libp2p/tcp": "^11.0.10",
     "@libp2p/websockets": "^10.1.3",
     "@multiformats/multiaddr": "^13.0.1",
-    "@optimystic/db-core": "^0.16.3",
+    "@optimystic/db-core": "^0.17.0",
     "async-mutex": "^0.5.0",
     "debug": "^4.4.3",
     "it-all": "^3.0.9",

package/{README.md → readme.md}

@@ -336,6 +336,23 @@ const keyNetwork = new Libp2pKeyPeerNetwork(node);
 - **Peer Discovery**: Integrates with libp2p DHT for peer discovery
 - **Security**: Leverages libp2p's cryptographic peer identity
 
+**Inbound stream authorization (optional).** The `repo`, `cluster`, `sync` and `block-transfer`
+protocols are open to any peer that can connect. An embedder whose database is private supplies one
+node-level, fail-closed predicate, consulted once per inbound stream before any decoding or execution:
+
+```typescript
+const node = await createLibp2pNode({
+  networkName: 'my-net',
+  bootstrapNodes: [],
+  // remotePeerId is the dialing peer's PeerId.toString(); only a literal `true` allows.
+  // false / throw / rejection / timeout all deny and abort the stream.
+  authorizeInboundStream: (remotePeerId, protocol) => memberSet.has(remotePeerId)
+});
+```
+
+Omitting it is the default and leaves behavior unchanged. See
+[internals](../../docs/internals.md) § Inbound Stream Authorization for the full contract.
+
 ## Usage Examples
 
 ### Setting Up a Coordinator Node

package/src/cluster/block-transfer-service.ts

@@ -1,4 +1,4 @@
-import type { Startable, Stream } from '@libp2p/interface';
+import type { Connection, Startable, Stream } from '@libp2p/interface';
 import type { IRepo, PeerId, IPeerNetwork, ActionId, ActionRev, IBlock, BlockId } from '@optimystic/db-core';
 import { pipe } from 'it-pipe';
 import * as lp from 'it-length-prefixed';
@@ -7,6 +7,7 @@ import { toString as u8ToString } from 'uint8arrays/to-string';
 import { ProtocolClient } from '../protocol-client.js';
 import { MAX_BLOCK_MESSAGE_BYTES } from '../protocol-limits.js';
 import { createLogger } from '../logger.js';
+import { createInboundStreamAuthorization, type InboundStreamAuthorization, type InboundStreamAuthorizationInit } from '../inbound-authorization.js';
 
 const log = createLogger('block-transfer-service');
 
@@ -61,7 +62,7 @@ export interface IBlockReplicaStore extends IRepo {
 	saveReplicatedBlock(blockId: BlockId, block: IBlock, source?: ActionRev): Promise<void>;
 }
 
-export interface BlockTransferServiceInit {
+export interface BlockTransferServiceInit extends InboundStreamAuthorizationInit {
 	protocolPrefix?: string;
 }
 
@@ -81,6 +82,8 @@ export class BlockTransferService implements Startable {
 	private readonly protocol: string;
 	private readonly repo: IBlockReplicaStore;
 	private readonly registrar: BlockTransferServiceComponents['registrar'];
+	/** Optional embedder authorization gate; `undefined` (the default) means no check runs. */
+	private readonly authorization: InboundStreamAuthorization | undefined;
 
 	constructor(
 		components: BlockTransferServiceComponents,
@@ -89,11 +92,12 @@ export class BlockTransferService implements Startable {
 		this.protocol = buildBlockTransferProtocol(init.protocolPrefix ?? '');
 		this.repo = components.repo;
 		this.registrar = components.registrar;
+		this.authorization = createInboundStreamAuthorization(init, this.protocol, (msg, ...args) => log(msg, ...args));
 	}
 
 	async start(): Promise<void> {
 		if (this.running) return;
-		await this.registrar.handle(this.protocol, async (data: any) => {
+		await this.registrar.handle(this.protocol, async (data: any, connection?: Connection) => {
 			// libp2p invokes the stream handler with the Stream as the FIRST positional argument
 			// (see cluster/repo/dispute services, which all use `(stream, connection)`). The block-
 			// transfer handler previously read `data.stream`, which is `undefined` for the positional
@@ -101,7 +105,7 @@ export class BlockTransferService implements Startable {
 			// never replied, and every push/pull dialled this service hung with no response. Unwrap
 			// defensively (older shape passed `{ stream }`), mirroring sync/service.ts.
 			const stream = data?.stream ?? data;
-			await this.handleRequest(stream);
+			await this.handleRequest(stream, connection);
 		});
 		this.running = true;
 		log('started on %s', this.protocol);
@@ -114,9 +118,12 @@ export class BlockTransferService implements Startable {
 		log('stopped');
 	}
 
-	private async handleRequest(stream: Stream): Promise<void> {
+	private async handleRequest(stream: Stream, connection?: Connection): Promise<void> {
 		const self = this;
 		try {
+			// Authorization runs before ANY decoding or execution. Guarded on the field so a
+			// node without a predicate keeps the original path untouched.
+			if (this.authorization && await this.authorization.deny(stream, connection?.remotePeer?.toString())) return;
 			// Read the request, process it, and write the response on ONE continuous duplex
 			// pipe (mirrors cluster/repo/dispute services). The earlier read-to-end-then-write
 			// design deadlocked over a real stream: the client sends one length-prefixed request

package/src/cluster/cluster-repo.ts

@@ -17,6 +17,8 @@ import type { FretService } from "p2p-fret";
 import type { IPeerReputation } from "../reputation/types.js";
 import { PenaltyReason } from "../reputation/types.js";
 import type { ITransactionStateStore } from "./i-transaction-state-store.js";
+import { isMissingBaseRevisionFailure } from "../storage/storage-repo.js";
+import { RECONCILE_TIMEOUT_MS } from "./reconcile-block.js";
 
 const log = createLogger('cluster-member')
 
@@ -176,7 +178,8 @@ const ExecutedTransactionTtlMs = 10 * 60 * 1000;
 // Upper bound on an awaited active reconciliation of a divergent commit. Bounds the
 // consensus path so a slow/unreachable cohort peer can't stall the cluster stream;
 // a timeout is logged and tolerated (never thrown — that would reset the stream).
-const ReconcileTimeoutMs = 5000;
+// Shared with the read path's acquisition (see RECONCILE_TIMEOUT_MS) — same operation, same bound.
+const ReconcileTimeoutMs = RECONCILE_TIMEOUT_MS;
 
 /**
  * True when a thrown storage error reports a missing pending action — i.e. this
@@ -1124,9 +1127,13 @@ export class ClusterMember implements ICluster {
 	 *   - **behind**: we missed the prior `pend` cluster-transaction (cohort drift
 	 *     between the independent pend and commit phases, or transient unreachability),
 	 *     so we lack the pending action — `StorageRepo.commit` *throws* "Pending
-	 *     action … not found".
+	 *     action … not found";
+	 *   - **behind (no base)**: we DID see the pend, but we never saw the revision that
+	 *     created the block, so the transform has nothing to apply to —
+	 *     `StorageRepo.commit` returns `success:false` with a `missing-base-revision`
+	 *     reason rather than recording a revision it could not materialize.
 	 *
-	 * For the **behind** case we hold no revision of the committed blocks at all, so we
+	 * For both **behind** cases we hold no usable revision of the committed blocks, so we
 	 * actively reconcile: pull the committed revision from a cohort peer that holds it
 	 * (`reconcileBlock`) and restore it locally. Lazy read-repair on a later read cannot
 	 * recover it on its own when cohort drift has left the block under-replicated (no
@@ -1215,7 +1222,8 @@ export class ClusterMember implements ICluster {
 			}
 			if (!result.success) {
 				// success:false is a StaleFailure. `missing` ⇒ ahead/stale divergence
-				// (we already hold ≥ this rev): tolerate, do NOT reconcile downward. A bare
+				// (we already hold ≥ this rev): tolerate, do NOT reconcile downward. A
+				// missing-base reason ⇒ behind divergence, reconcile (below). Any other bare
 				// `reason` with no `missing` ⇒ a genuine internalCommit fault: propagate so
 				// handleConsensus rolls back the executed marker and rethrows.
 				if (result.missing?.length) {
@@ -1228,6 +1236,22 @@ export class ClusterMember implements ICluster {
 					});
 					return;
 				}
+				// This member holds no materializable base for one of the blocks, so
+				// `StorageRepo.commit` REFUSED rather than record a revision it could never serve.
+				// Same "behind" divergence as a missing pend — and the same cure: pull the committed
+				// revision from a cohort peer. Reconciling here (after commit released its per-block
+				// latches) is what makes refusing safe; fetching inside the commit path would deadlock
+				// against the latch `saveReplicatedBlock` needs to persist what it fetched.
+				if (isMissingBaseRevisionFailure(result)) {
+					log('cluster-member:consensus-commit-diverged', {
+						messageHash,
+						actionId: commit.actionId,
+						divergence: 'behind',
+						reason: result.reason
+					});
+					await this.reconcileDivergentCommit(record, commit);
+					return;
+				}
 				throw new Error(`Consensus commit for action ${commit.actionId} failed: ${result.reason ?? 'unknown reason'}`);
 			}
 			return;

package/src/cluster/reconcile-block.ts

@@ -0,0 +1,158 @@
+import type { ActionRev, BlockId, IBlock } from "@optimystic/db-core";
+import type { BlockArchive } from "../storage/struct.js";
+import type { ReconcileBlockCallback } from "./cluster-repo.js";
+import type { IPeerReputation } from "../reputation/types.js";
+import { PenaltyReason } from "../reputation/types.js";
+import {
+	selectQuorumRev, selectQuorumBlock, canonicalBlockHash,
+	type RevClaim, type BlockHashCandidate, type QuorumRev
+} from "./quorum-restore.js";
+import { createLogger } from '../logger.js';
+
+const log = createLogger('reconcile-block');
+
+/**
+ * Wall-clock bound on one whole reconcile pass (all cohort peers, both quorums, the persist).
+ * Shared by both callers so a slow or unreachable cohort peer stalls neither the commit path
+ * (`ClusterMember.withReconcileTimeout` — a stall there holds up consensus execution) nor the read
+ * path (`CoordinatorRepo.restoreCorroborated` — a stall there holds up a caller's `get`).
+ */
+export const RECONCILE_TIMEOUT_MS = 5000;
+
+/** One cohort peer's answer for a block: its highest revision, and the block bytes if it carried them. */
+interface ReconcileCandidate {
+	peerId: string;
+	rev: number;
+	actionId: string;
+	/** Present only when the serving archive carried a materialized block for `rev`. */
+	block?: IBlock;
+}
+
+/** Collaborators {@link createReconcileBlock} needs, injected so the logic stays transport-agnostic. */
+export interface ReconcileBlockDeps {
+	/** This node's own peer id; excluded from the cohort targets. */
+	selfPeerId: string;
+	/** Fetch one cohort peer's archive for `blockId` — `undefined` when it is unreachable or holds nothing. */
+	fetchArchive: (peerId: string, blockId: BlockId) => Promise<BlockArchive | undefined>;
+	/** Persist the agreed content through the churn-replication funnel. */
+	saveReplicatedBlock: (blockId: BlockId, block: IBlock, source: ActionRev) => Promise<void>;
+	/** Proportional corroboration threshold; the cohort's `simpleMajorityThreshold`. */
+	simpleMajorityThreshold: number;
+	/** Configured full cluster size — the floor for {@link corroboratorCapacity}. */
+	clusterSize: number;
+	/** Best-effort misbehavior reporting; a throwing implementation is swallowed. */
+	reputation?: Pick<IPeerReputation, 'reportPeer'>;
+}
+
+/**
+ * How many peers other than this node could answer for the block at all. Mirrors
+ * `CoordinatorRepo.corroboratorCapacity` exactly, and for the same reason: the corroboration
+ * floor may be relaxed only for a cohort that is *genuinely* small, never for one that merely
+ * looks small. `cohortPeerIds` come from the (untrusted) coordinator-declared peer set, so a
+ * self-shrunk record could otherwise talk the requirement down to a single voter; taking the MAX
+ * against the configured `clusterSize` keeps that shrunken view out of the relaxed branch. The
+ * escape hatch for a real two-node deployment is to configure `clusterSize: 2`.
+ */
+function corroboratorCapacity(targets: string[], clusterSize: number): number {
+	return Math.max(targets.length, clusterSize - 1);
+}
+
+/**
+ * The claim a peer's archive makes: its highest revision, provided that revision is at least the
+ * one we committed. `undefined` when the peer served nothing usable (unreachable, empty archive,
+ * or only revisions older than the commit we are healing).
+ */
+function toCandidate(peerId: string, archive: BlockArchive | undefined, committedRev: number): ReconcileCandidate | undefined {
+	if (!archive) return undefined;
+	const revs = Object.keys(archive.revisions).map(Number);
+	if (revs.length === 0) return undefined;
+	const maxRev = Math.max(...revs);
+	if (maxRev < committedRev) return undefined;
+	const data = archive.revisions[maxRev];
+	if (!data?.action) return undefined;
+	return { peerId, rev: maxRev, actionId: data.action.actionId, block: data.block };
+}
+
+/** Hash the block bytes of every candidate that both corroborates `selected` and actually carried content. */
+async function hashCarriers(candidates: ReconcileCandidate[], selected: QuorumRev): Promise<BlockHashCandidate[]> {
+	const carriers = candidates.filter(c => c.rev === selected.rev && c.actionId === selected.actionId && c.block);
+	return await Promise.all(
+		carriers.map(async c => ({ peerId: c.peerId, hash: await canonicalBlockHash(c.block!), block: c.block! }))
+	);
+}
+
+/** Report cohort members that served content contradicting the agreed hash. Best-effort; never throws. */
+function penalizeContradictingContent(
+	reputation: Pick<IPeerReputation, 'reportPeer'> | undefined,
+	candidates: BlockHashCandidate[],
+	agreedHash: string,
+	blockId: BlockId
+): void {
+	if (!reputation) return;
+	try {
+		for (const c of candidates) {
+			if (c.hash !== agreedHash) {
+				reputation.reportPeer(c.peerId, PenaltyReason.InvalidRestoration, `reconcile:${blockId}`);
+			}
+		}
+	} catch (err) {
+		log('reconcile:penalize-error', { blockId, error: (err as Error).message });
+	}
+}
+
+/**
+ * Active reconciliation for a block this member committed without a materializable base
+ * (cohort drift between the independent pend and commit cluster-transactions, or a refused
+ * `missing-base-revision` commit). Queries the commit cohort — self already excluded by
+ * `ClusterMember.reconcileDivergentCommit` — for the block, picks the target revision by quorum
+ * corroboration rather than raw `Math.max` (a lone peer inflating its rev cannot steer
+ * reconciliation), verifies the cohort agrees on the *content* at that revision, and persists it.
+ *
+ * Both quorums are capped by {@link corroboratorCapacity}: demanding two corroborators from a
+ * cohort that contains exactly one other peer is a permanent deadlock, not a safety property —
+ * the node can never heal and stays unreadable forever.
+ *
+ * **Exposure at capacity 1 (documented, not accidental).** Block ids are random 256-bit strings
+ * (`db-core` `structs.ts`), NOT content-addressed, so nothing on the receive path can re-derive
+ * the id from the bytes: `canonicalBlockHash` is a cross-peer *agreement* hash, never a check
+ * against `blockId`. A sole cohort peer's content is therefore believed on its word. That adds no
+ * trust the cohort had not already extended — the same peer's `(rev, actionId)` claim is likewise
+ * uncorroborable at that size (see `selectQuorumRev`'s capacity note), and a two-member cohort has
+ * no honest majority to appeal to in the first place. Closing it needs commit-cert verification,
+ * tracked by backlog `debt-read-repair-commit-cert-verification`.
+ *
+ * Declines are cheap and retryable: nothing is persisted, nothing is marked, and the next commit
+ * or churn/rebalance pass tries again.
+ */
+export function createReconcileBlock(deps: ReconcileBlockDeps): ReconcileBlockCallback {
+	return async (blockId, committed, cohortPeerIds) => {
+		const targets = cohortPeerIds.filter(id => id !== deps.selfPeerId);
+		if (targets.length === 0) return;
+
+		const fetched = await Promise.all(
+			targets.map(async peerId => toCandidate(peerId, await deps.fetchArchive(peerId, blockId), committed.rev))
+		);
+		const candidates = fetched.filter((c): c is ReconcileCandidate => c !== undefined);
+		const capacity = corroboratorCapacity(targets, deps.clusterSize);
+
+		const revClaims: RevClaim[] = candidates.map(({ peerId, rev, actionId }) => ({ peerId, rev, actionId }));
+		const selected = selectQuorumRev(revClaims, deps.simpleMajorityThreshold, capacity);
+		if (!selected) {
+			// Leave the block behind; churn/rebalance and the next commit retry.
+			log('reconcile:no-rev-quorum', { blockId, rev: committed.rev, responders: revClaims.length, capacity });
+			return;
+		}
+
+		const hashCandidates = await hashCarriers(candidates, selected);
+		const agreed = selectQuorumBlock(hashCandidates, deps.simpleMajorityThreshold, capacity);
+		if (!agreed) {
+			log('reconcile:no-content-quorum', { blockId, rev: selected.rev, carriers: hashCandidates.length, capacity });
+			return;
+		}
+
+		penalizeContradictingContent(deps.reputation, hashCandidates, agreed.hash, blockId);
+
+		await deps.saveReplicatedBlock(blockId, agreed.block, { actionId: selected.actionId, rev: selected.rev });
+		log('reconcile:restored', { blockId, rev: selected.rev, actionId: selected.actionId });
+	};
+}

package/src/cluster/service.ts

@@ -7,6 +7,7 @@ import { encodePeers, type RedirectPayload } from '../repo/redirect.js';
 import { toClusterErrorEnvelope } from './cluster-error.js';
 import { MAX_CONTROL_MESSAGE_BYTES } from '../protocol-limits.js';
 import type { Uint8ArrayList } from 'uint8arraylist';
+import { createInboundStreamAuthorization, type InboundStreamAuthorization, type InboundStreamAuthorizationInit } from '../inbound-authorization.js';
 
 interface BaseComponents {
 	logger: { forComponent: (name: string) => Logger },
@@ -31,7 +32,7 @@ export interface ClusterServiceComponents extends BaseComponents {
 	getConnectionAddrs?: (peerId: PeerId) => string[]
 }
 
-export interface ClusterServiceInit {
+export interface ClusterServiceInit extends InboundStreamAuthorizationInit {
 	protocol?: string,
 	protocolPrefix?: string,
 	maxInboundStreams?: number,
@@ -65,6 +66,8 @@ export class ClusterService implements Startable {
 	private running: boolean;
 	/** Responsibility K - small-mesh bypass threshold for redirect decisions */
 	private readonly responsibilityK: number;
+	/** Optional embedder authorization gate; `undefined` (the default) means no check runs. */
+	private readonly authorization: InboundStreamAuthorization | undefined;
 
 	constructor(components: ClusterServiceComponents, init: ClusterServiceInit = {}) {
 		this.components = components;
@@ -75,6 +78,7 @@ export class ClusterService implements Startable {
 		this.cluster = components.cluster;
 		this.running = false;
 		this.responsibilityK = init.responsibilityK ?? 1;
+		this.authorization = createInboundStreamAuthorization(init, this.protocol, (msg, ...args) => this.log.error(msg, ...args));
 	}
 
 	readonly [Symbol.toStringTag] = '@libp2p/cluster';
@@ -180,8 +184,8 @@ export class ClusterService implements Startable {
 		throw new Error(`Unknown operation: ${message.operation}`);
 	}
 
-	private handleIncomingStream(stream: Stream, connection: Connection): void {
-		const peerId = connection.remotePeer;
+	private handleIncomingStream(stream: Stream, connection?: Connection): void {
+		const peerId = connection?.remotePeer;
 
 		const processStream = async function* (this: ClusterService, source: AsyncIterable<Uint8ArrayList>) {
 			for await (const msg of source) {
@@ -215,6 +219,9 @@ export class ClusterService implements Startable {
 
 		void (async () => {
 			try {
+				// Authorization runs before ANY decoding or execution. Guarded on the field so a
+				// node without a predicate keeps the original path untouched.
+				if (this.authorization && await this.authorization.deny(stream, peerId?.toString())) return;
 				const responses = pipe(
 					stream,
 					(source) => lpDecode(source, { maxDataLength: MAX_CONTROL_MESSAGE_BYTES }),

package/src/inbound-authorization.ts

@@ -0,0 +1,184 @@
+/**
+ * Optional, embedder-supplied authorization for inbound protocol streams.
+ *
+ * The `repo`, `cluster`, `sync` and `block-transfer` services otherwise go straight from
+ * "stream opened" to "decode and execute", so any peer that can open a connection can issue
+ * database operations. An application that owns a *private* database (only nodes it admitted
+ * may read or write) needs a seam ahead of decoding; this is that seam.
+ *
+ * Contract:
+ *
+ * - **Absent predicate → today's behavior exactly.** Every service holds
+ *   `InboundStreamAuthorization | undefined`; when it is `undefined` the handler never
+ *   awaits anything extra and no code on this path runs.
+ * - **Supplied predicate → fail closed.** Only a literal `true` allows the stream. `false`,
+ *   a throw, a rejection, a timeout, or an unidentifiable remote peer all deny, and denial
+ *   aborts the stream *before* any frame is decoded or any operation executed.
+ * - **Called once per inbound stream**, not once per operation — which is equivalent here
+ *   because all four protocols are strictly one request per stream (each handler's generator
+ *   `return`s after the first response, so a second queued frame is never read).
+ * - **Peer id encoding**: the predicate receives `connection.remotePeer.toString()` — the
+ *   libp2p base58btc/CIDv1 peer-id string (e.g. `12D3KooW…`), the same form
+ *   `PeerId.toString()` produces everywhere else in this codebase. Compare against that,
+ *   never against a multiaddr, a public-key hash, or a base64 encoding.
+ * - **What a caller observes**: a stream reset. Denial is deliberately *not* reported on the
+ *   wire — telling an unauthorized peer "you are not a member" confirms membership state to
+ *   exactly the party the embedder decided not to trust, and the four protocols have four
+ *   different response shapes with no common error frame. The denial is instead loud on the
+ *   *denying* node: it is logged with the peer id, protocol and reason, and the stream is
+ *   aborted with an {@link UnauthorizedInboundStreamError} carrying
+ *   {@link INBOUND_STREAM_UNAUTHORIZED_CODE}, so local diagnostics can tell a denial apart
+ *   from a transport fault.
+ * - **Cost**: the predicate sits in the hot path of every inbound stream, ahead of the work
+ *   that stream would do. Embedders are expected to make it cheap — an in-memory set lookup —
+ *   and to memoize anything that would otherwise hit storage or the network per stream.
+ */
+
+/**
+ * Predicate deciding whether `remotePeerId` may open `protocol` on this node.
+ *
+ * @param remotePeerId the dialing peer's `PeerId.toString()` (base58btc / CIDv1, `12D3KooW…`)
+ * @param protocol the full protocol id the stream was opened on, e.g.
+ *   `/optimystic/<network>/repo/1.0.0`
+ * @returns `true` to allow. Anything else — `false`, a throw, or a rejection — denies.
+ */
+export type AuthorizeInboundStream = (remotePeerId: string, protocol: string) => Promise<boolean> | boolean;
+
+/** Stable error code carried by {@link UnauthorizedInboundStreamError}. */
+export const INBOUND_STREAM_UNAUTHORIZED_CODE = 'ERR_INBOUND_STREAM_UNAUTHORIZED';
+
+/**
+ * The reason an inbound stream was aborted by the authorization gate. Distinct from a
+ * transport fault so the denying node's logs and any local abort-reason inspection can tell
+ * the two apart; the remote only ever sees the stream reset (see the module doc).
+ */
+export class UnauthorizedInboundStreamError extends Error {
+	readonly code = INBOUND_STREAM_UNAUTHORIZED_CODE;
+	constructor(remotePeerId: string, protocol: string, reason: string) {
+		super(`inbound stream denied: peer=${remotePeerId} protocol=${protocol} reason=${reason}`);
+		this.name = 'UnauthorizedInboundStreamError';
+	}
+}
+
+/**
+ * How long the predicate may take before the stream is denied. A hanging predicate would
+ * otherwise pin an inbound stream slot indefinitely; timing out is the fail-closed reading of
+ * "we could not establish that this peer is allowed".
+ */
+export const DEFAULT_INBOUND_AUTHORIZATION_TIMEOUT_MS = 5_000;
+
+/** The slice of a service's init that configures this gate. Mixed into all four service inits. */
+export interface InboundStreamAuthorizationInit {
+	/**
+	 * Optional predicate consulted once per inbound stream, before any decoding or execution.
+	 * Absent → no check at all. See {@link AuthorizeInboundStream}.
+	 */
+	authorizeInboundStream?: AuthorizeInboundStream;
+	/**
+	 * Deadline for {@link InboundStreamAuthorizationInit.authorizeInboundStream}; expiry denies
+	 * the stream. Default {@link DEFAULT_INBOUND_AUTHORIZATION_TIMEOUT_MS}.
+	 */
+	authorizeInboundStreamTimeoutMs?: number;
+}
+
+/** The part of a libp2p `Stream` this gate needs: the ability to tear it down. */
+interface AbortableStream {
+	abort: (err: Error) => void;
+}
+
+/** Log sink shape shared by the component loggers and the `debug` loggers the services use. */
+export type AuthorizationLog = (message: string, ...args: unknown[]) => void;
+
+/** Marker resolved by the deadline race when the predicate has not settled in time. */
+const TIMED_OUT = Symbol('inbound-authorization-timeout');
+
+/**
+ * A configured authorization gate for one service's protocol. Constructed only when the
+ * embedder supplied a predicate, so a service holding `undefined` runs the original code path.
+ */
+export class InboundStreamAuthorization {
+	constructor(
+		private readonly authorize: AuthorizeInboundStream,
+		private readonly protocol: string,
+		private readonly timeoutMs: number,
+		private readonly log: AuthorizationLog
+	) { }
+
+	/**
+	 * Consult the predicate for one inbound stream and abort the stream if it is not allowed.
+	 *
+	 * @returns `true` when the stream was denied — the caller must return immediately without
+	 *   decoding anything — and `false` when it may proceed.
+	 */
+	async deny(stream: AbortableStream, remotePeerId: string | undefined): Promise<boolean> {
+		// No identifiable remote → the predicate cannot be asked, so we cannot establish
+		// authorization. Fail closed rather than fall through to execution.
+		if (remotePeerId === undefined) {
+			return this.abort(stream, '<unidentified>', 'no remote peer id on the inbound connection');
+		}
+		const verdict = await this.decide(remotePeerId);
+		return verdict.allowed ? false : this.abort(stream, remotePeerId, verdict.reason);
+	}
+
+	/** Run the predicate under its deadline, converting every failure mode into a denial. */
+	private async decide(remotePeerId: string): Promise<{ allowed: true } | { allowed: false, reason: string }> {
+		let timer: ReturnType<typeof setTimeout> | undefined;
+		try {
+			const verdict = this.authorize(remotePeerId, this.protocol);
+			// A synchronous predicate needs no timer at all.
+			if (typeof verdict === 'boolean') {
+				return verdict ? { allowed: true } : { allowed: false, reason: 'predicate returned false' };
+			}
+			const decision = await Promise.race([
+				verdict,
+				new Promise<typeof TIMED_OUT>(resolve => { timer = setTimeout(() => resolve(TIMED_OUT), this.timeoutMs); })
+			]);
+			if (decision === TIMED_OUT) {
+				return { allowed: false, reason: `predicate did not settle within ${this.timeoutMs}ms` };
+			}
+			return decision === true ? { allowed: true } : { allowed: false, reason: 'predicate returned false' };
+		} catch (err) {
+			// A throwing predicate is a bug in the embedder, not permission to proceed: log it
+			// (never swallow) and deny.
+			this.log('authorization predicate threw for peer=%s protocol=%s - %o', remotePeerId, this.protocol, err);
+			return { allowed: false, reason: `predicate threw: ${err instanceof Error ? err.message : String(err)}` };
+		} finally {
+			if (timer !== undefined) clearTimeout(timer);
+		}
+	}
+
+	/** Log the denial and tear the stream down. Always returns `true` (denied). */
+	private abort(stream: AbortableStream, remotePeerId: string, reason: string): true {
+		const error = new UnauthorizedInboundStreamError(remotePeerId, this.protocol, reason);
+		this.log('inbound stream denied peer=%s protocol=%s reason=%s', remotePeerId, this.protocol, reason);
+		try {
+			stream.abort(error);
+		} catch (err) {
+			// The stream may already be torn down; the denial itself still stands.
+			this.log('aborting a denied stream failed peer=%s protocol=%s - %o', remotePeerId, this.protocol, err);
+		}
+		return true;
+	}
+}
+
+/**
+ * Build the gate for a service, or `undefined` when the embedder supplied no predicate.
+ *
+ * Returning `undefined` (rather than an always-allow gate) is what makes the absent-predicate
+ * case genuinely free: the call site guards on the field and never awaits.
+ */
+export function createInboundStreamAuthorization(
+	init: InboundStreamAuthorizationInit,
+	protocol: string,
+	log: AuthorizationLog
+): InboundStreamAuthorization | undefined {
+	if (init.authorizeInboundStream === undefined) {
+		return undefined;
+	}
+	return new InboundStreamAuthorization(
+		init.authorizeInboundStream,
+		protocol,
+		init.authorizeInboundStreamTimeoutMs ?? DEFAULT_INBOUND_AUTHORIZATION_TIMEOUT_MS,
+		log
+	);
+}

package/src/index.ts

@@ -6,6 +6,7 @@ export * from "./cluster/rebalance-monitor.js";
 export * from "./cluster/spread-on-churn.js";
 export * from "./cluster/block-transfer.js";
 export * from "./cluster/block-transfer-service.js";
+export * from "./inbound-authorization.js";
 export * from "./protocol-client.js";
 export * from "./repo/client.js";
 export * from "./repo/cluster-coordinator.js";