@joe-broadhead/messaging 0.7.0 → 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/errors.js

@@ -28,6 +28,8 @@ export const ErrorCode = z.enum([
     "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
+    "conv_conflict", // a conversation event does not extend the log, or its op head is not the current one; re-read and retry
+    "stale_epoch", // a conversation message is sealed under an epoch that is not the current one, or a rekey is due; re-seal 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
@@ -42,8 +44,23 @@ export const ErrorCode = z.enum([
     "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)
+    "store_refused", // messagingd refused the home's store and changed nothing; StoreRefusedError.reason says why: pre-reset or newer (spec §8.8)
     "internal", // unexpected failure; details are logged locally, never sent
 ]);
+/**
+ * The exit status of a messagingd or messaging-relay that refuses its store and changes nothing (spec §8.8): `EX_CONFIG`
+ * of sysexits(3), for either reason. messagingd also prints one stderr line,
+ * `messagingd: store_refused: <reason>: <why and how to start over>`. A client matches this status, the code and the
+ * reason, never the wording.
+ */
+export const STORE_REFUSED_EXIT = 78;
+/**
+ * Why a store is refused (spec §8.8):
+ * - `pre-reset`: it records no store generation, or another one. Starting over (moving the home aside) is the remedy.
+ * - `newer`: its `min_reader` is above this reader's schema: a newer messagingd wrote it. Upgrading is the remedy;
+ *   moving the home aside would set a newer home aside.
+ */
+export const StoreRefusedReason = z.enum(["pre-reset", "newer"]);
 export const ErrorBody = z.object({
     code: ErrorCode,
     message: z.string().max(500),
@@ -60,6 +77,28 @@ export class MessagingError extends Error {
         return { code: this.code, message: this.message.slice(0, 500) };
     }
 }
+/** `store_refused`, with its reason as a field: clients branch on `reason`, never on the message. */
+export class StoreRefusedError extends MessagingError {
+    reason;
+    constructor(reason, message, options) {
+        super("store_refused", message, options);
+        this.name = "StoreRefusedError";
+        this.reason = reason;
+    }
+}
+/** The stderr line of a messagingd that refuses its store: `messagingd: store_refused: <reason>: <text>`. */
+export function storeRefusedLine(reason, text) {
+    return `messagingd: store_refused: ${reason}: ${text}`;
+}
+/**
+ * The reason on a messagingd refusal line, or undefined for any other line. Reads the tokens only; the text after
+ * them may change between releases.
+ */
+export function storeRefusedReason(line) {
+    const match = /^messagingd: store_refused: ([a-z-]+): /.exec(line);
+    const parsed = StoreRefusedReason.safeParse(match?.[1]);
+    return parsed.success ? parsed.data : undefined;
+}
 export function isMessagingError(value) {
     return value instanceof MessagingError;
 }

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

@@ -13,3 +13,4 @@ export * from "./directory-frames.js";
 export * from "./ipc.js";
 export * from "./ipc/device.js";
 export * from "./ipc/consent.js";
+export * from "./conversation.js";

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

@@ -7,6 +7,7 @@ export { encodeTicket } from "./roster.js";
 export { grantHash } from "./delegation.js";
 export { signJellyToken } from "./directory/jelly-issuer.js";
 export { jellyHostDouble } from "./jelly-host-double.js";
+export { sealConvMetaWith, sealConvMsgWith, sealKeySharesWith } from "./conversation/seal.js";
 /**
  * Narrows a result whose `kind` tells its shape (`item.read`, `conv.read`) to the expected kind, and
  * throws with both kinds named otherwise: `client.call("item.read", p).then(asKind("received"))`.

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

@@ -3,4 +3,4 @@
  * its IPC hello and a client compares it with its own (spec §8.2). A test keeps it equal to the
  * root package.json.
  */
-export const VERSION = "0.7.0";
+export const VERSION = "0.7.1";