@calimero-network/mero-js 27.4.0 → 28.0.0

package/README.md

@@ -31,8 +31,9 @@ quotes and is loaded on first use.
 ```ts
 import { CalimeroClient, browserPasskey } from '@calimero-network/mero-js';
 
-const client = new CalimeroClient({
-  baseUrl: 'https://eu1.cloud.calimero.network',
+// Reach a Calimero Cloud cluster by name.
+const client = await CalimeroClient.connect({
+  cluster: 'eu-shared-1',
   // Trust the signed mero-tee release the node names, from this one up.
   policy: { release: { minReleaseVersion: '2.3.109' } },
 });
@@ -52,6 +53,34 @@ A development cluster (`merod local`, `merod run --dev`) sends mock quotes,
 which pass only with `policy: { allowMock: true }`. Nothing is read from the
 environment.
 
+## Connecting to a cluster
+
+`CalimeroClient.connect({ cluster, policy })` is the recommended way to reach a
+Calimero Cloud cluster. It reads the cluster's nodes from the public node
+directory (`DEFAULT_DIRECTORY`, `https://manager.cloud.calimero.network/api/v2/directory`;
+`directory` names another), puts those in `zone` first when you give one, and
+orders each group at random, weighted by the directory's weight. A cluster the
+directory does not know, or one with no usable node, throws `DirectoryError`.
+
+The directory only picks which nodes to try, and in what order. It is not
+trusted: every node is attested under **your** `policy` before anything is
+sent to it, so a wrong or tampered list can only make connecting fail.
+
+Any node of a cluster serves any request. While the node in use answers `503`
+or cannot be reached, a call or a view is retried there (`retry`); when those
+retries run out it fails over to the next node and starts them again there,
+with the **same** idempotency key, which the app's replicated log answers once
+cluster-wide. Each node is tried once per request; when all have failed, the
+last `UnavailableError` reaches you. After a failover, and once the directory's
+`refreshAfterSeconds` has passed (checked at the next request), the client
+reads the directory again in the background: the node in use stays first,
+nodes no longer listed are dropped. `client.nodeUrl` is the node in use,
+`client.nodes` the list.
+
+For a fixed list of nodes or a cluster you run yourself, construct the client
+directly: `new CalimeroClient({ baseUrl, nodes, policy })`. It fails over
+between `baseUrl` and `nodes` the same way, and never reads a directory.
+
 ## What the client checks
 
 Before it sends anything to a node, as core's Rust client does (`Measurements::Release`):
@@ -68,12 +97,12 @@ Pinned measurements go through `policy.verifyQuote` (`createQuoteVerifier`).
 
 ## The API
 
-- **Credentials**: `signUp`, `signIn`, `refresh`, `signOut`, `signOutEverywhere`, `useSession`, `useApiKey`, `me`, `usage`, `addPasskey`, `labelPasskey`, `removePasskey`, `createApiKey`, `listApiKeys`, `revokeApiKey`.
+- **Credentials**: `signUp`, `signIn`, `refresh`, `signOut`, `signOutEverywhere`, `useSession`, `useApiKey`, `me`, `usage`, `addPasskey`, `labelPasskey`, `removePasskey`, `createApiKey`, `listApiKeys`, `revokeApiKey`. Adding or removing a passkey and creating an API key are approved with a passkey the account already has.
 - **Packages**: `installPackage`, `uploadPackage`, `packages`, `package`, `uninstallPackage`; `uploadBundle` (raw WASM, development clusters only).
 - **Apps**: `createApp`, `listApps`, `getApp`, `deleteApp`, `setAccess`, `setAppMetadata`, `appStorage`, `appAbi`, `upgradeApp`, `transferApp`.
