@calimero-network/mero-js 29.3.0 → 29.4.0

package/README.md

@@ -103,7 +103,7 @@ Pinned measurements go through `policy.verifyQuote` (`createQuoteVerifier`).
 - **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

@@ -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 {
@@ -806,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,6 +14,7 @@ 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, SignUpRefused, TrapError, UnavailableError, WrongNode, errorFrom, } from './errors.js';
 /** A deployer's key, as `GET /deployers` lists it and `DELETE /deployers/{key}` takes it. */
@@ -926,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/index.d.ts

@@ -3,10 +3,11 @@ 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 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, 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

@@ -3,5 +3,6 @@ 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 { 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);