@learncard/lca-api-service 1.3.2 → 1.5.0

package/test/oidcLambdaApp.boot.spec.ts

@@ -0,0 +1,105 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+/**
+ * Boot contract for the dedicated OIDC Lambda. The OIDC function runs under a
+ * role that cannot read the runtime-secrets bundle and is deployed without
+ * SEED/MONGO/Postmark/Firebase, so its module graph must import and its handler
+ * must initialise using ONLY the focused OIDC/cache environments. These tests
+ * assert that graph boots with those secrets absent and that the focused schema
+ * still enforces the issuer/audience contract.
+ */
+
+const BOOT_BLOCKERS = [
+    'SEED',
+    'MONGO_URI',
+    'MONGO_DB_NAME',
+    'SA_SEED_KMS_KEY_ARN',
+    'SA_SEED_LOCAL_KEK',
+    'POSTMARK_SERVER_TOKEN',
+    'POSTMARK_FROM_EMAIL',
+    'GOOGLE_APPLICATION_CREDENTIAL',
+    'RUNTIME_SECRETS_ID',
+] as const;
+
+const stubBaseEnv = (): void => {
+    vi.stubEnv('NODE_ENV', 'production');
+    vi.stubEnv('LAMBDA_STAGE', 'prod');
+    vi.stubEnv('IS_OFFLINE', 'false');
+    vi.stubEnv('IS_E2E_TEST', 'false');
+    vi.stubEnv('OIDC_ISSUER', 'https://issuer.test');
+    vi.stubEnv('OIDC_CLIENT_ID', 'keycloak-broker');
+    vi.stubEnv('OIDC_CLIENT_SECRET', 'secret');
+    vi.stubEnv('OIDC_REDIRECT_URIS', '');
+    vi.stubEnv('OIDC_SIGNING_KEY_JWK', '');
+    vi.stubEnv('OIDC_SIGNING_KEY_SECRET_ID', '');
+    vi.stubEnv('KEYCLOAK_ISSUERS', 'https://kc.test/realms/test');
+    vi.stubEnv('KEYCLOAK_AUDIENCES', 'account');
+    for (const key of BOOT_BLOCKERS) vi.stubEnv(key, '');
+};
+
+beforeEach(() => {
+    vi.resetModules();
+    stubBaseEnv();
+});
+
+afterEach(() => {
+    vi.unstubAllEnvs();
+    vi.resetModules();
+});
+
+describe('OIDC Lambda boot contract', () => {
+    it('imports the focused OIDC environment without SEED/MONGO/Postmark present', async () => {
+        for (const key of BOOT_BLOCKERS) expect(process.env[key]).toBe('');
+
+        const module = await import('../src/config/oidcEnvironment');
+
+        expect(module.environment.OIDC_ISSUER).toBe('https://issuer.test');
+        expect(module.environment.OIDC_CLIENT_ID).toBe('keycloak-broker');
+        expect(module.environment.KEYCLOAK_AUDIENCES).toBe('account');
+    });
+
+    it('imports the focused cache environment without SEED/MONGO present', async () => {
+        const module = await import('../src/config/cacheEnvironment');
+
+        expect(module.environment.REDIS_HOST).toBeUndefined();
+        expect(module.environment.REDIS_PORT).toBeUndefined();
+    });
+
+    it('boots the OIDC handler module graph with core boot secrets absent', async () => {
+        const lambdaApp = await import('../oidcLambdaApp');
+
+        expect(typeof lambdaApp.oidcHandler).toBe('function');
+    });
+
+    it('builds the OIDC Fastify app without touching the full environment schema', async () => {
+        const fullSchema = vi.fn();
+        vi.doMock('../src/config/environment', () => {
+            fullSchema();
+            throw new Error('full environment schema must not load on the OIDC boot path');
+        });
+
+        const module = await import('../src/oidc');
+        expect(typeof module.app.inject).toBe('function');
+        expect(fullSchema).not.toHaveBeenCalled();
+
+        vi.doUnmock('../src/config/environment');
+    });
+
+    it('enforces the issuer requires audience contract in the focused schema', async () => {
+        const { parseOidcEnvironment } = await import('../src/config/oidcEnvironment');
+
+        expect(() =>
+            parseOidcEnvironment({
+                KEYCLOAK_ISSUERS: 'https://kc.test/realms/test',
+                KEYCLOAK_AUDIENCES: '',
+            })
+        ).toThrow(/KEYCLOAK_AUDIENCES/);
+
+        expect(() =>
+            parseOidcEnvironment({
+                KEYCLOAK_ISSUERS: 'https://kc.test/realms/test',
+                KEYCLOAK_AUDIENCES: 'account',
+            })
+        ).not.toThrow();
+    });
+});

