@calimero-network/mero-js 24.2.0 → 24.4.0

package/dist/relay/relay-client.d.ts

@@ -18,8 +18,9 @@
  * # The three preconditions, and why they are checked in this order
  *
  * `describe()` answers the first two in one call, before anything is signed:
- * the relay's executor account and signing key (which the warrant must name)
- * and whether it holds `CAN_AUTHOR_ON_BEHALF` on the owning group. The third,
+ * the relay's executor account and signing key and the release the context's
+ * group names (which the warrant must name), and whether it holds
+ * `CAN_AUTHOR_ON_BEHALF` on the owning group. The third,
  * that the author's account is a member, only the group knows, and it surfaces
  * as a refusal.
  *
@@ -43,7 +44,7 @@ export interface RelayClientConfig {
      * The account the relay writes as, hex — a warrant's `executor`.
      *
      * Only checked against what the relay answers: a warrant also names the
-     * relay's signing key, which only discovery reports, so the first call asks.
+     * relay's signing key and the release, which only discovery reports, so every write asks.
      */
     executorAccount?: string;
     /** The author's account, hex — whose consent the warrant carries. */
@@ -83,9 +84,9 @@ export interface RelayClientConfig {
     /**
      * Seconds a minted warrant stays valid. Defaults to 300.
      *
-     * Checked by the relay against its own clock and deliberately never by peers,
-     * so this bounds how long *this* request may sit in flight — not how long the
-     * network will accept the delta.
+     * Checked by the relay against its own clock, and by peers against the
+     * delta's own signed stamp, never their clocks: this bounds how long *this*
+     * request may sit in flight before the relay runs it.
      */
     ttlSeconds?: number;
     /** Injected for tests and non-browser runtimes. Defaults to global `fetch`. */
@@ -113,6 +114,13 @@ export interface RelayDescription extends RelayExecutor {
     canAuthorOnBehalf: boolean;
     /** The group whose admin grants that capability, hex. */
     groupId: string;
+    /**
+     * The blob id of the release the group names, hex: what a warrant must pin
+     * as `release_bytecode_id`. Discovery answers 404 while the group names none.
+     */
+    releaseBytecodeId: string;
+    /** That release's semver, signed as the warrant's `release_version`. */
+    releaseVersion: string;
 }
 /** What a relay says about its ability to create contexts in one group. */
 export interface CreationDescription extends RelayExecutor {
@@ -291,7 +299,6 @@ export declare class IntentRefusedError extends Error {
 }
 export declare class RelayClient {
     private readonly baseUrl;
-    private executor;
     private readonly config;
     private readonly fetchImpl;
     private readonly timeoutMs;
@@ -440,7 +447,7 @@ export declare class RelayClient {
     foundNamespace(input: FoundNamespaceInput): Promise<FoundedNamespace>;
     private postGovernance;
     /**
-     * The relay's answer, checked against a configured account and remembered.
+     * The relay's answer, checked against a configured account.
      * Decoded here so a relay naming no key is refused before a nonce is taken.
      */
     private checkedExecutor;

package/dist/relay/relay-client.js

@@ -18,8 +18,9 @@
  * # The three preconditions, and why they are checked in this order
  *
  * `describe()` answers the first two in one call, before anything is signed:
- * the relay's executor account and signing key (which the warrant must name)
- * and whether it holds `CAN_AUTHOR_ON_BEHALF` on the owning group. The third,
+ * the relay's executor account and signing key and the release the context's
+ * group names (which the warrant must name), and whether it holds
+ * `CAN_AUTHOR_ON_BEHALF` on the owning group. The third,
  * that the author's account is a member, only the group knows, and it surfaces
  * as a refusal.
  *
@@ -27,7 +28,7 @@
  * monotonic per-device sequence, and one minted against the wrong executor is
  * unspendable: the number is gone and the write never happened.
  */
-import { signWarrant } from '../warrant/warrant.js';
+import { releaseVersionBytes, signWarrant } from '../warrant/warrant.js';
 import { resolveSigner } from '../signer/signer.js';
 import { signCreationWarrant } from '../warrant/creation-warrant.js';
 import { signGovernanceWarrant } from '../warrant/governance-warrant.js';
@@ -137,9 +138,6 @@ export class RelayClient {
      */
     async describe(contextId) {
         const body = await this.json('GET', `/admin-api/contexts/${encodeURIComponent(contextId)}/intents`);
-        // Learned, not merely returned: a client that called `describe` should not
-        // then have to pass the executor back in to `execute`.
-        this.checkedExecutor(body.data);
         return body.data;
     }
     /**
@@ -150,7 +148,13 @@ export class RelayClient {
      * apply. Nothing accumulates and nothing is reusable.
      */
     async execute(contextId, method, argsJson = {}) {
-        const executor = this.executor ?? this.checkedExecutor(await this.describe(contextId));
+        // Asked on every write: the release moves with each upgrade of the group, and a
+        // warrant pinning the one before is refused. All of it is checked before the nonce.
+        const described = await this.describe(contextId);
+        const executor = this.checkedExecutor(described);
+        const releaseBytecodeId = hex(fromHex(described.releaseBytecodeId ?? '', "the relay's releaseBytecodeId", 32));
+        const releaseVersion = described.releaseVersion ?? '';
+        releaseVersionBytes(releaseVersion);
         // Resolved before the nonce, so a misconfigured key burns none.
         const signer = await this.authorSigner();
         const nonce = await this.config.nonces.next();
@@ -160,18 +164,15 @@ export class RelayClient {
             authorAccount: this.config.authorAccount,
             executor: executor.executorAccount,
             executorKey: executor.executorKey,
+            releaseBytecodeId,
+            releaseVersion,
             method,
             argsJson,
             nonce,
             notAfter: BigInt(Math.floor(Date.now() / 1000)) + BigInt(ttl),
             signer,
         });
-        const body = await this.json('POST', `/admin-api/contexts/${encodeURIComponent(contextId)}/intents`, { method, argsJson, warrant, authorProof: this.config.authorProof }).catch((err) => {
-            // A relay that re-keyed refuses every warrant naming its old key, so ask again next time.
-            if (err instanceof IntentRefusedError)
-                this.executor = undefined;
-            throw err;
-        });
+        const body = await this.json('POST', `/admin-api/contexts/${encodeURIComponent(contextId)}/intents`, { method, argsJson, warrant, authorProof: this.config.authorProof });
         return { rootHash: body.data.rootHash, returns: body.data.returns ?? null };
     }
     /**
@@ -412,7 +413,7 @@ export class RelayClient {
         return body.data;
     }
     /**
-     * The relay's answer, checked against a configured account and remembered.
+     * The relay's answer, checked against a configured account.
      * Decoded here so a relay naming no key is refused before a nonce is taken.
      */
     checkedExecutor(answered) {
@@ -425,7 +426,6 @@ export class RelayClient {
             throw new Error(`configured executorAccount ${configured} is not the relay's account ` +
                 `${executor.executorAccount}; a warrant naming it would be unspendable`);
         }
-        this.executor = executor;
         return executor;
     }
     /**

package/dist/warrant/warrant.d.ts

@@ -50,21 +50,19 @@ export interface WarrantInput {
      */
     executorKey: string;
     /**
-     * The application build this warrant is signed against, hex (32 bytes).
+     * The blob id of the release the context's group names, hex (32 bytes): the
+     * relay's `releaseBytecodeId` from discovery.
      *
-     * Pins the code rather than a version string, so a relay cannot wait for an
-     * upgrade that widens what `method` does and then spend a warrant signed
-     * against the narrower one. Read it from the context
-     * (`GET /admin-api/contexts/{id}` → `applicationId`); a value guessed here
-     * pins the wrong build, which is worse than not pinning.
-     *
-     * Defaults to 32 zero bytes, matching `merod account sign-warrant`'s
-     * `--app-version` default. Nothing verifies the field yet — core#3933 landed
-     * the field set ahead of its enforcement so a signer is written once against
-     * the final bytes — but a warrant minted with the default will be refused once
-     * pinning lands, so pass the real value for anything meant to outlive it.
+     * Pins the code, so a relay cannot wait for an upgrade that widens what
+     * `method` does and then spend a warrant signed against the narrower one. The
+     * relay refuses a warrant pinning any release other than the one it runs.
+     */
+    releaseBytecodeId: string;
+    /**
+     * That release's semver, discovery's `releaseVersion`: signed, never compared,
+     * at most 256 bytes of UTF-8. Defaults to empty, as `merod account warrant` does.
      */
-    appVersion?: string;
+    releaseVersion?: string;
     /**
      * The method the relay may run.
      *
@@ -149,6 +147,8 @@ export declare function signWarrant(input: WarrantInput): Promise<string>;
  * relay, far from the signer at fault. Internal.
  */
 export declare function checkedSignature(signature: Uint8Array): Uint8Array;
+/** A release version as UTF-8, refused past what a node accepts. Shared with `RelayClient`; internal. */
+export declare function releaseVersionBytes(version: string): Uint8Array;
 export declare function citedHeads(heads: string[] | undefined, label: string): Uint8Array[];
 /** A warrant's fields, as hex, decoded from the wire encoding. */
 export interface WarrantFields {
@@ -158,7 +158,9 @@ export interface WarrantFields {
     deviceKey: string;
     executor: string;
     executorKey: string;
-    appVersion: string;
+    releaseBytecodeId: string;
+    /** UTF-8, as hex like `method`. */
+    releaseVersion: string;
     method: string;
     intentHash: string;
     accountHeads: string[];
@@ -173,11 +175,11 @@ export interface WarrantFields {
  * 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.
+ * the head lists are vectors, so everything after `releaseBytecodeId` moves with
+ * the release version's and the method's lengths. 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

package/dist/warrant/warrant.js

@@ -36,8 +36,8 @@ const INTENT_DOMAIN = new TextEncoder().encode('calimero.warrant.intent.v1');
  * 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);
+/** core's `MAX_WARRANT_RELEASE_VERSION_LEN`, in UTF-8 bytes; a node refuses a longer one before any signature work. */
+const MAX_RELEASE_VERSION_LEN = 256;
 /**
  * The commitment a warrant carries in place of the intent itself.
  *
@@ -60,7 +60,8 @@ export async function signWarrant(input) {
     const authorAccount = fromHex(input.authorAccount, 'authorAccount', 32);
     const executor = fromHex(input.executor, 'executor', 32);
     const executorKey = fromHex(input.executorKey, 'executorKey', 32);
-    const appVersion = fromHex(input.appVersion ?? UNPINNED_APP, 'appVersion', 32);
+    const releaseBytecodeId = fromHex(input.releaseBytecodeId, 'releaseBytecodeId', 32);
+    const releaseVersion = releaseVersionBytes(input.releaseVersion ?? '');
     const accountHeads = citedHeads(input.accountHeads, 'accountHeads');
     const governanceFloor = citedHeads(input.governanceFloor, 'governanceFloor');
     const signer = await resolveSigner(input.deviceSecret, input.signer, 'deviceSecret');
@@ -80,7 +81,8 @@ export async function signWarrant(input) {
         publicKey,
         executor,
         executorKey,
-        appVersion,
+        releaseBytecodeId,
+        releaseVersion,
         method,
         commitment,
         u64le(accountHeads.length),
@@ -93,7 +95,7 @@ export async function signWarrant(input) {
     const signature = checkedSignature(await signer.sign(preimage));
     // 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, executorKey, appVersion, u32le(method.length), method, commitment, u32le(accountHeads.length), ...accountHeads, u32le(governanceFloor.length), ...governanceFloor, nonce, notAfter, signature));
+    return hex(concat(context, authorAccount, publicKey, executor, executorKey, releaseBytecodeId, u32le(releaseVersion.length), releaseVersion, 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.
@@ -113,6 +115,17 @@ export function checkedSignature(signature) {
     }
     return signature;
 }
+/** A release version as UTF-8, refused past what a node accepts. Shared with `RelayClient`; internal. */
+export function releaseVersionBytes(version) {
+    const bytes = new TextEncoder().encode(version);
+    checkReleaseVersionLength(bytes.length);
+    return bytes;
+}
+function checkReleaseVersionLength(len) {
+    if (len > MAX_RELEASE_VERSION_LEN) {
+        throw new Error(`releaseVersion is ${len} bytes, over the ${MAX_RELEASE_VERSION_LEN} a node accepts`);
+    }
+}
 export function citedHeads(heads, label) {
     const list = heads ?? [];
     if (list.length > MAX_CITED_HEADS) {
@@ -124,11 +137,11 @@ export function citedHeads(heads, label) {
  * 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.
+ * the head lists are vectors, so everything after `releaseBytecodeId` moves with
+ * the release version's and the method's lengths. 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
@@ -149,7 +162,11 @@ export function parseWarrant(warrant) {
     const deviceKey = take(32);
     const executor = take(32);
     const executorKey = take(32);
-    const appVersion = take(32);
+    const releaseBytecodeId = take(32);
+    const releaseVersionLen = u32At(o);
+    o += 4;
+    checkReleaseVersionLength(releaseVersionLen);
+    const releaseVersion = take(releaseVersionLen);
     const methodLen = u32At(o);
     o += 4;
     const method = take(methodLen);
@@ -172,7 +189,8 @@ export function parseWarrant(warrant) {
         deviceKey,
         executor,
         executorKey,
-        appVersion,
+        releaseBytecodeId,
+        releaseVersion,
         method,
         intentHash: intentHashField,
         accountHeads,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calimero-network/mero-js",
-  "version": "24.2.0",
+  "version": "24.4.0",
   "description": "Pure JavaScript SDK for Calimero",
   "type": "module",
   "exports": {