@joe-broadhead/messaging 0.0.0-stage → 0.7.1

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

@@ -0,0 +1,71 @@
+import type { Identity } from "./identity.js";
+import type { RealmView } from "./realm.js";
+import { type Hash, type MachineId, type SessionAddress, type Ulid } from "./schema/common.js";
+import type { RealmId } from "./schema/realm.js";
+import { DelegationGrant, type DelegationSummary } from "./schema/delegation.js";
+/** SHA-256 of the JCS form of the full grant, including `sig`: the next grant's `parent`. */
+export declare function grantHash(grant: DelegationGrant): Hash;
+export interface GrantArgs {
+    realm: RealmId;
+    task: Ulid;
+    /** The delegating session, on the signing machine. */
+    from: SessionAddress;
+    to: SessionAddress;
+    /** The grant this one extends: the last grant of the chain. Absent for a root. */
+    parent?: DelegationGrant;
+    /** Default: the parent's scope, or unrestricted for a root. Never wider than the parent's (`forbidden`). */
+    scope?: readonly string[];
+    /** Default: the parent's maxDepth, or `LIMITS.delegationDepth` for a root. Never above the parent's (`forbidden`). */
+    maxDepth?: number;
+    /** Default and maximum `LIMITS.ttlMs`. A grant never outlives its parent. */
+    ttlMs?: number;
+    now?: number;
+}
+/**
+ * Signs one grant with the machine key (spec §6.7): a root, or the next hop after `parent`. The new grant
+ * may narrow the parent's scope and maxDepth, never widen them, and expires no later than the parent.
+ * It does not check the chain as a whole; run `verifyChain` on the extended chain for that.
+ * Throws only MessagingError: `invalid_request` for bad arguments, `forbidden` for a widening, `expired`
+ * for a parent that has expired.
+ */
+export declare function createGrant(identity: Identity, args: GrantArgs): DelegationGrant;
+/** The hop a chain arrived on: the envelope that carried it and the task it requests. */
+export interface ChainHop {
+    /** The envelope's `from.device`. */
+    by: MachineId;
+    /** The sender's address, `person/session@label`. */
+    from: SessionAddress;
+    /** The addressed session on this machine. */
+    to: SessionAddress;
+    /** The task id of the request. */
+    task: Ulid;
+}
+export interface ChainContext {
+    /** The locally verified realm: a `Roster` for a roster realm. */
+    realm: RealmView;
+    now: number;
+    hop: ChainHop;
+}
+export interface VerifiedChain {
+    /** The raw grants, unknown fields included: store them to extend the chain later. */
+    grants: DelegationGrant[];
+    summary: DelegationSummary;
+}
+/**
+ * Verifies a delegation chain for the hop it arrived on (spec §6.7), against the locally verified realm.
+ * Checks, in order, stopping at the first failure:
+ *
+ * 1. schema, I-JSON and 1…`LIMITS.delegationDepth` grants (`invalid_request`); JCS within
+ *    `LIMITS.delegationBytes` (`too_large`);
+ * 2. for each grant, root first: this realm (`invalid_request`); the time window, as for envelopes
+ *    (`expired`); `by` a current member whose person and label `from` names (`not_member`); the
+ *    signature over the raw grant (`bad_signature`); linkage, no `parent` on the root and `from = previous.to`,
+ *    `parent = grantHash(previous)` after it (`invalid_request`); narrowing of scope, maxDepth and exp
+ *    (`forbidden`);
+ * 3. at most the smallest maxDepth grants (`forbidden`);
+ * 4. no session twice (`forbidden`);
+ * 5. the last grant is for this hop (`forbidden`).
+ *
+ * Throws only MessagingError, and never quotes the chain.
+ */
+export declare function verifyChain(raw: unknown, ctx: ChainContext): VerifiedChain;

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

