@cello-protocol/daemon 0.0.3 → 0.0.4

package/dist/session-connection-gater.d.ts

@@ -0,0 +1,91 @@
+/**
+ * CELLO Daemon — SessionConnectionGater
+ *
+ * Implements the libp2p ConnectionGater interface to enforce per-session
+ * peer allowlists on ephemeral session nodes.
+ *
+ * Two modes:
+ *   1. Session node gater: allows exactly one counterparty Peer ID.
+ *      Created with the counterparty's Peer ID at session node creation.
+ *   2. Standing receiver gater: starts OPEN (all peers allowed) because
+ *      the counterparty is unknown at creation time. Call setAllowedPeer()
+ *      before handing the node's multiaddr to the directory (AC-015).
+ *   3. Directory node gater: delegates to DirectoryPeerIdProvider.
+ *      Allows only known directory Peer IDs (MANIFEST-002 fills the real set).
+ *
+ * The gater uses denyInboundConnection (before Noise handshake) to reject
+ * unexpected peers as early as possible. Since PeerId is not yet known at
+ * that point, we use denyInboundEncryptedConnection (after Noise, before muxer)
+ * which has the PeerId and still occurs before any streams are opened.
+ *
+ * Observability: session.node.connection.rejected (WARN) is logged with
+ * sessionId, attemptedPeerId, and expectedPeerId.
+ */
+import type { ConnectionGater, MultiaddrConnection } from "@libp2p/interface";
+import type { PeerId } from "@libp2p/interface";
+import type { Logger } from "./types.js";
+/**
+ * Interface for providing directory Peer IDs to the directory-facing node gater.
+ * Stub for DAEMON-002: MANIFEST-002 replaces with manifest-backed implementation.
+ */
+export interface DirectoryPeerIdProvider {
+    isDirectoryPeer(peerId: string): boolean;
+}
+/** Permissive stub: allows all peers. Used for directory node in DAEMON-002. */
+export declare class PermissiveDirectoryPeerIdProvider implements DirectoryPeerIdProvider {
+    isDirectoryPeer(_peerId: string): boolean;
+}
+/** Restrictive stub: denies all peers. Used in unit tests (AC-016). */
+export declare class EmptyDirectoryPeerIdProvider implements DirectoryPeerIdProvider {
+    isDirectoryPeer(_peerId: string): boolean;
+}
+/**
+ * SessionConnectionGater — enforces a single allowed Peer ID on a session node.
+ *
+ * Initially open (allowedPeerId = null) for the standing receiver. Close the
+ * window by calling setAllowedPeer(initiatorPeerId) before returning the
+ * node's multiaddr to the caller (AC-015).
+ */
+export declare class SessionConnectionGater implements ConnectionGater {
+    #private;
+    constructor(opts: {
+        sessionId: string;
+        allowedPeerId: string | null;
+        logger: Logger;
+    });
+    /** Update the allowed Peer ID (called when standing receiver is claimed). */
+    setAllowedPeer(peerId: string): void;
+    /**
+     * M7 DOD-SPINE-6: permit an OUTBOUND connection to the relay witness (a third peer,
+     * authorized by the FROST-signed assignment). Does NOT widen the inbound allowlist.
+     */
+    setAllowedOutboundPeer(peerId: string): void;
+    getSessionId(): string;
+    getAllowedPeerId(): string | null;
+    /**
+     * denyInboundEncryptedConnection — called after Noise handshake, before muxer.
+     * This is the enforcement point for inbound connections: PeerId is known here.
+     * Return true to DENY the connection.
+     */
+    denyInboundEncryptedConnection(peerId: PeerId, _maConn: MultiaddrConnection): boolean;
+    /**
+     * denyOutboundEncryptedConnection — symmetric gate for outbound connections.
+     * Session nodes should only connect to the designated counterparty.
+     * Return true to DENY the connection.
+     */
+    denyOutboundEncryptedConnection(peerId: PeerId, _maConn: MultiaddrConnection): boolean;
+}
+/**
+ * DirectoryConnectionGater — enforces directory-only connections on the
+ * directory-facing node. Delegates to DirectoryPeerIdProvider.
+ *
+ * Logs session.node.connection.rejected (using sessionId='directory') when
+ * a non-directory peer is denied.
+ */
+export declare class DirectoryConnectionGater implements ConnectionGater {
+    #private;
+    constructor(provider: DirectoryPeerIdProvider, logger: Logger);
+    denyInboundEncryptedConnection(peerId: PeerId, _maConn: MultiaddrConnection): boolean;
+    denyOutboundEncryptedConnection(peerId: PeerId, _maConn: MultiaddrConnection): boolean;
+}
+//# sourceMappingURL=session-connection-gater.d.ts.map

