@joe-broadhead/messaging 0.0.0-stage → 0.7.1

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

@@ -0,0 +1,292 @@
+/**
+ * Conversations (spec §16): one log per conversation, sequenced by the relay, hash-chained and signed per event;
+ * sender keys for message bodies; pairwise sealed key shares; a person's `self` conversation; and the person's
+ * context rules for their agents. Every object is strict: an unknown member fails the schema.
+ *
+ *   sig    = Ed25519(by.device, DOMAIN.convEvent + JCS(event without sig))
+ *   h(0)   = SHA-256(DOMAIN.convGenesis + JCS(cid))
+ *   h(seq) = SHA-256(h(seq − 1) ‖ SHA-256(JCS(event))), over the raw 32-byte digests
+ *   dm id  = "d_" + base32lower(SHA-256(DOMAIN.dm + JCS([a, b] sorted)))[0..26]
+ *   self id= "s_" + base32lower(SHA-256(DOMAIN.self + JCS(person)))[0..26]
+ *
+ * The authority rules over these shapes are `ConvLog.apply`'s (spec §16.7).
+ */
+import { z } from "../../vendor/zod/index.js";
+import { Message, TaskArtifactUpdateEvent, TaskStatusUpdateEvent, Part } from "./a2a.js";
+import { Base64Url, ChannelName, EncKey, Hash, Key32, LIMITS, MachineId, Millis, PersonId, PROTOCOL, SessionName, Ulid } from "./common.js";
+import { DelegationChain, DelegationGrant } from "./delegation.js";
+import { RealmId } from "./realm.js";
+// ---- identifiers (spec §16.1) ----
+/** A person, or one agent of a person (`person/agent`). Every agent belongs to one person. */
+export const ParticipantId = z
+    .string()
+    .regex(/^(?:[a-z][a-z0-9-]{0,31}|p_[a-z2-7]{26})(?:\/[a-z0-9][a-z0-9._-]{0,63})?$/, "person or person/agent");
+/** `d_…` a dm (derived), `s_…` a person's `self` conversation (derived), `c_` + ULID a group or channel. */
+export const ConvId = z.string().regex(/^(?:[ds]_[a-z2-7]{26}|c_[0-7][0-9A-HJKMNP-TV-Z]{25})$/, "conversation id");
+export const ConvKind = z.enum(["dm", "group", "channel", "self"]);
+/** Channels only; every other kind is private. */
+export const Visibility = z.enum(["public", "private"]);
+/** What a late joiner may read: `shared` gets earlier chain keys, `none` reads from its add onwards. */
+export const HistoryPolicy = z.enum(["none", "shared"]);
+export const ConvRole = z.enum(["owner", "admin", "member", "guest"]);
+/** Who may do a thing in a group or channel. */
+export const Permit = z.enum(["all", "admins"]);
+/** Which mentions wake a seated agent: its own person's, any member's (under consent), or none. */
+export const RespondTo = z.enum(["self", "members", "none"]);
+/** A conversation's policy for members' agents mining it as context (spec §16.8). */
+export const AgentContext = z.enum(["members", "seats", "none"]);
+/** Why a sender epoch ends. */
+export const RekeyCause = z.enum(["removed", "device", "added", "settings", "schedule"]);
+const Seq = z.number().int().min(0);
+const RetainDays = z.number().int().min(1).max(LIMITS.retainDaysMax);
+/** A conversation event's signature: 64 bytes. */
+const Sig = z.string().regex(/^[A-Za-z0-9_-]{86}$/, "Ed25519 signature, base64url");
+/** An AES-GCM nonce: 12 bytes. */
+const Nonce = z.string().regex(/^[A-Za-z0-9_-]{16}$/, "12-byte nonce, base64url");
+const isAgent = (p) => p.includes("/");
+// ---- ops (spec §16.2, "Ops") ----
+/** A participant record as an op states it. `device` and `respondTo` are for agent participants only. */
+export const Seat = z
+    .strictObject({ p: ParticipantId, role: ConvRole, device: MachineId.optional(), respondTo: RespondTo.optional() })
+    .refine((s) => isAgent(s.p) || (s.device === undefined && s.respondTo === undefined), { message: "device and respondTo are for agents only" });
+export const ConvOp = z.discriminatedUnion("op", [
+    z.strictObject({
+        op: z.literal("create"),
+        kind: ConvKind,
+        visibility: Visibility.optional(),
+        history: HistoryPolicy,
+        retainDays: RetainDays,
+        /** A channel: the org it is open to when public. */
+        org: z.string().min(1).max(128).optional(),
+        participants: z.array(Seat).min(1).max(LIMITS.convParticipants),
+        /** Absent: `all`. */
+        post: Permit.optional(),
+        invite: Permit.optional(),
+        pins: Permit.optional(),
+        /** JCS(`ConvMeta`) sealed under the creator's epoch-0 message key 0 (spec §16.5). */
+        sealedMeta: Base64Url.max(2048).optional(),
+    }),
+    z.strictObject({ op: z.literal("add"), participants: z.array(Seat).min(1).max(LIMITS.convOpParticipants) }),
+    z.strictObject({ op: z.literal("accept") }),
+    z.strictObject({ op: z.literal("join") }),
+    z.strictObject({ op: z.literal("leave") }),
+    z.strictObject({ op: z.literal("remove"), participants: z.array(ParticipantId).min(1).max(LIMITS.convOpParticipants) }),
+    z.strictObject({ op: z.literal("role"), p: ParticipantId, role: ConvRole }),
+    z.strictObject({ op: z.literal("seat"), p: ParticipantId, device: MachineId.optional(), respondTo: RespondTo.optional() }),
+    z.strictObject({
+        op: z.literal("settings"),
+        visibility: Visibility.optional(),
+        history: HistoryPolicy.optional(),
+        retainDays: RetainDays.optional(),
+        post: Permit.optional(),
+        invite: Permit.optional(),
+        pins: Permit.optional(),
+    }),
+    z.strictObject({ op: z.literal("archive"), on: z.boolean() }),
+    z.strictObject({ op: z.literal("rekey"), epoch: z.number().int().min(1), cause: RekeyCause }),
+]);
+/** The plaintext of `create.sealedMeta` and of a `meta` body's fields. */
+export const ConvMeta = z.strictObject({
+    name: ChannelName.optional(),
+    topic: z.string().max(250).optional(),
+    purpose: z.string().max(250).optional(),
+});
+// ---- message bodies (spec §16.3) ----
+export const Mention = z.union([
+    z.strictObject({ p: ParticipantId }),
+    /** Every participant person. Never wakes an agent. */
+    z.strictObject({ all: z.literal("channel") }),
+    /** Every participant person online now. Never wakes an agent. */
+    z.strictObject({ all: z.literal("here") }),
+]);
+/** A file in the relay's blob store, sealed under its own AES-256-GCM key. The shape only; files land later. */
+export const Attachment = z.strictObject({
+    blob: z.string().regex(/^b_[A-Za-z0-9_-]{43}$/, "blob id"),
+    key: Key32,
+    nonce: Nonce,
+    sha256: Hash,
+    bytes: z.number().int().positive().max(LIMITS.blobBytes),
+    mime: z.string().max(100),
+    name: z.string().max(255),
+    thumb: Base64Url.max(16_384).optional(),
+});
+// ---- linked channels (spec §16.10; reserved: validated, no daemon behaviour yet) ----
+/** An outside channel a person may link as an alias of themselves. Telegram first, then Slack. */
+export const LinkChannel = z.enum(["telegram", "slack"]);
+/** What a linked channel may do: Jelly's `chat` and `view` action classes (spec §8.11), never more. */
+export const LinkAuthority = z.enum(["chat", "view"]);
+/** Who may mirror a conversation to a linked channel: nobody (the default), its owners and admins, or any member. */
+export const BridgePolicy = z.enum(["none", "admins", "members"]);
+/** A line's provenance when its person wrote it from a linked channel. Signed and sealed with the event. */
+export const Via = z.strictObject({ channel: LinkChannel });
+/**
+ * A person's linked channel, as a human-tier device records it in the person's `self` conversation (never the
+ * device log, which is public). `account` is the channel's own id for the person's account (Telegram `from.id`;
+ * Slack `team/user`); it exists only inside the sealed `self` conversation. The proof is the one-time code's digest
+ * and the six-digit code the person saw match on both sides. `revokedAt` ends it; the last writer wins by `seq`.
+ */
+export const LinkRecord = z.strictObject({
+    id: Ulid,
+    channel: LinkChannel,
+    account: z.string().regex(/^[A-Za-z0-9._:/-]{1,128}$/, "channel account id"),
+    /** The person's device that runs the bridge and wrote this record. */
+    host: MachineId,
+    proof: z.strictObject({ method: z.literal("code-sas"), codeDigest: Hash, sas: z.string().regex(/^[0-9]{6}$/, "six digits") }),
+    authority: z
+        .array(LinkAuthority)
+        .min(1)
+        .max(2)
+        .refine((a) => new Set(a).size === a.length, { message: "each authority once" }),
+    linkedAt: Millis,
+    revokedAt: Millis.optional(),
+});
+/**
+ * Who can read a piece of content, for the audience guard: a person, or a linked channel's provider as
+ * `ext:<channel>:<link id>`. Not on the wire; the guard's reader sets are typed with it.
+ */
+export const ReaderId = z.union([PersonId, z.string().regex(/^ext:(?:telegram|slack):[0-7][0-9A-HJKMNP-TV-Z]{25}$/, "ext:<channel>:<link id>")]);
+export const ReaderSet = z.array(ReaderId).max(LIMITS.convParticipants + LIMITS.convParticipants);
+export const ReceiptStage = z.enum(["delivered", "handed_to_agent", "read"]);
+/**
+ * A task as a thread (spec §16.3): `request` is the thread root, from the requester to an agent participant;
+ * `status` and `artifact` come from that agent; `cancel` and `followUp` from the requester.
+ */
+export const TaskEventBody = z.discriminatedUnion("k", [
+    z.strictObject({ k: z.literal("request"), to: ParticipantId.refine(isAgent, "a task goes to an agent"), message: Message, delegation: DelegationChain }),
+    z.strictObject({ k: z.literal("status"), root: Ulid, update: TaskStatusUpdateEvent }),
+    z.strictObject({ k: z.literal("artifact"), root: Ulid, update: TaskArtifactUpdateEvent }),
+    z.strictObject({ k: z.literal("cancel"), root: Ulid, reason: z.string().max(1000).optional() }),
+    z.strictObject({ k: z.literal("followUp"), root: Ulid, message: Message }),
+]);
+export const ContextAccess = z.enum(["allow", "ask", "off"]);
+export const ContextKind = z.enum(["own", "dm", "group", "channel.private", "channel.public"]);
+export const ContextScope = z.union([z.strictObject({ cid: ConvId }), z.strictObject({ kind: ContextKind })]);
+/** One of a person's rules for which of their agents may mine which conversations (spec §16.8). */
+export const ContextRule = z.strictObject({
+    agent: z.union([SessionName, z.literal("*")]),
+    scope: ContextScope,
+    access: ContextAccess,
+    /** Absent: the conversation's retention. */
+    lookbackDays: RetainDays.optional(),
+});
+const scopeKey = (r) => `${r.agent} ${"cid" in r.scope ? `cid:${r.scope.cid}` : `kind:${r.scope.kind}`}`;
+/** A person's whole rule set: at most one rule per (agent, scope). */
+export const ContextRules = z
+    .array(ContextRule)
+    .max(LIMITS.contextRules)
+    .refine((rules) => new Set(rules.map(scopeKey)).size === rules.length, { message: "at most one rule per agent and scope" });
+/** One sender chain at one index: `ck` is the chain key for message `idx` of `device`'s chain in `epoch`. */
+export const KeyShare = z.strictObject({ epoch: Seq, device: MachineId, idx: Seq, ck: Key32 });
+/** The plaintext of one recipient's sealed share in a `keys` event. */
+export const KeySharePayload = z.strictObject({ shares: z.array(KeyShare).min(1).max(LIMITS.keyShares) });
+/** The `self` conversation's bodies (spec §16.3, "The self conversation"). The last writer wins by `seq`. */
+export const SyncBody = z.discriminatedUnion("s", [
+    z.strictObject({ s: z.literal("read"), cid: ConvId, upTo: Seq, thread: Ulid.optional() }),
+    z.strictObject({ s: z.literal("unread"), cid: ConvId, from: z.number().int().min(1) }),
+    z.strictObject({
+        s: z.literal("prefs"),
+        cid: ConvId,
+        notify: z.enum(["all", "mentions", "none"]),
+        muteUntil: Millis.optional(),
+        /** dms only; absent is off. */
+        receipts: z.boolean().optional(),
+    }),
+    z.strictObject({ s: z.literal("follow"), cid: ConvId, thread: Ulid, on: z.boolean() }),
+    z.strictObject({ s: z.literal("save"), cid: ConvId, target: Ulid, on: z.boolean() }),
+    z.strictObject({ s: z.literal("draft"), cid: ConvId, thread: Ulid.optional(), text: z.string().max(8000) }),
+    z.strictObject({ s: z.literal("joined"), cid: ConvId, on: z.boolean() }),
+    /** A consent grant (spec §6.9), verified with `verifyConsentGrant` over this raw value. */
+    z.strictObject({ s: z.literal("grant"), grant: z.record(z.string(), z.unknown()) }),
+    z.strictObject({ s: z.literal("context"), rules: ContextRules }),
+    z.strictObject({ s: z.literal("localRetention"), cid: ConvId, days: RetainDays }),
+    z.strictObject({ s: z.literal("keys"), cid: ConvId, shares: z.array(KeyShare).min(1).max(LIMITS.keyShares) }),
+    z.strictObject({ s: z.literal("link"), link: LinkRecord }),
+]);
+/** The plaintext of a `msg` event. */
+export const MsgBody = z.discriminatedUnion("t", [
+    z.strictObject({
+        t: z.literal("line"),
+        text: z.string().max(LIMITS.lineChars),
+        format: z.enum(["plain", "md"]),
+        /** The thread root's event id. */
+        thread: Ulid.optional(),
+        /** A thread reply also shown in the main view. */
+        broadcast: z.boolean().optional(),
+        mentions: z.array(Mention).max(LIMITS.mentions).optional(),
+        files: z.array(Attachment).max(LIMITS.files).optional(),
+        /** A2A data parts, rendered as cards. */
+        parts: z.array(Part).max(8).optional(),
+        /** The mention this line answers. */
+        answers: Ulid.optional(),
+        grants: z.array(DelegationGrant).max(LIMITS.agentMentions).optional(),
+        /** Written by its person from a linked channel. Never on an agent's line. */
+        via: Via.optional(),
+    }),
+    z.strictObject({ t: z.literal("edit"), target: Ulid, text: z.string().max(LIMITS.lineChars), mentions: z.array(Mention).max(LIMITS.mentions).optional() }),
+    z.strictObject({ t: z.literal("delete"), target: Ulid }),
+    z.strictObject({ t: z.literal("react"), target: Ulid, key: z.string().min(1).max(64), on: z.boolean() }),
+    z.strictObject({ t: z.literal("pin"), target: Ulid, on: z.boolean() }),
+    z.strictObject({ t: z.literal("task"), task: TaskEventBody }),
+    z.strictObject({ t: z.literal("receipt"), target: Ulid, stage: ReceiptStage }),
+    z.strictObject({
+        t: z.literal("meta"),
+        name: ChannelName.optional(),
+        topic: z.string().max(250).optional(),
+        purpose: z.string().max(250).optional(),
+    }),
+    z
+        .strictObject({ t: z.literal("policy"), agentContext: AgentContext.optional(), bridges: BridgePolicy.optional() })
+        .refine((p) => p.agentContext !== undefined || p.bridges !== undefined, { message: "a policy sets agentContext, bridges or both" }),
+    z.strictObject({ t: z.literal("sync"), sync: SyncBody }),
+]);
+// ---- events and the log (spec §16.2) ----
+const Position = z.strictObject({ seq: Seq, hash: Hash });
+const header = {
+    v: z.literal(PROTOCOL),
+    realm: RealmId,
+    cid: ConvId,
+    /** Chosen by the author; unique in the conversation. */
+    id: Ulid,
+    by: z.strictObject({ person: PersonId, device: MachineId, agent: SessionName.optional() }),
+    ts: Millis,
+    /** The last op the author applied: its seq and h(seq), or {0, h(0)} before any. */
+    opHead: Position,
+    /** The head the author had, for gossip. */
+    seen: z.strictObject({ seq: z.number().int().min(1), hash: Hash }).optional(),
+};
+/** A control op, in plaintext: the relay routes and checks authority by it. */
+export const ConvOpEvent = z.strictObject({ ...header, class: z.literal("op"), body: ConvOp, sig: Sig });
+/** base64url(nonce ‖ AES-256-GCM ciphertext ‖ tag) of JCS(`MsgBody`), sealed under one message key. */
+export const SealedBody = Base64Url.min(38).max(Math.ceil(((LIMITS.convPlaintextBytes + 28) * 4) / 3));
+/** Everything else, sealed under the author device's sender key at (`epoch`, `idx`). */
+export const ConvMsgEvent = z.strictObject({
+    ...header,
+    class: z.literal("msg"),
+    epoch: Seq,
+    idx: Seq,
+    /** Own-person wake hint only: sessions of `by.person` that this event may wake. */
+    wake: z.array(SessionName).min(1).max(LIMITS.wakeHints).optional(),
+    body: SealedBody,
+    sig: Sig,
+});
+/** One recipient device's share, sealed to it under the envelope seal (spec §5, "Sealing"). */
+export const SealedShare = z.strictObject({
+    to: z.strictObject({ person: PersonId, device: MachineId }),
+    epk: EncKey,
+    nonce: Nonce,
+    ct: Base64Url.max(Math.ceil(((LIMITS.keyShares * 160 + 16) * 4) / 3)),
+});
+export const KeysBody = z.strictObject({
+    shares: z
+        .array(SealedShare)
+        .min(1)
+        .max(LIMITS.keySharesPerEvent)
+        .refine((shares) => new Set(shares.map((s) => s.to.device)).size === shares.length, { message: "one share per device" }),
+});
+/** Sender-key and history shares, sealed pairwise; the relay serves each share only to its recipient. */
+export const ConvKeysEvent = z.strictObject({ ...header, class: z.literal("keys"), body: KeysBody, sig: Sig });
+export const ConvEvent = z.discriminatedUnion("class", [ConvOpEvent, ConvMsgEvent, ConvKeysEvent]);
+/** An event as the relay stores and serves it. The relay does not sign it; members verify the chain. */
+export const ConvLogEntry = z.strictObject({ seq: z.number().int().min(1), prev: Hash, event: ConvEvent });
+/** A log position: a seq and h(seq). */
+export const ConvHead = Position;

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

