@learncard/lca-api-service 1.3.2 → 1.5.0

package/src/cache/getDel.ts

@@ -0,0 +1,32 @@
+import cache from '@cache';
+
+/**
+ * Atomically read-and-delete a key so its value can only ever be consumed once.
+ *
+ * Redis `GETDEL` is a single command, so concurrent redemptions return the value
+ * to exactly one caller — closing the read-then-delete race that `get` + `delete`
+ * would leave open. Used for login codes, login tickets and authorization codes.
+ *
+ * NOTE: `GETDEL` requires Redis >= 6.2. Deployed ElastiCache clusters are on 7.x
+ * (see the `ElasticCacheCluster` note in `serverless.yml`); `ioredis-mock`
+ * implements it for the no-Redis fallback.
+ */
+export const getDel = async (key: string): Promise<string | null> => {
+    const redis = cache.redis ?? cache.node;
+    return redis.getdel(key);
+};
+
+/** Consume a code only when its value matches, atomically preventing replay. */
+export const consumeMatchingCode = async (key: string, code: string): Promise<boolean> => {
+    const redis = cache.redis ?? cache.node;
+    const consumed = await redis.eval(
+        `if redis.call('GET', KEYS[1]) == ARGV[1] then
+            return redis.call('DEL', KEYS[1])
+        end
+        return 0`,
+        1,
+        key,
+        code
+    );
+    return consumed === 1;
+};

package/src/cache/in-memory-lru.ts