package/dist/session-connection-gater.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-connection-gater.d.ts","sourceRoot":"","sources":["../src/session-connection-gater.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC9E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1C;AAED,gFAAgF;AAChF,qBAAa,iCAAkC,YAAW,uBAAuB;IAC/E,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;CAG1C;AAED,uEAAuE;AACvE,qBAAa,4BAA6B,YAAW,uBAAuB;IAC1E,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;CAG1C;AAED;;;;;;GAMG;AACH,qBAAa,sBAAuB,YAAW,eAAe;;gBAYhD,IAAI,EAAE;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;QAC7B,MAAM,EAAE,MAAM,CAAC;KAChB;IAMD,6EAA6E;IAC7E,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAIpC;;;OAGG;IACH,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAI5C,YAAY,IAAI,MAAM;IAItB,gBAAgB,IAAI,MAAM,GAAG,IAAI;IAIjC;;;;OAIG;IACH,8BAA8B,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,GAAG,OAAO;IAIrF;;;;OAIG;IACH,+BAA+B,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,GAAG,OAAO;CAwBvF;AAED;;;;;;GAMG;AACH,qBAAa,wBAAyB,YAAW,eAAe;;gBAIlD,QAAQ,EAAE,uBAAuB,EAAE,MAAM,EAAE,MAAM;IAK7D,8BAA8B,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,GAAG,OAAO;IAIrF,+BAA+B,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,GAAG,OAAO;CAgBvF"}

package/dist/session-connection-gater.js

