@calimero-network/mero-js 19.6.0 → 19.7.0

package/dist/index.cjs

@@ -786,6 +786,41 @@ function createAuthApiClientFromHttpClient(httpClient, _config) {
   return new AuthApiClient(httpClient);
 }
 
+// src/capabilities.ts
+var CAPABILITIES = {
+  CAN_CREATE_CONTEXT: 1 << 0,
+  CAN_INVITE_MEMBERS: 1 << 1,
+  CAN_JOIN_OPEN_SUBGROUPS: 1 << 2,
+  MANAGE_MEMBERS: 1 << 3,
+  MANAGE_APPLICATION: 1 << 4,
+  CAN_CREATE_SUBGROUP: 1 << 5,
+  CAN_DELETE_SUBGROUP: 1 << 6,
+  CAN_MANAGE_VISIBILITY: 1 << 7,
+  CAN_MANAGE_METADATA: 1 << 8,
+  /**
+   * Publish writes attributed to ANOTHER member, under a warrant that member
+   * signed — the grant delegated execution runs on.
+   *
+   * Implied by nothing: not by membership, not by admin, and not propagated by
+   * the subgroup-admit cascade. So every group is authorship-closed until an
+   * admin sets this bit, and a relay without it is refused at
+   * `performIntent` before anything executes. That is why it is worth naming
+   * here rather than leaving callers to write `1 << 9`: a client granting it
+   * has to be able to say what it is granting.
+   */
+  CAN_AUTHOR_ON_BEHALF: 1 << 9
+};
+function hasCap(mask, cap) {
+  const capU32 = cap >>> 0;
+  return (mask & capU32) >>> 0 === capU32;
+}
+function withCap(mask, cap) {
+  return (mask | cap) >>> 0;
+}
+function withoutCap(mask, cap) {
+  return (mask & ~cap) >>> 0;
+}
+
 // src/admin-api/admin-client.ts
 function unwrap(response) {
   return response?.data;
@@ -1544,6 +1579,85 @@ var AdminApiClient = class {
   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);
   }
@@ -4841,6 +4955,65 @@ var CloudClient = class {
     const relays = await this.getNamespaceRelays(namespaceId);
     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.
    *
@@ -5833,7 +6006,7 @@ function explainNoRelay(namespace, relays) {
   }
   const waitingOnGrant = relays.filter((r) => !r.authorshipReady);
   if (waitingOnGrant.length === relays.length) {
-    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"}`;
+    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"} \u2014 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 \u2014 retry shortly`;
 }
@@ -6120,41 +6293,6 @@ async function login(config) {
   };
 }
 
-// src/capabilities.ts
-var CAPABILITIES = {
-  CAN_CREATE_CONTEXT: 1 << 0,
-  CAN_INVITE_MEMBERS: 1 << 1,
-  CAN_JOIN_OPEN_SUBGROUPS: 1 << 2,
-  MANAGE_MEMBERS: 1 << 3,
-  MANAGE_APPLICATION: 1 << 4,
-  CAN_CREATE_SUBGROUP: 1 << 5,
-  CAN_DELETE_SUBGROUP: 1 << 6,
-  CAN_MANAGE_VISIBILITY: 1 << 7,
-  CAN_MANAGE_METADATA: 1 << 8,
-  /**
-   * Publish writes attributed to ANOTHER member, under a warrant that member
-   * signed — the grant delegated execution runs on.
-   *
-   * Implied by nothing: not by membership, not by admin, and not propagated by
-   * the subgroup-admit cascade. So every group is authorship-closed until an
-   * admin sets this bit, and a relay without it is refused at
-   * `performIntent` before anything executes. That is why it is worth naming
-   * here rather than leaving callers to write `1 << 9`: a client granting it
-   * has to be able to say what it is granting.
-   */
-  CAN_AUTHOR_ON_BEHALF: 1 << 9
-};
-function hasCap(mask, cap) {
-  const capU32 = cap >>> 0;
-  return (mask & capU32) >>> 0 === capU32;
-}
-function withCap(mask, cap) {
-  return (mask | cap) >>> 0;
-}
-function withoutCap(mask, cap) {
-  return (mask & ~cap) >>> 0;
-}
-
 // src/nodeDiscovery.ts
 var DEFAULT_LOCAL_NODE_PORTS = [2428, 2429, 2528, 2529];
 var LOCAL_HOST = "localhost";