@@ -0,0 +1,58 @@
+/**
+ * Delegation chains (spec §6.7). A task request carries the chain of signed
+ * grants from its root requester to the session it addresses, so an executor (and whoever approves
+ * its work) sees who asked whom, for which task.
+ *
+ *   sig         = Ed25519(by, DOMAIN.delegation + JCS(grant without sig))
+ *   grantHash   = SHA-256(UTF-8(JCS(grant))), base64url, over the full grant including sig
+ *   chain       = [root grant, …, grant to this session]; each later grant has parent = grantHash(previous)
+ *
+ * Every hop is a new statement by the machine that delegates; nothing is forwarded as a credential.
+ * A hop can only narrow: scope ⊆ the previous scope (absent = unrestricted), maxDepth ≤ the previous
+ * maxDepth, exp ≤ the previous exp. `verifyChain` in core checks all of it.
+ *
+ * Grants are loose objects: a field a newer signer adds stays in the parsed grant, so the signature
+ * and the hash still cover it.
+ */
+import { z } from "../../vendor/zod/index.js";
+import { Base64Url, Hash, LIMITS, MachineId, Millis, SessionAddress, Ulid } from "./common.js";
+import { RealmId } from "./realm.js";
+/** A scope label. Its meaning is left to clients; the protocol only checks that a hop never widens the set. */
+export const DelegationScope = z.string().regex(/^[a-z0-9][a-z0-9._:/-]{0,63}$/, "scope label");
+export const DelegationGrant = z.looseObject({
+    /** The realm of the signer and of every session in the chain (spec §5). */
+    realm: RealmId,
+    /** The task this grant asks `to` to run: the task id of this hop. */
+    task: Ulid,
+    /** The delegating session. Its person and label must be the roster's for `by`. */
+    from: SessionAddress,
+    /** The session asked to run `task`. */
+    to: SessionAddress,
+    /** The signing machine: a current member. */
+    by: MachineId,
+    ts: Millis,
+    /** `ts ≤ exp`, `exp − ts ≤ LIMITS.ttlMs`, and no later than the previous grant's exp. */
+    exp: Millis,
+    /** The most grants any chain through this grant may hold. */
+    maxDepth: z.number().int().min(1).max(LIMITS.delegationDepth),
+    /** Absent: unrestricted. `[]`: nothing named, the narrowest scope. */
+    scope: z.array(DelegationScope).max(LIMITS.delegationScopes).optional(),
+    /** grantHash of the previous grant; absent on the root. */
+    parent: Hash.optional(),
+    sig: Base64Url,
+});
+/** Root first. Carried as `MessagePayload.delegation` on `kind: "task"` only. */
+export const DelegationChain = z.array(DelegationGrant).min(1).max(LIMITS.delegationDepth);
+/** What a verified chain says, as the daemon shows it on `InboxItem.chain` and `TaskRecord.chain`. */
+export const DelegationSummary = z.object({
+    /** Every session in the chain: the root requester first, the session the chain reaches last. */
+    addresses: z.array(SessionAddress).min(2).max(LIMITS.delegationDepth + 1),
+    /** Grants in the chain: `addresses.length − 1`. */
+    depth: z.number().int().min(1).max(LIMITS.delegationDepth),
+    /** The smallest maxDepth along the chain: the most grants any extension of it may hold. */
+    maxDepth: z.number().int().min(1).max(LIMITS.delegationDepth),
+    /** The last grant's scope; absent means unrestricted. Peer-chosen labels. */
+    scope: z.array(DelegationScope).max(LIMITS.delegationScopes).optional(),
+    /** The earliest grant expiry along the chain. */
+    exp: Millis,
+});

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