@@ -18,6 +18,7 @@ export const getLRUCache = <T>(limit = 50) => {
     };
 
     const add = (key: string, value: T) => {
+        items = items.filter(item => item.key !== key);
         items.unshift({ key, value, timestamp: Date.now() });
 
         items = items.slice(0, limit);

package/src/cache/index.ts

@@ -1,6 +1,6 @@
 /// <reference path="../global.d.ts" />
 
-import { environment } from '@environment';
+import { environment } from '@config/cacheEnvironment';
 import Redis, { RedisValue, RedisKey } from 'ioredis';
 import MemoryRedis, { Redis as RedisMockType } from 'ioredis-mock';
 

package/src/cache/login-tickets.ts

@@ -0,0 +1,26 @@
+import { randomBytes } from 'node:crypto';
+import cache from '@cache';
+import { getDel } from '@cache/getDel';
+
+export interface LoginTicketPayload {
+    subject: string;
+    email?: string;
+    emailVerified?: boolean;
+    phoneNumber?: string;
+    phoneNumberVerified?: boolean;
+    name?: string;
+    picture?: string;
+    identityKey: string;
+}
+
+export const issueLoginTicket = async (payload: LoginTicketPayload): Promise<string> => {
+    const ticket = randomBytes(32).toString('base64url');
+    const result = await cache.set(`login-ticket:${ticket}`, JSON.stringify(payload), 60);
+    if (result !== 'OK') throw new Error('Failed to persist login ticket');
+    return ticket;
+};
+
+export const redeemLoginTicket = async (ticket: string): Promise<LoginTicketPayload | null> => {
+    const raw = await getDel(`login-ticket:${ticket}`);
+    return raw ? (JSON.parse(raw) as LoginTicketPayload) : null;
+};

package/src/cache/recoverySessions.ts

@@ -0,0 +1,252 @@
+import { createHash, randomBytes } from 'crypto';
+
+import cache from '@cache';
+import type { AuthProviderType } from '@helpers/auth.helpers';
+
+export const RECOVERY_SESSION_TTL_SECS = 15 * 60;
+export const RECOVERY_OTP_TTL_SECS = 15 * 60;
+export const RECOVERY_OTP_SEND_COOLDOWN_SECS = 60;
+export const MAX_RECOVERY_OTP_ATTEMPTS = 5;
+
+export type RecoverySessionScope = 'recover' | 'rebind';
+
+export interface RecoverySessionRecord {
+    scope: RecoverySessionScope;
+    authProvider: { type: AuthProviderType; id: string };
+}
+
+export interface RecoveryOtpRecord {
+    codeHash: string;
+    authProvider: { type: AuthProviderType; id: string };
+}
+
+export type RecoveryOtpVerificationResult =
+    | { status: 'ok'; record: RecoveryOtpRecord }
+    | { status: 'mismatch'; attempts: number }
+    | { status: 'locked' }
+    | { status: 'none' };
+
+const digest = (value: string): string => createHash('sha256').update(value).digest('hex');
+
+export const getRecoveryEmailDigest = (email: string): string => digest(email.trim().toLowerCase());
+
+export const getRecoveryOtpCacheKey = (email: string): string =>
+    `recovery-session-otp|${getRecoveryEmailDigest(email)}`;
+
+export const getRecoveryOtpAttemptsCacheKey = (email: string): string =>
+    `recovery-session-otp-attempts|${getRecoveryEmailDigest(email)}`;
+
+export const getRecoveryOtpLockCacheKey = (email: string): string =>
+    `recovery-session-otp-lock|${getRecoveryEmailDigest(email)}`;
+
+export const getRecoveryOtpSendCacheKey = (email: string): string =>
+    `recovery-session-otp-send|${getRecoveryEmailDigest(email)}`;
+
+export const getRecoverySessionCacheKey = (token: string): string =>
+    `recovery-session|${digest(token)}`;
+
+export const createRecoverySession = async (
+    record: RecoverySessionRecord,
+    ttl = RECOVERY_SESSION_TTL_SECS
+): Promise<string> => {
+    const token = randomBytes(32).toString('hex');
+
+    await cache.set(getRecoverySessionCacheKey(token), JSON.stringify(record), ttl);
+
+    return token;
+};
+
+/** Atomically consume a recovery token. Every token authorizes exactly one route call. */
+export const consumeRecoverySession = async (
+    token: string,
+    expectedScope: RecoverySessionScope
+): Promise<RecoverySessionRecord | null> => {
+    const redis = cache.redis ?? cache.node;
+    const raw = await redis.getdel(getRecoverySessionCacheKey(token));
+
+    if (!raw) return null;
+
+    try {
+        const record = JSON.parse(raw) as RecoverySessionRecord;
+
+        return record.scope === expectedScope ? record : null;
+    } catch {
+        return null;
+    }
+};
+
+const VERIFY_RECOVERY_OTP_SCRIPT = `
+if redis.call('EXISTS', KEYS[3]) == 1 then
+    return 'locked'
+end
+
+local pending = redis.call('GET', KEYS[1])
+if not pending then
+    return 'none'
+end
+
+local decoded, record = pcall(cjson.decode, pending)
+if not decoded or type(record) ~= 'table' or type(record.codeHash) ~= 'string' then
+    redis.call('DEL', KEYS[1])
+    return 'none'
+end
+
+-- Both values are fixed-length SHA-256 hex digests rather than raw OTPs. A simple
+-- server-side equality check is acceptable here because attempts are capped and Redis
+-- round-trip noise makes digest-prefix timing impractical; doing it here also keeps the
+-- existence check, attempt increment, lock, and consume operations atomic.
+if record.codeHash == ARGV[1] then
+    redis.call('DEL', KEYS[1], KEYS[2])
+    return { 'ok', pending }
+end
+
+local attempts = redis.call('INCR', KEYS[2])
+if attempts == 1 then
+    redis.call('EXPIRE', KEYS[2], tonumber(ARGV[3]))
+end
+
+if attempts >= tonumber(ARGV[2]) then
+    redis.call('DEL', KEYS[1])
+    redis.call('SET', KEYS[3], 'locked', 'EX', tonumber(ARGV[3]))
+end
+
+return 'mismatch:' .. attempts
+`;
+
+const fallbackVerificationQueues = new Map<string, Promise<void>>();
+
+const withFallbackVerificationLock = async <T>(
+    key: string,
+    operation: () => Promise<T>
+): Promise<T> => {
+    const previous = fallbackVerificationQueues.get(key) ?? Promise.resolve();
+    let release = (): void => undefined;
+    const gate = new Promise<void>(resolve => {
+        release = resolve;
+    });
+    const queued = previous.then(() => gate);
+
+    fallbackVerificationQueues.set(key, queued);
+    await previous;
+
+    try {
+        return await operation();
+    } finally {
+        release();
+        if (fallbackVerificationQueues.get(key) === queued) {
+            fallbackVerificationQueues.delete(key);
+        }
+    }
+};
+
+const parseRecoveryOtpRecord = (raw: string): RecoveryOtpRecord | null => {
+    try {
+        const record = JSON.parse(raw) as RecoveryOtpRecord;
+
+        if (
+            typeof record.codeHash !== 'string' ||
+            typeof record.authProvider?.type !== 'string' ||
+            typeof record.authProvider.id !== 'string'
+        ) {
+            return null;
+        }
+
+        return record;
+    } catch {
+        return null;
+    }
+};
+
+export const storeRecoveryOtp = async (email: string, record: RecoveryOtpRecord): Promise<void> => {
+    const key = getRecoveryOtpCacheKey(email);
+    const value = JSON.stringify(record);
+
+    if (cache.redis) {
+        await cache.redis.setex(key, RECOVERY_OTP_TTL_SECS, value);
+        return;
+    }
+
+    await withFallbackVerificationLock(key, async () => {
+        await cache.node.setex(key, RECOVERY_OTP_TTL_SECS, value);
+    });
+};
+
+export const verifyRecoveryOtp = async (
+    email: string,
+    submittedCodeHash: string
+): Promise<RecoveryOtpVerificationResult> => {
+    const otpKey = getRecoveryOtpCacheKey(email);
+    const attemptsKey = getRecoveryOtpAttemptsCacheKey(email);
+    const lockKey = getRecoveryOtpLockCacheKey(email);
+
+    if (cache.redis) {
+        const result = await cache.redis.eval(
+            VERIFY_RECOVERY_OTP_SCRIPT,
+            3,
+            otpKey,
+            attemptsKey,
+            lockKey,
+            submittedCodeHash,
+            MAX_RECOVERY_OTP_ATTEMPTS,
+            RECOVERY_OTP_TTL_SECS
+        );
+
+        if (Array.isArray(result) && result[0] === 'ok' && typeof result[1] === 'string') {
+            const record = parseRecoveryOtpRecord(result[1]);
+            if (record) return { status: 'ok', record };
+            return { status: 'none' };
+        }
+
+        const status = String(result);
+        if (status === 'locked' || status === 'none') return { status };
+
+        const mismatch = /^mismatch:(\d+)$/.exec(status);
+        if (mismatch?.[1]) {
+            return { status: 'mismatch', attempts: Number(mismatch[1]) };
+        }
+
+        throw new Error(`Unexpected recovery OTP verification result: ${status}`);
+    }
+
+    return withFallbackVerificationLock(otpKey, async () => {
+        if (await cache.node.get(lockKey)) return { status: 'locked' };
+
+        const raw = await cache.node.get(otpKey);
+        if (!raw) return { status: 'none' };
+
+        const record = parseRecoveryOtpRecord(raw);
+        if (!record) {
+            await cache.node.del(otpKey);
+            return { status: 'none' };
+        }
+
+        // See the Lua comment above: only fixed-length server-side digests are compared.
+        if (record.codeHash === submittedCodeHash) {
+            await cache.node.del(otpKey, attemptsKey);
+            return { status: 'ok', record };
+        }
+
+        const attempts = await cache.node.incr(attemptsKey);
+        if (attempts === 1) await cache.node.expire(attemptsKey, RECOVERY_OTP_TTL_SECS);
+
+        if (attempts >= MAX_RECOVERY_OTP_ATTEMPTS) {
+            await cache.node.del(otpKey);
+            await cache.node.set(lockKey, 'locked', 'EX', RECOVERY_OTP_TTL_SECS);
+        }
+
+        return { status: 'mismatch', attempts };
+    });
+};
+
+export const claimRecoveryOtpSendWindow = async (email: string): Promise<boolean> => {
+    const redis = cache.redis ?? cache.node;
+    const result = await redis.set(
+        getRecoveryOtpSendCacheKey(email),
+        'sent',
+        'EX',
+        RECOVERY_OTP_SEND_COOLDOWN_SECS,
+        'NX'
+    );
+
+    return result === 'OK';
+};

package/src/config/applyDockerStageConfig.ts

@@ -0,0 +1,6 @@
+import { applyLcaApiStageConfig } from './stageConfig';
+
+// Side-effect import: runs before @environment is evaluated so Docker/local processes
+// pick up checked-in per-stage config. Keyed on CONFIG_STAGE (Lambda uses LAMBDA_STAGE);
+// explicit non-empty env values from the developer's .env still win.
+applyLcaApiStageConfig(process.env.CONFIG_STAGE);

package/src/config/cacheEnvironment.ts

@@ -0,0 +1,34 @@
+import 'dotenv/config';
+
+import { z } from 'zod';
+import {
+    optionalEnvironmentPort,
+    optionalEnvironmentString,
+    parseEnvironment,
+} from '@learncard/helpers';
+
+/**
+ * Focused environment contract for the Redis-backed cache so `src/cache/index.ts`
+ * can boot without the full schema's required SEED/MONGO. The cache reads only
+ * REDIS_HOST/REDIS_PORT, mirroring the parsers used by the full schema.
+ */
+export const cacheEnvironmentShape = {
+    REDIS_HOST: optionalEnvironmentString,
+    REDIS_PORT: optionalEnvironmentPort,
+} satisfies z.ZodRawShape;
+
+export const cacheEnvironmentSchema = z.object(cacheEnvironmentShape);
+
+export type CacheEnvironment = z.output<typeof cacheEnvironmentSchema>;
+
+export const parseCacheEnvironment = (
+    raw: Record<string, unknown>,
+    source = 'process environment'
+): CacheEnvironment =>
+    parseEnvironment(cacheEnvironmentSchema, raw, {
+        project: 'lca-api (cache)',
+        source,
+        examplePath: 'services/learn-card-network/lca-api/.env.example',
+    });
+
+export const environment = parseCacheEnvironment(process.env);

package/src/config/environment.test.ts

@@ -0,0 +1,159 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { isEscrowReleaseKillSwitchEnabled, parseLcaApiEnvironment } from './environment';
+
+afterEach(() => vi.unstubAllEnvs());
+
+describe('live escrow release kill switch', () => {
+    it.each(['1', 'true'])('blocks releases for %s', value => {
+        vi.stubEnv('ESCROW_RELEASE_KILL_SWITCH', value);
+        expect(isEscrowReleaseKillSwitchEnabled()).toBe(true);
+    });
+    it.each(['0', 'false', ''])('allows releases for %s', value => {
+        vi.stubEnv('ESCROW_RELEASE_KILL_SWITCH', value);
+        expect(isEscrowReleaseKillSwitchEnabled()).toBe(false);
+    });
+});
+
+const production = {
+    NODE_ENV: 'production',
+    DOMAIN_NAME: 'api.example.com',
+    SEED: 'a'.repeat(64),
+    MONGO_URI: 'mongodb://localhost:27017',
+    MONGO_DB_NAME: 'test',
+};
+
+describe('signing-authority seed environment', () => {
+    it.each(['1', 'true'])('keeps offline development plaintext without a KEK (%s)', offline => {
+        const env = parseLcaApiEnvironment({
+            ...production,
+            NODE_ENV: 'development',
+            IS_OFFLINE: offline,
+            SA_SEED_LOCAL_KEK: '',
+        });
+        expect(env.SA_SEED_LOCAL_KEK).toBeUndefined();
+        expect(env.SA_SEED_ENCRYPT_WRITES).toBe(false);
+        expect(env.SA_SEED_ALLOW_LEGACY_READ).toBe(true);
+    });
+    it('requires an explicit key when offline development opts into encryption', () => {
+        const raw = {
+            ...production,
+            NODE_ENV: 'development',
+            IS_OFFLINE: 'true',
+            SA_SEED_ENCRYPT_WRITES: 'true',
+        };
+        expect(() => parseLcaApiEnvironment(raw)).toThrow();
+        const env = parseLcaApiEnvironment({ ...raw, SA_SEED_LOCAL_KEK: 'b'.repeat(64) });
+        expect(env.SA_SEED_ENCRYPT_WRITES).toBe(true);
+        expect(env.SA_SEED_ALLOW_LEGACY_READ).toBe(true);
+        expect(env.SA_SEED_LOCAL_KEK).toBe('b'.repeat(64));
+    });
+    it('does not enable encryption just because a local key is configured', () => {
+        const env = parseLcaApiEnvironment({
+            ...production,
+            IS_OFFLINE: 'true',
+            SA_SEED_LOCAL_KEK: 'b'.repeat(64),
+        });
+        expect(env.SA_SEED_ENCRYPT_WRITES).toBe(false);
+        expect(env.SA_SEED_ALLOW_LEGACY_READ).toBe(true);
+        expect(() =>
+            parseLcaApiEnvironment({ ...production, IS_OFFLINE: 'true', SA_SEED_LOCAL_KEK: 'bad' })
+        ).toThrow();
+    });
+    it.each(['production', 'development'])('keeps online %s defaults encrypted', nodeEnv => {
+        const env = parseLcaApiEnvironment({
+            ...production,
+            NODE_ENV: nodeEnv,
+            SA_SEED_KMS_KEY_ARN:
+                'arn:aws:kms:us-east-1:123456789012:key/11111111-1111-1111-1111-111111111111',
+        });
+        expect(env.SA_SEED_ENCRYPT_WRITES).toBe(true);
+        expect(env.SA_SEED_ALLOW_LEGACY_READ).toBe(false);
+    });
+    it('defaults tests to ciphertext writes without AWS', () => {
+        const env = parseLcaApiEnvironment({ NODE_ENV: 'test', IS_OFFLINE: 'true' });
+        expect(env.SA_SEED_LOCAL_KEK).toHaveLength(64);
+        expect(env.SA_SEED_ENCRYPT_WRITES).toBe(true);
+        expect(env.SA_SEED_ALLOW_LEGACY_READ).toBe(false);
+    });
+    it('requires KMS for online deployments regardless of NODE_ENV', () => {
+        expect(() => parseLcaApiEnvironment(production)).toThrow();
+        expect(() => parseLcaApiEnvironment({ ...production, NODE_ENV: 'development' })).toThrow();
+        expect(() => parseLcaApiEnvironment({ ...production, IS_E2E_TEST: 'true' })).toThrow();
+    });
+    it('requires a real key ARN, or an explicit offline KEK', () => {
+        expect(() =>
+            parseLcaApiEnvironment({ ...production, SA_SEED_KMS_KEY_ARN: 'alias/test' })
+        ).toThrow();
+        expect(() =>
+            parseLcaApiEnvironment({
+                ...production,
+                IS_OFFLINE: 'true',
+                SA_SEED_ENCRYPT_WRITES: 'true',
+            })
+        ).toThrow();
+        expect(() =>
+            parseLcaApiEnvironment({
+                ...production,
+                IS_OFFLINE: 'true',
+                SA_SEED_ENCRYPT_WRITES: 'true',
+                SA_SEED_LOCAL_KEK: 'f'.repeat(64),
+            })
+        ).not.toThrow();
+        expect(() =>
+            parseLcaApiEnvironment({
+                ...production,
+                SA_SEED_KMS_KEY_ARN:
+                    'arn:aws:kms:us-east-1:123456789012:key/11111111-1111-1111-1111-111111111111',
+            })
+        ).not.toThrow();
+    });
+    it('does not allow a writer that its own reader cannot read', () => {
+        expect(() =>
+            parseLcaApiEnvironment({
+                ...production,
+                IS_OFFLINE: 'true',
+                SA_SEED_ALLOW_LEGACY_READ: 'false',
+            })
+        ).toThrow();
+        expect(() =>
+            parseLcaApiEnvironment({ NODE_ENV: 'test', SA_SEED_ENCRYPT_WRITES: 'false' })
+        ).toThrow();
+        expect(() =>
+            parseLcaApiEnvironment({
+                NODE_ENV: 'test',
+                SA_SEED_ENCRYPT_WRITES: 'false',
+                SA_SEED_ALLOW_LEGACY_READ: 'true',
+            })
+        ).not.toThrow();
+    });
+});
+
+describe('Keycloak startup configuration', () => {
+    it.each([undefined, '', '   ', ' , , '])('rejects missing audiences: %s', audiences => {
+        expect(() =>
+            parseLcaApiEnvironment({
+                NODE_ENV: 'test',
+                IS_OFFLINE: 'true',
+                KEYCLOAK_ISSUERS: 'https://identity.example/realms/learncard',
+                KEYCLOAK_AUDIENCES: audiences,
+            })
+        ).toThrow(/KEYCLOAK_AUDIENCES/);
+    });
+    it('allows disabled Keycloak and valid issuer/audience configuration', () => {
+        expect(() =>
+            parseLcaApiEnvironment({
+                NODE_ENV: 'test',
+                IS_OFFLINE: 'true',
+                KEYCLOAK_ISSUERS: ' , ',
+            })
+        ).not.toThrow();
+        expect(() =>
+            parseLcaApiEnvironment({
+                NODE_ENV: 'test',
+                IS_OFFLINE: 'true',
+                KEYCLOAK_ISSUERS: 'https://identity.example/realms/learncard',
+                KEYCLOAK_AUDIENCES: ' , learncard-app, ',
+            })
+        ).not.toThrow();
+    });
+});