@joe-broadhead/messaging 0.7.1 → 0.9.0

package/dist/lib/modules/core/conversation/request-log.js

@@ -0,0 +1,158 @@
+/** Permanent request activation and import reservations, replayed alongside ConvLog (spec §16.11). */
+import { b64u } from "../b64u.js";
+import { canonicalize } from "../jcs.js";
+import { parseWith } from "../check.js";
+import { RequestImport } from "../schema/contact-request.js";
+import { MessagingError } from "../schema/errors.js";
+import { convEventDigest, verifyConvEvent } from "./event.js";
+import { verifyContactAuthorization, verifyPortableRequest, verifyRequestActivation } from "./requests.js";
+const refuse = (message) => { throw new MessagingError("request_required", message); };
+const conflict = (message) => { throw new MessagingError("conv_conflict", message); };
+const digest = (event) => b64u.encode(convEventDigest(event));
+function proofFor(log, proof, binding) {
+    const state = log.state();
+    if (state?.kind !== "dm" || state.participants.length !== 2 || state.participants.some((p) => p.agent !== undefined))
+        refuse("activation is for a two-person DM");
+    const persons = state.participants.map((p) => p.person).sort();
+    const check = (p) => {
+        if (p.realm !== log.realm || p.cid !== log.cid || canonicalize([p.from, p.to].sort()) !== canonicalize(persons))
+            conflict("activation names another DM");
+    };
+    if ("contacts" in proof) {
+        const a = verifyContactAuthorization(proof.contacts[0], binding), b = verifyContactAuthorization(proof.contacts[1], binding);
+        check(a);
+        check(b);
+        if (a.from !== b.to || a.to !== b.from)
+            refuse("both contacts must authorize the DM");
+        return undefined;
+    }
+    const request = verifyRequestActivation(proof, binding);
+    check(request.descriptor);
+    return request;
+}
+/** Rebuilds permanent activation state even when imported messages have expired. */
+export function requestLogState(log, binding) {
+    const entries = log.entries();
+    const first = entries[0];
+    const required = !!first && "event" in first && first.event.class === "op" && first.event.body.op === "create" && first.event.body.admission === "request";
+    const state = { required, active: !required, reservations: new Map() };
+    for (const entry of entries) {
+        if (!("event" in entry) || entry.event.class !== "op" || log.at(entry.seq)?.changed !== entry.seq)
+            continue;
+        const op = entry.event.body;
+        if (op.op === "activate") {
+            if (!required)
+                refuse("this conversation has no request admission");
+            const p = proofFor(log, op.proof, binding);
+            state.active = true;
+            if (p) {
+                const old = state.reservations.get(p.descriptor.id);
+                if (old && canonicalize(old.proof) !== canonicalize(p))
+                    conflict("request activation conflicts with its reservation");
+                if (!old)
+                    state.reservations.set(p.descriptor.id, { proof: p });
+            }
+        }
+        else if (op.op === "request.complete") {
+            const reservation = state.reservations.get(op.request);
+            if (!reservation || reservation.completed)
+                conflict("request completion has no pending reservation");
+            if (entry.event.by.person !== reservation.proof.descriptor.to || entry.event.by.agent !== undefined)
+                refuse("only the accepting person completes an import");
+            const imported = entries[op.seq - 1];
+            if (!imported || op.seq >= entry.seq)
+                conflict("completion must name an earlier import");
+            if ("event" in imported) {
+                const e = imported.event;
+                if (e.class !== "msg" || e.id !== op.request || e.request !== op.request || e.by.person !== reservation.proof.descriptor.to || e.by.agent !== undefined)
+                    conflict("completion names another event");
+            }
+            if (("event" in imported ? digest(imported.event) : imported.digest) !== op.digest)
+                conflict("completion digest does not match the log");
+            reservation.completed = { seq: op.seq, digest: op.digest };
+        }
+    }
+    return state;
+}
+/** Checks before appending. The relay also checks live org admission on create. No mutation on failure. */
+export function checkRequestEvent(log, raw, binding, body) {
+    const event = verifyConvEvent(raw);
+    if (event.realm !== log.realm || event.cid !== log.cid)
+        throw new MessagingError("invalid_request", "request event names another conversation");
+    if (event.class === "op" && event.body.op === "create") {
+        if (event.body.admission && (event.body.kind !== "dm" || event.body.participants.some((p) => p.p.includes("/"))))
+            refuse("request admission is for human DMs only");
+        return;
+    }
+    const s = requestLogState(log, binding);
+    if (event.class === "op" && event.body.op === "activate") {
+        if (!s.required || event.by.agent !== undefined)
+            refuse("activation requires a person's request DM");
+        const p = proofFor(log, event.body.proof, binding);
+        if (p) {
+            if (event.by.person !== p.descriptor.to)
+                refuse("the accepting person activates the request");
+            const old = s.reservations.get(p.descriptor.id);
+            if (old)
+                conflict("this request already has a permanent activation");
+            if (log.entries().some((e) => "event" in e && e.event.id === p.descriptor.id))
+                conflict("request id collides with an existing event");
+        }
+        return;
+    }
+    const deviceControl = event.class === "op" && event.body.op === "rekey" && event.body.cause === "device";
+    if (!s.active && !deviceControl)
+        refuse("accept the contact request before content or key sharing");
+    const pending = [...s.reservations].filter(([, r]) => !r.completed);
+    if (event.class === "keys")
+        return;
+    if (event.class === "op" && event.body.op === "request.complete") {
+        const op = event.body, r = s.reservations.get(op.request);
+        if (!r || r.completed || event.by.person !== r.proof.descriptor.to || event.by.agent !== undefined)
+            conflict("no pending import for this recipient");
+        const e = log.entries()[op.seq - 1];
+        if (!e || ("event" in e ? e.event.class !== "msg" || e.event.request !== op.request || e.event.id !== op.request || digest(e.event) !== op.digest : e.digest !== op.digest))
+            conflict("completion does not bind the imported event");
+        return;
+    }
+    if (event.class === "msg" && event.request !== undefined) {
+        const r = s.reservations.get(event.request);
+        if (!r || r.completed || event.id !== event.request || event.by.person !== r.proof.descriptor.to || event.by.agent !== undefined || event.wake !== undefined)
+            refuse("no accepted import reservation for this author");
+        if (body !== undefined) {
+            const p = parseWith(RequestImport, body, "request import");
+            verifyPortableRequest({ descriptor: p.descriptor, opening: p.opening }, binding);
+            verifyRequestActivation({ descriptor: p.descriptor, decision: p.decision }, binding);
+            if (canonicalize({ descriptor: p.descriptor, decision: p.decision }) !== canonicalize(r.proof))
+                conflict("import differs from the permanent activation");
+        }
+        return;
+    }
+    if (s.reservations.has(event.id))
+        conflict("the request id is reserved for its import");
+    if (pending.length && !deviceControl)
+        refuse("accepted first messages must finish importing before ordinary sends");
+    if (body && typeof body === "object" && "t" in body) {
+        const b = body;
+        if (b.t === "request.import")
+            refuse("request imports require a reserved header");
+        if ((b.t === "edit" || b.t === "delete") && s.reservations.has(b.target)) {
+            if (b.t === "edit")
+                throw new MessagingError("forbidden", "an imported request is immutable");
+            if (event.by.agent !== undefined || event.by.person !== s.reservations.get(b.target).proof.descriptor.from)
+                throw new MessagingError("forbidden", "only the original author deletes a request import");
+        }
+    }
+}
+/** Member admission seam for the cut-over engine; preserves wrapper authorship and verifies source separately. */
+export function applyRequestEntry(log, entry, binding, options = {}) {
+    checkRequestEvent(log, entry.event, binding, options.body);
+    const body = options.body;
+    // ConvLog's line author is the wrapper author. Source attribution/deletion comes only from verified proofs.
+    const imported = body?.t === "request.import" || (body?.t === "delete" && requestLogState(log, binding).reservations.has(body.target));
+    return log.apply(entry, imported ? { ...options, body: undefined } : options);
+}
+/** Public author for a verified import, never the importing device. The renderer uses this only after admission. */
+export function importedRequestAuthor(log, id, binding) {
+    return requestLogState(log, binding).reservations.get(id)?.proof.descriptor.from;
+}

