@learncard/lca-api-service 1.3.2 → 1.5.0

package/test/jobs/escrowBlobRewrap.spec.ts

@@ -0,0 +1,262 @@
+import { randomUUID } from 'crypto';
+import { beforeAll, afterAll, afterEach, describe, it, expect } from 'vitest';
+import { client } from '@mongo';
+import { encryptEscrowBlob, generateEscrowKeyPair } from '@learncard/sss-key-manager';
+import {
+    createUserKeysIndexes,
+    getUserKeysCollection,
+    upsertUserKeyByAuthProvider,
+    setEscrowBlobByAuthProvider,
+    findUserKeyByAuthProvider,
+    createEscrowHoldsIndexes,
+    getEscrowHoldsCollection,
+    createEscrowHold,
+    generateEscrowResumeToken,
+    hashEscrowResumeToken,
+    type AuthProviderMapping,
+    type EscrowBlob,
+} from '@models';
+import { __setEscrowEnclaveForTests } from '../../src/services/escrow-enclave';
+import { runEscrowBlobRewrap } from '../../src/jobs/escrowBlobRewrap';
+
+const seededProviderIds: string[] = [];
+
+const makeProvider = (): AuthProviderMapping => {
+    const provider: AuthProviderMapping = {
+        type: 'firebase',
+        id: `escrow-rewrap-job-${randomUUID()}`,
+    };
+    seededProviderIds.push(provider.id);
+    return provider;
+};
+
+let previousKeys: { publicKey: string; privateKey: string };
+let currentKeys: { publicKey: string; privateKey: string };
+
+/**
+ * Seeds a UserKey with an escrow blob sealed under the given (public)
+ * key/keyId. Only creates the account on the FIRST call for a given
+ * provider — a second call (used to simulate a mid-run re-enrollment onto a
+ * different key) must not re-run `upsertUserKeyByAuthProvider` with the same
+ * `authShare`, which would bump the account's own `shareVersion` and break
+ * the escrow blob's `expectedShareVersion: 1` CAS below.
+ */
+const seedBlob = async (
+    provider: AuthProviderMapping,
+    keyId: string,
+    publicKey: string
+): Promise<EscrowBlob> => {
+    if (!(await findUserKeyByAuthProvider(provider.type, provider.id))) {
+        await upsertUserKeyByAuthProvider(
+            { type: 'email', value: `${provider.id}@example.com` },
+            provider,
+            {
+                primaryDid: 'did:key:test',
+                authShare: { encryptedData: 'data', encryptedDek: 'dek', iv: 'iv' },
+            }
+        );
+    }
+    const envelope = await encryptEscrowBlob(
+        { recoveryShare: 'ab'.repeat(33), did: 'did:key:test', shareVersion: 1 },
+        publicKey,
+        keyId
+    );
+    const stored = await setEscrowBlobByAuthProvider(
+        provider,
+        {
+            envelope,
+            enclaveKeyId: keyId,
+            enclaveMode: 'software',
+            measurements: {},
+            shareVersion: 1,
+            createdAt: new Date(),
+        },
+        1
+    );
+    return stored!.escrowBlob!;
+};
+
+beforeAll(async () => {
+    process.env.IS_E2E_TEST = 'true';
+    process.env.SEED ||= 'a'.repeat(64);
+    previousKeys = await generateEscrowKeyPair();
+    currentKeys = await generateEscrowKeyPair();
+    process.env.ESCROW_ENCLAVE_MODE = 'software';
+    process.env.ESCROW_ENCLAVE_SOFTWARE_PRIVATE_KEYS_JSON = JSON.stringify({
+        current: currentKeys.privateKey,
+        previous: previousKeys.privateKey,
+    });
+    process.env.ESCROW_ENCLAVE_ACTIVE_KEY_ID = 'current';
+    __setEscrowEnclaveForTests(undefined);
+    await client.connect();
+    await createUserKeysIndexes();
+    await createEscrowHoldsIndexes();
+});
+
+afterEach(async () => {
+    const ids = seededProviderIds.splice(0);
+    if (ids.length === 0) return;
+    await getUserKeysCollection().deleteMany({ 'authProviders.id': { $in: ids } });
+    await getEscrowHoldsCollection().deleteMany({ 'authProvider.id': { $in: ids } });
+});
+
+afterAll(async () => {
+    delete process.env.ESCROW_ENCLAVE_MODE;
+    delete process.env.ESCROW_ENCLAVE_SOFTWARE_PRIVATE_KEYS_JSON;
+    delete process.env.ESCROW_ENCLAVE_ACTIVE_KEY_ID;
+    __setEscrowEnclaveForTests(undefined);
+    await client.close();
+});
+
+describe('runEscrowBlobRewrap', () => {
+    it('migrates a previous-key blob onto the current key: keyId now current, epoch and version unchanged, escrowPin untouched', async () => {
+        const provider = makeProvider();
+        const oldBlob = await seedBlob(provider, 'previous', previousKeys.publicKey);
+        await getUserKeysCollection().updateOne(
+            { 'authProviders.id': provider.id },
+            {
+                $set: {
+                    escrowPin: {
+                        salt: Buffer.alloc(16).toString('base64'),
+                        failedAttempts: 3,
+                        enabledAt: new Date(),
+                        shareVersion: 1,
+                    },
+                },
+            }
+        );
+
+        const result = await runEscrowBlobRewrap();
+
+        expect(result).toEqual({ rewrapped: 1, skippedPendingHold: 0, failed: 0 });
+        const stored = await findUserKeyByAuthProvider(provider.type, provider.id);
+        expect(stored?.escrowBlob?.enclaveKeyId).toBe('current');
+        expect(stored?.escrowBlob?.envelope.keyId).toBe('current');
+        expect(stored?.escrowBlob?.shareVersion).toBe(1);
+        expect(stored?.escrowBlob?.enrollmentEpoch).toBe(oldBlob.enrollmentEpoch);
+        expect(stored?.escrowBlob?.blobHash).not.toBe(oldBlob.blobHash);
+        expect(stored?.escrowPin?.failedAttempts).toBe(3);
+        // Idempotent: nothing left to migrate on a second run.
+        expect(await runEscrowBlobRewrap()).toEqual({
+            rewrapped: 0,
+            skippedPendingHold: 0,
+            failed: 0,
+        });
+    });
+
+    it('skips (does not touch) an account with a pending recovery hold', async () => {
+        const provider = makeProvider();
+        const oldBlob = await seedBlob(provider, 'previous', previousKeys.publicKey);
+        await createEscrowHold({
+            holdRecord: {
+                hold: {
+                    holdId: randomUUID(),
+                    did: 'did:key:test',
+                    shareVersion: 1,
+                    blobHash: oldBlob.blobHash,
+                    enrollmentEpoch: oldBlob.enrollmentEpoch,
+                    releasePolicy: 'hold',
+                    clientEphemeralPublicKey: 'public-key',
+                    createdLo: 0,
+                    createdHi: 0,
+                    policyVersion: 1,
+                    signature: 'test-signature',
+                },
+                holdDurationMs: 0,
+                ledgerSeq: 0,
+            },
+            authProvider: provider,
+            primaryDid: 'did:key:test',
+            shareVersion: 1,
+            identityProofType: 'auth-token',
+            requestedAt: new Date(),
+            releaseAfter: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
+            releasePolicy: 'hold',
+            clientEphemeralPublicKey: 'public-key',
+            resumeTokenHash: hashEscrowResumeToken(generateEscrowResumeToken()),
+        });
+
+        const result = await runEscrowBlobRewrap();
+
+        expect(result).toEqual({ rewrapped: 0, skippedPendingHold: 1, failed: 0 });
+        const stored = await findUserKeyByAuthProvider(provider.type, provider.id);
+        expect(stored?.escrowBlob).toEqual(oldBlob);
+    });
+
+    it('never touches a blob sealed under a truly unknown (never current, never previous) key', async () => {
+        const provider = makeProvider();
+        const unknown = await generateEscrowKeyPair();
+        const oldBlob = await seedBlob(provider, 'totally-unknown', unknown.publicKey);
+
+        const result = await runEscrowBlobRewrap();
+
+        expect(result).toEqual({ rewrapped: 0, skippedPendingHold: 0, failed: 0 });
+        const stored = await findUserKeyByAuthProvider(provider.type, provider.id);
+        expect(stored?.escrowBlob).toEqual(oldBlob);
+    });
+
+    it('concurrent runs never double-write the same account (CAS)', async () => {
+        const provider = makeProvider();
+        await seedBlob(provider, 'previous', previousKeys.publicKey);
+
+        const [a, b] = await Promise.all([runEscrowBlobRewrap(), runEscrowBlobRewrap()]);
+
+        expect(a.rewrapped + b.rewrapped).toBe(1);
+        expect(a.failed + b.failed).toBe(0);
+        const stored = await findUserKeyByAuthProvider(provider.type, provider.id);
+        expect(stored?.escrowBlob?.enclaveKeyId).toBe('current');
+    });
+
+    it('a user who re-enrolled onto the current key mid-run wins the race (CAS no-op)', async () => {
+        const provider = makeProvider();
+        await seedBlob(provider, 'previous', previousKeys.publicKey);
+        // Simulates a concurrent P9.2 sign-in re-enroll landing between the
+        // job's candidate read and its write: the account is already on the
+        // current key by the time the job's CAS write is attempted.
+        await seedBlob(provider, 'current', currentKeys.publicKey);
+
+        const result = await runEscrowBlobRewrap();
+
+        expect(result).toEqual({ rewrapped: 0, skippedPendingHold: 0, failed: 0 });
+    });
+
+    it('no-ops without querying Mongo when the enclave has no previous keys configured', async () => {
+        process.env.ESCROW_ENCLAVE_SOFTWARE_PRIVATE_KEYS_JSON = JSON.stringify({
+            current: currentKeys.privateKey,
+        });
+        __setEscrowEnclaveForTests(undefined);
+        try {
+            const provider = makeProvider();
+            const oldBlob = await seedBlob(provider, 'previous', previousKeys.publicKey);
+
+            const result = await runEscrowBlobRewrap();
+
+            expect(result).toEqual({ rewrapped: 0, skippedPendingHold: 0, failed: 0 });
+            const stored = await findUserKeyByAuthProvider(provider.type, provider.id);
+            expect(stored?.escrowBlob).toEqual(oldBlob);
+        } finally {
+            process.env.ESCROW_ENCLAVE_SOFTWARE_PRIVATE_KEYS_JSON = JSON.stringify({
+                current: currentKeys.privateKey,
+                previous: previousKeys.privateKey,
+            });
+            __setEscrowEnclaveForTests(undefined);
+        }
+    });
+
+    it('no-ops without touching the database when escrow is disabled', async () => {
+        const provider = makeProvider();
+        const oldBlob = await seedBlob(provider, 'previous', previousKeys.publicKey);
+        delete process.env.ESCROW_ENCLAVE_MODE;
+        __setEscrowEnclaveForTests(undefined);
+
+        try {
+            const result = await runEscrowBlobRewrap();
+            expect(result).toEqual({ rewrapped: 0, skippedPendingHold: 0, failed: 0 });
+            const stored = await findUserKeyByAuthProvider(provider.type, provider.id);
+            expect(stored?.escrowBlob).toEqual(oldBlob);
+        } finally {
+            process.env.ESCROW_ENCLAVE_MODE = 'software';
+            __setEscrowEnclaveForTests(undefined);
+        }
+    });
+});

