@joe-broadhead/messaging 0.0.0-stage → 0.7.0

package/dist/types/core/directory/jelly-token.d.ts

@@ -0,0 +1,116 @@
+import type { MachineId } from "../schema/common.js";
+import { ArchivedJellyKey, CnfJwk, JellyClaims, JellyTokenHeader } from "../schema/jelly.js";
+/** Contract v1.1 §5 step 5: a token lives at most 900 s, and its `iat` may be at most 60 s ahead of now. */
+export declare const JELLY_MAX_LIFETIME_S = 900;
+export declare const JELLY_IAT_LEEWAY_S = 60;
+/** Contract v1.1 §5 step 2: Jelly's key set is believed for 24 h; the key history for 5 min. */
+export declare const JELLY_JWKS_TTL_MS: number;
+export declare const JELLY_HISTORY_TTL_MS: number;
+/** An archived key's revocation is rechecked against the key history when older than this (spec §15.2). */
+export declare const JELLY_REVOCATION_CHECK_MS: number;
+/** An unknown `kid` refetches a key set at most this often, so a stream of unknown `kid`s cannot loop. */
+export declare const JELLY_REFETCH_MIN_MS: number;
+/** A decoded, not yet verified, resource token. */
+export interface JellyToken {
+    readonly header: JellyTokenHeader;
+    readonly claims: JellyClaims;
+    /** `header.payload`, the bytes the signature covers. */
+    readonly signingInput: Uint8Array;
+    readonly signature: Uint8Array;
+}
+/** A Jelly key with what the key history says of it; a key seen only in the key set has no window. */
+export interface JellyKey {
+    readonly kid: string;
+    readonly x: string;
+    /** Seconds: first published (key history). */
+    readonly nbf?: number | undefined;
+    /** Seconds: dropped from the key set; null while published (key history). */
+    readonly retiredAt?: number | null | undefined;
+    /** Seconds: revoked by an operator (key history). */
+    readonly revokedAt?: number | null | undefined;
+}
+/**
+ * Decodes a compact resource token: three base64url segments, a header with `alg: EdDSA`, `typ:
+ * jelly-resource+jwt` and a printable `kid`, and claims of the contract's shape (contract v1.1 §4, §5 step 1;
+ * `cnf`, when present, exactly `{jwk: {kty, crv, x}}`). Verifies nothing. Throws `binding_invalid`.
+ */
+export declare function decodeJellyToken(token: string): JellyToken;
+/**
+ * True when a key may have signed a token issued at `iat` (seconds): always for a key seen only in the key set;
+ * for a key the history describes, `iat ∈ [nbf, retired_at)` (an open end while `retired_at` is null) and
+ * before any `revoked_at` (contract v1.1 §5 step 2, §11).
+ */
+export declare function jellyKeyCovers(key: JellyKey, iat: number): boolean;
+/** True when `x` is a key Jelly ID would bind (contract v1.1 §3): a canonical Ed25519 point not of small order. */
+export declare function isBindableKey(x: string): boolean;
+/** The `cnf_jwk` a host asks Jelly ID to bind for `device` (contract v1.1 §3, §6). Throws `invalid_request` for an unusable key. */
+export declare function cnfJwk(device: MachineId): CnfJwk;
+export interface JellyVerifyOptions {
+    /** The realm's issuer and resource, compared exactly with `iss` and `aud`. */
+    readonly issuer: string;
+    readonly audience: string;
+    /** The key with this `kid`, as `JellyKeyring.prepare` found it; undefined when no source knows it. */
+    readonly key: (kid: string) => JellyKey | undefined;
+    /** The device the token must be bound to (`cnf.jwk.x`). Without it, `cnf` is checked for shape only. */
+    readonly cnf?: MachineId | undefined;
+    /**
+     * Now, in milliseconds, to check a token as it is presented (contract v1.1 §5 step 5: `exp` in the future, `iat`
+     * at most 60 s ahead). Omit it to check a token kept in a log, whose freshness is judged at its append (§15.3).
+     */
+    readonly now?: number | undefined;
+}
+/**
+ * Verifies a resource token (contract v1.1 §5; spec §15.2 steps 1–6): the header, the key and its window, the
+ * signature, `iss` and `aud`, the lifetime, `sub`, how it was minted (`hst`, or `src: "device"` with no `hst`), and
+ * `cnf`. Returns the decoded token. Throws
+ * `binding_invalid`; never reports a missing key as anything else (finding it is `JellyKeyring`'s).
+ */
+export declare function verifyJellyToken(token: string, options: JellyVerifyOptions): JellyToken;
+export interface JellyKeySources {
+    /** `<issuer>/.well-known/jwks.json`, as text. Rejects when it cannot be fetched. */
+    readonly fetchJwks: () => Promise<string>;
+    /** `<issuer>/.well-known/jwks-history.json`, as text. Rejects when it cannot be fetched. */
+    readonly fetchHistory: () => Promise<string>;
+}
+/**
+ * Finds the keys of resource tokens, in the order of spec §15.2: the client's own archive of every key it has
+ * verified, then Jelly ID's key set (cached 24 h; an unknown `kid` refetches it at most once a minute), then the
+ * key history (cached 5 min). A key found in the key set or the history joins the archive, with the history's
+ * window. An archived key whose revocation was last checked over 24 h ago is checked again, and keeps its archived
+ * window if the history cannot be fetched. Persist `archive()`; pass it back to the constructor.
+ */
+export declare class JellyKeyring {
+    #private;
+    constructor(sources: JellyKeySources, archive?: readonly ArchivedJellyKey[]);
+    /** Every key this client has verified, to persist. */
+    archive(): ArchivedJellyKey[];
+    /** The archived key with this `kid`, without fetching. */
+    archived(kid: string): JellyKey | undefined;
+    /**
+     * Finds the keys of these tokens (a token that does not decode is skipped: verifying it fails anyway) and
+     * returns the synchronous lookup `verifyJellyToken` takes. Throws `jelly_unavailable` when a `kid` is in no
+     * source and a source it needed could not be fetched: never `binding_invalid` for an unreachable Jelly ID.
+     */
+    prepare(tokens: readonly string[], now: number): Promise<(kid: string) => JellyKey | undefined>;
+    /** Finds one key (see the class). Returns undefined when every source answered and none knows it. */
+    resolve(kid: string, now: number): Promise<JellyKey | undefined>;
+}
+/** What a refusal to mint a bound token means for the daemon (contract v1.1 §3, §6, and Jelly's change of 2026-11-05). */
+export type JellyMintRefusal = 
+/** `invalid_target` with `detail: "invalid_cnf_jwk"`: Jelly would not bind this key. A daemon bug: alarm, never retry. */
+"unbindable_key"
+/** `invalid_target` without a detail: the realm's Jelly ID offers no such resource. Say so in status; do not retry. */
+ | "no_resource"
+/** `access_denied`: the account is disabled or being deleted. Final. */
+ | "denied"
+/** `not_enrolled` or `invalid_client`: this host is not (or no longer) enrolled. Final until it is. */
+ | "not_enrolled"
+/** `invalid_request`: the ask was malformed. A daemon or plugin bug: alarm, never retry. */
+ | "bad_request"
+/** `unavailable`, `temporarily_unavailable`, `slow_down` or anything else: hold 30 s, then retry. */
+ | "retry";
+/**
+ * Reads a refusal from Jelly ID's mint route (`{error, detail?}`) or the engine accessor (an `Error` with
+ * `code` and `detail`). Branches on `detail`: a plain `invalid_target` still means no such resource.
+ */
+export declare function jellyMintRefusal(code: string, detail?: string): JellyMintRefusal;

