@cello-protocol/protocol-types 0.0.54 → 0.0.56

package/dist/document-ack.js

@@ -1,228 +0,0 @@
-/**
- * DOD-DOC-INBOUND-2 — the document ACK (§16.4).
- *
- * The frame that closes DELIVERY-2's loop. Until it exists, a sent envelope's outcome is
- * `admitted: null` forever: the worker knows the content left and nothing more, so it re-sends on
- * the ack timeout and eventually stalls the document at the unacked ceiling.
- *
- * ── WHY A REJECTION IS AN ACK ─────────────────────────────────────────────────────────────────
- *
- * `admitted: false` is not a failure to acknowledge — it is an acknowledgement that says no. The
- * peer has DECIDED, so the sender must stop retrying and supersede instead (§3.2). Modelling
- * rejection as "no ack" would leave the sender redelivering an envelope the peer has already ruled
- * on, re-triggering their gate and their retry counter until the document stalls for reasons the
- * operator cannot see.
- *
- * ── WHY IT IS SIGNED ──────────────────────────────────────────────────────────────────────────
- *
- * The ack settles an envelope permanently: an acked envelope stops being redelivered and, if the
- * ack says rejected, the sender rolls back local work. Both are consequences an unauthenticated
- * party must not be able to cause. An unsigned ack lets anyone who can reach the channel silence a
- * delivery — the content is dropped from the pending set and neither operator ever learns it was
- * never applied, which is exactly the silent divergence the two-layer design exists to prevent.
- *
- * The signature covers the ENVELOPE HASH, so an ack cannot be moved to a different envelope, and
- * the DOCUMENT ID, so it cannot be moved to a different document. It does not cover `admitted`
- * alone for the same reason a signature never covers one field: the whole statement is the claim.
- *
- * ── CONTRACT FOR THE CONSUMER: SETTLE ONCE ────────────────────────────────────────────────────
- *
- * Nothing here binds an ack to the acker's chain, and nothing at the type level stops one acker
- * producing a valid ADMISSION and a valid REJECTION for the same envelope. Envelopes have
- * `verifyDocumentChainLink` because per-sender ordering matters; acks have no equivalent. So the
- * consumer must settle an envelope ONCE and treat a second, contradicting ack as an ERROR with both
- * signatures retained — never as an update. Applying the later one would let a peer that admitted
- * an envelope later claim it refused it, and the sender would roll back work the peer already has.
- */
-import { createHash } from "node:crypto";
-import { encodeCbor, decodeCbor } from "./cbor.js";
-/** Domain tag in slot 0. Distinct from the update and proposal domains. */
-export const DOCUMENT_ACK_DOMAIN = "CELLO-DOCUMENT-ACK-v1";
-/**
- * The ack frame version, ON THE WIRE.
- *
- * The `-v1` in the domain string never travels — it lives inside the preimage — so a V2 acker's
- * frame would decode cleanly as V1 and fail SIGNATURE VERIFICATION, sending an operator to key
- * management and peer identity for a version-skew bug. The update envelope refuses `epoch_id` and
- * `update_encoding` by value for exactly this reason: skew that is not SAID becomes silent loss or
- * a misattributed error.
- */
-export const DOCUMENT_ACK_VERSION = 1;
-/**
- * A rejection reason is peer-controlled text bound for an operator's screen and the policy log.
- * Capped because unbounded peer-controlled display text is not something to hand onward untouched.
- */
-export const MAX_REJECTION_REASON_LENGTH = 200;
-const HEX32 = /^[0-9a-f]{64}$/;
-/**
- * The canonical to-be-signed preimage: a fixed-order CBOR ARRAY with the domain in slot 0.
- *
- * An array rather than a map for the reason `cbor.ts` gives — this encoder is deliberately not
- * deterministic for maps, so a map preimage would make the signature depend on the order the acker
- * happened to build the object in, and two honest implementations would disagree.
- *
- * `rejection_reason` is encoded as `null` when absent rather than omitted, so the slot is always
- * occupied and no field's meaning depends on whether the one before it was present.
- *
- * An earlier version of this comment claimed omission would be "silently absorbed by the next
- * field". That is FALSE for this encoder and worth correcting rather than deleting, because a wrong
- * fact about the wire is what the next structure's justification gets built on: a 6-element array
- * begins `0x86` and a 7-element one `0x87`, so a missing slot is loud, in byte 0. Measured.
- * `cbor.ts` says the same thing — arrays are minimal and order-fixed. The explicit null is still
- * right; the reason is stable slot indices, not collision avoidance.
- */
-export function buildDocumentAckTbs(ack, opts = {}) {
-    assertDocumentAckConsistent(ack);
-    const preimage = encodeCbor([
-        DOCUMENT_ACK_DOMAIN,
-        ack.ack_version,
-        ack.document_id,
-        ack.envelope_hash,
-        ack.acker_agent_id,
-        ack.admitted,
-        normalizeReason(ack.rejection_reason),
-        // BIGINT past 0xffffffff. cbor-x encodes a JS number that large as an IEEE float64 (`fb`)
-        // rather than a uint64 (`1b`) — measured: 1700000000000 gives fb4278bcfe56800000, not
-        // 1b0000018bcfe56800. A millisecond timestamp is always that large, so any implementation
-        // encoding RFC 8949-canonically would compute different TBS bytes and reject a GENUINE ack —
-        // surfacing as a signature failure, which reads as forgery. Three sibling builders carry this
-        // same coercion and primary-transfer.ts names it as a defect it shipped without.
-        typeof ack.acked_at_ms === "number" && ack.acked_at_ms > 0xffffffff
-            ? BigInt(ack.acked_at_ms)
-            : ack.acked_at_ms,
-    ]);
-    if (opts.preHash === false)
-        return preimage;
-    return new Uint8Array(createHash("sha256").update(preimage).digest());
-}
-/** Empty string means ABSENT. See `assertDocumentAckConsistent`. */
-function normalizeReason(reason) {
-    return reason === undefined || reason === "" ? null : reason;
-}
-/**
- * The cross-field rules, checked on ENCODE as well as decode.
- *
- * On encode too, because a locally-built contradictory ack would otherwise be signed and shipped
- * and fail only on the remote decode: the sender sees a silent stall, the peer sees the error, and
- * the two never meet. The rule belongs where the object is built, not only where it is read.
- */
-export function assertDocumentAckConsistent(ack) {
-    const reason = normalizeReason(ack.rejection_reason);
-    if (!ack.admitted && reason === null) {
-        // The sender is being told to stop and supersede. Without the reason it cannot know what to
-        // change — the failure the whole rejection protocol exists to prevent.
-        throw new Error("document_ack_reason: a rejection must carry its reason");
-    }
-    if (ack.admitted && reason !== null) {
-        // A contradiction: whichever field a reader trusts, the other is lying to them.
-        throw new Error(`document_ack_reason: an admission must not carry a rejection reason, and this one carries "${reason}"`);
-    }
-    if (reason !== null && reason.length > MAX_REJECTION_REASON_LENGTH) {
-        throw new Error(`document_ack_reason: a rejection reason may be at most ${MAX_REJECTION_REASON_LENGTH} ` +
-            `characters, and this one is ${reason.length}`);
-    }
-}
-export function encodeDocumentAck(ack) {
-    assertDocumentAckConsistent(ack);
-    return encodeCbor({
-        type: ack.type,
-        ack_version: ack.ack_version,
-        document_id: ack.document_id,
-        envelope_hash: ack.envelope_hash,
-        acker_agent_id: ack.acker_agent_id,
-        admitted: ack.admitted,
-        rejection_reason: normalizeReason(ack.rejection_reason),
-        acked_at_ms: ack.acked_at_ms,
-        signature: ack.signature,
-    });
-}
-function present(map, field) {
-    // `in`, not a nullish check — the same discipline as the update envelope. A defaulted field here
-    // is a claim the acker never made, and this frame's whole job is to carry their claim.
-    if (!(field in map)) {
-        throw new Error(`document_ack_missing_field: ${field} is mandatory and was not present`);
-    }
-    return map[field];
-}
-/**
- * Decode and validate. Refuses rather than defaulting on every field.
- *
- * The one that matters most: `admitted` must be a real boolean. Coerced, a truthy string like
- * `"false"` would settle a REJECTED envelope as admitted — the sender would stop retrying, never
- * roll back, and both parties would believe content was applied that the receiver refused.
- */
-export function decodeDocumentAck(bytes) {
-    const decoded = decodeCbor(bytes);
-    if (typeof decoded !== "object" || decoded === null || Array.isArray(decoded)) {
-        throw new Error("document_ack_malformed: not a CBOR map");
-    }
-    const map = decoded;
-    const type = present(map, "type");
-    if (type !== "document_ack") {
-        throw new Error(`document_ack_type: expected document_ack, got ${String(type)}`);
-    }
-    const version = present(map, "ack_version");
-    if (typeof version !== "number" || !Number.isInteger(version)) {
-        throw new Error("document_ack_version: must be an integer");
-    }
-    if (version !== DOCUMENT_ACK_VERSION) {
-        // Named as SKEW. Without a wire version this frame decoded cleanly and failed signature
-        // verification instead, sending an operator to key management for a version problem.
-        throw new Error(`document_ack_version: this build speaks ack version ${DOCUMENT_ACK_VERSION} and the frame ` +
-            `declares ${version} — one of the two clients needs upgrading`);
-    }
-    const documentId = present(map, "document_id");
-    if (typeof documentId !== "string" || !HEX32.test(documentId)) {
-        throw new Error(`document_ack_document_id: must be a 32-byte hex digest`);
-    }
-    const envelopeHash = present(map, "envelope_hash");
-    if (typeof envelopeHash !== "string" || !HEX32.test(envelopeHash)) {
-        throw new Error("document_ack_envelope_hash: must be a 32-byte hex digest");
-    }
-    const ackerAgentId = present(map, "acker_agent_id");
-    if (typeof ackerAgentId !== "string" || ackerAgentId.length === 0) {
-        throw new Error("document_ack_acker: acker_agent_id must be a non-empty text string");
-    }
-    const admitted = present(map, "admitted");
-    if (typeof admitted !== "boolean") {
-        throw new Error(`document_ack_admitted: must be a boolean, got ${typeof admitted}`);
-    }
-    const rawReason = present(map, "rejection_reason");
-    if (rawReason !== null && typeof rawReason !== "string") {
-        throw new Error("document_ack_reason: rejection_reason must be a text string or explicit null");
-    }
-    // NORMALIZED ONCE, before the cross-field rules. The empty string meant "absent" on the rejection
-    // branch and "present" on the admission branch, so an honest peer written in a language where a
-    // non-nullable string field defaults to "" — Go, Rust — had its ADMISSION refused as a
-    // contradiction it never expressed. The sender then never settles, retries to the unacked
-    // ceiling, and the document stalls: precisely the failure this frame exists to end.
-    const reason = rawReason === "" ? null : rawReason;
-    const ackedAt = present(map, "acked_at_ms");
-    // BOUNDED. `Number.isInteger(1e300)` is true, and this is the only field available to order two
-    // conflicting acks — leaving it unbounded hands that tiebreak to an attacker-chosen value.
-    if (typeof ackedAt !== "number" || !Number.isSafeInteger(ackedAt) || ackedAt <= 0) {
-        throw new Error(`document_ack_time: acked_at_ms must be a positive safe integer, got ${String(ackedAt)}`);
-    }
-    const signature = present(map, "signature");
-    if (!(signature instanceof Uint8Array)) {
-        throw new Error("document_ack_signature: must be a CBOR byte string");
-    }
-    const ack = {
-        type: "document_ack",
-        ack_version: version,
-        document_id: documentId,
-        envelope_hash: envelopeHash,
-        acker_agent_id: ackerAgentId,
-        admitted,
-        ...(reason === null ? {} : { rejection_reason: reason }),
-        acked_at_ms: ackedAt,
-        // COPIED — cbor-x returns byte strings as views into the buffer it decoded, so a caller reusing
-        // a pooled read buffer would have the signature change after it was verified.
-        signature: new Uint8Array(signature),
-    };
-    // The same cross-field rules the encoder applies. One implementation, so the two surfaces cannot
-    // drift into disagreeing about what a valid ack is.
-    assertDocumentAckConsistent(ack);
-    return ack;
-}
-//# sourceMappingURL=document-ack.js.map