package/test/jobs/escrowHoldReminders.spec.ts

@@ -0,0 +1,319 @@
+import { randomUUID } from 'crypto';
+import { beforeAll, afterAll, afterEach, describe, it, expect } from 'vitest';
+import { client } from '@mongo';
+import {
+    createUserKeysIndexes,
+    getUserKeysCollection,
+    upsertUserKeyByAuthProvider,
+    createEscrowHoldsIndexes,
+    getEscrowHoldsCollection,
+    createEscrowHold,
+    findEscrowHoldById,
+    completeEscrowHold,
+    cancelEscrowHold,
+    generateEscrowResumeToken,
+    hashEscrowResumeToken,
+    recordEscrowHoldNotification,
+    type AuthProviderMapping,
+} from '@models';
+import {
+    __setEscrowEnclaveForTests,
+    notifyEscrowHoldEvent,
+} from '../../src/services/escrow-enclave';
+import { escrowCancelTokenMatches, hashEscrowCancelToken } from '@helpers/escrowCancelToken';
+import { runEscrowHoldReminders } from '../../src/jobs/escrowHoldReminders';
+
+const HOUR = 60 * 60 * 1000;
+const seededProviderIds: string[] = [];
+
+const makeProvider = (): AuthProviderMapping => {
+    const provider: AuthProviderMapping = {
+        type: 'firebase',
+        id: `escrow-reminder-job-${randomUUID()}`,
+    };
+    seededProviderIds.push(provider.id);
+    return provider;
+};
+
+/** 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 provider = makeProvider();
+    await upsertUserKeyByAuthProvider(
+        { type: 'email', value: `${provider.id}@example.com` },
+        provider,
+        {
+            primaryDid: 'did:key:test',
+            authShare: { encryptedData: 'data', encryptedDek: 'dek', iv: 'iv' },
+        }
+    );
+    return createEscrowHold({
+        holdRecord: {
+            hold: {
+                holdId: randomUUID(),
+                did: 'did:key:test',
+                shareVersion: 1,
+                blobHash: 'ab'.repeat(32),
+                enrollmentEpoch: 1,
+                releasePolicy: 'hold',
+                clientEphemeralPublicKey: 'public-key',
+                createdLo: 0,
+                createdHi: 0,
+                policyVersion: 1,
+                signature: 'test-signature',
+            },
+            holdDurationMs: 0,
+            ledgerSeq: 0,
+        },
+        authProvider: provider,
+        primaryDid: 'did:key:test',
+        shareVersion: 1,
+        identityProofType: 'auth-token',
+        requestedAt: new Date(),
+        releaseAfter,
+        releasePolicy,
+        clientEphemeralPublicKey: 'public-key',
+        resumeTokenHash: hashEscrowResumeToken(generateEscrowResumeToken()),
+    });
+};
+
+beforeAll(async () => {
+    process.env.IS_E2E_TEST = 'true';
+    process.env.SEED ||= 'a'.repeat(64);
+    process.env.ESCROW_ENCLAVE_MODE = 'software';
+    process.env.ESCROW_ENCLAVE_SOFTWARE_PRIVATE_KEYS_JSON = JSON.stringify({
+        dummy: 'x'.repeat(10),
+    });
+    process.env.ESCROW_ENCLAVE_ACTIVE_KEY_ID = 'dummy';
+    __setEscrowEnclaveForTests(undefined);
+    await client.connect();
+    await createUserKeysIndexes();
+    await createEscrowHoldsIndexes();
+});
+
+afterEach(async () => {
+    const ids = seededProviderIds.splice(0);
+    if (ids.length === 0) return;
+    await getUserKeysCollection().deleteMany({ 'authProviders.id': { $in: ids } });
+    await getEscrowHoldsCollection().deleteMany({ 'authProvider.id': { $in: ids } });
+});
+
+afterAll(async () => {
+    delete process.env.ESCROW_ENCLAVE_MODE;
+    delete process.env.ESCROW_ENCLAVE_SOFTWARE_PRIVATE_KEYS_JSON;
+    delete process.env.ESCROW_ENCLAVE_ACTIVE_KEY_ID;
+    __setEscrowEnclaveForTests(undefined);
+    await client.close();
+});
+
+describe('runEscrowHoldReminders', () => {
+    it('bounds cancellation retries and gives unattempted cancellations priority', async () => {
+        const now = new Date();
+        const holds = await Promise.all(
+            Array.from({ length: 4 }, () => seed(new Date(now.getTime() + 7 * 24 * HOUR)))
+        );
+        for (const hold of holds) await cancelEscrowHold(hold._id, 'did');
+        // These legacy test records lack ciphertext: fail closed, but still rotate
+        // the bounded queue rather than retrying the same first three forever.
+        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, 1, 1, 1]);
+        const unattempted = firstRun.find(hold => hold?.enclaveCancelAttempts === 0)!;
+        await runEscrowHoldReminders({ now, limit: 1 });
+        expect((await findEscrowHoldById(unattempted._id))?.enclaveCancelAttempts).toBe(1);
+        for (const hold of holds) {
+            const stored = await findEscrowHoldById(hold._id);
+            expect(stored?.enclaveCancelPendingAt).toBeInstanceOf(Date);
+            expect(stored?.enclaveCancelConfirmedAt).toBeUndefined();
+        }
+    });
+
+    it('budgets both queues and moves failed starts behind unattempted holds', async () => {
+        const now = new Date();
+        const starts = await Promise.all(
+            Array.from({ length: 11 }, () => seed(new Date(now.getTime() + 7 * 24 * HOUR)))
+        );
+        await getEscrowHoldsCollection().updateMany(
+            { _id: { $in: starts.map(hold => hold._id) } },
+            { $set: { startedNotificationPending: true } }
+        );
+        const reminder = await seed(new Date(now.getTime() + HOUR));
+        const attempts: string[] = [];
+        const notify: typeof notifyEscrowHoldEvent = async event => {
+            attempts.push(event.hold._id);
+            return false;
+        };
+        await runEscrowHoldReminders({ now, limit: 200, notify });
+        expect(attempts).toHaveLength(11); // Ten starts plus one reminder, not 200 starts.
+        expect(attempts).toContain(reminder._id);
+        const untouched = starts.find(hold => !attempts.includes(hold._id))!;
+        attempts.length = 0;
+        await runEscrowHoldReminders({ now: new Date(now.getTime() + HOUR / 2), limit: 1, notify });
+        expect(attempts[0]).toBe(untouched._id);
+        expect(attempts[1]).toBe(reminder._id);
+    });
+
+    it('retries an undelivered start notification with a cancel link', async () => {
+        const now = new Date();
+        const hold = await seed(new Date(now.getTime() + 7 * 24 * HOUR));
+        await getEscrowHoldsCollection().updateOne(
+            { _id: hold._id },
+            { $set: { startedNotificationPending: true } }
+        );
+        const failed = await runEscrowHoldReminders({
+            now,
+            notify: event =>
+                notifyEscrowHoldEvent(event, {
+                    send: async () => {
+                        throw new Error('Postmark unavailable');
+                    },
+                    sendPush: async () => ({ successCount: 1, failureCount: 0, failedTokens: [] }),
+                }),
+        });
+        expect(failed.failed).toBe(1);
+        expect((await findEscrowHoldById(hold._id))?.startedNotificationPending).toBe(true);
+        let cancelUrl = '';
+        await runEscrowHoldReminders({
+            now,
+            notify: event =>
+                notifyEscrowHoldEvent(event, {
+                    send: async notification => {
+                        if ('templateModel' in notification)
+                            cancelUrl = String(notification.templateModel.cancelUrl);
+                    },
+                    sendPush: async () => ({ successCount: 0, failureCount: 0, failedTokens: [] }),
+                }),
+        });
+        const stored = await findEscrowHoldById(hold._id);
+        expect(stored?.startedNotificationPending).toBe(false);
+        expect(stored?.notifications.map(entry => entry.kind)).toEqual(['started']);
+        expect(cancelUrl).toContain(hold._id);
+    });
+
+    it('failed reminder delivery preserves the original cancel link and retries next run', async () => {
+        const now = new Date();
+        const hold = await seed(new Date(now.getTime() + HOUR));
+        const originalToken = 'a'.repeat(64);
+        await getEscrowHoldsCollection().updateOne(
+            { _id: hold._id },
+            { $set: { cancelTokenHash: hashEscrowCancelToken(originalToken) } }
+        );
+        const result = await runEscrowHoldReminders({
+            now,
+            notify: event =>
+                notifyEscrowHoldEvent(event, {
+                    send: async () => {
+                        throw new Error('Postmark unavailable');
+                    },
+                    sendPush: async () => ({ successCount: 1, failureCount: 0, failedTokens: [] }),
+                }),
+        });
+        expect(result.failed).toBe(1);
+        const stored = await findEscrowHoldById(hold._id);
+        expect(escrowCancelTokenMatches(stored!, originalToken)).toBe(true);
+        expect(stored?.notifications).toEqual([]);
+        expect((await runEscrowHoldReminders({ now })).reminded).toBe(1);
+        expect(escrowCancelTokenMatches((await findEscrowHoldById(hold._id))!, originalToken)).toBe(
+            true
+        );
+    });
+
+    it('reminds a hold due within 24h exactly once, even racing two full job runs', async () => {
+        const now = new Date();
+        const hold = await seed(new Date(now.getTime() + 23 * HOUR));
+
+        const [a, b] = await Promise.all([
+            runEscrowHoldReminders({ now }),
+            runEscrowHoldReminders({ now }),
+        ]);
+
+        expect(a.reminded + b.reminded).toBe(1);
+        expect(a.failed + b.failed).toBe(0);
+        const stored = await findEscrowHoldById(hold._id);
+        expect(stored?.notifications.filter(entry => entry.kind === 'reminder')).toHaveLength(1);
+    });
+
+    it('does not remind a hold due more than 24h out', async () => {
+        const now = new Date();
+        const hold = await seed(new Date(now.getTime() + 25 * HOUR));
+
+        const result = await runEscrowHoldReminders({ now });
+
+        expect(result.reminded).toBe(0);
+        expect((await findEscrowHoldById(hold._id))?.notifications).toEqual([]);
+    });
+
+    it('skips completed and cancelled holds', async () => {
+        const now = new Date();
+        const completed = await seed(new Date(now.getTime() + HOUR));
+        await completeEscrowHold(completed._id);
+        const cancelled = await seed(new Date(now.getTime() + 2 * HOUR));
+        await cancelEscrowHold(cancelled._id, 'did');
+
+        const result = await runEscrowHoldReminders({ now });
+
+        expect(result.reminded).toBe(0);
+        expect((await findEscrowHoldById(completed._id))?.notifications).toEqual([]);
+        expect((await findEscrowHoldById(cancelled._id))?.notifications).toEqual([]);
+    });
+
+    it('skips holds already reminded', async () => {
+        const now = new Date();
+        const hold = await seed(new Date(now.getTime() + HOUR));
+        await recordEscrowHoldNotification(hold._id, 'reminder');
+
+        const result = await runEscrowHoldReminders({ now });
+
+        expect(result.reminded).toBe(0);
+        expect((await findEscrowHoldById(hold._id))?.notifications).toHaveLength(1);
+    });
+
+    it('expires stale holds and reports the count alongside reminders sent in the same run', async () => {
+        const now = new Date();
+        const stale = await seed(new Date(now.getTime() - 31 * 24 * HOUR));
+        const due = await seed(new Date(now.getTime() + HOUR));
+
+        const result = await runEscrowHoldReminders({ now });
+
+        expect(result.expired).toBe(1);
+        expect(result.reminded).toBe(1);
+        expect((await findEscrowHoldById(stale._id))?.status).toBe('expired');
+        expect((await findEscrowHoldById(due._id))?.notifications.map(entry => entry.kind)).toEqual(
+            ['reminder']
+        );
+    });
+
+    it('counts a notifier failure without marking sent and retries on the next run', async () => {
+        const now = new Date();
+        const hold = await seed(new Date(now.getTime() + HOUR));
+
+        const result = await runEscrowHoldReminders({
+            now,
+            notify: async () => {
+                throw new Error('delivery exploded');
+            },
+        });
+
+        expect(result).toEqual({ reminded: 0, expired: 0, failed: 1 });
+        const stored = await findEscrowHoldById(hold._id);
+        expect(stored?.notifications.map(entry => entry.kind)).toEqual([]);
+        const rerun = await runEscrowHoldReminders({ now });
+        expect(rerun).toEqual({ reminded: 1, expired: 0, failed: 0 });
+    });
+
+    it('no-ops without touching the database when escrow is disabled', async () => {
+        const now = new Date();
+        const stale = await seed(new Date(now.getTime() - 31 * 24 * HOUR));
+        delete process.env.ESCROW_ENCLAVE_MODE;
+        __setEscrowEnclaveForTests(undefined);
+
+        try {
+            const result = await runEscrowHoldReminders({ now });
+            expect(result).toEqual({ reminded: 0, expired: 0, failed: 0 });
+            expect((await findEscrowHoldById(stale._id))?.status).toBe('pending');
+        } finally {
+            process.env.ESCROW_ENCLAVE_MODE = 'software';
+            __setEscrowEnclaveForTests(undefined);
+        }
+    });
+});

package/test/keycloak-admin.spec.ts

@@ -0,0 +1,58 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createKeycloakAdmin } from '../scripts/keycloak-admin';
+
+const token = (value: string): Response => Response.json({ access_token: value, expires_in: 100 });
+
+afterEach((): void => vi.unstubAllEnvs());
+
+describe('Keycloak admin token lifetime', (): void => {
+    it('refreshes once after 401 and retries with the new token', async (): Promise<void> => {
+        vi.stubEnv('KEYCLOAK_ADMIN_CLIENT_SECRET', 'test');
+        const fetchRequest = vi
+            .fn<typeof fetch>()
+            .mockResolvedValueOnce(token('first'))
+            .mockResolvedValueOnce(new Response(null, { status: 401 }))
+            .mockResolvedValueOnce(token('second'))
+            .mockResolvedValueOnce(Response.json([]));
+        const admin = await createKeycloakAdmin(fetchRequest);
+        await expect(admin.findUsers('test@example.com')).resolves.toEqual([]);
+        expect(fetchRequest).toHaveBeenCalledTimes(4);
+        expect(fetchRequest.mock.calls[3]?.[1]?.headers).toMatchObject({
+            Authorization: 'Bearer second',
+        });
+    });
+
+    it('does not retry a second 401', async (): Promise<void> => {
+        vi.stubEnv('KEYCLOAK_ADMIN_CLIENT_SECRET', 'test');
+        const fetchRequest = vi
+            .fn<typeof fetch>()
+            .mockResolvedValueOnce(token('first'))
+            .mockResolvedValueOnce(new Response(null, { status: 401 }))
+            .mockResolvedValueOnce(token('second'))
+            .mockResolvedValueOnce(new Response(null, { status: 401 }));
+        const admin = await createKeycloakAdmin(fetchRequest);
+        await expect(admin.request('/users')).rejects.toThrow('Admin operation failed (401)');
+        expect(fetchRequest).toHaveBeenCalledTimes(4);
+    });
+
+    it('refreshes shortly before expiry but reuses a valid token', async (): Promise<void> => {
+        vi.stubEnv('KEYCLOAK_ADMIN_CLIENT_SECRET', 'test');
+        let time = 0;
+        const fetchRequest = vi
+            .fn<typeof fetch>()
+            .mockResolvedValueOnce(token('first'))
+            .mockResolvedValueOnce(Response.json([]))
+            .mockResolvedValueOnce(token('second'))
+            .mockResolvedValueOnce(Response.json([]));
+        const admin = await createKeycloakAdmin(fetchRequest, (): number => time);
+        time = 89_000;
+        await admin.request('/users');
+        expect(fetchRequest).toHaveBeenCalledTimes(2);
+        time = 90_000;
+        await admin.request('/users');
+        expect(fetchRequest).toHaveBeenCalledTimes(4);
+        expect(fetchRequest.mock.calls[3]?.[1]?.headers).toMatchObject({
+            Authorization: 'Bearer second',
+        });
+    });
+});

package/test/keycloak-broker-roundtrip.integration.spec.ts

@@ -0,0 +1,40 @@
+import { randomUUID } from 'node:crypto';
+import { decodeJwt } from 'jose';
+import { describe, expect, it } from 'vitest';
+import { createKeycloakAdmin } from '../scripts/keycloak-admin';
+import { roundtripEnabled, signInThroughBroker } from './helpers/keycloak-broker';
+
+describe.runIf(roundtripEnabled)('full Keycloak broker round-trip', () => {
+    it('issues a Keycloak session for a new email without rendering any page', async () => {
+        const { verifyKeycloakToken } = await import('../src/helpers/auth.helpers');
+        const { getAuthSubjectsCollection } = await import('../src/models/AuthSubject');
+        const { client } = await import('./helpers/live-mongo');
+        const admin = await createKeycloakAdmin();
+        const email = `broker-${randomUUID()}@example.com`;
+        try {
+            const { idToken, trace } = await signInThroughBroker(email);
+            const verified = await verifyKeycloakToken(idToken);
+            const users = await admin.findUsers(email);
+            expect(users).toHaveLength(1);
+            expect(verified).toMatchObject({ providerType: 'keycloak', email, id: users[0]!.id });
+            expect(decodeJwt(idToken).sub).toBe(users[0]!.id);
+            const subject = await getAuthSubjectsCollection().findOne({
+                identityKey: `email:${email}`,
+            });
+            expect(subject).not.toBeNull();
+            expect(await admin.links(users[0]!.id)).toContainEqual(
+                expect.objectContaining({
+                    identityProvider: 'lca-api',
+                    userId: subject!.subject,
+                })
+            );
+            expect(trace.length).toBeGreaterThanOrEqual(4);
+            expect(trace.every(hop => /^3\d\d /.test(hop))).toBe(true);
+        } finally {
+            for (const user of await admin.findUsers(email))
+                await admin.request(`/users/${user.id}`, { method: 'DELETE' });
+            await getAuthSubjectsCollection().deleteOne({ identityKey: `email:${email}` });
+            await client.close();
+        }
+    }, 60_000);
+});