@joe-broadhead/messaging 0.7.1 → 0.8.0

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

@@ -0,0 +1,167 @@
+/** Internal X3-3 boundary. No discovery response is a pin and no result is human approval. */
+import { canonicalize } from "../jcs.js";
+import { sha256 } from "../hash.js";
+import { LIMITS } from "../schema/common.js";
+export const FOREIGN_LIMITS = { fetchMs: 10 * 60_000, headMs: 20 * 60_000, futureMs: LIMITS.clockSkewMs };
+/** Internal work budgets, independent of transport limits. `heads` bounds the recent-head
+ * working window only; the caller's durable archive retains observations beyond it. */
+export const FOREIGN_BUDGET = { proofBytes: 1_048_576, stateBytes: 4_194_304, nodes: 32_768, depth: 32, rosterEntries: 1024, rotations: 64, consistency: 64, heads: 1024 };
+export class ForeignInputError extends Error {
+    constructor() { super("foreign-input-limit"); }
+}
+/** Bound traversal before canonicalization allocates/sorts the complete value. No accessors run. */
+export function checkForeignValue(value, maxBytes = FOREIGN_BUDGET.proofBytes) {
+    let bytes = 0, nodes = 0;
+    const maxNodes = FOREIGN_BUDGET.nodes * Math.max(1, maxBytes / FOREIGN_BUDGET.proofBytes);
+    const add = (size) => { bytes += size; if (bytes > maxBytes)
+        throw new ForeignInputError(); };
+    const text = (s) => {
+        if (s.length > maxBytes - bytes)
+            throw new ForeignInputError();
+        add(Buffer.byteLength(JSON.stringify(s), "utf8"));
+    };
+    const visit = (item, depth) => {
+        if (++nodes > maxNodes)
+            throw new ForeignInputError();
+        if (item === null) {
+            add(4);
+            return;
+        }
+        if (typeof item === "string") {
+            text(item);
+            return;
+        }
+        if (typeof item === "boolean") {
+            add(item ? 4 : 5);
+            return;
+        }
+        if (typeof item === "number" && Number.isFinite(item)) {
+            add(String(item).length);
+            return;
+        }
+        if (typeof item !== "object" || depth >= FOREIGN_BUDGET.depth)
+            throw new ForeignInputError();
+        add(2);
+        if (Array.isArray(item)) {
+            if (item.length > maxNodes - nodes)
+                throw new ForeignInputError();
+            for (let i = 0; i < item.length; i++) {
+                const field = Object.getOwnPropertyDescriptor(item, String(i));
+                if (!field || !("value" in field))
+                    throw new ForeignInputError();
+                if (i)
+                    add(1);
+                visit(field.value, depth + 1);
+            }
+            return;
+        }
+        const proto = Object.getPrototypeOf(item);
+        if (proto !== Object.prototype && proto !== null && Object.getPrototypeOf(proto) !== null)
+            throw new ForeignInputError();
+        let count = 0;
+        for (const key in item) {
+            if (!Object.hasOwn(item, key))
+                continue;
+            if (++nodes > maxNodes)
+                throw new ForeignInputError();
+            const field = Object.getOwnPropertyDescriptor(item, key);
+            if (!("value" in field))
+                throw new ForeignInputError();
+            if (field.value === undefined)
+                continue;
+            if (count++)
+                add(1);
+            text(key);
+            add(1);
+            visit(field.value, depth + 1);
+        }
+    };
+    visit(value, 0);
+}
+export function admitForeignProof(proof, kind) {
+    checkForeignValue(proof);
+    if (typeof proof !== "object" || proof === null)
+        return; // The verifier owns schema errors.
+    const bundle = proof;
+    const collection = (name, max) => {
+        const entries = bundle[name];
+        if (Array.isArray(entries) && entries.length > max)
+            throw new ForeignInputError();
+    };
+    if (kind === "roster") {
+        collection("entries", FOREIGN_BUDGET.rosterEntries);
+        if (Array.isArray(bundle.entries))
+            for (const entry of bundle.entries)
+                checkForeignValue(entry, LIMITS.rosterEntryBytes);
+    }
+    else {
+        collection("rotations", FOREIGN_BUDGET.rotations);
+        collection("consistency", FOREIGN_BUDGET.consistency);
+    }
+}
+export class ForeignProofError extends Error {
+    reason;
+    code;
+    compatible;
+    constructor(reason, code, compatible = false) {
+        super(code);
+        this.reason = reason;
+        this.code = code;
+        this.compatible = compatible;
+    }
+}
+export function requireProof(condition, code, reason = "invalid", compatible = false) {
+    if (!condition)
+        throw new ForeignProofError(reason, code, compatible);
+}
+export function proofDigest(value) { checkForeignValue(value); return sha256(canonicalize(value)); }
+export function proofFailure(error, proof) {
+    let digest;
+    if (error instanceof ForeignInputError)
+        return { ok: false, reason: "invalid", evidence: { code: "foreign-input-limit", digest: sha256("foreign-input-limit") } };
+    try {
+        digest = proofDigest(proof);
+    }
+    catch {
+        digest = sha256("non-json-proof");
+    }
+    return { ok: false, reason: error instanceof ForeignProofError && error.reason !== "stale" ? error.reason : "invalid", evidence: { code: error instanceof ForeignProofError ? error.code : "invalid-proof", digest, ...(error instanceof ForeignProofError && error.reason === "rollback" && error.compatible ? { compatible: true } : {}) } };
+}
+/** Expiry changes key eligibility, never the authenticated history we must retain. */
+export function verifiedProof(verified, now) {
+    try {
+        checkHeadTime(verified.realm.head, now);
+    }
+    catch (error) {
+        if (!(error instanceof ForeignProofError) || error.reason !== "stale")
+            throw error;
+        return { ok: false, reason: "stale", verified, evidence: { code: error.code, digest: verified.identity.proofDigest } };
+    }
+    return { ok: true, ...verified };
+}
+export function checkContext(input, kind) {
+    requireProof(Number.isSafeInteger(input.now) && input.now >= 0, "clock");
+    requireProof(input.pin.kind === kind && input.subject.realm === input.pin.realm, "pinned-realm", "root");
+    if (input.realm)
+        requireProof(input.realm.realm === input.pin.realm && input.realm.pinDigest === proofDigest(input.pin), "known-root", "root");
+    if (input.known)
+        requireProof(input.known.subject.realm === input.subject.realm && input.known.subject.person === input.subject.person, "known-person");
+}
+export function checkHeadTime(head, now) {
+    requireProof(Number.isSafeInteger(head.issuedAt) && Number.isSafeInteger(head.expiresAt), "head-time");
+    requireProof(head.issuedAt <= now + FOREIGN_LIMITS.futureMs, "future-head");
+    requireProof(head.expiresAt > head.issuedAt && head.expiresAt - head.issuedAt <= FOREIGN_LIMITS.headMs, "head-lifetime");
+    requireProof(now - head.issuedAt <= FOREIGN_LIMITS.headMs && now < head.expiresAt, "expired-head", "stale");
+}
+/** Caller clock only. A future local fetch time (including clock rollback) fails closed. */
+export function foreignFresh(head, fetchedAt, now) {
+    if (!Number.isSafeInteger(now) || !Number.isSafeInteger(fetchedAt) || fetchedAt > now || now - fetchedAt > FOREIGN_LIMITS.fetchMs)
+        return false;
+    try {
+        checkHeadTime(head, now);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,74 @@
+import { z } from "../../vendor/zod/index.js";
+import { parseWith } from "../check.js";
+import { Roster, entryHash } from "../roster.js";
+import { Hash, MachineId, Millis, PersonName } from "../schema/common.js";
+import { verify } from "../sign.js";
+import { admitForeignProof, checkContext, proofDigest, proofFailure, requireProof, verifiedProof } from "./proof-state.js";
+/** Internal until X3-2/3 supplies the normative contract. */
+export const DOMAIN = { rosterCheckpoint: "messaging/1/federation/roster-checkpoint\n" };
+const Checkpoint = z.strictObject({ realm: Hash, seq: z.number().int().nonnegative(), hash: Hash, issuedAt: Millis, expiresAt: Millis, by: MachineId, sig: z.string() });
+const Bundle = z.strictObject({ entries: z.array(z.unknown()).min(1), checkpoint: z.unknown() });
+/** Full history only; the caller has separately authorized its disclosure. */
+export function verifyForeignRoster(input) {
+    try {
+        admitForeignProof(input.proof, "roster");
+        checkContext(input, "roster");
+        parseWith(PersonName, input.subject.person, "foreign person");
+        const pin = parseWith(z.strictObject({ genesis: Hash }), input.pin.root, "roster pin");
+        requireProof(pin.genesis === input.pin.realm, "genesis-pin", "root");
+        const bundle = parseWith(Bundle, input.proof, "roster proof");
+        // Roster retains and verifies raw signed entries, including unknown signed fields.
+        const roster = Roster.fromEntries(bundle.entries);
+        requireProof(roster.realm === pin.genesis, "genesis-root", "root");
+        const raw = bundle.checkpoint;
+        requireProof(typeof raw === "object" && raw !== null, "checkpoint-shape");
+        const { sig, ...unsigned } = raw;
+        requireProof(typeof raw.by === "string" && typeof sig === "string" && verify(raw.by, DOMAIN.rosterCheckpoint, unsigned, sig), "checkpoint-signature");
+        const checkpoint = parseWith(Checkpoint, raw, "roster checkpoint");
+        const current = roster.head();
+        requireProof(checkpoint.realm === input.pin.realm, "checkpoint-realm");
+        requireProof(checkpoint.seq === current.seq && checkpoint.hash === current.hash, "checkpoint-head");
+        requireProof(roster.isAdmin(checkpoint.by), "checkpoint-admin");
+        // Compare every available common prefix before classifying an older response as rollback.
+        // The realm cursor also protects persons for whom we have never retained a separate view.
+        const hashes = roster.entries().map(entryHash);
+        for (const held of [input.realm, input.known]) {
+            if (!held)
+                continue;
+            const position = Math.min(current.seq, held.head.position);
+            const expected = position === held.head.position ? held.head.hash : held.cursor.hashes[position];
+            requireProof(hashes[position] === expected, "roster-fork", "fork");
+        }
+        for (const held of [input.realm?.head, input.known?.head]) {
+            if (!held)
+                continue;
+            requireProof(current.seq >= held.position, "roster-rollback", "rollback", true);
+            requireProof(checkpoint.issuedAt >= held.issuedAt, "checkpoint-rollback", "rollback", true);
+        }
+        const head = { position: current.seq, hash: current.hash, issuedAt: checkpoint.issuedAt, expiresAt: checkpoint.expiresAt };
+        const removed = new Set();
+        const people = new Map();
+        const reviews = new Map();
+        const versions = new Map();
+        for (const entry of roster.entries()) {
+            const member = entry.kind === "genesis" ? entry.body.founder : entry.kind === "member.add" ? entry.body : entry.kind === "invite.redeem" ? entry.body.member : undefined;
+            if (member)
+                people.set(member.machine, member.person);
+            if (entry.kind === "member.remove" && people.get(entry.body.machine) === input.subject.person)
+                removed.add(entry.body.machine);
+            if (entry.kind === "member.rekey") {
+                versions.set(entry.body.machine, entry.seq);
+                if (entry.by !== entry.body.machine)
+                    reviews.set(entry.body.machine, entryHash(entry));
+            }
+        }
+        const devices = roster.members().filter((member) => member.person === input.subject.person).map((member) => ({ signingKey: member.machine, encryptionKey: member.enc, keyVersion: versions.get(member.machine) ?? 0, review: reviews.get(member.machine) ?? null }));
+        return verifiedProof({
+            realm: { realm: input.pin.realm, pinDigest: proofDigest(input.pin), head, cursor: { hashes } },
+            identity: { subject: { ...input.subject }, head, devices, removed: [...removed], erased: false, proofDigest: proofDigest(input.proof), cursor: { hashes } },
+        }, input.now);
+    }
+    catch (error) {
+        return proofFailure(error, input.proof);
+    }
+}

package/dist/lib/modules/core/index.js

@@ -1,10 +1,15 @@
 // Wire contracts (frozen; change only with a spec update and new test vectors).
 export * from "./schema/index.js";
+export * from "./conversation-agent-tools.js";
 // Protocol logic; see docs/spec/messaging-v1.md §9.
 export { b64u } from "./b64u.js";
 export { VERSION } from "./version.js";
 export { canonicalize } from "./jcs.js";
 export { parseWire } from "./wire.js";
+export * from "./conversation/requests.js";
+export * from "./conversation/request-log.js";
+export * from "./conversation/request-seal.js";
+export * from "./conversation/guest-invitation.js";
 export { sha256 } from "./hash.js";
 export { ulid } from "./ulid.js";
 export { Identity, IdentityFile, generateIdentity, exportIdentity, importIdentity } from "./identity.js";
@@ -37,17 +42,17 @@ export { canTransition, isTerminal, isInterrupted } from "./task.js";
 export { TERMINAL_STATES } from "./schema/a2a.js";
 export { cleanPeerText, createFence, terminalSafe, displayWidth, HOST_TAGS, PEER_FENCE_TAG, PEER_DATA_NOTICE, provenanceOf } from "./peer-text.js";
 // The agent tool contract shared by the OpenCode plugin and messaging-mcp (spec §11, "Agent tools").
-export { AgentTool, TOOL_VERBS, TOOL_DESCRIPTIONS, ToolExpect, UNTRUSTED_SENTENCE, TOOL_REMEDIES, STORE_REFUSED_REMEDIES, DONE_STATES, TaskStateName, ToolErrorBody, ToolFiles, a2aTaskState, conversationOf, decodeToolCursor, encodeToolCursor, formatToolAddress, parseToolAddress, taskStateName, toolErrorBody, toolName, } from "./agent-tools.js";
+export { AgentTool, TOOL_VERBS, TOOL_DESCRIPTIONS, ToolExpect, UNTRUSTED_SENTENCE, TOOL_REMEDIES, STORE_REFUSED_REMEDIES, DONE_STATES, TaskStateName, ToolErrorBody, ToolFiles, a2aTaskState, formatToolAddress, parseToolAddress, taskStateName, toolErrorBody, toolName, } from "./agent-tools.js";
 // The agent tools' operations and presenters, shared by the plugin and messaging-mcp (spec §11).
 export { Operations, } from "./agent/operations.js";
-export { agentCan, consentOf, conversationOfPeer, followUpRead, isoOf, presentAgent, presentConvEntry, presentInboxItem, presentLine, presentMail, presentSent, presentTask, presentTaskItem, presentTaskView, } from "./agent/present.js";
+export { agentCan, consentOf, followUpRead, isoOf, presentAgent, presentInboxItem, presentTaskEnvelope, presentTask, presentTaskItem, presentTaskView, } from "./agent/present.js";
 export { chainPath, compact, delegated, delegationPrompt, EXPECT_TEXT, isSafeId, messageAttributes, validatedAddress, } from "./agent/text.js";
 // Conversations (spec §16): ids, events and the log's hash chain, sender keys and sealing, the log as a pure
 // reducer, and context-rule resolution. Fixed-randomness sealing for vectors lives in `@messaging/core/testing`.
 export { dmConvId, selfConvId, participantOf, participantPerson, participantAgent } from "./conversation/ids.js";
 export { admitConvEvent, convEntryHash, convEventDigest, convEventHeader, convEventSigned, convGenesisHash, convLinkHash, signConvEvent, verifyConvEvent, } from "./conversation/event.js";
 export { chainStep, ReceiverChains, ReceiverChainsState, SenderChain, SenderChainState } from "./conversation/ratchet.js";
-export { openConvMeta, openConvMsg, openKeyShares, sealConvMeta, sealConvMsg, sealKeyShares, } from "./conversation/seal.js";
+export { openConvMeta, openConvMsg, openConvState, openKeyShares, sealConvMeta, sealConvMsg, sealConvState, sealKeyShare, } from "./conversation/seal.js";
 export { ConvLog, } from "./conversation/log.js";
 export { checkVia, currentLinks, linkReader } from "./conversation/link.js";
 export { CONTEXT_DEFAULTS, contextKindOf, matchContextRule, resolveContext, seatReads, } from "./conversation/context.js";

package/dist/lib/modules/core/jelly-host.js

@@ -22,7 +22,7 @@ export const SESSION_TICKET_MAX_S = 7 * 24 * 60 * 60;
 /** The clock skew allowed on `iat` and `exp`. */
 export const JELLY_HOST_SKEW_S = 5;
 /** `chat`: the person's own lines and read state. */
-const CHAT_METHODS = ["person.send", "conv.markRead", "notice.ack"];
+const CHAT_METHODS = ["conv.send", "conv.edit", "conv.delete", "conv.react", "notice.ack"];
 /**
  * `view`: the read-only methods a Jelly section reads with (`section.rpc`): the read-only human-tier methods, and
  * `device.list`, the one admin-tier read a section shows. A preview is not one of them: it takes its action's class
@@ -32,13 +32,13 @@ const CHAT_METHODS = ["person.send", "conv.markRead", "notice.ack"];
 const VIEW_METHODS = [
     "conv.list",
     "conv.read",
-    "conv.subscribe",
+    "conv.sync", "conv.get", "conv.members", "conv.threads", "conv.search", "conv.context", "conv.access",
+    "request.waiting",
     "people.search",
     "people.get",
     "grant.list",
     "request.list",
-    "agents.list",
-    "agents.read",
+    "sessions.list",
     "notice.subscribe",
     "notice.list",
     "device.list",
@@ -46,7 +46,7 @@ const VIEW_METHODS = [
 const classOf = (method) => CHAT_METHODS.includes(method) ? "chat" : VIEW_METHODS.includes(method) ? "view" : "local";
 /**
  * The class a method grant must name in `cls` for each human- and admin-tier method (spec §8.11): `chat` for
- * `person.send`, `conv.markRead` and `notice.ack`, `view` for the read-only human-tier methods, `local` for every
+ * line mutations and `notice.ack`, `view` for the read-only human-tier methods, `local` for every
  * other. A plugin's `jelly` declaration gives each action and read the same class; a test there checks one against
  * the other.
  */

package/dist/lib/modules/core/schema/common.js

@@ -54,6 +54,12 @@ export const DOMAIN = {
     convMsg: "messaging/1/conv-msg",
     /** Conversations (spec §16.5): HKDF `info` for a sender chain's next chain key. */
     convChain: "messaging/1/conv-chain",
+    request: "messaging/1/contact-request\n",
+    requestContent: "messaging/1/contact-request-content\n",
+    requestDigest: "messaging/1/contact-request-digest\n",
+    requestDecision: "messaging/1/contact-request-decision\n",
+    contactAuthorization: "messaging/1/contact-authorization\n",
+    guestInvitation: "messaging/1/guest-invitation\n",
 };
 /** A2A extension and binding URIs owned by Messaging. */
 export const URI = {
@@ -81,8 +87,6 @@ export const HostedPersonId = z.string().regex(/^p_[a-z2-7]{26}$/, "hosted perso
 export const PersonId = z.union([PersonName, HostedPersonId]);
 /** A channel's name (spec §6.8). Unique among the channels one machine holds, not across the team. */
 export const ChannelName = z.string().regex(/^[a-z][a-z0-9-]{0,31}$/, "lowercase channel name");
-/** A chat room (spec §6.8): `dm:<person>` for a direct human message, `channel:<name>` for a channel. */
-export const RoomRef = z.string().regex(/^(?:dm:(?:[a-z][a-z0-9-]{0,31}|p_[a-z2-7]{26})|channel:[a-z][a-z0-9-]{0,31})$/, "dm:<person> or channel:<name>");
 export const SessionName = z.string().regex(/^[a-z0-9][a-z0-9._-]{0,63}$/, "lowercase session name");
 export const MachineLabel = z.string().regex(/^[a-z0-9][a-z0-9-]{0,31}$/, "lowercase machine label");
 export const TeamName = z.string().min(1).max(64);
@@ -90,7 +94,7 @@ export const TeamName = z.string().min(1).max(64);
 export const AgentKind = z.string().regex(/^[a-z0-9][a-z0-9._-]{0,63}$/, "lowercase agent kind");
 /**
  * The agent kind of the human `messaging` command line (spec §8.2, §8.3): never kept or expired on
- * disconnect, refused as a task executor, and the only sender of group addresses.
+ * disconnect and refused as a task executor. No sender can use group addresses.
  */
 export const CLI_AGENT = "cli";
 /** Milliseconds since the Unix epoch. */
@@ -134,6 +138,8 @@ export const LIMITS = {
     plaintextBytes: 262_144,
     /** Max characters in a single text part. */
     textPartChars: 65_536,
+    /** Existing model-visible per-part cap, shared with fenced conversation events. */
+    toolTextChars: 32_768,
     /** Max parts in one message. */
     partsPerMessage: 16,
     /** Default and max envelope TTL, and the max invite lifetime (`expires − ts`). */
@@ -282,12 +288,32 @@ export const LIMITS = {
     rekeyScheduleMs: 30 * 24 * 60 * 60 * 1000,
     /** Max chain keys in one sealed key share, and in one `keys` sync of the `self` conversation. */
     keyShares: 512,
-    /** Max recipient devices one `keys` event seals to; a larger share is split over several events. */
-    keySharesPerEvent: 500,
     /** Max agents one event's `wake` hint names. */
     wakeHints: 5,
     /** Max context rules a person holds (spec §16.8). */
     contextRules: 500,
+    /** Relay (spec §7, "Conversation frames"): appends one device makes to one conversation, a burst of this many... */
+    convAppendBurst: 20,
+    /** ...refilled at this many a minute. */
+    convAppendsPerMinute: 60,
+    /** Appends to one conversation from all its devices, a minute (burst and refill). */
+    convAppendsPerConvPerMinute: 600,
+    /** `rekey` ops with a cause the log cannot prove (`device`, `schedule`) per device per conversation, an hour. */
+    convRekeysPerHour: 4,
+    /** Conversations one device takes part in, through its person (create, add and join refuse past it). */
+    convsPerDevice: 5000,
+    /** Conversations one device creates, an hour (burst and refill). */
+    convCreatesPerHour: 60,
+    /** Key-share events in one `conv.share` frame. */
+    convSharesPerFrame: 100,
+    /** Key shares one sender device holds at the relay for one recipient device in one conversation. */
+    convSharesPerPair: 256,
+    /** Key shares one device sends to one conversation, a burst of this many, refilled per minute. */
+    convSharesPerMinute: 10_000,
+    /** Entries (and shares) in one `conv.entries` reply. */
+    convFetchEntries: 500,
+    /** Conversations named in one `conv.head`, and heads in one `conv.heads` reply. */
+    convHeads: 500,
 };
 const LOOPBACK_HOST = /^(?:localhost|127(?:\.\d{1,3}){3}|\[::1\])$/;
 /**

package/dist/lib/modules/core/schema/consent.js

@@ -6,14 +6,15 @@
 import { z } from "../../vendor/zod/index.js";
 import { Base64Url, LIMITS, MachineId, Millis, PersonId, PROTOCOL, Ulid } from "./common.js";
 import { RealmId } from "./realm.js";
+import { ConvId } from "./conversation.js";
 /** H2H lines from the subject: `muted` delivers with no notification and no unread mark; `blocked` refuses every class from them. */
 export const ChatLevel = z.enum(["open", "muted", "blocked"]);
 /** Lines from the subject's agents to the person (A2H). */
 export const AgentMailLevel = z.enum(["open", "blocked"]);
 /** Mail and tasks from the subject or their agents to the person's agents: `request` holds each one for the person to answer. */
 export const AskLevel = z.enum(["open", "request", "no"]);
-/** Whom a grant is about: one person, or every member of one channel (by its id). */
-export const GrantSubject = z.union([z.strictObject({ person: PersonId }), z.strictObject({ channel: Ulid })]);
+/** Whom a grant is about: one person, or the verified participants of one conversation. */
+export const GrantSubject = z.union([z.strictObject({ person: PersonId }), z.strictObject({ conv: ConvId })]);
 /**
  * A grant, signed by `by`, a device of `person`: `sig = Ed25519(by, "messaging/1/grant\n" || JCS(grant without sig))`.
  * Every level is optional: an absent level is the default for the relation (spec §6.9, "Effective policy"), and a
@@ -54,8 +55,8 @@ export const GrantSync = z.strictObject({ grants: z.array(z.record(z.string(), z
 /** The rules of a grant that its schema alone cannot say. */
 export function grantProblem(grant) {
     const own = "person" in grant.subject && grant.subject.person === grant.person;
-    if ("channel" in grant.subject && (grant.chat !== undefined || grant.trustedUntil !== undefined || grant.discoverable !== undefined)) {
-        return "a channel grant sets only ask and agentMail";
+    if ("conv" in grant.subject && (grant.chat !== undefined || grant.trustedUntil !== undefined || grant.discoverable !== undefined)) {
+        return "a conversation grant sets only ask and agentMail";
     }
     if (own && (grant.chat !== undefined || grant.agentMail !== undefined || grant.ask !== undefined || grant.trustedUntil !== undefined)) {
         return "a grant about its own person sets only discoverable";

package/dist/lib/modules/core/schema/contact-request.js

@@ -0,0 +1,22 @@
+/** Portable same-realm contact requests (spec §16.11). All proofs are strict and domain-separated. */
+import { z } from "../../vendor/zod/index.js";
+import { Hash, Key32, LIMITS, MachineId, Millis, PersonId, PROTOCOL, Ulid } from "./common.js";
+import { RealmId } from "./realm.js";
+const Dm = z.string().regex(/^d_[a-z2-7]{26}$/);
+const Sig = z.string().regex(/^[A-Za-z0-9_-]{86}$/);
+const Req = z.string().min(1).max(64);
+const route = { v: z.literal(PROTOCOL), realm: RealmId, cid: Dm, from: PersonId, to: PersonId };
+export const RequestDescriptor = z.strictObject({ ...route, id: Ulid, issuedAt: Millis, expiresAt: Millis, commitment: Hash, by: MachineId, sig: Sig });
+export const RequestOpening = z.strictObject({ salt: Key32, text: z.string().min(1).max(LIMITS.requestChars) });
+export const PortableRequest = z.strictObject({ descriptor: RequestDescriptor, opening: RequestOpening });
+/** A block is conveyed as decline. The first valid terminal answer is sequenced in the recipient mailbox. */
+export const RequestDecision = z.strictObject({ ...route, id: Ulid, descriptor: Hash, answer: z.enum(["accept", "decline"]), at: Millis, by: MachineId, sig: Sig });
+export const RequestActivation = z.strictObject({ descriptor: RequestDescriptor, decision: RequestDecision });
+/** Existing contacts authorize the exact human DM on both sides, under their current local grants. */
+export const ContactAuthorization = z.strictObject({ ...route, at: Millis, by: MachineId, sig: Sig });
+export const ActivationProof = z.union([RequestActivation, z.strictObject({ contacts: z.tuple([ContactAuthorization, ContactAuthorization]) })]);
+export const RequestImport = z.strictObject({ t: z.literal("request.import"), ...RequestActivation.shape, opening: RequestOpening });
+/** No opening or request text is sent to the relay. */
+export const RequestSettleFrame = z.strictObject({ t: z.literal("request.settle"), req: Req, ...RequestActivation.shape });
+export const RequestStateFrame = z.strictObject({ t: z.literal("request.state"), req: Req, descriptor: RequestDescriptor });
+export const RequestSettledFrame = z.strictObject({ t: z.literal("request.settled"), req: Req, id: Ulid, decision: RequestDecision.optional() });

package/dist/lib/modules/core/schema/conv-frames.js

@@ -0,0 +1,94 @@
+/**
+ * Conversation frames (spec §7, "Conversation frames"; spec §16): the frames a relay speaks after `hello` to carry
+ * conversation logs, in a roster realm and in a directory realm alike. They follow the frame rules of §7: one JSON
+ * object per text frame, discriminated by `t`; requests carry `req`, replies echo it, and a refusal is the relay
+ * binding's `nack {id: req, code, message}` (with `retryAfterMs` for `rate_limited`). Every frame is strict.
+ *
+ *   conv.append {req, event}                     → conv.ok {req, cid, seq, hash}        an op or a msg, sequenced
+ *   conv.share {req, events}                     → conv.shared {req, cid, count}        key shares, one recipient each
+ *   conv.fetch {req, cid, after, limit?, sharesAfter?} → conv.entries {req, cid, head, entries, shares, more}
+ *   conv.head {req, cids? | after?}              → conv.heads {req, heads, more}
+ *   conv.caps {req, persons}                     → conv.capabilities {req, outdated}   who cannot read conversations yet
+ *   relay → conv.push {cid, entry} | {cid, share}   a new entry to the members' online devices; a share to its recipient
+ *
+ * The relay sequences and filters; members verify everything (spec §16.4, §16.7). It never signs an entry.
+ */
+import { z } from "../../vendor/zod/index.js";
+import { LIMITS, PersonId } from "./common.js";
+import { ConvEvent, ConvHead, ConvId, ConvKeysEvent, ConvLogEntry, ConvServedEntry, ConvShareEntry } from "./conversation.js";
+const Req = z.string().min(1).max(64);
+const Count = z.number().int().min(0);
+// ---- client → relay ----
+/** Appends an op or a msg to its conversation (`event.cid`). The relay answers `conv.ok` once the entry is stored. */
+export const ConvAppendFrame = z.strictObject({ t: z.literal("conv.append"), req: Req, event: ConvEvent });
+/**
+ * Stores key shares (spec §16.6): each event to one recipient device, all of one conversation and by the sending
+ * device. All or none are stored; the relay answers `conv.shared` once they are.
+ */
+export const ConvShareFrame = z.strictObject({
+    t: z.literal("conv.share"),
+    req: Req,
+    events: z.array(ConvKeysEvent).min(1).max(LIMITS.convSharesPerFrame),
+});
+/**
+ * The entries of `cid` after `after`, in seq order, at most `limit` (and `LIMITS.convFetchEntries`) and as many as
+ * fit in a frame. `sharesAfter`: also the shares to this device after that `n`; absent, no shares.
+ */
+export const ConvFetchFrame = z.strictObject({
+    t: z.literal("conv.fetch"),
+    req: Req,
+    cid: ConvId,
+    after: Count,
+    limit: z.number().int().min(1).max(LIMITS.convFetchEntries).optional(),
+    sharesAfter: Count.optional(),
+});
+/**
+ * The heads of the named conversations, or, without `cids`, of every conversation this device's person takes part in,
+ * by cid after `after`, at most `LIMITS.convHeads`.
+ */
+export const ConvHeadFrame = z
+    .strictObject({
+    t: z.literal("conv.head"),
+    req: Req,
+    cids: z.array(ConvId).min(1).max(LIMITS.convHeads).optional(),
+    after: ConvId.optional(),
+})
+    .refine((f) => f.cids === undefined || f.after === undefined, { message: "cids or after, not both" });
+/**
+ * Which of these persons cannot read conversations yet: every current device of theirs whose latest presence the
+ * relay holds names no `conversations` feature (a daemon before the cut-over). A person with no such presence is not
+ * named. A hint from the relay: it can only make a sender refuse, never admit anything.
+ */
+export const ConvCapsFrame = z.strictObject({ t: z.literal("conv.caps"), req: Req, persons: z.array(PersonId).min(1).max(LIMITS.convOpParticipants) });
+// ---- relay → client ----
+/** `conv.append` stored: the entry's seq and h(seq), which the author recomputes. */
+export const ConvOkFrame = z.strictObject({ t: z.literal("conv.ok"), req: Req, cid: ConvId, seq: z.number().int().min(1), hash: ConvHead.shape.hash });
+/** `conv.share` stored: how many shares. */
+export const ConvSharedFrame = z.strictObject({ t: z.literal("conv.shared"), req: Req, cid: ConvId, count: z.number().int().min(1).max(LIMITS.convSharesPerFrame) });
+/**
+ * `conv.fetch`'s answer: the relay's head, the entries (an expired `msg` as its digest, `ConvExpiredEntry`) and this
+ * device's shares. `more`: ask again after the last entry (and the last share).
+ */
+export const ConvEntriesFrame = z.strictObject({
+    t: z.literal("conv.entries"),
+    req: Req,
+    cid: ConvId,
+    head: ConvHead,
+    entries: z.array(ConvServedEntry).max(LIMITS.convFetchEntries),
+    shares: z.array(ConvShareEntry).max(LIMITS.convFetchEntries),
+    more: z.boolean(),
+});
+/** One conversation's position at the relay: its head, its op head, and the last share `n` for this device (0: none). */
+export const ConvHeadView = z.strictObject({ cid: ConvId, head: ConvHead, opHead: ConvHead, shares: Count });
+/** `conv.head`'s answer. A named conversation this device's person is not in is left out, as one that does not exist. */
+export const ConvHeadsFrame = z.strictObject({ t: z.literal("conv.heads"), req: Req, heads: z.array(ConvHeadView).max(LIMITS.convHeads), more: z.boolean() });
+/** `conv.caps`'s answer: the named persons that cannot read conversations yet. */
+export const ConvCapabilitiesFrame = z.strictObject({ t: z.literal("conv.capabilities"), req: Req, outdated: z.array(PersonId).max(LIMITS.convOpParticipants) });
+/** A new entry, to the online devices of the conversation's participant persons; or a new share, to its recipient. */
+export const ConvPushFrame = z.union([
+    z.strictObject({ t: z.literal("conv.push"), cid: ConvId, entry: ConvLogEntry }),
+    z.strictObject({ t: z.literal("conv.push"), cid: ConvId, share: ConvShareEntry }),
+]);
+/** The conversation frames' types, for the relay's dispatch and `/metrics`. */
+export const CONV_FRAMES = ["conv.append", "conv.share", "conv.fetch", "conv.head", "conv.caps"];
+export const CONV_REPLIES = ["conv.ok", "conv.shared", "conv.entries", "conv.heads", "conv.capabilities", "conv.push"];