package/dist/document-ack.js.map

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

package/dist/document-control.d.ts

@@ -1,74 +0,0 @@
-/**
- * DOD-DOC-TOOLS-1 — the document CONTROL frame: close and kill (§16.5).
- *
- * A unilateral end, told to the other party.
- *
- * ── WHY THE PEER MUST BE TOLD, AND WHY IT IS BEST-EFFORT ──────────────────────────────────────
- *
- * `DocumentLifecycle` already ends a document locally without asking anyone — that is deliberate: a
- * kill is a safety verb, and a safety verb that needs the counterparty's cooperation is not one. But
- * a peer who is never told keeps publishing into a document that will never answer. Their updates
- * are refused at the far end forever, and nothing on their screen explains why. So the notification
- * is REQUIRED to be attempted and ALLOWED to fail, and the operator is told which happened.
- *
- * ── CLOSE AND KILL ARE DIFFERENT FRAMES OF THE SAME SHAPE ─────────────────────────────────────
- *
- * `close` is "I am done with this, and I expect you are too" — the document settles when both sides
- * have said it. `kill` is "this is over now", one-sided and immediate. They travel as one frame with
- * a verb rather than two types because the receiving side's routing, verification and settle-once
- * rules are identical, and two decoders for one shape is how the rules drift apart.
- *
- * The verb is REFUSED BY VALUE on decode. A third verb from a future build must not be admitted as
- * one of these two — a `kill` silently read as a `close` would leave a killed document waiting for
- * a reciprocal close that is never coming.
- *
- * ── WHY IT IS SIGNED ──────────────────────────────────────────────────────────────────────────
- *
- * 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. The signature
- * covers the document id — which commits to both parties, the properties and the nonce — and the
- * verb, because the whole statement is the claim.
- */
-/** Domain tag in slot 0. Distinct from every other document domain. */
-export declare const DOCUMENT_CONTROL_DOMAIN = "CELLO-DOCUMENT-CONTROL-v1";
-/** The frame version, ON THE WIRE, so skew is DETECTED rather than misread as a bad signature. */
-export declare const DOCUMENT_CONTROL_VERSION = 1;
-/** Peer-controlled display text bound for an operator's screen. Capped for that reason. */
-export declare const MAX_CONTROL_REASON_LENGTH = 200;
-/** The two ways a document ends. Closed set — see the header on refusing a third by value. */
-export declare const DOCUMENT_CONTROL_VERBS: readonly ["close", "kill"];
-export type DocumentControlVerb = (typeof DOCUMENT_CONTROL_VERBS)[number];
-export interface DocumentControl {
-    type: "document_control";
-    control_version: number;
-    document_id: string;
-    /** Who is ending it. */
-    sender_agent_id: string;
-    verb: DocumentControlVerb;
-    /** Optional, and optional for both verbs — an end is a decision, not something one must justify. */
-    reason?: string;
-    sent_at_ms: number;
-    /** Ed25519 (RFC 8032) over `buildDocumentControlTbs`. */
-    signature: Uint8Array;
-}
-export declare function assertDocumentControlConsistent(control: DocumentControl): void;
-/**
- * The canonical to-be-signed preimage: a fixed-order CBOR ARRAY with the domain in slot 0.
- *
- * An array rather than a map for the reason `cbor.ts` gives — this encoder is deliberately not
- * deterministic for maps, so a map preimage would make the signature depend on the order the sender
- * happened to build the object in, and two honest implementations would disagree.
- */
-export declare function buildDocumentControlTbs(control: DocumentControl, opts?: {
-    preHash?: boolean;
-}): Uint8Array;
-export declare function encodeDocumentControl(control: DocumentControl): Uint8Array;
-/**
- * Decode and validate. Refuses rather than defaulting on every field.
- *
- * The one that matters most is `verb`. Defaulted or coerced, a `kill` read as a `close` leaves a
- * killed document waiting for a reciprocal close that is never coming — the operator sees a
- * collaboration that will not settle and no reason anywhere for why.
- */
-export declare function decodeDocumentControl(bytes: Uint8Array): DocumentControl;
-//# sourceMappingURL=document-control.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"document-control.d.ts","sourceRoot":"","sources":["../src/document-control.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAKH,uEAAuE;AACvE,eAAO,MAAM,uBAAuB,8BAA8B,CAAC;AAEnE,kGAAkG;AAClG,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C,2FAA2F;AAC3F,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAE7C,8FAA8F;AAC9F,eAAO,MAAM,sBAAsB,4BAA6B,CAAC;AACjE,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAI1E,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,kBAAkB,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,wBAAwB;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,IAAI,EAAE,mBAAmB,CAAC;IAC1B,oGAAoG;IACpG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,SAAS,EAAE,UAAU,CAAC;CACvB;AAMD,wBAAgB,+BAA+B,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAgB9E;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,eAAe,EACxB,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GAC/B,UAAU,CAoBZ;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,eAAe,GAAG,UAAU,CAY1E;AASD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,UAAU,GAAG,eAAe,CAiExE"}