package/dist/types/core/directory/keys-statement.d.ts

@@ -0,0 +1,22 @@
+import type { Identity } from "../identity.js";
+import { type Hash, type HostedPersonId } from "../schema/common.js";
+import { KeysStatement } from "../schema/directory.js";
+import type { RealmId } from "../schema/realm.js";
+/** `SHA-256(JCS(statement))`, the signature included: what the map commits to. */
+export declare function keysStatementHash(statement: KeysStatement): Hash;
+/** This device's statement of its current encryption key. Throws `invalid_request`. */
+export declare function createKeysStatement(identity: Identity, args: {
+    realm: RealmId;
+    person: HostedPersonId;
+    seq: number;
+    ts: number;
+}): KeysStatement;
+/**
+ * Checks a keys statement: the schema and `LIMITS.keysStatementBytes` (`invalid_request`, `too_large`), then
+ * the realm, the person, and the device's signature (`binding_invalid`). Whether the device is current, and
+ * whether `seq` is above the last one seen, are the caller's (`verifyPersonView` checks both).
+ */
+export declare function verifyKeysStatement(statement: unknown, context: {
+    realm: RealmId;
+    person: HostedPersonId;
+}): KeysStatement;

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

@@ -0,0 +1,36 @@
+import type { Identity } from "../identity.js";
+import { type MachineLabel } from "../schema/common.js";
+import { LinkRequest, type DeviceKind } from "../schema/directory.js";
+import type { RealmId } from "../schema/realm.js";
+/** The prefix of a link request's text form. A link is not a secret, but it should not travel through chat. */
+export declare const LINK_PREFIX = "messaging-link.";
+export interface LinkArgs {
+    readonly realm: RealmId;
+    readonly label: MachineLabel;
+    readonly kind: DeviceKind;
+    /** 16 random bytes. */
+    readonly nonce: Uint8Array;
+    readonly ts: number;
+}
+/** The new device's signed link request. Throws `invalid_request`. */
+export declare function createLinkRequest(identity: Identity, args: LinkArgs): LinkRequest;
+/** `messaging-link.` and the base64url of the request's JCS. */
+export declare function encodeLink(link: LinkRequest): string;
+/** Reads a link's text (surrounding whitespace ignored), with `parseWire`. Verifies nothing. Throws `invalid_request`. */
+export declare function decodeLink(text: string): LinkRequest;
+/** True when the request's signature is its device's. Never throws. */
+export declare function verifyLinkSignature(link: LinkRequest): boolean;
+/**
+ * What an approving device checks before it shows the request (§15.3): the schema (`invalid_request`), the
+ * signature and the realm (`binding_invalid`), and `ts` no older than `LIMITS.linkTtlMs` and no later than the
+ * clock skew ahead of `now` (`expired`).
+ */
+export declare function verifyLinkRequest(link: unknown, context: {
+    realm: RealmId;
+    now: number;
+}): LinkRequest;
+/**
+ * The six-digit short authentication string both devices show: the first four bytes of SHA-256(JCS(request)),
+ * big-endian, modulo 1,000,000, zero-padded. The person compares the two before approving.
+ */
+export declare function linkSas(link: LinkRequest): string;

