@datumesh/verify 0.0.0-stage → 0.1.1

package/dist/cjs/json.js

@@ -0,0 +1,321 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_DEPTH = void 0;
+exports.isObject = isObject;
+exports.newObject = newObject;
+exports.has = has;
+exports.sortedKeys = sortedKeys;
+exports.memberPath = memberPath;
+exports.parseJsonText = parseJsonText;
+exports.parseJsonBytes = parseJsonBytes;
+exports.normalizeValue = normalizeValue;
+exports.toJson = toJson;
+// Strict JSON parsing (SPEC.md 6.1, I-JSON / RFC 7493). JSON.parse is not used: it accepts
+// duplicate members (last wins) and lone surrogates, both of which must be rejected.
+const errors_js_1 = require("./errors.js");
+const unicode_js_1 = require("./unicode.js");
+const utf8_js_1 = require("./utf8.js");
+/**
+ * Nesting deeper than this is rejected with E_PARSE_JSON. SPEC.md sets no depth limit; this is
+ * an implementation limit (Datumesh objects nest at most five levels) that keeps parsing and
+ * canonicalisation from exhausting the call stack.
+ */
+exports.MAX_DEPTH = 1000;
+function isObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function newObject() {
+    return Object.create(null);
+}
+function has(o, k) {
+    return Object.prototype.hasOwnProperty.call(o, k);
+}
+/** Member names in JCS order (UTF-16 code units, which is JavaScript's default sort). */
+function sortedKeys(o) {
+    return Object.keys(o).sort();
+}
+function memberPath(path, name) {
+    return /^[A-Za-z_][A-Za-z0-9_]*$/.test(name) ? `${path}.${name}` : `${path}[${JSON.stringify(name)}]`;
+}
+class Parser {
+    constructor(s) {
+        this.s = s;
+        this.i = 0;
+        /** Path of the first string holding an escaped lone surrogate; reported after parsing. */
+        this.surrogatePath = null;
+    }
+    err(msg) {
+        (0, errors_js_1.fail)('E_PARSE_JSON', `${msg} at offset ${this.i}`, '$');
+    }
+    ws() {
+        const s = this.s;
+        while (this.i < s.length) {
+            const c = s.charCodeAt(this.i);
+            if (c === 0x20 || c === 0x09 || c === 0x0a || c === 0x0d)
+                this.i++;
+            else
+                break;
+        }
+    }
+    parseDocument() {
+        this.ws();
+        const v = this.value('$', 0);
+        this.ws();
+        if (this.i !== this.s.length)
+            this.err('unexpected data after the JSON value');
+        return v;
+    }
+    value(path, depth) {
+        if (depth > exports.MAX_DEPTH)
+            this.err(`nesting deeper than ${exports.MAX_DEPTH} levels (implementation limit)`);
+        const s = this.s;
+        const c = s[this.i];
+        if (c === '{')
+            return this.object(path, depth);
+        if (c === '[')
+            return this.array(path, depth);
+        if (c === '"')
+            return this.string(path);
+        if (c === 't' && s.startsWith('true', this.i)) {
+            this.i += 4;
+            return true;
+        }
+        if (c === 'f' && s.startsWith('false', this.i)) {
+            this.i += 5;
+            return false;
+        }
+        if (c === 'n' && s.startsWith('null', this.i)) {
+            this.i += 4;
+            return null;
+        }
+        if (c === '-' || (c >= '0' && c <= '9'))
+            return this.number();
+        if (c === undefined)
+            this.err('unexpected end of input');
+        if (s.startsWith('NaN', this.i) || s.startsWith('Infinity', this.i) || s.startsWith('-Infinity', this.i)) {
+            this.err('NaN and Infinity are not JSON');
+        }
+        this.err(`unexpected character ${JSON.stringify(c)}`);
+    }
+    object(path, depth) {
+        this.i++; // {
+        const o = newObject();
+        let dup = null;
+        this.ws();
+        if (this.s[this.i] === '}') {
+            this.i++;
+            return o;
+        }
+        for (;;) {
+            this.ws();
+            if (this.s[this.i] !== '"')
+                this.err('expected a member name');
+            const k = this.string(path);
+            this.ws();
+            if (this.s[this.i] !== ':')
+                this.err("expected ':'");
+            this.i++;
+            this.ws();
+            const v = this.value(memberPath(path, k), depth + 1);
+            if (has(o, k)) {
+                if (dup === null)
+                    dup = k;
+            }
+            else
+                o[k] = v;
+            this.ws();
+            const c = this.s[this.i];
+            if (c === ',') {
+                this.i++;
+                continue;
+            }
+            if (c === '}') {
+                this.i++;
+                break;
+            }
+            this.err("expected ',' or '}'");
+        }
+        // Like an object-pairs hook, duplicates are reported once the object is complete.
+        if (dup !== null)
+            (0, errors_js_1.fail)('E_PARSE_DUPLICATE_KEY', `duplicate member ${JSON.stringify(dup)}`, path);
+        return o;
+    }
+    array(path, depth) {
+        this.i++; // [
+        const a = [];
+        this.ws();
+        if (this.s[this.i] === ']') {
+            this.i++;
+            return a;
+        }
+        for (;;) {
+            this.ws();
+            a.push(this.value(`${path}[${a.length}]`, depth + 1));
+            this.ws();
+            const c = this.s[this.i];
+            if (c === ',') {
+                this.i++;
+                continue;
+            }
+            if (c === ']') {
+                this.i++;
+                return a;
+            }
+            this.err("expected ',' or ']'");
+        }
+    }
+    string(path) {
+        const s = this.s;
+        this.i++; // opening quote
+        let out = '';
+        let start = this.i;
+        for (;;) {
+            if (this.i >= s.length)
+                this.err('unterminated string');
+            const c = s.charCodeAt(this.i);
+            if (c === 0x22) {
+                out += s.slice(start, this.i);
+                this.i++;
+                break;
+            }
+            if (c < 0x20)
+                this.err('control character in string');
+            if (c === 0x5c) {
+                out += s.slice(start, this.i);
+                const e = s[this.i + 1];
+                let ch;
+                switch (e) {
+                    case '"':
+                        ch = '"';
+                        break;
+                    case '\\':
+                        ch = '\\';
+                        break;
+                    case '/':
+                        ch = '/';
+                        break;
+                    case 'b':
+                        ch = '\b';
+                        break;
+                    case 'f':
+                        ch = '\f';
+                        break;
+                    case 'n':
+                        ch = '\n';
+                        break;
+                    case 'r':
+                        ch = '\r';
+                        break;
+                    case 't':
+                        ch = '\t';
+                        break;
+                    case 'u': {
+                        const h = s.slice(this.i + 2, this.i + 6);
+                        if (!/^[0-9A-Fa-f]{4}$/.test(h))
+                            this.err('bad \\u escape');
+                        ch = String.fromCharCode(parseInt(h, 16));
+                        this.i += 4;
+                        break;
+                    }
+                    default:
+                        this.err('bad escape');
+                }
+                out += ch;
+                this.i += 2;
+                start = this.i;
+                continue;
+            }
+            this.i++;
+        }
+        if (this.surrogatePath === null && (0, unicode_js_1.hasLoneSurrogate)(out))
+            this.surrogatePath = path;
+        return out;
+    }
+    number() {
+        const s = this.s;
+        const m = /-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?/y;
+        m.lastIndex = this.i;
+        const r = m.exec(s);
+        if (!r || r[0] === '-' || r[0] === '')
+            this.err('bad number');
+        const text = r[0];
+        // A digit right after "0" (e.g. 01) is not JSON.
+        const next = s[this.i + text.length];
+        if (next !== undefined && /[0-9.eE+-]/.test(next))
+            this.err('bad number');
+        this.i += text.length;
+        const n = Number(text);
+        if (!Number.isFinite(n))
+            (0, errors_js_1.fail)('E_PARSE_JSON', `number out of IEEE 754 range: ${text.slice(0, 40)}`, '$');
+        return n;
+    }
+}
+/** Parse JSON text strictly. */
+function parseJsonText(text) {
+    if (text.charCodeAt(0) === 0xfeff)
+        (0, errors_js_1.fail)('E_PARSE_JSON', 'byte order mark', '$');
+    if ((0, unicode_js_1.hasLoneSurrogate)(text))
+        (0, errors_js_1.fail)('E_PARSE_JSON', 'lone surrogate in the text', '$');
+    const p = new Parser(text);
+    const v = p.parseDocument();
+    if (p.surrogatePath !== null)
+        (0, errors_js_1.fail)('E_PARSE_JSON', 'lone surrogate', p.surrogatePath);
+    return v;
+}
+/** Parse UTF-8 JSON bytes strictly: no BOM, no invalid UTF-8. */
+function parseJsonBytes(bytes) {
+    if (bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf) {
+        (0, errors_js_1.fail)('E_PARSE_JSON', 'byte order mark', '$');
+    }
+    const text = (0, utf8_js_1.utf8Decode)(bytes);
+    if (text === null)
+        (0, errors_js_1.fail)('E_PARSE_JSON', 'invalid UTF-8', '$');
+    return parseJsonText(text);
+}
+/**
+ * Check an already-parsed JavaScript value against the JSON data model and return a private
+ * deep copy (plain data with null-prototype objects), so later checks cannot be affected by
+ * getters, prototypes or mutation. Duplicate members cannot be detected here: pass JSON text
+ * or bytes for that.
+ */
+function normalizeValue(v, path = '$', depth = 0) {
+    if (depth > exports.MAX_DEPTH)
+        (0, errors_js_1.fail)('E_PARSE_JSON', `nesting deeper than ${exports.MAX_DEPTH} levels (or a cycle)`, path);
+    if (v === null || typeof v === 'boolean')
+        return v;
+    if (typeof v === 'number') {
+        if (!Number.isFinite(v))
+            (0, errors_js_1.fail)('E_PARSE_JSON', 'NaN and Infinity are not JSON', path);
+        return v;
+    }
+    if (typeof v === 'string') {
+        if ((0, unicode_js_1.hasLoneSurrogate)(v))
+            (0, errors_js_1.fail)('E_PARSE_JSON', 'lone surrogate', path);
+        return v;
+    }
+    if (Array.isArray(v))
+        return v.map((x, i) => normalizeValue(x, `${path}[${i}]`, depth + 1));
+    if (typeof v === 'object') {
+        const proto = Object.getPrototypeOf(v);
+        if (proto !== Object.prototype && proto !== null)
+            (0, errors_js_1.fail)('E_PARSE_JSON', 'not a plain JSON object', path);
+        const o = newObject();
+        for (const k of Object.keys(v)) {
+            if ((0, unicode_js_1.hasLoneSurrogate)(k))
+                (0, errors_js_1.fail)('E_PARSE_JSON', 'lone surrogate in a member name', path);
+            o[k] = normalizeValue(v[k], memberPath(path, k), depth + 1);
+        }
+        return o;
+    }
+    (0, errors_js_1.fail)('E_PARSE_JSON', `${typeof v} is not a JSON value`, path);
+}
+/** JSON text (string), UTF-8 bytes (Uint8Array) or an already-parsed value. */
+function toJson(input) {
+    if (typeof input === 'string')
+        return parseJsonText(input);
+    if (input instanceof Uint8Array)
+        return parseJsonBytes(input);
+    if (input instanceof ArrayBuffer)
+        return parseJsonBytes(new Uint8Array(input));
+    return normalizeValue(input);
+}

