@cello-protocol/transport 0.0.2

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @cello-protocol/transport — public API
+ *
+ * Exports the CelloNode factory, interface, protocol constants, and error types.
+ */
+export { createNode } from "./node.js";
+export type { CelloNode, CreateNodeOptions, CelloStreamHandler } from "./types.js";
+export type { CelloTransportError, ProtocolNotSupportedError, ConnectionLostError, NodeStoppedError, ListenFailedError, } from "./types.js";
+export { CELLO_PROTOCOL_ID, CIRCUIT_RELAY_V2_HOP_PROTOCOL_ID, CELLO_CONTENT_PROTOCOL_ID } from "./protocols.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,YAAY,EAAE,SAAS,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACnF,YAAY,EACV,mBAAmB,EACnB,yBAAyB,EACzB,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,iBAAiB,EAAE,gCAAgC,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+/**
+ * @cello-protocol/transport — public API
+ *
+ * Exports the CelloNode factory, interface, protocol constants, and error types.
+ */
+export { createNode } from "./node.js";
+export { CELLO_PROTOCOL_ID, CIRCUIT_RELAY_V2_HOP_PROTOCOL_ID, CELLO_CONTENT_PROTOCOL_ID } from "./protocols.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AASvC,OAAO,EAAE,iBAAiB,EAAE,gCAAgC,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/node.d.ts

@@ -0,0 +1,82 @@
+/**
+ * CELLO Transport — node.ts
+ *
+ * createNode() and CelloNodeImpl: libp2p node bootstrap for the CELLO protocol.
+ *
+ * PSEUDOCODE (Phase P) — preserved as reference:
+ *
+ * createNode({ keyProvider, listenAddresses }):
+ *   1. Generate a fresh Ed25519 keypair via @libp2p/crypto/keys generateKeyPair('Ed25519').
+ *      This keypair is the libp2p transport identity (Peer ID + Noise handshake key).
+ *      It is completely independent of keyProvider — ADR-0001 invariant.
+ *      Noise spec reference: https://noiseprotocol.org/noise.html (XX pattern)
+ *      libp2p Noise spec: https://github.com/libp2p/specs/tree/master/noise
+ *   2. Call createLibp2p({
+ *        privateKey: freshKeypair,
+ *        addresses: { listen: listenAddresses },
+ *        transports: [tcp(), webSockets()],
+ *        connectionEncrypters: [noise()],   // ONLY Noise — no plaintext. SI-001.
+ *        streamMuxers: [yamux()],
+ *        services: {
+ *          identify: identify(),
+ *          relay: circuitRelayServer(),      // advertises HOP protocol
+ *          dcutr: dcutr(),
+ *        },
+ *      })
+ *   3. Do NOT start the libp2p node — return it in stopped state. AC-001 says
+ *      start() is called separately.
+ *   4. Wrap in CelloNodeImpl which stores keyProvider (for MSG-001 use) but
+ *      never calls keyProvider.getPublicKey() or keyProvider.sign(). SI-002.
+ *
+ * node.start():
+ *   - Call libp2p.start()
+ *   - node is now listening on configured addresses
+ *
+ * node.stop():
+ *   - Call libp2p.stop()
+ *   - All connections/streams are closed
+ *   - listenAddresses() will return []
+ *
+ * node.dial(multiaddr):
+ *   - If stopped: throw { reason: 'node_stopped', message }
+ *   - multiaddr string → multiaddr object via @multiformats/multiaddr
+ *   - libp2p.dial(multiaddr) → Connection
+ *   - Return { peerId: connection.remotePeer.toString() }
+ *
+ * node.handle(protocolId, handler):
+ *   - libp2p.handle(protocolId, ({stream}) => handler(stream))
+ *
+ * node.newStream(peerId, protocolId):
+ *   - If stopped: throw { reason: 'node_stopped', message }
+ *   - Get existing connections to peerId
+ *   - If no open connections: throw { reason: 'connection_lost', peerId, message }
+ *   - connection.newStream(protocolId):
+ *     - On protocol negotiation failure (UnsupportedProtocolError): throw { reason: 'protocol_not_supported', protocolId, message }
+ *     - On connection error: throw { reason: 'connection_lost', peerId, message }
+ *   - Return stream
+ *
+ * node.listenAddresses():
+ *   - Return libp2p.getMultiaddrs().map(ma => ma.toString())
+ *   - Returns [] when stopped (libp2p returns empty array)
+ *
+ * Stream framing: it-length-prefixed (unsigned varint prefix per multiformats spec)
+ * Use lp.encode(source) / lp.decode(source) with it-pipe for composing pipelines.
+ */
+import type { CelloNode, CreateNodeOptions } from "./types.js";
+/**
+ * Create a new CelloNode in stopped state.
+ *
+ * CRITICAL (ADR-0001 / SI-002):
+ * - A fresh libp2p-managed Ed25519 keypair is generated here.
+ * - This keypair drives the transport Peer ID and Noise handshake.
+ * - keyProvider is stored but NEVER called during createNode() or start().
+ * - The node's Peer ID will differ from any PeerId derived from keyProvider.
+ *
+ * Transport stack:
+ *   - Transports: TCP + WebSockets
+ *   - Security: Noise ONLY (XX pattern, RFC: https://noiseprotocol.org/noise.html)
+ *   - Muxer: Yamux
+ *   - Services: identify, circuitRelayServer (advertises HOP), DCuTR
+ */
+export declare function createNode(opts: CreateNodeOptions): Promise<CelloNode>;
+//# sourceMappingURL=node.d.ts.map

