@calimero-network/mero-js 27.4.0 → 28.0.0

package/dist/index.cjs

@@ -40,8 +40,10 @@ __export(index_exports, {
   ConfirmRequired: () => ConfirmRequired,
   ConsentStale: () => ConsentStale,
   DEFAULT_COLLATERAL_MIRROR: () => DEFAULT_COLLATERAL_MIRROR,
+  DEFAULT_DIRECTORY: () => DEFAULT_DIRECTORY,
   DEFAULT_ORG_CAPABILITIES: () => DEFAULT_ORG_CAPABILITIES,
   DEFAULT_RELEASE_MIRROR: () => DEFAULT_RELEASE_MIRROR,
+  DirectoryError: () => DirectoryError,
   GITHUB_RELEASES: () => GITHUB_RELEASES,
   HANDSHAKE_PATH: () => HANDSHAKE_PATH,
   IdempotencyMismatch: () => IdempotencyMismatch,
@@ -1357,6 +1359,85 @@ async function fetchAttestedKey(baseUrl, policy, fetchImpl = (input, init) => fe
   return transportKey;
 }
 
+// src/cloud-v2/directory.ts
+var DEFAULT_DIRECTORY = "https://manager.cloud.calimero.network/api/v2/directory";
+var DEFAULT_REFRESH_SECONDS = 60;
+var DirectoryError = class extends Error {
+  constructor(cluster, reason, message, status, cause) {
+    super(`directory for cluster ${cluster}: ${message}`);
+    this.cluster = cluster;
+    this.reason = reason;
+    this.status = status;
+    this.cause = cause;
+    this.name = "DirectoryError";
+  }
+};
+function directoryUrl(directory, cluster) {
+  return `${directory.replace(/\/+$/, "")}/${encodeURIComponent(cluster)}`;
+}
+async function readDirectory(directory, cluster, fetcher) {
+  let response;
+  try {
+    response = await fetcher(directoryUrl(directory, cluster), { method: "GET", headers: { accept: "application/json" } });
+  } catch (error) {
+    throw new DirectoryError(cluster, "unreachable", `could not be reached: ${String(error)}`, void 0, error);
+  }
+  if (response.status === 404) throw new DirectoryError(cluster, "not-found", "unknown cluster", 404);
+  if (!response.ok) throw new DirectoryError(cluster, "unreachable", `answered ${response.status}`, response.status);
+  let body;
+  try {
+    body = await response.json();
+  } catch (error) {
+    throw new DirectoryError(cluster, "bad-response", "answered something other than JSON", response.status, error);
+  }
+  const listing = body;
+  if (!listing || typeof listing !== "object" || !Array.isArray(listing.nodes)) {
+    throw new DirectoryError(cluster, "bad-response", "answered no node list", response.status);
+  }
+  const nodes = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const entry of listing.nodes) {
+    const node = usable(entry);
+    if (node && !seen.has(node.url)) {
+      seen.add(node.url);
+      nodes.push(node);
+    }
+  }
+  if (nodes.length === 0) throw new DirectoryError(cluster, "empty", "lists no usable node", response.status);
+  const after = listing.refreshAfterSeconds;
+  const refreshAfterSeconds = typeof after === "number" && Number.isFinite(after) && after >= 1 ? after : DEFAULT_REFRESH_SECONDS;
+  return { nodes, refreshAfterSeconds };
+}
+function usable(entry) {
+  if (!entry || typeof entry !== "object") return void 0;
+  const { url: url2, zone, weight } = entry;
+  if (typeof url2 !== "string" || typeof weight !== "number" || !Number.isInteger(weight) || weight < 1) return void 0;
+  let parsed;
+  try {
+    parsed = new URL(url2);
+  } catch {
+    return void 0;
+  }
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") return void 0;
+  return { url: url2.replace(/\/+$/, ""), zone: typeof zone === "string" ? zone : void 0, weight };
+}
+function orderNodes(nodes, zone, random) {
+  const near = zone === void 0 ? [] : nodes.filter((node) => node.zone === zone);
+  const far = zone === void 0 ? nodes : nodes.filter((node) => node.zone !== zone);
+  return [...weightedOrder(near, random), ...weightedOrder(far, random)];
+}
+function weightedOrder(nodes, random) {
+  const left = [...nodes];
+  const order = [];
+  while (left.length > 0) {
+    let roll = random() * left.reduce((sum, node) => sum + node.weight, 0);
+    let pick = 0;
+    while (pick < left.length - 1 && roll >= left[pick].weight) roll -= left[pick++].weight;
+    order.push(left.splice(pick, 1)[0].url);
+  }
+  return order;
+}
+
 // src/cloud-v2/errors.ts
 var CalimeroError = class extends Error {
   constructor(status, code, message, details = {}) {
@@ -1743,7 +1824,7 @@ function retryDelayMs(retry, options) {
 function ceremony(path) {
   return path === "auth/refresh" || path.startsWith("auth/passkey/");
 }
-var CalimeroClient = class {
+var CalimeroClient = class _CalimeroClient {
   constructor(options) {
     /** The one in use: an index into {@link nodeUrls}. */
     this.at = 0;
@@ -1766,10 +1847,40 @@ var CalimeroClient = class {
     };
     this.raw = raw;
   }
-  /** The node requests go to now: `baseUrl`, until a `421 WRONG_NODE` moved the client on. */
+  /**
+   * A client for the Calimero Cloud cluster named `cluster`: its node list read
+   * from the public node directory, those in `zone` first, each group in
+   * weighted-random order. The directory only picks which nodes to try: each is
+   * attested under `policy` before anything is sent to it. Throws
+   * {@link DirectoryError} when the directory names no usable node.
+   *
+   * The list is read again in the background after a failover, and at the
+   * first request once the directory's `refreshAfterSeconds` has passed.
+   */
+  static async connect(options) {
+    const directory = options.directory ?? DEFAULT_DIRECTORY;
+    const random = options.random ?? Math.random;
+    const fetcher = options.fetch ?? ((input, init) => fetch(input, init));
+    const listing = await readDirectory(directory, options.cluster, fetcher);
+    const [baseUrl, ...nodes] = orderNodes(listing.nodes, options.zone, random);
+    const client = new _CalimeroClient({ baseUrl, nodes, policy: options.policy, fetch: options.fetch, retry: options.retry });
+    client.source = {
+      directory,
+      cluster: options.cluster,
+      zone: options.zone,
+      random,
+      due: Date.now() + listing.refreshAfterSeconds * 1e3
+    };
+    return client;
+  }
+  /** The node requests go to now: `baseUrl`, until a `421 WRONG_NODE` or a failover moved the client on. */
   get nodeUrl() {
     return this.nodeUrls[this.at];
   }
+  /** Every node this client may use, in the order it moves through them. */
+  get nodes() {
+    return [...this.nodeUrls];
+  }
   /** The sealed channel to `url`, attested under the client's policy before its first request. */
   channel(url2) {
     let sealed = this.channels.get(url2);
@@ -1790,9 +1901,46 @@ var CalimeroClient = class {
    */
   moveOn(from) {
     if (this.nodeUrls.length < 2) return false;
-    if (this.at === from) this.at = (from + 1) % this.nodeUrls.length;
+    if (this.nodeUrl === from) this.at = (this.at + 1) % this.nodeUrls.length;
     return true;
   }
+  /**
+   * Fail over from node `from`, where a request's retries ran out, to the next
+   * node it has not `tried`. False when it has tried them all. A request whose
+   * node another request moved away from already goes to that node, if untried.
+   */
+  failOver(from, tried) {
+    if (this.nodeUrl !== from && !tried.has(this.nodeUrl)) return true;
+    const count = this.nodeUrls.length;
+    for (let step = 1; step < count; step++) {
+      const next = (this.at + step) % count;
+      if (!tried.has(this.nodeUrls[next])) {
+        this.at = next;
+        this.reread();
+        return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * Read the node list again from the directory, in the background, for a
+   * client made by {@link connect}: the node in use stays first, then the
+   * directory's order; a node no longer listed is dropped. A failed read is
+   * ignored. One read at a time.
+   */
+  reread() {
+    const source = this.source;
+    if (!source || source.reading) return;
+    source.reading = readDirectory(source.directory, source.cluster, this.raw).then((listing) => {
+      const current = this.nodeUrl;
+      const listed = orderNodes(listing.nodes, source.zone, source.random);
+      this.nodeUrls = [current, ...listed.filter((url2) => url2 !== current)];
+      this.at = 0;
+      source.due = Date.now() + listing.refreshAfterSeconds * 1e3;
+    }).catch(() => void 0).finally(() => {
+      source.reading = void 0;
+    });
+  }
   /** Authenticate every request with an API key. */
   useApiKey(key) {
     this.auth = key;
@@ -1820,6 +1968,7 @@ var CalimeroClient = class {
       headers["content-type"] = "application/json";
       payload = JSON.stringify(body);
     }
+    if (this.source && Date.now() >= this.source.due) this.reread();
     const url2 = this.nodeUrl;
     try {
       return await this.channel(url2)(`${url2}/${path}`, { method, headers, body: payload, signal });
@@ -1851,7 +2000,7 @@ var CalimeroClient = class {
     let refreshed = false;
     let moved = false;
     for (; ; ) {
-      const [token, at] = [this.auth, this.at];
+      const [token, at] = [this.auth, this.nodeUrl];
       const response = await this.request(method, path, body, raw, contentType, signal);
       if (response.ok) return response;
       const error = await refusal(response);
@@ -1887,25 +2036,40 @@ var CalimeroClient = class {
    * {@link json} for a call or a view (D70): while the node answers 503 or
    * cannot be reached, the same request, with the same idempotency key, is sent
    * again after {@link retryDelayMs} (or the pause the node asked for, if
-   * longer), at most `retries` times. Every other answer is final. The last
+   * longer), at most `retries` times. Every other answer is final.
+   *
+   * When a node's retries run out, the request fails over to the next node the
+   * client knows and its retries start again there, with the same key: the
+   * key is kept in the app's replicated log, so the cluster answers it once
+   * whichever node it reaches. Each node is tried once per request. The last
    * failure surfaces as {@link UnavailableError}: the node's 503, or reason
    * `network` for a connection that failed, whose `committed` is `'unknown'`.
-   * `retries` 0 sends the request exactly once.
+   *
+   * `once` sends the request exactly once, to the node in use (the confirmed
+   * attempt of {@link callConfirmed}, whose challenge is single-use).
    */
-  async retried(method, path, body, retries = this.retry.retries) {
-    for (let attempt = 0; ; attempt++) {
+  async retried(method, path, body, once = false) {
+    const retries = once ? 0 : this.retry.retries;
+    const tried = /* @__PURE__ */ new Set();
+    for (; ; ) {
       let unavailable;
-      try {
-        return await this.json(method, path, body);
-      } catch (error) {
-        if (error instanceof UnavailableError) unavailable = error;
-        else if (error instanceof TypeError && this.networkFailures.has(error)) {
-          unavailable = new UnavailableError("NETWORK", `the node could not be reached: ${error.message}`, {}, void 0, error);
-        } else throw error;
+      let node = this.nodeUrl;
+      for (let attempt = 0; ; attempt++) {
+        node = this.nodeUrl;
+        tried.add(node);
+        try {
+          return await this.json(method, path, body);
+        } catch (error) {
+          if (error instanceof UnavailableError) unavailable = error;
+          else if (error instanceof TypeError && this.networkFailures.has(error)) {
+            unavailable = new UnavailableError("NETWORK", `the node could not be reached: ${error.message}`, {}, void 0, error);
+          } else throw error;
+        }
+        if (attempt >= retries) break;
+        const backoff = retryDelayMs(attempt, this.retry);
+        await new Promise((resolve) => setTimeout(resolve, Math.max(backoff, (unavailable.retryAfter ?? 0) * 1e3)));
       }
-      if (attempt >= retries) throw unavailable;
-      const backoff = retryDelayMs(attempt, this.retry);
-      await new Promise((resolve) => setTimeout(resolve, Math.max(backoff, (unavailable.retryAfter ?? 0) * 1e3)));
+      if (once || !this.failOver(node, tried)) throw unavailable;
     }
   }
   post(path, body = {}) {
@@ -1993,19 +2157,25 @@ var CalimeroClient = class {
   me() {
     return this.get("auth/me");
   }
-  /** Add another passkey (another device) to the signed-in account; answers its credential id. */
-  async addPasskey(passkey) {
+  /**
+   * Add another passkey (another device, `passkey`) to the signed-in account;
+   * answers its credential id. The node asks for the approval of a passkey
+   * the account already has (`412 CONFIRM_REQUIRED`, never the new one),
+   * which `approver` gives.
+   */
+  async addPasskey(passkey, approver) {
     const begin = await this.post("auth/passkeys/add/begin");
     const registration = await passkey.create(begin.options);
-    const { credentialId } = await this.post("auth/passkeys/add/finish", {
-      challengeId: begin.challengeId,
-      registration
-    });
+    const { credentialId } = await this.postConfirmed(
+      "auth/passkeys/add/finish",
+      { challengeId: begin.challengeId, registration },
+      approver
+    );
     return credentialId;
   }
-  /** Remove one of the account's passkeys (not the last). */
-  async removePasskey(credentialId) {
-    await this.delete(`auth/passkeys/${seg(credentialId)}`);
+  /** Remove one of the account's passkeys (not the last), approved with `passkey` (one it has). */
+  async removePasskey(credentialId, passkey) {
+    await this.deleteConfirmed(`auth/passkeys/${seg(credentialId)}`, passkey);
   }
   /** Name one of the account's passkeys (a device label); `''` clears the name. */
   async labelPasskey(credentialId, label) {
@@ -2033,9 +2203,13 @@ var CalimeroClient = class {
   async revokeApiKey(keyId) {
     await this.delete(`auth/apikeys/${seg(keyId)}`);
   }
-  /** Create an API key for an agent or server. The key is returned once. */
-  createApiKey(options) {
-    return this.post("auth/apikeys", options);
+  /**
+   * Create an API key for an agent or server, approved with the account's
+   * `passkey` (`412 CONFIRM_REQUIRED`); needs a passkey session (an API key
+   * is refused `403`). The key is returned once.
+   */
+  createApiKey(options, passkey) {
+    return this.postConfirmed("auth/apikeys", { ...options }, passkey);
   }
   // ---------------------------------------------------------------- apps
   /** Upload a raw WASM bundle (development clusters only); answers its hash. */
@@ -2143,12 +2317,19 @@ var CalimeroClient = class {
   }
   /**
    * POST `body` to `path`, answering a `412 CONFIRM_REQUIRED` with `passkey`'s
-   * assertion over the node's challenge (deleting an org, approving a release, ...).
+   * assertion over the node's challenge (deleting an org, approving a release,
+   * adding a member, ...): the same body again, with `confirm`. Without a
+   * passkey (a caller in plain JavaScript passing none) the `412` reaches the
+   * caller as {@link ConfirmRequired}, carrying the challenge.
    */
   postConfirmed(path, body, passkey) {
     return this.confirmed("POST", path, body, passkey);
   }
-  /** {@link postConfirmed} for a DELETE (deleting an organization). */
+  /**
+   * {@link postConfirmed} for a DELETE (deleting an organization, removing a
+   * member or a passkey): `body` (`{}` by default) goes as JSON, and the
+   * confirmed retry carries `confirm` beside it.
+   */
   deleteConfirmed(path, passkey, body = {}) {
     return this.confirmed("DELETE", path, body, passkey);
   }
@@ -2156,7 +2337,7 @@ var CalimeroClient = class {
     try {
       return await send(body);
     } catch (error) {
-      if (!(error instanceof ConfirmRequired)) throw error;
+      if (!(error instanceof ConfirmRequired) || !passkey) throw error;
       const d = error.details;
       let assertion;
       try {
@@ -2200,7 +2381,7 @@ var CalimeroClient = class {
       path,
       { method, args, idempotencyKey: key },
       passkey,
-      (body) => this.retried("POST", path, body, body.confirm === void 0 ? this.retry.retries : 0)
+      (body) => this.retried("POST", path, body, body.confirm !== void 0)
     );
   }
   /** Run a read-only method: strong by default, or stale from any replica. */
@@ -2480,20 +2661,24 @@ var CalimeroClient = class {
   async liftReleaseDeadline(version) {
     await this.delete(`ops/releases/${seg(version)}/deadline`);
   }
-  /** Add a member, or change their role. */
-  async setMember(org, account, role) {
-    await this.post(`orgs/${seg(org)}/members`, { account, role });
+  /** Add a member, or change their role, approved with the caller's `passkey`. */
+  async setMember(org, account, role, passkey) {
+    await this.postConfirmed(`orgs/${seg(org)}/members`, { account, role }, passkey);
   }
-  removeMember(org, account) {
-    return this.delete(`orgs/${seg(org)}/members/${seg(account)}`);
+  /**
+   * Remove a member, or leave (`account` the caller's own), approved with the
+   * caller's `passkey`.
+   */
+  removeMember(org, account, passkey) {
+    return this.deleteConfirmed(`orgs/${seg(org)}/members/${seg(account)}`, passkey);
   }
   /**
    * Set capability bits ({@link ORG_CAPABILITIES}): for a member (`account`),
    * for a member of one team (`account` and `team`), or the organization's
-   * default (neither).
+   * default (neither). Approved with the caller's `passkey`.
    */
-  async setCapabilities(org, capabilities, at = {}) {
-    await this.post(`orgs/${seg(org)}/capabilities`, { capabilities, ...at });
+  async setCapabilities(org, capabilities, passkey, at = {}) {
+    await this.postConfirmed(`orgs/${seg(org)}/capabilities`, { capabilities, ...at }, passkey);
   }
   async createTeam(org, name, join, parent) {
     const { teamId } = await this.post(`orgs/${seg(org)}/teams`, { name, join, parent });
@@ -2513,15 +2698,28 @@ var CalimeroClient = class {
   async deleteTeam(org, team) {
     await this.delete(`orgs/${seg(org)}/teams/${seg(team)}`);
   }
-  /** Add a member to a team, or change their row: role, lead, capability bits. */
-  async setTeamMember(org, team, account, row = {}) {
-    await this.post(`orgs/${seg(org)}/teams/${seg(team)}/members`, { account, ...row });
+  /**
+   * Add a member to a team, or change their row: role, lead, capability bits.
+   * Approved with the caller's `passkey`.
+   */
+  async setTeamMember(org, team, account, passkey, row = {}) {
+    await this.postConfirmed(`orgs/${seg(org)}/teams/${seg(team)}/members`, { account, ...row }, passkey);
   }
-  async removeTeamMember(org, team, account) {
-    await this.delete(`orgs/${seg(org)}/teams/${seg(team)}/members/${seg(account)}`);
+  /** Remove a member from a team, approved with the caller's `passkey`. */
+  async removeTeamMember(org, team, account, passkey) {
+    await this.deleteConfirmed(`orgs/${seg(org)}/teams/${seg(team)}/members/${seg(account)}`, passkey);
   }
-  async invite(org, role, teams = [], options = {}) {
-    const { token } = await this.post(`orgs/${seg(org)}/invites`, { role, teams, ...options });
+  /**
+   * Make an invite into `org` (and `teams`), approved with the caller's
+   * `passkey`; answers its token, which {@link redeemInvite} takes (no
+   * approval there).
+   */
+  async invite(org, role, passkey, teams = [], options = {}) {
+    const { token } = await this.postConfirmed(
+      `orgs/${seg(org)}/invites`,
+      { role, teams, ...options },
+      passkey
+    );
     return token;
   }
   redeemInvite(token) {