@@ -0,0 +1,119 @@
+/**
+ * A hosted person's device log (spec §15.3): an append-only, hash-chained list of signed entries that binds,
+ * attests and unbinds the person's devices. `DeviceLog` replays and extends it, enforcing every authority rule;
+ * the directory and every client run the same checks. Binding freshness against the epoch log (an entry's
+ * first epoch) is `verifyPersonView`'s, which knows the epochs.
+ */
+import type { KeyObject } from "node:crypto";
+import { Identity } from "../identity.js";
+import { type Hash, type HostedPersonId } from "../schema/common.js";
+import { LogEntry, type DeviceId, type DeviceKind, type UnbindReason } from "../schema/directory.js";
+import type { RealmId } from "../schema/realm.js";
+import { type JellyKey, type JellyToken } from "./jelly-token.js";
+/** How strongly a device is vouched for: by Jelly ID, or by approval from a Jelly-vouched device. */
+export type Vouch = "jelly" | "device";
+/** A device as its person's log has it. */
+export interface DeviceRecord {
+    readonly device: DeviceId;
+    readonly label: string;
+    readonly kind: DeviceKind;
+    readonly vouch: Vouch;
+    /** The `ts` of its `bind`. */
+    readonly since: number;
+    /** The approver of a device bound by link. */
+    readonly approver?: DeviceId | undefined;
+    /** The Jelly host id of its latest Jelly token, for a Jelly-vouched device. */
+    readonly host?: string | undefined;
+    /** False once unbound. */
+    readonly current: boolean;
+    readonly unbound?: {
+        readonly ts: number;
+        readonly reason: UnbindReason;
+        readonly by: string;
+    } | undefined;
+}
+/** The person's profile, from the newest Jelly token of the log (spec §15.3): Jelly-signed claims. */
+export interface JellyProfile {
+    readonly iss: string;
+    readonly sub: string;
+    readonly name?: string | undefined;
+    /** Only when Jelly ID proved it (`email_verified`). */
+    readonly email?: string | undefined;
+    /** The `ts` of the entry that carried it. */
+    readonly at: number;
+}
+export interface DeviceLogContext {
+    readonly realm: RealmId;
+    readonly person: HostedPersonId;
+    /** The realm's Jelly issuer and resource, and the keys `JellyKeyring.prepare` found for the log's tokens. */
+    readonly jelly: {
+        readonly issuer: string;
+        readonly audience: string;
+        readonly key: (kid: string) => JellyKey | undefined;
+    };
+    /** The directory's epoch keys, current and past: the only signers of a `service` unbind. */
+    readonly directoryKeys: readonly string[];
+}
+export interface AppendOptions {
+    /** The directory's clock when it accepts an append: `ts` must be within the clock skew of it (`expired`). */
+    readonly now?: number | undefined;
+}
+/** `SHA-256(JCS(entry))`, the signature included. */
+export declare function logEntryHash(entry: LogEntry): Hash;
+/** A log entry without its signer and signature, as a caller builds it. */
+export type UnsignedLogEntry = Omit<LogEntry, "by" | "sig">;
+/**
+ * Signs an entry: `by` becomes the signer's public key, `sig` its signature over JCS(entry without sig). A
+ * device signs with its `Identity`; the directory signs the unbinds of an erased account with its epoch key.
+ * Throws `invalid_request`.
+ */
+export declare function signLogEntry(signer: Identity | KeyObject, entry: UnsignedLogEntry): LogEntry;
+/**
+ * One person's device log, verified entry by entry from `seq` 0. A failed `append` changes nothing. Errors:
+ * `invalid_request` (schema, size), `log_conflict` (not on the head), `device_limit` (an eleventh device),
+ * `expired` (with `now`), and `binding_invalid` for every other rule and signature.
+ */
+export declare class DeviceLog {
+    #private;
+    readonly realm: RealmId;
+    readonly person: HostedPersonId;
+    constructor(realm: RealmId, person: HostedPersonId);
+    /** A copy that appends independently of this log. Entries are not re-verified. */
+    clone(): DeviceLog;
+    /** Replays `entries` from `seq` 0. */
+    static fromEntries(entries: readonly unknown[], context: DeviceLogContext): DeviceLog;
+    get length(): number;
+    /** The head `{seq, hash}`, or undefined for an empty log. */
+    head(): {
+        seq: number;
+        hash: Hash;
+    } | undefined;
+    /** The hash of entry `seq`. */
+    hashAt(seq: number): Hash | undefined;
+    entries(): readonly LogEntry[];
+    /** Every device the log has bound, current or not. */
+    allDevices(): DeviceRecord[];
+    /** The current devices. */
+    devices(): DeviceRecord[];
+    device(device: DeviceId): DeviceRecord | undefined;
+    /** The device that replaced `device` (an `unbind` with reason `replaced`), if it did and is current (spec §15.3). */
+    successor(device: DeviceId): DeviceId | undefined;
+    /** The profile from the newest Jelly token in the log. */
+    profile(): JellyProfile | undefined;
+    /** The verified Jelly token of entry `seq`, for an entry with a `jelly` authority. */
+    token(seq: number): JellyToken | undefined;
+    /**
+     * A `bind` or `attest` of this log carried a sign-in's token (`src: "device"`) with this `jti`: that token
+     * vouched for its one act and vouches for nothing else (spec §15.3), an erasure included.
+     */
+    spentSignIn(jti: string): boolean;
+    /**
+     * The latest time at which entry `seq` may first appear in an epoch: its Jelly token's `exp` plus the clock
+     * skew, in ms. Undefined for an entry with no `jelly` authority.
+     */
+    bindingDeadline(seq: number): number | undefined;
+    /** Checks `entry` as the next entry and appends it. */
+    append(entry: unknown, context: DeviceLogContext, options?: AppendOptions): LogEntry;
+    /** Checks `entry` as the next entry without appending it. */
+    check(entry: unknown, context: DeviceLogContext, options?: AppendOptions): LogEntry;
+}

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

