@cello-protocol/daemon 0.0.193 → 0.0.195

package/dist/park-recovery.d.ts

@@ -0,0 +1,205 @@
+/**
+ * CELLO Daemon — MAIL THAT WAITED
+ *
+ * Split out of `session-node-manager.ts` by 036-GODFILE, Part 6. The relay store-and-forward path:
+ * depositing content the counterparty could not take live, recovering it when they come back, and
+ * the backstop sweep that drains it even when a trigger is missing.
+ *
+ * Moved verbatim, comments included.
+ *
+ * ⚠️ THE BACKSTOP SWEEP EXISTS BECAUSE THE INCIDENT WAS A MISSING TRIGGER, and a missing trigger is
+ * invisible: the daemon looked healthy, the content was intact on the relay, and the only thing that
+ * ever moved it was a human restarting the daemon. Do not delete it as redundant — the trigger-driven
+ * drains are what deliver, and this is what bounds the cost of the next gap in trigger coverage to
+ * one interval of latency.
+ */
+import type { Logger, SessionRecord } from "./types.js";
+import type { SealCarryLeaf } from "./session-seal-leaf-store.js";
+import type { SessionTree } from "./session-tree.js";
+import type { InboundRefusals } from "./inbound-refusals.js";
+import { type ParkedDrainReason, type ParkAttempt, type ActiveSessionEntry } from "./session-node-types.js";
+import { type ParkAuthFailure } from "./park-envelope.js";
+/** What park recovery needs from the manager, stated explicitly rather than handed `this`. */
+export interface ParkContext {
+    readonly logger: Logger;
+    readonly refusals: InboundRefusals;
+    shuttingDown(): boolean;
+    sessionKey(agentName: string, sessionId: string): string;
+    requireAgentId(agentName: string): string;
+    ownPubkeyHex(agentName: string): string | null;
+    /** The live session entry, when one exists. Park works for sessions that have none. */
+    activeEntry(key: string): ActiveSessionEntry | undefined;
+    /** Agents currently holding a standing receiver — the backstop sweep's population. */
+    agentsWithLiveReceiver(): Iterable<string>;
+    agentWantsReceiver(agentName: string): boolean;
+    getSessionRecord(agentName: string, sessionId: string): SessionRecord | null;
+    getSealCarry(agentName: string, sessionId: string): readonly SealCarryLeaf[];
+    getSessionTree(agentName: string, sessionId: string): SessionTree;
+    recordOrderingRecord(agentName: string, sessionId: string, structure1Cbor: Uint8Array, structure2Cbor: Uint8Array, contentHash: Uint8Array, correlationId?: string): number | null;
+    ingestReceivedContent(agentName: string, sessionId: string, content: Uint8Array, contentHash: Uint8Array, correlationId?: string, recoveredSeq?: number, contentHashAlgIn?: string | null): Promise<{
+        ok: true;
+        leafIndex: number;
+        sequenceNumber: number;
+        held?: boolean;
+        appendedCount?: number;
+        screenedOut?: boolean;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    witnessReceivedLeaf(agentName: string, sessionId: string, contentHash: Uint8Array, structure1Cbor: Uint8Array, senderSignature: Uint8Array, leafKind: number, correlationId?: string): void;
+    noteAcknowledgeable(agentName: string, sessionId: string, canonicalSeq: number, contentHash: Uint8Array): void;
+}
+export declare class ParkRecovery {
+    #private;
+    constructor(ctx: ParkContext, parkedDrainBackstopMs: number);
+    /**
+     * Arm the backstop clock from the START of watching, not from the epoch — otherwise the first
+     * tick always fires a sweep on top of the install drain that just ran.
+     */
+    armBackstopClock(now: number): void;
+    /** Arm the park-deposit fault. Returns the count now armed. */
+    injectParkFault(count: number, cause?: string): number;
+    /** Remaining armed park faults — so a test can assert the fault was actually consumed. */
+    getParkFaultRemaining(): number;
+    /**
+     * MSG-001-3b (2b): inject the live content-park deposit (seal + ContentParkClient.deposit).
+     * Injected by the composition root (daemon.ts). When absent, a not-confirmed send still records
+     * the durable awaiting entry (crash backstop) but does not deposit live.
+     * DOD-LEAVEMSG-1 (cello-unit-reviewer HIGH fix): the hook returns a TYPED result — `{ok:true}` or
+     * `{ok:false, reason}` — mirroring RetryQueue's ParkFn contract. It must NEVER resolve `{ok:true}`
+     * merely because it didn't throw: the production hook's own failure branches (standing receiver
+     * unavailable, relay explicitly rejects the deposit) log-and-return without throwing, and a
+     * throw-only contract would silently report those as success — the exact "system lies about its
+     * own health" bug the reviewer caught (a park that never happened reported to the operator as
+     * "dispatched to relay," with the durable retry_queue backstop skipped because sendContent's own
+     * caller only enqueues on an honest {ok:false}).
+     */
+    setContentParkHook(fn: (args: {
+        agentName: string;
+        sessionId: string;
+        recipientPubkeyHex: string;
+        relayPeerId: string;
+        relayAddrs: readonly string[];
+        contentHashHex: string;
+        content: Uint8Array;
+        structure1Cbor?: Uint8Array;
+        structure2Cbor?: Uint8Array;
+        structure1Signature?: Uint8Array;
+        leafKind?: number;
+        contentHashAlg: string | undefined;
+    }) => Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+        cause?: string;
+        retryAfterMs?: number;
+    }>): void;
+    /**
+     * DOD-PARK-DRAIN-1: inject the parked-mailbox drain (daemon.ts → contentPark.autoRecoverForAgent).
+     *
+     * The manager owns the two events that mean "content may be waiting for this agent on a relay":
+     * a standing receiver was (re)built, and the slow backstop sweep. It does not own the drain
+     * itself — that needs the agent's key provider and the inbound ingest funnel. So it calls out.
+     *
+     * Injected by the composition root, not passed to the constructor: the manager is built long
+     * before the content park exists (content-park.ts documents why that ordering is load-bearing).
+     */
+    setParkedDrainHook(fn: (agentName: string, reason: ParkedDrainReason) => void): void;
+    /** Ask for a drain. Never throws — a broken drain must never cost the caller its receiver. */
+    fireParkedDrain(agentName: string, reason: ParkedDrainReason): void;
+    /**
+     * MSG-001-3b (2b): deposit un-confirmed content to the relay store-and-forward backstop — keyed
+     * to the recipient, on the SAME relay this session is witnessed by — so an offline recipient
+     * recovers it (at the sequence the witness already assigned, R1). Best-effort, never throws.
+     * DOD-LEAVEMSG-1: returns whether the deposit actually succeeded (false if no hook/relay is
+     * configured, or the hook rejects) so a caller with a live response to shape (sendContent) can
+     * distinguish "genuinely parked" from "nothing recoverable" instead of guessing. Callers that
+     * fire this from an async backstop with no live caller (the TTF-expiry path) may ignore the
+     * result — the deposit itself and its logging are unchanged either way.
+     */
+    /**
+     * `contentHashAlg` is `string | undefined`, NOT optional — B2b-1 review F4's shape, applied to the
+     * last place it was missing.
+     *
+     * Optional, dropping it at a call site was neither a typecheck error nor a test failure, because
+     * absent silently means `sha256` and that is the only value in play today. Measured: the
+     * direct-dial-fail route's mutant SURVIVED the whole daemon suite. Requiring the argument — even
+     * when its value is `undefined` — forces each of the three callers to state what this message was
+     * hashed under, so a new fourth caller cannot omit it by accident.
+     */
+    parkContent(agentName: string, sessionId: string, contentHashHex: string, content: Uint8Array, structure1Cbor: Uint8Array | undefined, structure2Cbor: Uint8Array | undefined, contentHashAlg: string | undefined, structure1Signature?: Uint8Array, parkLeafKind?: number): Promise<ParkAttempt>;
+    /** DOD-M12B-INDEX-1 — this agent's own K_local pubkey, for attributing its own held content.
+     *  Null when it cannot be resolved: an UNATTRIBUTED annex row is true, a falsely attributed one
+     *  is not, and this is the record that outlives the session. */
+    /**
+     * Test seam for `#recoverOwnSealCtrlLeaf` (documented on the method itself, below). The
+     * distinction it draws — "there is none" versus "I could not tell" — is the whole safety
+     * property, and it had no coverage at any level.
+     */
+    recoverOwnSealCtrlLeafForTest(agentName: string, sessionId: string): {
+        reportedRootHex: string;
+        sequenceNumber: number;
+    } | "none" | "unknown";
+    /**
+     * DOD-M12B-INTERRUPTED-ESCALATE-1 — our own SEAL ctrl leaf, if a previous run already posted one.
+     *
+     * Returns the two values a unilateral escalation runs on, rebuilt from durable state:
+     * the ctrl leaf's relay-assigned sequence, and the root the tree WOULD have with that leaf
+     * appended. The content hash cannot be recomputed — the seal payload embeds a `close_timestamp`
+     * — so it is read out of the signed Structure 1 the store already holds.
+     *
+     * Null when there is no own ctrl leaf, which is the ordinary first-close case.
+     */
+    recoverOwnSealCtrlLeaf(agentName: string, sessionId: string): {
+        reportedRootHex: string;
+        sequenceNumber: number;
+    } | "none" | "unknown";
+    /**
+     * SEC-1 — THE ONLY WAY PARKED CONTENT ENTERS THE TRANSCRIPT.
+     *
+     * Authentication and ingest are FUSED here on purpose, and must stay fused. A caller cannot ingest
+     * parked content without passing the signature gate, because this is the only entry point. Exposing
+     * a separate `decode → ingest` path — with the signature check as its own optional step — is a
+     * downgrade attack: an attacker omits the thing that triggers the check, and the check never runs.
+     * A gate the caller can skip by leaving a field out is not a gate.
+     *
+     * FAILS CLOSED. No signature / bad signature / signer is not this session's counterparty / no
+     * session at all → REFUSED, nothing is appended, nothing is written, and the caller MUST NOT
+     * confirm-delete the entry from the relay (a forgery must not be able to evict itself, and a
+     * genuine bug must not silently eat mail).
+     */
+    recoverParkedEntry(agentName: string, sessionId: string, recipientPubkey: Uint8Array, unsealed: Uint8Array, contentHash: Uint8Array, correlationId?: string): Promise<{
+        ok: true;
+        leafIndex: number;
+        sequenceNumber: number;
+        held?: boolean;
+        appendedCount?: number;
+        screenedOut?: boolean;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    /**
+     * Review M4: bounded memo of parked entries we have already refused, so a mailbox stuffed with
+     * forgeries cannot force an unbounded unseal+verify on every reconnect. FIFO-capped — the cap
+     * matters more than the retention: forgetting an entry only costs one extra verification, whereas
+     * an unbounded map would be a memory leak fed by a remote party (the exact class the DOD-MSG-4
+     * review already caught once in the offered-moniker map).
+     */
+    rememberRefusedParkedEntry(key: string, reason: ParkAuthFailure): void;
+    /**
+     * DOD-PARK-DRAIN-1: the backstop sweep — every agent holding a standing receiver gets a drain
+     * every #parkedDrainBackstopMs, whether or not anything happened.
+     *
+     * The trigger-driven drains (agent start, receiver rebuild, signaling reconnect) are what
+     * actually deliver. This exists because the incident was a MISSING trigger, and a missing
+     * trigger is invisible: the daemon looked healthy, the content was intact on the relay, and the
+     * only thing that ever moved it was a human restarting the daemon. With the sweep, the worst a
+     * future gap in trigger coverage can cost is one interval of latency. Safe by construction —
+     * ingest is deduped and the relay is delete-on-confirm, so a redundant drain pulls nothing.
+     */
+    parkedDrainBackstopTick(now: number): void;
+}
+//# sourceMappingURL=park-recovery.d.ts.map

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

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