@waaskey/sdk 0.4.0 → 0.4.2

package/dist/index.d.cts

@@ -1044,6 +1044,23 @@ interface WalletBackupParams {
         salt: string;
         credentialId: string;
     };
+    /**
+     * Enrol the passkey as a recovery FACTOR **in place of** the recovery code (#511).
+     *
+     * The wrap (`passkey` above) decides what can OPEN the backup; a factor decides what the server
+     * demands before releasing it. Enrolling the passkey as a factor is the difference between "the
+     * code is still mandatory" and a user who never has to write one down.
+     *
+     * It REPLACES `recovery_code` rather than adding to it, because the gate is an AND of every enrolled
+     * factor: enrolling both would mean losing EITHER the code or the passkey makes the wallet
+     * unrecoverable — strictly worse than either alone.
+     *
+     * Requires `passkey`, and that credential must ALREADY be registered with the platform (the API
+     * refuses an unknown credential id — a factor nobody can satisfy is a lock-out discovered at the
+     * worst possible moment). Defaults to false: trading a written code for a synced authenticator is
+     * the app's call, not the SDK's.
+     */
+    passkeyFactor?: boolean;
 }
 /** Options for `wallets.joinCeremony(...)` (#349). */
 interface JoinCeremonyOptions {
@@ -1679,6 +1696,23 @@ interface RecoveryChallengeResponse {
      * and single-use with this session — feed it to `passkeyFactorVerification`.
      */
     passkeyChallenge?: string;
+    /**
+     * The non-secret inputs that reproduce the backup's PRF key — present only when the backup carries
+     * a `passkey_prf` wrap (#510).
+     *
+     * Pass `salt` + `credentialId` to `PasskeyPrfSecretProvider.unlock(...)` to obtain the
+     * `passkeySecret` that {@link RecoverParams} takes. They arrive HERE, on the challenge, because the
+     * salt is an INPUT to the authenticator ceremony while the wraps themselves are released only after
+     * every factor passes — so a device that lost its local storage (which is the recovery case) would
+     * otherwise have no way to use its passkey at all.
+     *
+     * Neither value is a secret: the credential id is public by WebAuthn design, and the salt is
+     * meaningless without the authenticator and a user-verified ceremony.
+     */
+    passkeyWrap?: {
+        salt: string;
+        credentialId: string;
+    };
 }
 /**
  * How the key that opens a backup was wrapped (backend `RecoveryKeyWrap`, #510).
@@ -1737,6 +1771,23 @@ interface RegisterRecoveryParams {
         salt: string;
         credentialId: string;
     };
+    /**
+     * Enrol the passkey as a recovery FACTOR **in place of** the recovery code (#511).
+     *
+     * The wrap (`passkey` above) decides what can OPEN the backup; a factor decides what the server
+     * demands before releasing it. Enrolling the passkey as a factor is the difference between "the
+     * code is still mandatory" and a user who never has to write one down.
+     *
+     * It REPLACES `recovery_code` rather than adding to it, because the gate is an AND of every enrolled
+     * factor: enrolling both would mean losing EITHER the code or the passkey makes the wallet
+     * unrecoverable — strictly worse than either alone.
+     *
+     * Requires `passkey`, and that credential must ALREADY be registered with the platform (the API
+     * refuses an unknown credential id — a factor nobody can satisfy is a lock-out discovered at the
+     * worst possible moment). Defaults to false: trading a written code for a synced authenticator is
+     * the app's call, not the SDK's.
+     */
+    passkeyFactor?: boolean;
 }
 /** Parameters for `recovery.recover(...)` / `recovery.retrieveShare(...)`. */
 interface RecoverParams {

package/dist/index.d.ts

@@ -1044,6 +1044,23 @@ interface WalletBackupParams {
         salt: string;
         credentialId: string;
     };
+    /**
+     * Enrol the passkey as a recovery FACTOR **in place of** the recovery code (#511).
+     *
+     * The wrap (`passkey` above) decides what can OPEN the backup; a factor decides what the server
+     * demands before releasing it. Enrolling the passkey as a factor is the difference between "the
+     * code is still mandatory" and a user who never has to write one down.
+     *
+     * It REPLACES `recovery_code` rather than adding to it, because the gate is an AND of every enrolled
+     * factor: enrolling both would mean losing EITHER the code or the passkey makes the wallet
+     * unrecoverable — strictly worse than either alone.
+     *
+     * Requires `passkey`, and that credential must ALREADY be registered with the platform (the API
+     * refuses an unknown credential id — a factor nobody can satisfy is a lock-out discovered at the
+     * worst possible moment). Defaults to false: trading a written code for a synced authenticator is
+     * the app's call, not the SDK's.
+     */
+    passkeyFactor?: boolean;
 }
 /** Options for `wallets.joinCeremony(...)` (#349). */
 interface JoinCeremonyOptions {
@@ -1679,6 +1696,23 @@ interface RecoveryChallengeResponse {
      * and single-use with this session — feed it to `passkeyFactorVerification`.
      */
     passkeyChallenge?: string;
+    /**
+     * The non-secret inputs that reproduce the backup's PRF key — present only when the backup carries
+     * a `passkey_prf` wrap (#510).
+     *
+     * Pass `salt` + `credentialId` to `PasskeyPrfSecretProvider.unlock(...)` to obtain the
+     * `passkeySecret` that {@link RecoverParams} takes. They arrive HERE, on the challenge, because the
+     * salt is an INPUT to the authenticator ceremony while the wraps themselves are released only after
+     * every factor passes — so a device that lost its local storage (which is the recovery case) would
+     * otherwise have no way to use its passkey at all.
+     *
+     * Neither value is a secret: the credential id is public by WebAuthn design, and the salt is
+     * meaningless without the authenticator and a user-verified ceremony.
+     */
+    passkeyWrap?: {
+        salt: string;
+        credentialId: string;
+    };
 }
 /**
  * How the key that opens a backup was wrapped (backend `RecoveryKeyWrap`, #510).
@@ -1737,6 +1771,23 @@ interface RegisterRecoveryParams {
         salt: string;
         credentialId: string;
     };
+    /**
+     * Enrol the passkey as a recovery FACTOR **in place of** the recovery code (#511).
+     *
+     * The wrap (`passkey` above) decides what can OPEN the backup; a factor decides what the server
+     * demands before releasing it. Enrolling the passkey as a factor is the difference between "the
+     * code is still mandatory" and a user who never has to write one down.
+     *
+     * It REPLACES `recovery_code` rather than adding to it, because the gate is an AND of every enrolled
+     * factor: enrolling both would mean losing EITHER the code or the passkey makes the wallet
+     * unrecoverable — strictly worse than either alone.
+     *
+     * Requires `passkey`, and that credential must ALREADY be registered with the platform (the API
+     * refuses an unknown credential id — a factor nobody can satisfy is a lock-out discovered at the
+     * worst possible moment). Defaults to false: trading a written code for a synced authenticator is
+     * the app's call, not the SDK's.
+     */
+    passkeyFactor?: boolean;
 }
 /** Parameters for `recovery.recover(...)` / `recovery.retrieveShare(...)`. */
 interface RecoverParams {

package/dist/index.js

@@ -484,6 +484,54 @@ var Onramp = class {
   }
 };
 
