@calimero-network/mero-js 22.6.0 → 22.7.0

package/dist/relay/index.d.ts

@@ -1,4 +1,4 @@
 export { RelayClient, IntentRefusedError } from './relay-client.js';
-export type { RelayClientConfig, RelayDescription, IntentResult, CreationDescription, CreateContextInput, CreatedContext, GovernanceDescription, GovernInput, GovernResult, } from './relay-client.js';
+export type { RelayClientConfig, RelayDescription, IntentResult, CreationDescription, CreateContextInput, CreatedContext, GovernanceDescription, GovernInput, GovernResult, FoundNamespaceInput, FoundedNamespace, } from './relay-client.js';
 export { createMemoryNonceSource, createLocalStorageNonceSource } from './nonce-source.js';
 export type { NonceSource } from './nonce-source.js';

package/dist/relay/relay-client.d.ts

@@ -27,7 +27,7 @@
  * monotonic per-device sequence, and one minted against the wrong executor is
  * unspendable: the number is gone and the write never happened.
  */
-import type { GovernanceOp } from '../warrant/governance-op.js';
+import { type GovernanceOp } from '../warrant/governance-op.js';
 import { type Signer } from '../signer/signer.js';
 import type { NonceSource } from './nonce-source.js';
 /** Where and as whom to write, plus the key that consents. */
@@ -169,6 +169,61 @@ export interface GovernResult {
     /** The group the op acted on, hex: the new subgroup, for a creation. */
     groupId: string;
 }
