@learncard/lca-api-service 1.4.0 → 1.5.0

package/test/oidc-e2e/broker.spec.ts

@@ -0,0 +1,116 @@
+import { randomUUID } from 'node:crypto';
+import { expect } from '@playwright/test';
+import {
+    test,
+    admin,
+    completeLogin,
+    issueTicket,
+    redeemCode,
+    redis,
+    rejectTicket,
+    subjects,
+    usersFor,
+} from './fixtures';
+
+test('new and returning users reach the same account without a web form', async ({
+    browser,
+    request,
+    account,
+}) => {
+    expect(await usersFor(account.email)).toEqual([]);
+    const first = await completeLogin(
+        browser,
+        await issueTicket(request, account.email),
+        account.email
+    );
+    const subject = await subjects.findOne({ identityKey: account.identityKey });
+    const returning = await completeLogin(
+        browser,
+        await issueTicket(request, account.email),
+        account.email
+    );
+    expect(returning).toBe(first);
+    expect(await subjects.countDocuments({ identityKey: account.identityKey })).toBe(1);
+    expect((await subjects.findOne({ identityKey: account.identityKey }))?.subject).toBe(
+        subject?.subject
+    );
+});
+
+test('a migrated user keeps the pre-linked Keycloak account', async ({
+    browser,
+    request,
+    account,
+}) => {
+    const subject = randomUUID();
+    await subjects.insertOne({
+        identityKey: account.identityKey,
+        subject,
+        email: account.email,
+        emailVerified: true,
+        createdAt: new Date(),
+        lastLoginAt: new Date(),
+    });
+    const response = await admin('users', {
+        method: 'POST',
+        body: JSON.stringify({
+            username: `migrated-${subject}`,
+            email: account.email,
+            emailVerified: true,
+            enabled: true,
+            federatedIdentities: [
+                { identityProvider: 'lca-api', userId: subject, userName: subject },
+            ],
+        }),
+    });
+    expect(response.status).toBe(201);
+    const id = response.headers.get('location')!.split('/').at(-1);
+    expect(
+        await completeLogin(browser, await issueTicket(request, account.email), account.email)
+    ).toBe(id);
+    expect((await subjects.findOne({ identityKey: account.identityKey }))?.subject).toBe(subject);
+});
+
+test('a consumed ticket cannot create another Keycloak session', async ({
+    browser,
+    request,
+    account,
+}) => {
+    const ticket = await issueTicket(request, account.email);
+    const id = await completeLogin(browser, ticket, account.email);
+    const before = await (await admin(`users/${id}/sessions`)).json();
+    expect(before).toHaveLength(1);
+    await rejectTicket(browser, ticket);
+    const after = await (await admin(`users/${id}/sessions`)).json();
+    expect(after.map((session: { id: string }) => session.id)).toEqual(
+        before.map((session: { id: string }) => session.id)
+    );
+});
+
+test('an expired ticket cannot create a Keycloak user', async ({ browser, request, account }) => {
+    const ticket = await issueTicket(request, account.email);
+    // issueTicket checks the production 60-second TTL. Shorten this one key to
+    // exercise actual Redis expiration without adding a minute to each run.
+    expect(await redis.pexpire(`login-ticket:${ticket}`, 1)).toBe(1);
+    await expect.poll(() => redis.exists(`login-ticket:${ticket}`)).toBe(0);
+    await rejectTicket(browser, ticket);
+    expect(await usersFor(account.email)).toEqual([]);
+});
+
+test('a wrong email code preserves the correct code, which can be redeemed only once concurrently', async ({
+    browser,
+    request,
+    account,
+}) => {
+    await redis.set(`login-code:${account.email}`, '123456', 'EX', 300);
+    expect(await redeemCode(request, account.email, '000000')).toMatchObject({ success: false });
+    expect(await redis.get(`login-code:${account.email}`)).toBe('123456');
+    const results = await Promise.all([
+        redeemCode(request, account.email, '123456'),
+        redeemCode(request, account.email, '123456'),
+    ]);
+    expect(results.filter(result => result.success)).toHaveLength(1);
+    expect(results.filter(result => !result.success)).toHaveLength(1);
+    expect(await redis.exists(`login-code:${account.email}`)).toBe(0);
+    await completeLogin(browser, results.find(result => result.success)!.ticket!, account.email);
+    expect(await subjects.countDocuments({ identityKey: account.identityKey })).toBe(1);
+});

