@datumesh/verify 0.1.1 → 0.2.0

package/dist/esm/units.js

@@ -0,0 +1,123 @@
+// Units (SPEC.md 7.1, units.md): shapes in a signature (step 2, E_SCHEMA), validity against the
+// closed list (step 3, E_CANON_UNIT), and resolution of a cell's unit (units.md section 3).
+import { fail } from './errors.js';
+import { has, isObject, memberPath } from './json.js';
+import { isDate, isNumber } from './lexical.js';
+import { UNIT_GROUPS } from './units-data.js';
+const CURRENCY = new Set(UNIT_GROUPS.currency);
+const LITERAL = new Set(Object.values(UNIT_GROUPS).flat());
+const INDEX_RE = /^index:([0-9]{4}(?:-[0-9]{2}(?:-[0-9]{2})?)?)=(.*)$/;
+const INDEX_MAX = 64;
+/** A currency code from units.md 2.1 (List One and the withdrawn codes). */
+export function isCurrency(s) {
+    return typeof s === 'string' && CURRENCY.has(s);
+}
+/** units.md 2.4: index:<YYYY[-MM[-DD]]>=<number greater than 0>, at most 64 characters. */
+export function isIndexUnit(s) {
+    if (s.length > INDEX_MAX)
+        return false;
+    const m = INDEX_RE.exec(s);
+    if (!m)
+        return false;
+    const [y, mo = '01', d = '01'] = m[1].split('-');
+    if (!isDate(`${y}-${mo}-${d}`))
+        return false;
+    return isNumber(m[2]) && !m[2].startsWith('-') && m[2] !== '0';
+}
+/** A literal unit (units.md section 2): a listed string or an index unit. Byte-for-byte. */
+export function isUnitLiteral(s) {
+    return typeof s === 'string' && (LITERAL.has(s) || isIndexUnit(s));
+}
+const isRef = (u) => Object.keys(u).length === 1 && has(u, 'arg') && typeof u.arg === 'string';
+/**
+ * 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 function structUnit(u, path) {
+    if (typeof u === 'string')
+        return;
+    if (isObject(u)) {
+        if (isRef(u))
+            return;
+        const keys = Object.keys(u);
+        if (keys.length === 2 && has(u, 'of') && has(u, 'per')) {
+            for (const side of ['of', 'per']) {
+                const v = u[side];
+                if (typeof v === 'string' || (isObject(v) && isRef(v)))
+                    continue;
+                fail('E_SCHEMA', 'a rate side is a currency code or {"arg": name}', memberPath(path, side));
+            }
+            return;
+        }
+    }
+    fail('E_SCHEMA', 'a unit is a string, {"arg": name} or {"of", "per"}', path);
+}
+/**
+ * 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 function canonUnit(u, args, path) {
+    const checkRef = (r, p) => {
+        const name = r.arg;
+        const d = has(args, name) ? args[name] : null;
+        if (!isObject(d) || d.type !== 'string')
+            fail('E_CANON_UNIT', `a unit names a string argument of the signature: ${JSON.stringify(name)}`, p);
+    };
+    if (typeof u === 'string') {
+        if (!isUnitLiteral(u))
+            fail('E_CANON_UNIT', `not a unit listed in units.md: ${JSON.stringify(u)}`, path);
+        return;
+    }
+    const o = u;
+    if (has(o, 'arg'))
+        return checkRef(o, path);
+    for (const side of ['of', 'per']) {
+        const v = o[side];
+        const p = memberPath(path, side);
+        if (typeof v === 'string') {
+            if (!isCurrency(v))
+                fail('E_CANON_UNIT', `a rate side is a currency code: ${JSON.stringify(v)}`, p);
+        }
+        else
+            checkRef(v, p);
+    }
+}
+/**
+ * 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 function resolveUnit(returns, cellArgs, path, argsPath) {
+    if (!isObject(returns))
+        return null; // only a number return is an object, and only it has a unit
+    const u = returns.unit;
+    const side = (v, p, currency) => {
+        if (typeof v === 'string')
+            return v; // a literal, already checked by canonUnit
+        const name = v.arg;
+        const ap = memberPath(argsPath, name);
+        if (!has(cellArgs, name))
+            fail('E_ARG_MISSING', `the cell does not bind ${JSON.stringify(name)}`, argsPath);
+        const a = cellArgs[name];
+        if (a === '*')
+            fail('E_SLICE', `${name} is a slice; its unit is not one string`, ap);
+        const scalar = a;
+        if (scalar.type !== 'string')
+            fail('E_ARG_TYPE', `${name} is declared string`, ap);
+        const value = scalar.value;
+        if (currency ? !isCurrency(value) : !isUnitLiteral(value)) {
+            fail('E_CANON_UNIT', `argument ${name} is not ${currency ? 'a currency code' : 'a unit'}: ${JSON.stringify(value)}`, p);
+        }
+        return value;
+    };
+    const p = memberPath(path, 'unit');
+    if (typeof u === 'string')
+        return u;
+    const o = u;
+    if (has(o, 'arg'))
+        return side(o, p, false);
+    const of = side(o.of, memberPath(p, 'of'), true);
+    const per = side(o.per, memberPath(p, 'per'), true);
+    return `${of}/${per}`;
+}

package/dist/esm/uri.d.ts

@@ -11,13 +11,25 @@ export interface CellRef {
     ns: string;
     asof?: string;
 }
-/** A function descriptor's `signature` member (SPEC 7). */
+/** A unit in a signature (SPEC 7.1): a literal from units.md, an argument reference, or a rate. */
+export type UnitRef = {
+    arg: string;
+};
+export type Unit = string | UnitRef | {
+    of: string | UnitRef;
+    per: string | UnitRef;
+};
+/** A function descriptor's `signature` member (SPEC 7). Numbers declare a unit. */
 export interface Signature {
     args: Record<string, {
         type: TypeName;
         valid: boolean;
+        unit?: Unit;
     }>;
-    returns: TypeName;
+    returns: Exclude<TypeName, 'number'> | {
+        type: 'number';
+        unit: Unit;
+    };
 }
 /**
  * Parse a cell URI into a cell reference, taking argument types from the function's

package/dist/esm/uri.js

@@ -1,9 +1,9 @@
 // Cell URIs (SPEC.md section 5).
-import { DatumeshError, fail } from './errors.js';
+import { fail } from './errors.js';
 import { isObject, sortedKeys, toJson } from './json.js';
-import { LIMITS, checkArgName, checkInstant, checkName, checkNamespace, checkTypedValue } from './lexical.js';
+import { LIMITS, checkArgName, checkInstant, checkName, checkNamespace, checkTypedValue, isTypeName } from './lexical.js';
 import { utf8Decode, utf8Encode } from './utf8.js';
-import { canonSignature, structSignature, validate } from './validate.js';
+import { validate } from './validate.js';
 const SCHEME = 'cell://';
 function isLiteral(c) {
     return /^[A-Za-z0-9\-._~:]$/.test(c);
@@ -44,20 +44,21 @@ function encodeValue(s) {
     }
     return out;
 }
+/**
+ * SPEC 5.4: the signature is taken as given (it comes from a descriptor already checked under
+ * section 7); only the declared argument names and types are used. Something that is not a
+ * signature at all is a programmer error.
+ */
 function readSignature(signature) {
-    if (signature === null || signature === undefined)
-        throw new TypeError('parseUri needs the function signature (descriptor.signature)');
     let sig;
     try {
         sig = toJson(signature);
-        structSignature(sig, 'signature');
-        canonSignature(sig, 'signature');
     }
-    catch (e) {
-        if (e instanceof DatumeshError)
-            throw new DatumeshError(e.code, `invalid signature: ${e.detail}`, e.path?.replace(/^\$/, 'signature') ?? 'signature');
-        throw e;
+    catch {
+        throw new TypeError('parseUri needs the function signature (descriptor.signature) as JSON');
     }
+    if (!isObject(sig) || !isObject(sig.args))
+        throw new TypeError('parseUri needs the function signature (descriptor.signature): an object with args');
     return sig;
 }
 /**
@@ -146,8 +147,15 @@ export function parseUri(uri, signature) {
             args[p.name] = '*';
             continue;
         }
-        const type = declared[p.name].type;
+        const decl = declared[p.name];
+        const type = (isObject(decl) ? decl.type : undefined);
         const s = decodeValue(p.value, at(p.name));
+        // The signature is not validated (5.4), but a value is read by its declared type: a
+        // declaration without a string type is E_SCHEMA, an unknown type name E_CANON_TYPE.
+        if (typeof type !== 'string')
+            fail('E_SCHEMA', `the signature declares ${p.name} without a string type`, `signature.args.${p.name}`);
+        if (!isTypeName(type))
+            fail('E_CANON_TYPE', `unknown type ${JSON.stringify(type)} in the signature`, `signature.args.${p.name}.type`);
         if (type === 'boolean') {
             if (s !== 'true' && s !== 'false')
                 fail('E_CANON_TYPE', 'boolean must be true or false', at(p.name));

package/dist/esm/validate.d.ts

@@ -3,8 +3,16 @@ export type Kind = 'scalar' | 'cell' | 'ref' | 'function' | 'receipt' | 'jcs';
 export declare const KINDS: readonly Kind[];
 export declare function structSignature(v: JsonValue, path: string): void;
 export declare function canonSignature(sig: JsonObject, path: string): void;
+/** The return type named by a valid signature's `returns` (SPEC 10.1 step 7.4). */
+export declare function returnType(sig: JsonObject): string;
 /** Validate `v` as `kind` (steps 2-3; for receipts also step 4). Throws DatumeshError. */
 export declare function validate(v: JsonValue, kind: Kind, path?: string): void;
+/**
+ * The unit of a cell's value (SPEC 7.1, units.md 3). Order: the cell (structure, canonical
+ * form), fn_hash against the descriptor (E_FN_HASH_MISMATCH), the descriptor (structure,
+ * canonical form), then substitution.
+ */
+export declare function cellUnit(desc: JsonValue, cell: JsonValue, fnHash: (d: JsonValue) => string): string | null;
 /** Receipt step 2 only: true when the receipt has the right members and JSON types. */
 export declare function receiptStructure(v: JsonValue): void;
 /** Receipt steps 3 and 4, after receiptStructure has passed. */

package/dist/esm/validate.js

@@ -4,6 +4,7 @@
 import { fail } from './errors.js';
 import { has, isObject, memberPath, sortedKeys } from './json.js';
 import { LIMITS, VALID_TIME_TYPES, checkArgName, checkFunctionName, checkHex, checkInstant, checkKeyRef, checkLicence, checkName, checkNamespace, checkString, checkTypedValue, isTypeName, } from './lexical.js';
+import { canonUnit, resolveUnit, structUnit } from './units.js';
 export const KINDS = ['scalar', 'cell', 'ref', 'function', 'receipt', 'jcs'];
 const SLICE = '*';
 // ---------------------------------------------------------------- step 2: structure
@@ -76,12 +77,24 @@ export function structSignature(v, path) {
     for (const k of sortedKeys(args)) {
         const p = memberPath(argsPath, k);
         const d = expectObject(args[k], p);
-        members(d, ['type', 'valid'], [], p);
+        members(d, ['type', 'valid'], ['unit'], p);
         expectString(d, 'type', p);
+        if (has(d, 'unit'))
+            structUnit(d.unit, memberPath(p, 'unit'));
         if (typeof d.valid !== 'boolean')
             fail('E_SCHEMA', 'valid must be a boolean', memberPath(p, 'valid'));
     }
-    expectString(sig, 'returns', path);
+    // SPEC 7: a type name, or {"type", "unit"} (the unit's absence is E_CANON_UNIT, in step 3).
+    const rp = memberPath(path, 'returns');
+    const r = sig.returns;
+    if (typeof r === 'string')
+        return;
+    if (!isObject(r))
+        fail('E_SCHEMA', 'returns must be a type name or an object', rp);
+    members(r, ['type'], ['unit'], rp);
+    expectString(r, 'type', rp);
+    if (has(r, 'unit'))
+        structUnit(r.unit, memberPath(rp, 'unit'));
 }
 const RECEIPT_MEMBERS = [
     'asof',
@@ -185,14 +198,43 @@ export function canonSignature(sig, path) {
         const p = memberPath(argsPath, k);
         checkArgName(k, p);
         const d = args[k];
+        // SPEC 7: type, then unit, then valid.
         if (!isTypeName(d.type))
             fail('E_CANON_TYPE', `unknown type ${JSON.stringify(d.type)}`, memberPath(p, 'type'));
+        if (d.type === 'number') {
+            if (!has(d, 'unit'))
+                fail('E_CANON_UNIT', 'a number argument declares its unit', p);
+            canonUnit(d.unit, args, memberPath(p, 'unit'));
+        }
+        else if (has(d, 'unit')) {
+            fail('E_CANON_UNIT', 'only number arguments have a unit', memberPath(p, 'unit'));
+        }
         if (d.valid === true && !VALID_TIME_TYPES.includes(d.type)) {
             fail('E_CANON_TYPE', 'a valid-time argument must be a date, instant or string', p);
         }
     }
-    if (!isTypeName(sig.returns))
-        fail('E_CANON_TYPE', `unknown type ${JSON.stringify(sig.returns)}`, memberPath(path, 'returns'));
+    const rp = memberPath(path, 'returns');
+    const r = sig.returns;
+    if (typeof r === 'string') {
+        if (!isTypeName(r))
+            fail('E_CANON_TYPE', `unknown type ${JSON.stringify(r)}`, rp);
+        if (r === 'number')
+            fail('E_CANON_UNIT', 'a number return is {"type": "number", "unit": ...}, not the bare name', rp);
+        return;
+    }
+    const o = r;
+    if (!isTypeName(o.type))
+        fail('E_CANON_TYPE', `unknown type ${JSON.stringify(o.type)}`, memberPath(rp, 'type'));
+    if (o.type !== 'number')
+        fail('E_CANON_UNIT', 'only a number return is written as an object', rp);
+    if (!has(o, 'unit'))
+        fail('E_CANON_UNIT', 'a number return declares its unit', rp);
+    canonUnit(o.unit, args, memberPath(rp, 'unit'));
+}
+/** The return type named by a valid signature's `returns` (SPEC 10.1 step 7.4). */
+export function returnType(sig) {
+    const r = sig.returns;
+    return typeof r === 'string' ? r : r.type;
 }
 function canonFunction(o, path) {
     const code = o.code;
@@ -308,6 +350,21 @@ export function validate(v, kind, path = '$') {
             return;
     }
 }
+/**
+ * The unit of a cell's value (SPEC 7.1, units.md 3). Order: the cell (structure, canonical
+ * form), fn_hash against the descriptor (E_FN_HASH_MISMATCH), the descriptor (structure,
+ * canonical form), then substitution.
+ */
+export function cellUnit(desc, cell, fnHash) {
+    structCell(cell, 'cell', false);
+    canonCell(cell, 'cell');
+    if (fnHash(desc) !== cell.fn_hash)
+        fail('E_FN_HASH_MISMATCH', 'the descriptor does not hash to cell.fn_hash', 'descriptor');
+    structFunction(desc, 'descriptor');
+    canonFunction(desc, 'descriptor');
+    const sig = desc.signature;
+    return resolveUnit(sig.returns, cell.args, 'descriptor.signature.returns', 'cell.args');
+}
 /** Receipt step 2 only: true when the receipt has the right members and JSON types. */
 export function receiptStructure(v) {
     structReceipt(v, '$');

package/dist/esm/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/esm/verify.js

@@ -5,7 +5,8 @@ import { fromHex, sha256Hex } from './hash.js';
 import { has, newObject, sortedKeys, toJson } from './json.js';
 import { jcsBytes } from './jcs.js';
 import { collectSources, lookupKey } from './keys.js';
-import { receiptCanonicalAndConsistent, receiptStructure, validate } from './validate.js';
+import { checkBlob } from './lexical.js';
+import { receiptCanonicalAndConsistent, receiptStructure, returnType, validate } from './validate.js';
 class Stop extends Error {
     constructor(code, detail, path) {
         super(detail);
@@ -103,9 +104,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 = 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 ?? {};
@@ -141,6 +143,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 = 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 (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;
@@ -158,32 +182,46 @@ 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.
  */
-export function verify(receipt, keys, recomputeArg) {
+export function verify(receipt, keys, recomputeArg, blob) {
     const sources = 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. */
+export function verifyEmbedded(receipt, sources) {
+    return verifySigned(receipt, sources, () => undefined);
+}
+export { Stop };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@datumesh/verify",
-  "version": "0.1.1",
-  "description": "Verifier for Datumesh receipts: strict canonical JSON (RFC 8785), cell URIs, key documents and Ed25519 signatures.",
+  "version": "0.2.0",
+  "description": "Verifier for Datumesh receipts: strict canonical JSON (RFC 8785), cell URIs, units, blobs, response envelopes, key documents and Ed25519 signatures.",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -10,7 +10,7 @@
   "homepage": "https://datumesh.com",
   "keywords": ["datumesh", "receipt", "verify", "ed25519", "jcs", "rfc8785", "canonical-json"],
   "datumesh": {
-    "spec": "spec-0.1.1"
+    "spec": "spec-0.2.0"
   },
   "type": "module",
   "main": "./dist/cjs/index.js",