@cello-protocol/daemon 0.0.225 → 0.0.227

package/dist/session-ephemerals.d.ts

@@ -1,279 +0,0 @@
-/**
- * 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

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