package/dist/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AAeH,OAAO,KAAK,EACV,SAAS,EAET,iBAAiB,EAClB,MAAM,YAAY,CAAC;AA4KpB;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,SAAS,CAAC,CAmC5E"}

package/dist/node.js

@@ -0,0 +1,261 @@
+/**
+ * CELLO Transport — node.ts
+ *
+ * createNode() and CelloNodeImpl: libp2p node bootstrap for the CELLO protocol.
+ *
+ * PSEUDOCODE (Phase P) — preserved as reference:
+ *
+ * createNode({ keyProvider, listenAddresses }):
+ *   1. Generate a fresh Ed25519 keypair via @libp2p/crypto/keys generateKeyPair('Ed25519').
+ *      This keypair is the libp2p transport identity (Peer ID + Noise handshake key).
+ *      It is completely independent of keyProvider — ADR-0001 invariant.
+ *      Noise spec reference: https://noiseprotocol.org/noise.html (XX pattern)
+ *      libp2p Noise spec: https://github.com/libp2p/specs/tree/master/noise
+ *   2. Call createLibp2p({
+ *        privateKey: freshKeypair,
+ *        addresses: { listen: listenAddresses },
+ *        transports: [tcp(), webSockets()],
+ *        connectionEncrypters: [noise()],   // ONLY Noise — no plaintext. SI-001.
+ *        streamMuxers: [yamux()],
+ *        services: {
+ *          identify: identify(),
+ *          relay: circuitRelayServer(),      // advertises HOP protocol
+ *          dcutr: dcutr(),
+ *        },
+ *      })
+ *   3. Do NOT start the libp2p node — return it in stopped state. AC-001 says
+ *      start() is called separately.
+ *   4. Wrap in CelloNodeImpl which stores keyProvider (for MSG-001 use) but
+ *      never calls keyProvider.getPublicKey() or keyProvider.sign(). SI-002.
+ *
+ * node.start():
+ *   - Call libp2p.start()
+ *   - node is now listening on configured addresses
+ *
+ * node.stop():
+ *   - Call libp2p.stop()
+ *   - All connections/streams are closed
+ *   - listenAddresses() will return []
+ *
+ * node.dial(multiaddr):
+ *   - If stopped: throw { reason: 'node_stopped', message }
+ *   - multiaddr string → multiaddr object via @multiformats/multiaddr
+ *   - libp2p.dial(multiaddr) → Connection
+ *   - Return { peerId: connection.remotePeer.toString() }
+ *
+ * node.handle(protocolId, handler):
+ *   - libp2p.handle(protocolId, ({stream}) => handler(stream))
+ *
+ * node.newStream(peerId, protocolId):
+ *   - If stopped: throw { reason: 'node_stopped', message }
+ *   - Get existing connections to peerId
+ *   - If no open connections: throw { reason: 'connection_lost', peerId, message }
+ *   - connection.newStream(protocolId):
+ *     - On protocol negotiation failure (UnsupportedProtocolError): throw { reason: 'protocol_not_supported', protocolId, message }
+ *     - On connection error: throw { reason: 'connection_lost', peerId, message }
+ *   - Return stream
+ *
+ * node.listenAddresses():
+ *   - Return libp2p.getMultiaddrs().map(ma => ma.toString())
+ *   - Returns [] when stopped (libp2p returns empty array)
+ *
+ * Stream framing: it-length-prefixed (unsigned varint prefix per multiformats spec)
+ * Use lp.encode(source) / lp.decode(source) with it-pipe for composing pipelines.
+ */
+import { createLibp2p } from "libp2p";
+import { tcp } from "@libp2p/tcp";
+import { webSockets } from "@libp2p/websockets";
+import { noise } from "@chainsafe/libp2p-noise";
+import { yamux } from "@chainsafe/libp2p-yamux";
+import { circuitRelayServer, circuitRelayTransport } from "@libp2p/circuit-relay-v2";
+import { dcutr } from "@libp2p/dcutr";
+import { identify } from "@libp2p/identify";
+import { generateKeyPair, generateKeyPairFromSeed } from "@libp2p/crypto/keys";
+import { multiaddr } from "@multiformats/multiaddr";
+import { peerIdFromString } from "@libp2p/peer-id";
+// ─── CelloNodeImpl ───────────────────────────────────────────────────────────
+class CelloNodeImpl {
+    #libp2p;
+    keyProvider;
+    constructor(libp2p, keyProvider) {
+        this.#libp2p = libp2p;
+        this.keyProvider = keyProvider;
+    }
+    async start() {
+        await this.#libp2p.start();
+    }
+    async stop() {
+        await this.#libp2p.stop();
+    }
+    listenAddresses() {
+        return this.#libp2p.getMultiaddrs().map((ma) => ma.toString());
+    }
+    async dial(multiaddrStr) {
+        if (this.#libp2p.status === "stopped") {
+            throw { reason: "node_stopped", message: "Node is stopped" };
+        }
+        try {
+            const ma = multiaddr(multiaddrStr);
+            const conn = await this.#libp2p.dial(ma);
+            return { peerId: conn.remotePeer.toString() };
+        }
+        catch (err) {
+            // Re-throw structured errors as-is
+            if (isStructuredError(err))
+                throw err;
+            throw mapDialError(err);
+        }
+    }
+    async handle(protocolId, handler, opts) {
+        // libp2p v3 StreamHandler receives (stream, connection); we only need stream
+        const streamHandler = (stream) => handler(stream);
+        await this.#libp2p.handle(protocolId, streamHandler, opts);
+    }
+    async newStream(peerIdStr, protocolId) {
+        if (this.#libp2p.status === "stopped") {
+            throw { reason: "node_stopped", message: "Node is stopped" };
+        }
+        // Look up existing connections to this peer
+        let peerId;
+        try {
+            peerId = peerIdFromString(peerIdStr);
+        }
+        catch {
+            throw {
+                reason: "connection_lost",
+                peerId: peerIdStr,
+                message: `Invalid peer ID: ${peerIdStr}`,
+            };
+        }
+        const connections = this.#libp2p.getConnections(peerId);
+        const openConn = connections.find((c) => c.status === "open");
+        if (!openConn) {
+            throw {
+                reason: "connection_lost",
+                peerId: peerIdStr,
+                message: `No open connection to peer ${peerIdStr}`,
+            };
+        }
+        try {
+            const stream = await openConn.newStream(protocolId);
+            return stream;
+        }
+        catch (err) {
+            if (isStructuredError(err))
+                throw err;
+            throw mapStreamError(err, peerIdStr, protocolId);
+        }
+    }
+    getPeerId() {
+        return this.#libp2p.peerId.toString();
+    }
+    getProtocols() {
+        return this.#libp2p.getProtocols();
+    }
+    getConnections() {
+        return this.#libp2p.getConnections().map((c) => ({
+            peerId: c.remotePeer.toString(),
+            encryption: c.encryption,
+        }));
+    }
+    onPeerConnect(handler) {
+        this.#libp2p.addEventListener("peer:connect", (evt) => {
+            handler(evt.detail.toString());
+        });
+    }
+    onPeerDisconnect(handler) {
+        this.#libp2p.addEventListener("peer:disconnect", (evt) => {
+            handler(evt.detail.toString());
+        });
+    }
+}
+// ─── Error helpers ───────────────────────────────────────────────────────────
+function isStructuredError(err) {
+    return (typeof err === "object" &&
+        err !== null &&
+        "reason" in err &&
+        typeof err.reason === "string");
+}
+function mapDialError(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    // Node stopped
+    if (msg.includes("stopped") || msg.includes("not started")) {
+        return { reason: "node_stopped", message: msg };
+    }
+    return { reason: "connection_lost", peerId: "unknown", message: msg };
+}
+function mapStreamError(err, peerId, protocolId) {
+    // Check error name first — most reliable signal from libp2p
+    if (err instanceof Error && err.name === "UnsupportedProtocolError") {
+        return { reason: "protocol_not_supported", protocolId, message: err.message };
+    }
+    const msg = err instanceof Error ? err.message : String(err);
+    // Protocol negotiation failure — match specific phrases, not generic "stream"
+    if (msg.includes("unsupported protocol") ||
+        msg.includes("not supported") ||
+        msg.includes("protocol negotiation failed") ||
+        msg.includes("multistream")) {
+        return { reason: "protocol_not_supported", protocolId, message: msg };
+    }
+    // Connection-level failure — explicit connection/reset/abort signals
+    if (msg.includes("reset") ||
+        msg.includes("connection closed") ||
+        msg.includes("connection reset") ||
+        msg.includes("aborted") ||
+        msg.includes("connection lost")) {
+        return { reason: "connection_lost", peerId, message: msg };
+    }
+    // Default to connection_lost
+    return { reason: "connection_lost", peerId, message: msg };
+}
+// ─── Factory ─────────────────────────────────────────────────────────────────
+/**
+ * Create a new CelloNode in stopped state.
+ *
+ * CRITICAL (ADR-0001 / SI-002):
+ * - A fresh libp2p-managed Ed25519 keypair is generated here.
+ * - This keypair drives the transport Peer ID and Noise handshake.
+ * - keyProvider is stored but NEVER called during createNode() or start().
+ * - The node's Peer ID will differ from any PeerId derived from keyProvider.
+ *
+ * Transport stack:
+ *   - Transports: TCP + WebSockets
+ *   - Security: Noise ONLY (XX pattern, RFC: https://noiseprotocol.org/noise.html)
+ *   - Muxer: Yamux
+ *   - Services: identify, circuitRelayServer (advertises HOP), DCuTR
+ */
+export async function createNode(opts) {
+    // ADR-0001: generate a fresh keypair for libp2p transport identity.
+    // keyProvider is intentionally NOT touched here — see SI-002.
+    const transportKey = opts.transportPrivateKey
+        ? await generateKeyPairFromSeed("Ed25519", opts.transportPrivateKey)
+        : await generateKeyPair("Ed25519");
+    const libp2p = await createLibp2p({
+        start: false,
+        privateKey: transportKey,
+        addresses: {
+            listen: opts.listenAddresses,
+        },
+        transports: [
+            tcp(),
+            webSockets(),
+            // Circuit relay transport enables dialing via relay addresses
+            circuitRelayTransport(),
+        ],
+        connectionEncrypters: [
+            // Noise ONLY — no plaintext. SI-001.
+            // Noise XX pattern per https://noiseprotocol.org/noise.html
+            noise(),
+        ],
+        streamMuxers: [yamux()],
+        services: {
+            identify: identify(),
+            // circuitRelayServer advertises CIRCUIT_RELAY_V2_HOP_PROTOCOL_ID
+            relay: circuitRelayServer(),
+            dcutr: dcutr(),
+        },
+    });
+    // Return node in STOPPED state — caller must call start()
+    return new CelloNodeImpl(libp2p, opts.keyProvider);
+}
+//# sourceMappingURL=node.js.map

