@learncard/lca-api-service 1.3.2 → 1.4.0

package/serverless-local.yml

@@ -38,6 +38,9 @@ provider:
     environment:
         LAMBDA_STAGE: ${opt:stage, "dev"}
         SEED: ${env:SEED}
+        SA_SEED_LOCAL_KEK: ${env:SA_SEED_LOCAL_KEK, ''}
+        SA_SEED_ENCRYPT_WRITES: ${env:SA_SEED_ENCRYPT_WRITES, 'false'}
+        SA_SEED_ALLOW_LEGACY_READ: ${env:SA_SEED_ALLOW_LEGACY_READ, 'true'}
         DOMAIN_NAME: ${env:DOMAIN_NAME}
         OPENAI_API_KEY: ${env:OPENAI_API_KEY}
         METABASE_SECRET_KEY: ${env:METABASE_SECRET_KEY}

package/serverless.escrow-env.cjs

@@ -0,0 +1,20 @@
+// Empty-string keys still count toward Lambda's 4KB env limit, so emit only set values.
+// Enclave keys are gated on ESCROW_ENCLAVE_MODE: unsetting that one variable disables
+// escrow without deleting the stored key secret.
+const RELAY_KEYS = ['ESCROW_RELAY_URL', 'ESCROW_RELAY_AUTH_TOKEN'];
+
+const ENCLAVE_KEYS = [
+    'ESCROW_ENCLAVE_MODE',
+    'ESCROW_ENCLAVE_SOFTWARE_PRIVATE_KEYS_JSON',
+    'ESCROW_ENCLAVE_ACTIVE_KEY_ID',
+    'ESCROW_HOLD_DURATION_MS',
+    'ESCROW_HOLD_RESTART_MIN_AGE_MS',
+];
+
+module.exports = () => {
+    const keys = process.env.ESCROW_ENCLAVE_MODE ? [...RELAY_KEYS, ...ENCLAVE_KEYS] : RELAY_KEYS;
+
+    return Object.fromEntries(
+        keys.filter(key => process.env[key]).map(key => [key, process.env[key]])
+    );
+};

package/serverless.yml

@@ -18,6 +18,10 @@ custom:
         number: 3
     config:
         CACHE_INSTANCE_SIZE: cache.t2.micro
+    # Lambda caps each function's environment at 4KB. Escrow config is only read
+    # by the trpc/api handlers, so it is attached per-function (not provider-wide)
+    # and unset keys are omitted entirely.
+    escrowEnvironment: ${file(./serverless.escrow-env.cjs)}
     esbuild:
         # serverless-esbuild does not support Bun as a Lambda artifact packager.
         # Bun remains the repo installer/runner; pnpm is used only for packaging externals.
@@ -132,6 +136,11 @@ provider:
     environment:
         LAMBDA_STAGE: ${opt:stage, "dev"}
         SEED: ${env:SEED, ''}
+        SA_SEED_KMS_KEY_ARN:
+            Fn::GetAtt: [SigningAuthoritySeedKey, Arn]
+        # First deployment upgrades readers only. Enable writes after every reader is compatible.
+        SA_SEED_ENCRYPT_WRITES: ${param:saSeedEncryptWrites, env:SA_SEED_ENCRYPT_WRITES, 'false'}
+        SA_SEED_ALLOW_LEGACY_READ: ${param:saSeedAllowLegacyRead, env:SA_SEED_ALLOW_LEGACY_READ, 'true'}
         DOMAIN_NAME: ${env:DOMAIN_NAME, ''}
         OPENAI_API_KEY: ${env:OPENAI_API_KEY, ''}
         METABASE_SECRET_KEY: ${env:METABASE_SECRET_KEY, ''}
@@ -167,6 +176,9 @@ provider:
 functions:
     trpc:
         handler: lambda.trpcHandler
+        role: SigningAuthorityExecutionRole
+        dependsOn: [SigningAuthoritySeedKeyPolicy]
+        environment: ${self:custom.escrowEnvironment}
         vpc:
             securityGroupIds:
                 - 'Fn::GetAtt': [ServerlessSecurityGroup, GroupId]
@@ -177,6 +189,9 @@ functions:
 
     api:
         handler: lambda.openApiHandler
+        role: SigningAuthorityExecutionRole
+        dependsOn: [SigningAuthoritySeedKeyPolicy]
+        environment: ${self:custom.escrowEnvironment}
         vpc:
             securityGroupIds:
                 - 'Fn::GetAtt': [ServerlessSecurityGroup, GroupId]
@@ -198,6 +213,19 @@ functions:
         url:
             cors: true
 
