@datumesh/verify 0.2.0 → 0.2.1

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.2.0` 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.1` and passing all of its test vectors.
 
 ```sh
 npm install @datumesh/verify

package/dist/cjs/ed25519.js

@@ -59,6 +59,8 @@ function verifyEd25519Strict(sig, msg, pub) {
     const h = (0, sha2_1.sha512)(concat(rBytes, pub, msg));
     const k = le(h) % L;
     // R' = [S]B - [k]A (multiplyUnsafe accepts 0; inputs are public, so variable time is fine).
+    // subtract() adds the negation of the point [k]A, as SPEC 10.1 step 6 requires; it is not
+    // [L - k]A, which differs for a mixed-order A (receipt/ed25519-mixed-order-key).
     const SB = s === 0n ? Point.ZERO : Point.BASE.multiplyUnsafe(s);
     const kA = k === 0n ? Point.ZERO : A.multiplyUnsafe(k);
     const rCheck = SB.subtract(kA).toBytes();

package/dist/cjs/errors.d.ts

@@ -1,5 +1,5 @@
 /** The spec revision this library conforms to. */
-export declare const SPEC_VERSION = "spec-0.2.0";
+export declare const SPEC_VERSION = "spec-0.2.1";
 /** Every error code defined by SPEC.md 10.2, in the order of that table. */
 export declare const ERROR_CODES: readonly ["E_PARSE_JSON", "E_PARSE_DUPLICATE_KEY", "E_PARSE_URI", "E_SCHEMA", "E_CANON_NAME", "E_CANON_ARG_NAME", "E_CANON_ARG_DUPLICATE", "E_CANON_ARG_ORDER", "E_CANON_PERCENT", "E_CANON_TYPE", "E_CANON_NUMBER", "E_CANON_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];

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.2.0';
+exports.SPEC_VERSION = 'spec-0.2.1';
 /** Every error code defined by SPEC.md 10.2, in the order of that table. */
 exports.ERROR_CODES = [
     'E_PARSE_JSON',

package/dist/cjs/index.d.ts

@@ -3,11 +3,11 @@ export { DatumeshError, ERROR_CODES, SPEC_VERSION, type ErrorCode } from './erro
 export { verify, type VerifyResult, type Recompute } from './verify.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 { keysFromResponse, keysFromDocument, fetchKeys, FETCH_TIMEOUT_MS, FETCH_MAX_BYTES, type KeysResult, type KeyEntry, type KeyMap, type KeySource } from './keys.js';
 export type { Kind } from './validate.js';
 export type { JsonValue } from './json.js';
 /** Library version. */
-export declare const VERSION = "0.2.0";
+export declare const VERSION = "0.2.1";
 /**
  * Validate `input` as `kind` and return its RFC 8785 canonical bytes. `input` is JSON text,
  * UTF-8 bytes, or an already-parsed value. `kind` is "scalar", "cell", "ref", "function" or

package/dist/cjs/index.js

@@ -1,6 +1,6 @@
 "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.checkEnvelope = exports.verify = exports.SPEC_VERSION = exports.ERROR_CODES = exports.DatumeshError = void 0;
+exports.VERSION = exports.FETCH_MAX_BYTES = 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;
@@ -9,7 +9,7 @@ exports.receiptPayload = receiptPayload;
 exports.resolvedUnit = resolvedUnit;
 exports.keyId = keyId;
 /**
- * @datumesh/verify: verify Datumesh receipts (SPEC.md, revision spec-0.2.0).
+ * @datumesh/verify: verify Datumesh receipts (SPEC.md, revision spec-0.2.1).
  *
  * Everything here is synchronous and offline except fetchKeys, the only function that uses the
  * network.
@@ -37,8 +37,9 @@ Object.defineProperty(exports, "keysFromResponse", { enumerable: true, get: func
 Object.defineProperty(exports, "keysFromDocument", { enumerable: true, get: function () { return keys_js_1.keysFromDocument; } });
 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; } });
+Object.defineProperty(exports, "FETCH_MAX_BYTES", { enumerable: true, get: function () { return keys_js_1.FETCH_MAX_BYTES; } });
 /** Library version. */
-exports.VERSION = '0.2.0';
+exports.VERSION = '0.2.1';
 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(', ')}`);

package/dist/cjs/json.d.ts

