@calimero-network/mero-js 18.2.0 → 19.0.0

package/dist/index.mjs

@@ -886,8 +886,10 @@ var AdminApiClient = class {
   async getContextStorage(contextId) {
     return unwrap(await this.httpClient.get(`/admin-api/contexts/${contextId}/storage`));
   }
+  /** Sync one context, or every context when `contextId` is omitted. */
   async syncContext(contextId) {
-    await this.httpClient.post(`/admin-api/contexts/sync/${contextId ?? ""}`, {});
+    const path = contextId ? `/admin-api/contexts/sync/${contextId}` : "/admin-api/contexts/sync";
+    await this.httpClient.post(path, {});
   }
   /**
    * Kick off a full state re-pull for a context (operator recovery for a
@@ -1102,6 +1104,32 @@ var AdminApiClient = class {
       )
     );
   }
+  /**
+   * Ask what this node can do for a member in `contextId`, before they sign
+   * anything.
+   *
+   * The two facts {@link performIntent} needs and a client cannot derive: whose
+   * account goes in the warrant's `executor`, and whether this node holds
+   * `CAN_AUTHOR_ON_BEHALF` on the owning group. `canAuthorOnBehalf: false` comes
+   * back as an answer rather than an error — it is the default state of every
+   * context — so a caller can say "an admin of `groupId` must grant it to
+   * `executorAccount`" instead of presenting a warrant that will be refused
+   * after the author has spent a nonce on it.
+   *
+   * `404` means the context belongs to no group, or this node holds no account
+   * yet; either way it can be named as no warrant's executor.
+   *
+   * For a caller with no credential on the node at all — a browser tab holding
+   * one signing key — use `RelayClient`, which reads this same route on a node
+   * run as a relay.
+   */
+  async getIntentRelay(contextId) {
+    return unwrap(
+      await this.httpClient.get(
+        `/admin-api/contexts/${contextId}/intents`
+      )
+    );
+  }
   async listNamespacesForApplication(applicationId) {
     return unwrap(await this.httpClient.get(`/admin-api/namespaces/for-application/${applicationId}`));
   }
@@ -2232,6 +2260,335 @@ var EphemeralClient = class {
   }
 };
 
