@calimero-network/mero-js 22.5.1 → 22.7.0

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/governance-warrant.d.ts

@@ -26,6 +26,7 @@
  * `crates/account/src/tests/governance_wire_fixture.rs`, and this module's test
  * asserts the same vectors. A drift would surface at a relay as a 400.
  */
+import { type Signer } from '../signer/signer.js';
 import type { GovernanceOp, GovernanceOpKind } from './governance-op.js';
 /** What a governance warrant authorises. */
 export interface GovernanceWarrantInput {
@@ -51,15 +52,28 @@ export interface GovernanceWarrantInput {
     accountHeads?: string[];
     /** Governance heads the author's view descended from, each hex (32 bytes). At most 64. */
     governanceFloor?: string[];
-    /** The author device's ed25519 signing secret, hex (32 bytes). Never sent. */
-    deviceSecret: string;
+    /**
+     * The author device's ed25519 signing secret, hex (32 bytes). Never sent.
+     *
+     * Mutually exclusive with {@link GovernanceWarrantInput.signer}: exactly one is required.
+     * Prefer `signer` in a browser, since a secret held as a string is readable
+     * by anything on the origin.
+     */
+    deviceSecret?: string;
+    /**
+     * The author device's signer, in place of {@link GovernanceWarrantInput.deviceSecret}: for a
+     * key that cannot be exported to hex (a non-extractable WebCrypto key, a
+     * passkey, a hardware or remote signer). Its `publicKey` becomes the
+     * warrant's `author_device_key`, and it signs the 32-byte preimage as is.
+     */
+    signer?: Signer;
 }
 /** A governance warrant's fields, decoded from the wire encoding. */
 export interface GovernanceWarrantFields {
     scope: string;
     kind: GovernanceOpKind;
     authorAccount: string;
-    /** The author device key `signGovernanceWarrant` derived from the secret. */
+    /** The author device key: the signer's public key. */
     deviceKey: string;
     executor: string;
     opHash: string;

package/dist/warrant/governance-warrant.js

@@ -26,8 +26,9 @@
  * `crates/account/src/tests/governance_wire_fixture.rs`, and this module's test
  * asserts the same vectors. A drift would surface at a relay as a 400.
  */
-import { concat, derivePublicKey, domainHash, fromHex, hex, importSigningKey, u32le, u64le, } from '../crypto/internal.js';
-import { citedHeads } from './warrant.js';
+import { concat, domainHash, fromHex, hex, u32le, u64le } from '../crypto/internal.js';
+import { resolveSigner } from '../signer/signer.js';
+import { checkedSignature, citedHeads } from './warrant.js';
 const SIGN_DOMAIN = new TextEncoder().encode('calimero.governance-warrant.v1');
 const OP_DOMAIN = new TextEncoder().encode('calimero.governance-warrant.op.v1');
 /** core's `GovernanceOpKind` discriminants. */
@@ -72,8 +73,8 @@ export async function signGovernanceWarrant(input) {
     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 signer = await resolveSigner(input.deviceSecret, input.signer, 'deviceSecret');
+    const deviceKey = fromHex(signer.publicKey, 'signer.publicKey', 32);
     const opHash = await governanceOpHash(input.op);
     const preimage = await governanceWarrantPreimage({
         scope,
@@ -87,7 +88,7 @@ export async function signGovernanceWarrant(input) {
         nonce: input.nonce,
         notAfter: input.notAfter,
     });
-    const signature = new Uint8Array(await crypto.subtle.sign({ name: 'Ed25519' }, key, preimage));
+    const signature = checkedSignature(await signer.sign(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));
 }
 /**

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/dist/warrant/warrant.d.ts

@@ -27,6 +27,7 @@
  * this producing well-formed warrants whose signatures verify nowhere, surfacing
  * at a relay as a 403: an authorization refusal, nowhere near the cause.
  */
+import { type Signer } from '../signer/signer.js';
 /** Ed25519 PKCS#8 prefix, so a raw 32-byte seed can be imported by WebCrypto. */
 /** What a warrant authorises. */
 export interface WarrantInput {
@@ -103,8 +104,18 @@ export interface WarrantInput {
      *
      * Never sent anywhere. It signs locally and only the signature travels, which
      * is the whole reason a warrant can be minted by something holding no node.
+     *
+     * Mutually exclusive with {@link WarrantInput.signer}: exactly one is
+     * required. Prefer `signer` in a browser, since a secret held as a string is
+     * readable by anything on the origin.
+     */
+    deviceSecret?: string;
+    /**
+     * The author device's signer, in place of {@link WarrantInput.deviceSecret}:
+     * for a key that cannot be exported to hex (a non-extractable WebCrypto key,
+     * a passkey, a hardware or remote signer).
      */
-    deviceSecret: string;
+    signer?: Signer;
 }
 /**
  * The commitment a warrant carries in place of the intent itself.
@@ -125,6 +136,14 @@ export declare function signWarrant(input: WarrantInput): Promise<string>;
  * Decode a cited-head list, refusing one longer than a node will accept.
  * Shared with `creation-warrant.ts`; internal, not exported from the package root.
  */
+/**
+ * A signer's output, refused unless it is a 64-byte Ed25519 signature.
+ *
+ * The signature is spliced into the encoding at a fixed width, so a signer that
+ * returned anything else would yield a warrant that parses as garbage at a
+ * relay, far from the signer at fault. Internal.
+ */
+export declare function checkedSignature(signature: Uint8Array): Uint8Array;
 export declare function citedHeads(heads: string[] | undefined, label: string): Uint8Array[];
 /** A warrant's fields, as hex, decoded from the wire encoding. */
 export interface WarrantFields {

package/dist/warrant/warrant.js

@@ -27,7 +27,8 @@
  * this producing well-formed warrants whose signatures verify nowhere, surfacing
  * at a relay as a 403: an authorization refusal, nowhere near the cause.
  */
-import { concat, derivePublicKey, domainHash, fromHex, hex, importSigningKey, u32le, u64le, } from '../crypto/internal.js';
+import { concat, domainHash, fromHex, hex, u32le, u64le } from '../crypto/internal.js';
+import { resolveSigner } from '../signer/signer.js';
 const SIGN_DOMAIN = new TextEncoder().encode('calimero.warrant.v2');
 const INTENT_DOMAIN = new TextEncoder().encode('calimero.warrant.intent.v1');
 /**
@@ -61,8 +62,8 @@ export async function signWarrant(input) {
     const appVersion = fromHex(input.appVersion ?? UNPINNED_APP, 'appVersion', 32);
     const accountHeads = citedHeads(input.accountHeads, 'accountHeads');
     const governanceFloor = citedHeads(input.governanceFloor, 'governanceFloor');
-    const key = await importSigningKey(input.deviceSecret);
-    const publicKey = await derivePublicKey(input.deviceSecret);
+    const signer = await resolveSigner(input.deviceSecret, input.signer, 'deviceSecret');
+    const publicKey = fromHex(signer.publicKey, 'signer.publicKey', 32);
     const method = new TextEncoder().encode(input.method);
     const commitment = await intentHash(input.method, input.argsJson);
     const nonce = u64le(input.nonce);
@@ -87,7 +88,7 @@ export async function signWarrant(input) {
         nonce,
         notAfter,
     ]);
-    const signature = new Uint8Array(await crypto.subtle.sign({ name: 'Ed25519' }, key, preimage));
+    const signature = checkedSignature(await signer.sign(preimage));
     // Borsh: a `String` is a u32 length then its UTF-8 bytes; a `Vec<[u8; 32]>` is
     // a u32 count then the elements. u32 HERE; u64 in the preimage above.
     return hex(concat(context, authorAccount, publicKey, executor, appVersion, u32le(method.length), method, commitment, u32le(accountHeads.length), ...accountHeads, u32le(governanceFloor.length), ...governanceFloor, nonce, notAfter, signature));
@@ -96,6 +97,20 @@ export async function signWarrant(input) {
  * Decode a cited-head list, refusing one longer than a node will accept.
  * Shared with `creation-warrant.ts`; internal, not exported from the package root.
  */
+/**
+ * A signer's output, refused unless it is a 64-byte Ed25519 signature.
+ *
+ * The signature is spliced into the encoding at a fixed width, so a signer that
+ * returned anything else would yield a warrant that parses as garbage at a
+ * relay, far from the signer at fault. Internal.
+ */
+export function checkedSignature(signature) {
+    if (!(signature instanceof Uint8Array) || signature.length !== 64) {
+        const got = signature instanceof Uint8Array ? `${signature.length} bytes` : typeof signature;
+        throw new Error(`signer returned ${got}, expected a 64-byte Ed25519 signature`);
+    }
+    return signature;
+}
 export function citedHeads(heads, label) {
     const list = heads ?? [];
     if (list.length > MAX_CITED_HEADS) {

package/package.json

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