@learncard/lca-api-service 1.4.0 → 1.5.1

package/src/helpers/oidc.helpers.ts

@@ -0,0 +1,354 @@
+/**
+ * Minimal OIDC provider primitives for lca-api (AD-2 of the Keycloak
+ * auth-provider migration).
+ *
+ * lca-api exposes a minimal OpenID Connect provider that Keycloak trusts as an
+ * upstream Identity Provider (alias `lca-api`). This module owns the signing
+ * key material, the discovery / JWKS documents, and the mint / verify
+ * primitives for the `id_token` returned from the `/oidc/token` endpoint.
+ *
+ * Design notes (per the design of record):
+ *  - The signing key is **separate from `SEED`** and rotated independently.
+ *    Deployed Lambdas fetch a JSON RSA private JWK using `OIDC_SIGNING_KEY_SECRET_ID`.
+ *    Local/Docker/CI can still set `OIDC_SIGNING_KEY_JWK`. When unset in production the provider fails closed
+ *    (503) — it never falls back to a forgeable key. In dev/CI an ephemeral
+ *    RSA keypair is generated once per process (random, never deterministic,
+ *    never a function of `SEED`) so local Keycloak can round-trip.
+ *  - RS256 is used because Keycloak's OIDC identity-provider brokering expects
+ *    RSA signing keys by default.
+ *  - Nothing here touches Mongo; it is pure crypto + config so it can be
+ *    unit-tested in isolation (see `test/oidc.spec.ts`).
+ */
+
+import crypto from 'node:crypto';
+import { GetSecretValueCommand, SecretsManagerClient } from '@aws-sdk/client-secrets-manager';
+
+import { environment } from '@config/oidcEnvironment';
+import { TRPCError } from '@trpc/server';
+import { SignJWT, calculateJwkThumbprint, exportJWK, importJWK } from 'jose';
+import type { CryptoKey, JWK, JWTPayload } from 'jose';
+
+/** The signing algorithm for self-issued OIDC tokens (Keycloak expects RSA). */
+export const OIDC_SIGNING_ALG = 'RS256' as const;
+
+/** Default lifetime (seconds) of a minted ID token. */
+export const DEFAULT_ID_TOKEN_TTL_SECONDS = 300;
+
+/** Default confidential relying-party client Keycloak brokers through. */
+export const DEFAULT_OIDC_CLIENT_ID = 'keycloak-broker';
+
+/** Claims carried by a self-issued OIDC ID token. */
+export interface OidcIdTokenClaims extends JWTPayload {
+    sub: string;
+    iss: string;
+    aud: string | string[];
+    email?: string;
+    email_verified?: boolean;
+    phone_number?: string;
+    phone_number_verified?: boolean;
+    name?: string;
+    picture?: string;
+}
+
+interface OidcSigningKey {
+    privateKey: CryptoKey;
+    publicKey: CryptoKey;
+    publicJwk: JWK;
+    kid: string;
+}
+
+let cachedKey: Promise<OidcSigningKey> | undefined;
+let cachedKeyMaterial: string | undefined;
+let ephemeralDevJwk: JWK | undefined;
+
+/**
+ * True when the service is running as a real deployment. `serverless.yml` does
+ * not set `NODE_ENV`, but it always sets `LAMBDA_STAGE`, so either signal counts;
+ * an ephemeral per-container key would otherwise be minted on every cold start.
+ */
+const isProduction = (): boolean =>
+    (environment.NODE_ENV === 'production' || Boolean(environment.LAMBDA_STAGE)) &&
+    !environment.IS_OFFLINE &&
+    !environment.IS_E2E_TEST;
+
+/** Parse both configured sources without exposing key material in errors. */
+const parseSigningJwk = (configured: string): JWK => {
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(configured);
+    } catch {
+        throw new TRPCError({
+            code: 'INTERNAL_SERVER_ERROR',
+            message: 'OIDC signing key must be a JSON RSA private JWK',
+        });
+    }
+    const jwk = parsed as JWK;
+    if (
+        !jwk ||
+        jwk.kty !== 'RSA' ||
+        typeof jwk.d !== 'string' ||
+        !jwk.d ||
+        typeof jwk.kid !== 'string' ||
+        !jwk.kid ||
+        jwk.alg !== 'RS256'
+    ) {
+        throw new TRPCError({
+            code: 'INTERNAL_SERVER_ERROR',
+            message: 'OIDC signing key must be an RSA private JWK with d, kid and alg=RS256',
+        });
+    }
+    return jwk;
+};
+
+/** Prefer the local override, then Secrets Manager; deployed instances fail closed. */
+const resolveSigningJwk = async (configured?: string, secretId?: string): Promise<JWK> => {
+    if (configured) return parseSigningJwk(configured);
+    if (secretId) {
+        let secretString: string | undefined;
+        try {
+            const client = new SecretsManagerClient({});
+            const result = await client.send(new GetSecretValueCommand({ SecretId: secretId }));
+            secretString = result.SecretString;
+        } catch {
+            throw new TRPCError({
+                code: 'INTERNAL_SERVER_ERROR',
+                message: 'OIDC signing key could not be fetched',
+            });
+        }
+        if (!secretString) {
+            throw new TRPCError({
+                code: 'INTERNAL_SERVER_ERROR',
+                message: 'OIDC signing key secret has no SecretString value',
+            });
+        }
+        return parseSigningJwk(secretString);
+    }
+
+    if (isProduction()) {
+        throw new TRPCError({
+            code: 'INTERNAL_SERVER_ERROR',
+            message: 'OIDC signing key is not configured',
+        });
+    }
+
+    if (!ephemeralDevJwk) {
+        const { privateKey } = crypto.generateKeyPairSync('rsa', { modulusLength: 2048 });
+        ephemeralDevJwk = privateKey.export({ format: 'jwk' }) as JWK;
+        process.emitWarning('OIDC is using an ephemeral development signing key.');
+    }
+    return ephemeralDevJwk;
+};
+
+/**
+ * Resolve (and memoize) the OIDC signing key.
+ *
+ * Cache the entire in-flight load by configuration; failures can be retried.
+ * Changing the local JWK or secret id transparently loads a fresh key.
+ */
+export const getOidcSigningKey = async (): Promise<OidcSigningKey> => {
+    const configured = environment.OIDC_SIGNING_KEY_JWK?.trim();
+    const secretId = environment.OIDC_SIGNING_KEY_SECRET_ID?.trim();
+    const material = configured
+        ? `configured:${configured}`
+        : secretId
+          ? `secret:${secretId}`
+          : isProduction()
+            ? 'unconfigured-production'
+            : 'ephemeral-dev';
+    if (cachedKey && cachedKeyMaterial === material) return cachedKey;
+
+    const pending = (async (): Promise<OidcSigningKey> => {
+        const jwk = await resolveSigningJwk(configured, secretId);
+        try {
+            const privateKey = (await importJWK(jwk, OIDC_SIGNING_ALG)) as CryptoKey;
+            const publicComponents: JWK = {
+                kty: 'RSA',
+                n: jwk.n,
+                e: jwk.e,
+            };
+            const publicKey = (await importJWK(publicComponents, OIDC_SIGNING_ALG)) as CryptoKey;
+
+            const publicJwk = await exportJWK(publicKey);
+            const kid = jwk.kid ?? (await calculateJwkThumbprint(publicJwk));
+
+            publicJwk.kid = kid;
+            publicJwk.alg = jwk.alg ?? OIDC_SIGNING_ALG;
+            publicJwk.use = 'sig';
+
+            return { privateKey, publicKey, publicJwk, kid };
+        } catch {
+            throw new TRPCError({
+                code: 'INTERNAL_SERVER_ERROR',
+                message: 'OIDC signing key could not be imported',
+            });
+        }
+    })();
+    cachedKey = pending;
+    cachedKeyMaterial = material;
+
+    try {
+        return await pending;
+    } catch (error) {
+        if (cachedKey === pending) resetOidcSigningKeyForTests();
+        throw error;
+    }
+};
+
+/** Clear the memoized signing key. Intended for isolated tests only. */
+export const resetOidcSigningKeyForTests = (): void => {
+    cachedKey = undefined;
+    cachedKeyMaterial = undefined;
+};
+
+/**
+ * The configured issuer identifier for this provider. Required — there is no
+ * default, so a misconfigured production deployment fails closed rather than
+ * minting tokens under a wrong issuer.
+ */
+export const getOidcIssuer = (): string => {
+    const issuer = environment.OIDC_ISSUER;
+    if (!issuer) {
+        throw new TRPCError({
+            code: 'INTERNAL_SERVER_ERROR',
+            message: 'OIDC issuer is not configured',
+        });
+    }
+    return issuer;
+};
+
+/**
+ * The confidential relying-party client Keycloak uses at the token endpoint.
+ * `id_token`s are minted with this client id as their audience so a token can
+ * only be consumed by the intended relying party.
+ */
+export const getOidcClientId = (): string => environment.OIDC_CLIENT_ID || DEFAULT_OIDC_CLIENT_ID;
+
+const splitCsv = (value: string | undefined): string[] =>
+    (value ?? '')
+        .split(',')
+        .map(entry => entry.trim())
+        .filter(Boolean);
+
+/**
+ * The exact redirect URIs the authorization endpoint will honor. `OIDC_REDIRECT_URIS`
+ * overrides; otherwise each `KEYCLOAK_ISSUERS` entry resolves to its single fixed
+ * broker callback `${issuer}/broker/lca-api/endpoint`. Prefixes are never accepted.
+ */
+export const getOidcRedirectUris = (): string[] => {
+    const explicit = splitCsv(environment.OIDC_REDIRECT_URIS);
+    if (explicit.length > 0) return explicit;
+    return splitCsv(environment.KEYCLOAK_ISSUERS).map(
+        issuer => `${issuer.replace(/\/+$/, '')}/broker/lca-api/endpoint`
+    );
+};
+
+/**
+ * Validate the confidential client's credentials at the token endpoint using a
+ * timing-safe comparison. In production `OIDC_CLIENT_SECRET` MUST be set; when
+ * it is unset (dev/CI only) the token endpoint refuses client authentication.
+ */
+export const verifyOidcClientCredentials = (clientId: string, clientSecret: string): boolean => {
+    const expectedSecret = environment.OIDC_CLIENT_SECRET;
+    if (!expectedSecret) return false;
+    if (clientId !== getOidcClientId()) return false;
+
+    const provided = Buffer.from(clientSecret);
+    const expected = Buffer.from(expectedSecret);
+    if (provided.length !== expected.length) return false;
+    return crypto.timingSafeEqual(provided, expected);
+};
+
+/**
+ * Require exact string equality; an empty allowlist rejects every redirect.
+ */
+export const isAllowedRedirectUri = (redirectUri: string): boolean => {
+    let candidate: URL;
+    try {
+        candidate = new URL(redirectUri);
+    } catch {
+        return false;
+    }
+    if (candidate.protocol !== 'https:' && candidate.protocol !== 'http:') return false;
+
+    return getOidcRedirectUris().includes(redirectUri);
+};
+
+/** The public JWKS document (single active signing key). */
+export const getOidcJwks = async (): Promise<{ keys: JWK[] }> => {
+    const { publicJwk } = await getOidcSigningKey();
+    return { keys: [publicJwk] };
+};
+
+/** The OIDC discovery document served at `/.well-known/openid-configuration`. */
+export const getOidcDiscoveryDocument = (): Record<string, unknown> => {
+    const issuer = getOidcIssuer();
+    return {
+        issuer,
+        authorization_endpoint: `${issuer}/oidc/authorize`,
+        token_endpoint: `${issuer}/oidc/token`,
+        jwks_uri: `${issuer}/oidc/jwks`,
+        userinfo_endpoint: `${issuer}/oidc/userinfo`,
+        response_types_supported: ['code'],
+        subject_types_supported: ['public'],
+        id_token_signing_alg_values_supported: [OIDC_SIGNING_ALG],
+        scopes_supported: ['openid', 'email', 'phone', 'profile'],
+        token_endpoint_auth_methods_supported: ['client_secret_post', 'client_secret_basic'],
+        grant_types_supported: ['authorization_code'],
+        claims_supported: [
+            'sub',
+            'iss',
+            'aud',
+            'exp',
+            'iat',
+            'email',
+            'email_verified',
+            'phone_number',
+            'phone_number_verified',
+            'name',
+            'picture',
+        ],
+    };
+};
+
+/** Mint a signed OIDC ID token whose audience is the confidential client. */
+export const mintIdToken = async (params: {
+    subject: string;
+    nonce?: string;
+    ttlSeconds?: number;
+    email?: string;
+    emailVerified?: boolean;
+    phoneNumber?: string;
+    phoneNumberVerified?: boolean;
+    name?: string;
+    picture?: string;
+}): Promise<{ token: string; expiresAt: number }> => {
+    const { privateKey, kid } = await getOidcSigningKey();
+    const issuer = getOidcIssuer();
+    const audience = getOidcClientId();
+    const now = Math.floor(Date.now() / 1000);
+    const ttl = params.ttlSeconds ?? DEFAULT_ID_TOKEN_TTL_SECONDS;
+    const expiresAt = now + ttl;
+
+    const claims: OidcIdTokenClaims = {
+        sub: params.subject,
+        iss: issuer,
+        aud: audience,
+    };
+    if (params.nonce !== undefined) claims.nonce = params.nonce;
+    if (params.email !== undefined) claims.email = params.email;
+    if (params.emailVerified !== undefined) claims.email_verified = params.emailVerified;
+    if (params.phoneNumber !== undefined) claims.phone_number = params.phoneNumber;
+    if (params.phoneNumberVerified !== undefined) {
+        claims.phone_number_verified = params.phoneNumberVerified;
+    }
+    if (params.name !== undefined) claims.name = params.name;
+    if (params.picture !== undefined) claims.picture = params.picture;
+
+    const token = await new SignJWT(claims)
+        .setProtectedHeader({ alg: OIDC_SIGNING_ALG, kid, typ: 'JWT' })
+        .setIssuedAt(now)
+        .setExpirationTime(expiresAt)
+        .sign(privateKey);
+
+    return { token, expiresAt };
+};

