@calimero-network/mero-js 22.4.0 → 22.5.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, signCreationWarrant, parseCreationWarrant, creationInitHash, } from "./warrant/index.js";
+export { signWarrant, intentHash, signCreationWarrant, parseCreationWarrant, creationInitHash, signGovernanceWarrant, parseGovernanceWarrant, governanceOpHash, memberAddedOp, memberRemovedOp, memberLeftOp, memberRoleSetOp, groupCreatedOp, groupReparentedOp, groupDeletedOp, } 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, CreationWarrantInput, CreationWarrantFields, SignedCreationWarrant, } from "./warrant/index.js";
+export type { WarrantInput, CreationWarrantInput, CreationWarrantFields, SignedCreationWarrant, GovernanceWarrantInput, GovernanceWarrantFields, GovernanceOp, GovernanceOpKind, GovernanceMemberRole, GroupCreatedInput, } 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, signCreationWarrant, parseCreationWarrant, creationInitHash, } from "./warrant/index.js";
+export { signWarrant, intentHash, signCreationWarrant, parseCreationWarrant, creationInitHash, signGovernanceWarrant, parseGovernanceWarrant, governanceOpHash, memberAddedOp, memberRemovedOp, memberLeftOp, memberRoleSetOp, groupCreatedOp, groupReparentedOp, groupDeletedOp, } 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

