@calimero-network/mero-js 29.3.0 → 29.5.0

package/README.md

@@ -98,12 +98,13 @@ 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`.
 - **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`. Setting or removing a member or team member, capabilities and invites are approved with the caller's passkey; redeeming an invite is not.
+- **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`.

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;
@@ -131,6 +131,24 @@ export interface OrgInfo extends Record<string, unknown> {
         release: string;
         after: string;
     } | null;
+    /** The recovery key and any recovery under way; absent while the organization has none. */
+    recovery?: OrgRecovery;
+}
+/** An organization's recovery key (core `Org::recovery`). */
+export interface OrgRecovery {
+    /** The key's Ed25519 public half, base64url. */
+    publicKey: string;
+    /** When the owner set it (Unix seconds). */
+    setAt: number;
+    /** A recovery under way: warn every member, the owner first, who may cancel it. */
+    pending: RecoveryTimes & {
+        account: string;
+    } | null;
+}
+/** When a recovery started and the earliest it may finish (Unix seconds). */
+export interface RecoveryTimes {
+    startedAt: number;
+    readyAt: number;
 }
 /** A blob's bytes with the content type the node serves them as. */
 export interface BlobContent {
@@ -284,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 {
@@ -592,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>>;
     /**
@@ -806,7 +878,40 @@ export declare class CalimeroClient {
     /** The app an alias names. */
     alias(alias: string): Promise<string>;
     deleteAlias(alias: string): Promise<void>;
-    createOrg(name: string): Promise<string>;
+    /**
+     * Create an organization. `recoveryKey` (from {@link recoveryPublicKey}) lets
+     * whoever holds its seed recover the organization if its owner loses every
+     * passkey; keep the seed offline ({@link recoverySeedText}).
+     */
+    createOrg(name: string, options?: {
+        recoveryKey?: string;
+    }): Promise<string>;
+    /**
+     * Set or rotate (`publicKey`, from {@link recoveryPublicKey}) or remove
+     * (`null`) the organization's recovery key: its owner only, approved with
+     * `passkey`. A recovery under way is cancelled, and the old seed's
+     * signatures are refused from then on.
+     */
+    setRecoveryKey(org: string, publicKey: string | null, passkey: PasskeyProvider): Promise<void>;
+    /**
+     * Start handing `org` to the signed-in account with the recovery seed,
+     * which signs here and never leaves this process. Finish with
+     * {@link finishRecovery} once `readyAt` has passed; until then the owner may
+     * cancel. A wrong seed (or no organization, or none set) is a `403`.
+     */
+    startRecovery(org: string, seed: Uint8Array): Promise<RecoveryTimes>;
+    /** Cancel the recovery under way: the organization's owner, approved with `passkey`. */
+    cancelRecovery(org: string, passkey: PasskeyProvider): Promise<void>;
+    /**
+     * Finish a recovery this account started, once its delay passed
+     * (`409 RECOVERY_NOT_READY` before, with `readyAt`), approved with this
+     * account's `passkey`. The account becomes the owner; the previous owner
+     * leaves the organization.
+     */
+    finishRecovery(org: string, passkey: PasskeyProvider): Promise<{
+        org: string;
+        previousOwners: string[];
+    }>;
     /** The organization, with the teams this caller reaches or manages. */
     getOrg(org: string): Promise<OrgInfo>;
     /**

package/dist/cloud-v2/client.js

@@ -12,10 +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}`;
@@ -150,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
@@ -607,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');
@@ -926,10 +992,52 @@ export class CalimeroClient {
         await this.delete(`auth/aliases/${seg(alias)}`);
     }
     // ---------------------------------------------------------------- organizations
