@datumesh/verify 0.0.0-stage → 0.1.1

package/dist/cjs/validate.js

@@ -0,0 +1,349 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KINDS = void 0;
+exports.structSignature = structSignature;
+exports.canonSignature = canonSignature;
+exports.validate = validate;
+exports.receiptStructure = receiptStructure;
+exports.receiptCanonicalAndConsistent = receiptCanonicalAndConsistent;
+exports.inferKind = inferKind;
+// Structure (SPEC 10.1 step 2, E_SCHEMA), canonical form (step 3) and receipt consistency
+// (step 4) for every kind of Datumesh object. Within a step members are examined in JCS order,
+// depth first; at each object its member set is checked before its members.
+const errors_js_1 = require("./errors.js");
+const json_js_1 = require("./json.js");
+const lexical_js_1 = require("./lexical.js");
+exports.KINDS = ['scalar', 'cell', 'ref', 'function', 'receipt', 'jcs'];
+const SLICE = '*';
+// ---------------------------------------------------------------- step 2: structure
+function expectObject(v, path) {
+    if (!(0, json_js_1.isObject)(v))
+        (0, errors_js_1.fail)('E_SCHEMA', 'expected an object', path);
+    return v;
+}
+function members(o, required, optional, path) {
+    const names = new Set([...Object.keys(o), ...required]);
+    for (const n of [...names].sort()) {
+        if (!(0, json_js_1.has)(o, n))
+            (0, errors_js_1.fail)('E_SCHEMA', `missing member ${JSON.stringify(n)}`, path);
+        if (!required.includes(n) && !optional.includes(n))
+            (0, errors_js_1.fail)('E_SCHEMA', `unexpected member ${JSON.stringify(n)}`, path);
+    }
+}
+function expectString(o, k, path) {
+    if (typeof o[k] !== 'string')
+        (0, errors_js_1.fail)('E_SCHEMA', `${k} must be a string`, (0, json_js_1.memberPath)(path, k));
+}
+function structScalar(v, path) {
+    const o = expectObject(v, path);
+    members(o, ['type', 'value'], [], path);
+    expectString(o, 'type', path);
+    if (typeof o.value !== 'string' && typeof o.value !== 'boolean') {
+        (0, errors_js_1.fail)('E_SCHEMA', 'value must be a string or a boolean', (0, json_js_1.memberPath)(path, 'value'));
+    }
+}
+function structArgs(v, path) {
+    const o = expectObject(v, path);
+    for (const k of (0, json_js_1.sortedKeys)(o)) {
+        if (o[k] === SLICE)
+            continue;
+        structScalar(o[k], (0, json_js_1.memberPath)(path, k));
+    }
+}
+function structCell(v, path, ref) {
+    const o = expectObject(v, path);
+    if (ref)
+        members(o, ['args', 'fn', 'ns'], ['asof'], path);
+    else
+        members(o, ['args', 'fn', 'fn_hash', 'ns'], [], path);
+    for (const k of (0, json_js_1.sortedKeys)(o)) {
+        if (k === 'args')
+            structArgs(o.args, (0, json_js_1.memberPath)(path, 'args'));
+        else
+            expectString(o, k, path);
+    }
+}
+function structFunction(v, path) {
+    const o = expectObject(v, path);
+    members(o, ['code', 'inputs', 'signature'], [], path);
+    const codePath = (0, json_js_1.memberPath)(path, 'code');
+    const code = expectObject(o.code, codePath);
+    members(code, ['body', 'lang'], [], codePath);
+    expectString(code, 'body', codePath);
+    expectString(code, 'lang', codePath);
+    const inputs = o.inputs;
+    if (!Array.isArray(inputs) || inputs.some((x) => typeof x !== 'string')) {
+        (0, errors_js_1.fail)('E_SCHEMA', 'inputs must be an array of strings', (0, json_js_1.memberPath)(path, 'inputs'));
+    }
+    structSignature(o.signature, (0, json_js_1.memberPath)(path, 'signature'));
+}
+function structSignature(v, path) {
+    const sig = expectObject(v, path);
+    members(sig, ['args', 'returns'], [], path);
+    const argsPath = (0, json_js_1.memberPath)(path, 'args');
+    const args = expectObject(sig.args, argsPath);
+    for (const k of (0, json_js_1.sortedKeys)(args)) {
+        const p = (0, json_js_1.memberPath)(argsPath, k);
+        const d = expectObject(args[k], p);
+        members(d, ['type', 'valid'], [], p);
+        expectString(d, 'type', p);
+        if (typeof d.valid !== 'boolean')
+            (0, errors_js_1.fail)('E_SCHEMA', 'valid must be a boolean', (0, json_js_1.memberPath)(p, 'valid'));
+    }
+    expectString(sig, 'returns', path);
+}
+const RECEIPT_MEMBERS = [
+    'asof',
+    'cell',
+    'computed_by',
+    'inputs',
+    'issued',
+    'licence',
+    'proto',
+    'publisher',
+    'sig',
+    'summary',
+    'tx',
+    'type',
+    'valid',
+    'value',
+];
+function structReceipt(v, path) {
+    const o = expectObject(v, path);
+    members(o, RECEIPT_MEMBERS, [], path);
+    for (const k of (0, json_js_1.sortedKeys)(o)) {
+        const p = (0, json_js_1.memberPath)(path, k);
+        switch (k) {
+            case 'cell':
+                structCell(o.cell, p, false);
+                break;
+            case 'inputs': {
+                const a = o.inputs;
+                if (!Array.isArray(a) || a.some((x) => typeof x !== 'string'))
+                    (0, errors_js_1.fail)('E_SCHEMA', 'inputs must be an array of strings', p);
+                break;
+            }
+            case 'valid':
+                structArgs(o.valid, p);
+                break;
+            case 'value':
+                if (typeof o.value !== 'string' && typeof o.value !== 'boolean')
+                    (0, errors_js_1.fail)('E_SCHEMA', 'value must be a string or a boolean', p);
+                break;
+            case 'proto':
+                expectString(o, k, path);
+                if (o.proto !== 'datumesh/1')
+                    (0, errors_js_1.fail)('E_SCHEMA', "proto must be 'datumesh/1'", p);
+                break;
+            default:
+                expectString(o, k, path);
+        }
+    }
+}
+// ---------------------------------------------------------------- step 3: canonical form
+function canonScalar(o, path) {
+    const t = o.type;
+    if (!(0, lexical_js_1.isTypeName)(t))
+        (0, errors_js_1.fail)('E_CANON_TYPE', `unknown type ${JSON.stringify(t)}`, (0, json_js_1.memberPath)(path, 'type'));
+    (0, lexical_js_1.checkTypedValue)(t, o.value, (0, json_js_1.memberPath)(path, 'value'));
+}
+function canonArgs(o, path) {
+    if (Object.keys(o).length > lexical_js_1.LIMITS.args)
+        (0, errors_js_1.fail)('E_CANON_LIMIT', `more than ${lexical_js_1.LIMITS.args} arguments`, path);
+    for (const k of (0, json_js_1.sortedKeys)(o)) {
+        const p = (0, json_js_1.memberPath)(path, k);
+        (0, lexical_js_1.checkArgName)(k, p);
+        if (o[k] !== SLICE)
+            canonScalar(o[k], p);
+    }
+}
+function canonCell(o, path) {
+    for (const k of (0, json_js_1.sortedKeys)(o)) {
+        const p = (0, json_js_1.memberPath)(path, k);
+        const v = o[k];
+        if (k === 'args')
+            canonArgs(o.args, p);
+        else if (k === 'asof')
+            (0, lexical_js_1.checkInstant)(v, p);
+        else if (k === 'fn')
+            (0, lexical_js_1.checkName)(v, p);
+        else if (k === 'fn_hash')
+            (0, lexical_js_1.checkHex)(v, 64, p);
+        else if (k === 'ns')
+            (0, lexical_js_1.checkNamespace)(v, p);
+    }
+    if (o.ns.length + 1 + o.fn.length > lexical_js_1.LIMITS.function_name) {
+        (0, errors_js_1.fail)('E_CANON_LIMIT', 'function name too long', path);
+    }
+}
+function canonStringSet(a, path, each) {
+    a.forEach((s, i) => each(s, `${path}[${i}]`));
+    for (let i = 1; i < a.length; i++) {
+        if (!(a[i - 1] < a[i]))
+            (0, errors_js_1.fail)('E_CANON_SET', 'entries must be strictly ascending', path);
+    }
+    if (a.length > lexical_js_1.LIMITS.inputs)
+        (0, errors_js_1.fail)('E_CANON_LIMIT', `more than ${lexical_js_1.LIMITS.inputs} inputs`, path);
+}
+function canonSignature(sig, path) {
+    const argsPath = (0, json_js_1.memberPath)(path, 'args');
+    const args = sig.args;
+    if (Object.keys(args).length > lexical_js_1.LIMITS.args)
+        (0, errors_js_1.fail)('E_CANON_LIMIT', `more than ${lexical_js_1.LIMITS.args} arguments`, argsPath);
+    for (const k of (0, json_js_1.sortedKeys)(args)) {
+        const p = (0, json_js_1.memberPath)(argsPath, k);
+        (0, lexical_js_1.checkArgName)(k, p);
+        const d = args[k];
+        if (!(0, lexical_js_1.isTypeName)(d.type))
+            (0, errors_js_1.fail)('E_CANON_TYPE', `unknown type ${JSON.stringify(d.type)}`, (0, json_js_1.memberPath)(p, 'type'));
+        if (d.valid === true && !lexical_js_1.VALID_TIME_TYPES.includes(d.type)) {
+            (0, errors_js_1.fail)('E_CANON_TYPE', 'a valid-time argument must be a date, instant or string', p);
+        }
+    }
+    if (!(0, lexical_js_1.isTypeName)(sig.returns))
+        (0, errors_js_1.fail)('E_CANON_TYPE', `unknown type ${JSON.stringify(sig.returns)}`, (0, json_js_1.memberPath)(path, 'returns'));
+}
+function canonFunction(o, path) {
+    const code = o.code;
+    const codePath = (0, json_js_1.memberPath)(path, 'code');
+    (0, lexical_js_1.checkString)(code.body, (0, json_js_1.memberPath)(codePath, 'body'), { body: true });
+    (0, lexical_js_1.checkName)(code.lang, (0, json_js_1.memberPath)(codePath, 'lang'));
+    canonStringSet(o.inputs, (0, json_js_1.memberPath)(path, 'inputs'), lexical_js_1.checkFunctionName);
+    canonSignature(o.signature, (0, json_js_1.memberPath)(path, 'signature'));
+}
+function canonReceipt(o, path) {
+    for (const k of (0, json_js_1.sortedKeys)(o)) {
+        const p = (0, json_js_1.memberPath)(path, k);
+        const v = o[k];
+        switch (k) {
+            case 'asof':
+            case 'issued':
+            case 'tx':
+                (0, lexical_js_1.checkInstant)(v, p);
+                break;
+            case 'cell':
+                canonCell(v, p);
+                break;
+            case 'computed_by':
+                (0, lexical_js_1.checkKeyRef)(v, p);
+                break;
+            case 'inputs':
+                canonStringSet(v, p, (s, q) => (0, lexical_js_1.checkHex)(s, 64, q));
+                break;
+            case 'licence':
+                (0, lexical_js_1.checkLicence)(v, p);
+                break;
+            case 'publisher':
+                (0, lexical_js_1.checkNamespace)(v, p);
+                break;
+            case 'sig':
+                (0, lexical_js_1.checkHex)(v, 128, p);
+                break;
+            case 'summary':
+                if (v === '')
+                    (0, errors_js_1.fail)('E_CANON_STRING', 'summary must not be empty', p);
+                (0, lexical_js_1.checkString)(v, p, { limit: lexical_js_1.LIMITS.summary });
+                break;
+            case 'type':
+                if (!(0, lexical_js_1.isTypeName)(v))
+                    (0, errors_js_1.fail)('E_CANON_TYPE', `unknown type ${JSON.stringify(v)}`, p);
+                break;
+            case 'valid':
+                canonArgs(v, p);
+                break;
+            case 'value':
+                (0, lexical_js_1.checkTypedValue)(o.type, v, p);
+                break;
+        }
+    }
+}
+// ---------------------------------------------------------------- step 4: consistency
+function consistency(o, path) {
+    const cell = o.cell;
+    const args = cell.args;
+    const valid = o.valid;
+    const argsPath = (0, json_js_1.memberPath)((0, json_js_1.memberPath)(path, 'cell'), 'args');
+    const validPath = (0, json_js_1.memberPath)(path, 'valid');
+    for (const k of (0, json_js_1.sortedKeys)(args)) {
+        if (args[k] === SLICE)
+            (0, errors_js_1.fail)('E_SLICE', 'a receipt is for one cell, not a slice', (0, json_js_1.memberPath)(argsPath, k));
+    }
+    for (const k of (0, json_js_1.sortedKeys)(valid)) {
+        if (valid[k] === SLICE)
+            (0, errors_js_1.fail)('E_SLICE', 'a receipt is for one cell, not a slice', (0, json_js_1.memberPath)(validPath, k));
+    }
+    if (o.publisher !== cell.ns)
+        (0, errors_js_1.fail)('E_PUBLISHER_MISMATCH', 'publisher must equal cell.ns', (0, json_js_1.memberPath)(path, 'publisher'));
+    for (const k of (0, json_js_1.sortedKeys)(valid)) {
+        const v = valid[k];
+        const a = (0, json_js_1.has)(args, k) ? args[k] : null;
+        if (!a || a.type !== v.type || a.value !== v.value) {
+            (0, errors_js_1.fail)('E_VALID_MISMATCH', `valid.${k} does not echo cell.args.${k}`, validPath);
+        }
+        if (!lexical_js_1.VALID_TIME_TYPES.includes(v.type)) {
+            (0, errors_js_1.fail)('E_VALID_MISMATCH', 'valid-time arguments are dates, instants or strings', validPath);
+        }
+    }
+    const tx = o.tx;
+    const asof = o.asof;
+    const issued = o.issued;
+    // Instants are fixed width, so string order is time order (SPEC 3.3).
+    if (!(tx <= asof && asof <= issued))
+        (0, errors_js_1.fail)('E_TIME_ORDER', 'requires tx <= asof <= issued', path);
+}
+// ---------------------------------------------------------------- entry points
+/** Validate `v` as `kind` (steps 2-3; for receipts also step 4). Throws DatumeshError. */
+function validate(v, kind, path = '$') {
+    switch (kind) {
+        case 'jcs':
+            return;
+        case 'scalar':
+            structScalar(v, path);
+            canonScalar(v, path);
+            return;
+        case 'cell':
+        case 'ref':
+            structCell(v, path, kind === 'ref');
+            canonCell(v, path);
+            return;
+        case 'function':
+            structFunction(v, path);
+            canonFunction(v, path);
+            return;
+        case 'receipt':
+            structReceipt(v, path);
+            canonReceipt(v, path);
+            consistency(v, path);
+            return;
+    }
+}
+/** Receipt step 2 only: true when the receipt has the right members and JSON types. */
+function receiptStructure(v) {
+    structReceipt(v, '$');
+}
+/** Receipt steps 3 and 4, after receiptStructure has passed. */
+function receiptCanonicalAndConsistent(v) {
+    canonReceipt(v, '$');
+    consistency(v, '$');
+}
+/**
+ * Infer the kind of an object from its members when the caller gives none: a receipt has
+ * `sig`, `proto` or `computed_by`; a descriptor `signature` or `code`; a cell `fn_hash`; a cell
+ * reference `fn`, `ns` or `args`; a typed scalar `type` or `value`. Anything else is E_SCHEMA.
+ */
+function inferKind(v) {
+    if (!(0, json_js_1.isObject)(v))
+        (0, errors_js_1.fail)('E_SCHEMA', 'cannot infer the kind of a non-object; pass kind', '$');
+    const h = (k) => (0, json_js_1.has)(v, k);
+    if (h('sig') || h('proto') || h('computed_by'))
+        return 'receipt';
+    if (h('signature') || h('code'))
+        return 'function';
+    if (h('fn_hash'))
+        return 'cell';
+    if (h('fn') || h('ns') || h('args'))
+        return 'ref';
+    if (h('type') || h('value'))
+        return 'scalar';
+    (0, errors_js_1.fail)('E_SCHEMA', 'cannot infer the kind from the members; pass kind', '$');
+}