+// src/passkey/assertion.ts
+function isPasskeyAssertionSupported() {
+  return typeof globalThis.navigator !== "undefined" && typeof globalThis.navigator.credentials !== "undefined";
+}
+async function defaultAssertionCeremony() {
+  let mod;
+  try {
+    mod = await import('@simplewebauthn/browser');
+  } catch {
+    throw new WaaskeyError('Passkey step-up requires "@simplewebauthn/browser" installed, or pass a custom ceremony.', "unsupported");
+  }
+  return {
+    get: (options) => mod.startAuthentication({ optionsJSON: options })
+  };
+}
+async function getSigningAssertion(challenge, options = {}) {
+  if (options.ceremony === void 0 && !isPasskeyAssertionSupported()) {
+    throw new WaaskeyError("Passkey step-up is not available in this runtime (no WebAuthn API).", "unsupported");
+  }
+  const ceremony = options.ceremony ?? await defaultAssertionCeremony();
+  const rpId = options.rpId ?? (typeof location === "undefined" ? void 0 : location.hostname);
+  const requestOptions = {
+    challenge,
+    userVerification: "required",
+    ...rpId ? { rpId } : {},
+    ...options.credentialId ? { allowCredentials: [{ id: options.credentialId, type: "public-key" }] } : {}
+  };
+  try {
+    return await ceremony.get(requestOptions);
+  } catch (cause) {
+    if (cause instanceof WaaskeyError) throw cause;
+    const msg = cause instanceof Error ? cause.message : String(cause);
+    if (/cancel|abort|not allowed|user gesture/i.test(msg)) {
+      throw new WaaskeyError("Passkey authentication was cancelled by the user.", "aborted", { cause });
+    }
+    throw new WaaskeyError("Passkey step-up assertion failed.", "unsupported", { cause });
+  }
+}
+
+// src/passkey/recovery-factor.ts
+function passkeyFactorEnrollment(credentialId) {
+  return { type: "passkey", credential: credentialId };
+}
+async function passkeyFactorVerification(challenge, options = {}) {
+  const assertion = await getSigningAssertion(challenge, options);
+  return { type: "passkey", token: JSON.stringify(assertion) };
+}
+
 // src/storage/crypto.ts
 var PBKDF2_ITERATIONS = 21e4;
 var PBKDF2_HASH = "SHA-256";
