@joe-broadhead/messaging 0.0.0-stage → 0.7.1

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

@@ -0,0 +1,6 @@
+/** RFC 4648 §5 base64url without padding. `decode` rejects padding, foreign characters and non-canonical trailing bits. */
+export declare const b64u: {
+    encode(bytes: Uint8Array): string;
+    decode(text: string): Uint8Array;
+};
+export declare function utf8(text: string): Uint8Array;

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

@@ -0,0 +1,21 @@
+import { z } from "zod";
+declare const TeamCard: z.ZodObject<{
+    v: z.ZodLiteral<"messaging/1">;
+    relay: z.ZodString;
+    team: z.ZodString;
+    name: z.ZodString;
+}, z.core.$strict>;
+export type TeamCard = z.infer<typeof TeamCard>;
+declare const AdmitCard: z.ZodObject<{
+    v: z.ZodLiteral<"messaging/1">;
+    machine: z.ZodString;
+    enc: z.ZodString;
+    person: z.ZodString;
+    label: z.ZodString;
+}, z.core.$strict>;
+export type AdmitCard = z.infer<typeof AdmitCard>;
+export declare function encodeTeamCard(card: TeamCard): string;
+export declare function decodeTeamCard(text: string): TeamCard;
+export declare function encodeAdmitCard(card: AdmitCard): string;
+export declare function decodeAdmitCard(text: string): AdmitCard;
+export {};

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

@@ -0,0 +1,10 @@
+import type { z } from "zod";
+import { type ErrorCode, MessagingError } from "./schema/errors.js";
+/** Parses with a schema, throwing a MessagingError that names the failing path but never echoes the value. */
+export declare function parseWith<S extends z.ZodType>(schema: S, value: unknown, what: string, code?: ErrorCode): z.output<S>;
+/**
+ * What a public entry point throws for `error`: a MessagingError unchanged; anything else (a RangeError or a
+ * TypeError caused by a hostile value) as `invalid_request`. The original is not chained as `cause`,
+ * because its message can quote the input.
+ */
+export declare function asMessagingError(error: unknown, what: string): MessagingError;

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

