@calimero-network/mero-js 29.2.0 → 29.4.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,11 +60,13 @@ __export(index_exports, {
   OriginTaken: () => OriginTaken,
   PRODUCTION_PROFILE: () => PRODUCTION_PROFILE,
   QuotaExceeded: () => QuotaExceeded,
+  RECOVERY_DOMAIN: () => RECOVERY_DOMAIN,
   RELEASE_VERIFIER: () => RELEASE_VERIFIER,
   ReleaseDeadlineError: () => ReleaseDeadlineError,
   SEALED_CONTENT_TYPE: () => SEALED_CONTENT_TYPE,
   SEALED_PATH: () => SEALED_PATH,
   SealedTransportError: () => SealedTransportError,
+  SignUpRefused: () => SignUpRefused,
   StaleTransportKeyError: () => StaleTransportKeyError,
   TrapError: () => TrapError,
   UnavailableError: () => UnavailableError,
@@ -91,18 +94,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,
@@ -253,20 +262,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) {
@@ -1536,6 +1545,21 @@ var OriginTaken = class extends CalimeroError {
     this.name = "OriginTaken";
   }
 };
+var SignUpRefused = class 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";
+}
 var QuotaExceeded = class extends CalimeroError {
   constructor(message, details = {}) {
     super(429, "QUOTA_EXCEEDED", message, details);
@@ -1610,6 +1634,8 @@ 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":
@@ -1686,6 +1712,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 = {}) {
@@ -2178,23 +2270,33 @@ var CalimeroClient = 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 invite = options.invite ? { invite: options.invite } : {};
     const begin = await this.begin(
       "auth/passkey/register/begin",
-      origin === void 0 ? { name } : { name, origin },
+      origin === void 0 ? { 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 },
+      { 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
@@ -2627,10 +2729,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)}`);