@learncard/lca-api-service 1.4.0 → 1.5.1

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

@@ -0,0 +1,228 @@
+import { createRequire } from 'node:module';
+import type { Browser, Page, chromium as Chromium } from '@playwright/test';
+import { decodeJwt } from 'jose';
+import { z } from 'zod';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { createKeycloakAdmin } from '../scripts/keycloak-admin';
+import {
+    callback,
+    createBrokerAuthorization,
+    exchangeBrokerCode,
+    keycloakIssuer,
+    roundtripEnabled,
+    signInThroughBroker,
+    trpc,
+} from './helpers/keycloak-broker';
+
+const idpSchema = z.object({
+    trustEmail: z.boolean(),
+    firstBrokerLoginFlowAlias: z.string(),
+    config: z.record(z.string(), z.string()),
+});
+const isCallback = (url: URL): boolean => `${url.origin}${url.pathname}` === callback;
+const callbacks = new WeakMap<Page, URL>();
+
+// Same browser-form driver as infra/keycloak/qa/signin.ts, shared PKCE with the ticket tests.
+// No traces/screenshots: Playwright errors can include authorization codes and action links.
+// The original error is intentionally not attached as `cause`: it would carry the URLs.
+const redactBrowserError = (error: unknown): Error => {
+    const reason =
+        error instanceof Error
+            ? error.message.split('\n')[0]?.replace(/https?:\/\/\S+/g, '[redacted URL]')
+            : 'unknown';
+    return new Error(`Synthetic browser action failed: ${reason}`);
+};
+
+const browserAction = <T>(action: () => Promise<T>): Promise<T> =>
+    action().catch((error: unknown): never => {
+        throw redactBrowserError(error);
+    });
+
+describe.runIf(roundtripEnabled)('web social broker ownership policy', () => {
+    let admin: Awaited<ReturnType<typeof createKeycloakAdmin>>;
+    let browser: Browser;
+    beforeAll(async () => {
+        if (keycloakIssuer !== 'http://localhost:8081/realms/learncard')
+            throw new Error('Fake social tests are loopback-only');
+        admin = await createKeycloakAdmin();
+        const require = createRequire(
+            new URL('../../../../tests/smoketests/package.json', import.meta.url)
+        );
+        const { chromium } = require('@playwright/test') as { chromium: typeof Chromium };
+        browser = await chromium.launch();
+    });
+    afterAll(async () => {
+        await browser?.close();
+    });
+
+    const signIn = async (
+        page: Page,
+        username: string
+    ): Promise<ReturnType<typeof createBrokerAuthorization>> => {
+        const authorization = createBrokerAuthorization('fake-google');
+        page.setDefaultTimeout(15_000);
+        page.on('request', request => {
+            const url = new URL(request.url());
+            if (isCallback(url)) callbacks.set(page, url);
+        });
+        await browserAction(async () => {
+            await page.route(isCallback, route =>
+                route.fulfill({ status: 200, contentType: 'text/plain', body: 'Test callback' })
+            );
+            await page.goto(authorization.url.href);
+            await page.locator('input[name="username"]').fill(username);
+            await page.locator('input[name="password"]').fill('test-only-password');
+            await page.locator('#kc-login').click();
+            await page.waitForURL(url => !url.pathname.startsWith('/realms/fake-google/'));
+        });
+        return authorization;
+    };
+
+    const tokenFromPage = async (
+        page: Page,
+        auth: ReturnType<typeof createBrokerAuthorization>
+    ): Promise<string> => {
+        await expect.poll(() => callbacks.has(page), { timeout: 15_000 }).toBe(true);
+        // Chromium may refuse the unused app port after a server-side redirect.
+        // Capture the request rather than relying on the destination being served.
+        const url = callbacks.get(page);
+        if (!url) throw new Error('No authorization callback request');
+        if (url.searchParams.get('state') !== auth.state || url.searchParams.has('error'))
+            throw new Error('Invalid social callback state/result');
+        const code = url.searchParams.get('code');
+        if (!code) throw new Error('Social callback has no code');
+        return exchangeBrokerCode(code, auth.verifier);
+    };
+
+    it('uses the same verified-claim and automatic linking policy for Google, Apple and the fake', async () => {
+        const providers = await Promise.all(
+            ['google', 'apple', 'fake-google'].map(async alias =>
+                idpSchema.parse(
+                    await (await admin.request(`/identity-provider/instances/${alias}`)).json()
+                )
+            )
+        );
+        for (const provider of providers) {
+            expect(provider.trustEmail).toBe(true);
+            expect(provider.firstBrokerLoginFlowAlias).toBe(
+                providers[0]!.firstBrokerLoginFlowAlias
+            );
+            expect(provider.config).toMatchObject({
+                filteredByClaim: 'true',
+                claimFilterName: 'email_verified',
+                claimFilterValue: '^true$',
+            });
+        }
+        expect(providers[1]!.config.tokenExchangeAccountLinkingEnabled).toBe('false');
+        const executions = z
+            .array(z.object({ providerId: z.string().optional(), requirement: z.string() }))
+            .parse(
+                await (
+                    await admin.request(
+                        `/authentication/flows/${encodeURIComponent(providers[0]!.firstBrokerLoginFlowAlias)}/executions`
+                    )
+                ).json()
+            );
+        expect(executions).toContainEqual(
+            expect.objectContaining({ providerId: 'idp-auto-link', requirement: 'ALTERNATIVE' })
+        );
+        expect(
+            executions.some(
+                e =>
+                    ['idp-confirm-link', 'idp-detect-existing-broker-user'].includes(
+                        e.providerId ?? ''
+                    ) && e.requirement !== 'DISABLED'
+            )
+        ).toBe(false);
+    });
+
+    it('creates a verified new account via browser + PKCE that the live lca-api accepts', async () => {
+        const email = 'alice@example.com';
+        expect(await admin.findUsers(email)).toHaveLength(0);
+        const context = await browser.newContext();
+        try {
+            const page = await context.newPage();
+            const auth = await signIn(page, 'new-social');
+            const idToken = await tokenFromPage(page, auth);
+            expect(decodeJwt(idToken).email_verified).toBe(true);
+            const { verifyKeycloakToken } = await import('../src/helpers/auth.helpers');
+            expect(await verifyKeycloakToken(idToken)).toMatchObject({
+                email,
+                providerType: 'keycloak',
+            });
+            expect(
+                await trpc('keys.getAuthShare', { authToken: idToken, providerType: 'keycloak' })
+            ).toBeNull();
+            const users = await admin.findUsers(email);
+            expect(users).toHaveLength(1);
+            expect(users[0]!.emailVerified).toBe(true);
+            expect(await admin.links(users[0]!.id)).toContainEqual(
+                expect.objectContaining({ identityProvider: 'fake-google' })
+            );
+            // A fresh ticket hop has no browser SSO cookies and must link the existing
+            // web-social user rather than rendering an account confirmation page.
+            expect(await admin.links(users[0]!.id)).not.toContainEqual(
+                expect.objectContaining({ identityProvider: 'lca-api' })
+            );
+            const emailLogin = await signInThroughBroker(email);
+            expect(decodeJwt(emailLogin.idToken).sub).toBe(users[0]!.id);
+            expect(await admin.findUsers(email)).toHaveLength(1);
+            expect(await admin.links(users[0]!.id)).toEqual(
+                expect.arrayContaining([
+                    expect.objectContaining({ identityProvider: 'fake-google' }),
+                    expect.objectContaining({ identityProvider: 'lca-api' }),
+                ])
+            );
+        } finally {
+            await context.close();
+            for (const user of await admin.findUsers(email))
+                await admin.request(`/users/${user.id}`, { method: 'DELETE' });
+        }
+    }, 60_000);
+
+    it('automatically links an existing passwordless account without an extra page', async () => {
+        const email = 'existing-social@example.com';
+        expect(await admin.findUsers(email)).toHaveLength(0);
+        await admin.request('/users', {
+            method: 'POST',
+            body: JSON.stringify({
+                username: 'r2-existing-passwordless',
+                email,
+                emailVerified: true,
+                enabled: true,
+            }),
+        });
+        const [existing] = await admin.findUsers(email);
+        if (!existing) throw new Error('Missing collision fixture');
+        const context = await browser.newContext();
+        try {
+            const page = await context.newPage();
+            const auth = await signIn(page, 'existing-social');
+            const idToken = await tokenFromPage(page, auth);
+            expect(decodeJwt(idToken).sub).toBe(existing.id);
+            expect(decodeJwt(idToken).email_verified).toBe(true);
+            expect(await admin.links(existing.id)).toContainEqual(
+                expect.objectContaining({ identityProvider: 'fake-google' })
+            );
+            expect(await admin.findUsers(email)).toHaveLength(1);
+        } finally {
+            await context.close();
+            await admin.request(`/users/${existing.id}`, { method: 'DELETE' });
+        }
+    }, 60_000);
+
+    it('rejects an explicitly unverified upstream email before creating or linking a user', async () => {
+        const context = await browser.newContext();
+        try {
+            const page = await context.newPage();
+            await signIn(page, 'unverified-social');
+            expect(isCallback(new URL(page.url()))).toBe(false);
+            expect(await page.locator('#kc-error-message').innerText()).toContain(
+                'identity provider'
+            );
+            expect(await admin.findUsers('unverified-social@example.com')).toHaveLength(0);
+        } finally {
+            await context.close();
+        }
+    }, 60_000);
+});

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

