@learncard/lca-api-service 1.6.0 → 1.6.1

package/package.json

@@ -1,11 +1,11 @@
 {
     "name": "@learncard/lca-api-service",
-    "version": "1.6.0",
+    "version": "1.6.1",
     "description": "",
     "engines": {
         "node": ">=24.12 <25"
     },
-    "packageManager": "bun@1.4.2",
+    "packageManager": "bun@1.4.4",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
     "scripts": {
@@ -68,13 +68,13 @@
         "@fastify/static": "^10.1.1",
         "@learncard/core": "9.4.41",
         "@learncard/did-web-plugin": "1.1.41",
-        "@learncard/didkit-plugin": "1.10.6",
-        "@learncard/didkit-plugin-node": "0.3.6",
+        "@learncard/didkit-plugin": "1.10.7",
+        "@learncard/didkit-plugin-node": "0.3.7",
         "@learncard/email-templates": "1.2.1",
         "@learncard/helpers": "1.7.1",
-        "@learncard/init": "2.5.6",
+        "@learncard/init": "2.5.7",
         "@learncard/types": "5.24.0",
-        "@learncard/sss-key-manager": "0.2.4",
+        "@learncard/sss-key-manager": "0.2.5",
         "@sentry/serverless": "^7.61.0",
         "@trpc/server": "11.8.0",
         "@types/jsonwebtoken": "^9.0.8",

package/project.json

@@ -59,7 +59,7 @@
         },
         "test": {
             "executor": "nx:run-script",
-            "inputs": ["source", "tests"],
+            "inputs": ["source", "tests", "ciTestConfig"],
             "options": {
                 "script": "test"
             }

package/src/models/EscrowHold.ts

@@ -282,7 +282,8 @@ export const findEscrowHoldsPendingEnclaveCancellation = async (
             enclaveCancelPendingAt: { $exists: true },
             enclaveCancelConfirmedAt: { $exists: false },
         })
-        .sort({ enclaveCancelAttempts: 1, releaseAfter: 1 })
+        // Mongo sorts are unstable on ties; the unique ID makes bounded batches repeatable.
+        .sort({ enclaveCancelAttempts: 1, releaseAfter: 1, _id: 1 })
         .limit(limit)
         .toArray();
 
@@ -499,7 +500,8 @@ export const findEscrowHoldsPendingStartNotification = async (
 ): Promise<EscrowHold[]> =>
     getEscrowHoldsCollection()
         .find({ status: 'pending', startedNotificationPending: true })
-        .sort({ startedNotificationAttemptedAt: 1, requestedAt: 1 })
+        // Keep tied start-notification batches deterministic before the limit.
+        .sort({ startedNotificationAttemptedAt: 1, requestedAt: 1, _id: 1 })
         .limit(limit)
         .toArray();
 
@@ -563,7 +565,8 @@ export const findEscrowHoldsDueForReminder = async (
             releaseAfter: { $lte: new Date(now.getTime() + ESCROW_HOLD_REMINDER_WINDOW_MS) },
             'notifications.kind': { $ne: 'reminder' },
         })
-        .sort({ reminderAttemptedAt: 1, releaseAfter: 1 })
+        // Keep tied reminder batches deterministic before the limit.
+        .sort({ reminderAttemptedAt: 1, releaseAfter: 1, _id: 1 })
         .limit(limit)
         .toArray();
 

package/src/models/UserKey.ts

