@datumesh/verify 0.1.1 → 0.2.1

package/dist/cjs/verify.d.ts

@@ -1,4 +1,6 @@
 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;
@@ -14,6 +16,8 @@ export interface VerifyResult {
     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 {
@@ -27,12 +31,27 @@ export interface Recompute {
         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.
+ * {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): VerifyResult;
+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 };

package/dist/cjs/verify.js

@@ -1,6 +1,8 @@
 "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");
@@ -8,6 +10,7 @@ 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) {
@@ -17,6 +20,7 @@ class Stop extends Error {
         this.path = path;
     }
 }
+exports.Stop = Stop;
 function stop(code, detail, path = '$') {
     throw new Stop(code, detail, path);
 }
@@ -106,9 +110,10 @@ function recompute(receipt, rc, sources) {
     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.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 ?? {};
@@ -144,6 +149,28 @@ function recompute(receipt, rc, sources) {
     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;
@@ -161,32 +188,45 @@ function checkRecomputeArg(rc) {
 /**
  * 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.
+ * {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) {
+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: rc ? 'fully verified: signature valid and value recomputed' : `signature-valid: signed by ${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 };
+            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.js

@@ -56,6 +56,8 @@ export function verifyEd25519Strict(sig, msg, pub) {
     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).
+    // subtract() adds the negation of the point [k]A, as SPEC 10.1 step 6 requires; it is not
+    // [L - k]A, which differs for a mixed-order A (receipt/ed25519-mixed-order-key).
     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();

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

@@ -1,7 +1,7 @@
 /** The spec revision this library conforms to. */
-export declare const SPEC_VERSION = "spec-0.1.1";
+export declare const SPEC_VERSION = "spec-0.2.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 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 {

package/dist/esm/errors.js

@@ -1,5 +1,5 @@
 /** The spec revision this library conforms to. */
-export const SPEC_VERSION = 'spec-0.1.1';
+export const SPEC_VERSION = 'spec-0.2.1';
 /** Every error code defined by SPEC.md 10.2, in the order of that table. */
 export const ERROR_CODES = [
     'E_PARSE_JSON',
@@ -13,9 +13,11 @@ export const ERROR_CODES = [
     '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',
@@ -39,6 +41,8 @@ export const ERROR_CODES = [
     '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 {

package/dist/esm/index.d.ts

@@ -1,12 +1,13 @@
 import { type Kind } from './validate.js';
 export { DatumeshError, ERROR_CODES, SPEC_VERSION, type ErrorCode } from './errors.js';
 export { verify, type VerifyResult, type Recompute } from './verify.js';
-export { parseUri, formatUri, httpsUrl, type CellRef, type TypedScalar, type Signature } from './uri.js';
-export { keysFromResponse, keysFromDocument, fetchKeys, FETCH_TIMEOUT_MS, type KeysResult, type KeyEntry, type KeyMap, type KeySource } from './keys.js';
+export { checkEnvelope, type EnvelopeResult, type EnvelopeRequest, type Outcome, type Trust } from './envelope.js';
+export { parseUri, formatUri, httpsUrl, type CellRef, type TypedScalar, type Signature, type Unit, type UnitRef } from './uri.js';
+export { keysFromResponse, keysFromDocument, fetchKeys, FETCH_TIMEOUT_MS, FETCH_MAX_BYTES, type KeysResult, type KeyEntry, type KeyMap, type KeySource } from './keys.js';
 export type { Kind } from './validate.js';
 export type { JsonValue } from './json.js';
 /** Library version. */
-export declare const VERSION = "0.1.1";
+export declare const VERSION = "0.2.1";
 /**
  * Validate `input` as `kind` and return its RFC 8785 canonical bytes. `input` is JSON text,
  * UTF-8 bytes, or an already-parsed value. `kind` is "scalar", "cell", "ref", "function" or
@@ -23,5 +24,14 @@ export declare function functionHash(descriptor: unknown): string;
 export declare function receiptHash(receipt: unknown): string;
 /** The signed payload of a receipt (SPEC 8.3): canonical bytes without `sig`. Throws DatumeshError. */
 export declare function receiptPayload(receipt: unknown): Uint8Array;
+/**
+ * The unit of a cell's value (SPEC 7.1, units.md section 3): the descriptor's return unit with
+ * the cell's argument values substituted, e.g. "USD/EUR"; null when the function does not
+ * return a number. `descriptor` must be the cell's function (E_FN_HASH_MISMATCH otherwise).
+ * Both are JSON text, bytes or parsed objects. Throws DatumeshError like canonicalize, and
+ * E_ARG_MISSING / E_SLICE / E_ARG_TYPE / E_CANON_UNIT when a referenced argument cannot give a
+ * unit.
+ */
+export declare function resolvedUnit(descriptor: unknown, cell: unknown): string | null;
 /** Key id of an Ed25519 public key given as 64 lowercase hex digits (SPEC 9.1). Throws DatumeshError. */
 export declare function keyId(publicKeyHex: string): string;

package/dist/esm/index.js

@@ -1,5 +1,5 @@
 /**
- * @datumesh/verify: verify Datumesh receipts (SPEC.md, revision spec-0.1.1).
+ * @datumesh/verify: verify Datumesh receipts (SPEC.md, revision spec-0.2.1).
  *
  * Everything here is synchronous and offline except fetchKeys, the only function that uses the
  * network.
@@ -9,13 +9,14 @@ import { sha256Hex, keyIdOf, fromHex } from './hash.js';
 import { newObject, toJson } from './json.js';
 import { jcsBytes } from './jcs.js';
 import { isHex } from './lexical.js';
-import { KINDS, inferKind, validate } from './validate.js';
+import { KINDS, cellUnit, inferKind, validate } from './validate.js';
 export { DatumeshError, ERROR_CODES, SPEC_VERSION } from './errors.js';
 export { verify } from './verify.js';
+export { checkEnvelope } from './envelope.js';
 export { parseUri, formatUri, httpsUrl } from './uri.js';
-export { keysFromResponse, keysFromDocument, fetchKeys, FETCH_TIMEOUT_MS } from './keys.js';
+export { keysFromResponse, keysFromDocument, fetchKeys, FETCH_TIMEOUT_MS, FETCH_MAX_BYTES } from './keys.js';
 /** Library version. */
-export const VERSION = '0.1.1';
+export const VERSION = '0.2.1';
 function parseAndValidate(input, kind) {
     if (kind !== undefined && kind !== null && !KINDS.includes(kind))
         throw new TypeError(`unknown kind ${JSON.stringify(kind)}; expected one of ${KINDS.join(', ')}`);
@@ -55,6 +56,21 @@ export function receiptPayload(receipt) {
             o[k] = r[k];
     return jcsBytes(o);
 }
+/**
+ * The unit of a cell's value (SPEC 7.1, units.md section 3): the descriptor's return unit with
+ * the cell's argument values substituted, e.g. "USD/EUR"; null when the function does not
+ * return a number. `descriptor` must be the cell's function (E_FN_HASH_MISMATCH otherwise).
+ * Both are JSON text, bytes or parsed objects. Throws DatumeshError like canonicalize, and
+ * E_ARG_MISSING / E_SLICE / E_ARG_TYPE / E_CANON_UNIT when a referenced argument cannot give a
+ * unit.
+ */
+export function resolvedUnit(descriptor, cell) {
+    if (descriptor === undefined || cell === undefined)
+        throw new TypeError('resolvedUnit(descriptor, cell) needs both arguments');
+    const d = toJson(descriptor);
+    const c = toJson(cell);
+    return cellUnit(d, c, (x) => sha256Hex(jcsBytes(x)));
+}
 /** Key id of an Ed25519 public key given as 64 lowercase hex digits (SPEC 9.1). Throws DatumeshError. */
 export function keyId(publicKeyHex) {
     if (typeof publicKeyHex !== 'string' || !isHex(publicKeyHex, 64))

package/dist/esm/json.d.ts

@@ -3,11 +3,10 @@ export interface JsonObject {
     [key: string]: JsonValue;
 }
 /**
- * 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.
+ * SPEC 6.1: at most 64 levels of nesting ([ and { open at once, counted outside strings), checked
+ * before anything else in the text. Datumesh objects nest at most five levels.
  */
-export declare const MAX_DEPTH = 1000;
+export declare const MAX_DEPTH = 64;
 export declare function isObject(v: unknown): v is JsonObject;
 export declare function newObject(): JsonObject;
 export declare function has(o: JsonObject, k: string): boolean;
@@ -15,9 +14,9 @@ export declare function has(o: JsonObject, k: string): boolean;
 export declare function sortedKeys(o: JsonObject): string[];
 export declare function memberPath(path: string, name: string): string;
 /** Parse JSON text strictly. */
-export declare function parseJsonText(text: string): JsonValue;
+export declare function parseJsonText(text: string, numbers?: Map<string, string>): JsonValue;
 /** Parse UTF-8 JSON bytes strictly: no BOM, no invalid UTF-8. */
-export declare function parseJsonBytes(bytes: Uint8Array): JsonValue;
+export declare function parseJsonBytes(bytes: Uint8Array, numbers?: Map<string, string>): JsonValue;
 /**
  * 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
@@ -26,4 +25,4 @@ export declare function parseJsonBytes(bytes: Uint8Array): JsonValue;
  */
 export declare function normalizeValue(v: unknown, path?: string, depth?: number): JsonValue;
 /** JSON text (string), UTF-8 bytes (Uint8Array) or an already-parsed value. */
-export declare function toJson(input: unknown): JsonValue;
+export declare function toJson(input: unknown, numbers?: Map<string, string>): JsonValue;