package/test/provision-keycloak-users.spec.ts

@@ -0,0 +1,299 @@
+import { ObjectId } from 'mongodb';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => ({
+    find: vi.fn(),
+    countDocuments: vi.fn().mockResolvedValue(0),
+    findUsers: vi.fn(),
+    findSubject: vi.fn(),
+    findOne: vi.fn(),
+    updateOne: vi.fn(),
+    createSubject: vi.fn(),
+    closeCursor: vi.fn(),
+}));
+vi.mock('../src/mongo', () => ({ client: { close: vi.fn() } }));
+vi.mock('../src/models/UserKey', () => ({ getUserKeysCollection: () => mocks }));
+vi.mock('../src/models/AuthSubject', () => ({
+    getAuthSubjectsCollection: () => ({ findOne: mocks.findSubject }),
+    getOrCreateAuthSubject: mocks.createSubject,
+}));
+vi.mock('../scripts/keycloak-admin', async importOriginal => ({
+    ...(await importOriginal<typeof import('../scripts/keycloak-admin')>()),
+    createKeycloakAdmin: async () => ({ findUsers: mocks.findUsers }),
+}));
+import { provisionKeycloakUsers } from '../scripts/provision-keycloak-users';
+import { KeycloakAdminError, type createKeycloakAdmin } from '../scripts/keycloak-admin';
+import type { FirebaseReader } from '../scripts/keycloak-provider-links';
+
+afterEach((): void => {
+    vi.restoreAllMocks();
+    vi.resetAllMocks();
+    mocks.countDocuments.mockResolvedValue(0);
+});
+
+const setupUser = (
+    mapped: boolean
+): {
+    admin: Awaited<ReturnType<typeof createKeycloakAdmin>>;
+    firebase: FirebaseReader;
+} => {
+    const row = {
+        _id: new ObjectId(),
+        contactMethod: { type: 'email', value: 'person@example.com' },
+        authProviders: [
+            { type: 'firebase', id: 'firebase-uid' },
+            ...(mapped ? [{ type: 'keycloak', id: 'keycloak-id' }] : []),
+        ],
+    };
+    mocks.find.mockReturnValue({
+        sort: (): AsyncIterable<typeof row> => ({
+            [Symbol.asyncIterator]: (): AsyncIterator<typeof row> => {
+                let done = false;
+                return {
+                    return: mocks.closeCursor.mockResolvedValue({ done: true, value: undefined }),
+                    next: async (): Promise<IteratorResult<typeof row>> => {
+                        if (done) return { done: true, value: undefined };
+                        done = true;
+                        return { done: false, value: row };
+                    },
+                };
+            },
+        }),
+    });
+    mocks.countDocuments.mockResolvedValueOnce(1).mockResolvedValue(0);
+    mocks.findOne.mockResolvedValue(null);
+    mocks.findSubject.mockResolvedValue({ subject: 'subject-id' });
+    mocks.updateOne.mockResolvedValue({ modifiedCount: 1 });
+    vi.spyOn(process.stdout, 'write').mockReturnValue(true);
+    return {
+        admin: {
+            findUsers: vi.fn().mockResolvedValue([
+                {
+                    id: 'keycloak-id',
+                    email: 'person@example.com',
+                    emailVerified: true,
+                    enabled: true,
+                },
+            ]),
+            links: vi
+                .fn()
+                .mockResolvedValue([
+                    { identityProvider: 'lca-api', userId: 'subject-id', userName: 'subject-id' },
+                ]),
+            request: vi.fn().mockResolvedValue(new Response(null, { status: 204 })),
+        },
+        firebase: {
+            getUsers: vi.fn().mockResolvedValue({
+                users: [
+                    {
+                        uid: 'firebase-uid',
+                        email: 'person@example.com',
+                        disabled: false,
+                        emailVerified: true,
+                        providerData: [
+                            { providerId: 'google.com', uid: 'google-sub' },
+                            { providerId: 'apple.com', uid: 'apple-sub' },
+                        ],
+                    },
+                ],
+            }),
+        },
+    };
+};
+
+describe('provisioning social providers', (): void => {
+    it.each(['google', 'apple'])(
+        'refuses a conflicting %s link before any Mongo or Keycloak write',
+        async alias => {
+            const dependencies = setupUser(false);
+            mocks.findSubject.mockResolvedValue(null);
+            vi.mocked(dependencies.admin.links).mockResolvedValue([
+                { identityProvider: alias, userId: 'other-subject', userName: 'other' },
+            ]);
+            expect(await provisionKeycloakUsers({ apply: true }, dependencies)).toMatchObject({
+                refused: 1,
+                conflicts: 1,
+                linked: 0,
+                mapped: 0,
+            });
+            expect(dependencies.admin.request).not.toHaveBeenCalled();
+            expect(mocks.createSubject).not.toHaveBeenCalled();
+            expect(mocks.updateOne).not.toHaveBeenCalled();
+        }
+    );
+    it.each([
+        { disabled: true, emailVerified: true, email: 'person@example.com' },
+        { disabled: false, emailVerified: false, email: 'person@example.com' },
+        { disabled: false, emailVerified: true, email: 'other@example.com' },
+    ])('refuses unsafe Firebase ownership: %j', async (attributes): Promise<void> => {
+        const dependencies = setupUser(false);
+        vi.mocked(dependencies.firebase.getUsers).mockResolvedValueOnce({
+            users: [{ uid: 'firebase-uid', providerData: [], ...attributes }],
+        });
+        expect(await provisionKeycloakUsers({ apply: true }, dependencies)).toMatchObject({
+            refused: 1,
+            linked: 0,
+        });
+        expect(dependencies.admin.request).not.toHaveBeenCalled();
+        expect(mocks.createSubject).not.toHaveBeenCalled();
+        expect(mocks.updateOne).not.toHaveBeenCalled();
+    });
+
+    it('closes the cursor when Firebase discovery fails without advancing the checkpoint', async (): Promise<void> => {
+        const dependencies = setupUser(true);
+        vi.mocked(dependencies.firebase.getUsers).mockRejectedValueOnce(
+            new Error('discovery failed')
+        );
+        await expect(provisionKeycloakUsers({ apply: true }, dependencies)).rejects.toThrow(
+            'discovery failed'
+        );
+        expect(mocks.closeCursor).toHaveBeenCalledTimes(1);
+        expect(process.stdout.write).toHaveBeenCalledWith(
+            expect.stringContaining('Last processed id: (none)')
+        );
+    });
+
+    it('reports a successful Google link when Apple fails and closes the cursor', async (): Promise<void> => {
+        const dependencies = setupUser(true);
+        vi.mocked(dependencies.admin.request)
+            .mockResolvedValueOnce(new Response(null, { status: 204 }))
+            .mockRejectedValueOnce(new KeycloakAdminError(503));
+        await expect(provisionKeycloakUsers({ apply: true }, dependencies)).rejects.toThrow('503');
+        expect(mocks.closeCursor).toHaveBeenCalledTimes(1);
+        expect(process.stdout.write).toHaveBeenCalledWith(expect.stringContaining('"linked":1'));
+        expect(process.stdout.write).toHaveBeenCalledWith(
+            expect.stringContaining('Last processed id: (none)')
+        );
+    });
+
+    it('reports conflicts in the provisioning summary and continues to the other provider', async (): Promise<void> => {
+        const dependencies = setupUser(true);
+        vi.mocked(dependencies.admin.request).mockRejectedValueOnce(new KeycloakAdminError(409));
+        expect(await provisionKeycloakUsers({ apply: true }, dependencies)).toMatchObject({
+            conflicts: 1,
+            linked: 1,
+        });
+        expect(mocks.updateOne).not.toHaveBeenCalled();
+    });
+
+    it('dry-runs mapped users without writes', async (): Promise<void> => {
+        const dependencies = setupUser(true);
+        expect(await provisionKeycloakUsers({}, dependencies)).toMatchObject({
+            wouldLink: 2,
+            linked: 0,
+        });
+        expect(dependencies.admin.request).not.toHaveBeenCalled();
+        expect(mocks.updateOne).not.toHaveBeenCalled();
+        expect(mocks.createSubject).not.toHaveBeenCalled();
+    });
+    it('pre-links already mapped users without rewriting mappings or subjects', async (): Promise<void> => {
+        const dependencies = setupUser(true);
+        const result = await provisionKeycloakUsers({ apply: true }, dependencies);
+        expect(result).toMatchObject({ processed: 1, linked: 2, mapped: 0, skipped: 0 });
+        expect(dependencies.firebase.getUsers).toHaveBeenCalledExactlyOnceWith([
+            { uid: 'firebase-uid' },
+        ]);
+        expect(mocks.updateOne).not.toHaveBeenCalled();
+        expect(mocks.createSubject).not.toHaveBeenCalled();
+    });
+
+    it('creates a new user, subject and mapping then links both providers', async (): Promise<void> => {
+        const dependencies = setupUser(false);
+        vi.mocked(dependencies.admin.findUsers).mockResolvedValueOnce([]);
+        mocks.findSubject.mockResolvedValueOnce(null);
+        mocks.createSubject.mockResolvedValueOnce({ subject: 'subject-id' });
+        const result = await provisionKeycloakUsers({ apply: true }, dependencies);
+        expect(result).toMatchObject({ mapped: 1, linked: 2 });
+        expect(dependencies.admin.request).toHaveBeenCalledWith(
+            '/users',
+            expect.objectContaining({ method: 'POST' })
+        );
+        expect(dependencies.admin.request).toHaveBeenCalledWith(
+            '/users/keycloak-id/federated-identity/lca-api',
+            expect.objectContaining({ method: 'POST' })
+        );
+        expect(mocks.updateOne).toHaveBeenCalledTimes(1);
+    });
+
+    it('dry-run discovers providers but never writes Keycloak or Mongo resources', async (): Promise<void> => {
+        const dependencies = setupUser(false);
+        vi.mocked(dependencies.admin.findUsers).mockResolvedValueOnce([]);
+        mocks.findSubject.mockResolvedValueOnce(null);
+        const result = await provisionKeycloakUsers({}, dependencies);
+        expect(result).toMatchObject({ linked: 0, wouldLink: 2, mapped: 0 });
+        expect(dependencies.admin.request).not.toHaveBeenCalled();
+        expect(mocks.createSubject).not.toHaveBeenCalled();
+        expect(mocks.updateOne).not.toHaveBeenCalled();
+    });
+
+    it('refuses a missing Firebase UID rather than reporting no social provider', async (): Promise<void> => {
+        const dependencies = setupUser(true);
+        vi.mocked(dependencies.firebase.getUsers).mockResolvedValueOnce({ users: [] });
+        const result = await provisionKeycloakUsers({ apply: true }, dependencies);
+        expect(result).toMatchObject({ refused: 1, noSocialProvider: 0, linked: 0 });
+        expect(dependencies.admin.request).not.toHaveBeenCalled();
+    });
+
+    it('refuses a mapped Keycloak ID different from the email match', async (): Promise<void> => {
+        const dependencies = setupUser(true);
+        vi.mocked(dependencies.admin.findUsers).mockResolvedValueOnce([
+            { id: 'other-id', email: 'person@example.com', emailVerified: true, enabled: true },
+        ]);
+        expect(await provisionKeycloakUsers({ apply: true }, dependencies)).toMatchObject({
+            refused: 1,
+            linked: 0,
+        });
+        expect(dependencies.admin.request).not.toHaveBeenCalled();
+    });
+});
+
+describe('provisioning resume', (): void => {
+    const skippedRow = {
+        contactMethod: { type: 'phone', value: '+15555550100' },
+        authProviders: [{ type: 'firebase', id: 'firebase-id' }],
+    };
+
+    it('uses an exclusive ObjectId cursor', async (): Promise<void> => {
+        const ids = [1, 2, 3].map(value => new ObjectId(value.toString().padStart(24, '0')));
+        const output = vi.spyOn(process.stdout, 'write').mockReturnValue(true);
+        const sort = vi.fn();
+        mocks.find.mockImplementation((filter: { _id: { $gt: ObjectId } }) => {
+            const rows = ids.filter(id => id.toHexString() > filter._id.$gt.toHexString());
+            sort.mockReturnValue({
+                async *[Symbol.asyncIterator]() {
+                    for (const _id of rows) yield { _id, ...skippedRow };
+                },
+            });
+            return { sort };
+        });
+        const summary = await provisionKeycloakUsers({
+            after: ids[1]!.toHexString(),
+            linkProviders: false,
+        });
+        expect(sort).toHaveBeenCalledWith({ _id: 1 });
+        expect(summary.processed).toBe(1);
+        expect(summary.skipped).toBe(1);
+        expect(mocks.findUsers).not.toHaveBeenCalled();
+        expect(mocks.findSubject).not.toHaveBeenCalled();
+        expect(output).toHaveBeenCalledWith(
+            expect.stringContaining(`--after ${ids[2]!.toHexString()}`)
+        );
+    });
+
+    it('reports only the completed cursor on failure', async (): Promise<void> => {
+        const id = new ObjectId();
+        const output = vi.spyOn(process.stdout, 'write').mockReturnValue(true);
+        mocks.find.mockReturnValue({
+            sort: () => ({
+                async *[Symbol.asyncIterator]() {
+                    yield { _id: id, ...skippedRow };
+                    throw new Error('connection lost');
+                },
+            }),
+        });
+        await expect(provisionKeycloakUsers({ linkProviders: false })).rejects.toThrow(
+            'connection lost'
+        );
+        expect(output).toHaveBeenCalledWith(expect.stringContaining(`--after ${id.toHexString()}`));
+    });
+});

