@cello-protocol/client 0.0.2

package/dist/encrypted-file-signing-key-provider.js

@@ -0,0 +1,251 @@
+/**
+ * EncryptedFileSigningKeyProvider — file-backed SigningKeyProvider for CELLO_ENV=local/dev.
+ *
+ * PERSIST-010: Reads the Ed25519 private key seed from an encrypted key file at the
+ * configured path, decrypts it into memory for signing, and zeroes the in-memory key
+ * buffer after each sign() call (SI-002).
+ *
+ * The private key NEVER crosses the provider boundary (SI-001). The only exported
+ * values are the public key (via getPublicKey()) and signatures (via sign()).
+ *
+ * Key file format (same as FileKeyProvider in @cello-protocol/crypto):
+ *   Bytes 0–3:   Magic [0xCE, 0x11, 0x0E, 0x01]
+ *   Byte 4:      Version (0x01)
+ *   Bytes 5–36:  32-byte Ed25519 seed
+ *
+ * This file is NOT exported from packages/client/src/index.ts.
+ * It is only imported by the composition root (server.ts).
+ *
+ * RFC reference: Ed25519 signing per RFC 8032.
+ */
+import { readFile } from "node:fs/promises";
+import { ed25519 } from "@noble/curves/ed25519.js";
+import { SigningKeyProviderError } from "@cello-protocol/interfaces";
+// ─── Key file format constants ───────────────────────────────────────────────
+const KEY_FILE_MAGIC = new Uint8Array([0xce, 0x11, 0x0e, 0x01]);
+const KEY_FILE_VERSION = 1;
+const SEED_BYTES = 32;
+const KEY_FILE_SIZE = KEY_FILE_MAGIC.length + 1 + SEED_BYTES; // 37 bytes
+// ─── EncryptedFileSigningKeyProvider ─────────────────────────────────────────
+/**
+ * SigningKeyProvider backed by an encrypted key file on disk.
+ *
+ * Lifecycle: EncryptedFileSigningKeyProvider.load(path, opts) → ready to sign.
+ *
+ * On each sign() call, the seed is read from the file into a temporary buffer,
+ * used for signing, and the buffer is zeroed immediately after — even on throw.
+ * This ensures the private key exists in process memory only for the minimum
+ * time required to produce the signature.
+ *
+ * Security invariants:
+ *   SI-001: No method returns/exports the private key.
+ *   SI-002: Key buffer zeroed after EVERY sign() call, even on throw (try/finally).
+ *   SI-003: sign() failure propagates — never falls back to weaker signing.
+ */
+export class EncryptedFileSigningKeyProvider {
+    #publicKey;
+    #keyPath;
+    #agentId;
+    #logger;
+    /**
+     * Working buffer for seed bytes during signing — zeroed in finally after every sign() call.
+     *
+     * This is a persistent instance field shared across sign() calls. The design is safe because
+     * ed25519.sign() is synchronous — there is no await between raw.copy() and the finally zeroing,
+     * so no concurrent call can observe key material in the buffer. If async operations were ever
+     * added between load and use, a local-variable-per-call design would be safer.
+     */
+    #workingBuffer = new Uint8Array(SEED_BYTES);
+    #corrupted = false;
+    #throwAfterLoad = false;
+    constructor(publicKey, keyPath, agentId, logger) {
+        this.#publicKey = publicKey;
+        this.#keyPath = keyPath;
+        this.#agentId = agentId;
+        this.#logger = logger;
+    }
+    /**
+     * Load the signing key from the key file at the given path.
+     *
+     * Validates the file format and derives the public key. The seed itself
+     * is not retained — it is re-read from the file on each sign() call.
+     *
+     * Throws SigningKeyProviderError if:
+     *   - File not found (reason: 'key_file_not_found')
+     *   - File corrupt (reason: 'key_file_corrupt')
+     *
+     * @param path - Absolute path to the encrypted key file (SIGNING_KEY_PATH)
+     * @param opts - Configuration including agentId and logger
+     */
+    static async load(path, opts) {
+        const { agentId, logger } = opts;
+        let raw;
+        try {
+            raw = await readFile(path);
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === "ENOENT") {
+                logger.error("client.key.provider.init.failed", {
+                    agentId,
+                    providerType: "EncryptedFileSigningKeyProvider",
+                    reason: "key_file_not_found",
+                    errorMessage: err.message,
+                });
+                throw new SigningKeyProviderError("key_file_not_found", path);
+            }
+            const reason = `cannot read key file: ${err.message}`;
+            logger.error("client.key.provider.init.failed", {
+                agentId,
+                providerType: "EncryptedFileSigningKeyProvider",
+                reason,
+                errorMessage: err.message,
+            });
+            throw new SigningKeyProviderError("key_file_corrupt", path);
+        }
+        // Validate and extract seed to derive public key, then zero the temp buffer
+        const seedForInit = validateAndExtractSeed(raw, path, agentId, logger);
+        const publicKey = ed25519.getPublicKey(seedForInit);
+        seedForInit.fill(0); // Zero the initialization buffer immediately
+        logger.info("client.key.provider.initialised", {
+            agentId,
+            providerType: "EncryptedFileSigningKeyProvider",
+        });
+        return new EncryptedFileSigningKeyProvider(publicKey, path, agentId, logger);
+    }
+    /** Return the 32-byte Ed25519 public key. */
+    async getPublicKey() {
+        return this.#publicKey;
+    }
+    /**
+     * Sign data with the Ed25519 private key.
+     *
+     * Security: On each call, the seed is re-read from the key file into a
+     * working buffer, used for signing, and the buffer is zeroed in a finally
+     * block — even if signing throws (SI-002).
+     *
+     * The public key is derived once at load() and cached — it is not sensitive.
+     */
+    async sign(data, opts) {
+        if (this.#corrupted) {
+            this.#workingBuffer.fill(0);
+            const err = new SigningKeyProviderError("provider_corrupted");
+            this.#logger.error("client.key.sign.failed", {
+                agentId: this.#agentId,
+                reason: "provider_corrupted",
+            });
+            throw err;
+        }
+        // Re-read seed from file into working buffer
+        try {
+            const raw = await readFile(this.#keyPath);
+            raw.copy(Buffer.from(this.#workingBuffer.buffer, this.#workingBuffer.byteOffset, SEED_BYTES), 0, KEY_FILE_MAGIC.length + 1, KEY_FILE_SIZE);
+        }
+        catch (err) {
+            this.#workingBuffer.fill(0);
+            const reason = err instanceof Error ? err.message : String(err);
+            this.#logger.error("client.key.sign.failed", {
+                agentId: this.#agentId,
+                reason,
+                errorMessage: err.message,
+            });
+            throw new SigningKeyProviderError(reason);
+        }
+        // SI-002 test seam: throw AFTER key material is in the buffer so the finally
+        // block zeroing is exercised under adversarial conditions.
+        if (this.#throwAfterLoad) {
+            try {
+                throw new Error("injected failure after key load");
+            }
+            finally {
+                // SI-002: ALWAYS zero the working buffer, even on test-injected throw
+                this.#workingBuffer.fill(0);
+            }
+        }
+        try {
+            const signature = ed25519.sign(data, this.#workingBuffer);
+            this.#logger.info("client.key.signed", {
+                agentId: this.#agentId,
+                dataLength: data.length,
+                ...(opts?.correlationId !== undefined && { correlationId: opts.correlationId }),
+            });
+            return signature;
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            this.#logger.error("client.key.sign.failed", {
+                agentId: this.#agentId,
+                reason,
+                errorMessage: err.message,
+            });
+            throw new SigningKeyProviderError(reason);
+        }
+        finally {
+            // SI-002: ALWAYS zero the working buffer after sign(), even on throw
+            this.#workingBuffer.fill(0);
+        }
+    }
+    // ─── Test-only methods (not part of SigningKeyProvider interface) ───────────
+    /**
+     * @internal Test seam — returns true if the working buffer is currently all-zeros.
+     * This does NOT expose key material. Tests use this to verify SI-002 (zeroing)
+     * without ever seeing the private key bytes.
+     */
+    isKeyBufferZeroedForTesting() {
+        return this.#workingBuffer.every((b) => b === 0);
+    }
+    /**
+     * @internal Test seam — corrupts the provider state to trigger sign() failures
+     * BEFORE the key file is read. Used to test SI-003 (no fallback).
+     * Note: does NOT exercise the try/finally zeroing path — use throwAfterLoadForTesting() for that.
+     */
+    corruptForTesting() {
+        this.#corrupted = true;
+    }
+    /**
+     * @internal Test seam — causes sign() to throw AFTER the key has been loaded into
+     * the working buffer but BEFORE ed25519.sign() is called. Used to verify SI-002:
+     * the finally block zeroes the key buffer even when sign() throws mid-operation.
+     */
+    throwAfterLoadForTesting() {
+        this.#throwAfterLoad = true;
+    }
+}
+// ─── Private helpers ─────────────────────────────────────────────────────────
+/**
+ * Validate key file format and extract the seed into a new buffer.
+ * Throws SigningKeyProviderError on invalid format.
+ */
+function validateAndExtractSeed(raw, path, agentId, logger) {
+    if (raw.length !== KEY_FILE_SIZE) {
+        logger.error("client.key.provider.init.failed", {
+            agentId,
+            providerType: "EncryptedFileSigningKeyProvider",
+            reason: "key_file_corrupt",
+        });
+        throw new SigningKeyProviderError("key_file_corrupt", path);
+    }
+    for (let i = 0; i < KEY_FILE_MAGIC.length; i++) {
+        if (raw[i] !== KEY_FILE_MAGIC[i]) {
+            logger.error("client.key.provider.init.failed", {
+                agentId,
+                providerType: "EncryptedFileSigningKeyProvider",
+                reason: "key_file_corrupt",
+            });
+            throw new SigningKeyProviderError("key_file_corrupt", path);
+        }
+    }
+    if (raw[KEY_FILE_MAGIC.length] !== KEY_FILE_VERSION) {
+        logger.error("client.key.provider.init.failed", {
+            agentId,
+            providerType: "EncryptedFileSigningKeyProvider",
+            reason: "key_file_corrupt",
+        });
+        throw new SigningKeyProviderError("key_file_corrupt", path);
+    }
+    // Copy seed into a new buffer (caller must zero after use)
+    const seed = new Uint8Array(SEED_BYTES);
+    raw.copy(Buffer.from(seed.buffer), 0, KEY_FILE_MAGIC.length + 1, KEY_FILE_SIZE);
+    return seed;
+}
+//# sourceMappingURL=encrypted-file-signing-key-provider.js.map