@@ -3,11 +3,10 @@ export interface JsonObject {
     [key: string]: JsonValue;
 }
 /**
- * Nesting deeper than this is rejected with E_PARSE_JSON. SPEC.md sets no depth limit; this is
- * an implementation limit (Datumesh objects nest at most five levels) that keeps parsing and
- * canonicalisation from exhausting the call stack.
+ * SPEC 6.1: at most 64 levels of nesting ([ and { open at once, counted outside strings), checked
+ * before anything else in the text. Datumesh objects nest at most five levels.
  */
-export declare const MAX_DEPTH = 1000;
+export declare const MAX_DEPTH = 64;
 export declare function isObject(v: unknown): v is JsonObject;
 export declare function newObject(): JsonObject;
 export declare function has(o: JsonObject, k: string): boolean;

package/dist/cjs/json.js

@@ -16,11 +16,33 @@ const errors_js_1 = require("./errors.js");
 const unicode_js_1 = require("./unicode.js");
 const utf8_js_1 = require("./utf8.js");
 /**
- * Nesting deeper than this is rejected with E_PARSE_JSON. SPEC.md sets no depth limit; this is
- * an implementation limit (Datumesh objects nest at most five levels) that keeps parsing and
- * canonicalisation from exhausting the call stack.
+ * SPEC 6.1: at most 64 levels of nesting ([ and { open at once, counted outside strings), checked
+ * before anything else in the text. Datumesh objects nest at most five levels.
  */
-exports.MAX_DEPTH = 1000;
+exports.MAX_DEPTH = 64;
+/** SPEC 6.1 order step 3: true when more than MAX_DEPTH brackets are open at once. */
+function tooDeep(s) {
+    let depth = 0;
+    let inString = false;
+    for (let i = 0; i < s.length; i++) {
+        const c = s.charCodeAt(i);
+        if (inString) {
+            if (c === 0x5c)
+                i++; // skip the escaped character
+            else if (c === 0x22)
+                inString = false;
+        }
+        else if (c === 0x22)
+            inString = true;
+        else if (c === 0x5b || c === 0x7b) {
+            if (++depth > exports.MAX_DEPTH)
+                return true;
+        }
+        else if (c === 0x5d || c === 0x7d)
+            depth--;
+    }
+    return false;
+}
 function isObject(v) {
     return typeof v === 'object' && v !== null && !Array.isArray(v);
 }