package/test/signing-authority-http.spec.ts

@@ -0,0 +1,161 @@
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { APIGatewayProxyEventV2, Context as LambdaContext } from 'aws-lambda';
+import { client, mongodb } from '@mongo';
+import { SigningAuthorities } from '@accesslayer/signing-authority';
+import {
+    decryptSigningAuthoritySeed,
+    seedEncryption,
+    SeedEncryptionError,
+} from '@helpers/seedEncryption.helpers';
+import { createOpenApiAwsLambdaHandler } from '@helpers/shim';
+import { appRouter } from '../src/app';
+import { getUser } from './helpers/getClient';
+import {
+    runSeedMigrationBatch,
+    SEED_MIGRATION_RECEIPTS_COLLECTION,
+    SEED_MIGRATION_STATE_COLLECTION,
+} from '../src/migrations/signingAuthoritySeeds';
+
+let user: Awaited<ReturnType<typeof getUser>>;
+const handler = createOpenApiAwsLambdaHandler({
+    router: appRouter,
+    createContext: async () => ({
+        domain: 'localhost:3000',
+        tenant: { id: 'learncard', emailBranding: {}, resolvedVia: 'default' as const },
+        user: { did: user.learnCard.id.did(), isChallengeValid: true, authorizedDid: true },
+    }),
+});
+const request = async (path: string, body: unknown) =>
+    handler(
+        {
+            version: '2.0',
+            routeKey: 'ANY /api/{trpc+}',
+            rawPath: `/api${path}`,
+            rawQueryString: '',
+            headers: { 'content-type': 'application/json' },
+            pathParameters: { trpc: path.slice(1) },
+            requestContext: {
+                accountId: 'test',
+                apiId: 'test',
+                domainName: 'localhost',
+                domainPrefix: 'localhost',
+                http: {
+                    method: 'POST',
+                    path,
+                    protocol: 'HTTP/1.1',
+                    sourceIp: '127.0.0.1',
+                    userAgent: 'test',
+                },
+                requestId: 'test-request',
+                routeKey: 'ANY /api/{trpc+}',
+                stage: 'test',
+                time: '',
+                timeEpoch: 0,
+            },
+            body: JSON.stringify(body),
+            isBase64Encoded: false,
+        } satisfies APIGatewayProxyEventV2,
+        {} as LambdaContext
+    );
+
+beforeAll(async () => {
+    await client.connect();
+    user = await getUser();
+});
+afterAll(async () => {
+    await client.close();
+});
+beforeEach(async () => {
+    await SigningAuthorities.deleteMany({});
+    // Spec files share one database; another file may leave a migration lease or receipts behind.
+    await mongodb.collection(SEED_MIGRATION_STATE_COLLECTION).deleteMany({});
+    await mongodb.collection(SEED_MIGRATION_RECEIPTS_COLLECTION).deleteMany({});
+    vi.spyOn(console, 'error').mockImplementation(() => undefined);
+});
+afterEach(() => vi.restoreAllMocks());
+
+describe('encrypted signing-authority OpenAPI routes', () => {
+    it('keeps the same signing identity after migrating and purging a legacy seed', async () => {
+        const created = await request('/signing-authority/create', { name: 'migrated-http' });
+        const authority = JSON.parse(created.body);
+        const stored = await SigningAuthorities.findOne({ _id: authority._id });
+        const seed = await decryptSigningAuthoritySeed(stored!);
+        await SigningAuthorities.updateOne(
+            { _id: authority._id },
+            {
+                $set: { seed },
+                $unset: { encryptedSeed: '', encryptedDek: '', keyVersion: '' },
+            }
+        );
+        for (const phase of ['prepare', 'verify', 'purge'] as const) {
+            const result = await runSeedMigrationBatch(
+                mongodb,
+                { phase },
+                { encryptedWritesEnabled: true }
+            );
+            expect(result.done).toBe(true);
+        }
+        expect(await SigningAuthorities.findOne({ _id: authority._id })).not.toHaveProperty('seed');
+        const response = await request('/credentials/issue', {
+            credential: user.learnCard.invoke.newCredential(),
+            signingAuthority: authority,
+        });
+        expect(response.statusCode).toBe(200);
+        const signed = JSON.parse(response.body);
+        expect(signed.issuer).toBe(authority.did);
+        expect((await user.learnCard.invoke.verifyCredential(signed)).errors).toHaveLength(0);
+    });
+
+    it('creates ciphertext-only records and issues a verifiable credential over HTTP', async () => {
+        const created = await request('/signing-authority/create', { name: 'http' });
+        expect(created.statusCode).toBe(200);
+        const authority = JSON.parse(created.body);
+        expect(authority).not.toHaveProperty('seed');
+        expect(authority).not.toHaveProperty('encryptedSeed');
+        expect(await SigningAuthorities.findOne({ name: 'http' })).not.toHaveProperty('seed');
+        const response = await request('/credentials/issue', {
+            credential: user.learnCard.invoke.newCredential(),
+            signingAuthority: authority,
+        });
+        expect(response.statusCode).toBe(200);
+        const verification = await user.learnCard.invoke.verifyCredential(
+            JSON.parse(response.body)
+        );
+        expect(verification.errors).toHaveLength(0);
+    });
+
+    it.each(['kms_access_denied', 'kms_unavailable', 'authentication_failed'] as const)(
+        'returns a generic 500 and structured logs on %s',
+        async category => {
+            const created = await request('/signing-authority/create', { name: category });
+            const authority = JSON.parse(created.body);
+            vi.spyOn(seedEncryption, 'decrypt').mockRejectedValueOnce(
+                new SeedEncryptionError(category, 'request-1')
+            );
+            const response = await request('/credentials/issue', {
+                credential: user.learnCard.invoke.newCredential(),
+                signingAuthority: authority,
+            });
+            expect(response.statusCode).toBe(500);
+            expect(response.body).toContain('Signing authority key is unavailable');
+            expect(response.body).not.toContain(category);
+            expect(response.body).not.toContain('request-1');
+            expect(console.error).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    event: 'signing_authority_seed_failure',
+                    operation: 'decrypt',
+                    category,
+                })
+            );
+        }
+    );
+
+    it('does not insert a record when encryption fails during creation', async () => {
+        vi.spyOn(seedEncryption, 'encrypt').mockRejectedValueOnce(
+            new SeedEncryptionError('kms_unavailable')
+        );
+        const response = await request('/signing-authority/create', { name: 'failed-create' });
+        expect(response.statusCode).toBe(500);
+        expect(await SigningAuthorities.countDocuments()).toBe(0);
+    });
+});