@calimero-network/mero-js 29.4.0 → 29.6.0

package/README.md

@@ -98,7 +98,8 @@ 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.
-- **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`.
+- **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`. `packageOrigins.add(pkg, origin, passkey, { served: true })` registers a custom domain: the cluster also serves the package's frontend there from its signed bundle (`https://host`, no port; the passkey's consent names `served: true`); `list` answers `served` on each origin, and the extra refusals are `NotServing` (the cluster serves no frontends), `ClusterNotUpgraded` (a node is on an older release), `QuotaExceeded` (4 served per package, 64 per cluster) and `OriginTaken` (held with the other `served`).
 - **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.
@@ -106,7 +107,7 @@ Pinned measurements go through `policy.verifyQuote` (`createQuoteVerifier`).
 - **Organizations**: `createOrg`, `getOrg`, `deleteOrg`, `setOrgMetadata`, `setMember`, `removeMember`, `setMemberMetadata`, `setCapabilities` (`ORG_CAPABILITIES`), teams, `invite`, `redeemInvite`, recovery (`setRecoveryKey`, `startRecovery`, `cancelRecovery`, `finishRecovery`; `newRecoverySeed`, `recoveryPublicKey`). 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`.
+- **Operator** (ops token): `opsApps`, `opsOrgs`, `opsServedOrigins` (every custom domain the log holds, by package label), `setReleaseDeadline`, `liftReleaseDeadline`.
 - **Any route**: `get`, `post`, `put`, `delete`; `postConfirmed` and `deleteConfirmed` answer a `412 CONFIRM_REQUIRED` with a passkey.
 
 Refusals are typed (`LoginRequired`, `WrongNode`, `NotFound`, `ConfirmRequired`, `ConfirmCancelled`,

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 {
@@ -312,6 +331,12 @@ export interface PackageOrigin {
     /** The account that registered it. */
     addedBy: string;
     addedAt: string | number;
+    /**
+     * The cluster serves the package's frontend on this origin too (a custom
+     * domain, from its signed bundle). Absent (`false`) from a node that
+     * predates served origins.
+     */
+    served?: boolean;
 }
 /** What registering an origin answers. */
 export interface PackageOriginAdded extends PackageOrigin {
@@ -337,9 +362,21 @@ export interface PackageOrigins {
      * caller as {@link ConfirmRequired}). `rpId` defaults to the node's choice
      * for the origin (its host). Refusals: {@link BadOrigin} (`BAD_ORIGIN`,
      * `BAD_RP_ID`), {@link OriginTaken}, {@link QuotaExceeded}.
+     *
+     * `served: true` makes it a custom domain: the cluster also serves the
+     * package's frontend on it (`https://host`, no port; never a name under the
+     * apps domain or the cluster's rp-id), and the consent the passkey signs
+     * names it (`{ origin, rpId, served: true }`). Further refusals:
+     * {@link NotServing} (the cluster serves no frontends),
+     * {@link ClusterNotUpgraded} (a node of the cluster is on an older release),
+     * {@link QuotaExceeded} for the served limits (4 per package, 64 per
+     * cluster), {@link OriginTaken} when the origin is held with the other
+     * `served` (remove it first). Serving it to browsers also needs the
+     * certificate and route Calimero Cloud sets up for the domain.
      */
     add(pkg: string, origin: string, passkey?: PasskeyProvider, options?: {
         rpId?: string;
+        served?: boolean;
     }): Promise<PackageOriginAdded>;
     /**
      * Remove `origin` from `pkg`, approved with `passkey` (`__remove_origin`).
@@ -347,6 +384,22 @@ export interface PackageOrigins {
      */
     remove(pkg: string, origin: string, passkey?: PasskeyProvider): Promise<PackageOriginRemoved>;
 }
+/** One served origin (custom domain) of the cluster, as `GET /ops/served-origins` lists it. */
+export interface ServedOrigin {
+    /** `https://host`. */
+    origin: string;
+    /** The origin's host, the name a certificate and a route are for. */
+    host: string;
+    /** The package's app-host label (`{label}.{apps domain}`); the listing names no package. */
+    label: string;
+    addedAt: string;
+}
+/** `GET /ops/served-origins`: every served origin the cluster's log holds. Operator token. */
+export interface ServedOrigins {
+    /** This node had caught up with the system leader. */
+    fresh: boolean;
+    origins: ServedOrigin[];
+}
 /**
  * Where a sign-up or sign-in says it runs. By default the page's origin
  * (`window.location.origin`) when it is not the origin of a node the client
@@ -610,6 +663,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>>;
     /**
@@ -981,6 +1069,12 @@ export declare class CalimeroClient {
     opsApps(page?: PageOptions): Promise<OpsAppsReport>;
     /** `GET /ops/orgs`: each organization's approved releases. Operator token. */
     opsOrgs(page?: PageOptions): Promise<OpsOrgsReport>;