package/test/oidc-e2e/compose.yaml

@@ -0,0 +1,33 @@
+# Exclusive, disposable stack owned by run.mjs. Never mounts developer data.
+services:
+    mongo:
+        image: mongo:7.0
+        ports: ['127.0.0.1::27017']
+        tmpfs: ['/data/db', '/data/configdb']
+    redis:
+        image: redis:7.4-alpine
+        command: ['redis-server', '--save', '', '--appendonly', 'no']
+        ports: ['127.0.0.1::6379']
+        tmpfs: ['/data']
+    keycloak:
+        # The canonical realm includes Apple, so stock Keycloak cannot import it.
+        build:
+            context: ../../../../../infra/keycloak
+            dockerfile: Dockerfile.dev
+        command: start-dev --import-realm
+        environment:
+            KC_BOOTSTRAP_ADMIN_USERNAME: admin
+            KC_BOOTSTRAP_ADMIN_PASSWORD: ${OIDC_E2E_ADMIN_PASSWORD:-unused-during-cleanup}
+            KC_HOSTNAME: http://localhost:${OIDC_E2E_KEYCLOAK_PORT:-18081}
+            KC_HTTP_ENABLED: 'true'
+            GOOGLE_CLIENT_ID: ci-google-client-id.apps.googleusercontent.com
+            GOOGLE_CLIENT_SECRET: ci-google-client-secret
+            APPLE_SERVICE_ID: com.learncard.ci.signin
+            APPLE_TEAM_ID: ci-apple-team-id
+            APPLE_KEY_ID: ci-apple-key-id
+            APPLE_P8_CONTENT: ci-placeholder-not-a-real-key
+        ports: ['127.0.0.1:${OIDC_E2E_KEYCLOAK_PORT:-18081}:8080']
+        extra_hosts: ['host.docker.internal:host-gateway']
+        tmpfs: ['/opt/keycloak/data:uid=1000,gid=0']
+        volumes:
+            - ${OIDC_E2E_REALM_FILE:-/dev/null}:/opt/keycloak/data/import/learncard-oidc-e2e-realm.json:ro

package/test/oidc-e2e/fixtures.ts

