@cello-protocol/daemon 0.0.211 → 0.0.213

package/dist/session-delivery-acks.d.ts

@@ -0,0 +1,195 @@
+/**
+ * DOD-M15-DELIVERYACK-1 — the delivery acknowledgement, both directions.
+ *
+ * Split out of `session-content-ingest.ts` rather than added to it. The acknowledgement is now a
+ * signed artifact with its own five rules and its own evidence store, which is a subject of its
+ * own — and the ingest file sits on a `max-lines` ratchet whose whole purpose is that a feature
+ * lands as a module instead of as growth in a file nobody can read.
+ *
+ * ⚠️ NOTHING HERE TOUCHES THE TAMPER-EVIDENT RECORD. An acknowledgement takes no chain leaf, is
+ * never itself acknowledged, and its absence proves nothing. The evidence it produces is read by
+ * the sealed-receipt surface and by nothing else.
+ */
+import type { SessionContentPipelineContext } from "./session-content-context.js";
+import { type ParkedDeliveryAck } from "./park-envelope.js";
+import type { DaemonDatabase } from "./sqlcipher-db.js";
+import type { Logger } from "./types.js";
+/**
+ * Send a SIGNED `persisted` delivery ACK back to the sender over the same
+ * /cello/content/1.0.0 protocol (AC-001).
+ *
+ * ⚠️ IT USED TO BE UNSIGNED, and the comment here used to justify that: "authentication is the
+ * Noise session channel, so the ACK carries no signature". That is true of the HOP and it dies
+ * with the connection — it left the sender holding nothing it could show a third party, which is
+ * what `DOD-M15-DELIVERYACK-1` exists to fix. Rewritten rather than deleted, because the old
+ * sentence is exactly why an auditor would conclude the frame is unsigned by design.
+ *
+ * What is signed says only *this machine received these bytes in this session*. Signed on INGEST,
+ * so it asserts nothing about attention and nothing about agreement.
+ *
+ * Still best-effort in the SEND: a failed ACK send is logged and the sender recovers via its
+ * TTF/recovery path rather than a thrown error here.
+ */
+export declare function sendDeliveryAck(ctx: SessionContentPipelineContext, agentName: string, sessionId: string, contentHash: Uint8Array, correlationId?: string): Promise<void>;
+/**
+ * DOD-M15-DELIVERYACK-1 — AN INBOUND ACKNOWLEDGEMENT IS ATTACKER-CONTROLLED INPUT.
+ *
+ * The client is open source and runs on the counterparty's machine, so they can send whatever
+ * they like here. Five properties, and all five are load-bearing:
+ *
+ * 1. **Verified against the session's RECORDED counterparty key**, never a key in the frame. The
+ *    recorded key comes from what the operator asked for (initiator) or the directory-attested
+ *    offer (responder) — `entry.counterpartyPubkey`. Checking a signature against a key carried
+ *    inside its own frame proves only that somebody owns a keypair.
+ *    ⚠️ Deliberately NARROWER than "either participant". The clause says an ack verifying under
+ *    neither participant key is discarded; ours additionally discards one signed by US, which is
+ *    the self-referential case — our own signature on our own message, stored in our own
+ *    database, constrains nobody.
+ * 2. **Bound** — it must name a hash this side actually sent in this session and is still
+ *    awaiting. The session is already pinned by the shared frame gate above.
+ * 3. **Inert** — it records evidence and resolves the sender's own fallback timer. It advances no
+ *    sequence, touches no tree, takes no leaf, closes nothing, seals nothing.
+ * 4. **Idempotent and bounded** — the awaiting entry is consumed on the first accepted ack, so a
+ *    duplicate finds nothing and does nothing, and the number of acks that can ever be recorded
+ *    for a session is the number of messages this side sent in it. There is no counter an
+ *    attacker can inflate because there is no per-ack allocation at all.
+ * 5. **Malformed fails exactly as missing does.** Both take this one discard path: the timer stays
+ *    armed, no `content.delivery.acked` fires, nothing is recorded, and the message parks on TTF
+ *    expiry exactly as it would have with no acknowledgement at all.
+ *
+ * 🚨 AND A DISCARD IS NOT A SECURITY EVENT. It does not freeze the session and must never feed a
+ * trust signal. A missing acknowledgement is usually innocent — the relay parked the content, the
+ * far daemon died between ordering and pull, a bounded queue dropped its oldest frame, a screener
+ * refused it. Reading absence as evasion is the defect, not the fix.
+ */
+export declare function onDeliveryAck(ctx: SessionContentPipelineContext, resolveAwaitingAck: (agentName: string, sessionId: string, contentHash: Uint8Array) => void, agentName: string, sessionId: string, contentHash: Uint8Array, rawSig: unknown, correlationId?: string): void;
+/**
+ * DOD-M15-DELIVERYACK-1 — keep the counterparty's signature that their machine received a message.
+ *
+ * Called ONLY after `verifyDeliveryAck` succeeded against the session's recorded counterparty key.
+ * `INSERT OR IGNORE` is the idempotence: the first acknowledgement recorded for a (session, hash)
+ * stands and a replay changes nothing.
+ *
+ * A write failure is LOUD and it is not fatal. The message was delivered; what is lost is this
+ * side's ability to prove it later, and the operator is the only one who can act on that.
+ */
+export declare function storeDeliveryAck(db: DaemonDatabase, logger: Logger, a: {
+    agentId: string;
+    agentName: string;
+    sessionId: string;
+    contentHashHex: string;
+    signerPubkeyHex: string;
+    signature: Uint8Array;
+    correlationId?: string;
+}): boolean;
+/**
+ * DOD-M15-DELIVERYACK-1 rule 2, at the database — did this side put these exact bytes on the wire in
+ * this session?
+ *
+ * The durable bind, reachable from both routes: the live inbound handler asks through
+ * `SessionRecords`, and the mailbox drain asks here directly because it holds a database handle and
+ * no manager. A sent-direction transcript row joined to its leaf is written by our own send path and
+ * survives the fallback timer and a restart, which is what lets an acknowledgement for a message
+ * that had to be parked and recovered still count. Nothing a counterparty sends creates a row here.
+ */
+export declare function sentContentHashExists(db: DaemonDatabase, agentId: string, sessionId: string, contentHashHex: string): boolean;
+/**
+ * DOD-M15-DELIVERYACK-1 unit 1 — ACCEPT AN ACKNOWLEDGEMENT THAT CAME BACK THROUGH THE RELAY'S
+ * MAILBOX.
+ *
+ * This is the offline route: the counterparty read the message while this daemon was down, could not
+ * reach it directly, and parked the acknowledgement. It is held to the SAME five rules the live
+ * route is, because it is the same attacker-controlled input arriving by a different road — and to
+ * one more check the live route does not need, which has already run before this is called: the park
+ * envelope's own SEC-1 gate proved the DEPOSITOR is this session's counterparty.
+ *
+ * ⚠️ THE TWO CHECKS ARE INDEPENDENT AND BOTH ARE REQUIRED. The envelope gate says who put it in the
+ * mailbox; the signature below says who acknowledged the message. A relay holding the recipient's
+ * public key can deposit anything, and the envelope gate is what stops that — but a counterparty who
+ * rewrote their own daemon passes the envelope gate by construction, and only the signature check
+ * catches an acknowledgement they did not actually sign for this message.
+ *
+ * 🚨 INERT, exactly as the live route is. It records evidence. It appends no leaf, advances no
+ * sequence, touches no tree, and nothing about a refusal here says anything about the counterparty.
+ *
+ * ─── RULE 4's "rate-limited", on THIS route, and why there is no memo here ─────────────────────
+ *
+ * A refused entry is deliberately NOT confirm-deleted — a forgery must never be able to evict
+ * itself — so a bad acknowledgement is re-pulled on every drain, forever. The content path answers
+ * that with a bounded in-memory memo of what it already refused. This route does not need one, and
+ * the reason is three enforced bounds rather than an argument:
+ *
+ *   1. Only the COUNTERPARTY can put an entry here at all. The park envelope's SEC-1 gate runs
+ *      first and refuses anyone else, the relay included.
+ *   2. The relay caps each recipient's mailbox — `#maxRecipientEntries` / `#maxRecipientBytes` in
+ *      `file-content-store.ts`, with FIFO eviction inside the quota. So the number of entries that
+ *      can be waiting is bounded by the operator's own mailbox size, not by the counterparty's
+ *      patience.
+ *   3. The slot check above runs BEFORE any cryptography, so the cheap forgery — an entry filed
+ *      anywhere but the derived slot — costs one SHA-256 and no signature verification.
+ *
+ * What is left is one Ed25519 verify per correctly-slotted, wrongly-signed entry per drain,
+ * multiplied by a mailbox the relay already bounds. That is a cost, and it is a bounded one; a memo
+ * would shave it at the price of a second piece of state whose key a counterparty influences.
+ */
+export declare function acceptParkedDeliveryAck(a: {
+    db: DaemonDatabase;
+    logger: Logger;
+    agentId: string;
+    agentName: string;
+    /** The session the RELAY filed this entry under. */
+    sessionId: string;
+    /** The mailbox slot the entry was pulled from — what the relay files it by. */
+    mailboxSlotHex: string;
+    /** The session's RECORDED counterparty key. Never a key carried in the payload. */
+    counterpartyPubkeyHex: string | undefined;
+    ack: ParkedDeliveryAck;
+    correlationId?: string;
+}): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * DOD-M15-DELIVERYACK-1 — the three facts, per message this side SENT, each standing alone.
+ *
+ * ⚠️ READ THE ASYMMETRY BEFORE USING THIS. Each fact is present or absent on its own and a
+ * missing one is reported as missing and NOTHING MORE. There is deliberately no combined status,
+ * no derived verdict, and no count — a message can be delivered, read and acted on with no
+ * acknowledgement recorded here, because the acknowledgement can be lost exactly as the message
+ * can. Anything that renders absence as fault is a defect, not a display choice.
+ *
+ *   ordered      — the RELAY assigned it a position. Read from `relay_ack_receipts`, which holds
+ *                  the relay's own countersignature, scoped to THIS agent's pubkey so a loopback
+ *                  session's two ends never read each other's.
+ *   delivered    — the RELAY handed the bytes over. **This side holds no such evidence for any
+ *                  message today, on either path**: the relay answers the RECIPIENT on pickup and
+ *                  never tells the depositor. It is reported absent with that reason named rather
+ *                  than fabricated from "our own send succeeded", which would be this machine
+ *                  asserting a relay fact about itself. `069-ORDERPROOF` plus a pickup notice to
+ *                  the depositor is what fills it.
+ *   acknowledged — the RECIPIENT's own signature, from `delivery_acks`.
+ */
+export declare function readDeliveryFacts(db: DaemonDatabase, logger: Logger, agentId: string, sessionId: string): Array<{
+    seq: number | null;
+    content_hash: string;
+    ordered: {
+        asserted_by: "relay";
+        relay_id: string;
+        relay_timestamp: number;
+        signature: string;
+    } | null;
+    delivered: {
+        asserted_by: "relay";
+        held: false;
+        why_absent: string;
+    };
+    acknowledged: {
+        asserted_by: "recipient";
+        signer_pubkey: string;
+        signature: string;
+        recorded_at: number;
+    } | null;
+}>;
+//# sourceMappingURL=session-delivery-acks.d.ts.map

package/dist/session-delivery-acks.d.ts.map

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