+    /**
+     * `GET /ops/served-origins`: every served origin (custom domain) the
+     * cluster's log holds, with its package's label and no package name or
+     * account. Operator token.
+     */
+    opsServedOrigins(): Promise<ServedOrigins>;
     /**
      * Announce when work on images older than `version` ends: from `after` on,
      * a scope that has not approved it (or newer) starts no new work. Operator

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
@@ -198,7 +200,14 @@ export class CalimeroClient {
                 const { origins } = await this.get(`package-origins/${seg(pkg)}`);
                 return origins ?? [];
             },
-            add: (pkg, origin, passkey, options = {}) => this.confirmed('POST', `package-origins/${seg(pkg)}`, options.rpId === undefined ? { origin } : { origin, rpId: options.rpId }, passkey),
+            add: (pkg, origin, passkey, options = {}) => this.confirmed('POST', `package-origins/${seg(pkg)}`, 
+            // Only the fields set: the node refuses unknown ones, and one that
+            // predates served origins takes a plain add unchanged.
+            {
+                origin,
+                ...(options.rpId === undefined ? {} : { rpId: options.rpId }),
+                ...(options.served ? { served: true } : {}),
+            }, passkey),
             remove: (pkg, origin, passkey) => this.confirmed('DELETE', `package-origins/${seg(pkg)}`, { origin }, passkey),
         };
         const trim = (url) => url.replace(/\/+$/, '');
@@ -608,6 +617,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');
@@ -1176,6 +1248,14 @@ export class CalimeroClient {
     opsOrgs(page = {}) {
         return this.get(`ops/orgs${pageQuery(page)}`);
     }
+    /**
+     * `GET /ops/served-origins`: every served origin (custom domain) the
+     * cluster's log holds, with its package's label and no package name or
+     * account. Operator token.
+     */
+    opsServedOrigins() {
+        return this.get('ops/served-origins');
+    }
     /**
      * Announce when work on images older than `version` ends: from `after` on,
      * a scope that has not approved it (or newer) starts no new work. Operator

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

@@ -117,15 +117,58 @@ export declare class OriginNotRegistered extends CalimeroError {
  * `400 BAD_ORIGIN` or `400 BAD_RP_ID`: the node does not accept the origin a
  * package's manager tried to register (it must be a bare web origin,
  * `scheme://host[:port]`), or the relying-party id given for it (which must
- * fit the origin's host). `code` says which.
+ * fit the origin's host). `code` says which. A served origin (`served: true`)
+ * must also be `https://host` with no port, and not a name under the
+ * cluster's apps domain or its rp-id.
  */
 export declare class BadOrigin extends CalimeroError {
     constructor(code: 'BAD_ORIGIN' | 'BAD_RP_ID', message: string, details?: Record<string, unknown>);
 }
-/** `409 ORIGIN_TAKEN`: the origin is registered already (for this package or another). */
+/**
+ * `409 ORIGIN_TAKEN`: the origin is registered already (for another package,
+ * or for this one with the other `served`: remove it first), or it is one of
+ * the cluster's own (a node's API host, a cluster origin, a frontend it
+ * serves).
+ */
 export declare class OriginTaken extends CalimeroError {
     constructor(message: string, details?: Record<string, unknown>);
 }
