@learncard/lca-api-service 1.3.1 → 1.4.0

package/src/config/environment.ts

@@ -15,6 +15,11 @@ export const lcaApiEnvironmentShape = {
     NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
     PORT: environmentPort.default(3000),
     SEED: requiredEnvironmentString,
+    SA_SEED_KMS_KEY_ARN: optionalEnvironmentString,
+    SA_SEED_LOCAL_KEK: optionalEnvironmentString,
+    // Defaults depend on offline/test mode and are resolved below.
+    SA_SEED_ENCRYPT_WRITES: optionalEnvironmentBoolean,
+    SA_SEED_ALLOW_LEGACY_READ: optionalEnvironmentBoolean,
     MONGO_URI: requiredEnvironmentString,
     MONGO_DB_NAME: requiredEnvironmentString,
     DOMAIN_NAME: optionalEnvironmentString,
@@ -32,6 +37,17 @@ export const lcaApiEnvironmentShape = {
     POSTMARK_ENDORSEMENT_REQUEST_TEMPLATE_ALIAS: optionalEnvironmentString,
     POSTMARK_RECOVERY_EMAIL_CODE_TEMPLATE_ALIAS: optionalEnvironmentString,
     POSTMARK_RECOVERY_KEY_TEMPLATE_ALIAS: optionalEnvironmentString,
+    ESCROW_RELAY_URL: optionalEnvironmentUrl,
+    ESCROW_RELAY_AUTH_TOKEN: optionalEnvironmentString,
+    ESCROW_ENCLAVE_MODE: optionalEnvironmentString.pipe(z.enum(['software', 'remote']).optional()),
+    ESCROW_ENCLAVE_SOFTWARE_PRIVATE_KEYS_JSON: optionalEnvironmentString,
+    ESCROW_ENCLAVE_ACTIVE_KEY_ID: optionalEnvironmentString,
+    ESCROW_HOLD_DURATION_MS: optionalEnvironmentString
+        .transform(value => (value === undefined ? 604_800_000 : Number(value)))
+        .pipe(z.number().int().positive().max(Number.MAX_SAFE_INTEGER)),
+    ESCROW_HOLD_RESTART_MIN_AGE_MS: optionalEnvironmentString
+        .transform(value => (value === undefined ? 86_400_000 : Number(value)))
+        .pipe(z.number().int().positive().max(Number.MAX_SAFE_INTEGER)),
     ANDROID_PUSH_ICON: optionalEnvironmentString,
     REDIS_HOST: optionalEnvironmentString,
     REDIS_PORT: optionalEnvironmentPort,
@@ -49,7 +65,74 @@ export const lcaApiEnvironmentShape = {
 
 export const lcaApiEnvironmentSchema = z
     .object(lcaApiEnvironmentShape)
+    .transform(environment => {
+        const legacyLocalDefaults = environment.IS_OFFLINE && environment.NODE_ENV !== 'test';
+        return {
+            ...environment,
+            SA_SEED_ENCRYPT_WRITES: environment.SA_SEED_ENCRYPT_WRITES ?? !legacyLocalDefaults,
+            SA_SEED_ALLOW_LEGACY_READ: environment.SA_SEED_ALLOW_LEGACY_READ ?? legacyLocalDefaults,
+        };
+    })
     .superRefine((environment, context) => {
+        if (environment.ESCROW_ENCLAVE_MODE === 'software') {
+            try {
+                const keys = parseEscrowPrivateKeys(
+                    environment.ESCROW_ENCLAVE_SOFTWARE_PRIVATE_KEYS_JSON ?? ''
+                );
+                if (
+                    !environment.ESCROW_ENCLAVE_ACTIVE_KEY_ID ||
+                    !Object.hasOwn(keys, environment.ESCROW_ENCLAVE_ACTIVE_KEY_ID)
+                ) {
+                    context.addIssue({
+                        code: 'custom',
+                        path: ['ESCROW_ENCLAVE_ACTIVE_KEY_ID'],
+                        message: 'Software escrow requires an active key ID present in the key map',
+                    });
+                }
+            } catch {
+                context.addIssue({
+                    code: 'custom',
+                    path: ['ESCROW_ENCLAVE_SOFTWARE_PRIVATE_KEYS_JSON'],
+                    message:
+                        'Software escrow requires a valid nonempty key ID to private key JSON map',
+                });
+            }
+        }
+        if (environment.SA_SEED_KMS_KEY_ARN) {
+            if (
+                !/^arn:aws[a-z-]*:kms:[a-z0-9-]+:\d{12}:key\/[a-zA-Z0-9-]+$/.test(
+                    environment.SA_SEED_KMS_KEY_ARN
+                )
+            ) {
+                context.addIssue({
+                    code: 'custom',
+                    path: ['SA_SEED_KMS_KEY_ARN'],
+                    message: 'Must be a KMS key ARN (not an alias)',
+                });
+            }
+        } else if (!environment.IS_OFFLINE && environment.NODE_ENV !== 'test') {
+            context.addIssue({
+                code: 'custom',
+                path: ['SA_SEED_KMS_KEY_ARN'],
+                message: 'Required outside offline/test environments',
+            });
+        } else if (
+            (environment.SA_SEED_ENCRYPT_WRITES || environment.SA_SEED_LOCAL_KEK !== undefined) &&
+            !/^[a-fA-F0-9]{64}$/.test(environment.SA_SEED_LOCAL_KEK ?? '')
+        ) {
+            context.addIssue({
+                code: 'custom',
+                path: ['SA_SEED_LOCAL_KEK'],
+                message: 'A 32-byte hex key is required for local seed encryption',
+            });
+        }
+        if (!environment.SA_SEED_ENCRYPT_WRITES && !environment.SA_SEED_ALLOW_LEGACY_READ) {
+            context.addIssue({
+                code: 'custom',
+                path: ['SA_SEED_ENCRYPT_WRITES'],
+                message: 'Plaintext writes require the compatibility reader',
+            });
+        }
         if (
             environment.NODE_ENV === 'production' &&
             !environment.IS_OFFLINE &&
@@ -85,6 +168,7 @@ export const parseLcaApiEnvironment = (
         raw.NODE_ENV === 'test'
             ? {
                   SEED: 'a'.repeat(64),
+                  SA_SEED_LOCAL_KEK: 'f'.repeat(64),
                   MONGO_URI: 'mongodb://localhost:27017',
                   MONGO_DB_NAME: 'lca-api-test',
               }
@@ -101,4 +185,17 @@ export const parseLcaApiEnvironment = (
     );
 };
 
+/** Parse configuration without exposing secret values in validation errors. */
+export const parseEscrowPrivateKeys = (serialized: string): Record<string, string> => {
+    try {
+        const parsed: unknown = JSON.parse(serialized);
+        return z
+            .record(z.string().regex(/^[A-Za-z0-9._-]{1,128}$/), z.string().trim().min(1))
+            .refine(keys => Object.keys(keys).length > 0)
+            .parse(parsed);
+    } catch {
+        throw new Error('Invalid escrow private key configuration');
+    }
+};
+
 export const environment = parseLcaApiEnvironment(process.env);

package/src/docker-entry.ts

@@ -9,6 +9,7 @@ import { fastifyTRPCOpenApiPlugin, CreateOpenApiFastifyPluginOptions } from 'trp
 import { appRouter, type AppRouter, createContext } from './app';
 import { openApiDocument } from './openapi';
 import { didFastifyPlugin } from './dids';
+import { ensureUserKeysIndexes, createEscrowHoldsIndexes } from './models';
 
 const server = Fastify({ maxParamLength: 5000 });
 
@@ -50,6 +51,7 @@ server.register(fastifyCors, {
         'Authorization',
         'X-Tenant-Id',
         'X-Guardian-Approval',
+        'X-Auth-Token',
         'baggage',
         'sentry-trace',
     ],
@@ -104,6 +106,8 @@ server.register(didFastifyPlugin);
 (async () => {
     try {
         console.log('Server starting on port ', environment.PORT || 3000);
+        await ensureUserKeysIndexes();
+        await createEscrowHoldsIndexes();
         await server.listen({ host: '0.0.0.0', port: Number(environment.PORT || 3000) });
     } catch (err) {
         console.error(err);

package/src/helpers/learnCard.helpers.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it, vi } from 'vitest';
 
 const mocks = vi.hoisted(() => ({
-    getSigningAuthorityForDid: vi.fn(async () => ({ seed: 'shared-seed' })),
+    getSigningAuthorityForDid: vi.fn(),
     initLearnCard: vi.fn(async (options: { didWeb?: string }) => ({
         did: options.didWeb ?? 'did:key:cached-test',
     })),
@@ -18,9 +18,19 @@ vi.mock('@learncard/didkit-plugin-node', () => ({
 }));
 
 import { getSigningAuthorityLearnCard } from './learnCard.helpers';
+import { seedEncryption } from './seedEncryption.helpers';
 
 describe('getSigningAuthorityLearnCard', () => {
     it('isolates cached wallets by owner DID when authorities share a seed', async () => {
+        const authorities = await Promise.all(
+            ['did:key:z6MkOwner', 'did:web:example.com:owner'].map(async ownerDid => {
+                const identity = { _id: ownerDid, ownerDid, name: 'shared-authority' };
+                return { ...identity, ...(await seedEncryption.encrypt('a'.repeat(64), identity)) };
+            })
+        );
+        mocks.getSigningAuthorityForDid.mockImplementation(async ownerDid =>
+            authorities.find(authority => authority.ownerDid === ownerDid)
+        );
         const didKeyWallet = await getSigningAuthorityLearnCard(
             'did:key:z6MkOwner',
             'shared-authority'

package/src/helpers/learnCard.helpers.ts

@@ -8,6 +8,11 @@ import type { EmptyLearnCard, LearnCardFromSeed, DidWebLearnCardFromSeed } from
 
 import { getSigningAuthorityForDid } from '@accesslayer/signing-authority/read';
 import { getLRUCache } from '@cache/in-memory-lru';
+import {
+    decryptSigningAuthoritySeed,
+    getSeedCacheFingerprint,
+    logSeedEncryptionFailure,
+} from '@helpers/seedEncryption.helpers';
 
 const cloud = environment.LEARN_CLOUD_URL
     ? { url: environment.LEARN_CLOUD_URL }
@@ -16,11 +21,11 @@ const cloud = environment.LEARN_CLOUD_URL
 let emptyLearnCard: EmptyLearnCard['returnValue'];
 let learnCard: LearnCardFromSeed['returnValue'];
 
-const saCardsCache = getLRUCache<
-    LearnCardFromSeed['returnValue'] | DidWebLearnCardFromSeed['returnValue']
->();
+const saCardsCache = getLRUCache<{
+    fingerprint: string;
+    card: LearnCardFromSeed['returnValue'] | DidWebLearnCardFromSeed['returnValue'];
+}>();
 const didWebCardsCache = getLRUCache<DidWebLearnCardFromSeed['returnValue']>();
-const ephemeralCardsCache = getLRUCache<LearnCardFromSeed['returnValue']>();
 
 // The DIDKit WASM is copied next to the compiled handler at build time (see
 // esbuildPlugins.cjs). The Lambda bundle's node_modules layout doesn't match what
@@ -116,22 +121,20 @@ export const getSigningAuthorityLearnCard = async (
 
     const sa = await getSigningAuthorityForDid(ownerDID, name);
 
-    if (!sa?.seed) {
-        console.error('[LCA getSigningAuthorityLearnCard] SA not found or has no seed:', {
-            ownerDID,
-            name,
-            saFound: !!sa,
-            hasSeed: !!sa?.seed,
-        });
+    if (!sa) {
         throw new Error(`No signing authority found for ownerDID="${ownerDID}" name="${name}"`);
     }
-    const cacheKey = `${sa.seed}|${ownerDID}`;
-
-    const cachedValue = saCardsCache.get(cacheKey);
-
-    if (cachedValue) {
-        console.log('[LCA getSigningAuthorityLearnCard] Using cached SA LearnCard');
-        return cachedValue;
+    const cacheKey = `${ownerDID}|${name}`;
+    let fingerprint: string;
+    try {
+        // Validate the envelope before accepting a cache hit. The database lookup remains
+        // on the warm path so deletion/recreation or modification cannot reuse an old key.
+        fingerprint = getSeedCacheFingerprint(sa);
+        const cachedValue = saCardsCache.get(cacheKey);
+        if (cachedValue?.fingerprint === fingerprint) return cachedValue.card;
+    } catch (error) {
+        logSeedEncryptionFailure(error, 'decrypt', sa);
+        throw error;
     }
 
     console.log('[LCA getSigningAuthorityLearnCard] Initializing SA LearnCard:', {
@@ -139,24 +142,40 @@ export const getSigningAuthorityLearnCard = async (
         ownerDID,
     });
 
-    const saLearnCard = ownerDID.startsWith('did:web:')
-        ? await initLearnCard({
-              didkit: await getDidKitInit(),
-              seed: sa.seed,
-              didWeb: ownerDID,
-              cloud,
-              allowRemoteContexts: true,
-          })
-        : await initLearnCard({
-              didkit: await getDidKitInit(),
-              seed: sa.seed,
-              cloud,
-              allowRemoteContexts: true,
-          });
-
-    saCardsCache.add(cacheKey, saLearnCard);
-
-    return saLearnCard;
+    // Finish engine setup before decrypting so the seed is only materialized when
+    // the signer is ready to initialize.
+    const options: LearnCardFromSeed['args'] | DidWebLearnCardFromSeed['args'] = {
+        didkit: await getDidKitInit(),
+        seed: '',
+        cloud,
+        allowRemoteContexts: true,
+        ...(ownerDID.startsWith('did:web:') ? { didWeb: ownerDID } : {}),
+    };
+
+    try {
+        try {
+            options.seed = await decryptSigningAuthoritySeed(sa);
+        } catch (error) {
+            logSeedEncryptionFailure(error, 'decrypt', sa);
+            throw error;
+        }
+
+        // Select the seed initializer overload without copying the seed-bearing options.
+        const initialize: (
+            config: LearnCardFromSeed['args'] | DidWebLearnCardFromSeed['args']
+        ) => Promise<LearnCardFromSeed['returnValue'] | DidWebLearnCardFromSeed['returnValue']> =
+            initLearnCard;
+        const saLearnCard = await initialize(options);
+        saCardsCache.add(cacheKey, { fingerprint, card: saLearnCard });
+
+        return saLearnCard;
+    } finally {
+        // Release this transient reference on both success and failure. This is
+        // not zeroization: initLearnCard requires an immutable string, and its
+        // DID Key plugin retains the seed/private keys for the cached signer's
+        // lifetime. Envelope encryption protects storage, not process memory.
+        options.seed = '';
+    }
 };
 
 export const getServerDidWebDID = (): string => {
@@ -196,17 +215,10 @@ export const getDidWebLearnCard = async (
 export const getEphemeralLearnCard = async (
     seed: string
 ): Promise<LearnCardFromSeed['returnValue']> => {
-    const cachedValue = ephemeralCardsCache.get(seed);
-
-    if (cachedValue) return cachedValue;
-
-    const ephemeralLearnCard = await initLearnCard({
+    // Creation is a one-shot operation; do not retain its seed in a cache key.
+    return initLearnCard({
         didkit: await getDidKitInit(),
         seed,
         cloud,
     });
-
-    ephemeralCardsCache.add(seed, ephemeralLearnCard);
-
-    return ephemeralLearnCard;
 };

package/src/helpers/learnCard.signingAuthority.test.ts

@@ -0,0 +1,194 @@
+import { KMSClient, GenerateDataKeyCommand } from '@aws-sdk/client-kms';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => ({
+    read: vi.fn(),
+    init: vi.fn(),
+    nativeInit: vi.fn(async () => ({})),
+    keys: [] as string[],
+}));
+vi.mock('@accesslayer/signing-authority/read', () => ({ getSigningAuthorityForDid: mocks.read }));
+vi.mock('@learncard/init', () => ({ initLearnCard: mocks.init }));
+vi.mock('@learncard/didkit-plugin-node', () => ({ getDidKitPlugin: mocks.nativeInit }));
+vi.mock('@cache/in-memory-lru', async importOriginal => {
+    const actual = await importOriginal<typeof import('@cache/in-memory-lru')>();
+    return {
+        getLRUCache: <T>() => {
+            const cache = actual.getLRUCache<T>();
+            return {
+                ...cache,
+                add: (key: string, value: T) => {
+                    mocks.keys.push(key);
+                    return cache.add(key, value);
+                },
+            };
+        },
+    };
+});
+vi.mock('@environment', async importOriginal => {
+    const actual = await importOriginal<typeof import('@environment')>();
+    return {
+        environment: {
+            ...actual.environment,
+            SKIP_DIDKIT_NAPI: false,
+            SA_SEED_KMS_KEY_ARN:
+                'arn:aws:kms:us-east-1:123456789012:key/11111111-1111-1111-1111-111111111111',
+        },
+    };
+});
+
+import { environment } from '@environment';
+import { seedEncryption } from './seedEncryption.helpers';
+import { getEphemeralLearnCard, getSigningAuthorityLearnCard } from './learnCard.helpers';
+
+const spyOnKms = () => vi.spyOn(KMSClient.prototype, 'send');
+let send: ReturnType<typeof spyOnKms>;
+beforeEach(() => {
+    vi.restoreAllMocks();
+    mocks.read.mockReset();
+    mocks.init.mockReset().mockImplementation(async options => ({ options }));
+    mocks.keys.length = 0;
+    send = vi.spyOn(KMSClient.prototype, 'send').mockImplementation(async command => ({
+        Plaintext: Buffer.alloc(32, 7),
+        KeyId: environment.SA_SEED_KMS_KEY_ARN,
+        ...(command instanceof GenerateDataKeyCommand
+            ? { CiphertextBlob: Buffer.from('wrapped') }
+            : {}),
+        $metadata: {},
+    }));
+    vi.spyOn(console, 'error').mockImplementation(() => undefined);
+});
+
+const authority = async (id: string, ownerDid = 'did:example:owner', seed = 'a'.repeat(64)) => {
+    const identity = { _id: id, ownerDid, name: 'main', did: 'did:key:example' };
+    return { ...identity, ...(await seedEncryption.encrypt(seed, identity)) };
+};
+
+describe('SA signing cache', () => {
+    it('waits for engine setup before decrypting the seed', async () => {
+        const sa = await authority('engine-setup', 'did:example:engine-setup');
+        mocks.read.mockResolvedValue(sa);
+        let finishEngineSetup!: () => void;
+        mocks.nativeInit.mockImplementationOnce(
+            () =>
+                new Promise(resolve => {
+                    finishEngineSetup = () => resolve({});
+                })
+        );
+        send.mockClear();
+
+        const initialization = getSigningAuthorityLearnCard(sa.ownerDid, sa.name);
+        await vi.waitFor(() => expect(finishEngineSetup).toBeTypeOf('function'));
+        expect(send).not.toHaveBeenCalled();
+        expect(mocks.init).not.toHaveBeenCalled();
+
+        finishEngineSetup();
+        await initialization;
+        expect(send).toHaveBeenCalledTimes(1);
+    });
+
+    it.each(['did:example:seed-lifetime', 'did:web:seed-lifetime.example'])(
+        'releases initialization options after success for %s',
+        async ownerDid => {
+            const seed = 'c'.repeat(64);
+            const sa = await authority(ownerDid, ownerDid, seed);
+            mocks.read.mockResolvedValue(sa);
+            let finishInitialization!: () => void;
+            let initializationOptions: { seed: string; didWeb?: string } | undefined;
+            const card = {};
+            mocks.init.mockImplementationOnce(options => {
+                initializationOptions = options;
+                return new Promise(resolve => {
+                    finishInitialization = () => resolve(card);
+                });
+            });
+
+            const initialization = getSigningAuthorityLearnCard(sa.ownerDid, sa.name);
+            await vi.waitFor(() => expect(initializationOptions?.seed).toBe(seed));
+            expect(initializationOptions?.didWeb).toBe(
+                ownerDid.startsWith('did:web:') ? ownerDid : undefined
+            );
+            expect(mocks.keys).toEqual([]);
+
+            finishInitialization();
+            expect(await initialization).toBe(card);
+            expect(initializationOptions?.seed).toBe('');
+            expect(await getSigningAuthorityLearnCard(sa.ownerDid, sa.name)).toBe(card);
+            expect(mocks.init).toHaveBeenCalledTimes(1);
+        }
+    );
+
+    it('releases initialization options after failure and does not cache a failed signer', async () => {
+        const sa = await authority('init-failure', 'did:example:init-failure');
+        mocks.read.mockResolvedValue(sa);
+        let initializationOptions: { seed: string } | undefined;
+        const failure = new Error('Signer initialization failed');
+        mocks.init.mockImplementationOnce(async options => {
+            initializationOptions = options;
+            expect(options.seed).toBe('a'.repeat(64));
+            throw failure;
+        });
+
+        await expect(getSigningAuthorityLearnCard(sa.ownerDid, sa.name)).rejects.toBe(failure);
+        expect(initializationOptions?.seed).toBe('');
+        expect(mocks.keys).toEqual([]);
+
+        await getSigningAuthorityLearnCard(sa.ownerDid, sa.name);
+        expect(mocks.init).toHaveBeenCalledTimes(2);
+    });
+
+    it('makes one KMS call when cold and zero when warm, retaining no seed in cache keys', async () => {
+        const sa = await authority('warm');
+        mocks.read.mockResolvedValue(sa);
+        send.mockClear();
+        const first = await getSigningAuthorityLearnCard(sa.ownerDid, sa.name);
+        expect(send).toHaveBeenCalledTimes(1);
+        expect(await getSigningAuthorityLearnCard(sa.ownerDid, sa.name)).toBe(first);
+        expect(send).toHaveBeenCalledTimes(1);
+        expect(mocks.read).toHaveBeenCalledTimes(2);
+        expect(mocks.keys).toEqual([`${sa.ownerDid}|${sa.name}`]);
+        await getEphemeralLearnCard('b'.repeat(64));
+        expect(mocks.keys).toEqual([`${sa.ownerDid}|${sa.name}`]);
+    });
+
+    it('does not reuse a deleted/recreated authority under the same owner and name', async () => {
+        const firstRecord = await authority('old');
+        const replacement = await authority('replacement', firstRecord.ownerDid, 'b'.repeat(64));
+        mocks.read
+            .mockResolvedValueOnce(firstRecord)
+            .mockResolvedValueOnce(null)
+            .mockResolvedValueOnce(replacement);
+        send.mockClear();
+        const first = await getSigningAuthorityLearnCard(firstRecord.ownerDid, firstRecord.name);
+        await expect(
+            getSigningAuthorityLearnCard(firstRecord.ownerDid, firstRecord.name)
+        ).rejects.toThrow();
+        const second = await getSigningAuthorityLearnCard(replacement.ownerDid, replacement.name);
+        expect(first).not.toBe(second);
+        expect(send).toHaveBeenCalledTimes(2);
+    });
+
+    it('does not serve a warm wallet after its envelope is tampered with', async () => {
+        const sa = await authority('tamper');
+        mocks.read.mockResolvedValue(sa);
+        await getSigningAuthorityLearnCard(sa.ownerDid, sa.name);
+        const bytes = Buffer.from(sa.encryptedSeed, 'base64');
+        bytes[15] = bytes[15]! ^ 1;
+        mocks.read.mockResolvedValue({ ...sa, encryptedSeed: bytes.toString('base64') });
+        await expect(getSigningAuthorityLearnCard(sa.ownerDid, sa.name)).rejects.toMatchObject({
+            category: 'authentication_failed',
+        });
+    });
+
+    it('keeps did:web initialization behavior and does not cache failed decrypts', async () => {
+        const sa = await authority('did-web', 'did:web:issuer.example');
+        mocks.read.mockResolvedValue(sa);
+        send.mockRejectedValueOnce({ name: 'AccessDeniedException' });
+        await expect(getSigningAuthorityLearnCard(sa.ownerDid, sa.name)).rejects.toThrow();
+        expect(mocks.keys).toEqual([]);
+        await getSigningAuthorityLearnCard(sa.ownerDid, sa.name);
+        expect(mocks.init).toHaveBeenLastCalledWith(
+            expect.objectContaining({ didWeb: sa.ownerDid })
+        );
+    });
+});

package/src/helpers/rateLimit.helpers.ts

@@ -0,0 +1,112 @@
+/**
+ * Rate Limiting Helpers
+ *
+ * Shared utilities for rate limiting across routes. Uses atomic Redis
+ * operations to prevent TOCTOU races.
+ */
+
+import cache from '@cache';
+
+/** Default Redis key prefix for rate limit counters */
+const DEFAULT_RATE_PREFIX = 'rate-limit:';
+
+/**
+ * Lua script for atomic increment with fixed-window TTL.
+ * Only sets EXPIRE on first increment OR when TTL is missing/expired.
+ * This prevents a sliding window where blocked clients keep retrying
+ * and re-arming their own TTL indefinitely.
+ */
+const ATOMIC_INCR_SCRIPT = `
+local current = redis.call('INCR', KEYS[1])
+if current == 1 or redis.call('TTL', KEYS[1]) < 0 then
+    redis.call('EXPIRE', KEYS[1], ARGV[1])
+end
+return current
+`;
+
+/**
+ * Check and increment a rate-limit counter in Redis.
+ * Returns true if the request is allowed, false if rate-limited.
+ *
+ * Uses an atomic Lua script to increment and set TTL in a single operation,
+ * preventing the race condition where a crash between INCR and EXPIRE
+ * could leave a key with no expiry, permanently blocking users.
+ *
+ * @param key - Unique key identifying the resource being rate-limited (e.g., `login-verify:user@example.com`)
+ * @param maxAttempts - Maximum number of attempts allowed within the window
+ * @param windowSeconds - Duration of the rate-limit window in seconds
+ * @param prefix - Optional key prefix (defaults to 'rate-limit:')
+ * @returns true if the request is allowed, false if rate-limited
+ */
+export const checkRateLimit = async (
+    key: string,
+    maxAttempts: number,
+    windowSeconds: number,
+    prefix: string = DEFAULT_RATE_PREFIX
+): Promise<boolean> => {
+    const fullKey = `${prefix}${key}`;
+    const redis = cache.redis ?? cache.node;
+
+    // Use Lua script for atomic INCR + EXPIRE
+    const current = (await redis.eval(
+        ATOMIC_INCR_SCRIPT,
+        1,
+        fullKey,
+        windowSeconds.toString()
+    )) as number;
+
+    if (current > maxAttempts) return false;
+
+    return true;
+};
+
+/**
+ * Get the current count for a rate-limit key without incrementing.
+ *
+ * @param key - The rate-limit key
+ * @param prefix - Optional key prefix (defaults to 'rate-limit:')
+ * @returns Current count, or 0 if key doesn't exist
+ */
+export const getRateLimitCount = async (
+    key: string,
+    prefix: string = DEFAULT_RATE_PREFIX
+): Promise<number> => {
+    const fullKey = `${prefix}${key}`;
+    const redis = cache.redis ?? cache.node;
+    const count = await redis.get(fullKey);
+    return count ? parseInt(count, 10) : 0;
+};
+
+/**
+ * Clear a rate-limit counter (e.g., after successful authentication).
+ *
+ * @param key - The rate-limit key to clear
+ * @param prefix - Optional key prefix (defaults to 'rate-limit:')
+ */
+export const clearRateLimit = async (
+    key: string,
+    prefix: string = DEFAULT_RATE_PREFIX
+): Promise<void> => {
+    const fullKey = `${prefix}${key}`;
+    const redis = cache.redis ?? cache.node;
+    await redis.del(fullKey);
+};
+
+/**
+ * Decrement a rate-limit counter (e.g., on successful login to not penalize legit users).
+ * Unlike clearRateLimit, this preserves the counter for abuse detection while
+ * ensuring legitimate successes don't accumulate toward the limit.
+ *
+ * @param key - The rate-limit key to decrement
+ * @param prefix - Optional key prefix (defaults to 'rate-limit:')
+ */
+export const decrementRateLimit = async (
+    key: string,
+    prefix: string = DEFAULT_RATE_PREFIX
+): Promise<void> => {
+    const fullKey = `${prefix}${key}`;
+    const redis = cache.redis ?? cache.node;
+    // DECR returns -1 if key doesn't exist, but we don't care about the result
+    // The key will naturally expire via its TTL
+    await redis.decr(fullKey);
+};