@calimero-network/mero-js 22.6.0 → 22.7.0

package/dist/index.d.ts

@@ -18,7 +18,7 @@ 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, signGovernanceWarrant, parseGovernanceWarrant, governanceOpHash, memberAddedOp, memberRemovedOp, memberLeftOp, memberRoleSetOp, groupCreatedOp, groupReparentedOp, groupDeletedOp, } from "./warrant/index.js";
+export { signWarrant, intentHash, signCreationWarrant, parseCreationWarrant, creationInitHash, signGovernanceWarrant, parseGovernanceWarrant, governanceOpHash, memberAddedOp, memberRemovedOp, memberLeftOp, memberRoleSetOp, groupCreatedOp, groupReparentedOp, groupDeletedOp, namespaceCreatedOp, defaultCapabilitiesSetOp, foundedNamespaceId, } from "./warrant/index.js";
 export { signerFromSecret, signerFromCryptoKey } from "./signer/index.js";
 export type { Signer } from "./signer/index.js";
 export { generateAccountRoot, accountRootFromPhrase, accountRootFromSecret, signAccountLink, signAccountLogin, } from "./account/index.js";
@@ -27,7 +27,7 @@ export { signDeviceCert, mintDeviceId, deviceCertPayload, accountForRoot, } from
 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, GovernanceWarrantInput, GovernanceWarrantFields, GovernanceOp, GovernanceOpKind, GovernanceMemberRole, GroupCreatedInput, } from "./warrant/index.js";
+export type { WarrantInput, CreationWarrantInput, CreationWarrantFields, SignedCreationWarrant, GovernanceWarrantInput, GovernanceWarrantFields, GovernanceOp, GovernanceOpKind, GovernanceMemberRole, GroupCreatedInput, NamespaceCreatedInput, } 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, signGovernanceWarrant, parseGovernanceWarrant, governanceOpHash, memberAddedOp, memberRemovedOp, memberLeftOp, memberRoleSetOp, groupCreatedOp, groupReparentedOp, groupDeletedOp, } from "./warrant/index.js";
+export { signWarrant, intentHash, signCreationWarrant, parseCreationWarrant, creationInitHash, signGovernanceWarrant, parseGovernanceWarrant, governanceOpHash, memberAddedOp, memberRemovedOp, memberLeftOp, memberRoleSetOp, groupCreatedOp, groupReparentedOp, groupDeletedOp, namespaceCreatedOp, defaultCapabilitiesSetOp, foundedNamespaceId, } from "./warrant/index.js";
 // Who signs — a key's capability, separated from its material, so a
 // non-extractable key can be used wherever a hex secret could.
 export { signerFromSecret, signerFromCryptoKey } from "./signer/index.js";

package/dist/index.mjs

@@ -745,6 +745,41 @@ var CAPABILITIES = {
    */
   CAN_AUTHOR_ON_BEHALF: 1 << 9
 };
