@joe-broadhead/messaging 0.0.0-stage → 0.7.0

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

@@ -0,0 +1,65 @@
+import { z } from "../../vendor/zod/index.js";
+/** The closed set of Messaging error codes. Every emitted code must be documented in docs/spec/messaging-v1.md. */
+export const ErrorCode = z.enum([
+    "invalid_request", // malformed input or schema violation
+    "not_member", // sender or recipient machine is not a current team member
+    "bad_signature", // signature or seal failed verification
+    "unknown_session", // recipient session does not exist on the target machine
+    "ambiguous_address", // address matches more than one session
+    "no_recipients", // address resolved to nothing
+    "unknown_address", // an agent tool's address names no person, agent or channel this machine knows (client-side; never on the wire)
+    "refused", // recipient policy refuses this sender
+    "declined", // the recipient's person declined a held request (spec §6.9)
+    "request_required", // the recipient's person has not accepted this sender: a message request comes first (spec §6.9)
+    "rate_limited", // too many envelopes; retry later
+    "loop_guard", // agent-to-agent loop guard tripped
+    "too_large", // size limit exceeded
+    "secret_refused", // the sending daemon found a credential in outbound text; nothing was stored or sent
+    "expired", // envelope TTL passed, or ts outside the skew window
+    "duplicate", // envelope id already seen (receivers treat as success)
+    "relay_unavailable", // no relay connection
+    "not_found", // unknown id
+    "invalid_state", // illegal task transition or wrong role for the operation
+    "forbidden", // caller lacks authority (e.g. non-admin roster change)
+    "guarded_turn", // a guarded peer turn tried to send outside its allowance (client-side; never on the wire)
+    "roster_conflict", // roster entry does not extend the current head; resync and retry
+    "invite_invalid", // unknown, expired, revoked, used or mismatched invite
+    "no_identity", // daemon has no identity/team yet
+    "binding_invalid", // a device binding, log entry or its authority failed verification (hosted realms)
+    "jelly_unavailable", // Jelly ID's key set or key history could not be fetched; never reported as invalid
+    "log_conflict", // a device-log entry does not extend the log's head; resync and retry
+    "device_limit", // the person already has LIMITS.devicesPerPerson current devices
+    "admission_required", // dir.bind without a Jelly-vouched bind of the connecting device
+    "admission_invalid", // dir.bind whose Jelly token is not live, or not for this directory's issuer and resource
+    "directory_inconsistent", // the directory showed a split view, a fork or an inconsistent tree head; evidence kept, alarm raised
+    "unknown_device", // a directory realm: the sender's device is not a current device of its person
+    "directory_unavailable", // the key directory could not be reached to verify a person's devices within the freshness bound
+    "login_unsupported", // Jelly ID offers no device sign-in for this realm's resource (no v1.2 device sign-in in its metadata)
+    "login_denied", // the person denied the sign-in at Jelly ID, or the account is disabled or being deleted
+    "grant_required", // deployment "jelly": a human- or admin-tier call carried no action grant (spec §8.11)
+    "grant_invalid", // deployment "jelly": the action grant did not verify, is for another call, expired or was spent
+    "ticket_required", // deployment "jelly": session.register carried no session ticket
+    "ticket_invalid", // deployment "jelly": the session ticket did not verify, expired, or names another session or agent
+    "daemon_unavailable", // client could not reach the local daemon socket
+    "daemon_mismatch", // the daemon on the socket is another version or IPC protocol than the client (spec §8.2)
+    "internal", // unexpected failure; details are logged locally, never sent
+]);
+export const ErrorBody = z.object({
+    code: ErrorCode,
+    message: z.string().max(500),
+});
+/** Error carrying a Messaging code. Messages must never contain bodies, keys or secrets. */
+export class MessagingError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = "MessagingError";
+        this.code = code;
+    }
+    toBody() {
+        return { code: this.code, message: this.message.slice(0, 500) };
+    }
+}
+export function isMessagingError(value) {
+    return value instanceof MessagingError;
+}

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

