@datumesh/verify 0.0.0-stage → 0.2.0

package/dist/cjs/verify.js

@@ -0,0 +1,232 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Stop = void 0;
+exports.verify = verify;
+exports.verifyEmbedded = verifyEmbedded;
+// Receipt verification (SPEC.md 10.1). Synchronous, offline, no global state, no logging.
+const errors_js_1 = require("./errors.js");
+const ed25519_js_1 = require("./ed25519.js");
+const hash_js_1 = require("./hash.js");
+const json_js_1 = require("./json.js");
+const jcs_js_1 = require("./jcs.js");
+const keys_js_1 = require("./keys.js");
+const lexical_js_1 = require("./lexical.js");
+const validate_js_1 = require("./validate.js");
+class Stop extends Error {
+    constructor(code, detail, path) {
+        super(detail);
+        this.code = code;
+        this.detail = detail;
+        this.path = path;
+    }
+}
+exports.Stop = Stop;
+function stop(code, detail, path = '$') {
+    throw new Stop(code, detail, path);
+}
+function withoutSig(r) {
+    const o = (0, json_js_1.newObject)();
+    for (const k of Object.keys(r))
+        if (k !== 'sig')
+            o[k] = r[k];
+    return o;
+}
+/** Steps 1-6. Throws Stop; returns the parsed receipt and its hash. */
+function verifySigned(input, sources, setHash) {
+    let r;
+    try {
+        r = (0, json_js_1.toJson)(input); // step 1
+        (0, validate_js_1.receiptStructure)(r); // step 2
+    }
+    catch (e) {
+        if (e instanceof errors_js_1.DatumeshError)
+            stop(e.code, e.detail, e.path);
+        throw e;
+    }
+    const receipt = r;
+    const payload = (0, jcs_js_1.jcsBytes)(withoutSig(receipt));
+    const hash = (0, hash_js_1.sha256Hex)(payload);
+    setHash(hash);
+    try {
+        (0, validate_js_1.receiptCanonicalAndConsistent)(receipt); // steps 3-4
+    }
+    catch (e) {
+        if (e instanceof errors_js_1.DatumeshError)
+            stop(e.code, e.detail, e.path);
+        throw e;
+    }
+    // Step 5.
+    const ref = receipt.computed_by;
+    const hashAt = ref.indexOf('#');
+    const host = ref.slice(0, hashAt);
+    const id = ref.slice(hashAt + 1);
+    const found = (0, keys_js_1.lookupKey)(sources, host, id, receipt.issued);
+    if (!found.ok)
+        stop(found.code, found.detail, found.code === 'E_KEY_NOT_VALID' ? '$.issued' : '$.computed_by');
+    // Step 6.
+    if (!(0, ed25519_js_1.verifyEd25519Strict)((0, hash_js_1.fromHex)(receipt.sig), payload, (0, hash_js_1.fromHex)(found.key.public))) {
+        stop('E_SIGNATURE', 'Ed25519 verification failed', '$.sig');
+    }
+    return { receipt, hash };
+}
+function recompute(receipt, rc, sources) {
+    const cell = receipt.cell;
+    const cellArgs = cell.args;
+    // 7.1 Descriptor.
+    if (rc.descriptor === undefined || rc.descriptor === null)
+        stop('E_FN_UNAVAILABLE', `no descriptor for ${cell.fn_hash}`, '$.cell.fn_hash');
+    let desc;
+    try {
+        const d = (0, json_js_1.toJson)(rc.descriptor);
+        if ((0, hash_js_1.sha256Hex)((0, jcs_js_1.jcsBytes)(d)) !== cell.fn_hash)
+            stop('E_FN_HASH_MISMATCH', 'descriptor does not hash to cell.fn_hash', '$.cell.fn_hash');
+        (0, validate_js_1.validate)(d, 'function', 'descriptor');
+        desc = d;
+    }
+    catch (e) {
+        if (e instanceof errors_js_1.DatumeshError)
+            stop(e.code, `descriptor: ${e.detail}`, e.path);
+        throw e;
+    }
+    const sig = desc.signature;
+    const declared = sig.args;
+    // 7.2 Arguments: unknown, then missing, then types.
+    for (const k of (0, json_js_1.sortedKeys)(cellArgs)) {
+        if (!(0, json_js_1.has)(declared, k))
+            stop('E_ARG_UNKNOWN', `function declares no argument ${JSON.stringify(k)}`, `$.cell.args.${k}`);
+    }
+    for (const k of (0, json_js_1.sortedKeys)(declared)) {
+        if (!(0, json_js_1.has)(cellArgs, k))
+            stop('E_ARG_MISSING', `argument ${JSON.stringify(k)} is not bound`, '$.cell.args');
+    }
+    for (const k of (0, json_js_1.sortedKeys)(cellArgs)) {
+        const want = declared[k].type;
+        if (cellArgs[k].type !== want)
+            stop('E_ARG_TYPE', `${k} is declared ${String(want)}`, `$.cell.args.${k}`);
+    }
+    // 7.3 valid holds exactly the declared valid-time arguments.
+    const validNames = (0, json_js_1.sortedKeys)(receipt.valid);
+    const declaredValid = (0, json_js_1.sortedKeys)(declared).filter((k) => declared[k].valid === true);
+    if (validNames.join('\u0000') !== declaredValid.join('\u0000')) {
+        stop('E_VALID_MISMATCH', 'valid must echo exactly the declared valid-time arguments', '$.valid');
+    }
+    // 7.4 Return type: `returns`, or its `type` member when it is an object.
+    const rt = (0, validate_js_1.returnType)(sig);
+    if (receipt.type !== rt)
+        stop('E_RETURN_TYPE', `function returns ${rt}`, '$.type');
+    // 7.5 Inputs.
+    const declaredInputs = desc.inputs;
+    const supplied = rc.inputs ?? {};
+    let latestTx = null;
+    for (const h of receipt.inputs) {
+        if (!Object.prototype.hasOwnProperty.call(supplied, h))
+            stop('E_INPUT_UNAVAILABLE', `input receipt ${h} not available`, '$.inputs');
+        let inner;
+        try {
+            inner = verifySigned(supplied[h], sources, () => undefined);
+        }
+        catch (e) {
+            if (e instanceof Stop)
+                stop('E_INPUT_INVALID', `input ${h}: ${e.code}: ${e.detail}`, '$.inputs');
+            throw e;
+        }
+        if (inner.hash !== h)
+            stop('E_INPUT_UNAVAILABLE', `supplied receipt does not hash to ${h}`, '$.inputs');
+        const ic = inner.receipt.cell;
+        if (!declaredInputs.includes(`${ic.ns}/${ic.fn}`)) {
+            stop('E_INPUT_UNDECLARED', `input ${h} is a cell of an undeclared function`, '$.inputs');
+        }
+        if (inner.receipt.asof !== receipt.asof)
+            stop('E_TIME_ORDER', "input receipts must share the receipt's asof", '$.inputs');
+        const itx = inner.receipt.tx;
+        if (latestTx === null || itx > latestTx)
+            latestTx = itx;
+    }
+    if (latestTx !== null && receipt.tx !== latestTx)
+        stop('E_TIME_ORDER', 'tx must be the latest input tx', '$.tx');
+    // 7.6 Value.
+    const v = rc.value;
+    if (v.type !== receipt.type || v.value !== receipt.value)
+        stop('E_VALUE_MISMATCH', 'recomputed value differs from the receipt', '$.value');
+}
+/**
+ * Step 7.7: content is only for a blob value (E_SCHEMA otherwise); it has exactly `length`
+ * bytes, then a SHA-256 equal to the blob's hash (E_BLOB_MISMATCH).
+ */
+function checkContent(receipt, content) {
+    if (receipt.type !== 'blob')
+        stop('E_SCHEMA', `content was supplied, but the value is a ${String(receipt.type)}, not a blob`, '$.type');
+    const blob = (0, lexical_js_1.checkBlob)(receipt.value, '$.value'); // already checked in step 3
+    if (content.length !== blob.length)
+        stop('E_BLOB_MISMATCH', `content is ${content.length} bytes, the blob says ${blob.length}`, '$.value');
+    if ((0, hash_js_1.sha256Hex)(content) !== blob.sha256)
+        stop('E_BLOB_MISMATCH', "the content's SHA-256 is not the blob's hash", '$.value');
+}
+function checkBlobArg(b) {
+    if (b === undefined || b === null)
+        return null;
+    if (b instanceof Uint8Array)
+        return b;
+    if (b instanceof ArrayBuffer)
+        return new Uint8Array(b);
+    throw new TypeError('blob must be the content bytes (Uint8Array or ArrayBuffer)');
+}
+function checkRecomputeArg(rc) {
+    if (rc === undefined || rc === null)
+        return null;
+    if (typeof rc !== 'object' || Array.isArray(rc))
+        throw new TypeError('recompute must be an object {descriptor, inputs, value}');
+    const r = rc;
+    if (!r.value || typeof r.value !== 'object' || typeof r.value.type !== 'string' || (typeof r.value.value !== 'string' && typeof r.value.value !== 'boolean')) {
+        throw new TypeError('recompute.value must be the evaluated typed scalar {type, value}');
+    }
+    if (r.inputs !== undefined && (typeof r.inputs !== 'object' || r.inputs === null || Array.isArray(r.inputs))) {
+        throw new TypeError('recompute.inputs must be an object mapping receipt hash to receipt JSON');
+    }
+    return r;
+}
+/**
+ * Verify a receipt (SPEC 10.1). `receipt` is JSON text, UTF-8 bytes or a parsed object (only
+ * text and bytes allow duplicate-member detection). `keys` is a key document, a KeysResult, a
+ * {keyId: publicKeyHex} map, or an array of these. With `recompute`, step 7 runs too. With
+ * `blob`, the content of a blob value, step 7.7 runs last (after step 7 when recomputing,
+ * otherwise right after step 6): E_SCHEMA if the value is not a blob, E_BLOB_MISMATCH if the
+ * content does not match. It does not change `level`; `blobChecked` reports it.
+ *
+ * Never throws for an invalid receipt or bad key material; throws TypeError only when an
+ * argument is of the wrong kind altogether.
+ */
+function verify(receipt, keys, recomputeArg, blob) {
+    const sources = (0, keys_js_1.collectSources)(keys);
+    const rc = checkRecomputeArg(recomputeArg);
+    const content = checkBlobArg(blob);
+    let hash = null;
+    try {
+        const { receipt: r } = verifySigned(receipt, sources, (h) => (hash = h));
+        if (rc)
+            recompute(r, rc, sources);
+        const checked = content !== null;
+        if (checked)
+            checkContent(r, content);
+        const what = rc ? 'fully verified: signature valid and value recomputed' : `signature-valid: signed by ${r.computed_by}`;
+        return {
+            ok: true,
+            code: 'OK',
+            level: rc ? 'recomputed' : 'signed',
+            hash,
+            key: r.computed_by,
+            detail: checked ? `${what}; blob content matches` : what,
+            path: null,
+            blobChecked: checked,
+        };
+    }
+    catch (e) {
+        if (e instanceof Stop)
+            return { ok: false, code: e.code, level: null, hash, key: null, detail: e.detail, path: e.path, blobChecked: false };
+        throw e; // a bug in this library, not a property of the receipt
+    }
+}
+/** Steps 1-6 for an already-parsed receipt (used by checkEnvelope). Throws a Stop. */
+function verifyEmbedded(receipt, sources) {
+    return verifySigned(receipt, sources, () => undefined);
+}