package/dist/node.js.map

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

package/dist/protocols.d.ts

@@ -0,0 +1,26 @@
+/**
+ * CELLO Transport — protocols.ts
+ *
+ * Protocol ID constants for the CELLO transport layer.
+ */
+/**
+ * CELLO M0 stream protocol identifier.
+ * Used for all CELLO envelope exchanges in the walking skeleton (M0) milestone.
+ * Stream framing: it-length-prefixed varint-prefixed frames
+ * (unsigned varint per https://github.com/multiformats/unsigned-varint).
+ */
+export declare const CELLO_PROTOCOL_ID = "/cello/m0/1.0.0";
+/**
+ * Circuit Relay v2 HOP protocol identifier.
+ * Read from @libp2p/circuit-relay-v2 package (RELAY_V2_HOP_CODEC constant).
+ * Value: '/libp2p/circuit/relay/0.2.0/hop'
+ * Source: @libp2p/circuit-relay-v2 v4.2.3, src/constants.ts
+ */
+export declare const CIRCUIT_RELAY_V2_HOP_PROTOCOL_ID = "/libp2p/circuit/relay/0.2.0/hop";
+/**
+ * CELLO content protocol identifier.
+ * Used for direct peer-to-peer content exchange after session establishment (SESSION-002).
+ * Stream framing: it-length-prefixed varint-prefixed frames.
+ */
+export declare const CELLO_CONTENT_PROTOCOL_ID = "/cello/content/1.0.0";
+//# sourceMappingURL=protocols.d.ts.map

