@cello-protocol/transport 0.0.3 → 0.0.5

package/dist/manifest-interfaces.d.ts

@@ -0,0 +1,143 @@
+/**
+ * M7-MANIFEST-002 — Manifest-related interface definitions for the CELLO client daemon.
+ *
+ * These interfaces decouple the daemon and SignalingManager from their concrete
+ * implementations. All interfaces are narrow by design.
+ *
+ * Interface overview:
+ *
+ * Client-side (daemon / SignalingManager):
+ *   IManifestVersionStore   — persists the last-seen manifest version (monotonicity gate)
+ *   IManifestProvider       — loads, verifies, and caches the consortium manifest
+ *   IDirectoryChallengeVerifier — verifies the directory's step-5 Ed25519 challenge response
+ *   IManifestPollScheduler  — schedules background manifest poll calls
+ *
+ * Directory-side (directory node):
+ *   DirectoryKeyProvider    — provides the per-node nodeId and signs TBS bytes
+ *   DirectoryManifestStore  — provides the current consortium manifest for poll responses
+ *
+ * Crypto reference: RFC 8032 (Ed25519).
+ */
+import type { ConsortiumManifest } from "@cello-protocol/protocol-types";
+/**
+ * Persists the last-seen manifest version number across daemon restarts.
+ * Used to enforce version monotonicity: a manifest with a lower version number
+ * than the last-seen version is rejected as a potential rollback attack.
+ *
+ * In production: backed by SQLCipher local database.
+ * In tests: InMemoryManifestVersionStore (starts at null, holds in memory).
+ */
+export interface IManifestVersionStore {
+    /** Returns the last persisted version number, or null if none has been seen. */
+    getLastSeenVersion(): Promise<number | null>;
+    /** Persists a new version number, replacing the previous value. */
+    persistVersion(version: number): Promise<void>;
+}
+/**
+ * Loads, verifies, and caches the consortium manifest.
+ * Abstracts manifest source (bundled JSON file vs test-supplied object).
+ *
+ * Production: FileManifestProvider reads consortium-manifest.json from package root.
+ * Tests: TestManifestProvider takes a pre-built ConsortiumManifest, skips file read.
+ */
+export interface IManifestProvider {
+    /**
+     * Load the manifest from its source, verify the threshold signatures against
+     * the supplied root keys, and cache it for getCurrentManifest().
+     * Throws on signature failure, expiry, or missing nodes.
+     */
+    loadAndVerify(rootKeys: readonly string[], threshold: number): Promise<ConsortiumManifest>;
+    /**
+     * Returns the cached manifest from the last successful loadAndVerify() call.
+     * Returns null if loadAndVerify() has not been called or failed.
+     */
+    getCurrentManifest(): ConsortiumManifest | null;
+    /**
+     * Replace the cached manifest with a newly polled manifest.
+     * Called by SignalingManager.handleManifestPollResponse() after successful poll
+     * verification. This ensures IDirectoryChallengeVerifier (which reads from
+     * getCurrentManifest()) picks up key rotations reflected in the polled manifest.
+     */
+    updateManifest(manifest: ConsortiumManifest): void;
+}
+/**
+ * Verifies the directory's step-5 challenge response.
+ *
+ * Step 5 TBS (RFC 8032 signing input):
+ *   UTF-8('cello-directory-auth-challenge-v1\n') +
+ *   UTF-8(nodeId) + UTF-8('\n') +
+ *   UTF-8(agentPubkeyHex) + UTF-8('\n') +
+ *   UTF-8(nonceHex) + UTF-8('\n') +
+ *   UTF-8(isoTimestamp)
+ *
+ * Production: ManifestDirectoryChallengeVerifier reads the node's pubkey from
+ * the in-memory manifest loaded by IManifestProvider, verifies with @noble/curves.
+ * Tests: TestDirectoryChallengeVerifier — configurable pass/fail per nodeId.
+ */
+/** Result from a successful challenge verification. */
+export interface ChallengeVerifyOk {
+    valid: true;
+}
+/** Result from a failed challenge verification — reason distinguishes the failure cause. */
+export interface ChallengeVerifyFail {
+    valid: false;
+    /** 'key_not_in_manifest': nodeId not present in the loaded manifest.
+     *  'signature_invalid': nodeId found but Ed25519 signature failed verification. */
+    reason: "key_not_in_manifest" | "signature_invalid";
+}
+export type ChallengeVerifyResult = ChallengeVerifyOk | ChallengeVerifyFail;
+export interface IDirectoryChallengeVerifier {
+    /**
+     * Verify an Ed25519 signature over tbsBytes for the given nodeId.
+     * The nodeId is looked up in the loaded manifest; the corresponding pubkey
+     * is used for verification.
+     * Returns ChallengeVerifyOk if valid.
+     * Returns ChallengeVerifyFail with reason 'key_not_in_manifest' if nodeId absent.
+     * Returns ChallengeVerifyFail with reason 'signature_invalid' if nodeId found but sig fails.
+     * Never throws — all errors produce a ChallengeVerifyFail.
+     */
+    verifyChallenge(nodeId: string, tbsBytes: Uint8Array, signatureHex: string): ChallengeVerifyResult;
+}
+/**
+ * Schedules background manifest poll callbacks.
+ *
+ * Production: RandomizedPollScheduler — fires the callback after a random interval
+ * in the 6–12 hour window.
+ * Tests: ImmediatePollScheduler — fires once with a configurable delay (0ms default).
+ */
+export interface IManifestPollScheduler {
+    /**
+     * Schedule the next poll call. After the delay elapses, callbackFn() is invoked.
+     */
+    scheduleNext(callbackFn: () => Promise<void>): void;
+    /** Cancel any pending scheduled callback. Idempotent. */
+    cancel(): void;
+}
+/**
+ * Provides the directory node's unique identifier and signing capability.
+ * Each directory node has its own Ed25519 private key — never shared between nodes.
+ *
+ * Production: SecretsManagerDirectoryKeyProvider reads from AWS Secrets Manager at startup.
+ * Tests: TestDirectoryKeyProvider — takes { nodeId, privateKeyHex } in constructor.
+ */
+export interface DirectoryKeyProvider {
+    /** Returns the node's unique identifier string. */
+    getNodeId(): string;
+    /**
+     * Sign tbsBytes with the node's Ed25519 private key (RFC 8032).
+     * Returns a 64-byte signature as Uint8Array.
+     */
+    sign(tbsBytes: Uint8Array): Promise<Uint8Array>;
+}
+/**
+ * Provides the current consortium manifest for manifest_poll_response frames.
+ *
+ * Production: FileDirectoryManifestStore reads the manifest JSON deployed alongside
+ * the directory binary.
+ * Tests: TestDirectoryManifestStore — takes a fixed ConsortiumManifest.
+ */
+export interface DirectoryManifestStore {
+    /** Returns the current consortium manifest. Never throws in production. */
+    getCurrentManifest(): ConsortiumManifest;
+}
+//# sourceMappingURL=manifest-interfaces.d.ts.map

