@joe-broadhead/messaging 0.0.0-stage → 0.7.0

package/dist/lib/modules/core/directory/device-log.js

@@ -0,0 +1,258 @@
+import { asMessagingError, parseWith } from "../check.js";
+import { Identity } from "../identity.js";
+import { canonicalize } from "../jcs.js";
+import { sha256 } from "../hash.js";
+import { rawPublicKey } from "../keys.js";
+import { signWith, verify } from "../sign.js";
+import { DOMAIN, LIMITS } from "../schema/common.js";
+import { JELLY_DEVICE_SOURCE } from "../schema/jelly.js";
+import { LogEntry } from "../schema/directory.js";
+import { MessagingError } from "../schema/errors.js";
+import { verifyJellyToken } from "./jelly-token.js";
+import { verifyLinkSignature } from "./link.js";
+import { personId } from "./person.js";
+/** `SHA-256(JCS(entry))`, the signature included. */
+export function logEntryHash(entry) {
+    return sha256(canonicalize(entry));
+}
+/**
+ * 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 function signLogEntry(signer, entry) {
+    const key = signer instanceof Identity ? signer.signingKey : signer;
+    const unsigned = { ...entry, by: rawPublicKey(key) };
+    return parseWith(LogEntry, { ...unsigned, sig: signWith(key, DOMAIN.deviceLog, unsigned) }, "log entry");
+}
+const refuse = (what) => new MessagingError("binding_invalid", what);
+/**
+ * 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 class DeviceLog {
+    realm;
+    person;
+    #state = { entries: [], hashes: [], devices: new Map(), tokens: new Map(), profile: undefined };
+    constructor(realm, person) {
+        this.realm = realm;
+        this.person = person;
+    }
+    /** A copy that appends independently of this log. Entries are not re-verified. */
+    clone() {
+        const copy = new DeviceLog(this.realm, this.person);
+        copy.#state = this.#state;
+        return copy;
+    }
+    /** Replays `entries` from `seq` 0. */
+    static fromEntries(entries, context) {
+        const log = new DeviceLog(context.realm, context.person);
+        for (const entry of entries)
+            log.append(entry, context);
+        return log;
+    }
+    get length() {
+        return this.#state.entries.length;
+    }
+    /** The head `{seq, hash}`, or undefined for an empty log. */
+    head() {
+        const seq = this.#state.entries.length - 1;
+        return seq < 0 ? undefined : { seq, hash: this.#state.hashes[seq] };
+    }
+    /** The hash of entry `seq`. */
+    hashAt(seq) {
+        return this.#state.hashes[seq];
+    }
+    entries() {
+        return this.#state.entries;
+    }
+    /** Every device the log has bound, current or not. */
+    allDevices() {
+        return [...this.#state.devices.values()];
+    }
+    /** The current devices. */
+    devices() {
+        return this.allDevices().filter((device) => device.current);
+    }
+    device(device) {
+        return this.#state.devices.get(device);
+    }
+    /** The device that replaced `device` (an `unbind` with reason `replaced`), if it did and is current (spec §15.3). */
+    successor(device) {
+        const record = this.#state.devices.get(device);
+        if (record?.unbound?.reason !== "replaced")
+            return undefined;
+        return this.#state.devices.get(record.unbound.by)?.current ? record.unbound.by : undefined;
+    }
+    /** The profile from the newest Jelly token in the log. */
+    profile() {
+        return this.#state.profile;
+    }
+    /** The verified Jelly token of entry `seq`, for an entry with a `jelly` authority. */
+    token(seq) {
+        return this.#state.tokens.get(seq);
+    }
+    /**
+     * 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) {
+        for (const [seq, token] of this.#state.tokens) {
+            if (token.claims.src === JELLY_DEVICE_SOURCE && token.claims.jti === jti && this.#state.entries[seq].op !== "unbind")
+                return true;
+        }
+        return false;
+    }
+    /**
+     * 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) {
+        const token = this.#state.tokens.get(seq);
+        return token === undefined ? undefined : token.claims.exp * 1000 + LIMITS.clockSkewMs;
+    }
+    /** Checks `entry` as the next entry and appends it. */
+    append(entry, context, options = {}) {
+        try {
+            const { parsed, next } = this.#check(entry, context, options);
+            this.#state = next;
+            return parsed;
+        }
+        catch (error) {
+            throw asMessagingError(error, "log entry");
+        }
+    }
+    /** Checks `entry` as the next entry without appending it. */
+    check(entry, context, options = {}) {
+        try {
+            return this.#check(entry, context, options).parsed;
+        }
+        catch (error) {
+            throw asMessagingError(error, "log entry");
+        }
+    }
+    #check(entry, context, options) {
+        const parsed = parseWith(LogEntry, entry, "log entry");
+        if (Buffer.byteLength(canonicalize(parsed), "utf8") > LIMITS.logEntryBytes)
+            throw new MessagingError("too_large", "log entry is over its size limit");
+        if (context.realm !== this.realm || context.person !== this.person)
+            throw new MessagingError("invalid_request", "log context is for another log");
+        const state = this.#state;
+        const head = this.head();
+        if (parsed.seq !== state.entries.length || parsed.prev !== (head?.hash ?? null))
+            throw new MessagingError("log_conflict", "log entry does not extend the head");
+        if (parsed.realm !== this.realm)
+            throw refuse("log entry is for another realm");
+        if (parsed.person !== this.person)
+            throw refuse("log entry is for another person");
+        const last = state.entries[state.entries.length - 1];
+        if (last && parsed.ts < last.ts - LIMITS.clockSkewMs)
+            throw refuse("log entry is dated before the one it follows");
+        if (options.now !== undefined && Math.abs(parsed.ts - options.now) > LIMITS.clockSkewMs)
+            throw new MessagingError("expired", "log entry ts is outside the clock skew");
+        const { sig, ...unsigned } = parsed;
+        if (!verify(parsed.by, DOMAIN.deviceLog, unsigned, sig))
+            throw refuse("log entry signature does not verify");
+        const devices = new Map(state.devices);
+        const tokens = new Map(state.tokens);
+        let profile = state.profile;
+        const jelly = (bound) => {
+            if (parsed.authority.kind !== "jelly")
+                throw refuse("this entry needs a jelly authority");
+            const token = verifyJellyToken(parsed.authority.token, { ...context.jelly, cnf: bound });
+            const { claims } = token;
+            if (personId(claims.iss, claims.sub) !== this.person)
+                throw refuse("Jelly token names another person");
+            // A sign-in through the browser vouches for one act (spec §15.3): the token that bound or attested a device
+            // vouches for nothing else, so one phished code removes no device. Unbinds may share one sign-in.
+            if (claims.src === JELLY_DEVICE_SOURCE) {
+                for (const [seq, used] of state.tokens) {
+                    if (used.claims.src !== JELLY_DEVICE_SOURCE || used.claims.jti !== claims.jti)
+                        continue;
+                    if (parsed.op !== "unbind" || state.entries[seq].op !== "unbind")
+                        throw refuse("a sign-in's token vouches for one act: this one was used");
+                }
+            }
+            // Freshness at the append (spec §15.3): the entry is dated within the token's life.
+            if (parsed.ts < claims.iat * 1000 - LIMITS.clockSkewMs || parsed.ts > claims.exp * 1000 + LIMITS.clockSkewMs)
+                throw refuse("log entry is dated outside its Jelly token's life");
+            tokens.set(parsed.seq, token);
+            profile = { iss: claims.iss, sub: claims.sub, name: claims.name, email: claims.email, at: parsed.ts };
+            return token;
+        };
+        const current = (device) => {
+            const record = devices.get(device);
+            return record?.current ? record : undefined;
+        };
+        if (parsed.op === "bind") {
+            if (devices.has(parsed.device))
+                throw refuse("a device is bound to a person at most once");
+            if ([...devices.values()].filter((d) => d.current).length >= LIMITS.devicesPerPerson)
+                throw new MessagingError("device_limit", "the person has the most current devices allowed");
+            const base = { device: parsed.device, label: parsed.label, kind: parsed.kind, since: parsed.ts, current: true };
+            if (parsed.authority.kind === "jelly") {
+                if (parsed.by !== parsed.device)
+                    throw refuse("a Jelly bind is signed by the device it binds");
+                const token = jelly(parsed.device);
+                devices.set(parsed.device, { ...base, vouch: "jelly", host: token.claims.hst });
+            }
+            else if (parsed.authority.kind === "device") {
+                if (state.entries.length === 0)
+                    throw refuse("a person's first device is vouched by Jelly ID");
+                const { approver, link } = parsed.authority;
+                if (parsed.by !== approver)
+                    throw refuse("a link approval is signed by its approver");
+                if (current(approver)?.vouch !== "jelly")
+                    throw refuse("only a current Jelly-vouched device approves a link");
+                if (!verifyLinkSignature(link))
+                    throw refuse("link request signature does not verify");
+                if (link.device !== parsed.device || link.realm !== parsed.realm)
+                    throw refuse("link request is for another device or realm");
+                if (link.label !== parsed.label || link.kind !== parsed.kind)
+                    throw refuse("the approval changes the link request's label or kind");
+                if (parsed.ts - link.ts > LIMITS.linkTtlMs || link.ts - parsed.ts > LIMITS.clockSkewMs)
+                    throw refuse("the approval is outside the link request's ten minutes");
+                devices.set(parsed.device, { ...base, vouch: "device", approver });
+            }
+            else {
+                throw refuse("a bind is vouched by Jelly ID or by a link approval");
+            }
+        }
+        else if (parsed.op === "attest") {
+            const record = current(parsed.device);
+            if (!record)
+                throw refuse("only a current device attests");
+            if (parsed.by !== parsed.device)
+                throw refuse("an attest is signed by its device");
+            const token = jelly(parsed.device);
+            devices.set(parsed.device, { ...record, vouch: "jelly", label: parsed.label ?? record.label, kind: parsed.kind ?? record.kind, host: token.claims.hst });
+        }
+        else {
+            const record = current(parsed.device);
+            if (!record)
+                throw refuse("only a current device is unbound");
+            const reason = parsed.reason;
+            if (reason === "self") {
+                if (parsed.authority.kind !== "self" || parsed.by !== parsed.device)
+                    throw refuse("a self unbind is signed by the device, with a self authority");
+            }
+            else if (reason === "account_deleted") {
+                if (parsed.authority.kind !== "service" || !context.directoryKeys.includes(parsed.by))
+                    throw refuse("only the directory unbinds an erased account");
+            }
+            else {
+                if (parsed.by === parsed.device)
+                    throw refuse("a device removes itself with reason self");
+                if (current(parsed.by)?.vouch !== "jelly")
+                    throw refuse("only a current Jelly-vouched device removes another");
+                jelly(parsed.by);
+            }
+            devices.set(parsed.device, { ...record, current: false, unbound: { ts: parsed.ts, reason, by: parsed.by } });
+        }
+        return {
+            parsed,
+            next: { entries: [...state.entries, parsed], hashes: [...state.hashes, logEntryHash(parsed)], devices, tokens, profile },
+        };
+    }
+}

