@calimero-network/mero-js 22.3.0 → 22.5.0

package/dist/namespace-op/namespace-op.d.ts

@@ -17,11 +17,15 @@ import type { SignedGroupOpenInvitation } from '../admin-api/admin-types.js';
 /**
  * Core's `SIGNED_NAMESPACE_OP_SCHEMA_VERSION`. A node refuses any other value.
  *
- * 12: core gained the `RelayTee` role and the TEE admission policy's
- * replica/relay mode. No layout this module signs changed; the version moves
- * with core's so a v11 node and a v12 node never share a namespace.
+ * 15: core went to 13 (TEE rows locked to the TEE roles, a TEE's relay role
+ * read at its namespace root row, inherited read-only roles read-only in Open
+ * subgroups), then 14 (`GroupOp::ContextRegisteredOnBehalf`) and 15
+ * (`GroupOp::OnBehalf` / `RootOp::OnBehalf`) for delegated context creation and
+ * governance through a relay. None of these changes a layout this module
+ * signs; the version moves with core's so nodes on different versions never
+ * share a namespace.
  */
-export declare const SIGNED_NAMESPACE_OP_SCHEMA_VERSION = 12;
+export declare const SIGNED_NAMESPACE_OP_SCHEMA_VERSION = 15;
 /**
  * Borsh-encode a `SignedGroupOpenInvitation`.
  *

package/dist/namespace-op/namespace-op.js

@@ -2,11 +2,15 @@ import { concat, derivePublicKey, fromHex, hex, importSigningKey, u32le, u64le,
 /**
  * Core's `SIGNED_NAMESPACE_OP_SCHEMA_VERSION`. A node refuses any other value.
  *
- * 12: core gained the `RelayTee` role and the TEE admission policy's
- * replica/relay mode. No layout this module signs changed; the version moves
- * with core's so a v11 node and a v12 node never share a namespace.
+ * 15: core went to 13 (TEE rows locked to the TEE roles, a TEE's relay role
+ * read at its namespace root row, inherited read-only roles read-only in Open
+ * subgroups), then 14 (`GroupOp::ContextRegisteredOnBehalf`) and 15
+ * (`GroupOp::OnBehalf` / `RootOp::OnBehalf`) for delegated context creation and
+ * governance through a relay. None of these changes a layout this module
+ * signs; the version moves with core's so nodes on different versions never
+ * share a namespace.
  */
-export const SIGNED_NAMESPACE_OP_SCHEMA_VERSION = 12;
+export const SIGNED_NAMESPACE_OP_SCHEMA_VERSION = 15;
 /** Domain prefixed to the signable bytes; core's `NAMESPACE_GOVERNANCE_SIGN_DOMAIN`. */
 const NAMESPACE_SIGN_DOMAIN = new TextEncoder().encode('calimero.namespace.v1');
 /** `NamespaceOp::Root` is the first variant. */

package/dist/relay/index.d.ts

@@ -1,4 +1,4 @@
 export { RelayClient, IntentRefusedError } from './relay-client.js';
