@cello-protocol/daemon 0.0.227 → 0.0.228

package/dist/content-park-client.js

@@ -0,0 +1,362 @@
+/**
+ * M7 MSG-001-3b — daemon-side content-park CLIENT (deposit + pull).
+ *
+ * The relay runs a store-and-forward "mailbox" so a message survives the recipient being
+ * OFFLINE: the sender DEPOSITS ciphertext keyed to the recipient's pubkey; when the
+ * recipient comes online it PULLS its parked entries. The relay holds CIPHERTEXT only
+ * (sealed to the recipient — INV-3); it is a hash custodian, not a data custodian.
+ *
+ * This is the daemon counterpart to `packages/relay/src/content-park.ts` (the relay handler).
+ * It speaks the same protocol (`/cello/content-park/1.0.0`, CBOR frames, length-prefixed) over
+ * a libp2p stream, exactly mirroring the dial/stream/framing of `session-relay-client.ts` (the
+ * hash-witness client) — only the protocol ID and the frames differ.
+ *
+ * Wire contract (relay is authoritative — packages/relay/src/content-park.ts):
+ *   deposit:  → content_park_deposit { recipient_pubkey, content_hash, session_id, ciphertext }
+ *             ← content_park_deposit_ack { content_hash, ok, reason? }
+ *   pull:     → content_park_pull_request { recipient_pubkey, content_hash? }
+ *             ← content_park_auth_challenge { nonce(32) }          (I1: prove recipient identity)
+ *             → content_park_auth_response { signature(64) }       Ed25519(buildContentParkAuthMsg)
+ *             ← content_park_pull_count { count }
+ *             ← count × content_park_pull_response { found, content_hash, session_id?, ciphertext? }
+ *
+ * Crypto: Ed25519 (RFC 8032). The pull auth binds the caller to the recipient identity key so a
+ * stranger cannot drain another recipient's mailbox (the recipient pubkey is public).
+ */
+import * as lp from "it-length-prefixed";
+import { decode } from "cbor-x";
+import { encodeCbor } from "@cello-protocol/protocol-types";
+import { CONTENT_PARK_PROTOCOL_ID, buildContentParkAuthMsg } from "@cello-protocol/protocol-types";
+import { extractErrorMessage } from "./error-message.js";
+const FRAME_TIMEOUT_MS = 8_000;
+function toU8(chunk) {
+    if (chunk instanceof Uint8Array)
+        return chunk;
+    const c = chunk;
+    if (typeof c?.subarray === "function")
+        return c.subarray();
+    return new Uint8Array(chunk);
+}
+function asBytes(v) {
+    if (v instanceof Uint8Array)
+        return v;
+    if (typeof Buffer !== "undefined" && Buffer.isBuffer(v))
+        return new Uint8Array(v);
+    return null;
+}
+/**
+ * DOD-M15-RELAYAUTH-1 review HIGH-3: the relay REFUSED to release parked content, as distinct from
+ * having none. Thrown rather than returned so it cannot be mistaken for an empty result — the whole
+ * defect was a refusal flattening into `[]`, which reads to an operator as "nothing was waiting".
+ */
+export class ContentParkRefusedError extends Error {
+    reason;
+    constructor(reason) {
+        super(`the relay refused to release parked content: ${reason}`);
+        this.name = "ContentParkRefusedError";
+        this.reason = reason;
+    }
+}
+/**
+ * DOD-M15-PARKCONN-1 — the content-park stream could not be opened, WITH the reason there was
+ * nothing to open it on.
+ *
+ * `#open` dials before it opens a stream, and it used to discard every dial failure in an empty
+ * `catch`. That catch was the only place the reason for a missing connection ever existed, so an
+ * operator messaging an offline counterparty was told `No open connection to peer 12D3Koo…` — that
+ * there was no connection, never why — and the same action parked or failed with nothing to tell
+ * the two apart.
+ *
+ * A real `Error` (so `instanceof Error` and `extractErrorMessage` both work on it — the transport
+ * throws plain object literals, which stringify to "[object Object]") carrying the transport's own
+ * `reason` under the same field name the literal used, so existing `err.reason` readers are
+ * unaffected.
+ */
+export class ContentParkUnreachableError extends Error {
+    reason;
+    relayPeerId;
+    dialFailures;
+    constructor(args) {
+        const dials = args.dialFailures.length > 0
+            ? ` Dials tried: ${args.dialFailures.map((f) => `${f.addr} → ${f.error}`).join("; ")}`
+            : " No dial failed, so the connection existed or was never attempted.";
+        super(`content park relay ${args.relayPeerId} is unreachable (${args.reason}): ${args.cause}.${dials}`);
+        this.name = "ContentParkUnreachableError";
+        this.reason = args.reason;
+        this.relayPeerId = args.relayPeerId;
+        this.dialFailures = args.dialFailures;
+    }
+}
+export class ContentParkClient {
+    #relayPeerId;
+    #relayAddrs;
+    #logger;
+    constructor(opts) {
+        this.#relayPeerId = opts.relayPeerId;
+        this.#relayAddrs = opts.relayAddrs;
+        this.#logger = opts.logger;
+    }
+    /**
+     * Deposit ciphertext into the recipient's relay mailbox (sender side). Deposit is OPEN by
+     * design — the blob is E2E-encrypted to the recipient, so an unauthenticated deposit cannot
+     * leak plaintext.
+     */
+    async deposit(node, args) {
+        const stream = await this.#open(node);
+        try {
+            const iter = this.#iter(stream);
+            stream.send(lp.encode.single(encodeCbor({
+                type: "content_park_deposit",
+                recipient_pubkey: args.recipientPubkey,
+                content_hash: args.contentHash,
+                session_id: args.sessionId,
+                ciphertext: args.ciphertext,
+            })));
+            const ack = await this.#read(iter);
+            if (!ack || ack["type"] !== "content_park_deposit_ack") {
+                return { ok: false, reason: "no_deposit_ack" };
+            }
+            const ok = ack["ok"] === true;
+            /**
+             * DOD-M15-RELAYABUSE-1 — **CARRY THE RELAY'S OWN ANSWER TO "WHEN?".**
+             *
+             * The relay computes exactly when a throttle clears and now puts `retry_after_ms` on the ack.
+             * Dropping it here would make it a value with no reader — the defect this milestone keeps
+             * finding — and it is the one number that decides whether a queued message waits sixty seconds
+             * or waits for an unrelated reconnect that may be minutes away.
+             */
+            const rawRetry = ack["retry_after_ms"];
+            const retryAfterMs = typeof rawRetry === "number" && Number.isFinite(rawRetry) && rawRetry > 0 ? rawRetry : undefined;
+            this.#logger.info("content.park.deposit.result", {
+                relayPeerId: this.#relayPeerId,
+                ok,
+                reason: typeof ack["reason"] === "string" ? ack["reason"] : undefined,
+                ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+            });
+            return {
+                ok,
+                reason: typeof ack["reason"] === "string" ? ack["reason"] : undefined,
+                ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+            };
+        }
+        finally {
+            await stream.close().catch(() => { });
+        }
+    }
+    /**
+     * Pull the recipient's parked entries (recipient side). Runs the relay's auth challenge:
+     * sign buildContentParkAuthMsg(nonce, recipientPubkey) with the recipient's K_local to prove
+     * ownership before the relay releases anything.
+     */
+    async pull(node, recipientPubkey, signer) {
+        const stream = await this.#open(node);
+        try {
+            const iter = this.#iter(stream);
+            stream.send(lp.encode.single(encodeCbor({ type: "content_park_pull_request", recipient_pubkey: recipientPubkey })));
+            // I1 auth challenge → response.
+            const challenge = await this.#read(iter);
+            if (!challenge || challenge["type"] !== "content_park_auth_challenge") {
+                this.#logger.warn("content.park.pull.failed", { relayPeerId: this.#relayPeerId, reason: "no_auth_challenge" });
+                return [];
+            }
+            const nonce = asBytes(challenge["nonce"]);
+            if (!nonce)
+                return [];
+            const signature = await signer.sign(buildContentParkAuthMsg(nonce, recipientPubkey));
+            stream.send(lp.encode.single(encodeCbor({ type: "content_park_auth_response", signature })));
+            // Count header, then N responses.
+            const countFrame = await this.#read(iter);
+            /**
+             * DOD-M15-RELAYAUTH-1 review HIGH-3 — **A REFUSAL MUST NOT READ AS AN EMPTY MAILBOX.**
+             *
+             * The relay refuses a pull from a key it has never seen named by a directory-signed
+             * assignment, and it names the cause: `content_park_pull_refused { reason }`. Without this
+             * branch that frame simply is not `content_park_pull_count`, so the operator was told
+             * `no_pull_count` — a wire-shape complaint about the RIGHT answer — and the caller got `[]`,
+             * which the recover flow reports as `pulled: 0`: *nothing was waiting for you*. The relay was
+             * honest and the client threw the reason away one layer up.
+             *
+             * This is reachable on the ordinary path, not just under attack: the relay's vouched set is
+             * in-process, so every relay restart empties it, and a client does not re-present its
+             * assignment on reconnect.
+             */
+            if (countFrame && countFrame["type"] === "content_park_pull_refused") {
+                const reason = typeof countFrame["reason"] === "string" ? countFrame["reason"] : "refused";
+                // Review L2: named `..._by_relay`, not `content.park.pull.refused` — that name is already
+                // emitted by the relay itself, and an operator grepping one aggregated log for it would get
+                // two events from opposite sides of a trust boundary under a single name.
+                this.#logger.warn("content.park.pull.refused_by_relay", {
+                    relayPeerId: this.#relayPeerId,
+                    reason,
+                    impact: "this relay refused to release parked content for this key — it is NOT an empty mailbox. " +
+                        "Content may still be waiting. If the reason is not_a_participant the relay has no record " +
+                        "of a session naming this agent (it restarts empty), and a new session on this relay re-vouches it.",
+                });
+                throw new ContentParkRefusedError(reason);
+            }
+            if (!countFrame || countFrame["type"] !== "content_park_pull_count") {
+                this.#logger.warn("content.park.pull.failed", { relayPeerId: this.#relayPeerId, reason: "no_pull_count" });
+                return [];
+            }
+            const count = typeof countFrame["count"] === "number" ? countFrame["count"] : 0;
+            const entries = [];
+            for (let i = 0; i < count; i++) {
+                const r = await this.#read(iter);
+                if (!r || r["type"] !== "content_park_pull_response")
+                    break;
+                if (r["found"] !== true)
+                    continue;
+                const contentHash = asBytes(r["content_hash"]);
+                const sessionId = asBytes(r["session_id"]);
+                const ciphertext = asBytes(r["ciphertext"]);
+                if (!contentHash || !ciphertext)
+                    continue;
+                entries.push({
+                    contentHashHex: Buffer.from(contentHash).toString("hex"),
+                    sessionIdHex: sessionId ? Buffer.from(sessionId).toString("hex") : "",
+                    ciphertext,
+                });
+            }
+            this.#logger.info("content.park.pull.result", { relayPeerId: this.#relayPeerId, count: entries.length });
+            return entries;
+        }
+        finally {
+            await stream.close().catch(() => { });
+        }
+    }
+    /**
+     * Confirm-delete one parked entry (recipient side). The relay is delete-on-CONFIRM, not
+     * delete-on-pull, so without this the mailbox never drains and every reconnect re-pulls the whole
+     * history. Mirrors pull's I1 auth (sign buildContentParkAuthMsg(nonce, recipientPubkey)). Called
+     * after a parked entry is durably ingested. Best-effort: a failed confirm leaves the entry (it will
+     * be re-pulled + deduped next time, and the relay TTL eventually evicts it) — never loses content.
+     */
+    async confirm(node, recipientPubkey, contentHash, signer) {
+        const stream = await this.#open(node);
+        try {
+            const iter = this.#iter(stream);
+            stream.send(lp.encode.single(encodeCbor({ type: "content_park_confirm", recipient_pubkey: recipientPubkey, content_hash: contentHash })));
+            const challenge = await this.#read(iter);
+            if (!challenge || challenge["type"] !== "content_park_auth_challenge") {
+                this.#logger.warn("content.park.confirm.failed", { relayPeerId: this.#relayPeerId, reason: "no_auth_challenge" });
+                return false;
+            }
+            const nonce = asBytes(challenge["nonce"]);
+            if (!nonce)
+                return false;
+            const signature = await signer.sign(buildContentParkAuthMsg(nonce, recipientPubkey));
+            stream.send(lp.encode.single(encodeCbor({ type: "content_park_auth_response", signature })));
+            const ack = await this.#read(iter);
+            const ok = !!ack && ack["type"] === "content_park_confirm_ack" && ack["ok"] === true;
+            if (!ok) {
+                /**
+                 * Review M3 — the same error substitution HIGH-3 fixed on the pull path, left standing one
+                 * function above in this same file.
+                 *
+                 * A refused confirm is not a missing ack. The relay answers with a perfectly well-formed
+                 * `content_park_confirm_ack { ok: false, reason }`, and reporting `no_confirm_ack` is a
+                 * complaint about the wire shape of the RIGHT answer — it sends the operator to look at the
+                 * transport when the relay has already said exactly what is wrong.
+                 *
+                 * What it costs: confirm is delete-on-pickup. If it is refused, the entry is never deleted,
+                 * so the recipient is re-notified about a message it has already read, every time it
+                 * reconnects, forever — while the log blames the connection.
+                 */
+                const reason = typeof ack?.["reason"] === "string"
+                    ? ack["reason"]
+                    : ack
+                        ? "unexpected_frame"
+                        : "no_confirm_ack";
+                this.#logger.warn("content.park.confirm.failed", {
+                    relayPeerId: this.#relayPeerId,
+                    reason,
+                    impact: "pickup was not confirmed, so the relay keeps the entry and will keep announcing it as " +
+                        "unread on every reconnect. If the reason is not_a_participant this relay has no record " +
+                        "of a session naming this agent; a new session on it re-vouches the key.",
+                });
+            }
+            return ok;
+        }
+        finally {
+            await stream.close().catch(() => { });
+        }
+    }
+    /**
+     * Dial the relay (best-effort per addr) and open a content-park stream.
+     *
+     * DOD-M15-PARKCONN-1 — **A DIAL FAILURE IS A NON-EVENT UNTIL THE STREAM ALSO FAILS, AND THEN IT
+     * IS THE ONLY EVIDENCE THERE IS.**
+     *
+     * The loop stays best-effort on purpose: the peerstore may already hold a connection, so a dial
+     * that fails while `newStream` succeeds anyway explains nothing and must stay silent. What used to
+     * happen as well is that the dial errors were discarded in ALL cases, including the one where
+     * `newStream` then reported `no_connection` — and the throw site's own comment calls that "the one
+     * condition a dial fixes". A dial had run; its verdict had been deleted by this catch.
+     *
+     * Collected here and surfaced only on the failing path, which splits the two causes an operator
+     * otherwise cannot tell apart: every address was unusable, or a dial succeeded and the connection
+     * was gone again a moment later.
+     */
+    async #open(node) {
+        const dialFailures = [];
+        for (const addr of this.#relayAddrs) {
+            try {
+                await node.dial(addr);
+                break;
+            }
+            catch (err) {
+                // extractErrorMessage, NOT String(err): the transport rejects with plain object literals.
+                dialFailures.push({ addr, error: extractErrorMessage(err) });
+            }
+        }
+        try {
+            return await node.newStream(this.#relayPeerId, CONTENT_PARK_PROTOCOL_ID);
+        }
+        catch (err) {
+            // The transport's own reason (`no_connection`, `node_stopped`, `invalid_peer_id`, …) survives
+            // to the caller — Invariant 3: a downstream handler must not overwrite it with a generic one.
+            const reason = err !== null && typeof err === "object" && typeof err.reason === "string"
+                ? err.reason
+                : "stream_open_failed";
+            // The loop `break`s on the first success, so fewer failures than addresses means one worked.
+            const dialOutcome = this.#relayAddrs.length === 0
+                ? "no_address_configured"
+                : dialFailures.length < this.#relayAddrs.length
+                    ? "dialed_then_lost"
+                    : "all_addresses_failed";
+            this.#logger.warn("content.park.open.failed", {
+                relayPeerId: this.#relayPeerId,
+                reason,
+                dialOutcome,
+                addrsTried: this.#relayAddrs.length,
+                dialFailures,
+                error: extractErrorMessage(err),
+                impact: dialOutcome === "all_addresses_failed"
+                    ? "every relay address failed to dial, so there was no connection for the stream to use — the dial errors above are the cause, not the missing connection"
+                    : dialOutcome === "dialed_then_lost"
+                        // Review LOW-7: state the FACT, not a prescription. "re-dialling is not the remedy"
+                        // generalised from one sample, and a connection lost right after a successful dial is
+                        // often exactly a re-dial case.
+                        ? "a dial SUCCEEDED and the connection was gone by the time the stream was opened — the loss is AFTER the dial, so the question is what closed it, not whether the relay is reachable"
+                        : "no relay address was configured for this content-park client, so no dial was attempted at all",
+            });
+            throw new ContentParkUnreachableError({
+                reason,
+                relayPeerId: this.#relayPeerId,
+                dialFailures,
+                cause: extractErrorMessage(err),
+            });
+        }
+    }
+    #iter(stream) {
+        return lp.decode(stream)[Symbol.asyncIterator]();
+    }
+    async #read(iter) {
+        const timeout = new Promise((_, reject) => setTimeout(() => reject(new Error("content_park_frame_timeout")), FRAME_TIMEOUT_MS));
+        const res = (await Promise.race([iter.next(), timeout]));
+        if (res.done || res.value === undefined)
+            return null;
+        return decode(toU8(res.value));
+    }
+}
+//# sourceMappingURL=content-park-client.js.map