@@ -0,0 +1,15 @@
+export * from "./common.js";
+export * from "./errors.js";
+export * from "./realm.js";
+export * from "./jelly.js";
+export * from "./directory.js";
+export * as A2A from "./a2a.js";
+export * from "./envelope.js";
+export * from "./delegation.js";
+export * from "./consent.js";
+export * from "./roster.js";
+export * from "./relay.js";
+export * from "./directory-frames.js";
+export * from "./ipc.js";
+export * from "./ipc/device.js";
+export * from "./ipc/consent.js";

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

@@ -0,0 +1,181 @@
+/**
+ * Consent methods (spec §8.2, "Consent"; §6.9): grants and held requests. Every one is human tier: none is in `AGENT_METHODS`, so the agent
+ * socket refuses them, and agents never set or read a person's grants. Spread into `IPC_METHODS`.
+ */
+import { z } from "../../../vendor/zod/index.js";
+import { ChannelName, LIMITS, MachineId, MachineLabel, Millis, PersonId, RoomRef, SessionAddress, SessionName, Ulid } from "../common.js";
+import { AgentMailLevel, AskLevel, CardCan, ChatLevel } from "../consent.js";
+import { Email } from "../directory-frames.js";
+/** A grant's subject as a person names it: a person, or a channel by its name here. */
+export const GrantTarget = z.union([z.strictObject({ person: PersonId }), z.strictObject({ channel: ChannelName })]);
+const Levels = {
+    chat: ChatLevel.optional(),
+    agentMail: AgentMailLevel.optional(),
+    ask: AskLevel.optional(),
+    trustedUntil: Millis.optional(),
+    discoverable: z.boolean().optional(),
+};
+/** A grant as this device holds it. A channel subject carries the channel's id and, while this person is in it, its name here. */
+export const GrantView = z.object({
+    subject: z.union([z.object({ person: PersonId }), z.object({ channel: Ulid, name: ChannelName.optional() })]),
+    ...Levels,
+    id: Ulid,
+    ts: Millis,
+    /** The device that signed it. */
+    by: MachineId,
+    /** Set when a device of the person re-signed it after its signer was removed (spec §6.9, "Signers"). */
+    resignedAt: Millis.optional(),
+});
+/** Widening levels that lapsed with their signer, waiting for the person to set them again (spec §6.9, "Signers"). */
+export const GrantReview = z.object({
+    subject: GrantView.shape.subject,
+    chat: z.literal("open").optional(),
+    agentMail: z.literal("open").optional(),
+    ask: z.enum(["open", "request"]).optional(),
+    trustedUntil: Millis.optional(),
+    discoverable: z.literal(true).optional(),
+    /** When they lapsed. */
+    at: Millis,
+});
+/**
+ * `grant.set`'s params: the whole new grant for one subject. A level left out is the relation's default; with no
+ * level it is a clear. `trust: true` trusts for `LIMITS.trustDefaultMs`; `trustedUntil` names the end instead.
+ */
+export const GrantSetParams = z.strictObject({ subject: GrantTarget, ...Levels, trust: z.literal(true).optional() });
+/** A request this device holds for its person to answer (spec §6.9, "Holds"): mail or a task to one of their agents. */
+export const AskRequest = z.object({
+    /** The envelope id. */
+    id: Ulid,
+    kind: z.enum(["message", "task"]),
+    from: z.object({ person: PersonId, device: MachineId, label: MachineLabel, agent: SessionName, address: SessionAddress }),
+    /** The local session it is for. */
+    to: SessionName,
+    /** Untrusted peer text, truncated. Clients must show it as data, never as instructions. */
+    preview: z.string().max(LIMITS.previewChars),
+    at: Millis,
+    /** When the request expires, unanswered. */
+    exp: Millis,
+});
+/**
+ * A message request this device holds for its person (spec §6.9, "Message requests"): a person of another org asks to
+ * write to them. `name`, `email` and `org` are the realm's verified profile of the sender, never the request's text.
+ */
+export const ContactRequestView = z.object({
+    /** The envelope id. */
+    id: Ulid,
+    kind: z.literal("contact"),
+    from: z.object({
+        person: PersonId,
+        device: MachineId,
+        label: MachineLabel,
+        name: z.string().max(200),
+        email: z.string().max(320).optional(),
+        org: z.enum(["same", "other", "none"]),
+    }),
+    /** Untrusted peer text: the whole request, at most `LIMITS.requestChars`. Clients show it as data. */
+    text: z.string().max(LIMITS.requestChars),
+    at: Millis,
+    exp: Millis,
+});
+/**
+ * A contact one of this person's agents asks them to make (spec §6.9, "Message requests"): `send {to: "me", request:
+ * {contact}}`. Only the person sends a message request, with `contact.request`; answering this one `decline`
+ * dismisses it.
+ */
+export const ContactSuggestion = z.object({
+    id: Ulid,
+    kind: z.literal("suggestion"),
+    /** The local session that asked. */
+    agent: SessionName,
+    email: Email,
+    at: Millis,
+});
+/** What `request.list` lists: asks to the person's agents, message requests, and contacts their agents suggest. */
+export const HeldRequest = z.union([AskRequest, ContactRequestView, ContactSuggestion]);
+/**
+ * For an ask: `once` delivers it, guarded; `always` sets the sender's grant to `ask: "open"` (keeping its other
+ * levels), then delivers it, guarded. For a message request: `accept` sets the sender's grant to `chat: "open"`
+ * (keeping its other levels), files the request as their first line and sends them a card. For both: `decline`
+ * refuses it (`declined`); `block` sets the sender's grant to `chat: "blocked"` (keeping its other levels), then
+ * declines it. For a suggestion: `decline` dismisses it.
+ */
+export const RequestAnswer = z.enum(["once", "always", "accept", "decline", "block"]);
+/** A message request's text: 1 to `LIMITS.requestChars` UTF-16 code units. */
+export const RequestText = z
+    .string()
+    .min(1)
+    .refine((text) => text.length <= LIMITS.requestChars, { message: `at most ${LIMITS.requestChars} UTF-16 code units` });
+/**
+ * What another person's card says this person may send them, or, with no card, the defaults of the relation
+ * (spec §6.9, "Contact cards"). `at` is when the card was signed.
+ */
+/**
+ * What a person may be sent (spec §6.9, "Contact cards"), and `devicesChangedAt`: when a device of theirs was last
+ * added or removed, while that is under 7 days ago (design §2.8: their devices changed; a rekey or attest is not a change).
+ */
+export const PersonReach = z.object({ person: PersonId, can: CardCan, source: z.enum(["card", "default"]), at: Millis.optional(), devicesChangedAt: Millis.optional() });
+/** `request.answer`'s params, which `request.answer.preview` takes too (spec §8.2, "Previews"). */
+export const RequestAnswerParams = z.strictObject({ id: Ulid, answer: RequestAnswer, all: z.boolean().optional() });
+/** `contact.request`'s params; its preview takes them with `text` optional (it reads only `email`). */
+export const ContactRequestParams = z.strictObject({ email: Email, text: RequestText, suggestion: Ulid.optional() });
+export const CONSENT_METHODS = {
+    /** This person's grants, newest first, and the review list. With `subject`, only that subject's. */
+    "grant.list": {
+        params: z.strictObject({ subject: GrantTarget.optional() }),
+        result: z.object({ grants: z.array(GrantView), review: z.array(GrantReview) }),
+    },
+    /**
+     * Signs and stores the subject's new grant, sends it to this person's other devices, and drops the subject from
+     * the review list. `not_found` for a person the realm does not know or a channel this person is not in.
+     */
+    "grant.set": { params: GrantSetParams, result: z.object({ grant: GrantView }) },
+    /** What `grant.set` with these params would mean, in one fixed sentence; changes nothing. */
+    "grant.set.preview": { params: GrantSetParams, result: z.object({ sentence: z.string().max(500) }) },
+    /** The requests this device holds for its person, oldest first: asks, then message requests, then suggestions. */
+    "request.list": { params: z.strictObject({}), result: z.object({ requests: z.array(HeldRequest).max(LIMITS.heldTotal * 3) }) },
+    /**
+     * Answers a held request; with `all`, every request of the same kind held from the same sending person. Returns
+     * the ids answered. `not_found` for an id this device does not hold; `invalid_request` for an answer its kind does
+     * not take.
+     */
+    "request.answer": {
+        params: RequestAnswerParams,
+        result: z.object({ answered: z.array(Ulid).max(LIMITS.heldTotal) }),
+    },
+    /**
+     * Read-only: what `request.answer` would do, for its confirmation (spec §6.9, "Holds", "Message requests"). It takes
+     * exactly `request.answer`'s input. It returns whom the person answers (`from`: the realm's verified profile of the
+     * sender, or of the person for their own agent's suggestion; `name` and `email` are untrusted text), the request's
+     * `kind`, the sender's `agent` and the local session it is `to` (an ask), how many requests the answer would settle
+     * (`count`, more than 1 only with `all`), and one fixed `sentence`: what this `answer` does. `not_found` and `invalid_request` as `request.answer` would answer. Changes nothing.
+     */
+    "request.answer.preview": {
+        params: RequestAnswerParams,
+        result: z.object({
+            kind: z.enum(["message", "task", "contact", "suggestion"]),
+            from: z.object({ name: z.string().max(200), email: z.string().max(320).optional(), org: z.enum(["same", "other", "none"]) }),
+            agent: SessionName.optional(),
+            to: SessionName.optional(),
+            count: z.number().int().positive(),
+            sentence: z.string().max(500),
+        }),
+    },
+    /**
+     * A message request (spec §6.9, "Message requests"), hosted realms only: resolves the exact `email` at the
+     * directory, then sends `text` to every device of that person as a request, and files it as this person's line in
+     * `dm:<person>`. `not_found` when no Messaging user with that email accepts requests (the same for an unknown and an
+     * undiscoverable email); `rate_limited` while a request to them waits, or past `LIMITS.requestsPerDay` persons
+     * today. `suggestion` dismisses the agent's suggestion it answers.
+     */
+    "contact.request": {
+        params: ContactRequestParams,
+        result: z.object({ id: Ulid, conversation: RoomRef, person: PersonId }),
+    },
+    /** Whether `contact.request` would find a person for `email`; counts against the directory's lookup limits. Sends nothing. */
+    "contact.request.preview": { params: ContactRequestParams.partial({ text: true }), result: z.object({ found: z.boolean() }) },
+    /**
+     * Asks `person` for their card (spec §6.9, "Contact cards"): at most once a day per person; `sent: false` when
+     * this device asked them in the last day.
+     */
+    "card.get": { params: z.strictObject({ person: PersonId }), result: z.object({ sent: z.boolean() }) },
+};