@@ -0,0 +1,245 @@
+import { readFileSync } from 'node:fs';
+import { createHash, randomBytes, randomInt, randomUUID } from 'node:crypto';
+import { test as base, expect, type Browser, type APIRequestContext } from '@playwright/test';
+import { MongoClient } from 'mongodb';
+import Redis from 'ioredis';
+import { createRemoteJWKSet, jwtVerify } from 'jose';
+import type { OidcE2eRuntime, LoginTicketResult, TestAccount } from './types';
+
+if (!process.env.OIDC_E2E_RUNTIME) throw new Error('Run this suite via bun run test:oidc:e2e');
+export const runtime: OidcE2eRuntime = JSON.parse(
+    readFileSync(process.env.OIDC_E2E_RUNTIME, 'utf8')
+);
+const mongo = new MongoClient(runtime.mongoUri);
+export const subjects = mongo.db(runtime.mongoDbName).collection('authsubjects');
+export const redis = new Redis({ host: '127.0.0.1', port: runtime.redisPort, lazyConnect: true });
+const jwks = createRemoteJWKSet(new URL(`${runtime.issuer}/protocol/openid-connect/certs`));
+
+/** Admin calls can only target the ephemeral realm created by the runner. */
+export const admin = async (path: string, init?: RequestInit): Promise<Response> => {
+    const tokenResponse = await fetch(
+        `${runtime.keycloakUrl}/realms/master/protocol/openid-connect/token`,
+        {
+            method: 'POST',
+            body: new URLSearchParams({
+                grant_type: 'password',
+                client_id: 'admin-cli',
+                username: 'admin',
+                password: runtime.adminPassword,
+            }),
+        }
+    );
+    expect(tokenResponse.ok).toBe(true);
+    const { access_token } = await tokenResponse.json();
+    return fetch(`${runtime.keycloakUrl}/admin/realms/learncard-oidc-e2e/${path}`, {
+        ...init,
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${access_token}`,
+            ...init?.headers,
+        },
+    });
+};
+
+export const usersFor = async (email: string): Promise<{ id: string }[]> => {
+    const response = await admin(`users?${new URLSearchParams({ email, exact: 'true' })}`);
+    expect(response.ok).toBe(true);
+    return response.json();
+};
+
+const cleanupAccount = async ({ email, identityKey }: TestAccount): Promise<void> => {
+    const cleanup = await Promise.allSettled([
+        (async () => {
+            for (const user of await usersFor(email)) {
+                expect((await admin(`users/${user.id}`, { method: 'DELETE' })).status).toBe(204);
+            }
+            expect(await usersFor(email)).toEqual([]);
+        })(),
+        (async () => {
+            await subjects.deleteMany({ identityKey });
+            expect(await subjects.countDocuments({ identityKey })).toBe(0);
+        })(),
+        // The runner provisions a private Redis container and this config has
+        // one worker. Clear all transient tickets/codes/tokens/rate counters.
+        (async () => {
+            await redis.flushdb();
+            expect(await redis.dbsize()).toBe(0);
+        })(),
+    ]);
+    const failures = cleanup.filter(result => result.status === 'rejected');
+    if (failures.length)
+        throw new AggregateError(
+            failures.map(result => result.reason),
+            'Per-test cleanup failed'
+        );
+};
+
+export const test = base.extend<{ account: TestAccount }>({
+    // Playwright requires a destructured fixture argument even with no dependencies.
+    // eslint-disable-next-line no-empty-pattern
+    account: async ({}, provideAccount) => {
+        const email = `oidc-e2e-${randomUUID()}@example.com`;
+        const identityKey = `email:${email}`;
+        try {
+            await provideAccount({ email, identityKey });
+        } finally {
+            // Exact test identity, never a broad user deletion. Deleting the user also
+            // removes sessions and federated links. The outer runner independently
+            // destroys all three disposable stores even if any of these actions fail.
+            await cleanupAccount({ email, identityKey });
+        }
+    },
+});
+
+test.beforeAll(async () => {
+    await Promise.all([mongo.connect(), redis.connect()]);
+});
+test.afterAll(async () => {
+    await Promise.all([mongo.close(), redis.quit()]);
+});
+
+export const redeemCode = async (
+    request: APIRequestContext,
+    email: string,
+    code: string
+): Promise<LoginTicketResult> => {
+    const response = await request.post(`${runtime.apiUrl}/api/auth/login-ticket`, {
+        data: { email, code },
+    });
+    expect(response.ok()).toBe(true);
+    return response.json();
+};
+
+export const issueTicket = async (request: APIRequestContext, email: string): Promise<string> => {
+    // Seed only the email delivery boundary. All code validation, identity creation,
+    // ticket issuance and token exchange go through real HTTP routes and stores.
+    const code = String(randomInt(100_000, 1_000_000));
+    await redis.set(`login-code:${email}`, code, 'EX', 300);
+    const result = await redeemCode(request, email, code);
+    expect(result.success).toBe(true);
+    expect(result.ticket).toBeTruthy();
+    expect(await redis.exists(`login-code:${email}`)).toBe(0);
+    expect(await redis.ttl(`login-ticket:${result.ticket}`)).toBeGreaterThan(0);
+    expect(await redis.ttl(`login-ticket:${result.ticket}`)).toBeLessThanOrEqual(60);
+    return result.ticket!;
+};
+
+const authorization = (
+    ticket: string
+): { url: string; verifier: string; nonce: string; state: string } => {
+    const verifier = randomBytes(32).toString('base64url');
+    const nonce = randomUUID();
+    const state = randomUUID();
+    const params = new URLSearchParams({
+        client_id: 'learncard-app',
+        redirect_uri: runtime.callbackUrl,
+        response_type: 'code',
+        scope: 'openid email profile',
+        state,
+        nonce,
+        code_challenge: createHash('sha256').update(verifier).digest('base64url'),
+        code_challenge_method: 'S256',
+        kc_idp_hint: 'lca-api',
+        login_hint: ticket,
+    });
+    return {
+        url: `${runtime.issuer}/protocol/openid-connect/auth?${params}`,
+        verifier,
+        nonce,
+        state,
+    };
+};
+
+/** Fresh context on every attempt prevents an existing SSO cookie hiding a broken ticket flow. */
+export const completeLogin = async (
+    browser: Browser,
+    ticket: string,
+    email: string
+): Promise<string> => {
+    const context = await browser.newContext();
+    try {
+        const page = await context.newPage();
+        const auth = authorization(ticket);
+        await page.goto(auth.url);
+        // There are no form-filling/clicking actions: an unexpected login, profile,
+        // or account-linking form cannot satisfy this callback assertion.
+        await page.waitForURL(url => `${url.origin}${url.pathname}` === runtime.callbackUrl);
+        const callback = new URL(page.url());
+        expect(callback.searchParams.get('error')).toBeNull();
+        expect(callback.searchParams.get('state')).toBe(auth.state);
+        const code = callback.searchParams.get('code');
+        expect(code).toBeTruthy();
+        expect(await redis.exists(`login-ticket:${ticket}`)).toBe(0);
+        const response = await context.request.post(
+            `${runtime.issuer}/protocol/openid-connect/token`,
+            {
+                form: {
+                    grant_type: 'authorization_code',
+                    client_id: 'learncard-app',
+                    code: code!,
+                    redirect_uri: runtime.callbackUrl,
+                    code_verifier: auth.verifier,
+                },
+            }
+        );
+        expect(response.ok()).toBe(true);
+        const tokens = await response.json();
+        const { payload } = await jwtVerify(tokens.id_token, jwks, {
+            issuer: runtime.issuer,
+            audience: 'learncard-app',
+            algorithms: ['RS256'],
+            requiredClaims: ['sub', 'exp', 'iat', 'nonce'],
+        });
+        expect(payload).toMatchObject({ email, email_verified: true, nonce: auth.nonce });
+        expect(payload.sub).toBeTruthy();
+        const userinfo = await context.request.get(
+            `${runtime.issuer}/protocol/openid-connect/userinfo`,
+            {
+                headers: { Authorization: `Bearer ${tokens.access_token}` },
+            }
+        );
+        expect(userinfo.ok()).toBe(true);
+        expect(await userinfo.json()).toMatchObject({ sub: payload.sub, email });
+        const record = await subjects.findOne({ identityKey: `email:${email}` });
+        expect(record?.subject).toBeTruthy();
+        const links = await admin(`users/${payload.sub}/federated-identity`);
+        expect(links.ok).toBe(true);
+        expect(await links.json()).toEqual(
+            expect.arrayContaining([
+                expect.objectContaining({ identityProvider: 'lca-api', userId: record!.subject }),
+            ])
+        );
+        expect(await usersFor(email)).toEqual([expect.objectContaining({ id: payload.sub })]);
+        return payload.sub!;
+    } finally {
+        await context.close();
+    }
+};
+
+export const rejectTicket = async (browser: Browser, ticket: string): Promise<void> => {
+    const context = await browser.newContext();
+    try {
+        const page = await context.newPage();
+        const upstream = page.waitForResponse(response => {
+            const url = new URL(response.url());
+            return url.origin === runtime.apiUrl && url.pathname === '/oidc/authorize';
+        });
+        const auth = authorization(ticket);
+        await page.goto(auth.url);
+        const response = await upstream;
+        expect(response.status()).toBe(302);
+        const location = new URL(response.headers().location!);
+        expect(`${location.origin}${location.pathname}`).toBe(
+            `${runtime.issuer}/broker/lca-api/endpoint`
+        );
+        expect(location.searchParams.get('error')).toBe('login_required');
+        expect(location.searchParams.get('code')).toBeNull();
+        await page.waitForURL(url => `${url.origin}${url.pathname}` === runtime.callbackUrl);
+        const callback = new URL(page.url());
+        expect(callback.searchParams.get('error')).toBeTruthy();
+        expect(callback.searchParams.get('code')).toBeNull();
+        expect(callback.searchParams.get('state')).toBe(auth.state);
+    } finally {
+        await context.close();
+    }
+};

package/test/oidc-e2e/lock.test.mjs

@@ -0,0 +1,73 @@
+import assert from 'node:assert/strict';
+import { fork } from 'node:child_process';
+import { once } from 'node:events';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { test } from 'node:test';
+
+for (const replaceLock of [false, true]) {
+    test(`concurrent stale-lock contenders preserve the ${replaceLock ? 'replacement' : 'stale'} lock`, { timeout: 15_000 }, async () => {
+        const temp = await mkdtemp(join(tmpdir(), 'oidc-lock-test-'));
+        const lock = join(temp, 'learncard-oidc-e2e.lock');
+        const preload = join(temp, 'barrier.mjs');
+        const children = [];
+        try {
+            // Hold both runners after reading the old PID, reproducing the reclamation race.
+            await writeFile(preload, `
+                import fs from 'node:fs/promises';
+                import { syncBuiltinESMExports } from 'node:module';
+                import { once } from 'node:events';
+                const readFile = fs.readFile;
+                fs.readFile = async (...args) => {
+                    const result = await readFile(...args);
+                    if (String(args[0]).endsWith('learncard-oidc-e2e.lock')) {
+                        const release = once(process, 'message');
+                        process.send('read');
+                        await release;
+                        process.disconnect();
+                    }
+                    return result;
+                };
+                syncBuiltinESMExports();
+            `);
+            const stalePid = '2147483647';
+            assert.throws(() => process.kill(Number(stalePid), 0), { code: 'ESRCH' });
+            await writeFile(lock, stalePid);
+            const runs = [0, 1].map(() => {
+                const child = fork(new URL('./run.mjs', import.meta.url), [], {
+                    execArgv: ['--import', preload],
+                    env: { ...process.env, TMPDIR: temp, TMP: temp, TEMP: temp },
+                    silent: true,
+                });
+                children.push(child);
+                let output = '';
+                child.stderr.on('data', chunk => { output += chunk; });
+                return {
+                    child,
+                    ready: once(child, 'message'),
+                    exited: once(child, 'exit'),
+                    output: () => output,
+                };
+            });
+            await Promise.all(runs.map(run => run.ready));
+            const expected = replaceLock ? String(process.pid) : stalePid;
+            if (replaceLock) {
+                await rm(lock);
+                await writeFile(lock, expected);
+            }
+            for (const run of runs) run.child.send('release');
+            for (const run of runs) {
+                assert.deepEqual(await run.exited, [1, null]);
+                assert.match(run.output(), /Stale OIDC E2E lock at .*remove this lock manually/);
+                assert.doesNotMatch(run.output(), /cleanup complete|Starting disposable/);
+            }
+            assert.equal(await readFile(lock, 'utf8'), expected);
+        } finally {
+            for (const child of children) {
+                if (child.exitCode === null && child.signalCode === null) child.kill('SIGKILL');
+            }
+            await rm(temp, { recursive: true, force: true });
+        }
+    });
+}

package/test/oidc-e2e/playwright.config.ts

@@ -0,0 +1,21 @@
+import { defineConfig } from '@playwright/test';
+
+if (!process.env.OIDC_E2E_RUNTIME) {
+    throw new Error('Use bun run test:oidc:e2e; this suite requires its disposable services.');
+}
+
+export default defineConfig({
+    testDir: '.',
+    testMatch: 'broker.spec.ts',
+    workers: 1,
+    fullyParallel: false,
+    retries: 0,
+    forbidOnly: Boolean(process.env.CI),
+    timeout: 30_000,
+    globalTimeout: 180_000,
+    expect: { timeout: 10_000 },
+    reporter: 'list',
+    // All artifacts, including any browser state, disappear with the runner's temp directory.
+    outputDir: process.env.OIDC_E2E_OUTPUT,
+    use: { browserName: 'chromium', headless: true, trace: 'off' },
+});