package/dist/esm/ed25519.d.ts

@@ -0,0 +1,2 @@
+/** Strict Ed25519 verification of `sig` (64 bytes) over `msg` with public key `pub` (32 bytes). */
+export declare function verifyEd25519Strict(sig: Uint8Array, msg: Uint8Array, pub: Uint8Array): boolean;

package/dist/esm/ed25519.js

@@ -0,0 +1,79 @@
+// Ed25519 verification as SPEC.md 10.1 step 6 requires (libsodium-strict, RFC 8032 cofactorless):
+//   - S < L;
+//   - A and R canonically encoded (y < p; x = 0 with the sign bit set is rejected);
+//   - A and R not of small order;
+//   - [S]B - [k]A, encoded, equals R byte for byte, with k = SHA-512(R || A || M) mod L.
+//
+// @noble/curves supplies the group arithmetic. Its own verify() with zip215:false enforces
+// S < L, canonical A and R, and rejects small-order A, but it accepts small-order R and checks
+// the cofactored equation [8]([S]B - R - [k]A) = 0, which accepts some signatures the
+// cofactorless rule rejects. So the checks are done here, and noble's verify() is additionally
+// required to succeed (it is implied by the cofactorless check; it is a second opinion only).
+import { ed25519 } from '@noble/curves/ed25519';
+import { sha512 } from '@noble/hashes/sha2';
+const Point = ed25519.Point;
+const L = 2n ** 252n + 27742317777372353535851937790883648493n;
+const P = 2n ** 255n - 19n;
+function le(b) {
+    let n = 0n;
+    for (let i = b.length - 1; i >= 0; i--)
+        n = (n << 8n) | BigInt(b[i]);
+    return n;
+}
+function decodeStrict(b) {
+    const y = le(b) & ((1n << 255n) - 1n);
+    if (y >= P)
+        return null; // non-canonical encoding
+    try {
+        return Point.fromBytes(b, false); // also rejects x = 0 with the sign bit set
+    }
+    catch {
+        return null;
+    }
+}
+function equalBytes(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let d = 0;
+    for (let i = 0; i < a.length; i++)
+        d |= a[i] ^ b[i];
+    return d === 0;
+}
+/** Strict Ed25519 verification of `sig` (64 bytes) over `msg` with public key `pub` (32 bytes). */
+export function verifyEd25519Strict(sig, msg, pub) {
+    if (sig.length !== 64 || pub.length !== 32)
+        return false;
+    const rBytes = sig.subarray(0, 32);
+    const s = le(sig.subarray(32, 64));
+    if (s >= L)
+        return false;
+    const A = decodeStrict(pub);
+    const R = decodeStrict(rBytes);
+    if (!A || !R)
+        return false;
+    if (A.isSmallOrder() || R.isSmallOrder())
+        return false;
+    const h = sha512(concat(rBytes, pub, msg));
+    const k = le(h) % L;
+    // R' = [S]B - [k]A (multiplyUnsafe accepts 0; inputs are public, so variable time is fine).
+    const SB = s === 0n ? Point.ZERO : Point.BASE.multiplyUnsafe(s);
+    const kA = k === 0n ? Point.ZERO : A.multiplyUnsafe(k);
+    const rCheck = SB.subtract(kA).toBytes();
+    if (!equalBytes(rCheck, rBytes))
+        return false;
+    try {
+        return ed25519.verify(sig, msg, pub, { zip215: false });
+    }
+    catch {
+        return false;
+    }
+}
+function concat(...parts) {
+    const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let o = 0;
+    for (const p of parts) {
+        out.set(p, o);
+        o += p.length;
+    }
+    return out;
+}

