@joe-broadhead/messaging 0.7.0 → 0.7.1

package/dist/types/core/conversation/log.d.ts

@@ -0,0 +1,142 @@
+import type { AnchorRelation } from "../realm.js";
+import { type Hash, type MachineId, type PersonId } from "../schema/common.js";
+import { type AgentContext, type BridgePolicy, type ConvEvent, type ConvHead, type ConvId, type ConvKind, type ConvLogEntry, type ConvRole, type HistoryPolicy, type MsgKind, type ParticipantId, type Permit, type RekeyCause, type RespondTo, type Visibility } from "../schema/conversation.js";
+import type { RealmId } from "../schema/realm.js";
+/** A participant at one position. */
+export interface ConvParticipant {
+    p: ParticipantId;
+    person: PersonId;
+    /** The agent's session name, for an agent participant. */
+    agent?: string;
+    role: ConvRole;
+    /** `invited` until the person accepts, or until the agent's person seats it. */
+    state: "member" | "invited";
+    device?: MachineId;
+    respondTo?: RespondTo;
+    /** The seq at which it became a participant. */
+    since: number;
+}
+/** Everything the log decides at one position. Frozen. */
+export interface ConvSnapshot {
+    cid: ConvId;
+    kind: ConvKind;
+    visibility?: Visibility;
+    history: HistoryPolicy;
+    retainDays: number;
+    org?: string;
+    post: Permit;
+    invite: Permit;
+    pins: Permit;
+    archived: boolean;
+    epoch: number;
+    /** The seq and `ts` of the op that started the epoch. */
+    epochSince: number;
+    epochTs: number;
+    /** Causes that need a `rekey` before the next message (spec §16.7). Sorted. */
+    rekeyDue: RekeyCause[];
+    /** Sorted by `p`. */
+    participants: ConvParticipant[];
+    /** The effective policy. In a channel the owners' and admins'; in a dm or a group the strictest vote. */
+    agentContext: AgentContext;
+    /**
+     * Who may mirror the conversation to a linked channel (reserved: no daemon acts on it yet). In a channel the
+     * owners' and admins'; in a dm or a group the strictest vote, where a person who has not voted counts as `none`.
+     */
+    bridges: BridgePolicy;
+    /** dm and group: each participant person's votes, sorted by person. */
+    votes: ConvVote[];
+    /** The seq of the entry that last changed any of the above. */
+    changed: number;
+}
+/** One participant person's policy votes in a dm or group. */
+export interface ConvVote {
+    person: PersonId;
+    agentContext?: AgentContext;
+    bridges?: BridgePolicy;
+}
+/** What a member knows of one event, by id. */
+export interface ConvMessage {
+    id: string;
+    seq: number;
+    class: ConvEvent["class"];
+    author: ParticipantId;
+    /** Known when the body was opened. */
+    t?: MsgKind;
+    deleted: boolean;
+    pinned: boolean;
+    reactions: {
+        key: string;
+        by: ParticipantId[];
+    }[];
+    /** For a task request: its executor. */
+    taskTo?: ParticipantId;
+    /** For a task request: true. */
+    taskRoot?: boolean;
+}
+/** Checks only a live append can make: they depend on the realm now, not on the log. */
+export interface ConvLiveChecks {
+    /** Wall-clock time; the event's `ts` must be within `skewMs` (default `LIMITS.clockSkewMs`) of it (`expired`). */
+    now?: number;
+    skewMs?: number;
+    /** True when `device` is a current device of `person` in the realm (`unknown_device` otherwise). */
+    isDevice?: (person: PersonId, device: MachineId) => boolean;
+    /** The org of `person`, for `join`, and for an add of a person who is not a guest (`forbidden`). */
+    orgOf?: (person: PersonId) => string | undefined;
+}
+export interface ConvApplyOptions {
+    /** The opened body of a `msg` entry; the message rules run only with it. */
+    body?: unknown;
+    live?: ConvLiveChecks;
+}
+/** An entry whose content the relay expired: its seq, its prev and the digest SHA-256(JCS(event)). */
+export interface ConvExpiredEntry {
+    seq: number;
+    prev: Hash;
+    digest: Hash;
+}
+/**
+ * A verified conversation log. Every method throws only MessagingError. Entries are kept as frozen copies of the
+ * received JSON, so hashes cover exactly what was received.
+ */
+export declare class ConvLog {
+    #private;
+    readonly cid: ConvId;
+    readonly realm: RealmId;
+    private constructor();
+    /** An empty log of `cid` in `realm`: its head is {0, h(0)}. */
+    static open(cid: ConvId, realm: RealmId): ConvLog;
+    /** Replays `entries` (each with the opened body of a `msg`, when the caller has it). Throws the first failure. */
+    static fromEntries(cid: ConvId, realm: RealmId, entries: {
+        entry: unknown;
+        body?: unknown;
+    }[]): ConvLog;
+    head(): ConvHead;
+    /** The last op's seq and hash, or {0, h(0)}: what an author puts in `opHead`. */
+    opHead(): ConvHead;
+    /** h(seq), for 0 ≤ seq ≤ head. */
+    hashAt(seq: number): Hash | undefined;
+    entries(): (ConvLogEntry | ConvExpiredEntry)[];
+    /** The state at the head; undefined before `create`. */
+    state(): ConvSnapshot | undefined;
+    /** The state after the entry at `seq`, as a log holding only entries 1..seq has it. */
+    at(seq: number): ConvSnapshot | undefined;
+    /** What a member knows of the event `id`. */
+    message(id: string): ConvMessage | undefined;
+    /**
+     * Gossip (spec §16.4): `ahead` past the head (fetch up to it first); `consistent` when h(seq) is ours; `diverged`
+     * when this log has another hash at that seq, a fork whose evidence is the signed event that named it.
+     */
+    relate(head: ConvHead): AnchorRelation;
+    /**
+     * Checks one entry and appends it, in order: I-JSON and size (`invalid_request`, `too_large`); schema, realm and
+     * cid (`invalid_request`); the chain, seq = head + 1 and prev = h(head) (`conv_conflict`); the signature
+     * (`bad_signature`); the live checks given (`expired`, `unknown_device`); a reused id (`duplicate`); then the
+     * authority rules of spec §16.7. Returns the entry's h(seq).
+     */
+    apply(raw: unknown, options?: ConvApplyOptions): Hash;
+    /**
+     * Appends an entry whose content the relay expired (spec §16.4, "Retention"), by its digest: the chain stays
+     * verifiable and the state does not change. An op is never expired: a later op head that names this seq fails.
+     */
+    applyExpired(raw: ConvExpiredEntry): Hash;
+}

