@calimero-network/mero-js 22.2.0 → 22.4.0

package/dist/index.d.ts

@@ -18,14 +18,14 @@ export type { Codec, EphemeralEntry } from "./ephemeral/index.js";
 export * from "./cloud/index.js";
 export * from "./sealed/index.js";
 export * from "./relay/index.js";
-export { signWarrant, intentHash } from "./warrant/index.js";
+export { signWarrant, intentHash, signCreationWarrant, parseCreationWarrant, creationInitHash, } from "./warrant/index.js";
 export { generateAccountRoot, accountRootFromPhrase, accountRootFromSecret, signAccountLink, signAccountLogin, } from "./account/index.js";
 export type { AccountRoot, RecoverableAccountRoot, AccountLinkInput, AccountLoginInput, } from "./account/index.js";
 export { signDeviceCert, mintDeviceId, deviceCertPayload, accountForRoot, } from "./device-cert/index.js";
 export type { DeviceCertInput } from "./device-cert/index.js";
 export { signMemberJoinOp, encodeSignedInvitation, SIGNED_NAMESPACE_OP_SCHEMA_VERSION, } from "./namespace-op/index.js";
 export type { SignMemberJoinInput } from "./namespace-op/index.js";
-export type { WarrantInput } from "./warrant/index.js";
+export type { WarrantInput, CreationWarrantInput, CreationWarrantFields, SignedCreationWarrant, } from "./warrant/index.js";
 export { requestBodyHash, signRequest, callerProof, createProofSigner, } from "./request/index.js";
 export type { CallerProofInput, ProofRequest, ProofSignerOptions, } from "./request/index.js";
 export type { RequestSigInput } from "./request/index.js";

package/dist/index.js

@@ -27,7 +27,7 @@ export * from "./sealed/index.js";
 // Relay client — write through delegated execution, holding only a signing key
 export * from "./relay/index.js";
 // Warrant signing — mint the author's consent for a relay to run one intent
-export { signWarrant, intentHash } from "./warrant/index.js";
+export { signWarrant, intentHash, signCreationWarrant, parseCreationWarrant, creationInitHash, } from "./warrant/index.js";
 // Account roots — mint one with a recovery phrase, or prove you hold one
 export { generateAccountRoot, accountRootFromPhrase, accountRootFromSecret, signAccountLink, signAccountLogin, } from "./account/index.js";
 export { signDeviceCert, mintDeviceId, deviceCertPayload, accountForRoot, } from "./device-cert/index.js";

package/dist/index.mjs

@@ -2183,11 +2183,11 @@ function u32le(value) {
 function hex(bytes) {
   return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
 }
-function fromHex(value, label, expectedBytes) {
+function fromHex(value, label2, 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}`
+      `${label2} must be ${expectedBytes * 2} hex characters, got ${clean.length}`
     );
   }
   const bytes = new Uint8Array(expectedBytes);
@@ -2196,10 +2196,10 @@ function fromHex(value, label, expectedBytes) {
   }
   return bytes;
 }
-function fromHexUnsized(value, label) {
+function fromHexUnsized(value, label2) {
   const clean = value.trim();
   if (!/^[0-9a-fA-F]*$/.test(clean) || clean.length % 2 !== 0) {
-    throw new Error(`${label} must be an even number of hex characters`);
+    throw new Error(`${label2} must be an even number of hex characters`);
   }
   const bytes = new Uint8Array(clean.length / 2);
   for (let i = 0; i < bytes.length; i += 1) {
@@ -6513,14 +6513,172 @@ async function signWarrant(input) {
     )
   );
 }
-function citedHeads(heads, label) {
+function citedHeads(heads, label2) {
   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`
+      `${label2} cites ${list.length} heads, over the ${MAX_CITED_HEADS} a node accepts`
     );
   }