package/dist/cjs/verify.d.ts

@@ -0,0 +1,38 @@
+import { type ErrorCode } from './errors.js';
+export interface VerifyResult {
+    /** True when the receipt is signature-valid (and, if recompute was given, fully verified). */
+    ok: boolean;
+    /** "OK" or a SPEC 10.2 error code. */
+    code: 'OK' | ErrorCode;
+    /** "signed" (steps 1-6) or "recomputed" (steps 1-7) when ok, else null. */
+    level: 'signed' | 'recomputed' | null;
+    /** The receipt hash, once the receipt has the structure of a receipt (step 2), else null. */
+    hash: string | null;
+    /** The `computed_by` key reference when ok, else null. */
+    key: string | null;
+    /** Human-readable explanation. */
+    detail: string;
+    /** Where the failure was found (a JSON path like `$.cell.args.base`), or null. */
+    path: string | null;
+}
+/** Input for SPEC 10.1 step 7. The library does not evaluate functions; `value` is the result. */
+export interface Recompute {
+    /** The function descriptor for cell.fn_hash (object or JSON text); absent: E_FN_UNAVAILABLE. */
+    descriptor?: unknown;
+    /** Input receipts by receipt hash, as JSON text (or bytes, or parsed objects). */
+    inputs?: Record<string, unknown>;
+    /** What evaluating the function produced: a typed scalar. */
+    value: {
+        type: string;
+        value: string | boolean;
+    };
+}
+/**
+ * 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.
+ *
+ * Never throws for an invalid receipt or bad key material; throws TypeError only when an
+ * argument is of the wrong kind altogether.
+ */
+export declare function verify(receipt: unknown, keys: unknown, recomputeArg?: Recompute | null): VerifyResult;