package/dist/types/core/directory/merkle-log.d.ts

@@ -0,0 +1,40 @@
+import type { Hash } from "../schema/common.js";
+type Bytes = Uint8Array;
+/** `SHA-256(0x00 ‖ data)`, the hash of a leaf. */
+export declare function merkleLeafHash(data: Bytes): Hash;
+/**
+ * The leaf hashes of a log, appended in order. It answers the tree head at any size it holds, and the audit
+ * path and consistency proof between sizes (RFC 9162 §2.1.1-§2.1.4). Subtree roots are cached, so a proof
+ * costs O(log² n) hashes after the first.
+ */
+export declare class MerkleLog {
+    #private;
+    /** A log of these leaf hashes (from `merkleLeafHash`), in order. */
+    static fromLeafHashes(hashes: readonly Hash[]): MerkleLog;
+    get size(): number;
+    /** Appends the leaf whose data is `data`; returns its index. */
+    append(data: Bytes): number;
+    /** Appends a leaf by its hash; returns its index. */
+    appendLeafHash(hash: Hash): number;
+    /** The root the log would have with the leaf `hash` appended; the log itself does not change. */
+    rootWith(hash: Hash): Hash;
+    leafHash(index: number): Hash;
+    /** MTH of the first `size` leaves (default: all). The empty tree's root is SHA-256 of nothing. */
+    root(size?: number): Hash;
+    /** The audit path of leaf `index` in the tree of the first `size` leaves, bottom up (RFC 9162 §2.1.3.1). */
+    inclusionProof(index: number, size?: number): Hash[];
+    /** The consistency proof from the tree of `from` leaves to the tree of `size` leaves (RFC 9162 §2.1.4.1). */
+    consistencyProof(from: number, size?: number): Hash[];
+}
+/**
+ * True when `proof` is the audit path of the leaf with hash `leafHash` at `index` in a tree of `size` leaves
+ * whose root is `root` (RFC 9162 §2.1.3.2). Never throws.
+ */
+export declare function verifyInclusion(index: number, size: number, leafHash: Hash, proof: readonly Hash[], root: Hash): boolean;
+/**
+ * True when `proof` shows that the tree of `size1` leaves with root `root1` is a prefix of the tree of `size2`
+ * leaves with root `root2` (RFC 9162 §2.1.4.2). Equal sizes need an empty proof and equal roots; a proof from
+ * the empty tree proves nothing and is false. Never throws.
+ */
+export declare function verifyConsistency(size1: number, size2: number, proof: readonly Hash[], root1: Hash, root2: Hash): boolean;
+export {};

package/dist/types/core/directory/person-view.d.ts