package/dist/esm/envelope.d.ts

@@ -0,0 +1,38 @@
+import { type ErrorCode } from './errors.js';
+export type Outcome = 'ok' | 'stale' | 'not_covered' | 'unlicensed' | 'payment_required' | 'rate_limited' | 'error' | 'bad_request';
+/** What the client asked for (SPEC 5.5 step 5): the requested cell's id, and `asof` if the request had one. */
+export interface EnvelopeRequest {
+    cell_id: string;
+    asof?: string;
+}
+export type Trust = 'primary' | 'verified' | 'unverified';
+export interface EnvelopeResult {
+    /** True when the envelope is well formed, matches the status, and its receipt (if any) is signature-valid. */
+    ok: boolean;
+    /** "OK", E_ENVELOPE, a parse code, or the code of the embedded receipt's verification. */
+    code: 'OK' | ErrorCode;
+    /** The envelope's outcome when ok, else null. */
+    outcome: Outcome | null;
+    /** The trust label when ok and the envelope carries a receipt, else null. */
+    trust: Trust | null;
+    /** The embedded receipt's hash once it has been verified (SPEC 10.1 steps 1-6), else null. */
+    receiptHash: string | null;
+    /** Human-readable explanation. */
+    detail: string;
+    /** Where the failure was found (a JSON path such as `$.quote.amount`), or null. */
+    path: string | null;
+}
+/**
+ * Check a mesh response (SPEC 5.5): `status` is the HTTP status, `body` the response body as
+ * JSON text or bytes (a parsed object is accepted too, without duplicate-member detection), and
+ * `keys` any key source `verify` accepts, used to verify an embedded receipt through step 6.
+ * `request` is what the client asked for: `{cell_id, asof?}`, the id (SPEC 4.4) of the requested
+ * cell resolved to the fn_hash the client used, and the requested asof if there was one.
+ * Steps: strict parse; members (E_ENVELOPE); status against outcome (E_ENVELOPE); the receipt
+ * (its own codes); the receipt answers the request (E_ENVELOPE); then `trust` against the receipt
+ * and `superseded_by` against its hash (E_ENVELOPE).
+ *
+ * Never throws for an invalid body or bad key material; throws TypeError only when `status` is
+ * not an integer, `request` is malformed, or `keys` is not a key source at all.
+ */
+export declare function checkEnvelope(status: number, body: unknown, keys: unknown, request: EnvelopeRequest): EnvelopeResult;