package/src/helpers/rate-limit.helpers.test.ts

@@ -0,0 +1,61 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import cache from '@cache';
+import { isRateLimited, recordFailure } from './rate-limit.helpers';
+
+vi.mock('@environment', () => ({ environment: {} }));
+
+const key = 'oidc:rate:test';
+
+beforeEach(async () => {
+    await cache.node.flushall();
+});
+
+afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+});
+
+describe('failure counter expiry', () => {
+    it('increments and expires a new counter atomically', async () => {
+        await recordFailure(key, 60);
+        expect(await cache.node.get(key)).toBe('1');
+        expect(await cache.node.ttl(key)).toBeGreaterThan(0);
+        expect(await cache.node.ttl(key)).toBeLessThanOrEqual(60);
+    });
+
+    it('repairs a counter without a TTL when recording a failure', async () => {
+        await cache.node.set(key, '4');
+        expect(await cache.node.ttl(key)).toBe(-1);
+        await recordFailure(key, 60);
+        expect(await cache.node.get(key)).toBe('5');
+        expect(await cache.node.ttl(key)).toBeGreaterThan(0);
+    });
+
+    it('repairs an already-blocked counter on read and eventually unblocks it', async () => {
+        vi.useFakeTimers();
+        await cache.node.set(key, '50');
+        expect(await isRateLimited(key)).toBe(true);
+        expect(await cache.node.ttl(key)).toBe(600);
+        vi.advanceTimersByTime(601_000);
+        expect(await isRateLimited(key)).toBe(false);
+    });
+
+    it('does not extend a live window on reads or writes', async () => {
+        vi.useFakeTimers();
+        await recordFailure(key, 60);
+        vi.advanceTimersByTime(10_000);
+        await recordFailure(key, 60);
+        expect(await isRateLimited(key)).toBe(false);
+        expect(await cache.node.ttl(key)).toBe(50);
+    });
+
+    it('does not create a counter for successful traffic', async () => {
+        expect(await isRateLimited(key)).toBe(false);
+        expect(await cache.node.exists(key)).toBe(0);
+    });
+
+    it('keeps the read-side fail-open behavior when Redis is unavailable', async () => {
+        vi.spyOn(cache.node, 'eval').mockRejectedValueOnce(new Error('Redis unavailable'));
+        expect(await isRateLimited(key)).toBe(false);
+    });
+});

