@cello-protocol/daemon 0.0.227 → 0.0.228

package/dist/session-assignment-parser.js

@@ -0,0 +1,345 @@
+/**
+ * Session assignment parsing.
+ *
+ * Decodes a raw CBOR-decoded `assignment` object (from a directory
+ * `session_assignment` frame) into a typed SessionAssignment. **Shape-validates ONLY** — it checks
+ * that a signature is 64 bytes, never that it is correct. The logic lives here in the daemon
+ * because the daemon must NOT import the core/client stack.
+ *
+ * ⚠️ DOD-M15-CLAIM-COMMENTS-1 — THIS HEADER NAMED A CHECK THAT DID NOT EXIST. It read: *"the
+ * FROST/single signature is verified downstream by the transport/session layer against the
+ * directory's pinned key."* There was no such site anywhere in the tree —
+ * `buildSessionEstablishmentTbs` was called to SIGN and nowhere to verify — so every caller of this
+ * parser was relying on a verification the sentence invented.
+ *
+ * Verification now exists, in exactly one place: `assignment-verify.ts`, called by
+ * `outbound-sessions.ts` on the initiator path, which REFUSES the session when it fails. Two
+ * corrections to the old sentence while the record is open: it is not verified by "the
+ * transport/session layer", and it is not "the directory's pinned key" — the FROST signature is by
+ * the INITIATOR's own threshold group key, which is why the verifier compares `signer_pubkey`
+ * against this agent's persisted `primaryPubkey` before trusting it.
+ *
+ * **The responder verifies it too** (`verifyInboundAssignment`, `DOD-M15-RESPONDER-VERIFY-1`), and
+ * 038-KEYBIND changed what that is worth on FIRST CONTACT. The old sentence here said the responder
+ * *"can only prove the signature holds over the assignment's own recomputed contents — which catches
+ * tampering but cannot authenticate a directory"*, and that was accurate: with no pin it verified
+ * against `signer_pubkey`, a field of the frame under verification.
+ *
+ * The frame now carries `participant_a_key_binding` — a signature by the INITIATOR's own K_local
+ * naming their group key. The responder checks that FIRST and verifies the threshold signature under
+ * the key it proved, so a directory can no longer name a group key of its choosing. What first
+ * contact still cannot tell you is whether `participant_a` is who you think: the identity key itself
+ * is the out-of-band value, and no field on this frame can vouch for it.
+ */
+function toU8Safe(v) {
+    if (v instanceof Uint8Array)
+        return v;
+    if (Buffer.isBuffer(v))
+        return new Uint8Array(v);
+    return null;
+}
+function parseStringArray(v) {
+    if (!Array.isArray(v))
+        return null;
+    if (!v.every((x) => typeof x === "string"))
+        return null;
+    return v;
+}
+function parseParticipantInfo(raw, onTolerated) {
+    if (typeof raw !== "object" || raw === null)
+        return null;
+    const r = raw;
+    const pubkey = toU8Safe(r["pubkey"]);
+    if (!pubkey || pubkey.length !== 32)
+        return null;
+    /**
+     * `peer_id` IS TOLERATED TOO, and it is the WORSE of the two.
+     *
+     * Same three properties as `multiaddrs` below — unread (the only reads anywhere are the
+     * directory's own encoder), covered by no signature, and it refused the entire assignment. But
+     * the killing value is not a bug's output, it is a DEFAULT the directory writes on purpose:
+     * `directory-node.ts:2049` seeds `{ peer_id: "", multiaddrs: [] }` on auth, and `:3867` uses the
+     * same object when the peer-info map misses. `:4120` copies whichever it got into
+     * `participant_a/b`, and nothing gates it — the only announce requirement checks the INITIATOR,
+     * never the TARGET.
+     *
+     * So an agent whose peer-info announce is late or absent could not be talked to at all: the
+     * directory FROST-signs a valid assignment, both clients parse it, both refuse over an empty
+     * string neither one reads, and the operator is told the assignment was "missing or malformed"
+     * when it was neither.
+     */
+    if (r["peer_id"] !== undefined && typeof r["peer_id"] !== "string")
+        onTolerated?.("participant.peer_id");
+    const peerId = typeof r["peer_id"] === "string" ? r["peer_id"] : "";
+    /**
+     * `multiaddrs` IS TOLERATED, NOT VALIDATED — `DOD-M15-DEAD-WIRE-FIELD-1`.
+     *
+     * It has been permanently `[]` on every session assignment since the directory-facing node
+     * stopped listening. The directory stores it and SIGNS NOTHING over it — neither the session nor
+     * the relay TBS includes it — and the only read of a parsed participant takes `.pubkey`.
+     *
+     * Rejecting the WHOLE assignment when it was malformed therefore ended a conversation over a
+     * value that cannot affect anything and that no signature protects: a checked-then-ignored, and
+     * the refusing half is the one that costs. Absent or malformed now yields `[]`, which is what it
+     * always is in practice.
+     *
+     * ⚠️ NOT the same field on `parseEndpointInfo` below. Those multiaddrs belong to the RELAY and
+     * DIRECTORY endpoints and are DIALED — a malformed one is a session that cannot connect, worth
+     * refusing at the boundary rather than discovering at dial time. Identical name, adjacent
+     * function, one dead and one load-bearing.
+     *
+     * Removing the field from the wire is bilateral and rides with the other pending wire changes so
+     * the two repos move once; accepting its ABSENCE here is what makes this client already
+     * compatible when that lands.
+     */
+    if (r["multiaddrs"] !== undefined && parseStringArray(r["multiaddrs"]) === null) {
+        onTolerated?.("participant.multiaddrs");
+    }
+    const multiaddrs = parseStringArray(r["multiaddrs"]) ?? [];
+    return { pubkey, peer_id: peerId, multiaddrs };
+}
+function parseEndpointInfo(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return null;
+    const r = raw;
+    const peerId = typeof r["peer_id"] === "string" ? r["peer_id"] : null;
+    if (!peerId)
+        return null;
+    const multiaddrs = parseStringArray(r["multiaddrs"]);
+    if (!multiaddrs)
+        return null;
+    return { peer_id: peerId, multiaddrs };
+}
+/**
+ * Decode a raw CBOR-decoded object (frame["assignment"]) into a typed SessionAssignment.
+ * Returns null if any required field is missing or malformed.
+ */
+export function parseSessionAssignment(raw, 
+/**
+ * Called for each dead field that arrived PRESENT-BUT-MALFORMED. Optional so the parser keeps no
+ * logger dependency — it is a pure shape-validator, as its header says. Callers that have a
+ * logger (the inbound and outbound session paths) pass one; the rest are unaffected.
+ */
+onTolerated) {
+    const sessionId = toU8Safe(raw["session_id"]);
+    if (!sessionId || sessionId.length !== 16)
+        return null;
+    const dirPubkey = toU8Safe(raw["directory_pubkey"]);
+    if (!dirPubkey || dirPubkey.length !== 32)
+        return null;
+    const dirSig = toU8Safe(raw["directory_signature"]);
+    if (!dirSig || dirSig.length !== 64)
+        return null;
+    // The per-node directory signature over the relay TBS. Optional — absent on older assignments and on
+    // direct-mode sessions. When present it must be a valid 64-byte sig; a malformed value is dropped to
+    // undefined (the session then has no relay assignment to present, which surfaces as a relay-witness
+    // gap, not a hard failure).
+    const relayDirSigRaw = toU8Safe(raw["relay_directory_signature"]);
+    const relayDirSig = relayDirSigRaw && relayDirSigRaw.length === 64 ? relayDirSigRaw : undefined;
+    const tsRaw = raw["session_timestamp"];
+    const sessionTimestamp = typeof tsRaw === "number" ? tsRaw : typeof tsRaw === "bigint" ? Number(tsRaw) : null;
+    if (sessionTimestamp === null)
+        return null;
+    const participantA = parseParticipantInfo(raw["participant_a"], onTolerated);
+    if (!participantA)
+        return null;
+    const participantB = parseParticipantInfo(raw["participant_b"], onTolerated);
+    if (!participantB)
+        return null;
+    const relayEndpoint = parseEndpointInfo(raw["relay_endpoint"]);
+    if (!relayEndpoint)
+        return null;
+    const directoryEndpoint = parseEndpointInfo(raw["directory_endpoint"]);
+    if (!directoryEndpoint)
+        return null;
+    const sigType = typeof raw["signature_type"] === "string" ? raw["signature_type"] : "single";
+    // Session peer IDs + transport mode — undefined when absent (an older peer omits them).
+    const initiatorSessionPeerId = typeof raw["initiator_session_peer_id"] === "string" && raw["initiator_session_peer_id"] !== ""
+        ? raw["initiator_session_peer_id"]
+        : undefined;
+    const initiatorSessionAddrs = parseStringArray(raw["initiator_session_addrs"]) ?? undefined;
+    const counterpartySessionPeerId = typeof raw["counterparty_session_peer_id"] === "string" && raw["counterparty_session_peer_id"] !== ""
+        ? raw["counterparty_session_peer_id"]
+        : undefined;
+    const counterpartySessionAddrs = parseStringArray(raw["counterparty_session_addrs"]) ?? undefined;
+    const transportModeRaw = raw["transport_mode"];
+    const transportMode = transportModeRaw === "direct" ? "direct" : transportModeRaw === "relay" ? "relay" : undefined;
+    /**
+     * 017-TBS. These two are read DIFFERENTLY from the peer ids above, and the difference is the
+     * whole reason the verifier can reconstruct the right layout.
+     *
+     * A peer id of `""` means "the directory never learned this endpoint", so it becomes `undefined`
+     * and both sides drop to the short layout. These two are not like that: `high_stakes: false` and
+     * `prior_relay_id: ""` are ANSWERS — "not high stakes" and "this is a fresh session, no prior
+     * relay". Mapping either to `undefined` would silently take the verifier to the 10-field layout
+     * while the directory signed 12, and every fresh non-high-stakes session — the common case —
+     * would fail to verify.
+     *
+     * So the test is the TYPE, never truthiness: `typeof === "boolean"` admits `false`, and
+     * `typeof === "string"` admits `""`. `undefined` here means only one thing — the field was
+     * genuinely absent, i.e. a directory that predates this layout.
+     */
+    const highStakes = typeof raw["high_stakes"] === "boolean" ? raw["high_stakes"] : undefined;
+    const priorRelayId = typeof raw["prior_relay_id"] === "string" ? raw["prior_relay_id"] : undefined;
+    // 069-ORDERPROOF: read the same way and for the same reason — `""` is the ANSWER "this session
+    // has no relay", not an absence. Mapping it to `undefined` would take the verifier to the
+    // 12-field layout while the directory signed 13, and every direct session would fail to verify.
+    const relayId = typeof raw["relay_id"] === "string" ? raw["relay_id"] : undefined;
+    const common = {
+        session_id: sessionId,
+        participant_a: participantA,
+        participant_b: participantB,
+        relay_endpoint: relayEndpoint,
+        directory_endpoint: directoryEndpoint,
+        session_timestamp: sessionTimestamp,
+        directory_pubkey: dirPubkey,
+        directory_signature: dirSig,
+        relay_directory_signature: relayDirSig,
+        initiator_session_peer_id: initiatorSessionPeerId,
+        initiator_session_addrs: initiatorSessionAddrs,
+        counterparty_session_peer_id: counterpartySessionPeerId,
+        counterparty_session_addrs: counterpartySessionAddrs,
+        transport_mode: transportMode,
+        high_stakes: highStakes,
+        prior_relay_id: priorRelayId,
+        relay_id: relayId,
+    };
+    if (sigType === "frost") {
+        const signerPubkey = toU8Safe(raw["signer_pubkey"]);
+        if (!signerPubkey || signerPubkey.length !== 32)
+            return null;
+        /**
+         * 038-KEYBIND — the key bindings are SHAPE-CHECKED HERE AND JUDGED IN `assignment-verify.ts`.
+         *
+         * A wrong-length value yields `undefined`, which the verifiers treat exactly as absent: both
+         * take the REFUSE path, and refuse by name. That is the missing/malformed/mismatched collapse
+         * the milestone requires — there is no shape of these fields that reaches a session.
+         *
+         * They are NOT rejected here (a `return null`) on purpose. `null` from this parser means "the
+         * assignment was malformed", which tells an operator nothing about which protection stopped
+         * them. Carrying the absence one layer further is what lets the refusal say
+         * "this counterparty's directory did not supply the proof that its group key is theirs".
+         */
+        const bindA = toU8Safe(raw["participant_a_key_binding"]);
+        const bPrimary = toU8Safe(raw["participant_b_primary_pubkey"]);
+        const bindB = toU8Safe(raw["participant_b_key_binding"]);
+        return {
+            ...common,
+            signature_type: "frost",
+            signer_pubkey: signerPubkey,
+            participant_a_key_binding: bindA && bindA.length === 64 ? bindA : undefined,
+            participant_b_primary_pubkey: bPrimary && bPrimary.length === 32 ? bPrimary : undefined,
+            participant_b_key_binding: bindB && bindB.length === 64 ? bindB : undefined,
+        };
+    }
+    return { ...common, signature_type: "single" };
+}
+/**
+ * Decode a `discovery_lookup_result` frame. Shape-validates the 3-state answer; returns null on an
+ * unrecognized state (never fabricates one). A malformed/missing owning_node_ids defaults to [] — the
+ * negotiator treats online-with-no-owner as not-actionable (retry), never dials a fabricated node.
+ */
+export function parseDiscoveryLookupResult(frame) {
+    const state = frame["state"];
+    if (state !== "online" && state !== "offline" && state !== "unknown_agent")
+        return null;
+    const owningNodeIds = parseStringArray(frame["owning_node_ids"]) ?? [];
+    return { state, owningNodeIds };
+}
+/**
+ * Map a `discovery_lookup_error` frame's reason to a stable code. The directory returns this on a DB
+ * error during the lookup — a RETRYABLE condition, never a fabricated authoritative offline/unknown.
+ * Unknown reasons collapse to the same retryable "lookup_failed".
+ */
+export function discoveryLookupErrorReason(_frame) {
+    // Only one reason today; any discovery_lookup_error is the same retryable condition. Kept as a
+    // function (not a constant) so a future reason set slots in without touching call sites.
+    return "lookup_failed";
+}
+/**
+ * Map a raw `session_request_error` frame's reason to a stable negotiator reason code.
+ * Distinct cause → distinct code; an unknown reason collapses to directory_unreachable.
+ */
+export function sessionRequestErrorReason(frame) {
+    const reason = frame["reason"];
+    const known = new Set([
+        "target_offline",
+        "relay_unavailable",
+        "frost_signer_not_configured",
+        "directory_below_threshold",
+        "ceremony_timeout",
+        "ceremony_exhausted",
+        "ceremony_conflict",
+        "not_registered",
+        "peer_not_registered",
+        "no_connection",
+        "connection_id_required",
+        "session_request_missing_peer_id",
+        "agent_revoked", // the target (or initiator) agent is revoked
+        "agent_suspended", // the target/initiator is PAUSED (reversible suspend)
+        // The directory fails closed instead of FROST-signing an endpoint-less assignment — the target
+        // never accepted the session_offer. Distinct from target_offline: the target IS connected to the
+        // directory, it just cannot serve this session (e.g. its standing receiver has not come up).
+        // Omitting it here collapses the cause to `directory_unreachable`, blaming the DIRECTORY for a
+        // healthy directory and a COUNTERPARTY that declined — the wrong subsystem, which is what makes
+        // such bugs cost days.
+        "counterparty_did_not_accept",
+        // M16: the initiator or target is a broadcast channel, which never holds a session. Collapsed to
+        // `directory_unreachable`, a caller trying to reach a channel was sent to debug their network.
+        "channel_participant",
+        // M16: the directory could not check whether a side is a channel, and refused rather than broker
+        // unchecked. Its own reason, so a database fault is never reported as "that is a channel".
+        "channel_check_failed",
+    ]);
+    return typeof reason === "string" && known.has(reason) ? reason : "directory_unreachable";
+}
+/**
+ * The guidance returned with a `session_request_error`. Most reasons share one sentence; the M16
+ * channel refusals get their own, because "ensure the counterparty is registered and online" is
+ * the wrong advice for an identity that is online and simply never converses.
+ */
+export function sessionRequestErrorGuidance(reason) {
+    if (reason === "channel_participant") {
+        return "The directory refused the session request (channel_participant): one side is a broadcast channel. Channels publish and never hold sessions. To reach the operator behind a channel, open a session with the channel's admin agent instead.";
+    }
+    if (reason === "channel_check_failed") {
+        return "The directory refused the session request (channel_check_failed): it could not check whether either side is a broadcast channel, and does not broker a session it could not check. Retry; if it repeats, the directory node is failing to read its own records.";
+    }
+    return `The directory refused the session request (${reason}). Ensure the counterparty is registered and online.`;
+}
+// ─── The offer-moniker validation seams ──────────────────────────
+import { validateMoniker } from "@cello-protocol/protocol-types";
+/**
+ * The receiver's wire boundary, validated ONCE here so downstream code can never
+ * observe an invalid moniker. Absent ≠ invalid: an absent field is an older client
+ * (silent, rejected: false); a present-but-invalid value means the sender runs
+ * modified code (rejected: true — the caller logs `moniker.rejected`, never the raw
+ * value). Reject, never strip: the value is returned verbatim or null, never repaired.
+ */
+export function extractOfferedMoniker(raw) {
+    if (!("moniker" in raw) || raw["moniker"] === undefined) {
+        return { offeredMoniker: null, rejected: false };
+    }
+    const value = raw["moniker"];
+    if (typeof value !== "string") {
+        return { offeredMoniker: null, rejected: true, reason: "not_string" };
+    }
+    if (value.length < 1 || value.length > 64) {
+        return { offeredMoniker: null, rejected: true, reason: "length" };
+    }
+    const valid = validateMoniker(value);
+    return valid !== null
+        ? { offeredMoniker: valid, rejected: false }
+        : { offeredMoniker: null, rejected: true, reason: "charset" };
+}
+/**
+ * Defense-in-depth re-validation of the initiator's own outbound name. Returns
+ * undefined (field OMITTED from the wire, never an empty string) when there is no
+ * name or the stored value somehow fails validation.
+ */
+export function resolveOutboundMoniker(outboundName) {
+    if (outboundName === null)
+        return undefined;
+    return validateMoniker(outboundName) ?? undefined;
+}
+//# sourceMappingURL=session-assignment-parser.js.map