+// src/cloud/cloud-client.ts
+var DEFAULT_CLOUD_BASE_URL = "https://cloud.calimero.network";
+var REFRESH_HEADER = "x-mdma-session-refresh";
+var REFRESH_EXPIRES_HEADER = "x-mdma-session-expires";
+var CloudClient = class {
+  constructor(config = {}) {
+    this.session = null;
+    this.baseUrl = (config.cloudBaseUrl || DEFAULT_CLOUD_BASE_URL).replace(/\/+$/, "");
+    this.onSession = config.onSession;
+    const injected = config.fetch;
+    this.fetchImpl = injected ? (input, init) => injected(input, init) : (input, init) => globalThis.fetch(input, init);
+    this.timeoutMs = config.timeoutMs ?? 1e4;
+    if (config.sessionToken) {
+      this.session = {
+        sessionToken: config.sessionToken,
+        expiresAt: 0,
+        user: { email: "" }
+      };
+    }
+  }
+  /** The current session, or `null` when nobody is signed in. */
+  getSession() {
+    return this.session;
+  }
+  /** Whether a session token is held. Says nothing about the server agreeing. */
+  isSignedIn() {
+    return this.session !== null;
+  }
+  /**
+   * Exchange a Google OAuth2 ID token for an MDMA session.
+   *
+   * The app owns the Google flow (One Tap, an auth-code popup, a native
+   * browser) and hands the resulting ID token here once. Everything after this
+   * uses the returned session token, so the Google credential does not have to
+   * be kept or re-minted per call.
+   */
+  async signInWithGoogle(idToken) {
+    const body = await this.request("POST", "/api/auth/google", { body: { id_token: idToken }, anonymous: true });
+    return this.adoptSession(body);
+  }
+  /**
+   * Refresh the session token explicitly.
+   *
+   * Rarely needed: MDMA rolling-refreshes on ordinary authenticated calls and
+   * this client adopts the replacement automatically. Use it when an app wants
+   * a fresh token before going idle rather than on the next request.
+   */
+  async refreshSession() {
+    const body = await this.request("POST", "/api/auth/refresh");
+    return this.adoptSession(body);
+  }
+  /**
+   * Revoke this session server-side and forget it locally.
+   *
+   * Local state is cleared even if the server call fails: the caller asked to
+   * be signed out, and keeping a token they believe is gone is the worse of the
+   * two failures.
+   */
+  async signOut() {
+    try {
+      if (this.session) await this.request("POST", "/api/auth/logout", { parse: "none" });
+    } finally {
+      this.session = null;
+      void this.notifySession(null);
+    }
+  }
+  /** Namespaces the signed-in user owns. */
+  async getMyNamespaces() {
+    const rows = await this.request(
+      "GET",
+      "/api/cloud/me/namespaces"
+    );
+    return rows.map((row) => ({
+      namespaceId: String(row.namespace_id ?? row.group_id ?? ""),
+      groupId: String(row.group_id ?? row.namespace_id ?? ""),
+      haStatus: String(row.ha_status ?? "none"),
+      haEnabledAt: row.ha_enabled_at ?? null,
+      contexts: Array.isArray(row.contexts) ? row.contexts : [],
+      fleetReplicas: row.fleet_replicas
+    }));
+  }
+  /**
+   * 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.
+   */
+  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
+    }));
+  }
+  /**
+   * 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.
+   */
+  async findExecutingRelay(namespaceId) {
+    const relays = await this.getNamespaceRelays(namespaceId);
+    return relays.find((r) => r.authorshipReady && r.relayUrl !== null && r.executorAccount !== null) ?? null;
+  }
+  /**
+   * Every attested machine currently serving something this account owns.
+   *
+   * The account-wide view of the same rows {@link getNamespaceRelays} returns
+   * per namespace, keyed by machine — so a UI can answer "what is running for
+   * me?" in one call. `canExecute` folds the three-way precondition, so a
+   * caller does not re-derive it.
+   *
+   * Only the caller's own namespaces appear on each machine. A plan's
+   * `usersPerMachine` is greater than one, so a fleet node routinely serves
+   * several accounts at once.
+   */
+  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) => {
+        const ns = n;
+        return {
+          namespaceId: String(ns.namespace_id ?? ""),
+          status: String(ns.status ?? ""),
+          authorshipReady: ns.authorship_ready === true,
+          fresh: ns.fresh === true,
+          confirmedAt: ns.confirmed_at ?? null,
+          lastSeenAt: ns.last_seen_at ?? null
+        };
+      })
+    }));
+  }
+  /**
+   * Claim a namespace under this account, proving ownership.
+   *
+   * The cloud has no other way to learn a namespace exists — namespaces are
+   * created on a node, and there is deliberately no "create namespace" in the
+   * cloud. `ownershipProof` comes from
+   * `admin.issueNamespaceOwnershipProof(namespaceId, …)` on a node that is a
+   * **direct admin** of that namespace; merod refuses to issue one otherwise.
+   *
+   * Pass merod's response object straight through. The cloud accepts core's
+   * `signerPublicKey`/`signedPayload` casing as well as snake_case, so there is
+   * no re-keying step — and getting that wrong used to surface as a `422`
+   * naming three missing fields.
+   *
+   * Idempotent for the same account. A namespace already claimed by someone
+   * else is a `409`; a replayed proof nonce is a `403`.
+   */
+  async claimNamespace(namespaceId, ownershipProof) {
+    await this.request("POST", "/api/cloud/namespaces/claim", {
+      body: { namespace_id: namespaceId, ownership_proof: ownershipProof }
+    });
+  }
+  /**
+   * Ask the fleet to host a claimed namespace — the step that gets a relay
+   * assigned.
+   *
+   * Takes no body: {@link claimNamespace} already established ownership, and
+   * this is the separate "now host it" half. Idempotent.
+   *
+   * Not to be confused with {@link enableHA}, which opens the cloud's web flow
+   * in a browser tab for a user to complete by hand. This is the API call.
+   */
+  async enableNamespaceHa(namespaceId) {
+    return this.request(
+      "POST",
+      `/api/cloud/namespaces/${encodeURIComponent(namespaceId)}/enable-ha`,
+      { body: {} }
+    );
+  }
+  /**
+   * Stop hosting a claimed namespace.
+   *
+   * The fleet's own reconcile loop does the rest: each assigned node notices
+   * the namespace is no longer assigned to it and **self-leaves**, which makes
+   * core evict it and purge its local data and keys. So this is not just a
+   * billing flip.
+   */
+  async disableNamespaceHa(namespaceId) {
+    return this.request(
+      "POST",
+      `/api/cloud/namespaces/${encodeURIComponent(namespaceId)}/disable-ha`,
+      { body: {} }
+    );
+  }
+  /**
+   * The node assigned to the signed-in user, or `null`.
+   *
+   * @deprecated Use {@link getMyMachines}. This reads the cloud's retired
+   * `NodeAssignment` ledger, which nothing has written since the v1
+   * retirement, so it answers `null` for every namespace-native account —
+   * which reads as "you have no machine" when the truth is "that is no longer
+   * how a machine is assigned".
+   */
+  async getMyNode() {
+    const body = await this.request(
+      "GET",
+      "/api/cloud/me/node"
+    );
+    return body.node ?? null;
+  }
+  enableHA(options) {
+    const params = new URLSearchParams({
+      group_id: options.groupId,
+      context_id: options.contextId
+    });
+    if (options.redirectUrl) {
+      params.set("redirect_url", options.redirectUrl);
+    }
+    window.open(`${this.baseUrl}/enable-ha?${params.toString()}`);
+  }
+  disableHA(options) {
+    const params = new URLSearchParams({
+      group_id: options.groupId,
+      context_id: options.contextId
+    });
+    if (options.redirectUrl) {
+      params.set("redirect_url", options.redirectUrl);
+    }
+    window.open(`${this.baseUrl}/disable-ha?${params.toString()}`);
+  }
+  /** Record a freshly-issued session and tell the app to persist it. */
+  adoptSession(body) {
+    this.session = {
+      sessionToken: body.session_token,
+      expiresAt: body.expires_at,
+      user: body.user
+    };
+    void this.notifySession(this.session);
+    return this.session;
+  }
+  async notifySession(session) {
+    try {
+      await this.onSession?.(session);
+    } catch {
+    }
+  }
+  async request(method, path, options = {}) {
+    if (!options.anonymous && !this.session) {
+      throw new Error(
+        "Not signed in to Calimero Cloud: call signInWithGoogle() or construct the client with a sessionToken"
+      );
+    }
+    const headers = { Accept: "application/json" };
+    if (options.body !== void 0) headers["Content-Type"] = "application/json";
+    if (!options.anonymous && this.session) {
+      headers.Authorization = `Bearer ${this.session.sessionToken}`;
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    let response;
+    try {
+      response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+        method,
+        headers,
+        body: options.body === void 0 ? void 0 : JSON.stringify(options.body),
+        signal: controller.signal
+      });
+    } catch (err) {
+      throw new HTTPError(
+        0,
+        err instanceof Error ? err.name : "NetworkError",
+        `${this.baseUrl}${path}`,
+        new Headers(),
+        err instanceof Error ? err.message : String(err)
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+    this.adoptRollingRefresh(response);
+    if (!response.ok) {
+      const bodyText = await response.text().catch(() => void 0);
+      throw new HTTPError(
+        response.status,
+        response.statusText,
+        `${this.baseUrl}${path}`,
+        response.headers,
+        bodyText
+      );
+    }
+    if (options.parse === "none" || response.status === 204) return void 0;
+    return await response.json();
+  }
+  /**
+   * Adopt a session token the server refreshed mid-request.
+   *
+   * MDMA rotates the token on activity and returns the replacement in a
+   * response header rather than making the client ask. Ignoring it costs
+   * nothing immediately and then logs the user out a week later, which is the
+   * kind of bug that is impossible to reproduce in a short session.
+   *
+   * The user identity is carried over: the header holds only a token, and the
+   * refresh is the same logical session as the sign-in that named the user.
+   */
+  adoptRollingRefresh(response) {
+    const token = response.headers.get(REFRESH_HEADER);
+    if (!token || !this.session) return;
+    const expiresRaw = response.headers.get(REFRESH_EXPIRES_HEADER);
+    const expiresAt = Number(expiresRaw);
+    this.session = {
+      sessionToken: token,
+      expiresAt: Number.isFinite(expiresAt) && expiresAt > 0 ? expiresAt : this.session.expiresAt,
+      user: this.session.user
+    };
+    void this.notifySession(this.session);
+  }
+};
+
 // src/mero-js.ts
 var REFRESH_LOCK_NAME = "mero-js:token-refresh";
 function getLockManager() {
@@ -2365,6 +2722,22 @@ var MeroJs = class {
     }
     return this.ephemeralClient;
   }