package/dist/lib/modules/core/conversation/request-seal.js

@@ -0,0 +1,41 @@
+/** The request.import profile uses the conversation sender-key seal, with its own strict plaintext schema. */
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import { b64u } from "../b64u.js";
+import { asMessagingError, parseWith } from "../check.js";
+import { canonicalize } from "../jcs.js";
+import { RequestImport } from "../schema/contact-request.js";
+import { MessagingError } from "../schema/errors.js";
+import { parseWire } from "../wire.js";
+import { convEventHeader, signConvEvent, verifyConvEvent } from "./event.js";
+export function sealRequestImport(identity, header, body, mk) {
+    try {
+        const value = parseWith(RequestImport, body, "request import");
+        if (header.request !== value.descriptor.id || header.id !== header.request || header.by.person !== value.descriptor.to || header.by.agent !== undefined || header.wake !== undefined)
+            throw new MessagingError("invalid_request", "import header does not bind its recipient and reservation");
+        const nonce = randomBytes(12), cipher = createCipheriv("aes-256-gcm", mk, nonce);
+        cipher.setAAD(Buffer.from(canonicalize(header)));
+        const sealed = Buffer.concat([nonce, cipher.update(canonicalize(value), "utf8"), cipher.final(), cipher.getAuthTag()]);
+        return signConvEvent(identity, { ...header, body: b64u.encode(sealed) });
+    }
+    catch (error) {
+        throw asMessagingError(error, "request import seal");
+    }
+}
+export function openRequestImport(raw, mk) {
+    try {
+        const event = verifyConvEvent(raw);
+        if (event.class !== "msg" || !event.request)
+            throw new MessagingError("invalid_request", "not a reserved request import");
+        const data = b64u.decode(event.body);
+        if (data.length > 8192)
+            throw new MessagingError("too_large", "request import too large");
+        const decipher = createDecipheriv("aes-256-gcm", mk, data.subarray(0, 12));
+        decipher.setAAD(Buffer.from(canonicalize(convEventHeader(event))));
+        decipher.setAuthTag(data.subarray(-16));
+        const bytes = Buffer.concat([decipher.update(data.subarray(12, -16)), decipher.final()]);
+        return parseWith(RequestImport, parseWire(new TextDecoder("utf-8", { fatal: true }).decode(bytes)), "request import");
+    }
+    catch (error) {
+        throw asMessagingError(error, "request import open");
+    }
+}

