@calimero-network/mero-js 29.2.0 → 29.4.0

package/README.md

@@ -97,13 +97,13 @@ 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`. Adding or removing a passkey and creating an API key are approved with a passkey the account already has.
+- **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`.
 - **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,8 +12,8 @@
 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, TrapError, UnavailableError, WrongNode, errorFrom, } from './errors.js';
-export type { Committed } from './errors.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 type { Committed, SignUpRefusal } from './errors.js';
 export interface CalimeroSession {
     accountId: string;
     sessionToken: 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 {
@@ -338,6 +356,30 @@ export interface PackageOrigins {
 export interface SignInOptions {
     origin?: string | null;
 }
+/**
+ * {@link SignInOptions} for a sign-up, and the invite it is made with: an
+ * organization invite's token (the new account joins the organization at
+ * the invite's role) or a cluster sign-up invite's. A cluster whose policy
+ * is `invite` or `closed` ({@link CalimeroClient.signUpPolicy}) needs one.
+ */
+export interface SignUpOptions extends SignInOptions {
+    invite?: string;
+}
+/**
+ * `GET /sign-up`: who may create an account on the cluster (core's sign-up
+ * policy, read without a session), so a page can say "invite only" before
+ * any passkey prompt.
+ */
+export interface SignUpPolicy {
+    /** `open` (anyone), `invite` (an organization or sign-up invite), `closed` (a sign-up invite only). */
+    policy: 'open' | 'invite' | 'closed';
+    /** Whether an organization invite lets a new person sign up (and join it). */
+    orgInvites: boolean;
+    /** Whether a cluster sign-up invite does (always). */
+    signUpInvites: boolean;
+    /** Whether a sign-up without an invite is refused. */
+    inviteRequired: boolean;
+}
 /**
  * How a call or a view is sent again while the node is unavailable (D70): with
  * the same key, after a backoff that starts at `baseDelayMs` and doubles up to
@@ -520,8 +562,15 @@ export declare class CalimeroClient {
      * origin's relying party (the confirmation's `rpId` is that origin's too)
      * and binds the session to the package the origin is registered for; an
      * unregistered origin is refused with {@link OriginNotRegistered}.
+     *
+     * `invite` ({@link SignUpOptions}) goes on both halves and on the retry,
+     * as the node judges it on each before it spends anything; a sign-up the
+     * cluster's policy refuses, or an unknown, expired or used invite, is
+     * {@link SignUpRefused} (from `begin`, before any passkey is made).
      */
-    signUp(passkey: PasskeyProvider, name: string, options?: SignInOptions): Promise<CalimeroSession>;
+    signUp(passkey: PasskeyProvider, name: string, options?: SignUpOptions): Promise<CalimeroSession>;
+    /** Who may create an account on the cluster (`GET /sign-up`); needs no session. */
+    signUpPolicy(): Promise<SignUpPolicy>;
     /**
      * Sign in with an existing passkey. On a page whose origin is not the
      * cluster's ({@link SignInOptions}), the assertion is made for that
@@ -775,7 +824,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

@@ -14,8 +14,9 @@ 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 { 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, TrapError, UnavailableError, WrongNode, errorFrom, } from './errors.js';
+export { AppError, ArgsTooLarge, BadOrigin, CalimeroError, ConfirmCancelled, ConfirmRequired, IdempotencyMismatch, LoginRequired, ConsentStale, NotFound, OriginNotRegistered, OriginTaken, QuotaExceeded, ReleaseDeadlineError, SignUpRefused, TrapError, UnavailableError, WrongNode, 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}`;
@@ -462,15 +463,25 @@ export class CalimeroClient {
      * origin's relying party (the confirmation's `rpId` is that origin's too)
      * and binds the session to the package the origin is registered for; an
      * unregistered origin is refused with {@link OriginNotRegistered}.
+     *
+     * `invite` ({@link SignUpOptions}) goes on both halves and on the retry,
+     * as the node judges it on each before it spends anything; a sign-up the
+     * cluster's policy refuses, or an unknown, expired or used invite, is
+     * {@link SignUpRefused} (from `begin`, before any passkey is made).
      */
     async signUp(passkey, name, options = {}) {
         const origin = this.pageOrigin(options);
-        const begin = await this.begin('auth/passkey/register/begin', origin === undefined ? { name } : { name, origin }, origin);
+        const invite = options.invite ? { invite: options.invite } : {};
+        const begin = await this.begin('auth/passkey/register/begin', origin === undefined ? { name, ...invite } : { name, origin, ...invite }, origin);
         const registration = await passkey.create(begin.options);
-        const session = await this.postConfirmed('auth/passkey/register/finish', { challengeId: begin.challengeId, registration }, passkey);
+        const session = await this.postConfirmed('auth/passkey/register/finish', { challengeId: begin.challengeId, registration, ...invite }, passkey);
         this.useSession(session);
         return session;
     }
+    /** Who may create an account on the cluster (`GET /sign-up`); needs no session. */
+    signUpPolicy() {
+        return this.get('sign-up');
+    }
     /**
      * Sign in with an existing passkey. On a page whose origin is not the
      * cluster's ({@link SignInOptions}), the assertion is made for that
@@ -916,10 +927,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,26 @@ export declare class BadOrigin extends CalimeroError {
 export declare class OriginTaken 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';
+/**
+ * `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
+ * passkey is made and by `register/finish` before its challenge is spent.
+ * `reason` says why, so a page can say "invite only" or "this invite has
+ * expired" instead of the node's sentence:
+ *
+ * - `invite-only`: the cluster takes new accounts with an invite only.
+ * - `closed`: only a cluster sign-up invite (the operator's or the owner's) admits.
+ * - `unknown-invite`: the invite is not one the cluster knows (mistyped, revoked,
+ *   or used up: a spent invite is gone).
+ * - `expired-invite`: past its expiry, or no use left.
+ * - `org-gone`: the organization the invite was for was deleted.
+ */
+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. */
 export declare class QuotaExceeded extends CalimeroError {
     constructor(message: string, details?: Record<string, unknown>);

package/dist/cloud-v2/errors.js

@@ -165,6 +165,40 @@ export class OriginTaken extends CalimeroError {
         this.name = 'OriginTaken';
     }
 }
+/**
+ * `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
+ * passkey is made and by `register/finish` before its challenge is spent.
+ * `reason` says why, so a page can say "invite only" or "this invite has
+ * expired" instead of the node's sentence:
+ *
+ * - `invite-only`: the cluster takes new accounts with an invite only.
+ * - `closed`: only a cluster sign-up invite (the operator's or the owner's) admits.
+ * - `unknown-invite`: the invite is not one the cluster knows (mistyped, revoked,
+ *   or used up: a spent invite is gone).
+ * - `expired-invite`: past its expiry, or no use left.
+ * - `org-gone`: the organization the invite was for was deleted.
+ */
+export class SignUpRefused extends CalimeroError {
+    constructor(message, details = {}) {
+        super(403, 'SIGN_UP_REFUSED', message, details);
+        this.name = 'SignUpRefused';
+        this.reason = signUpRefusal(message);
+    }
+}
+function signUpRefusal(message) {
+    if (/invite only/.test(message))
+        return 'invite-only';
+    if (/pre-authorized|sign-up invite/.test(message))
+        return 'closed';
+    if (/unknown invite/.test(message))
+        return 'unknown-invite';
+    if (/invite has expired/.test(message))
+        return 'expired-invite';
+    if (/organization is gone/.test(message))
+        return 'org-gone';
+    return 'other';
+}
 /** `429 QUOTA_EXCEEDED`: the caller holds as many of something (origins, blobs, ...) as it may. */
 export class QuotaExceeded extends CalimeroError {
     constructor(message, details = {}) {
@@ -265,6 +299,8 @@ export function errorFrom(status, body, retryAfterHeader) {
             return new OriginTaken(message, details);
         case '429 QUOTA_EXCEEDED':
             return new QuotaExceeded(message, details);
+        case '403 SIGN_UP_REFUSED':
+            return new SignUpRefused(message, details);
         case '412 CONFIRM_REQUIRED':
             return new ConfirmRequired(message, details);
         case '413 ARGS_TOO_LARGE':

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, TrapError, UnavailableError, WrongNode, errorFrom, } from './errors.js';
-export type { Committed } from './errors.js';
-export type { AppInfo, AppXcalls, BlobContent, BlobInfo, DeadLetter, Deployer, DeployerGrant, DeployersInfo, DeploymentInfo, DeploymentOffer, DeploymentOrgs, FrontendManifest, MeInfo, PackageOrigin, PackageOriginAdded, PackageOriginRemoved, PackageOrigins, SignInOptions, PublicDeployment, CallResult, CalimeroClientOptions, CalimeroConnectOptions, CloudEvent, CalimeroSession, PackageInfo, PackageInstalled, CloudRetryOptions, OrgInfo, OrgUpgradeTarget, PresenceEntry, UpgradeRun, ViewResult, } from './client.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 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 { 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, TrapError, UnavailableError, WrongNode, errorFrom, } from './errors.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 { 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);