package/dist/document-control.js

@@ -1,174 +0,0 @@
-/**
- * DOD-DOC-TOOLS-1 — the document CONTROL frame: close and kill (§16.5).
- *
- * A unilateral end, told to the other party.
- *
- * ── WHY THE PEER MUST BE TOLD, AND WHY IT IS BEST-EFFORT ──────────────────────────────────────
- *
- * `DocumentLifecycle` already ends a document locally without asking anyone — that is deliberate: a
- * kill is a safety verb, and a safety verb that needs the counterparty's cooperation is not one. But
- * a peer who is never told keeps publishing into a document that will never answer. Their updates
- * are refused at the far end forever, and nothing on their screen explains why. So the notification
- * is REQUIRED to be attempted and ALLOWED to fail, and the operator is told which happened.
- *
- * ── CLOSE AND KILL ARE DIFFERENT FRAMES OF THE SAME SHAPE ─────────────────────────────────────
- *
- * `close` is "I am done with this, and I expect you are too" — the document settles when both sides
- * have said it. `kill` is "this is over now", one-sided and immediate. They travel as one frame with
- * a verb rather than two types because the receiving side's routing, verification and settle-once
- * rules are identical, and two decoders for one shape is how the rules drift apart.
- *
- * The verb is REFUSED BY VALUE on decode. A third verb from a future build must not be admitted as
- * one of these two — a `kill` silently read as a `close` would leave a killed document waiting for
- * a reciprocal close that is never coming.
- *
- * ── WHY IT IS SIGNED ──────────────────────────────────────────────────────────────────────────
- *
- * 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. The signature
- * covers the document id — which commits to both parties, the properties and the nonce — and the
- * verb, because the whole statement is the claim.
- */
-import { createHash } from "node:crypto";
-import { encodeCbor, decodeCbor } from "./cbor.js";
-/** Domain tag in slot 0. Distinct from every other document domain. */
-export const DOCUMENT_CONTROL_DOMAIN = "CELLO-DOCUMENT-CONTROL-v1";
-/** The frame version, ON THE WIRE, so skew is DETECTED rather than misread as a bad signature. */
-export const DOCUMENT_CONTROL_VERSION = 1;
-/** Peer-controlled display text bound for an operator's screen. Capped for that reason. */
-export const MAX_CONTROL_REASON_LENGTH = 200;
-/** The two ways a document ends. Closed set — see the header on refusing a third by value. */
-export const DOCUMENT_CONTROL_VERBS = ["close", "kill"];
-const HEX32 = /^[0-9a-f]{64}$/;
-function normalizeReason(reason) {
-    return reason === undefined || reason === "" ? null : reason;
-}
-export function assertDocumentControlConsistent(control) {
-    if (!DOCUMENT_CONTROL_VERBS.includes(control.verb)) {
-        throw new Error(`document_control_verb: expected one of ${DOCUMENT_CONTROL_VERBS.join(", ")}, got "${control.verb}"`);
-    }
-    if (!HEX32.test(control.document_id)) {
-        throw new Error("document_control_document_id: expected 64 lowercase hex characters");
-    }
-    const reason = normalizeReason(control.reason);
-    if (reason !== null && reason.length > MAX_CONTROL_REASON_LENGTH) {
-        throw new Error(`document_control_reason: a reason may be at most ${MAX_CONTROL_REASON_LENGTH} characters, ` +
-            `and this one is ${reason.length}`);
-    }
-}
-/**
- * The canonical to-be-signed preimage: a fixed-order CBOR ARRAY with the domain in slot 0.
- *
- * An array rather than a map for the reason `cbor.ts` gives — this encoder is deliberately not
- * deterministic for maps, so a map preimage would make the signature depend on the order the sender
- * happened to build the object in, and two honest implementations would disagree.
- */
-export function buildDocumentControlTbs(control, opts = {}) {
-    assertDocumentControlConsistent(control);
-    const preimage = encodeCbor([
-        DOCUMENT_CONTROL_DOMAIN,
-        control.control_version,
-        control.document_id,
-        control.sender_agent_id,
-        // THE VERB IS SIGNED. Unsigned, a captured `close` could be replayed as a `kill` — the peer
-        // would end a collaboration the sender only meant to wind down, with a valid signature on it.
-        control.verb,
-        normalizeReason(control.reason),
-        // BIGINT past 0xffffffff — cbor-x encodes a large JS number as IEEE float64 (`fb`) rather than
-        // uint64 (`1b`), so a canonically-encoding implementation would compute different TBS bytes and
-        // reject a GENUINE frame, surfacing as a signature failure that reads as forgery.
-        typeof control.sent_at_ms === "number" && control.sent_at_ms > 0xffffffff
-            ? BigInt(control.sent_at_ms)
-            : control.sent_at_ms,
-    ]);
-    if (opts.preHash === false)
-        return preimage;
-    return new Uint8Array(createHash("sha256").update(preimage).digest());
-}
-export function encodeDocumentControl(control) {
-    assertDocumentControlConsistent(control);
-    return encodeCbor({
-        type: control.type,
-        control_version: control.control_version,
-        document_id: control.document_id,
-        sender_agent_id: control.sender_agent_id,
-        verb: control.verb,
-        reason: normalizeReason(control.reason),
-        sent_at_ms: control.sent_at_ms,
-        signature: control.signature,
-    });
-}
-function present(map, field) {
-    if (!(field in map)) {
-        throw new Error(`document_control_missing_field: ${field} is mandatory and was not present`);
-    }
-    return map[field];
-}
-/**
- * Decode and validate. Refuses rather than defaulting on every field.
- *
- * The one that matters most is `verb`. Defaulted or coerced, a `kill` read as a `close` leaves a
- * killed document waiting for a reciprocal close that is never coming — the operator sees a
- * collaboration that will not settle and no reason anywhere for why.
- */
-export function decodeDocumentControl(bytes) {
-    const decoded = decodeCbor(bytes);
-    if (typeof decoded !== "object" || decoded === null || Array.isArray(decoded)) {
-        throw new Error("document_control_malformed: not a CBOR map");
-    }
-    const map = decoded;
-    if (present(map, "type") !== "document_control") {
-        throw new Error("document_control_type: expected document_control");
-    }
-    const version = present(map, "control_version");
-    if (typeof version !== "number" || !Number.isInteger(version)) {
-        throw new Error("document_control_version: must be an integer");
-    }
-    if (version !== DOCUMENT_CONTROL_VERSION) {
-        throw new Error(`document_control_version_unsupported: this build speaks version ${DOCUMENT_CONTROL_VERSION} ` +
-            `and the frame declares ${version} — the peer is running a newer CELLO and one of you needs ` +
-            `to upgrade`);
-    }
-    const documentId = present(map, "document_id");
-    if (typeof documentId !== "string" || !HEX32.test(documentId)) {
-        throw new Error("document_control_document_id: expected 64 lowercase hex characters");
-    }
-    const senderAgentId = present(map, "sender_agent_id");
-    if (typeof senderAgentId !== "string" || senderAgentId.length === 0) {
-        throw new Error("document_control_sender: must be a non-empty string");
-    }
-    const verb = present(map, "verb");
-    if (typeof verb !== "string" || !DOCUMENT_CONTROL_VERBS.includes(verb)) {
-        // REFUSED BY VALUE. A third verb from a future build must not be admitted as one of these two.
-        throw new Error(`document_control_verb_unsupported: this build understands ` +
-            `${DOCUMENT_CONTROL_VERBS.join(" and ")}, and the frame says "${String(verb)}" — the peer is ` +
-            `running a newer CELLO and one of you needs to upgrade`);
-    }
-    const reason = present(map, "reason");
-    if (reason !== null && typeof reason !== "string") {
-        throw new Error("document_control_reason: must be a string or null");
-    }
-    const sentAt = present(map, "sent_at_ms");
-    if (typeof sentAt !== "number" || !Number.isFinite(sentAt)) {
-        throw new Error("document_control_sent_at: must be a finite number");
-    }
-    const signature = present(map, "signature");
-    if (!(signature instanceof Uint8Array) || signature.length !== 64) {
-        throw new Error("document_control_signature: expected 64 bytes");
-    }
-    const control = {
-        type: "document_control",
-        control_version: version,
-        document_id: documentId,
-        sender_agent_id: senderAgentId,
-        verb: verb,
-        ...(reason !== null && reason !== "" ? { reason } : {}),
-        sent_at_ms: sentAt,
-        // COPIED out of the decode buffer — cbor-x returns byte strings as VIEWS into the input, so
-        // retaining one pins the whole frame and lets a later reuse mutate a verified signature.
-        signature: Uint8Array.from(signature),
-    };
-    assertDocumentControlConsistent(control);
-    return control;
-}
-//# sourceMappingURL=document-control.js.map

