@calimero-network/mero-js 19.6.0 → 19.7.1

package/dist/admin-api/admin-client.d.ts

@@ -343,6 +343,75 @@ export declare class AdminApiClient {
      */
     setMemberCapabilities(groupId: string, identity: string, request: SetMemberCapabilitiesRequest): Promise<void>;
     setDefaultCapabilities(groupId: string, request: SetDefaultCapabilitiesRequest): Promise<void>;
+    /**
+     * Make every member admitted to `groupId` from now on able to relay a
+     * delegated write, without a per-node governance op each time.
+     *
+     * `CAN_AUTHOR_ON_BEHALF` is implied by nothing — not membership, not admin —
+     * so every group is authorship-closed and each fleet relay otherwise needs an
+     * admin to grant it individually, at the moment the relay is assigned and the
+     * admin is not watching. Setting it in the group's DEFAULT mask is core's own
+     * answer to that: `add_member` seeds a non-admin's capability row from the
+     * default, so an attested node admitted afterwards lands open.
+     *
+     * Call it on the NAMESPACE (the root group). A grant resolves through the
+     * membership anchor, so one at the root reaches every Open subgroup beneath
+     * it, which is where contexts actually live; a `Restricted` subgroup is a
+     * membership boundary and needs its own call.
+     *
+     * ### Two things this does not do
+     *
+     * **It is not retroactive.** The default is copied into a member's row when
+     * that member is admitted, so nodes already admitted keep the row they got.
+     * Use {@link grantAuthorship} for those — or call this at namespace creation,
+     * which is the only point that needs no backfill at all.
+     *
+     * **It does not reach admins.** Core seeds the default only for non-admin
+     * roles, and `CAN_AUTHOR_ON_BEHALF` is deliberately not implied by admin. An
+     * admin's own node therefore stays closed and needs {@link grantAuthorship}.
+     *
+     * ### What it widens
+     *
+     * Every future non-admin member of the group, not only attested TEE nodes, so
+     * any of them may be named as a warrant's `executor`. The bound worth knowing
+     * before deciding: an executor cannot FORGE. A delegated write is authorized
+     * by the author's own warrant — signed by their device key, committed to one
+     * context, method and exact arguments, with its nonce checked unspent — so a
+     * holder can only spend a warrant it was deliberately handed. What it does
+     * gain is the arguments in cleartext and the choice of when, or whether, to
+     * publish.
+     *
+     * Read-modify-write rather than a blind set: core seeds a new group's default
+     * with `CAN_JOIN_OPEN_SUBGROUPS`, and overwriting that would quietly stop
+     * every later member inheriting into Open subgroups.
+     *
+     * Returns the resulting mask and whether an op was published — it is a no-op
+     * when the bit is already set, so it is safe to call on every startup.
+     */
+    openToDelegatedExecution(groupId: string): Promise<{
+        changed: boolean;
+        defaultCapabilities: number;
+    }>;
+    /**
+     * Grant `account` the authorship bit on `groupId`, leaving its other
+     * capabilities alone.
+     *
+     * The per-member counterpart to {@link openToDelegatedExecution}, and what
+     * closes the gap that method cannot: a relay admitted BEFORE the default was
+     * set, and an admin's own node, which never receives the default at all.
+     *
+     * `account` is the member's ACCOUNT id (64 hex) as `listGroupMembers` returns
+     * it — for a fleet relay, the `account` the cloud reports for that node. Not
+     * the signing key that added them; both are 64 hex, so nothing but the source
+     * tells them apart.
+     *
+     * Read-modify-write, so it adds the bit rather than replacing the member's
+     * mask. A no-op when the member already holds it.
+     */
+    grantAuthorship(groupId: string, account: string): Promise<{
+        changed: boolean;
+        capabilities: number;
+    }>;
     setSubgroupVisibility(groupId: string, request: SetSubgroupVisibilityRequest): Promise<void>;
     setTeeAdmissionPolicy(groupId: string, request: SetTeeAdmissionPolicyRequest): Promise<void>;
     getTeeAdmissionPolicy(groupId: string): Promise<GetTeeAdmissionPolicyResponseData>;

package/dist/admin-api/admin-client.js

@@ -1,4 +1,5 @@
 import { withRetry } from '../http-client/index.js';
+import { CAPABILITIES, hasCap, withCap } from '../capabilities.js';
 /**
  * Helper: server wraps most responses in `{ data: T }`.
  * This extracts `.data` so callers get the inner payload directly. Null-safe so an
@@ -709,6 +710,85 @@ export class AdminApiClient {
     async setDefaultCapabilities(groupId, request) {
         await this.httpClient.put(`/admin-api/groups/${groupId}/settings/default-capabilities`, request);
     }
+    /**
+     * Make every member admitted to `groupId` from now on able to relay a
+     * delegated write, without a per-node governance op each time.
+     *
+     * `CAN_AUTHOR_ON_BEHALF` is implied by nothing — not membership, not admin —
+     * so every group is authorship-closed and each fleet relay otherwise needs an
+     * admin to grant it individually, at the moment the relay is assigned and the
+     * admin is not watching. Setting it in the group's DEFAULT mask is core's own
+     * answer to that: `add_member` seeds a non-admin's capability row from the
+     * default, so an attested node admitted afterwards lands open.
+     *
+     * Call it on the NAMESPACE (the root group). A grant resolves through the
+     * membership anchor, so one at the root reaches every Open subgroup beneath
+     * it, which is where contexts actually live; a `Restricted` subgroup is a
+     * membership boundary and needs its own call.
+     *
+     * ### Two things this does not do
+     *
+     * **It is not retroactive.** The default is copied into a member's row when
+     * that member is admitted, so nodes already admitted keep the row they got.
+     * Use {@link grantAuthorship} for those — or call this at namespace creation,
+     * which is the only point that needs no backfill at all.
+     *
+     * **It does not reach admins.** Core seeds the default only for non-admin
+     * roles, and `CAN_AUTHOR_ON_BEHALF` is deliberately not implied by admin. An
+     * admin's own node therefore stays closed and needs {@link grantAuthorship}.
+     *
+     * ### What it widens
+     *
+     * Every future non-admin member of the group, not only attested TEE nodes, so
+     * any of them may be named as a warrant's `executor`. The bound worth knowing
+     * before deciding: an executor cannot FORGE. A delegated write is authorized
+     * by the author's own warrant — signed by their device key, committed to one
+     * context, method and exact arguments, with its nonce checked unspent — so a
+     * holder can only spend a warrant it was deliberately handed. What it does
+     * gain is the arguments in cleartext and the choice of when, or whether, to
+     * publish.
+     *
+     * Read-modify-write rather than a blind set: core seeds a new group's default
+     * with `CAN_JOIN_OPEN_SUBGROUPS`, and overwriting that would quietly stop
+     * every later member inheriting into Open subgroups.
+     *
+     * Returns the resulting mask and whether an op was published — it is a no-op
+     * when the bit is already set, so it is safe to call on every startup.
+     */
+    async openToDelegatedExecution(groupId) {
+        const current = await this.getDefaultCapabilities(groupId);
+        if (hasCap(current, CAPABILITIES.CAN_AUTHOR_ON_BEHALF)) {
+            return { changed: false, defaultCapabilities: current };
+        }
+        const next = withCap(current, CAPABILITIES.CAN_AUTHOR_ON_BEHALF);
+        await this.setDefaultCapabilities(groupId, { defaultCapabilities: next });
+        return { changed: true, defaultCapabilities: next };
+    }
+    /**
+     * Grant `account` the authorship bit on `groupId`, leaving its other
+     * capabilities alone.
+     *
+     * The per-member counterpart to {@link openToDelegatedExecution}, and what
+     * closes the gap that method cannot: a relay admitted BEFORE the default was
+     * set, and an admin's own node, which never receives the default at all.
+     *
+     * `account` is the member's ACCOUNT id (64 hex) as `listGroupMembers` returns
+     * it — for a fleet relay, the `account` the cloud reports for that node. Not
+     * the signing key that added them; both are 64 hex, so nothing but the source
+     * tells them apart.
+     *
+     * Read-modify-write, so it adds the bit rather than replacing the member's
+     * mask. A no-op when the member already holds it.
+     */
+    async grantAuthorship(groupId, account) {
+        const { capabilities } = await this.getMemberCapabilities(groupId, account);
+        if (hasCap(capabilities, CAPABILITIES.CAN_AUTHOR_ON_BEHALF)) {
+            return { changed: false, capabilities };
+        }
+        const next = withCap(capabilities, CAPABILITIES.CAN_AUTHOR_ON_BEHALF);
+        await this.setMemberCapabilities(groupId, account, { capabilities: next });
+        return { changed: true, capabilities: next };
+    }
     async setSubgroupVisibility(groupId, request) {
         await this.httpClient.put(`/admin-api/groups/${groupId}/settings/subgroup-visibility`, request);
     }

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

@@ -94,6 +94,62 @@ export interface CloudRelay {
     lastSeenAt?: string | null;
     confirmedAt?: string | null;
 }
+/**
+ * One node serving a namespace, as a caller with no cloud account sees it.
+ *
+ * The public counterpart to {@link CloudRelay}: same fleet rows, but keyed on a
+ * namespace id anyone holding an invitation already has, and answering both
+ * things a keyholder needs from a node rather than one of them.
+ */
+export interface CloudNamespaceNode {
+    peerId: string;
+    /**
+     * The node's own account id, hex.
+     *
+     * Intersect this against the invitation's signed `admitters` list before
+     * using the node. That list is a MINT-TIME SNAPSHOT, so a node assigned after
+     * an invitation was created is live, healthy, listed here, and still refused
+     * with 403 — the cloud cannot know which invitation you hold.
+     */
+    account: string | null;
+    /** Base URL, or `null` when the cloud knows none yet. */
+    relayUrl: string | null;
+    /** Ready-made admission URL, so a caller never rebuilds the path. */
+    admitUrl: string | null;
+    /** `'assigned'` (admitted pending confirm) or `'active'`. */
+    status: string;
+    /** Whether the node's heartbeat for this namespace is recent. */
+    fresh: boolean;
+    /**
+     * Whether a signed join can be presented here now.
+     *
+     * Deliberately independent of {@link CloudNamespaceNode.authorshipReady}:
+     * relaying a join the joiner already signed is not authoring on anyone's
+     * behalf, so a node with no grant admits perfectly well.
+     */
+    canAdmit: boolean;
+    /** Whether the node holds `CAN_AUTHOR_ON_BEHALF` on the namespace root group. */
+    authorshipReady: boolean;
+    /**
+     * Whether a delegated write can be posted here now — a URL, an account, a
+     * fresh heartbeat and the grant.
+     *
+     * Namespace-level. A context in a RESTRICTED SUBGROUP is governed by that
+     * subgroup, so per-context routing remains the exact answer if a write is
+     * refused despite this being true.
+     */
+    canExecute: boolean;
+}
+/** What {@link CloudClient.getNamespaceRouting} reports. */
+export interface CloudNamespaceRouting {
+    namespaceId: string;
+    /** Usable nodes first, then a stable order, so a polling caller sees no shuffle. */
+    nodes: CloudNamespaceNode[];
+    /** Whether any listed node can take a join now. */
+    servable: boolean;
+    /** Whether any listed node can take a delegated write now. */
+    writable: boolean;
+}
 /** One namespace of the caller's that a machine is serving. */
 export interface CloudMachineNamespace {
     namespaceId: string;
@@ -247,6 +303,39 @@ export declare class CloudClient {
      * must be in place.
      */
     findExecutingRelay(namespaceId: string): Promise<CloudRelay | null>;
+    /**
+     * Where to reach a namespace without owning it: one read, both verbs.
+     *
+     * **Anonymous.** A joiner is by construction not the namespace owner and holds
+     * no cloud session — needing one is exactly what this path exists to avoid.
+     * Discovery is not authorization: merod refuses an `/admit` call unless the
+     * relaying node's account is on the invitation's signed `admitters` list, and
+     * refuses an intent unless the warrant is genuinely the member's, so naming a
+     * node grants the caller nothing it did not already have.
+     *
+     * A keyholder resolves a namespace to a node ONCE and then admits, reads and
+     * posts intents against that same node, which is why admission and writability
+     * are answered together rather than across two endpoints — the per-context
+     * read needs a context id a joiner does not yet have.
+     *
+     * An empty `nodes` list is a state, not an error: a namespace with no fleet
+     * assignment has no cloud node, and the joiner must use one of the
+     * invitation's other admitters — another admin's node, or a self-hosted peer.
+     */
+    getNamespaceRouting(namespaceId: string): Promise<CloudNamespaceRouting>;
+    /**
+     * The node to send a signed join to, chosen from those an invitation names.
+     *
+     * Pass the invitation's `admitters` and the intersection is done here, because
+     * skipping it is the failure this method exists to prevent: the cloud lists
+     * every node assigned to the namespace, while `admitters` is a snapshot signed
+     * when the invitation was minted. A node added afterwards looks perfect in
+     * every field here and answers 403.
+     *
+     * Omit `admitters` only for an invitation that names none — an empty list on
+     * the wire authorises any node to admit.
+     */
+    findAdmitter(namespaceId: string, admitters?: readonly string[]): Promise<CloudNamespaceNode | null>;
     /**
      * Every attested machine currently serving something this account owns.
      *

package/dist/cloud/cloud-client.js

@@ -149,6 +149,64 @@ export class CloudClient {
         return (relays.find((r) => r.authorshipReady && r.relayUrl !== null && r.executorAccount !== null) ??
             null);
     }
+    /**
+     * Where to reach a namespace without owning it: one read, both verbs.
+     *
+     * **Anonymous.** A joiner is by construction not the namespace owner and holds
+     * no cloud session — needing one is exactly what this path exists to avoid.
+     * Discovery is not authorization: merod refuses an `/admit` call unless the
+     * relaying node's account is on the invitation's signed `admitters` list, and
+     * refuses an intent unless the warrant is genuinely the member's, so naming a
+     * node grants the caller nothing it did not already have.
+     *
+     * A keyholder resolves a namespace to a node ONCE and then admits, reads and
+     * posts intents against that same node, which is why admission and writability
+     * are answered together rather than across two endpoints — the per-context
+     * read needs a context id a joiner does not yet have.
+     *
+     * An empty `nodes` list is a state, not an error: a namespace with no fleet
+     * assignment has no cloud node, and the joiner must use one of the
+     * invitation's other admitters — another admin's node, or a self-hosted peer.
+     */
+    async getNamespaceRouting(namespaceId) {
+        const body = await this.request('GET', `/api/cloud/namespaces/${encodeURIComponent(namespaceId)}/admitters`, {
+            anonymous: true,
+        });
+        return {
+            namespaceId: String(body.namespace_id ?? namespaceId),
+            nodes: (body.admitters ?? []).map((row) => ({
+                peerId: String(row.peer_id ?? ''),
+                account: row.account ?? null,
+                relayUrl: row.relay_url ?? null,
+                admitUrl: row.admit_url ?? null,
+                status: String(row.status ?? ''),
+                fresh: row.fresh === true,
+                canAdmit: row.can_admit === true,
+                authorshipReady: row.authorship_ready === true,
+                canExecute: row.can_execute === true,
+            })),
+            servable: body.servable === true,
+            writable: body.writable === true,
+        };
+    }
+    /**
+     * The node to send a signed join to, chosen from those an invitation names.
+     *
+     * Pass the invitation's `admitters` and the intersection is done here, because
+     * skipping it is the failure this method exists to prevent: the cloud lists
+     * every node assigned to the namespace, while `admitters` is a snapshot signed
+     * when the invitation was minted. A node added afterwards looks perfect in
+     * every field here and answers 403.
+     *
+     * Omit `admitters` only for an invitation that names none — an empty list on
+     * the wire authorises any node to admit.
+     */
+    async findAdmitter(namespaceId, admitters) {
+        const { nodes } = await this.getNamespaceRouting(namespaceId);
+        const allowed = admitters && admitters.length > 0 ? new Set(admitters.map((a) => a.toLowerCase())) : null;
+        return (nodes.find((n) => n.canAdmit &&
+            (allowed === null || (n.account !== null && allowed.has(n.account.toLowerCase())))) ?? null);
+    }
     /**
      * Every attested machine currently serving something this account owns.
      *

package/dist/cloud/connect.js

@@ -123,8 +123,15 @@ function explainNoRelay(namespace, relays) {
     }
     const waitingOnGrant = relays.filter((r) => !r.authorshipReady);
     if (waitingOnGrant.length === relays.length) {
+        // Name the call, not just the capability. The grant is a governance op only
+        // a namespace admin can publish, so this message is read by someone who has
+        // to go ask for it — and "grant CAN_AUTHOR_ON_BEHALF" alone leaves them
+        // relaying a constant to an admin who then has to work out the command.
+        // `openToDelegatedExecution` is the durable half (every relay assigned from
+        // then on lands open), `grantAuthorship` the one for relays already here.
         return (`every relay on namespace ${namespace.namespaceId} is waiting for the authorship grant: ` +
-            `an admin of the namespace must grant CAN_AUTHOR_ON_BEHALF to ${waitingOnGrant.map((r) => r.executorAccount ?? r.peerId).join(', ') || 'the relay account'}`);
+            `an admin of the namespace must grant CAN_AUTHOR_ON_BEHALF to ${waitingOnGrant.map((r) => r.executorAccount ?? r.peerId).join(', ') || 'the relay account'} — with AdminClient.grantAuthorship(namespaceId, account) for these relays, and ` +
+            `AdminClient.openToDelegatedExecution(namespaceId) so relays assigned later need no further op`);
     }
     return `namespace ${namespace.namespaceId} has ${relays.length} relay(s), but none reported both a URL and an executor account yet — retry shortly`;
 }

package/dist/cloud/index.d.ts

@@ -1,4 +1,4 @@
 export { CloudClient } from './cloud-client.js';
-export type { CloudClientConfig, CloudSession, CloudNamespace, CloudRelay, CloudMachine, CloudMachineNamespace, CloudLinkedAccount, CloudLinkedAccounts, CloudAccountLink, AccountLinkChallenge, AccountLinkProof, EnableHAOptions, DisableHAOptions, } from './cloud-client.js';
+export type { CloudClientConfig, CloudSession, CloudNamespace, CloudRelay, CloudNamespaceNode, CloudNamespaceRouting, CloudMachine, CloudMachineNamespace, CloudLinkedAccount, CloudLinkedAccounts, CloudAccountLink, AccountLinkChallenge, AccountLinkProof, EnableHAOptions, DisableHAOptions, } from './cloud-client.js';
 export { connectCloud } from './connect.js';
 export type { ConnectCloudOptions, CloudConnection } from './connect.js';