@cello-protocol/daemon 0.0.227 → 0.0.229

package/dist/session-ephemerals.d.ts

@@ -0,0 +1,279 @@
+/**
+ * CELLO Daemon — THE PER-SESSION EPHEMERAL KEY AND THE CONTENT KEY IT AGREES
+ *
+ * Split out of `session-node-manager.ts` by 037-SESSIONCORE. Each side mints a throwaway keypair for
+ * the session, announces the public half, and the two halves agree the key that encrypts content at
+ * the application layer — so the bytes on the wire are not readable by anything between them, relay
+ * included.
+ *
+ * Moved verbatim, comments included.
+ *
+ * ⚠️ THE SECRET IS DESTROYED EXPLICITLY, NOT LEFT TO THE GARBAGE COLLECTOR. `destroySessionEphemeral`
+ * zeroes the bytes; dropping the reference would leave them in the heap for as long as the process
+ * lives, which is the difference between a throwaway key and one an attacker can find in a core
+ * dump. Every PER-SESSION teardown goes through `destroySessionEphemeralFor`; shutdown goes through
+ * `destroyAll`, which does the same zeroing for every live session at once rather than one at a
+ * time. Two entry points, one guarantee — said precisely because "every path goes through one
+ * method" was the earlier wording and it was not true of shutdown.
+ */
+import type { Logger } from "./types.js";
+import type { ActiveSessionEntry } from "./session-node-types.js";
+import { type SessionEphemeral, type KeyProvider } from "@cello-protocol/crypto";
+import { type ContentEncryptionReason } from "./content-encryption-status.js";
+/** What the ephemeral key agreement needs from the manager. */
+export interface SessionEphemeralContext {
+    readonly logger: Logger;
+    sessionKey(agentName: string, sessionId: string): string;
+    activeEntry(key: string): ActiveSessionEntry | undefined;
+    /**
+     * ⚠️ A FUNCTION, NOT A CAPTURED VALUE. The daemon injects the per-agent key providers AFTER the
+     * manager is constructed (`setKeyProviderResolver`), so a resolver snapshotted at wiring time is
+     * null for the life of the process — and the failure is silent in the worst way: signing simply
+     * does not happen, the exchange never completes, and the session falls back to unencrypted.
+     */
+    keyProvider(agentName: string): KeyProvider | undefined;
+    /**
+     * ⚠️ THE REASON TYPE IS WIDER THAN `ContentEncryptionReason` ON PURPOSE. The freeze is reached
+     * from the ephemeral AUTH refusals too, and narrowing here would have forced a cast at the call
+     * site — which is how a reason ends up reported as a neighbouring one it is not.
+     */
+    freezeSessionForKeyRefusal(agentName: string, sessionId: string, reason: string, correlationId?: string): Promise<void>;
+}
+export declare class SessionEphemerals {
+    #private;
+    constructor(ctx: SessionEphemeralContext);
+    /**
+     * DOD-M15-FRAME-1 — a proven identity failure ends the session, and says so as an OBSERVATION.
+     *
+     * SESSION-ENDING, NOT PER-MESSAGE. One frame that fails to verify against the expected
+     * counterparty is not a bad message to drop while hoping the next is better — it is evidence
+     * about the CONNECTION. Dropping the frame and continuing leaves the same peer able to try again
+     * with a frame that omits the proof entirely.
+     *
+     * THE WORDING IS NOT A VERDICT, and that is deliberate rather than squeamish. The identical
+     * signal comes from a real impersonation attempt and from our own infrastructure mishandling a
+     * fallback — a relay bug, a bad deploy, an uncovered edge in the direct-connection failover. The
+     * daemon cannot tell those apart from this signal, so it must not pretend to. This mirrors the
+     * account-recovery pattern already in the codebase, which anchors a compromise window to logged
+     * events and accepts that some evidence cannot separate misconduct from an innocent cause.
+     *
+     * IT MUST NEVER FEED A TRUST SIGNAL. An automatic reputation consequence driven by a signal this
+     * ambiguous would let a hostile peer — or a bad deploy of ours — manufacture a mark against an
+     * innocent counterparty. Recorded here because the absence of that wiring is a decision, not an
+     * omission, and the next person to reach for it should find this comment first.
+     *
+     * The accusatory half stays local for the same reason. Freezing what THIS daemon trusts is always
+     * safe unilaterally; asserting on the record that a counterparty misbehaved needs corroboration
+     * from a party the accusing client does not control, which is `DOD-M15-CORROBORATE-1` (the relay
+     * holds the sender's signed hash independently and never routes it through the receiver).
+     */
+    /**
+     * DOD-M15-SEALWIRE-1 bullet 6 (part A) — THE SALT AGREEMENT, the I/O half.
+     *
+     * The decisions live in `session-salt-agreement.ts` as a pure function; everything here is the
+     * three things that function cannot do: read and write the durable row, put a frame on the wire,
+     * and stop a session.
+     *
+     * ─── Where a contribution may travel, and it is the one rule that cannot be fixed later ───────
+     *
+     * `/cello/content/1.0.0` ONLY. It rides circuit-relay-v2 carrying its own Noise session, so a
+     * relay forwarding it sees ciphertext. It must never be added to `session_offer` /
+     * `session_offer_accept` or anything a DIRECTORY brokers — and that is the trap, because the only
+     * round trip at session open today runs on the directory's signaling stream, which makes it the
+     * obvious place to put one. A session that shipped it there could not be repaired: the relay
+     * would already hold the salt and every hash it protects.
+     */
+    /**
+     * MINT THIS SESSION'S THROWAWAY KEYPAIR — once, at the moment the session becomes active.
+     *
+     * Idempotent on purpose. Three paths make a session active (open, hand-off from the standing
+     * receiver, revive) and a reconnect can re-enter them; minting a second keypair mid-session would
+     * leave the two sides deriving against a moving value, and the symptom — a session that reconnects
+     * and still cannot agree — reads as a network fault rather than as a bug here. `#saltContributionFor`
+     * mints once for exactly the same reason.
+     *
+     * A REVIVED session is not an exception, and this guard is why it took a fix to make that true.
+     * Revival requires status `interrupted`, and the producer of `interrupted` drops the entry without
+     * evicting — so while the secret outlived that path, this guard found it still present and
+     * silently kept a key that had been resident for hours, on the one path where re-keying was
+     * explicitly decided. The interrupt path now destroys it, so the map really is empty by the time
+     * a revival reaches here and it mints fresh (Decisions Carried #5).
+     */
+    mintSessionEphemeral(agentName: string, sessionId: string, correlationId?: string): void;
+    /**
+     * DESTROY THIS SESSION'S THROWAWAY SECRET — 006-CRYPTO, and this is what forward secrecy IS.
+     *
+     * ⚠️ CALLED FROM EVERY SITE THAT DROPS THE `#activeNodes` ENTRY, not from `#evictSessionCaches`,
+     * and review pass 2 finding 2 is why. The first version rode the evict, which sounded right and
+     * was wrong on the path an interrupted session actually takes:
+     *
+     *   `markInterruptedWithDetails` drops the entry and DELIBERATELY does not evict — the received
+     *   plaintext has to stay drainable and the TTF park timers have to stay armed. So the secret
+     *   survived. Then, when that session later sealed, `destroySessionNode` returned at its
+     *   `if (!entry) return` — the entry was already gone — and never reached the evict either. The
+     *   receipt landed, the session was over, and the secret stayed resident until the process exited.
+     *
+     * A relay blip is the ORDINARY way a session ends badly, so that was the common path, not a corner.
+     * The evict's reasons for keeping the other caches are real and do not transfer: buffered plaintext
+     * must stay readable, and a secret nothing reads must not stay alive.
+     *
+     * Zero THEN drop. Dropping alone leaves the bytes wherever the collector last moved them;
+     * `destroySessionEphemeral` overwrites the one copy this process controls.
+     */
+    destroySessionEphemeralFor(agentName: string, sessionId: string, correlationId?: string): void;
+    /**
+     * AN INBOUND SIGNED EPHEMERAL — verify, THEN derive. Never the other way round.
+     *
+     * 🚨 A FAILED VERIFICATION IS A SECURITY EVENT AND IT STOPS THE SESSION. It is not a degradation
+     * to unencrypted, and the difference is the whole unit: an unsigned or wrongly-signed key is what
+     * a relay substituting its own looks like, and carrying on unencrypted would hand that relay
+     * exactly the plaintext it was reaching for. Missing, malformed and mismatched take this same
+     * path — a check that is lenient about a missing proof is a check an attacker skips.
+     *
+     * Contrast with a peer that says NOTHING at all: that is an old build, it is not evidence of
+     * anything about them, and it is recorded as `PEER_SILENT` — which still blocks sending, because
+     * there is no unencrypted path to fall back to.
+     */
+    handleEphemeralFrame(agentName: string, sessionId: string, frame: {
+        ephemeralPublic?: Uint8Array;
+        signature?: Uint8Array;
+    }, correlationId?: string): Promise<void>;
+    /**
+     * The agreed content key for a session, or `null` with the reason there is none.
+     *
+     * ONE place decides this, so the send path, the receive path and the status surface cannot
+     * disagree about whether a session is encrypted — the failure `wire-content-hash.ts` already
+     * records for the hash, where the expression was written out at five call sites and the two added
+     * last got it wrong.
+     */
+    contentEncryptionState(agentName: string, sessionId: string): {
+        key: Uint8Array;
+        reason?: undefined;
+    } | {
+        key: null;
+        reason: ContentEncryptionReason;
+    };
+    noteContentEncryptionReason(agentName: string, sessionId: string, reason: ContentEncryptionReason): void;
+    /**
+     * ANNOUNCE THIS SIDE'S SIGNED EPHEMERAL — `DOD-M15-EPHEMERAL-AUTH-1`.
+     *
+     * 🚨 ON THE PEER-TO-PEER CONTENT STREAM ONLY, exactly like the salt contribution and for the same
+     * unrepairable reason: it rides circuit-relay-v2 carrying its own Noise session, so a forwarding
+     * relay sees ciphertext. It must NEVER be added to `session_offer` / `session_offer_accept` or
+     * anything a DIRECTORY brokers — and that is the trap, because the only round trip at session open
+     * is the directory's signaling stream.
+     *
+     * Fire-and-forget on the connect handler, like the salt: a failed announcement must not turn a
+     * peer-connect handler into a rejected promise, and we re-announce on the next connect.
+     */
+    /**
+     * `attempt` is WHICH RETRY THIS IS, and it is a parameter because the catch below is the only
+     * place that can advance it. It was hardcoded to 1 at the retry call site, which made
+     * `SESSION_KEY_ANNOUNCE_RETRIES` unreachable: every failure re-entered the chain at 1, so the
+     * bound was never tested and `session.key.announce.gave_up` was never once logged in production.
+     * Measured 2026-09-08 on session `0646b474`: 49,137 failures, ~17/second, still running eleven
+     * hours after the session went quiet. Do not reintroduce a literal here.
+     */
+    sendEphemeralFrame(agentName: string, sessionId: string, correlationId?: string, attempt?: number): Promise<void>;
+    /**
+     * Re-announce this side's ephemeral after a failed attempt — review F5.
+     *
+     * Backs off, and gives up rather than looping: a peer that is simply gone must not have a timer
+     * chasing it for the life of the process.
+     */
+    retryEphemeralAnnounce(agentName: string, sessionId: string, correlationId: string | undefined, attempt: number): void;
+    /**
+     * Our throwaway keypair for a session, WITHOUT minting one — the read-only counterpart.
+     *
+     * `null` means the session is not active here. It never means "mint one now": minting outside
+     * `#mintSessionEphemeral` is how a second keypair appears mid-session.
+     */
+    sessionEphemeralFor(agentName: string, sessionId: string): SessionEphemeral | null;
+    /**
+     * Test seams: re-enter the mint path, and read back the PUBLIC half — 006-CRYPTO.
+     *
+     * `#mintSessionEphemeral` is idempotent because a reconnect can re-enter an activation path, and a
+     * second keypair mid-session would leave the two sides deriving against a moving value. Proving
+     * that needs the path called TWICE, and the alternative — driving a real reconnect — drags in node
+     * rebuild and relay reconnection, none of which the property is about. Same justification as
+     * `forgetSaltContributionForTest` above.
+     *
+     * It calls the REAL private method, so a test cannot pass against a decision production does not
+     * make. The reader returns the public half ONLY: a seam that could hand out the secret is a way
+     * for the secret to leave this object, which is the one thing the whole unit is about.
+     */
+    mintSessionEphemeralForTest(agentName: string, sessionId: string): void;
+    sessionEphemeralPublicForTest(agentName: string, sessionId: string): Uint8Array | null;
+    /**
+     * Test seam: INSTALL a keypair the caller already holds — the only way to prove ZEROING.
+     *
+     * Presence is easy to assert and is not the property. `destroySessionEphemeral` overwrites the
+     * buffer before the entry is dropped, and a mutant that drops without overwriting leaves the
+     * secret wherever the collector last moved it while passing every presence check — which is
+     * exactly what happened: the shutdown zeroing shipped with a surviving mutant, and the transport
+     * seeds four lines above it have the same untested gap today.
+     *
+     * The direction matters. Nothing here HANDS OUT a secret — the test supplies an object it already
+     * owns and then inspects its own reference. A reader that returned the live keypair would be a
+     * path for the secret to leave this object, which is the one thing this unit exists to prevent.
+     */
+    setSessionEphemeralForTest(agentName: string, sessionId: string, ephemeral: SessionEphemeral): void;
+    /**
+     * Test seam: put a session into the state a COMPLETED exchange leaves it in — 007-CRYPTO.
+     *
+     * A live send now requires an agreed key, because there is no plaintext path to fall back to. In
+     * production the exchange completes on connect, before any send. A fixture with no real peer never
+     * completes it, so without this every content test in the repo would be exercising the refusal
+     * path instead of the thing it was written for.
+     *
+     * ⚠️ IT SHORT-CIRCUITS HOW THE KEY GOT THERE, NEVER WHAT THE KEY IS FOR. The state it produces —
+     * a session holding an agreed content key — is exactly the production state, which is what makes
+     * it legitimate; `setSaltContributionForTest` exists for the same reason. Tests of the EXCHANGE
+     * itself drive the real signed frames and must not use this.
+     */
+    setSessionContentKeyForTest(agentName: string, sessionId: string, key: Uint8Array): void;
+    /**
+     * Test seam: drop the agreed key while leaving the session up — the state before an exchange
+     * completes, and after a teardown evicts one. Its mirror above is what a completed exchange
+     * leaves; both are needed, or a status field stuck in one position passes either test alone.
+     */
+    forgetSessionContentKeyForTest(agentName: string, sessionId: string): void;
+    /**
+     * Test seam: produce THIS side's signed ephemeral, using the manager's own identity resolver.
+     *
+     * For harnesses whose connectivity is one-directional — one side dials, so only one announce ever
+     * lands. Carrying the other side's half across with a REAL signature is what completes the
+     * exchange, and it beats seeding a key: a seeded key has no peer half recorded against it, so the
+     * first genuine announce replaces it and the two ends drift apart (which is correct behaviour —
+     * see the re-key guard — and exactly what made seeding fragile here).
+     *
+     * It signs with the same provider production signs with, so a test cannot pass against a signature
+     * production would have refused.
+     */
+    signOwnEphemeralForTest(agentName: string, sessionId: string): Promise<{
+        ephemeralPublic: Uint8Array;
+        signature: Uint8Array;
+    } | null>;
+    /**
+     * Test seam: deliver a peer's signed ephemeral, exactly as the content-stream decoder does.
+     *
+     * For harnesses whose connectivity is one-directional — one side dials, so only one announce ever
+     * lands — this is what completes the exchange instead of stuffing a key in. It runs the REAL
+     * verification and the REAL derivation, so a test cannot pass against a signature production would
+     * have refused.
+     */
+    handleEphemeralFrameForTest(agentName: string, sessionId: string, frame: {
+        ephemeralPublic?: Uint8Array;
+        signature?: Uint8Array;
+    }, correlationId?: string): Promise<void>;
+    /**
+     * Zero and drop EVERY session's ephemeral secret. Called on shutdown.
+     *
+     * ⚠️ THE ZEROING IS THE POINT, not the map clear. Shutdown marks rows `interrupted` by direct SQL,
+     * so no per-session teardown fires for them — and this process is known to linger (a `cello
+     * logout` has been seen still alive 30+ seconds later). Without this, every live session's key
+     * survives the shutdown in memory for as long as the process does.
+     */
+    destroyAll(): void;
+}
+//# sourceMappingURL=session-ephemerals.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session-ephemerals.d.ts","sourceRoot":"","sources":["../src/session-ephemerals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EAML,KAAK,gBAAgB,EACrB,KAAK,WAAW,EACjB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EAGL,KAAK,uBAAuB,EAC7B,MAAM,gCAAgC,CAAC;AAQxC,+DAA+D;AAC/D,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IACzD,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAAC;IACzD;;;;;OAKG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;IACxD;;;;OAIG;IACH,0BAA0B,CACxB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED,qBAAa,iBAAiB;;gBAGhB,GAAG,EAAE,uBAAuB;IAmDxC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH;;;;;;;;;;;;;;;OAeG;IACH;;;;;;;;;;;;;;;OAeG;IACH,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI;IAWxF;;;;;;;;;;;;;;;;;;;OAmBG;IACH,0BAA0B,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI;IAiB9F;;;;;;;;;;;;OAYG;IACG,oBAAoB,CACxB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE;QAAE,eAAe,CAAC,EAAE,UAAU,CAAC;QAAC,SAAS,CAAC,EAAE,UAAU,CAAA;KAAE,EAC/D,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC;IAqHhB;;;;;;;OAOG;IACH,sBAAsB,CACpB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB;QAAE,GAAG,EAAE,UAAU,CAAC;QAAC,MAAM,CAAC,EAAE,SAAS,CAAA;KAAE,GAAG;QAAE,GAAG,EAAE,IAAI,CAAC;QAAC,MAAM,EAAE,uBAAuB,CAAA;KAAE;IAQ3F,2BAA2B,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,uBAAuB,GAAG,IAAI;IAOxG;;;;;;;;;;;OAWG;IACH;;;;;;;OAOG;IACG,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,EAAE,OAAO,SAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IA0FlH;;;;;OAKG;IACH,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAgCtH;;;;;OAKG;IACH,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI;IAGlF;;;;;;;;;;;;OAYG;IACH,2BAA2B,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAGvE,6BAA6B,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAItF;;;;;;;;;;;;OAYG;IACH,0BAA0B,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,gBAAgB,GAAG,IAAI;IAGnG;;;;;;;;;;;;OAYG;IACH,2BAA2B,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,GAAG,IAAI;IAIxF;;;;OAIG;IACH,8BAA8B,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAG1E;;;;;;;;;;;OAWG;IACG,uBAAuB,CAC3B,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC;QAAE,eAAe,EAAE,UAAU,CAAC;QAAC,SAAS,EAAE,UAAU,CAAA;KAAE,GAAG,IAAI,CAAC;IAOzE;;;;;;;OAOG;IACG,2BAA2B,CAC/B,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE;QAAE,eAAe,CAAC,EAAE,UAAU,CAAC;QAAC,SAAS,CAAC,EAAE,UAAU,CAAA;KAAE,EAC/D,aAAa,SAAS,GACrB,OAAO,CAAC,IAAI,CAAC;IAIhB;;;;;;;OAOG;IACH,UAAU,IAAI,IAAI;CAInB"}