package/dist/content-park-client.js.map

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

package/dist/content-park.d.ts

@@ -0,0 +1,52 @@
+import type { IpcHandler } from "./ipc-server.js";
+import type { SessionNodeManager } from "./session-node-manager.js";
+import type { AgentInfo, Logger } from "./types.js";
+import type { KeyProvider } from "@cello-protocol/crypto";
+import type { SecurityGatewayClient } from "@cello-protocol/gateway";
+import { ContentParkClient } from "./content-park-client.js";
+export interface ContentParkDeps {
+    logger: Logger;
+    sessionNodeManager: SessionNodeManager;
+    agents: AgentInfo[];
+    getKeyProvider: (agentName: string) => KeyProvider | undefined;
+    /**
+     * M12-P17: the annex is the ONE durable store holding counterparty content that never passed the
+     * inbound screen — `ingestReceivedContent` refuses a committed session before it reaches that
+     * seam. Screening at WRITE makes every future reader safe, rather than leaving a guidance string
+     * as the only thing between a stale instruction and an agent that acts on it.
+     */
+    securityGateway: SecurityGatewayClient;
+    /**
+     * M12-P17: seam for tests. Production leaves it undefined and gets the real client. Injecting it
+     * is what makes the recover path's screening branches reachable — one of them DELETES the relay
+     * copy, and an untested delete path is where this milestone's defects have consistently lived.
+     */
+    makeContentParkClient?: (opts: {
+        relayPeerId: string;
+        relayAddrs: string[];
+        logger: Logger;
+    }) => ContentParkClient;
+}
+export declare function createContentPark(deps: ContentParkDeps): {
+    autoRecoverForAgent: (agentName: string, trigger?: string) => Promise<void>;
+    registerHandlers: (handlers: Map<string, IpcHandler>) => void;
+    recoverParkedFromRelay: (recipientAgent: {
+        name: string;
+        pubkey?: string;
+    }, relayPeerId: string, relayAddrs: string[]) => Promise<{
+        ok: true;
+        recovered: number;
+        pulled: number;
+        refused: number;
+        refusals: Array<{
+            contentHash: string;
+            sessionId: string;
+            reason: string;
+        }>;
+    } | {
+        ok: false;
+        reason: string;
+        guidance?: string;
+    }>;
+};
+//# sourceMappingURL=content-park.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"content-park.d.ts","sourceRoot":"","sources":["../src/content-park.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AACrE,OAAO,EAAE,iBAAiB,EAAwD,MAAM,0BAA0B,CAAC;AAenH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB,EAAE,kBAAkB,CAAC;IACvC,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,cAAc,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,WAAW,GAAG,SAAS,CAAC;IAC/D;;;;;OAKG;IACH,eAAe,EAAE,qBAAqB,CAAC;IACvC;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,EAAE,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,iBAAiB,CAAC;CACpH;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,eAAe;qCAg4BP,MAAM,uBAA4B,OAAO,CAAC,IAAI,CAAC;iCAkEzD,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,KAAG,IAAI;6CAtxBhD;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,eACpC,MAAM,cACP,MAAM,EAAE,KACnB,OAAO,CACN;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,KAAK,CAAC;YAAE,WAAW,EAAE,MAAM,CAAC;YAAC,SAAS,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE,GAG7I;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CACnD;EA8nCF"}