@@ -0,0 +1,90 @@
+import type { Hash, HostedPersonId } from "../schema/common.js";
+import { type EpochProof, type KeysStatement, type LogEntry, type MapValue, type STH } from "../schema/directory.js";
+import { MessagingError } from "../schema/errors.js";
+import type { DeviceId } from "../schema/directory.js";
+import { DeviceLog, type DeviceLogContext } from "./device-log.js";
+/** What a client keeps evidence of when the directory contradicts itself or what the client holds. */
+export type DirectoryEvidence = 
+/** Two signed entries at one `seq` of one log. */
+{
+    readonly kind: "fork";
+    readonly seq: number;
+    readonly ours: LogEntry;
+    readonly theirs: LogEntry;
+}
+/**
+ * The directory serves an older keys statement than the client holds (`theirs` −1: none), or, at a later tree head,
+ * a shorter log than it served at an earlier one (`what: "log"`: the two lengths).
+ */
+ | {
+    readonly kind: "rollback";
+    readonly what: "keys" | "log";
+    readonly ours: number;
+    readonly theirs: number;
+}
+/** The map at the STH does not commit to what was served. */
+ | {
+    readonly kind: "map";
+    readonly sth: STH;
+    readonly head: EpochProof;
+};
+/** `directory_inconsistent`, with the evidence a client keeps and shows in its alarm. Its message never holds values. */
+export declare class DirectoryInconsistency extends MessagingError {
+    readonly evidence: DirectoryEvidence;
+    constructor(message: string, evidence: DirectoryEvidence);
+}
+/** What a client holds of one person: their verified log and their devices' latest keys statements. */
+export interface PersonState {
+    readonly person: HostedPersonId;
+    readonly log: DeviceLog;
+    /** The latest statement of each current device that published one. */
+    readonly keys: ReadonlyMap<DeviceId, KeysStatement>;
+    /** The person was erased: the map holds the tombstone. */
+    readonly erased: boolean;
+}
+export interface PersonViewContext extends Omit<DeviceLogContext, "person"> {
+    /** The STH the view is at, adopted (`adoptSth`). */
+    readonly sth: STH;
+    /** The STH's last epoch leaf (index `size − 1`) with its audit path: `dir.sthIs`'s `head`. */
+    readonly head: unknown;
+    /** What the client already holds of the person, if anything. */
+    readonly known?: PersonState | undefined;
+}
+/**
+ * Verifies one person's view and returns their new state (spec §15.7). Errors: `invalid_request` (shapes),
+ * `binding_invalid` (an entry, a keys statement, or a binding that first appeared in an epoch after its token's
+ * life), the log's own codes, and `directory_inconsistent` (a `DirectoryInconsistency` with evidence when the
+ * directory contradicts what the client holds; a plain one for a proof that fails).
+ */
+export declare function verifyPersonView(view: unknown, context: PersonViewContext): PersonState;
+/**
+ * Two states of one person, each verified (`verifyPersonView`) at its own tree head of one adopted epoch log, `earlier`
+ * at a size at most `later`'s (spec §15.9, "One tree head per view"). The later must extend the earlier: the same
+ * entries at every seq the earlier holds, and, for each device still current, a keys statement at least as new.
+ * A client that verified two views of a person concurrently checks them against each other with this instead of
+ * one against the other's tree head. An erased state on either side is not compared (an erase drops the log).
+ * Throws a `DirectoryInconsistency` with the evidence.
+ */
+export declare function checkPersonSuccession(earlier: PersonState, later: PersonState): void;
+/** What a person's head (`PersonHead`) proves at an STH: absent from the map, erased, or this log head and these keys. */
+export type VerifiedHead = {
+    readonly person: HostedPersonId;
+    readonly state: "absent";
+} | {
+    readonly person: HostedPersonId;
+    readonly state: "erased";
+} | {
+    readonly person: HostedPersonId;
+    readonly state: "live";
+    readonly log: MapValue["log"];
+    readonly keys: readonly Hash[];
+};
+/**
+ * Verifies one person's head (spec §7, `dir.heads`) against the STH a client adopted: the map at its last epoch holds
+ * exactly that value (`mapValue` of the preimage), the tombstone, or nothing. It proves the log head a device binding
+ * to the person extends (`seq + 1`, `prev` = `hash`), and nothing about the entries before it.
+ */
+export declare function verifyPersonHead(view: unknown, context: {
+    sth: STH;
+    head: unknown;
+}): VerifiedHead;

package/dist/types/core/directory/person.d.ts

@@ -0,0 +1,8 @@
+import { type HostedPersonId } from "../schema/common.js";
+/** RFC 4648 §6 base32 in lower case, without padding. */
+export declare function base32Lower(bytes: Uint8Array): string;
+/**
+ * `"p_" + base32lower(SHA-256(UTF-8("messaging/1/person\n") ‖ UTF-8(JCS({iss, sub}))))[0..26]`. `iss` is the
+ * issuer exactly as the token states it; `sub` must be a Jelly account id (`acc_…`). Throws `invalid_request`.
+ */
+export declare function personId(iss: string, sub: string): HostedPersonId;

