@cello-protocol/transport 0.0.4 → 0.0.5

package/dist/autonat-service.d.ts

@@ -0,0 +1,85 @@
+/**
+ * CELLO Transport — autonat-service.ts (CELLO-M7-TRANSPORT-001)
+ *
+ * NodeAutoNatService — the REAL IAutoNatService adapter (CELLO_ENV dev/staging/
+ * production). It wraps a started CelloNode and surfaces the node's
+ * libp2p-AutoNAT-driven dialability observable, gated by the directory-node prober
+ * set, and emits the story's AutoNAT observability events through an injected
+ * Logger.
+ *
+ * ─── Why this exists (review finding C2 + C1) ────────────────────────────────
+ * The transport node owns a dialability observable but emits NO log events. The
+ * story REQUIRES:
+ *   - transport.autonat.result      (INFO, every probe cycle) — { dialable,
+ *                                     publicAddr, nodeType }
+ *   - transport.autonat.unavailable (WARN, when no directory probers are
+ *                                     reachable) — { nodeType,
+ *                                     directorySignalingStatus }
+ * NodeAutoNatService is where those events are produced. It is the production
+ * counterpart of LocalAutoNatStub (which returns canned values with no node).
+ *
+ * ─── SI-002: probers are exclusively manifest directory nodes ────────────────
+ * AutoNAT can only run when at least one manifest-verified directory node is
+ * connected to act as a dial-back prober. When the prober set is empty (directory
+ * in 'reconnecting' state — SIGNAL-001), AutoNAT cannot run: getDialability()
+ * returns the conservative DEFAULT_DIALABILITY ({ dialable:false, publicAddr:null })
+ * regardless of what the node's raw observable says, and the dual unavailable
+ * WARN event fires. A rogue non-manifest responder is never in the prober set, so
+ * it can never push the node to dialable:true.
+ */
+import type { CelloNode } from "./types.js";
+import type { Dialability, IAutoNatService, Unsubscribe } from "./autonat.js";
+/** Minimal logger surface used by NodeAutoNatService (injected, never imported). */
+export interface AutoNatLogger {
+    info(event: string, context: Record<string, unknown>): void;
+    warn(event: string, context: Record<string, unknown>): void;
+}
+export type AutoNatNodeType = "session" | "standing_receiver";
+export interface NodeAutoNatServiceOptions {
+    /** The started CelloNode whose AutoNAT dialability this service surfaces. */
+    node: CelloNode;
+    /** Injected logger for the AutoNAT observability events. */
+    logger: AutoNatLogger;
+    /** 'standing_receiver' or 'session' — recorded on every event. */
+    nodeType: AutoNatNodeType;
+    /**
+     * Directory-node multiaddrs serving as AutoNAT probers (SI-002). Empty when the
+     * directory connection is in 'reconnecting' state — AutoNAT cannot run then.
+     */
+    probers?: string[];
+    /**
+     * Source of the directory signaling status string for the unavailable event.
+     * Defaults to 'reconnecting' (the only state in which probers are empty).
+     */
+    directorySignalingStatus?: () => string;
+}
+/**
+ * Real IAutoNatService over a live CelloNode. Subscribes to the node's dialability
+ * observable; every change emits transport.autonat.result (and, when no probers
+ * are reachable, transport.autonat.unavailable).
+ */
+export declare class NodeAutoNatService implements IAutoNatService {
+    #private;
+    constructor(opts: NodeAutoNatServiceOptions);
+    /**
+     * Current dialability. AutoNAT requires at least one directory-node prober; when
+     * the prober set is empty (reconnecting), return the conservative default — the
+     * node's raw observable is not trusted because no manifest prober confirmed it
+     * (SI-002 / AC-004 / DB-001).
+     */
+    getDialability(): Dialability;
+    /** The manifest directory-node prober set (SI-002). */
+    getProbers(): string[];
+    onChange(listener: (d: Dialability) => void): Unsubscribe;
+    /** Update the prober set (e.g. on directory connect/disconnect). */
+    setProbers(probers: string[]): void;
+    /**
+     * Emit the current probe result. Call once after the node has started so the
+     * standing-receiver/session node's initial dialability (and any unavailable
+     * condition) is logged even before libp2p fires its first self:peer:update.
+     */
+    emitInitialResult(): void;
+    /** Release the node subscription. */
+    stop(): void;
+}
+//# sourceMappingURL=autonat-service.d.ts.map