+var CAPABILITY_PRESETS = {
+  /** No capabilities. */
+  NONE: 0,
+  /** Join Open subgroups only: what a namespace starts with. */
+  JOIN_ONLY: CAPABILITIES.CAN_JOIN_OPEN_SUBGROUPS,
+  /**
+   * Create contexts, invite members, join Open subgroups (= 7). A member who
+   * can work in the namespace but not reshape it.
+   */
+  CONTRIBUTOR: CAPABILITIES.CAN_CREATE_CONTEXT | CAPABILITIES.CAN_INVITE_MEMBERS | CAPABILITIES.CAN_JOIN_OPEN_SUBGROUPS,
+  /**
+   * `CONTRIBUTOR` plus create and delete subgroups and manage their visibility
+   * (= 231). What mero-chat gives members, so they can start and close their
+   * own channels.
+   */
+  COLLABORATOR: CAPABILITIES.CAN_CREATE_CONTEXT | CAPABILITIES.CAN_INVITE_MEMBERS | CAPABILITIES.CAN_JOIN_OPEN_SUBGROUPS | CAPABILITIES.CAN_CREATE_SUBGROUP | CAPABILITIES.CAN_DELETE_SUBGROUP | CAPABILITIES.CAN_MANAGE_VISIBILITY
+};
+function capMask(...caps) {
+  let mask = 0;
+  for (const cap of caps) {
+    if (typeof cap === "number") {
+      mask |= cap;
+    } else if (Object.prototype.hasOwnProperty.call(CAPABILITIES, cap)) {
+      mask |= CAPABILITIES[cap];
+    } else {
+      throw new Error(`unknown capability: ${String(cap)}`);
+    }
+  }
+  return mask >>> 0;
+}
+function capNames(mask) {
+  return Object.keys(CAPABILITIES).filter(
+    (name) => hasCap(mask, CAPABILITIES[name])
+  );
+}
 function hasCap(mask, cap) {
   const capU32 = cap >>> 0;
   return (mask & capU32) >>> 0 === capU32;
@@ -6921,6 +6956,138 @@ function kindByte(kind) {
   return byte;
 }
 
+// src/warrant/governance-op.ts
+var ROLE = {
+  Admin: 0,
+  Member: 1,
+  ReadOnly: 2
+};
+var GROUP_OP = {
+  MemberAdded: 1,
+  MemberRemoved: 2,
+  MemberLeft: 3,
+  MemberRoleSet: 4,
+  DefaultCapabilitiesSet: 6
+};
+var ROOT_OP = {
+  GroupCreated: 0,
+  GroupReparented: 1,
+  GroupDeleted: 2,
+  NamespaceCreatedV2: 9
+};
+var NAMESPACE_ID_DOMAIN = new TextEncoder().encode("calimero.namespace.id.v1");
+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 defaultCapabilitiesSetOp(capabilities) {
+  if (!Number.isInteger(capabilities) || capabilities < 0 || capabilities > 4294967295) {
+    throw new Error(`capabilities must be a u32 bit mask, got ${String(capabilities)}`);
+  }
+  if (hasCap(capabilities, CAPABILITIES.CAN_AUTHOR_ON_BEHALF)) {
+    throw new Error(
+      "capabilities may not include CAN_AUTHOR_ON_BEHALF (512): a relay never carries a change to it"
+    );
+  }
+  return {
+    kind: "group",
+    bytes: concat(tag(GROUP_OP.DefaultCapabilitiesSet), u32le(capabilities))
+  };
+}
+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)
+  };
+}
+async function foundedNamespaceId(founder, salt) {
+  return hex(
+    await domainHash(NAMESPACE_ID_DOMAIN, [
+      fromHex(founder, "founder", 32),
+      fromHex(salt, "salt", 32)
+    ])
+  );
+}
+function namespaceCreatedOp(input) {
+  const credential = fromHexUnsized(input.credential, "credential");
+  if (credential.length === 0) {
+    throw new Error("credential must be the founder's AccountProof<DeviceCert>, got nothing");
+  }
+  return {
+    kind: "root",
+    bytes: concat(
+      tag(ROOT_OP.NamespaceCreatedV2),
+      fromHex(input.founder, "founder", 32),
+      credential,
+      fromHex(input.salt, "salt", 32)
+    )
+  };
+}
+
 // src/relay/relay-client.ts
 var DEFAULT_TTL_SECONDS = 300;
 var IntentRefusedError = class extends Error {
@@ -7121,12 +7288,93 @@ var RelayClient = class {
       notAfter: BigInt(Math.floor(Date.now() / 1e3)) + BigInt(ttl),
       signer
     });