package/dist/manifest-interfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-interfaces.d.ts","sourceRoot":"","sources":["../src/manifest-interfaces.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAIzE;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAqB;IACpC,gFAAgF;IAChF,kBAAkB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC7C,mEAAmE;IACnE,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,aAAa,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC3F;;;OAGG;IACH,kBAAkB,IAAI,kBAAkB,GAAG,IAAI,CAAC;IAChD;;;;;OAKG;IACH,cAAc,CAAC,QAAQ,EAAE,kBAAkB,GAAG,IAAI,CAAC;CACpD;AAED;;;;;;;;;;;;;GAaG;AACH,uDAAuD;AACvD,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,IAAI,CAAC;CACb;AAED,4FAA4F;AAC5F,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,KAAK,CAAC;IACb;uFACmF;IACnF,MAAM,EAAE,qBAAqB,GAAG,mBAAmB,CAAC;CACrD;AAED,MAAM,MAAM,qBAAqB,GAAG,iBAAiB,GAAG,mBAAmB,CAAC;AAE5E,MAAM,WAAW,2BAA2B;IAC1C;;;;;;;;OAQG;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,GAAG,qBAAqB,CAAC;CACpG;AAED;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,YAAY,CAAC,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACpD,yDAAyD;IACzD,MAAM,IAAI,IAAI,CAAC;CAChB;AAID;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,mDAAmD;IACnD,SAAS,IAAI,MAAM,CAAC;IACpB;;;OAGG;IACH,IAAI,CAAC,QAAQ,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACjD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,2EAA2E;IAC3E,kBAAkB,IAAI,kBAAkB,CAAC;CAC1C"}

package/dist/manifest-interfaces.js