@@ -0,0 +1,53 @@
+/**
+ * The epoch log's signed tree heads (spec §15.6): signing and verifying STHs and epoch-key rotations, proving
+ * an epoch leaf into an STH, and the checks a client makes before it adopts a newer STH (§15.6, "Adopting").
+ */
+import type { KeyObject } from "node:crypto";
+import { type Hash } from "../schema/common.js";
+import { EpochLeaf, EpochProof, KeyRotation, STH } from "../schema/directory.js";
+import type { EpochAnchor, RealmId } from "../schema/realm.js";
+/** The RFC 9162 leaf hash of an epoch leaf: `SHA-256(0x00 ‖ UTF-8(JCS(leaf)))`. */
+export declare function epochLeafHash(leaf: EpochLeaf): Hash;
+/** An STH signed with the directory's epoch key. Throws `invalid_request`. */
+export declare function signSth(key: KeyObject, head: {
+    realm: RealmId;
+    size: number;
+    root: Hash;
+    ts: number;
+}): STH;
+/** True when `sth` is signed by `key`. Never throws. */
+export declare function verifySthSignature(sth: STH, key: string): boolean;
+/** The anchor an envelope carries for this STH. */
+export declare function epochAnchor(sth: STH): EpochAnchor;
+/** A rotation of the epoch key from `oldKey` to `newKey`, signed by both, from `fromSize` on. Throws `invalid_request`. */
+export declare function signKeyRotation(oldKey: KeyObject, newKey: KeyObject, args: {
+    realm: RealmId;
+    fromSize: number;
+}): KeyRotation;
+/**
+ * Checks that `proof` puts its leaf at its index in the tree of `sth` (the leaf's `epoch` is its index). Throws
+ * `invalid_request` for a malformed proof and `directory_inconsistent` when it does not prove the leaf.
+ */
+export declare function verifyEpochProof(sth: STH, proof: unknown): EpochProof;
+/** What a client holds of the epoch log: the STH it adopted and the epoch key it trusts. */
+export interface AdoptedHead {
+    readonly sth: STH;
+    readonly key: string;
+}
+export interface AdoptArgs {
+    readonly realm: RealmId;
+    /** The STH to adopt. */
+    readonly next: unknown;
+    /** RFC 9162 consistency proof from the adopted STH's size to `next`'s. */
+    readonly consistency?: readonly Hash[] | undefined;
+    /** Rotation statements from the trusted key to the key that signed `next`, oldest first. */
+    readonly rotations?: readonly unknown[] | undefined;
+}
+/**
+ * The checks before a client adopts a newer STH (spec §15.6): the schema (`invalid_request`); the realm; the
+ * signature by the trusted key, or by a key that rotation statements reach from it; `size` and `ts` not below
+ * the adopted STH's; and the consistency proof from the adopted STH (equal sizes: equal roots). Every other
+ * failure is `directory_inconsistent`. `current` is undefined for the first STH, which only the pinned key
+ * (`pinnedKey`) may sign, or a key its rotations reach.
+ */
+export declare function adoptSth(current: AdoptedHead | undefined, pinnedKey: string, args: AdoptArgs): AdoptedHead;

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