package/dist/session-assignment-parser.js.map

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

package/dist/session-category.d.ts

@@ -0,0 +1,19 @@
+import type { SessionStatus } from "./types.js";
+/**
+ * The operator-facing CATEGORY of a session, derived from its raw status + message count.
+ * The raw statuses (active / interrupted / sealed / seal_interrupted_pending) are an internal
+ * lifecycle detail; operators reason in three buckets:
+ *
+ *   - open    — live or resumable: an active session, OR an interrupted one that actually
+ *               exchanged messages (you can pick it back up).
+ *   - closed  — done: sealed (or sealing — seal_interrupted_pending).
+ *   - failed  — a session-initiation that never exchanged a message and got cut. A dead
+ *               handshake. These must NOT clutter `cello status`, and are only returned by
+ *               `get-sessions --failed` (or --all).
+ *
+ * This is the single source of truth for the status filter and the get-sessions flags, so the
+ * two never drift.
+ */
+export type SessionCategory = "open" | "closed" | "failed";
+export declare function classifySession(status: SessionStatus, messageCount: number): SessionCategory;
+//# sourceMappingURL=session-category.d.ts.map

package/dist/session-category.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-category.d.ts","sourceRoot":"","sources":["../src/session-category.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE3D,wBAAgB,eAAe,CAAC,MAAM,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,GAAG,eAAe,CAS5F"}