package/dist/autonat-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"autonat-service.d.ts","sourceRoot":"","sources":["../src/autonat-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAG9E,oFAAoF;AACpF,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5D,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC7D;AAED,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,mBAAmB,CAAC;AAE9D,MAAM,WAAW,yBAAyB;IACxC,6EAA6E;IAC7E,IAAI,EAAE,SAAS,CAAC;IAChB,4DAA4D;IAC5D,MAAM,EAAE,aAAa,CAAC;IACtB,kEAAkE;IAClE,QAAQ,EAAE,eAAe,CAAC;IAC1B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB;;;OAGG;IACH,wBAAwB,CAAC,EAAE,MAAM,MAAM,CAAC;CACzC;AAED;;;;GAIG;AACH,qBAAa,kBAAmB,YAAW,eAAe;;gBAS5C,IAAI,EAAE,yBAAyB;IAW3C;;;;;OAKG;IACH,cAAc,IAAI,WAAW;IAK7B,uDAAuD;IACvD,UAAU,IAAI,MAAM,EAAE;IAItB,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,WAAW,KAAK,IAAI,GAAG,WAAW;IAOzD,oEAAoE;IACpE,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI;IAInC;;;;OAIG;IACH,iBAAiB,IAAI,IAAI;IAIzB,qCAAqC;IACrC,IAAI,IAAI,IAAI;CA+Bb"}

package/dist/autonat-service.js

@@ -0,0 +1,117 @@
+/**
+ * CELLO Transport — autonat-service.ts (CELLO-M7-TRANSPORT-001)
+ *
+ * NodeAutoNatService — the REAL IAutoNatService adapter (CELLO_ENV dev/staging/
+ * production). It wraps a started CelloNode and surfaces the node's
+ * libp2p-AutoNAT-driven dialability observable, gated by the directory-node prober
+ * set, and emits the story's AutoNAT observability events through an injected
+ * Logger.
+ *
+ * ─── Why this exists (review finding C2 + C1) ────────────────────────────────
+ * The transport node owns a dialability observable but emits NO log events. The
+ * story REQUIRES:
+ *   - transport.autonat.result      (INFO, every probe cycle) — { dialable,
+ *                                     publicAddr, nodeType }
+ *   - transport.autonat.unavailable (WARN, when no directory probers are
+ *                                     reachable) — { nodeType,
+ *                                     directorySignalingStatus }
+ * NodeAutoNatService is where those events are produced. It is the production
+ * counterpart of LocalAutoNatStub (which returns canned values with no node).
+ *
+ * ─── SI-002: probers are exclusively manifest directory nodes ────────────────
+ * AutoNAT can only run when at least one manifest-verified directory node is
+ * connected to act as a dial-back prober. When the prober set is empty (directory
+ * in 'reconnecting' state — SIGNAL-001), AutoNAT cannot run: getDialability()
+ * returns the conservative DEFAULT_DIALABILITY ({ dialable:false, publicAddr:null })
+ * regardless of what the node's raw observable says, and the dual unavailable
+ * WARN event fires. A rogue non-manifest responder is never in the prober set, so
+ * it can never push the node to dialable:true.
+ */
+import { DEFAULT_DIALABILITY } from "./autonat.js";
+/**
+ * Real IAutoNatService over a live CelloNode. Subscribes to the node's dialability
+ * observable; every change emits transport.autonat.result (and, when no probers
+ * are reachable, transport.autonat.unavailable).
+ */
+export class NodeAutoNatService {
+    #node;
+    #logger;
+    #nodeType;
+    #probers;
+    #getStatus;
+    #listeners = new Set();
+    #unsubNode;
+    constructor(opts) {
+        this.#node = opts.node;
+        this.#logger = opts.logger;
+        this.#nodeType = opts.nodeType;
+        this.#probers = opts.probers ? [...opts.probers] : [];
+        this.#getStatus = opts.directorySignalingStatus ?? (() => "reconnecting");
+        // Each AutoNAT probe cycle that changes the node's dialability re-emits the
+        // result event and notifies daemon-side observers.
+        this.#unsubNode = this.#node.onDialabilityChange((d) => this.#emitResult(d));
+    }
+    /**
+     * Current dialability. AutoNAT requires at least one directory-node prober; when
+     * the prober set is empty (reconnecting), return the conservative default — the
+     * node's raw observable is not trusted because no manifest prober confirmed it
+     * (SI-002 / AC-004 / DB-001).
+     */
+    getDialability() {
+        if (this.#probers.length === 0)
+            return { ...DEFAULT_DIALABILITY };
+        return this.#node.getDialability();
+    }
+    /** The manifest directory-node prober set (SI-002). */
+    getProbers() {
+        return [...this.#probers];
+    }
+    onChange(listener) {
+        this.#listeners.add(listener);
+        return () => {
+            this.#listeners.delete(listener);
+        };
+    }
+    /** Update the prober set (e.g. on directory connect/disconnect). */
+    setProbers(probers) {
+        this.#probers = [...probers];
+    }
+    /**
+     * Emit the current probe result. Call once after the node has started so the
+     * standing-receiver/session node's initial dialability (and any unavailable
+     * condition) is logged even before libp2p fires its first self:peer:update.
+     */
+    emitInitialResult() {
+        this.#emitResult(this.#node.getDialability());
+    }
+    /** Release the node subscription. */
+    stop() {
+        this.#unsubNode();
+    }
+    #emitResult(raw) {
+        const noProbers = this.#probers.length === 0;
+        // When AutoNAT cannot run, force the conservative default — the node's raw
+        // observable was never confirmed by a manifest prober (SI-002).
+        const d = noProbers ? { ...DEFAULT_DIALABILITY } : raw;
+        this.#logger.info("transport.autonat.result", {
+            dialable: d.dialable,
+            publicAddr: d.publicAddr,
+            nodeType: this.#nodeType,
+            ...(noProbers
+                ? { note: "autonat_unavailable — directory in reconnecting state" }
+                : {}),
+        });
+        // Dual-event (story Observability §notes): the unavailable WARN fires
+        // alongside the INFO result whenever AutoNAT could not run. The INFO event is
+        // the standard per-probe report; the WARN drives operational alarms.
+        if (noProbers) {
+            this.#logger.warn("transport.autonat.unavailable", {
+                nodeType: this.#nodeType,
+                directorySignalingStatus: this.#getStatus(),
+            });
+        }
+        for (const l of this.#listeners)
+            l({ ...d });
+    }
+}
+//# sourceMappingURL=autonat-service.js.map