package/dist/esm/envelope.js

@@ -0,0 +1,240 @@
+// Response envelopes (SPEC.md 5.5): the unsigned JSON body a mesh returns around a receipt.
+// Synchronous, offline; the embedded receipt is verified through step 6 with the given keys.
+import { DatumeshError, ERROR_CODES } from './errors.js';
+import { has, isObject, memberPath, sortedKeys, toJson } from './json.js';
+import { LIMITS, URL_RE, checkNumber, checkString, isHex, isInstant } from './lexical.js';
+import { sha256Hex } from './hash.js';
+import { jcsBytes } from './jcs.js';
+import { collectSources } from './keys.js';
+import { isCurrency } from './units.js';
+import { Stop, verifyEmbedded } from './verify.js';
+/** SPEC 5.5: required and optional members per outcome (besides `outcome`). */
+const MEMBERS = {
+    ok: { required: ['receipt', 'trust'], optional: ['superseded_by', 'reason'] },
+    stale: { required: ['receipt', 'trust', 'age_seconds'], optional: ['superseded_by', 'reason'] },
+    not_covered: { required: [], optional: [] },
+    unlicensed: { required: [], optional: [] },
+    payment_required: { required: ['quote'], optional: [] },
+    rate_limited: { required: ['retry_after_seconds'], optional: [] },
+    error: { required: ['error'], optional: [] },
+    bad_request: { required: ['error'], optional: [] },
+};
+const STATUS = {
+    ok: (s) => s === 200,
+    stale: (s) => s === 200,
+    not_covered: (s) => s === 404,
+    unlicensed: (s) => s === 403,
+    payment_required: (s) => s === 402,
+    rate_limited: (s) => s === 429,
+    error: (s) => s >= 500 && s <= 599,
+    bad_request: (s) => s === 400,
+};
+/** SPEC 5.5: the codes `parse` can raise (5.4), the only ones a bad_request carries. */
+const PARSE_CODES = ['E_PARSE_URI', 'E_CANON_NAME', 'E_CANON_ARG_NAME', 'E_CANON_ARG_DUPLICATE', 'E_CANON_ARG_ORDER', 'E_CANON_PERCENT', 'E_CANON_TYPE', 'E_CANON_NUMBER', 'E_CANON_DATE', 'E_CANON_INSTANT', 'E_CANON_STRING', 'E_CANON_BLOB', 'E_CANON_LIMIT', 'E_ARG_UNKNOWN', 'E_ARG_MISSING'];
+const TRUST = ['primary', 'verified', 'unverified'];
+const MAX_SECONDS = 9007199254740991;
+class Bad extends Error {
+    constructor(detail, path) {
+        super(detail);
+        this.detail = detail;
+        this.path = path;
+    }
+}
+function bad(detail, path) {
+    throw new Bad(detail, path);
+}
+/** A rule of 3.x checked inside an envelope: its own code becomes part of the E_ENVELOPE detail. */
+function inner(f, path) {
+    try {
+        f();
+    }
+    catch (e) {
+        if (e instanceof DatumeshError)
+            bad(`${e.code}: ${e.detail}`, path);
+        throw e;
+    }
+}
+/**
+ * SPEC 5.5 integer members: written 0 or [1-9][0-9]*, at most 2^53 - 1. The source text decides
+ * (`30.0`, `3e1` and `-0` are rejected); for an already-parsed body, whose text is gone, the
+ * value must be a non-negative safe integer other than -0.
+ */
+function seconds(v, text, name, path) {
+    const why = `${name} is written 0 or [1-9][0-9]*, at most 2^53 - 1`;
+    if (typeof v !== 'number')
+        bad(why, path);
+    if (text !== undefined ? !/^(0|[1-9][0-9]*)$/.test(text) : !Number.isSafeInteger(v) || Object.is(v, -0))
+        bad(why, path);
+    if (v < 0 || v > MAX_SECONDS)
+        bad(why, path);
+}
+function quote(v, path) {
+    if (!isObject(v))
+        bad('quote is an object {amount, authorise, currency}', path);
+    for (const k of ['amount', 'authorise', 'currency'])
+        if (!has(v, k))
+            bad(`quote has no ${k}`, path);
+    for (const k of sortedKeys(v))
+        if (!['amount', 'authorise', 'currency'].includes(k))
+            bad(`quote has an unexpected member ${JSON.stringify(k)}`, path);
+    const amount = v.amount;
+    const ap = memberPath(path, 'amount');
+    if (typeof amount !== 'string')
+        bad('amount is a decimal string (SPEC 3.1)', ap);
+    inner(() => checkNumber(amount, ap), ap);
+    if (amount.startsWith('-') || amount === '0')
+        bad('amount is greater than zero', ap);
+    const url = v.authorise;
+    const up = memberPath(path, 'authorise');
+    if (typeof url !== 'string' || !URL_RE.test(url) || url.length > LIMITS.licence_url)
+        bad('authorise is an https:// URL in the form of a licence URL (SPEC 8.1)', up);
+    if (!isCurrency(v.currency))
+        bad('currency is a currency code from units.md', memberPath(path, 'currency'));
+}
+/** Step 2: members against the table and their rules. Returns the outcome. */
+function members(o, numbers) {
+    if (!isObject(o) || typeof o.outcome !== 'string')
+        bad('an envelope is an object with a string outcome', '$');
+    const outcome = o.outcome;
+    if (!Object.prototype.hasOwnProperty.call(MEMBERS, outcome))
+        bad(`unknown outcome ${JSON.stringify(outcome)}`, '$.outcome');
+    const { required, optional } = MEMBERS[outcome];
+    for (const k of required)
+        if (!has(o, k))
+            bad(`outcome ${outcome} requires ${k}`, '$');
+    for (const k of sortedKeys(o))
+        if (k !== 'outcome' && !required.includes(k) && !optional.includes(k))
+            bad(`member ${JSON.stringify(k)} is not allowed with outcome ${outcome}`, memberPath('$', k));
+    if (has(o, 'reason') && !has(o, 'superseded_by'))
+        bad('reason is only present with superseded_by', '$.reason');
+    for (const k of sortedKeys(o)) {
+        const v = o[k];
+        const p = memberPath('$', k);
+        switch (k) {
+            case 'age_seconds':
+            case 'retry_after_seconds':
+                seconds(v, numbers.get(p), k, p);
+                break;
+            case 'error':
+                if (outcome === 'bad_request') {
+                    if (typeof v !== 'string' || !PARSE_CODES.includes(v))
+                        bad('a bad_request carries a code that parsing a cell URI raises (SPEC 5.4)', p);
+                }
+                else if (typeof v !== 'string' || v === 'E_ENVELOPE' || !ERROR_CODES.includes(v)) {
+                    bad('error is a code from SPEC.md 10.2 other than E_ENVELOPE', p);
+                }
+                break;
+            case 'quote':
+                quote(v, p);
+                break;
+            case 'reason':
+                if (typeof v !== 'string')
+                    bad('reason is a string', p);
+                if (v === '')
+                    bad('reason must not be empty', p);
+                inner(() => checkString(v, p, { limit: LIMITS.summary }), p);
+                break;
+            case 'receipt':
+                if (!isObject(v))
+                    bad('receipt is a receipt object', p);
+                break;
+            case 'superseded_by':
+                if (typeof v !== 'string' || !isHex(v, 64))
+                    bad('superseded_by is a receipt hash: 64 lowercase hex digits', p);
+                break;
+            case 'trust':
+                if (typeof v !== 'string' || !TRUST.includes(v))
+                    bad('trust is one of primary, verified, unverified', p);
+                break;
+        }
+    }
+    return outcome;
+}
+function checkRequest(request) {
+    const ok = isObject(request) &&
+        typeof request.cell_id === 'string' &&
+        isHex(request.cell_id, 64) &&
+        Object.keys(request).every((k) => k === 'cell_id' || k === 'asof') &&
+        (!has(request, 'asof') || (typeof request.asof === 'string' && isInstant(request.asof)));
+    if (!ok)
+        throw new TypeError('request must be {cell_id: <64 lowercase hex>, asof?: <instant>}: the cell id of the requested cell (resolved to the fn_hash used) and its asof, if the request had one');
+}
+const hostOf = (s, sep) => {
+    const i = s.indexOf(sep);
+    return i < 0 ? s : s.slice(0, i);
+};
+/**
+ * Check a mesh response (SPEC 5.5): `status` is the HTTP status, `body` the response body as
+ * JSON text or bytes (a parsed object is accepted too, without duplicate-member detection), and
+ * `keys` any key source `verify` accepts, used to verify an embedded receipt through step 6.
+ * `request` is what the client asked for: `{cell_id, asof?}`, the id (SPEC 4.4) of the requested
+ * cell resolved to the fn_hash the client used, and the requested asof if there was one.
+ * Steps: strict parse; members (E_ENVELOPE); status against outcome (E_ENVELOPE); the receipt
+ * (its own codes); the receipt answers the request (E_ENVELOPE); then `trust` against the receipt
+ * and `superseded_by` against its hash (E_ENVELOPE).
+ *
+ * Never throws for an invalid body or bad key material; throws TypeError only when `status` is
+ * not an integer, `request` is malformed, or `keys` is not a key source at all.
+ */
+export function checkEnvelope(status, body, keys, request) {
+    if (typeof status !== 'number' || !Number.isInteger(status))
+        throw new TypeError('status must be the HTTP status as an integer');
+    checkRequest(request);
+    const sources = collectSources(keys);
+    const fail = (code, detail, path, receiptHash = null) => ({ ok: false, code, outcome: null, trust: null, receiptHash, detail, path });
+    let o;
+    const numbers = new Map();
+    try {
+        o = toJson(body, numbers); // step 1
+    }
+    catch (e) {
+        if (e instanceof DatumeshError)
+            return fail(e.code, e.detail, e.path);
+        throw e;
+    }
+    let outcome;
+    try {
+        outcome = members(o, numbers); // step 2
+        if (!STATUS[outcome](status))
+            bad(`status ${status} does not match outcome ${outcome}`, '$.outcome'); // step 3
+    }
+    catch (e) {
+        if (e instanceof Bad)
+            return fail('E_ENVELOPE', e.detail, e.path);
+        throw e;
+    }
+    const env = o;
+    if (!has(env, 'receipt'))
+        return { ok: true, code: 'OK', outcome, trust: null, receiptHash: null, detail: `outcome ${outcome}`, path: null };
+    // Step 4.
+    let r;
+    try {
+        r = verifyEmbedded(env.receipt, sources);
+    }
+    catch (e) {
+        if (e instanceof Stop)
+            return fail(e.code, `receipt: ${e.detail}`, e.path === null ? '$.receipt' : e.path.replace(/^\$/, '$.receipt'));
+        throw e;
+    }
+    // Step 5: the receipt answers the request.
+    const cellId = sha256Hex(jcsBytes(r.receipt.cell));
+    if (cellId !== request.cell_id)
+        return fail('E_ENVELOPE', `the receipt is for cell ${cellId}, not the requested ${request.cell_id}`, '$.receipt.cell', r.hash);
+    // With a requested asof: equal for ok; at or before it for stale (D31). Instants are fixed
+    // width, so string order is time order (SPEC 3.3).
+    const asof = r.receipt.asof;
+    if (request.asof !== undefined && (outcome === 'stale' ? !(asof <= request.asof) : asof !== request.asof)) {
+        const want = outcome === 'stale' ? `at or before the requested ${request.asof}` : `the requested ${request.asof}`;
+        return fail('E_ENVELOPE', `the receipt answers asof ${asof}, not ${want}`, '$.receipt.asof', r.hash);
+    }
+    // Step 6.
+    const trust = env.trust;
+    const cell = r.receipt.cell;
+    const primary = hostOf(r.receipt.computed_by, '#') === hostOf(cell.ns, '/') && r.receipt.inputs.length === 0;
+    if ((trust === 'primary') !== primary) {
+        return fail('E_ENVELOPE', primary ? 'the receipt is primary (signed by its namespace host, no inputs): trust must be primary' : 'trust primary needs a receipt signed by the host of cell.ns with no inputs', '$.trust', r.hash);
+    }
+    if (env.superseded_by === r.hash)
+        return fail('E_ENVELOPE', 'superseded_by is the receipt itself', '$.superseded_by', r.hash);
+    return { ok: true, code: 'OK', outcome, trust, receiptHash: r.hash, detail: `outcome ${outcome}, trust ${trust}, receipt signed by ${r.receipt.computed_by}`, path: null };
+}