@@ -685,8 +733,12 @@ var Recovery = class {
 async function buildRecoveryRegistration(params) {
   const recoveryCode = params.recoveryCode ?? generateRecoveryCode();
   const backup = params.passkey ? await sealRecoveryBackup(params.share, recoveryCode, params.passkey) : { ciphertext: await sealWithPassword(recoveryCode, params.share), keyWraps: void 0 };
+  if (params.passkeyFactor && !params.passkey) {
+    throw new WaaskeyError("passkeyFactor requires `passkey` \u2014 a factor for a credential this backup cannot open would be a lock-out.", "validation");
+  }
+  const strongFactor = params.passkeyFactor ? passkeyFactorEnrollment(params.passkey.credentialId) : { type: "recovery_code", credential: await sha256Hex(recoveryCode) };
   const factors = [
-    { type: "recovery_code", credential: await sha256Hex(recoveryCode) },
+    strongFactor,
     { type: "totp", credential: params.totpSecret },
     { type: "email_otp", credential: params.email },
     ...params.extraFactors ?? []
@@ -1169,45 +1221,6 @@ function deserializeShare(blob) {
   };
 }
 
-// src/passkey/assertion.ts
-function isPasskeyAssertionSupported() {
-  return typeof globalThis.navigator !== "undefined" && typeof globalThis.navigator.credentials !== "undefined";
-}
-async function defaultAssertionCeremony() {
-  let mod;
-  try {
-    mod = await import('@simplewebauthn/browser');
-  } catch {
-    throw new WaaskeyError('Passkey step-up requires "@simplewebauthn/browser" installed, or pass a custom ceremony.', "unsupported");
-  }
-  return {
-    get: (options) => mod.startAuthentication({ optionsJSON: options })
-  };
-}
-async function getSigningAssertion(challenge, options = {}) {
-  if (options.ceremony === void 0 && !isPasskeyAssertionSupported()) {
-    throw new WaaskeyError("Passkey step-up is not available in this runtime (no WebAuthn API).", "unsupported");
-  }
-  const ceremony = options.ceremony ?? await defaultAssertionCeremony();
-  const rpId = options.rpId ?? (typeof location === "undefined" ? void 0 : location.hostname);
-  const requestOptions = {
-    challenge,
-    userVerification: "required",
-    ...rpId ? { rpId } : {},
-    ...options.credentialId ? { allowCredentials: [{ id: options.credentialId, type: "public-key" }] } : {}
-  };
-  try {
-    return await ceremony.get(requestOptions);
-  } catch (cause) {
-    if (cause instanceof WaaskeyError) throw cause;
-    const msg = cause instanceof Error ? cause.message : String(cause);
-    if (/cancel|abort|not allowed|user gesture/i.test(msg)) {
-      throw new WaaskeyError("Passkey authentication was cancelled by the user.", "aborted", { cause });
-    }
-    throw new WaaskeyError("Passkey step-up assertion failed.", "unsupported", { cause });
-  }
-}
-
 // src/wallet.ts
 var DEVICE_ROLE = "device";
 var Wallet = class {
@@ -2359,15 +2372,6 @@ function resolveSink(analytics, http) {
   return analytics ?? new HttpAnalyticsSink(http);
 }
 
-// src/passkey/recovery-factor.ts
-function passkeyFactorEnrollment(credentialId) {
-  return { type: "passkey", credential: credentialId };
-}
-async function passkeyFactorVerification(challenge, options = {}) {
-  const assertion = await getSigningAssertion(challenge, options);
-  return { type: "passkey", token: JSON.stringify(assertion) };
-}
-
 // src/mpc/wasm-core.ts
 var WasmMpcCore = class {
   constructor(load) {