@calimero-network/mero-js 29.4.0 → 29.5.0

package/dist/index.cjs

@@ -62,6 +62,7 @@ __export(index_exports, {
   QuotaExceeded: () => QuotaExceeded,
   RECOVERY_DOMAIN: () => RECOVERY_DOMAIN,
   RELEASE_VERIFIER: () => RELEASE_VERIFIER,
+  RecoveryNotReady: () => RecoveryNotReady,
   ReleaseDeadlineError: () => ReleaseDeadlineError,
   SEALED_CONTENT_TYPE: () => SEALED_CONTENT_TYPE,
   SEALED_PATH: () => SEALED_PATH,
@@ -71,6 +72,7 @@ __export(index_exports, {
   TrapError: () => TrapError,
   UnavailableError: () => UnavailableError,
   WrongNode: () => WrongNode,
+  WrongRecoveryCode: () => WrongRecoveryCode,
   agentKeyBinding: () => agentKeyBinding,
   agentQuoteVerifier: () => agentQuoteVerifier,
   attestAgent: () => attestAgent,
@@ -1545,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);
@@ -1634,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":
@@ -1980,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}. */
@@ -2416,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");