@@ -0,0 +1,22 @@
+/**
+ * M7-MANIFEST-002 — Manifest-related interface definitions for the CELLO client daemon.
+ *
+ * These interfaces decouple the daemon and SignalingManager from their concrete
+ * implementations. All interfaces are narrow by design.
+ *
+ * Interface overview:
+ *
+ * Client-side (daemon / SignalingManager):
+ *   IManifestVersionStore   — persists the last-seen manifest version (monotonicity gate)
+ *   IManifestProvider       — loads, verifies, and caches the consortium manifest
+ *   IDirectoryChallengeVerifier — verifies the directory's step-5 Ed25519 challenge response
+ *   IManifestPollScheduler  — schedules background manifest poll calls
+ *
+ * Directory-side (directory node):
+ *   DirectoryKeyProvider    — provides the per-node nodeId and signs TBS bytes
+ *   DirectoryManifestStore  — provides the current consortium manifest for poll responses
+ *
+ * Crypto reference: RFC 8032 (Ed25519).
+ */
+export {};
+//# sourceMappingURL=manifest-interfaces.js.map

package/dist/manifest-interfaces.js.map

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

package/dist/manifest-stubs.d.ts

@@ -0,0 +1,93 @@
+/**
+ * M7-MANIFEST-002 — In-memory stubs for manifest interfaces.
+ *
+ * These stubs are test-only implementations of the interfaces defined in
+ * manifest-interfaces.ts. They are intentionally simple — no file I/O, no external calls.
+ *
+ * Crypto reference: RFC 8032 (Ed25519).
+ */
+import type { ConsortiumManifest } from "@cello-protocol/protocol-types";
+import type { IManifestVersionStore, IManifestProvider, IDirectoryChallengeVerifier, ChallengeVerifyResult, IManifestPollScheduler, DirectoryKeyProvider, DirectoryManifestStore } from "./manifest-interfaces.js";
+/**
+ * InMemoryManifestVersionStore — starts at null, holds state in memory.
+ *
+ * // SQLCipher: InMemory stub used — real store wired in DAEMON-001
+ */
+export declare class InMemoryManifestVersionStore implements IManifestVersionStore {
+    #private;
+    getLastSeenVersion(): Promise<number | null>;
+    persistVersion(version: number): Promise<void>;
+}
+/**
+ * TestManifestProvider — takes a pre-built ConsortiumManifest, skips file read.
+ *
+ * loadAndVerify() returns the supplied manifest without signature verification.
+ */
+export declare class TestManifestProvider implements IManifestProvider {
+    #private;
+    constructor(manifest: ConsortiumManifest);
+    loadAndVerify(_rootKeys: readonly string[], _threshold: number): Promise<ConsortiumManifest>;
+    getCurrentManifest(): ConsortiumManifest | null;
+    updateManifest(manifest: ConsortiumManifest): void;
+}
+/**
+ * TestDirectoryChallengeVerifier — configurable pass/fail per nodeId.
+ * Rejected nodeIds produce 'key_not_in_manifest'; all other failures produce 'signature_invalid'.
+ */
+export declare class TestDirectoryChallengeVerifier implements IDirectoryChallengeVerifier {
+    #private;
+    rejectNodeId(nodeId: string): void;
+    invalidateSig(nodeId: string): void;
+    verifyChallenge(nodeId: string, _tbsBytes: Uint8Array, _signatureHex: string): ChallengeVerifyResult;
+}
+/**
+ * ManifestDirectoryChallengeVerifier — reads pubkey from in-memory manifest, verifies
+ * with @noble/curves Ed25519 (RFC 8032). Production client-side verifier.
+ *
+ * Pseudocode (RFC 8032 — Ed25519 verify):
+ *   1. Get the current manifest from IManifestProvider.
+ *   2. Find the node entry with nodeId == nodeId.
+ *   3. Decode pubkey hex (32 bytes) and signatureHex (64 bytes).
+ *   4. Call ed25519.verify(sigBytes, tbsBytes, pubkeyBytes).
+ *   5. Return the result; catch all errors and return false.
+ */
+export declare class ManifestDirectoryChallengeVerifier implements IDirectoryChallengeVerifier {
+    #private;
+    constructor(manifestProvider: IManifestProvider);
+    verifyChallenge(nodeId: string, tbsBytes: Uint8Array, signatureHex: string): ChallengeVerifyResult;
+}
+/**
+ * ImmediatePollScheduler — fires once with a configurable delay (0ms default).
+ */
+export declare class ImmediatePollScheduler implements IManifestPollScheduler {
+    #private;
+    constructor(delayMs?: number);
+    scheduleNext(callbackFn: () => Promise<void>): void;
+    cancel(): void;
+}
+/**
+ * TestDirectoryKeyProvider — takes { nodeId, privateKeyHex } in constructor.
+ *
+ * Crypto reference: RFC 8032 (Ed25519).
+ */
+export declare class TestDirectoryKeyProvider implements DirectoryKeyProvider {
+    #private;
+    constructor(opts: {
+        nodeId: string;
+        privateKeyHex: string;
+    });
+    getNodeId(): string;
+    /** Sign tbsBytes with Ed25519 private key (RFC 8032). Returns 64-byte Uint8Array. */
+    sign(tbsBytes: Uint8Array): Promise<Uint8Array>;
+    /** Returns the corresponding Ed25519 public key (32 bytes) as hex. */
+    getPublicKeyHex(): string;
+}
+/**
+ * TestDirectoryManifestStore — holds a fixed ConsortiumManifest.
+ */
+export declare class TestDirectoryManifestStore implements DirectoryManifestStore {
+    #private;
+    constructor(manifest: ConsortiumManifest);
+    getCurrentManifest(): ConsortiumManifest;
+}
+//# sourceMappingURL=manifest-stubs.d.ts.map

