@calimero-network/mero-js 22.1.0 → 22.3.0

package/README.md

@@ -132,11 +132,13 @@ builds the relay client. `sdk.cloud` exposes the same cloud API from an existing
 `MeroJs` instance for apps that have both a node and a cloud account, and
 `RelayClient` is available directly for a relay you were told about out of band.
 
-One precondition is not yours to satisfy: an admin of the namespace must grant
-the relay `CAN_AUTHOR_ON_BEHALF` (core implies it from nothing — not from
-membership, not from admin). Until then `connectCloud` throws naming the account
-that needs the grant, and `relay.describe(contextId)` reports
-`canAuthorOnBehalf: false` so a UI can say so rather than failing a write.
+One precondition is not yours to satisfy: the node must relay. A fleet node
+admitted as a `RelayTee` (the namespace's TEE admission policy set with
+`mode: 'relay'`) relays by role; a `ReadOnlyTee` is a replica and never relays;
+and a node too old to report a role needs an admin of the namespace to grant it
+`CAN_AUTHOR_ON_BEHALF`. `connectCloud` picks a relay on the cloud's `canExecute`,
+which folds that rule in, and otherwise throws saying which of those is missing —
+naming the account that needs the grant when that is the fix.
 
 See the [cloud client](https://calimero-network.github.io/mero-js/reference/cloud/),
 [relay client](https://calimero-network.github.io/mero-js/reference/relay/) and

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

@@ -25,6 +25,13 @@
  * to involve it.
  */
 import { type DiscoveryChallenge, type RoutingChallenge, type RoutingCredential } from './routing-proof.js';
+/**
+ * The first relay a warrant can be spent at, or `null`.
+ *
+ * Shared by {@link CloudClient.findExecutingRelay} and `connectCloud`, which
+ * already holds the list and must not fetch it twice.
+ */
+export declare function pickExecutingRelay(relays: readonly CloudRelay[]): CloudRelay | null;
 export interface CloudClientConfig {
     cloudBaseUrl?: string;
     /**
@@ -90,11 +97,13 @@ export interface CloudNamespace {
  * One attested node the cloud has assigned to a namespace, described as a
  * relay.
  *
- * `authorshipReady` is the field that decides whether a write can happen, and
- * it is reported rather than assumed because it is not the cloud's to grant:
- * `CAN_AUTHOR_ON_BEHALF` is a governance capability, set by an admin of the
- * namespace, and the cloud only relays what the node observed. A relay that is
- * `active` with `authorshipReady: false` is a healthy node waiting for a grant.
+ * `canExecute` is the field that decides whether a write can happen, and it is
+ * the cloud's own verdict rather than something to re-derive: a node that
+ * reports a role relays only as a `RelayTee` (the namespace's TEE admission
+ * policy set with `mode: 'relay'`), whatever its grant; a `ReadOnlyTee` is a
+ * replica and never relays. Only a node too old to report a role is decided by
+ * `authorshipReady` — the `CAN_AUTHOR_ON_BEHALF` grant, which is reported
+ * rather than assumed because it is not the cloud's to give.
  */
 export interface CloudRelay {
     peerId: string;
@@ -106,6 +115,20 @@ export interface CloudRelay {
     status: string;
     /** Whether this relay holds `CAN_AUTHOR_ON_BEHALF` on the namespace. */
     authorshipReady: boolean;
+    /**
+     * The core role the node reported for itself here — `'RelayTee'` or
+     * `'ReadOnlyTee'` — or `null` for a sidecar too old to report one.
+     */
+    teeRole: string | null;
+    /**
+     * Whether an intent can be presented here now: a URL, an executor account, a
+     * fresh heartbeat, and a node that relays by role (or, for one reporting no
+     * role, holds the grant).
+     *
+     * The cloud's `can_execute`. Against an older cloud that does not send it,
+     * derived from `authorshipReady` plus the URL and account, as before.
+     */
+    canExecute: boolean;
     lastSeenAt?: string | null;
     confirmedAt?: string | null;
 }
@@ -159,9 +182,12 @@ export interface CloudNamespaceNode {
     canAdmit: boolean;
     /** Whether the node holds `CAN_AUTHOR_ON_BEHALF` on the namespace root group. */
     authorshipReady: boolean;
+    /** `'RelayTee'`, `'ReadOnlyTee'`, or `null` for a node too old to report one. */
+    teeRole: string | null;
     /**
      * Whether a delegated write can be posted here now — a URL, an account, a
-     * fresh heartbeat and the grant.
+     * fresh heartbeat, and a `RelayTee` (or, for a node reporting no role, the
+     * grant). A `ReadOnlyTee` is a replica and never relays.
      *
      * 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
@@ -186,6 +212,8 @@ export interface CloudMachineNamespace {
     status: string;
     /** Whether the machine holds `CAN_AUTHOR_ON_BEHALF` on this namespace. */
     authorshipReady: boolean;
+    /** `'RelayTee'`, `'ReadOnlyTee'`, or `null` for a machine too old to report one. */
+    teeRole: string | null;
     /**
      * Whether the machine's heartbeat for this namespace is recent.
      *
@@ -210,7 +238,8 @@ export interface CloudMachine {
     executorAccount: string | null;
     /**
      * Whether this machine can write for the caller *somewhere* — a URL, an
-     * executor account, and the grant on at least one namespace.
+     * executor account, and at least one namespace it relays in: as a
+     * `RelayTee`, or, reporting no role, holding the grant.
      *
      * Folded here so a client does not re-derive the three-way precondition and
      * get a refusal it cannot explain.
@@ -395,19 +424,20 @@ export declare class CloudClient {
      * The relays serving one namespace: where to present an intent, and as whom.
      *
      * Everything a client needs in order to mint a warrant it can actually
-     * spend. Filter on `authorshipReady` before signing — a warrant presented to
-     * a relay with no grant is refused *after* the author has burned a nonce from
-     * its monotonic sequence on it.
+     * spend. Filter on `canExecute` before signing — a warrant presented to a
+     * relay that does not relay (a `ReadOnlyTee` replica, or a node with no role
+     * and no grant) is refused *after* the author has burned a nonce from its
+     * monotonic sequence on it.
      */
     getNamespaceRelays(namespaceId: string): Promise<CloudRelay[]>;
     /**
      * The first relay for `namespaceId` that can actually run an intent, or
      * `null`.
      *
-     * "Can actually run one" is three conditions, and a client that checks fewer
-     * gets a refusal it cannot explain: the cloud must know a URL, the relay must
-     * have reported the executor account a warrant has to name, and the grant
-     * must be in place.
+     * "Can actually run one" is several conditions, and a client that checks
+     * fewer gets a refusal it cannot explain: the cloud must know a URL, the
+     * relay must have reported the executor account a warrant has to name, and
+     * the node must relay — which the cloud folds into `canExecute`.
      */
     findExecutingRelay(namespaceId: string): Promise<CloudRelay | null>;
     /**

package/dist/cloud/cloud-client.js

@@ -29,6 +29,31 @@ import { HTTPError } from '../http-client/web-client.js';
 import { routingProofHeaders, } from './routing-proof.js';
 /** Where the hosted cloud lives when a caller names no other. */
 const DEFAULT_CLOUD_BASE_URL = 'https://cloud.calimero.network';
+/**
+ * The cloud's own `can_execute` where it sends one, else `legacy`.
+ *
+ * The cloud decides relaying by role (`RelayTee` relays, `ReadOnlyTee` never
+ * does) and only falls back to the `CAN_AUTHOR_ON_BEHALF` grant for a node
+ * that reports none, so re-deriving it here from `authorship_ready` would call
+ * a grant-holding `ReadOnlyTee` writable. `legacy` is the grant-based answer,
+ * for a cloud older than the field — the only rule such a cloud knew.
+ */
+function canExecuteOf(row, legacy) {
+    return typeof row.can_execute === 'boolean' ? row.can_execute : legacy;
+}
+/** The reported `tee_role`, or `null` when absent (older cloud or sidecar). */
+function teeRoleOf(row) {
+    return typeof row.tee_role === 'string' && row.tee_role !== '' ? row.tee_role : null;
+}
+/**
+ * The first relay a warrant can be spent at, or `null`.
+ *
+ * Shared by {@link CloudClient.findExecutingRelay} and `connectCloud`, which
+ * already holds the list and must not fetch it twice.
+ */
+export function pickExecutingRelay(relays) {
+    return (relays.find((r) => r.canExecute && r.relayUrl !== null && r.executorAccount !== null) ?? null);
+}
 /** Response headers MDMA uses to hand back a rolling-refreshed session. */
 const REFRESH_HEADER = 'x-mdma-session-refresh';
 const REFRESH_EXPIRES_HEADER = 'x-mdma-session-expires';
@@ -181,35 +206,42 @@ export class CloudClient {
      * The relays serving one namespace: where to present an intent, and as whom.
      *
      * Everything a client needs in order to mint a warrant it can actually
-     * spend. Filter on `authorshipReady` before signing — a warrant presented to
-     * a relay with no grant is refused *after* the author has burned a nonce from
-     * its monotonic sequence on it.
+     * spend. Filter on `canExecute` before signing — a warrant presented to a
+     * relay that does not relay (a `ReadOnlyTee` replica, or a node with no role
+     * and no grant) is refused *after* the author has burned a nonce from its
+     * monotonic sequence on it.
      */
     async getNamespaceRelays(namespaceId) {
         const body = await this.request('GET', `/api/cloud/me/namespaces/${encodeURIComponent(namespaceId)}/relays`);
-        return (body.relays ?? []).map((row) => ({
-            peerId: String(row.peer_id ?? ''),
-            relayUrl: row.relay_url ?? null,
-            executorAccount: row.executor_account ?? null,
-            status: String(row.status ?? ''),
-            authorshipReady: row.authorship_ready === true,
-            lastSeenAt: row.last_seen_at ?? null,
-            confirmedAt: row.confirmed_at ?? null,
-        }));
+        return (body.relays ?? []).map((row) => {
+            const relayUrl = row.relay_url ?? null;
+            const executorAccount = row.executor_account ?? null;
+            const authorshipReady = row.authorship_ready === true;
+            return {
+                peerId: String(row.peer_id ?? ''),
+                relayUrl,
+                executorAccount,
+                status: String(row.status ?? ''),
+                authorshipReady,
+                teeRole: teeRoleOf(row),
+                canExecute: canExecuteOf(row, authorshipReady && relayUrl !== null && executorAccount !== null),
+                lastSeenAt: row.last_seen_at ?? null,
+                confirmedAt: row.confirmed_at ?? null,
+            };
+        });
     }
     /**
      * The first relay for `namespaceId` that can actually run an intent, or
      * `null`.
      *
-     * "Can actually run one" is three conditions, and a client that checks fewer
-     * gets a refusal it cannot explain: the cloud must know a URL, the relay must
-     * have reported the executor account a warrant has to name, and the grant
-     * must be in place.
+     * "Can actually run one" is several conditions, and a client that checks
+     * fewer gets a refusal it cannot explain: the cloud must know a URL, the
+     * relay must have reported the executor account a warrant has to name, and
+     * the node must relay — which the cloud folds into `canExecute`.
      */
     async findExecutingRelay(namespaceId) {
         const relays = await this.getNamespaceRelays(namespaceId);
-        return (relays.find((r) => r.authorshipReady && r.relayUrl !== null && r.executorAccount !== null) ??
-            null);
+        return pickExecutingRelay(relays);
     }
     /**
      * Where to reach a namespace without owning it: one read, both verbs.
@@ -237,17 +269,24 @@ export class CloudClient {
         });
         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,
-            })),
+            nodes: (body.admitters ?? []).map((row) => {
+                const account = row.account ?? null;
+                const relayUrl = row.relay_url ?? null;
+                const fresh = row.fresh === true;
+                const authorshipReady = row.authorship_ready === true;
+                return {
+                    peerId: String(row.peer_id ?? ''),
+                    account,
+                    relayUrl,
+                    admitUrl: row.admit_url ?? null,
+                    status: String(row.status ?? ''),
+                    fresh,
+                    canAdmit: row.can_admit === true,
+                    authorshipReady,
+                    teeRole: teeRoleOf(row),
+                    canExecute: canExecuteOf(row, authorshipReady && relayUrl !== null && account !== null && fresh),
+                };
+            }),
             servable: body.servable === true,
             writable: body.writable === true,
         };
@@ -374,23 +413,29 @@ export class CloudClient {
      */
     async getMyMachines() {
         const body = await this.request('GET', '/api/cloud/me/machines');
-        return (body.machines ?? []).map((row) => ({
-            peerId: String(row.peer_id ?? ''),
-            relayUrl: row.relay_url ?? null,
-            executorAccount: row.executor_account ?? null,
-            canExecute: row.can_execute === true,
-            namespaces: (Array.isArray(row.namespaces) ? row.namespaces : []).map((n) => {
+        return (body.machines ?? []).map((row) => {
+            const relayUrl = row.relay_url ?? null;
+            const executorAccount = row.executor_account ?? null;
+            const namespaces = (Array.isArray(row.namespaces) ? row.namespaces : []).map((n) => {
                 const ns = n;
                 return {
                     namespaceId: String(ns.namespace_id ?? ''),
                     status: String(ns.status ?? ''),
                     authorshipReady: ns.authorship_ready === true,
+                    teeRole: teeRoleOf(ns),
                     fresh: ns.fresh === true,
                     confirmedAt: ns.confirmed_at ?? null,
                     lastSeenAt: ns.last_seen_at ?? null,
                 };
-            }),
-        }));
+            });
+            return {
+                peerId: String(row.peer_id ?? ''),
+                relayUrl,
+                executorAccount,
+                canExecute: canExecuteOf(row, relayUrl !== null && executorAccount !== null && namespaces.some((n) => n.authorshipReady)),
+                namespaces,
+            };
+        });
     }
     /**
      * Claim a namespace under this account, proving ownership.

package/dist/cloud/connect.d.ts

@@ -106,7 +106,8 @@ export interface CloudConnection {
  *
  * Throws rather than returning a half-usable connection, and the message says
  * which step is missing — no namespace, several to choose between, HA not
- * enabled, or no relay holding the authorship grant. Every one of those is
+ * enabled, or no relay that relays (only replicas, or relays waiting for a
+ * grant). Every one of those is
  * something the user has to go and do, and a client that reports them alike
  * cannot tell them what.
  */

package/dist/cloud/connect.js

@@ -34,7 +34,7 @@
  * rather than presenting a half-working `MeroJs` whose `admin` and `rpc` would
  * need a credential nobody holds.
  */
-import { CloudClient } from './cloud-client.js';
+import { CloudClient, pickExecutingRelay } from './cloud-client.js';
 import { RelayClient } from '../relay/relay-client.js';
 import { createLocalStorageNonceSource, createMemoryNonceSource } from '../relay/nonce-source.js';
 import { derivePublicKey, hex } from '../crypto/internal.js';
@@ -44,7 +44,8 @@ import { createAttestedSealedFetch } from '../sealed/sealed.js';
  *
  * Throws rather than returning a half-usable connection, and the message says
  * which step is missing — no namespace, several to choose between, HA not
- * enabled, or no relay holding the authorship grant. Every one of those is
+ * enabled, or no relay that relays (only replicas, or relays waiting for a
+ * grant). Every one of those is
  * something the user has to go and do, and a client that reports them alike
  * cannot tell them what.
  */
@@ -69,13 +70,12 @@ export async function connectCloud(options) {
     // first — reporting "waiting for the grant" about a relay that was already
     // usable a moment ago.
     const relays = await cloud.getNamespaceRelays(namespace.namespaceId);
-    const relayInfo = relays.find((r) => r.authorshipReady && r.relayUrl !== null && r.executorAccount !== null) ??
-        null;
+    const relayInfo = pickExecutingRelay(relays);
     if (!relayInfo) {
         throw new Error(explainNoRelay(namespace, relays));
     }
     const relay = new RelayClient({
-        // Checked by `findExecutingRelay`, which is the only thing that returns a
+        // Checked by `pickExecutingRelay`, which is the only thing that returns a
         // relay — narrowed here rather than re-validated, so the invariant lives in
         // one place.
         relayUrl: relayInfo.relayUrl,
@@ -125,11 +125,11 @@ function pickNamespace(namespaces, requested) {
     return namespaces[0];
 }
 /**
- * Why no relay can write here — the three states, kept apart.
+ * Why no relay can write here — the states, kept apart.
  *
- * They are three different asks of the user (turn HA on, wait, or get an admin
- * to grant a capability) and one message for all of them would send them to
- * the wrong one.
+ * They are different asks of the user (turn HA on, wait, have an admin admit
+ * TEEs as relays, or have an admin grant a capability) and one message for all
+ * of them would send them to the wrong one.
  */
 function explainNoRelay(namespace, relays) {
     if (relays.length === 0) {
@@ -137,8 +137,19 @@ function explainNoRelay(namespace, relays) {
             ? `namespace ${namespace.namespaceId} has HA enabled but no relay has been assigned to it yet — retry shortly`
             : `namespace ${namespace.namespaceId} has no relays: enable HA on it in the cloud to have an attested node assigned`;
     }
-    const waitingOnGrant = relays.filter((r) => !r.authorshipReady);
-    if (waitingOnGrant.length === relays.length) {
+    // A node that reports a role is decided by it alone: a `ReadOnlyTee` is a
+    // replica and never relays, whatever its grant, so asking for the grant would
+    // send the admin to the wrong fix. Only a node too old to report a role is
+    // still waiting on `CAN_AUTHOR_ON_BEHALF`.
+    const replicas = relays.filter((r) => r.teeRole !== null && r.teeRole !== 'RelayTee');
+    if (replicas.length === relays.length) {
+        return (`every node on namespace ${namespace.namespaceId} is a read-only TEE replica (ReadOnlyTee), ` +
+            `which never relays delegated writes: an admin of the namespace must set its TEE admission ` +
+            `policy with mode: 'relay' — AdminClient.setTeeAdmissionPolicy(namespaceId, { ..., mode: 'relay' }) ` +
+            `— so fleet nodes are admitted as RelayTee`);
+    }
+    const waitingOnGrant = relays.filter((r) => r.teeRole === null && !r.authorshipReady);
+    if (waitingOnGrant.length > 0 && waitingOnGrant.length + replicas.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
@@ -149,7 +160,7 @@ function explainNoRelay(namespace, relays) {
             `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`;
+    return `namespace ${namespace.namespaceId} has ${relays.length} relay(s), but none is ready to relay yet (a URL, an executor account and a recent heartbeat) — retry shortly`;
 }
 /**
  * A persisted nonce source keyed by the author's device public key.