package/dist/encrypted-file-signing-key-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"encrypted-file-signing-key-provider.js","sourceRoot":"","sources":["../src/encrypted-file-signing-key-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAEnD,OAAO,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAGrE,gFAAgF;AAEhF,MAAM,cAAc,GAAG,IAAI,UAAU,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;AAChE,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAC3B,MAAM,UAAU,GAAG,EAAE,CAAC;AACtB,MAAM,aAAa,GAAG,cAAc,CAAC,MAAM,GAAG,CAAC,GAAG,UAAU,CAAC,CAAC,WAAW;AAYzE,gFAAgF;AAEhF;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,+BAA+B;IACjC,UAAU,CAAmB;IAC7B,QAAQ,CAAS;IACjB,QAAQ,CAAS;IACjB,OAAO,CAAS;IACzB;;;;;;;OAOG;IACM,cAAc,GAAe,IAAI,UAAU,CAAC,UAAU,CAAC,CAAC;IACjE,UAAU,GAAY,KAAK,CAAC;IAC5B,eAAe,GAAY,KAAK,CAAC;IAEjC,YACE,SAA2B,EAC3B,OAAe,EACf,OAAe,EACf,MAAc;QAEd,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;QAC5B,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;QACxB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;QACxB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IACxB,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,KAAK,CAAC,IAAI,CACf,IAAY,EACZ,IAA4C;QAE5C,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QAEjC,IAAI,GAAW,CAAC;QAChB,IAAI,CAAC;YACH,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC7B,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACtB,MAAM,IAAI,GAAI,GAA6B,CAAC,IAAI,CAAC;YACjD,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACtB,MAAM,CAAC,KAAK,CAAC,iCAAiC,EAAE;oBAC9C,OAAO;oBACP,YAAY,EAAE,iCAAiC;oBAC/C,MAAM,EAAE,oBAAoB;oBAC5B,YAAY,EAAG,GAAa,CAAC,OAAO;iBACrC,CAAC,CAAC;gBACH,MAAM,IAAI,uBAAuB,CAAC,oBAAoB,EAAE,IAAI,CAAC,CAAC;YAChE,CAAC;YACD,MAAM,MAAM,GAAG,yBAA0B,GAAa,CAAC,OAAO,EAAE,CAAC;YACjE,MAAM,CAAC,KAAK,CAAC,iCAAiC,EAAE;gBAC9C,OAAO;gBACP,YAAY,EAAE,iCAAiC;gBAC/C,MAAM;gBACN,YAAY,EAAG,GAAa,CAAC,OAAO;aACrC,CAAC,CAAC;YACH,MAAM,IAAI,uBAAuB,CAAC,kBAAkB,EAAE,IAAI,CAAC,CAAC;QAC9D,CAAC;QAED,4EAA4E;QAC5E,MAAM,WAAW,GAAG,sBAAsB,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;QACvE,MAAM,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;QACpD,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,6CAA6C;QAElE,MAAM,CAAC,IAAI,CAAC,iCAAiC,EAAE;YAC7C,OAAO;YACP,YAAY,EAAE,iCAAiC;SAChD,CAAC,CAAC;QAEH,OAAO,IAAI,+BAA+B,CAAC,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IAC/E,CAAC;IAED,6CAA6C;IAC7C,KAAK,CAAC,YAAY;QAChB,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,IAAI,CAAC,IAAgB,EAAE,IAAkB;QAC7C,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACpB,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAC5B,MAAM,GAAG,GAAG,IAAI,uBAAuB,CAAC,oBAAoB,CAAC,CAAC;YAC9D,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,wBAAwB,EAAE;gBAC3C,OAAO,EAAE,IAAI,CAAC,QAAQ;gBACtB,MAAM,EAAE,oBAAoB;aAC7B,CAAC,CAAC;YACH,MAAM,GAAG,CAAC;QACZ,CAAC;QAED,6CAA6C;QAC7C,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC1C,GAAG,CAAC,IAAI,CACN,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,cAAc,CAAC,UAAU,EAAE,UAAU,CAAC,EACnF,CAAC,EACD,cAAc,CAAC,MAAM,GAAG,CAAC,EACzB,aAAa,CACd,CAAC;QACJ,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACtB,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAC5B,MAAM,MAAM,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAChE,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,wBAAwB,EAAE;gBAC3C,OAAO,EAAE,IAAI,CAAC,QAAQ;gBACtB,MAAM;gBACN,YAAY,EAAG,GAAa,CAAC,OAAO;aACrC,CAAC,CAAC;YACH,MAAM,IAAI,uBAAuB,CAAC,MAAM,CAAC,CAAC;QAC5C,CAAC;QAED,6EAA6E;QAC7E,2DAA2D;QAC3D,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;YACzB,IAAI,CAAC;gBACH,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;YACrD,CAAC;oBAAS,CAAC;gBACT,sEAAsE;gBACtE,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAC9B,CAAC;QACH,CAAC;QAED,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC;YAC1D,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,mBAAmB,EAAE;gBACrC,OAAO,EAAE,IAAI,CAAC,QAAQ;gBACtB,UAAU,EAAE,IAAI,CAAC,MAAM;gBACvB,GAAG,CAAC,IAAI,EAAE,aAAa,KAAK,SAAS,IAAI,EAAE,aAAa,EAAE,IAAI,CAAC,aAAa,EAAE,CAAC;aAChF,CAAC,CAAC;YACH,OAAO,SAAS,CAAC;QACnB,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACtB,MAAM,MAAM,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAChE,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,wBAAwB,EAAE;gBAC3C,OAAO,EAAE,IAAI,CAAC,QAAQ;gBACtB,MAAM;gBACN,YAAY,EAAG,GAAa,CAAC,OAAO;aACrC,CAAC,CAAC;YACH,MAAM,IAAI,uBAAuB,CAAC,MAAM,CAAC,CAAC;QAC5C,CAAC;gBAAS,CAAC;YACT,qEAAqE;YACrE,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IAED,+EAA+E;IAE/E;;;;OAIG;IACH,2BAA2B;QACzB,OAAO,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;IACnD,CAAC;IAED;;;;OAIG;IACH,iBAAiB;QACf,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;IACzB,CAAC;IAED;;;;OAIG;IACH,wBAAwB;QACtB,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC;IAC9B,CAAC;CACF;AAED,gFAAgF;AAEhF;;;GAGG;AACH,SAAS,sBAAsB,CAC7B,GAAW,EACX,IAAY,EACZ,OAAe,EACf,MAAc;IAEd,IAAI,GAAG,CAAC,MAAM,KAAK,aAAa,EAAE,CAAC;QACjC,MAAM,CAAC,KAAK,CAAC,iCAAiC,EAAE;YAC9C,OAAO;YACP,YAAY,EAAE,iCAAiC;YAC/C,MAAM,EAAE,kBAAkB;SAC3B,CAAC,CAAC;QACH,MAAM,IAAI,uBAAuB,CAAC,kBAAkB,EAAE,IAAI,CAAC,CAAC;IAC9D,CAAC;IAED,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,cAAc,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC/C,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,cAAc,CAAC,CAAC,CAAC,EAAE,CAAC;YACjC,MAAM,CAAC,KAAK,CAAC,iCAAiC,EAAE;gBAC9C,OAAO;gBACP,YAAY,EAAE,iCAAiC;gBAC/C,MAAM,EAAE,kBAAkB;aAC3B,CAAC,CAAC;YACH,MAAM,IAAI,uBAAuB,CAAC,kBAAkB,EAAE,IAAI,CAAC,CAAC;QAC9D,CAAC;IACH,CAAC;IAED,IAAI,GAAG,CAAC,cAAc,CAAC,MAAM,CAAC,KAAK,gBAAgB,EAAE,CAAC;QACpD,MAAM,CAAC,KAAK,CAAC,iCAAiC,EAAE;YAC9C,OAAO;YACP,YAAY,EAAE,iCAAiC;YAC/C,MAAM,EAAE,kBAAkB;SAC3B,CAAC,CAAC;QACH,MAAM,IAAI,uBAAuB,CAAC,kBAAkB,EAAE,IAAI,CAAC,CAAC;IAC9D,CAAC;IAED,2DAA2D;IAC3D,MAAM,IAAI,GAAG,IAAI,UAAU,CAAC,UAAU,CAAC,CAAC;IACxC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,cAAc,CAAC,MAAM,GAAG,CAAC,EAAE,aAAa,CAAC,CAAC;IAChF,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { createClient } from "./client.js";
+export { S3CloudStorageProvider } from "./s3-cloud-storage-provider.js";
+export type { S3CloudStorageConfig } from "./s3-cloud-storage-provider.js";
+export { AgentHashQueue, buildSignedAckTbs, verifyRelayAck, RELAY_PREDECESSOR_UNKNOWN, } from "./agent-hash-queue.js";
+export type { AgentHashQueueOptions, RelayAck, PendingHashEntry, RelayPredecessorUnknown, } from "./agent-hash-queue.js";
+export { NetworkDirectoryNode, bootstrapNetworkKeyShares, runNetworkDkg } from "./network-directory-node.js";
+export { createMcpSessionServer } from "./mcp-server.js";
+export { ClientBackup, BACKUP_WARNING } from "./client-backup.js";
+export type { ClientBackupOptions } from "./client-backup.js";
+export type { CelloClient, PeerEntry, SendResult, SendFailureReason, ReceivedEnvelope, ReceivedMessage, SendMessageResult, SendMessageFailureReason, SessionRecord, SessionStatus, ReceiveAssignmentResult, SessionAssignmentEvent, InitiateSessionResult, } from "./types.js";
+export { evaluateConnectionPackage, OPEN_POLICY, SELECTIVE_DEFAULT, CLOSED_POLICY, } from "./connection-policy.js";
+export type { DirectoryContext, SignalRequirement, SignalRequirementPolicy, UnmetRequirement, ConnectionReport, } from "./connection-policy.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,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AACxE,YAAY,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AAC3E,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,yBAAyB,GAC1B,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EACV,qBAAqB,EACrB,QAAQ,EACR,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC7G,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAClE,YAAY,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,YAAY,EACV,WAAW,EACX,SAAS,EACT,UAAU,EACV,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,wBAAwB,EACxB,aAAa,EACb,aAAa,EACb,uBAAuB,EACvB,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,yBAAyB,EACzB,WAAW,EACX,iBAAiB,EACjB,aAAa,GACd,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACV,gBAAgB,EAChB,iBAAiB,EACjB,uBAAuB,EACvB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,wBAAwB,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+export { createClient } from "./client.js";
+export { S3CloudStorageProvider } from "./s3-cloud-storage-provider.js";
+export { AgentHashQueue, buildSignedAckTbs, verifyRelayAck, RELAY_PREDECESSOR_UNKNOWN, } from "./agent-hash-queue.js";
+export { NetworkDirectoryNode, bootstrapNetworkKeyShares, runNetworkDkg } from "./network-directory-node.js";
+export { createMcpSessionServer } from "./mcp-server.js";
+export { ClientBackup, BACKUP_WARNING } from "./client-backup.js";
+export { evaluateConnectionPackage, OPEN_POLICY, SELECTIVE_DEFAULT, CLOSED_POLICY, } from "./connection-policy.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,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAExE,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,yBAAyB,GAC1B,MAAM,uBAAuB,CAAC;AAO/B,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC7G,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAiBlE,OAAO,EACL,yBAAyB,EACzB,WAAW,EACX,iBAAiB,EACjB,aAAa,GACd,MAAM,wBAAwB,CAAC"}