@@ -0,0 +1,11 @@
+/**
+ * Lower-case the local part, map every run of characters outside `[a-z0-9]` to `-`, trim `-`, and, when the
+ * result does not start with a letter, prefix `u-`; then cut to 32 characters and trim a trailing `-`. An empty
+ * result is `u`. The result always matches `[a-z][a-z0-9-]{0,31}`.
+ */
+export declare function hostedHandle(email: string): string;
+/**
+ * The org of a verified email until Jelly contract v1.2 (spec §15.10): `domain:<d>` when its domain `d` is one of
+ * the realm's `orgDomains`, otherwise none (an individual).
+ */
+export declare function emailOrg(email: string | undefined, orgDomains: readonly string[]): string | undefined;

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

@@ -0,0 +1,88 @@
+import type { MachineId } from "../schema/common.js";
+/** RFC 8628's device grant type. */
+export declare const DEVICE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
+/** RFC 8628 §3.5, v1.2 §12.3: `slow_down` adds 5 s to the interval. The interval is kept within [1, 60] s. */
+export declare const LOGIN_SLOW_DOWN_S = 5;
+export declare const LOGIN_INTERVAL_MAX_S = 60;
+/** The most bytes of an answer from Jelly ID that the daemon reads. */
+export declare const JELLY_ANSWER_BYTES = 65536;
+/**
+ * The key's fingerprint as Jelly ID's consent page shows it (v1.2 §12.2, item 3): the first six bytes of the RFC 7638
+ * thumbprint of `{kty: "OKP", crv: "Ed25519", x}` (SHA-256 over its members in that RFC's order), in lower-case hex,
+ * in three groups of four.
+ */
+export declare function jellyKeyFingerprint(device: MachineId): string;
+/** Where a device signs in, read from Jelly ID's metadata. */
+export interface DeviceSignIn {
+    /** `jelly_resource_device_authorization_endpoint`. */
+    readonly codeEndpoint: string;
+    /** `jelly_resource_device_token_endpoint`. */
+    readonly tokenEndpoint: string;
+    /** The resource's `name` in `jelly_resources`: the device client's `client_id`. */
+    readonly clientId: string;
+}
+/**
+ * Reads device sign-in from Jelly ID's RFC 8414 metadata (`<issuer>/.well-known/oauth-authorization-server`, as
+ * text). It needs the two members of v1.2 §12 (`jelly_resource_device_authorization_endpoint`, `…_token_endpoint`), both on the issuer's own origin, and the realm's resource in
+ * `jelly_resources`. It never takes RFC 8628's `device_authorization_endpoint`: at Jelly ID that route enrols hosts.
+ * Throws `login_unsupported` (Jelly ID lacks it) or `jelly_unavailable` (an answer that is not metadata for `issuer`).
+ */
+export declare function readDeviceSignIn(text: string, realm: {
+    readonly issuer: string;
+    readonly resource: string;
+}): DeviceSignIn;
+/** Where the person signs in and what they type there. Never a link with the code in it. */
+export interface DeviceCodeAnswer {
+    readonly deviceCode: string;
+    readonly userCode: string;
+    /** Jelly ID's `/link` page, where the person types `userCode`. */
+    readonly verificationUri: string;
+    readonly expiresInS: number;
+    readonly intervalS: number;
+}
+/**
+ * Reads Jelly ID's answer to the code request (v1.2 §12.1). Every refusal Jelly ID defines throws in the house style:
+ * - `429 slow_down` (too many codes from this address, or waiting for this client): `rate_limited`;
+ * - `400 invalid_target` with `detail: "invalid_cnf_jwk"` (Jelly would not bind this key): `binding_invalid`;
+ * - `400 invalid_target` (not this client's resource), `401 invalid_client` (not a device client, or device sign-in
+ *   off for it): `login_unsupported`;
+ * - `400 invalid_request` (a field missing, repeated or malformed): `invalid_request`;
+ * - `503 temporarily_unavailable`, and anything Jelly ID does not define: `jelly_unavailable`.
+ */
+export declare function readDeviceCodeAnswer(status: number, text: string, issuer: string): DeviceCodeAnswer;
+/** What a poll of the token route says (RFC 8628 §3.5; v1.2 §12.3). */
+export type DevicePoll = {
+    readonly kind: "token";
+    readonly token: string;
+} | {
+    readonly kind: "pending";
+} | {
+    readonly kind: "slow_down";
+}
+/** Jelly ID could not answer now (a 5xx, a timeout, an answer that is not one): keep polling until the code expires. */
+ | {
+    readonly kind: "retry";
+};
+/**
+ * Reads a poll's answer (v1.2 §12.3). `authorization_pending` and `slow_down` keep polling. A final refusal throws:
+ * `login_denied` (`access_denied`: the person denied it, or the account is disabled or being deleted), `expired`
+ * (`expired_token`: the code's time passed, decided or not; or `invalid_grant`: the code was used, or Jelly ID no
+ * longer knows it), `login_unsupported` (`invalid_client`, `unsupported_grant_type`). `503 temporarily_unavailable`,
+ * and any answer Jelly ID does not define, is `retry`: the daemon polls on until the code expires.
+ */
+export declare function readDevicePoll(status: number, text: string): DevicePoll;
+/** The form of the code request (v1.2 §12.1). */
+export declare function deviceCodeForm(args: {
+    clientId: string;
+    resource: string;
+    device: MachineId;
+    label: string;
+    kind: string;
+}): URLSearchParams;
+/** The form of a poll (v1.2 §12.3). */
+export declare function devicePollForm(args: {
+    clientId: string;
+    deviceCode: string;
+}): URLSearchParams;
+/** For tests of the fingerprint's preimage: the RFC 7638 thumbprint, base64url. */
+export declare function jellyKeyThumbprint(device: MachineId): string;

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

@@ -0,0 +1,8 @@
+/**
+ * A Jelly ID issuer double, for tests and the vectors only (exported from `@messaging/core/testing`): it signs a
+ * resource token as Jelly ID does (contract v1.1 §4). A JWS signs its own base64url text, not JCS, so this is
+ * Jelly's format and not a Messaging signature.
+ */
+import { type KeyObject } from "node:crypto";
+/** A compact JWS over `header` and `claims` as given (members in their insertion order), signed with `key`. */
+export declare function signJellyToken(key: KeyObject, header: Record<string, unknown>, claims: Record<string, unknown>): string;

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 {};