-- **Calls**: `call`, `callConfirmed`, `view`, `events`. A call always carries an idempotency key, and is sent again with it while the node answers `503`.
+- **Calls**: `call`, `callConfirmed`, `view`, `events`. A call always carries an idempotency key, and is sent again with it while the node answers `503`, then to the next node.
 - **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`.
+- **Organizations**: `createOrg`, `getOrg`, `deleteOrg`, `setOrgMetadata`, `setMember`, `removeMember`, `setMemberMetadata`, `setCapabilities` (`ORG_CAPABILITIES`), teams, `invite`, `redeemInvite`. Setting or removing a member or team member, capabilities and invites are approved with the caller's passkey; redeeming an invite is not.
 - **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`. 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`.

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

@@ -160,9 +160,10 @@ export interface CalimeroClientOptions {
     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}.
+     * answers `421 WRONG_NODE` (its release may not serve this account), or stays
+     * unavailable to a call or a view through all its retries. 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;
@@ -171,9 +172,26 @@ export interface CalimeroClientOptions {
     /** How calls and views retry a 503 or a failed connection. */
     retry?: CloudRetryOptions;
 }
+/** How {@link CalimeroClient.connect} reaches a Calimero Cloud cluster by name. */
+export interface CalimeroConnectOptions {
+    /** The cluster's name, e.g. `eu-shared-1`. */
+    cluster: string;
+    /** What every node must attest to before anything is sent to it. */
+    policy: CloudPolicy;
+    /** The node directory to ask. Default {@link DEFAULT_DIRECTORY}. */
+    directory?: string;
+    /** Try the nodes in this zone (e.g. `europe-west4-a`) first. */
+    zone?: string;
+    /** Fetch for the directory, attestation and envelopes. Defaults to global `fetch`. */
+    fetch?: typeof fetch;
+    /** How calls and views retry a 503 or a failed connection. */
+    retry?: CloudRetryOptions;
+    /** Randomness for the weighted node order, in [0, 1). Defaults to `Math.random`. */
+    random?: () => number;
+}
 export declare class CalimeroClient {
-    /** Every node this client may use, `baseUrl` first. */
-    private readonly nodeUrls;
+    /** Every node this client may use, `baseUrl` first (or as the directory last ordered them). */
+    private 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. */
@@ -188,9 +206,24 @@ export declare class CalimeroClient {
     private readonly retry;
     /** Rejections of the underlying `fetch` itself: the node could not be reached or dropped the connection. */
     private readonly networkFailures;
+    /** The directory the node list came from, for a client made by {@link connect}. */
+    private source;
+    /**
+     * A client for the Calimero Cloud cluster named `cluster`: its node list read
+     * from the public node directory, those in `zone` first, each group in
+     * weighted-random order. The directory only picks which nodes to try: each is
+     * attested under `policy` before anything is sent to it. Throws
+     * {@link DirectoryError} when the directory names no usable node.
+     *
+     * The list is read again in the background after a failover, and at the
+     * first request once the directory's `refreshAfterSeconds` has passed.
+     */
+    static connect(options: CalimeroConnectOptions): Promise<CalimeroClient>;
     constructor(options: CalimeroClientOptions);
-    /** The node requests go to now: `baseUrl`, until a `421 WRONG_NODE` moved the client on. */
+    /** The node requests go to now: `baseUrl`, until a `421 WRONG_NODE` or a failover moved the client on. */
     get nodeUrl(): string;
+    /** Every node this client may use, in the order it moves through them. */
+    get nodes(): string[];
     /** The sealed channel to `url`, attested under the client's policy before its first request. */
     private channel;
     /**
@@ -199,6 +232,19 @@ export declare class CalimeroClient {
      * refuse after another request moved on already does not move again.
      */
     private moveOn;
+    /**
+     * 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.
+     */
+    private failOver;
+    /**
+     * 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.
+     */
+    private reread;
     /** Authenticate every request with an API key. */
     useApiKey(key: string): void;
     useSession(session: CalimeroSession): void;
@@ -241,10 +287,17 @@ export declare class CalimeroClient {
      * {@link json} for a call or a view (D70): while the node answers 503 or
      * cannot be reached, the same request, with the same idempotency key, is sent
      * again after {@link retryDelayMs} (or the pause the node asked for, if
-     * longer), at most `retries` times. Every other answer is final. The last
+     * longer), at most `retries` times. Every other answer is final.
+     *
+     * When a node's retries run out, the request fails over to the next node the
+     * client knows and its retries start again there, with the same key: the
+     * key is kept in the app's replicated log, so the cluster answers it once
+     * whichever node it reaches. Each node is tried once per request. The last
      * failure surfaces as {@link UnavailableError}: the node's 503, or reason
      * `network` for a connection that failed, whose `committed` is `'unknown'`.
-     * `retries` 0 sends the request exactly once.
+     *
+     * `once` sends the request exactly once, to the node in use (the confirmed
+     * attempt of {@link callConfirmed}, whose challenge is single-use).
      */
     private retried;
     post<T = Record<string, unknown>>(path: string, body?: unknown): Promise<T>;
@@ -267,10 +320,15 @@ export declare class CalimeroClient {
     /** End every session of the signed-in account, on every device, this one too. */
     signOutEverywhere(): Promise<void>;
     me(): Promise<Record<string, unknown>>;
-    /** Add another passkey (another device) to the signed-in account; answers its credential id. */
-    addPasskey(passkey: PasskeyProvider): Promise<string>;
-    /** Remove one of the account's passkeys (not the last). */
-    removePasskey(credentialId: string): Promise<void>;
+    /**
+     * Add another passkey (another device, `passkey`) to the signed-in account;
+     * answers its credential id. The node asks for the approval of a passkey
+     * the account already has (`412 CONFIRM_REQUIRED`, never the new one),
+     * which `approver` gives.
+     */
+    addPasskey(passkey: PasskeyProvider, approver: PasskeyProvider): Promise<string>;
+    /** Remove one of the account's passkeys (not the last), approved with `passkey` (one it has). */
+    removePasskey(credentialId: string, passkey: PasskeyProvider): Promise<void>;
     /** Name one of the account's passkeys (a device label); `''` clears the name. */
     labelPasskey(credentialId: string, label: string): Promise<void>;
     /** What this account uses (apps, bundle bytes, API keys, owned orgs), with the cluster's quotas. */
@@ -283,7 +341,11 @@ export declare class CalimeroClient {
     /** The account's API keys (never the keys themselves). */
     listApiKeys(): Promise<Array<Record<string, unknown>>>;
     revokeApiKey(keyId: string): Promise<void>;
-    /** Create an API key for an agent or server. The key is returned once. */
+    /**
+     * Create an API key for an agent or server, approved with the account's
+     * `passkey` (`412 CONFIRM_REQUIRED`); needs a passkey session (an API key
+     * is refused `403`). The key is returned once.
+     */
     createApiKey(options: {
         label?: string;
         apps?: string[];
@@ -291,7 +353,7 @@ export declare class CalimeroClient {
         readOnly?: boolean;
         allowConfirm?: boolean;
         ttlSecs?: number;
-    }): Promise<{
+    }, passkey: PasskeyProvider): Promise<{
         keyId: string;
         key: string;
     }>;
@@ -365,10 +427,17 @@ export declare class CalimeroClient {
     }>;
     /**
      * POST `body` to `path`, answering a `412 CONFIRM_REQUIRED` with `passkey`'s
-     * assertion over the node's challenge (deleting an org, approving a release, ...).
+     * assertion over the node's challenge (deleting an org, approving a release,
+     * adding a member, ...): the same body again, with `confirm`. Without a
+     * passkey (a caller in plain JavaScript passing none) the `412` reaches the
+     * caller as {@link ConfirmRequired}, carrying the challenge.
      */
     postConfirmed<T>(path: string, body: Record<string, unknown>, passkey: PasskeyProvider): Promise<T>;
-    /** {@link postConfirmed} for a DELETE (deleting an organization). */
+    /**
+     * {@link postConfirmed} for a DELETE (deleting an organization, removing a
+     * member or a passkey): `body` (`{}` by default) goes as JSON, and the
+     * confirmed retry carries `confirm` beside it.
+     */
     deleteConfirmed<T>(path: string, passkey: PasskeyProvider, body?: Record<string, unknown>): Promise<T>;
     private confirmed;
     /**
@@ -559,15 +628,19 @@ export declare class CalimeroClient {
     setReleaseDeadline(version: string, after: Date | string): Promise<void>;
     /** Lift a release's deadline. Operator token. */
     liftReleaseDeadline(version: string): Promise<void>;
-    /** Add a member, or change their role. */
-    setMember(org: string, account: string, role: 'guest' | 'member' | 'admin' | 'owner'): Promise<void>;
-    removeMember(org: string, account: string): Promise<Record<string, unknown>>;
+    /** Add a member, or change their role, approved with the caller's `passkey`. */
+    setMember(org: string, account: string, role: 'guest' | 'member' | 'admin' | 'owner', passkey: PasskeyProvider): Promise<void>;
+    /**
+     * Remove a member, or leave (`account` the caller's own), approved with the
+     * caller's `passkey`.
+     */
+    removeMember(org: string, account: string, passkey: PasskeyProvider): Promise<Record<string, unknown>>;
     /**
      * Set capability bits ({@link ORG_CAPABILITIES}): for a member (`account`),
      * for a member of one team (`account` and `team`), or the organization's
-     * default (neither).
+     * default (neither). Approved with the caller's `passkey`.
      */
-    setCapabilities(org: string, capabilities: number, at?: {
+    setCapabilities(org: string, capabilities: number, passkey: PasskeyProvider, at?: {
         account?: string;
         team?: string;
     }): Promise<void>;
@@ -585,14 +658,23 @@ export declare class CalimeroClient {
     }): Promise<void>;
     /** Delete a team, the teams below it and their apps. */
     deleteTeam(org: string, team: string): Promise<void>;
-    /** Add a member to a team, or change their row: role, lead, capability bits. */
-    setTeamMember(org: string, team: string, account: string, row?: {
+    /**
+     * Add a member to a team, or change their row: role, lead, capability bits.
+     * Approved with the caller's `passkey`.
+     */
+    setTeamMember(org: string, team: string, account: string, passkey: PasskeyProvider, row?: {
         role?: 'lead' | 'member' | 'readOnly';
         lead?: boolean;
         capabilities?: number;
     }): Promise<void>;
-    removeTeamMember(org: string, team: string, account: string): Promise<void>;
-    invite(org: string, role: 'guest' | 'member' | 'admin', teams?: string[], options?: {
+    /** Remove a member from a team, approved with the caller's `passkey`. */
+    removeTeamMember(org: string, team: string, account: string, passkey: PasskeyProvider): Promise<void>;
+    /**
+     * Make an invite into `org` (and `teams`), approved with the caller's
+     * `passkey`; answers its token, which {@link redeemInvite} takes (no
+     * approval there).
+     */
+    invite(org: string, role: 'guest' | 'member' | 'admin', passkey: PasskeyProvider, teams?: string[], options?: {
         ttlSecs?: number;
         uses?: number;
     }): Promise<string>;

package/dist/cloud-v2/client.js

@@ -11,6 +11,7 @@
  */
 import { SealedTransportError, createSealedFetch } from '../sealed/sealed.js';
 import { fetchAttestedKey } from './attestation.js';
+import { DEFAULT_DIRECTORY, orderNodes, readDirectory } from './directory.js';
 import { CalimeroError, ConfirmCancelled, ConfirmRequired, LoginRequired, UnavailableError, WrongNode, errorFrom, } from './errors.js';
 import { b64url, fromB64url } from './passkey.js';
 import { confirmationCode, pageQuery, pendingApprovalsFrom, } from './approvals.js';
@@ -114,6 +115,32 @@ function ceremony(path) {
     return path === 'auth/refresh' || path.startsWith('auth/passkey/');
 }
 export class CalimeroClient {
+    /**
+     * A client for the Calimero Cloud cluster named `cluster`: its node list read
+     * from the public node directory, those in `zone` first, each group in
+     * weighted-random order. The directory only picks which nodes to try: each is
+     * attested under `policy` before anything is sent to it. Throws
+     * {@link DirectoryError} when the directory names no usable node.
+     *
+     * The list is read again in the background after a failover, and at the
+     * first request once the directory's `refreshAfterSeconds` has passed.
+     */
+    static async connect(options) {
+        const directory = options.directory ?? DEFAULT_DIRECTORY;
+        const random = options.random ?? Math.random;
+        const fetcher = options.fetch ?? ((input, init) => fetch(input, init));
+        const listing = await readDirectory(directory, options.cluster, fetcher);
+        const [baseUrl, ...nodes] = orderNodes(listing.nodes, options.zone, random);
+        const client = new CalimeroClient({ baseUrl, nodes, policy: options.policy, fetch: options.fetch, retry: options.retry });
+        client.source = {
+            directory,
+            cluster: options.cluster,
+            zone: options.zone,
+            random,
+            due: Date.now() + listing.refreshAfterSeconds * 1000,
+        };
+        return client;
+    }
     constructor(options) {
         /** The one in use: an index into {@link nodeUrls}. */
         this.at = 0;
@@ -142,10 +169,14 @@ export class CalimeroClient {
         };
         this.raw = raw;
     }
-    /** The node requests go to now: `baseUrl`, until a `421 WRONG_NODE` moved the client on. */
+    /** The node requests go to now: `baseUrl`, until a `421 WRONG_NODE` or a failover moved the client on. */
     get nodeUrl() {
         return this.nodeUrls[this.at];
     }
+    /** Every node this client may use, in the order it moves through them. */
+    get nodes() {
+        return [...this.nodeUrls];
+    }
     /** The sealed channel to `url`, attested under the client's policy before its first request. */
     channel(url) {
         let sealed = this.channels.get(url);
@@ -167,10 +198,52 @@ export class CalimeroClient {
     moveOn(from) {
         if (this.nodeUrls.length < 2)
             return false;
-        if (this.at === from)
-            this.at = (from + 1) % this.nodeUrls.length;
+        if (this.nodeUrl === from)
+            this.at = (this.at + 1) % this.nodeUrls.length;
         return true;
     }
+    /**
+     * Fail over from node `from`, where a request's retries ran out, to the next
+     * node it has not `tried`. False when it has tried them all. A request whose
+     * node another request moved away from already goes to that node, if untried.
+     */
+    failOver(from, tried) {
+        if (this.nodeUrl !== from && !tried.has(this.nodeUrl))
+            return true;
+        const count = this.nodeUrls.length;
+        for (let step = 1; step < count; step++) {
+            const next = (this.at + step) % count;
+            if (!tried.has(this.nodeUrls[next])) {
+                this.at = next;
+                this.reread();
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Read the node list again from the directory, in the background, for a
+     * client made by {@link connect}: the node in use stays first, then the
+     * directory's order; a node no longer listed is dropped. A failed read is
+     * ignored. One read at a time.
+     */
+    reread() {
+        const source = this.source;
+        if (!source || source.reading)
+            return;
+        source.reading = readDirectory(source.directory, source.cluster, this.raw)
+            .then((listing) => {
+            const current = this.nodeUrl;
+            const listed = orderNodes(listing.nodes, source.zone, source.random);
+            this.nodeUrls = [current, ...listed.filter((url) => url !== current)];
+            this.at = 0;
+            source.due = Date.now() + listing.refreshAfterSeconds * 1000;
+        })
+            .catch(() => undefined)
+            .finally(() => {
+            source.reading = undefined;
+        });
+    }
     /** Authenticate every request with an API key. */
     useApiKey(key) {
         this.auth = key;
@@ -200,6 +273,8 @@ export class CalimeroClient {
             headers['content-type'] = 'application/json';
             payload = JSON.stringify(body);
         }
+        if (this.source && Date.now() >= this.source.due)
+            this.reread();
         const url = this.nodeUrl;
         try {
             return await this.channel(url)(`${url}/${path}`, { method, headers, body: payload, signal });
@@ -232,7 +307,7 @@ export class CalimeroClient {
         let refreshed = false;
         let moved = false;
         for (;;) {
-            const [token, at] = [this.auth, this.at];
+            const [token, at] = [this.auth, this.nodeUrl];
             const response = await this.request(method, path, body, raw, contentType, signal);
             if (response.ok)
                 return response;
@@ -272,30 +347,46 @@ export class CalimeroClient {
      * {@link json} for a call or a view (D70): while the node answers 503 or
      * cannot be reached, the same request, with the same idempotency key, is sent
      * again after {@link retryDelayMs} (or the pause the node asked for, if
-     * longer), at most `retries` times. Every other answer is final. The last
+     * longer), at most `retries` times. Every other answer is final.
+     *
+     * When a node's retries run out, the request fails over to the next node the
+     * client knows and its retries start again there, with the same key: the
+     * key is kept in the app's replicated log, so the cluster answers it once
+     * whichever node it reaches. Each node is tried once per request. The last
      * failure surfaces as {@link UnavailableError}: the node's 503, or reason
      * `network` for a connection that failed, whose `committed` is `'unknown'`.
-     * `retries` 0 sends the request exactly once.
+     *
+     * `once` sends the request exactly once, to the node in use (the confirmed
+     * attempt of {@link callConfirmed}, whose challenge is single-use).
      */
-    async retried(method, path, body, retries = this.retry.retries) {
-        for (let attempt = 0;; attempt++) {
+    async retried(method, path, body, once = false) {
+        const retries = once ? 0 : this.retry.retries;
+        const tried = new Set();
+        for (;;) {
             let unavailable;
-            try {
-                return await this.json(method, path, body);
-            }
-            catch (error) {
-                if (error instanceof UnavailableError)
-                    unavailable = error;
-                else if (error instanceof TypeError && this.networkFailures.has(error)) {
-                    unavailable = new UnavailableError('NETWORK', `the node could not be reached: ${error.message}`, {}, undefined, error);
+            let node = this.nodeUrl;
+            for (let attempt = 0;; attempt++) {
+                node = this.nodeUrl;
+                tried.add(node);
+                try {
+                    return await this.json(method, path, body);
                 }
-                else
-                    throw error;
+                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}`, {}, undefined, 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) * 1000)));
             }