package/dist/cjs/verify.js

@@ -0,0 +1,192 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verify = verify;
+// 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 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;
+    }
+}
+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.
+    if (receipt.type !== sig.returns)
+        stop('E_RETURN_TYPE', `function returns ${String(sig.returns)}`, '$.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');
+}
+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.
+ *
+ * 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) {
+    const sources = (0, keys_js_1.collectSources)(keys);
+    const rc = checkRecomputeArg(recomputeArg);
+    let hash = null;
+    try {
+        const { receipt: r } = verifySigned(receipt, sources, (h) => (hash = h));
+        if (rc)
+            recompute(r, rc, sources);
+        return {
+            ok: true,
+            code: 'OK',
+            level: rc ? 'recomputed' : 'signed',
+            hash,
+            key: r.computed_by,
+            detail: rc ? 'fully verified: signature valid and value recomputed' : `signature-valid: signed by ${r.computed_by}`,
+            path: null,
+        };
+    }
+    catch (e) {
+        if (e instanceof Stop)
+            return { ok: false, code: e.code, level: null, hash, key: null, detail: e.detail, path: e.path };
+        throw e; // a bug in this library, not a property of the receipt
+    }
+}

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/errors.d.ts

@@ -0,0 +1,14 @@
+/** The spec revision this library conforms to. */
+export declare const SPEC_VERSION = "spec-0.1.1";
+/** 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_DATE", "E_CANON_INSTANT", "E_CANON_STRING", "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"];
+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;