package/dist/protocols.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocols.d.ts","sourceRoot":"","sources":["../src/protocols.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,oBAAoB,CAAC;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC,oCAAoC,CAAC;AAElF;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,yBAAyB,CAAC"}

package/dist/protocols.js

@@ -0,0 +1,26 @@
+/**
+ * CELLO Transport — protocols.ts
+ *
+ * Protocol ID constants for the CELLO transport layer.
+ */
+/**
+ * CELLO M0 stream protocol identifier.
+ * Used for all CELLO envelope exchanges in the walking skeleton (M0) milestone.
+ * Stream framing: it-length-prefixed varint-prefixed frames
+ * (unsigned varint per https://github.com/multiformats/unsigned-varint).
+ */
+export const CELLO_PROTOCOL_ID = "/cello/m0/1.0.0";
+/**
+ * Circuit Relay v2 HOP protocol identifier.
+ * Read from @libp2p/circuit-relay-v2 package (RELAY_V2_HOP_CODEC constant).
+ * Value: '/libp2p/circuit/relay/0.2.0/hop'
+ * Source: @libp2p/circuit-relay-v2 v4.2.3, src/constants.ts
+ */
+export const CIRCUIT_RELAY_V2_HOP_PROTOCOL_ID = "/libp2p/circuit/relay/0.2.0/hop";
+/**
+ * CELLO content protocol identifier.
+ * Used for direct peer-to-peer content exchange after session establishment (SESSION-002).
+ * Stream framing: it-length-prefixed varint-prefixed frames.
+ */
+export const CELLO_CONTENT_PROTOCOL_ID = "/cello/content/1.0.0";
+//# sourceMappingURL=protocols.js.map