package/dist/types/core/conversation/ratchet.d.ts

@@ -0,0 +1,95 @@
+import { z } from "zod";
+import { type MachineId } from "../schema/common.js";
+import { type KeyShare } from "../schema/conversation.js";
+/** One ratchet step: the message key for this index and the chain key for the next. */
+export declare function chainStep(ck: Uint8Array): {
+    mk: Uint8Array;
+    next: Uint8Array;
+};
+/** A sender chain as a device stores it. */
+export declare const SenderChainState: z.ZodObject<{
+    epoch: z.ZodNumber;
+    device: z.ZodString;
+    start: z.ZodNumber;
+    origin: z.ZodString;
+    idx: z.ZodNumber;
+    ck: z.ZodString;
+    startedAt: z.ZodNumber;
+}, z.core.$strict>;
+export type SenderChainState = z.infer<typeof SenderChainState>;
+/** The sending side of one chain. `next()` hands out each message key once. */
+export declare class SenderChain {
+    #private;
+    readonly epoch: number;
+    readonly device: MachineId;
+    /** The index this chain starts at. */
+    readonly start: number;
+    readonly startedAt: number;
+    private constructor();
+    /** A new chain at `idx` (default 0) of `epoch`, from a fresh random chain key. */
+    static start(args: {
+        epoch: number;
+        device: MachineId;
+        idx?: number;
+        now: number;
+    }): SenderChain;
+    /** `start` with a caller-chosen chain key: for test vectors, and for a device restoring its own state. */
+    static startWith(args: {
+        epoch: number;
+        device: MachineId;
+        idx?: number;
+        now: number;
+    }, ck: Uint8Array): SenderChain;
+    static restore(raw: unknown): SenderChain;
+    export(): SenderChainState;
+    /** The index the next message gets. */
+    get idx(): number;
+    /** The share that lets a receiver open every message of this chain: its chain key at its start. */
+    share(): KeyShare;
+    /** The key for the next message, and its index. The chain moves past it. */
+    next(): {
+        idx: number;
+        mk: Uint8Array;
+    };
+    /** True once the chain has sent `LIMITS.chainMessages` messages or is `LIMITS.chainMaxMs` old: rotate before the next. */
+    due(now: number): boolean;
+    /** A fresh chain in the same epoch, starting at this chain's next index. Share it before sending on it. */
+    rotate(now: number): SenderChain;
+    /** `rotate` with a caller-chosen chain key, for test vectors. */
+    rotateWith(now: number, ck: Uint8Array): SenderChain;
+}
+export declare const ReceiverChainsState: z.ZodObject<{
+    chains: z.ZodArray<z.ZodObject<{
+        epoch: z.ZodNumber;
+        device: z.ZodString;
+        start: z.ZodNumber;
+        origin: z.ZodString;
+        pos: z.ZodNumber;
+        ck: z.ZodString;
+        skipped: z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodString], null>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ReceiverChainsState = z.infer<typeof ReceiverChainsState>;
+/**
+ * The receiving side: every chain this device holds for one conversation, by (epoch, sender device). It derives
+ * forward only and hands out each message key once; a message that arrives out of order uses a key kept from an
+ * earlier derivation, at most `LIMITS.skippedKeys` per sender and epoch. The chain keys at each share's index are
+ * kept, so the device can share them with a late joiner (history `shared`).
+ */
+export declare class ReceiverChains {
+    #private;
+    static restore(raw: unknown): ReceiverChains;
+    export(): ReceiverChainsState;
+    /**
+     * Adds a share. The first share at a given (epoch, device, idx) wins: a later one with another key changes
+     * nothing, and `add` returns false. Returns true when the share was new.
+     */
+    add(raw: KeyShare): boolean;
+    /** Every share this device holds, from each chain's start: what it shares with a late joiner. */
+    shares(): KeyShare[];
+    /**
+     * The message key for (`epoch`, `device`, `idx`), used once. `not_found` when no share covers it, or its key was
+     * already used or dropped; `too_large` when it is more than `LIMITS.skippedKeys` past the chain's position.
+     */
+    messageKey(epoch: number, device: MachineId, idx: number): Uint8Array;
+}

package/dist/types/core/conversation/seal.d.ts

@@ -0,0 +1,47 @@
+import type { Identity } from "../identity.js";
+import { type EncKey, type MachineId, type PersonId } from "../schema/common.js";
+import { type ConvKeysEvent, ConvMeta, type ConvMsgEvent, type ConvOpEvent, type KeyShare, MsgBody } from "../schema/conversation.js";
+/** A message event before its body: the header its author signs, with `class: "msg"`. */
+export type UnsealedMsg = Omit<ConvMsgEvent, "body" | "sig">;
+/** A keys event before its body. */
+export type UnsealedKeys = Omit<ConvKeysEvent, "body" | "sig">;
+/** A recipient device of a key share: its person, its machine and its X25519 key, as the realm verified them. */
+export interface ShareRecipient {
+    person: PersonId;
+    device: MachineId;
+    enc: EncKey;
+}
+/** Fixed randomness of one sealed share, for test vectors: the ephemeral X25519 private key and the nonce. */
+export interface ShareRandomness {
+    ephemeral: Uint8Array;
+    nonce: Uint8Array;
+}
+/** Seals `body` under `mk` as the body of `unsealed` and signs the event. Throws only MessagingError. */
+export declare function sealConvMsg(identity: Identity, unsealed: UnsealedMsg, body: MsgBody, mk: Uint8Array): ConvMsgEvent;
+/** `sealConvMsg` with a caller-chosen nonce: for test vectors only (`@messaging/core/testing`). */
+export declare function sealConvMsgWith(identity: Identity, unsealed: UnsealedMsg, body: MsgBody, mk: Uint8Array, nonce: Uint8Array): ConvMsgEvent;
+/**
+ * Opens a `msg` event's body with its message key: `bad_signature` when it fails to open, `too_large` over
+ * `LIMITS.convPlaintextBytes`, `invalid_request` when the plaintext is not a `MsgBody` (parsed with `parseWire`).
+ * The caller has verified the event's signature.
+ */
+export declare function openConvMsg(event: ConvMsgEvent, mk: Uint8Array): MsgBody;
+/** `create.sealedMeta`: JCS(meta) sealed under the creator's epoch-0 key 0, with the create event's header as AAD. */
+export declare function sealConvMeta(header: Omit<ConvOpEvent, "body" | "sig">, meta: ConvMeta, mk0: Uint8Array): string;
+/** `sealConvMeta` with a caller-chosen nonce: for test vectors only. */
+export declare function sealConvMetaWith(header: Omit<ConvOpEvent, "body" | "sig">, meta: ConvMeta, mk0: Uint8Array, nonce: Uint8Array): string;
+/** Opens a `create` event's `sealedMeta`. Errors as for `openConvMsg`; `not_found` when it has none. */
+export declare function openConvMeta(event: ConvOpEvent, mk0: Uint8Array): ConvMeta;
+/**
+ * Seals `shares` to each recipient device as the body of `unsealed`, and signs the event. One sealed share per
+ * device; at most `LIMITS.keySharesPerEvent` devices and `LIMITS.keyShares` chain keys. Throws only MessagingError.
+ */
+export declare function sealKeyShares(identity: Identity, unsealed: UnsealedKeys, recipients: ShareRecipient[], shares: KeyShare[]): ConvKeysEvent;
+/** `sealKeyShares` with fixed randomness per recipient, in order: for test vectors only. */
+export declare function sealKeySharesWith(identity: Identity, unsealed: UnsealedKeys, recipients: ShareRecipient[], shares: KeyShare[], randomness: ShareRandomness[]): ConvKeysEvent;
+/**
+ * Opens the share sealed to `identity`'s device in a `keys` event: `not_found` when there is none, `bad_signature`
+ * when it fails to open, `invalid_request` when the plaintext is not a share payload. The caller has verified the
+ * event's signature and applied it to the log.
+ */
+export declare function openKeyShares(event: ConvKeysEvent, identity: Identity): KeyShare[];

package/dist/types/core/index.d.ts

@@ -32,7 +32,14 @@ export { createGrant, verifyChain, type GrantArgs, type ChainHop, type ChainCont
 export { canTransition, isTerminal, isInterrupted } from "./task.js";
 export { TERMINAL_STATES } from "./schema/a2a.js";
 export { cleanPeerText, createFence, terminalSafe, displayWidth, HOST_TAGS, PEER_FENCE_TAG, PEER_DATA_NOTICE, provenanceOf, type CleanOptions, type Fence, type FenceAttributes, type FenceOptions, type TerminalOptions } from "./peer-text.js";
-export { AgentTool, TOOL_VERBS, TOOL_DESCRIPTIONS, ToolExpect, UNTRUSTED_SENTENCE, TOOL_REMEDIES, DONE_STATES, TaskStateName, ToolErrorBody, ToolFiles, a2aTaskState, conversationOf, decodeToolCursor, encodeToolCursor, formatToolAddress, parseToolAddress, taskStateName, toolErrorBody, toolName, type ToolAddress, type ToolAuthor, type ToolChain, type ToolConsent, type ToolCursor, type ToolInput, type ToolOutput, type ToolPart, type ToolTask, type ToolVerb, } from "./agent-tools.js";
+export { AgentTool, TOOL_VERBS, TOOL_DESCRIPTIONS, ToolExpect, UNTRUSTED_SENTENCE, TOOL_REMEDIES, STORE_REFUSED_REMEDIES, DONE_STATES, TaskStateName, ToolErrorBody, ToolFiles, a2aTaskState, conversationOf, decodeToolCursor, encodeToolCursor, formatToolAddress, parseToolAddress, taskStateName, toolErrorBody, toolName, type ToolAddress, type ToolAuthor, type ToolChain, type ToolConsent, type ToolCursor, type ToolInput, type ToolOutput, type ToolPart, type ToolTask, type ToolVerb, } from "./agent-tools.js";
 export { Operations, type CallSession, type ChatAccess, type OperationsContext, type OperationsHooks, type SendPlan, type ToolLink, } from "./agent/operations.js";
 export { agentCan, consentOf, conversationOfPeer, followUpRead, isoOf, presentAgent, presentConvEntry, presentInboxItem, presentLine, presentMail, presentSent, presentTask, presentTaskItem, presentTaskView, } from "./agent/present.js";
 export { chainPath, compact, delegated, delegationPrompt, EXPECT_TEXT, isSafeId, messageAttributes, validatedAddress, type SessionAddressParts, type ToolFramer, } from "./agent/text.js";
+export { dmConvId, selfConvId, participantOf, participantPerson, participantAgent } from "./conversation/ids.js";
+export { admitConvEvent, convEntryHash, convEventDigest, convEventHeader, convEventSigned, convGenesisHash, convLinkHash, signConvEvent, verifyConvEvent, } from "./conversation/event.js";
+export { chainStep, ReceiverChains, ReceiverChainsState, SenderChain, SenderChainState } from "./conversation/ratchet.js";
+export { openConvMeta, openConvMsg, openKeyShares, sealConvMeta, sealConvMsg, sealKeyShares, type ShareRecipient, type UnsealedKeys, type UnsealedMsg, } from "./conversation/seal.js";
+export { ConvLog, type ConvApplyOptions, type ConvExpiredEntry, type ConvLiveChecks, type ConvMessage, type ConvParticipant, type ConvSnapshot, type ConvVote, } from "./conversation/log.js";
+export { checkVia, currentLinks, linkReader } from "./conversation/link.js";
+export { CONTEXT_DEFAULTS, contextKindOf, matchContextRule, resolveContext, seatReads, type ContextConv, type ContextDecision, } from "./conversation/context.js";

package/dist/types/core/schema/common.d.ts

@@ -42,6 +42,18 @@ export declare const DOMAIN: {
     readonly epoch: "messaging/1/epoch\n";
     /** Hosted realms (spec §15.6): an epoch-key rotation, signed by the old key and by the new over JCS(rotation without sigs). */
     readonly dirKey: "messaging/1/dir-key\n";
+    /** Conversations (spec §16.4): a conversation event, signed by `by.device` over JCS(event without sig). */
+    readonly convEvent: "messaging/1/conv-event\n";
+    /** Conversations (spec §16.4): the prefix of a conversation log's genesis hash h(0), over JCS(cid). */
+    readonly convGenesis: "messaging/1/conv-genesis\n";
+    /** Conversations (spec §16.1): the prefix of the hash that derives a dm's id, over JCS of its two sorted participants. */
+    readonly dm: "messaging/1/dm\n";
+    /** Conversations (spec §16.1): the prefix of the hash that derives a person's `self` conversation id, over JCS(person). */
+    readonly self: "messaging/1/self\n";
+    /** Conversations (spec §16.5): HKDF `info` for a sender chain's message key. */
+    readonly convMsg: "messaging/1/conv-msg";
+    /** Conversations (spec §16.5): HKDF `info` for a sender chain's next chain key. */
+    readonly convChain: "messaging/1/conv-chain";
 };
 /** A2A extension and binding URIs owned by Messaging. */
 export declare const URI: {
@@ -242,6 +254,50 @@ export declare const LIMITS: {
     readonly a2hPerHour: 30;
     /** Max lines one person's agents send to another person in a day, summed over the agents (spec §6.9, "Pacing"). */
     readonly a2hPerDay: 100;
+    /** Conversations (spec §16): max participants (persons and agents) of a channel. */
+    readonly convParticipants: 1000;
+    /** Max participants (persons and agents) of a group. A group has at least 3. */
+    readonly groupParticipants: 50;
+    /** Max participants one `add` or `remove` op names. */
+    readonly convOpParticipants: 100;
+    /** Max UTF-8 bytes of one conversation event (JCS), signature and body included. */
+    readonly convEventBytes: 262144;
+    /** Max UTF-8 bytes of one message body's plaintext (JCS) before it is sealed. */
+    readonly convPlaintextBytes: 65536;
+    /** Max UTF-16 code units of one conversation line's text. */
+    readonly lineChars: 40000;
+    /** Max mentions in one line or edit. */
+    readonly mentions: 50;
+    /** Max attachments in one line. */
+    readonly files: 10;
+    /** Max delegation grants one line carries for the agents it mentions (spec §16.3). */
+    readonly agentMentions: 5;
+    /** Max bytes of one attached file, encrypted. */
+    readonly blobBytes: 26214400;
+    /** Max distinct reaction keys on one event. */
+    readonly reactionsPerEvent: 50;
+    /** Max pinned events in one conversation. */
+    readonly pins: 100;
+    /** Retention of a conversation that sets none, in days. */
+    readonly retainDaysDefault: 90;
+    /** Max `retainDays` of a conversation, and max lookback of a context rule. */
+    readonly retainDaysMax: 365;
+    /** Max message keys a receiver keeps for one sender chain to open messages that arrive out of order. */
+    readonly skippedKeys: 1000;
+    /** A sender starts a new chain after this many messages on one chain... */
+    readonly chainMessages: 500;
+    /** ...or this long after it started the chain, whichever comes first. */
+    readonly chainMaxMs: number;
+    /** An epoch older than this may be ended by a `rekey` with cause `schedule`. */
+    readonly rekeyScheduleMs: number;
+    /** Max chain keys in one sealed key share, and in one `keys` sync of the `self` conversation. */
+    readonly keyShares: 512;
+    /** Max recipient devices one `keys` event seals to; a larger share is split over several events. */
+    readonly keySharesPerEvent: 500;
+    /** Max agents one event's `wake` hint names. */
+    readonly wakeHints: 5;
+    /** Max context rules a person holds (spec §16.8). */
+    readonly contextRules: 500;
 };
 /**
  * True for a relay URL a client may connect to: `wss://`, or `ws://` to a loopback host (`localhost`,