@@ -0,0 +1,270 @@
+/**
+ * Directory frames (spec §7, "Directory frames"; design §3.2): the frames a hosted relay, one that runs the
+ * key directory, speaks on the same WebSocket as the relay binding. 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`).
+ *
+ * Connection, hosted:
+ *   relay  → challenge {proto, relay, nonce}                      (unchanged)
+ *   client → [pre-auth, optional] dir.bind {req, entry}           first binding of this device → dir.ok {req, person, seq, sth}
+ *   client → [pre-auth, optional] dir.sth, dir.heads, dir.device  what a device about to bind reads; heads only, no log
+ *   client → [pre-auth, optional] dir.lookup {.., proof}          a device reads its own person's log (its key proven)
+ *   client → hello {realm, person, device, ts, sig}               sig = Ed25519(device, DOMAIN.relayAuth + JCS(hostedRelayAuthPayload))
+ *   relay  → welcome {sth}                                        or close 4001 (`unknown_device`) when the device is not current
+ *
+ * After welcome, besides send / deliver / presence / recv.ack / ping of §7:
+ *   dir.append {req, entry}               → dir.ok {req, seq, sth}
+ *   dir.keys {req, stmt}                  → dir.ok {req, sth}
+ *   dir.sth {req, size?, from?, epoch?}   → dir.sthIs {req, sth, head, consistency?, epoch?, rotation?}
+ *   dir.lookup {req, persons, size?}      → dir.persons {req, sth, head, persons}
+ *   dir.heads {req, persons, size?}       → dir.headsAre {req, sth, head, persons}
+ *   dir.resolve {req, handle | email}     → dir.resolved {req, persons}
+ *   dir.search {req, query, limit}        → dir.resolved {req, persons}
+ *   dir.watch {req, persons}              → dir.ok {req}; then dir.changed {persons, sth} pushes
+ *   presence.watch {req, persons}         → dir.ok {req}
+ *   dir.erase {req, entries, token}       → dir.ok {req}
+ *   wake.arm {req, url, ticket, agents, awaiting} → dir.ok {req}   a Jelly host's device, before it sleeps (§7, "Wake tickets")
+ *   wake.disarm {req}                     → dir.ok {req}
+ *   relay → dir.unbound {entry, sth}      this device's own unbind, just before close 4003
+ *
+ * The directory's own structures (HostedPersonId, LogEntry, KeysStatement, STH, PersonView, ...) are in
+ * `schema/directory.ts` and `schema/common.ts`, with their verifiers in `packages/core/src/directory/` (spec §15).
+ * The frames take a hosted person (`HostedPersonId`) only.
+ */
+import { z } from "../../vendor/zod/index.js";
+import { Base64Url, Hash, HostedPersonId, LIMITS, Millis, RELAY_PROTOCOL, SessionName, Ulid } from "./common.js";
+import { EpochProof } from "./directory.js";
+import { RealmId } from "./realm.js";
+import { DeviceId, KeyRotation, KeysStatement, LogEntry, PersonHead, PersonView, STH } from "./directory.js";
+import { Jws } from "./jelly.js";
+const Req = z.string().min(1).max(64);
+const Size = z.number().int().positive();
+/** A hosted handle (design §6.1): the normalised local part of a verified email. */
+export const Handle = z.string().regex(/^[a-z][a-z0-9-]{0,31}$/, "lowercase handle");
+/** An exact email address, lower-cased (design §6.1): the domain is ASCII, as Jelly ID's verified emails are. */
+export const Email = z
+    .string()
+    .max(254)
+    .regex(/^[^\s@A-Z]{1,64}@(?:[a-z0-9-]+\.)+[a-z0-9-]+$/, "lower-case email address");
+/** An org (design §2.3): `domain:<d>` until Jelly contract v1.2, then the organisation id. Absent for an individual. */
+export const OrgId = z.string().min(1).max(200);
+/** The value a device signs (with `DOMAIN.relayAuth`) in the hosted `hello` frame. */
+export function hostedRelayAuthPayload(args) {
+    return { proto: RELAY_PROTOCOL, relay: args.relay, realm: args.realm, person: args.person, device: args.device, nonce: args.nonce, ts: args.ts };
+}
+/** The value a device signs (with `DOMAIN.dirRead`) in a `dir.lookup` before `hello`: its key, on this connection. */
+export function dirReadPayload(args) {
+    return { proto: RELAY_PROTOCOL, relay: args.relay, realm: args.realm, device: args.device, nonce: args.nonce };
+}
+/** A device's proof before `hello` (`dirReadPayload`): `sig` by `device` over this connection's challenge. */
+export const DirReadProof = z.strictObject({ device: DeviceId, sig: Base64Url });
+// ---- client → relay ----
+/** Pre-auth: the first binding of this device, a `bind` entry with a `jelly` authority (design §2.2). */
+export const DirBindFrame = z.object({ t: z.literal("dir.bind"), req: Req, entry: LogEntry });
+/** The hosted `hello`: authenticates a device of a person in a directory realm. A roster relay refuses it. */
+export const HostedHelloFrame = z.object({
+    t: z.literal("hello"),
+    realm: RealmId,
+    person: HostedPersonId,
+    device: DeviceId,
+    ts: Millis,
+    sig: Base64Url,
+});
+/** An `attest`, an `unbind`, or the `bind` of a QR approval (design §2.1, §2.5), appended to the sender's person's log. */
+export const DirAppendFrame = z.object({ t: z.literal("dir.append"), req: Req, entry: LogEntry });
+/** The sending device's own latest encryption-key statement (design §2.6). */
+export const DirKeysFrame = z.object({ t: z.literal("dir.keys"), req: Req, stmt: KeysStatement });
+/**
+ * The latest STH, or the STH at `size`. `from`: also a consistency proof from that size. `epoch`: also that
+ * epoch-log leaf with its inclusion proof (an entry's first epoch, design §2.2 step 7).
+ */
+export const DirSthFrame = z.object({
+    t: z.literal("dir.sth"),
+    req: Req,
+    size: Size.optional(),
+    from: Size.optional(),
+    epoch: z.number().int().nonnegative().optional(),
+});
+/**
+ * Persons' views at the directory's latest STH, which is at least `size`. `knownSeq`: send only the log after it.
+ * Before `hello`, only with `proof` (a device's key on this connection), and only for persons whose log names that
+ * device, current or not: a device reads its own person's log; anyone else reads heads (`dir.heads`).
+ */
+export const DirLookupFrame = z.object({
+    t: z.literal("dir.lookup"),
+    req: Req,
+    persons: z
+        .array(z.object({ person: HostedPersonId, knownSeq: z.number().int().nonnegative().optional() }))
+        .min(1)
+        .max(LIMITS.dirLookupPersons),
+    size: Size.optional(),
+    proof: DirReadProof.optional(),
+});
+/** Persons' heads (`PersonHead`) at the STH of `size`, or the latest; before or after `hello`. */
+export const DirHeadsFrame = z.object({
+    t: z.literal("dir.heads"),
+    req: Req,
+    persons: z.array(HostedPersonId).min(1).max(LIMITS.dirLookupPersons),
+    size: Size.optional(),
+});
+/**
+ * Before `hello` only: the person whose log binds `device` as a current device, as `dir.headsAre` with that one head at
+ * the latest STH, or none. A device approved by link learns its person this way (design §2.5), then reads that
+ * person's log with `dir.lookup` and its proof.
+ */
+export const DirDeviceFrame = z.object({
+    t: z.literal("dir.device"),
+    req: Req,
+    device: DeviceId,
+});
+/** By handle (same org only) or by exact email: exactly one of the two. */
+export const DirResolveFrame = z
+    .object({ t: z.literal("dir.resolve"), req: Req, handle: Handle.optional(), email: Email.optional() })
+    .refine((frame) => (frame.handle === undefined) !== (frame.email === undefined), { message: "exactly one of handle and email" });
+/** A same-org prefix search on handle, name and email local part. */
+export const DirSearchFrame = z.object({
+    t: z.literal("dir.search"),
+    req: Req,
+    query: z.string().min(1).max(64),
+    limit: z.number().int().min(1).max(LIMITS.dirSearchResults),
+});
+/** Sets the persons this connection watches for log and key changes; it replaces the previous set, and `[]` clears it. */
+export const DirWatchFrame = z.object({
+    t: z.literal("dir.watch"),
+    req: Req,
+    persons: z.array(HostedPersonId).max(LIMITS.watchPersons),
+});
+/** Sets the persons whose presence this connection watches (design §8.2); it replaces the previous set. */
+export const PresenceWatchFrame = z.object({
+    t: z.literal("presence.watch"),
+    req: Req,
+    persons: z.array(HostedPersonId).max(LIMITS.watchPersons),
+});
+/** The person erases their account from Messaging (design §3.7): an `unbind` of every current device, and a fresh `cnf` token for this device. */
+export const DirEraseFrame = z.object({
+    t: z.literal("dir.erase"),
+    req: Req,
+    entries: z.array(LogEntry).min(1).max(LIMITS.devicesPerPerson),
+    token: Jws,
+});
+/** Most agents a wake ticket's filter names, and most awaited task requests (spec §7, "Wake tickets"). */
+export const WAKE_AGENTS = 64;
+export const WAKE_AWAITING = 500;
+/** Most bytes of a wake ticket, and its longest life: Jelly's `jelly-wake+jwt` lives at most seven days. */
+export const WAKE_TICKET_BYTES = 4096;
+export const WAKE_TICKET_MAX_S = 7 * 24 * 60 * 60;
+/** A wake URL: `https://<issuer host>/hosts/<hst>/wake` (or `http://` to a loopback issuer, for tests). */
+export const WakeUrl = z.string().max(2048).regex(/^https?:\/\/[^/?#@\s]+\/hosts\/hst_[A-Za-z0-9._:-]{1,123}\/wake$/, "a Jelly ID wake URL");
+/**
+ * A Jelly host's device arms a wake ticket before the host sleeps (spec §7, "Wake tickets"). `url` is Jelly ID's wake
+ * endpoint for this device's host; `ticket` the host's single-use `jelly-wake+jwt`, which the relay never verifies
+ * (Jelly ID does) and reads only for its `exp`; `agents` the local sessions whose own person's mail may wake the host;
+ * `awaiting` the request envelope ids of the tasks those agents wait on, whose updates (`replyTo`) may wake it. A new
+ * arm replaces the device's previous one.
+ */
+export const WakeArmFrame = z.object({
+    t: z.literal("wake.arm"),
+    req: Req,
+    url: WakeUrl,
+    ticket: Jws.refine((ticket) => ticket.length <= WAKE_TICKET_BYTES, { message: `at most ${WAKE_TICKET_BYTES} bytes` }),
+    agents: z.array(SessionName).max(WAKE_AGENTS),
+    awaiting: z.array(Ulid).max(WAKE_AWAITING),
+});
+/** The relay forgets this device's wake ticket. */
+export const WakeDisarmFrame = z.object({ t: z.literal("wake.disarm"), req: Req });
+/** Every frame of a directory client that the relay binding (§7) does not already define. */
+export const DirectoryClientFrame = z.discriminatedUnion("t", [
+    DirBindFrame,
+    HostedHelloFrame,
+    DirAppendFrame,
+    DirKeysFrame,
+    DirSthFrame,
+    DirLookupFrame,
+    DirDeviceFrame,
+    DirHeadsFrame,
+    DirResolveFrame,
+    DirSearchFrame,
+    DirWatchFrame,
+    PresenceWatchFrame,
+    DirEraseFrame,
+    WakeArmFrame,
+    WakeDisarmFrame,
+]);
+// ---- relay → client ----
+/** The answer to a hosted `hello`: the directory's latest STH. */
+export const HostedWelcomeFrame = z.object({ t: z.literal("welcome"), sth: STH });
+/**
+ * Success. `dir.bind` gets `person`, `seq` and `sth`; `dir.append` gets `seq` and `sth`; `dir.keys` gets `sth`;
+ * `dir.watch`, `presence.watch` and `dir.erase` get none of them.
+ */
+export const DirOkFrame = z.object({
+    t: z.literal("dir.ok"),
+    req: Req,
+    person: HostedPersonId.optional(),
+    seq: z.number().int().nonnegative().optional(),
+    sth: STH.optional(),
+});
+/**
+ * An STH; `head` is its last epoch-log leaf (index `size − 1`, whose `mapRoot` lookups at this STH prove
+ * against) with its inclusion proof. `consistency` answers `from`, `epoch` answers `epoch`, and `rotation`
+ * comes with any STH signed by a new epoch key (design §3.8).
+ */
+export const DirSthIsFrame = z.object({
+    t: z.literal("dir.sthIs"),
+    req: Req,
+    sth: STH,
+    head: EpochProof,
+    consistency: z.array(Hash).max(64).optional(),
+    epoch: EpochProof.optional(),
+    rotation: KeyRotation.optional(),
+});
+/** One view per person asked, at `sth`. Fewer when the frame would pass `LIMITS.frameBytes`: ask again for the rest. */
+export const DirPersonsFrame = z.object({
+    t: z.literal("dir.persons"),
+    req: Req,
+    sth: STH,
+    /** The STH's last epoch leaf (index `size − 1`) with its inclusion proof: what `verifyPersonView` checks the map against. */
+    head: EpochProof,
+    persons: z.array(PersonView).max(LIMITS.dirLookupPersons),
+});
+/** One head per person asked, at `sth`; `head` as in `dir.persons`. */
+export const DirHeadsAreFrame = z.object({
+    t: z.literal("dir.headsAre"),
+    req: Req,
+    sth: STH,
+    head: EpochProof,
+    persons: z.array(PersonHead).max(LIMITS.dirLookupPersons),
+});
+/** A person a handle, an email or a search matched, as the directory reads them from the person's latest verified token. */
+export const ResolvedPerson = z.object({
+    person: HostedPersonId,
+    handle: Handle,
+    name: z.string().max(200).optional(),
+    email: Email.optional(),
+    org: OrgId.optional(),
+});
+/** An unknown email and an undiscoverable one get the same empty answer. */
+export const DirResolvedFrame = z.object({
+    t: z.literal("dir.resolved"),
+    req: Req,
+    persons: z.array(ResolvedPerson).max(LIMITS.dirSearchResults),
+});
+/** A push: the logs or keys of these watched persons changed as of `sth`. */
+export const DirChangedFrame = z.object({
+    t: z.literal("dir.changed"),
+    persons: z.array(HostedPersonId).min(1).max(LIMITS.watchPersons),
+    sth: STH,
+});
+/** A push to a device just removed: its own signed `unbind` entry, before the relay closes with 4003. */
+export const DirUnboundFrame = z.object({ t: z.literal("dir.unbound"), entry: LogEntry, sth: STH });
+/** Every frame a directory relay sends that the relay binding (§7) does not already define. */
+export const DirectoryRelayFrame = z.discriminatedUnion("t", [
+    HostedWelcomeFrame,
+    DirOkFrame,
+    DirSthIsFrame,
+    DirPersonsFrame,
+    DirHeadsAreFrame,
+    DirResolvedFrame,
+    DirChangedFrame,
+    DirUnboundFrame,
+]);