@calimero-network/mero-js 22.8.0 → 23.0.0

package/dist/warrant/governance-op.d.ts

@@ -52,6 +52,17 @@ export declare function memberRemovedOp(member: string): GovernanceOp;
 export declare function memberLeftOp(member: string): GovernanceOp;
 /** Set `member`'s role (an account, hex). */
 export declare function memberRoleSetOp(member: string, memberRole: GovernanceMemberRole): GovernanceOp;
+/**
+ * The id `admin` derives for a subgroup under `parentId` with birth visibility
+ * `restricted` and `salt` (all hex), as core's `created_subgroup_id` does:
+ * `domain_hash("calimero.subgroup.id.v1", [admin, parentId, [restricted], salt])`.
+ *
+ * A subgroup's id is bound to its create, so nobody but its creator can name
+ * it: a node refuses a `GroupCreated` whose fields do not reproduce its id.
+ * That is what stops a second member racing a concurrent create for an id it
+ * saw gossiped.
+ */
+export declare function createdSubgroupId(admin: string, parentId: string, restricted: boolean, salt: string): Promise<string>;
 /**
  * Set the group's default capability mask (`MemberCapabilities` bits, a `u32`),
  * the capabilities every member holds without a per-member grant. Needs admin.
@@ -63,7 +74,11 @@ export declare function memberRoleSetOp(member: string, memberRole: GovernanceMe
 export declare function defaultCapabilitiesSetOp(capabilities: number): GovernanceOp;
 /** What a subgroup is created with. */
 export interface GroupCreatedInput {
-    /** The new subgroup's id, hex (32 bytes). Choose it fresh; a taken id is refused. */
+    /**
+     * The new subgroup's id, hex (32 bytes). It must be
+     * `createdSubgroupId(admin, parentId, restricted, salt)`; a node refuses any
+     * other. {@link subgroupCreation} draws the salt and derives it for you.
+     */
     groupId: string;
     /** The group it is nested under, hex: the namespace root or an existing subgroup. */
     parentId: string;
@@ -74,6 +89,8 @@ export interface GroupCreatedInput {
      * refuses any other, since the op is applied as the author.
      */
     admin: string;
+    /** The salt `groupId` was derived with, hex (32 bytes). Random; need not be kept. */
+    salt: string;
 }
 /**
  * Create a subgroup under `parentId`, a root op published on the namespace.
@@ -82,6 +99,19 @@ export interface GroupCreatedInput {
  * relay, becomes the new subgroup's admin.
  */
 export declare function groupCreatedOp(input: GroupCreatedInput): GovernanceOp;
+/** A new subgroup's create: its derived id, the salt it was derived with, and the op. */
+export interface SubgroupCreation {
+    groupId: string;
+    salt: string;
+    op: GovernanceOp;
+}
+/**
+ * Create a subgroup under `parentId`: draws a fresh salt (unless one is given),
+ * derives the id with {@link createdSubgroupId}, and encodes the op.
+ */
+export declare function subgroupCreation(input: Omit<GroupCreatedInput, 'groupId' | 'salt'> & {
+    salt?: string;
+}): Promise<SubgroupCreation>;
 /** Move `childGroupId` under `newParentId`, a root op. */
 export declare function groupReparentedOp(childGroupId: string, newParentId: string): GovernanceOp;
 /**

package/dist/warrant/governance-op.js

@@ -100,6 +100,26 @@ export function memberRoleSetOp(member, memberRole) {
         bytes: concat(tag(GROUP_OP.MemberRoleSet), fromHex(member, 'member', 32), role(memberRole)),
     };
 }
+/** Domain of core's `created_subgroup_id`. */
+const SUBGROUP_ID_DOMAIN = new TextEncoder().encode('calimero.subgroup.id.v1');
+/**
+ * The id `admin` derives for a subgroup under `parentId` with birth visibility
+ * `restricted` and `salt` (all hex), as core's `created_subgroup_id` does:
+ * `domain_hash("calimero.subgroup.id.v1", [admin, parentId, [restricted], salt])`.
+ *
+ * A subgroup's id is bound to its create, so nobody but its creator can name
+ * it: a node refuses a `GroupCreated` whose fields do not reproduce its id.
+ * That is what stops a second member racing a concurrent create for an id it
+ * saw gossiped.
+ */
+export async function createdSubgroupId(admin, parentId, restricted, salt) {
+    return hex(await domainHash(SUBGROUP_ID_DOMAIN, [
+        fromHex(admin, 'admin', 32),
+        fromHex(parentId, 'parentId', 32),
+        new Uint8Array([restricted ? 1 : 0]),
+        fromHex(salt, 'salt', 32),
+    ]));
+}
 /**
  * Set the group's default capability mask (`MemberCapabilities` bits, a `u32`),
  * the capabilities every member holds without a per-member grant. Needs admin.
@@ -130,9 +150,18 @@ export function defaultCapabilitiesSetOp(capabilities) {
 export 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)),
+        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), fromHex(input.salt, 'salt', 32)),
     };
 }
+/**
+ * Create a subgroup under `parentId`: draws a fresh salt (unless one is given),
+ * derives the id with {@link createdSubgroupId}, and encodes the op.
+ */
+export async function subgroupCreation(input) {
+    const salt = input.salt ?? hex(crypto.getRandomValues(new Uint8Array(32)));
+    const groupId = await createdSubgroupId(input.admin, input.parentId, input.restricted, salt);
+    return { groupId, salt, op: groupCreatedOp({ ...input, groupId, salt }) };
+}
 /** Move `childGroupId` under `newParentId`, a root op. */
 export function groupReparentedOp(childGroupId, newParentId) {
     return {

package/dist/warrant/index.d.ts

@@ -4,5 +4,5 @@ export { signCreationWarrant, parseCreationWarrant, creationInitHash, } from './
 export type { CreationWarrantInput, CreationWarrantFields, SignedCreationWarrant, } from './creation-warrant.js';
 export { signGovernanceWarrant, parseGovernanceWarrant, governanceOpHash, } from './governance-warrant.js';
 export type { GovernanceWarrantInput, GovernanceWarrantFields, } from './governance-warrant.js';
-export { memberAddedOp, memberRemovedOp, memberLeftOp, memberRoleSetOp, groupCreatedOp, groupReparentedOp, groupDeletedOp, namespaceCreatedOp, defaultCapabilitiesSetOp, foundedNamespaceId, } from './governance-op.js';
-export type { GovernanceOp, GovernanceOpKind, GovernanceMemberRole, GroupCreatedInput, NamespaceCreatedInput, } from './governance-op.js';
+export { memberAddedOp, memberRemovedOp, memberLeftOp, memberRoleSetOp, groupCreatedOp, createdSubgroupId, subgroupCreation, groupReparentedOp, groupDeletedOp, namespaceCreatedOp, defaultCapabilitiesSetOp, foundedNamespaceId, } from './governance-op.js';
+export type { GovernanceOp, GovernanceOpKind, GovernanceMemberRole, GroupCreatedInput, SubgroupCreation, NamespaceCreatedInput, } from './governance-op.js';

package/dist/warrant/index.js

@@ -2,4 +2,4 @@
 export { signWarrant, intentHash } from './warrant.js';
 export { signCreationWarrant, parseCreationWarrant, creationInitHash, } from './creation-warrant.js';
 export { signGovernanceWarrant, parseGovernanceWarrant, governanceOpHash, } from './governance-warrant.js';
-export { memberAddedOp, memberRemovedOp, memberLeftOp, memberRoleSetOp, groupCreatedOp, groupReparentedOp, groupDeletedOp, namespaceCreatedOp, defaultCapabilitiesSetOp, foundedNamespaceId, } from './governance-op.js';
+export { memberAddedOp, memberRemovedOp, memberLeftOp, memberRoleSetOp, groupCreatedOp, createdSubgroupId, subgroupCreation, groupReparentedOp, groupDeletedOp, namespaceCreatedOp, defaultCapabilitiesSetOp, foundedNamespaceId, } from './governance-op.js';

package/package.json

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