package/dist/session-category.js

@@ -0,0 +1,14 @@
+export function classifySession(status, messageCount) {
+    if (status === "sealed" || status === "seal_interrupted_pending")
+        return "closed";
+    // CC-5/F21: a force-abandoned / reaped half-open session is a dead handshake — it belongs in the
+    // "failed" bucket (out of `cello status`, visible only via --failed/--all), regardless of whether its
+    // own auto-"Dispatched." ack bumped message_count.
+    if (status === "abandoned")
+        return "failed";
+    if (status === "interrupted")
+        return messageCount > 0 ? "open" : "failed";
+    // "active"
+    return "open";
+}
+//# sourceMappingURL=session-category.js.map

package/dist/session-category.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-category.js","sourceRoot":"","sources":["../src/session-category.ts"],"names":[],"mappings":"AAmBA,MAAM,UAAU,eAAe,CAAC,MAAqB,EAAE,YAAoB;IACzE,IAAI,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,0BAA0B;QAAE,OAAO,QAAQ,CAAC;IAClF,iGAAiG;IACjG,sGAAsG;IACtG,mDAAmD;IACnD,IAAI,MAAM,KAAK,WAAW;QAAE,OAAO,QAAQ,CAAC;IAC5C,IAAI,MAAM,KAAK,aAAa;QAAE,OAAO,YAAY,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC;IAC1E,WAAW;IACX,OAAO,MAAM,CAAC;AAChB,CAAC"}