package/src/helpers/rate-limit.helpers.ts

@@ -0,0 +1,73 @@
+import type { FastifyRequest } from 'fastify';
+
+import cache from '@cache';
+
+export const DEFAULT_MAX_FAILED_ATTEMPTS = 50;
+export const DEFAULT_RATE_LIMIT_WINDOW_SECONDS = 10 * 60;
+
+// Repair legacy counters during reads too: an already-blocked caller never reaches recordFailure.
+const READ_ATTEMPTS = `
+local attempts = redis.call('GET', KEYS[1])
+if attempts and redis.call('TTL', KEYS[1]) < 0 then
+    redis.call('EXPIRE', KEYS[1], ARGV[1])
+end
+return attempts
+`;
+
+const RECORD_FAILURE = `
+local attempts = redis.call('INCR', KEYS[1])
+if redis.call('TTL', KEYS[1]) < 0 then
+    redis.call('EXPIRE', KEYS[1], ARGV[1])
+end
+return attempts
+`;
+
+/**
+ * Failures-only rate limiting. Callers check `isRateLimited` up front and call
+ * `recordFailure` only on rejected attempts, so legitimate traffic behind a
+ * shared NAT never counts toward the ceiling. Increment and TTL repair run in
+ * one script without extending an existing window.
+ *
+ * Both halves fail open: if Redis is unreachable, reads return false and
+ * `recordFailure` logs and returns
+ * rather than turning a rejected login attempt into a 500. Limiting is a
+ * brute-force speed bump, not the access control — that is the ticket / code /
+ * client secret entropy.
+ */
+export const isRateLimited = async (
+    key: string,
+    max = DEFAULT_MAX_FAILED_ATTEMPTS
+): Promise<boolean> => {
+    const redis = cache.redis ?? cache.node;
+    try {
+        const attempts =
+            Number(await redis.eval(READ_ATTEMPTS, 1, key, DEFAULT_RATE_LIMIT_WINDOW_SECONDS)) || 0;
+        return attempts >= max;
+    } catch {
+        return false;
+    }
+};
+
+export const recordFailure = async (
+    key: string,
+    windowSeconds = DEFAULT_RATE_LIMIT_WINDOW_SECONDS
+): Promise<void> => {
+    const redis = cache.redis ?? cache.node;
+    try {
+        await redis.eval(RECORD_FAILURE, 1, key, windowSeconds);
+    } catch (error) {
+        console.error('Rate limit recordFailure error', error);
+    }
+};
+
+/**
+ * Client address for rate-limit keys.
+ *
+ * `request.ip` is the transport-level peer: under `serverless-http` it is API
+ * Gateway's `requestContext.http.sourceIp`, which the caller cannot forge. The
+ * `x-forwarded-for` header is NOT trusted — API Gateway appends the real source
+ * to whatever the client sent, so the first hop is attacker-controlled and would
+ * let anyone mint a fresh per-IP bucket per request.
+ */
+export const getRequestClientIp = (request: Pick<FastifyRequest, 'ip'>): string =>
+    request.ip || 'unknown';