@@ -0,0 +1,100 @@
+import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
+
+// No Firebase credentials or network calls are needed to verify Keycloak tokens.
+vi.mock('firebase-admin', () => ({ default: { auth: vi.fn() } }));
+vi.mock('@environment', () => ({
+    environment: {
+        IS_OFFLINE: false,
+        IS_E2E_TEST: false,
+        get KEYCLOAK_ISSUERS(): string | undefined {
+            return process.env.KEYCLOAK_ISSUERS;
+        },
+        get KEYCLOAK_AUDIENCES(): string | undefined {
+            return process.env.KEYCLOAK_AUDIENCES;
+        },
+        get KEYCLOAK_JWKS_URL_OVERRIDES(): string | undefined {
+            return process.env.KEYCLOAK_JWKS_URL_OVERRIDES;
+        },
+    },
+}));
+
+describe.skipIf(process.env.KEYCLOAK_INTEGRATION !== 'true')('real Keycloak tokens', () => {
+    let verifyKeycloakToken: typeof import('../src/helpers/auth.helpers').verifyKeycloakToken;
+    let verifyAuthToken: typeof import('../src/helpers/auth.helpers').verifyAuthToken;
+
+    beforeAll(async () => {
+        // Avoid initializing service configuration at all when this suite is skipped.
+        ({ verifyKeycloakToken, verifyAuthToken } = await import('../src/helpers/auth.helpers'));
+    });
+
+    afterEach(() => vi.unstubAllEnvs());
+
+    const getToken = async (
+        username: string
+    ): Promise<{ access_token: string; id_token: string }> => {
+        const issuer = process.env.KEYCLOAK_ISSUERS?.split(',')[0];
+        if (!issuer) throw new Error('KEYCLOAK_ISSUERS must be set for integration tests');
+        const response = await fetch(`${issuer}/protocol/openid-connect/token`, {
+            method: 'POST',
+            body: new URLSearchParams({
+                grant_type: 'password',
+                client_id: 'ci-tests',
+                client_secret: 'ci-tests-dev-only-secret',
+                username,
+                password: 'password',
+                scope: 'openid',
+            }),
+        });
+        if (!response.ok) {
+            throw new Error(`Token request failed (${response.status}): ${await response.text()}`);
+        }
+        return response.json();
+    };
+
+    it('accepts a verified email ID token through provider dispatch', async () => {
+        const { id_token } = await getToken('dev-email');
+        const user = await verifyAuthToken(id_token, 'keycloak');
+        expect(user.id).toBeTruthy();
+        expect(user.email).toBe('dev-email@example.com');
+        expect(user.providerType).toBe('keycloak');
+    });
+
+    it('preserves phone profile attributes and accepts a phone-only ID token', async () => {
+        const { id_token } = await getToken('dev-phone');
+        const payload = JSON.parse(Buffer.from(id_token.split('.')[1]!, 'base64url').toString());
+        expect(payload.phone_number).toBe('+15555550100');
+        expect(payload.phone_number_verified).toBe(true);
+        const user = await verifyKeycloakToken(id_token);
+        expect(user.phone).toBe('+15555550100');
+        expect(user.email).toBeUndefined();
+        expect(user.providerType).toBe('keycloak');
+    });
+
+    it('accepts a phone-only access token using the authorized party', async () => {
+        const { access_token } = await getToken('dev-phone');
+        const user = await verifyKeycloakToken(access_token);
+        expect(user.phone).toBe('+15555550100');
+        expect(user.email).toBeUndefined();
+    });
+
+    it('rejects an unverified contact', async () => {
+        const { id_token } = await getToken('dev-unverified');
+        await expect(verifyKeycloakToken(id_token)).rejects.toMatchObject({ code: 'UNAUTHORIZED' });
+    });
+
+    it('rejects a tampered signature', async () => {
+        const { id_token } = await getToken('dev-email');
+        const parts = id_token.split('.');
+        const signature = parts[2]!;
+        parts[2] = `${signature[0] === 'A' ? 'B' : 'A'}${signature.slice(1)}`;
+        await expect(verifyKeycloakToken(parts.join('.'))).rejects.toMatchObject({
+            code: 'UNAUTHORIZED',
+        });
+    });
+
+    it('rejects a client outside the configured audience allowlist', async () => {
+        const { id_token } = await getToken('dev-email');
+        vi.stubEnv('KEYCLOAK_AUDIENCES', 'some-other-client');
+        await expect(verifyKeycloakToken(id_token)).rejects.toMatchObject({ code: 'UNAUTHORIZED' });
+    });
+});