+  /**
+   * Calimero Cloud (lazy initialized).
+   *
+   * Available whether or not `cloud` was configured — an app that signs in
+   * later gets an unauthenticated client it can call `signInWithGoogle` on,
+   * which is one fewer construction path than making the getter conditional.
+   * It is entirely independent of this instance's node credential: the cloud
+   * knows nothing about the node's tokens and the node knows nothing about the
+   * cloud session.
+   */
+  get cloud() {
+    if (!this.cloudClient) {
+      this.cloudClient = new CloudClient(this.config.cloud ?? {});
+    }
+    return this.cloudClient;
+  }
   /**
    * Get the WebSocket event client (lazy initialized).
    * @experimental Use `events` (SSE) for production. WsClient is experimental.
@@ -2609,33 +2982,6 @@ var LocalStorageTokenStore = class {
   }
 };
 
-// src/cloud/cloud-client.ts
-var CloudClient = class {
-  constructor(config = {}) {
-    this.baseUrl = (config.cloudBaseUrl || "https://cloud.calimero.network").replace(/\/+$/, "");
-  }
-  enableHA(options) {
-    const params = new URLSearchParams({
-      group_id: options.groupId,
-      context_id: options.contextId
-    });
-    if (options.redirectUrl) {
-      params.set("redirect_url", options.redirectUrl);
-    }
-    window.open(`${this.baseUrl}/enable-ha?${params.toString()}`);
-  }
-  disableHA(options) {
-    const params = new URLSearchParams({
-      group_id: options.groupId,
-      context_id: options.contextId
-    });
-    if (options.redirectUrl) {
-      params.set("redirect_url", options.redirectUrl);
-    }
-    window.open(`${this.baseUrl}/disable-ha?${params.toString()}`);
-  }
-};
-
 // src/crypto/internal.ts
 var PKCS8_ED25519_PREFIX = new Uint8Array([
   48,
@@ -2736,8 +3082,10 @@ async function derivePublicKey(secretHex) {
 }
 
 // src/warrant/warrant.ts
-var SIGN_DOMAIN = new TextEncoder().encode("calimero.warrant.v1");
+var SIGN_DOMAIN = new TextEncoder().encode("calimero.warrant.v2");
 var INTENT_DOMAIN = new TextEncoder().encode("calimero.warrant.intent.v1");
+var MAX_CITED_HEADS = 64;
+var UNPINNED_APP = "00".repeat(32);
 async function intentHash(method, argsJson) {
   const args = new TextEncoder().encode(JSON.stringify(argsJson));
   return domainHash(INTENT_DOMAIN, [new TextEncoder().encode(method), args]);
@@ -2746,8 +3094,16 @@ async function signWarrant(input) {
   const context = fromHex(input.context, "context", 32);
   const authorAccount = fromHex(input.authorAccount, "authorAccount", 32);
   const executor = fromHex(input.executor, "executor", 32);
+  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 method = new TextEncoder().encode(input.method);
   const commitment = await intentHash(input.method, input.argsJson);
   const nonce = u64le(input.nonce);
   const notAfter = u64le(input.notAfter);
@@ -2756,7 +3112,13 @@ async function signWarrant(input) {
     authorAccount,
     publicKey,
     executor,
+    appVersion,
+    method,
     commitment,
+    u64le(accountHeads.length),
+    ...accountHeads,
+    u64le(governanceFloor.length),
+    ...governanceFloor,
     nonce,
     notAfter
   ]);
@@ -2769,13 +3131,268 @@ async function signWarrant(input) {
       authorAccount,
       publicKey,
       executor,
+      appVersion,
+      u32le(method.length),
+      method,
       commitment,
+      u32le(accountHeads.length),
+      ...accountHeads,
+      u32le(governanceFloor.length),
+      ...governanceFloor,
       nonce,
       notAfter,
       signature
     )
   );
 }
+function citedHeads(heads, label) {
+  const list = heads ?? [];
+  if (list.length > MAX_CITED_HEADS) {
+    throw new Error(
+      `${label} cites ${list.length} heads, over the ${MAX_CITED_HEADS} a node accepts`
+    );
+  }
+  return list.map((head, i) => fromHex(head, `${label}[${i}]`, 32));
+}
+
+// src/relay/relay-client.ts
+var DEFAULT_TTL_SECONDS = 300;
+var IntentRefusedError = class extends Error {
+  constructor(reason, retryable, status) {
+    super(`relay refused the intent (HTTP ${status}): ${reason}`);
+    this.reason = reason;
+    this.retryable = retryable;
+    this.status = status;
+    this.name = "IntentRefusedError";
+  }
+};
+var RelayClient = class {
+  constructor(config) {
+    this.config = config;
+    this.baseUrl = config.relayUrl.replace(/\/+$/, "");
+    this.executorAccount = config.executorAccount;
+    const injected = config.fetch;
+    this.fetchImpl = injected ? (input, init) => injected(input, init) : (input, init) => globalThis.fetch(input, init);
+    this.timeoutMs = config.timeoutMs ?? 1e4;
+  }
+  /**
+   * Ask the relay what it can do in `contextId`.
+   *
+   * Cheap and unauthenticated on a relay that serves delegated execution
+   * publicly, which is what makes it usable as a precondition check rather than
+   * as diagnostics after a failure.
+   */
+  async describe(contextId) {
+    const body = await this.json("GET", `/admin-api/contexts/${encodeURIComponent(contextId)}/intents`);
+    this.executorAccount = body.data.executorAccount;
+    return body.data;
+  }
+  /**
+   * Mint a warrant for `method(args)` and present it to the relay.
+   *
+   * One intent, once: the warrant authorizes exactly this method and these
+   * arguments in exactly this context, and its nonce is spent by the network on
+   * apply. Nothing accumulates and nothing is reusable.
+   */
+  async execute(contextId, method, argsJson = {}) {
+    const executor = this.executorAccount ?? (await this.describe(contextId)).executorAccount;
+    const nonce = await this.config.nonces.next();
+    const ttl = this.config.ttlSeconds ?? DEFAULT_TTL_SECONDS;
+    const warrant = await signWarrant({
+      context: contextId,
+      authorAccount: this.config.authorAccount,
+      executor,
+      method,
+      argsJson,
+      nonce,
+      notAfter: BigInt(Math.floor(Date.now() / 1e3)) + BigInt(ttl),
+      deviceSecret: this.config.deviceSecret
+    });
+    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 };
+  }
+  async json(method, path, body) {
+    const headers = { Accept: "application/json" };
+    if (body !== void 0) headers["Content-Type"] = "application/json";
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    let response;
+    try {
+      response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+        method,
+        headers,
+        body: body === void 0 ? void 0 : JSON.stringify(body),
+        signal: controller.signal
+      });
+    } catch (err) {
+      throw new HTTPError(
+        0,
+        err instanceof Error ? err.name : "NetworkError",
+        `${this.baseUrl}${path}`,
+        new Headers(),
+        err instanceof Error ? err.message : String(err)
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+    if (!response.ok) {
+      const text = await response.text().catch(() => "");
+      if (response.status === 400 || response.status === 403) {
+        const reason = extractReason(text);
+        throw new IntentRefusedError(reason, /nonce/i.test(reason), response.status);
+      }
+      throw new HTTPError(
+        response.status,
+        response.statusText,
+        `${this.baseUrl}${path}`,
+        response.headers,
+        text
+      );
+    }
+    return await response.json();
+  }
+};
+function extractReason(bodyText) {
+  if (!bodyText) return "no reason given";
+  try {
+    const parsed = JSON.parse(bodyText);
+    for (const candidate of [parsed.error, parsed.message]) {
+      if (typeof candidate === "string" && candidate) return candidate;
+    }
+  } catch {
+  }
+  return bodyText;
+}
+
+// src/relay/nonce-source.ts
+function createMemoryNonceSource(start = 1) {
+  let next = BigInt(start);
+  if (next < 1n) {
+    throw new Error("nonce sequence starts at 1");
+  }
+  return {
+    next() {
+      const value = next;
+      next += 1n;
+      return Promise.resolve(value);
+    }
+  };
+}
+function createLocalStorageNonceSource(key, storage) {
+  const store = storage ?? globalThis.localStorage;
+  if (!store) {
+    throw new Error(
+      "no localStorage in this runtime: pass a storage implementation, or use createMemoryNonceSource for a process that owns its whole sequence"
+    );
+  }
+  return {
+    next() {
+      const raw = store.getItem(key);
+      let current = 0n;
+      if (raw !== null && raw !== "") {
+        try {
+          const parsed = BigInt(raw);
+          if (parsed > 0n) current = parsed;
+        } catch {
+          current = 0n;
+        }
+      }
+      const value = current + 1n;
+      store.setItem(key, value.toString());
+      return Promise.resolve(value);
+    }
+  };
+}
+
+// src/cloud/connect.ts
+async function connectCloud(options) {
+  if (!options.sessionToken && !options.googleIdToken) {
+    throw new Error("connectCloud needs either a sessionToken or a googleIdToken");
+  }
+  const cloud = new CloudClient({
+    cloudBaseUrl: options.cloudBaseUrl,
+    sessionToken: options.sessionToken,
+    onSession: options.onSession,
+    fetch: options.fetch,
+    timeoutMs: options.timeoutMs
+  });
+  if (!options.sessionToken && options.googleIdToken) {
+    await cloud.signInWithGoogle(options.googleIdToken);
+  }
+  const namespaces = await cloud.getMyNamespaces();
+  const namespace = pickNamespace(namespaces, options.namespaceId);
+  const relays = await cloud.getNamespaceRelays(namespace.namespaceId);
+  const relayInfo = relays.find((r) => r.authorshipReady && r.relayUrl !== null && r.executorAccount !== null) ?? null;
+  if (!relayInfo) {
+    throw new Error(explainNoRelay(namespace, relays));
+  }
+  const relay = new RelayClient({
+    // Checked by `findExecutingRelay`, 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,
+    executorAccount: relayInfo.executorAccount,
+    authorAccount: options.authorAccount,
+    authorProof: options.authorProof,
+    deviceSecret: options.deviceSecret,
+    nonces: options.nonces ?? await defaultNonceSource(options.deviceSecret),
+    ttlSeconds: options.ttlSeconds,
+    fetch: options.fetch,
+    timeoutMs: options.timeoutMs
+  });
+  return {
+    cloud,
+    relay,
+    namespaceId: namespace.namespaceId,
+    namespace,
+    relayInfo,
+    execute: (contextId, method, argsJson) => relay.execute(contextId, method, argsJson)
+  };
+}
+function pickNamespace(namespaces, requested) {
+  if (requested) {
+    const found = namespaces.find((n) => n.namespaceId === requested);
+    if (!found) {
+      throw new Error(
+        `this account owns no namespace ${requested}; it owns: ${namespaces.map((n) => n.namespaceId).join(", ") || "(none)"}`
+      );
+    }
+    return found;
+  }
+  if (namespaces.length === 0) {
+    throw new Error(
+      "this account owns no namespaces in the cloud: claim one first, then enable HA on it so a relay is assigned"
+    );
+  }
+  if (namespaces.length > 1) {
+    throw new Error(
+      `this account owns ${namespaces.length} namespaces \u2014 pass namespaceId to say which: ${namespaces.map((n) => n.namespaceId).join(", ")}`
+    );
+  }
+  return namespaces[0];
+}
+function explainNoRelay(namespace, relays) {
+  if (relays.length === 0) {
+    return namespace.haStatus === "enabled" ? `namespace ${namespace.namespaceId} has HA enabled but no relay has been assigned to it yet \u2014 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) {
+    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 `namespace ${namespace.namespaceId} has ${relays.length} relay(s), but none reported both a URL and an executor account yet \u2014 retry shortly`;
+}
+async function defaultNonceSource(deviceSecret) {
+  const key = `mero-js:warrant-nonce:${hex(await derivePublicKey(deviceSecret))}`;
+  try {
+    return createLocalStorageNonceSource(key);
+  } catch {
+    return createMemoryNonceSource(1);
+  }
+}
 
 // src/device-cert/device-cert.ts
 var CERT_DOMAIN = new TextEncoder().encode("calimero.device.cert.v1");
@@ -2973,7 +3590,19 @@ var CAPABILITIES = {
   CAN_CREATE_SUBGROUP: 1 << 5,
   CAN_DELETE_SUBGROUP: 1 << 6,
   CAN_MANAGE_VISIBILITY: 1 << 7,
-  CAN_MANAGE_METADATA: 1 << 8
+  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;
@@ -3047,9 +3676,11 @@ export {
   DEFAULT_LOCAL_NODE_PORTS,
   EphemeralClient,
   HTTPError,
+  IntentRefusedError,
   LocalStorageTokenStore,
   MemoryTokenStore,
   MeroJs,
+  RelayClient,
   RpcClient,
   RpcError,
   SIGNED_NAMESPACE_OP_SCHEMA_VERSION,
@@ -3060,6 +3691,7 @@ export {
   buildAuthLoginUrl,
   combineSignals,
   compareSemver,
+  connectCloud,
   createAdminApiClient,
   createAdminApiClientFromHttpClient,
   createAuthApiClient,
@@ -3068,6 +3700,8 @@ export {
   createBrowserAuthApiClient,
   createBrowserHttpClient,
   createHttpClient,
+  createLocalStorageNonceSource,
+  createMemoryNonceSource,
   createMeroJs,
   createNodeAdminApiClient,
   createNodeAuthApiClient,