@joe-broadhead/messaging 0.0.0-stage → 0.7.0

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,
+]);

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

@@ -0,0 +1,169 @@
+/**
+ * Hosted realms: the key directory's signed and hashed objects (spec §15). Every object here is hashed or
+ * signed as JCS, so each is strict: an unknown member is refused rather than carried unsigned.
+ */
+import { z } from "../../vendor/zod/index.js";
+import { Base64Url, EncKey, Hash, HostedPersonId, Key32, LIMITS, MachineId, MachineLabel, Millis, PROTOCOL } from "./common.js";
+import { Jws } from "./jelly.js";
+import { RealmId } from "./realm.js";
+/** A map proof (§15.5): a 256-bit bitmap of the non-empty siblings, and those siblings, bottom up. */
+export const MapProof = z.strictObject({
+    bitmap: Base64Url.length(43),
+    siblings: z.array(Hash).max(256),
+});
+/** What a live person's map leaf commits to (§15.5): their log head, and the hashes of their current keys statements. */
+export const MapValue = z.strictObject({
+    log: z.strictObject({ seq: z.number().int().nonnegative(), hash: Hash }),
+    keys: z.array(Hash).max(LIMITS.devicesPerPerson),
+});
+/** A device's id: its Ed25519 public key, as a machine's (§3). */
+export const DeviceId = MachineId.describe("Ed25519 public key of a device, base64url");
+/** What kind of device it is; informational. */
+export const DeviceKind = z.enum(["jelly-host", "laptop", "server", "other"]);
+/** Why a device was unbound (§15.3). */
+export const UnbindReason = z.enum(["self", "removed", "lost", "replaced", "account_deleted"]);
+/** An Ed25519 signature: 64 bytes, base64url. */
+const Signature = z.string().regex(/^[A-Za-z0-9_-]{86}$/, "64 bytes, base64url without padding");
+/**
+ * A new device's request to be approved by one of its person's devices (§15.3): shown as
+ * `messaging-link.<base64url(JCS(request))>`. `sig` is the new device's, over JCS(request without sig).
+ */
+export const LinkRequest = z.strictObject({
+    v: z.literal(PROTOCOL),
+    realm: RealmId,
+    device: DeviceId,
+    enc: EncKey,
+    label: MachineLabel,
+    kind: DeviceKind,
+    nonce: z.string().regex(/^[A-Za-z0-9_-]{22}$/, "16 bytes, base64url"),
+    ts: Millis,
+    sig: Signature,
+});
+/** Who vouches for a device-log entry (§15.3). */
+export const Authority = z.discriminatedUnion("kind", [
+    /** Jelly ID, by a resource token bound (`cnf`) to the signing device. */
+    z.strictObject({ kind: z.literal("jelly"), token: Jws }),
+    /** One of the person's Jelly-vouched devices, approving the link request of a new one; the entry's `by`. */
+    z.strictObject({ kind: z.literal("device"), approver: DeviceId, link: LinkRequest }),
+    /** The directory, by its epoch key: only the unbinds of an erased account. */
+    z.strictObject({ kind: z.literal("service") }),
+    /** The device itself: only its own unbind. */
+    z.strictObject({ kind: z.literal("self") }),
+]);
+/**
+ * One entry of a hosted person's device log (§15.3), hash-chained by `prev` and signed by `by` over
+ * JCS(entry without sig) with `DOMAIN.deviceLog`. `bind` names the device's `label` and `kind`; `attest` may
+ * change them; `unbind` gives a `reason` and nothing else.
+ */
+export const LogEntry = z
+    .strictObject({
+    v: z.literal(PROTOCOL),
+    realm: RealmId,
+    person: HostedPersonId,
+    seq: z.number().int().nonnegative(),
+    prev: Hash.nullable(),
+    ts: Millis,
+    op: z.enum(["bind", "attest", "unbind"]),
+    device: DeviceId,
+    label: MachineLabel.optional(),
+    kind: DeviceKind.optional(),
+    reason: UnbindReason.optional(),
+    authority: Authority,
+    by: Key32,
+    sig: Signature,
+})
+    .refine((entry) => (entry.seq === 0) === (entry.prev === null), { message: "prev is null exactly at seq 0", path: ["prev"] })
+    .refine((entry) => entry.op !== "bind" || (entry.label !== undefined && entry.kind !== undefined), { message: "a bind names label and kind", path: ["label"] })
+    .refine((entry) => (entry.op === "unbind") === (entry.reason !== undefined), { message: "an unbind, and only an unbind, gives a reason", path: ["reason"] })
+    .refine((entry) => entry.op !== "unbind" || (entry.label === undefined && entry.kind === undefined), { message: "an unbind names no label or kind", path: ["label"] });
+/**
+ * A device's self-signed encryption key (§15.4): the directory keeps the latest per device (`seq` strictly
+ * increases). `sig` is the device's, over JCS(statement without sig) with `DOMAIN.deviceKeys`.
+ */
+export const KeysStatement = z.strictObject({
+    v: z.literal(PROTOCOL),
+    realm: RealmId,
+    person: HostedPersonId,
+    device: DeviceId,
+    enc: EncKey,
+    seq: z.number().int().nonnegative(),
+    ts: Millis,
+    sig: Signature,
+});
+/**
+ * One leaf of the epoch log (§15.6): the map root of epoch `epoch` and of the epoch before it (`E[256]`, the
+ * empty map's root, before epoch 0). The leaf's data is UTF-8(JCS(leaf)).
+ */
+export const EpochLeaf = z.strictObject({
+    epoch: z.number().int().nonnegative(),
+    ts: Millis,
+    mapRoot: Hash,
+    prevMapRoot: Hash,
+});
+/** An epoch-log leaf and its RFC 9162 audit path in the tree of the STH it is sent with (§15.6). */
+export const EpochProof = z.strictObject({
+    index: z.number().int().nonnegative(),
+    leaf: EpochLeaf,
+    inclusion: z.array(Hash).max(64),
+});
+/**
+ * A signed tree head of the epoch log (§15.6): `size` leaves with root `root`, at `ts`. `sig` is the directory's
+ * epoch key's, over JCS(head without sig) with `DOMAIN.epoch`.
+ */
+export const STH = z.strictObject({
+    v: z.literal(PROTOCOL),
+    realm: RealmId,
+    size: z.number().int().positive(),
+    root: Hash,
+    ts: Millis,
+    sig: Signature,
+});
+/**
+ * The directory's epoch key moving from `old` to `new` (§15.6): STHs of `fromSize` leaves and more are signed by
+ * `new`. Each key signs JCS(rotation without its two signatures) with `DOMAIN.dirKey`.
+ */
+export const KeyRotation = z.strictObject({
+    v: z.literal(PROTOCOL),
+    realm: RealmId,
+    old: Key32,
+    new: Key32,
+    fromSize: z.number().int().positive(),
+    sigOld: Signature,
+    sigNew: Signature,
+});
+/**
+ * Evidence that log entry `seq` was in the directory by an epoch (§15.7): that epoch's leaf in the view's STH,
+ * and the person's map value there, which commits to a log head at or after `seq`.
+ */
+export const EntryEpoch = z.strictObject({
+    seq: z.number().int().nonnegative(),
+    epoch: EpochProof,
+    value: MapValue,
+    mapProof: MapProof,
+});
+/**
+ * One person's head as the directory serves it at an STH (§7, "Directory frames"; §15.7): the map proof of their value
+ * at the STH's last epoch, and that value's preimage (`value`: their log head and the hashes of their current devices'
+ * keys statements), or none for a person the map does not hold, or `tombstone: true` for an erased one. It holds no
+ * log entry, so no Jelly token and nothing of a profile: what a device about to bind needs, and what anyone may read.
+ */
+export const PersonHead = z.strictObject({
+    person: HostedPersonId,
+    mapProof: MapProof,
+    value: MapValue.optional(),
+    tombstone: z.literal(true).optional(),
+});
+/**
+ * One person as the directory serves them at an STH (§15.7): their log after the asker's `knownSeq` (all of it
+ * without one), the keys statements of their current devices, the map proof of their value at the STH's last
+ * epoch, and for every entry of `log` with a `jelly` authority, an `EntryEpoch` (its first epoch, from the
+ * directory's records). An erased person is `tombstone: true` with an empty log and no keys.
+ */
+export const PersonView = z.strictObject({
+    person: HostedPersonId,
+    log: z.array(LogEntry).max(1024),
+    keys: z.array(KeysStatement).max(LIMITS.devicesPerPerson),
+    mapProof: MapProof,
+    epochs: z.array(EntryEpoch).max(1024).optional(),
+    tombstone: z.literal(true).optional(),
+});

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