@@ -0,0 +1,146 @@
+/**
+ * CELLO Daemon — SessionConnectionGater
+ *
+ * Implements the libp2p ConnectionGater interface to enforce per-session
+ * peer allowlists on ephemeral session nodes.
+ *
+ * Two modes:
+ *   1. Session node gater: allows exactly one counterparty Peer ID.
+ *      Created with the counterparty's Peer ID at session node creation.
+ *   2. Standing receiver gater: starts OPEN (all peers allowed) because
+ *      the counterparty is unknown at creation time. Call setAllowedPeer()
+ *      before handing the node's multiaddr to the directory (AC-015).
+ *   3. Directory node gater: delegates to DirectoryPeerIdProvider.
+ *      Allows only known directory Peer IDs (MANIFEST-002 fills the real set).
+ *
+ * The gater uses denyInboundConnection (before Noise handshake) to reject
+ * unexpected peers as early as possible. Since PeerId is not yet known at
+ * that point, we use denyInboundEncryptedConnection (after Noise, before muxer)
+ * which has the PeerId and still occurs before any streams are opened.
+ *
+ * Observability: session.node.connection.rejected (WARN) is logged with
+ * sessionId, attemptedPeerId, and expectedPeerId.
+ */
+/** Permissive stub: allows all peers. Used for directory node in DAEMON-002. */
+export class PermissiveDirectoryPeerIdProvider {
+    isDirectoryPeer(_peerId) {
+        return true;
+    }
+}
+/** Restrictive stub: denies all peers. Used in unit tests (AC-016). */
+export class EmptyDirectoryPeerIdProvider {
+    isDirectoryPeer(_peerId) {
+        return false;
+    }
+}
+/**
+ * SessionConnectionGater — enforces a single allowed Peer ID on a session node.
+ *
+ * Initially open (allowedPeerId = null) for the standing receiver. Close the
+ * window by calling setAllowedPeer(initiatorPeerId) before returning the
+ * node's multiaddr to the caller (AC-015).
+ */
+export class SessionConnectionGater {
+    #allowedPeerId;
+    /**
+     * M7 DOD-SPINE-6: an additional peer the session node may connect to OUTBOUND only —
+     * the relay witness. The session node dials the relay (Structure-2 hash submit); the
+     * relay never dials back. Kept OUTBOUND-only so the INBOUND counterparty-only invariant
+     * (INV-5 — a session node admits exactly one counterparty) is fully preserved.
+     */
+    #allowedOutboundPeerId = null;
+    #sessionId;
+    #logger;
+    constructor(opts) {
+        this.#sessionId = opts.sessionId;
+        this.#allowedPeerId = opts.allowedPeerId;
+        this.#logger = opts.logger;
+    }
+    /** Update the allowed Peer ID (called when standing receiver is claimed). */
+    setAllowedPeer(peerId) {
+        this.#allowedPeerId = peerId;
+    }
+    /**
+     * M7 DOD-SPINE-6: permit an OUTBOUND connection to the relay witness (a third peer,
+     * authorized by the FROST-signed assignment). Does NOT widen the inbound allowlist.
+     */
+    setAllowedOutboundPeer(peerId) {
+        this.#allowedOutboundPeerId = peerId;
+    }
+    getSessionId() {
+        return this.#sessionId;
+    }
+    getAllowedPeerId() {
+        return this.#allowedPeerId;
+    }
+    /**
+     * denyInboundEncryptedConnection — called after Noise handshake, before muxer.
+     * This is the enforcement point for inbound connections: PeerId is known here.
+     * Return true to DENY the connection.
+     */
+    denyInboundEncryptedConnection(peerId, _maConn) {
+        return this.#denyIfNotAllowed(peerId);
+    }
+    /**
+     * denyOutboundEncryptedConnection — symmetric gate for outbound connections.
+     * Session nodes should only connect to the designated counterparty.
+     * Return true to DENY the connection.
+     */
+    denyOutboundEncryptedConnection(peerId, _maConn) {
+        // The relay witness is an OUTBOUND-only allowance (the session node dials it).
+        if (this.#allowedOutboundPeerId !== null && peerId.toString() === this.#allowedOutboundPeerId) {
+            return false; // allow
+        }
+        return this.#denyIfNotAllowed(peerId);
+    }
+    #denyIfNotAllowed(peerId) {
+        // If no allowed peer set (fully open gater), allow all.
+        if (this.#allowedPeerId === null) {
+            return false;
+        }
+        const attemptedPeerId = peerId.toString();
+        if (attemptedPeerId === this.#allowedPeerId) {
+            return false; // allow
+        }
+        this.#logger.warn("session.node.connection.rejected", {
+            sessionId: this.#sessionId,
+            attemptedPeerId,
+            expectedPeerId: this.#allowedPeerId,
+        });
+        return true; // deny
+    }
+}
+/**
+ * DirectoryConnectionGater — enforces directory-only connections on the
+ * directory-facing node. Delegates to DirectoryPeerIdProvider.
+ *
+ * Logs session.node.connection.rejected (using sessionId='directory') when
+ * a non-directory peer is denied.
+ */
+export class DirectoryConnectionGater {
+    #provider;
+    #logger;
+    constructor(provider, logger) {
+        this.#provider = provider;
+        this.#logger = logger;
+    }
+    denyInboundEncryptedConnection(peerId, _maConn) {
+        return this.#denyIfNotDirectory(peerId);
+    }
+    denyOutboundEncryptedConnection(peerId, _maConn) {
+        return this.#denyIfNotDirectory(peerId);
+    }
+    #denyIfNotDirectory(peerId) {
+        const peerIdStr = peerId.toString();
+        if (this.#provider.isDirectoryPeer(peerIdStr)) {
+            return false; // allow
+        }
+        this.#logger.warn("session.node.connection.rejected", {
+            sessionId: "__directory_facing__",
+            attemptedPeerId: peerIdStr,
+            expectedPeerId: "known_directory_peer",
+        });
+        return true; // deny
+    }
+}
+//# sourceMappingURL=session-connection-gater.js.map

package/dist/session-connection-gater.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-connection-gater.js","sourceRoot":"","sources":["../src/session-connection-gater.ts"],"names":[],"mappings":"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"}