package/dist/manifest-stubs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-stubs.d.ts","sourceRoot":"","sources":["../src/manifest-stubs.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACzE,OAAO,KAAK,EACV,qBAAqB,EACrB,iBAAiB,EACjB,2BAA2B,EAC3B,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,EACpB,sBAAsB,EACvB,MAAM,0BAA0B,CAAC;AAIlC;;;;GAIG;AACH,qBAAa,4BAA6B,YAAW,qBAAqB;;IAGlE,kBAAkB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAI5C,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGrD;AAID;;;;GAIG;AACH,qBAAa,oBAAqB,YAAW,iBAAiB;;gBAIhD,QAAQ,EAAE,kBAAkB;IAIlC,aAAa,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAKlG,kBAAkB,IAAI,kBAAkB,GAAG,IAAI;IAI/C,cAAc,CAAC,QAAQ,EAAE,kBAAkB,GAAG,IAAI;CAInD;AAID;;;GAGG;AACH,qBAAa,8BAA+B,YAAW,2BAA2B;;IAIhF,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAIlC,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAInC,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,GAAG,qBAAqB;CASrG;AAED;;;;;;;;;;GAUG;AACH,qBAAa,kCAAmC,YAAW,2BAA2B;;gBAGxE,gBAAgB,EAAE,iBAAiB;IAI/C,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,GAAG,qBAAqB;CA2BnG;AAID;;GAEG;AACH,qBAAa,sBAAuB,YAAW,sBAAsB;;gBAIvD,OAAO,SAAI;IAIvB,YAAY,CAAC,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAWnD,MAAM,IAAI,IAAI;CAMf;AAID;;;;GAIG;AACH,qBAAa,wBAAyB,YAAW,oBAAoB;;gBAIvD,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE;IAQ3D,SAAS,IAAI,MAAM;IAInB,qFAAqF;IAC/E,IAAI,CAAC,QAAQ,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IAIrD,sEAAsE;IACtE,eAAe,IAAI,MAAM;CAG1B;AAID;;GAEG;AACH,qBAAa,0BAA2B,YAAW,sBAAsB;;gBAG3D,QAAQ,EAAE,kBAAkB;IAIxC,kBAAkB,IAAI,kBAAkB;CAGzC"}

package/dist/manifest-stubs.js

