@calimero-network/mero-js 27.1.0 → 27.2.0

package/README.md

@@ -79,10 +79,13 @@ Pinned measurements go through `policy.verifyQuote` (`createQuoteVerifier`).
 - **Operator** (ops token): `opsApps`, `opsOrgs`, `setReleaseDeadline`, `liftReleaseDeadline`.
 - **Any route**: `get`, `post`, `put`, `delete`; `postConfirmed` and `deleteConfirmed` answer a `412 CONFIRM_REQUIRED` with a passkey.
 
-Refusals are typed (`LoginRequired`, `NotFound`, `ConfirmRequired`, `ConfirmCancelled`,
+Refusals are typed (`LoginRequired`, `WrongNode`, `NotFound`, `ConfirmRequired`, `ConfirmCancelled`,
 `ArgsTooLarge`, `IdempotencyMismatch`, `ReleaseDeadlineError`, `ConsentStale`, `AppError`, `TrapError`,
 `UnavailableError`),
-all extending `CalimeroError` with the node's `status` and `code`. See the
+all extending `CalimeroError` with the node's `status` and `code`. A `401` once
+the node that issued the session is replaced or out of reach is answered by one
+refresh and a repeat; a `421 WRONG_NODE` by moving to the next of the `nodes` the client was
+given. See the
 [error model](https://calimero-network.github.io/mero-js/reference/error-model/).
 
 The pieces it is built from are exported too: the sealed transport

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

@@ -12,7 +12,7 @@
 import { type AttestationDoc, type CloudPolicy } from './attestation.js';
 import { type PasskeyProvider } from './passkey.js';
 import { type AppsReport, type ConsentRequest, type ConsentResult, type ConsentStarted, type OpsAppsReport, type OpsOrgsReport, type PageOptions, type PendingApprovals, type PublisherBindingInfo, type PublisherProof, type ReleaseRules } from './approvals.js';
-export { AppError, ArgsTooLarge, CalimeroError, ConfirmCancelled, ConfirmRequired, IdempotencyMismatch, LoginRequired, ConsentStale, NotFound, ReleaseDeadlineError, TrapError, UnavailableError, errorFrom, } from './errors.js';
+export { AppError, ArgsTooLarge, CalimeroError, ConfirmCancelled, ConfirmRequired, IdempotencyMismatch, LoginRequired, ConsentStale, NotFound, ReleaseDeadlineError, TrapError, UnavailableError, WrongNode, errorFrom, } from './errors.js';
 export type { Committed } from './errors.js';
 export interface CalimeroSession {
     accountId: string;
@@ -156,8 +156,15 @@ export declare function retryDelayMs(retry: number, options: {
     maxDelayMs: number;
 }): number;
 export interface CalimeroClientOptions {
-    /** One node of the cluster. */
+    /** One node of the cluster: the one the client talks to first. */
     baseUrl: string;
+    /**
+     * Other nodes of the same cluster, in the order to move to them when a node
+     * answers `421 WRONG_NODE` (its release may not serve this account). Each is
+     * attested under the same `policy` before anything is sent to it. Without
+     * them a `421` reaches the caller as {@link WrongNode}.
+     */
+    nodes?: string[];
     policy: CloudPolicy;
     /** Fetch that carries attestation and envelopes. Defaults to global `fetch`. */
     fetch?: typeof fetch;
@@ -165,21 +172,70 @@ export interface CalimeroClientOptions {
     retry?: CloudRetryOptions;
 }
 export declare class CalimeroClient {
-    private readonly base;
-    private readonly sealed;
+    /** Every node this client may use, `baseUrl` first. */
+    private readonly nodeUrls;
+    /** The one in use: an index into {@link nodeUrls}. */
+    private at;
+    /** A sealed fetch per node, each attesting its own node on first use. */
+    private readonly channels;
+    private readonly policy;
     /** The unsealed fetch, for the one route served in the clear (`/attestation`). */
     private readonly raw;
     private auth;
     private current;
+    /** The refresh under way, which every request that needs one shares. */
+    private refreshing;
     private readonly retry;
     /** Rejections of the underlying `fetch` itself: the node could not be reached or dropped the connection. */
     private readonly networkFailures;
     constructor(options: CalimeroClientOptions);
+    /** The node requests go to now: `baseUrl`, until a `421 WRONG_NODE` moved the client on. */
+    get nodeUrl(): string;
+    /** The sealed channel to `url`, attested under the client's policy before its first request. */
+    private channel;
+    /**
+     * 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.
+     */
+    private moveOn;
     /** Authenticate every request with an API key. */
     useApiKey(key: string): void;
     useSession(session: CalimeroSession): void;
     get session(): CalimeroSession | undefined;
+    /**
+     * Send one request to the node in use, with the credential held now, and
+     * answer the response, whatever its status. {@link send} judges it.
+     */
     private request;
+    /**
+     * {@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.
+     */
+    private send;
+    /** Whether a `401` to a request sent with `token` is one a refresh may answer. */
+    private mayRefresh;
+    /**
+     * A fresh session in place of the one `token` belonged to: by the refresh
+     * another request already made, or by one this request starts.
+     */
+    private renew;
     private json;
     /**
      * {@link json} for a call or a view (D70): while the node answers 503 or
@@ -199,8 +255,14 @@ export declare class CalimeroClient {
     signUp(passkey: PasskeyProvider, name: string): Promise<CalimeroSession>;
     /** Sign in with an existing passkey. */
     signIn(passkey: PasskeyProvider): Promise<CalimeroSession>;
-    /** Swap the refresh token for a new 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(): Promise<CalimeroSession>;
+    private exchangeRefresh;
     signOut(): Promise<void>;
     /** End every session of the signed-in account, on every device, this one too. */
     signOutEverywhere(): Promise<void>;

package/dist/cloud-v2/client.js

@@ -11,10 +11,10 @@
  */
 import { SealedTransportError, createSealedFetch } from '../sealed/sealed.js';
 import { fetchAttestedKey } from './attestation.js';
-import { CalimeroError, ConfirmCancelled, ConfirmRequired, UnavailableError, errorFrom } from './errors.js';
+import { CalimeroError, ConfirmCancelled, ConfirmRequired, LoginRequired, UnavailableError, WrongNode, errorFrom, } from './errors.js';
 import { b64url, fromB64url } from './passkey.js';
 import { pageQuery, pendingApprovalsFrom, } from './approvals.js';
-export { AppError, ArgsTooLarge, CalimeroError, ConfirmCancelled, ConfirmRequired, IdempotencyMismatch, LoginRequired, ConsentStale, NotFound, ReleaseDeadlineError, TrapError, UnavailableError, errorFrom, } from './errors.js';
+export { AppError, ArgsTooLarge, CalimeroError, ConfirmCancelled, ConfirmRequired, IdempotencyMismatch, LoginRequired, ConsentStale, NotFound, ReleaseDeadlineError, TrapError, UnavailableError, WrongNode, errorFrom, } from './errors.js';
 /** One URL path segment, so an id cannot reach another route. */
 function seg(value) {
     return encodeURIComponent(value);
@@ -103,11 +103,27 @@ export const DEFAULT_RETRY = { retries: 6, baseDelayMs: 200, maxDelayMs: 2000 };
 export function retryDelayMs(retry, options) {
     return Math.min(options.baseDelayMs * 2 ** retry, options.maxDelayMs);
 }
+/**
+ * The ceremonies that mint a session, which {@link CalimeroClient.send} never
+ * repeats by itself: a sign-in or sign-up is started again by its caller (with
+ * the passkey), and a refresh moves through the nodes in
+ * {@link CalimeroClient.exchangeRefresh}. A node answers them `421 WRONG_NODE`
+ * before it spends the challenge or the refresh token (core #4774).
+ */
+function ceremony(path) {
+    return path === 'auth/refresh' || path.startsWith('auth/passkey/');
+}
 export class CalimeroClient {
     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 = new Map();
         /** Rejections of the underlying `fetch` itself: the node could not be reached or dropped the connection. */
         this.networkFailures = new WeakSet();
-        this.base = options.baseUrl.replace(/\/+$/, '');
+        const trim = (url) => url.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));
         // `fetch` rejects with a `TypeError` when it gets no answer: the connection
@@ -125,11 +141,35 @@ export class CalimeroClient {
             }
         };
         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(url) {
+        let sealed = this.channels.get(url);
+        if (!sealed) {
+            sealed = createSealedFetch({
+                baseUrl: url,
+                transportPublicKey: () => fetchAttestedKey(url, this.policy, this.raw),
+                fetch: this.raw,
+            });
+            this.channels.set(url, 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) {
@@ -143,7 +183,11 @@ export class CalimeroClient {
     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}`;
@@ -156,17 +200,71 @@ export class CalimeroClient {
             headers['content-type'] = 'application/json';
             payload = JSON.stringify(body);
         }
+        const url = this.nodeUrl;
         try {
-            return await this.sealed(`${this.base}/${path}`, { method, headers, body: payload });
+            return await this.channel(url)(`${url}/${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 !== undefined && this.current !== undefined && !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) : {});
     }
@@ -235,12 +333,44 @@ export class CalimeroClient {
         this.useSession(session);
         return session;
     }
-    /** Swap the refresh token for a new session. */
-    async refresh() {
-        if (!this.current)
+    /**
+     * 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 = undefined;
+            };
+            pending.then(clear, clear);
+        }
+        return this.refreshing;
+    }
+    async exchangeRefresh() {
+        const current = this.current;
+        if (!current)
             throw new Error('no session to refresh');
-        const session = await this.post('auth/refresh', { refreshToken: this.current.refreshToken });
-        this.useSession(session);
+        let session;
+        // A node that may not serve the account answers `421 WRONG_NODE` before it
+        // spends the refresh token (core #4774), so the same token goes to the next
+        // node (`send` moved there already): once per node, at most.
+        for (let tried = 1; session === undefined; tried++) {
+            try {
+                session = await this.post('auth/refresh', { refreshToken: current.refreshToken });
+            }
+            catch (error) {
+                if (!(error instanceof WrongNode) || tried >= this.nodeUrls.length)
+                    throw error;
+            }
+        }
+        // A sign-in or another session taken while this one was refreshing wins.
+        if (this.current === current)
+            this.useSession(session);
         return session;
     }
     async signOut() {
@@ -285,7 +415,7 @@ export class CalimeroClient {
      */
     async attestation() {
         const nonce = toHex(crypto.getRandomValues(new Uint8Array(32)));
-        const response = await this.raw(`${this.base}/attestation?nonce=${nonce}`);
+        const response = await this.raw(`${this.nodeUrl}/attestation?nonce=${nonce}`);
         if (!response.ok)
             throw await refusal(response);
         return (await response.json());
@@ -314,9 +444,7 @@ export class CalimeroClient {
     }
     /** 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. */
@@ -489,12 +617,7 @@ export class CalimeroClient {
     }
     /** 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, undefined, undefined, undefined, signal);
         if (!response.body)
             throw new CalimeroError(response.status, 'EVENTS', 'the event stream has no body');
         yield* sseFrames(response.body);

package/dist/cloud-v2/errors.d.ts

@@ -19,10 +19,35 @@ export declare class CalimeroError extends Error {
     readonly details: Record<string, unknown>;
     constructor(status: number, code: string, message: string, details?: Record<string, unknown>);
 }
-/** `401 UNAUTHENTICATED`: sign in (again) and repeat the request. */
+/**
+ * `401 UNAUTHENTICATED` that refreshing could not answer: sign in (again) and
+ * repeat the request.
+ *
+ * A session token is signed by the node that issued it, and other nodes take
+ * it only while they can vouch for that node's signing key: a `401` often
+ * means only that the issuer was replaced or cannot be reached, not that the
+ * user signed out. The client answers that itself when it holds a refresh
+ * token: it refreshes once (any node takes the refresh) and repeats the
+ * request. This error reaches a caller when there is no refresh token (an API
+ * key, say), or the refresh was refused.
+ */
 export declare class LoginRequired extends CalimeroError {
     constructor(message: string, details?: Record<string, unknown>);
 }
+/**
+ * `421 WRONG_NODE`: this node runs a mero-tee release the account's owners have
+ * not approved, so it neither issues nor takes the account's sessions. Use
+ * another node of the cluster; refreshing here would not help.
+ *
+ * The client moves to the next node it was given (`nodes`) and repeats the
+ * request once by itself (a refresh: once per node). This error reaches a
+ * caller when it knows no other node, when the next one refused too (for a
+ * refresh, every node), or after a sign-in (which needs the passkey again:
+ * repeat it, and it goes to the next node).
+ */
+export declare class WrongNode extends CalimeroError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
 /**
  * `404 NOT_FOUND`: what the request names does not exist for this caller. For
  * an app this does not say whether it exists: an account the app does not

package/dist/cloud-v2/errors.js

@@ -22,13 +22,41 @@ export class CalimeroError extends Error {
         this.name = 'CalimeroError';
     }
 }
-/** `401 UNAUTHENTICATED`: sign in (again) and repeat the request. */
+/**
+ * `401 UNAUTHENTICATED` that refreshing could not answer: sign in (again) and
+ * repeat the request.
+ *
+ * A session token is signed by the node that issued it, and other nodes take
+ * it only while they can vouch for that node's signing key: a `401` often
+ * means only that the issuer was replaced or cannot be reached, not that the
+ * user signed out. The client answers that itself when it holds a refresh
+ * token: it refreshes once (any node takes the refresh) and repeats the
+ * request. This error reaches a caller when there is no refresh token (an API
+ * key, say), or the refresh was refused.
+ */
 export class LoginRequired extends CalimeroError {
     constructor(message, details = {}) {
         super(401, 'UNAUTHENTICATED', message, details);
         this.name = 'LoginRequired';
     }
 }
+/**
+ * `421 WRONG_NODE`: this node runs a mero-tee release the account's owners have
+ * not approved, so it neither issues nor takes the account's sessions. Use
+ * another node of the cluster; refreshing here would not help.
+ *
+ * The client moves to the next node it was given (`nodes`) and repeats the
+ * request once by itself (a refresh: once per node). This error reaches a
+ * caller when it knows no other node, when the next one refused too (for a
+ * refresh, every node), or after a sign-in (which needs the passkey again:
+ * repeat it, and it goes to the next node).
+ */
+export class WrongNode extends CalimeroError {
+    constructor(message, details = {}) {
+        super(421, 'WRONG_NODE', message, details);
+        this.name = 'WrongNode';
+    }
+}
 /**
  * `404 NOT_FOUND`: what the request names does not exist for this caller. For
  * an app this does not say whether it exists: an account the app does not
@@ -174,6 +202,8 @@ export 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':

package/dist/cloud-v2/index.d.ts

@@ -1,5 +1,5 @@
 export { CalimeroClient } from './client.js';
-export { AppError, ArgsTooLarge, CalimeroError, ConfirmCancelled, ConfirmRequired, IdempotencyMismatch, LoginRequired, ConsentStale, NotFound, ReleaseDeadlineError, TrapError, UnavailableError, errorFrom, } from './errors.js';
+export { AppError, ArgsTooLarge, CalimeroError, ConfirmCancelled, ConfirmRequired, IdempotencyMismatch, LoginRequired, ConsentStale, NotFound, ReleaseDeadlineError, TrapError, UnavailableError, WrongNode, errorFrom, } from './errors.js';
 export type { Committed } from './errors.js';
 export type { AppInfo, BlobInfo, CallResult, CalimeroClientOptions, CloudEvent, CalimeroSession, PackageInfo, PackageInstalled, CloudRetryOptions, OrgInfo, OrgUpgradeTarget, PresenceEntry, UpgradeRun, ViewResult, } from './client.js';
 export { claimedRelease, fetchAttestedKey, MOCK_QUOTE_HEADER } from './attestation.js';

package/dist/cloud-v2/index.js

@@ -1,5 +1,5 @@
 export { CalimeroClient } from './client.js';
-export { AppError, ArgsTooLarge, CalimeroError, ConfirmCancelled, ConfirmRequired, IdempotencyMismatch, LoginRequired, ConsentStale, NotFound, ReleaseDeadlineError, TrapError, UnavailableError, errorFrom, } from './errors.js';
+export { AppError, ArgsTooLarge, CalimeroError, ConfirmCancelled, ConfirmRequired, IdempotencyMismatch, LoginRequired, ConsentStale, NotFound, ReleaseDeadlineError, TrapError, UnavailableError, WrongNode, errorFrom, } from './errors.js';
 export { claimedRelease, fetchAttestedKey, MOCK_QUOTE_HEADER } from './attestation.js';
 export { browserPasskey, b64url, fromB64url } from './passkey.js';
 export { MAX_REPORT_PAGE, RELEASE_VERIFIER, compareVersions, consentReturn, pageQuery, pendingApprovalsFrom, publisherBindingBytes, publisherBindingMessage, releaseConsent, releaseNotesUrl, stalledBy, upgradeConsent, verifyReleaseUrl, withdrawConsent, } from './approvals.js';