@learncard/lca-api-service 1.6.1 → 1.6.2

package/AGENTS.md

@@ -127,6 +127,27 @@ The `escrow` tRPC router is disabled unless `ESCROW_ENCLAVE_MODE` is configured.
 | `POST /keys/escrow/cancel-link` | `escrow.cancelRecoveryByLink` | Cancels a pending hold via the single-use email cancel link (no DID auth) |
 | `POST /keys/escrow/complete`    | `escrow.completeRecovery`     | Claim an elapsed hold and release sealed recovery material once           |
 
+### Recovery sessions, rebind and PIN sign-in
+
+Lost-login recovery issues single-use, 15-minute tokens (`src/cache/recoverySessions.ts`): a `'recover'` token from `/keys/recovery-session/verify`, then a `'rebind'` token from `useRecoverySession` or `/keys/escrow/complete`.
+
+| Route                                     | Procedure                     | Effect                                                                                                                                         |
+| ----------------------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `POST /keys/recovery-session/rebind`      | `keys.completeRecoveryRebind` | Wiping rebind: new login replaces the old, new split, history purged, methods `pending`, escrow cleared                                        |
+| `POST /keys/recovery-session/pin-sign-in` | `keys.completePinSignIn`      | Keep mode: adds the new login (old one stays); shares, history, methods, escrow and contact unchanged. Only PIN-release tokens are accepted    |
+| `POST /keys/revoke-other-devices`         | `keys.revokeOtherDevices`     | "Secure my account": owner-authenticated security rotation (same wipe as rebind; only the caller's login stays), CAS on `expectedShareVersion` |
+
+- Only `/keys/escrow/complete` for a `releasePolicy:'pin'` hold mints a `'rebind'` token with `origin:'pin-release'` plus the released `primaryDid`/`shareVersion`. Keep mode trusts those server-side fields, never client input. Waiting-period and `useRecoverySession` tokens can only use the wiping rebind.
+- Every recovery token records `userKey.securityEpoch` (missing = 0) at mint; a `'rebind'` token from `useRecoverySession` inherits the `'recover'` session's epoch. Wiping rotations (`/rebind`, revoke) `$inc` the epoch in the same update, and `/rebind` and `/pin-sign-in` include the epoch in their update filter, so any token minted before a revoke or wiping rebind gets CONFLICT. `useRecoverySession` and escrow start (with a recovery session) also reject a stale epoch. Non-wiping rotations leave the epoch alone.
+- Keep mode never spends the PIN-release token, so `/rebind` also only accepts one while `userKey.shareVersion` still equals the released version. `/pin-sign-in` peeks at the token before consuming it, so a rejected hold/phrase token or a wrong DID does not burn it.
+- The revoke re-splits the same key; it does not evict a device that already holds the private key (see `services/escrow-enclave-app/SECURITY.md` D19). After the commit it emails the contact and verified recovery addresses (`account-secured`, awaited within a 3 s budget, fail-open); the copy assumes the reader may not have run it and may have lost their login, says the recovery methods were reset, and sends them to the tenant support address (or the organization, when there is none) rather than to lost-login recovery, which the revoke itself disabled.
+- A successful PIN release sends the `escrow-pin-sign-in` notice ("Not you? Secure your account", link to `/account/secure` on the tenant app URL) instead of `escrow-hold-released`. It is sent fail-open within the escrow notification budget.
+- `getEscrowPinStatus().wrongAttempts` counts verified wrong entries only and is omitted for legacy records that cannot tell (until a reservation initialises the verified counter to 0; clients therefore also read the status before a release).
+- `escrow.enroll` accepts `expectedPinCharges: { attemptsRemaining, wrongAttempts }` with a new `pinSalt` (the keep-mode same-PIN refresh). It is checked against the current PIN, then (software mode) again in the write's filter, or (authority mode) by the lease claim below, so a guess reserved or resolved after the client's check makes it CONFLICT instead of being wiped by the fresh generation. A non-zero `wrongAttempts` is always refused.
+- **PIN-operation lease (authority mode).** Every relayed owner-signed intent (`escrow.enroll`, `escrow.disable`/`remove`) runs under `applyEnrollmentIntentUnderLease` (`src/routes/escrow.ts`): `claimEscrowEnrollmentLease` sets `userKey.escrowEnrollmentLease` in one write conditioned on the read blob + PIN record, no other lease and no live `escrowPinCompares` marker; then the authority call; then `commitEscrowEnrollmentLease`, conditioned on the lease id and the replaced `blobHash` (not on charges), which also removes the lease. `reserveEscrowPinAttempt` refuses while any lease exists and pushes a compare marker (`compareId`) that `completeRecovery` pulls once the authority answers (kept until its TTL after a transport failure). `startRecovery` and `completeRecovery` answer 429 `Automatic recovery is being updated…` under a live lease, before creating a hold or charging; `completeRecovery` also refuses (FORBIDDEN, uncharged) a PIN hold whose `holdRecord.hold.blobHash` is not the current blob's. The rewrap job (`src/jobs/escrowBlobRewrap.ts`) claims the same lease (`action: 'rewrap'`) around `rewrapEscrowBlob` in authority mode. Releasing a compare marker is best effort (its TTL covers a miss). TTLs: `ESCROW_ENROLLMENT_LEASE_TTL_MS` / `ESCROW_PIN_COMPARE_TTL_MS` = 120 s (4x the 30 s max `ESCROW_ENCLAVE_REMOTE_TIMEOUT_MS`).
+- **Reconciliation.** If the commit write misses or the authority call fails ambiguously, `settleEscrowEnrollmentLease` (`src/services/escrow-enclave/enrollmentLease.ts`) reads the authority state and adopts it when it is exactly the lease's commit (enrollment version +1, epoch, PIN generation, share version, returned envelope identity), using the salt/PIN action recorded in the lease; a definite refusal releases the lease; an unknown outcome keeps it until expiry. `settleExpiredEscrowLease` runs on start/complete/enroll/disable/authority-state, so a crash converges on the next request. A settle that finds the same commit already persisted counts as adopted. A lost response still fails the request even when its commit is adopted (no receipt to return). `/keys/auth-share` reports `escrowBlobIdentity` so authority-mode clients can detect and repair any copy mismatch that is left, and `escrowUpdating` while a lease is held so they do not mistake an in-progress operation for a stale copy. Live-Mongo coverage: `test/keys-pin-lease.spec.ts`.
+- Software-mode PIN carry ignores releases completed before `escrowPin.enabledAt`, so a PIN re-set at the same version after a PIN sign-in survives the next rotation.
+
 ### Important Invariants
 
 - **Auth shares are encrypted at rest** with a KEK derived from `SEED`. Losing `SEED` means every stored auth share is permanently unrecoverable.

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @welibraryos/lca-api-service
 
+## 1.6.2
+
+### Patch Changes
+
+- [#1905](https://github.com/learningeconomy/LearnCard/pull/1905) [`c20460f6fef685272227f506f536b6811f90b8a0`](https://github.com/learningeconomy/LearnCard/commit/c20460f6fef685272227f506f536b6811f90b8a0) Thanks [@Custard7](https://github.com/Custard7)! - Make the recovery PIN the main way to sign in on a new device, without resetting the account. A PIN sign-in now keeps the account's shares, history, recovery methods and escrow: the device stores the released recovery piece at the current version and re-sets the same PIN for a fresh attempt budget only when no wrong entry is recorded against it; otherwise the PIN keeps its reduced budget and the app asks for a new, different PIN (refusing the PIN just used, also after a restart on that device, via a tag keyed by the account key), asking again on each app start until one is chosen; the same-PIN refresh is skipped when another charge landed during the release, and lca-api writes it only while the PIN still shows the charges the client saw (`expectedPinCharges`) (a lost login is linked with the new `POST /keys/recovery-session/pin-sign-in`, accepted only after a PIN release). The server emails the account's verified addresses on every PIN sign-in ("New device signed in with your PIN. Not you? Secure your account."), and the PIN status reports earlier wrong entries. The app leads its recovery screen with PIN entry (no sign-out warnings on that path; the 7-day hold keeps them), asks once after signing in whether a device was lost or the PIN is known to someone else (warning about earlier wrong entries), and adds "Secure my account" / "Sign out of all other devices" (`POST /keys/revoke-other-devices`), reachable from that question, Account Recovery settings and the email link `/account/secure`. That action re-splits the key, purges older versions and unlinks every login except the current one; it does not change the key itself, so a device that is already signed in may keep working until it signs out (the app says so). The revoke emails the account's contact and verified recovery addresses (new `account-secured` template, written for an owner who did not do it and may have lost their login: it says the recovery methods were reset and points to the tenant's support address, or to the organization when there is none). Every recovery token (recovery-email code, phrase, passkey, backup, waiting-period hold and PIN) is now bound to an account security epoch that every revoke and wiping rebind advances, so no token minted before one can rebind or re-link after it. Recovery is one-at-a-time: the coordinator rejects a second recovery while one is pending (`RecoveryInProgressError`; after a cancel, a new recovery-email code can be requested at once) and the app disables switching methods while a PIN sign-in is in flight. `@learncard/email-templates` omits an absent `locale` rather than passing `undefined` (`exactOptionalPropertyTypes`-safe) and exports each template from one declaration.
+
+- Updated dependencies [[`372c1431e78a9708454f9c4c2f2c99dd5486b8e9`](https://github.com/learningeconomy/LearnCard/commit/372c1431e78a9708454f9c4c2f2c99dd5486b8e9), [`c20460f6fef685272227f506f536b6811f90b8a0`](https://github.com/learningeconomy/LearnCard/commit/c20460f6fef685272227f506f536b6811f90b8a0)]:
+    - @learncard/sss-key-manager@0.2.6
+    - @learncard/types@5.24.1
+    - @learncard/email-templates@1.2.2
+    - @learncard/core@9.4.42
+    - @learncard/helpers@1.7.2
+    - @learncard/init@2.5.8
+    - @learncard/did-web-plugin@1.1.42
+    - @learncard/didkit-plugin@1.10.8
+    - @learncard/didkit-plugin-node@0.3.8
+
 ## 1.6.1
 
 ### Patch Changes

package/dist/app.d.ts

@@ -1041,6 +1041,7 @@ export declare const appRouter: import("@trpc/server").TRPCBuiltRouter<{
                     state: "enabled" | "none" | "locked" | "stale";
                     enabled: boolean;
                     attemptsRemaining: number;
+                    wrongAttempts?: number | undefined;
                     salt?: string | undefined;
                 };
                 primaryDid: string | null;
@@ -1089,6 +1090,39 @@ export declare const appRouter: import("@trpc/server").TRPCBuiltRouter<{
             };
             meta: import("trpc-to-openapi").OpenApiMeta;
         }>;
+        completePinSignIn: import("@trpc/server").TRPCMutationProcedure<{
+            input: {
+                recoverySessionToken: string;
+                providerType: "firebase" | "supertokens" | "keycloak" | "oidc";
+                primaryDid: string;
+                newAuthToken?: string | undefined;
+            };
+            output: {
+                success: true;
+                shareVersion: number;
+                linked: boolean;
+            };
+            meta: import("trpc-to-openapi").OpenApiMeta;
+        }>;
+        revokeOtherDevices: import("@trpc/server").TRPCMutationProcedure<{
+            input: {
+                providerType: "firebase" | "supertokens" | "keycloak" | "oidc";
+                primaryDid: string;
+                authShare: {
+                    encryptedData: string;
+                    encryptedDek: string;
+                    iv: string;
+                };
+                expectedShareVersion: number;
+                authToken?: string | undefined;
+            };
+            output: {
+                success: true;
+                shareVersion: number;
+                recoveryMethodsRequireConfirmation: ("email" | "passkey" | "backup" | "phrase" | "escrow")[];
+            };
+            meta: import("trpc-to-openapi").OpenApiMeta;
+        }>;
         issueDidChallenge: import("@trpc/server").TRPCMutationProcedure<{
             input: {
                 did: string;
@@ -1127,11 +1161,14 @@ export declare const appRouter: import("@trpc/server").TRPCBuiltRouter<{
                     state: "enabled" | "none" | "locked" | "stale";
                     enabled: boolean;
                     attemptsRemaining: number;
+                    wrongAttempts?: number | undefined;
                     salt?: string | undefined;
                 };
                 priorEscrowEnrollment: boolean;
                 sssActivationState: "active" | "provisional";
                 escrowStale?: "mode-mismatch" | "key-rotated" | undefined;
+                escrowBlobIdentity?: string | undefined;
+                escrowUpdating?: boolean | undefined;
             } | null;
             meta: import("trpc-to-openapi").OpenApiMeta;
         }>;
@@ -1433,6 +1470,10 @@ export declare const appRouter: import("@trpc/server").TRPCBuiltRouter<{
                     iv: string;
                     ciphertext: string;
                 } | null | undefined;
+                expectedPinCharges?: {
+                    attemptsRemaining: number;
+                    wrongAttempts: number;
+                } | undefined;
             };
             output: {
                 success: true;

package/dist/cache/recoverySessions.d.ts

@@ -10,6 +10,10 @@ export interface RecoverySessionRecord {
         type: AuthProviderType;
         id: string;
     };
+    origin?: 'pin-release';
+    primaryDid?: string;
+    shareVersion?: number;
+    securityEpoch?: number;
 }
 export interface RecoveryOtpRecord {
     codeHash: string;
@@ -36,6 +40,7 @@ export declare const getRecoveryOtpLockCacheKey: (email: string) => string;
 export declare const getRecoveryOtpSendCacheKey: (email: string) => string;
 export declare const getRecoverySessionCacheKey: (token: string) => string;
 export declare const createRecoverySession: (record: RecoverySessionRecord, ttl?: number) => Promise<string>;
+export declare const peekRecoverySession: (token: string, expectedScope: RecoverySessionScope) => Promise<RecoverySessionRecord | null>;
 export declare const consumeRecoverySession: (token: string, expectedScope: RecoverySessionScope) => Promise<RecoverySessionRecord | null>;
 export declare const storeRecoveryOtp: (email: string, record: RecoveryOtpRecord) => Promise<void>;
 export declare const verifyRecoveryOtp: (email: string, submittedCodeHash: string) => Promise<RecoveryOtpVerificationResult>;

package/dist/helpers/accountSecureLink.d.ts

@@ -0,0 +1,4 @@
+export declare const ACCOUNT_SECURE_PATH = "/account/secure";
+export declare const buildAccountSecureUrl: ({ baseUrl }: {
+    baseUrl: string;
+}) => string;

package/dist/helpers/accountSecureLink.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: package/dist/index.js
-size: 166884820 bytes
-sha256: 1a2ff8c7bd0130c90602a7cd4885f7e5ed3945534ae9974d7ef3a5182b9f3a53
+size: 167146968 bytes
+sha256: e837ca38f23dbcecdd16d4cc36272db9d19b6ffac4d5142e91b4a5fd4c9af1cd

package/dist/models/EscrowHold.d.ts

@@ -141,6 +141,7 @@ export declare const EscrowHoldValidator: z.ZodObject<{
             "pin-locked": "pin-locked";
             started: "started";
             reminder: "reminder";
+            "pin-sign-in": "pin-sign-in";
         }>;
         sentAt: z.ZodDate;
     }, z.core.$strip>>>;
@@ -166,7 +167,9 @@ export declare const cancelEscrowHold: (id: string, cancelledBy: "did" | "system
 export declare const cancelEscrowHoldByCancelToken: (id: string, cancelTokenHash: string) => Promise<EscrowHold | null>;
 export declare const recordEscrowHoldConfirmation: (id: string, confirmedAt: Date, releaseAfter: Date) => Promise<EscrowHold | null>;
 export declare const completeEscrowHold: (id: string) => Promise<EscrowHold | null>;
-export declare const hasCompletedEscrowHoldForVersion: (authProvider: AuthProviderMapping, shareVersion: number) => Promise<boolean>;
+export declare const hasCompletedEscrowHoldForVersion: (authProvider: AuthProviderMapping, shareVersion: number, options?: {
+    completedAfter?: Date;
+}) => Promise<boolean>;
 export declare const expireStaleEscrowHolds: (now: Date) => Promise<number>;
 export declare const markClaimedEscrowHoldFailed: (id: string, reason: "pin-mismatch" | "pin-locked" | "release-failed", completedAt: Date) => Promise<void>;
 export declare const retryClaimedEscrowHold: (id: string, completedAt: Date) => Promise<void>;

package/dist/models/UserKey.d.ts

@@ -126,6 +126,49 @@ export declare const EscrowPinValidator: z.ZodObject<{
     disabledAt: z.ZodOptional<z.ZodDate>;
     shareVersion: z.ZodNumber;
 }, z.core.$strip>;
+export declare const ESCROW_ENROLLMENT_LEASE_TTL_MS = 120000;
+export declare const ESCROW_PIN_COMPARE_TTL_MS = 120000;
+export declare const EscrowEnrollmentLeaseValidator: z.ZodObject<{
+    id: z.ZodString;
+    expiresAt: z.ZodDate;
+    action: z.ZodEnum<{
+        enroll: "enroll";
+        replace: "replace";
+        disable: "disable";
+        carry: "carry";
+        rewrap: "rewrap";
+    }>;
+    pinAction: z.ZodEnum<{
+        set: "set";
+        change: "change";
+        clear: "clear";
+        keep: "keep";
+    }>;
+    pin: z.ZodEnum<{
+        clear: "clear";
+        keep: "keep";
+        fresh: "fresh";
+    }>;
+    pinSalt: z.ZodOptional<z.ZodString>;
+    optOut: z.ZodOptional<z.ZodBoolean>;
+    shareVersion: z.ZodNumber;
+    authorityGeneration: z.ZodString;
+    expectedEnrollmentVersion: z.ZodNumber;
+    expectedPinGeneration: z.ZodOptional<z.ZodNumber>;
+    enrollmentEpoch: z.ZodNumber;
+    sourceBlobHash: z.ZodNullable<z.ZodString>;
+    measurements: z.ZodObject<{
+        imageSha384: z.ZodOptional<z.ZodString>;
+        pcr0: z.ZodOptional<z.ZodString>;
+        pcr1: z.ZodOptional<z.ZodString>;
+        pcr2: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type EscrowEnrollmentLease = z.infer<typeof EscrowEnrollmentLeaseValidator>;
+export declare const EscrowPinCompareValidator: z.ZodObject<{
+    id: z.ZodString;
+    expiresAt: z.ZodDate;
+}, z.core.$strip>;
 export declare const EscrowPinStatusValidator: z.ZodObject<{
     state: z.ZodEnum<{
         none: "none";
@@ -135,6 +178,7 @@ export declare const EscrowPinStatusValidator: z.ZodObject<{
     }>;
     enabled: z.ZodBoolean;
     attemptsRemaining: z.ZodNumber;
+    wrongAttempts: z.ZodOptional<z.ZodNumber>;
     salt: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const getEscrowPinStatus: (userKey: MongoUserKeyType) => z.infer<typeof EscrowPinStatusValidator>;
@@ -192,6 +236,46 @@ declare const MongoUserKeyBaseValidator: z.ZodObject<{
         shareVersion: z.ZodNumber;
     }, z.core.$strip>>;
     escrowOptedOutAt: z.ZodOptional<z.ZodDate>;
+    escrowEnrollmentLease: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        expiresAt: z.ZodDate;
+        action: z.ZodEnum<{
+            enroll: "enroll";
+            replace: "replace";
+            disable: "disable";
+            carry: "carry";
+            rewrap: "rewrap";
+        }>;
+        pinAction: z.ZodEnum<{
+            set: "set";
+            change: "change";
+            clear: "clear";
+            keep: "keep";
+        }>;
+        pin: z.ZodEnum<{
+            clear: "clear";
+            keep: "keep";
+            fresh: "fresh";
+        }>;
+        pinSalt: z.ZodOptional<z.ZodString>;
+        optOut: z.ZodOptional<z.ZodBoolean>;
+        shareVersion: z.ZodNumber;
+        authorityGeneration: z.ZodString;
+        expectedEnrollmentVersion: z.ZodNumber;
+        expectedPinGeneration: z.ZodOptional<z.ZodNumber>;
+        enrollmentEpoch: z.ZodNumber;
+        sourceBlobHash: z.ZodNullable<z.ZodString>;
+        measurements: z.ZodObject<{
+            imageSha384: z.ZodOptional<z.ZodString>;
+            pcr0: z.ZodOptional<z.ZodString>;
+            pcr1: z.ZodOptional<z.ZodString>;
+            pcr2: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+    escrowPinCompares: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        expiresAt: z.ZodDate;
+    }, z.core.$strip>>>;
     _id: z.ZodOptional<z.ZodString>;
     contactMethod: z.ZodObject<{
         type: z.ZodEnum<{
@@ -271,6 +355,7 @@ declare const MongoUserKeyBaseValidator: z.ZodObject<{
         provisional: "provisional";
     }>>;
     provisionalCreatedAt: z.ZodOptional<z.ZodDate>;
+    securityEpoch: z.ZodOptional<z.ZodNumber>;
     createdAt: z.ZodDate;
     updatedAt: z.ZodDate;
 }, z.core.$strip>;
@@ -328,6 +413,46 @@ export declare const MongoUserKeyValidator: z.ZodObject<{
         shareVersion: z.ZodNumber;
     }, z.core.$strip>>;
     escrowOptedOutAt: z.ZodOptional<z.ZodDate>;
+    escrowEnrollmentLease: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        expiresAt: z.ZodDate;
+        action: z.ZodEnum<{
+            enroll: "enroll";
+            replace: "replace";
+            disable: "disable";
+            carry: "carry";
+            rewrap: "rewrap";
+        }>;
+        pinAction: z.ZodEnum<{
+            set: "set";
+            change: "change";
+            clear: "clear";
+            keep: "keep";
+        }>;
+        pin: z.ZodEnum<{
+            clear: "clear";
+            keep: "keep";
+            fresh: "fresh";
+        }>;
+        pinSalt: z.ZodOptional<z.ZodString>;
+        optOut: z.ZodOptional<z.ZodBoolean>;
+        shareVersion: z.ZodNumber;
+        authorityGeneration: z.ZodString;
+        expectedEnrollmentVersion: z.ZodNumber;
+        expectedPinGeneration: z.ZodOptional<z.ZodNumber>;
+        enrollmentEpoch: z.ZodNumber;
+        sourceBlobHash: z.ZodNullable<z.ZodString>;
+        measurements: z.ZodObject<{
+            imageSha384: z.ZodOptional<z.ZodString>;
+            pcr0: z.ZodOptional<z.ZodString>;
+            pcr1: z.ZodOptional<z.ZodString>;
+            pcr2: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+    escrowPinCompares: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        expiresAt: z.ZodDate;
+    }, z.core.$strip>>>;
     _id: z.ZodOptional<z.ZodString>;
     contactMethod: z.ZodObject<{
         type: z.ZodEnum<{
@@ -407,6 +532,7 @@ export declare const MongoUserKeyValidator: z.ZodObject<{
         provisional: "provisional";
     }>>;
     provisionalCreatedAt: z.ZodOptional<z.ZodDate>;
+    securityEpoch: z.ZodOptional<z.ZodNumber>;
     createdAt: z.ZodDate;
     updatedAt: z.ZodDate;
 }, z.core.$loose>;
@@ -519,6 +645,31 @@ export declare const getUserKeysCollection: () => import("mongodb").Collection<{
         disabledAt?: Date | undefined;
     } | undefined;
     escrowOptedOutAt?: Date | undefined;
+    escrowEnrollmentLease?: {
+        id: string;
+        expiresAt: Date;
+        action: "enroll" | "replace" | "disable" | "carry" | "rewrap";
+        pinAction: "set" | "change" | "clear" | "keep";
+        pin: "clear" | "keep" | "fresh";
+        shareVersion: number;
+        authorityGeneration: string;
+        expectedEnrollmentVersion: number;
+        enrollmentEpoch: number;
+        sourceBlobHash: string | null;
+        measurements: {
+            imageSha384?: string | undefined;
+            pcr0?: string | undefined;
+            pcr1?: string | undefined;
+            pcr2?: string | undefined;
+        };
+        pinSalt?: string | undefined;
+        optOut?: boolean | undefined;
+        expectedPinGeneration?: number | undefined;
+    } | undefined;
+    escrowPinCompares?: {
+        id: string;
+        expiresAt: Date;
+    }[] | undefined;
     _id?: string | undefined;
     authShare?: {
         encryptedData: string;
@@ -531,6 +682,7 @@ export declare const getUserKeysCollection: () => import("mongodb").Collection<{
     migratedAt?: Date | undefined;
     sssActivationState?: "active" | "provisional" | undefined;
     provisionalCreatedAt?: Date | undefined;
+    securityEpoch?: number | undefined;
 }>;
 export declare const createUserKeysIndexes: () => Promise<void>;
 export declare const ensureUserKeysIndexes: () => Promise<void>;
@@ -543,6 +695,7 @@ export declare const upsertUserKey: (contactMethod: ContactMethod, data: Partial
 export declare const upsertUserKeyByAuthProvider: (contactMethod: ContactMethod, authProvider: AuthProviderMapping, data: Partial<Omit<MongoUserKeyType, "_id" | "contactMethod" | "createdAt" | "authProviders">>, expectedVersion?: number) => Promise<MongoUserKeyType>;
 export declare const addAuthProviderToUserKey: (contactMethod: ContactMethod, authProvider: AuthProviderMapping) => Promise<void>;
 export declare const addRecoveryMethodToUserKey: (contactMethod: ContactMethod, recoveryMethod: RecoveryMethod) => Promise<void>;
+export declare const getSecurityEpoch: (userKey: Pick<MongoUserKeyType, "securityEpoch">) => number;
 export declare const setEscrowBlobByAuthProvider: (authProvider: AuthProviderMapping, blob: Omit<EscrowBlob, "enrollmentEpoch" | "blobHash">, expectedShareVersion: number, pin?: {
     salt: string;
 }, carryFrom?: {
@@ -552,6 +705,28 @@ export declare const setEscrowBlobByAuthProvider: (authProvider: AuthProviderMap
     enrollmentEpoch: number;
     expectedBlob?: EscrowBlob;
     expectedPin?: MongoUserKeyType["escrowPin"];
+}, expectedPinCharges?: {
+    failedAttempts: number;
+    verifiedFailedAttempts: number;
+}) => Promise<MongoUserKeyType | null>;
+export interface ClaimEscrowEnrollmentLeaseInput {
+    lease: EscrowEnrollmentLease;
+    expectedBlob?: EscrowBlob;
+    expectedPin?: MongoUserKeyType['escrowPin'];
+    requireOptedIn: boolean;
+}
+export declare const claimEscrowEnrollmentLease: (authProvider: AuthProviderMapping, input: ClaimEscrowEnrollmentLeaseInput) => Promise<MongoUserKeyType | null>;
+export declare const releaseEscrowEnrollmentLease: (authProvider: AuthProviderMapping, leaseId: string) => Promise<void>;
+export interface EscrowAuthorityCommit {
+    envelope: EscrowBlob['envelope'] | null;
+    authorityGeneration: string;
+    enrollmentVersion: number;
+    enrollmentEpoch: number;
+    receipt?: AuthorityRecord;
+    stateProof?: AuthorityRecord;
+}
+export declare const commitEscrowEnrollmentLease: (authProvider: AuthProviderMapping, lease: EscrowEnrollmentLease, commit: EscrowAuthorityCommit, { adoptWithoutLease }?: {
+    adoptWithoutLease?: boolean;
 }) => Promise<MongoUserKeyType | null>;
 export declare const rewrapEscrowBlobByAuthProvider: (authProvider: AuthProviderMapping, oldBlob: EscrowBlob, oldPin: MongoUserKeyType["escrowPin"], newEnvelope: EscrowBlob["envelope"], identity: Pick<EscrowBlob, "enclaveKeyId" | "enclaveMode" | "measurements">, authority?: Pick<AuthorityMutationResult, "authorityGeneration" | "enrollmentVersion"> & {
     receipt?: AuthorityRecord;
@@ -566,7 +741,8 @@ export declare const clearEscrowByAuthProvider: (authProvider: AuthProviderMappi
     };
 }) => Promise<MongoUserKeyType | null>;
 export declare const setEscrowOptInByAuthProvider: (authProvider: AuthProviderMapping) => Promise<MongoUserKeyType | null>;
-export declare const reserveEscrowPinAttempt: (authProvider: AuthProviderMapping, shareVersion: number, expectedCiphertext?: string) => Promise<MongoUserKeyType | null>;
+export declare const reserveEscrowPinAttempt: (authProvider: AuthProviderMapping, shareVersion: number, expectedCiphertext?: string, compareId?: string) => Promise<MongoUserKeyType | null>;
+export declare const releaseEscrowPinCompare: (authProvider: AuthProviderMapping, compareId: string) => Promise<void>;
 export declare const refundEscrowPinAttempt: (authProvider: AuthProviderMapping, shareVersion: number, expectedCiphertext: string) => Promise<void>;
 export declare const recordEscrowPinFailure: (authProvider: AuthProviderMapping, shareVersion: number, expectedCiphertext: string) => Promise<MongoUserKeyType | null>;
 export declare const disableEscrowPin: (authProvider: AuthProviderMapping, shareVersion?: number, expectedCiphertext?: string) => Promise<boolean>;
@@ -591,8 +767,30 @@ export interface CompleteIdentityRebindInput {
     newContactMethod: ContactMethod;
     primaryDid: string;
     authShare: ServerEncryptedShare;
+    expectedShareVersion?: number;
+    expectedSecurityEpoch: number;
 }
 export declare const completeIdentityRebind: (input: CompleteIdentityRebindInput) => Promise<{
     shareVersion: number;
     methodsRequiringConfirmation: RecoveryMethod["type"][];
 } | null>;
+export interface LinkAuthProviderKeepingSharesInput {
+    oldAuthProvider: AuthProviderMapping;
+    newAuthProvider: AuthProviderMapping;
+    primaryDid: string;
+    shareVersion: number;
+    securityEpoch: number;
+}
+export declare const linkAuthProviderKeepingShares: (input: LinkAuthProviderKeepingSharesInput) => Promise<{
+    shareVersion: number;
+} | null>;
+export interface RevokeOtherDeviceSharesInput {
+    authProvider: AuthProviderMapping;
+    primaryDid: string;
+    expectedShareVersion: number;
+    authShare: ServerEncryptedShare;
+}
+export declare const revokeOtherDeviceShares: (input: RevokeOtherDeviceSharesInput) => Promise<{
+    shareVersion: number;
+    methodsRequiringConfirmation: RecoveryMethod["type"][];
+} | null>;