package/dist/esm/errors.d.ts

@@ -0,0 +1,14 @@
+/** The spec revision this library conforms to. */
+export declare const SPEC_VERSION = "spec-0.2.0";
+/** Every error code defined by SPEC.md 10.2, in the order of that table. */
+export declare const ERROR_CODES: readonly ["E_PARSE_JSON", "E_PARSE_DUPLICATE_KEY", "E_PARSE_URI", "E_SCHEMA", "E_CANON_NAME", "E_CANON_ARG_NAME", "E_CANON_ARG_DUPLICATE", "E_CANON_ARG_ORDER", "E_CANON_PERCENT", "E_CANON_TYPE", "E_CANON_NUMBER", "E_CANON_UNIT", "E_CANON_DATE", "E_CANON_INSTANT", "E_CANON_STRING", "E_CANON_BLOB", "E_CANON_HEX", "E_CANON_LICENCE", "E_CANON_SET", "E_CANON_LIMIT", "E_SLICE", "E_PUBLISHER_MISMATCH", "E_VALID_MISMATCH", "E_TIME_ORDER", "E_ARG_UNKNOWN", "E_ARG_MISSING", "E_KEY_UNAVAILABLE", "E_KEY_DOC", "E_KEY_UNKNOWN", "E_KEY_NOT_VALID", "E_SIGNATURE", "E_FN_UNAVAILABLE", "E_FN_HASH_MISMATCH", "E_ARG_TYPE", "E_RETURN_TYPE", "E_INPUT_UNAVAILABLE", "E_INPUT_INVALID", "E_INPUT_UNDECLARED", "E_VALUE_MISMATCH", "E_BLOB_MISMATCH", "E_ENVELOPE"];
+export type ErrorCode = (typeof ERROR_CODES)[number];
+/** A Datumesh rule was broken. `code` is a SPEC.md 10.2 code; `path` locates the failure. */
+export declare class DatumeshError extends Error {
+    readonly code: ErrorCode;
+    readonly path: string | null;
+    readonly detail: string;
+    constructor(code: ErrorCode, detail: string, path?: string | null);
+}
+/** Shorthand used throughout: throw a DatumeshError. */
+export declare function fail(code: ErrorCode, detail: string, path?: string | null): never;

