@datumesh/verify 0.1.1 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @datumesh/verify
 
-Verify [Datumesh](https://datumesh.com) receipts in JavaScript: signed answers for addressable data cells, checked offline against strict RFC 8785 canonical JSON and Ed25519, following the [Datumesh specification](https://github.com/datumesh-com/datumesh-spec) revision `spec-0.1.1` and passing all of its test vectors.
+Verify [Datumesh](https://datumesh.com) receipts in JavaScript: signed answers for addressable data cells, checked offline against strict RFC 8785 canonical JSON and Ed25519, following the [Datumesh specification](https://github.com/datumesh-com/datumesh-spec) revision `spec-0.2.0` and passing all of its test vectors.
 
 ```sh
 npm install @datumesh/verify
@@ -15,7 +15,7 @@ const vector = JSON.parse(readFileSync('stored-number.json', 'utf8'));
 const keys = keysFromResponse('rates.example.org', 200, vector.keys['rates.example.org'].https.body);
 const result = verify(vector.input, keys);
 console.log(result.ok, result.code, result.level, result.hash);
-// true OK signed 501f744d910c585859a5be4f3b62385ed0d6803db53dbbf95dff5097a68bee0d
+// true OK signed 19a5fe3a744c5792f747fb4c286ce396ab44b95922de4f07937502fe595b6f81
 ```
 
 The same with CommonJS:
@@ -31,12 +31,14 @@ console.log(verify(vector.input, keys).code); // OK
 
 ## What it does
 
-- `verify(receipt, keys, recompute?)` runs the verification procedure of SPEC.md 10.1 and returns `{ ok, code, level, hash, key, detail, path }`. It is synchronous, never touches the network and never throws for a bad receipt or bad key material; failures come back as the spec's error codes (`E_SIGNATURE`, `E_KEY_NOT_VALID`, ...). `level` is `"signed"`, or `"recomputed"` when you pass the descriptor, the input receipts and the value you obtained by evaluating the function (the library checks lineage and compares; it does not evaluate functions).
+- `verify(receipt, keys, recompute?, blob?)` runs the verification procedure of SPEC.md 10.1 and returns `{ ok, code, level, hash, key, detail, path, blobChecked }`. It is synchronous, never touches the network and never throws for a bad receipt or bad key material; failures come back as the spec's error codes (`E_SIGNATURE`, `E_KEY_NOT_VALID`, ...). `level` is `"signed"`, or `"recomputed"` when you pass the descriptor, the input receipts and the value you obtained by evaluating the function (the library checks lineage and compares; it does not evaluate functions). For a receipt whose value is a `blob`, pass the content bytes as `blob` to check their length and SHA-256 (`E_BLOB_MISMATCH`; `blobChecked` is then true).
 - `keys` is a key document, the result of `keysFromResponse` / `fetchKeys`, a `{ keyId: publicKeyHex }` map, or an array of these (one per host for lineage).
 - `fetchKeys(host)` is the only function that uses the network: one `GET https://<host>/.well-known/datumesh.json`, no redirects, 10 s timeout, using the platform's `fetch` and TLS verification.
-- `canonicalize(obj, kind)`, `cellHash`, `receiptHash`, `functionHash`, `parseUri(uri, signature)`, `formatUri(ref)` and `keyId` expose canonical forms, hashes and cell URIs. They throw `DatumeshError` (with `.code` and `.path`).
+- `checkEnvelope(status, body, keys, request)` checks a mesh's response envelope (SPEC.md 5.5) against its HTTP status, verifies the embedded receipt through the signature, and checks that it answers your request (`request` is `{ cell_id, asof? }`: the id of the cell you asked for and the `asof` you asked with, if any), returning `{ ok, code, outcome, trust, receiptHash, detail, path }`. The envelope itself is unsigned: `stale`, `superseded_by` and `verified` remain the mesh's claims.
+- `resolvedUnit(descriptor, cell)` gives the unit of a cell's value from its function's declared units (`"USD/EUR"`, `"degC"`, or `null` for a non-number), using the closed list of `units.md` shipped with the package. The library never converts or checks values against units.
+- `canonicalize(obj, kind)`, `cellHash`, `receiptHash`, `functionHash`, `parseUri(uri, signature)`, `formatUri(ref)` and `keyId` expose canonical forms, hashes and cell URIs. These and `resolvedUnit` throw `DatumeshError` (with `.code` and `.path`).
 
-Strings are checked against Unicode 15.1 tables shipped with the package, so results do not depend on the JavaScript engine's Unicode version. Ed25519 verification is libsodium-strict, as the spec requires. ESM and CommonJS builds with TypeScript types, for Node 18+ and for browsers through a bundler (the core uses no Node built-ins). Where the specification left a question open, the choices made are listed in [DEFECTS.md](https://github.com/datumesh-com/datumesh-verify-js/blob/main/DEFECTS.md).
+SHA-256 and Ed25519 come from the `@noble` libraries (pure JavaScript), so blob checks work the same in Node 18.0 and in browsers. Strings are checked against Unicode 15.1 tables shipped with the package, so results do not depend on the JavaScript engine's Unicode version. Ed25519 verification is libsodium-strict, as the spec requires. ESM and CommonJS builds with TypeScript types, for Node 18+ and for browsers through a bundler (the core uses no Node built-ins). Where the specification left a question open, the choices made are listed in [DEFECTS.md](https://github.com/datumesh-com/datumesh-verify-js/blob/main/DEFECTS.md).
 
 A valid signature means only that the holder of the key named in `computed_by` stated the value. Whom to trust is your policy.
 

package/dist/cjs/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/cjs/envelope.js

@@ -0,0 +1,243 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkEnvelope = checkEnvelope;
+// 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.
+const errors_js_1 = require("./errors.js");
+const json_js_1 = require("./json.js");
+const lexical_js_1 = require("./lexical.js");
+const hash_js_1 = require("./hash.js");
+const jcs_js_1 = require("./jcs.js");
+const keys_js_1 = require("./keys.js");
+const units_js_1 = require("./units.js");
+const verify_js_1 = require("./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 errors_js_1.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 (!(0, json_js_1.isObject)(v))
+        bad('quote is an object {amount, authorise, currency}', path);
+    for (const k of ['amount', 'authorise', 'currency'])
+        if (!(0, json_js_1.has)(v, k))
+            bad(`quote has no ${k}`, path);
+    for (const k of (0, json_js_1.sortedKeys)(v))
+        if (!['amount', 'authorise', 'currency'].includes(k))
+            bad(`quote has an unexpected member ${JSON.stringify(k)}`, path);
+    const amount = v.amount;
+    const ap = (0, json_js_1.memberPath)(path, 'amount');
+    if (typeof amount !== 'string')
+        bad('amount is a decimal string (SPEC 3.1)', ap);
+    inner(() => (0, lexical_js_1.checkNumber)(amount, ap), ap);
+    if (amount.startsWith('-') || amount === '0')
+        bad('amount is greater than zero', ap);
+    const url = v.authorise;
+    const up = (0, json_js_1.memberPath)(path, 'authorise');
+    if (typeof url !== 'string' || !lexical_js_1.URL_RE.test(url) || url.length > lexical_js_1.LIMITS.licence_url)
+        bad('authorise is an https:// URL in the form of a licence URL (SPEC 8.1)', up);
+    if (!(0, units_js_1.isCurrency)(v.currency))
+        bad('currency is a currency code from units.md', (0, json_js_1.memberPath)(path, 'currency'));
+}
+/** Step 2: members against the table and their rules. Returns the outcome. */
+function members(o, numbers) {
+    if (!(0, json_js_1.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 (!(0, json_js_1.has)(o, k))
+            bad(`outcome ${outcome} requires ${k}`, '$');
+    for (const k of (0, json_js_1.sortedKeys)(o))
+        if (k !== 'outcome' && !required.includes(k) && !optional.includes(k))
+            bad(`member ${JSON.stringify(k)} is not allowed with outcome ${outcome}`, (0, json_js_1.memberPath)('$', k));
+    if ((0, json_js_1.has)(o, 'reason') && !(0, json_js_1.has)(o, 'superseded_by'))
+        bad('reason is only present with superseded_by', '$.reason');
+    for (const k of (0, json_js_1.sortedKeys)(o)) {
+        const v = o[k];
+        const p = (0, json_js_1.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' || !errors_js_1.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(() => (0, lexical_js_1.checkString)(v, p, { limit: lexical_js_1.LIMITS.summary }), p);
+                break;
+            case 'receipt':
+                if (!(0, json_js_1.isObject)(v))
+                    bad('receipt is a receipt object', p);
+                break;
+            case 'superseded_by':
+                if (typeof v !== 'string' || !(0, lexical_js_1.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 = (0, json_js_1.isObject)(request) &&
+        typeof request.cell_id === 'string' &&
+        (0, lexical_js_1.isHex)(request.cell_id, 64) &&
+        Object.keys(request).every((k) => k === 'cell_id' || k === 'asof') &&
+        (!(0, json_js_1.has)(request, 'asof') || (typeof request.asof === 'string' && (0, lexical_js_1.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.
+ */
+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 = (0, keys_js_1.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 = (0, json_js_1.toJson)(body, numbers); // step 1
+    }
+    catch (e) {
+        if (e instanceof errors_js_1.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 (!(0, json_js_1.has)(env, 'receipt'))
+        return { ok: true, code: 'OK', outcome, trust: null, receiptHash: null, detail: `outcome ${outcome}`, path: null };
+    // Step 4.
+    let r;
+    try {
+        r = (0, verify_js_1.verifyEmbedded)(env.receipt, sources);
+    }
+    catch (e) {
+        if (e instanceof verify_js_1.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 = (0, hash_js_1.sha256Hex)((0, jcs_js_1.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/cjs/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.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_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/cjs/errors.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DatumeshError = exports.ERROR_CODES = exports.SPEC_VERSION = void 0;
 exports.fail = fail;
 /** The spec revision this library conforms to. */
-exports.SPEC_VERSION = 'spec-0.1.1';
+exports.SPEC_VERSION = 'spec-0.2.0';
 /** Every error code defined by SPEC.md 10.2, in the order of that table. */
 exports.ERROR_CODES = [
     'E_PARSE_JSON',
@@ -17,9 +17,11 @@ exports.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',
@@ -43,6 +45,8 @@ exports.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. */
 class DatumeshError extends Error {

package/dist/cjs/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 { 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, 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.0";
 /**
  * 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/cjs/index.js

@@ -1,14 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VERSION = exports.FETCH_TIMEOUT_MS = exports.fetchKeys = exports.keysFromDocument = exports.keysFromResponse = exports.httpsUrl = exports.formatUri = exports.parseUri = exports.verify = exports.SPEC_VERSION = exports.ERROR_CODES = exports.DatumeshError = void 0;
+exports.VERSION = exports.FETCH_TIMEOUT_MS = exports.fetchKeys = exports.keysFromDocument = exports.keysFromResponse = exports.httpsUrl = exports.formatUri = exports.parseUri = exports.checkEnvelope = exports.verify = exports.SPEC_VERSION = exports.ERROR_CODES = exports.DatumeshError = void 0;
 exports.canonicalize = canonicalize;
 exports.cellHash = cellHash;
 exports.functionHash = functionHash;
 exports.receiptHash = receiptHash;
 exports.receiptPayload = receiptPayload;
+exports.resolvedUnit = resolvedUnit;
 exports.keyId = keyId;
 /**
- * @datumesh/verify: verify Datumesh receipts (SPEC.md, revision spec-0.1.1).
+ * @datumesh/verify: verify Datumesh receipts (SPEC.md, revision spec-0.2.0).
  *
  * Everything here is synchronous and offline except fetchKeys, the only function that uses the
  * network.
@@ -25,6 +26,8 @@ Object.defineProperty(exports, "ERROR_CODES", { enumerable: true, get: function
 Object.defineProperty(exports, "SPEC_VERSION", { enumerable: true, get: function () { return errors_js_2.SPEC_VERSION; } });
 var verify_js_1 = require("./verify.js");
 Object.defineProperty(exports, "verify", { enumerable: true, get: function () { return verify_js_1.verify; } });
+var envelope_js_1 = require("./envelope.js");
+Object.defineProperty(exports, "checkEnvelope", { enumerable: true, get: function () { return envelope_js_1.checkEnvelope; } });
 var uri_js_1 = require("./uri.js");
 Object.defineProperty(exports, "parseUri", { enumerable: true, get: function () { return uri_js_1.parseUri; } });
 Object.defineProperty(exports, "formatUri", { enumerable: true, get: function () { return uri_js_1.formatUri; } });
@@ -35,7 +38,7 @@ Object.defineProperty(exports, "keysFromDocument", { enumerable: true, get: func
 Object.defineProperty(exports, "fetchKeys", { enumerable: true, get: function () { return keys_js_1.fetchKeys; } });
 Object.defineProperty(exports, "FETCH_TIMEOUT_MS", { enumerable: true, get: function () { return keys_js_1.FETCH_TIMEOUT_MS; } });
 /** Library version. */
-exports.VERSION = '0.1.1';
+exports.VERSION = '0.2.0';
 function parseAndValidate(input, kind) {
     if (kind !== undefined && kind !== null && !validate_js_1.KINDS.includes(kind))
         throw new TypeError(`unknown kind ${JSON.stringify(kind)}; expected one of ${validate_js_1.KINDS.join(', ')}`);
@@ -75,6 +78,21 @@ function receiptPayload(receipt) {
             o[k] = r[k];
     return (0, jcs_js_1.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.
+ */
+function resolvedUnit(descriptor, cell) {
+    if (descriptor === undefined || cell === undefined)
+        throw new TypeError('resolvedUnit(descriptor, cell) needs both arguments');
+    const d = (0, json_js_1.toJson)(descriptor);
+    const c = (0, json_js_1.toJson)(cell);
+    return (0, validate_js_1.cellUnit)(d, c, (x) => (0, hash_js_1.sha256Hex)((0, jcs_js_1.jcsBytes)(x)));
+}
 /** Key id of an Ed25519 public key given as 64 lowercase hex digits (SPEC 9.1). Throws DatumeshError. */
 function keyId(publicKeyHex) {
     if (typeof publicKeyHex !== 'string' || !(0, lexical_js_1.isHex)(publicKeyHex, 64))

package/dist/cjs/json.d.ts

@@ -15,9 +15,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 +26,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;

package/dist/cjs/json.js

@@ -38,8 +38,11 @@ function memberPath(path, name) {
     return /^[A-Za-z_][A-Za-z0-9_]*$/.test(name) ? `${path}.${name}` : `${path}[${JSON.stringify(name)}]`;
 }
 class Parser {
-    constructor(s) {
+    constructor(s, 
+    /** When given, receives the source text of every number, by JSON path. */
+    numbers) {
         this.s = s;
+        this.numbers = numbers;
         this.i = 0;
         /** Path of the first string holding an escaped lone surrogate; reported after parsing. */
         this.surrogatePath = null;
@@ -89,7 +92,7 @@ class Parser {
             return null;
         }
         if (c === '-' || (c >= '0' && c <= '9'))
-            return this.number();
+            return this.number(path);
         if (c === undefined)
             this.err('unexpected end of input');
         if (s.startsWith('NaN', this.i) || s.startsWith('Infinity', this.i) || s.startsWith('-Infinity', this.i)) {
@@ -231,7 +234,7 @@ class Parser {
             this.surrogatePath = path;
         return out;
     }
-    number() {
+    number(path) {
         const s = this.s;
         const m = /-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?/y;
         m.lastIndex = this.i;
@@ -247,30 +250,31 @@ class Parser {
         const n = Number(text);
         if (!Number.isFinite(n))
             (0, errors_js_1.fail)('E_PARSE_JSON', `number out of IEEE 754 range: ${text.slice(0, 40)}`, '$');
+        this.numbers?.set(path, text);
         return n;
     }
 }
 /** Parse JSON text strictly. */
-function parseJsonText(text) {
+function parseJsonText(text, numbers) {
     if (text.charCodeAt(0) === 0xfeff)
         (0, errors_js_1.fail)('E_PARSE_JSON', 'byte order mark', '$');
     if ((0, unicode_js_1.hasLoneSurrogate)(text))
         (0, errors_js_1.fail)('E_PARSE_JSON', 'lone surrogate in the text', '$');
-    const p = new Parser(text);
+    const p = new Parser(text, numbers);
     const v = p.parseDocument();
     if (p.surrogatePath !== null)
         (0, errors_js_1.fail)('E_PARSE_JSON', 'lone surrogate', p.surrogatePath);
     return v;
 }
 /** Parse UTF-8 JSON bytes strictly: no BOM, no invalid UTF-8. */
-function parseJsonBytes(bytes) {
+function parseJsonBytes(bytes, numbers) {
     if (bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf) {
         (0, errors_js_1.fail)('E_PARSE_JSON', 'byte order mark', '$');
     }
     const text = (0, utf8_js_1.utf8Decode)(bytes);
     if (text === null)
         (0, errors_js_1.fail)('E_PARSE_JSON', 'invalid UTF-8', '$');
-    return parseJsonText(text);
+    return parseJsonText(text, numbers);
 }
 /**
  * Check an already-parsed JavaScript value against the JSON data model and return a private
@@ -310,12 +314,12 @@ function normalizeValue(v, path = '$', depth = 0) {
     (0, errors_js_1.fail)('E_PARSE_JSON', `${typeof v} is not a JSON value`, path);
 }
 /** JSON text (string), UTF-8 bytes (Uint8Array) or an already-parsed value. */
-function toJson(input) {
+function toJson(input, numbers) {
     if (typeof input === 'string')
-        return parseJsonText(input);
+        return parseJsonText(input, numbers);
     if (input instanceof Uint8Array)
-        return parseJsonBytes(input);
+        return parseJsonBytes(input, numbers);
     if (input instanceof ArrayBuffer)
-        return parseJsonBytes(new Uint8Array(input));
+        return parseJsonBytes(new Uint8Array(input), numbers);
     return normalizeValue(input);
 }

package/dist/cjs/lexical.d.ts

@@ -11,7 +11,7 @@ export declare const LIMITS: {
     readonly licence_url: 512;
     readonly keys: 64;
 };
-export declare const TYPES: readonly ["boolean", "date", "instant", "number", "string"];
+export declare const TYPES: readonly ["blob", "boolean", "date", "instant", "number", "string"];
 export type TypeName = (typeof TYPES)[number];
 export declare const VALID_TIME_TYPES: readonly string[];
 export declare function isTypeName(t: unknown): t is TypeName;
@@ -32,6 +32,8 @@ export declare function checkKeyRef(s: string, path: string): {
     host: string;
     id: string;
 };
+/** SPEC 3.1: a canonical decimal of at most 128 characters. */
+export declare function isNumber(s: string): boolean;
 /** SPEC 3.1. Grammar (E_CANON_NUMBER) before the 128-character limit (E_CANON_LIMIT). */
 export declare function checkNumber(s: string, path: string): void;
 export declare function isDate(s: string): boolean;
@@ -48,6 +50,14 @@ export declare function checkString(s: string, path: string, opts?: {
     body?: boolean;
     limit?: number;
 }): void;
+export declare const MEDIA_TYPE_MAX = 128;
+/** SPEC 3.7. Grammar, then length <= 2^53 - 1, then media type <= 128 characters; all E_CANON_BLOB. */
+export declare function checkBlob(s: string, path: string): {
+    sha256: string;
+    length: number;
+    mediaType: string;
+};
+export declare const URL_RE: RegExp;
 /**
  * SPEC 8.1 `licence`: an SPDX licence identifier or an https:// URL. SPEC.md gives no grammar;
  * this follows schemas/receipt.schema.json (and the reference tool): an identifier matches