@joe-broadhead/messaging 0.0.0-stage → 0.7.0

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/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;