package/test/keycloak-verify.spec.ts

@@ -0,0 +1,307 @@
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import { createLocalJWKSet, exportJWK, generateKeyPair, SignJWT } from 'jose';
+import type { JWTPayload } from 'jose';
+import admin from 'firebase-admin';
+import {
+    verifyFirebaseToken,
+    verifyAuthToken,
+    verifyKeycloakToken,
+} from '../src/helpers/auth.helpers';
+import {
+    getKeycloakIssuerJwksUrl,
+    getKeycloakJwks,
+    getKeycloakVerifyOptionsFromEnv,
+    setKeycloakJwksResolverForTests,
+} from '../src/helpers/keycloak.helpers';
+
+vi.mock('@environment', () => ({
+    environment: {
+        IS_OFFLINE: true,
+        IS_E2E_TEST: true,
+        get KEYCLOAK_ISSUERS(): string | undefined {
+            return process.env.KEYCLOAK_ISSUERS;
+        },
+        get KEYCLOAK_AUDIENCES(): string | undefined {
+            return process.env.KEYCLOAK_AUDIENCES;
+        },
+        get KEYCLOAK_JWKS_URL_OVERRIDES(): string | undefined {
+            return process.env.KEYCLOAK_JWKS_URL_OVERRIDES;
+        },
+    },
+}));
+vi.mock('firebase-admin', () => ({ default: { auth: vi.fn() } }));
+
+const issuer = 'https://identity.example/realms/learncard';
+const client = 'learncard-app';
+const kid = 'test-key';
+let keys: Awaited<ReturnType<typeof generateKeyPair>>;
+let otherKeys: Awaited<ReturnType<typeof generateKeyPair>>;
+let localJwks: ReturnType<typeof createLocalJWKSet>;
+const resolver = vi.fn(() => localJwks);
+
+const signToken = async (
+    overrides: JWTPayload = {},
+    signingKeys = keys,
+    algorithm = 'RS256'
+): Promise<string> => {
+    const now = Math.floor(Date.now() / 1000);
+    return new SignJWT({
+        sub: 'user-123',
+        iss: issuer,
+        aud: client,
+        typ: 'ID',
+        email: 'learner@example.com',
+        email_verified: true,
+        exp: now + 300,
+        ...overrides,
+    })
+        .setProtectedHeader({ alg: algorithm, kid, typ: 'JWT' })
+        .sign(signingKeys.privateKey);
+};
+
+beforeAll(async () => {
+    keys = await generateKeyPair('RS256');
+    otherKeys = await generateKeyPair('RS256');
+    localJwks = createLocalJWKSet({ keys: [{ ...(await exportJWK(keys.publicKey)), kid }] });
+});
+
+beforeEach(() => {
+    vi.stubEnv('KEYCLOAK_ISSUERS', issuer);
+    vi.stubEnv('KEYCLOAK_AUDIENCES', client);
+    vi.stubEnv('KEYCLOAK_JWKS_URL_OVERRIDES', '');
+    resolver.mockClear();
+    setKeycloakJwksResolverForTests(resolver);
+});
+
+afterEach(() => {
+    setKeycloakJwksResolverForTests(undefined);
+    vi.unstubAllEnvs();
+});
+
+describe('Keycloak token verification', () => {
+    it('accepts ID tokens with a verified email', async () => {
+        await expect(verifyKeycloakToken(await signToken())).resolves.toEqual({
+            id: 'user-123',
+            email: 'learner@example.com',
+            phone: undefined,
+            providerType: 'keycloak',
+        });
+    });
+
+    it('accepts access tokens via azp even when aud is account', async () => {
+        await expect(
+            verifyKeycloakToken(await signToken({ typ: 'Bearer', aud: 'account', azp: client }))
+        ).resolves.toMatchObject({ providerType: 'keycloak' });
+    });
+
+    it('accepts a verified token without the optional payload typ', async () => {
+        await expect(verifyKeycloakToken(await signToken({ typ: undefined }))).resolves.toEqual({
+            id: 'user-123',
+            email: 'learner@example.com',
+            phone: undefined,
+            providerType: 'keycloak',
+        });
+    });
+
+    it.each([
+        ['wrong issuer', { iss: 'https://wrong.example/realms/learncard' }],
+        ['same-key issuer outside allowlist', { iss: `${issuer}/` }],
+    ])('rejects %s before resolving keys', async (_label, claims) => {
+        await expect(verifyKeycloakToken(await signToken(claims))).rejects.toMatchObject({
+            code: 'UNAUTHORIZED',
+        });
+        expect(resolver).not.toHaveBeenCalled();
+    });
+
+    it.each([
+        ['wrong audience and azp', { aud: 'account', azp: 'another-client' }],
+        ['expired token', { exp: 1 }],
+        ['future nbf', { nbf: Math.floor(Date.now() / 1000) + 300 }],
+        ['refresh token', { typ: 'Refresh' }],
+        ['offline token', { typ: 'Offline' }],
+        ['unsupported payload typ', { typ: 'bearer' }],
+        ['null payload typ', { typ: null }],
+        ['missing subject', { sub: undefined }],
+        ['missing audience and azp', { aud: undefined, azp: undefined }],
+    ])('rejects %s', async (_label, claims) => {
+        await expect(verifyKeycloakToken(await signToken(claims))).rejects.toMatchObject({
+            code: 'UNAUTHORIZED',
+            message: 'Invalid Keycloak token',
+        });
+    });
+
+    it('rejects a bad signature', async () => {
+        await expect(verifyKeycloakToken(await signToken({}, otherKeys))).rejects.toMatchObject({
+            code: 'UNAUTHORIZED',
+            message: 'Invalid Keycloak token',
+        });
+    });
+
+    it.each([
+        ['unverified email', { email_verified: false }, 'Email address is not verified'],
+        [
+            'missing email verification',
+            { email_verified: undefined },
+            'Email address is not verified',
+        ],
+        [
+            'unverified phone with verified email',
+            { phone_number: '+15555550123', phone_number_verified: false },
+            'Phone number is not verified',
+        ],
+        [
+            'missing phone verification',
+            { phone_number: '+15555550123' },
+            'Phone number is not verified',
+        ],
+        ['no contact claims', { email: undefined }, 'Token has no verified contact method'],
+    ])('rejects %s', async (_label, claims, message) => {
+        await expect(verifyKeycloakToken(await signToken(claims))).rejects.toMatchObject({
+            code: 'UNAUTHORIZED',
+            message,
+        });
+    });
+
+    it('accepts a verified phone-only user', async () => {
+        const token = await signToken({
+            email: undefined,
+            phone_number: '+15555550123',
+            phone_number_verified: true,
+        });
+        await expect(verifyKeycloakToken(token)).resolves.toEqual({
+            id: 'user-123',
+            email: undefined,
+            phone: '+15555550123',
+            providerType: 'keycloak',
+        });
+    });
+
+    it('rejects unconfigured verification', async () => {
+        vi.stubEnv('KEYCLOAK_ISSUERS', undefined);
+        await expect(verifyKeycloakToken(await signToken())).rejects.toMatchObject({
+            code: 'UNAUTHORIZED',
+            message: 'Keycloak verification is not configured',
+        });
+    });
+
+    it('dispatches verifyAuthToken to Keycloak', async () => {
+        await expect(verifyAuthToken(await signToken(), 'keycloak')).resolves.toMatchObject({
+            id: 'user-123',
+            providerType: 'keycloak',
+        });
+    });
+
+    it('accepts audience arrays', async () => {
+        await expect(
+            verifyKeycloakToken(await signToken({ aud: ['account', client] }))
+        ).resolves.toMatchObject({ id: 'user-123' });
+    });
+
+    it('rejects malformed tokens without leaking parser errors', async () => {
+        await expect(verifyKeycloakToken('not-a-token')).rejects.toMatchObject({
+            code: 'UNAUTHORIZED',
+            message: 'Invalid Keycloak token',
+        });
+    });
+
+    it('accepts ES256 signatures', async () => {
+        const ecKeys = await generateKeyPair('ES256');
+        const ecJwks = createLocalJWKSet({
+            keys: [{ ...(await exportJWK(ecKeys.publicKey)), kid }],
+        });
+        setKeycloakJwksResolverForTests(() => ecJwks);
+        await expect(
+            verifyKeycloakToken(await signToken({}, ecKeys, 'ES256'))
+        ).resolves.toMatchObject({ id: 'user-123' });
+    });
+
+    it('rejects algorithms outside the allowlist', async () => {
+        const rs512Keys = await generateKeyPair('RS512');
+        await expect(
+            verifyKeycloakToken(await signToken({}, rs512Keys, 'RS512'))
+        ).rejects.toMatchObject({ code: 'UNAUTHORIZED' });
+    });
+});
+
+describe('Keycloak configuration', () => {
+    it('memoizes remote JWKS by exact issuer without fetching', () => {
+        setKeycloakJwksResolverForTests(undefined);
+        expect(getKeycloakJwks(issuer)).toBe(getKeycloakJwks(issuer));
+        expect(getKeycloakJwks(`${issuer}/other`)).not.toBe(getKeycloakJwks(issuer));
+    });
+
+    it('trims allowlists and drops empty entries', () => {
+        vi.stubEnv('KEYCLOAK_ISSUERS', ` , ${issuer}, , https://second.example, `);
+        vi.stubEnv('KEYCLOAK_AUDIENCES', ' , learncard-app, , another-client, ');
+        expect(getKeycloakVerifyOptionsFromEnv()).toEqual({
+            issuers: [issuer, 'https://second.example'],
+            audiences: [client, 'another-client'],
+        });
+    });
+
+    it('returns null for empty issuers', () => {
+        vi.stubEnv('KEYCLOAK_ISSUERS', ' , , ');
+        expect(getKeycloakVerifyOptionsFromEnv()).toBeNull();
+    });
+
+    it('reports missing audiences as a configuration error', async () => {
+        vi.stubEnv('KEYCLOAK_AUDIENCES', ' , ');
+        await expect(verifyKeycloakToken(await signToken())).rejects.toMatchObject({
+            code: 'INTERNAL_SERVER_ERROR',
+            message: 'KEYCLOAK_AUDIENCES is required when KEYCLOAK_ISSUERS is configured',
+        });
+    });
+
+    it('resolves exact-issuer overrides and preserves equals in URLs', () => {
+        const url = 'http://keycloak:8080/certs?value=a=b';
+        vi.stubEnv(
+            'KEYCLOAK_JWKS_URL_OVERRIDES',
+            `ignored, ${issuer} = ${url}, https://other.example= `
+        );
+        expect(getKeycloakIssuerJwksUrl(issuer)).toBe(url);
+        expect(getKeycloakIssuerJwksUrl(`${issuer}/`)).toBe(
+            `${issuer}//protocol/openid-connect/certs`
+        );
+        expect(getKeycloakIssuerJwksUrl('https://other.example')).toBe(
+            'https://other.example/protocol/openid-connect/certs'
+        );
+    });
+});
+
+describe('offline Firebase verification', () => {
+    it.each(['invalid', 'header.%%.signature', 'header.eyJlbWFpbCI6MTIzfQ.signature'])(
+        'rejects malformed claims without contacting Firebase: %s',
+        async token => {
+            vi.mocked(admin.auth).mockClear();
+            await expect(verifyFirebaseToken(token)).rejects.toMatchObject({
+                code: 'UNAUTHORIZED',
+                message: 'Could not decode Firebase token in offline/E2E mode',
+            });
+            expect(admin.auth).not.toHaveBeenCalled();
+        }
+    );
+    it('accepts valid offline claims without contacting Firebase', async () => {
+        vi.mocked(admin.auth).mockClear();
+        const payload = Buffer.from(JSON.stringify({ uid: 'offline-id' })).toString('base64url');
+        await expect(verifyFirebaseToken(`header.${payload}.signature`)).resolves.toMatchObject({
+            id: 'offline-id',
+            providerType: 'firebase',
+        });
+        expect(admin.auth).not.toHaveBeenCalled();
+    });
+});
+
+describe('JWKS endpoint cache', () => {
+    it('replaces the resolver when the resolved URL changes and reuses unchanged URLs', () => {
+        setKeycloakJwksResolverForTests(undefined);
+        const original = getKeycloakJwks(issuer);
+        vi.stubEnv('KEYCLOAK_JWKS_URL_OVERRIDES', `${issuer}=http://internal:8080/certs`);
+        const updated = getKeycloakJwks(issuer);
+        expect(updated).not.toBe(original);
+        expect(getKeycloakJwks(issuer)).toBe(updated);
+        vi.stubEnv('KEYCLOAK_JWKS_URL_OVERRIDES', `${issuer}=http://other:8080/certs`);
+        expect(getKeycloakJwks(issuer)).not.toBe(updated);
+        vi.stubEnv('KEYCLOAK_JWKS_URL_OVERRIDES', '');
+        expect(getKeycloakJwks(issuer)).not.toBe(updated);
+    });
+});