@@ -6627,9 +6627,9 @@ function parseCreationWarrant(warrant) {
   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 tag2 = take(1, what)[0];
+    if (tag2 === 0) return null;
+    if (tag2 !== 1) throw new Error(`${what} has option tag ${tag2}, 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`);
@@ -6681,6 +6681,134 @@ function borshOption(bytes) {
   return concat(new Uint8Array([1]), u32le(bytes.length), bytes);
 }
 
+// src/warrant/governance-warrant.ts
+var SIGN_DOMAIN4 = new TextEncoder().encode("calimero.governance-warrant.v1");
+var OP_DOMAIN = new TextEncoder().encode("calimero.governance-warrant.op.v1");
+var KIND_BYTE = { group: 0, root: 1 };
+async function governanceOpHash(op) {
+  return domainHash(OP_DOMAIN, [new Uint8Array([kindByte(op.kind)]), op.bytes]);
+}
+async function governanceWarrantPreimage(p) {
+  return domainHash(SIGN_DOMAIN4, [
+    p.scope,
+    new Uint8Array([kindByte(p.kind)]),
+    p.authorAccount,
+    p.deviceKey,
+    p.executor,
+    p.opHash,
+    u64le(p.accountHeads.length),
+    ...p.accountHeads,
+    u64le(p.governanceFloor.length),
+    ...p.governanceFloor,
+    u64le(p.nonce),
+    u64le(p.notAfter)
+  ]);
+}
+async function signGovernanceWarrant(input) {
+  const scope = fromHex(input.scope, "scope", 32);
+  const authorAccount = fromHex(input.authorAccount, "authorAccount", 32);
+  const executor = fromHex(input.executor, "executor", 32);
+  const accountHeads = citedHeads(input.accountHeads, "accountHeads");
+  const governanceFloor = citedHeads(input.governanceFloor, "governanceFloor");
+  const kind = kindByte(input.op.kind);
+  const key = await importSigningKey(input.deviceSecret);
+  const deviceKey = await derivePublicKey(input.deviceSecret);
+  const opHash = await governanceOpHash(input.op);
+  const preimage = await governanceWarrantPreimage({
+    scope,
+    kind: input.op.kind,
+    authorAccount,
+    deviceKey,
+    executor,
+    opHash,
+    accountHeads,
+    governanceFloor,
+    nonce: input.nonce,
+    notAfter: input.notAfter
+  });
+  const signature = new Uint8Array(
+    await crypto.subtle.sign({ name: "Ed25519" }, key, preimage)
+  );
+  return hex(
+    concat(
+      scope,
+      new Uint8Array([kind]),
+      authorAccount,
+      deviceKey,
+      executor,
+      opHash,
+      u32le(accountHeads.length),
+      ...accountHeads,
+      u32le(governanceFloor.length),
+      ...governanceFloor,
+      u64le(input.nonce),
+      u64le(input.notAfter),
+      signature
+    )
+  );
+}
+function parseGovernanceWarrant(warrant) {
+  const clean = warrant.trim();
+  if (!/^[0-9a-fA-F]*$/.test(clean) || clean.length % 2 !== 0) {
+    throw new Error("governance 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(`governance 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 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 kind = () => {
+    const byte = take(1, "kind")[0];
+    if (byte === 0) return "group";
+    if (byte === 1) return "root";
+    throw new Error(`governance warrant has kind ${byte}, expected 0 (group) or 1 (root)`);
+  };
+  const fields = {
+    scope: hex(take(32, "scope")),
+    kind: kind(),
+    authorAccount: hex(take(32, "authorAccount")),
+    deviceKey: hex(take(32, "deviceKey")),
+    executor: hex(take(32, "executor")),
+    opHash: hex(take(32, "opHash")),
+    accountHeads: heads("accountHeads"),
+    governanceFloor: heads("governanceFloor"),
+    nonce: u64("nonce"),
+    notAfter: u64("notAfter"),
+    signature: hex(take(64, "signature"))
+  };
+  if (o !== bytes.length) {
+    throw new Error(
+      `governance warrant is ${bytes.length} bytes but its fields account for ${o}`
+    );
+  }
+  return fields;
+}
+function kindByte(kind) {
+  const byte = KIND_BYTE[kind];
+  if (byte === void 0) {
+    throw new Error(`op kind must be 'group' or 'root', got ${String(kind)}`);
+  }
+  return byte;
+}
+
 // src/relay/relay-client.ts
 var DEFAULT_TTL_SECONDS = 300;
 var IntentRefusedError = class extends Error {
@@ -6794,14 +6922,7 @@ var RelayClient = class {
         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 executor = this.checkedExecutor(described.executorAccount);
     const initArgs = input.initArgs ?? {};
     const nonce2 = await this.config.nonces.next();
     const ttl = this.config.ttlSeconds ?? DEFAULT_TTL_SECONDS;
@@ -6829,6 +6950,75 @@ var RelayClient = class {
       memberPublicKey: body.data.memberPublicKey
     };
   }
+  /**
+   * Ask the relay whether it may publish governance ops for members of
+   * `groupId`, and which account a warrant must name.
+   */
+  async describeGovernance(groupId) {
+    const body = await this.json(
+      "GET",
+      `/admin-api/groups/${encodeURIComponent(groupId)}/governance-intents`
+    );
+    return body.data;
+  }
+  /**
+   * Publish one governance op through the relay, as the author.
+   *
+   * The warrant commits to the op's exact bytes and is scoped to `groupId`, so
+   * the relay can neither change what the op does nor spend it elsewhere. Every
+   * peer applies the op as the author, so the author's own rights decide
+   * (`MANAGE_MEMBERS` to add a member, `CAN_CREATE_SUBGROUP` to create a
+   * subgroup, and so on); a lack of them comes back as an
+   * {@link IntentRefusedError} from the relay.
+   *
+   * Always asks {@link describeGovernance} first and refuses *before* taking a
+   * nonce when the relay has no standing, for the reason `createContext` does.
+   * The nonce comes from the configured {@link NonceSource}; it is spent in a
+   * per-group ledger, and a monotonic source is correct for it as for every
+   * other warrant.
+   */
+  async govern(input) {
+    const described = await this.describeGovernance(input.groupId);
+    if (!described.canActOnBehalf) {
+      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, no nonce was spent)`,
+        false,
+        403
+      );
+    }
+    const executor = this.checkedExecutor(described.executorAccount);
+    const nonce2 = await this.config.nonces.next();
+    const ttl = this.config.ttlSeconds ?? DEFAULT_TTL_SECONDS;
+    const warrant = await signGovernanceWarrant({
+      scope: input.groupId,
+      op: input.op,
+      authorAccount: this.config.authorAccount,
+      executor,
+      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)}/governance-intents`,
+      { warrant, authorProof: this.config.authorProof, op: hex(input.op.bytes) }
+    );
+    return { groupId: body.data.groupId };
+  }
+  /**
+   * The executor a warrant must name: the one the relay answered with, which a
+   * configured account must agree with. Remembered for later calls.
+   */
+  checkedExecutor(answered) {
+    const configured = this.config.executorAccount;
+    if (configured && configured.toLowerCase() !== answered.toLowerCase()) {
+      throw new Error(
+        `configured executorAccount ${configured} is not the relay's account ${answered}; a warrant naming it would be unspendable`
+      );
+    }
+    this.executorAccount = answered;
+    return answered;
+  }
   async json(method, path, body) {
     const headers = { Accept: "application/json" };
     if (body !== void 0) headers["Content-Type"] = "application/json";
@@ -7715,8 +7905,8 @@ var SIGNATURE_HASHES = {
 };
 function read(bytes, offset, limit) {
   if (offset + 2 > limit) throw new Error("it is truncated");
-  const tag = bytes[offset];
-  if ((tag & 31) === 31) throw new Error("it uses a tag this parser does not read");
+  const tag2 = bytes[offset];
+  if ((tag2 & 31) === 31) throw new Error("it uses a tag this parser does not read");
   let length = bytes[offset + 1];
   let start = offset + 2;
   if (length & 128) {
@@ -7728,7 +7918,7 @@ function read(bytes, offset, limit) {
   }
   const end = start + length;
   if (end > limit) throw new Error("it is truncated");
-  return { tag, bytes, offset, start, end };
+  return { tag: tag2, bytes, offset, start, end };
 }
 function parseDer(bytes) {
   const element = read(bytes, 0, bytes.length);
@@ -7744,8 +7934,8 @@ function children(element) {
   }
   return out;
 }
-function expectTag(element, tag, what) {
-  if (!element || element.tag !== tag) throw new Error(`${what} is not where it should be`);
+function expectTag(element, tag2, what) {
+  if (!element || element.tag !== tag2) throw new Error(`${what} is not where it should be`);
   return element;
 }
 function contents(element) {
@@ -8207,11 +8397,103 @@ function splitVersion2(version) {
   return [[Number(match[1]), Number(match[2]), Number(match[3])], match[4]];
 }
 
+// src/warrant/governance-op.ts
+var ROLE = {
+  Admin: 0,
+  Member: 1,
+  ReadOnly: 2
+};
+var GROUP_OP = {
+  MemberAdded: 1,
+  MemberRemoved: 2,
+  MemberLeft: 3,
+  MemberRoleSet: 4
+};
+var ROOT_OP = {
+  GroupCreated: 0,
+  GroupReparented: 1,
+  GroupDeleted: 2
+};
+var CLEARED_HASH = new Uint8Array(32);
+var EMPTY_VEC = u32le(0);
+function role(value) {
+  const byte = ROLE[value];
+  if (byte === void 0) {
+    throw new Error(`role must be Admin, Member or ReadOnly, got ${String(value)}`);
+  }
+  return new Uint8Array([byte]);
+}
+function tag(byte) {
+  return new Uint8Array([byte]);
+}
+function memberAddedOp(member, memberRole) {
+  return {
+    kind: "group",
+    bytes: concat(tag(GROUP_OP.MemberAdded), fromHex(member, "member", 32), role(memberRole))
+  };
+}
+function memberRemovedOp(member) {
+  return {
+    kind: "group",
+    bytes: concat(
+      tag(GROUP_OP.MemberRemoved),
+      fromHex(member, "member", 32),
+      CLEARED_HASH,
+      EMPTY_VEC
+    )
+  };
+}
+function memberLeftOp(member) {
+  return {
+    kind: "group",
+    bytes: concat(
+      tag(GROUP_OP.MemberLeft),
+      fromHex(member, "member", 32),
+      CLEARED_HASH,
+      EMPTY_VEC
+    )
+  };
+}
+function memberRoleSetOp(member, memberRole) {
+  return {
+    kind: "group",
+    bytes: concat(tag(GROUP_OP.MemberRoleSet), fromHex(member, "member", 32), role(memberRole))
+  };
+}
+function groupCreatedOp(input) {
+  return {
+    kind: "root",
+    bytes: concat(
+      tag(ROOT_OP.GroupCreated),
+      fromHex(input.groupId, "groupId", 32),
+      fromHex(input.parentId, "parentId", 32),
+      tag(input.restricted ? 1 : 0),
+      fromHex(input.admin, "admin", 32)
+    )
+  };
+}
+function groupReparentedOp(childGroupId, newParentId) {
+  return {
+    kind: "root",
+    bytes: concat(
+      tag(ROOT_OP.GroupReparented),
+      fromHex(childGroupId, "childGroupId", 32),
+      fromHex(newParentId, "newParentId", 32)
+    )
+  };
+}
+function groupDeletedOp(rootGroupId) {
+  return {
+    kind: "root",
+    bytes: concat(tag(ROOT_OP.GroupDeleted), fromHex(rootGroupId, "rootGroupId", 32), EMPTY_VEC, EMPTY_VEC)
+  };
+}
+
 // src/namespace-op/namespace-op.ts
-var SIGNED_NAMESPACE_OP_SCHEMA_VERSION = 12;
+var SIGNED_NAMESPACE_OP_SCHEMA_VERSION = 15;
 var NAMESPACE_SIGN_DOMAIN = new TextEncoder().encode("calimero.namespace.v1");
 var NAMESPACE_OP_ROOT = 0;
-var ROOT_OP = {
+var ROOT_OP2 = {
   GroupCreated: 0,
   GroupReparented: 1,
   GroupDeleted: 2,
@@ -8286,13 +8568,13 @@ async function signMemberJoinOp(input) {
   const expires = BigInt(input.invitation.invitation.expiration_timestamp ?? 0) !== 0n;
   const joinedAt = input.joinedAt ?? BigInt(Math.floor(Date.now() / 1e3));
   const rootOp = expires ? concat(
-    new Uint8Array([ROOT_OP.MemberJoinedAt]),
+    new Uint8Array([ROOT_OP2.MemberJoinedAt]),
     fromHex(input.member, "member", 32),
     encodeSignedInvitation(input.invitation),
     u64le(joinedAt),
     credential
   ) : concat(
-    new Uint8Array([ROOT_OP.MemberJoined]),
+    new Uint8Array([ROOT_OP2.MemberJoined]),
     fromHex(input.member, "member", 32),
     encodeSignedInvitation(input.invitation),
     credential
@@ -8317,7 +8599,7 @@ async function signMemberJoinOp(input) {
 }
 
 // src/login/login.ts
-var SIGN_DOMAIN4 = new TextEncoder().encode("calimero.auth.login.v1");
+var SIGN_DOMAIN5 = new TextEncoder().encode("calimero.auth.login.v1");
 var AUDIENCE_TAG = {
   webOrigin: 0,
   codeSigningId: 1,
@@ -8341,12 +8623,12 @@ function audienceSigningBytes(audience) {
   );
 }
 function audienceWire(audience) {
-  const tag = Uint8Array.from([AUDIENCE_TAG[audience.kind]]);
+  const tag2 = Uint8Array.from([AUDIENCE_TAG[audience.kind]]);
   if (audience.kind === "cli") {
-    return tag;
+    return tag2;
   }
   const body = audienceBody(audience);
-  return concat(tag, u32le(body.length), body);
+  return concat(tag2, u32le(body.length), body);
 }
 async function signLoginStatement(input) {
   const node = fromHex(input.node, "node", 32);
@@ -8356,7 +8638,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_DOMAIN4, [
+  const preimage = await domainHash(SIGN_DOMAIN5, [
     node,
     audienceSigningBytes(input.audience),
     challenge,
@@ -8600,6 +8882,10 @@ export {
   fetchNodeReleaseVersion,
   generateAccountRoot,
   generateSessionKey,
+  governanceOpHash,
+  groupCreatedOp,
+  groupDeletedOp,
+  groupReparentedOp,
   hasCap,
   hexEncodeUtf8,
   intentHash,
@@ -8607,11 +8893,16 @@ export {
   jsonCodec,
   localNodeUrl,
   login,
+  memberAddedOp,
+  memberLeftOp,
+  memberRemovedOp,
+  memberRoleSetOp,
   mintDeviceId,
   nodeEndpoint,
   nodeReleaseVersionFromImage,
   parseAuthCallback,
   parseCreationWarrant,
+  parseGovernanceWarrant,
   probeNodeHealth,
   redeemInvitation,
   requestBodyHash,
@@ -8621,6 +8912,7 @@ export {
   signAccountLogin,
   signCreationWarrant,
   signDeviceCert,
+  signGovernanceWarrant,
   signLoginStatement,
   signMemberJoinOp,
   signRequest,