@cello-protocol/daemon 0.0.131 → 0.0.133

package/dist/document-layer.js

@@ -0,0 +1,255 @@
+/**
+ * DOD-DOC-INBOUND-2 / DOD-DOC-DELIVERY-2 — the composition of the document layer.
+ *
+ * Everything M14 built is a unit with injected seams. This is where they become one thing, and it
+ * is a module rather than a block inside `daemon.ts` for one reason: the assembly makes decisions.
+ * Which verifier, which live-doc policy, and — the one that matters — whether the layer is present
+ * at all.
+ *
+ * ── ALL OR NOTHING ────────────────────────────────────────────────────────────────────────────
+ *
+ * The layer is built completely or not built. There is no partially-wired mode, because every
+ * half-wiring is a distinct silent failure: an inbound path with no ack producer leaves the peer
+ * retrying until their document stalls; a delivery worker with no inbound counterpart publishes
+ * envelopes nobody can answer. `DOD-DOC-DELIVERY-2` records that ordering constraint on its own
+ * line, and this is where it is enforced instead of remembered.
+ *
+ * ── THE VERIFIER IS REQUIRED, AND RESOLVES THROUGH THE CALLER ─────────────────────────────────
+ *
+ * Signature verification needs an agent id → public key mapping, which lives with the daemon's
+ * contact and session state rather than here. It is passed in, and there is no default: a default
+ * would be a default answer to "is this authentic", and both inbound paths refuse rather than
+ * admit when it says no.
+ */
+import { verify } from "@cello-protocol/crypto";
+import { DocumentStore } from "./document-store.js";
+import { DocumentEngine } from "./document-engine.js";
+import { DocumentGate } from "./document-gate.js";
+import { DocumentRejections } from "./document-rejection.js";
+import { DocumentInbound } from "./document-inbound.js";
+import { DocumentAckInbound } from "./document-ack-inbound.js";
+import { DocumentFrameRouter } from "./document-frame-router.js";
+import { LiveDocuments } from "./document-live-docs.js";
+import { DocumentLifecycle } from "./document-lifecycle.js";
+import { DocumentNotifications } from "./document-notify.js";
+import { DocumentHandshake } from "./document-handshake.js";
+import { DocumentWritePath } from "./document-write-path.js";
+import { decodeDocumentRejection, buildDocumentRejectionTbs, documentRejectionHash, decodeDocumentProposalAck, buildDocumentProposalAckTbs, decodeDocumentControl, buildDocumentControlTbs, decodeDocumentUpdateEnvelope, encodeDocumentAck, buildDocumentAckTbs, } from "@cello-protocol/protocol-types";
+/**
+ * The default `publicKeyFor`: a remote agent's id IS its K_local public key, hex-encoded (M14-D5).
+ *
+ * `agent_id` in this daemon is a LOCAL primary key on the `agents` table — it names rows in our own
+ * database and cannot identify a remote peer. The pubkey is the only self-verifying identifier
+ * available: the signature checks against it directly, with no lookup that could be stale, missing
+ * or poisoned sitting on the critical path of every authentication.
+ *
+ * Malformed input returns null rather than throwing, and null is a refusal. An id that is not a
+ * 32-byte hex key is not "a peer we have no key for" — it is a frame that does not follow the
+ * protocol — but both must refuse, and refusing loudly at the verify step is where it belongs.
+ */
+export function agentPublicKeyFromId(agentId) {
+    if (!/^[0-9a-f]{64}$/.test(agentId))
+        return null;
+    return Uint8Array.from(Buffer.from(agentId, "hex"));
+}
+export function createDocumentLayer(deps) {
+    const { db, logger } = deps;
+    const store = new DocumentStore(db, logger);
+    const engine = new DocumentEngine(logger);
+    const gate = new DocumentGate(engine, {}, logger);
+    const rejections = new DocumentRejections(store, logger);
+    // Epoch zero comes from the stored PROPOSAL, not from the envelope log — see `LiveDocuments.get`.
+    // Declared before `handshake` exists, so it is resolved lazily; a rebuild only ever happens long
+    // after construction.
+    const live = new LiveDocuments(store, engine, logger, (ownerAgentId, documentId) => {
+        const record = handshake.get(ownerAgentId, documentId);
+        return record?.envelope.starting_content ?? null;
+    });
+    const lifecycle = new DocumentLifecycle(store, logger, { notifyPeer: deps.notifyPeer }, deps.rollback);
+    const notifications = new DocumentNotifications(store, logger);
+    // THE FILE SURFACE. Built, tested and instantiated NOWHERE until now — the same defect the tool
+    // surface had: a complete unit with no production caller reads exactly like a working feature.
+    // Without it §4.1's whole premise is missing, because a human collaborating on a document edits a
+    // file in their editor, and an agent with file tools reaches for them before any MCP verb.
+    const writePath = deps.workspaceRoot ? new DocumentWritePath(engine, deps.workspaceRoot, logger) : null;
+    /**
+     * One verifier for both paths. Ed25519 (RFC 8032) over the TBS the caller built.
+     *
+     * An UNKNOWN agent verifies as FALSE, and is logged distinctly. "We have no key for this peer"
+     * and "the signature is wrong" both have to refuse — admitting what we cannot authenticate is
+     * the outcome the verify step exists to prevent — but they are different things to tell an
+     * operator, and only one of them is a peer misbehaving.
+     *
+     * No try/catch: `verify` already fails closed on a malformed key or signature (its own body is a
+     * try returning false), so a catch here would be a branch nothing can reach.
+     */
+    const verifySignature = (agentId, tbs, signature) => {
+        const pubkey = deps.publicKeyFor(agentId);
+        if (pubkey === null) {
+            logger.warn("document.verify.no_key", { agentId });
+            return false;
+        }
+        return verify(pubkey, tbs, signature);
+    };
+    const inbound = new DocumentInbound({
+        store,
+        engine,
+        gate,
+        rejections,
+        logger,
+        verifySignature,
+        liveDocFor: (ownerAgentId, documentId) => live.get(ownerAgentId, documentId),
+        sign: deps.sign,
+    });
+    const ackInbound = new DocumentAckInbound({ store, rejections, logger, verifySignature });
+    // The handshake verifies a proposal against its NAMED proposer — the same resolver, so a forged
+    // proposal is refused before it can occupy a document_id (ON CONFLICT DO NOTHING makes the first
+    // arrival's bytes permanent for that id).
+    const handshake = new DocumentHandshake(db, logger, verifySignature);
+    const router = new DocumentFrameRouter({
+        inbound,
+        ackInbound,
+        logger,
+        ownerKeyFor: deps.ownerKeyFor,
+        recordProposal: (ownerAgentId, wire, nowMs) => {
+            // THROWS on a forged or misaddressed proposal, which the router contains and reports. That is
+            // right: those are refusals, and nothing should be recorded for them.
+            handshake.recordProposal(ownerAgentId, wire, nowMs);
+        },
+        // `_nowMs` unused: the received-rejection row takes its clock where it is written, and the
+        // rejection's own SIGNED timestamp is inside the envelope. A second clock read here would put a
+        // third time on one event.
+        rewriteFile: async (ownerAgentId, inResponseTo) => {
+            if (!writePath)
+                return;
+            const env = decodeDocumentUpdateEnvelope(inResponseTo);
+            const document = store.getDocument(ownerAgentId, env.document_id);
+            if (!document)
+                return;
+            await writePath.materialize(ownerAgentId, env.document_id, document.documentType, live.get(ownerAgentId, env.document_id));
+        },
+        sendFrameToPeer: async (ownerAgentId, inResponseTo, bytes) => {
+            // Addressed to whoever AUTHORED the envelope being answered, taken from the envelope itself
+            // rather than from the document row: the row's peer and the envelope's sender are the same
+            // party in a two-party document, and reading it from the signed bytes means a refusal can
+            // only ever go back to the agent that actually sent the thing refused.
+            const env = decodeDocumentUpdateEnvelope(inResponseTo);
+            const sent = await deps.sendFrame(ownerAgentId, env.sender_agent_id, bytes);
+            if (!sent.ok) {
+                logger.warn("document.rejection.unsent", {
+                    documentId: env.document_id,
+                    peerAgentId: env.sender_agent_id,
+                    reason: sent.reason,
+                });
+            }
+        },
+        sendAck: async (ownerAgentId, wire, outcome) => {
+            const env = decodeDocumentUpdateEnvelope(wire);
+            const ack = {
+                type: "document_ack",
+                // The wire version this build speaks. Inlined rather than imported because protocol-types
+                // exports the domain and the codec but not the constant; the decoder pins it by value.
+                ack_version: 1,
+                document_id: env.document_id,
+                envelope_hash: outcome.envelopeHash,
+                acker_agent_id: ownerAgentId,
+                admitted: outcome.admitted,
+                ...(outcome.admitted ? {} : { rejection_reason: outcome.rejectionReason ?? "refused" }),
+                acked_at_ms: Date.now(),
+                signature: new Uint8Array(0),
+            };
+            ack.signature = await deps.sign(ownerAgentId, buildDocumentAckTbs(ack));
+            // BEST-EFFORT, and it must be: an ack that could not be sent is not a reason to refuse
+            // content we have already admitted. The sender redelivers on its own timer, and the
+            // redelivery is acked too — which is the case this whole path exists to terminate.
+            const sent = await deps.sendFrame(ownerAgentId, env.sender_agent_id, encodeDocumentAck(ack));
+            if (!sent.ok) {
+                logger.warn("document.ack.unsent", {
+                    documentId: env.document_id,
+                    envelopeHash: outcome.envelopeHash,
+                    reason: sent.reason,
+                    correlationId: outcome.correlationId,
+                });
+            }
+        },
+        recordControl: (ownerAgentId, wire, nowMs) => {
+            const control = decodeDocumentControl(wire);
+            // VERIFIED FIRST. A kill frame ends a collaboration; unsigned, anyone reaching the channel
+            // could end any document between any two parties and each operator would believe the other
+            // walked away.
+            if (!verifySignature(control.sender_agent_id, buildDocumentControlTbs(control), control.signature)) {
+                throw new Error(`document_control_signature_invalid: the ${control.verb} claims to come from ` +
+                    `${control.sender_agent_id} but its signature does not verify against that agent`);
+            }
+            const verdict = control.verb === "kill"
+                ? lifecycle.recordPeerKill(ownerAgentId, control.document_id, control.sender_agent_id, nowMs)
+                : lifecycle.recordPeerClose(ownerAgentId, control.document_id, control.sender_agent_id, nowMs);
+            if (!verdict.ok) {
+                // Refusals here are real: an unknown document, or a sender who is not this document's peer.
+                // Thrown so the router reports them rather than recording an end nobody was entitled to.
+                throw new Error(`${verdict.reason}: ${verdict.detail}`);
+            }
+        },
+        recordProposalAck: (ownerAgentId, wire, _nowMs) => {
+            const ack = decodeDocumentProposalAck(wire);
+            // VERIFIED against the agent it names, before anything is written. A refusal ack makes the
+            // proposer stop waiting and, at the surface, reads as "they said no" — so unsigned, anyone on
+            // the channel could make a proposal appear refused by a party who never saw it, and the two
+            // operators would each believe the other walked away.
+            if (!verifySignature(ack.acker_agent_id, buildDocumentProposalAckTbs(ack), ack.signature)) {
+                throw new Error(`document_proposal_ack_signature_invalid: the answer claims to come from ` +
+                    `${ack.acker_agent_id} but its signature does not verify against that agent`);
+            }
+            // The acker is passed through and CHECKED against the proposal's peer. Verifying the
+            // signature proves the frame is authentic; it says nothing about whether its author was
+            // entitled to answer this proposal.
+            const stored = handshake.recordPeerDecision(ownerAgentId, ack.document_id, ack.acker_agent_id, {
+                accepted: ack.accepted,
+                ...(ack.refusal_reason !== undefined ? { reason: ack.refusal_reason } : {}),
+                decidedAtMs: ack.decided_at_ms,
+            });
+            if (!stored.ok) {
+                // SETTLE ONCE — a contradicting second answer is an error, never an update. A peer that
+                // accepted must not be able to later claim it refused, or the proposer tears down a
+                // document the peer is still editing.
+                throw new Error(`${stored.reason}: ${stored.detail}`);
+            }
+        },
+        recordRejection: (ownerAgentId, wire, _nowMs) => {
+            const env = decodeDocumentRejection(wire);
+            if (!verifySignature(env.rejecting_agent_id, buildDocumentRejectionTbs(env), env.signature)) {
+                // A rejection stops the sender retrying and makes them supersede. Unsigned, anyone on the
+                // channel could freeze a document by asserting a refusal nobody made.
+                throw new Error(`document_rejection_signature_invalid: the rejection claims to come from ` +
+                    `${env.rejecting_agent_id} but its signature does not verify against that agent`);
+            }
+            rejections.recordIncomingRejection(ownerAgentId, env.document_id, {
+                rejectionEnvelopeHash: documentRejectionHash(env),
+                rejectedEnvelopeHash: env.rejected_envelope_hash,
+                reason: env.reason,
+                detail: env.detail,
+                fromAgentId: env.rejecting_agent_id,
+            });
+        },
+    });
+    return {
+        store,
+        writePath,
+        handshake,
+        engine,
+        live,
+        lifecycle,
+        notifications,
+        rejections,
+        router,
+        onDocumentFrame: (agentName, _sessionId, content, _senderPubkey, correlationId) => 
+        // `agentName` names the owning agent for the session; the router maps it to the owner KEY
+        // that scopes the store. The session id and the sender's transport pubkey are unused: a
+        // document is bound to its PEER by the handshake, not to whichever session carried the
+        // frame, and the envelope's own signed `sender_agent_id` is what the inbound path checks
+        // against that binding. Trusting the transport identity instead would let a frame arriving
+        // on any session act on any document that session's peer happens to share.
+        router.routeSync(agentName, content, Date.now(), correlationId ?? "frame"),
+    };
+}
+//# sourceMappingURL=document-layer.js.map