package/dist/lib/modules/core/conversation/requests.js

@@ -0,0 +1,87 @@
+/** Portable request proofs. Verify raw signatures before using parsed values. No key material is transported. */
+import { createHash, randomBytes } from "node:crypto";
+import { parseWith } from "../check.js";
+import { canonicalize } from "../jcs.js";
+import { assertEd25519PublicKey } from "../keys.js";
+import { DOMAIN, LIMITS } from "../schema/common.js";
+import { ContactAuthorization, PortableRequest, RequestActivation, RequestDecision, RequestDescriptor, RequestOpening } from "../schema/contact-request.js";
+import { MessagingError } from "../schema/errors.js";
+import { sign, verify } from "../sign.js";
+import { dmConvId } from "./ids.js";
+const fail = (message) => { throw new MessagingError("invalid_request", message); };
+const digest = (domain, value) => createHash("sha256").update(domain).update(canonicalize(value)).digest("base64url");
+export const requestCommitment = (opening) => digest(DOMAIN.requestContent, parseWith(RequestOpening, opening, "request opening"));
+export const requestDigest = (descriptor) => digest(DOMAIN.requestDigest, descriptor);
+function signed(schema, raw, domain) {
+    parseWith(schema, raw, "request proof");
+    const value = raw;
+    assertEd25519PublicKey(value.by, "request device");
+    const { sig, ...unsigned } = value;
+    if (!verify(value.by, domain, unsigned, sig))
+        throw new MessagingError("bad_signature", "invalid request proof signature");
+    return parseWith(schema, raw, "request proof");
+}
+function bound(person, device, binding) {
+    if (!binding(person, device))
+        throw new MessagingError("unknown_device", "request signer has no verified person binding");
+}
+function route(p) {
+    if (p.from === p.to || p.cid !== dmConvId(p.from, p.to))
+        fail("request must name its two persons' exact DM");
+}
+export function verifyRequestDescriptor(raw, binding) {
+    const d = signed(RequestDescriptor, raw, DOMAIN.request);
+    route(d);
+    bound(d.from, d.by, binding);
+    if (d.expiresAt <= d.issuedAt || d.expiresAt - d.issuedAt > LIMITS.ttlMs)
+        fail("invalid request consent window");
+    return d;
+}
+export function verifyPortableRequest(raw, binding) {
+    parseWith(PortableRequest, raw, "portable request");
+    const value = raw;
+    const descriptor = verifyRequestDescriptor(value.descriptor, binding);
+    const opening = parseWith(RequestOpening, value.opening, "request opening");
+    if (requestCommitment(opening) !== descriptor.commitment)
+        throw new MessagingError("bad_signature", "request opening does not match signed content");
+    return { descriptor, opening };
+}
+export function createPortableRequest(identity, args, text) {
+    const opening = parseWith(RequestOpening, { salt: randomBytes(32).toString("base64url"), text }, "request opening");
+    const unsigned = { ...args, commitment: requestCommitment(opening), by: identity.machine };
+    return verifyPortableRequest({ descriptor: { ...unsigned, sig: sign(identity, DOMAIN.request, unsigned) }, opening }, (person, by) => person === args.from && by === identity.machine);
+}
+export function verifyRequestDecision(raw, descriptor, binding) {
+    const d = verifyRequestDescriptor(descriptor, binding);
+    const a = signed(RequestDecision, raw, DOMAIN.requestDecision);
+    bound(d.to, a.by, binding);
+    if (a.realm !== d.realm || a.cid !== d.cid || a.id !== d.id || a.from !== d.from || a.to !== d.to || a.descriptor !== requestDigest(d))
+        fail("decision does not bind this request");
+    if (a.at < d.issuedAt || a.at >= d.expiresAt)
+        throw new MessagingError("expired", "decision is outside the original consent window");
+    return a;
+}
+export function signRequestDecision(identity, d, answer, at) {
+    const unsigned = { v: d.v, realm: d.realm, cid: d.cid, id: d.id, from: d.from, to: d.to, descriptor: requestDigest(d), answer, at, by: identity.machine };
+    return parseWith(RequestDecision, { ...unsigned, sig: sign(identity, DOMAIN.requestDecision, unsigned) }, "request decision");
+}
+export function verifyRequestActivation(raw, binding) {
+    parseWith(RequestActivation, raw, "activation");
+    const p = raw;
+    const descriptor = verifyRequestDescriptor(p.descriptor, binding);
+    const decision = verifyRequestDecision(p.decision, descriptor, binding);
+    if (decision.answer !== "accept")
+        throw new MessagingError("forbidden", "a declined request cannot activate a conversation");
+    return { descriptor, decision };
+}
+export function signContactAuthorization(identity, args) {
+    route(args);
+    const unsigned = { ...args, by: identity.machine };
+    return parseWith(ContactAuthorization, { ...unsigned, sig: sign(identity, DOMAIN.contactAuthorization, unsigned) }, "contact authorization");
+}
+export function verifyContactAuthorization(raw, binding) {
+    const c = signed(ContactAuthorization, raw, DOMAIN.contactAuthorization);
+    route(c);
+    bound(c.from, c.by, binding);
+    return c;
+}