@@ -0,0 +1,132 @@
+import type { Identity } from "./identity.js";
+import { type MachineId, type PersonId, type Ulid } from "./schema/common.js";
+import { type AgentMailLevel, type AskLevel, type ChatLevel, ConsentGrant, type GrantLevels, type GrantSubject } from "./schema/consent.js";
+import type { RealmId } from "./schema/realm.js";
+export interface ConsentGrantArgs {
+    realm: RealmId;
+    /** The person whose policy this is: the signing device's person. */
+    person: PersonId;
+    subject: GrantSubject;
+    levels: GrantLevels;
+    now: number;
+    id?: Ulid;
+}
+/** Signs a new grant with `identity`, a device of `args.person`. Throws `invalid_request` for a grant that breaks a rule. */
+export declare function signConsentGrant(identity: Identity, args: ConsentGrantArgs): ConsentGrant;
+/**
+ * Checks a grant received from another device: the schema and its rules, the size, the realm, the person when
+ * given, and the signature by `by` over the raw value (so members a newer device adds stay covered). Whether `by`
+ * is a current device of `person` is the caller's: that changes over time (spec §6.9, "Signers"). Throws only
+ * MessagingError: `invalid_request`, `too_large` or `bad_signature`.
+ */
+export declare function verifyConsentGrant(raw: unknown, ctx: {
+    realm: RealmId;
+    person?: PersonId;
+}): ConsentGrant;
+/** The key one grant is stored under: its subject. One grant per subject. */
+export declare function grantSubjectKey(subject: GrantSubject): string;
+/**
+ * Of two copies of the grant for one subject, the one that counts (spec §6.9, "Merging"): the newer by `ts`, then
+ * by `id`. Copies that tie on both are one grant signed twice: a copy whose signer is current beats one whose
+ * signer is not; between two current signers (or two removed ones), the signer that sorts first wins, then the
+ * signature. The choice is commutative and idempotent, so devices that see the same copies in any order agree.
+ */
+export declare function preferGrant(a: ConsentGrant, b: ConsentGrant, current: (device: MachineId) => boolean): ConsentGrant;
+/** Levels that narrow reach: blocks never lapse (spec §6.9, "Signers"). */
+export declare function restrictingLevels(grant: GrantLevels): GrantLevels;
+/** Levels that widen reach: they lapse with their signer, into the person's review list. */
+export declare function wideningLevels(grant: GrantLevels): GrantLevels;
+/**
+ * Re-signs a grant whose signer is no longer current with `identity`, a current device of the same person
+ * (spec §6.9, "Signers"). `keep: "all"` (a replacement) keeps every level; `keep: "restricting"` (any other
+ * removal) keeps only the restricting ones, and returns undefined when there are none: the grant lapses whole.
+ * The copy keeps `id` and `ts`, so it never overrides a newer change, and records `resignedAt`.
+ */
+export declare function resignGrant(identity: Identity, grant: ConsentGrant, opts: {
+    now: number;
+    keep: "all" | "restricting";
+}): ConsentGrant | undefined;
+export declare function levelsOf(grant: GrantLevels): GrantLevels;
+/** How the sending person relates to the receiving person (spec §6.9, "Relations"). A roster realm has only `self` and `org`. */
+export type Relation = "self" | "org" | "contact" | "stranger";
+/** How an item delivered to an agent may run (spec §6.9): the person's own, a trusted sender's, or a guarded peer turn. */
+export type ConsentClass = "self" | "guarded" | "trusted";
+/** The levels that apply to one sender, and where each came from. */
+export interface EffectivePolicy {
+    chat: ChatLevel | "request_required";
+    agentMail: AgentMailLevel;
+    ask: AskLevel;
+    /** Set while the person grant trusts the sender. */
+    trustedUntil?: number;
+    /** Which levels a grant set, rather than the relation's default. */
+    granted: {
+        chat: boolean;
+        agentMail: boolean;
+        ask: boolean;
+    };
+}
+/**
+ * Spec §6.9, "Effective policy": each level is the person grant's when it sets one; otherwise, for `ask` and
+ * `agentMail`, the most permissive among the grants of channels the sender is in; otherwise the relation's
+ * default. An expired `trustedUntil` reads as absent. The caller passes only grants whose signer is current.
+ */
+export declare function effectivePolicy(relation: Exclude<Relation, "self">, person: GrantLevels | undefined, channels: readonly GrantLevels[], now: number): EffectivePolicy;
+/**
+ * What arrived, classified by the receiver (spec §6.9, "Enforcement"):
+ * - `answer`: a receipt, a task update or cancel, or a message the counterpart binding ties to this person's own
+ *   traffic (a reply or a follow-up); never gated;
+ * - `line`: a DM line or channel post, from the person (`agent: false`) or one of their agents (`agent: true`);
+ * - `op`: a channel change;
+ * - `ask`: mail or a task request to one of the receiver's agents, with the persons of its delegation chain (the
+ *   sender's alone for mail);
+ * - `request`: a message request (class `request`), a person's first line to a person of another org.
+ */
+export type Inbound = {
+    kind: "answer";
+} | {
+    kind: "line";
+    agent: boolean;
+} | {
+    kind: "op";
+} | {
+    kind: "ask";
+    chain: readonly PersonId[];
+} | {
+    kind: "request";
+};
+export type ConsentDecision = {
+    action: "deliver";
+    consent: ConsentClass;
+    silent?: true;
+} | {
+    action: "hold";
+} | {
+    action: "refuse";
+    code: "refused" | "request_required";
+};
+export interface DecideArgs {
+    /** The receiving person. */
+    self: PersonId;
+    /** The sending person. */
+    sender: PersonId;
+    relation: Relation;
+    /** The person grant for the sender, when its signer is current. */
+    grant?: GrantLevels;
+    /** Grants of channels the sender is in, in the receiver's own view, each with a current signer. */
+    channels: readonly GrantLevels[];
+    inbound: Inbound;
+    now: number;
+}
+/**
+ * Spec §6.9, "Enforcement": step 10 of the receiver order (§5), before the inbound policy of §8.3.
+ * - The person's own traffic is delivered as `self`.
+ * - Answers to the person's own traffic are delivered whatever the grants, so a change never strands a task.
+ * - A `blocked` chat level refuses every other class from the sender.
+ * - A `stranger` reaches the person only through a level a grant opened; otherwise `request_required`.
+ * - Lines follow `chat` (person) or `agentMail` (agent); `muted` delivers silently.
+ * - Asks follow `ask`: `open` delivers guarded, or trusted while the person grant trusts the sender and every person
+ *   in the delegation chain is the sender or the receiver; `request` holds; `no` refuses, `request_required` when
+ *   it is the default of a `contact` or a `stranger`.
+ * - A message request from a `stranger` is held for the person to accept; from anyone else it is a DM line.
+ */
+export declare function decide(args: DecideArgs): ConsentDecision;

package/dist/types/core/contact-card.d.ts