@@ -70,7 +92,7 @@ class Parser {
     }
     value(path, depth) {
         if (depth > exports.MAX_DEPTH)
-            this.err(`nesting deeper than ${exports.MAX_DEPTH} levels (implementation limit)`);
+            this.err(`nesting deeper than ${exports.MAX_DEPTH} levels`); // tooDeep found it first
         const s = this.s;
         const c = s[this.i];
         if (c === '{')
@@ -256,12 +278,16 @@ class Parser {
 }
 /** Parse JSON text strictly. */
 function parseJsonText(text, numbers) {
+    // SPEC 6.1 order: BOM, (invalid UTF-8: parseJsonBytes), nesting, the first of syntax / NaN /
+    // overflow / duplicate in text order, then lone surrogates.
     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', '$');
+    if (tooDeep(text))
+        (0, errors_js_1.fail)('E_PARSE_JSON', `nesting deeper than ${exports.MAX_DEPTH} levels`, '$');
     const p = new Parser(text, numbers);
     const v = p.parseDocument();
+    if ((0, unicode_js_1.hasLoneSurrogate)(text))
+        (0, errors_js_1.fail)('E_PARSE_JSON', 'lone surrogate in the text', '$');
     if (p.surrogatePath !== null)
         (0, errors_js_1.fail)('E_PARSE_JSON', 'lone surrogate', p.surrogatePath);
     return v;
@@ -283,7 +309,8 @@ function parseJsonBytes(bytes, numbers) {
  * or bytes for that.
  */
 function normalizeValue(v, path = '$', depth = 0) {
-    if (depth > exports.MAX_DEPTH)
+    const container = typeof v === 'object' && v !== null;
+    if (container && depth >= exports.MAX_DEPTH)
         (0, errors_js_1.fail)('E_PARSE_JSON', `nesting deeper than ${exports.MAX_DEPTH} levels (or a cycle)`, path);
     if (v === null || typeof v === 'boolean')
         return v;

package/dist/cjs/keys.d.ts

@@ -34,6 +34,8 @@ export declare function keysFromResponse(host: string, status: number | null, bo
 export declare function keysFromDocument(doc: unknown): KeysResult;
 /** Default timeout of fetchKeys, in milliseconds. */
 export declare const FETCH_TIMEOUT_MS = 10000;
+/** fetchKeys abandons a key document larger than this (SPEC 9.3: SHOULD bound retrieval). */
+export declare const FETCH_MAX_BYTES: number;
 /**
  * Fetch https://<host>/.well-known/datumesh.json once, with TLS verified by the platform, no
  * redirects followed and a timeout, then interpret it with keysFromResponse. The only function

package/dist/cjs/keys.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FETCH_TIMEOUT_MS = void 0;
+exports.FETCH_MAX_BYTES = exports.FETCH_TIMEOUT_MS = void 0;
 exports.keysFromResponse = keysFromResponse;
 exports.keysFromDocument = keysFromDocument;
 exports.fetchKeys = fetchKeys;
@@ -11,6 +11,15 @@ const errors_js_1 = require("./errors.js");
 const hash_js_1 = require("./hash.js");
 const json_js_1 = require("./json.js");
 const lexical_js_1 = require("./lexical.js");
+function isDnsName(s) {
+    try {
+        (0, lexical_js_1.checkDnsName)(s, '$');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 class KeyDocError extends Error {
     constructor(msg, path) {
         super(msg);
@@ -32,6 +41,9 @@ function validateKeyDocument(doc, host) {
             bad(`missing member ${JSON.stringify(k)}`, '$');
     if (doc.proto !== 'datumesh/1')
         bad("proto must be 'datumesh/1'", '$.proto');
+    // 9.2 / 9.3: `host` is a DNS name (2.1); a document for any other host cannot satisfy 9.2.
+    if (typeof doc.host !== 'string' || !isDnsName(doc.host))
+        bad('host must be a DNS name (SPEC 2.1); keys are resolved only for DNS names', '$.host');
     if (doc.host !== host)
         bad(`host must be ${JSON.stringify(host)}`, '$.host');
     const keys = doc.keys;
@@ -134,6 +146,45 @@ function keysFromDocument(doc) {
 }
 /** Default timeout of fetchKeys, in milliseconds. */
 exports.FETCH_TIMEOUT_MS = 10000;
+/** fetchKeys abandons a key document larger than this (SPEC 9.3: SHOULD bound retrieval). */
+exports.FETCH_MAX_BYTES = 256 * 1024;
+class TooLarge extends Error {
+}
+/** Read a response body, abandoning it once it exceeds FETCH_MAX_BYTES. */
+async function readBounded(res) {
+    const reader = res.body && typeof res.body.getReader === 'function' ? res.body.getReader() : null;
+    if (!reader) {
+        const b = new Uint8Array(await res.arrayBuffer());
+        if (b.length > exports.FETCH_MAX_BYTES)
+            throw new TooLarge();
+        return b;
+    }
+    const parts = [];
+    let n = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        n += value.length;
+        if (n > exports.FETCH_MAX_BYTES) {
+            try {
+                await reader.cancel();
+            }
+            catch {
+                // abandoned anyway
+            }
+            throw new TooLarge();
+        }
+        parts.push(value);
+    }
+    const out = new Uint8Array(n);
+    let o = 0;
+    for (const p of parts) {
+        out.set(p, o);
+        o += p.length;
+    }
+    return out;
+}
 /**
  * Fetch https://<host>/.well-known/datumesh.json once, with TLS verified by the platform, no
  * redirects followed and a timeout, then interpret it with keysFromResponse. The only function
@@ -165,9 +216,11 @@ async function fetchKeys(host, timeoutMs = exports.FETCH_TIMEOUT_MS) {
             status = 0;
         if (status !== 200)
             return keysFromResponse(host, status);
-        body = new Uint8Array(await res.arrayBuffer());
+        body = await readBounded(res);
     }
     catch (e) {
+        if (e instanceof TooLarge)
+            return { ok: false, code: 'E_KEY_UNAVAILABLE', host, detail: `key document larger than 256 KiB; retrieval abandoned` };
         return { ok: false, code: 'E_KEY_UNAVAILABLE', host, detail: `retrieval failed: ${e instanceof Error ? e.message : String(e)}` };
     }
     return keysFromResponse(host, status, body);

package/dist/cjs/uri.js

@@ -50,20 +50,29 @@ 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.
+ * SPEC 5.4 step 5: the signature is taken as given (it comes from a descriptor already checked
+ * under section 7), but it must be readable: an object with an `args` object whose members are
+ * objects with a string `type` (E_SCHEMA otherwise, in JCS order of names). Nothing else in it is
+ * examined; an unknown type name fails only when a value of that argument is read (step 6).
  */
 function readSignature(signature) {
     let sig;
     try {
-        sig = (0, json_js_1.toJson)(signature);
+        sig = (0, json_js_1.normalizeValue)(signature, 'signature');
     }
     catch {
-        throw new TypeError('parseUri needs the function signature (descriptor.signature) as JSON');
+        (0, errors_js_1.fail)('E_SCHEMA', 'the signature is not JSON data', 'signature');
+    }
+    if (!(0, json_js_1.isObject)(sig))
+        (0, errors_js_1.fail)('E_SCHEMA', 'the signature is not an object', 'signature');
+    const args = sig.args;
+    if (!(0, json_js_1.isObject)(args))
+        (0, errors_js_1.fail)('E_SCHEMA', 'the signature has no args object', 'signature.args');
+    for (const k of (0, json_js_1.sortedKeys)(args)) {
+        const d = args[k];
+        if (!(0, json_js_1.isObject)(d) || typeof d.type !== 'string')
+            (0, errors_js_1.fail)('E_SCHEMA', `the declaration of ${JSON.stringify(k)} is not an object with a string type`, (0, json_js_1.memberPath)('signature.args', k));
     }
-    if (!(0, json_js_1.isObject)(sig) || !(0, json_js_1.isObject)(sig.args))
-        throw new TypeError('parseUri needs the function signature (descriptor.signature): an object with args');
     return sig;
 }
 /**
@@ -74,8 +83,6 @@ function readSignature(signature) {
 function parseUri(uri, signature) {
     if (typeof uri !== 'string')
         throw new TypeError('uri must be a string');
-    const sig = readSignature(signature);
-    const declared = sig.args;
     // 1. Outer grammar.
     if (!uri.startsWith(SCHEME) || uri.includes('#'))
         (0, errors_js_1.fail)('E_PARSE_URI', 'not cell://<namespace>/<function>[?<query>] without fragment', '$');
@@ -85,8 +92,7 @@ function parseUri(uri, signature) {
     const query = q < 0 ? null : rest.slice(q + 1);
     if (query === '')
         (0, errors_js_1.fail)('E_PARSE_URI', 'empty query', '$');
-    // SPEC 5.1 lists userinfo and a port among outer-grammar failures (E_PARSE_URI). (The
-    // reference tool reports them as E_CANON_NAME; see DEFECTS.md.)
+    // SPEC 5.1: an @ or : in the authority is userinfo or a port (E_PARSE_URI).
     const authority = path.split('/')[0];
     if (authority.includes('@'))
         (0, errors_js_1.fail)('E_PARSE_URI', 'a cell URI has no userinfo', '$');
@@ -135,7 +141,9 @@ function parseUri(uri, signature) {
     // 4. Argument count.
     if (argParams.length > lexical_js_1.LIMITS.args)
         (0, errors_js_1.fail)('E_CANON_LIMIT', `more than ${lexical_js_1.LIMITS.args} arguments`, 'uri.query');
-    // 5. Against the signature: unknown arguments, then missing ones.
+    // 5. The signature (readable, E_SCHEMA), then the arguments against it: unknown arguments,
+    // then missing ones.
+    const declared = readSignature(signature).args;
     for (const p of argParams) {
         if (!Object.prototype.hasOwnProperty.call(declared, p.name))
             (0, errors_js_1.fail)('E_ARG_UNKNOWN', `function declares no argument ${JSON.stringify(p.name)}`, at(p.name));
@@ -152,13 +160,8 @@ function parseUri(uri, signature) {
             args[p.name] = '*';
             continue;
         }
-        const decl = declared[p.name];
-        const type = ((0, json_js_1.isObject)(decl) ? decl.type : undefined);
+        const type = declared[p.name].type;
         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')
-            (0, errors_js_1.fail)('E_SCHEMA', `the signature declares ${p.name} without a string type`, `signature.args.${p.name}`);
         if (!(0, lexical_js_1.isTypeName)(type))
             (0, errors_js_1.fail)('E_CANON_TYPE', `unknown type ${JSON.stringify(type)} in the signature`, `signature.args.${p.name}.type`);
         if (type === 'boolean') {
@@ -205,5 +208,7 @@ function formatUri(ref) {
 function httpsUrl(uri, mesh) {
     if (!uri.startsWith(SCHEME))
         (0, errors_js_1.fail)('E_PARSE_URI', 'not a cell URI', '$');
+    // SPEC 5.3: the mesh is a DNS name on the default HTTPS port (no port, IP address or userinfo).
+    (0, lexical_js_1.checkDnsName)(mesh, 'mesh');
     return `https://${mesh}/cell/${uri.slice(SCHEME.length)}`;
 }

package/dist/esm/ed25519.js

@@ -56,6 +56,8 @@ export function verifyEd25519Strict(sig, msg, pub) {
     const h = sha512(concat(rBytes, pub, msg));
     const k = le(h) % L;
     // R' = [S]B - [k]A (multiplyUnsafe accepts 0; inputs are public, so variable time is fine).
+    // subtract() adds the negation of the point [k]A, as SPEC 10.1 step 6 requires; it is not
+    // [L - k]A, which differs for a mixed-order A (receipt/ed25519-mixed-order-key).
     const SB = s === 0n ? Point.ZERO : Point.BASE.multiplyUnsafe(s);
     const kA = k === 0n ? Point.ZERO : A.multiplyUnsafe(k);
     const rCheck = SB.subtract(kA).toBytes();

package/dist/esm/errors.d.ts

@@ -1,5 +1,5 @@
 /** The spec revision this library conforms to. */
-export declare const SPEC_VERSION = "spec-0.2.0";
+export declare const SPEC_VERSION = "spec-0.2.1";
 /** Every error code defined by SPEC.md 10.2, in the order of that table. */
 export declare const ERROR_CODES: readonly ["E_PARSE_JSON", "E_PARSE_DUPLICATE_KEY", "E_PARSE_URI", "E_SCHEMA", "E_CANON_NAME", "E_CANON_ARG_NAME", "E_CANON_ARG_DUPLICATE", "E_CANON_ARG_ORDER", "E_CANON_PERCENT", "E_CANON_TYPE", "E_CANON_NUMBER", "E_CANON_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];

package/dist/esm/errors.js

@@ -1,5 +1,5 @@
 /** The spec revision this library conforms to. */
-export const SPEC_VERSION = 'spec-0.2.0';
+export const SPEC_VERSION = 'spec-0.2.1';
 /** Every error code defined by SPEC.md 10.2, in the order of that table. */
 export const ERROR_CODES = [
     'E_PARSE_JSON',

package/dist/esm/index.d.ts

@@ -3,11 +3,11 @@ export { DatumeshError, ERROR_CODES, SPEC_VERSION, type ErrorCode } from './erro
 export { verify, type VerifyResult, type Recompute } from './verify.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 { keysFromResponse, keysFromDocument, fetchKeys, FETCH_TIMEOUT_MS, FETCH_MAX_BYTES, type KeysResult, type KeyEntry, type KeyMap, type KeySource } from './keys.js';
 export type { Kind } from './validate.js';
 export type { JsonValue } from './json.js';
 /** Library version. */
-export declare const VERSION = "0.2.0";
+export declare const VERSION = "0.2.1";
 /**
  * Validate `input` as `kind` and return its RFC 8785 canonical bytes. `input` is JSON text,
  * UTF-8 bytes, or an already-parsed value. `kind` is "scalar", "cell", "ref", "function" or

package/dist/esm/index.js

@@ -1,5 +1,5 @@
 /**
- * @datumesh/verify: verify Datumesh receipts (SPEC.md, revision spec-0.2.0).
+ * @datumesh/verify: verify Datumesh receipts (SPEC.md, revision spec-0.2.1).
  *
  * Everything here is synchronous and offline except fetchKeys, the only function that uses the
  * network.
@@ -14,9 +14,9 @@ export { DatumeshError, ERROR_CODES, SPEC_VERSION } from './errors.js';
 export { verify } from './verify.js';
 export { checkEnvelope } from './envelope.js';
 export { parseUri, formatUri, httpsUrl } from './uri.js';
-export { keysFromResponse, keysFromDocument, fetchKeys, FETCH_TIMEOUT_MS } from './keys.js';
+export { keysFromResponse, keysFromDocument, fetchKeys, FETCH_TIMEOUT_MS, FETCH_MAX_BYTES } from './keys.js';
 /** Library version. */
-export const VERSION = '0.2.0';
+export const VERSION = '0.2.1';
 function parseAndValidate(input, kind) {
     if (kind !== undefined && kind !== null && !KINDS.includes(kind))
         throw new TypeError(`unknown kind ${JSON.stringify(kind)}; expected one of ${KINDS.join(', ')}`);

package/dist/esm/json.d.ts

@@ -3,11 +3,10 @@ export interface JsonObject {
     [key: string]: JsonValue;
 }
 /**
- * Nesting deeper than this is rejected with E_PARSE_JSON. SPEC.md sets no depth limit; this is
- * an implementation limit (Datumesh objects nest at most five levels) that keeps parsing and
- * canonicalisation from exhausting the call stack.
+ * SPEC 6.1: at most 64 levels of nesting ([ and { open at once, counted outside strings), checked
+ * before anything else in the text. Datumesh objects nest at most five levels.
  */
-export declare const MAX_DEPTH = 1000;
+export declare const MAX_DEPTH = 64;
 export declare function isObject(v: unknown): v is JsonObject;
 export declare function newObject(): JsonObject;
 export declare function has(o: JsonObject, k: string): boolean;

package/dist/esm/json.js

@@ -4,11 +4,33 @@ import { fail } from './errors.js';
 import { hasLoneSurrogate } from './unicode.js';
 import { utf8Decode } from './utf8.js';
 /**
- * Nesting deeper than this is rejected with E_PARSE_JSON. SPEC.md sets no depth limit; this is
- * an implementation limit (Datumesh objects nest at most five levels) that keeps parsing and
- * canonicalisation from exhausting the call stack.
+ * SPEC 6.1: at most 64 levels of nesting ([ and { open at once, counted outside strings), checked
+ * before anything else in the text. Datumesh objects nest at most five levels.
  */
-export const MAX_DEPTH = 1000;
+export const MAX_DEPTH = 64;
+/** SPEC 6.1 order step 3: true when more than MAX_DEPTH brackets are open at once. */
+function tooDeep(s) {
+    let depth = 0;
+    let inString = false;
+    for (let i = 0; i < s.length; i++) {
+        const c = s.charCodeAt(i);
+        if (inString) {
+            if (c === 0x5c)
+                i++; // skip the escaped character
+            else if (c === 0x22)
+                inString = false;
+        }
+        else if (c === 0x22)
+            inString = true;
+        else if (c === 0x5b || c === 0x7b) {
+            if (++depth > MAX_DEPTH)
+                return true;
+        }
+        else if (c === 0x5d || c === 0x7d)
+            depth--;
+    }
+    return false;
+}
 export function isObject(v) {
     return typeof v === 'object' && v !== null && !Array.isArray(v);
 }
@@ -58,7 +80,7 @@ class Parser {
     }
     value(path, depth) {
         if (depth > MAX_DEPTH)
-            this.err(`nesting deeper than ${MAX_DEPTH} levels (implementation limit)`);
+            this.err(`nesting deeper than ${MAX_DEPTH} levels`); // tooDeep found it first
         const s = this.s;
         const c = s[this.i];
         if (c === '{')
@@ -244,12 +266,16 @@ class Parser {
 }
 /** Parse JSON text strictly. */
 export function parseJsonText(text, numbers) {
+    // SPEC 6.1 order: BOM, (invalid UTF-8: parseJsonBytes), nesting, the first of syntax / NaN /
+    // overflow / duplicate in text order, then lone surrogates.
     if (text.charCodeAt(0) === 0xfeff)
         fail('E_PARSE_JSON', 'byte order mark', '$');
-    if (hasLoneSurrogate(text))
-        fail('E_PARSE_JSON', 'lone surrogate in the text', '$');
+    if (tooDeep(text))
+        fail('E_PARSE_JSON', `nesting deeper than ${MAX_DEPTH} levels`, '$');
     const p = new Parser(text, numbers);
     const v = p.parseDocument();
+    if (hasLoneSurrogate(text))
+        fail('E_PARSE_JSON', 'lone surrogate in the text', '$');
     if (p.surrogatePath !== null)
         fail('E_PARSE_JSON', 'lone surrogate', p.surrogatePath);
     return v;
@@ -271,7 +297,8 @@ export function parseJsonBytes(bytes, numbers) {
  * or bytes for that.
  */
 export function normalizeValue(v, path = '$', depth = 0) {
-    if (depth > MAX_DEPTH)
+    const container = typeof v === 'object' && v !== null;
+    if (container && depth >= MAX_DEPTH)
         fail('E_PARSE_JSON', `nesting deeper than ${MAX_DEPTH} levels (or a cycle)`, path);
     if (v === null || typeof v === 'boolean')
         return v;

package/dist/esm/keys.d.ts

@@ -34,6 +34,8 @@ export declare function keysFromResponse(host: string, status: number | null, bo
 export declare function keysFromDocument(doc: unknown): KeysResult;
 /** Default timeout of fetchKeys, in milliseconds. */
 export declare const FETCH_TIMEOUT_MS = 10000;
+/** fetchKeys abandons a key document larger than this (SPEC 9.3: SHOULD bound retrieval). */
+export declare const FETCH_MAX_BYTES: number;
 /**
  * Fetch https://<host>/.well-known/datumesh.json once, with TLS verified by the platform, no
  * redirects followed and a timeout, then interpret it with keysFromResponse. The only function

package/dist/esm/keys.js

@@ -3,6 +3,15 @@ import { DatumeshError } from './errors.js';
 import { fromHex, keyIdOf } from './hash.js';
 import { has, isObject, memberPath, sortedKeys, toJson } from './json.js';
 import { LIMITS, checkDnsName, isHex, isInstant } from './lexical.js';
+function isDnsName(s) {
+    try {
+        checkDnsName(s, '$');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 class KeyDocError extends Error {
     constructor(msg, path) {
         super(msg);
@@ -24,6 +33,9 @@ function validateKeyDocument(doc, host) {
             bad(`missing member ${JSON.stringify(k)}`, '$');
     if (doc.proto !== 'datumesh/1')
         bad("proto must be 'datumesh/1'", '$.proto');
+    // 9.2 / 9.3: `host` is a DNS name (2.1); a document for any other host cannot satisfy 9.2.
+    if (typeof doc.host !== 'string' || !isDnsName(doc.host))
+        bad('host must be a DNS name (SPEC 2.1); keys are resolved only for DNS names', '$.host');
     if (doc.host !== host)
         bad(`host must be ${JSON.stringify(host)}`, '$.host');
     const keys = doc.keys;
@@ -126,6 +138,45 @@ export function keysFromDocument(doc) {
 }
 /** Default timeout of fetchKeys, in milliseconds. */
 export const FETCH_TIMEOUT_MS = 10000;
+/** fetchKeys abandons a key document larger than this (SPEC 9.3: SHOULD bound retrieval). */
+export const FETCH_MAX_BYTES = 256 * 1024;
+class TooLarge extends Error {
+}
+/** Read a response body, abandoning it once it exceeds FETCH_MAX_BYTES. */
+async function readBounded(res) {
+    const reader = res.body && typeof res.body.getReader === 'function' ? res.body.getReader() : null;
+    if (!reader) {
+        const b = new Uint8Array(await res.arrayBuffer());
+        if (b.length > FETCH_MAX_BYTES)
+            throw new TooLarge();
+        return b;
+    }
+    const parts = [];
+    let n = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        n += value.length;
+        if (n > FETCH_MAX_BYTES) {
+            try {
+                await reader.cancel();
+            }
+            catch {
+                // abandoned anyway
+            }
+            throw new TooLarge();
+        }
+        parts.push(value);
+    }
+    const out = new Uint8Array(n);
+    let o = 0;
+    for (const p of parts) {
+        out.set(p, o);
+        o += p.length;
+    }
+    return out;
+}
 /**
  * Fetch https://<host>/.well-known/datumesh.json once, with TLS verified by the platform, no
  * redirects followed and a timeout, then interpret it with keysFromResponse. The only function
@@ -157,9 +208,11 @@ export async function fetchKeys(host, timeoutMs = FETCH_TIMEOUT_MS) {
             status = 0;
         if (status !== 200)
             return keysFromResponse(host, status);
-        body = new Uint8Array(await res.arrayBuffer());
+        body = await readBounded(res);
     }
     catch (e) {
+        if (e instanceof TooLarge)
+            return { ok: false, code: 'E_KEY_UNAVAILABLE', host, detail: `key document larger than 256 KiB; retrieval abandoned` };
         return { ok: false, code: 'E_KEY_UNAVAILABLE', host, detail: `retrieval failed: ${e instanceof Error ? e.message : String(e)}` };
     }
     return keysFromResponse(host, status, body);

package/dist/esm/uri.js

@@ -1,7 +1,7 @@
 // Cell URIs (SPEC.md section 5).
 import { fail } from './errors.js';
-import { isObject, sortedKeys, toJson } from './json.js';
-import { LIMITS, checkArgName, checkInstant, checkName, checkNamespace, checkTypedValue, isTypeName } from './lexical.js';
+import { isObject, memberPath, normalizeValue, sortedKeys, toJson } from './json.js';
+import { LIMITS, checkArgName, checkDnsName, checkInstant, checkName, checkNamespace, checkTypedValue, isTypeName } from './lexical.js';
 import { utf8Decode, utf8Encode } from './utf8.js';
 import { validate } from './validate.js';
 const SCHEME = 'cell://';
@@ -45,20 +45,29 @@ 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.
+ * SPEC 5.4 step 5: the signature is taken as given (it comes from a descriptor already checked
+ * under section 7), but it must be readable: an object with an `args` object whose members are
+ * objects with a string `type` (E_SCHEMA otherwise, in JCS order of names). Nothing else in it is
+ * examined; an unknown type name fails only when a value of that argument is read (step 6).
  */
 function readSignature(signature) {
     let sig;
     try {
-        sig = toJson(signature);
+        sig = normalizeValue(signature, 'signature');
     }
     catch {
-        throw new TypeError('parseUri needs the function signature (descriptor.signature) as JSON');
+        fail('E_SCHEMA', 'the signature is not JSON data', 'signature');
+    }
+    if (!isObject(sig))
+        fail('E_SCHEMA', 'the signature is not an object', 'signature');
+    const args = sig.args;
+    if (!isObject(args))
+        fail('E_SCHEMA', 'the signature has no args object', 'signature.args');
+    for (const k of sortedKeys(args)) {
+        const d = args[k];
+        if (!isObject(d) || typeof d.type !== 'string')
+            fail('E_SCHEMA', `the declaration of ${JSON.stringify(k)} is not an object with a string type`, memberPath('signature.args', k));
     }
-    if (!isObject(sig) || !isObject(sig.args))
-        throw new TypeError('parseUri needs the function signature (descriptor.signature): an object with args');
     return sig;
 }
 /**
@@ -69,8 +78,6 @@ function readSignature(signature) {
 export function parseUri(uri, signature) {
     if (typeof uri !== 'string')
         throw new TypeError('uri must be a string');
-    const sig = readSignature(signature);
-    const declared = sig.args;
     // 1. Outer grammar.
     if (!uri.startsWith(SCHEME) || uri.includes('#'))
         fail('E_PARSE_URI', 'not cell://<namespace>/<function>[?<query>] without fragment', '$');
@@ -80,8 +87,7 @@ export function parseUri(uri, signature) {
     const query = q < 0 ? null : rest.slice(q + 1);
     if (query === '')
         fail('E_PARSE_URI', 'empty query', '$');
-    // SPEC 5.1 lists userinfo and a port among outer-grammar failures (E_PARSE_URI). (The
-    // reference tool reports them as E_CANON_NAME; see DEFECTS.md.)
+    // SPEC 5.1: an @ or : in the authority is userinfo or a port (E_PARSE_URI).
     const authority = path.split('/')[0];
     if (authority.includes('@'))
         fail('E_PARSE_URI', 'a cell URI has no userinfo', '$');
@@ -130,7 +136,9 @@ export function parseUri(uri, signature) {
     // 4. Argument count.
     if (argParams.length > LIMITS.args)
         fail('E_CANON_LIMIT', `more than ${LIMITS.args} arguments`, 'uri.query');
-    // 5. Against the signature: unknown arguments, then missing ones.
+    // 5. The signature (readable, E_SCHEMA), then the arguments against it: unknown arguments,
+    // then missing ones.
+    const declared = readSignature(signature).args;
     for (const p of argParams) {
         if (!Object.prototype.hasOwnProperty.call(declared, p.name))
             fail('E_ARG_UNKNOWN', `function declares no argument ${JSON.stringify(p.name)}`, at(p.name));
@@ -147,13 +155,8 @@ export function parseUri(uri, signature) {
             args[p.name] = '*';
             continue;
         }
-        const decl = declared[p.name];
-        const type = (isObject(decl) ? decl.type : undefined);
+        const type = declared[p.name].type;
         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') {
@@ -200,5 +203,7 @@ export function formatUri(ref) {
 export function httpsUrl(uri, mesh) {
     if (!uri.startsWith(SCHEME))
         fail('E_PARSE_URI', 'not a cell URI', '$');
+    // SPEC 5.3: the mesh is a DNS name on the default HTTPS port (no port, IP address or userinfo).
+    checkDnsName(mesh, 'mesh');
     return `https://${mesh}/cell/${uri.slice(SCHEME.length)}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datumesh/verify",
-  "version": "0.2.0",
+  "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": {
@@ -10,7 +10,7 @@
   "homepage": "https://datumesh.com",
   "keywords": ["datumesh", "receipt", "verify", "ed25519", "jcs", "rfc8785", "canonical-json"],
   "datumesh": {
-    "spec": "spec-0.2.0"
+    "spec": "spec-0.2.1"
   },
   "type": "module",
   "main": "./dist/cjs/index.js",