package/dist/cjs/keys.d.ts

@@ -0,0 +1,73 @@
+import { type ErrorCode } from './errors.js';
+/** One validated key from a key document. */
+export interface KeyEntry {
+    alg: 'ed25519';
+    id: string;
+    public: string;
+    valid_from: string;
+    valid_to?: string;
+}
+/** The outcome of resolving one host's keys (SPEC 9.3). */
+export interface KeysResult {
+    ok: boolean;
+    /** "OK", "E_KEY_UNAVAILABLE" or "E_KEY_DOC". */
+    code: 'OK' | 'E_KEY_UNAVAILABLE' | 'E_KEY_DOC';
+    host: string;
+    detail: string;
+    /** The validated keys, in document order, when ok. */
+    keys?: KeyEntry[];
+}
+/** A mapping of key id to 64-hex public key: usable for any host, with no validity windows. */
+export type KeyMap = Record<string, string>;
+/** Anything `verify` accepts as keys. */
+export type KeySource = KeysResult | KeyMap | Record<string, unknown> | KeySource[];
+/**
+ * Interpret the HTTPS response for https://<host>/.well-known/datumesh.json (SPEC 9.3).
+ * `status` is the HTTP status, or null for a network, DNS, TLS or timeout failure. `body` is the
+ * response body as text or bytes. Never throws.
+ */
+export declare function keysFromResponse(host: string, status: number | null, body?: string | Uint8Array | null): KeysResult;
+/**
+ * Validate an already-parsed key document (its `host` member names the host it covers).
+ * Never throws.
+ */
+export declare function keysFromDocument(doc: unknown): KeysResult;
+/** Default timeout of fetchKeys, in milliseconds. */
+export declare const FETCH_TIMEOUT_MS = 10000;
+/**
+ * Fetch https://<host>/.well-known/datumesh.json once, with TLS verified by the platform, no
+ * redirects followed and a timeout, then interpret it with keysFromResponse. The only function
+ * in this library that touches the network. Never throws.
+ */
+export declare function fetchKeys(host: string, timeoutMs?: number): Promise<KeysResult>;
+interface HostSource {
+    host: string;
+    result: KeysResult;
+}
+interface AnySource {
+    ok: boolean;
+    code: ErrorCode | 'OK';
+    detail: string;
+    keys: KeyEntry[];
+}
+export interface Sources {
+    hosts: HostSource[];
+    any: AnySource[];
+}
+/**
+ * Normalise the `keys` argument of verify. Throws TypeError only for arguments that are not key
+ * sources at all (programmer errors); malformed key material becomes an error source.
+ */
+export declare function collectSources(keys: unknown, into?: Sources, depth?: number): Sources;
+export type KeyLookup = {
+    ok: true;
+    key: KeyEntry;
+    windows: boolean;
+} | {
+    ok: false;
+    code: ErrorCode;
+    detail: string;
+};
+/** SPEC 10.1 step 5 for key reference host#id at time `issued`. */
+export declare function lookupKey(sources: Sources, host: string, id: string, issued: string): KeyLookup;
+export {};