-  return list.map((head, i) => fromHex(head, `${label}[${i}]`, 32));
+  return list.map((head, i) => fromHex(head, `${label2}[${i}]`, 32));
+}
+
+// src/warrant/creation-warrant.ts
+var SIGN_DOMAIN3 = new TextEncoder().encode("calimero.context-creation-warrant.v1");
+var INIT_DOMAIN = new TextEncoder().encode("calimero.context-creation.init.v1");
+var MAX_LABEL_BYTES = 256;
+async function creationInitHash(initArgs) {
+  const bytes = new TextEncoder().encode(JSON.stringify(initArgs));
+  return domainHash(INIT_DOMAIN, [bytes]);
+}
+async function creationWarrantPreimage(p) {
+  return domainHash(SIGN_DOMAIN3, [
+    p.group,
+    p.seed,
+    p.authorAccount,
+    p.deviceKey,
+    p.executor,
+    p.applicationId,
+    new Uint8Array([p.serviceName === null ? 0 : 1]),
+    p.serviceName ?? new Uint8Array(0),
+    new Uint8Array([p.name === null ? 0 : 1]),
+    p.name ?? new Uint8Array(0),
+    p.initHash,
+    u64le(p.accountHeads.length),
+    ...p.accountHeads,
+    u64le(p.governanceFloor.length),
+    ...p.governanceFloor,
+    u64le(p.nonce),
+    u64le(p.notAfter)
+  ]);
+}
+async function signCreationWarrant(input) {
+  const group = fromHex(input.group, "group", 32);
+  const seed = input.seed === void 0 ? crypto.getRandomValues(new Uint8Array(32)) : fromHex(input.seed, "seed", 32);
+  const authorAccount = fromHex(input.authorAccount, "authorAccount", 32);
+  const executor = fromHex(input.executor, "executor", 32);
+  const applicationId = fromHex(input.applicationId, "applicationId", 32);
+  const serviceName = label(input.serviceName, "serviceName");
+  const name = label(input.name, "name");
+  const accountHeads = citedHeads(input.accountHeads, "accountHeads");
+  const governanceFloor = citedHeads(input.governanceFloor, "governanceFloor");
+  const key = await importSigningKey(input.deviceSecret);
+  const deviceKey = await derivePublicKey(input.deviceSecret);
+  const initHash = await creationInitHash(input.initArgs);
+  const preimage = await creationWarrantPreimage({
+    group,
+    seed,
+    authorAccount,
+    deviceKey,
+    executor,
+    applicationId,
+    serviceName,
+    name,
+    initHash,
+    accountHeads,
+    governanceFloor,
+    nonce: input.nonce,
+    notAfter: input.notAfter
+  });
+  const signature = new Uint8Array(
+    await crypto.subtle.sign({ name: "Ed25519" }, key, preimage)
+  );
+  const warrant = hex(
+    concat(
+      group,
+      seed,
+      authorAccount,
+      deviceKey,
+      executor,
+      applicationId,
+      borshOption(serviceName),
+      borshOption(name),
+      initHash,
+      u32le(accountHeads.length),
+      ...accountHeads,
+      u32le(governanceFloor.length),
+      ...governanceFloor,
+      u64le(input.nonce),
+      u64le(input.notAfter),
+      signature
+    )
+  );
+  return { warrant, seed: hex(seed) };
+}
+function parseCreationWarrant(warrant) {
+  const clean = warrant.trim();
+  if (!/^[0-9a-fA-F]*$/.test(clean) || clean.length % 2 !== 0) {
+    throw new Error("creation warrant must be an even number of hex characters");
+  }
+  const bytes = new Uint8Array(clean.length / 2);
+  for (let i = 0; i < bytes.length; i += 1) {
+    bytes[i] = Number.parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+  }
+  const view = new DataView(bytes.buffer);
+  let o = 0;
+  const take = (n, what) => {
+    if (o + n > bytes.length) {
+      throw new Error(`creation warrant ends inside ${what} (${bytes.length} bytes)`);
+    }
+    const out = bytes.subarray(o, o + n);
+    o += n;
+    return out;
+  };
+  const u32 = (what) => view.getUint32(take(4, what).byteOffset, true);
+  const u64 = (what) => view.getBigUint64(take(8, what).byteOffset, true);
+  const option = (what) => {
+    const tag = take(1, what)[0];
+    if (tag === 0) return null;
+    if (tag !== 1) throw new Error(`${what} has option tag ${tag}, expected 0 or 1`);
+    const len = u32(what);
+    if (len > MAX_LABEL_BYTES) {
+      throw new Error(`${what} is ${len} bytes, over the ${MAX_LABEL_BYTES} a node accepts`);
+    }
+    return new TextDecoder("utf-8", { fatal: true }).decode(take(len, what));
+  };
+  const heads = (what) => {
+    const count = u32(what);
+    if (count > 64) {
+      throw new Error(`${what} cites ${count} heads, over the 64 a node accepts`);
+    }
+    return Array.from({ length: count }, () => hex(take(32, what)));
+  };
+  const fields = {
+    group: hex(take(32, "group")),
+    seed: hex(take(32, "seed")),
+    authorAccount: hex(take(32, "authorAccount")),
+    deviceKey: hex(take(32, "deviceKey")),
+    executor: hex(take(32, "executor")),
+    applicationId: hex(take(32, "applicationId")),
+    serviceName: option("serviceName"),
+    name: option("name"),
+    initHash: hex(take(32, "initHash")),
+    accountHeads: heads("accountHeads"),
+    governanceFloor: heads("governanceFloor"),
+    nonce: u64("nonce"),
+    notAfter: u64("notAfter"),
+    signature: hex(take(64, "signature"))
+  };
+  if (o !== bytes.length) {
+    throw new Error(
+      `creation warrant is ${bytes.length} bytes but its fields account for ${o}`
+    );
+  }
+  return fields;
+}
+function label(value, what) {
+  if (value === void 0) return null;
+  const bytes = new TextEncoder().encode(value);
+  if (bytes.length > MAX_LABEL_BYTES) {
+    throw new Error(
+      `${what} is ${bytes.length} UTF-8 bytes, over the ${MAX_LABEL_BYTES} a node accepts`
+    );
+  }
+  return bytes;
+}
+function borshOption(bytes) {
+  if (bytes === null) return new Uint8Array([0]);
+  return concat(new Uint8Array([1]), u32le(bytes.length), bytes);
 }
 
 // src/relay/relay-client.ts