@@ -1301,6 +1301,12 @@ export const activateUserKeyByAuthProvider = async (
 /**
  * Lazily discard abandoned migration shares after the P0-1 TTL. New-user
  * provisional records are excluded because their keyProvider is already SSS.
+ *
+ * A migration with a confirmed escrow enrollment is not abandoned: the user
+ * skipped the PIN, but escrow can recover them, and staying provisional keeps
+ * the faster Web3Auth re-derive on new devices. Such records stay until the
+ * user activates (e.g. sets a PIN) or operators activate them before Web3Auth
+ * is retired (internal-docs/architecture/web3auth-sss-migration-runbook.md).
  */
 export const purgeExpiredProvisionalMigrationByAuthProvider = async (
     authProvider: AuthProviderMapping,
@@ -1313,6 +1319,14 @@ export const purgeExpiredProvisionalMigrationByAuthProvider = async (
             keyProvider: 'web3auth',
             sssActivationState: 'provisional',
             provisionalCreatedAt: { $lte: cutoff },
+            $nor: [
+                {
+                    escrowBlob: { $exists: true },
+                    recoveryMethods: {
+                        $elemMatch: { type: 'escrow', confirmationStatus: 'confirmed' },
+                    },
+                },
+            ],
         },
         {
             $set: {

package/test/jobs/escrowHoldReminders.spec.ts

@@ -15,6 +15,13 @@ import {
     hashEscrowResumeToken,
     recordEscrowHoldNotification,
     computeEffectiveReleaseAfter,
+    findEscrowHoldsDueForReminder,
+    findEscrowHoldsPendingStartNotification,
+    findEscrowHoldsPendingEnclaveCancellation,
+    claimEscrowHoldForReminder,
+    releaseEscrowReminderClaim,
+    recordEscrowStartNotificationAttempt,
+    recordEscrowEnclaveCancelAttempt,
     ESCROW_RELEASE_TIME_MARGIN_MS,
     ESCROW_RELEASE_WARNING_GAP_MS,
     type AuthProviderMapping,
@@ -41,7 +48,11 @@ const makeProvider = (): AuthProviderMapping => {
 
 /** Every seed() call gets its own authProvider (see test/models/escrow.spec.ts
  * for why: only one pending hold-policy hold is allowed per authProvider). */
-const seed = async (releaseAfter: Date, releasePolicy: 'hold' | 'pin' = 'hold') => {
+const seed = async (
+    releaseAfter: Date,
+    releasePolicy: 'hold' | 'pin' = 'hold',
+    holdId = randomUUID()
+) => {
     const provider = makeProvider();
     await upsertUserKeyByAuthProvider(
         { type: 'email', value: `${provider.id}@example.com` },
@@ -54,7 +65,7 @@ const seed = async (releaseAfter: Date, releasePolicy: 'hold' | 'pin' = 'hold')
     return createEscrowHold({
         holdRecord: {
             hold: {
-                holdId: randomUUID(),
+                holdId,
                 did: 'did:key:test',
                 shareVersion: 1,
                 blobHash: 'ab'.repeat(32),
@@ -117,6 +128,75 @@ afterAll(async () => {
 });
 
 describe('runEscrowHoldReminders', () => {
+    describe.each(['reminder', 'started', 'cancelled'] as const)('%s queue ordering', queue => {
+        it.each([false, true])(
+            'keeps tied batches stable and rotates retries (previously attempted: %s)',
+            async previouslyAttempted => {
+                const now = new Date();
+                const previousAttempt = new Date(now.getTime() - HOUR);
+                // More than a default delivery batch. Insert backwards so physical
+                // insertion order cannot accidentally satisfy the expected ID order.
+                const ids = Array.from(
+                    { length: 13 },
+                    (_, index) => `00000000-0000-4000-8000-${String(index + 1).padStart(12, '0')}`
+                );
+                for (const id of [...ids].reverse()) {
+                    await seed(new Date(now.getTime() + HOUR), 'hold', id);
+                }
+                await getEscrowHoldsCollection().updateMany(
+                    {},
+                    {
+                        $set: {
+                            requestedAt: previousAttempt,
+                            ...(queue === 'started' ? { startedNotificationPending: true } : {}),
+                            ...(queue === 'cancelled'
+                                ? {
+                                      status: 'cancelled' as const,
+                                      enclaveCancelPendingAt: previousAttempt,
+                                      enclaveCancelAttempts: previouslyAttempted ? 2 : 0,
+                                  }
+                                : previouslyAttempted
+                                  ? queue === 'reminder'
+                                      ? { reminderAttemptedAt: previousAttempt }
+                                      : { startedNotificationAttemptedAt: previousAttempt }
+                                  : {}),
+                        },
+                    }
+                );
+                const readBatch = () =>
+                    queue === 'reminder'
+                        ? findEscrowHoldsDueForReminder(now, 5)
+                        : queue === 'started'
+                          ? findEscrowHoldsPendingStartNotification(5)
+                          : findEscrowHoldsPendingEnclaveCancellation(5);
+
+                for (let repeat = 0; repeat < 3; repeat += 1) {
+                    expect((await readBatch()).map(hold => hold._id)).toEqual(ids.slice(0, 5));
+                }
+                // Failed deliveries remain eligible. Updating their real attempt
+                // markers must put untouched rows first, even with tied timestamps.
+                for (let offset = 0; offset < ids.length; offset += 5) {
+                    const batch = await readBatch();
+                    const remaining = Math.min(5, ids.length - offset);
+                    expect(batch.slice(0, remaining).map(hold => hold._id)).toEqual(
+                        ids.slice(offset, offset + remaining)
+                    );
+                    for (const hold of batch) {
+                        if (queue === 'reminder') {
+                            const claimed = await claimEscrowHoldForReminder(hold._id, now);
+                            expect(claimed).not.toBeNull();
+                            if (claimed) await releaseEscrowReminderClaim(claimed);
+                        } else if (queue === 'started') {
+                            await recordEscrowStartNotificationAttempt(hold._id, now);
+                        } else {
+                            expect(await recordEscrowEnclaveCancelAttempt(hold._id)).toBe(true);
+                        }
+                    }
+                }
+            }
+        );
+    });
+
     it('bounds cancellation retries and gives unattempted cancellations priority', async () => {
         const now = new Date();
         const holds = await Promise.all(
@@ -129,9 +209,13 @@ describe('runEscrowHoldReminders', () => {
         await runEscrowHoldReminders({ now, limit: 200 });
         const firstRun = await Promise.all(holds.map(hold => findEscrowHoldById(hold._id)));
         expect(firstRun.map(hold => hold?.enclaveCancelAttempts).sort()).toEqual([0, 0, 1, 1]);
-        const unattempted = firstRun.find(hold => hold?.enclaveCancelAttempts === 0)!;
+        // UUIDs are ASCII: default string ordering matches Mongo's byte ordering.
+        const unattemptedId = firstRun
+            .filter(hold => hold?.enclaveCancelAttempts === 0)
+            .map(hold => hold!._id)
+            .sort()[0]!;
         await runEscrowHoldReminders({ now, limit: 1 });
-        expect((await findEscrowHoldById(unattempted._id))?.enclaveCancelAttempts).toBe(1);
+        expect((await findEscrowHoldById(unattemptedId))?.enclaveCancelAttempts).toBe(1);
         for (const hold of holds) {
             const stored = await findEscrowHoldById(hold._id);
             expect(stored?.enclaveCancelPendingAt).toBeInstanceOf(Date);

package/test/keys-lifecycle-invariants.spec.ts

@@ -676,6 +676,82 @@ describe('P0-1 provisional SSS activation', () => {
     });
 });
 
+describe('P0-1 provisional purge spares escrow-enrolled migrations', () => {
+    const expiredMigration = (
+        email: string,
+        uid: string,
+        did: string,
+        escrow: { blob: boolean; method?: 'confirmed' | 'pending' }
+    ): MongoUserKeyType => {
+        const key = makeUserKey(email, uid, did, 'migrated-share');
+
+        Object.assign(key, {
+            keyProvider: 'web3auth' as const,
+            sssActivationState: 'provisional' as const,
+            provisionalCreatedAt: new Date(Date.now() - PROVISIONAL_MIGRATION_TTL_MS - 1_000),
+            recoveryMethods: escrow.method
+                ? [
+                      {
+                          type: 'escrow' as const,
+                          createdAt: new Date(),
+                          confirmationStatus: escrow.method,
+                          ...(escrow.method === 'confirmed' ? { confirmedAt: new Date() } : {}),
+                          shareVersion: 1,
+                      },
+                  ]
+                : [],
+            // Only presence matters to the purge filter.
+            ...(escrow.blob
+                ? { escrowBlob: { shareVersion: 1 } as unknown as MongoUserKeyType['escrowBlob'] }
+                : {}),
+        });
+
+        return key;
+    };
+
+    it.each([
+        ['confirmed escrow enrollment', false, { blob: true, method: 'confirmed' as const }],
+        [
+            'escrow blob without a confirmed method',
+            true,
+            { blob: true, method: 'pending' as const },
+        ],
+        ['confirmed method without a blob', true, { blob: false, method: 'confirmed' as const }],
+    ])('%s → purged: %s', async (_name, purged, escrow) => {
+        const suffix = `${Date.now()}-${randomUUID()}`;
+        const email = `escrow-purge-${suffix}@example.com`;
+        const uid = `uid-${suffix}`;
+        const { learnCard } = await getUser('5'.repeat(64));
+        const collection = getUserKeysCollection();
+
+        await collection.insertOne(expiredMigration(email, uid, learnCard.id.did(), escrow));
+
+        try {
+            const result = await getClient().keys.getAuthShare({
+                authToken: makeMockToken(email, uid),
+                providerType: 'firebase',
+            });
+            const stored = await collection.findOne({
+                authProviders: { $elemMatch: { type: 'firebase', id: uid } },
+            });
+
+            if (purged) {
+                expect(result?.authShare).toBeNull();
+                expect(stored?.authShare).toBeUndefined();
+                expect(stored?.escrowBlob).toBeUndefined();
+                expect(stored?.sssActivationState).toBeUndefined();
+            } else {
+                expect(stored?.authShare?.encryptedData).toBe('migrated-share');
+                expect(stored?.escrowBlob).toBeDefined();
+                expect(stored?.sssActivationState).toBe('provisional');
+                expect(stored?.keyProvider).toBe('web3auth');
+            }
+        } finally {
+            await collection.deleteMany({ 'contactMethod.value': email });
+        }
+    });
+});
+
 describe('P0-6 fresh DID authorization', () => {
     it('issues short-lived challenges that can only be consumed once', async () => {
         const did = `did:key:${randomUUID()}`;

package/tsconfig.json

@@ -17,21 +17,20 @@
         "emitDeclarationOnly": true,
         "sourceMap": true,
         "rootDir": ".",
-        "baseUrl": ".",
         "paths": {
-            "@accesslayer/*": ["src/accesslayer/*"],
-            "@cache": ["src/cache/index.ts"],
-            "@cache/*": ["src/cache/*"],
-            "@config/*": ["src/config/*"],
-            "@environment": ["src/config/environment.ts"],
-            "@helpers/*": ["src/helpers/*"],
-            "@instance": ["src/instance.ts"],
-            "@firebase": ["src/firebase.ts"],
-            "@mongo": ["src/mongo.ts"],
-            "@models": ["src/models/index.ts"],
-            "@routes": ["src/routes/index.ts"],
-            "@routes/*": ["src/routes/*"],
-            "types/*": ["src/types/*"]
+            "@accesslayer/*": ["./src/accesslayer/*"],
+            "@cache": ["./src/cache/index.ts"],
+            "@cache/*": ["./src/cache/*"],
+            "@config/*": ["./src/config/*"],
+            "@environment": ["./src/config/environment.ts"],
+            "@helpers/*": ["./src/helpers/*"],
+            "@instance": ["./src/instance.ts"],
+            "@firebase": ["./src/firebase.ts"],
+            "@mongo": ["./src/mongo.ts"],
+            "@models": ["./src/models/index.ts"],
+            "@routes": ["./src/routes/index.ts"],
+            "@routes/*": ["./src/routes/*"],
+            "types/*": ["./src/types/*"]
         },
         "allowJs": false
     },