+    seedMigration:
+        handler: seedMigrationLambda.handler
+        role: SigningAuthorityExecutionRole
+        timeout: 900
+        reservedConcurrency: 1
+        dependsOn: [SigningAuthoritySeedKeyPolicy]
+        # IAM invoke only: intentionally no events, schedule, or function URL.
+        vpc:
+            securityGroupIds:
+                - Fn::GetAtt: [ServerlessSecurityGroup, GroupId]
+            subnetIds:
+                - Ref: PrivateSubnetA
+
     swagger:
         handler: lambda.swaggerUiHandler
         package:
@@ -208,7 +236,112 @@ functions:
             - httpApi: GET /docs/{trpc+}
 
 resources:
+    Outputs:
+        SigningAuthoritySeedKeyArn:
+            Value:
+                Fn::GetAtt: [SigningAuthoritySeedKey, Arn]
+        SigningAuthoritySeedMigrationFunctionName:
+            Value:
+                Ref: SeedMigrationLambdaFunction
     Resources:
+        # Only the two signing entry points and the migration worker assume this role.
+        # Keep KMS references out of the role itself to avoid a Role -> Key -> Role cycle.
+        SigningAuthorityExecutionRole:
+            Type: AWS::IAM::Role
+            Properties:
+                AssumeRolePolicyDocument:
+                    Version: '2012-10-17'
+                    Statement:
+                        - Effect: Allow
+                          Principal:
+                              Service: lambda.amazonaws.com
+                          Action: sts:AssumeRole
+                ManagedPolicyArns:
+                    - Fn::Sub: arn:${AWS::Partition}:iam::aws:policy/service-role/AWSLambdaVPCAccessExecutionRole
+                    - Fn::Sub: arn:${AWS::Partition}:iam::aws:policy/AWSXRayDaemonWriteAccess
+        SigningAuthoritySeedKey:
+            Type: AWS::KMS::Key
+            DeletionPolicy: Retain
+            UpdateReplacePolicy: Retain
+            Properties:
+                Description: Envelope encryption for hosted signing-authority seeds
+                KeySpec: SYMMETRIC_DEFAULT
+                KeyUsage: ENCRYPT_DECRYPT
+                EnableKeyRotation: true
+                PendingWindowInDays: 30
+                KeyPolicy:
+                    Version: '2012-10-17'
+                    Statement:
+                        - Sid: AccountKeyAdministration
+                          Effect: Allow
+                          Principal:
+                              AWS:
+                                  Fn::Sub: arn:${AWS::Partition}:iam::${AWS::AccountId}:root
+                          Action:
+                              - kms:DescribeKey
+                              - kms:GetKeyPolicy
+                              - kms:PutKeyPolicy
+                              - kms:ListResourceTags
+                              - kms:TagResource
+                              - kms:UntagResource
+                              - kms:GetKeyRotationStatus
+                              - kms:EnableKeyRotation
+                              - kms:DisableKeyRotation
+                              - kms:UpdateKeyDescription
+                              - kms:EnableKey
+                              - kms:DisableKey
+                              - kms:ScheduleKeyDeletion
+                              - kms:CancelKeyDeletion
+                              - kms:CreateAlias
+                              - kms:UpdateAlias
+                              - kms:DeleteAlias
+                          Resource: '*'
+                        - Sid: LcaApiSeedEncryption
+                          Effect: Allow
+                          Principal:
+                              AWS:
+                                  Fn::GetAtt: [SigningAuthorityExecutionRole, Arn]
+                          Action: [kms:GenerateDataKey, kms:Decrypt]
+                          Resource: '*'
+                          Condition:
+                              StringEquals:
+                                  kms:EncryptionContext:purpose: lca-signing-authority-seed
+                        - Sid: DenyOtherCryptographicPrincipals
+                          Effect: Deny
+                          Principal: '*'
+                          Action:
+                              [kms:Decrypt, 'kms:ReEncrypt*', 'kms:GenerateDataKey*', kms:Encrypt]
+                          Resource: '*'
+                          Condition:
+                              ArnNotEquals:
+                                  aws:PrincipalArn:
+                                      Fn::GetAtt: [SigningAuthorityExecutionRole, Arn]
+        SigningAuthoritySeedKeyAlias:
+            Type: AWS::KMS::Alias
+            Properties:
+                AliasName: alias/${self:service}-${self:provider.stage}-sa-seeds
+                TargetKeyId:
+                    Ref: SigningAuthoritySeedKey
+        # The direct execution-role grant in the KEY policy authorizes cryptographic use.
+        # This matching IAM allow is not required by that grant; it documents the scope and
+        # provides a dependsOn deployment barrier. Keeping it separate avoids a Role -> Key
+        # -> Role CloudFormation dependency cycle. Swagger/didWeb use the generated role.
+        SigningAuthoritySeedKeyPolicy:
+            Type: AWS::IAM::Policy
+            Properties:
+                PolicyName: ${self:service}-${self:provider.stage}-sa-seeds
+                Roles:
+                    - Ref: SigningAuthorityExecutionRole
+                PolicyDocument:
+                    Version: '2012-10-17'
+                    Statement:
+                        - Effect: Allow
+                          Action: [kms:GenerateDataKey, kms:Decrypt]
+                          Resource:
+                              Fn::GetAtt: [SigningAuthoritySeedKey, Arn]
+                          Condition:
+                              StringEquals:
+                                  kms:EncryptionContext:purpose: lca-signing-authority-seed
         VPC:
             Type: AWS::EC2::VPC
             Properties:

package/src/accesslayer/signing-authority/create.ts

@@ -3,6 +3,7 @@ import { getEphemeralLearnCard } from '@helpers/learnCard.helpers';
 import { SigningAuthorities } from '.';
 import crypto from 'node:crypto';
 import { v4 as uuidv4 } from 'uuid';
+import { logSeedEncryptionFailure, seedEncryption } from '@helpers/seedEncryption.helpers';
 
 export const createSigningAuthorityForDID = async (
     ownerDid: string,
@@ -10,19 +11,22 @@ export const createSigningAuthorityForDID = async (
 ): Promise<string | false> => {
     const seed =
         environment.NODE_ENV === 'test' ? 'e'.repeat(64) : crypto.randomBytes(32).toString('hex');
-    const did = (await getEphemeralLearnCard(seed)).id.did();
+    const _id = uuidv4();
     try {
+        const did = (await getEphemeralLearnCard(seed)).id.did();
+        const identity = { _id, ownerDid, did, name };
+        // Plaintext writes support the compatibility deployment and offline opt-in defaults.
+        const secret = environment.SA_SEED_ENCRYPT_WRITES
+            ? await seedEncryption.encrypt(seed, identity)
+            : { seed };
         return (
             await SigningAuthorities.insertOne({
-                _id: uuidv4(),
-                ownerDid,
-                did,
-                name,
-                seed,
+                ...identity,
+                ...secret,
             })
         ).insertedId;
     } catch (e) {
-        console.error(e);
+        logSeedEncryptionFailure(e, 'create', { _id });
         return false;
     }
 };

package/src/app.ts

@@ -10,6 +10,7 @@ import { analyticsRouter } from '@routes/analytics';
 export { createContext } from '@routes';
 import { preferencesRouter } from '@routes/preferences';
 import { keysRouter } from '@routes/keys';
+import { escrowRouter } from '@routes/escrow';
 import { qrLoginRouter } from '@routes/qr-login';
 import { testRouter, type TestRouter } from '@routes/test';
 import { environment } from '@environment';
@@ -25,6 +26,7 @@ const routes = {
     analytics: analyticsRouter,
     preferences: preferencesRouter,
     keys: keysRouter,
+    escrow: escrowRouter,
     qrLogin: qrLoginRouter,
 };
 

package/src/cache/challenges.ts

@@ -4,6 +4,7 @@ export const getChallengeCacheKey = (did: string, challenge: string): string =>
     `challenge|${did}|${challenge}`;
 
 export const VALID = 'valid';
+export const DID_CHALLENGE_TTL_SECS = 5 * 60;
 
 export const isChallengeValidForDid = async (
     did: string,
@@ -14,8 +15,17 @@ export const isChallengeValidForDid = async (
     return result === VALID ? result : undefined;
 };
 
+/** Atomically validate and consume a challenge so concurrent replays cannot both succeed. */
+export const consumeChallengeForDid = async (did: string, challenge: string): Promise<boolean> => {
+    const key = getChallengeCacheKey(did, challenge);
+    const redis = cache.redis ?? cache.node;
+    const value = await redis.getdel(key);
+
+    return value === VALID;
+};
+
 export const setValidChallengeForDid = async (did: string, challenge: string) => {
-    return cache.set(getChallengeCacheKey(did, challenge), VALID);
+    return cache.set(getChallengeCacheKey(did, challenge), VALID, DID_CHALLENGE_TTL_SECS);
 };
 
 export const setValidChallengesForDid = async (did: string, challenges: string[]) => {
@@ -25,7 +35,7 @@ export const setValidChallengesForDid = async (did: string, challenges: string[]
         return acc;
     }, {});
 
-    return cache.mset(values);
+    return cache.mset(values, DID_CHALLENGE_TTL_SECS);
 };
 
 export const invalidateChallengeForDid = async (did: string, challenge: string) => {

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/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/environment.test.ts

@@ -0,0 +1,116 @@
+import { describe, expect, it } from 'vitest';
+import { parseLcaApiEnvironment } from './environment';
+
+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();
+    });
+});