@@ -6583,6 +6741,94 @@ var RelayClient = class {
     );
     return { rootHash: body.data.rootHash, returns: body.data.returns ?? null };
   }
+  /**
+   * Ask the relay what it can do about creating contexts in `groupId`.
+   *
+   * Pass `author` (an account, hex) to also learn whether that account may
+   * create here — `authorMayCreate` is present only then.
+   */
+  async describeCreation(groupId, opts = {}) {
+    const query = opts.author ? `?author=${encodeURIComponent(opts.author)}` : "";
+    const body = await this.json(
+      "GET",
+      `/admin-api/groups/${encodeURIComponent(groupId)}/context-intents${query}`
+    );
+    return body.data;
+  }
+  /**
+   * Create a context in a group through the relay, as the author.
+   *
+   * Always asks {@link describeCreation} first — with the author, so both
+   * standing checks happen before anything is signed. A relay without standing
+   * in the group, or an author without `CAN_CREATE_CONTEXT`, is refused here as
+   * an {@link IntentRefusedError} *before* a nonce is taken: the nonce source
+   * is monotonic, and a warrant nobody will spend burns one for nothing.
+   *
+   * The creation warrant's nonce is spent in the new context's per-device
+   * ledger — the same one later `execute` calls in that context draw from — so
+   * it comes from the configured {@link NonceSource} like any other warrant.
+   *
+   * Sealing: nothing here is plaintext-specific. The request goes through the
+   * injected `fetch`, so a `createAttestedSealedFetch` seals it exactly as it
+   * seals `execute`. Whether the relay *accepts* it sealed is the node's call:
+   * a proxy-auth relay only admits sealed requests for routes `merod` serves
+   * without a credential, so `/admin-api/groups/:id/context-intents` must be on
+   * that list on the core side or the request comes back
+   * `403 sealed_route_unguarded`.
+   */
+  async createContext(input) {
+    const described = await this.describeCreation(input.groupId, {
+      author: this.config.authorAccount
+    });
+    if (!described.canCreateOnBehalf) {
+      throw new IntentRefusedError(
+        `the relay (${described.executorAccount}) has no standing to act for members of group ${described.groupId}; an admin must admit it as a relay or grant it CAN_AUTHOR_ON_BEHALF (checked before signing \u2014 no nonce was spent)`,
+        false,
+        403
+      );
+    }
+    if (described.authorMayCreate === false) {
+      throw new IntentRefusedError(
+        `the author (${this.config.authorAccount}) may not create contexts in group ${described.groupId}; it needs CAN_CREATE_CONTEXT or admin (checked before signing \u2014 no nonce was spent)`,
+        false,
+        403
+      );
+    }
+    const configured = this.config.executorAccount;
+    if (configured && configured.toLowerCase() !== described.executorAccount.toLowerCase()) {
+      throw new Error(
+        `configured executorAccount ${configured} is not the relay's account ${described.executorAccount}; a warrant naming it would be unspendable`
+      );
+    }
+    const executor = described.executorAccount;
+    this.executorAccount = executor;
+    const initArgs = input.initArgs ?? {};
+    const nonce2 = await this.config.nonces.next();
+    const ttl = this.config.ttlSeconds ?? DEFAULT_TTL_SECONDS;
+    const { warrant } = await signCreationWarrant({
+      group: input.groupId,
+      seed: input.seed,
+      authorAccount: this.config.authorAccount,
+      executor,
+      applicationId: input.applicationId,
+      serviceName: input.serviceName,
+      name: input.name,
+      initArgs,
+      nonce: nonce2,
+      notAfter: BigInt(Math.floor(Date.now() / 1e3)) + BigInt(ttl),
+      deviceSecret: this.config.deviceSecret
+    });
+    const body = await this.json(
+      "POST",
+      `/admin-api/groups/${encodeURIComponent(input.groupId)}/context-intents`,
+      { warrant, authorProof: this.config.authorProof, initArgs }
+    );
+    return {
+      contextId: body.data.contextId,
+      groupId: body.data.groupId,
+      memberPublicKey: body.data.memberPublicKey
+    };
+  }
   async json(method, path, body) {
     const headers = { Accept: "application/json" };
     if (body !== void 0) headers["Content-Type"] = "application/json";
@@ -7282,8 +7528,8 @@ var REGISTERS = ["mrtd", "rtmr0", "rtmr1", "rtmr2", "rtmr3"];
 function createQuoteVerifier(options) {
   const allowedMrtd = measurements(options.allowedMrtd ?? [], "allowedMrtd");
   const allowedImages = (options.allowedMeasurements ?? []).map((image, index) => {
-    const label = `allowedMeasurements[${index}]`;
-    return REGISTERS.map((register) => measurements([image?.[register] ?? ""], `${label}.${register}`)[0]).join();
+    const label2 = `allowedMeasurements[${index}]`;
+    return REGISTERS.map((register) => measurements([image?.[register] ?? ""], `${label2}.${register}`)[0]).join();
   });
   const allowedRtmr = [
     measurements(options.allowedRtmr0 ?? [], "allowedRtmr0"),
@@ -7352,11 +7598,11 @@ function createQuoteVerifier(options) {
   };
   return Object.assign(verifier, { includeCollateral: true });
 }
-function measurements(values, label) {
+function measurements(values, label2) {
   return values.map((value) => {
     const normalized = value.trim().toLowerCase();
     if (!MEASUREMENT_HEX.test(normalized)) {
-      throw new Error(`${label} holds ${JSON.stringify(value)}, which is not a 48-byte hex measurement`);
+      throw new Error(`${label2} holds ${JSON.stringify(value)}, which is not a 48-byte hex measurement`);
     }
     return normalized;
   });
@@ -7842,8 +8088,24 @@ function nodeReleaseVersionFromImage(osImage) {
   return `${Number(match[1])}.${Number(match[2])}.${Number(match[3])}`;
 }
 async function fetchNodeReleaseVersion(baseUrl, options = {}) {
-  const url = `${baseUrl.replace(/\/+$/, "")}/admin-api/tee/info`;
-  const response = await (options.fetch ?? fetch)(url, { headers: { accept: "application/json" } });
+  const version = await readNodeReleaseVersion(baseUrl, options.fetch ?? fetch);
+  if (version === void 0) {
+    throw new Error(
+      `${infoUrl(baseUrl)} was refused unsealed: the node requires sealing and is too old to name its release before a session exists. Name the release it runs yourself (createSignedReleaseSealedFetch's \`releaseVersion\`), or upgrade the node`
+    );
+  }
+  return version;
+}
+function infoUrl(baseUrl) {
+  return `${baseUrl.replace(/\/+$/, "")}/admin-api/tee/info`;
+}
+async function readNodeReleaseVersion(baseUrl, givenFetch) {
+  const url = infoUrl(baseUrl);
+  const response = await givenFetch(url, { headers: { accept: "application/json" } });
+  if (response.status === 403) {
+    const code = await response.json().then((body) => body?.error?.code).catch(() => void 0);
+    if (code === "sealed_required") return void 0;
+  }
   if (!response.ok) throw new Error(`Fetching ${url} failed: HTTP ${response.status}`);
   let osImage;
   try {
@@ -7890,10 +8152,19 @@ function createSignedReleaseVerifier(options) {
   return Object.assign(verifier, { includeCollateral: true });
 }
 function createSignedReleaseSealedFetch(options) {
-  const { baseUrl, releaseSource, applicationId, applicationHash, fetch: givenFetch, ...verifierOptions } = options;
+  const {
+    baseUrl,
+    releaseSource,
+    releaseVersion: fallbackVersion,
+    applicationId,
+    applicationHash,
+    fetch: givenFetch,
+    ...verifierOptions
+  } = options;
+  if (fallbackVersion !== void 0) releaseVersion(fallbackVersion, "releaseVersion");
   const baseFetch = givenFetch ?? ((input, init) => fetch(input, init));
   const release = async () => {
-    const version = await fetchNodeReleaseVersion(baseUrl, { fetch: baseFetch });
+    const version = fallbackVersion === void 0 ? await fetchNodeReleaseVersion(baseUrl, { fetch: baseFetch }) : await readNodeReleaseVersion(baseUrl, baseFetch) ?? fallbackVersion;
     return typeof releaseSource === "function" ? releaseSource({ baseUrl, version, fetch: baseFetch }) : fetchNodeRelease(cloudNodeReleaseUrl(releaseSource ?? DEFAULT_RELEASE_MIRROR, version), { fetch: baseFetch });
   };
   return createAttestedSealedFetch({
@@ -7953,18 +8224,18 @@ var ROOT_OP = {
   NamespaceCreatedV2: 9,
   MemberJoinedViaTeeAttestation: 10
 };
-function bytes32(value, label) {
+function bytes32(value, label2) {
   if (value.length !== 32) {
-    throw new Error(`${label} must be 32 bytes, got ${value.length}`);
+    throw new Error(`${label2} must be 32 bytes, got ${value.length}`);
   }
   return new Uint8Array(value);
 }
-function optionalBytes32(value, label) {
+function optionalBytes32(value, label2) {
   if (value === null || value === void 0) {
     return new Uint8Array([0]);
   }
   if (value.length !== 32) {
-    throw new Error(`${label} must be 32 bytes, got ${value.length}`);
+    throw new Error(`${label2} must be 32 bytes, got ${value.length}`);
   }
   return concat(new Uint8Array([1]), new Uint8Array(value));
 }
@@ -8046,7 +8317,7 @@ async function signMemberJoinOp(input) {
 }
 
 // src/login/login.ts
-var SIGN_DOMAIN3 = new TextEncoder().encode("calimero.auth.login.v1");
+var SIGN_DOMAIN4 = new TextEncoder().encode("calimero.auth.login.v1");
 var AUDIENCE_TAG = {
   webOrigin: 0,
   codeSigningId: 1,
@@ -8085,7 +8356,7 @@ async function signLoginStatement(input) {
   const deviceKey = await derivePublicKey(input.deviceSecret);
   const issuedAt = u64le(input.issuedAt);
   const expiresAt = u64le(input.expiresAt);
-  const preimage = await domainHash(SIGN_DOMAIN3, [
+  const preimage = await domainHash(SIGN_DOMAIN4, [
     node,
     audienceSigningBytes(input.audience),
     challenge,
@@ -8320,6 +8591,7 @@ export {
   createSignedReleaseVerifier,
   createTimeoutSignal,
   createUniversalHttpClient,
+  creationInitHash,
   deviceCertPayload,
   discoverLocalNodes,
   encodeSignedInvitation,
@@ -8339,6 +8611,7 @@ export {
   nodeEndpoint,
   nodeReleaseVersionFromImage,
   parseAuthCallback,
+  parseCreationWarrant,
   probeNodeHealth,
   redeemInvitation,
   requestBodyHash,
@@ -8346,6 +8619,7 @@ export {
   shouldRetain,
   signAccountLink,
   signAccountLogin,
+  signCreationWarrant,
   signDeviceCert,
   signLoginStatement,
   signMemberJoinOp,