@calimero-network/mero-js 29.3.0 → 29.5.0

package/dist/index.cjs

@@ -50,6 +50,7 @@ __export(index_exports, {
   IdempotencyMismatch: () => IdempotencyMismatch,
   KMS_RELEASE_SIGNER: () => KMS_RELEASE_SIGNER,
   LoginRequired: () => LoginRequired,
+  MAX_RECOVERY_NONCE_BYTES: () => MAX_RECOVERY_NONCE_BYTES,
   MAX_REPORT_PAGE: () => MAX_REPORT_PAGE,
   MOCK_QUOTE_HEADER: () => MOCK_QUOTE_HEADER,
   NODE_RELEASE_SIGNER: () => NODE_RELEASE_SIGNER,
@@ -59,7 +60,9 @@ __export(index_exports, {
   OriginTaken: () => OriginTaken,
   PRODUCTION_PROFILE: () => PRODUCTION_PROFILE,
   QuotaExceeded: () => QuotaExceeded,
+  RECOVERY_DOMAIN: () => RECOVERY_DOMAIN,
   RELEASE_VERIFIER: () => RELEASE_VERIFIER,
+  RecoveryNotReady: () => RecoveryNotReady,
   ReleaseDeadlineError: () => ReleaseDeadlineError,
   SEALED_CONTENT_TYPE: () => SEALED_CONTENT_TYPE,
   SEALED_PATH: () => SEALED_PATH,
@@ -69,6 +72,7 @@ __export(index_exports, {
   TrapError: () => TrapError,
   UnavailableError: () => UnavailableError,
   WrongNode: () => WrongNode,
+  WrongRecoveryCode: () => WrongRecoveryCode,
   agentKeyBinding: () => agentKeyBinding,
   agentQuoteVerifier: () => agentQuoteVerifier,
   attestAgent: () => attestAgent,
@@ -92,18 +96,24 @@ __export(index_exports, {
   fromB64url: () => fromB64url,
   frontendManifest: () => frontendManifest,
   generateOwnerKey: () => generateOwnerKey,
+  newRecoverySeed: () => newRecoverySeed,
   orgCapabilities: () => orgCapabilities,
   ownerPublicKey: () => ownerPublicKey,
   pageDeployment: () => pageDeployment,
   pageQuery: () => pageQuery,
+  parseRecoverySeed: () => parseRecoverySeed,
   pendingApprovalsFrom: () => pendingApprovalsFrom,
   provisionAgent: () => provisionAgent,
   provisionInfo: () => provisionInfo,
   publisherBindingBytes: () => publisherBindingBytes,
   publisherBindingMessage: () => publisherBindingMessage,
+  recoveryMessage: () => recoveryMessage,
+  recoveryPublicKey: () => recoveryPublicKey,
+  recoverySeedText: () => recoverySeedText,
   releaseAgent: () => releaseAgent,
   releaseConsent: () => releaseConsent,
   releaseNotesUrl: () => releaseNotesUrl,
+  signRecovery: () => signRecovery,
   stalledBy: () => stalledBy,
   transportKeyBinding: () => transportKeyBinding,
   trustSignedRelease: () => trustSignedRelease,
@@ -254,20 +264,20 @@ async function x25519KeyPair(secret) {
     const publicKey = new Uint8Array(await crypto.subtle.exportKey("raw", pair.publicKey));
     return { privateKey: pair.privateKey, publicKey };
   }
-  const privateKey = await crypto.subtle.importKey(
+  const privateKey2 = await crypto.subtle.importKey(
     "pkcs8",
     concat(PKCS8_X25519_PREFIX, secret),
     { name: "X25519" },
     true,
     ["deriveBits"]
   );
-  const jwk = await crypto.subtle.exportKey("jwk", privateKey);
-  return { privateKey, publicKey: base64UrlDecode(jwk.x) };
+  const jwk = await crypto.subtle.exportKey("jwk", privateKey2);
+  return { privateKey: privateKey2, publicKey: base64UrlDecode(jwk.x) };
 }
-async function dh(privateKey, publicKey) {
+async function dh(privateKey2, publicKey) {
   const peer = await crypto.subtle.importKey("raw", publicKey, { name: "X25519" }, false, []);
   return new Uint8Array(
-    await crypto.subtle.deriveBits({ name: "X25519", public: peer }, privateKey, 256)
+    await crypto.subtle.deriveBits({ name: "X25519", public: peer }, privateKey2, 256)
   );
 }
 function noiseNonce(n) {
@@ -1537,6 +1547,19 @@ var OriginTaken = class extends CalimeroError {
     this.name = "OriginTaken";
   }
 };
+var RecoveryNotReady = class extends CalimeroError {
+  constructor(message, details = {}) {
+    super(409, "RECOVERY_NOT_READY", message, details);
+    this.name = "RecoveryNotReady";
+    this.readyAt = typeof details.readyAt === "number" ? details.readyAt : void 0;
+  }
+};
+var WrongRecoveryCode = class extends CalimeroError {
+  constructor(message, details = {}) {
+    super(401, "UNAUTHENTICATED", message || "unknown or used recovery code", details);
+    this.name = "WrongRecoveryCode";
+  }
+};
 var SignUpRefused = class extends CalimeroError {
   constructor(message, details = {}) {
     super(403, "SIGN_UP_REFUSED", message, details);
@@ -1626,6 +1649,8 @@ 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":
@@ -1704,6 +1729,72 @@ function browserPasskey() {
   };
 }
 
+// src/cloud-v2/recovery.ts
+var RECOVERY_DOMAIN = "calimero.org-recovery.v1\0";
+var MAX_RECOVERY_NONCE_BYTES = 64;
+var PKCS8_ED25519 = Uint8Array.from([
+  48,
+  46,
+  2,
+  1,
+  0,
+  48,
+  5,
+  6,
+  3,
+  43,
+  101,
+  112,
+  4,
+  34,
+  4,
+  32
+]);
+function newRecoverySeed() {
+  return crypto.getRandomValues(new Uint8Array(32));
+}
+function recoverySeedText(seed) {
+  checkSeed(seed);
+  const hex2 = Array.from(seed, (b) => b.toString(16).padStart(2, "0")).join("");
+  const groups = [];
+  for (let i = 0; i < hex2.length; i += 8) groups.push(hex2.slice(i, i + 8));
+  return groups.join("-");
+}
+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));
+}
+function recoveryMessage(org, account, nonce2) {
+  return new TextEncoder().encode(`${RECOVERY_DOMAIN}${org}\0${account}\0${nonce2}`);
+}
+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;
+}
+async function signRecovery(seed, org, account, nonce2) {
+  const nonceBytes = new TextEncoder().encode(nonce2).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, buf2(recoveryMessage(org, account, nonce2)));
+  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", buf2(pkcs8), { name: "Ed25519" }, extractable, ["sign"]);
+}
+var buf2 = (b) => b.buffer.slice(b.byteOffset, b.byteOffset + b.byteLength);
+
 // src/cloud-v2/approvals.ts
 var MAX_REPORT_PAGE = 100;
 function pageQuery(page = {}) {
@@ -1906,8 +1997,9 @@ function retryDelayMs(retry, options) {
   return Math.min(options.baseDelayMs * 2 ** retry, options.maxDelayMs);
 }
 function ceremony(path) {
-  return path === "auth/refresh" || path.startsWith("auth/passkey/");
+  return path === "auth/refresh" || path.startsWith("auth/passkey/") || RECOVERY_CEREMONIES.has(path);
 }
+var RECOVERY_CEREMONIES = /* @__PURE__ */ new Set(["auth/recovery/begin", "auth/recovery/start", "auth/recovery/finish"]);
 var CalimeroClient = class _CalimeroClient {
   constructor(options) {
     /** The one in use: an index into {@link nodeUrls}. */
@@ -2342,6 +2434,71 @@ var CalimeroClient = 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");
@@ -2655,10 +2812,51 @@ var CalimeroClient = 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 !== void 0) 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 nonce2 = b64url(crypto.getRandomValues(new Uint8Array(16)));
+    const signature = await signRecovery(seed, org, account, nonce2);
+    return this.post(`orgs/${seg(org)}/recovery/start`, { nonce: nonce2, 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)}`);