@calimero-network/mero-js 13.2.5 → 13.4.0

package/dist/index.d.ts

@@ -16,6 +16,8 @@ export type { SseEventData, WsEventData, AppVersionChangedEvent, GroupMembership
 export { EphemeralClient, jsonCodec } from './ephemeral/index.js';
 export type { Codec, EphemeralEntry } from './ephemeral/index.js';
 export * from './cloud/index.js';
+export { signWarrant, intentHash } from './warrant/index.js';
+export type { WarrantInput } from './warrant/index.js';
 export * from './capabilities.js';
 export { DEFAULT_LOCAL_NODE_PORTS, localNodeUrl, nodeEndpoint, probeNodeHealth, discoverLocalNodes, } from './nodeDiscovery.js';
 export type { DiscoverLocalNodesOptions } from './nodeDiscovery.js';

package/dist/index.js

@@ -22,6 +22,8 @@ export { SseClient, WsClient } from './events/index.js';
 export { EphemeralClient, jsonCodec } from './ephemeral/index.js';
 // Cloud client (enable-HA, disable-HA)
 export * from './cloud/index.js';
+// Warrant signing — mint the author's consent for a relay to run one intent
+export { signWarrant, intentHash } from './warrant/index.js';
 // Member capability bitmask constants & helpers
 export * from './capabilities.js';
 // Utilities

package/dist/index.mjs

@@ -1096,6 +1096,40 @@ var AdminApiClient = class {
     const node = await this.getNodeIdentity();
     return { namespaceId, publicKey: node.publicKey, account: node.accountId };
   }
+  /**
+   * Ask this node to run one method on a member's behalf, under a warrant that
+   * member signed.
+   *
+   * The node executes and signs the envelope with its own key; the change is
+   * attributed to the **author**. Both halves travel together, so every peer
+   * re-checks that the member consented instead of trusting the relay.
+   *
+   * Three things have to be true first, and none is implied by the others:
+   *
+   * - the author's **account** is a member of the group owning the context —
+   *   their device joins nothing and is in no group's binding rows, which is
+   *   exactly the case a device certificate covers;
+   * - this node holds `CAN_AUTHOR_ON_BEHALF` on that group, which is implied by
+   *   neither membership nor admin;
+   * - the warrant has not been spent. It is single-use: presenting a valid one
+   *   twice is refused, because the signature stays valid forever and replay is
+   *   not forgery.
+   *
+   * A refusal comes back as a `403` carrying the reason — "an admin must grant
+   * CAN_AUTHOR_ON_BEHALF to …", or that the nonce is already spent — so a caller
+   * can tell which precondition failed rather than only that one did.
+   *
+   * Mint the warrant with {@link signWarrant}; see
+   * {@link PerformIntentRequest.warrant}.
+   */
+  async performIntent(contextId, request) {
+    return unwrap(
+      await this.httpClient.post(
+        `/admin-api/contexts/${contextId}/intents`,
+        request
+      )
+    );
+  }
   async listNamespacesForApplication(applicationId) {
     return unwrap(await this.httpClient.get(`/admin-api/namespaces/for-application/${applicationId}`));
   }
@@ -2462,10 +2496,10 @@ function toHex(bytes) {
   for (const byte of bytes) out += byte.toString(16).padStart(2, "0");
   return out;
 }
-function fromHex(hex) {
-  const bytes = new Uint8Array(hex.length / 2);
+function fromHex(hex2) {
+  const bytes = new Uint8Array(hex2.length / 2);
   for (let i = 0; i < bytes.length; i++) {
-    bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    bytes[i] = parseInt(hex2.slice(i * 2, i * 2 + 2), 16);
   }
   return bytes;
 }
@@ -2570,6 +2604,182 @@ var CloudClient = class {
   }
 };
 
+// src/warrant/warrant.ts
+var SIGN_DOMAIN = new TextEncoder().encode("calimero.warrant.v1");
+var INTENT_DOMAIN = new TextEncoder().encode("calimero.warrant.intent.v1");
+var PKCS8_ED25519_PREFIX = new Uint8Array([
+  48,
+  46,
+  2,
+  1,
+  0,
+  48,
+  5,
+  6,
+  3,
+  43,
+  101,
+  112,
+  4,
+  34,
+  4,
+  32
+]);
+var B58 = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+function hex(bytes) {
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+function fromHex2(value, label, expectedBytes) {
+  const clean = value.trim();
+  if (!/^[0-9a-fA-F]*$/.test(clean) || clean.length !== expectedBytes * 2) {
+    throw new Error(
+      `${label} must be ${expectedBytes * 2} hex characters, got ${clean.length}`
+    );
+  }
+  const bytes = new Uint8Array(expectedBytes);
+  for (let i = 0; i < expectedBytes; i += 1) {
+    bytes[i] = Number.parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}
+function fromBase58(value, label) {
+  const clean = value.trim();
+  let n = 0n;
+  for (const char of clean) {
+    const digit = B58.indexOf(char);
+    if (digit < 0) {
+      throw new Error(`${label} is not base58: unexpected character '${char}'`);
+    }
+    n = n * 58n + BigInt(digit);
+  }
+  const out = new Uint8Array(32);
+  for (let i = 31; i >= 0; i -= 1) {
+    out[i] = Number(n & 0xffn);
+    n >>= 8n;
+  }
+  if (n !== 0n) {
+    throw new Error(`${label} decodes to more than 32 bytes`);
+  }
+  if (toBase58(out) !== clean) {
+    throw new Error(
+      `${label} is not a canonical base58 32-byte id. If you have it in hex, note that ${label} is base58 here while accounts are hex`
+    );
+  }
+  return out;
+}
+function toBase58(bytes) {
+  let n = 0n;
+  for (const byte of bytes) {
+    n = n << 8n | BigInt(byte);
+  }
+  let out = "";
+  while (n > 0n) {
+    out = B58[Number(n % 58n)] + out;
+    n /= 58n;
+  }
+  let leadingZeros = 0;
+  while (leadingZeros < bytes.length && bytes[leadingZeros] === 0) {
+    leadingZeros += 1;
+  }
+  return "1".repeat(leadingZeros) + out;
+}
+function u64le(value) {
+  const out = new Uint8Array(8);
+  new DataView(out.buffer).setBigUint64(0, BigInt(value), true);
+  return out;
+}
+function concat(...parts) {
+  const out = new Uint8Array(parts.reduce((total, p) => total + p.length, 0));
+  let offset = 0;
+  for (const part of parts) {
+    out.set(part, offset);
+    offset += part.length;
+  }
+  return out;
+}
+async function domainHash(domain, parts) {
+  const chunks = [u64le(domain.length), domain];
+  for (const part of parts) {
+    chunks.push(u64le(part.length), part);
+  }
+  return new Uint8Array(
+    await crypto.subtle.digest("SHA-256", concat(...chunks))
+  );
+}
+async function intentHash(method, argsJson) {
+  const args = new TextEncoder().encode(JSON.stringify(argsJson));
+  return domainHash(INTENT_DOMAIN, [new TextEncoder().encode(method), args]);
+}
+async function importSigningKey(secretHex) {
+  const seed = fromHex2(secretHex, "deviceSecret", 32);
+  const pkcs8 = concat(PKCS8_ED25519_PREFIX, seed);
+  try {
+    return await crypto.subtle.importKey(
+      "pkcs8",
+      pkcs8,
+      { name: "Ed25519" },
+      false,
+      ["sign"]
+    );
+  } catch (cause) {
+    const detail = cause instanceof Error ? `: ${cause.message}` : "";
+    throw new Error(
+      "this runtime has no WebCrypto Ed25519, so a warrant cannot be signed here. Node 18.4+, Safari 17+, Firefox 129+ and Chrome 137+ have it; otherwise mint the warrant with `merod account warrant`" + detail
+    );
+  }
+}
+async function signWarrant(input) {
+  const context = fromBase58(input.context, "context");
+  const authorAccount = fromHex2(input.authorAccount, "authorAccount", 32);
+  const executor = fromHex2(input.executor, "executor", 32);
+  const key = await importSigningKey(input.deviceSecret);
+  const publicKey = await derivePublicKey(input.deviceSecret);
+  const commitment = await intentHash(input.method, input.argsJson);
+  const nonce = u64le(input.nonce);
+  const notAfter = u64le(input.notAfter);
+  const preimage = await domainHash(SIGN_DOMAIN, [
+    context,
+    authorAccount,
+    publicKey,
+    executor,
+    commitment,
+    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
+    )
+  );
+}
+async function derivePublicKey(secretHex) {
+  const seed = fromHex2(secretHex, "deviceSecret", 32);
+  const pkcs8 = concat(PKCS8_ED25519_PREFIX, seed);
+  const key = await crypto.subtle.importKey(
+    "pkcs8",
+    pkcs8,
+    { name: "Ed25519" },
+    true,
+    ["sign"]
+  );
+  const jwk = await crypto.subtle.exportKey("jwk", key);
+  const raw = jwk.x;
+  return Uint8Array.from(
+    atob(raw.replace(/-/g, "+").replace(/_/g, "/")),
+    (c) => c.charCodeAt(0)
+  );
+}
+
 // src/capabilities.ts
 var CAPABILITIES = {
   CAN_CREATE_CONTEXT: 1 << 0,
@@ -2682,12 +2892,14 @@ export {
   createUniversalHttpClient,
   discoverLocalNodes,
   hasCap,
+  intentHash,
   jsonCodec,
   localNodeUrl,
   nodeEndpoint,
   parseAuthCallback,
   probeNodeHealth,
   sameAccount,
+  signWarrant,
   toAccountBase58,
   toAccountHex,
   withCap,