@calimero-network/mero-js 27.1.0 → 27.3.0

package/README.md

@@ -75,14 +75,17 @@ Pinned measurements go through `policy.verifyQuote` (`createQuoteVerifier`).
 - **Blobs and presence**: `uploadBlob`, `downloadBlob`, `listBlobs`, `blobInfo`, `deleteBlob`; `publishPresence`, `presence`, `presenceStream`.
 - **Organizations**: `createOrg`, `getOrg`, `deleteOrg`, `setOrgMetadata`, `setMember`, `removeMember`, `setMemberMetadata`, `setCapabilities` (`ORG_CAPABILITIES`), teams, `invite`, `redeemInvite`.
 - **Owner decisions** (passkey approval, never from an app's frontend): `upgradeOrg`, `upgradeRun`, `retryUpgradeRun`, `approveRelease`, `approveOutbound`, `bindPublisher`, `upgradePublished`.
-- **Approvals from an app**: `appsReport`, `releaseRules`, `pendingApprovals`, then `requestConsent` / `openConsentPage` to send the user to the node's consent page, and `consentResult`. See [Ask your users to approve node images and app upgrades](https://calimero-network.github.io/mero-js/guides/user-approvals/).
+- **Approvals from an app**: `appsReport`, `releaseRules`, `pendingApprovals`, then `requestConsent` / `openConsentPage` to send the user to the node's consent page, and `consentResult`. Show the answer's `code` to the user before sending them to `url` (`openConsentPage`'s `confirm` hook); they should see the same code on the page (`confirmationCode(requestId)` checks it). See [Ask your users to approve node images and app upgrades](https://calimero-network.github.io/mero-js/guides/user-approvals/).
 - **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/approvals.d.ts

@@ -234,7 +234,34 @@ export interface ConsentStarted {
     url: string;
     /** Unix seconds; a request lives 10 minutes. */
     expiresAt: number;
+    /**
+     * The confirmation code the consent page shows, `XXX-XXX`
+     * ({@link confirmationCode} of `requestId`). Show it to the person before
+     * sending them to `url`: the page they land on should show the same code,
+     * which tells them it is the page their request opened. Not a secret.
+     * Nodes older than the code leave it out.
+     */
+    code?: string;
 }
+/** How {@link CalimeroClient.openConsentPage} sends the person to the page. */
+export interface OpenConsentOptions {
+    /** Sends the browser to the page's `url`; by default `window.location.assign`. */
+    navigate?: (url: string) => void;
+    /**
+     * Runs after the node answers and before navigating, with the answer: show
+     * the person `started.code` here so they can check the page shows the same.
+     * Answer `false` and the page is not opened (the request stays on the node
+     * until it expires).
+     */
+    confirm?: (started: ConsentStarted) => boolean | Promise<boolean>;
+}
+/**
+ * The confirmation code the node's consent page shows for `requestId`: the
+ * first 30 bits of SHA-256 of its UTF-8 bytes, big-endian, as six Crockford
+ * base32 characters written `XXX-XXX` (core's consent page). Compare it with
+ * {@link ConsentStarted.code} to check the node's answer.
+ */
+export declare function confirmationCode(requestId: string): Promise<string>;
 export type ConsentStatus = 'pending' | 'approved' | 'declined';
 /** `GET /consent/{id}/result`. */
 export interface ConsentResult {

package/dist/cloud-v2/approvals.js

@@ -74,6 +74,24 @@ export function publisherBindingMessage(cluster, org, signerId, generation) {
 export function publisherBindingBytes(cluster, org, signerId, generation) {
     return new TextEncoder().encode(publisherBindingMessage(cluster, org, signerId, generation));
 }
+const CROCKFORD = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+/**
+ * The confirmation code the node's consent page shows for `requestId`: the
+ * first 30 bits of SHA-256 of its UTF-8 bytes, big-endian, as six Crockford
+ * base32 characters written `XXX-XXX` (core's consent page). Compare it with
+ * {@link ConsentStarted.code} to check the node's answer.
+ */
+export 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;
+}
 /**
  * What the consent page put on `returnTo` when it sent the person back, or
  * `null` when `href` carries none. A hint only (anyone can type a URL): confirm

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

@@ -11,8 +11,8 @@
  */
 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';
+import { type AppsReport, type ConsentRequest, type ConsentResult, type ConsentStarted, type OpenConsentOptions, 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, 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>;
@@ -443,11 +505,16 @@ export declare class CalimeroClient {
     requestConsent(request: ConsentRequest): Promise<ConsentStarted>;
     /**
      * {@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}.
      */
-    openConsentPage(request: ConsentRequest, navigate?: (url: string) => void): Promise<ConsentStarted>;
+    openConsentPage(request: ConsentRequest, navigateOrOptions?: ((url: string) => void) | OpenConsentOptions): Promise<ConsentStarted>;
     /** The decision on a consent request (any node answers, for the account that asked). */
     consentResult(requestId: string): Promise<ConsentResult>;
     /**

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';
+import { confirmationCode, pageQuery, pendingApprovalsFrom, } from './approvals.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);
@@ -658,17 +781,37 @@ export class CalimeroClient {
     }
     /**
      * {@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 = (url) => {
-        const w = globalThis.window;
-        if (!w)
-            throw new Error('no window to open the consent page in; pass `navigate`');
-        w.location.assign(url);
-    }) {
+    async openConsentPage(request, navigateOrOptions = {}) {
+        const options = typeof navigateOrOptions === 'function' ? { navigate: navigateOrOptions } : navigateOrOptions;
+        const navigate = options.navigate ??
+            ((url) => {
+                const w = globalThis.window;
+                if (!w)
+                    throw new Error('no window to open the consent page in; pass `navigate`');
+                w.location.assign(url);
+            });
         const started = await this.requestConsent(request);
+        if (started.code !== undefined) {
+            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;
     }

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,12 +1,12 @@
 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';
 export type { AttestationDoc, CloudPolicy, CloudReleasePolicy } from './attestation.js';
 export { browserPasskey, b64url, fromB64url } from './passkey.js';
 export type { AssertionJSON, PasskeyProvider, RegistrationJSON } from './passkey.js';
-export { MAX_REPORT_PAGE, RELEASE_VERIFIER, compareVersions, consentReturn, pageQuery, pendingApprovalsFrom, publisherBindingBytes, publisherBindingMessage, releaseConsent, releaseNotesUrl, stalledBy, upgradeConsent, verifyReleaseUrl, withdrawConsent, } from './approvals.js';
-export type { ActorKind, AppsReport, Authority, ClusterRelease, ConsentReleaseModel, ConsentRequest, ConsentResult, ConsentScope, ConsentStarted, ConsentStatus, Governance, LastUpgrade, OpsAppsReport, OpsOrgsReport, PageOptions, PendingApprovals, PendingRelease, PendingUpgrade, PublisherBindingInfo, PublisherProof, ReleaseDeadline, ReleaseRules, ReportScope, ReportedApp, ReportedBundle, ReportedRelease, ReportedReplica, UpgradeAuthority, } from './approvals.js';
+export { MAX_REPORT_PAGE, RELEASE_VERIFIER, compareVersions, confirmationCode, consentReturn, pageQuery, pendingApprovalsFrom, publisherBindingBytes, publisherBindingMessage, releaseConsent, releaseNotesUrl, stalledBy, upgradeConsent, verifyReleaseUrl, withdrawConsent, } from './approvals.js';
+export type { ActorKind, AppsReport, Authority, ClusterRelease, ConsentReleaseModel, ConsentRequest, ConsentResult, ConsentScope, ConsentStarted, ConsentStatus, OpenConsentOptions, Governance, LastUpgrade, OpsAppsReport, OpsOrgsReport, PageOptions, PendingApprovals, PendingRelease, PendingUpgrade, PublisherBindingInfo, PublisherProof, ReleaseDeadline, ReleaseRules, ReportScope, ReportedApp, ReportedBundle, ReportedRelease, ReportedReplica, UpgradeAuthority, } from './approvals.js';
 export { DEFAULT_ORG_CAPABILITIES, ORG_CAPABILITIES, orgCapabilities } from './capabilities.js';
 export type { OrgCapability } from './capabilities.js';

package/dist/cloud-v2/index.js

@@ -1,6 +1,6 @@
 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';
+export { MAX_REPORT_PAGE, RELEASE_VERIFIER, compareVersions, confirmationCode, consentReturn, pageQuery, pendingApprovalsFrom, publisherBindingBytes, publisherBindingMessage, releaseConsent, releaseNotesUrl, stalledBy, upgradeConsent, verifyReleaseUrl, withdrawConsent, } from './approvals.js';
 export { DEFAULT_ORG_CAPABILITIES, ORG_CAPABILITIES, orgCapabilities } from './capabilities.js';