package/src/helpers/social-token.helpers.ts

@@ -0,0 +1,144 @@
+/**
+ * Native Google / Apple `id_token` verification for the lca-api auth router
+ * (AD-2 / AD-3).
+ *
+ * The native app obtains an Apple/Google `id_token` through the platform SDK
+ * and posts it here. We verify it against the provider's published JWKS — exact
+ * issuer + audience (client id) allowlists, signature, `exp`/`nbf` — before
+ * issuing a login ticket. A test seam (`setSocialJwksResolverForTests`) swaps
+ * the remote JWKS for a local key set so the flow is unit-testable without
+ * network access.
+ */
+
+import { environment } from '@environment';
+import { TRPCError } from '@trpc/server';
+import { createRemoteJWKSet, jwtVerify } from 'jose';
+import type { JWTVerifyGetKey } from 'jose';
+import { z } from 'zod';
+
+export type SocialProviderId = 'google' | 'apple';
+
+export interface SocialProviderConfig {
+    issuers: string[];
+    audiences: string[];
+    jwksUri: string;
+}
+
+export interface SocialClaims {
+    sub: string;
+    iss: string;
+    email?: string;
+    email_verified?: boolean;
+    name?: string;
+    picture?: string;
+}
+
+const GOOGLE_DEFAULT_ISSUERS = ['https://accounts.google.com', 'accounts.google.com'];
+const GOOGLE_JWKS_URI = 'https://www.googleapis.com/oauth2/v3/certs';
+const APPLE_DEFAULT_ISSUERS = ['https://appleid.apple.com'];
+const APPLE_JWKS_URI = 'https://appleid.apple.com/auth/keys';
+
+const claimsSchema = z
+    .object({
+        sub: z.string().min(1),
+        iss: z.string().min(1),
+        email: z.string().min(1).optional(),
+        email_verified: z.union([z.boolean(), z.string()]).optional(),
+        name: z.string().optional(),
+        picture: z.string().optional(),
+    })
+    .passthrough();
+
+const splitCsv = (value: string | undefined): string[] =>
+    (value ?? '')
+        .split(',')
+        .map(entry => entry.trim())
+        .filter(Boolean);
+
+export const getSocialProviderConfig = (
+    provider: SocialProviderId
+): SocialProviderConfig | null => {
+    if (provider === 'google') {
+        const audiences = splitCsv(environment.GOOGLE_OAUTH_CLIENT_IDS);
+        if (audiences.length === 0) return null;
+        return {
+            audiences,
+            issuers: GOOGLE_DEFAULT_ISSUERS,
+            jwksUri: GOOGLE_JWKS_URI,
+        };
+    }
+
+    const audiences = splitCsv(environment.APPLE_OAUTH_CLIENT_IDS);
+    if (audiences.length === 0) return null;
+    return {
+        audiences,
+        issuers: APPLE_DEFAULT_ISSUERS,
+        jwksUri: APPLE_JWKS_URI,
+    };
+};
+
+const jwksByUri = new Map<string, JWTVerifyGetKey>();
+let resolverForTests: ((jwksUri: string) => JWTVerifyGetKey) | undefined;
+
+export const setSocialJwksResolverForTests = (
+    resolver: ((jwksUri: string) => JWTVerifyGetKey) | undefined
+): void => {
+    resolverForTests = resolver;
+    jwksByUri.clear();
+};
+
+export const getSocialJwks = (jwksUri: string): JWTVerifyGetKey => {
+    let jwks = jwksByUri.get(jwksUri);
+    if (!jwks) {
+        jwks = resolverForTests ? resolverForTests(jwksUri) : createRemoteJWKSet(new URL(jwksUri));
+        jwksByUri.set(jwksUri, jwks);
+    }
+    return jwks;
+};
+
+export const verifySocialIdToken = async (
+    provider: SocialProviderId,
+    token: string
+): Promise<SocialClaims> => {
+    const config = getSocialProviderConfig(provider);
+    if (!config) {
+        throw new TRPCError({
+            code: 'UNAUTHORIZED',
+            message: `Sign-in with ${provider} is not configured.`,
+        });
+    }
+
+    let payload: unknown;
+    try {
+        ({ payload } = await jwtVerify(token, getSocialJwks(config.jwksUri), {
+            issuer: config.issuers,
+            audience: config.audiences,
+            algorithms: ['RS256', 'ES256'],
+            requiredClaims: ['sub', 'exp', 'email', 'email_verified'],
+        }));
+    } catch {
+        throw new TRPCError({ code: 'UNAUTHORIZED', message: 'Invalid social token' });
+    }
+
+    const result = claimsSchema.safeParse(payload);
+    if (!result.success) {
+        throw new TRPCError({ code: 'UNAUTHORIZED', message: 'Invalid social token' });
+    }
+
+    const claims = result.data;
+    const emailVerified =
+        claims.email_verified === true ||
+        (provider === 'apple' && claims.email_verified === 'true');
+    if (!claims.email || !emailVerified) {
+        throw new TRPCError({ code: 'UNAUTHORIZED', message: 'Invalid social token' });
+    }
+
+    return {
+        sub: claims.sub,
+        iss: claims.iss,
+        email: claims.email,
+        email_verified: emailVerified,
+        name: claims.name,
+        picture: claims.picture,
+    };
+};

package/src/index.ts

@@ -2,4 +2,5 @@ export type { AppRouter } from './app';
 
 export { appRouter as mainApp } from './app';
 export { app as didApp } from './dids';
+export { app as oidcApp } from './oidc';
 export { app as swaggerApp } from './openapi';