package/dist/lib/modules/core/directory/epoch.js

@@ -0,0 +1,103 @@
+import { utf8 } from "../b64u.js";
+import { asMessagingError, parseWith } from "../check.js";
+import { canonicalize } from "../jcs.js";
+import { assertEd25519PublicKey, rawPublicKey } from "../keys.js";
+import { signWith, verify } from "../sign.js";
+import { DOMAIN, PROTOCOL } from "../schema/common.js";
+import { EpochLeaf, EpochProof, KeyRotation, STH } from "../schema/directory.js";
+import { MessagingError } from "../schema/errors.js";
+import { merkleLeafHash, verifyConsistency, verifyInclusion } from "./merkle-log.js";
+const inconsistent = (what) => new MessagingError("directory_inconsistent", what);
+/** The RFC 9162 leaf hash of an epoch leaf: `SHA-256(0x00 ‖ UTF-8(JCS(leaf)))`. */
+export function epochLeafHash(leaf) {
+    return merkleLeafHash(utf8(canonicalize(parseWith(EpochLeaf, leaf, "epoch leaf"))));
+}
+/** An STH signed with the directory's epoch key. Throws `invalid_request`. */
+export function signSth(key, head) {
+    const unsigned = { v: PROTOCOL, realm: head.realm, size: head.size, root: head.root, ts: head.ts };
+    return parseWith(STH, { ...unsigned, sig: signWith(key, DOMAIN.epoch, unsigned) }, "STH");
+}
+/** True when `sth` is signed by `key`. Never throws. */
+export function verifySthSignature(sth, key) {
+    try {
+        const { sig, ...unsigned } = sth;
+        return verify(key, DOMAIN.epoch, unsigned, sig);
+    }
+    catch {
+        return false;
+    }
+}
+/** The anchor an envelope carries for this STH. */
+export function epochAnchor(sth) {
+    return { kind: "epoch", size: sth.size, root: sth.root };
+}
+/** A rotation of the epoch key from `oldKey` to `newKey`, signed by both, from `fromSize` on. Throws `invalid_request`. */
+export function signKeyRotation(oldKey, newKey, args) {
+    const unsigned = { v: PROTOCOL, realm: args.realm, old: rawPublicKey(oldKey), new: rawPublicKey(newKey), fromSize: args.fromSize };
+    return parseWith(KeyRotation, { ...unsigned, sigOld: signWith(oldKey, DOMAIN.dirKey, unsigned), sigNew: signWith(newKey, DOMAIN.dirKey, unsigned) }, "key rotation");
+}
+/**
+ * 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 function verifyEpochProof(sth, proof) {
+    try {
+        const parsed = parseWith(EpochProof, proof, "epoch proof");
+        if (parsed.leaf.epoch !== parsed.index)
+            throw inconsistent("epoch leaf is not at its own index");
+        if (!verifyInclusion(parsed.index, sth.size, epochLeafHash(parsed.leaf), parsed.inclusion, sth.root))
+            throw inconsistent("epoch leaf is not in the tree head");
+        return parsed;
+    }
+    catch (error) {
+        throw asMessagingError(error, "epoch proof");
+    }
+}
+/**
+ * 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 function adoptSth(current, pinnedKey, args) {
+    try {
+        const next = parseWith(STH, args.next, "STH");
+        if (next.realm !== args.realm)
+            throw inconsistent("STH is for another realm");
+        let key = current?.key ?? pinnedKey;
+        let floor = current?.sth.size ?? 0;
+        for (const raw of args.rotations ?? []) {
+            const rotation = parseWith(KeyRotation, raw, "key rotation");
+            const { sigOld, sigNew, ...unsigned } = rotation;
+            // A directory sends its rotation with every STH the new key signs: one already applied is skipped.
+            if (rotation.new === key && rotation.old !== key)
+                continue;
+            if (rotation.realm !== args.realm || rotation.old !== key)
+                throw inconsistent("key rotation does not start from the trusted key");
+            assertEd25519PublicKey(rotation.new, "new epoch key");
+            if (!verify(rotation.old, DOMAIN.dirKey, unsigned, sigOld) || !verify(rotation.new, DOMAIN.dirKey, unsigned, sigNew))
+                throw inconsistent("key rotation signature does not verify");
+            // The old key signed every adopted STH, so the new one may only sign past them.
+            if (rotation.fromSize <= floor || rotation.fromSize > next.size)
+                throw inconsistent("key rotation size is not consistent with the adopted STH");
+            key = rotation.new;
+            floor = rotation.fromSize;
+        }
+        if (!verifySthSignature(next, key))
+            throw inconsistent("STH signature does not verify");
+        if (current) {
+            const { sth } = current;
+            if (next.size < sth.size)
+                throw inconsistent("STH is smaller than the adopted one");
+            if (next.ts < sth.ts)
+                throw inconsistent("STH is older than the adopted one");
+            if (!verifyConsistency(sth.size, next.size, args.consistency ?? [], sth.root, next.root))
+                throw inconsistent("STH is not consistent with the adopted one");
+        }
+        return { sth: next, key };
+    }
+    catch (error) {
+        throw asMessagingError(error, "STH");
+    }
+}

package/dist/lib/modules/core/directory/handle.js

@@ -0,0 +1,29 @@
+/**
+ * A hosted person's handle (spec §15.8; design §6.2): what a person types to address someone in their org, made
+ * from the local part of the verified email. The directory answers `dir.resolve {handle}` with it, and a client
+ * shows it; both compute it the same way. And the org a verified email puts a person in (spec §15.10).
+ */
+import { Email } from "../schema/directory-frames.js";
+/**
+ * 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 function hostedHandle(email) {
+    const at = email.lastIndexOf("@");
+    const local = (at < 0 ? email : email.slice(0, at)).toLowerCase();
+    let handle = local.replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+    if (!/^[a-z]/.test(handle))
+        handle = handle === "" ? "u" : `u-${handle}`;
+    return handle.slice(0, 32).replace(/-+$/, "");
+}
+/**
+ * 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 function emailOrg(email, orgDomains) {
+    if (email === undefined || !Email.safeParse(email.toLowerCase()).success)
+        return undefined;
+    const domain = email.toLowerCase().slice(email.lastIndexOf("@") + 1);
+    return orgDomains.includes(domain) ? `domain:${domain}` : undefined;
+}

package/dist/lib/modules/core/directory/jelly-device.js

@@ -0,0 +1,204 @@
+/**
+ * A device's sign-in through the browser at Jelly ID (Jelly's resource-token contract v1.2 §12, as built in
+ * hey-jelly `protocol/contracts/src/jelly-id-device-sign-in.ts`; spec §15.9, "Signing in through the browser"):
+ * reading Jelly ID's metadata for the two routes, the key fingerprint the consent page shows, and the reading of Jelly
+ * ID's answers. Pure: the daemon does the HTTP.
+ *
+ * Jelly ID never sends `verification_uri_complete` (v1.2 §12.1): a link with the code in it turns a phished code into
+ * one click, so the person types the code at `verification_uri`. An answer that carries one anyway is read without it:
+ * the field is never kept, shown or opened.
+ */
+import { createHash } from "node:crypto";
+import { b64u } from "../b64u.js";
+import { assertEd25519PublicKey } from "../keys.js";
+import { parseWire } from "../wire.js";
+import { MessagingError } from "../schema/errors.js";
+import { z } from "../../vendor/zod/index.js";
+/** RFC 8628's device grant type. */
+export 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 const LOGIN_SLOW_DOWN_S = 5;
+export const LOGIN_INTERVAL_MAX_S = 60;
+/** The most bytes of an answer from Jelly ID that the daemon reads. */
+export const JELLY_ANSWER_BYTES = 65_536;
+/**
+ * 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 function jellyKeyFingerprint(device) {
+    assertEd25519PublicKey(device, "device key");
+    const hex = createHash("sha256").update(`{"crv":"Ed25519","kty":"OKP","x":"${device}"}`).digest().subarray(0, 6).toString("hex");
+    return `${hex.slice(0, 4)}-${hex.slice(4, 8)}-${hex.slice(8, 12)}`;
+}
+const ResourceName = z.string().regex(/^[a-z][a-z0-9-]{0,31}$/);
+const Metadata = z.looseObject({
+    issuer: z.string().max(2048),
+    jelly_resources: z.array(z.looseObject({ name: ResourceName, resource: z.string().max(2048) })).max(8).optional(),
+    jelly_resource_device_authorization_endpoint: z.string().max(2048).optional(),
+    jelly_resource_device_token_endpoint: z.string().max(2048).optional(),
+});
+const unsupported = (why) => new MessagingError("login_unsupported", `Jelly ID does not offer device sign-in yet: ${why}`);
+/** An answer's JSON object, or undefined when it is not one. */
+function object(text) {
+    try {
+        return parseWire(text, { maxBytes: JELLY_ANSWER_BYTES });
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 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 function readDeviceSignIn(text, realm) {
+    const parsed = Metadata.safeParse(object(text));
+    if (!parsed.success)
+        throw new MessagingError("jelly_unavailable", "Jelly ID's metadata could not be read");
+    const meta = parsed.data;
+    if (meta.issuer !== realm.issuer)
+        throw new MessagingError("jelly_unavailable", "Jelly ID's metadata is for another issuer");
+    const code = meta.jelly_resource_device_authorization_endpoint;
+    const token = meta.jelly_resource_device_token_endpoint;
+    if (code === undefined || token === undefined)
+        throw unsupported("its metadata names no jelly_resource_device_authorization_endpoint (Jelly's contract v1.2, device sign-in)");
+    const origin = new URL(realm.issuer).origin;
+    for (const url of [code, token]) {
+        let at;
+        try {
+            at = new URL(url);
+        }
+        catch {
+            throw unsupported("its device sign-in endpoint is not a URL");
+        }
+        if (at.origin !== origin || at.username !== "" || at.password !== "" || at.hash !== "")
+            throw unsupported("its device sign-in endpoint is not on its own origin");
+    }
+    const entry = meta.jelly_resources?.find((r) => r.resource === realm.resource);
+    if (!entry)
+        throw unsupported("it lists no resource for this realm");
+    return { codeEndpoint: code, tokenEndpoint: token, clientId: entry.name };
+}
+/**
+ * Jelly ID's answer to the code request (RFC 8628 §3.2; v1.2 §12.1, `ResourceDeviceCodeResponseSchema`). Read loosely,
+ * so a member Jelly ID adds later is ignored: above all `verification_uri_complete`, which is never taken.
+ */
+const CodeAnswer = z.looseObject({
+    device_code: z.string().min(22).max(256),
+    user_code: z.string().regex(/^[A-HJ-NP-Z2-9]{5}-[A-HJ-NP-Z2-9]{5}$/),
+    verification_uri: z.string().max(2048),
+    expires_in: z.number().int().positive().max(3600),
+    interval: z.number().int().positive().max(LOGIN_INTERVAL_MAX_S),
+});
+const ErrorAnswer = z.looseObject({ error: z.string().max(64), detail: z.string().max(64).optional() });
+function errorOf(text) {
+    const parsed = ErrorAnswer.safeParse(object(text));
+    return parsed.success ? parsed.data : undefined;
+}
+/**
+ * A page URL from Jelly ID, on the issuer's origin (https, or http to a loopback issuer, as the realm's), with no
+ * query or fragment: the page the person types the code into carries no code.
+ */
+function page(url, issuer) {
+    let at;
+    try {
+        at = new URL(url);
+    }
+    catch {
+        throw new MessagingError("jelly_unavailable", "Jelly ID's sign-in page is not a URL");
+    }
+    if (at.origin !== new URL(issuer).origin)
+        throw new MessagingError("jelly_unavailable", "Jelly ID's sign-in page is not on its own origin");
+    if (at.search !== "" || at.hash !== "" || at.username !== "" || at.password !== "")
+        throw new MessagingError("jelly_unavailable", "Jelly ID's sign-in page carries a query or credentials");
+    return at.href;
+}
+/**
+ * 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 function readDeviceCodeAnswer(status, text, issuer) {
+    if (status === 200) {
+        const parsed = CodeAnswer.safeParse(object(text));
+        if (!parsed.success)
+            throw new MessagingError("jelly_unavailable", "Jelly ID's sign-in code could not be read");
+        const a = parsed.data;
+        return { deviceCode: a.device_code, userCode: a.user_code, verificationUri: page(a.verification_uri, issuer), expiresInS: a.expires_in, intervalS: a.interval };
+    }
+    const answer = errorOf(text);
+    switch (answer?.error) {
+        case "slow_down":
+            throw new MessagingError("rate_limited", "Jelly ID asks this address to wait before signing in again");
+        case "invalid_target":
+            if (answer.detail === "invalid_cnf_jwk")
+                throw new MessagingError("binding_invalid", "Jelly ID would not bind this device's key");
+            throw unsupported("it offers no device sign-in for this realm's resource");
+        case "invalid_client":
+            throw unsupported("it offers no device sign-in for this realm's resource");
+        case "invalid_request":
+            throw new MessagingError("invalid_request", "Jelly ID refused the sign-in request as malformed");
+        default:
+            throw new MessagingError("jelly_unavailable", `Jelly ID answered ${status}`);
+    }
+}
+const TokenAnswer = z.looseObject({ access_token: z.string().min(1).max(8192), token_type: z.string().max(32) });
+/**
+ * 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 function readDevicePoll(status, text) {
+    if (status === 200) {
+        const parsed = TokenAnswer.safeParse(object(text));
+        if (!parsed.success || parsed.data.token_type.toLowerCase() !== "bearer")
+            return { kind: "retry" };
+        return { kind: "token", token: parsed.data.access_token };
+    }
+    const answer = errorOf(text);
+    switch (answer?.error) {
+        case "authorization_pending":
+            return { kind: "pending" };
+        case "slow_down":
+            return { kind: "slow_down" };
+        case "access_denied":
+            throw new MessagingError("login_denied", "the sign-in was denied at Jelly ID, or the account is disabled or being deleted");
+        case "expired_token":
+            throw new MessagingError("expired", "the sign-in code expired before it was approved; start again");
+        case "invalid_grant":
+            throw new MessagingError("expired", "Jelly ID no longer accepts this sign-in code: it was used, or it expired; start again");
+        case "invalid_client":
+        case "unsupported_grant_type":
+            throw unsupported("it refused this device client");
+        default:
+            return { kind: "retry" };
+    }
+}
+/** The form of the code request (v1.2 §12.1). */
+export function deviceCodeForm(args) {
+    assertEd25519PublicKey(args.device, "device key");
+    return new URLSearchParams({
+        client_id: args.clientId,
+        resource: args.resource,
+        cnf_jwk: JSON.stringify({ kty: "OKP", crv: "Ed25519", x: args.device }),
+        label: args.label,
+        kind: args.kind,
+    });
+}
+/** The form of a poll (v1.2 §12.3). */
+export function devicePollForm(args) {
+    return new URLSearchParams({ grant_type: DEVICE_GRANT_TYPE, device_code: args.deviceCode, client_id: args.clientId });
+}
+/** For tests of the fingerprint's preimage: the RFC 7638 thumbprint, base64url. */
+export function jellyKeyThumbprint(device) {
+    return b64u.encode(createHash("sha256").update(`{"crv":"Ed25519","kty":"OKP","x":"${device}"}`).digest());
+}

package/dist/lib/modules/core/directory/jelly-issuer.js

@@ -0,0 +1,12 @@
+/**
+ * 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 { sign as ed25519Sign } from "node:crypto";
+import { b64u, utf8 } from "../b64u.js";
+/** A compact JWS over `header` and `claims` as given (members in their insertion order), signed with `key`. */
+export function signJellyToken(key, header, claims) {
+    const input = `${b64u.encode(utf8(JSON.stringify(header)))}.${b64u.encode(utf8(JSON.stringify(claims)))}`;
+    return `${input}.${b64u.encode(ed25519Sign(null, utf8(input), key))}`;
+}