package/dist/esm/errors.js

@@ -0,0 +1,60 @@
+/** The spec revision this library conforms to. */
+export const SPEC_VERSION = 'spec-0.2.0';
+/** Every error code defined by SPEC.md 10.2, in the order of that table. */
+export const ERROR_CODES = [
+    'E_PARSE_JSON',
+    'E_PARSE_DUPLICATE_KEY',
+    'E_PARSE_URI',
+    'E_SCHEMA',
+    'E_CANON_NAME',
+    'E_CANON_ARG_NAME',
+    'E_CANON_ARG_DUPLICATE',
+    'E_CANON_ARG_ORDER',
+    'E_CANON_PERCENT',
+    'E_CANON_TYPE',
+    'E_CANON_NUMBER',
+    'E_CANON_UNIT',
+    'E_CANON_DATE',
+    'E_CANON_INSTANT',
+    'E_CANON_STRING',
+    'E_CANON_BLOB',
+    'E_CANON_HEX',
+    'E_CANON_LICENCE',
+    'E_CANON_SET',
+    'E_CANON_LIMIT',
+    'E_SLICE',
+    'E_PUBLISHER_MISMATCH',
+    'E_VALID_MISMATCH',
+    'E_TIME_ORDER',
+    'E_ARG_UNKNOWN',
+    'E_ARG_MISSING',
+    'E_KEY_UNAVAILABLE',
+    'E_KEY_DOC',
+    'E_KEY_UNKNOWN',
+    'E_KEY_NOT_VALID',
+    'E_SIGNATURE',
+    'E_FN_UNAVAILABLE',
+    'E_FN_HASH_MISMATCH',
+    'E_ARG_TYPE',
+    'E_RETURN_TYPE',
+    'E_INPUT_UNAVAILABLE',
+    'E_INPUT_INVALID',
+    'E_INPUT_UNDECLARED',
+    'E_VALUE_MISMATCH',
+    'E_BLOB_MISMATCH',
+    'E_ENVELOPE',
+];
+/** A Datumesh rule was broken. `code` is a SPEC.md 10.2 code; `path` locates the failure. */
+export class DatumeshError extends Error {
+    constructor(code, detail, path = null) {
+        super(`${code}${path ? ` at ${path}` : ''}: ${detail}`);
+        this.name = 'DatumeshError';
+        this.code = code;
+        this.path = path;
+        this.detail = detail;
+    }
+}
+/** Shorthand used throughout: throw a DatumeshError. */
+export function fail(code, detail, path = null) {
+    throw new DatumeshError(code, detail, path);
+}