@learncard/sss-key-manager 0.2.4 → 0.2.6

package/dist/sss-key-manager.esm.js

@@ -24025,7 +24025,13 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
       state: external_exports.enum(["none", "enabled", "locked", "stale"]),
       enabled: external_exports.boolean(),
       attemptsRemaining: external_exports.number().int().nonnegative(),
-      salt: external_exports.string().optional()
+      salt: external_exports.string().optional(),
+      /**
+       * Verified wrong PIN entries against the current PIN (successful releases and
+       * unresolved reservations are not counted). Omitted when the server cannot tell,
+       * e.g. legacy records that predate the verified counter.
+       */
+      wrongAttempts: external_exports.number().int().nonnegative().optional()
     });
     var BITSTRING_STATUS_PURPOSES = ["revocation", "suspension"];
     var DEFAULT_BITSTRING_STATUS_LIST_SIZE = 131072;
@@ -27532,6 +27538,15 @@ var EscrowPinLockedError = class extends Error {
     this.name = "EscrowPinLockedError";
   }
 };
+var PinSignInStaleError = class extends Error {
+  static {
+    __name(this, "PinSignInStaleError");
+  }
+  constructor() {
+    super("Your account changed while signing in. Try again.");
+    this.name = "PinSignInStaleError";
+  }
+};
 
 // src/escrow-pin.ts
 var PIN_MIN_LENGTH = 6;
@@ -27790,6 +27805,15 @@ var EscrowRequestError = class extends Error {
     __name(this, "EscrowRequestError");
   }
 };
