@calimero-network/mero-js 29.14.0 → 29.16.0

package/dist/index.mjs

@@ -1406,6 +1406,14 @@ var ReleaseDeadlineError = class extends CalimeroError {
     this.after = typeof details.after === "string" ? details.after : "";
   }
 };
+var RuntimeTooOld = class extends CalimeroError {
+  constructor(message, details = {}) {
+    super(409, "RUNTIME_TOO_OLD", message, details);
+    this.name = "RuntimeTooOld";
+    this.minRuntimeVersion = typeof details.minRuntimeVersion === "string" ? details.minRuntimeVersion : "";
+    this.nodes = Array.isArray(details.nodes) ? details.nodes : [];
+  }
+};
 var ConsentStale = class extends CalimeroError {
   constructor(message, details = {}) {
     super(409, "CONSENT_STALE", message, details);
@@ -1541,6 +1549,8 @@ function errorFrom(status, body, retryAfterHeader) {
       return new IdempotencyMismatch(message, details);
     case "409 RELEASE_DEADLINE":
       return new ReleaseDeadlineError(message, details);
+    case "409 RUNTIME_TOO_OLD":
+      return new RuntimeTooOld(message, details);
     case "409 CONSENT_STALE":
       return new ConsentStale(message, details);
     case "403 ORIGIN_NOT_REGISTERED":
@@ -1659,6 +1669,440 @@ function browserPasskey() {
   };
 }
 
+// src/runtime/transport.ts
+var DEFAULT_RETRY = { retries: 6, baseDelayMs: 200, maxDelayMs: 2e3 };
+function retryDelayMs(retry, options) {
+  return Math.min(options.baseDelayMs * 2 ** retry, options.maxDelayMs);
+}
+function userVerificationOf(named, fallback) {
+  return named === "required" || named === "preferred" || named === "discouraged" ? named : fallback;
+}
+function promptFailure(error) {
+  const e = error;
+  const name = e?.name;
+  const message = typeof e?.message === "string" ? e.message : "";
+  if (name === "InvalidStateError" || /not focused|already pending/i.test(message)) {
+    return new ConfirmPromptBlocked(error);
+  }
+  if (name === "NotAllowedError" || name === "AbortError") return new ConfirmCancelled(error);
+  return error;
+}
+function sealedError(error) {
+  if (error instanceof SealedTransportError && error.status === 413) {
+    return errorFrom(413, {
+      error: "TOO_LARGE",
+      message: error.message.replace(/^Sealed request refused: /, "")
+    });
+  }
+  return error;
+}
+async function refusal(response) {
+  const text = await response.text().catch(() => "");
+  let body = {};
+  try {
+    body = text ? JSON.parse(text) : {};
+  } catch {
+    body = { message: text };
+  }
+  return errorFrom(response.status, body, response.headers.get("retry-after"));
+}
+async function* sseFrames(body) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  for (; ; ) {
+    const { value, done } = await reader.read();
+    if (done) return;
+    buffer += decoder.decode(value, { stream: true });
+    let cut;
+    while ((cut = buffer.indexOf("\n\n")) >= 0) {
+      const frame = buffer.slice(0, cut);
+      buffer = buffer.slice(cut + 2);
+      let id = "";
+      let kind = "";
+      let data = "";
+      for (const line of frame.split("\n")) {
+        if (line.startsWith("id:")) id = line.slice(3).trim();
+        else if (line.startsWith("event:")) kind = line.slice(6).trim();
+        else if (line.startsWith("data:")) data += line.slice(5).trim();
+      }
+      if (!kind && !data) continue;
+      let parsed = data;
+      try {
+        parsed = JSON.parse(data);
+      } catch {
+      }
+      yield { id, kind, data: parsed };
+    }
+  }
+}
+function newIdempotencyKey() {
+  return `node:c-${b64url(crypto.getRandomValues(new Uint8Array(16)))}`;
+}
+function routePath(template, params = {}) {
+  return template.replace(/\{([^}]+)\}/g, (_, name) => {
+    const value = params[name];
+    if (value === void 0) throw new Error(`no value for path parameter ${name} of ${template}`);
+    return encodeURIComponent(String(value));
+  });
+}
+function queryString(query) {
+  if (!query) return "";
+  const search = new URLSearchParams();
+  for (const [name, value] of Object.entries(query)) {
+    for (const one of Array.isArray(value) ? value : [value]) {
+      if (one !== void 0 && one !== null) search.append(name, String(one));
+    }
+  }
+  const text = search.toString();
+  return text ? `?${text}` : "";
+}
+function ceremony(path) {
+  return path === "auth/refresh" || path.startsWith("auth/passkey/") || RECOVERY_CEREMONIES.has(path);
+}
+var RECOVERY_CEREMONIES = /* @__PURE__ */ new Set(["auth/recovery/begin", "auth/recovery/start", "auth/recovery/finish"]);
+function relative(path) {
+  return path.replace(/^\/+/, "");
+}
+var NodeTransport = 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();
+    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) => {
+      try {
+        return await given(input, init);
+      } catch (error) {
+        if (error instanceof TypeError) this.networkFailures.add(error);
+        throw error;
+      }
+    };
+    this.raw = raw;
+  }
+  /** Re-read the node list from `source` when it is due, and after a failover. */
+  useDirectory(source) {
+    this.source = source;
+  }
+  /** The node requests go to now: `baseUrl`, until a `421 WRONG_NODE` or a failover moved on. */
+  get nodeUrl() {
+    return this.nodeUrls[this.at];
+  }
+  /** Every node this transport may use, in the order it moves through them. */
+  get nodes() {
+    return [...this.nodeUrls];
+  }
+  /** Authenticate every request with an API key. */
+  useApiKey(key) {
+    this.auth = key;
+    this.current = void 0;
+  }
+  /** Authenticate every request with `session`, refreshed when a node answers `401` to it. */
+  useSession(session) {
+    this.auth = session.sessionToken;
+    this.current = session;
+  }
+  /** Drop the credential: no request after this carries it. */
+  signOut() {
+    this.auth = void 0;
+    this.current = void 0;
+  }
+  get session() {
+    return this.current;
+  }
+  /** The sealed channel to `url`, attested under the 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.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: 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;
+    });
+  }
+  /**
+   * 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 once(method, path, options) {
+    const headers = {};
+    if (this.auth) headers.authorization = `Bearer ${this.auth}`;
+    let payload;
+    if (options.bytes) {
+      headers["content-type"] = options.contentType ?? "application/wasm";
+      payload = options.bytes;
+    } else if (options.body !== void 0) {
+      headers["content-type"] = "application/json";
+      payload = JSON.stringify(options.body);
+    }
+    if (this.source && Date.now() >= this.source.due) this.reread();
+    const url2 = this.nodeUrl;
+    try {
+      return await this.channel(url2)(`${url2}/${path}${queryString(options.query)}`, {
+        method,
+        headers,
+        body: payload,
+        signal: options.signal
+      });
+    } catch (error) {
+      throw sealedError(error);
+    }
+  }
+  /**
+   * {@link once}, 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
+   *   transport 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
+   *   transport 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, options) {
+    let refreshed = false;
+    let moved = false;
+    for (; ; ) {
+      const [token, at] = [this.auth, this.nodeUrl];
+      const response = await this.once(method, path, options);
+      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 read(method, path, options) {
+    const response = await this.send(method, path, options);
+    const text = await response.text();
+    return text ? JSON.parse(text) : {};
+  }
+  /**
+   * {@link read} 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.
+   *
+   * When a node's retries run out, the request fails over to the next node the
+   * transport 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'`.
+   *
+   * `once` sends the request exactly once, to the node in use (a confirmed
+   * attempt, whose challenge is single-use).
+   */
+  async retried(method, path, options, once) {
+    const retries = once ? 0 : this.retry.retries;
+    const tried = /* @__PURE__ */ new Set();
+    for (; ; ) {
+      let unavailable;
+      let node = this.nodeUrl;
+      for (let attempt = 0; ; attempt++) {
+        node = this.nodeUrl;
+        tried.add(node);
+        try {
+          return await this.read(method, path, options);
+        } 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 (once || !this.failOver(node, tried)) throw unavailable;
+    }
+  }
+  /**
+   * One JSON request, retried as `options.retry` says. The confirmed attempt
+   * of a step-up (`body.confirm` set) goes out exactly once.
+   */
+  attempt(method, path, options) {
+    if (!options.retry) return this.read(method, path, options);
+    const confirming = options.body?.confirm !== void 0;
+    return this.retried(method, path, options, options.retry === "once" || confirming);
+  }
+  /**
+   * {@link attempt}, answering a `412 CONFIRM_REQUIRED` with `passkey`'s
+   * assertion over the node's challenge: the same body again, with `confirm`.
+   * Without a passkey the `412` reaches the caller as {@link ConfirmRequired}.
+   */
+  async confirmed(method, path, options) {
+    const { passkey } = options;
+    const signal = options.promptSignal ?? options.signal;
+    try {
+      return await this.attempt(method, path, options);
+    } catch (error) {
+      if (!(error instanceof ConfirmRequired) || !passkey) throw error;
+      const d = error.details;
+      let assertion;
+      try {
+        assertion = await passkey.get(fromB64url(d.challenge), d.rpId, d.allowCredentials, {
+          userVerification: userVerificationOf(d.userVerification, options.userVerification ?? "required"),
+          ...signal ? { signal } : {}
+        });
+      } catch (declined) {
+        throw promptFailure(declined);
+      }
+      const body = { ...options.body, confirm: { challengeId: d.challengeId, assertion } };
+      return this.attempt(method, path, { ...options, body });
+    }
+  }
+  request(method, path, options = {}) {
+    return this.send(method, relative(path), options);
+  }
+  json(method, path, options = {}) {
+    return this.confirmed(method, relative(path), options);
+  }
+  async *events(path, options = {}) {
+    const response = await this.send("GET", relative(path), options);
+    if (!response.body) throw new CalimeroError(response.status, "EVENTS", "the event stream has no body");
+    yield* sseFrames(response.body);
+  }
+  /**
+   * `GET path` in the clear, from the node in use: only for the route a node
+   * serves unsealed (`attestation`), and never with the credential.
+   */
+  async unsealed(path, options = {}) {
+    const response = await this.raw(`${this.nodeUrl}/${relative(path)}${queryString(options.query)}`);
+    if (!response.ok) throw await refusal(response);
+    return response;
+  }
+  /**
+   * Swap the refresh token for a new session, on whichever node the transport
+   * uses: any node of the cluster takes it. A refresh token is used once, so
+   * requests 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.json("POST", "auth/refresh", { body: { 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 function directoryTransport(options) {
+  const random = options.random ?? Math.random;
+  const fetcher = options.fetch ?? ((input, init) => fetch(input, init));
+  const listing = await readDirectory(options.directory, options.cluster, fetcher);
+  const [baseUrl, ...nodes] = orderNodes(listing.nodes, options.zone, random);
+  const transport = new NodeTransport({ baseUrl, nodes, policy: options.policy, fetch: options.fetch, retry: options.retry });
+  transport.useDirectory({
+    directory: options.directory,
+    cluster: options.cluster,
+    zone: options.zone,
+    random,
+    due: Date.now() + listing.refreshAfterSeconds * 1e3
+  });
+  return transport;
+}
+
 // src/cloud-v2/recovery.ts
 var RECOVERY_DOMAIN = "calimero.org-recovery.v1\0";
 var MAX_RECOVERY_NONCE_BYTES = 64;
@@ -1808,12 +2252,16 @@ function pendingApprovalsFrom(report, rules, now = Date.now() / 1e3) {
   for (const a of report.apps) {
     const available = a.availableVersions ?? [];
     if (a.package === null || available.length === 0) continue;
+    const latest = available[available.length - 1];
+    const reachable = a.latestReachable === void 0 ? latest : a.latestReachable;
     upgrades.push({
       app: a.app,
       name: a.name ?? null,
       package: a.package.package,
       from: a.package.version,
-      to: available[available.length - 1],
+      to: reachable ?? latest,
+      reachable: reachable !== null,
+      blocked: a.latestBlocked ?? null,
       available,
       actionable: upgradesActionable
     });
@@ -1843,114 +2291,36 @@ function upgradeConsent(app, toVersion, returnTo) {
   return { kind: "upgrade", subject: { app, toVersion }, returnTo };
 }
 
-// src/cloud-v2/client.ts
-function deployerKey(deployer) {
-  return "account" in deployer ? `account:${deployer.account}` : `org:${deployer.org}`;
-}
-async function frontendManifest(origin, fetcher = fetch) {
-  const base = origin ?? globalThis.location?.origin;
-  if (!base) throw new Error("no page origin to read the frontend manifest from; pass `origin`");
-  const response = await fetcher(new URL("/.well-known/calimero.json", base).toString());
-  if (!response.ok) throw await refusal(response);
-  const manifest = await response.json();
-  return { ...manifest, deployments: manifest.deployments ?? [] };
-}
-function pageDeployment(href) {
-  const at = href ?? globalThis.location?.href;
-  if (!at) return null;
-  try {
-    return new URL(at).searchParams.get("deployment") || null;
-  } catch {
-    return null;
-  }
-}
-function userVerificationOf(named, fallback) {
-  return named === "required" || named === "preferred" || named === "discouraged" ? named : fallback;
-}
-function promptFailure(error) {
-  const e = error;
-  const name = e?.name;
-  const message = typeof e?.message === "string" ? e.message : "";
-  if (name === "InvalidStateError" || /not focused|already pending/i.test(message)) {
-    return new ConfirmPromptBlocked(error);
-  }
-  if (name === "NotAllowedError" || name === "AbortError") return new ConfirmCancelled(error);
-  return error;
-}
-function seg(value) {
-  return encodeURIComponent(value);
-}
-function sealedError(error) {
-  if (error instanceof SealedTransportError && error.status === 413) {
-    return errorFrom(413, {
-      error: "TOO_LARGE",
-      message: error.message.replace(/^Sealed request refused: /, "")
-    });
-  }
-  return error;
-}
-async function refusal(response) {
-  const text = await response.text().catch(() => "");
-  let body = {};
-  try {
-    body = text ? JSON.parse(text) : {};
-  } catch {
-    body = { message: text };
-  }
-  return errorFrom(response.status, body, response.headers.get("retry-after"));
-}
-async function* sseFrames(body) {
-  const reader = body.getReader();
-  const decoder = new TextDecoder();
-  let buffer = "";
-  for (; ; ) {
-    const { value, done } = await reader.read();
-    if (done) return;
-    buffer += decoder.decode(value, { stream: true });
-    let cut;
-    while ((cut = buffer.indexOf("\n\n")) >= 0) {
-      const frame = buffer.slice(0, cut);
-      buffer = buffer.slice(cut + 2);
-      let id = "";
-      let kind = "";
-      let data = "";
-      for (const line of frame.split("\n")) {
-        if (line.startsWith("id:")) id = line.slice(3).trim();
-        else if (line.startsWith("event:")) kind = line.slice(6).trim();
-        else if (line.startsWith("data:")) data += line.slice(5).trim();
-      }
-      if (!kind && !data) continue;
-      let parsed = data;
-      try {
-        parsed = JSON.parse(data);
-      } catch {
-      }
-      yield { id, kind, data: parsed };
-    }
-  }
+// src/cloud-v2/client.ts
+function deployerKey(deployer) {
+  return "account" in deployer ? `account:${deployer.account}` : `org:${deployer.org}`;
 }
-function toHex(bytes) {
-  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+async function frontendManifest(origin, fetcher = fetch) {
+  const base = origin ?? globalThis.location?.origin;
+  if (!base) throw new Error("no page origin to read the frontend manifest from; pass `origin`");
+  const response = await fetcher(new URL("/.well-known/calimero.json", base).toString());
+  if (!response.ok) throw await refusal(response);
+  const manifest = await response.json();
+  return { ...manifest, deployments: manifest.deployments ?? [] };
 }
-function newIdempotencyKey() {
-  return `node:c-${b64url(crypto.getRandomValues(new Uint8Array(16)))}`;
+function pageDeployment(href) {
+  const at = href ?? globalThis.location?.href;
+  if (!at) return null;
+  try {
+    return new URL(at).searchParams.get("deployment") || null;
+  } catch {
+    return null;
+  }
 }
-var DEFAULT_RETRY = { retries: 6, baseDelayMs: 200, maxDelayMs: 2e3 };
-function retryDelayMs(retry, options) {
-  return Math.min(options.baseDelayMs * 2 ** retry, options.maxDelayMs);
+function seg(value) {
+  return encodeURIComponent(value);
 }
-function ceremony(path) {
-  return path === "auth/refresh" || path.startsWith("auth/passkey/") || RECOVERY_CEREMONIES.has(path);
+function toHex(bytes) {
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
 }
-var RECOVERY_CEREMONIES = /* @__PURE__ */ new Set(["auth/recovery/begin", "auth/recovery/start", "auth/recovery/finish"]);
 var CalimeroClient = class _CalimeroClient {
+  /** A client of the nodes `options` names, or one sending through an existing `transport`. */
   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();
     // ---------------------------------------------------------------- package origins
     /**
      * The web origins `{package}`'s managers registered so a frontend they host
@@ -1976,20 +2346,7 @@ var CalimeroClient = class _CalimeroClient {
       ),
       remove: (pkg, origin, passkey) => this.confirmed("DELETE", `package-origins/${seg(pkg)}`, { origin }, passkey)
     };
-    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) => {
-      try {
-        return await given(input, init);
-      } catch (error) {
-        if (error instanceof TypeError) this.networkFailures.add(error);
-        throw error;
-      }
-    };
-    this.raw = raw;
+    this.transport = options instanceof NodeTransport ? options : new NodeTransport(options);
   }
   /**
    * A client for the Calimero Cloud cluster named `cluster`: its node list read
@@ -2002,219 +2359,31 @@ var CalimeroClient = class _CalimeroClient {
    * 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;
+    const transport = await directoryTransport({ ...options, directory: options.directory ?? DEFAULT_DIRECTORY });
+    return new _CalimeroClient(transport);
   }
   /** 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];
+    return this.transport.nodeUrl;
   }
   /** 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);
-    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.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;
-    });
+    return this.transport.nodes;
   }
   /** Authenticate every request with an API key. */
   useApiKey(key) {
-    this.auth = key;
-    this.current = void 0;
+    this.transport.useApiKey(key);
   }
   useSession(session) {
-    this.auth = session.sessionToken;
-    this.current = session;
+    this.transport.useSession(session);
   }
   get session() {
-    return this.current;
-  }
-  /**
-   * 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;
-    if (raw) {
-      headers["content-type"] = contentType;
-      payload = raw;
-    } else if (body !== void 0) {
-      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 });
-    } 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.nodeUrl];
-      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;
-    }
+    return this.transport.session;
   }
-  /** 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.send(method, path, body, raw, contentType);
-    const text = await response.text();
-    return text ? JSON.parse(text) : {};
-  }
-  /**
-   * {@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.
-   *
-   * 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'`.
-   *
-   * `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, once = false) {
-    const retries = once ? 0 : this.retry.retries;
-    const tried = /* @__PURE__ */ new Set();
-    for (; ; ) {
-      let unavailable;
-      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 (once || !this.failOver(node, tried)) throw unavailable;
-    }
+  /** A JSON request, or a raw one when `raw` is given (as `contentType`, the transport's default when absent). */
+  json(method, path, body, raw, contentType) {
+    const options = raw ? { bytes: raw, ...contentType === void 0 ? {} : { contentType } } : { body };
+    return this.transport.json(method, path, options);
   }
   post(path, body = {}) {
     return this.json("POST", path, body);
@@ -2258,7 +2427,6 @@ var CalimeroClient = class _CalimeroClient {
       "auth/passkey/register/finish",
       { challengeId: begin.challengeId, registration, ...invite },
       passkey,
-      void 0,
       "preferred",
       signal
     );
@@ -2299,7 +2467,7 @@ var CalimeroClient = class _CalimeroClient {
     const page = globalThis.location?.origin;
     if (!page || page === "null") return void 0;
     const nodes = new Set(
-      this.nodeUrls.map((url2) => {
+      this.transport.nodes.map((url2) => {
         try {
           return new URL(url2).origin;
         } catch {
@@ -2327,29 +2495,7 @@ var CalimeroClient = class _CalimeroClient {
    * 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;
+    return this.transport.refresh();
   }
   /**
    * End this session. The client is signed out whether or not the node
@@ -2409,8 +2555,7 @@ var CalimeroClient = class _CalimeroClient {
     try {
       await this.post(path);
     } finally {
-      this.auth = void 0;
-      this.current = void 0;
+      this.transport.signOut();
     }
   }
   /** Who the credential is: the account, how it signed in, and the package (`app`) and `origin` a session is bound to. */
@@ -2516,8 +2661,7 @@ var CalimeroClient = class _CalimeroClient {
    */
   async attestation() {
     const nonce2 = toHex(crypto.getRandomValues(new Uint8Array(32)));
-    const response = await this.raw(`${this.nodeUrl}/attestation?nonce=${nonce2}`);
-    if (!response.ok) throw await refusal(response);
+    const response = await this.transport.unsealed("attestation", { query: { nonce: nonce2 } });
     return await response.json();
   }
   /** The account's API keys (never the keys themselves). */
@@ -2578,8 +2722,9 @@ var CalimeroClient = class _CalimeroClient {
    * app; `application/octet-stream` otherwise.
    */
   async blobContent(app, id, options = {}) {
-    const query = options.grant === void 0 ? "" : `?grant=${encodeURIComponent(options.grant)}`;
-    const response = await this.send("GET", `apps/${seg(app)}/blobs/${seg(id)}${query}`);
+    const response = await this.transport.request("GET", `apps/${seg(app)}/blobs/${seg(id)}`, {
+      query: { grant: options.grant }
+    });
     return {
       data: new Uint8Array(await response.arrayBuffer()),
       contentType: response.headers.get("content-type") ?? "application/octet-stream"
@@ -2690,8 +2835,10 @@ var CalimeroClient = class _CalimeroClient {
   }
   /**
    * Move an app to another release of its package (`{ version }`), another
-   * package, or a bundle hash, running its migration. Answers the upgrade's
-   * entry; a failed migration rejects with code `UPGRADE_FAILED` (422).
+   * package, or a bundle hash. An upgrade is code only: the app moves to any
+   * newer release in one step. Answers the upgrade's entry; one the app's
+   * group refuses rejects with code `UPGRADE_FAILED` (422), and one a
+   * replica's node is too old to run with {@link RuntimeTooOld} (409).
    * Where owners hold app upgrades, the node asks for the approval of
    * whoever the package's manifest names (`412 CONFIRM_REQUIRED`), which
    * `passkey` gives. Refused (`403`) to a session opened on an app's
@@ -2722,23 +2869,12 @@ var CalimeroClient = class _CalimeroClient {
   deleteConfirmed(path, passkey, body = {}) {
     return this.confirmed("DELETE", path, body, passkey);
   }
-  async confirmed(method, path, body, passkey, send = (b) => this.json(method, path, b), userVerification = "required", signal) {
-    try {
-      return await send(body);
-    } catch (error) {
-      if (!(error instanceof ConfirmRequired) || !passkey) throw error;
-      const d = error.details;
-      let assertion;
-      try {
-        assertion = await passkey.get(fromB64url(d.challenge), d.rpId, d.allowCredentials, {
-          userVerification: userVerificationOf(d.userVerification, userVerification),
-          ...signal ? { signal } : {}
-        });
-      } catch (declined) {
-        throw promptFailure(declined);
-      }
-      return send({ ...body, confirm: { challengeId: d.challengeId, assertion } });
-    }
+  /**
+   * `body` to `path`, answering a `412 CONFIRM_REQUIRED` with `passkey` when one
+   * is given; `signal` aborts only the passkey prompt.
+   */
+  confirmed(method, path, body, passkey, userVerification, signal) {
+    return this.transport.json(method, path, { body, passkey, userVerification, promptSignal: signal });
   }
   /**
    * Create an app instance from a bundle hash, or from a package release
@@ -2762,7 +2898,7 @@ var CalimeroClient = class _CalimeroClient {
    */
   call(app, method, args = {}, idempotencyKey) {
     const key = idempotencyKey ?? newIdempotencyKey();
-    return this.retried("POST", `apps/${seg(app)}/intents`, { method, args, idempotencyKey: key });
+    return this.transport.json("POST", `apps/${seg(app)}/intents`, { body: { method, args, idempotencyKey: key }, retry: true });
   }
   /**
    * Call a method that needs the account holder's approval: the node returns a
@@ -2772,32 +2908,23 @@ var CalimeroClient = class _CalimeroClient {
   async callConfirmed(app, method, args, passkey, idempotencyKey) {
     const path = `apps/${seg(app)}/intents`;
     const key = idempotencyKey ?? newIdempotencyKey();
-    return this.confirmed(
-      "POST",
-      path,
-      { method, args, idempotencyKey: key },
-      passkey,
-      (body) => this.retried("POST", path, body, body.confirm !== void 0)
-    );
+    return this.transport.json("POST", path, { body: { method, args, idempotencyKey: key }, passkey, retry: true });
   }
   /** Run a read-only method: strong by default, or stale from any replica. */
   view(app, method, args = {}, options = {}) {
-    return this.retried("POST", `apps/${seg(app)}/views`, {
-      method,
-      args,
-      consistency: options.stale ? "stale" : "strong",
-      minIndex: options.minIndex ?? 0
+    return this.transport.json("POST", `apps/${seg(app)}/views`, {
+      body: {
+        method,
+        args,
+        consistency: options.stale ? "stale" : "strong",
+        minIndex: options.minIndex ?? 0
+      },
+      retry: true
     });
   }
   /** Committed events from index `from`, then live, until `signal` aborts. */
   events(app, from = 0, signal) {
-    return this.stream(`apps/${seg(app)}/events?from=${from}`, signal);
-  }
-  /** A server-sent event stream on `path`, sealed like every other answer. */
-  async *stream(path, signal) {
-    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);
+    return this.transport.events(`apps/${seg(app)}/events`, { query: { from }, signal });
   }
   // ---------------------------------------------------------------- presence
   /**
@@ -2818,7 +2945,7 @@ var CalimeroClient = class _CalimeroClient {
    * entries present), then a `presence` event (`data` one entry) per change.
    */
   presenceStream(app, signal) {
-    return this.stream(`apps/${seg(app)}/presence/stream`, signal);
+    return this.transport.events(`apps/${seg(app)}/presence/stream`, { signal });
   }
   // ---------------------------------------------------------------- aliases
   /** Name an app (its id or context id) for this account. */
@@ -3833,6 +3960,7 @@ export {
   DEFAULT_DIRECTORY,
   DEFAULT_ORG_CAPABILITIES,
   DEFAULT_RELEASE_MIRROR,
+  DEFAULT_RETRY,
   DirectoryError,
   GITHUB_RELEASES,
   HANDSHAKE_PATH,
@@ -3843,6 +3971,7 @@ export {
   MAX_REPORT_PAGE,
   MOCK_QUOTE_HEADER,
   NODE_RELEASE_SIGNER,
+  NodeTransport,
   NotFound,
   NotServing,
   ORG_CAPABILITIES,
@@ -3855,6 +3984,7 @@ export {
   RELEASE_VERIFIER,
   RecoveryNotReady,
   ReleaseDeadlineError,
+  RuntimeTooOld,
   SEALED_CONTENT_TYPE,
   SEALED_PATH,
   SealedTransportError,
@@ -3879,6 +4009,7 @@ export {
   createSealedFetch,
   createSignedReleaseVerifier,
   deployerKey,
+  directoryTransport,
   errorFrom,
   fetchAttestedKey,
   fetchGithubNodeRelease,
@@ -3887,6 +4018,7 @@ export {
   fromB64url,
   frontendManifest,
   generateOwnerKey,
+  newIdempotencyKey,
   newRecoverySeed,
   orgCapabilities,
   ownerPublicKey,
@@ -3898,13 +4030,18 @@ export {
   provisionInfo,
   publisherBindingBytes,
   publisherBindingMessage,
+  queryString,
   recoveryMessage,
   recoveryPublicKey,
   recoverySeedText,
+  refusal,
   releaseAgent,
   releaseConsent,
   releaseNotesUrl,
+  retryDelayMs,
+  routePath,
   signRecovery,
+  sseFrames,
   stalledBy,
   transportKeyBinding,
   trustSignedRelease,