package/dist/protocols.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocols.js","sourceRoot":"","sources":["../src/protocols.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,iBAAiB,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAG,iCAAiC,CAAC;AAElF;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,sBAAsB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,149 @@
+/**
+ * CELLO Transport — types.ts
+ *
+ * Defines the CelloNode interface, CreateNodeOptions, StreamHandler, and structured
+ * error types for the @cello-protocol/transport package.
+ *
+ * ARCHITECTURE NOTE (ADR-0001):
+ * The KeyProvider is stored on CelloNode for use by higher layers (MSG-001 signing)
+ * but is NEVER passed into libp2p's Noise handshake or peer identity. libp2p generates
+ * its own internal Ed25519 keypair. This means:
+ *   - node.getPeerId() returns the TRANSPORT peer ID (libp2p-managed)
+ *   - KeyProvider.getPublicKey() returns K_local (CELLO signing identity)
+ *   - These are always different keys serving different trust claims.
+ */
+import type { KeyProvider } from "@cello-protocol/crypto";
+import type { Stream } from "@libp2p/interface";
+export interface CreateNodeOptions {
+    /**
+     * The CELLO KeyProvider holding K_local (Ed25519 signing key).
+     * Stored on the node for higher-layer use (MSG-001). NOT wired into libp2p
+     * transport identity — see ADR-0001.
+     */
+    keyProvider: KeyProvider;
+    /**
+     * libp2p listen multiaddrs. Use '/ip4/127.0.0.1/tcp/0' for ephemeral port.
+     */
+    listenAddresses: string[];
+    /**
+     * Optional pre-generated transport private key (raw Ed25519 seed, 32 bytes).
+     * When provided, the node uses this key for its libp2p Peer ID instead of
+     * generating a fresh one. Use this for services (directory, relay) that need
+     * a stable Peer ID across restarts.
+     */
+    transportPrivateKey?: Uint8Array;
+}
+/**
+ * Handler called when a remote peer opens a stream on a registered protocol.
+ * The Stream object has `source` (AsyncIterable) and `sink` (async iterable consumer).
+ * Use `it-length-prefixed` and `it-pipe` for framed I/O per the it-length-prefixed
+ * varint-prefix convention (unsigned varint per https://github.com/multiformats/unsigned-varint).
+ */
+export type CelloStreamHandler = (stream: Stream) => void | Promise<void>;
+export interface CelloNode {
+    /**
+     * Start the node: begin listening on configured addresses.
+     * After start(), the node is dialable by remote peers.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the node: close all streams and connections, release all resources.
+     * After stop(), listenAddresses() returns [] and all operations fail with node_stopped.
+     */
+    stop(): Promise<void>;
+    /**
+     * Returns current listen multiaddrs as strings.
+     * Returns [] before start() or after stop().
+     */
+    listenAddresses(): string[];
+    /**
+     * Connect to a remote peer by multiaddr string.
+     * Returns the remote peer's transport PeerId as a string.
+     * Fails with node_stopped if called after stop().
+     */
+    dial(multiaddr: string): Promise<{
+        peerId: string;
+    }>;
+    /**
+     * Register a stream handler for a protocol ID.
+     * The handler is called when a remote peer opens a stream on this protocol.
+     */
+    handle(protocolId: string, handler: CelloStreamHandler, opts?: {
+        maxInboundStreams?: number;
+    }): Promise<void>;
+    /**
+     * Open a new multiplexed stream to a connected remote peer.
+     * Returns the libp2p Stream object for use with it-length-prefixed framing.
+     *
+     * Structured errors (thrown as plain objects):
+     *   { reason: 'protocol_not_supported', protocolId, message }
+     *   { reason: 'connection_lost', peerId, message }
+     *   { reason: 'node_stopped', message }
+     */
+    newStream(peerId: string, protocolId: string): Promise<Stream>;
+    /**
+     * Returns the node's own transport PeerId as a string.
+     * This is the libp2p-managed keypair identity, NOT derived from KeyProvider.
+     * See ADR-0001.
+     */
+    getPeerId(): string;
+    /**
+     * Returns the libp2p protocol strings advertised by this node.
+     * Used by tests to verify Noise is present and plaintext is absent (SI-001, SI-003).
+     */
+    getProtocols(): string[];
+    /**
+     * Returns basic info about all current connections.
+     * Used by SI-001 test to verify connection-level encryption is Noise.
+     * encryption is undefined when libp2p has not yet completed the security handshake.
+     */
+    getConnections(): Array<{
+        peerId: string;
+        encryption: string | undefined;
+    }>;
+    /**
+     * Subscribe to peer connect/disconnect events for observability logging.
+     * Callback fires whenever a new libp2p connection is established or closed.
+     */
+    onPeerConnect(handler: (peerId: string) => void): void;
+    onPeerDisconnect(handler: (peerId: string) => void): void;
+    /**
+     * Access the stored KeyProvider for higher-layer use (MSG-001 signing).
+     * The transport layer itself never calls any methods on this object.
+     */
+    readonly keyProvider: KeyProvider;
+}
+/**
+ * Thrown (as a thrown plain object, not an Error instance) when a remote peer
+ * does not support the requested protocol.
+ */
+export interface ProtocolNotSupportedError {
+    reason: "protocol_not_supported";
+    protocolId: string;
+    message: string;
+}
+/**
+ * Thrown when the connection to the remote peer has been lost.
+ */
+export interface ConnectionLostError {
+    reason: "connection_lost";
+    peerId: string;
+    message: string;
+}
+/**
+ * Thrown when the node has been stopped and operations are attempted.
+ */
+export interface NodeStoppedError {
+    reason: "node_stopped";
+    message: string;
+}
+/**
+ * Thrown when the node fails to bind to a listen address.
+ */
+export interface ListenFailedError {
+    reason: "listen_failed";
+    multiaddr: string;
+    message: string;
+}
+export type CelloTransportError = ProtocolNotSupportedError | ConnectionLostError | NodeStoppedError | ListenFailedError;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAIhD,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,WAAW,EAAE,WAAW,CAAC;IACzB;;OAEG;IACH,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,UAAU,CAAC;CAClC;AAID;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAI1E,MAAM,WAAW,SAAS;IACxB;;;OAGG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB;;;OAGG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtB;;;OAGG;IACH,eAAe,IAAI,MAAM,EAAE,CAAC;IAE5B;;;;OAIG;IACH,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAErD;;;OAGG;IACH,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,EAAE,IAAI,CAAC,EAAE;QAAE,iBAAiB,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9G;;;;;;;;OAQG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE/D;;;;OAIG;IACH,SAAS,IAAI,MAAM,CAAC;IAEpB;;;OAGG;IACH,YAAY,IAAI,MAAM,EAAE,CAAC;IAEzB;;;;OAIG;IACH,cAAc,IAAI,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,CAAC,CAAC;IAE5E;;;OAGG;IACH,aAAa,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAC;IACvD,gBAAgB,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAC;IAE1D;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;CACnC;AAID;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,wBAAwB,CAAC;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,cAAc,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,eAAe,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,mBAAmB,GAC3B,yBAAyB,GACzB,mBAAmB,GACnB,gBAAgB,GAChB,iBAAiB,CAAC"}