+var DuplicateShareCoordinateError = class extends Error {
+  static {
+    __name(this, "DuplicateShareCoordinateError");
+  }
+  constructor() {
+    super("Stored shares have the same coordinate and cannot be combined");
+    this.name = "DuplicateShareCoordinateError";
+  }
+};
 var fetchAuthShareRaw = /* @__PURE__ */ __name(async (serverUrl, token, providerType, shareVersion, tenantId) => {
   const response = await fetch(`${serverUrl}/keys/auth-share`, {
     method: "POST",
@@ -28385,7 +28409,7 @@ function createSSSStrategy(config) {
     assertCurrent();
     return result;
   }, "fetchAuthorityState");
-  const enrollEscrow = /* @__PURE__ */ __name(async (token, providerType, privateKey, primaryDid, shares, shareVersion, signDidAuthVp, verifiedKey, pinMaterial, clearPin = false, assertCurrent = guardedStorage().assertCurrent, recoveryEmail = "", recoveryLanguage = "") => {
+  const enrollEscrow = /* @__PURE__ */ __name(async (token, providerType, privateKey, primaryDid, shares, shareVersion, signDidAuthVp, verifiedKey, pinMaterial, clearPin = false, assertCurrent = guardedStorage().assertCurrent, recoveryEmail = "", recoveryLanguage = "", expectedPinCharges) => {
     if (!config.escrow?.enabled) throw new Error("Escrow enrollment is disabled");
     if (!signDidAuthVp) throw new Error("DID proof signing is required for escrow enrollment");
     const identity = verifiedKey ?? await fetchVerifiedEnclaveKey();
@@ -28444,7 +28468,8 @@ function createSSSStrategy(config) {
         enclaveKeyId: keyId,
         ...pinMaterial ? { pinSalt: pinMaterial.pinSalt } : {},
         ...(signedIntent ? signedIntent.intent.pinAction === "clear" : clearPin) ? { clearPin: true } : {},
-        ...signedIntent ? { signedIntent, sourceEnvelope: authority?.envelope ?? null } : {}
+        ...signedIntent ? { signedIntent, sourceEnvelope: authority?.envelope ?? null } : {},
+        ...expectedPinCharges ? { expectedPinCharges } : {}
       })
     });
     if (signedIntent) {
@@ -28457,11 +28482,11 @@ function createSSSStrategy(config) {
       verifiedEscrowEnvelope = committed.envelope ?? void 0;
     }
   }, "enrollEscrow");
-  const tryEnrollEscrow = /* @__PURE__ */ __name(async (...args) => {
-    if (!config.escrow?.enabled) return false;
+  const attemptEnrollEscrow = /* @__PURE__ */ __name(async (...args) => {
+    if (!config.escrow?.enabled) return { enrolled: false };
     try {
       await enrollEscrow(...args);
-      return true;
+      return { enrolled: true };
     } catch (err) {
       try {
         if (config.onEscrowError) config.onEscrowError(err);
@@ -28469,9 +28494,10 @@ function createSSSStrategy(config) {
       } catch {
         console.warn("SSS: escrow error reporting failed");
       }
-      return false;
+      return { enrolled: false, error: err };
     }
-  }, "tryEnrollEscrow");
+  }, "attemptEnrollEscrow");
+  const tryEnrollEscrow = /* @__PURE__ */ __name(async (...args) => (await attemptEnrollEscrow(...args)).enrolled, "tryEnrollEscrow");
   const withAutoClear = /* @__PURE__ */ __name((shareVersion, autoClearedFrom) => {
     if (!autoClearedFrom) return { enrolled: true, changed: true, shareVersion };
     try {
@@ -28532,7 +28558,22 @@ function createSSSStrategy(config) {
         clearPinForEnrollment ||= current.hasPin && pin === void 0;
       }
       currentlyEnrolled = currentlyEnrolled && current.status === "active" && current.shareVersion === status.shareVersion && current.envelope?.keyId === verifiedKey.keyId;
+      let identityMismatch = false;
+      if (currentlyEnrolled && current.envelope && status.escrowBlobIdentity !== void 0) {
+        const authorityIdentity = await getEscrowBlobIdentity(current.envelope);
+        if (authorityIdentity !== status.escrowBlobIdentity) {
+          const reread = await self.fetchServerKeyStatus(
+            params.token,
+            params.providerType
+          );
+          storage2.assertCurrent();
+          identityMismatch = reread.escrowBlobIdentity !== authorityIdentity && reread.escrowUpdating !== true;
+        }
+      }
+      if (identityMismatch) currentlyEnrolled = false;
       if (currentlyEnrolled) verifiedEscrowEnvelope = current.envelope ?? void 0;
+      if (identityMismatch && current.hasPin && pin === void 0 && !clearPinForEnrollment)
+        return { enrolled: false, reason: "pin-reset-required" };
       hasPin = current.hasPin;
       const uncarryablePin = !clearPinForEnrollment && current.status === "active" && current.hasPin && pin === void 0 && !currentlyEnrolled && status.escrowPin?.state === "none";
       if (uncarryablePin && (config.autoClearUncarryablePin ?? DEFAULT_AUTO_CLEAR_UNCARRYABLE_PIN) && current.shareVersion !== null && status.shareVersion !== null && current.shareVersion < status.shareVersion && !status.recoveryMethods.some(
@@ -28660,6 +28701,378 @@ function createSSSStrategy(config) {
       }
     };
   }, "captureActiveUserGuard");
+  const pinHasRecordedWrongAttempts = /* @__PURE__ */ __name((escrowPin) => {
+    const status = escrowPin;
+    if (status?.state === "none") return false;
+    return typeof status?.wrongAttempts !== "number" || status.wrongAttempts > 0;
+  }, "pinHasRecordedWrongAttempts");
+  const refreshablePinCharges = /* @__PURE__ */ __name((before, after) => {
+    const pre = before;
+    const post = after;
+    if (pinHasRecordedWrongAttempts(before) || pinHasRecordedWrongAttempts(after))
+      return void 0;
+    if (pre?.state !== "enabled" || post?.state !== "enabled") return void 0;
+    if (typeof pre.attemptsRemaining !== "number" || typeof post.attemptsRemaining !== "number")
+      return void 0;
+    if (post.attemptsRemaining !== pre.attemptsRemaining - 1) return void 0;
+    return { attemptsRemaining: post.attemptsRemaining, wrongAttempts: 0 };
+  }, "refreshablePinCharges");
+  const freshPinMaterial = /* @__PURE__ */ __name(async (pin) => {
+    if (!validatePin(pin).ok) return void 0;
+    try {
+      const pinSalt = generatePinSalt();
+      return { pinSalt, pinVerifier: await derivePinProof(pin, pinSalt) };
+    } catch {
+      return void 0;
+    }
+  }, "freshPinMaterial");
+  const adoptReleasedShare = /* @__PURE__ */ __name(async (storage2, storageId, released, shareVersion, currentVersion) => {
+    await storage2.storeDeviceShare(released.recoveryShare, storageId);
+    await storage2.storeShareVersion(shareVersion, storageId);
+    lastEmailShare = void 0;
+    lastShareVersion = shareVersion;
+    lastServerSnapshot = {
+      currentVersion,
+      resolvedVersion: shareVersion,
+      authShare: released.authShare,
+      primaryDid: released.primaryDid
+    };
+  }, "adoptReleasedShare");
+  const completePinSignInKeep = /* @__PURE__ */ __name(async (params, released, pin, pinBefore) => {
+    const storage2 = guardedStorage();
+    const generation = storageGeneration;
+    const storageId = activeStorageId;
+    const assertActive = /* @__PURE__ */ __name(() => {
+      if (activeStorageId !== storageId || storageGeneration !== generation) {
+        throw new Error("This recovery request was cancelled.");
+      }
+    }, "assertActive");
+    const { mode, newPinRequired, refreshCharges } = await withShareUpdateLock(
+      storage2,
+      storageId,
+      () => withRotationLock(async () => {
+        assertActive();
+        const current = await fetchAuthShareRaw(
+          serverUrl,
+          params.token,
+          params.providerType,
+          void 0,
+          tenantId
+        );
+        assertActive();
+        if (!current || current.primaryDid !== released.primaryDid || typeof current.shareVersion !== "number") {
+          throw new PinSignInStaleError();
+        }
+        let mode2;
+        if (current.shareVersion === released.shareVersion) {
+          if (authShareToString(current.authShare) !== released.authShare) {
+            throw new PinSignInStaleError();
+          }
+          mode2 = "kept";
+        } else {
+          const historical = current.shareVersion > released.shareVersion ? await fetchAuthShareRaw(
+            serverUrl,
+            params.token,
+            params.providerType,
+            released.shareVersion,
+            tenantId
+          ) : null;
+          if (authShareToString(historical?.authShare) !== released.authShare) {
+            throw new PinSignInStaleError();
+          }
+          mode2 = "deferred-rotation";
+        }
+        assertActive();
+        await adoptReleasedShare(
+          storage2,
+          storageId,
+          released,
+          released.shareVersion,
+          current.shareVersion
+        );
+        pendingIdentityRecovery = void 0;
+        return {
+          mode: mode2,
+          newPinRequired: pinHasRecordedWrongAttempts(pinBefore) || pinHasRecordedWrongAttempts(current.escrowPin),
+          refreshCharges: refreshablePinCharges(pinBefore, current.escrowPin)
+        };
+      })
+    );
+    let pinRefreshed = false;
+    let pinRefreshFailed = false;
+    if (mode === "kept" && !newPinRequired && refreshCharges && params.signDidAuthVp) {
+      const pinMaterial = await freshPinMaterial(pin);
+      pinRefreshed = pinMaterial !== void 0 && await tryEnrollEscrow(
+        params.token,
+        params.providerType,
+        released.privateKey,
+        released.primaryDid,
+        { recoveryShare: released.recoveryShare },
+        released.shareVersion,
+        params.signDidAuthVp,
+        void 0,
+        pinMaterial,
+        false,
+        storage2.assertCurrent,
+        params.options?.recoveryEmail,
+        params.options?.recoveryLanguage,
+        refreshCharges
+      );
+      pinRefreshFailed = pinMaterial !== void 0 && !pinRefreshed;
+    }
+    assertActive();
+    return {
+      privateKey: released.privateKey,
+      did: released.primaryDid,
+      escrowEnrolled: true,
+      escrowRecovery: true,
+      pinSignIn: {
+        mode,
+        pinRefreshed,
+        newPinRequired,
+        ...pinRefreshFailed ? { pinRefreshFailed: true } : {}
+      }
+    };
+  }, "completePinSignInKeep");
+  const completePinSignInRelink = /* @__PURE__ */ __name(async (params, pending, signDidAuthVp) => {
+    const storage2 = guardedStorage();
+    const generation = storageGeneration;
+    const storageId = activeStorageId;
+    const shareVersion = pending.pinKeep.shareVersion;
+    const assertActive = /* @__PURE__ */ __name(() => {
+      if (activeStorageId !== storageId || pendingIdentityRecovery !== pending || storageGeneration !== generation) {
+        throw new Error("This recovery request was cancelled.");
+      }
+    }, "assertActive");
+    await withShareUpdateLock(
+      storage2,
+      storageId,
+      () => withRotationLock(async () => {
+        assertActive();
+        const didAuthVp = await requestFreshDidAuthVp(
+          serverUrl,
+          pending.privateKey,
+          pending.primaryDid,
+          signDidAuthVp,
+          tenantId
+        );
+        assertActive();
+        try {
+          const response = await postJson(
+            `${serverUrl}/keys/recovery-session/pin-sign-in`,
+            {
+              recoverySessionToken: pending.rebindSessionToken,
+              providerType: params.providerType,
+              primaryDid: pending.primaryDid
+            },
+            {
+              ...buildHeaders("", didAuthVp, tenantId),
+              "X-Auth-Token": params.token
+            }
+          );
+          if (response.shareVersion !== shareVersion) throw new PinSignInStaleError();
+        } catch (error) {
+          const current = await fetchAuthShareRaw(
+            serverUrl,
+            params.token,
+            params.providerType,
+            void 0,
+            tenantId
+          ).catch(() => null);
+          if (!current || current.primaryDid !== pending.primaryDid || current.shareVersion !== shareVersion || authShareToString(current.authShare) !== pending.authShare) {
+            throw error;
+          }
+        }
+        assertActive();
+        await adoptReleasedShare(storage2, storageId, pending, shareVersion, shareVersion);
+        pendingIdentityRecovery = void 0;
+      })
+    );
+    if (activeStorageId !== storageId || storageGeneration !== generation) {
+      throw new Error("This recovery request was cancelled.");
+    }
+    const status = await fetchAuthShareRaw(
+      serverUrl,
+      params.token,
+      params.providerType,
+      void 0,
+      tenantId
+    ).catch(() => null);
+    return {
+      privateKey: pending.privateKey,
+      did: pending.primaryDid,
+      escrowEnrolled: true,
+      escrowRecovery: true,
+      pinSignIn: {
+        mode: "relinked",
+        pinRefreshed: false,
+        newPinRequired: pinHasRecordedWrongAttempts(status?.escrowPin)
+      }
+    };
+  }, "completePinSignInRelink");
+  const completeIdentityRecoveryWith = /* @__PURE__ */ __name(async (params) => {
+    const storage2 = guardedStorage();
+    const generation = storageGeneration;
+    const pending = pendingIdentityRecovery;
+    const signDidAuthVp = params.signDidAuthVp;
+    if (!pending) throw new Error("No identity recovery is waiting for a new sign-in");
+    if (!signDidAuthVp) {
+      throw new Error("DID proof signing is required to bind a new sign-in");
+    }
+    if (pending.pinKeep) return completePinSignInRelink(params, pending, signDidAuthVp);
+    const storageId = activeStorageId;
+    const { shares, shareVersion } = await withShareUpdateLock(
+      storage2,
+      storageId,
+      () => withRotationLock(async () => {
+        const assertActive = /* @__PURE__ */ __name(() => {
+          if (activeStorageId !== storageId || pendingIdentityRecovery !== pending || storageGeneration !== generation) {
+            throw new Error("This recovery request was cancelled.");
+          }
+        }, "assertActive");
+        assertActive();
+        const candidates = await readPendingShareCandidates(storage2, storageId);
+        if (pending.rebind && pending.rebind.storageId !== storageId) {
+          throw new Error("Active account changed during identity recovery");
+        }
+        if (candidates.some(
+          (candidate) => candidate.share !== pending.rebind?.shares.deviceShare
+        )) {
+          throw new Error("Reconcile the pending share update before binding a sign-in");
+        }
+        let shareVersion2;
+        const retry = pending.rebind?.attempted ?? false;
+        if (retry && pending.rebind) {
+          const current = await fetchAuthShareRaw(
+            serverUrl,
+            params.token,
+            params.providerType,
+            void 0,
+            tenantId
+          );
+          const authShare = authShareToString(current?.authShare);
+          if (authShare && current?.shareVersion != null) {
+            const health = await verifyStoredShares(
+              {
+                getDevice: /* @__PURE__ */ __name(async () => pending.rebind.shares.deviceShare, "getDevice"),
+                getAuth: /* @__PURE__ */ __name(async () => authShare, "getAuth")
+              },
+              pending.primaryDid,
+              async (key) => key === pending.privateKey ? pending.primaryDid : ""
+            );
+            if (health.healthy) shareVersion2 = current.shareVersion;
+          }
+        }
+        assertActive();
+        if (shareVersion2 === void 0) {
+          const didAuthVp = await requestFreshDidAuthVp(
+            serverUrl,
+            pending.privateKey,
+            pending.primaryDid,
+            signDidAuthVp,
+            tenantId
+          );
+          assertActive();
+          pending.rebind ??= {
+            shares: (await splitAndVerify(pending.privateKey)).shares,
+            storageId,
+            attempted: false
+          };
+          const rebind = pending.rebind;
+          if (!candidates.some((candidate) => candidate.share === rebind.shares.deviceShare)) {
+            await addPendingShareCandidate(
+              storage2,
+              { share: rebind.shares.deviceShare, createdAt: Date.now() },
+              storageId
+            );
+          }
+          assertActive();
+          rebind.attempted = true;
+          try {
+            const response = await postJson(
+              `${serverUrl}/keys/recovery-session/rebind`,
+              {
+                recoverySessionToken: pending.rebindSessionToken,
+                providerType: params.providerType,
+                primaryDid: pending.primaryDid,
+                authShare: {
+                  encryptedData: rebind.shares.authShare,
+                  encryptedDek: "",
+                  iv: ""
+                }
+              },
+              {
+                ...buildHeaders("", didAuthVp, tenantId),
+                "X-Auth-Token": params.token
+              }
+            );
+            shareVersion2 = response.shareVersion;
+          } catch (error) {
+            if (error instanceof ShareWriteRejectedError && !retry) {
+              await removePendingShareCandidate(
+                storage2,
+                rebind.shares.deviceShare,
+                storageId
+              );
+              pending.rebind = void 0;
+            }
+            throw error;
+          }
+        }
+        if (shareVersion2 === void 0 || !pending.rebind) {
+          throw new Error("Server did not confirm the new share");
+        }
+        assertActive();
+        const shares2 = pending.rebind.shares;
+        await storage2.storeDeviceShare(shares2.deviceShare, storageId);
+        await storage2.storeShareVersion(shareVersion2, storageId);
+        await clearPendingShareCandidates(storage2, storageId);
+        assertActive();
+        lastEmailShare = shares2.emailShare;
+        lastShareVersion = shareVersion2;
+        lastServerSnapshot = {
+          currentVersion: shareVersion2,
+          resolvedVersion: shareVersion2,
+          authShare: shares2.authShare,
+          primaryDid: pending.primaryDid
+        };
+        pendingIdentityRecovery = void 0;
+        return { shares: shares2, shareVersion: shareVersion2 };
+      })
+    );
+    const enrolled = pending.fromEscrow && await tryEnrollEscrow(
+      params.token,
+      params.providerType,
+      pending.privateKey,
+      pending.primaryDid,
+      shares,
+      shareVersion,
+      signDidAuthVp,
+      void 0,
+      void 0,
+      true,
+      storage2.assertCurrent,
+      params.options?.recoveryEmail,
+      params.options?.recoveryLanguage
+    );
+    if (activeStorageId !== storageId || storageGeneration !== generation) {
+      throw new Error("This recovery request was cancelled.");
+    }
+    if (!enrolled) {
+      unenrolledRotation = {
+        shares,
+        shareVersion,
+        primaryDid: pending.primaryDid,
+        clearPin: true
+      };
+    }
+    return {
+      privateKey: pending.privateKey,
+      did: pending.primaryDid,
+      escrowEnrolled: enrolled,
+      escrowRecovery: pending.fromEscrow
+    };
+  }, "completeIdentityRecoveryWith");
   return {
     name: "sss",
     capabilities: {
@@ -28729,6 +29142,10 @@ function createSSSStrategy(config) {
       };
     },
     async reconstructKey(localKey, remoteKey) {
+      const coordinate = localKey.slice(-2).toLowerCase();
+      if (localKey.length === remoteKey.length && /^(?:[0-9a-f]{2}){2,}$/i.test(localKey) && /^(?:[0-9a-f]{2}){2,}$/i.test(remoteKey) && coordinate !== "00" && coordinate === remoteKey.slice(-2).toLowerCase()) {
+        throw new DuplicateShareCoordinateError();
+      }
       return reconstructFromShares([localKey, remoteKey]);
     },
     async verifyKeys(localKey, remoteKey, expectedDid, didFromPrivateKey) {
@@ -28957,6 +29374,8 @@ function createSSSStrategy(config) {
         escrowOptedOut: data.escrowOptedOut === true,
         escrowPin: data.escrowPin,
         escrowStale: data.escrowStale,
+        ...typeof data.escrowBlobIdentity === "string" ? { escrowBlobIdentity: data.escrowBlobIdentity } : {},
+        ...data.escrowUpdating === true ? { escrowUpdating: true } : {},
         sssActivationState: data.sssActivationState ?? "active",
         ...typeof data.priorEscrowEnrollment === "boolean" ? { priorEscrowEnrollment: data.priorEscrowEnrollment } : {}
       };
@@ -29331,9 +29750,20 @@ function createSSSStrategy(config) {
       if (input.method === "escrow" || input.method === "escrow-pin") {
         if (!didFromPrivateKey)
           throw new Error("DID verification is required for escrow recovery");
-        const start = input.method === "escrow-pin" ? await this.startEscrowRecovery({
+        if (input.method === "escrow-pin" && !token && !input.recoverySessionToken)
+          throw new Error("PIN recovery requires signing in first.");
+        const pinBefore = input.method === "escrow-pin" && token ? await fetchAuthShareRaw(
+          serverUrl,
           token,
           providerType,
+          void 0,
+          tenantId
+        ).then(
+          (current) => current?.escrowPin,
+          () => void 0
+        ) : void 0;
+        const start = input.method === "escrow-pin" ? await this.startEscrowRecovery({
+          ...token ? { token, providerType } : { recoverySessionToken: input.recoverySessionToken },
           expectedDid: input.expectedDid,
           options: { releasePolicy: "pin" }
         }) : input;
@@ -29385,16 +29815,32 @@ function createSSSStrategy(config) {
             "Recovery produced an incorrect key. Try another recovery method."
           );
         }
+        if (input.method === "escrow-pin" && token) {
+          return completePinSignInKeep(
+            { token, providerType, signDidAuthVp, options: params.options },
+            {
+              privateKey: privateKey2,
+              primaryDid: material.primaryDid,
+              recoveryShare: plaintext.recoveryShare,
+              authShare,
+              shareVersion: material.shareVersion
+            },
+            input.pin,
+            pinBefore
+          );
+        }
         pendingIdentityRecovery = {
           privateKey: privateKey2,
           primaryDid: material.primaryDid,
           recoveryShare: plaintext.recoveryShare,
           authShare,
           rebindSessionToken: material.rebindSessionToken,
-          fromEscrow: true
+          fromEscrow: true,
+          // The PIN itself is not kept across the new-login step.
+          ...input.method === "escrow-pin" ? { pinKeep: { shareVersion: material.shareVersion } } : {}
         };
         if (!token) return { privateKey: privateKey2, did: material.primaryDid };
-        return this.completeIdentityRecovery({
+        return completeIdentityRecoveryWith({
           token,
           providerType,
           signDidAuthVp,
@@ -29969,125 +30415,128 @@ function createSSSStrategy(config) {
       pendingIdentityRecovery = void 0;
     },
     async completeIdentityRecovery(params) {
-      const storage2 = guardedStorage();
-      const generation = storageGeneration;
-      const pending = pendingIdentityRecovery;
-      const signDidAuthVp = params.signDidAuthVp;
-      if (!pending) throw new Error("No identity recovery is waiting for a new sign-in");
-      if (!signDidAuthVp) {
-        throw new Error("DID proof signing is required to bind a new sign-in");
+      return completeIdentityRecoveryWith(params);
+    },
+    /**
+     * "Secure my account": one atomic server update re-splits the key and drops all
+     * older auth share versions, signing out other devices and turning off the old
+     * phrase/backup/passkey/email key. Staged through the pending-candidate slot, so
+     * a lost acknowledgement is promoted by the usual reconciliation. Escrow is then
+     * re-enrolled with `pin` (fresh salt) or, for `null`, without a PIN. The PIN is
+     * used in this call only and never kept in retry state.
+     */
+    async revokeOtherDevices(params) {
+      const { token, providerType, privateKey, did, signDidAuthVp, pin } = params;
+      if (!signDidAuthVp) throw new Error("DID proof signing is required");
+      if (pin !== null) {
+        const validation = validatePin(pin);
+        if (!validation.ok)
+          throw new Error(
+            validation.reason === "length" ? "PIN must contain 6\u201312 digits." : "Choose a PIN without trivial or sequential patterns."
+          );
       }
+      const storage2 = guardedStorage();
       const storageId = activeStorageId;
+      const assertUser = captureActiveUserGuard();
+      const assertActive = /* @__PURE__ */ __name(() => {
+        assertUser();
+        storage2.assertCurrent();
+      }, "assertActive");
+      const before = await fetchAuthShareRaw(
+        serverUrl,
+        token,
+        providerType,
+        void 0,
+        tenantId
+      );
+      if (!before || before.primaryDid !== did) {
+        throw new Error("This account could not be found. Sign in again.");
+      }
+      const hadEscrow = !before.escrowOptedOut && (before.priorEscrowEnrollment === true || Array.isArray(before.recoveryMethods) && before.recoveryMethods.some(
+        (method) => method?.type === "escrow"
+      ));
+      const didFromKey = /* @__PURE__ */ __name(async (key) => key === privateKey ? did : `${did}:mismatch`, "didFromKey");
       const { shares, shareVersion } = await withShareUpdateLock(
         storage2,
         storageId,
         () => withRotationLock(async () => {
-          const assertActive = /* @__PURE__ */ __name(() => {
-            if (activeStorageId !== storageId || pendingIdentityRecovery !== pending || storageGeneration !== generation) {
-              throw new Error("This recovery request was cancelled.");
-            }
-          }, "assertActive");
-          assertActive();
-          const candidates = await readPendingShareCandidates(storage2, storageId);
-          if (pending.rebind && pending.rebind.storageId !== storageId) {
-            throw new Error("Active account changed during identity recovery");
-          }
-          if (candidates.some(
-            (candidate) => candidate.share !== pending.rebind?.shares.deviceShare
-          )) {
-            throw new Error(
-              "Reconcile the pending share update before binding a sign-in"
-            );
-          }
-          let shareVersion2;
-          const retry = pending.rebind?.attempted ?? false;
-          if (retry && pending.rebind) {
-            const current = await fetchAuthShareRaw(
-              serverUrl,
-              params.token,
-              params.providerType,
-              void 0,
-              tenantId
-            );
-            const authShare = authShareToString(current?.authShare);
-            if (authShare && current?.shareVersion != null) {
-              const health = await verifyStoredShares(
-                {
-                  getDevice: /* @__PURE__ */ __name(async () => pending.rebind.shares.deviceShare, "getDevice"),
-                  getAuth: /* @__PURE__ */ __name(async () => authShare, "getAuth")
-                },
-                pending.primaryDid,
-                async (key) => key === pending.privateKey ? pending.primaryDid : ""
+          const { snapshot } = await resolvePendingShareCandidates(
+            storage2,
+            storageId,
+            async () => {
+              const data = await fetchAuthShareRaw(
+                serverUrl,
+                token,
+                providerType,
+                void 0,
+                tenantId
               );
-              if (health.healthy) shareVersion2 = current.shareVersion;
-            }
+              return {
+                currentVersion: data?.shareVersion ?? null,
+                authShare: authShareToString(data?.authShare)
+              };
+            },
+            did,
+            didFromKey,
+            assertActive,
+            recordPromotion(did),
+            async (version) => authShareToString(
+              (await fetchAuthShareRaw(
+                serverUrl,
+                token,
+                providerType,
+                version,
+                tenantId
+              ))?.authShare
+            )
+          );
+          if (!snapshot.currentVersion) {
+            throw new Error("This account could not be found. Sign in again.");
           }
+          const expectedShareVersion = snapshot.currentVersion;
+          const didAuthVp = await requestFreshDidAuthVp(
+            serverUrl,
+            privateKey,
+            did,
+            signDidAuthVp,
+            tenantId
+          );
           assertActive();
-          if (shareVersion2 === void 0) {
-            const didAuthVp = await requestFreshDidAuthVp(
-              serverUrl,
-              pending.privateKey,
-              pending.primaryDid,
-              signDidAuthVp,
-              tenantId
-            );
-            assertActive();
-            pending.rebind ??= {
-              shares: (await splitAndVerify(pending.privateKey)).shares,
-              storageId,
-              attempted: false
-            };
-            const rebind = pending.rebind;
-            if (!candidates.some(
-              (candidate) => candidate.share === rebind.shares.deviceShare
-            )) {
+          let shareVersion2;
+          let stagedShare = "";
+          const shares2 = await atomicShareUpdate(privateKey, {
+            storeDevice: /* @__PURE__ */ __name(async (share) => {
+              assertActive();
+              stagedShare = share;
               await addPendingShareCandidate(
                 storage2,
-                { share: rebind.shares.deviceShare, createdAt: Date.now() },
+                { share, createdAt: Date.now() },
                 storageId
               );
-            }
-            assertActive();
-            rebind.attempted = true;
-            try {
+            }, "storeDevice"),
+            clearDevice: /* @__PURE__ */ __name(() => removePendingShareCandidate(storage2, stagedShare, storageId), "clearDevice"),
+            storeAuth: /* @__PURE__ */ __name(async (share) => {
+              assertActive();
               const response = await postJson(
-                `${serverUrl}/keys/recovery-session/rebind`,
+                `${serverUrl}/keys/revoke-other-devices`,
                 {
-                  recoverySessionToken: pending.rebindSessionToken,
-                  providerType: params.providerType,
-                  primaryDid: pending.primaryDid,
-                  authShare: {
-                    encryptedData: rebind.shares.authShare,
-                    encryptedDek: "",
-                    iv: ""
-                  }
+                  authToken: token,
+                  providerType,
+                  primaryDid: did,
+                  authShare: { encryptedData: share, encryptedDek: "", iv: "" },
+                  expectedShareVersion
                 },
-                {
-                  ...buildHeaders("", didAuthVp, tenantId),
-                  "X-Auth-Token": params.token
-                }
+                buildHeaders(token, didAuthVp, tenantId)
               );
               shareVersion2 = response.shareVersion;
-            } catch (error) {
-              if (error instanceof ShareWriteRejectedError && !retry) {
-                await removePendingShareCandidate(
-                  storage2,
-                  rebind.shares.deviceShare,
-                  storageId
-                );
-                pending.rebind = void 0;
-              }
-              throw error;
-            }
-          }
-          if (shareVersion2 === void 0 || !pending.rebind) {
-            throw new Error("Server did not confirm the new share");
+            }, "storeAuth")
+          });
+          if (shareVersion2 === void 0) {
+            throw new Error("Server did not return a share version");
           }
-          assertActive();
-          const shares2 = pending.rebind.shares;
           await storage2.storeDeviceShare(shares2.deviceShare, storageId);
           await storage2.storeShareVersion(shareVersion2, storageId);
-          await clearPendingShareCandidates(storage2, storageId);
+          await removePendingShareCandidate(storage2, shares2.deviceShare, storageId);
           assertActive();
           lastEmailShare = shares2.emailShare;
           lastShareVersion = shareVersion2;
@@ -30095,44 +30544,36 @@ function createSSSStrategy(config) {
             currentVersion: shareVersion2,
             resolvedVersion: shareVersion2,
             authShare: shares2.authShare,
-            primaryDid: pending.primaryDid
+            primaryDid: did
           };
-          pendingIdentityRecovery = void 0;
           return { shares: shares2, shareVersion: shareVersion2 };
         })
       );
-      const enrolled = pending.fromEscrow && await tryEnrollEscrow(
-        params.token,
-        params.providerType,
-        pending.privateKey,
-        pending.primaryDid,
+      if (!hadEscrow || !config.escrow?.enabled) {
+        return { shareVersion, escrowEnrolled: false, pinKept: false };
+      }
+      const pinMaterial = pin === null ? void 0 : await freshPinMaterial(pin);
+      const enrollArgs = [
+        token,
+        providerType,
+        privateKey,
+        did,
         shares,
         shareVersion,
         signDidAuthVp,
         void 0,
-        void 0,
-        true,
+        pinMaterial,
+        !pinMaterial,
         storage2.assertCurrent,
         params.options?.recoveryEmail,
         params.options?.recoveryLanguage
-      );
-      if (activeStorageId !== storageId || storageGeneration !== generation) {
-        throw new Error("This recovery request was cancelled.");
-      }
+      ];
+      const attempt = await attemptEnrollEscrow(...enrollArgs);
+      const enrolled = attempt.enrolled || attempt.error instanceof EscrowRequestError && attempt.error.status === 403 && await tryEnrollEscrow(...enrollArgs);
       if (!enrolled) {
-        unenrolledRotation = {
-          shares,
-          shareVersion,
-          primaryDid: pending.primaryDid,
-          clearPin: true
-        };
+        unenrolledRotation = { shares, shareVersion, primaryDid: did, clearPin: true };
       }
-      return {
-        privateKey: pending.privateKey,
-        did: pending.primaryDid,
-        escrowEnrolled: enrolled,
-        escrowRecovery: pending.fromEscrow
-      };
+      return { shareVersion, escrowEnrolled: enrolled, pinKept: enrolled && !!pinMaterial };
     },
     // --- Contact method management ---
     async upgradeContactMethod(token, providerType, previousPhone, email, code) {
@@ -30423,6 +30864,7 @@ export {
   AtomicUpdateError,
   export_AuthSessionError as AuthSessionError,
   DEFAULT_KDF_PARAMS,
+  DuplicateShareCoordinateError,
   EMAIL_RELAY_ALGORITHM,
   EMAIL_RELAY_ENVELOPE_VERSION,
   ESCROW_ALGORITHM,
@@ -30443,6 +30885,7 @@ export {
   NitroAttestationError,
   PIN_MAX_LENGTH,
   PIN_MIN_LENGTH,
+  PinSignInStaleError,
   SSSApiClient,
   SSSKeyManager,
   SSS_THRESHOLD,