package/dist/lib/modules/core/conversation/seal.js

@@ -5,7 +5,9 @@
  *   12-byte nonce, under the author's message key for (`epoch`, `idx`);
  * - `create.sealedMeta`: the same, of JCS(ConvMeta) under the creator's epoch-0 message key 0, with the create
  *   event's header as AAD;
- * - a `keys` share: JCS({shares}) sealed to one recipient device under the envelope seal (spec §5, "Sealing": X25519
+ * - a `meta` or `setting` op's content: the same, under the author's key at the op's (`epoch`, `idx`), with
+ *   aad = JCS(event without `sig`, the op without `sealed`);
+ * - a `keys` share: JCS({shares}) sealed to its one recipient device under the envelope seal (spec §5, "Sealing": X25519
  *   with a fresh ephemeral key, HKDF-SHA256 with salt epk ‖ recipient enc and info DOMAIN.seal, AES-256-GCM), with
  *   aad = JCS({header, to}).
  */
@@ -15,7 +17,7 @@ import { asMessagingError, parseWith } from "../check.js";
 import { canonicalize } from "../jcs.js";
 import { privateKeyFromRaw, publicKeyFromRaw, rawPublicKey } from "../keys.js";
 import { DOMAIN, LIMITS } from "../schema/common.js";
-import { ConvMeta, KeySharePayload, MsgBody, } from "../schema/conversation.js";
+import { ConvMeta, KeySharePayload, MsgBody, SettingBody, } from "../schema/conversation.js";
 import { MessagingError } from "../schema/errors.js";
 import { parseWire } from "../wire.js";
 import { convEventHeader, signConvEvent } from "./event.js";
@@ -133,54 +135,49 @@ function shareKey(shared, epk, recipientEnc) {
     return new Uint8Array(hkdfSync("sha256", shared, Buffer.concat([epk, recipientEnc]), DOMAIN.seal, 32));
 }
 /**
- * Seals `shares` to each recipient device as the body of `unsealed`, and signs the event. One sealed share per
- * device; at most `LIMITS.keySharesPerEvent` devices and `LIMITS.keyShares` chain keys. Throws only MessagingError.
+ * Seals `shares` to one recipient device as the body of `unsealed`, and signs the event: one `keys` event per
+ * recipient device (spec §16.6), at most `LIMITS.keyShares` chain keys. Throws only MessagingError.
  */
-export function sealKeyShares(identity, unsealed, recipients, shares) {
-    return sealShares(identity, unsealed, recipients, shares, () => {
-        const { privateKey } = generateKeyPairSync("x25519");
-        return { ephemeral: privateKey, nonce: randomBytes(NONCE_BYTES) };
-    });
-}
-/** `sealKeyShares` with fixed randomness per recipient, in order: for test vectors only. */
-export function sealKeySharesWith(identity, unsealed, recipients, shares, randomness) {
-    let i = 0;
-    return sealShares(identity, unsealed, recipients, shares, () => {
-        const r = randomness[i++];
-        if (!r)
-            throw new MessagingError("invalid_request", "one randomness per recipient");
-        return { ephemeral: privateKeyFromRaw("x25519", r.ephemeral), nonce: r.nonce };
-    });
-}
-function sealShares(identity, unsealed, recipients, shares, randomness) {
+export function sealKeyShare(identity, unsealed, recipient, shares) {
+    const { privateKey } = generateKeyPairSync("x25519");
+    return sealShare(identity, unsealed, recipient, shares, { ephemeral: privateKey, nonce: randomBytes(NONCE_BYTES) });
+}
+/** `sealKeyShare` with fixed randomness: for test vectors only. */
+export function sealKeyShareWith(identity, unsealed, recipient, shares, randomness) {
+    try {
+        return sealShare(identity, unsealed, recipient, shares, { ephemeral: privateKeyFromRaw("x25519", randomness.ephemeral), nonce: randomness.nonce });
+    }
+    catch (error) {
+        throw asMessagingError(error, "key shares");
+    }
+}
+function sealShare(identity, unsealed, recipient, shares, randomness) {
     try {
         const header = convEventHeader({ ...unsealed, class: "keys" });
         const plaintext = utf8(canonicalize(parseWith(KeySharePayload, { shares }, "key shares")));
-        const sealed = recipients.map((recipient) => {
-            const to = { person: recipient.person, device: recipient.device };
-            const { ephemeral, nonce } = randomness();
-            const shared = diffieHellman({ privateKey: ephemeral, publicKey: publicKeyFromRaw("x25519", recipient.enc) });
-            const epk = rawPublicKey(ephemeral);
-            const key = shareKey(shared, b64u.decode(epk), b64u.decode(recipient.enc));
-            const data = aesSeal(key, nonce, plaintext, shareAad(header, to));
-            return { to, epk, nonce: b64u.encode(nonce), ct: b64u.encode(data.subarray(NONCE_BYTES)) };
-        });
-        return signConvEvent(identity, { ...header, body: { shares: sealed } });
+        const to = { person: recipient.person, device: recipient.device };
+        const { ephemeral, nonce } = randomness;
+        const shared = diffieHellman({ privateKey: ephemeral, publicKey: publicKeyFromRaw("x25519", recipient.enc) });
+        const epk = rawPublicKey(ephemeral);
+        const key = shareKey(shared, b64u.decode(epk), b64u.decode(recipient.enc));
+        const data = aesSeal(key, nonce, plaintext, shareAad(header, to));
+        const body = { to, epk, nonce: b64u.encode(nonce), ct: b64u.encode(data.subarray(NONCE_BYTES)) };
+        return signConvEvent(identity, { ...header, body });
     }
     catch (error) {
         throw asMessagingError(error, "key shares");
     }
 }
 /**
- * Opens the share sealed to `identity`'s device in a `keys` event: `not_found` when there is none, `bad_signature`
- * when it fails to open, `invalid_request` when the plaintext is not a share payload. The caller has verified the
- * event's signature and applied it to the log.
+ * Opens a `keys` event sealed to `identity`'s device: `not_found` when it is another device's, `bad_signature` when it
+ * fails to open, `invalid_request` when the plaintext is not a share payload. The caller has checked the event
+ * (`ConvLog.checkShare`).
  */
 export function openKeyShares(event, identity) {
     try {
-        const share = event.body.shares.find((s) => s.to.device === identity.machine);
-        if (!share)
-            throw new MessagingError("not_found", "no share for this device");
+        const share = event.body;
+        if (share.to.device !== identity.machine)
+            throw new MessagingError("not_found", "the share is for another device");
         let key;
         try {
             const shared = diffieHellman({ privateKey: identity.encKey, publicKey: publicKeyFromRaw("x25519", share.epk) });
@@ -196,3 +193,59 @@ export function openKeyShares(event, identity) {
         throw asMessagingError(error, "key shares");
     }
 }
+/** AAD of a sealed op: JCS of the event without `sig`, with the op without `sealed`. */
+function stateAad(event) {
+    const { sealed: _sealed, ...op } = event.body;
+    return utf8(canonicalize({ ...convEventHeader(event), body: op }));
+}
+function statePlaintext(op, content) {
+    const value = op.op === "meta" ? parseWith(ConvMeta, content, "conversation meta") : parseWith(SettingBody, content, "setting");
+    if (op.op === "setting" && value.s !== op.kind)
+        throw new MessagingError("invalid_request", "a setting's body is of its op's kind");
+    const bytes = utf8(canonicalize(value));
+    if (bytes.length > LIMITS.convPlaintextBytes)
+        throw new MessagingError("too_large", "sealed op is over LIMITS.convPlaintextBytes");
+    return bytes;
+}
+/**
+ * Seals `content` (a `ConvMeta` for `meta`, a `SettingBody` of the op's kind for `setting`) under `mk`, the author's
+ * message key at the op's (`epoch`, `idx`), and signs the op event. Throws only MessagingError.
+ */
+export function sealConvState(identity, unsealed, content, mk) {
+    return sealConvStateWith(identity, unsealed, content, mk, randomBytes(NONCE_BYTES));
+}
+/** `sealConvState` with a caller-chosen nonce: for test vectors only. */
+export function sealConvStateWith(identity, unsealed, content, mk, nonce) {
+    try {
+        const event = { ...unsealed, class: "op" };
+        const sealed = b64u.encode(aesSeal(mk, nonce, statePlaintext(unsealed.body, content), stateAad(event)));
+        return signConvEvent(identity, { ...event, body: { ...unsealed.body, sealed } });
+    }
+    catch (error) {
+        throw asMessagingError(error, "sealed op");
+    }
+}
+/**
+ * Opens a `meta` or `setting` op with the author's message key at its (`epoch`, `idx`): a `ConvMeta`, or a
+ * `SettingBody` whose `s` is the op's `kind` (`invalid_request` otherwise). `not_found` for another op; errors as
+ * for `openConvMsg`. The caller has applied the event to the log.
+ */
+export function openConvState(event, mk) {
+    try {
+        const op = event.body;
+        if (op.op !== "meta" && op.op !== "setting")
+            throw new MessagingError("not_found", "the op carries no sealed content");
+        if (mk.length !== 32)
+            throw new MessagingError("invalid_request", "a message key is 32 bytes");
+        const value = wireJson(aesOpen(mk, op.sealed, stateAad(event), LIMITS.convPlaintextBytes));
+        if (op.op === "meta")
+            return parseWith(ConvMeta, value, "conversation meta");
+        const setting = parseWith(SettingBody, value, "setting");
+        if (setting.s !== op.kind)
+            throw new MessagingError("invalid_request", "a setting's body is of its op's kind");
+        return setting;
+    }
+    catch (error) {
+        throw asMessagingError(error, "sealed op");
+    }
+}

package/dist/lib/modules/core/conversation-agent-tools.js

@@ -0,0 +1,69 @@
+/** Shared conversation-model tools, including the retained task-envelope path. */
+import { z } from "../vendor/zod/index.js";
+import { AgentTool, TaskReadOutput, TaskSendFields, TaskSendOutput, TaskSource, ToolChainSchema, ToolConsentSchema, ToolExpect } from "./agent-tools.js";
+import { LIMITS, Millis, Ulid } from "./schema/common.js";
+import { ConvId, ConvKind, ParticipantId } from "./schema/conversation.js";
+const Cursor = z.string().min(1).max(512).optional();
+const Limit = z.number().int().min(1).max(50).optional();
+const Fenced = z.string().describe("Untrusted peer content, fenced and with closing delimiters neutralized");
+const Author = z.object({ person: Fenced, agent: Fenced.optional(), of: Fenced.optional(), side: z.enum(["ours", "peer"]) });
+const Citation = z.string().regex(/^messaging:(?:[ds]_[a-z2-7]{26}|c_[0-7][0-9A-HJKMNP-TV-Z]{25})\/[0-7][0-9A-HJKMNP-TV-Z]{25}$/);
+const ConvSource = z.strictObject({ kind: z.literal("conv"), cid: ConvId, event: Ulid });
+export const ToolSource = z.discriminatedUnion("kind", [ConvSource, TaskSource]);
+/** Rendered model result: peer text and names are fenced by the client, never instructions. */
+export const ConversationToolEvent = z.object({
+    cite: Citation, cid: ConvId, id: Ulid, seq: z.number().int().positive().safe(), at: Millis,
+    conv: z.object({ kind: ConvKind, name: Fenced.optional() }), author: Author, thread: Ulid.optional(),
+    text: Fenced.max(LIMITS.toolTextChars).optional(), truncated: z.boolean().optional(), deleted: z.boolean().optional(), nextOffset: z.number().int().nonnegative().optional(),
+}).refine((e) => e.cite === `messaging:${e.cid}/${e.id}`, "citation names this event")
+    .refine((e) => !e.deleted || e.text === undefined, "deleted events contain no text");
+const Held = z.object({ stage: z.literal("held"), code: z.enum(["context", "audience"]), expect: z.literal("on_consent"), note: z.string().max(500) });
+const Events = z.array(ConversationToolEvent).max(50).refine((items) => items.reduce((n, item) => n + new TextEncoder().encode(item.text ?? "").length, 0) <= 32 * 1024, "at most 32 KiB of text");
+const EventPage = z.object({ events: Events, cursor: Cursor, notice: z.string().optional() });
+const Item = z.object({ item: z.union([
+        z.object({ id: Ulid, source: ConvSource, event: ConversationToolEvent }).refine((p) => p.source.cid === p.event.cid && p.source.event === p.event.id, "source names this event"),
+        TaskReadOutput.shape.item,
+    ]), notice: z.string().optional() });
+const Address = z.string().min(1).max(200).describe("me, person, person/agent or #channel");
+export const ConversationTools = {
+    contacts: AgentTool.contacts,
+    conversations: {
+        input: z.strictObject({ cid: ConvId.optional(), limit: Limit, cursor: Cursor }),
+        output: z.object({ conversations: z.array(z.object({ cid: ConvId, kind: ConvKind, name: Fenced.optional(), reason: z.enum(["seat", "allow", "ask"]), lookbackDays: z.number().int().positive().max(365), indexedFrom: Millis.optional(), complete: z.boolean() })).max(50), cursor: Cursor, notice: z.string().optional() }),
+    },
+    send: {
+        input: z.strictObject({ to: Address.optional(), cid: ConvId.optional(), text: z.string().min(1).max(40_000), thread: Ulid.optional(), answer: Ulid.optional(), ask: z.boolean().optional(), clientId: z.string().min(1).max(200).optional(),
+            ...TaskSendFields })
+            .refine((p) => (p.to === undefined) !== (p.cid === undefined), "choose exactly one destination"),
+        output: z.union([z.object({ source: ConvSource, stage: z.literal("pending"), clientId: z.string().max(200), expect: ToolExpect.optional() }),
+            TaskSendOutput, Held]),
+    },
+    inbox: {
+        input: z.strictObject({ unread: z.boolean().optional(), from: ParticipantId.optional(), limit: Limit }),
+        output: z.object({ items: z.array(z.object({ id: Ulid, source: ToolSource, from: Fenced, preview: Fenced.max(2000).optional(), at: Millis, stage: z.enum(["delivered", "handed_to_agent", "read"]),
+                consent: ToolConsentSchema, chain: ToolChainSchema.optional() })).max(50), unread: z.number().int().nonnegative(), notice: z.string().optional() }),
+    },
+    read: {
+        input: z.strictObject({ cid: ConvId.optional(), source: ToolSource.optional(), id: Ulid.optional().describe("A received envelope of the named task"), offset: z.number().int().min(0).max(LIMITS.lineChars).optional(), thread: Ulid.optional(), before: z.string().min(1).max(512).optional(), after: z.string().min(1).max(512).optional(), limit: Limit, cursor: Cursor })
+            .refine((p) => (p.cid === undefined) !== (p.source === undefined), "choose exactly one of cid or source")
+            .refine((p) => [p.before, p.after, p.cursor].filter((v) => v !== undefined).length <= 1, "choose one page position")
+            .refine((p) => p.offset === undefined || p.source?.kind === "conv", "offset requires a conversation event source")
+            .refine((p) => p.id === undefined || p.source?.kind === "task", "envelope id requires its task source")
+            .refine((p) => p.source === undefined || (p.thread === undefined && p.before === undefined && p.after === undefined && p.cursor === undefined), "item reads do not page"),
+        output: z.union([EventPage, Item, Held]),
+    },
+    search: {
+        input: z.strictObject({ query: z.string().min(1).max(200), cid: ConvId.optional(), from: ParticipantId.optional(), after: Millis.optional(), before: Millis.optional(), thread: Ulid.optional(), limit: Limit, cursor: Cursor }),
+        output: z.union([EventPage, Held]),
+    },
+    context: {
+        input: z.strictObject({ cid: ConvId, event: Ulid, before: z.number().int().min(0).max(20).optional(), after: z.number().int().min(0).max(20).optional() }),
+        output: z.union([z.object({ event: ConversationToolEvent, before: Events, after: Events, root: ConversationToolEvent.optional(), notice: z.string().optional() })
+                .refine((p) => p.before.length <= 20 && p.after.length <= 20, "at most 20 neighbours on each side")
+                .refine((p) => [...p.before, ...p.after].reduce((n, e) => n + new TextEncoder().encode(e.text ?? "").length, 0) <= 32 * 1024, "at most 32 KiB of neighbour text"), Held]),
+    },
+    tasks: AgentTool.tasks,
+    task_update: AgentTool.task_update,
+    task_cancel: AgentTool.task_cancel,
+};
+export const CONVERSATION_TOOL_VERBS = ["contacts", "conversations", "send", "inbox", "read", "search", "context", "tasks", "task_update", "task_cancel"];

package/dist/lib/modules/core/federation/directory-proof.js

@@ -0,0 +1,83 @@
+import { z } from "../../vendor/zod/index.js";
+import { parseWith } from "../check.js";
+import { DeviceLog } from "../directory/device-log.js";
+import { adoptSth } from "../directory/epoch.js";
+import { verifyPersonView } from "../directory/person-view.js";
+import { DirectoryRealmConfig, directoryRealmId } from "../directory/realm.js";
+import { DOMAIN, Hash, HostedPersonId } from "../schema/common.js";
+import { KeyRotation } from "../schema/directory.js";
+import { verify } from "../sign.js";
+import { admitForeignProof, checkContext, FOREIGN_BUDGET, FOREIGN_LIMITS, ForeignProofError, proofDigest, proofFailure, requireProof, verifiedProof } from "./proof-state.js";
+const Bundle = z.strictObject({ sth: z.unknown(), head: z.unknown(), view: z.unknown(), rotations: z.array(KeyRotation), consistency: z.array(Hash) });
+/** Key resolution is trusted issuer configuration, never keys embedded in a foreign response.
+ * `options.heads` may only shrink the recent-head working window (tests exercise eviction with a
+ * few heads); it never exceeds FOREIGN_BUDGET.heads. */
+export function verifyForeignDirectory(input, key, options = {}) {
+    const window = options.heads ?? FOREIGN_BUDGET.heads;
+    if (!Number.isSafeInteger(window) || window < 1 || window > FOREIGN_BUDGET.heads)
+        throw new RangeError("invalid-head-window");
+    try {
+        admitForeignProof(input.proof, "directory");
+        checkContext(input, "directory");
+        const person = parseWith(HostedPersonId, input.subject.person, "foreign person");
+        const pin = parseWith(DirectoryRealmConfig, input.pin.root, "directory pin");
+        requireProof(directoryRealmId(pin) === input.pin.realm, "directory-root", "root");
+        const bundle = parseWith(Bundle, input.proof, "directory proof");
+        // Require the full rotation chain from the original pin on every bundle. Strict schemas preserve
+        // signed JSON exactly; they reject extra fields rather than stripping them before verification.
+        // adoptSth intentionally skips already-applied rotations. A full foreign bundle must authenticate
+        // those too, before their keys become service-unbind authorities or enter the retained cursor.
+        let rotationKey = pin.key;
+        for (const rotation of bundle.rotations) {
+            const { sigOld, sigNew, ...unsigned } = rotation;
+            requireProof(verify(rotation.old, DOMAIN.dirKey, unsigned, sigOld) && verify(rotation.new, DOMAIN.dirKey, unsigned, sigNew), "rotation-signature");
+            requireProof(rotation.realm === input.pin.realm && rotation.old === rotationKey && rotation.new !== rotationKey, "rotation-chain");
+            rotationKey = rotation.new;
+        }
+        const anchored = adoptSth(undefined, pin.key, { realm: input.pin.realm, next: bundle.sth, rotations: bundle.rotations });
+        const previous = input.realm?.cursor;
+        const heldHeads = [...(previous?.heads ?? []), ...[input.realm?.head, input.known?.head, input.observedHead].filter((head) => head !== undefined)];
+        const comparable = heldHeads.filter((held) => held.position === anchored.sth.size);
+        for (const held of comparable)
+            requireProof(anchored.sth.root === held.hash, "directory-fork", "fork");
+        for (const held of [input.realm?.head, input.known?.head]) {
+            if (!held)
+                continue;
+            requireProof(anchored.sth.size >= held.position, "directory-rollback", "rollback", comparable.length > 0);
+            requireProof(anchored.sth.ts >= held.issuedAt, "directory-time-rollback", "rollback", comparable.length > 0);
+        }
+        requireProof(!input.known || previous !== undefined, "missing-realm-continuity");
+        const after = previous ? bundle.rotations.findIndex((rotation) => rotation.new === previous.adopted.key) + 1 : 0;
+        let adopted;
+        try {
+            adopted = adoptSth(previous?.adopted, pin.key, { realm: input.pin.realm, next: bundle.sth, rotations: bundle.rotations.slice(after), consistency: bundle.consistency });
+        }
+        catch {
+            // A stale consistency base does not prove compatibility with the current head.
+            throw new ForeignProofError("invalid", "continuity-proof");
+        }
+        const directoryKeys = [pin.key, ...bundle.rotations.map((rotation) => rotation.new)];
+        const context = { realm: input.pin.realm, person, jelly: { issuer: pin.issuer, audience: pin.resource, key }, directoryKeys };
+        const saved = input.known?.cursor;
+        const known = saved ? { person, log: DeviceLog.fromEntries(saved.log, context), keys: new Map(saved.keys.map((statement) => [statement.device, statement])), erased: saved.erased } : undefined;
+        const state = verifyPersonView(bundle.view, { ...context, sth: adopted.sth, head: bundle.head, known });
+        requireProof(state.person === person, "requested-person");
+        requireProof(!known?.erased || state.erased, "erasure-reversal", "rollback");
+        const head = { position: adopted.sth.size, hash: adopted.sth.root, issuedAt: adopted.sth.ts, expiresAt: adopted.sth.ts + FOREIGN_LIMITS.headMs };
+        // A working window, never a lifetime limit. The caller archives every authenticated
+        // observation and supplies observedHead for comparisons outside this window.
+        const heads = [...(previous?.heads ?? []).filter((held) => held.position !== head.position), head].slice(-window);
+        const devices = state.erased ? [] : state.log.devices().map((device) => {
+            const statement = state.keys.get(device.device);
+            return { signingKey: device.device, encryptionKey: statement?.enc, keyVersion: statement?.seq ?? -1, review: null };
+        });
+        const removed = state.log.allDevices().filter((device) => state.erased || !device.current).map((device) => device.device);
+        return verifiedProof({
+            realm: { realm: input.pin.realm, pinDigest: proofDigest(input.pin), head, cursor: { adopted, keys: directoryKeys, heads } },
+            identity: { subject: { ...input.subject }, head, devices, removed, erased: state.erased, proofDigest: proofDigest(input.proof), cursor: { log: [...state.log.entries()], keys: [...state.keys.values()], erased: state.erased } },
+        }, input.now);
+    }
+    catch (error) {
+        return proofFailure(error, input.proof);
+    }
+}