@@ -0,0 +1,34 @@
+import { type Relation } from "./consent.js";
+import type { Identity } from "./identity.js";
+import { type PersonId, type Ulid } from "./schema/common.js";
+import { type CardCan, ContactCard, type GrantLevels } from "./schema/consent.js";
+import type { RealmId } from "./schema/realm.js";
+export interface ContactCardArgs {
+    realm: RealmId;
+    /** The person the card speaks for: the signing device's person. */
+    from: PersonId;
+    /** The person it is for. */
+    to: PersonId;
+    seq: number;
+    now: number;
+    grantId?: Ulid;
+    can: CardCan;
+}
+/** Signs a card with `identity`, a device of `args.from`. Throws `invalid_request` or `too_large`. */
+export declare function signContactCard(identity: Identity, args: ContactCardArgs): ContactCard;
+/**
+ * Checks a card received from another person: the schema and its rules, the size, the realm, its two persons, and
+ * the signature by `by` over the raw value. Whether `by` is a current device of `from` is the caller's: a card
+ * whose signer was removed counts as absent. Throws only MessagingError: `invalid_request`, `too_large` or
+ * `bad_signature`.
+ */
+export declare function verifyContactCard(raw: unknown, ctx: {
+    realm: RealmId;
+    from: PersonId;
+    to: PersonId;
+}): ContactCard;
+/**
+ * What a card says for a sender of `relation` with the person grant `grant` (spec §6.9, "Contact cards"): the
+ * person grant over the relation's defaults. Channel grants are not on a card: the sender knows its own channels.
+ */
+export declare function cardCan(relation: Exclude<Relation, "self">, grant: GrantLevels | undefined, now: number): CardCan;

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

@@ -0,0 +1,56 @@
+import type { PersonId, SessionName } from "../schema/common.js";
+import { type AgentContext, type ContextAccess, type ContextKind, type ContextRule, type ConvId, type ConvKind, type Visibility } from "../schema/conversation.js";
+/** The defaults that apply where a person has no rule (decided 2026-11-08). `lookbackDays` absent: the retention. */
+export declare const CONTEXT_DEFAULTS: Readonly<Record<ContextKind, {
+    access: ContextAccess;
+    lookbackDays?: number;
+}>>;
+/** The facts about a conversation that resolution reads. `persons` are its participant persons at the read. */
+export interface ContextConv {
+    cid: ConvId;
+    kind: ConvKind;
+    visibility?: Visibility;
+    persons: readonly PersonId[];
+    retainDays: number;
+    agentContext: AgentContext;
+}
+/**
+ * The scope a conversation falls in for `person`: `own` when its participant persons are `person` alone, else its
+ * kind (a channel by its visibility). A `self` conversation has none: no agent mines it.
+ */
+export declare function contextKindOf(person: PersonId, conv: Pick<ContextConv, "kind" | "visibility" | "persons">): ContextKind | undefined;
+/**
+ * The person's rule for (agent, conversation), most specific first: a `cid` scope over a `kind` scope, then a named
+ * agent over `*`. Undefined when no rule matches; the defaults then apply.
+ */
+export declare function matchContextRule(rules: readonly ContextRule[], agent: SessionName, cid: ConvId, kind: ContextKind): ContextRule | undefined;
+/** The outcome of a context read: served, held for the person (`ask`), or refused. */
+export type ContextDecision = {
+    access: "allow" | "ask";
+    lookbackDays: number;
+    source: "rule" | "default";
+} | {
+    access: "forbidden";
+    source: "policy" | "rule" | "self";
+};
+/**
+ * The effective rule for agent `agent` of `person` reading `conv` as context (not by its seat):
+ * - the conversation's policy `seats` or `none` forbids it, whatever the person's rule says;
+ * - else the person's rule, or the default: `off` forbids, `ask` holds, `allow` serves;
+ * - the lookback is the smallest of the rule's (or the default's) `lookbackDays`, the conversation's `retainDays`,
+ *   and the person's local retention for it.
+ * Throws `invalid_request` for a rule set that fails `ContextRules`.
+ */
+export declare function resolveContext(args: {
+    person: PersonId;
+    agent: SessionName;
+    conv: ContextConv;
+    rules: readonly ContextRule[];
+    localRetentionDays?: number;
+}): ContextDecision;
+/**
+ * What a seated agent reads by its seat (spec §16.8): everything from its seat's `seq` on, unless the policy is
+ * `none`, when it reads only the events addressed to it and the threads they are in. The person's rules do not
+ * apply to seat reads.
+ */
+export declare function seatReads(agentContext: AgentContext): "conversation" | "items";

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