package/dist/lib/modules/core/schema/ipc/device.js

@@ -0,0 +1,276 @@
+/**
+ * The `device.*` IPC methods (spec §8.2, "Devices"; design §2.2, §7.5): this device's binding in its realm, and
+ * its person's devices. `device.status` and `device.bind` are on the agent tier (the plugin's runtime binds its
+ * host's daemon zero-click with a Jelly token, never a tool); `device.list`, `device.remove`, `device.link` and
+ * `device.approve` are for people, on the admin socket, and `device.approve.preview` is human tier. Spread into
+ * `IPC_METHODS`.
+ */
+import { z } from "../../../vendor/zod/index.js";
+import { Hash, MachineId, MachineLabel, Millis, PersonId } from "../common.js";
+import { DeviceKind, UnbindReason } from "../directory.js";
+import { ErrorCode } from "../errors.js";
+import { Jws } from "../jelly.js";
+/**
+ * - `none`: this device is not a device of any person yet (a directory realm: not bound; a roster realm: no team).
+ * - `bound`: a current device of its person.
+ * - `attest-due`: bound, and its last Jelly token is over `LIMITS.attestAfterMs` old: the plugin binds again.
+ * - `removed`: its person's log (or the roster) shows it removed; it can never be bound again.
+ * - `replace`: `identity.replace` made this device new keys to replace its predecessor (design §13.8); the plugin
+ *   binds it with a Jelly token for `device`, as for `none`, and the daemon then removes the predecessor.
+ */
+export const BindingState = z.enum(["none", "bound", "attest-due", "removed", "replace"]);
+/** An alarm of this device's realm (spec §15.9): `directory` (the directory contradicted itself) or `restored`. */
+export const RealmAlarmSummary = z.object({
+    kind: z.enum(["directory", "restored"]),
+    reason: z.string().max(500),
+    at: Millis,
+});
+export const DeviceStatus = z.object({
+    realm: z.enum(["roster", "directory"]),
+    /** This device's public key: the `x` of the `cnf` a Jelly token for it names. Absent before the home has keys. */
+    device: MachineId.optional(),
+    binding: BindingState,
+    person: PersonId.optional(),
+    label: MachineLabel.optional(),
+    /** A directory realm's adopted tree head. */
+    sth: z.object({ size: z.number().int().positive(), root: Hash, ts: Millis }).optional(),
+    alarm: RealmAlarmSummary.optional(),
+});
+/**
+ * One change of a person's devices (design §2.8): `added` (bound; a roster realm: admitted), `vouched` (an `attest`
+ * raised a device approved by link to Jelly-vouched), `removed` (unbound, or `member.remove`) or `replaced` (unbound
+ * by its successor after a restore, design §13.8). `label`, `kind`, `vouch` and `via` are the device's; `approver`
+ * names the device that approved one bound by link, by its label; `at` is the entry's time.
+ */
+export const DeviceChangeView = z.object({
+    change: z.enum(["added", "vouched", "removed", "replaced"]),
+    device: MachineId,
+    label: MachineLabel,
+    kind: DeviceKind.optional(),
+    vouch: z.enum(["jelly", "device", "admin"]),
+    via: z.enum(["host", "browser"]).optional(),
+    approver: MachineLabel.optional(),
+    at: Millis,
+});
+/** One device of this device's person. */
+export const DeviceListEntry = z.object({
+    device: MachineId,
+    label: MachineLabel,
+    /** A directory realm's device kind; a roster realm has none. */
+    kind: DeviceKind.optional(),
+    /** `jelly`: vouched by Jelly ID; `device`: approved by another device of the person; `admin`: a roster admin admitted it. */
+    vouched: z.enum(["jelly", "device", "admin"]),
+    /**
+     * How a Jelly-vouched device got its latest Jelly token: from a Jelly `host`, or signed in through the `browser`
+     * (`src: "device"`, spec §15.9). Absent for other vouches.
+     */
+    via: z.enum(["host", "browser"]).optional(),
+    current: z.boolean(),
+    self: z.boolean(),
+    since: Millis.optional(),
+    /** For a removed device of a directory realm: when, why and by which device. */
+    unbound: z.object({ at: Millis, reason: UnbindReason, by: MachineId }).optional(),
+});
+/** A link request's text (`messaging-link.…`, spec §15.3): what a new device shows and its person's device reads. */
+const LinkText = z.string().min(1).max(2048);
+/** The six-digit code both devices show for a link request (`linkSas`). */
+const Sas = z.string().regex(/^[0-9]{6}$/, "six digits");
+/** What a link request asks for, and the code to compare. */
+export const LinkPreview = z.object({ device: MachineId, label: MachineLabel, kind: DeviceKind, sas: Sas });
+/**
+ * A key's fingerprint as Jelly ID's consent page shows it (Jelly's contract v1.2 §12.2): the first six bytes of the
+ * key's RFC 7638 thumbprint, lower-case hex, in three groups of four.
+ */
+export const KeyFingerprint = z.string().regex(/^[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}$/, "key fingerprint");
+/** The code the person types at Jelly ID's page: ten symbols grouped 5-5 (Jelly's contract v1.2 §12.1). */
+export const LoginUserCode = z.string().regex(/^[A-HJ-NP-Z2-9]{5}-[A-HJ-NP-Z2-9]{5}$/, "user code");
+/**
+ * What a sign-in is for: binding (or attesting) this device, removing another device of its person, a step of
+ * `identity.replace` (binding the new keys, then removing the predecessor), or `directory.erase`.
+ */
+export const LoginPurpose = z.enum(["bind", "remove", "replace", "erase"]);
+/** The kinds a device that signs in may give itself: never `jelly-host`. */
+export const LoginKind = z.enum(["laptop", "server", "other"]);
+/**
+ * Where the person signs in, the code they type there, and what to check. Never the token or Jelly's device code, and
+ * never a link with the code in it: Jelly ID sends none (its contract v1.2 §12.1), so a phished link is not a sign-in.
+ */
+const LoginShown = z.object({
+    /** Jelly ID's page (`verification_uri`), where the person types `userCode`. */
+    verificationUri: z.string().url().max(2048),
+    userCode: LoginUserCode,
+    /** This device's key as the page shows it. */
+    fingerprint: KeyFingerprint,
+    /** When the code expires (ms). */
+    expires: Millis,
+});
+/**
+ * A device's sign-in through the browser (spec §15.9, "Signing in through the browser"), as `device.login.status`
+ * reports it and the `login` event announces it.
+ *
+ * - `idle`: none since the daemon started.
+ * - `pending`: waiting for the person at Jelly ID (or binding with the token Jelly ID just gave).
+ * - `done`: `bind` bound or attested this device; `remove` removed `device`. `seq` is the log entry's.
+ * - `failed`: `code` and `message` in the house style (`expired`, `login_denied`, `login_unsupported`, ...).
+ * - `cancelled`: `device.login.cancel`, a newer `device.login`, or the daemon stopping.
+ */
+export const LoginState = z.discriminatedUnion("state", [
+    z.object({ state: z.literal("idle") }),
+    LoginShown.extend({ state: z.literal("pending"), purpose: LoginPurpose }),
+    z.object({ state: z.literal("done"), purpose: LoginPurpose, person: PersonId, device: MachineId, seq: z.number().int().nonnegative() }),
+    z.object({ state: z.literal("failed"), purpose: LoginPurpose, code: ErrorCode, message: z.string().max(500) }),
+    z.object({ state: z.literal("cancelled"), purpose: LoginPurpose }),
+]);
+/** `device.remove`'s params, which its preview takes too (spec §8.2, "Previews"). */
+export const DeviceRemoveParams = z.strictObject({ device: MachineId, reason: z.enum(["self", "removed", "lost"]).optional(), token: Jws.optional() });
+/** `device.approve`'s params; its preview takes them with `sas` optional. */
+export const DeviceApproveParams = z.strictObject({ link: LinkText, sas: Sas });
+/** `identity.replace`'s params, which its preview takes too (spec §8.2, "Previews"); the preview never reads `token`. */
+export const IdentityReplaceParams = z.strictObject({
+    /** A fresh Jelly token whose `cnf` names this device's new key: a Jelly host's. Without it, a sign-in through the browser. */
+    token: Jws.optional(),
+    /** The new device's label; default the predecessor's. */
+    label: MachineLabel.optional(),
+});
+/** A sign-in that a step of `identity.replace` or `directory.erase` waits for: where the person approves it. */
+const SignInStep = LoginShown.extend({ state: z.literal("sign-in"), purpose: LoginPurpose, interval: z.number().int().positive() });
+/** `directory.erase`'s params, which its preview takes too; the preview never reads `token`. */
+export const DirectoryEraseParams = z.strictObject({
+    /** A fresh Jelly token bound to this device: a Jelly host's. Without it, a sign-in through the browser. */
+    token: Jws.optional(),
+});
+export const DEVICE_METHODS = {
+    /** Agent tier. This device's realm and binding; the device id the plugin asks Jelly ID to bind. */
+    "device.status": { params: z.strictObject({}), result: DeviceStatus },
+    /**
+     * Agent tier, for the plugin's runtime only (design §2.2). Binds this device (or attests it again) with a Jelly
+     * resource token whose `cnf` names this device's key, for this home's account if it has one. A directory realm only.
+     */
+    "device.bind": {
+        params: z.strictObject({ token: Jws, label: MachineLabel.optional(), kind: DeviceKind.optional() }),
+        result: z.object({ person: PersonId, device: MachineId, seq: z.number().int().nonnegative() }),
+    },
+    /** Admin tier. This device's person's devices, current first. */
+    "device.list": { params: z.strictObject({}), result: z.object({ devices: z.array(DeviceListEntry) }) },
+    /**
+     * Admin tier. Removes a device of this device's person: this device itself, or another with a fresh Jelly token
+     * bound to this device (design §2.1). A directory realm only; a roster realm removes machines with `team.remove`.
+     */
+    "device.remove": {
+        params: DeviceRemoveParams,
+        result: z.object({ seq: z.number().int().nonnegative() }),
+    },
+    /**
+     * Admin tier, on a new device that Jelly ID does not enrol (design §2.5). Makes this device's link request: its
+     * text (shown as a QR code too) and the code to compare, valid until `expires`. The daemon then waits to be
+     * approved, and binds itself when its person's log shows the approval. A directory realm only.
+     */
+    "device.link": {
+        params: z.strictObject({ label: MachineLabel.optional(), kind: DeviceKind.optional() }),
+        result: z.object({ link: LinkText, sas: Sas, expires: Millis }),
+    },
+    /**
+     * Admin tier, in a directory realm, not under a Jelly host (spec §15.9, "Signing in through the browser"). Starts
+     * a sign-in at Jelly ID for this device and returns where the person approves it, the code and this key's
+     * fingerprint to check there, and when it expires. The daemon then polls Jelly ID and, once approved, binds this
+     * device (or attests it again), or with `remove` removes that other device of its person with the token. A newer
+     * call cancels a pending one. Needs Jelly ID's device sign-in (its contract v1.2 §12): `login_unsupported` without.
+     */
+    "device.login": {
+        params: z.strictObject({
+            label: MachineLabel.optional(),
+            kind: LoginKind.optional(),
+            remove: z.strictObject({ device: MachineId, reason: z.enum(["removed", "lost"]).optional() }).optional(),
+        }),
+        result: LoginShown.extend({ purpose: LoginPurpose, interval: z.number().int().positive() }),
+    },
+    /** Admin tier. The sign-in's state; with `waitMs`, answers once it changes or the wait ends. */
+    "device.login.status": { params: z.strictObject({ waitMs: z.number().int().min(0).max(120_000).optional() }), result: LoginState },
+    /** Admin tier. Cancels a pending sign-in; nothing when none is pending. */
+    "device.login.cancel": { params: z.strictObject({}), result: z.object({ ok: z.literal(true) }) },
+    /** Human tier, read-only (design §13.12): what a link request asks for, and its code. Refuses an expired one. */
+    /** `device.approve`'s input (spec §8.2, "Previews"); the code may be left out, and is never checked here. */
+    "device.approve.preview": { params: DeviceApproveParams.partial({ sas: true }), result: LinkPreview },
+    /**
+     * Admin tier, on a device of the person that Jelly ID vouched for: approves the link request, whose code the
+     * person compared and gives back as `sas`, by appending the new device's `bind` to the person's log.
+     */
+    "device.approve": {
+        params: DeviceApproveParams,
+        result: z.object({ device: MachineId, seq: z.number().int().nonnegative() }),
+    },
+    /**
+     * Admin tier, a directory realm (design §13.8, A8; spec §15.9 "Replacing this device"): this home gets new keys
+     * and replaces its predecessor, the device its store belongs to (after a restore: `keys_missing` or `restored`; or
+     * on purpose, for a fresh key). Each call moves the replacement on and says where it stands:
+     * - `done`: the new device is bound (a `bind` with a Jelly token for its key) and the predecessor unbound with
+     *   reason `replaced` (signed by the new device, with a Jelly token for it); grants re-signed, conversations kept
+     *   under the successor rule;
+     * - `token`: under a Jelly host, waiting for the host's token for `device` (`device.bind` or this method with it);
+     * - `sign-in`: waiting for the person at Jelly ID; call again once it is done. A sign-in's token vouches for one
+     *   act (spec §15.3), so through the browser the replacement takes two: one binds the new key, one removes the
+     *   predecessor. A Jelly host's token does both.
+     * `no_identity` before this home was bound to an account; `invalid_state` on a removed device.
+     */
+    "identity.replace": {
+        params: IdentityReplaceParams,
+        result: z.discriminatedUnion("state", [
+            z.object({ state: z.literal("done"), person: PersonId, device: MachineId, predecessor: MachineId, seq: z.number().int().nonnegative() }),
+            z.object({ state: z.literal("token"), device: MachineId }),
+            SignInStep.extend({ device: MachineId }),
+        ]),
+    },
+    /**
+     * Human tier, read-only: what `identity.replace` would do (design §13.8: the predecessor as `device.remove.preview`
+     * shows a device), why, how many sign-ins it still needs, and the confirmation's fixed sentence.
+     */
+    "identity.replace.preview": {
+        params: IdentityReplaceParams,
+        result: z.object({
+            predecessor: z.object({
+                device: MachineId,
+                label: MachineLabel,
+                kind: DeviceKind.optional(),
+                vouch: z.enum(["jelly", "device"]),
+                via: z.enum(["host", "browser"]).optional(),
+                since: Millis.optional(),
+                current: z.boolean(),
+            }),
+            /** Why: the store's key files are gone, it runs from an older copy, or neither (a fresh key on purpose). */
+            alarm: z.enum(["keys_missing", "restored"]).nullable(),
+            /** The new device's id, once `identity.replace` made it. */
+            device: MachineId.optional(),
+            /** Sign-ins through the browser still needed without a host's token: 2, 1 (the new key is bound) or 0. */
+            signIns: z.number().int().min(0).max(2),
+            sentence: z.string().max(600),
+        }),
+    },
+    /**
+     * Admin tier, a directory realm (design §3.7; spec §15.10 `dir.erase`): erases this person's account from
+     * Messaging, from this device: an `unbind` of every current device, with a fresh Jelly token bound to this one (a
+     * Jelly host's `token`, or a sign-in through the browser). The directory deletes the profile, every log body and
+     * keys statement, and the queues; the account can never be bound again. `done`: erased, and this device stops as
+     * removed. `rate_limited` (with `retryAfterMs`) past the directory's 10 erasures per person a day.
+     */
+    "directory.erase": {
+        params: DirectoryEraseParams,
+        result: z.discriminatedUnion("state", [z.object({ state: z.literal("done"), person: PersonId, devices: z.number().int().nonnegative() }), SignInStep]),
+    },
+    /** Human tier, read-only: exactly what `directory.erase` deletes, and what stays. */
+    "directory.erase.preview": {
+        params: DirectoryEraseParams,
+        result: z.object({
+            person: PersonId,
+            /** Every current device of the person, each unbound for good. */
+            devices: z.array(z.object({ device: MachineId, label: MachineLabel, kind: DeviceKind.optional(), self: z.boolean() })),
+            /** Sign-ins through the browser needed without a host's token. */
+            signIns: z.number().int().min(0).max(1),
+            /** The directory's limit: erasures per person a day. */
+            perDay: z.number().int().positive(),
+            /** What is lost, in fixed sentences. */
+            lost: z.array(z.string().max(300)).max(10),
+            /** What stays. */
+            kept: z.array(z.string().max(300)).max(10),
+        }),
+    },
+};