package/dist/document-layer.js.map

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

package/dist/document-lifecycle.d.ts

@@ -0,0 +1,125 @@
+/**
+ * DOD-DOC-LIFECYCLE-1 — the verbs (§3.5 + §16.4).
+ *
+ * Three ways a document can end, and they are not interchangeable. Conflating any two of them
+ * makes a promise the protocol cannot keep:
+ *
+ *   close     BILATERAL. Both sides ack and the document is complete by agreement. One side's
+ *             close is a REQUEST — treating it as a conclusion would tell this operator the
+ *             collaboration ended while the peer is still writing into it.
+ *   kill      UNILATERAL. Stop accepting and publishing, notify the peer, and KEEP the local copy
+ *             and the log. The peer keeps what it holds, and that is said out loud: it is the one
+ *             thing an operator is most likely to assume a kill undoes, and the one thing it
+ *             cannot.
+ *   withdraw  ONE UNDELIVERED update. A local rollback plus a withdrawal record BESIDE the
+ *             original — marked, never deleted, because a hole in an append-only log is
+ *             indistinguishable from tampering. Once the peer has it, withdrawal is refused rather
+ *             than faked.
+ *
+ * ── THE KILL SWITCH (§16.7-11) ────────────────────────────────────────────────────────────────
+ *
+ * A platform-paused agent refuses OUTBOUND publishes loudly, still admits INBOUND mechanically,
+ * and suppresses notifications. The asymmetry is deliberate. Refusing inbound would surface the
+ * pause to the peer as a protocol fault and force a rejection round for something that is not
+ * their doing; refusing outbound silently would leave the operator writing into a document that is
+ * going nowhere, with their work piling up locally and no sign anything is wrong.
+ */
+import type { DocumentStore } from "./document-store.js";
+import type { Logger } from "./types.js";
+/** How the peer is told about a unilateral end. Injected — the transport is not this unit's. */
+export interface LifecycleNotifier {
+    notifyPeer(documentId: string, verb: "kill" | "close"): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+}
+export interface DocumentListRow {
+    documentId: string;
+    peerAgentId: string;
+    documentType: string;
+    /** Constant in V1, shown because it is seam surface — a field nobody sees cannot be noticed. */
+    assuranceTier: string;
+    epochId: number;
+    status: string;
+    pendingDeliveries: number;
+    /** Of those, how many have LEFT and are awaiting the peer's confirmation. */
+    pendingSent: number;
+    /** Of those, how many have not left this machine at all. */
+    pendingUnsent: number;
+    /** We have closed and the peer has not. */
+    closePending: boolean;
+}
+export type Verdict = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+    detail: string;
+};
+export declare class DocumentLifecycle {
+    #private;
+    constructor(store: DocumentStore, logger: Logger, notifier: LifecycleNotifier, 
+    /**
+     * Undo one envelope's operations on the LIVE document, as inverses. Injected because the live
+     * `Y.Doc` and its UndoManager belong to the engine, not here — and REQUIRED, because a default
+     * that quietly did nothing would restore exactly the defect this argument exists to fix.
+     */
+    rollback: (ownerAgentId: string, documentId: string, envelopeHash: string) => {
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+    }, senderAgentId?: (ownerAgentId: string) => string);
+    list(ownerAgentId: string, nowMs: number): DocumentListRow[];
+    /** Our half of a bilateral close. Completes only when the peer's half is also on record. */
+    close(ownerAgentId: string, documentId: string, nowMs: number): Promise<(Verdict & {
+        ok: true;
+        peerNotified: boolean;
+    }) | (Verdict & {
+        ok: false;
+    })>;
+    /** The peer's half, arriving over the session. */
+    recordPeerClose(ownerAgentId: string, documentId: string, peerAgentId: string, nowMs: number): Verdict;
+    /**
+     * The peer KILLED the document. Their half of the unilateral end.
+     *
+     * Terminal immediately, and there is no reciprocal step: a kill is one-sided by definition, which
+     * is what separates it from a close. Continuing to publish afterwards would send updates to a
+     * party who has stopped listening — refused at their end forever, with nothing on this screen
+     * explaining why.
+     *
+     * The SENDER IS CHECKED against the document's peer for the same reason `recordPeerClose` checks
+     * it: without that, any string plus a valid-looking frame ends someone else's document.
+     */
+    recordPeerKill(ownerAgentId: string, documentId: string, peerAgentId: string, nowMs: number): Verdict;
+    /**
+     * Unilateral end. Local, and deliberately not contingent on the peer hearing about it — a
+     * decision to stop that depends on the other party being online is not a decision to stop.
+     */
+    kill(ownerAgentId: string, documentId: string, nowMs: number): Promise<{
+        ok: true;
+        peerNotified: boolean;
+        note: string;
+    } | {
+        ok: false;
+        reason: string;
+        detail: string;
+    }>;
+    /**
+     * Withdraw ONE undelivered update: a withdrawal record beside the original.
+     *
+     * Every refusal here is the same shape — say no rather than produce a record that claims
+     * something untrue about the log.
+     */
+    withdraw(ownerAgentId: string, documentId: string, envelopeHash: string, nowMs: number): Verdict;
+    setPlatformPaused(agentId: string, paused: boolean, nowMs: number): void;
+    isPlatformPaused(agentId: string): boolean;
+    /** Outbound. Refused loudly while paused, and while the document has ended. */
+    canPublish(ownerAgentId: string, documentId: string): Verdict;
+    /** Inbound. A pause does NOT refuse it — see the header. */
+    canAdmit(ownerAgentId: string, documentId: string): Verdict;
+    shouldNotify(agentId: string): boolean;
+}
+//# sourceMappingURL=document-lifecycle.d.ts.map

package/dist/document-lifecycle.d.ts.map

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