@calimero-network/mero-js 27.5.0 → 28.0.0

package/README.md

@@ -97,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`, 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

@@ -320,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. */
@@ -336,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[];
@@ -344,7 +353,7 @@ export declare class CalimeroClient {
         readOnly?: boolean;
         allowConfirm?: boolean;
         ttlSecs?: number;
-    }): Promise<{
+    }, passkey: PasskeyProvider): Promise<{
         keyId: string;
         key: string;
     }>;
@@ -418,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;
     /**
@@ -612,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>;
@@ -638,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

@@ -478,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) {
@@ -519,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. */
@@ -631,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);
     }
@@ -645,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;
@@ -973,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 });
@@ -1006,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) {