package/dist/autonat-service.js.map

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

package/dist/autonat.d.ts

@@ -0,0 +1,90 @@
+/**
+ * CELLO Transport — autonat.ts (CELLO-M7-TRANSPORT-001)
+ *
+ * AutoNAT dialability detection for session and standing-receiver nodes.
+ *
+ * ─── Specification (Phase S) ──────────────────────────────────────────────────
+ * AutoNAT (libp2p) asks already-connected peers to dial back the node's
+ * advertised address. If a dial-back succeeds, the node is publicly dialable; if
+ * it fails, the node is behind NAT and must use a relay circuit address. CELLO
+ * uses directory nodes (manifest-verified, three independent regions) as the
+ * dial-back probers — they are already connected and trusted, so no dedicated
+ * AutoNAT bootstrap infrastructure is required.
+ *
+ * Adapter pattern (mandatory per CLAUDE.md):
+ *   IAutoNatService is the daemon-facing adapter for querying dialability. The
+ *   real implementation (NodeAutoNatService) wraps a CelloNode and surfaces the
+ *   node's libp2p-driven dialability observable, plus the directory prober set
+ *   obtained from the daemon context. LocalAutoNatStub returns configurable
+ *   values without any network access (CELLO_ENV='local'|'test').
+ *
+ * SI-002: probers are exclusively directory nodes whose identity is verified via
+ * the consortium manifest. libp2p AutoNAT v1 probes connected peers; CELLO only
+ * connects to manifest-verified directory nodes (enforced by the connection
+ * policy / connection gater), so the effective prober set is the directory node
+ * set. getProbers() surfaces that set so callers can assert it (AC-001(c)) and so
+ * a rogue non-manifest responder cannot be counted (SI-002).
+ *
+ * ─── Pseudocode (Phase P) ─────────────────────────────────────────────────────
+ * Dialability is { dialable, publicAddr }:
+ *   - dialable: true iff AutoNAT confirmed at least one externally-reachable
+ *     (public, non-circuit) multiaddr.
+ *   - publicAddr: that confirmed multiaddr, or null when behind NAT / undetermined.
+ *
+ * LocalAutoNatStub:
+ *   constructor(initial = { dialable: false, publicAddr: null }, probers = [])
+ *   getDialability(): return current
+ *   getProbers(): return probers
+ *   onChange(cb): register; return unsubscribe
+ *   setDialability(next): set current; notify all listeners  (test driver)
+ *   setProbers(p): set probers  (test driver — e.g. simulate reconnecting => [])
+ */
+/**
+ * The result of an AutoNAT probe cycle. Node-level (not session-scoped).
+ *   dialable  — true if at least one directory node confirmed dial-back success.
+ *   publicAddr — the externally-reachable multiaddr if dialable; null otherwise.
+ */
+export interface Dialability {
+    dialable: boolean;
+    publicAddr: string | null;
+}
+/** Conservative default used before any probe completes / when AutoNAT cannot run. */
+export declare const DEFAULT_DIALABILITY: Dialability;
+/** Unsubscribe handle returned by observe registrations. */
+export type Unsubscribe = () => void;
+/**
+ * Daemon-facing adapter for dialability. The session establishment logic reads
+ * getDialability() to decide what address to advertise in the SessionAssignment
+ * negotiation (direct multiaddr when dialable, relay circuit address otherwise).
+ */
+export interface IAutoNatService {
+    /** Current dialability. Returns DEFAULT_DIALABILITY before the first probe. */
+    getDialability(): Dialability;
+    /**
+     * The directory-node multiaddrs serving as AutoNAT probers (SI-002). Empty when
+     * no directory nodes are connected (reconnecting state — AutoNAT cannot run).
+     */
+    getProbers(): string[];
+    /** Observe dialability changes. Returns an unsubscribe handle. */
+    onChange(listener: (d: Dialability) => void): Unsubscribe;
+}
+/**
+ * In-process AutoNAT stub. Returns configurable dialability with no network
+ * access. Selected when CELLO_ENV is 'local' or 'test'. Defaults to NOT dialable
+ * (the conservative relay fallback) per the story's edge-case requirements.
+ */
+export declare class LocalAutoNatStub implements IAutoNatService {
+    #private;
+    constructor(opts?: {
+        dialability?: Dialability;
+        probers?: string[];
+    });
+    getDialability(): Dialability;
+    getProbers(): string[];
+    onChange(listener: (d: Dialability) => void): Unsubscribe;
+    /** Test driver: update dialability and notify observers. */
+    setDialability(next: Dialability): void;
+    /** Test driver: set the prober set (e.g. [] to simulate the reconnecting state). */
+    setProbers(probers: string[]): void;
+}
+//# sourceMappingURL=autonat.d.ts.map