package/dist/types.js

@@ -0,0 +1,16 @@
+/**
+ * CELLO Transport — types.ts
+ *
+ * Defines the CelloNode interface, CreateNodeOptions, StreamHandler, and structured
+ * error types for the @cello-protocol/transport package.
+ *
+ * ARCHITECTURE NOTE (ADR-0001):
+ * The KeyProvider is stored on CelloNode for use by higher layers (MSG-001 signing)
+ * but is NEVER passed into libp2p's Noise handshake or peer identity. libp2p generates
+ * its own internal Ed25519 keypair. This means:
+ *   - node.getPeerId() returns the TRANSPORT peer ID (libp2p-managed)
+ *   - KeyProvider.getPublicKey() returns K_local (CELLO signing identity)
+ *   - These are always different keys serving different trust claims.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@cello-protocol/transport",
+  "version": "0.0.2",
+  "private": false,
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist/",
+    "package.json"
+  ],
+  "dependencies": {
+    "@libp2p/crypto": "^5.0.0",
+    "@libp2p/interface": "^3.0.0",
+    "@libp2p/peer-id": "^6.0.0",
+    "@multiformats/multiaddr": "^13.0.0",
+    "@chainsafe/libp2p-noise": "^17.0.0",
+    "@chainsafe/libp2p-yamux": "^8.0.1",
+    "@libp2p/circuit-relay-v2": "^4.2.3",
+    "@libp2p/dcutr": "^3.0.18",
+    "@libp2p/identify": "^4.1.3",
+    "@libp2p/tcp": "^11.0.18",
+    "@libp2p/websockets": "^10.1.11",
+    "it-length-prefixed": "^10.0.1",
+    "it-pipe": "^3.0.1",
+    "libp2p": "^3.2.3",
+    "uint8arrays": "^5.1.1",
+    "@cello-protocol/crypto": "0.0.2"
+  },
+  "devDependencies": {
+    "@claude-flow/testing": "3.0.0-alpha.6",
+    "@types/node": "^25.6.2"
+  },
+  "scripts": {
+    "typecheck": "tsc --build",
+    "test": "vitest run"
+  }
+}