-            if (attempt >= retries)
+            if (once || !this.failOver(node, tried))
                 throw unavailable;
-            const backoff = retryDelayMs(attempt, this.retry);
-            await new Promise((resolve) => setTimeout(resolve, Math.max(backoff, (unavailable.retryAfter ?? 0) * 1000)));
         }
     }
     post(path, body = {}) {
@@ -387,19 +478,21 @@ export class CalimeroClient {
     me() {
         return this.get('auth/me');
     }
-    /** Add another passkey (another device) to the signed-in account; answers its credential id. */
-    async addPasskey(passkey) {
+    /**
+     * Add another passkey (another device, `passkey`) to the signed-in account;
+     * answers its credential id. The node asks for the approval of a passkey
+     * the account already has (`412 CONFIRM_REQUIRED`, never the new one),
+     * which `approver` gives.
+     */
+    async addPasskey(passkey, approver) {
         const begin = await this.post('auth/passkeys/add/begin');
         const registration = await passkey.create(begin.options);
-        const { credentialId } = await this.post('auth/passkeys/add/finish', {
-            challengeId: begin.challengeId,
-            registration,
-        });
+        const { credentialId } = await this.postConfirmed('auth/passkeys/add/finish', { challengeId: begin.challengeId, registration }, approver);
         return credentialId;
     }
-    /** Remove one of the account's passkeys (not the last). */
-    async removePasskey(credentialId) {
-        await this.delete(`auth/passkeys/${seg(credentialId)}`);
+    /** Remove one of the account's passkeys (not the last), approved with `passkey` (one it has). */
+    async removePasskey(credentialId, passkey) {
+        await this.deleteConfirmed(`auth/passkeys/${seg(credentialId)}`, passkey);
     }
     /** Name one of the account's passkeys (a device label); `''` clears the name. */
     async labelPasskey(credentialId, label) {
@@ -428,9 +521,13 @@ export class CalimeroClient {
     async revokeApiKey(keyId) {
         await this.delete(`auth/apikeys/${seg(keyId)}`);
     }
-    /** Create an API key for an agent or server. The key is returned once. */
-    createApiKey(options) {
-        return this.post('auth/apikeys', options);
+    /**
+     * Create an API key for an agent or server, approved with the account's
+     * `passkey` (`412 CONFIRM_REQUIRED`); needs a passkey session (an API key
+     * is refused `403`). The key is returned once.
+     */
+    createApiKey(options, passkey) {
+        return this.postConfirmed('auth/apikeys', { ...options }, passkey);
     }
     // ---------------------------------------------------------------- apps
     /** Upload a raw WASM bundle (development clusters only); answers its hash. */
@@ -540,12 +637,19 @@ export class CalimeroClient {
     }
     /**
      * POST `body` to `path`, answering a `412 CONFIRM_REQUIRED` with `passkey`'s
-     * assertion over the node's challenge (deleting an org, approving a release, ...).
+     * assertion over the node's challenge (deleting an org, approving a release,
+     * adding a member, ...): the same body again, with `confirm`. Without a
+     * passkey (a caller in plain JavaScript passing none) the `412` reaches the
+     * caller as {@link ConfirmRequired}, carrying the challenge.
      */
     postConfirmed(path, body, passkey) {
         return this.confirmed('POST', path, body, passkey);
     }
-    /** {@link postConfirmed} for a DELETE (deleting an organization). */
+    /**
+     * {@link postConfirmed} for a DELETE (deleting an organization, removing a
+     * member or a passkey): `body` (`{}` by default) goes as JSON, and the
+     * confirmed retry carries `confirm` beside it.
+     */
     deleteConfirmed(path, passkey, body = {}) {
         return this.confirmed('DELETE', path, body, passkey);
     }
@@ -554,7 +658,7 @@ export class CalimeroClient {
             return await send(body);
         }
         catch (error) {
-            if (!(error instanceof ConfirmRequired))
+            if (!(error instanceof ConfirmRequired) || !passkey)
                 throw error;
             const d = error.details;
             let assertion;
@@ -600,7 +704,7 @@ export class CalimeroClient {
         const key = idempotencyKey ?? newIdempotencyKey();
         // The confirmed attempt goes out exactly once: its challenge is single-use,
         // so a resend would be refused on the challenge, not answered from the key.
-        return this.confirmed('POST', path, { method, args, idempotencyKey: key }, passkey, (body) => this.retried('POST', path, body, body.confirm === undefined ? this.retry.retries : 0));
+        return this.confirmed('POST', path, { method, args, idempotencyKey: key }, passkey, (body) => this.retried('POST', path, body, body.confirm !== undefined));
     }
     /** Run a read-only method: strong by default, or stale from any replica. */
     view(app, method, args = {}, options = {}) {
@@ -882,20 +986,24 @@ export class CalimeroClient {
     async liftReleaseDeadline(version) {
         await this.delete(`ops/releases/${seg(version)}/deadline`);
     }
-    /** Add a member, or change their role. */
-    async setMember(org, account, role) {
-        await this.post(`orgs/${seg(org)}/members`, { account, role });
+    /** Add a member, or change their role, approved with the caller's `passkey`. */
+    async setMember(org, account, role, passkey) {
+        await this.postConfirmed(`orgs/${seg(org)}/members`, { account, role }, passkey);
     }
-    removeMember(org, account) {
-        return this.delete(`orgs/${seg(org)}/members/${seg(account)}`);
+    /**
+     * Remove a member, or leave (`account` the caller's own), approved with the
+     * caller's `passkey`.
+     */
+    removeMember(org, account, passkey) {
+        return this.deleteConfirmed(`orgs/${seg(org)}/members/${seg(account)}`, passkey);
     }
     /**
      * Set capability bits ({@link ORG_CAPABILITIES}): for a member (`account`),
      * for a member of one team (`account` and `team`), or the organization's
-     * default (neither).
+     * default (neither). Approved with the caller's `passkey`.
      */
-    async setCapabilities(org, capabilities, at = {}) {
-        await this.post(`orgs/${seg(org)}/capabilities`, { capabilities, ...at });
+    async setCapabilities(org, capabilities, passkey, at = {}) {
+        await this.postConfirmed(`orgs/${seg(org)}/capabilities`, { capabilities, ...at }, passkey);
     }
     async createTeam(org, name, join, parent) {
         const { teamId } = await this.post(`orgs/${seg(org)}/teams`, { name, join, parent });
@@ -915,15 +1023,24 @@ export class CalimeroClient {
     async deleteTeam(org, team) {
         await this.delete(`orgs/${seg(org)}/teams/${seg(team)}`);
     }
-    /** Add a member to a team, or change their row: role, lead, capability bits. */
-    async setTeamMember(org, team, account, row = {}) {
-        await this.post(`orgs/${seg(org)}/teams/${seg(team)}/members`, { account, ...row });
+    /**
+     * Add a member to a team, or change their row: role, lead, capability bits.
+     * Approved with the caller's `passkey`.
+     */
+    async setTeamMember(org, team, account, passkey, row = {}) {
+        await this.postConfirmed(`orgs/${seg(org)}/teams/${seg(team)}/members`, { account, ...row }, passkey);
     }
-    async removeTeamMember(org, team, account) {
-        await this.delete(`orgs/${seg(org)}/teams/${seg(team)}/members/${seg(account)}`);
+    /** Remove a member from a team, approved with the caller's `passkey`. */
+    async removeTeamMember(org, team, account, passkey) {
+        await this.deleteConfirmed(`orgs/${seg(org)}/teams/${seg(team)}/members/${seg(account)}`, passkey);
     }
-    async invite(org, role, teams = [], options = {}) {
-        const { token } = await this.post(`orgs/${seg(org)}/invites`, { role, teams, ...options });
+    /**
+     * Make an invite into `org` (and `teams`), approved with the caller's
+     * `passkey`; answers its token, which {@link redeemInvite} takes (no
+     * approval there).
+     */
+    async invite(org, role, passkey, teams = [], options = {}) {
+        const { token } = await this.postConfirmed(`orgs/${seg(org)}/invites`, { role, teams, ...options }, passkey);
         return token;
     }
     redeemInvite(token) {