@@ -0,0 +1,211 @@
+/**
+ * The Messaging envelope: the end-to-end unit between machines. The sender signs it;
+ * every body except presence is sealed to the recipient machine's X25519 key.
+ * The relay can read the header (routing) but not the body.
+ */
+import { z } from "../../vendor/zod/index.js";
+import { Message, TaskArtifactUpdateEvent, TaskStatusUpdateEvent } from "./a2a.js";
+import { AgentKind, Base64Url, ChannelName, DeliveryTier, MachineId, MachineLabel, Millis, PersonId, PROTOCOL, SessionAddress, SessionName, SessionState, Ulid, LIMITS, } from "./common.js";
+import { CardData, CardGetData, GrantSync } from "./consent.js";
+import { DelegationChain } from "./delegation.js";
+import { ErrorCode } from "./errors.js";
+import { Anchor, RealmId } from "./realm.js";
+export const EnvelopeType = z.enum(["message", "task.status", "task.artifact", "task.cancel", "receipt", "presence"]);
+export const SEAL_ALG = "x25519-hkdf-sha256-a256gcm";
+/**
+ * What the envelope is to its recipient's person (spec §5, "Class"), in the header so the signature and the AAD
+ * cover it: `self` between two devices of one person (`from.person` = `to.person`), `contact` between two persons,
+ * and `request` for a message request (spec §6.9, "Message requests"): a person's first line to a person of another
+ * org, which a directory relay paces by this header alone. Every sealed envelope carries it; presence does not.
+ */
+export const EnvelopeClass = z.enum(["self", "contact", "request"]);
+/**
+ * One end of an envelope (spec §5, "Ends"): a person, one of their devices, and optionally an agent (a session) on
+ * that device. With no `agent`, the end is the person (or, for receipts and task control, the device acting for them).
+ */
+export const Party = z.object({
+    person: PersonId,
+    device: MachineId,
+    agent: SessionName.optional(),
+});
+/** Sender: the signing device, its person, and the agent that wrote the envelope, if an agent did. */
+export const Sender = Party;
+/** Recipient: one device of a person, and optionally an agent on it; presence alone goes to the whole team. */
+export const Recipient = z.union([
+    Party,
+    z.object({ team: z.literal(true) }), // presence broadcast
+]);
+/**
+ * Wire form. `sig` = Ed25519(from.device, DOMAIN.envelope + JCS(envelope without `sig`)).
+ * Sealed: enc = SEAL_ALG, epk + nonce present, body = base64url(ciphertext||tag),
+ *   AAD = UTF-8(JCS(header)), header = envelope without body and sig.
+ * Plain (presence only): enc = "none", body = payload object, no epk/nonce.
+ * `realm` is the sender's realm, and `anchor` its view of the realm when it sealed the envelope (spec §5,
+ * "Realm and anchor"): the signature covers both, and so does the AAD of a sealed envelope.
+ */
+export const Envelope = z.object({
+    v: z.literal(PROTOCOL),
+    id: Ulid,
+    realm: RealmId,
+    type: EnvelopeType,
+    from: Sender,
+    to: Recipient,
+    ts: Millis,
+    exp: Millis,
+    anchor: Anchor,
+    class: EnvelopeClass.optional(),
+    replyTo: Ulid.optional(),
+    enc: z.enum([SEAL_ALG, "none"]),
+    epk: Base64Url.optional(),
+    nonce: Base64Url.optional(),
+    body: z.unknown(),
+    sig: Base64Url,
+});
+// ---- Decrypted body payloads, by envelope type ----
+/** A channel's persons: roster person names, or hosted `p_…` ids in a directory realm (spec §6.8). */
+const ChannelPersons = z.array(PersonId).min(1).max(LIMITS.channelPersons);
+/**
+ * A channel change or post (spec §6.8), on a `kind: "message"` envelope sealed to a device with no recipient agent.
+ * `create`: the full channel record with the person who created it, to every member device and to each later
+ * invitee. `invite`: persons added, to the existing members. `leave`: the sender left. `remove`: persons removed by
+ * the creator or an admin, to every member device. `post`: a line in the channel. `name` is always the channel's own
+ * name. A DM line has no `conv` (spec §5, "Meaning").
+ */
+export const ChannelConv = z.discriminatedUnion("op", [
+    z.object({ kind: z.literal("channel"), op: z.literal("create"), id: Ulid, name: ChannelName, persons: ChannelPersons, creator: PersonId }),
+    z.object({ kind: z.literal("channel"), op: z.literal("invite"), id: Ulid, name: ChannelName, persons: ChannelPersons }),
+    z.object({ kind: z.literal("channel"), op: z.literal("leave"), id: Ulid, name: ChannelName }),
+    z.object({ kind: z.literal("channel"), op: z.literal("remove"), id: Ulid, name: ChannelName, persons: ChannelPersons }),
+    z.object({ kind: z.literal("channel"), op: z.literal("post"), id: Ulid, name: ChannelName }),
+]);
+/**
+ * Sync between two devices of one person (spec §6.9, "Sync"): `grant` carries grants the person set or re-signed,
+ * `snapshot` every current grant, for a device of the person that is new to the sender. The message carries exactly
+ * one data part, a `GrantSync`.
+ */
+export const SelfConv = z.object({ kind: z.literal("self"), what: z.enum(["grant", "snapshot"]) });
+/**
+ * A message request (spec §6.9, "Message requests"), on an envelope of class `request` from a person to a person:
+ * its message carries exactly one text part of at most `LIMITS.requestChars`.
+ */
+export const RequestConv = z.object({ kind: z.literal("request") });
+/**
+ * A contact card between two persons (spec §6.9, "Contact cards"): `card` carries one data part `{card}`, the signed
+ * card; `get` asks for the receiver's card and carries one data part `{get: true}`.
+ */
+export const CardConv = z.object({ kind: z.literal("card"), what: z.enum(["card", "get"]) });
+/** The conversation a `message` belongs to when its ends alone do not say (spec §5, "Meaning"). */
+export const Conv = z.discriminatedUnion("kind", [ChannelConv, SelfConv, RequestConv, CardConv]);
+/**
+ * type "message". `kind: "task"` asks the recipient to run `message` as a new A2A task;
+ * the sender assigns `message.taskId` (a ULID) and `message.contextId`.
+ * Replies to a task are task.status/task.artifact envelopes, not messages.
+ */
+export const MessagePayload = z
+    .object({
+    kind: z.enum(["message", "task"]),
+    message: Message,
+    /** Sender's hint that the recipient may wake an idle session. Recipient policy decides. */
+    wake: z.boolean().optional(),
+    /** Required on `kind: "task"`, absent otherwise: the signed chain from the root requester to this hop (spec §6.7). Receivers run `verifyChain`. */
+    delegation: DelegationChain.optional(),
+    /**
+     * The conversation, when the ends do not say it (spec §5, "Meaning"): a channel change or post (§6.8).
+     * `message.messageId` is a ULID shared by every copy; `message.contextId`, when set, is the ULID `messageId` of
+     * the thread's first line.
+     */
+    conv: Conv.optional(),
+})
+    .refine((p) => (p.kind === "task" ? p.message.taskId !== undefined : true), { message: "a task message needs message.taskId" })
+    .refine((p) => (p.kind === "task") === (p.delegation !== undefined), { message: "a task request carries a delegation chain, and only a task request" })
+    .refine((p) => p.conv?.kind !== "self" || (p.message.parts.length === 1 && GrantSync.safeParse(p.message.parts[0].data).success), {
+    message: "a self sync message carries exactly one data part with its grants",
+})
+    .refine((p) => p.conv?.kind !== "request" || requestMessage(p.message), {
+    message: `a message request carries one text part of 1 to ${LIMITS.requestChars} characters, and nothing else`,
+})
+    .refine((p) => p.conv?.kind !== "card" || cardMessage(p.message, p.conv.what), {
+    message: "a card message carries one data part, the card or the request for one, and nothing else",
+})
+    .refine((p) => p.message.taskId === undefined || Ulid.safeParse(p.message.taskId).success, {
+    message: "Messaging task ids are ULIDs",
+});
+/** The members a message request or card message may have: no metadata, extensions or other text beside its one part. */
+const BARE_MESSAGE = new Set(["messageId", "role", "parts"]);
+const bare = (message, part) => Object.keys(message).every((key) => BARE_MESSAGE.has(key)) && message.parts.length === 1 && Object.keys(message.parts[0]).join() === part;
+/** Spec §6.9, "Message requests": exactly one text part of 1 to `LIMITS.requestChars` UTF-16 code units, and nothing else. */
+function requestMessage(message) {
+    const text = message.parts[0]?.text;
+    return bare(message, "text") && typeof text === "string" && text.length >= 1 && text.length <= LIMITS.requestChars;
+}
+/** Spec §6.9, "Contact cards": exactly one data part, `{card}` or `{get: true}`, and nothing else. */
+function cardMessage(message, what) {
+    return bare(message, "data") && (what === "card" ? CardData : CardGetData).safeParse(message.parts[0].data).success;
+}
+/** type "task.status": executor → requester. */
+export const TaskStatusPayload = TaskStatusUpdateEvent;
+/** type "task.artifact": executor → requester. */
+export const TaskArtifactPayload = TaskArtifactUpdateEvent;
+/** type "task.cancel": requester → executor. The executor daemon moves the task to CANCELED if not terminal. */
+export const TaskCancelPayload = z.object({
+    taskId: Ulid,
+    reason: z.string().max(1000).optional(),
+});
+/** type "receipt": recipient → sender, signed proof of a delivery stage for envelope `ref`. */
+export const ReceiptPayload = z.object({
+    ref: Ulid,
+    stage: z.enum(["delivered", "held", "handed_to_agent", "read", "rejected"]),
+    code: ErrorCode.optional(),
+    note: z.string().max(500).optional(),
+});
+export const SessionInfo = z.object({
+    session: SessionName,
+    agent: AgentKind,
+    repo: z.string().max(200).optional(),
+    branch: z.string().max(200).optional(),
+    state: SessionState,
+    doing: z.string().max(200).optional(),
+    tier: DeliveryTier,
+    since: Millis,
+    /** No client holds the session: it is kept (spec §8.2) and its mail waits for it. */
+    kept: z.literal(true).optional(),
+    /** This machine would act on a sender's wake hint for the session now (spec §6.5, §8.3, §8.6). */
+    wake: z.literal(true).optional(),
+});
+/** type "presence": plain (not sealed), to {team:true}. Latest `seq` per machine wins. */
+export const PresencePayload = z.object({
+    seq: z.number().int().nonnegative(),
+    label: MachineLabel,
+    sessions: z.array(SessionInfo).max(LIMITS.presenceSessions),
+    /** Optional protocol features this machine supports, e.g. "tasks". Unknown features are ignored. */
+    features: z.array(z.string().max(64)).max(32).optional(),
+    /**
+     * Under a Jelly host: no window of this device's person is visible on it (`person.attached`, spec §6.5, §8.11). Its
+     * agents still run; the person is away from this device. Absent: the person may be at it.
+     */
+    away: z.literal(true).optional(),
+});
+export const PAYLOAD_BY_TYPE = {
+    message: MessagePayload,
+    "task.status": TaskStatusPayload,
+    "task.artifact": TaskArtifactPayload,
+    "task.cancel": TaskCancelPayload,
+    receipt: ReceiptPayload,
+    presence: PresencePayload,
+};
+/**
+ * Provenance the receiving daemon attaches at `Message.metadata[URI.provenance]` before
+ * handing a message to any client. Clients show it; peers can never set it (the daemon overwrites it).
+ */
+export const Provenance = z.object({
+    envelopeId: Ulid,
+    from: SessionAddress.describe("sender address person/agent@label"),
+    person: PersonId,
+    /** The sending agent; absent when the person wrote it. */
+    agent: SessionName.optional(),
+    /** The sending device. */
+    device: MachineId,
+    label: MachineLabel,
+    verified: z.literal("signature"),
+    receivedAt: Millis,
+});