@calimero-network/mero-js 29.4.0 → 29.5.0

package/README.md

@@ -98,6 +98,7 @@ Pinned measurements go through `policy.verifyQuote` (`createQuoteVerifier`).
 ## The API
 
 - **Credentials**: `signUp` (with an `invite`, on a cluster that takes new accounts by invite; `signUpPolicy` reads which), `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.
+- **Account recovery** (core #4844): `createRecoveryCode`, `removeRecoveryCode` (passkey-approved; the code is shown once), then signed out `startAccountRecovery(code, passkey)` and, 72 hours later, `finishAccountRecovery(passkey, accountId?)`; a passkey the account still has cancels in between (`cancelAccountRecovery`; `me()` shows `recoveryCode` and `recoveryPending`).
 - **Package origins**: `packageOrigins.list`, `packageOrigins.add`, `packageOrigins.remove`. A package's managers register the web origins of a frontend they host themselves (approved with a passkey); `signUp` and `signIn` on such a page send its origin, sign for that origin's relying-party id, and open a session bound to the package (`me()` answers its `app` and `origin`). An unregistered origin is refused with `OriginNotRegistered`.
 - **Packages**: `installPackage`, `uploadPackage`, `packages`, `package`, `uninstallPackage`; `uploadBundle` (raw WASM, development clusters only).
 - **Apps**: `createApp`, `listApps`, `getApp`, `deleteApp`, `setAccess`, `setAppMetadata`, `appStorage`, `appAbi`, `upgradeApp`, `transferApp`.

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 OpenConsentOptions, type OpsAppsReport, type OpsOrgsReport, type PageOptions, type PendingApprovals, type PublisherBindingInfo, type PublisherProof, type ReleaseRules } from './approvals.js';
-export { AppError, ArgsTooLarge, BadOrigin, CalimeroError, ConfirmCancelled, ConfirmRequired, IdempotencyMismatch, LoginRequired, ConsentStale, NotFound, OriginNotRegistered, OriginTaken, QuotaExceeded, ReleaseDeadlineError, SignUpRefused, TrapError, UnavailableError, WrongNode, errorFrom, } from './errors.js';
+export { AppError, ArgsTooLarge, BadOrigin, CalimeroError, ConfirmCancelled, ConfirmRequired, IdempotencyMismatch, LoginRequired, ConsentStale, NotFound, OriginNotRegistered, OriginTaken, QuotaExceeded, RecoveryNotReady, ReleaseDeadlineError, SignUpRefused, TrapError, UnavailableError, WrongNode, WrongRecoveryCode, errorFrom, } from './errors.js';
 export type { Committed, SignUpRefusal } from './errors.js';
 export interface CalimeroSession {
     accountId: string;
@@ -302,6 +302,25 @@ export interface MeInfo extends Record<string, unknown> {
     app?: string | null;
     /** The web origin the session was opened on, when the node recorded one. */
     origin?: string | null;
+    /** Whether the account holds a recovery code ({@link CalimeroClient.createRecoveryCode}); never the code. */
+    recoveryCode?: boolean;
+    /**
+     * A recovery of this account under way: someone holding its recovery code
+     * started it with a new passkey. Warn on every device; a passkey the
+     * account has cancels it ({@link CalimeroClient.cancelAccountRecovery})
+     * until `readyAt`.
+     */
+    recoveryPending?: AccountRecovery | null;
+}
+/** A recovery of an account under way (core #4844, `docs/specs/account-recovery.md`). */
+export interface AccountRecovery {
+    accountId: string;
+    /** The new passkey the recovery adds when it finishes. */
+    credentialId: string;
+    /** When it started (Unix seconds). */
+    startedAt: number;
+    /** The earliest it may finish (Unix seconds): 72 hours after the start. */
+    readyAt: number;
 }
 /** One web origin registered for a package (`GET /package-origins/{package}`). */
 export interface PackageOrigin {
@@ -610,6 +629,41 @@ export declare class CalimeroClient {
     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>;
+    /**
+     * Make the account's recovery code (replacing any it had), approved with
+     * `passkey` (`412 CONFIRM_REQUIRED`). Answers the code, once: show it to
+     * the person to keep offline; the node keeps only its public key. A passkey
+     * session on the cluster's own origin only (never an API key or a
+     * package-bound session).
+     */
+    createRecoveryCode(passkey: PasskeyProvider): Promise<string>;
+    /** Remove the account's recovery code, approved with `passkey`. */
+    removeRecoveryCode(passkey: PasskeyProvider): Promise<void>;
+    /**
+     * Signed out: start recovering the account `code` names. `passkey` makes a
+     * new passkey for it (the browser's create prompt, user verified); the
+     * node spends the code and keeps the passkey as pending. Nothing is added
+     * and no session opens: finish with {@link finishAccountRecovery} at
+     * `readyAt`. A code the cluster does not hold (mistyped, replaced or
+     * spent) is {@link WrongRecoveryCode}; an account with a recovery already
+     * under way `409 RECOVERY_PENDING`.
+     */
+    startAccountRecovery(code: string, passkey: PasskeyProvider): Promise<AccountRecovery>;
+    /**
+     * Cancel the recovery of the signed-in account under way, approved with
+     * `passkey` (one the account already has). The code stays spent: make a
+     * new one.
+     */
+    cancelAccountRecovery(passkey: PasskeyProvider): Promise<void>;
+    /**
+     * Signed out, once the delay passed: finish the recovery with the passkey
+     * it registered (`passkey` signs the node's sign-in challenge). The passkey
+     * joins the account, every other session of the account ends, and this
+     * client is signed in. `accountId` (from the start) lets the node refuse
+     * early and offer only that passkey; before `readyAt` it is
+     * {@link RecoveryNotReady}, with no recovery under way {@link NotFound}.
+     */
+    finishAccountRecovery(passkey: PasskeyProvider, accountId?: string): Promise<CalimeroSession>;
     /** What this account uses (apps, bundle bytes, API keys, owned orgs), with the cluster's quotas. */
     usage(): Promise<Record<string, unknown>>;
     /**

package/dist/cloud-v2/client.js

@@ -12,11 +12,11 @@
 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, OriginNotRegistered, UnavailableError, WrongNode, errorFrom, } from './errors.js';
+import { CalimeroError, ConfirmCancelled, ConfirmRequired, LoginRequired, OriginNotRegistered, UnavailableError, WrongNode, WrongRecoveryCode, errorFrom, } from './errors.js';
 import { b64url, fromB64url } from './passkey.js';
 import { signRecovery } from './recovery.js';
 import { confirmationCode, pageQuery, pendingApprovalsFrom, } from './approvals.js';
-export { AppError, ArgsTooLarge, BadOrigin, CalimeroError, ConfirmCancelled, ConfirmRequired, IdempotencyMismatch, LoginRequired, ConsentStale, NotFound, OriginNotRegistered, OriginTaken, QuotaExceeded, ReleaseDeadlineError, SignUpRefused, TrapError, UnavailableError, WrongNode, errorFrom, } from './errors.js';
+export { AppError, ArgsTooLarge, BadOrigin, CalimeroError, ConfirmCancelled, ConfirmRequired, IdempotencyMismatch, LoginRequired, ConsentStale, NotFound, OriginNotRegistered, OriginTaken, QuotaExceeded, RecoveryNotReady, ReleaseDeadlineError, SignUpRefused, TrapError, UnavailableError, WrongNode, WrongRecoveryCode, errorFrom, } from './errors.js';
 /** A deployer's key, as `GET /deployers` lists it and `DELETE /deployers/{key}` takes it. */
 export function deployerKey(deployer) {
     return 'account' in deployer ? `account:${deployer.account}` : `org:${deployer.org}`;
@@ -151,8 +151,10 @@ export function retryDelayMs(retry, options) {
  * before it spends the challenge or the refresh token (core #4774).
  */
 function ceremony(path) {
-    return path === 'auth/refresh' || path.startsWith('auth/passkey/');
+    return path === 'auth/refresh' || path.startsWith('auth/passkey/') || RECOVERY_CEREMONIES.has(path);
 }
+/** The signed-out halves of an account recovery: a `401` there is the code's, not a session's. */
+const RECOVERY_CEREMONIES = new Set(['auth/recovery/begin', 'auth/recovery/start', 'auth/recovery/finish']);
 export class CalimeroClient {
     /**
      * A client for the Calimero Cloud cluster named `cluster`: its node list read
@@ -608,6 +610,69 @@ export class CalimeroClient {
     async labelPasskey(credentialId, label) {
         await this.post(`auth/passkeys/${seg(credentialId)}`, { label });
     }
+    // ---------------------------------------------------------------- account recovery
+    //
+    // core #4844 (`docs/specs/account-recovery.md`): a recovery code, made with
+    // a passkey and shown once, lets someone who lost every passkey register a
+    // new one; it is added, and the account signed in, 72 hours later unless a
+    // passkey the account still has cancels it first.
+    /**
+     * Make the account's recovery code (replacing any it had), approved with
+     * `passkey` (`412 CONFIRM_REQUIRED`). Answers the code, once: show it to
+     * the person to keep offline; the node keeps only its public key. A passkey
+     * session on the cluster's own origin only (never an API key or a
+     * package-bound session).
+     */
+    async createRecoveryCode(passkey) {
+        const { code } = await this.postConfirmed('auth/recovery', {}, passkey);
+        return code;
+    }
+    /** Remove the account's recovery code, approved with `passkey`. */
+    async removeRecoveryCode(passkey) {
+        await this.deleteConfirmed('auth/recovery', passkey);
+    }
+    /**
+     * Signed out: start recovering the account `code` names. `passkey` makes a
+     * new passkey for it (the browser's create prompt, user verified); the
+     * node spends the code and keeps the passkey as pending. Nothing is added
+     * and no session opens: finish with {@link finishAccountRecovery} at
+     * `readyAt`. A code the cluster does not hold (mistyped, replaced or
+     * spent) is {@link WrongRecoveryCode}; an account with a recovery already
+     * under way `409 RECOVERY_PENDING`.
+     */
+    async startAccountRecovery(code, passkey) {
+        try {
+            const begin = await this.post('auth/recovery/begin', { code });
+            const registration = await passkey.create(begin.options);
+            return await this.post('auth/recovery/start', { challengeId: begin.challengeId, code, registration });
+        }
+        catch (error) {
+            if (error instanceof LoginRequired)
+                throw new WrongRecoveryCode(error.message.replace(/^401 UNAUTHENTICATED: /, ''), error.details);
+            throw error;
+        }
+    }
+    /**
+     * Cancel the recovery of the signed-in account under way, approved with
+     * `passkey` (one the account already has). The code stays spent: make a
+     * new one.
+     */
+    async cancelAccountRecovery(passkey) {
+        await this.postConfirmed('auth/recovery/cancel', {}, passkey);
+    }
+    /**
+     * Signed out, once the delay passed: finish the recovery with the passkey
+     * it registered (`passkey` signs the node's sign-in challenge). The passkey
+     * joins the account, every other session of the account ends, and this
+     * client is signed in. `accountId` (from the start) lets the node refuse
+     * early and offer only that passkey; before `readyAt` it is
+     * {@link RecoveryNotReady}, with no recovery under way {@link NotFound}.
+     */
+    async finishAccountRecovery(passkey, accountId) {
+        const session = await this.postConfirmed('auth/recovery/finish', accountId ? { accountId } : {}, passkey);
+        this.useSession(session);
+        return session;
+    }
     /** What this account uses (apps, bundle bytes, API keys, owned orgs), with the cluster's quotas. */
     usage() {
         return this.get('auth/usage');

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

@@ -126,6 +126,24 @@ export declare class BadOrigin extends CalimeroError {
 export declare class OriginTaken extends CalimeroError {
     constructor(message: string, details?: Record<string, unknown>);
 }
+/**
+ * `409 RECOVERY_NOT_READY`: a recovery (an account's or an organization's)
+ * may finish only once its 72-hour delay has passed. `readyAt` is when it may
+ * (Unix seconds), when the node said.
+ */
+export declare class RecoveryNotReady extends CalimeroError {
+    readonly readyAt: number | undefined;
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * The recovery code is not one the cluster holds: mistyped, replaced by a
+ * newer one, or spent by a recovery that started (whether it finished or was
+ * cancelled). The node answers it `401`; a recovery is signed out, so it is
+ * this error, not {@link LoginRequired}.
+ */
+export declare class WrongRecoveryCode extends CalimeroError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
 /** Why a sign-up was refused ({@link SignUpRefused.reason}), read from what the node said. */
 export type SignUpRefusal = 'invite-only' | 'closed' | 'unknown-invite' | 'expired-invite' | 'org-gone' | 'other';
 /**

package/dist/cloud-v2/errors.js

@@ -165,6 +165,30 @@ export class OriginTaken extends CalimeroError {
         this.name = 'OriginTaken';
     }
 }
+/**
+ * `409 RECOVERY_NOT_READY`: a recovery (an account's or an organization's)
+ * may finish only once its 72-hour delay has passed. `readyAt` is when it may
+ * (Unix seconds), when the node said.
+ */
+export class RecoveryNotReady extends CalimeroError {
+    constructor(message, details = {}) {
+        super(409, 'RECOVERY_NOT_READY', message, details);
+        this.name = 'RecoveryNotReady';
+        this.readyAt = typeof details.readyAt === 'number' ? details.readyAt : undefined;
+    }
+}
+/**
+ * The recovery code is not one the cluster holds: mistyped, replaced by a
+ * newer one, or spent by a recovery that started (whether it finished or was
+ * cancelled). The node answers it `401`; a recovery is signed out, so it is
+ * this error, not {@link LoginRequired}.
+ */
+export class WrongRecoveryCode extends CalimeroError {
+    constructor(message, details = {}) {
+        super(401, 'UNAUTHENTICATED', message || 'unknown or used recovery code', details);
+        this.name = 'WrongRecoveryCode';
+    }
+}
 /**
  * `403 SIGN_UP_REFUSED`: the cluster's sign-up policy does not take this
  * sign-up (core `SystemState::admits`), answered by `register/begin` before a
@@ -299,6 +323,8 @@ export function errorFrom(status, body, retryAfterHeader) {
             return new OriginTaken(message, details);
         case '429 QUOTA_EXCEEDED':
             return new QuotaExceeded(message, details);
+        case '409 RECOVERY_NOT_READY':
+            return new RecoveryNotReady(message, details);
         case '403 SIGN_UP_REFUSED':
             return new SignUpRefused(message, details);
         case '412 CONFIRM_REQUIRED':

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

@@ -1,9 +1,9 @@
 export { CalimeroClient, deployerKey, frontendManifest, pageDeployment } from './client.js';
 export { DEFAULT_DIRECTORY, DirectoryError } from './directory.js';
 export type { DirectoryFailure } from './directory.js';
-export { AppError, ArgsTooLarge, BadOrigin, CalimeroError, ConfirmCancelled, ConfirmRequired, IdempotencyMismatch, LoginRequired, ConsentStale, NotFound, OriginNotRegistered, OriginTaken, QuotaExceeded, ReleaseDeadlineError, SignUpRefused, TrapError, UnavailableError, WrongNode, errorFrom, } from './errors.js';
+export { AppError, ArgsTooLarge, BadOrigin, CalimeroError, ConfirmCancelled, ConfirmRequired, IdempotencyMismatch, LoginRequired, ConsentStale, NotFound, OriginNotRegistered, OriginTaken, QuotaExceeded, RecoveryNotReady, ReleaseDeadlineError, SignUpRefused, TrapError, UnavailableError, WrongNode, WrongRecoveryCode, errorFrom, } from './errors.js';
 export type { Committed, SignUpRefusal } from './errors.js';
-export type { AppInfo, AppXcalls, BlobContent, BlobInfo, DeadLetter, Deployer, DeployerGrant, DeployersInfo, DeploymentInfo, DeploymentOffer, DeploymentOrgs, FrontendManifest, MeInfo, PackageOrigin, PackageOriginAdded, PackageOriginRemoved, PackageOrigins, SignInOptions, SignUpOptions, SignUpPolicy, PublicDeployment, CallResult, CalimeroClientOptions, CalimeroConnectOptions, CloudEvent, CalimeroSession, PackageInfo, PackageInstalled, CloudRetryOptions, OrgInfo, OrgRecovery, RecoveryTimes, OrgUpgradeTarget, PresenceEntry, UpgradeRun, ViewResult, } from './client.js';
+export type { AppInfo, AppXcalls, BlobContent, BlobInfo, DeadLetter, Deployer, DeployerGrant, DeployersInfo, DeploymentInfo, DeploymentOffer, DeploymentOrgs, FrontendManifest, MeInfo, PackageOrigin, PackageOriginAdded, PackageOriginRemoved, PackageOrigins, SignInOptions, AccountRecovery, SignUpOptions, SignUpPolicy, PublicDeployment, CallResult, CalimeroClientOptions, CalimeroConnectOptions, CloudEvent, CalimeroSession, PackageInfo, PackageInstalled, CloudRetryOptions, OrgInfo, OrgRecovery, RecoveryTimes, OrgUpgradeTarget, PresenceEntry, UpgradeRun, ViewResult, } from './client.js';
 export { claimedRelease, fetchAttestedKey, freshCollateral, MOCK_QUOTE_HEADER } from './attestation.js';
 export type { AttestationDoc, CloudPolicy, CloudReleasePolicy } from './attestation.js';
 export { browserPasskey, b64url, fromB64url } from './passkey.js';

package/dist/cloud-v2/index.js

@@ -1,6 +1,6 @@
 export { CalimeroClient, deployerKey, frontendManifest, pageDeployment } from './client.js';
 export { DEFAULT_DIRECTORY, DirectoryError } from './directory.js';
-export { AppError, ArgsTooLarge, BadOrigin, CalimeroError, ConfirmCancelled, ConfirmRequired, IdempotencyMismatch, LoginRequired, ConsentStale, NotFound, OriginNotRegistered, OriginTaken, QuotaExceeded, ReleaseDeadlineError, SignUpRefused, TrapError, UnavailableError, WrongNode, errorFrom, } from './errors.js';
+export { AppError, ArgsTooLarge, BadOrigin, CalimeroError, ConfirmCancelled, ConfirmRequired, IdempotencyMismatch, LoginRequired, ConsentStale, NotFound, OriginNotRegistered, OriginTaken, QuotaExceeded, RecoveryNotReady, ReleaseDeadlineError, SignUpRefused, TrapError, UnavailableError, WrongNode, WrongRecoveryCode, errorFrom, } from './errors.js';
 export { claimedRelease, fetchAttestedKey, freshCollateral, MOCK_QUOTE_HEADER } from './attestation.js';
 export { browserPasskey, b64url, fromB64url } from './passkey.js';
 export { MAX_RECOVERY_NONCE_BYTES, RECOVERY_DOMAIN, newRecoverySeed, parseRecoverySeed, recoveryMessage, recoveryPublicKey, recoverySeedText, signRecovery, } from './recovery.js';