@@ -0,0 +1,36 @@
+import type { Identity } from "../identity.js";
+import { type Hash } from "../schema/common.js";
+import { type ConvEvent, type ConvEventHeader, type ConvId, type UnsignedConvEvent } from "../schema/conversation.js";
+/** h(0) of `cid`'s log: SHA-256(DOMAIN.convGenesis ‖ JCS(cid)), base64url. */
+export declare function convGenesisHash(cid: ConvId): Hash;
+/** SHA-256(JCS(event)), the raw digest, as the chain links it. Throws `invalid_request` for non-I-JSON. */
+export declare function convEventDigest(event: unknown): Uint8Array;
+/** h(seq) = SHA-256(h(seq − 1) ‖ SHA-256(JCS(event))), over the raw 32-byte digests, base64url. */
+export declare function convEntryHash(prev: Hash, event: unknown): Hash;
+/** `convEntryHash` from the event's digest: what a member checks for an entry whose content has expired. */
+export declare function convLinkHash(prev: Hash, digest: Uint8Array): Hash;
+/** The header of an event: everything but `body` and `sig`. JCS of it is the AAD of a sealed body. */
+export declare function convEventHeader(event: ConvEvent | Omit<ConvEvent, "sig"> | ConvEventHeader): ConvEventHeader;
+/**
+ * Checks that `raw` is I-JSON within `LIMITS.jsonDepth` and at most `LIMITS.convEventBytes` (`too_large`), that it
+ * matches `ConvEvent`, and that `by.device` is a usable Ed25519 key. Returns a frozen JSON copy of the raw value, so
+ * the signature and the hash cover exactly what was received. The signature is not checked.
+ */
+export declare function admitConvEvent(raw: unknown): ConvEvent;
+/**
+ * Signs an event (spec §16.4): `sig = Ed25519(by.device, DOMAIN.convEvent ‖ JCS(event without sig))`. `by.device`
+ * must be `identity`'s machine. Refuses an event that fails the schema (`invalid_request`) or is over
+ * `LIMITS.convEventBytes` once signed (`too_large`). Authority is checked when the event is applied.
+ */
+export declare function signConvEvent<E extends UnsignedConvEvent>(identity: Identity, unsigned: E): E & {
+    sig: string;
+};
+/** True only for a valid signature by `event.by.device` over the event without `sig`. Never throws. */
+export declare function convEventSigned(event: ConvEvent): boolean;
+/**
+ * Admits `raw` (`admitConvEvent`) and checks its signature over the raw value (`bad_signature`). Membership and
+ * authority are `ConvLog.apply`'s. Throws only MessagingError.
+ */
+export declare function verifyConvEvent(raw: unknown): ConvEvent;
+/** Freezes a JSON value and everything in it, iteratively. */
+export declare function deepFreeze<T>(value: T): T;

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

@@ -0,0 +1,18 @@
+import { PersonId } from "../schema/common.js";
+import { type ConvId, ParticipantId } from "../schema/conversation.js";
+/**
+ * The id of the dm between `a` and `b`: `"d_" + base32lower(SHA-256(DOMAIN.dm ‖ JCS([a, b] sorted)))[0..26]`. Both
+ * ends derive the same id, so a dm has no create race. `a` may equal `b`: a person's note to themselves.
+ */
+export declare function dmConvId(a: ParticipantId, b: ParticipantId): ConvId;
+/** The id of `person`'s own `self` conversation: `"s_" + base32lower(SHA-256(DOMAIN.self ‖ JCS(person)))[0..26]`. */
+export declare function selfConvId(person: PersonId): ConvId;
+/** The person a participant is, or belongs to. */
+export declare function participantPerson(p: ParticipantId): PersonId;
+/** The agent's session name, for an agent participant. */
+export declare function participantAgent(p: ParticipantId): string | undefined;
+/** The participant an event's `by` names: `person`, or `person/agent`. */
+export declare function participantOf(by: {
+    person: PersonId;
+    agent?: string | undefined;
+}): ParticipantId;

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

@@ -0,0 +1,16 @@
+import type { MachineId, PersonId } from "../schema/common.js";
+import { type LinkRecord, type MsgBody, type ReaderId } from "../schema/conversation.js";
+/** The links in force: for each link id the record written last (records are in `seq` order), unless revoked. */
+export declare function currentLinks(records: readonly LinkRecord[]): LinkRecord[];
+/**
+ * Checks a line's `via` against the author's links, as the author's own devices can (other members cannot see the
+ * person's links): only a person writes from a linked channel, never an agent, and only through a link of that
+ * channel that the authoring device hosts and that is in force. Throws `forbidden`.
+ */
+export declare function checkVia(body: MsgBody, by: {
+    person: PersonId;
+    device: MachineId;
+    agent?: string;
+}, links: readonly LinkRecord[]): void;
+/** The reader id of a link's channel provider, for the audience guard: `ext:<channel>:<link id>`. */
+export declare function linkReader(link: Pick<LinkRecord, "channel" | "id">): ReaderId;

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[];