package/dist/types/core/directory/realm.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A directory realm (spec §15.8): what a daemon home pins of its key directory, and the realm id that follows
+ * from it. The id commits to the directory's origin, the Jelly issuer that vouches for its persons and the epoch
+ * key that signs its tree heads, so two directories never share a realm and a client can tell which one an
+ * envelope belongs to.
+ */
+import { z } from "zod";
+import type { RealmId } from "../schema/realm.js";
+/** What a daemon's `config.json` pins of a directory realm (design §1.1): its relay, issuer, resource and epoch key. */
+export declare const DirectoryRealmConfig: z.ZodObject<{
+    kind: z.ZodLiteral<"directory">;
+    url: z.ZodString;
+    issuer: z.ZodString;
+    resource: z.ZodString;
+    key: z.ZodString;
+    orgDomains: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type DirectoryRealmConfig = z.infer<typeof DirectoryRealmConfig>;
+/**
+ * `base64url(SHA-256(JCS({kind: "directory", origin, issuer, key})))`, where `origin` is the WHATWG origin of the
+ * relay URL. Throws `invalid_request` for a config that does not parse or a key that is not a usable Ed25519 key.
+ */
+export declare function directoryRealmId(config: Omit<DirectoryRealmConfig, "kind" | "resource" | "orgDomains"> & Partial<DirectoryRealmConfig>): RealmId;

package/dist/types/core/directory/smt.d.ts

@@ -0,0 +1,52 @@
+import { type Hash } from "../schema/common.js";
+import { MapValue, type MapProof } from "../schema/directory.js";
+export declare const MAP_DEPTH = 256;
+/** The hash of an empty subtree of height `h` (0 ≤ h ≤ 256), base64url. */
+export declare function emptyMapHash(height: number): Hash;
+/** The map key of a person: `SHA-256(UTF-8(person))`, base64url. */
+export declare function mapKey(person: string): Hash;
+/**
+ * The value a live person's leaf holds: `SHA-256(JCS({log: {seq, hash}, keys}))`, where `log` is the head of
+ * their device log and `keys` the hashes of the current devices' keys statements, ordered by device.
+ */
+export declare function mapValue(value: MapValue): Hash;
+/** The value an erased person's leaf holds: `SHA-256(UTF-8("messaging/1/tombstone"))`. */
+export declare const TOMBSTONE: Hash;
+/**
+ * The map, in memory. `set` costs about 256 hashes plus the branches above the person; `prove` reads siblings
+ * from the trie. A person never leaves the map: an erased person's value becomes `TOMBSTONE`.
+ */
+export declare class SparseMerkleTree {
+    #private;
+    /**
+     * A map of these persons and values, built at once: each leaf's path is hashed once. This is the way to load
+     * a large map (about 2.4 million hashes for 10,000 persons). A person given twice keeps the last value.
+     */
+    static from(entries: Iterable<readonly [person: string, value: Hash]>): SparseMerkleTree;
+    get size(): number;
+    root(): Hash;
+    get(person: string): Hash | undefined;
+    /** Sets a person's value (from `mapValue`, or `TOMBSTONE`). */
+    set(person: string, value: Hash): void;
+    /**
+     * The map as it is now, for `root` and `prove` only: a later `set` on this tree does not change it. Cheap: the trie
+     * is persistent, so the snapshot shares every node.
+     */
+    snapshot(): SparseMerkleTree;
+    /**
+     * A tree that starts as this one and changes on its own: a `set` on either leaves the other as it was. The trie is
+     * shared (it is persistent); only the person index is copied. A directory prepares an epoch on a copy and adopts it
+     * once the epoch is stored.
+     */
+    copy(): SparseMerkleTree;
+    /** The proof for `person`, present or absent, against `root()`. */
+    prove(person: string): MapProof;
+}
+/**
+ * The root that `proof` gives for `person` holding `value` (undefined: no leaf, an absent person). Throws
+ * `invalid_request` for a malformed proof: a bitmap that is not 32 bytes, a sibling count that differs from
+ * the bitmap's, or a sibling equal to the empty hash of its height (a proof names only non-empty siblings).
+ */
+export declare function mapRootFromProof(person: string, value: Hash | undefined, proof: MapProof): Hash;
+/** True when `proof` shows `person` holding `value` (undefined: absent) in the map with root `root`. Never throws. */
+export declare function verifyMapProof(root: Hash, person: string, value: Hash | undefined, proof: MapProof): boolean;

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

@@ -0,0 +1,68 @@
+import type { Identity } from "./identity.js";
+import type { RealmView } from "./realm.js";
+import { type EncKey, type MachineId, Ulid } from "./schema/common.js";
+import { Envelope, type EnvelopeClass, EnvelopeType, type PayloadByType, type Recipient, type Sender } from "./schema/envelope.js";
+import type { Anchor, RealmId } from "./schema/realm.js";
+import type { Member } from "./schema/roster.js";
+export interface SealArgs<T extends EnvelopeType = EnvelopeType> {
+    identity: Identity;
+    realm: RealmId;
+    type: T;
+    from: Sender;
+    to: Recipient;
+    /** The recipient device's X25519 key. Required for every type except presence. */
+    recipientEnc?: EncKey;
+    /** The sender's current view of the realm (spec §5); the receiver catches up to it or reports a divergence. */
+    anchor: Anchor;
+    payload: PayloadByType[T];
+    replyTo?: Ulid;
+    /** Default and maximum `LIMITS.ttlMs`. */
+    ttlMs?: number;
+    now?: number;
+    id?: Ulid;
+}
+/** Fixed sealing randomness: the ephemeral X25519 private key (32 raw bytes) and the 12-byte nonce. */
+export interface SealRandomness {
+    ephemeral: Uint8Array;
+    nonce: Uint8Array;
+}
+export interface VerifyContext {
+    /** The locally verified realm: a `Roster` for a roster realm. */
+    realm: RealmView;
+    /** This device. When given, every envelope except presence must be addressed to it and to its person in `realm`. */
+    self?: MachineId;
+    now: number;
+}
+/** Builds, seals (spec §5) and signs an envelope. Presence is signed but not sealed. */
+export declare function sealEnvelope<T extends EnvelopeType>(args: SealArgs<T>): Envelope;
+/**
+ * `sealEnvelope` with caller-chosen ephemeral key and nonce, for test vectors and tests only; exported from
+ * `@messaging/core/testing`. Reusing an ephemeral key and nonce for real traffic breaks confidentiality.
+ */
+export declare function sealEnvelopeWith<T extends EnvelopeType>(args: SealArgs<T>, randomness: SealRandomness): Envelope;
+/**
+ * Seals arbitrary `plaintext` bytes as the body of a sealed type, with a valid header and signature but no
+ * payload validation or canonicalization, so tests can build envelopes a conforming sender never makes.
+ * Tests only; exported from `@messaging/core/testing`.
+ */
+export declare function sealPlaintext(args: Omit<SealArgs, "payload"> & {
+    class?: EnvelopeClass;
+}, plaintext: Uint8Array, randomness?: SealRandomness): Envelope;
+/**
+ * Receiver checks, spec §5 steps 1–6. Membership is checked against the locally verified realm and the
+ * signature over the raw JSON value, so unknown fields from newer peers stay covered. Returns the raw
+ * envelope; deduplication and recipient policy are the caller's. Throws only MessagingError.
+ */
+export declare function verifyEnvelope(raw: unknown, ctx: VerifyContext): {
+    env: Envelope;
+    sender: Member;
+};
+/**
+ * Decrypts (or, for presence, reads) the body and validates it against `PAYLOAD_BY_TYPE[type]`.
+ * A seal failure is `bad_signature`; an oversized body is `too_large`; a body that decrypts but is not
+ * UTF-8 I-JSON (`parseWire`, then `canonicalize`) or not a valid payload is `invalid_request`, so every
+ * payload returned canonicalizes. Throws only MessagingError, and never chains the plaintext as a cause.
+ */
+export declare function openEnvelope<T extends EnvelopeType>(env: Envelope & {
+    type: T;
+}, identity: Identity): PayloadByType[T];

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

@@ -0,0 +1,2 @@
+/** SHA-256, base64url. Strings are hashed as UTF-8. */
+export declare function sha256(data: string | Uint8Array): string;

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

@@ -0,0 +1,34 @@
+/**
+ * Roster head commitments (spec §5). Every envelope's anchor is the sender's roster head, so a
+ * receiver can tell whether the sender saw entries it has not (sync first), or a different chain (a
+ * divergence: the relay showed the two machines different branches).
+ */
+import type { AnchorRelation } from "./realm.js";
+import type { Roster } from "./roster.js";
+import { type MachineId, type PersonName, type Ulid } from "./schema/common.js";
+import type { RealmId, RosterAnchor } from "./schema/realm.js";
+import type { RosterHead } from "./schema/roster.js";
+/**
+ * How a head relates to a roster:
+ * - `ahead`: past the roster's head; the sender knows entries this roster does not;
+ * - `consistent`: an entry of this chain, its head or an earlier one (a peer may lag);
+ * - `diverged`: this chain has another entry at that seq, whose hash is `ours`.
+ */
+export type HeadRelation = AnchorRelation;
+export declare function headRelation(roster: Roster, head: RosterHead): HeadRelation;
+/** The anchor a roster realm's envelopes carry: the roster's head (spec §5). */
+export declare function rosterAnchor(roster: Roster): RosterAnchor;
+/** The head an envelope commits to, with the machine whose signature covers it. */
+export interface SignedHead {
+    head: RosterHead;
+    machine: MachineId;
+    person: PersonName;
+    id: Ulid;
+}
+/**
+ * The roster head `raw` commits to, if `raw` is an envelope of `realm` (schema) whose signature over the
+ * raw JSON verifies under `from.device`. Membership and the time window are not checked: a receiver
+ * uses this to bring its roster up to the head before it checks membership (a new joiner is not in a
+ * stale roster), and to check stored evidence. Never throws; anything else is undefined.
+ */
+export declare function signedHead(raw: unknown, realm: RealmId): SignedHead | undefined;

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

@@ -0,0 +1,35 @@
+import { type KeyObject } from "node:crypto";
+import { z } from "zod";
+import { EncKey, MachineId } from "./schema/common.js";
+/** `$MESSAGING_HOME/identity.json`. `signingKey` and `encKey` are the private JWK `d` values. */
+export declare const IdentityFile: z.ZodObject<{
+    v: z.ZodLiteral<"messaging/1">;
+    machine: z.ZodString;
+    enc: z.ZodString;
+    signingKey: z.ZodString;
+    encKey: z.ZodString;
+}, z.core.$strip>;
+export type IdentityFile = z.infer<typeof IdentityFile>;
+/**
+ * A machine identity: an Ed25519 signing key and an X25519 encryption key. The public ids are
+ * derived from the private keys, so they always match. The private keys are held in private
+ * fields and never appear in `JSON.stringify`, `String()` or `util.inspect` output.
+ */
+export declare class Identity {
+    #private;
+    readonly machine: MachineId;
+    readonly enc: EncKey;
+    constructor(signingKey: KeyObject, encKey: KeyObject);
+    get signingKey(): KeyObject;
+    get encKey(): KeyObject;
+    toJSON(): {
+        machine: MachineId;
+        enc: EncKey;
+    };
+    toString(): string;
+}
+export declare function generateIdentity(): Identity;
+/** The identity file contents. This is the only API that returns private key material. */
+export declare function exportIdentity(identity: Identity): IdentityFile;
+/** Validates an identity file and checks that its public keys belong to its private keys. */
+export declare function importIdentity(file: unknown): Identity;

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

@@ -0,0 +1,38 @@
+export * from "./schema/index.js";
+export { b64u } from "./b64u.js";
+export { VERSION } from "./version.js";
+export { canonicalize } from "./jcs.js";
+export { parseWire } from "./wire.js";
+export { sha256 } from "./hash.js";
+export { ulid } from "./ulid.js";
+export { Identity, IdentityFile, generateIdentity, exportIdentity, importIdentity } from "./identity.js";
+export { sign, verify } from "./sign.js";
+export { sealEnvelope, verifyEnvelope, openEnvelope, type SealArgs, type VerifyContext } from "./envelope.js";
+export { type AnchorRelation, type RealmView } from "./realm.js";
+export { headRelation, rosterAnchor, signedHead, type HeadRelation, type SignedHead } from "./head.js";
+export { Roster, entryHash, createGenesis, createEntry, createInvite, decodeTicket, createRedeem, relayAuthPayload, inviteJoinPayload, inviteJoinProof, type ApplyOptions, type RosterBody, type InviteState, } from "./roster.js";
+export { ACT_GRANT_MAX_S, ACTION_CLASSES, HOST_GRANT_MAX_S, JELLY_HOST_SKEW_S, SESSION_TICKET_MAX_S, actionClass, grantInput, parseActKey, readWakeTicket, verifyActGrant, verifySessionTicket, type ActGrant, type ActGrantCheck, type ActionClass, type WakeTicketClaims, type SessionTicket, } from "./jelly-host.js";
+export { personId } from "./directory/person.js";
+export { DirectoryRealmConfig, directoryRealmId } from "./directory/realm.js";
+export { emailOrg, hostedHandle } from "./directory/handle.js";
+export { JELLY_HISTORY_TTL_MS, JELLY_IAT_LEEWAY_S, JELLY_JWKS_TTL_MS, JELLY_MAX_LIFETIME_S, JELLY_REFETCH_MIN_MS, JELLY_REVOCATION_CHECK_MS, JellyKeyring, cnfJwk, decodeJellyToken, isBindableKey, jellyKeyCovers, jellyMintRefusal, verifyJellyToken, type JellyKey, type JellyKeySources, type JellyMintRefusal, type JellyToken, type JellyVerifyOptions, } from "./directory/jelly-token.js";
+export { DeviceLog, logEntryHash, signLogEntry, type AppendOptions, type DeviceLogContext, type DeviceRecord, type JellyProfile, type UnsignedLogEntry, type Vouch, } from "./directory/device-log.js";
+export { DEVICE_GRANT_TYPE, JELLY_ANSWER_BYTES, LOGIN_INTERVAL_MAX_S, LOGIN_SLOW_DOWN_S, deviceCodeForm, devicePollForm, jellyKeyFingerprint, jellyKeyThumbprint, readDeviceCodeAnswer, readDevicePoll, readDeviceSignIn, type DeviceCodeAnswer, type DevicePoll, type DeviceSignIn, } from "./directory/jelly-device.js";
+export { LINK_PREFIX, createLinkRequest, decodeLink, encodeLink, linkSas, verifyLinkRequest, verifyLinkSignature, type LinkArgs } from "./directory/link.js";
+export { createKeysStatement, keysStatementHash, verifyKeysStatement } from "./directory/keys-statement.js";
+export { adoptSth, epochAnchor, epochLeafHash, signKeyRotation, signSth, verifyEpochProof, verifySthSignature, type AdoptArgs, type AdoptedHead, } from "./directory/epoch.js";
+export { checkPersonSuccession, DirectoryInconsistency, verifyPersonHead, verifyPersonView, type DirectoryEvidence, type PersonState, type PersonViewContext, type VerifiedHead, } from "./directory/person-view.js";
+export { MerkleLog, merkleLeafHash, verifyConsistency, verifyInclusion } from "./directory/merkle-log.js";
+export { MAP_DEPTH, SparseMerkleTree, TOMBSTONE, emptyMapHash, mapKey, mapRootFromProof, mapValue, verifyMapProof } from "./directory/smt.js";
+export { parseAddress, formatAddress, type ParsedAddress } from "./address.js";
+export { decodeAdmitCard, decodeTeamCard, encodeAdmitCard, encodeTeamCard, type AdmitCard, type TeamCard, } from "./cards.js";
+export { decide, effectivePolicy, grantSubjectKey, levelsOf, preferGrant, resignGrant, restrictingLevels, signConsentGrant, verifyConsentGrant, wideningLevels, type ConsentClass, type ConsentDecision, type ConsentGrantArgs, type DecideArgs, type EffectivePolicy, type Inbound, type Relation, } from "./consent.js";
+export { cardCan, signContactCard, verifyContactCard, type ContactCardArgs } from "./contact-card.js";
+export { createGrant, verifyChain, type GrantArgs, type ChainHop, type ChainContext, type VerifiedChain } from "./delegation.js";
+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 { 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";

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

@@ -0,0 +1,12 @@
+/**
+ * RFC 8785 JSON Canonicalization Scheme over the I-JSON subset Messaging signs.
+ * Object members whose value is `undefined` are dropped. Throws `invalid_request` for anything
+ * that is not I-JSON: NaN, ±Infinity, integers beyond ±(2^53 − 1), bigint, functions, symbols,
+ * `undefined` array elements or top-level values, lone surrogates, cycles, and non-plain objects.
+ * It also throws `invalid_request` for arrays and objects nested deeper than `LIMITS.jsonDepth`.
+ *
+ * The cost is linear in the size of the value, and the result never depends on the call stack: each
+ * node is visited once with O(1) bookkeeping, recursion stops at `LIMITS.jsonDepth`, and a cycle is
+ * caught by that same limit (sorting member names is the only superlinear step).
+ */
+export declare function canonicalize(value: unknown): string;

package/dist/types/core/jelly-host-double.d.ts

@@ -0,0 +1,21 @@
+import { type ActKeyJwk } from "./schema/jelly.js";
+export interface JellyHostDouble {
+    /** The public action key, as the host writes it for `--act-key`. */
+    readonly key: ActKeyJwk;
+    /** `key` as file text. */
+    readonly keyText: string;
+    /**
+     * A method grant for one call: `act` = `method`, `in` = the params' digest, `cls` = the method's class
+     * (`actionClass`), 60 s. A claim set to `undefined` in `claims` is left out.
+     */
+    act(method: string, params?: unknown, claims?: Record<string, unknown>, header?: Record<string, unknown>): string;
+    /** A host-scope grant: `act: "host"`, ten minutes. */
+    host(claims?: Record<string, unknown>): string;
+    /** A session ticket for agent `agt` and session `name`: seven days. */
+    ticket(agt: string, name: string, claims?: Record<string, unknown>, header?: Record<string, unknown>): string;
+}
+/** A host double with a fresh action key, signing at `now()` (milliseconds; default the wall clock). */
+export declare function jellyHostDouble(options?: {
+    now?: () => number;
+    kid?: string;
+}): JellyHostDouble;