@calimero-network/mero-js 27.1.0 → 27.3.0

package/dist/index.cjs

@@ -60,6 +60,7 @@ __export(index_exports, {
   StaleTransportKeyError: () => StaleTransportKeyError,
   TrapError: () => TrapError,
   UnavailableError: () => UnavailableError,
+  WrongNode: () => WrongNode,
   agentKeyBinding: () => agentKeyBinding,
   agentQuoteVerifier: () => agentQuoteVerifier,
   attestAgent: () => attestAgent,
@@ -69,6 +70,7 @@ __export(index_exports, {
   claimedRelease: () => claimedRelease,
   cloudNodeReleaseUrl: () => cloudNodeReleaseUrl,
   compareVersions: () => compareVersions,
+  confirmationCode: () => confirmationCode,
   consentReturn: () => consentReturn,
   createQuoteVerifier: () => createQuoteVerifier,
   createSealedFetch: () => createSealedFetch,
@@ -1340,6 +1342,12 @@ var LoginRequired = class extends CalimeroError {
     this.name = "LoginRequired";
   }
 };
+var WrongNode = class extends CalimeroError {
+  constructor(message, details = {}) {
+    super(421, "WRONG_NODE", message, details);
+    this.name = "WrongNode";
+  }
+};
 var NotFound = class extends CalimeroError {
   constructor(message, details = {}) {
     super(404, "NOT_FOUND", message, details);
@@ -1434,6 +1442,8 @@ function errorFrom(status, body, retryAfterHeader) {
   switch (`${status} ${code}`) {
     case "401 UNAUTHENTICATED":
       return new LoginRequired(message, details);
+    case "421 WRONG_NODE":
+      return new WrongNode(message, details);
     case "404 NOT_FOUND":
       return new NotFound(message, details);
     case "409 IDEMPOTENCY_MISMATCH":
@@ -1560,6 +1570,17 @@ ${generation}`;
 function publisherBindingBytes(cluster, org, signerId, generation) {
   return new TextEncoder().encode(publisherBindingMessage(cluster, org, signerId, generation));
 }
+var CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+async function confirmationCode(requestId) {
+  const h = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(requestId)));
+  const word = (h[0] << 24 | h[1] << 16 | h[2] << 8 | h[3]) >>> 0;
+  let code = "";
+  for (let i = 0; i < 6; i++) {
+    if (i === 3) code += "-";
+    code += CROCKFORD[word >>> 27 - 5 * i & 31];
+  }
+  return code;
+}
 function consentReturn(href) {
   const url2 = typeof href === "string" ? new URL(href) : href;
   const requestId = url2.searchParams.get("request_id");
@@ -1688,11 +1709,20 @@ var DEFAULT_RETRY = { retries: 6, baseDelayMs: 200, maxDelayMs: 2e3 };
 function retryDelayMs(retry, options) {
   return Math.min(options.baseDelayMs * 2 ** retry, options.maxDelayMs);
 }
+function ceremony(path) {
+  return path === "auth/refresh" || path.startsWith("auth/passkey/");
+}
 var CalimeroClient = class {
   constructor(options) {
+    /** The one in use: an index into {@link nodeUrls}. */
+    this.at = 0;
+    /** A sealed fetch per node, each attesting its own node on first use. */
+    this.channels = /* @__PURE__ */ new Map();
     /** Rejections of the underlying `fetch` itself: the node could not be reached or dropped the connection. */
     this.networkFailures = /* @__PURE__ */ new WeakSet();
-    this.base = options.baseUrl.replace(/\/+$/, "");
+    const trim = (url2) => url2.replace(/\/+$/, "");
+    this.nodeUrls = [...new Set([options.baseUrl, ...options.nodes ?? []].map(trim))];
+    this.policy = options.policy;
     this.retry = { ...DEFAULT_RETRY, ...options.retry };
     const given = options.fetch ?? ((input, init) => fetch(input, init));
     const raw = async (input, init) => {
@@ -1704,11 +1734,33 @@ var CalimeroClient = class {
       }
     };
     this.raw = raw;
-    this.sealed = createSealedFetch({
-      baseUrl: this.base,
-      transportPublicKey: () => fetchAttestedKey(this.base, options.policy, raw),
-      fetch: raw
-    });
+  }
+  /** The node requests go to now: `baseUrl`, until a `421 WRONG_NODE` moved the client on. */
+  get nodeUrl() {
+    return this.nodeUrls[this.at];
+  }
+  /** The sealed channel to `url`, attested under the client's policy before its first request. */
+  channel(url2) {
+    let sealed = this.channels.get(url2);
+    if (!sealed) {
+      sealed = createSealedFetch({
+        baseUrl: url2,
+        transportPublicKey: () => fetchAttestedKey(url2, this.policy, this.raw),
+        fetch: this.raw
+      });
+      this.channels.set(url2, sealed);
+    }
+    return sealed;
+  }
+  /**
+   * Move on from node `from` (the one that answered `421 WRONG_NODE`) to the
+   * next one. False when there is no other. A request that saw the same node
+   * refuse after another request moved on already does not move again.
+   */
+  moveOn(from) {
+    if (this.nodeUrls.length < 2) return false;
+    if (this.at === from) this.at = (from + 1) % this.nodeUrls.length;
+    return true;
   }
   /** Authenticate every request with an API key. */
   useApiKey(key) {
@@ -1722,7 +1774,11 @@ var CalimeroClient = class {
   get session() {
     return this.current;
   }
-  async request(method, path, body, raw, contentType = "application/wasm") {
+  /**
+   * Send one request to the node in use, with the credential held now, and
+   * answer the response, whatever its status. {@link send} judges it.
+   */
+  async request(method, path, body, raw, contentType = "application/wasm", signal) {
     const headers = {};
     if (this.auth) headers.authorization = `Bearer ${this.auth}`;
     let payload;
@@ -1733,15 +1789,66 @@ var CalimeroClient = class {
       headers["content-type"] = "application/json";
       payload = JSON.stringify(body);
     }
+    const url2 = this.nodeUrl;
     try {
-      return await this.sealed(`${this.base}/${path}`, { method, headers, body: payload });
+      return await this.channel(url2)(`${url2}/${path}`, { method, headers, body: payload, signal });
     } catch (error) {
       throw sealedError(error);
     }
   }
+  /**
+   * {@link request}, answering what a lost issuing node or a node on the
+   * wrong release does to a session: a successful response, or the refusal as a
+   * typed error ({@link errorFrom}).
+   *
+   * - `401 UNAUTHENTICATED` to a request that carried a session: the node that
+   *   signed the session may be gone, replaced, or out of reach of the node
+   *   asked, which any node of the cluster answers with a refresh. The client
+   *   refreshes once, shared by every request that needs it at the same time
+   *   ({@link refresh}), and repeats the request once. A refresh that is
+   *   refused surfaces as {@link LoginRequired}.
+   * - `421 WRONG_NODE`: this node's release may not serve the account. The
+   *   client moves to the next node it knows and repeats the request once; with
+   *   none, the {@link WrongNode} reaches the caller.
+   *
+   * Repeating is safe even for a request that is not idempotent: the node
+   * answers `401` and `421` when it judges the credential, before it reads what
+   * the request asks, so the first attempt ran nothing. The exceptions are the
+   * ceremonies that mint a session ({@link ceremony}), never repeated here.
+   */
+  async send(method, path, body, raw, contentType, signal) {
+    let refreshed = false;
+    let moved = false;
+    for (; ; ) {
+      const [token, at] = [this.auth, this.at];
+      const response = await this.request(method, path, body, raw, contentType, signal);
+      if (response.ok) return response;
+      const error = await refusal(response);
+      if (error instanceof WrongNode && !moved) {
+        moved = true;
+        if (this.moveOn(at) && !ceremony(path)) continue;
+      } else if (error instanceof LoginRequired && !refreshed && this.mayRefresh(token, path)) {
+        refreshed = true;
+        await this.renew(token);
+        continue;
+      }
+      throw error;
+    }
+  }
+  /** Whether a `401` to a request sent with `token` is one a refresh may answer. */
+  mayRefresh(token, path) {
+    return token !== void 0 && this.current !== void 0 && !ceremony(path);
+  }
+  /**
+   * A fresh session in place of the one `token` belonged to: by the refresh
+   * another request already made, or by one this request starts.
+   */
+  async renew(token) {
+    if (this.auth !== token) return;
+    await this.refresh();
+  }
   async json(method, path, body, raw, contentType) {
-    const response = await this.request(method, path, body, raw, contentType);
-    if (!response.ok) throw await refusal(response);
+    const response = await this.send(method, path, body, raw, contentType);
     const text = await response.text();
     return text ? JSON.parse(text) : {};
   }
@@ -1810,11 +1917,35 @@ var CalimeroClient = class {
     this.useSession(session);
     return session;
   }
-  /** Swap the refresh token for a new session. */
-  async refresh() {
-    if (!this.current) throw new Error("no session to refresh");
-    const session = await this.post("auth/refresh", { refreshToken: this.current.refreshToken });
-    this.useSession(session);
+  /**
+   * Swap the refresh token for a new session, on whichever node the client
+   * uses: any node of the cluster takes it. A refresh token is used once, so
+   * calls made while one refresh is under way share it rather than sending the
+   * same token again (which would revoke the session).
+   */
+  refresh() {
+    if (!this.refreshing) {
+      const pending = this.exchangeRefresh();
+      this.refreshing = pending;
+      const clear = () => {
+        if (this.refreshing === pending) this.refreshing = void 0;
+      };
+      pending.then(clear, clear);
+    }
+    return this.refreshing;
+  }
+  async exchangeRefresh() {
+    const current = this.current;
+    if (!current) throw new Error("no session to refresh");
+    let session;
+    for (let tried = 1; session === void 0; tried++) {
+      try {
+        session = await this.post("auth/refresh", { refreshToken: current.refreshToken });
+      } catch (error) {
+        if (!(error instanceof WrongNode) || tried >= this.nodeUrls.length) throw error;
+      }
+    }
+    if (this.current === current) this.useSession(session);
     return session;
   }
   async signOut() {
@@ -1859,7 +1990,7 @@ var CalimeroClient = class {
    */
   async attestation() {
     const nonce2 = toHex(crypto.getRandomValues(new Uint8Array(32)));
-    const response = await this.raw(`${this.base}/attestation?nonce=${nonce2}`);
+    const response = await this.raw(`${this.nodeUrl}/attestation?nonce=${nonce2}`);
     if (!response.ok) throw await refusal(response);
     return await response.json();
   }
@@ -1887,8 +2018,7 @@ var CalimeroClient = class {
   }
   /** One of `app`'s blobs, by id (base58 or hex). */
   async downloadBlob(app, id) {
-    const response = await this.request("GET", `apps/${seg(app)}/blobs/${seg(id)}`);
-    if (!response.ok) throw await refusal(response);
+    const response = await this.send("GET", `apps/${seg(app)}/blobs/${seg(id)}`);
     return new Uint8Array(await response.arrayBuffer());
   }
   /** `app`'s blobs. */
@@ -2057,10 +2187,7 @@ var CalimeroClient = class {
   }
   /** A server-sent event stream on `path`, sealed like every other answer. */
   async *stream(path, signal) {
-    const headers = {};
-    if (this.auth) headers.authorization = `Bearer ${this.auth}`;
-    const response = await this.sealed(`${this.base}/${path}`, { headers, signal });
-    if (!response.ok) throw await refusal(response);
+    const response = await this.send("GET", path, void 0, void 0, void 0, signal);
     if (!response.body) throw new CalimeroError(response.status, "EVENTS", "the event stream has no body");
     yield* sseFrames(response.body);
   }
@@ -2227,16 +2354,34 @@ var CalimeroClient = class {
   }
   /**
    * {@link requestConsent}, then send the browser to the consent page
-   * (`navigate`, by default `window.location.assign`). Answers the request
-   * once `navigate` returns: with a popup (`url => window.open(url)`), poll it
-   * with {@link waitForConsent}.
+   * (`navigate`, by default `window.location.assign`). Pass `navigate` itself
+   * or {@link OpenConsentOptions}, whose `confirm` runs first with the node's
+   * answer so the app can show the person its `code`; when it answers `false`
+   * the page is not opened. When the node sends a `code` that is not
+   * {@link confirmationCode} of `requestId`, it throws `CalimeroError`
+   * (`CONSENT_CODE_MISMATCH`) and does not navigate. Answers the request
+   * once `navigate` returns (or `confirm` declines): with a popup
+   * (`url => window.open(url)`), poll it with {@link waitForConsent}.
    */
-  async openConsentPage(request, navigate = (url2) => {
-    const w = globalThis.window;
-    if (!w) throw new Error("no window to open the consent page in; pass `navigate`");
-    w.location.assign(url2);
-  }) {
+  async openConsentPage(request, navigateOrOptions = {}) {
+    const options = typeof navigateOrOptions === "function" ? { navigate: navigateOrOptions } : navigateOrOptions;
+    const navigate = options.navigate ?? ((url2) => {
+      const w = globalThis.window;
+      if (!w) throw new Error("no window to open the consent page in; pass `navigate`");
+      w.location.assign(url2);
+    });
     const started = await this.requestConsent(request);
+    if (started.code !== void 0) {
+      const expected = await confirmationCode(started.requestId);
+      if (started.code !== expected) {
+        throw new CalimeroError(200, "CONSENT_CODE_MISMATCH", "the consent page code does not match the request", {
+          requestId: started.requestId,
+          code: started.code,
+          expected
+        });
+      }
+    }
+    if (options.confirm && !await options.confirm(started)) return started;
     navigate(started.url);
     return started;
   }