@calimero-network/mero-js 18.2.0 → 19.0.0

package/dist/warrant/warrant.js

@@ -7,11 +7,17 @@
  * so "a member with no node" in practice meant "a member with a node it is not
  * allowed to use for anything else".
  *
- * **No dependencies, and that is not incidental.** The three primitives are all
- * built in: `crypto.subtle.digest('SHA-256')` for the hash, `crypto.subtle`
- * Ed25519 for the signature, and `DataView.setBigUint64` for the two u64s. The
- * warrant's every field is fixed-width, so its encoding is concatenation — there
- * is no borsh here because none is needed.
+ * **No dependencies, and that is not incidental.** The primitives are all built
+ * in: `crypto.subtle.digest('SHA-256')` for the hash, `crypto.subtle` Ed25519
+ * for the signature, and `DataView` for the integers.
+ *
+ * Warrant v2 (core#3933) gave up the fixed-width encoding that used to make this
+ * pure concatenation: `method` travels in the clear as a string and each cited
+ * head list is a vector, so three borsh `u32` counts now sit inside the bytes.
+ * Two widths to keep straight, and they are not the same: the counts **inside
+ * the encoding** are `u32`, while the counts the **signing preimage** hashes are
+ * `u64`. Same numbers, different serialization — reusing one for the other
+ * produces a warrant that is well-formed and verifies nowhere.
  *
  * **The byte contract is pinned in core**, at
  * `crates/account/src/tests/warrant_wire_fixture.rs`. The domain strings below
@@ -21,9 +27,16 @@
  * this producing well-formed warrants whose signatures verify nowhere, surfacing
  * at a relay as a 403: an authorization refusal, nowhere near the cause.
  */
-import { concat, derivePublicKey, domainHash, fromHex, hex, importSigningKey, u64le, } from '../crypto/internal.js';
-const SIGN_DOMAIN = new TextEncoder().encode('calimero.warrant.v1');
+import { concat, derivePublicKey, domainHash, fromHex, hex, importSigningKey, u32le, u64le, } from '../crypto/internal.js';
+const SIGN_DOMAIN = new TextEncoder().encode('calimero.warrant.v2');
 const INTENT_DOMAIN = new TextEncoder().encode('calimero.warrant.intent.v1');
+/**
+ * core's `MAX_WARRANT_CITED_HEADS`. A node refuses more than this before doing
+ * any Ed25519 work, so minting past it produces a warrant nothing will spend.
+ */
+const MAX_CITED_HEADS = 64;
+/** 32 zero bytes — the `appVersion` default. See {@link WarrantInput.appVersion}. */
+const UNPINNED_APP = '00'.repeat(32);
 /**
  * The commitment a warrant carries in place of the intent itself.
  *
@@ -37,29 +50,113 @@ export async function intentHash(method, argsJson) {
 /**
  * Sign a warrant and return it hex-encoded, ready for `performIntent`.
  *
- * The 240 bytes are the canonical form: the signature covers exactly them, which
- * is why this returns the encoding rather than an object. A caller that rebuilt
- * the fields from JSON would have a second spelling able to disagree with what
- * was signed.
+ * Returns the encoding rather than an object because the signature covers
+ * exactly these bytes: a caller that rebuilt the fields from JSON would have a
+ * second spelling able to disagree with what was signed.
  */
 export async function signWarrant(input) {
     const context = fromHex(input.context, 'context', 32);
     const authorAccount = fromHex(input.authorAccount, 'authorAccount', 32);
     const executor = fromHex(input.executor, 'executor', 32);
+    const appVersion = fromHex(input.appVersion ?? UNPINNED_APP, 'appVersion', 32);
+    const accountHeads = citedHeads(input.accountHeads, 'accountHeads');
+    const governanceFloor = citedHeads(input.governanceFloor, 'governanceFloor');
     const key = await importSigningKey(input.deviceSecret);
     const publicKey = await derivePublicKey(input.deviceSecret);
+    const method = new TextEncoder().encode(input.method);
     const commitment = await intentHash(input.method, input.argsJson);
     const nonce = u64le(input.nonce);
     const notAfter = u64le(input.notAfter);
+    // Each head list is preceded by its own count. `domainHash` length-prefixes
+    // every part it is given, so the heads are individually unambiguous — but the
+    // two lists are adjacent, so without the counts `accountHeads = [a, b],
+    // governanceFloor = []` hashes identically to `[a], [b]`, and a relay could
+    // relabel which plane a head was cited from. u64 HERE; u32 in the encoding.
     const preimage = await domainHash(SIGN_DOMAIN, [
         context,
         authorAccount,
         publicKey,
         executor,
+        appVersion,
+        method,
         commitment,
+        u64le(accountHeads.length),
+        ...accountHeads,
+        u64le(governanceFloor.length),
+        ...governanceFloor,
         nonce,
         notAfter,
     ]);
     const signature = new Uint8Array(await crypto.subtle.sign({ name: 'Ed25519' }, key, preimage));
-    return hex(concat(context, authorAccount, publicKey, executor, commitment, nonce, notAfter, signature));
+    // Borsh: a `String` is a u32 length then its UTF-8 bytes; a `Vec<[u8; 32]>` is
+    // a u32 count then the elements. u32 HERE; u64 in the preimage above.
+    return hex(concat(context, authorAccount, publicKey, executor, appVersion, u32le(method.length), method, commitment, u32le(accountHeads.length), ...accountHeads, u32le(governanceFloor.length), ...governanceFloor, nonce, notAfter, signature));
+}
+/** Decode a cited-head list, refusing one longer than a node will accept. */
+function citedHeads(heads, label) {
+    const list = heads ?? [];
+    if (list.length > MAX_CITED_HEADS) {
+        throw new Error(`${label} cites ${list.length} heads, over the ${MAX_CITED_HEADS} a node accepts`);
+    }
+    return list.map((head, i) => fromHex(head, `${label}[${i}]`, 32));
+}
+/**
+ * Decode a hex warrant back into its fields.
+ *
+ * Exists because v2's offsets are no longer constants: `method` is a string and
+ * the head lists are vectors, so everything after `appVersion` moves with the
+ * method's length. Anything reading a warrant by fixed offset — a test, a client
+ * inspecting one it was handed — silently reads the wrong field instead of
+ * failing, which is how the three call sites that did so passed while comparing
+ * the method's length prefix to a nonce.
+ *
+ * One copy of the layout, beside the encoder that produces it, so the two cannot
+ * drift. Internal: not exported from the package root, because a client that
+ * needs a warrant's fields has the input it signed.
+ */
+export function parseWarrant(warrant) {
+    const at = (start, bytes) => warrant.slice(start * 2, (start + bytes) * 2);
+    // A borsh u32 is little-endian, so the hex pairs read back to front.
+    const u32At = (start) => Number.parseInt((at(start, 4).match(/../g) ?? []).reverse().join(''), 16);
+    let o = 0;
+    const take = (bytes) => {
+        const field = at(o, bytes);
+        o += bytes;
+        return field;
+    };
+    const context = take(32);
+    const authorAccount = take(32);
+    const deviceKey = take(32);
+    const executor = take(32);
+    const appVersion = take(32);
+    const methodLen = u32At(o);
+    o += 4;
+    const method = take(methodLen);
+    const intentHashField = take(32);
+    const accountCount = u32At(o);
+    o += 4;
+    const accountHeads = Array.from({ length: accountCount }, () => take(32));
+    const governanceCount = u32At(o);
+    o += 4;
+    const governanceFloor = Array.from({ length: governanceCount }, () => take(32));
+    const nonce = take(8);
+    const notAfter = take(8);
+    const signature = take(64);
+    if (o * 2 !== warrant.length) {
+        throw new Error(`warrant is ${warrant.length / 2} bytes but its fields account for ${o}`);
+    }
+    return {
+        context,
+        authorAccount,
+        deviceKey,
+        executor,
+        appVersion,
+        method,
+        intentHash: intentHashField,
+        accountHeads,
+        governanceFloor,
+        nonce,
+        notAfter,
+        signature,
+    };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calimero-network/mero-js",
-  "version": "18.2.0",
+  "version": "19.0.0",
   "description": "Pure JavaScript SDK for Calimero",
   "type": "module",
   "exports": {
@@ -50,6 +50,7 @@
     "typecheck": "tsc --noEmit",
     "typecheck:contract": "tsc --noEmit -p tsconfig.contract.json",
     "typecheck:consumer": "tsc --noEmit -p tsconfig.consumer.json",
+    "typecheck:e2e": "tsc --noEmit -p tsconfig.e2e.json",
     "test:contract": "vitest run --config vitest.config.ts src/__contract__",
     "tsc": "tsc -b",
     "clean": "pnpm rimraf dist",