-export type { RelayClientConfig, RelayDescription, IntentResult } from './relay-client.js';
+export type { RelayClientConfig, RelayDescription, IntentResult, CreationDescription, CreateContextInput, CreatedContext, GovernanceDescription, GovernInput, GovernResult, } 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,6 +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 { NonceSource } from './nonce-source.js';
 /** Where and as whom to write, plus the key that consents. */
 export interface RelayClientConfig {
@@ -84,6 +85,79 @@ export interface RelayDescription {
     /** The group whose admin grants that capability, hex. */
     groupId: string;
 }
+/** What a relay says about its ability to create contexts in one group. */
+export interface CreationDescription {
+    /** The account a creation warrant must name as `executor`, hex. */
+    executorAccount: string;
+    /** The group, hex. */
+    groupId: string;
+    /**
+     * Whether the relay has standing to act for members of this group (a
+     * `RelayTee` role or `CAN_AUTHOR_ON_BEHALF`). It needs no create rights of
+     * its own — those are checked on the author.
+     */
+    canCreateOnBehalf: boolean;
+    /**
+     * Whether the author holds `CAN_CREATE_CONTEXT` (or admin) here. Present only
+     * when `describeCreation` was given an `author`.
+     */
+    authorMayCreate?: boolean;
+}
+/** What {@link RelayClient.createContext} creates. */
+export interface CreateContextInput {
+    /** The group to create the context in, hex. */
+    groupId: string;
+    /** The application to create it with, hex (32 bytes). */
+    applicationId: string;
+    /** The JSON the app's `init()` receives — run as the author's account. */
+    initArgs?: unknown;
+    /** Which service of a multi-service bundle; absent for the default. */
+    serviceName?: string;
+    /** A display name for the context. */
+    name?: string;
+    /**
+     * The seed the context id is derived from, hex (32 bytes). Random when
+     * absent, which is what almost every caller wants.
+     */
+    seed?: string;
+}
+/** Where a delegated creation landed. */
+export interface CreatedContext {
+    /** The new context's id, hex. */
+    contextId: string;
+    /** The group it was created in, hex. */
+    groupId: string;
+    /** The relay's identity in the new context, hex. */
+    memberPublicKey: string;
+}
+/** What a relay says about publishing governance ops for members of one group. */
+export interface GovernanceDescription {
+    /** The account a governance warrant must name as `executor`, hex. */
+    executorAccount: string;
+    /** The group asked about, hex. */
+    groupId: string;
+    /**
+     * Whether the relay may act for members here (a `RelayTee` role or
+     * `CAN_AUTHOR_ON_BEHALF`). It needs no right to the op itself: that is
+     * checked on the author, as the op is applied as the author.
+     */
+    canActOnBehalf: boolean;
+}
+/** What {@link RelayClient.govern} publishes. */
+export interface GovernInput {
+    /**
+     * Where the op is published, hex: the group itself for a group op, the
+     * **namespace** for a root op (creating, moving or deleting a subgroup).
+     */
+    groupId: string;
+    /** The op, from one of the encoders (`memberAddedOp`, `groupCreatedOp`, ...). */
+    op: GovernanceOp;
+}
+/** Where a delegated governance op landed. */
+export interface GovernResult {
+    /** The group the op acted on, hex: the new subgroup, for a creation. */
+    groupId: string;
+}
 /** Where an accepted intent landed. */
 export interface IntentResult<T = unknown> {
     /** The context's scope root after the run — did this change anything? */
@@ -140,5 +214,63 @@ export declare class RelayClient {
      * apply. Nothing accumulates and nothing is reusable.
      */
     execute<T = unknown>(contextId: string, method: string, argsJson?: unknown): Promise<IntentResult<T>>;
+    /**
+     * Ask the relay what it can do about creating contexts in `groupId`.
+     *
+     * Pass `author` (an account, hex) to also learn whether that account may
+     * create here — `authorMayCreate` is present only then.
+     */
+    describeCreation(groupId: string, opts?: {
+        author?: string;
+    }): Promise<CreationDescription>;
+    /**
+     * Create a context in a group through the relay, as the author.
+     *
+     * Always asks {@link describeCreation} first — with the author, so both
+     * standing checks happen before anything is signed. A relay without standing
+     * in the group, or an author without `CAN_CREATE_CONTEXT`, is refused here as
+     * an {@link IntentRefusedError} *before* a nonce is taken: the nonce source
+     * is monotonic, and a warrant nobody will spend burns one for nothing.
+     *
+     * The creation warrant's nonce is spent in the new context's per-device
+     * ledger — the same one later `execute` calls in that context draw from — so
+     * it comes from the configured {@link NonceSource} like any other warrant.
+     *
+     * Sealing: nothing here is plaintext-specific. The request goes through the
+     * injected `fetch`, so a `createAttestedSealedFetch` seals it exactly as it
+     * seals `execute`. Whether the relay *accepts* it sealed is the node's call:
+     * a proxy-auth relay only admits sealed requests for routes `merod` serves
+     * without a credential, so `/admin-api/groups/:id/context-intents` must be on
+     * that list on the core side or the request comes back
+     * `403 sealed_route_unguarded`.
+     */
+    createContext(input: CreateContextInput): Promise<CreatedContext>;
+    /**
+     * Ask the relay whether it may publish governance ops for members of
+     * `groupId`, and which account a warrant must name.
+     */
+    describeGovernance(groupId: string): Promise<GovernanceDescription>;
+    /**
+     * 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.
+     */
+    govern(input: GovernInput): Promise<GovernResult>;
+    /**
+     * The executor a warrant must name: the one the relay answered with, which a
+     * configured account must agree with. Remembered for later calls.
+     */
+    private checkedExecutor;
     private json;
 }

package/dist/relay/relay-client.js

@@ -28,7 +28,10 @@
  * unspendable: the number is gone and the write never happened.
  */
 import { signWarrant } from '../warrant/warrant.js';
+import { signCreationWarrant } from '../warrant/creation-warrant.js';
+import { signGovernanceWarrant } from '../warrant/governance-warrant.js';
 import { HTTPError } from '../http-client/web-client.js';
+import { hex } from '../crypto/internal.js';
 /** How long a freshly minted warrant stays presentable, in seconds. */
 const DEFAULT_TTL_SECONDS = 300;
 /**
@@ -106,6 +109,135 @@ export class RelayClient {
         const body = await this.json('POST', `/admin-api/contexts/${encodeURIComponent(contextId)}/intents`, { method, argsJson, warrant, authorProof: this.config.authorProof });
         return { rootHash: body.data.rootHash, returns: body.data.returns ?? null };
     }
+    /**
+     * Ask the relay what it can do about creating contexts in `groupId`.
+     *
+     * Pass `author` (an account, hex) to also learn whether that account may
+     * create here — `authorMayCreate` is present only then.
+     */
+    async describeCreation(groupId, opts = {}) {
+        const query = opts.author ? `?author=${encodeURIComponent(opts.author)}` : '';
+        const body = await this.json('GET', `/admin-api/groups/${encodeURIComponent(groupId)}/context-intents${query}`);
+        return body.data;
+    }
+    /**
+     * Create a context in a group through the relay, as the author.
+     *
+     * Always asks {@link describeCreation} first — with the author, so both
+     * standing checks happen before anything is signed. A relay without standing
+     * in the group, or an author without `CAN_CREATE_CONTEXT`, is refused here as
+     * an {@link IntentRefusedError} *before* a nonce is taken: the nonce source
+     * is monotonic, and a warrant nobody will spend burns one for nothing.
+     *
+     * The creation warrant's nonce is spent in the new context's per-device
+     * ledger — the same one later `execute` calls in that context draw from — so
+     * it comes from the configured {@link NonceSource} like any other warrant.
+     *
+     * Sealing: nothing here is plaintext-specific. The request goes through the
+     * injected `fetch`, so a `createAttestedSealedFetch` seals it exactly as it
+     * seals `execute`. Whether the relay *accepts* it sealed is the node's call:
+     * a proxy-auth relay only admits sealed requests for routes `merod` serves
+     * without a credential, so `/admin-api/groups/:id/context-intents` must be on
+     * that list on the core side or the request comes back
+     * `403 sealed_route_unguarded`.
+     */
+    async createContext(input) {
+        const described = await this.describeCreation(input.groupId, {
+            author: this.config.authorAccount,
+        });
+        if (!described.canCreateOnBehalf) {
+            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);
+        }
+        if (described.authorMayCreate === false) {
+            throw new IntentRefusedError(`the author (${this.config.authorAccount}) may not create contexts in group ` +
+                `${described.groupId}; it needs CAN_CREATE_CONTEXT or admin ` +
+                '(checked before signing — no nonce was spent)', false, 403);
+        }
+        const executor = this.checkedExecutor(described.executorAccount);
+        const initArgs = input.initArgs ?? {};
+        const nonce = await this.config.nonces.next();
+        const ttl = this.config.ttlSeconds ?? DEFAULT_TTL_SECONDS;
+        const { warrant } = await signCreationWarrant({
+            group: input.groupId,
+            seed: input.seed,
+            authorAccount: this.config.authorAccount,
+            executor,
+            applicationId: input.applicationId,
+            serviceName: input.serviceName,
+            name: input.name,
+            initArgs,
+            nonce,
+            notAfter: BigInt(Math.floor(Date.now() / 1000)) + BigInt(ttl),
+            deviceSecret: this.config.deviceSecret,
+        });
+        const body = await this.json('POST', `/admin-api/groups/${encodeURIComponent(input.groupId)}/context-intents`, { warrant, authorProof: this.config.authorProof, initArgs });
+        return {
+            contextId: body.data.contextId,
+            groupId: body.data.groupId,
+            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 nonce = 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,
+            notAfter: BigInt(Math.floor(Date.now() / 1000)) + 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 !== undefined)

package/dist/warrant/creation-warrant.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Mint a creation warrant: the author's consent for one relay to create one
+ * context in one group, once.
+ *
+ * The intent warrant in `warrant.ts` lets an account with no node *write* to a
+ * context; this lets it *create* one. The relay executes the warrant and
+ * publishes `GroupOp::ContextRegisteredOnBehalf` carrying it, and every peer
+ * checks the **author's** `CAN_CREATE_CONTEXT` (or admin) — the relay needs no
+ * create rights of its own, only standing to act for members. The app's `init`
+ * runs as the author's account.
+ *
+ * Same primitives and the same two-widths trap as `warrant.ts`: counts **inside
+ * the encoding** are borsh `u32`, counts the **signing preimage** hashes are
+ * `u64`. The two `Option<String>` labels add a third shape: on the wire an
+ * option is a one-byte tag followed (when present) by a `u32`-prefixed string,
+ * while the preimage hashes the tag and the bytes as two separate parts, the
+ * bytes empty when absent. That is what keeps `None` and `Some("")` distinct in
+ * both.
+ *
+ * **The byte contract is pinned in core**, at
+ * `crates/account/src/tests/creation_wire_fixture.rs`, and this module's test
+ * asserts the same vectors. A drift would surface at a relay as a 403.
+ */
+/** What a creation warrant authorises. */
+export interface CreationWarrantInput {
+    /** The group the context is created in, hex (32 bytes). */
+    group: string;
+    /**
+     * The seed the node derives the new context's id from, hex (32 bytes).
+     *
+     * Optional: when absent, 32 random bytes are drawn and returned alongside the
+     * warrant. Pass one only to make the id predictable — reusing a seed asks for
+     * a context that already exists.
+     */
+    seed?: string;
+    /** The author's account, hex — whose consent this is, and who runs `init`. */
+    authorAccount: string;
+    /** The relay authorised to act, hex. An account, not a key. */
+    executor: string;
+    /** The application the context is created with, hex (32 bytes). */
+    applicationId: string;
+    /**
+     * Which service of a multi-service bundle, or absent for the default.
+     *
+     * Absent and `""` are different values and sign differently. At most 256
+     * UTF-8 bytes.
+     */
+    serviceName?: string;
+    /** A display name for the context, or absent. At most 256 UTF-8 bytes. */
+    name?: string;
+    /**
+     * The JSON the app's `init()` will receive.
+     *
+     * Committed to rather than carried: the relay is sent the same value
+     * separately and the node checks it hashes to what was signed, so pass the
+     * exact value you will send. See {@link creationInitHash}.
+     */
+    initArgs: unknown;
+    /**
+     * Monotonic per author **device**. Spent in the *new* context's warrant
+     * ledger, so the same per-device nonce source `RelayClient` uses is correct.
+     */
+    nonce: number | bigint;
+    /** Unix seconds after which the relay must refuse it. */
+    notAfter: number | bigint;
+    /** Account-log heads the author saw, each hex (32 bytes). At most 64. */
+    accountHeads?: string[];
+    /**
+     * Governance heads the author's view descended from, each hex (32 bytes). At
+     * most 64. The same caveat as the intent warrant's floor applies: one the
+     * relay supplied is one the relay chose.
+     */
+    governanceFloor?: string[];
+    /** The author device's ed25519 signing secret, hex (32 bytes). Never sent. */
+    deviceSecret: string;
+}
+/** A signed creation warrant and the seed it commits to. */
+export interface SignedCreationWarrant {
+    /** Hex borsh `ContextCreationWarrant`, ready for the relay. */
+    warrant: string;
+    /** The seed, hex — the one passed in, or the one drawn when none was. */
+    seed: string;
+}
+/** A creation warrant's fields, decoded from the wire encoding. */
+export interface CreationWarrantFields {
+    group: string;
+    seed: string;
+    authorAccount: string;
+    /** The author device key `signCreationWarrant` derived from the secret. */
+    deviceKey: string;
+    executor: string;
+    applicationId: string;
+    /** `null` when absent — distinct from `""`. */
+    serviceName: string | null;
+    /** `null` when absent — distinct from `""`. */
+    name: string | null;
+    initHash: string;
+    accountHeads: string[];
+    governanceFloor: string[];
+    nonce: bigint;
+    notAfter: bigint;
+    signature: string;
+}
+/**
+ * The commitment a creation warrant carries in place of the init arguments.
+ *
+ * Hashes `JSON.stringify(initArgs)`, the same bytes `RelayClient.createContext`
+ * sends, under its own domain.
+ */
+export declare function creationInitHash(initArgs: unknown): Promise<Uint8Array>;
+/** The already-decoded fields the signature covers. Internal. */
+export interface CreationPreimageParts {
+    group: Uint8Array;
+    seed: Uint8Array;
+    authorAccount: Uint8Array;
+    deviceKey: Uint8Array;
+    executor: Uint8Array;
+    applicationId: Uint8Array;
+    serviceName: Uint8Array | null;
+    name: Uint8Array | null;
+    initHash: Uint8Array;
+    accountHeads: Uint8Array[];
+    governanceFloor: Uint8Array[];
+    nonce: number | bigint;
+    notAfter: number | bigint;
+}
+/**
+ * The bytes the device key signs. Exported for the conformance test only — not
+ * from the package root.
+ */
+export declare function creationWarrantPreimage(p: CreationPreimageParts): Promise<Uint8Array>;
+/**
+ * Sign a creation warrant and return it hex-encoded, with its seed.
+ *
+ * Returns the encoding rather than an object for the reason `signWarrant`
+ * does: the signature covers exactly these bytes.
+ */
+export declare function signCreationWarrant(input: CreationWarrantInput): Promise<SignedCreationWarrant>;
+/**
+ * Decode a hex creation warrant back into its fields.
+ *
+ * Refuses truncated or trailing bytes rather than reading a neighbouring field.
+ * Does not verify the signature.
+ */
+export declare function parseCreationWarrant(warrant: string): CreationWarrantFields;