package/dist/cjs/keys.js

@@ -0,0 +1,257 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FETCH_TIMEOUT_MS = void 0;
+exports.keysFromResponse = keysFromResponse;
+exports.keysFromDocument = keysFromDocument;
+exports.fetchKeys = fetchKeys;
+exports.collectSources = collectSources;
+exports.lookupKey = lookupKey;
+// Key documents (SPEC.md 9.2), their retrieval (9.3) and the key sources `verify` accepts.
+const errors_js_1 = require("./errors.js");
+const hash_js_1 = require("./hash.js");
+const json_js_1 = require("./json.js");
+const lexical_js_1 = require("./lexical.js");
+class KeyDocError extends Error {
+    constructor(msg, path) {
+        super(msg);
+        this.path = path;
+    }
+}
+function bad(msg, path) {
+    throw new KeyDocError(msg, path);
+}
+/** Validate a parsed key document for `host` (SPEC 9.2). Throws KeyDocError. */
+function validateKeyDocument(doc, host) {
+    if (!(0, json_js_1.isObject)(doc))
+        bad('expected an object', '$');
+    for (const k of (0, json_js_1.sortedKeys)(doc))
+        if (!['host', 'keys', 'proto'].includes(k))
+            bad(`unexpected member ${JSON.stringify(k)}`, '$');
+    for (const k of ['host', 'keys', 'proto'])
+        if (!(0, json_js_1.has)(doc, k))
+            bad(`missing member ${JSON.stringify(k)}`, '$');
+    if (doc.proto !== 'datumesh/1')
+        bad("proto must be 'datumesh/1'", '$.proto');
+    if (doc.host !== host)
+        bad(`host must be ${JSON.stringify(host)}`, '$.host');
+    const keys = doc.keys;
+    if (!Array.isArray(keys) || keys.length < 1 || keys.length > lexical_js_1.LIMITS.keys)
+        bad(`keys must be an array of 1 to ${lexical_js_1.LIMITS.keys} keys`, '$.keys');
+    const out = [];
+    const seenIds = new Set();
+    const seenPublic = new Set();
+    keys.forEach((k, i) => {
+        const p = `$.keys[${i}]`;
+        if (!(0, json_js_1.isObject)(k))
+            bad('expected an object', p);
+        for (const m of (0, json_js_1.sortedKeys)(k))
+            if (!['alg', 'id', 'public', 'valid_from', 'valid_to'].includes(m))
+                bad(`unexpected member ${JSON.stringify(m)}`, p);
+        for (const m of ['alg', 'id', 'public', 'valid_from'])
+            if (!(0, json_js_1.has)(k, m))
+                bad(`missing member ${JSON.stringify(m)}`, p);
+        if (k.alg !== 'ed25519')
+            bad('alg must be ed25519', (0, json_js_1.memberPath)(p, 'alg'));
+        if (typeof k.id !== 'string' || !(0, lexical_js_1.isHex)(k.id, 16))
+            bad('id must be 16 lowercase hex digits', (0, json_js_1.memberPath)(p, 'id'));
+        if (typeof k.public !== 'string' || !(0, lexical_js_1.isHex)(k.public, 64))
+            bad('public must be 64 lowercase hex digits', (0, json_js_1.memberPath)(p, 'public'));
+        if (typeof k.valid_from !== 'string' || !(0, lexical_js_1.isInstant)(k.valid_from))
+            bad('valid_from must be an instant', (0, json_js_1.memberPath)(p, 'valid_from'));
+        if ((0, json_js_1.has)(k, 'valid_to')) {
+            if (typeof k.valid_to !== 'string' || !(0, lexical_js_1.isInstant)(k.valid_to))
+                bad('valid_to must be an instant', (0, json_js_1.memberPath)(p, 'valid_to'));
+            if (!(k.valid_to > k.valid_from))
+                bad('valid_to must be later than valid_from', p);
+        }
+        if ((0, hash_js_1.keyIdOf)((0, hash_js_1.fromHex)(k.public)) !== k.id)
+            bad('id is not the key id of public', (0, json_js_1.memberPath)(p, 'id'));
+        if (seenIds.has(k.id) || seenPublic.has(k.public))
+            bad('key appears twice', p);
+        seenIds.add(k.id);
+        seenPublic.add(k.public);
+        const e = { alg: 'ed25519', id: k.id, public: k.public, valid_from: k.valid_from };
+        if ((0, json_js_1.has)(k, 'valid_to'))
+            e.valid_to = k.valid_to;
+        out.push(e);
+    });
+    return out;
+}
+function docResult(host, parse) {
+    let doc;
+    try {
+        doc = parse();
+    }
+    catch (e) {
+        const d = e instanceof errors_js_1.DatumeshError ? `${e.code}: ${e.detail}` : String(e);
+        return { ok: false, code: 'E_KEY_DOC', host, detail: `key document is not strict JSON (${d})` };
+    }
+    try {
+        const keys = validateKeyDocument(doc, host);
+        return { ok: true, code: 'OK', host, detail: `${keys.length} key(s) for ${host}`, keys };
+    }
+    catch (e) {
+        if (e instanceof KeyDocError)
+            return { ok: false, code: 'E_KEY_DOC', host, detail: `${e.message} at ${e.path}` };
+        throw e;
+    }
+}
+/**
+ * Interpret the HTTPS response for https://<host>/.well-known/datumesh.json (SPEC 9.3).
+ * `status` is the HTTP status, or null for a network, DNS, TLS or timeout failure. `body` is the
+ * response body as text or bytes. Never throws.
+ */
+function keysFromResponse(host, status, body) {
+    const h = typeof host === 'string' ? host : String(host);
+    try {
+        if (status === null || status === undefined) {
+            return { ok: false, code: 'E_KEY_UNAVAILABLE', host: h, detail: 'network, DNS, TLS or timeout failure' };
+        }
+        if (status !== 200) {
+            return { ok: false, code: 'E_KEY_UNAVAILABLE', host: h, detail: `HTTP status ${String(status)} (only 200 is accepted; redirects are not followed)` };
+        }
+        if (typeof body !== 'string' && !(body instanceof Uint8Array)) {
+            return { ok: false, code: 'E_KEY_DOC', host: h, detail: '200 response without a body' };
+        }
+        return docResult(h, () => (0, json_js_1.toJson)(body));
+    }
+    catch (e) {
+        return { ok: false, code: 'E_KEY_UNAVAILABLE', host: h, detail: `could not interpret the response: ${String(e)}` };
+    }
+}
+/**
+ * Validate an already-parsed key document (its `host` member names the host it covers).
+ * Never throws.
+ */
+function keysFromDocument(doc) {
+    const host = (0, json_js_1.isObject)(doc) && typeof doc.host === 'string' ? doc.host : '';
+    try {
+        return docResult(host, () => (0, json_js_1.toJson)(doc));
+    }
+    catch (e) {
+        return { ok: false, code: 'E_KEY_DOC', host, detail: String(e) };
+    }
+}
+/** Default timeout of fetchKeys, in milliseconds. */
+exports.FETCH_TIMEOUT_MS = 10000;
+/**
+ * Fetch https://<host>/.well-known/datumesh.json once, with TLS verified by the platform, no
+ * redirects followed and a timeout, then interpret it with keysFromResponse. The only function
+ * in this library that touches the network. Never throws.
+ */
+async function fetchKeys(host, timeoutMs = exports.FETCH_TIMEOUT_MS) {
+    try {
+        (0, lexical_js_1.checkDnsName)(host, '$');
+    }
+    catch {
+        return { ok: false, code: 'E_KEY_UNAVAILABLE', host: String(host), detail: 'host is not a lowercase DNS name (SPEC 2.1); nothing was fetched' };
+    }
+    const f = globalThis.fetch;
+    if (typeof f !== 'function')
+        return { ok: false, code: 'E_KEY_UNAVAILABLE', host, detail: 'no global fetch in this runtime' };
+    let status;
+    let body;
+    try {
+        const res = await f(`https://${host}/.well-known/datumesh.json`, {
+            method: 'GET',
+            redirect: 'manual',
+            credentials: 'omit',
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        status = res.status;
+        // A redirect under redirect:"manual" is a 3xx (Node) or an opaque-redirect response with
+        // status 0 (browsers); either way it is not 200.
+        if (res.type === 'opaqueredirect')
+            status = 0;
+        if (status !== 200)
+            return keysFromResponse(host, status);
+        body = new Uint8Array(await res.arrayBuffer());
+    }
+    catch (e) {
+        return { ok: false, code: 'E_KEY_UNAVAILABLE', host, detail: `retrieval failed: ${e instanceof Error ? e.message : String(e)}` };
+    }
+    return keysFromResponse(host, status, body);
+}
+function isKeysResult(v) {
+    return typeof v.ok === 'boolean' && typeof v.code === 'string' && typeof v.host === 'string';
+}
+function fromMap(m) {
+    const keys = [];
+    for (const id of Object.keys(m)) {
+        const pub = m[id];
+        if (!(0, lexical_js_1.isHex)(id, 16) || typeof pub !== 'string' || !(0, lexical_js_1.isHex)(pub, 64) || (0, hash_js_1.keyIdOf)((0, hash_js_1.fromHex)(pub)) !== id) {
+            return { ok: false, code: 'E_KEY_DOC', detail: `key map entry ${JSON.stringify(id)} is not <key id>: <64-hex public key> with a matching id`, keys: [] };
+        }
+        keys.push({ alg: 'ed25519', id, public: pub, valid_from: '0001-01-01T00:00:00.000000Z' });
+    }
+    return { ok: true, code: 'OK', detail: 'key map (any host, no validity windows)', keys };
+}
+/**
+ * Normalise the `keys` argument of verify. Throws TypeError only for arguments that are not key
+ * sources at all (programmer errors); malformed key material becomes an error source.
+ */
+function collectSources(keys, into = { hosts: [], any: [] }, depth = 0) {
+    if (Array.isArray(keys)) {
+        if (depth > 8)
+            throw new TypeError('keys: arrays nested too deeply');
+        for (const k of keys)
+            collectSources(k, into, depth + 1);
+        return into;
+    }
+    if (typeof keys !== 'object' || keys === null) {
+        throw new TypeError('keys must be a key document, a KeysResult, a {keyId: publicKeyHex} map, or an array of these');
+    }
+    const o = keys;
+    if (isKeysResult(o)) {
+        const r = o;
+        if (r.ok) {
+            // Re-check what a caller may have built by hand.
+            const ok = Array.isArray(r.keys) && r.keys.every((k) => k && (0, lexical_js_1.isHex)(k.id, 16) && (0, lexical_js_1.isHex)(k.public, 64) && (0, lexical_js_1.isInstant)(k.valid_from) && (k.valid_to === undefined || (0, lexical_js_1.isInstant)(k.valid_to)));
+            into.hosts.push({ host: r.host, result: ok ? r : { ok: false, code: 'E_KEY_DOC', host: r.host, detail: 'KeysResult has malformed keys' } });
+        }
+        else {
+            const code = r.code === 'E_KEY_DOC' ? 'E_KEY_DOC' : 'E_KEY_UNAVAILABLE';
+            into.hosts.push({ host: r.host, result: { ok: false, code, host: r.host, detail: String(r.detail ?? '') } });
+        }
+        return into;
+    }
+    if ('keys' in o || 'host' in o || 'proto' in o) {
+        const r = keysFromDocument(o);
+        if (r.host)
+            into.hosts.push({ host: r.host, result: r });
+        else
+            into.any.push({ ok: false, code: 'E_KEY_DOC', detail: `key document without a host: ${r.detail}`, keys: [] });
+        return into;
+    }
+    into.any.push(fromMap(o));
+    return into;
+}
+/** SPEC 10.1 step 5 for key reference host#id at time `issued`. */
+function lookupKey(sources, host, id, issued) {
+    const h = sources.hosts.find((s) => s.host === host);
+    let keys;
+    let windows;
+    if (h) {
+        if (!h.result.ok)
+            return { ok: false, code: h.result.code, detail: `${host}: ${h.result.detail}` };
+        keys = h.result.keys ?? [];
+        windows = true;
+    }
+    else if (sources.any.length) {
+        const a = sources.any[0];
+        if (!a.ok)
+            return { ok: false, code: a.code, detail: a.detail };
+        keys = a.keys;
+        windows = false;
+    }
+    else {
+        return { ok: false, code: 'E_KEY_UNAVAILABLE', detail: `no key source covers ${host}` };
+    }
+    const key = keys.find((k) => k.id === id);
+    if (!key)
+        return { ok: false, code: 'E_KEY_UNKNOWN', detail: `${host} publishes no key ${id}` };
+    if (windows && !(key.valid_from <= issued && (key.valid_to === undefined || issued < key.valid_to))) {
+        return { ok: false, code: 'E_KEY_NOT_VALID', detail: `issued ${issued} is outside the window of key ${id}` };
+    }
+    return { ok: true, key, windows };
+}