+/**
+ * `400 NOT_SERVING`: a served origin (a custom domain, `served: true`) was
+ * asked of a cluster that serves no frontends (merod without
+ * `--apps-domain`). Register the origin unserved, or use a cluster that
+ * serves them.
+ */
+export declare class NotServing extends CalimeroError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * `409 CLUSTER_NOT_UPGRADED`: the change needs every node of the cluster
+ * (replicas, voters and learners) on the node's release or later, and one
+ * is not yet; for instance adding a served origin. Retry once the cluster is
+ * upgraded.
+ */
+export declare class ClusterNotUpgraded 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';
 /**
@@ -146,7 +189,10 @@ export declare class SignUpRefused extends CalimeroError {
     readonly reason: SignUpRefusal;
     constructor(message: string, details?: Record<string, unknown>);
 }
-/** `429 QUOTA_EXCEEDED`: the caller holds as many of something (origins, blobs, ...) as it may. */
+/**
+ * `429 QUOTA_EXCEEDED`: the caller holds as many of something (origins,
+ * served origins per package or per cluster, blobs, ...) as it may.
+ */
 export declare class QuotaExceeded extends CalimeroError {
     constructor(message: string, details?: Record<string, unknown>);
 }

package/dist/cloud-v2/errors.js

@@ -150,7 +150,9 @@ export class OriginNotRegistered extends CalimeroError {
  * `400 BAD_ORIGIN` or `400 BAD_RP_ID`: the node does not accept the origin a
  * package's manager tried to register (it must be a bare web origin,
  * `scheme://host[:port]`), or the relying-party id given for it (which must
- * fit the origin's host). `code` says which.
+ * fit the origin's host). `code` says which. A served origin (`served: true`)
+ * must also be `https://host` with no port, and not a name under the
+ * cluster's apps domain or its rp-id.
  */
 export class BadOrigin extends CalimeroError {
     constructor(code, message, details = {}) {
@@ -158,13 +160,66 @@ export class BadOrigin extends CalimeroError {
         this.name = 'BadOrigin';
     }
 }
-/** `409 ORIGIN_TAKEN`: the origin is registered already (for this package or another). */
+/**
+ * `409 ORIGIN_TAKEN`: the origin is registered already (for another package,
+ * or for this one with the other `served`: remove it first), or it is one of
+ * the cluster's own (a node's API host, a cluster origin, a frontend it
+ * serves).
+ */
 export class OriginTaken extends CalimeroError {
     constructor(message, details = {}) {
         super(409, 'ORIGIN_TAKEN', message, details);
         this.name = 'OriginTaken';
     }
 }
+/**
+ * `400 NOT_SERVING`: a served origin (a custom domain, `served: true`) was
+ * asked of a cluster that serves no frontends (merod without
+ * `--apps-domain`). Register the origin unserved, or use a cluster that
+ * serves them.
+ */
+export class NotServing extends CalimeroError {
+    constructor(message, details = {}) {
+        super(400, 'NOT_SERVING', message, details);
+        this.name = 'NotServing';
+    }
+}
+/**
+ * `409 CLUSTER_NOT_UPGRADED`: the change needs every node of the cluster
+ * (replicas, voters and learners) on the node's release or later, and one
+ * is not yet; for instance adding a served origin. Retry once the cluster is
+ * upgraded.
+ */
+export class ClusterNotUpgraded extends CalimeroError {
+    constructor(message, details = {}) {
+        super(409, 'CLUSTER_NOT_UPGRADED', message, details);
+        this.name = 'ClusterNotUpgraded';
+    }
+}
+/**
+ * `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
@@ -199,7 +254,10 @@ function signUpRefusal(message) {
         return 'org-gone';
     return 'other';
 }
-/** `429 QUOTA_EXCEEDED`: the caller holds as many of something (origins, blobs, ...) as it may. */
+/**
+ * `429 QUOTA_EXCEEDED`: the caller holds as many of something (origins,
+ * served origins per package or per cluster, blobs, ...) as it may.
+ */
 export class QuotaExceeded extends CalimeroError {
     constructor(message, details = {}) {
         super(429, 'QUOTA_EXCEEDED', message, details);
@@ -297,8 +355,14 @@ export function errorFrom(status, body, retryAfterHeader) {
             return new BadOrigin(code, message, details);
         case '409 ORIGIN_TAKEN':
             return new OriginTaken(message, details);
+        case '400 NOT_SERVING':
+            return new NotServing(message, details);
+        case '409 CLUSTER_NOT_UPGRADED':
+            return new ClusterNotUpgraded(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, ClusterNotUpgraded, ConfirmCancelled, ConfirmRequired, IdempotencyMismatch, LoginRequired, ConsentStale, NotFound, NotServing, 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, ServedOrigin, ServedOrigins, 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, ClusterNotUpgraded, ConfirmCancelled, ConfirmRequired, IdempotencyMismatch, LoginRequired, ConsentStale, NotFound, NotServing, 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';