package/dist/autonat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"autonat.d.ts","sourceRoot":"","sources":["../src/autonat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAIH;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,sFAAsF;AACtF,eAAO,MAAM,mBAAmB,EAAE,WAGhC,CAAC;AAEH,4DAA4D;AAC5D,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC;AAIrC;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,cAAc,IAAI,WAAW,CAAC;IAC9B;;;OAGG;IACH,UAAU,IAAI,MAAM,EAAE,CAAC;IACvB,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,WAAW,KAAK,IAAI,GAAG,WAAW,CAAC;CAC3D;AAID;;;;GAIG;AACH,qBAAa,gBAAiB,YAAW,eAAe;;gBAK1C,IAAI,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,WAAW,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE;IAKpE,cAAc,IAAI,WAAW;IAI7B,UAAU,IAAI,MAAM,EAAE;IAItB,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,WAAW,KAAK,IAAI,GAAG,WAAW;IAOzD,4DAA4D;IAC5D,cAAc,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI;IAKvC,oFAAoF;IACpF,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI;CAGpC"}

package/dist/autonat.js

@@ -0,0 +1,84 @@
+/**
+ * CELLO Transport — autonat.ts (CELLO-M7-TRANSPORT-001)
+ *
+ * AutoNAT dialability detection for session and standing-receiver nodes.
+ *
+ * ─── Specification (Phase S) ──────────────────────────────────────────────────
+ * AutoNAT (libp2p) asks already-connected peers to dial back the node's
+ * advertised address. If a dial-back succeeds, the node is publicly dialable; if
+ * it fails, the node is behind NAT and must use a relay circuit address. CELLO
+ * uses directory nodes (manifest-verified, three independent regions) as the
+ * dial-back probers — they are already connected and trusted, so no dedicated
+ * AutoNAT bootstrap infrastructure is required.
+ *
+ * Adapter pattern (mandatory per CLAUDE.md):
+ *   IAutoNatService is the daemon-facing adapter for querying dialability. The
+ *   real implementation (NodeAutoNatService) wraps a CelloNode and surfaces the
+ *   node's libp2p-driven dialability observable, plus the directory prober set
+ *   obtained from the daemon context. LocalAutoNatStub returns configurable
+ *   values without any network access (CELLO_ENV='local'|'test').
+ *
+ * SI-002: probers are exclusively directory nodes whose identity is verified via
+ * the consortium manifest. libp2p AutoNAT v1 probes connected peers; CELLO only
+ * connects to manifest-verified directory nodes (enforced by the connection
+ * policy / connection gater), so the effective prober set is the directory node
+ * set. getProbers() surfaces that set so callers can assert it (AC-001(c)) and so
+ * a rogue non-manifest responder cannot be counted (SI-002).
+ *
+ * ─── Pseudocode (Phase P) ─────────────────────────────────────────────────────
+ * Dialability is { dialable, publicAddr }:
+ *   - dialable: true iff AutoNAT confirmed at least one externally-reachable
+ *     (public, non-circuit) multiaddr.
+ *   - publicAddr: that confirmed multiaddr, or null when behind NAT / undetermined.
+ *
+ * LocalAutoNatStub:
+ *   constructor(initial = { dialable: false, publicAddr: null }, probers = [])
+ *   getDialability(): return current
+ *   getProbers(): return probers
+ *   onChange(cb): register; return unsubscribe
+ *   setDialability(next): set current; notify all listeners  (test driver)
+ *   setProbers(p): set probers  (test driver — e.g. simulate reconnecting => [])
+ */
+/** Conservative default used before any probe completes / when AutoNAT cannot run. */
+export const DEFAULT_DIALABILITY = Object.freeze({
+    dialable: false,
+    publicAddr: null,
+});
+// ─── LocalAutoNatStub ─────────────────────────────────────────────────────────
+/**
+ * In-process AutoNAT stub. Returns configurable dialability with no network
+ * access. Selected when CELLO_ENV is 'local' or 'test'. Defaults to NOT dialable
+ * (the conservative relay fallback) per the story's edge-case requirements.
+ */
+export class LocalAutoNatStub {
+    #dialability;
+    #probers;
+    #listeners = new Set();
+    constructor(opts) {
+        this.#dialability = opts?.dialability ?? { ...DEFAULT_DIALABILITY };
+        this.#probers = opts?.probers ? [...opts.probers] : [];
+    }
+    getDialability() {
+        return { ...this.#dialability };
+    }
+    getProbers() {
+        return [...this.#probers];
+    }
+    onChange(listener) {
+        this.#listeners.add(listener);
+        return () => {
+            this.#listeners.delete(listener);
+        };
+    }
+    /** Test driver: update dialability and notify observers. */
+    setDialability(next) {
+        this.#dialability = { ...next };
+        for (const l of this.#listeners)
+            l(this.getDialability());
+    }
+    /** Test driver: set the prober set (e.g. [] to simulate the reconnecting state). */
+    setProbers(probers) {
+        this.#probers = [...probers];
+    }
+}
+//# sourceMappingURL=autonat.js.map

package/dist/autonat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"autonat.js","sourceRoot":"","sources":["../src/autonat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAcH,sFAAsF;AACtF,MAAM,CAAC,MAAM,mBAAmB,GAAgB,MAAM,CAAC,MAAM,CAAC;IAC5D,QAAQ,EAAE,KAAK;IACf,UAAU,EAAE,IAAI;CACjB,CAAC,CAAC;AAwBH,iFAAiF;AAEjF;;;;GAIG;AACH,MAAM,OAAO,gBAAgB;IAC3B,YAAY,CAAc;IAC1B,QAAQ,CAAW;IACV,UAAU,GAAG,IAAI,GAAG,EAA4B,CAAC;IAE1D,YAAY,IAAwD;QAClE,IAAI,CAAC,YAAY,GAAG,IAAI,EAAE,WAAW,IAAI,EAAE,GAAG,mBAAmB,EAAE,CAAC;QACpE,IAAI,CAAC,QAAQ,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACzD,CAAC;IAED,cAAc;QACZ,OAAO,EAAE,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;IAClC,CAAC;IAED,UAAU;QACR,OAAO,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC5B,CAAC;IAED,QAAQ,CAAC,QAAkC;QACzC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC9B,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QACnC,CAAC,CAAC;IACJ,CAAC;IAED,4DAA4D;IAC5D,cAAc,CAAC,IAAiB;QAC9B,IAAI,CAAC,YAAY,GAAG,EAAE,GAAG,IAAI,EAAE,CAAC;QAChC,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,UAAU;YAAE,CAAC,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC,CAAC;IAC5D,CAAC;IAED,oFAAoF;IACpF,UAAU,CAAC,OAAiB;QAC1B,IAAI,CAAC,QAAQ,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC;IAC/B,CAAC;CACF"}

package/dist/content-cap.d.ts

@@ -0,0 +1,43 @@
+/**
+ * CELLO-M7-MSG-001 — transport content-size cap.
+ *
+ * Reads the first length-prefixed frame from a content stream and enforces the
+ * application content cap (MAX_CONTENT_BYTES = 1 MB) EXPLICITLY, before the bare
+ * it-length-prefixed transport default (4 MB) can fire. Oversize content yields a
+ * distinct `content_too_large` outcome — never a silent decode failure that the
+ * caller mistakes for a desync (AC-014, SI-003).
+ *
+ * Pseudocode (SPARC Phase P):
+ *   readCappedContentFrame(source, cap):
+ *     decode with maxDataLength = transport default (4 MB) so 1–4 MB frames are
+ *       observable and we can report their exact size
+ *     for first frame:
+ *       payload = bytes
+ *       if payload.length > cap → { ok:false, content_too_large, size, cap }
+ *       else → { ok:true, payload }
+ *     no frame → { ok:false, empty }
+ *     decode throw (e.g. > 4 MB transport max) → { ok:false, content_too_large }
+ */
+export type CappedFrameResult = {
+    ok: true;
+    payload: Uint8Array;
+} | {
+    ok: false;
+    reason: "content_too_large";
+    size?: number;
+    cap: number;
+    message?: string;
+} | {
+    ok: false;
+    reason: "empty";
+} | {
+    ok: false;
+    reason: "decode_error";
+    message: string;
+};
+/**
+ * Read and length-cap the first content frame off a length-prefixed source.
+ * `cap` defaults to the 1 MB application message cap.
+ */
+export declare function readCappedContentFrame(source: AsyncIterable<Uint8Array>, cap?: number): Promise<CappedFrameResult>;
+//# sourceMappingURL=content-cap.d.ts.map

package/dist/content-cap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-cap.d.ts","sourceRoot":"","sources":["../src/content-cap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAKH,MAAM,MAAM,iBAAiB,GACzB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAE,GACjC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,mBAAmB,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACxF;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GAC9B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,cAAc,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAU3D;;;GAGG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,aAAa,CAAC,UAAU,CAAC,EACjC,GAAG,GAAE,MAA0B,GAC9B,OAAO,CAAC,iBAAiB,CAAC,CAoB5B"}

package/dist/content-cap.js

@@ -0,0 +1,58 @@
+/**
+ * CELLO-M7-MSG-001 — transport content-size cap.
+ *
+ * Reads the first length-prefixed frame from a content stream and enforces the
+ * application content cap (MAX_CONTENT_BYTES = 1 MB) EXPLICITLY, before the bare
+ * it-length-prefixed transport default (4 MB) can fire. Oversize content yields a
+ * distinct `content_too_large` outcome — never a silent decode failure that the
+ * caller mistakes for a desync (AC-014, SI-003).
+ *
+ * Pseudocode (SPARC Phase P):
+ *   readCappedContentFrame(source, cap):
+ *     decode with maxDataLength = transport default (4 MB) so 1–4 MB frames are
+ *       observable and we can report their exact size
+ *     for first frame:
+ *       payload = bytes
+ *       if payload.length > cap → { ok:false, content_too_large, size, cap }
+ *       else → { ok:true, payload }
+ *     no frame → { ok:false, empty }
+ *     decode throw (e.g. > 4 MB transport max) → { ok:false, content_too_large }
+ */
+import * as lp from "it-length-prefixed";
+import { MAX_CONTENT_BYTES, IT_LENGTH_PREFIX_DEFAULT_MAX } from "@cello-protocol/protocol-types";
+function toU8(chunk) {
+    if (chunk instanceof Uint8Array)
+        return chunk;
+    // Uint8ArrayList from it-length-prefixed exposes subarray()
+    const c = chunk;
+    if (typeof c?.subarray === "function")
+        return c.subarray();
+    return new Uint8Array(chunk);
+}
+/**
+ * Read and length-cap the first content frame off a length-prefixed source.
+ * `cap` defaults to the 1 MB application message cap.
+ */
+export async function readCappedContentFrame(source, cap = MAX_CONTENT_BYTES) {
+    try {
+        for await (const chunk of lp.decode(source, { maxDataLength: IT_LENGTH_PREFIX_DEFAULT_MAX })) {
+            const payload = toU8(chunk);
+            if (payload.length > cap) {
+                return { ok: false, reason: "content_too_large", size: payload.length, cap };
+            }
+            return { ok: true, payload };
+        }
+        return { ok: false, reason: "empty" };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        // A frame larger than the it-length-prefixed transport default trips the
+        // decoder's max-length guard. Surface it as content_too_large (never a silent
+        // failure, never a desync) rather than an opaque decode error.
+        if (/max|length|too long|data length/i.test(message)) {
+            return { ok: false, reason: "content_too_large", cap, message };
+        }
+        return { ok: false, reason: "decode_error", message };
+    }
+}
+//# sourceMappingURL=content-cap.js.map

package/dist/content-cap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-cap.js","sourceRoot":"","sources":["../src/content-cap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,MAAM,oBAAoB,CAAC;AACzC,OAAO,EAAE,iBAAiB,EAAE,4BAA4B,EAAE,MAAM,gCAAgC,CAAC;AAQjG,SAAS,IAAI,CAAC,KAAc;IAC1B,IAAI,KAAK,YAAY,UAAU;QAAE,OAAO,KAAK,CAAC;IAC9C,4DAA4D;IAC5D,MAAM,CAAC,GAAG,KAAwC,CAAC;IACnD,IAAI,OAAO,CAAC,EAAE,QAAQ,KAAK,UAAU;QAAE,OAAO,CAAC,CAAC,QAAQ,EAAE,CAAC;IAC3D,OAAO,IAAI,UAAU,CAAC,KAAwB,CAAC,CAAC;AAClD,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,MAAiC,EACjC,MAAc,iBAAiB;IAE/B,IAAI,CAAC;QACH,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,aAAa,EAAE,4BAA4B,EAAE,CAAC,EAAE,CAAC;YAC7F,MAAM,OAAO,GAAG,IAAI,CAAC,KAAgB,CAAC,CAAC;YACvC,IAAI,OAAO,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;gBACzB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,mBAAmB,EAAE,IAAI,EAAE,OAAO,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC;YAC/E,CAAC;YACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;QAC/B,CAAC;QACD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;IACxC,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,yEAAyE;QACzE,8EAA8E;QAC9E,+DAA+D;QAC/D,IAAI,kCAAkC,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YACrD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,mBAAmB,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC;QAClE,CAAC;QACD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,CAAC;IACxD,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -6,5 +6,15 @@
 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";
+export { CELLO_PROTOCOL_ID, CIRCUIT_RELAY_V2_HOP_PROTOCOL_ID, CELLO_CONTENT_PROTOCOL_ID, AUTONAT_PROTOCOL_ID } from "./protocols.js";
+export type { IAutoNatService, Dialability, Unsubscribe } from "./autonat.js";
+export { LocalAutoNatStub, DEFAULT_DIALABILITY } from "./autonat.js";
+export { NodeAutoNatService } from "./autonat-service.js";
+export type { AutoNatLogger, AutoNatNodeType, NodeAutoNatServiceOptions, } from "./autonat-service.js";
+export { readCappedContentFrame } from "./content-cap.js";
+export type { CappedFrameResult } from "./content-cap.js";
+export type { IManifestVersionStore, IManifestProvider, IDirectoryChallengeVerifier, ChallengeVerifyResult, ChallengeVerifyOk, ChallengeVerifyFail, IManifestPollScheduler, DirectoryKeyProvider, DirectoryManifestStore, } from "./manifest-interfaces.js";
+export { InMemoryManifestVersionStore, TestManifestProvider, TestDirectoryChallengeVerifier, ManifestDirectoryChallengeVerifier, ImmediatePollScheduler, TestDirectoryKeyProvider, TestDirectoryManifestStore, } from "./manifest-stubs.js";
+export { SignalingManager, InMemorySignalingOutboundQueue, buildStep5Tbs, } from "./signaling-manager.js";
+export type { SignalingAuthOkFrame, ManifestPollResponseFrame, ISignalingOutboundQueue, SignalingManagerConfig, SignalingManagerOptions, SignalingLogger, Logger as SignalingConnectionLogger, ProcessStep5Result, SignalingStream, ConnectResult, OperationResult, OperationSuccess, OperationFailure, SignalingFailureReason, } from "./signaling-manager.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +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"}
+{"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,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAGrI,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC9E,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAGrE,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,YAAY,EACV,aAAa,EACb,eAAe,EACf,yBAAyB,GAC1B,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,YAAY,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAG1D,YAAY,EACV,qBAAqB,EACrB,iBAAiB,EACjB,2BAA2B,EAC3B,qBAAqB,EACrB,iBAAiB,EACjB,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EACL,4BAA4B,EAC5B,oBAAoB,EACpB,8BAA8B,EAC9B,kCAAkC,EAClC,sBAAsB,EACtB,wBAAwB,EACxB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,gBAAgB,EAChB,8BAA8B,EAC9B,aAAa,GACd,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACV,oBAAoB,EACpB,yBAAyB,EACzB,uBAAuB,EACvB,sBAAsB,EACtB,uBAAuB,EACvB,eAAe,EACf,MAAM,IAAI,yBAAyB,EACnC,kBAAkB,EAClB,eAAe,EACf,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,wBAAwB,CAAC"}

package/dist/index.js

@@ -4,5 +4,15 @@
  * 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";
+export { CELLO_PROTOCOL_ID, CIRCUIT_RELAY_V2_HOP_PROTOCOL_ID, CELLO_CONTENT_PROTOCOL_ID, AUTONAT_PROTOCOL_ID } from "./protocols.js";
+export { LocalAutoNatStub, DEFAULT_DIALABILITY } from "./autonat.js";
+// CELLO-M7-TRANSPORT-001: real IAutoNatService over a live CelloNode (emits the
+// transport.autonat.result / transport.autonat.unavailable observability events).
+export { NodeAutoNatService } from "./autonat-service.js";
+// M7-MSG-001: content-size cap on inbound content decode
+export { readCappedContentFrame } from "./content-cap.js";
+// M7-MANIFEST-002: manifest stubs (for test use)
+export { InMemoryManifestVersionStore, TestManifestProvider, TestDirectoryChallengeVerifier, ManifestDirectoryChallengeVerifier, ImmediatePollScheduler, TestDirectoryKeyProvider, TestDirectoryManifestStore, } from "./manifest-stubs.js";
+// M7-SIGNAL-001 + M7-MANIFEST-002: SignalingManager, frame types, and helpers
+export { SignalingManager, InMemorySignalingOutboundQueue, buildStep5Tbs, } from "./signaling-manager.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +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"}
+{"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,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAIrI,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACrE,gFAAgF;AAChF,kFAAkF;AAClF,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAO1D,yDAAyD;AACzD,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAgB1D,iDAAiD;AACjD,OAAO,EACL,4BAA4B,EAC5B,oBAAoB,EACpB,8BAA8B,EAC9B,kCAAkC,EAClC,sBAAsB,EACtB,wBAAwB,EACxB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC;AAE7B,8EAA8E;AAC9E,OAAO,EACL,gBAAgB,EAChB,8BAA8B,EAC9B,aAAa,GACd,MAAM,wBAAwB,CAAC"}