-    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 };
+    const data = await this.postGovernance(input.groupId, input.op, warrant);
+    return { groupId: data.groupId };
+  }
+  /**
+   * Found a namespace through the relay, with the author as its founder, owner
+   * and admin. For an account with no node, this is how it gets a namespace at
+   * all.
+   *
+   * The author signs the exact genesis (`NamespaceCreatedV2`, carrying the
+   * author's own credential and the salt) under a root-plane governance
+   * warrant scoped to the new namespace's id, which is derived from the
+   * author's account and the salt, so the relay can neither choose another id
+   * nor found it for anyone else. The relay takes an identity in the new
+   * namespace, mints its key, publishes the genesis, and is seated as the
+   * founding relay (a `Member` holding `CAN_AUTHOR_ON_BEHALF`), so later
+   * `govern`, `createContext` and `execute` calls in the namespace work
+   * through it straight away. A TEE relay then admits itself as the
+   * namespace's first TEE; `teeEnabled` reports whether it did.
+   *
+   * The executor cannot be learned from the relay first: the namespace does not
+   * exist, so `describeGovernance` has nothing to answer about. It comes from
+   * `input.executorAccount`, the configured one, or one an earlier call learned
+   * (`describe`, `createContext`, `govern`), and without any of them this
+   * throws before taking a nonce.
+   * The nonce is spent in the new namespace's ledger.
+   *
+   * With `defaultCapabilities`, the founder then sets the namespace's default
+   * capability mask through the same relay (a second warrant, a second nonce)
+   * and `defaultCapabilitiesSet` reports whether it landed. A failure there
+   * does not throw, since the namespace is already founded.
+   *
+   * Refusals (`400`/`403`) come back as {@link IntentRefusedError}; a salt
+   * that names an existing namespace is a `409`, an `HTTPError`.
+   */
+  async foundNamespace(input = {}) {
+    const executor = input.executorAccount ? this.checkedExecutor(input.executorAccount) : this.executorAccount;
+    if (!executor) {
+      throw new Error(
+        "foundNamespace needs the relay's account: pass executorAccount or configure it (checked before signing, no nonce was spent)"
+      );
+    }
+    const salt = input.salt ? hex(fromHex(input.salt, "salt", 32)) : hex(crypto.getRandomValues(new Uint8Array(32)));
+    const namespaceId = await foundedNamespaceId(this.config.authorAccount, salt);
+    const op = namespaceCreatedOp({
+      founder: this.config.authorAccount,
+      credential: this.config.authorProof,
+      salt
+    });
+    const capabilitiesOp = input.defaultCapabilities === void 0 ? void 0 : defaultCapabilitiesSetOp(input.defaultCapabilities);
+    const signer = await this.authorSigner();
+    const nonce2 = await this.config.nonces.next();
+    const ttl = this.config.ttlSeconds ?? DEFAULT_TTL_SECONDS;
+    const warrant = await signGovernanceWarrant({
+      scope: namespaceId,
+      op,
+      authorAccount: this.config.authorAccount,
+      executor,
+      nonce: nonce2,
+      notAfter: BigInt(Math.floor(Date.now() / 1e3)) + BigInt(ttl),
+      signer
+    });
+    const data = await this.postGovernance(namespaceId, op, warrant);
+    const founded = {
+      namespaceId: data.groupId,
+      salt,
+      teeEnabled: data.teeEnabled ?? false,
+      ...data.teeError ? { teeError: data.teeError } : {}
+    };
+    if (!capabilitiesOp) return founded;
+    try {
+      await this.govern({ groupId: founded.namespaceId, op: capabilitiesOp });
+      return { ...founded, defaultCapabilitiesSet: true };
+    } catch (err) {
+      return {
+        ...founded,
+        defaultCapabilitiesSet: false,
+        defaultCapabilitiesError: err instanceof Error ? err.message : String(err)
+      };
+    }
+  }
+  async postGovernance(groupId, op, warrant) {
+    const body = await this.json("POST", `/admin-api/groups/${encodeURIComponent(groupId)}/governance-intents`, {
+      warrant,
+      authorProof: this.config.authorProof,
+      op: hex(op.bytes)
+    });
+    return body.data;
   }
   /**
    * The executor a warrant must name: the one the relay answered with, which a
@@ -8520,98 +8768,6 @@ 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 = 16;
 var NAMESPACE_SIGN_DOMAIN = new TextEncoder().encode("calimero.namespace.v1");
@@ -8940,6 +9096,7 @@ export {
   AuthApiClient,
   AuthRevokedError,
   CAPABILITIES,
+  CAPABILITY_PRESETS,
   CloudClient,
   DEFAULT_LOCAL_NODE_PORTS,
   DEFAULT_RELEASE_MIRROR,
@@ -8968,6 +9125,8 @@ export {
   admitterAddrsFromNetworkStatus,
   buildAuthLoginUrl,
   callerProof,
+  capMask,
+  capNames,
   classifyError,
   cloudNodeReleaseUrl,
   combineSignals,
@@ -8997,12 +9156,14 @@ export {
   createTimeoutSignal,
   createUniversalHttpClient,
   creationInitHash,
+  defaultCapabilitiesSetOp,
   deviceCertPayload,
   discoverLocalNodes,
   encodeSignedInvitation,
   fetchAttestedTransportKey,
   fetchNodeRelease,
   fetchNodeReleaseVersion,
+  foundedNamespaceId,
   generateAccountRoot,
   generateSessionKey,
   governanceOpHash,
@@ -9021,6 +9182,7 @@ export {
   memberRemovedOp,
   memberRoleSetOp,
   mintDeviceId,
+  namespaceCreatedOp,
   nodeEndpoint,
   nodeReleaseVersionFromImage,
   parseAuthCallback,