package/dist/mcp-server.d.ts

@@ -0,0 +1,270 @@
+/**
+ * CELLO MCP Session Server — mcp-server.ts (CELLO-MCP-003)
+ *
+ * createMcpSessionServer(node, client, keyProvider): McpServer
+ *   Registers the M3 tool set (19 tools) against a CelloClient.
+ *   Transport-agnostic: identical tool names, schemas, and wiring under
+ *   InMemoryTransport (tests) and stdio (production). AC-016.
+ *
+ * MCP-003 additions (10 new tools):
+ *   cello_register               — REG-001 DKG registration
+ *   cello_request_connection     — CONNREQ-002 Round 1 sender
+ *   cello_respond_to_disclosure_request — CONNREQ-002 Round 2 sender
+ *   cello_await_connection_request — waits for agent-review inbound request
+ *   cello_accept_connection      — inference-mode accept
+ *   cello_reject_connection      — inference-mode reject
+ *   cello_request_more_disclosure — inference-mode ask for more
+ *   cello_list_connections       — list active connections
+ *   cello_set_policy             — configure policy engine
+ *   cello_get_policy             — read current policy
+ *
+ * MCP-002 modifications:
+ *   cello_initiate_session: checks hasConnection() first
+ *   cello_status: gains registered, agent_id, connection_count, policy_mode, policy_review_mode
+ *
+ * PSEUDOCODE (Phase P — MCP-003):
+ *
+ * cello_register({ phone_stub }):
+ *   1. result = await client.register(phone_stub)
+ *   2. if 'error' in result: return { error: { reason: result.error } }
+ *   3. return { registered: true, agent_id, primary_pubkey, ml_dsa_pubkey }
+ *      SI-001: never include ml_dsa secret
+ *
+ * cello_request_connection({ target_pubkey, include_endorsements?, include_attestations? }):
+ *   1. Build a minimal ConnectionPackage (empty endorsements/attestations unless requested)
+ *   2. result = await client.cello_request_connection({ target_pubkey, package_cbor })
+ *   3. Map result to MCP response shape
+ *
+ * cello_respond_to_disclosure_request({ connection_request_id, ... }):
+ *   1. result = await client.cello_respond_to_disclosure_request({ connection_request_id, package_cbor })
+ *   2. Map result
+ *
+ * cello_await_connection_request({ timeout_ms? }):
+ *   1. result = await client.awaitConnectionRequest(timeout_ms ?? 30_000)
+ *   2. if timeout: return { type: 'timeout' }
+ *   3. Return { type: 'pending_review', connection_request_id, from_pubkey, report }
+ *      SI-003: report is ConnectionReport — no raw signatures, no full pubkeys
+ *
+ * cello_accept_connection({ connection_request_id }):
+ *   1. result = await client.acceptConnection(connection_request_id)
+ *   2. Map to { accepted: true, connection_id } or { error: { reason } }
+ *
+ * cello_reject_connection({ connection_request_id, reason? }):
+ *   1. result = await client.rejectConnection(connection_request_id, reason)
+ *   2. Map to { rejected: true } or { error: { reason } }
+ *
+ * cello_request_more_disclosure({ connection_request_id, requested_items }):
+ *   1. result = await client.requestMoreDisclosure(connection_request_id, requested_items)
+ *   2. Map to { request_sent: true } or { error: { reason } }
+ *
+ * cello_list_connections():
+ *   1. connections = client.listConnections()
+ *   2. Map each record to { connection_id, counterparty_pubkey, counterparty_primary_pubkey,
+ *      established_at, status: 'active' }
+ *
+ * cello_set_policy({ mode, review_mode, requirements? }):
+ *   1. policy = { mode, review_mode, requirements: requirements ?? [] }
+ *   2. client.setPolicy(policy)
+ *   3. return { policy_set: true, mode, review_mode, requirement_count }
+ *
+ * cello_get_policy():
+ *   1. policy = client.getPolicy()
+ *   2. return { mode, review_mode, requirements }
+ *
+ * Modified: cello_initiate_session({ target_pubkey }):
+ *   1. NEW: check client.hasConnection(target_pubkey)
+ *      if !connection → return { ok: false, reason: 'no_connection' }
+ *      (existing transport guard + directory signaling unchanged)
+ *
+ * Modified: cello_status():
+ *   + registered: bool
+ *   + agent_id: hex | null
+ *   + connection_count: number
+ *   + policy_mode: string
+ *   + policy_review_mode: string
+ *
+ * PSEUDOCODE (Phase P):
+ *
+ * State held by the MCP server instance:
+ *   startedAt: number = Date.now()
+ *   inboundSessionQueue: Uint8Array[]  — FIFO queue of inbound session_id bytes
+ *
+ * Server setup:
+ *   client.onSessionAssignment((sessionIdBytes) => {
+ *     inboundSessionQueue.push(sessionIdBytes)
+ *   })
+ *
+ * Helper: transportStarted():
+ *   return node.listenAddresses().length > 0
+ *
+ * Helper: directoryReachable():
+ *   // In M1, we determine directory reachability from whether we have active sessions
+ *   // with a directory_endpoint set. Best-effort check from session records.
+ *   return any session in client.listSessions() has a directory_endpoint with a peer_id
+ *
+ * Helper: toHex(bytes):
+ *   return Buffer.from(bytes).toString('hex')
+ *
+ * Helper: fromHex(str):
+ *   return Buffer.from(str, 'hex')
+ *
+ * ─── tool: cello_initiate_session({ target_pubkey }) ─────────────────────────────
+ * 1. Guard: if !transportStarted() → return transport_not_started error
+ * 2. SESSION-002 session_request flow:
+ *    a. Look up target_pubkey in client's sessions (M1 stub: directory signaling is
+ *       handled via receiveSessionAssignment. The session_request must be sent through
+ *       the directory signaling stream. In M1 this is driven externally by the test
+ *       harness calling receiveSessionAssignment on both clients. Here we emit the
+ *       request via the stored directory stream if available, then poll listSessions()
+ *       for the resulting session_id.)
+ *    b. Actually: The NODE-001 signaling flow is: client initiates a session_request
+ *       to the directory over the persistent signaling stream, the directory creates a
+ *       SessionAssignment and pushes it to both clients. In M1, the directory is a
+ *       separate process that receives the request. For the MCP tool surface:
+ *       - The client must have a way to send a session_request to the directory.
+ *       - CelloClientImpl already holds directoryStreams per session. But those are
+ *         post-assignment. The pre-session directory signaling stream is separate.
+ *    c. Per CONTEXT.md: session establishment — directory issues signed SessionAssignment.
+ *       The client sends session_request to directory's /cello/signaling/1.0.0 stream.
+ *    d. Implementation: initiate a directory signaling stream at the MCP server level
+ *       (separate from the per-session streams in CelloClientImpl). The MCP server
+ *       must know the directory endpoint. In M1 tests, the directory endpoint is
+ *       obtained from an existing session's record OR passed at construction time.
+ *
+ * NOTE: In M1, cello_initiate_session is driven by the test harness calling
+ * receiveSessionAssignment on both clients (the directory side is real in e2e tests).
+ * The MCP tool implements the client-side: send the session_request frame to the
+ * directory signaling stream and poll until session_assignment arrives.
+ *
+ * For the actual M1 implementation:
+ * 1. Connect to directory /cello/signaling/1.0.0 (using stored endpoint from existing session,
+ *    or a pre-configured directory multiaddr)
+ * 2. Auth challenge-response
+ * 3. Send { type: "session_request", target_pubkey: fromHex(target_pubkey) }
+ * 4. Poll listSessions() every 100ms until a new session with counterparty_pubkey == target_pubkey
+ *    appears, or timeout (10s)
+ * 5. Return session details from the new SessionRecord
+ *
+ * ─── tool: cello_await_session({ timeout_ms }) ────────────────────────────────────
+ * 1. deadline = Date.now() + timeout_ms
+ * 2. Poll every 20ms until deadline:
+ *    a. if inboundSessionQueue.length > 0:
+ *         sessionId = inboundSessionQueue.shift()
+ *         sessionIdHex = toHex(sessionId)
+ *         record = client.listSessions().find(s => toHex(s.session_id) === sessionIdHex)
+ *         if record: return { type: 'new_session', session_id: sessionIdHex,
+ *                             counterparty_pubkey: toHex(record.counterparty_pubkey),
+ *                             genesis_prev_root: toHex(record.genesis_prev_root) }
+ * 3. return { type: 'timeout' }
+ *
+ * ─── tool: cello_send({ session_id, content }) ────────────────────────────────────
+ * 1. Guard: transport_not_started
+ * 2. result = await client.sendMessage(session_id, TextEncoder.encode(content))
+ * 3. if result.ok:
+ *      // Retrieve leaf_hash from the session record's most recent leaf
+ *      record = client.listSessions().find(s => toHex(s.session_id) === session_id)
+ *      leafHash = computeLeafHash(record.local_tree_leaves[last])
+ *      return { delivered: true, leaf_hash: toHex(leafHash) }
+ *    else:
+ *      return { delivered: false, reason: result.reason }
+ *
+ * ─── tool: cello_receive_session({ session_id, timeout_ms }) — session-locked ────────
+ * 1. Guard: transport_not_started
+ * 2. deadline = Date.now() + timeout_ms
+ * 3. Poll every 20ms until deadline:
+ *    a. msg = client.receiveMessage(session_id)
+ *    b. if msg:
+ *         return { type: 'message', content: TextDecoder.decode(msg.content),
+ *                  sender_pubkey: toHex(msg.senderPubkey),
+ *                  sequence_number: msg.sequenceNumber,
+ *                  leaf_hash: toHex(msg.leafHash) }
+ * 4. return { type: 'timeout' }
+ *
+ * ─── tool: cello_receive({ timeout_ms }) — any-session default ───────────────────────
+ * 1. Guard: transport_not_started
+ * 2. result = await client.receiveMessageAsync(timeout_ms)
+ * 3. if timeout: return { type: 'timeout' }
+ * 4. return { type: 'message', session_id, content, sender_pubkey, sequence_number, leaf_hash }
+ *
+ * ─── tool: cello_close_session({ session_id }) ────────────────────────────────────
+ * 1. Guard: transport_not_started
+ * 2. result = await client.initiateSessionSeal(session_id)
+ *    if !result.ok: return { status: 'seal_rejected', sealed_root: null,
+ *                            close_timestamp: Date.now(), reason: result.reason, mmr_peak: null }
+ * 3. Poll listSessions() every 100ms for up to 30s:
+ *    a. record = sessions.find(s => toHex(s.session_id) === session_id)
+ *    b. if record.status === 'sealed':
+ *         return { status: 'sealed', sealed_root: toHex(record.sealed_root),
+ *                  close_timestamp: Date.now(), reason: null, mmr_peak: null }
+ *    c. if record.status === 'seal_rejected':
+ *         return { status: 'seal_rejected', sealed_root: null,
+ *                  close_timestamp: Date.now(), reason: 'directory_rejected', mmr_peak: null }
+ * 4. return { status: 'seal_deferred', sealed_root: null,
+ *             close_timestamp: Date.now(), reason: 'directory_unreachable', mmr_peak: null }
+ *
+ * ─── tool: cello_list_sessions() ──────────────────────────────────────────────────
+ * 1. records = client.listSessions()
+ * 2. For each record:
+ *      emit { session_id: hex, counterparty_pubkey: hex, counterparty_peer_id: string,
+ *             relay_endpoint: { peer_id: hex, multiaddrs }, status, last_seen_seq,
+ *             leaf_count: record.local_tree_leaves.length }
+ *
+ * ─── tool: cello_status() ─────────────────────────────────────────────────────────
+ * No transport_not_started guard (same as MCP-001).
+ * 1. ownPubkey = toHex(await keyProvider.getPublicKey())
+ * 2. activeSessions = client.listSessions().filter(s => s.status === 'active')
+ * 3. return {
+ *      transport_started: transportStarted(),
+ *      own_pubkey: ownPubkey,
+ *      listen_addresses: node.listenAddresses(),
+ *      connected_peer_count: node.getConnections().length,
+ *      uptime_seconds: Math.floor((Date.now() - startedAt) / 1000),
+ *      active_session_count: activeSessions.length,
+ *      directory_reachable: directoryReachable()
+ *    }
+ *
+ * ─── tool: cello_get_sealed_receipt({ session_id }) ──────────────────────────────
+ * SI-001: MUST NOT return for seal_rejected sessions.
+ * SI-002: MUST NOT return private key material.
+ * 1. record = client.listSessions().find(s => toHex(s.session_id) === session_id)
+ * 2. if !record: return { error: { reason: 'session_not_found', session_id } }
+ * 3. if record.status !== 'sealed': return { error: { reason: 'session_not_sealed', session_id } }
+ * 4. pubA = record (lower hex participant), pubB = higher hex participant (from genesis_prev_root ordering)
+ *    Actually: participants are [own_pubkey, counterparty_pubkey] sorted as stored. The spec says
+ *    [A_pubkey, B_pubkey] which is the order they appear in the session (A=initiator, B=responder).
+ *    Since we don't know which role we played, emit [own, counterparty] in canonical order.
+ * 5. return { session_id, sealed_root: hex, participants: [hex, hex],
+ *             close_timestamp: <from seal>, attestation_self: 'PENDING',
+ *             attestation_counterparty: 'PENDING',
+ *             leaf_count: record.local_tree_leaves.length,
+ *             directory_signature: hex }
+ *
+ * ─── tool: cello_get_inclusion_proof({ session_id, leaf_index }) ──────────────────
+ * SI-001: MUST NOT return proof for seal_rejected sessions.
+ * SI-003: returned sealed_root MUST equal inclusionProof reconstruction root.
+ * 1. record = client.listSessions().find(s => toHex(s.session_id) === session_id)
+ * 2. if !record || record.status !== 'sealed':
+ *      return { error: { reason: 'session_not_sealed' } }
+ * 3. treeSize = record.local_tree_leaves.length
+ * 4. if leaf_index < 0 || leaf_index >= treeSize:
+ *      return { error: { reason: 'leaf_index_out_of_range', leaf_index, tree_size: treeSize } }
+ * 5. Build tree from record.local_tree_leaves using buildMerkleTree(inputs: LeafInput[])
+ * 6. leafHash = tree.levelHashes[0][leaf_index]
+ * 7. proof = inclusionProof(tree, leaf_index)
+ * 8. root = merkleRoot(tree)
+ * 9. SI-003: assert root equals record.sealed_root (consistent snapshot)
+ *    NOTE: sealed_root from directory is based on the canonical leaf sequence. The local
+ *    tree should match if seal completed. If they don't match, return internal_error.
+ * 10. return { leaf_hash: hex, leaf_index, tree_size: treeSize, proof: [hex], sealed_root: hex }
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CelloClient } from "./types.js";
+import type { CelloNode } from "@cello-protocol/transport";
+import type { KeyProvider } from "@cello-protocol/crypto";
+import type { CheckpointStatusProvider } from "@cello-protocol/interfaces";
+import type { ClientBackup } from "./client-backup.js";
+export declare function createMcpSessionServer(node: CelloNode, client: CelloClient, keyProvider: KeyProvider, opts?: {
+    checkpointStatusProvider?: CheckpointStatusProvider;
+    clientBackup?: ClientBackup;
+}): McpServer;
+//# sourceMappingURL=mcp-server.d.ts.map

package/dist/mcp-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkQG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAKpE,OAAO,KAAK,EAAE,WAAW,EAA0B,MAAM,YAAY,CAAC;AACtE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAI1D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AAC3E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAuBvD,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,SAAS,EACf,MAAM,EAAE,WAAW,EACnB,WAAW,EAAE,WAAW,EACxB,IAAI,CAAC,EAAE;IAAE,wBAAwB,CAAC,EAAE,wBAAwB,CAAC;IAAC,YAAY,CAAC,EAAE,YAAY,CAAA;CAAE,GAC1F,SAAS,CA+jCX"}