@@ -0,0 +1,192 @@
+/**
+ * M7-MANIFEST-002 — In-memory stubs for manifest interfaces.
+ *
+ * These stubs are test-only implementations of the interfaces defined in
+ * manifest-interfaces.ts. They are intentionally simple — no file I/O, no external calls.
+ *
+ * Crypto reference: RFC 8032 (Ed25519).
+ */
+import { ed25519 } from "@noble/curves/ed25519.js";
+// ─── IManifestVersionStore ───────────────────────────────────────────────────
+/**
+ * InMemoryManifestVersionStore — starts at null, holds state in memory.
+ *
+ * // SQLCipher: InMemory stub used — real store wired in DAEMON-001
+ */
+export class InMemoryManifestVersionStore {
+    #lastSeenVersion = null;
+    async getLastSeenVersion() {
+        return this.#lastSeenVersion;
+    }
+    async persistVersion(version) {
+        this.#lastSeenVersion = version;
+    }
+}
+// ─── IManifestProvider ───────────────────────────────────────────────────────
+/**
+ * TestManifestProvider — takes a pre-built ConsortiumManifest, skips file read.
+ *
+ * loadAndVerify() returns the supplied manifest without signature verification.
+ */
+export class TestManifestProvider {
+    #manifest;
+    #loaded = null;
+    constructor(manifest) {
+        this.#manifest = manifest;
+    }
+    async loadAndVerify(_rootKeys, _threshold) {
+        this.#loaded = this.#manifest;
+        return this.#manifest;
+    }
+    getCurrentManifest() {
+        return this.#loaded;
+    }
+    updateManifest(manifest) {
+        this.#manifest = manifest;
+        this.#loaded = manifest;
+    }
+}
+// ─── IDirectoryChallengeVerifier ─────────────────────────────────────────────
+/**
+ * TestDirectoryChallengeVerifier — configurable pass/fail per nodeId.
+ * Rejected nodeIds produce 'key_not_in_manifest'; all other failures produce 'signature_invalid'.
+ */
+export class TestDirectoryChallengeVerifier {
+    #rejectedNodeIds = new Set();
+    #invalidSigNodeIds = new Set();
+    rejectNodeId(nodeId) {
+        this.#rejectedNodeIds.add(nodeId);
+    }
+    invalidateSig(nodeId) {
+        this.#invalidSigNodeIds.add(nodeId);
+    }
+    verifyChallenge(nodeId, _tbsBytes, _signatureHex) {
+        if (this.#rejectedNodeIds.has(nodeId)) {
+            return { valid: false, reason: "key_not_in_manifest" };
+        }
+        if (this.#invalidSigNodeIds.has(nodeId)) {
+            return { valid: false, reason: "signature_invalid" };
+        }
+        return { valid: true };
+    }
+}
+/**
+ * ManifestDirectoryChallengeVerifier — reads pubkey from in-memory manifest, verifies
+ * with @noble/curves Ed25519 (RFC 8032). Production client-side verifier.
+ *
+ * Pseudocode (RFC 8032 — Ed25519 verify):
+ *   1. Get the current manifest from IManifestProvider.
+ *   2. Find the node entry with nodeId == nodeId.
+ *   3. Decode pubkey hex (32 bytes) and signatureHex (64 bytes).
+ *   4. Call ed25519.verify(sigBytes, tbsBytes, pubkeyBytes).
+ *   5. Return the result; catch all errors and return false.
+ */
+export class ManifestDirectoryChallengeVerifier {
+    #manifestProvider;
+    constructor(manifestProvider) {
+        this.#manifestProvider = manifestProvider;
+    }
+    verifyChallenge(nodeId, tbsBytes, signatureHex) {
+        try {
+            const manifest = this.#manifestProvider.getCurrentManifest();
+            if (!manifest)
+                return { valid: false, reason: "key_not_in_manifest" };
+            const node = manifest.nodes.find((n) => n.nodeId === nodeId);
+            if (!node)
+                return { valid: false, reason: "key_not_in_manifest" };
+            // Decode 32-byte pubkey from 64-char hex (RFC 8032)
+            if (node.pubkey.length !== 64 || !/^[0-9a-fA-F]+$/.test(node.pubkey)) {
+                return { valid: false, reason: "signature_invalid" };
+            }
+            const pubkeyBytes = hexToBytes(node.pubkey);
+            // Decode 64-byte signature from 128-char hex
+            if (signatureHex.length !== 128 || !/^[0-9a-fA-F]+$/.test(signatureHex)) {
+                return { valid: false, reason: "signature_invalid" };
+            }
+            const sigBytes = hexToBytes(signatureHex);
+            // RFC 8032: ed25519.verify(signature, message, publicKey)
+            const ok = ed25519.verify(sigBytes, tbsBytes, pubkeyBytes);
+            return ok ? { valid: true } : { valid: false, reason: "signature_invalid" };
+        }
+        catch {
+            return { valid: false, reason: "signature_invalid" };
+        }
+    }
+}
+// ─── IManifestPollScheduler ───────────────────────────────────────────────────
+/**
+ * ImmediatePollScheduler — fires once with a configurable delay (0ms default).
+ */
+export class ImmediatePollScheduler {
+    #delayMs;
+    #timer = null;
+    constructor(delayMs = 0) {
+        this.#delayMs = delayMs;
+    }
+    scheduleNext(callbackFn) {
+        this.cancel();
+        this.#timer = setTimeout(() => {
+            this.#timer = null;
+            // Let errors propagate in test context — swallowing them hides assertion failures
+            callbackFn().catch((err) => {
+                throw err instanceof Error ? err : new Error(String(err));
+            });
+        }, this.#delayMs);
+    }
+    cancel() {
+        if (this.#timer !== null) {
+            clearTimeout(this.#timer);
+            this.#timer = null;
+        }
+    }
+}
+// ─── DirectoryKeyProvider ─────────────────────────────────────────────────────
+/**
+ * TestDirectoryKeyProvider — takes { nodeId, privateKeyHex } in constructor.
+ *
+ * Crypto reference: RFC 8032 (Ed25519).
+ */
+export class TestDirectoryKeyProvider {
+    #nodeId;
+    #privateKeyBytes;
+    constructor(opts) {
+        this.#nodeId = opts.nodeId;
+        if (opts.privateKeyHex.length !== 64) {
+            throw new Error(`TestDirectoryKeyProvider: privateKeyHex must be 64 chars (32 bytes), got ${opts.privateKeyHex.length}`);
+        }
+        this.#privateKeyBytes = hexToBytes(opts.privateKeyHex);
+    }
+    getNodeId() {
+        return this.#nodeId;
+    }
+    /** Sign tbsBytes with Ed25519 private key (RFC 8032). Returns 64-byte Uint8Array. */
+    async sign(tbsBytes) {
+        return ed25519.sign(tbsBytes, this.#privateKeyBytes);
+    }
+    /** Returns the corresponding Ed25519 public key (32 bytes) as hex. */
+    getPublicKeyHex() {
+        return Buffer.from(ed25519.getPublicKey(this.#privateKeyBytes)).toString("hex");
+    }
+}
+// ─── DirectoryManifestStore ────────────────────────────────────────────────────
+/**
+ * TestDirectoryManifestStore — holds a fixed ConsortiumManifest.
+ */
+export class TestDirectoryManifestStore {
+    #manifest;
+    constructor(manifest) {
+        this.#manifest = manifest;
+    }
+    getCurrentManifest() {
+        return this.#manifest;
+    }
+}
+// ─── Internal helpers ────────────────────────────────────────────────────────
+function hexToBytes(hex) {
+    const bytes = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < bytes.length; i++) {
+        bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    }
+    return bytes;
+}
+//# sourceMappingURL=manifest-stubs.js.map

package/dist/manifest-stubs.js.map

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

package/dist/node.d.ts

@@ -76,7 +76,18 @@ import type { CelloNode, CreateNodeOptions } from "./types.js";
  *   - Transports: TCP + WebSockets
  *   - Security: Noise ONLY (XX pattern, RFC: https://noiseprotocol.org/noise.html)
  *   - Muxer: Yamux
- *   - Services: identify, circuitRelayServer (advertises HOP), DCuTR
+ *   - Services: identify, circuitRelayServer (advertises HOP), AutoNAT, DCuTR
+ *
+ * CELLO-M7-TRANSPORT-001:
+ *   - autoNAT() is added to ALL nodes. On client nodes (session / standing
+ *     receiver) it probes connected directory nodes for dial-back to determine
+ *     dialability; on directory nodes it serves the responder role, answering
+ *     dial-back requests (AC-011). Protocol: /libp2p/autonat/1.0.0.
+ *   - dcutr() is included for session nodes (and the default/service nodes) so a
+ *     relay-fallback connection can be hole-punch upgraded to direct, but is
+ *     OMITTED for standing-receiver nodes (nodeType==='standing_receiver') — a
+ *     standing receiver only needs to know its own dialability, not upgrade
+ *     existing connections (AC-002).
  */
 export declare function createNode(opts: CreateNodeOptions): Promise<CelloNode>;
 //# sourceMappingURL=node.d.ts.map

package/dist/node.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AAgBH,OAAO,KAAK,EACV,SAAS,EAET,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAkTpB;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,SAAS,CAAC,CA0E5E"}