@datumesh/verify 0.1.1 → 0.2.0

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.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/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.0';
 /** 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 { 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/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.0).
  *
  * 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';
 /** Library version. */
-export const VERSION = '0.1.1';
+export const VERSION = '0.2.0';
 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

@@ -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/esm/json.js

@@ -26,8 +26,11 @@ export 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;
@@ -77,7 +80,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)) {
@@ -219,7 +222,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;
@@ -235,30 +238,31 @@ class Parser {
         const n = Number(text);
         if (!Number.isFinite(n))
             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. */
-export function parseJsonText(text) {
+export function parseJsonText(text, numbers) {
     if (text.charCodeAt(0) === 0xfeff)
         fail('E_PARSE_JSON', 'byte order mark', '$');
     if (hasLoneSurrogate(text))
         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)
         fail('E_PARSE_JSON', 'lone surrogate', p.surrogatePath);
     return v;
 }
 /** Parse UTF-8 JSON bytes strictly: no BOM, no invalid UTF-8. */
-export function parseJsonBytes(bytes) {
+export function parseJsonBytes(bytes, numbers) {
     if (bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf) {
         fail('E_PARSE_JSON', 'byte order mark', '$');
     }
     const text = utf8Decode(bytes);
     if (text === null)
         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
@@ -298,12 +302,12 @@ export function normalizeValue(v, path = '$', depth = 0) {
     fail('E_PARSE_JSON', `${typeof v} is not a JSON value`, path);
 }
 /** JSON text (string), UTF-8 bytes (Uint8Array) or an already-parsed value. */
-export function toJson(input) {
+export 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/esm/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

package/dist/esm/lexical.js

@@ -17,7 +17,7 @@ export const LIMITS = {
     licence_url: 512,
     keys: 64,
 };
-export const TYPES = ['boolean', 'date', 'instant', 'number', 'string'];
+export const TYPES = ['blob', 'boolean', 'date', 'instant', 'number', 'string'];
 export const VALID_TIME_TYPES = ['date', 'instant', 'string'];
 export function isTypeName(t) {
     return typeof t === 'string' && TYPES.includes(t);
@@ -87,6 +87,10 @@ export function checkKeyRef(s, path) {
     return { host, id };
 }
 const NUMBER_RE = /^-?(?:0|[1-9][0-9]*)(?:\.[0-9]*[1-9])?$/;
+/** SPEC 3.1: a canonical decimal of at most 128 characters. */
+export function isNumber(s) {
+    return NUMBER_RE.test(s) && s !== '-0' && s.length <= LIMITS.number;
+}
 /** SPEC 3.1. Grammar (E_CANON_NUMBER) before the 128-character limit (E_CANON_LIMIT). */
 export function checkNumber(s, path) {
     if (!NUMBER_RE.test(s) || s === '-0')
@@ -146,8 +150,24 @@ export function checkString(s, path, opts = {}) {
 function hex4(cp) {
     return cp.toString(16).toUpperCase().padStart(4, '0');
 }
+// SPEC 3.7: <sha256>:<length>:<type>/<subtype>, with RFC 6838 restricted names in lowercase.
+const BLOB_RE = /^[0-9a-f]{64}:(0|[1-9][0-9]*):([a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*)$/;
+const MAX_SAFE = '9007199254740991';
+export const MEDIA_TYPE_MAX = 128;
+/** SPEC 3.7. Grammar, then length <= 2^53 - 1, then media type <= 128 characters; all E_CANON_BLOB. */
+export function checkBlob(s, path) {
+    const m = BLOB_RE.exec(s);
+    if (!m)
+        fail('E_CANON_BLOB', `not <sha256>:<length>:<type/subtype>: ${JSON.stringify(s)}`, path);
+    const len = m[1];
+    if (len.length > MAX_SAFE.length || (len.length === MAX_SAFE.length && len > MAX_SAFE))
+        fail('E_CANON_BLOB', `length above ${MAX_SAFE}`, path);
+    if (m[2].length > MEDIA_TYPE_MAX)
+        fail('E_CANON_BLOB', `media type longer than ${MEDIA_TYPE_MAX} characters`, path);
+    return { sha256: s.slice(0, 64), length: Number(len), mediaType: m[2] };
+}
 const SPDX_RE = /^[A-Za-z0-9][A-Za-z0-9.+-]*$/;
-const URL_RE = /^https:\/\/[!-~]+$/;
+export const URL_RE = /^https:\/\/[!-~]+$/;
 /**
  * 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
@@ -182,6 +202,8 @@ export function checkTypedValue(type, value, path) {
         checkDate(value, path);
     else if (type === 'instant')
         checkInstant(value, path);
+    else if (type === 'blob')
+        checkBlob(value, path);
     else
         checkString(value, path);
 }

package/dist/esm/units-data.d.ts

@@ -0,0 +1,4 @@
+/** Literal units by group, in units.md order. Index units (units.md 2.4) are a pattern. */
+export declare const UNIT_GROUPS: {
+    readonly [group: string]: readonly string[];
+};

package/dist/esm/units-data.js

@@ -0,0 +1,8 @@
+// GENERATED by tools/gen-units.mjs from spec/units.md (the `units-…` fenced blocks).
+// Do not edit by hand; test/units.test.mjs checks that this file matches units.md.
+/** Literal units by group, in units.md order. Index units (units.md 2.4) are a pattern. */
+export const UNIT_GROUPS = {
+    currency: ["AED", "AFN", "ALL", "AMD", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BBD", "BDT", "BHD", "BIF", "BMD", "BND", "BOB", "BOV", "BRL", "BSD", "BTN", "BWP", "BYN", "BZD", "CAD", "CDF", "CHE", "CHF", "CHW", "CLF", "CLP", "CNY", "COP", "COU", "CRC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB", "EUR", "FJD", "FKP", "GBP", "GEL", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HTG", "HUF", "IDR", "ILS", "INR", "IQD", "IRR", "ISK", "JMD", "JOD", "JPY", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LYD", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRU", "MUR", "MVR", "MWK", "MXN", "MXV", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLE", "SOS", "SRD", "SSP", "STN", "SVC", "SYP", "SZL", "THB", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TWD", "TZS", "UAH", "UGX", "USD", "USN", "UYI", "UYU", "UYW", "UZS", "VED", "VES", "VND", "VUV", "WST", "XAD", "XAF", "XAG", "XAU", "XBA", "XBB", "XBC", "XBD", "XCD", "XCG", "XDR", "XOF", "XPD", "XPF", "XPT", "XSU", "XTS", "XUA", "YER", "ZAR", "ZMW", "ZWG", "BGN", "CYP", "EEK", "GRD", "HRK", "LTL", "LVL", "MTL", "ROL", "SIT", "SKK", "TRL"],
+    physical: ["m", "kg", "s", "A", "K", "mol", "cd", "degC", "m/s", "W", "kWh", "mm", "cm", "km/h", "hPa", "W/m2"],
+    ratio: ["percent", "permille", "bp", "1", "count"],
+};

package/dist/esm/units.d.ts

@@ -0,0 +1,24 @@
+import { type JsonObject, type JsonValue } from './json.js';
+/** A currency code from units.md 2.1 (List One and the withdrawn codes). */
+export declare function isCurrency(s: unknown): boolean;
+/** units.md 2.4: index:<YYYY[-MM[-DD]]>=<number greater than 0>, at most 64 characters. */
+export declare function isIndexUnit(s: string): boolean;
+/** A literal unit (units.md section 2): a listed string or an index unit. Byte-for-byte. */
+export declare function isUnitLiteral(s: unknown): boolean;
+/**
+ * Step 2 for a unit: a string, {"arg": <string>}, or {"of": side, "per": side} where a side is
+ * a string or {"arg": <string>}. Anything else is E_SCHEMA (SPEC 7.1, units.md 1).
+ */
+export declare function structUnit(u: JsonValue, path: string): void;
+/**
+ * Step 3 for a unit whose shape passed structUnit. `args` is the signature's `args`: a
+ * reference must name one of them whose declared type is `string` (E_CANON_UNIT).
+ */
+export declare function canonUnit(u: JsonValue, args: JsonObject, path: string): void;
+/**
+ * units.md section 3: the unit of one cell's value, for a descriptor and a cell that have
+ * passed validation and whose fn_hash matches. `returns` is the signature's `returns`.
+ * A referenced argument must be bound (E_ARG_MISSING), not a slice (E_SLICE), of its declared
+ * type (E_ARG_TYPE), and a literal unit (E_CANON_UNIT); on a rate side, a currency.
+ */
+export declare function resolveUnit(returns: JsonValue, cellArgs: JsonObject, path: string, argsPath: string): string | null;