@datumesh/verify 0.0.0-stage → 0.2.0

package/dist/cjs/validate.js

@@ -0,0 +1,408 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KINDS = void 0;
+exports.structSignature = structSignature;
+exports.canonSignature = canonSignature;
+exports.returnType = returnType;
+exports.validate = validate;
+exports.cellUnit = cellUnit;
+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");
+const units_js_1 = require("./units.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'], ['unit'], p);
+        expectString(d, 'type', p);
+        if ((0, json_js_1.has)(d, 'unit'))
+            (0, units_js_1.structUnit)(d.unit, (0, json_js_1.memberPath)(p, 'unit'));
+        if (typeof d.valid !== 'boolean')
+            (0, errors_js_1.fail)('E_SCHEMA', 'valid must be a boolean', (0, json_js_1.memberPath)(p, 'valid'));
+    }
+    // SPEC 7: a type name, or {"type", "unit"} (the unit's absence is E_CANON_UNIT, in step 3).
+    const rp = (0, json_js_1.memberPath)(path, 'returns');
+    const r = sig.returns;
+    if (typeof r === 'string')
+        return;
+    if (!(0, json_js_1.isObject)(r))
+        (0, errors_js_1.fail)('E_SCHEMA', 'returns must be a type name or an object', rp);
+    members(r, ['type'], ['unit'], rp);
+    expectString(r, 'type', rp);
+    if ((0, json_js_1.has)(r, 'unit'))
+        (0, units_js_1.structUnit)(r.unit, (0, json_js_1.memberPath)(rp, 'unit'));
+}
+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];
+        // SPEC 7: type, then unit, then valid.
+        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.type === 'number') {
+            if (!(0, json_js_1.has)(d, 'unit'))
+                (0, errors_js_1.fail)('E_CANON_UNIT', 'a number argument declares its unit', p);
+            (0, units_js_1.canonUnit)(d.unit, args, (0, json_js_1.memberPath)(p, 'unit'));
+        }
+        else if ((0, json_js_1.has)(d, 'unit')) {
+            (0, errors_js_1.fail)('E_CANON_UNIT', 'only number arguments have a unit', (0, json_js_1.memberPath)(p, 'unit'));
+        }
+        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);
+        }
+    }
+    const rp = (0, json_js_1.memberPath)(path, 'returns');
+    const r = sig.returns;
+    if (typeof r === 'string') {
+        if (!(0, lexical_js_1.isTypeName)(r))
+            (0, errors_js_1.fail)('E_CANON_TYPE', `unknown type ${JSON.stringify(r)}`, rp);
+        if (r === 'number')
+            (0, errors_js_1.fail)('E_CANON_UNIT', 'a number return is {"type": "number", "unit": ...}, not the bare name', rp);
+        return;
+    }
+    const o = r;
+    if (!(0, lexical_js_1.isTypeName)(o.type))
+        (0, errors_js_1.fail)('E_CANON_TYPE', `unknown type ${JSON.stringify(o.type)}`, (0, json_js_1.memberPath)(rp, 'type'));
+    if (o.type !== 'number')
+        (0, errors_js_1.fail)('E_CANON_UNIT', 'only a number return is written as an object', rp);
+    if (!(0, json_js_1.has)(o, 'unit'))
+        (0, errors_js_1.fail)('E_CANON_UNIT', 'a number return declares its unit', rp);
+    (0, units_js_1.canonUnit)(o.unit, args, (0, json_js_1.memberPath)(rp, 'unit'));
+}
+/** The return type named by a valid signature's `returns` (SPEC 10.1 step 7.4). */
+function returnType(sig) {
+    const r = sig.returns;
+    return typeof r === 'string' ? r : r.type;
+}
+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;
+    }
+}
+/**
+ * The unit of a cell's value (SPEC 7.1, units.md 3). Order: the cell (structure, canonical
+ * form), fn_hash against the descriptor (E_FN_HASH_MISMATCH), the descriptor (structure,
+ * canonical form), then substitution.
+ */
+function cellUnit(desc, cell, fnHash) {
+    structCell(cell, 'cell', false);
+    canonCell(cell, 'cell');
+    if (fnHash(desc) !== cell.fn_hash)
+        (0, errors_js_1.fail)('E_FN_HASH_MISMATCH', 'the descriptor does not hash to cell.fn_hash', 'descriptor');
+    structFunction(desc, 'descriptor');
+    canonFunction(desc, 'descriptor');
+    const sig = desc.signature;
+    return (0, units_js_1.resolveUnit)(sig.returns, cell.args, 'descriptor.signature.returns', 'cell.args');
+}
+/** 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,57 @@
+import { type ErrorCode } from './errors.js';
+import { type JsonObject, type JsonValue } from './json.js';
+import { type Sources } from './keys.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;
+    /** True only when blob content was supplied and step 7.7 ran and passed. Does not change `level`. */
+    blobChecked: boolean;
+}
+/** 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;
+    };
+}
+declare class Stop extends Error {
+    readonly code: ErrorCode;
+    readonly detail: string;
+    readonly path: string | null;
+    constructor(code: ErrorCode, detail: string, path: string | null);
+}
+/**
+ * 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.
+ */
+export declare function verify(receipt: unknown, keys: unknown, recomputeArg?: Recompute | null, blob?: Uint8Array | ArrayBuffer | null): VerifyResult;
+/** Steps 1-6 for an already-parsed receipt (used by checkEnvelope). Throws a Stop. */
+export declare function verifyEmbedded(receipt: JsonValue, sources: Sources): {
+    receipt: JsonObject;
+    hash: string;
+};
+export { Stop };