package/dist/document-control.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"document-control.js","sourceRoot":"","sources":["../src/document-control.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAEnD,uEAAuE;AACvE,MAAM,CAAC,MAAM,uBAAuB,GAAG,2BAA2B,CAAC;AAEnE,kGAAkG;AAClG,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC;AAE1C,2FAA2F;AAC3F,MAAM,CAAC,MAAM,yBAAyB,GAAG,GAAG,CAAC;AAE7C,8FAA8F;AAC9F,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,OAAO,EAAE,MAAM,CAAU,CAAC;AAGjE,MAAM,KAAK,GAAG,gBAAgB,CAAC;AAgB/B,SAAS,eAAe,CAAC,MAA0B;IACjD,OAAO,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC;AAC/D,CAAC;AAED,MAAM,UAAU,+BAA+B,CAAC,OAAwB;IACtE,IAAI,CAAE,sBAA4C,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1E,MAAM,IAAI,KAAK,CACb,0CAA0C,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,OAAO,CAAC,IAAI,GAAG,CACrG,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CAAC,oEAAoE,CAAC,CAAC;IACxF,CAAC;IACD,MAAM,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/C,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,CAAC,MAAM,GAAG,yBAAyB,EAAE,CAAC;QACjE,MAAM,IAAI,KAAK,CACb,oDAAoD,yBAAyB,eAAe;YAC1F,mBAAmB,MAAM,CAAC,MAAM,EAAE,CACrC,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CACrC,OAAwB,EACxB,OAA8B,EAAE;IAEhC,+BAA+B,CAAC,OAAO,CAAC,CAAC;IACzC,MAAM,QAAQ,GAAG,UAAU,CAAC;QAC1B,uBAAuB;QACvB,OAAO,CAAC,eAAe;QACvB,OAAO,CAAC,WAAW;QACnB,OAAO,CAAC,eAAe;QACvB,4FAA4F;QAC5F,8FAA8F;QAC9F,OAAO,CAAC,IAAI;QACZ,eAAe,CAAC,OAAO,CAAC,MAAM,CAAC;QAC/B,+FAA+F;QAC/F,gGAAgG;QAChG,kFAAkF;QAClF,OAAO,OAAO,CAAC,UAAU,KAAK,QAAQ,IAAI,OAAO,CAAC,UAAU,GAAG,UAAU;YACvE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC;YAC5B,CAAC,CAAC,OAAO,CAAC,UAAU;KACvB,CAAC,CAAC;IACH,IAAI,IAAI,CAAC,OAAO,KAAK,KAAK;QAAE,OAAO,QAAQ,CAAC;IAC5C,OAAO,IAAI,UAAU,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;AACxE,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,OAAwB;IAC5D,+BAA+B,CAAC,OAAO,CAAC,CAAC;IACzC,OAAO,UAAU,CAAC;QAChB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,eAAe,EAAE,OAAO,CAAC,eAAe;QACxC,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,eAAe,EAAE,OAAO,CAAC,eAAe;QACxC,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,MAAM,EAAE,eAAe,CAAC,OAAO,CAAC,MAAM,CAAC;QACvC,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,SAAS,EAAE,OAAO,CAAC,SAAS;KAC7B,CAAC,CAAC;AACL,CAAC;AAED,SAAS,OAAO,CAAC,GAA4B,EAAE,KAAa;IAC1D,IAAI,CAAC,CAAC,KAAK,IAAI,GAAG,CAAC,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CAAC,mCAAmC,KAAK,mCAAmC,CAAC,CAAC;IAC/F,CAAC;IACD,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC;AACpB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAiB;IACrD,MAAM,OAAO,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;IAClC,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QAC9E,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;IAChE,CAAC;IACD,MAAM,GAAG,GAAG,OAAkC,CAAC;IAE/C,IAAI,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,kBAAkB,EAAE,CAAC;QAChD,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;IACtE,CAAC;IACD,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAC;IAChD,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;QAC9D,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;IAClE,CAAC;IACD,IAAI,OAAO,KAAK,wBAAwB,EAAE,CAAC;QACzC,MAAM,IAAI,KAAK,CACb,mEAAmE,wBAAwB,GAAG;YAC5F,0BAA0B,OAAO,4DAA4D;YAC7F,YAAY,CACf,CAAC;IACJ,CAAC;IACD,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,EAAE,aAAa,CAAC,CAAC;IAC/C,IAAI,OAAO,UAAU,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;QAC9D,MAAM,IAAI,KAAK,CAAC,oEAAoE,CAAC,CAAC;IACxF,CAAC;IACD,MAAM,aAAa,GAAG,OAAO,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAC;IACtD,IAAI,OAAO,aAAa,KAAK,QAAQ,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpE,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IACzE,CAAC;IACD,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAClC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAE,sBAA4C,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9F,+FAA+F;QAC/F,MAAM,IAAI,KAAK,CACb,4DAA4D;YAC1D,GAAG,sBAAsB,CAAC,IAAI,CAAC,OAAO,CAAC,yBAAyB,MAAM,CAAC,IAAI,CAAC,kBAAkB;YAC9F,uDAAuD,CAC1D,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IACtC,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAClD,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;IACvE,CAAC;IACD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;IAC1C,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;IACvE,CAAC;IACD,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;IAC5C,IAAI,CAAC,CAAC,SAAS,YAAY,UAAU,CAAC,IAAI,SAAS,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;QAClE,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;IACnE,CAAC;IAED,MAAM,OAAO,GAAoB;QAC/B,IAAI,EAAE,kBAAkB;QACxB,eAAe,EAAE,OAAO;QACxB,WAAW,EAAE,UAAU;QACvB,eAAe,EAAE,aAAa;QAC9B,IAAI,EAAE,IAA2B;QACjC,GAAG,CAAC,MAAM,KAAK,IAAI,IAAI,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvD,UAAU,EAAE,MAAM;QAClB,4FAA4F;QAC5F,yFAAyF;QACzF,SAAS,EAAE,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC;KACtC,CAAC;IACF,+BAA+B,CAAC,OAAO,CAAC,CAAC;IACzC,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/document-join-answer.d.ts

@@ -1,34 +0,0 @@
-/**
- * DOD-MP-JOIN-1 — the invitee's ANSWER to a join offer: a signed, settle-once fact.
- *
- * Keyed on the ADMITTING AMENDMENT'S HASH — the amendment is what the invitee answers, and a
- * re-invitation after a refusal is a new amendment with a new hash, so two answers can never be
- * confused. Its own frame for the proposal-ack reason: a join offer is not in the envelope log,
- * so `document_ack` would settle a hash of nothing.
- *
- * Consent is local and final the moment the operator makes it; sending the answer is
- * best-effort, and an unreachable inviter gets no veto over the invitee's choice — the same
- * doctrine as the proposal ack.
- */
-/** Domain tag in slot 0 of the to-be-signed array. */
-export declare const DOCUMENT_JOIN_ANSWER_DOMAIN = "CELLO-DOCUMENT-JOIN-ANSWER-v1";
-export declare const MAX_JOIN_REFUSAL_REASON_LENGTH = 512;
-export interface DocumentJoinAnswer {
-    type: "document_join_answer";
-    document_id: string;
-    /** Hex hash of the admitting `add_holder` amendment — the settle key. */
-    amendment_hash: string;
-    invitee_agent_id: string;
-    accepted: boolean;
-    /** Operator prose on a refusal; explicit null on an accept — never absent. */
-    refusal_reason: string | null;
-    answered_at_ms: number;
-    /** Ed25519 (RFC 8032) by the invitee over `buildDocumentJoinAnswerTbs`. */
-    signature: Uint8Array;
-}
-export declare function buildDocumentJoinAnswerTbs(answer: DocumentJoinAnswer, opts?: {
-    preHash?: boolean;
-}): Uint8Array;
-export declare function encodeDocumentJoinAnswer(answer: DocumentJoinAnswer): Uint8Array;
-export declare function decodeDocumentJoinAnswer(input: Uint8Array): DocumentJoinAnswer;
-//# sourceMappingURL=document-join-answer.d.ts.map

package/dist/document-join-answer.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"document-join-answer.d.ts","sourceRoot":"","sources":["../src/document-join-answer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,sDAAsD;AACtD,eAAO,MAAM,2BAA2B,kCAAkC,CAAC;AAE3E,eAAO,MAAM,8BAA8B,MAAM,CAAC;AAElD,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,sBAAsB,CAAC;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE,OAAO,CAAC;IAClB,8EAA8E;IAC9E,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,2EAA2E;IAC3E,SAAS,EAAE,UAAU,CAAC;CACvB;AAED,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,kBAAkB,EAC1B,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GAC/B,UAAU,CAcZ;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,kBAAkB,GAAG,UAAU,CAW/E;AAiBD,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,UAAU,GAAG,kBAAkB,CA8C9E"}

package/dist/document-join-answer.js

@@ -1,100 +0,0 @@
-/**
- * DOD-MP-JOIN-1 — the invitee's ANSWER to a join offer: a signed, settle-once fact.
- *
- * Keyed on the ADMITTING AMENDMENT'S HASH — the amendment is what the invitee answers, and a
- * re-invitation after a refusal is a new amendment with a new hash, so two answers can never be
- * confused. Its own frame for the proposal-ack reason: a join offer is not in the envelope log,
- * so `document_ack` would settle a hash of nothing.
- *
- * Consent is local and final the moment the operator makes it; sending the answer is
- * best-effort, and an unreachable inviter gets no veto over the invitee's choice — the same
- * doctrine as the proposal ack.
- */
-import { createHash } from "node:crypto";
-import { encodeCbor, decodeCbor } from "./cbor.js";
-/** Domain tag in slot 0 of the to-be-signed array. */
-export const DOCUMENT_JOIN_ANSWER_DOMAIN = "CELLO-DOCUMENT-JOIN-ANSWER-v1";
-export const MAX_JOIN_REFUSAL_REASON_LENGTH = 512;
-export function buildDocumentJoinAnswerTbs(answer, opts = {}) {
-    const preimage = encodeCbor([
-        DOCUMENT_JOIN_ANSWER_DOMAIN,
-        answer.document_id,
-        answer.amendment_hash,
-        answer.invitee_agent_id,
-        answer.accepted,
-        answer.refusal_reason,
-        typeof answer.answered_at_ms === "number" && answer.answered_at_ms > 0xffffffff
-            ? BigInt(answer.answered_at_ms)
-            : answer.answered_at_ms,
-    ]);
-    if (opts.preHash === false)
-        return preimage;
-    return new Uint8Array(createHash("sha256").update(preimage).digest());
-}
-export function encodeDocumentJoinAnswer(answer) {
-    return encodeCbor({
-        type: answer.type,
-        document_id: answer.document_id,
-        amendment_hash: answer.amendment_hash,
-        invitee_agent_id: answer.invitee_agent_id,
-        accepted: answer.accepted,
-        refusal_reason: answer.refusal_reason,
-        answered_at_ms: answer.answered_at_ms,
-        signature: answer.signature,
-    });
-}
-function present(map, field) {
-    if (!(field in map)) {
-        throw new Error(`document_join_answer_missing_field: ${field} is mandatory and was not present`);
-    }
-    return map[field];
-}
-function str(map, field) {
-    const v = present(map, field);
-    if (typeof v !== "string" || v.length === 0) {
-        throw new Error(`document_join_answer_field_type: ${field} must be a non-empty text string`);
-    }
-    return v;
-}
-export function decodeDocumentJoinAnswer(input) {
-    const decoded = decodeCbor(input);
-    if (typeof decoded !== "object" || decoded === null || Array.isArray(decoded)) {
-        throw new Error("document_join_answer_malformed: not a CBOR map");
-    }
-    const map = decoded;
-    const type = str(map, "type");
-    if (type !== "document_join_answer") {
-        throw new Error(`document_join_answer_type: expected document_join_answer, got ${type}`);
-    }
-    const accepted = present(map, "accepted");
-    if (typeof accepted !== "boolean") {
-        throw new Error("document_join_answer_field_type: accepted must be a boolean — consent is never inferred " +
-            "from a truthy value");
-    }
-    const reason = present(map, "refusal_reason");
-    if (reason !== null && typeof reason !== "string") {
-        throw new Error("document_join_answer_field_type: refusal_reason must be a text string or explicit null");
-    }
-    if (typeof reason === "string" && reason.length > MAX_JOIN_REFUSAL_REASON_LENGTH) {
-        throw new Error(`document_join_answer_field_type: refusal_reason exceeds ${MAX_JOIN_REFUSAL_REASON_LENGTH} chars`);
-    }
-    const answeredAt = present(map, "answered_at_ms");
-    if (typeof answeredAt !== "number" || !Number.isInteger(answeredAt)) {
-        throw new Error("document_join_answer_field_type: answered_at_ms must be an integer");
-    }
-    const signature = present(map, "signature");
-    if (!(signature instanceof Uint8Array)) {
-        throw new Error("document_join_answer_field_type: signature must be a CBOR byte string");
-    }
-    return {
-        type: "document_join_answer",
-        document_id: str(map, "document_id"),
-        amendment_hash: str(map, "amendment_hash"),
-        invitee_agent_id: str(map, "invitee_agent_id"),
-        accepted,
-        refusal_reason: reason,
-        answered_at_ms: answeredAt,
-        signature: new Uint8Array(signature),
-    };
-}
-//# sourceMappingURL=document-join-answer.js.map