+/** What {@link RelayClient.foundNamespace} founds with. */
+export interface FoundNamespaceInput {
+    /**
+     * The salt the namespace id is derived from, hex (32 bytes). Random when
+     * absent, which is what almost every caller wants: one account founds many
+     * namespaces by varying it.
+     */
+    salt?: string;
+    /**
+     * The relay's account, hex: the warrant's `executor`. The namespace does not
+     * exist yet, so there is nothing to ask `describeGovernance` about. Falls back
+     * to the client's configured or already-learned `executorAccount`.
+     */
+    executorAccount?: string;
+    /**
+     * The namespace root's default capability mask (`MemberCapabilities` bits),
+     * set right after founding. A namespace is founded with core's minimal
+     * default (`CAN_JOIN_OPEN_SUBGROUPS` only), so an app that wants members to
+     * create contexts or invite, for example, names its own mask here.
+     *
+     * Set through the relay with a delegated `DefaultCapabilitiesSet`, applied as
+     * the founder, who is the namespace's admin. It cannot include
+     * `CAN_AUTHOR_ON_BEHALF` (bit 9): which relays may write for members is never
+     * decided through a relay, and such a mask is refused before anything is
+     * signed.
+     */
+    defaultCapabilities?: number;
+}
+/** A namespace founded through a relay. */
+export interface FoundedNamespace {
+    /** The new namespace's id, hex: `foundedNamespaceId(author, salt)`. */
+    namespaceId: string;
+    /**
+     * The salt it was derived with, hex. Keep it if anyone will need to be shown
+     * who founded the namespace: `(founder, salt)` reproduces the id.
+     */
+    salt: string;
+    /**
+     * Whether the relay admitted itself as the namespace's first TEE, which also
+     * sets its default relay-mode admission policy. `false` from a relay that is
+     * not a TEE, or whose attestation failed (see `teeError`). The namespace is
+     * founded either way.
+     */
+    teeEnabled: boolean;
+    /** Why `teeEnabled` is `false`, when the relay tried and failed. */
+    teeError?: string;
+    /**
+     * Present only when `defaultCapabilities` was asked for: whether the mask was
+     * set. `false` leaves the namespace founded with core's default; retry with
+     * `govern({ groupId: namespaceId, op: defaultCapabilitiesSetOp(mask) })`.
+     */
+    defaultCapabilitiesSet?: boolean;
+    /** Why `defaultCapabilitiesSet` is `false`. */
+    defaultCapabilitiesError?: string;
+}
 /** Where an accepted intent landed. */
 export interface IntentResult<T = unknown> {
     /** The context's scope root after the run — did this change anything? */
@@ -284,6 +339,39 @@ export declare class RelayClient {
      * other warrant.
      */
     govern(input: GovernInput): Promise<GovernResult>;
+    /**
+     * 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`.
+     */
+    foundNamespace(input?: FoundNamespaceInput): Promise<FoundedNamespace>;
+    private postGovernance;
     /**
      * The executor a warrant must name: the one the relay answered with, which a
      * configured account must agree with. Remembered for later calls.

package/dist/relay/relay-client.js

@@ -30,8 +30,9 @@
 import { signWarrant } from '../warrant/warrant.js';
 import { signCreationWarrant } from '../warrant/creation-warrant.js';
 import { signGovernanceWarrant } from '../warrant/governance-warrant.js';
+import { defaultCapabilitiesSetOp, foundedNamespaceId, namespaceCreatedOp, } from '../warrant/governance-op.js';
 import { HTTPError } from '../http-client/web-client.js';
-import { hex } from '../crypto/internal.js';
+import { fromHex, hex } from '../crypto/internal.js';
 import { resolveSigner } from '../signer/signer.js';
 /** How long a freshly minted warrant stays presentable, in seconds. */
 const DEFAULT_TTL_SECONDS = 300;
@@ -237,8 +238,107 @@ export class RelayClient {
             notAfter: BigInt(Math.floor(Date.now() / 1000)) + 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,
+        });
+        // Encoded (and so validated) before anything is signed: a mask the relay
+        // would refuse must not cost the founding a nonce.
+        const capabilitiesOp = input.defaultCapabilities === undefined
+            ? undefined
+            : defaultCapabilitiesSetOp(input.defaultCapabilities);
+        // Resolved before the nonce, so a misconfigured key burns none.
+        const signer = await this.authorSigner();
+        const nonce = 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,
+            notAfter: BigInt(Math.floor(Date.now() / 1000)) + 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;
+        // A second op, under its own warrant, on the namespace root: the founder is
+        // its admin and the relay was seated to act for members, so it goes through
+        // the ordinary `govern` path. The namespace exists whatever happens here, so
+        // a failure is reported rather than thrown.
+        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

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

@@ -15,7 +15,8 @@
  *
  * Sources in core, for the next person to check a discriminant:
  * `crates/governance-types/src/lib.rs` (`GroupOp`, `RootOp`),
- * `crates/primitives/src/context.rs` (`GroupMemberRole`), and the vectors in
+ * `crates/primitives/src/context.rs` (`GroupMemberRole`),
+ * `crates/account/src/namespace_id.rs` (`founded_namespace_id`), and the vectors in
  * `crates/governance-types/src/tests.rs` (`delegated_governance_op_vectors_are_stable`).
  */
 /**
@@ -51,6 +52,15 @@ 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;
+/**
+ * Set the group's default capability mask (`MemberCapabilities` bits, a `u32`),
+ * the capabilities every member holds without a per-member grant. Needs admin.
+ *
+ * The relay refuses any change to `CAN_AUTHOR_ON_BEHALF` (bit 9) through this
+ * path, and no namespace starts with it in its default mask, so a mask that
+ * sets it is refused here rather than burning a nonce on a certain 403.
+ */
+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. */
@@ -79,3 +89,39 @@ export declare function groupReparentedOp(childGroupId: string, newParentId: str
  * empty, for the relay to enumerate.
  */
 export declare function groupDeletedOp(rootGroupId: string): GovernanceOp;
+/**
+ * The id of the namespace `founder` founds with `salt`: core's
+ * `founded_namespace_id`, `domain_hash("calimero.namespace.id.v1", [founder, salt])`.
+ *
+ * Anyone holding the pair can recompute it, and only the founder's account
+ * hashes to it, which is why a relay founding a namespace for a member cannot
+ * choose the id: the member computes it and signs it.
+ */
+export declare function foundedNamespaceId(founder: string, salt: string): Promise<string>;
+/** What a namespace is founded with. */
+export interface NamespaceCreatedInput {
+    /** The founding account, hex: the **author's**. It becomes founder, owner and admin. */
+    founder: string;
+    /**
+     * The founder's `AccountProof<DeviceCert>`, hex: the credential the author
+     * already presents as `authorProof`. Its account must be `founder` and its
+     * device key the one that signs the warrant; the genesis apply checks both
+     * and binds the founder's device from it.
+     */
+    credential: string;
+    /**
+     * The salt the namespace id is derived with, hex (32 bytes). Choose it at
+     * random; {@link foundedNamespaceId} gives the id it yields.
+     */
+    salt: string;
+}
+/**
+ * Found a namespace: core's `RootOp::NamespaceCreatedV2` genesis, a root op
+ * published on the new namespace's own log.
+ *
+ * Its delegable form is the op itself, nothing cleared, so the author signs the
+ * exact genesis. Borsh is `[9] || founder || credential || salt`: the credential
+ * is a nested struct, not a length-prefixed byte string, so it is written
+ * inline. The warrant's scope must be {@link foundedNamespaceId}`(founder, salt)`.
+ */
+export declare function namespaceCreatedOp(input: NamespaceCreatedInput): GovernanceOp;

package/dist/warrant/governance-op.js

@@ -15,10 +15,12 @@
  *
  * Sources in core, for the next person to check a discriminant:
  * `crates/governance-types/src/lib.rs` (`GroupOp`, `RootOp`),
- * `crates/primitives/src/context.rs` (`GroupMemberRole`), and the vectors in
+ * `crates/primitives/src/context.rs` (`GroupMemberRole`),
+ * `crates/account/src/namespace_id.rs` (`founded_namespace_id`), and the vectors in
  * `crates/governance-types/src/tests.rs` (`delegated_governance_op_vectors_are_stable`).
  */
-import { concat, fromHex, u32le } from '../crypto/internal.js';
+import { CAPABILITIES, hasCap } from '../capabilities.js';
+import { concat, domainHash, fromHex, fromHexUnsized, hex, u32le } from '../crypto/internal.js';
 /**
  * `GroupMemberRole` discriminants. The two TEE roles (3 and 4) are minted only
  * by attestation admission and never by a member's op, so they are not offered.
@@ -34,13 +36,17 @@ const GROUP_OP = {
     MemberRemoved: 2,
     MemberLeft: 3,
     MemberRoleSet: 4,
+    DefaultCapabilitiesSet: 6,
 };
 /** `RootOp` discriminants, by position in core's enum. */
 const ROOT_OP = {
     GroupCreated: 0,
     GroupReparented: 1,
     GroupDeleted: 2,
+    NamespaceCreatedV2: 9,
 };
+/** core's `NAMESPACE_ID_DOMAIN`, which a founded namespace id is hashed under. */
+const NAMESPACE_ID_DOMAIN = new TextEncoder().encode('calimero.namespace.id.v1');
 /** A post-state hash left for the relay to compute: 32 zero bytes. */
 const CLEARED_HASH = new Uint8Array(32);
 /** An empty borsh `Vec`: a zero `u32` count. */
@@ -94,6 +100,27 @@ export function memberRoleSetOp(member, memberRole) {
         bytes: concat(tag(GROUP_OP.MemberRoleSet), fromHex(member, 'member', 32), role(memberRole)),
     };
 }
+/**
+ * Set the group's default capability mask (`MemberCapabilities` bits, a `u32`),
+ * the capabilities every member holds without a per-member grant. Needs admin.
+ *
+ * The relay refuses any change to `CAN_AUTHOR_ON_BEHALF` (bit 9) through this
+ * path, and no namespace starts with it in its default mask, so a mask that
+ * sets it is refused here rather than burning a nonce on a certain 403.
+ */
+export function defaultCapabilitiesSetOp(capabilities) {
+    if (!Number.isInteger(capabilities) || capabilities < 0 || capabilities > 4294967295) {
+        throw new Error(`capabilities must be a u32 bit mask, got ${String(capabilities)}`);
+    }
+    // Never changed through a relay.
+    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)),
+    };
+}
 /**
  * Create a subgroup under `parentId`, a root op published on the namespace.
  *
@@ -123,3 +150,36 @@ export function groupDeletedOp(rootGroupId) {
         bytes: concat(tag(ROOT_OP.GroupDeleted), fromHex(rootGroupId, 'rootGroupId', 32), EMPTY_VEC, EMPTY_VEC),
     };
 }
+/**
+ * The id of the namespace `founder` founds with `salt`: core's
+ * `founded_namespace_id`, `domain_hash("calimero.namespace.id.v1", [founder, salt])`.
+ *
+ * Anyone holding the pair can recompute it, and only the founder's account
+ * hashes to it, which is why a relay founding a namespace for a member cannot
+ * choose the id: the member computes it and signs it.
+ */
+export async function foundedNamespaceId(founder, salt) {
+    return hex(await domainHash(NAMESPACE_ID_DOMAIN, [
+        fromHex(founder, 'founder', 32),
+        fromHex(salt, 'salt', 32),
+    ]));
+}
+/**
+ * Found a namespace: core's `RootOp::NamespaceCreatedV2` genesis, a root op
+ * published on the new namespace's own log.
+ *
+ * Its delegable form is the op itself, nothing cleared, so the author signs the
+ * exact genesis. Borsh is `[9] || founder || credential || salt`: the credential
+ * is a nested struct, not a length-prefixed byte string, so it is written
+ * inline. The warrant's scope must be {@link foundedNamespaceId}`(founder, salt)`.
+ */
+export 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)),
+    };
+}

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, } from './governance-op.js';
-export type { GovernanceOp, GovernanceOpKind, GovernanceMemberRole, GroupCreatedInput, } from './governance-op.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';

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, } from './governance-op.js';
+export { memberAddedOp, memberRemovedOp, memberLeftOp, memberRoleSetOp, groupCreatedOp, groupReparentedOp, groupDeletedOp, namespaceCreatedOp, defaultCapabilitiesSetOp, foundedNamespaceId, } from './governance-op.js';

package/package.json

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