@learncard/lca-api-service 1.4.0 → 1.5.1

package/test/keycloak-migration.integration.spec.ts

@@ -0,0 +1,266 @@
+import { execFile } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { ObjectId, type Collection } from 'mongodb';
+import { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { z } from 'zod';
+import { createKeycloakAdmin } from '../scripts/keycloak-admin';
+import { encryptAuthShare } from '../src/helpers/shareEncryption.helpers';
+import { maskEmail } from '../src/helpers/maskEmail';
+import { roundtripEnabled, signInThroughBroker, trpc } from './helpers/keycloak-broker';
+
+const exec = promisify(execFile);
+const runProvision = async (...args: string[]): Promise<string> => {
+    const { stdout } = await exec(
+        'bun',
+        [
+            '--conditions=development',
+            'scripts/provision-keycloak-users.ts',
+            '--no-link-providers',
+            ...args,
+        ],
+        {
+            cwd: fileURLToPath(new URL('../', import.meta.url)),
+            env: { ...process.env, NODE_ENV: 'development' },
+            timeout: 60_000,
+        }
+    );
+    process.stdout.write(stdout);
+    return stdout;
+};
+
+describe.runIf(roundtripEnabled)('Firebase-era UserKey migration', () => {
+    let keys: typeof import('../src/models/UserKey');
+    let subjects: typeof import('../src/models/AuthSubject');
+    let mongo: typeof import('./helpers/live-mongo');
+    let admin: Awaited<ReturnType<typeof createKeycloakAdmin>>;
+    const emails: string[] = [];
+    const ids: ObjectId[] = [];
+    // Match the real driver's ObjectIds; the model type describes serialized records.
+    const userKeys = (): Collection<
+        Omit<import('../src/models/UserKey').MongoUserKeyType, '_id'>
+    > =>
+        keys.getUserKeysCollection() as unknown as Collection<
+            Omit<import('../src/models/UserKey').MongoUserKeyType, '_id'>
+        >;
+    const knownShare = { encryptedData: 'known-firebase-era-auth-share', encryptedDek: '', iv: '' };
+
+    beforeAll(async () => {
+        if (!process.env.SEED) throw new Error('Set SEED to the running API encryption seed');
+        keys = await import('../src/models/UserKey');
+        subjects = await import('../src/models/AuthSubject');
+        mongo = await import('./helpers/live-mongo');
+        admin = await createKeycloakAdmin();
+    });
+    afterAll(async () => {
+        if (!mongo) return;
+        try {
+            for (const email of emails) {
+                for (const user of await admin.findUsers(email))
+                    await admin.request(`/users/${user.id}`, { method: 'DELETE' });
+                await subjects
+                    .getAuthSubjectsCollection()
+                    .deleteOne({ identityKey: `email:${email}` });
+            }
+            await userKeys().deleteMany({ _id: { $in: ids } });
+        } finally {
+            await mongo.client.close();
+        }
+    });
+
+    const seedKey = async (
+        phoneOnly = false
+    ): Promise<
+        Omit<import('../src/models/UserKey').MongoUserKeyType, '_id'> & { _id: ObjectId }
+    > => {
+        const id = new ObjectId();
+        const email = `migration-${id}@example.com`;
+        ids.push(id);
+        if (!phoneOnly) emails.push(email);
+        const key = keys.MongoUserKeyValidator.parse({
+            contactMethod: {
+                type: phoneOnly ? 'phone' : 'email',
+                value: phoneOnly ? `+1555${Date.now().toString().slice(-7)}` : email,
+            },
+            authProviders: [{ type: 'firebase', id: `firebase-uid-${id}` }],
+            primaryDid: `did:example:firebase-${id}`,
+            keyProvider: 'sss',
+            sssActivationState: 'active',
+            authShare: encryptAuthShare(knownShare, process.env.SEED!),
+            shareVersion: 1,
+            createdAt: new Date(),
+            updatedAt: new Date(),
+        });
+        const record = { ...key, _id: id };
+        await userKeys().insertOne(record);
+        return record;
+    };
+    const snapshot = async (email: string): Promise<unknown> => {
+        const users = await admin.findUsers(email);
+        return {
+            keys: await userKeys().find({ 'contactMethod.value': email }).toArray(),
+            subjects: await subjects
+                .getAuthSubjectsCollection()
+                .find({ identityKey: `email:${email}` })
+                .toArray(),
+            users,
+            links: await Promise.all(users.map(user => admin.links(user.id))),
+        };
+    };
+
+    it('returns null without mapping, then the exact original share and DID after provisioning', async () => {
+        const seeded = await seedKey();
+        const email = seeded.contactMethod.value;
+        const before = await snapshot(email);
+        expect(await runProvision('--email', email)).toContain('DRY RUN');
+        expect(await snapshot(email)).toEqual(before); // Includes absent subject/user: no accidental upserts.
+
+        const { verifyKeycloakToken } = await import('../src/helpers/auth.helpers');
+        const negative = await signInThroughBroker(email);
+        const unlinked = await verifyKeycloakToken(negative.idToken);
+        expect(unlinked).toMatchObject({ email, providerType: 'keycloak' });
+        expect(await keys.findUserKeyByAuthProvider('keycloak', unlinked.id)).toBeNull();
+        expect(
+            await trpc('keys.getAuthShare', {
+                authToken: negative.idToken,
+                providerType: 'keycloak',
+            })
+        ).toBeNull();
+
+        const beforeExisting = await snapshot(email);
+        await runProvision('--email', email);
+        expect(await snapshot(email)).toEqual(beforeExisting);
+        await runProvision('--apply', '--email', email);
+
+        const positive = await signInThroughBroker(email);
+        const linked = await verifyKeycloakToken(positive.idToken);
+        expect(linked.id).toBe(unlinked.id);
+        const restored = await keys.findUserKeyByAuthProvider('keycloak', linked.id);
+        expect(restored).toMatchObject({
+            _id: seeded._id,
+            authShare: seeded.authShare,
+            primaryDid: seeded.primaryDid,
+            shareVersion: 1,
+        });
+        expect(restored!.authProviders).toEqual([
+            ...seeded.authProviders,
+            { type: 'keycloak', id: linked.id },
+        ]);
+        expect(
+            await keys.getUserKeysCollection().countDocuments({ 'contactMethod.value': email })
+        ).toBe(1);
+        expect(
+            await trpc('keys.getAuthShare', {
+                authToken: positive.idToken,
+                providerType: 'keycloak',
+            })
+        ).toMatchObject({
+            authShare: knownShare,
+            primaryDid: seeded.primaryDid,
+            shareVersion: 1,
+            keyProvider: 'sss',
+            sssActivationState: 'active',
+        });
+        const subject = await subjects
+            .getAuthSubjectsCollection()
+            .findOne({ identityKey: `email:${email}` });
+        expect(await admin.links(linked.id)).toContainEqual(
+            expect.objectContaining({
+                identityProvider: 'lca-api',
+                userId: subject!.subject,
+            })
+        );
+        expect(positive.trace.every(hop => /^3\d\d /.test(hop))).toBe(true);
+        const after = await snapshot(email);
+        expect(await runProvision('--apply', '--email', email)).toContain('unchanged');
+        expect(await snapshot(email)).toEqual(after);
+        process.stdout.write(
+            `Migration proof ${maskEmail(email)}: negative HTTP=null; positive _id=${seeded._id}, primaryDid=${seeded.primaryDid}, shareVersion=1, encrypted share unchanged, returned share=known fixture, email record count=1; dry-run snapshots identical (absent and existing identities); second apply identical.\n`
+        );
+    }, 120_000);
+
+    it('pre-provisions a missing user and federated link before its first silent login', async () => {
+        const seeded = await seedKey();
+        const email = seeded.contactMethod.value;
+        expect(await admin.findUsers(email)).toHaveLength(0);
+        await runProvision('--apply', '--email', email);
+        const { idToken } = await signInThroughBroker(email);
+        expect(
+            await trpc('keys.getAuthShare', { authToken: idToken, providerType: 'keycloak' })
+        ).toMatchObject({ authShare: knownShare, primaryDid: seeded.primaryDid });
+    }, 60_000);
+
+    it('refuses a different lca-api link without changing either database resource', async () => {
+        const seeded = await seedKey();
+        const email = seeded.contactMethod.value;
+        await subjects.getOrCreateAuthSubject(`email:${email}`, { email, emailVerified: true });
+        await admin.request('/users', {
+            method: 'POST',
+            body: JSON.stringify({ username: email, email, emailVerified: true, enabled: true }),
+        });
+        const [user] = await admin.findUsers(email);
+        await admin.request(`/users/${user!.id}/federated-identity/lca-api`, {
+            method: 'POST',
+            body: JSON.stringify({
+                identityProvider: 'lca-api',
+                userId: randomUUID(),
+                userName: 'different-subject',
+            }),
+        });
+        const before = await snapshot(email);
+        await expect(runProvision('--apply', '--email', email)).rejects.toMatchObject({
+            code: 1,
+            stdout: expect.stringContaining('REFUSED: existing lca-api link differs'),
+        });
+        expect(await snapshot(email)).toEqual(before);
+    }, 60_000);
+
+    it('counts and skips phone-only records without writing', async () => {
+        const seeded = await seedKey(true);
+        const phoneCount = await keys
+            .getUserKeysCollection()
+            .countDocuments({ 'authProviders.type': 'firebase', 'contactMethod.type': 'phone' });
+        const output = await runProvision().catch((error: unknown): string => {
+            // A full dry-run can also report unrelated, deliberately conflicting fixtures.
+            const failure = z
+                .object({ code: z.literal(1), stdout: z.string().includes('Summary:') })
+                .parse(error);
+            return failure.stdout;
+        });
+        const serialized = output.match(/^Summary: (.+)$/m)?.[1];
+        const summary = z.object({ skipped: z.number() }).parse(JSON.parse(serialized!));
+        expect(summary.skipped).toBe(phoneCount);
+        expect(phoneCount).toBeGreaterThanOrEqual(1);
+        expect(await userKeys().findOne({ _id: seeded._id })).toEqual(seeded);
+        process.stdout.write(
+            `Phone-only skip count=${summary.skipped} (includes one synthetic fixture); no writes.\n`
+        );
+    }, 60_000);
+
+    it('lets a linked social identity share the provisioned subject in real Mongo', async () => {
+        await subjects.createAuthSubjectIndexes();
+        const email = `link-${randomUUID()}@example.com`;
+        const googleKey = `google:${randomUUID()}`;
+        const attrs = { email, emailVerified: true };
+
+        const emailSubject = await subjects.getOrCreateAuthSubject(`email:${email}`, attrs);
+        try {
+            const linked = await subjects.getOrCreateAuthSubjectLinkedTo(
+                googleKey,
+                emailSubject.subject,
+                attrs
+            );
+            expect(linked.subject).toBe(emailSubject.subject);
+            expect(
+                await subjects
+                    .getAuthSubjectsCollection()
+                    .countDocuments({ subject: emailSubject.subject })
+            ).toBe(2);
+        } finally {
+            await subjects
+                .getAuthSubjectsCollection()
+                .deleteMany({ identityKey: { $in: [`email:${email}`, googleKey] } });
+        }
+    }, 60_000);
+});

package/test/keycloak-provider-links.spec.ts

@@ -0,0 +1,201 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+    createKeycloakAdmin,
+    KeycloakAdminError,
+    type FederatedIdentity,
+} from '../scripts/keycloak-admin';
+import {
+    fetchFirebaseUsers,
+    linkFirebaseProviders,
+    type FirebaseProvider,
+    type FirebaseReader,
+} from '../scripts/keycloak-provider-links';
+
+const providers: FirebaseProvider[] = [
+    { providerId: 'google.com', uid: 'google-sub', email: 'person@example.com' },
+    { providerId: 'apple.com', uid: 'apple-sub' },
+];
+const makeAdmin = (): {
+    links: ReturnType<typeof vi.fn<(id: string) => Promise<FederatedIdentity[]>>>;
+    request: ReturnType<typeof vi.fn<(path: string, init?: RequestInit) => Promise<Response>>>;
+} => ({
+    links: vi.fn<(id: string) => Promise<FederatedIdentity[]>>().mockResolvedValue([]),
+    request: vi
+        .fn<(path: string, init?: RequestInit) => Promise<Response>>()
+        .mockResolvedValue(new Response(null, { status: 204 })),
+});
+
+afterEach((): void => vi.unstubAllEnvs());
+
+describe('Firebase provider pre-linking', (): void => {
+    it('links Google and Apple with provider subjects and is idempotent on rerun', async (): Promise<void> => {
+        const admin = makeAdmin();
+        const input = { userId: 'user/id', providers, apply: true, admin, log: vi.fn() };
+        expect(await linkFirebaseProviders(input)).toMatchObject({ linked: 2, conflicts: 0 });
+        expect(
+            admin.request.mock.calls.map(([path, init]) => [path, JSON.parse(String(init?.body))])
+        ).toEqual([
+            [
+                '/users/user%2Fid/federated-identity/google',
+                {
+                    identityProvider: 'google',
+                    userId: 'google-sub',
+                    userName: 'person@example.com',
+                },
+            ],
+            [
+                '/users/user%2Fid/federated-identity/apple',
+                { identityProvider: 'apple', userId: 'apple-sub', userName: 'apple-sub' },
+            ],
+        ]);
+        admin.links.mockResolvedValue([
+            { identityProvider: 'google', userId: 'google-sub', userName: 'old-name' },
+            { identityProvider: 'apple', userId: 'apple-sub', userName: 'apple-sub' },
+        ]);
+        expect(await linkFirebaseProviders(input)).toMatchObject({ linked: 0, alreadyLinked: 2 });
+        expect(admin.request).toHaveBeenCalledTimes(2);
+    });
+
+    it('skips occupied aliases without writes', async (): Promise<void> => {
+        const admin = makeAdmin();
+        admin.links.mockResolvedValue([
+            { identityProvider: 'google', userId: 'other', userName: 'other' },
+        ]);
+        const result = await linkFirebaseProviders({
+            userId: 'user',
+            providers: [providers[0]!],
+            apply: true,
+            admin,
+            log: vi.fn(),
+        });
+        expect(result.conflicts).toBe(1);
+        expect(admin.request).not.toHaveBeenCalled();
+    });
+
+    it('reports a link belonging to another Keycloak user as a conflict and continues', async (): Promise<void> => {
+        const admin = makeAdmin();
+        admin.request.mockRejectedValueOnce(new KeycloakAdminError(409));
+        const result = await linkFirebaseProviders({
+            userId: 'user',
+            providers,
+            apply: true,
+            admin,
+            log: vi.fn(),
+        });
+        expect(result).toMatchObject({ conflicts: 1, linked: 1 });
+        expect(admin.request.mock.calls.every(([, init]) => init?.method === 'POST')).toBe(true);
+    });
+
+    it('dry-run without a user makes no Keycloak calls and prints both plans', async (): Promise<void> => {
+        const admin = makeAdmin();
+        const log = vi.fn();
+        const result = await linkFirebaseProviders({ providers, apply: false, admin, log });
+        expect(result).toMatchObject({ linked: 0, wouldLink: 2 });
+        expect(admin.links).not.toHaveBeenCalled();
+        expect(admin.request).not.toHaveBeenCalled();
+        expect(log).toHaveBeenCalledTimes(2);
+    });
+
+    it('dry-run of a mapped user only reads existing links', async (): Promise<void> => {
+        const admin = makeAdmin();
+        expect(
+            await linkFirebaseProviders({
+                userId: 'user',
+                providers,
+                apply: false,
+                admin,
+                log: vi.fn(),
+            })
+        ).toMatchObject({ wouldLink: 2 });
+        expect(admin.links).toHaveBeenCalledWith('user');
+        expect(admin.request).not.toHaveBeenCalled();
+    });
+
+    it('counts non-social users and refuses ambiguous provider subjects', async (): Promise<void> => {
+        const admin = makeAdmin();
+        expect(
+            await linkFirebaseProviders({
+                providers: [{ providerId: 'password', uid: 'firebase' }],
+                apply: true,
+                admin,
+                log: vi.fn(),
+            })
+        ).toMatchObject({ noSocialProvider: 1 });
+        expect(
+            await linkFirebaseProviders({
+                userId: 'user',
+                providers: [providers[0]!, { providerId: 'google.com', uid: 'different' }],
+                apply: true,
+                admin,
+                log: vi.fn(),
+            })
+        ).toMatchObject({ conflicts: 1 });
+        expect(admin.request).not.toHaveBeenCalled();
+    });
+
+    it('uses the refresh-once path for a 401 during the linking POST', async (): Promise<void> => {
+        vi.stubEnv('KEYCLOAK_ADMIN_CLIENT_SECRET', 'test');
+        const fetchRequest = vi
+            .fn<typeof fetch>()
+            .mockResolvedValueOnce(Response.json({ access_token: 'first', expires_in: 100 }))
+            .mockResolvedValueOnce(Response.json([]))
+            .mockResolvedValueOnce(new Response(null, { status: 401 }))
+            .mockResolvedValueOnce(Response.json({ access_token: 'second', expires_in: 100 }))
+            .mockResolvedValueOnce(new Response(null, { status: 204 }));
+        const admin = await createKeycloakAdmin(fetchRequest);
+        expect(
+            await linkFirebaseProviders({
+                userId: 'user',
+                providers: [providers[0]!],
+                apply: true,
+                admin,
+                log: vi.fn(),
+            })
+        ).toMatchObject({ linked: 1 });
+        expect(fetchRequest).toHaveBeenCalledTimes(5);
+        expect(fetchRequest.mock.calls[4]?.[1]).toMatchObject({
+            method: 'POST',
+            headers: { Authorization: 'Bearer second' },
+        });
+        expect(fetchRequest.mock.calls[4]?.[1]?.body).toBe(fetchRequest.mock.calls[2]?.[1]?.body);
+    });
+
+    it('propagates non-conflict failures', async (): Promise<void> => {
+        const admin = makeAdmin();
+        admin.request.mockRejectedValueOnce(new KeycloakAdminError(403));
+        await expect(
+            linkFirebaseProviders({ userId: 'user', providers, apply: true, admin, log: vi.fn() })
+        ).rejects.toThrow('403');
+    });
+});
+
+describe('Firebase discovery', (): void => {
+    it('deduplicates UIDs and batches at 100 with a pause', async (): Promise<void> => {
+        const getUsers = vi
+            .fn<FirebaseReader['getUsers']>()
+            .mockImplementation(async identifiers => ({
+                users: identifiers.map(({ uid }) => ({
+                    uid,
+                    disabled: false,
+                    emailVerified: true,
+                    providerData: providers,
+                })),
+            }));
+        const sleep = vi.fn<(ms: number) => Promise<void>>().mockResolvedValue(undefined);
+        const ids = Array.from({ length: 101 }, (_, index) => `uid-${index}`);
+        const users = await fetchFirebaseUsers([...ids, ids[0]!], { getUsers }, sleep);
+        expect(users.size).toBe(101);
+        expect(getUsers.mock.calls.map(([batch]) => batch.length)).toEqual([100, 1]);
+        expect(sleep).toHaveBeenCalledExactlyOnceWith(1000);
+        expect(users.get('uid-0')?.providerData).toEqual(providers);
+    });
+
+    it('backs off on rate limits and stops after three retries', async (): Promise<void> => {
+        const error = { code: 'auth/too-many-requests' };
+        const getUsers = vi.fn<FirebaseReader['getUsers']>().mockRejectedValue(error);
+        const sleep = vi.fn<(ms: number) => Promise<void>>().mockResolvedValue(undefined);
+        await expect(fetchFirebaseUsers(['uid'], { getUsers }, sleep)).rejects.toEqual(error);
+        expect(getUsers).toHaveBeenCalledTimes(4);
+        expect(sleep.mock.calls).toEqual([[1000], [2000], [4000]]);
+    });
+});