-    async createOrg(name) {
-        const { orgId } = await this.post('orgs', { name });
+    /**
+     * Create an organization. `recoveryKey` (from {@link recoveryPublicKey}) lets
+     * whoever holds its seed recover the organization if its owner loses every
+     * passkey; keep the seed offline ({@link recoverySeedText}).
+     */
+    async createOrg(name, options = {}) {
+        const body = { name };
+        if (options.recoveryKey !== undefined)
+            body.recoveryKey = options.recoveryKey;
+        const { orgId } = await this.post('orgs', body);
         return orgId;
     }
+    /**
+     * Set or rotate (`publicKey`, from {@link recoveryPublicKey}) or remove
+     * (`null`) the organization's recovery key: its owner only, approved with
+     * `passkey`. A recovery under way is cancelled, and the old seed's
+     * signatures are refused from then on.
+     */
+    async setRecoveryKey(org, publicKey, passkey) {
+        await this.postConfirmed(`orgs/${seg(org)}/recovery`, { publicKey }, passkey);
+    }
+    /**
+     * Start handing `org` to the signed-in account with the recovery seed,
+     * which signs here and never leaves this process. Finish with
+     * {@link finishRecovery} once `readyAt` has passed; until then the owner may
+     * cancel. A wrong seed (or no organization, or none set) is a `403`.
+     */
+    async startRecovery(org, seed) {
+        const account = (await this.me()).accountId;
+        const nonce = b64url(crypto.getRandomValues(new Uint8Array(16)));
+        const signature = await signRecovery(seed, org, account, nonce);
+        return this.post(`orgs/${seg(org)}/recovery/start`, { nonce, signature });
+    }
+    /** Cancel the recovery under way: the organization's owner, approved with `passkey`. */
+    async cancelRecovery(org, passkey) {
+        await this.postConfirmed(`orgs/${seg(org)}/recovery/cancel`, {}, passkey);
+    }
+    /**
+     * Finish a recovery this account started, once its delay passed
+     * (`409 RECOVERY_NOT_READY` before, with `readyAt`), approved with this
+     * account's `passkey`. The account becomes the owner; the previous owner
+     * leaves the organization.
+     */
+    finishRecovery(org, passkey) {
+        return this.postConfirmed(`orgs/${seg(org)}/recovery/finish`, {}, passkey);
+    }
     /** The organization, with the teams this caller reaches or manages. */
     getOrg(org) {
         return this.get(`orgs/${seg(org)}`);

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,12 +1,13 @@
 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, 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';
+export { MAX_RECOVERY_NONCE_BYTES, RECOVERY_DOMAIN, newRecoverySeed, parseRecoverySeed, recoveryMessage, recoveryPublicKey, recoverySeedText, signRecovery, } from './recovery.js';
 export type { AssertionJSON, PasskeyProvider, RegistrationJSON } from './passkey.js';
 export { MAX_REPORT_PAGE, RELEASE_VERIFIER, compareVersions, confirmationCode, consentReturn, pageQuery, pendingApprovalsFrom, publisherBindingBytes, publisherBindingMessage, releaseConsent, releaseNotesUrl, stalledBy, upgradeConsent, verifyReleaseUrl, withdrawConsent, } from './approvals.js';
 export type { ActorKind, AppsReport, Authority, ClusterRelease, ConsentReleaseModel, ConsentRequest, ConsentResult, ConsentScope, ConsentStarted, ConsentStatus, OpenConsentOptions, Governance, LastUpgrade, OpsAppsReport, OpsOrgsReport, PageOptions, PendingApprovals, PendingRelease, PendingUpgrade, PublisherBindingInfo, PublisherProof, ReleaseDeadline, ReleaseRules, ReportScope, ReportedApp, ReportedBundle, ReportedRelease, ReportedReplica, UpgradeAuthority, } from './approvals.js';

package/dist/cloud-v2/index.js

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

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

@@ -0,0 +1,23 @@
+/**
+ * An organization's recovery key (core `docs/specs/org-recovery.md`): an
+ * Ed25519 key whose 32-byte seed the owner keeps offline. The node stores only
+ * the public half; the seed signs, here and never on a node, the statement
+ * that hands the organization to one account. Byte-for-byte core's
+ * `calimero_identity::recovery`.
+ */
+/** What a recovery signature covers before the organization, the account and the nonce. */
+export declare const RECOVERY_DOMAIN = "calimero.org-recovery.v1\0";
+/** The longest nonce a recovery carries, in bytes (core's `MAX_RECOVERY_NONCE_BYTES`). */
+export declare const MAX_RECOVERY_NONCE_BYTES = 64;
+/** A new random seed. */
+export declare function newRecoverySeed(): Uint8Array;
+/** The seed as people write it down: 64 hex digits in eight groups of eight, joined by `-`. */
+export declare function recoverySeedText(seed: Uint8Array): string;
+/** A seed from its written form: 64 hex digits; `-`, whitespace and case are ignored. */
+export declare function parseRecoverySeed(text: string): Uint8Array;
+/** The bytes a recovery signs: `"calimero.org-recovery.v1\0" || org || 0 || account || 0 || nonce`. */
+export declare function recoveryMessage(org: string, account: string, nonce: string): Uint8Array;
+/** The seed's public key, base64url: what the organization stores. */
+export declare function recoveryPublicKey(seed: Uint8Array): Promise<string>;
+/** The seed's signature (base64url) handing `org` to `account` under `nonce`. */
+export declare function signRecovery(seed: Uint8Array, org: string, account: string, nonce: string): Promise<string>;

package/dist/cloud-v2/recovery.js

@@ -0,0 +1,70 @@
+/**
+ * An organization's recovery key (core `docs/specs/org-recovery.md`): an
+ * Ed25519 key whose 32-byte seed the owner keeps offline. The node stores only
+ * the public half; the seed signs, here and never on a node, the statement
+ * that hands the organization to one account. Byte-for-byte core's
+ * `calimero_identity::recovery`.
+ */
+import { b64url } from './passkey.js';
+/** What a recovery signature covers before the organization, the account and the nonce. */
+export const RECOVERY_DOMAIN = 'calimero.org-recovery.v1\0';
+/** The longest nonce a recovery carries, in bytes (core's `MAX_RECOVERY_NONCE_BYTES`). */
+export const MAX_RECOVERY_NONCE_BYTES = 64;
+/** PKCS#8 prefix of an Ed25519 private key; the 32-byte seed follows. */
+const PKCS8_ED25519 = Uint8Array.from([
+    0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x04, 0x22, 0x04, 0x20,
+]);
+/** A new random seed. */
+export function newRecoverySeed() {
+    return crypto.getRandomValues(new Uint8Array(32));
+}
+/** The seed as people write it down: 64 hex digits in eight groups of eight, joined by `-`. */
+export function recoverySeedText(seed) {
+    checkSeed(seed);
+    const hex = Array.from(seed, (b) => b.toString(16).padStart(2, '0')).join('');
+    const groups = [];
+    for (let i = 0; i < hex.length; i += 8)
+        groups.push(hex.slice(i, i + 8));
+    return groups.join('-');
+}
+/** A seed from its written form: 64 hex digits; `-`, whitespace and case are ignored. */
+export function parseRecoverySeed(text) {
+    const digits = text.replace(/[-\s]/g, '');
+    if (!/^[0-9a-fA-F]{64}$/.test(digits))
+        throw new Error('a recovery seed is 64 hex digits');
+    return Uint8Array.from({ length: 32 }, (_, i) => parseInt(digits.slice(2 * i, 2 * i + 2), 16));
+}
+/** The bytes a recovery signs: `"calimero.org-recovery.v1\0" || org || 0 || account || 0 || nonce`. */
+export function recoveryMessage(org, account, nonce) {
+    return new TextEncoder().encode(`${RECOVERY_DOMAIN}${org}\0${account}\0${nonce}`);
+}
+/** The seed's public key, base64url: what the organization stores. */
+export async function recoveryPublicKey(seed) {
+    const key = await privateKey(seed, true);
+    const jwk = await crypto.subtle.exportKey('jwk', key);
+    if (!jwk.x)
+        throw new Error('this runtime cannot export an Ed25519 public key');
+    return jwk.x;
+}
+/** The seed's signature (base64url) handing `org` to `account` under `nonce`. */
+export async function signRecovery(seed, org, account, nonce) {
+    const nonceBytes = new TextEncoder().encode(nonce).length;
+    if (nonceBytes === 0 || nonceBytes > MAX_RECOVERY_NONCE_BYTES) {
+        throw new Error(`a recovery nonce is 1 to ${MAX_RECOVERY_NONCE_BYTES} bytes`);
+    }
+    const key = await privateKey(seed, false);
+    const sig = await crypto.subtle.sign('Ed25519', key, buf(recoveryMessage(org, account, nonce)));
+    return b64url(new Uint8Array(sig));
+}
+function checkSeed(seed) {
+    if (seed.length !== 32)
+        throw new Error('a recovery seed is 32 bytes');
+}
+function privateKey(seed, extractable) {
+    checkSeed(seed);
+    const pkcs8 = new Uint8Array(PKCS8_ED25519.length + 32);
+    pkcs8.set(PKCS8_ED25519);
+    pkcs8.set(seed, PKCS8_ED25519.length);
+    return crypto.subtle.importKey('pkcs8', buf(pkcs8), { name: 'Ed25519' }, extractable, ['sign']);
+}
+const buf = (b) => b.buffer.slice(b.byteOffset, b.byteOffset + b.byteLength);