@datumesh/verify 0.1.1 → 0.2.1

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.1",
+  "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.1"
   },
   "type": "module",
   "main": "./dist/cjs/index.js",