@learncard/lca-api-service 1.3.2 → 1.4.0

package/src/routes/qr-login.ts

@@ -20,8 +20,9 @@ import crypto from 'crypto';
 
 import { t, openRoute } from '@routes';
 import cache from '@cache';
-import { verifyAuthToken, getContactMethodFromUser, AuthProviderType } from '@helpers/auth.helpers';
-import { findUserKeyByContactMethod } from '@models';
+import { verifyAuthToken, AuthProviderType } from '@helpers/auth.helpers';
+import { findUserKeyByAuthProvider } from '@models';
+import { checkRateLimit } from '@helpers/rateLimit.helpers';
 import { sendPushNotification } from '@helpers/pushNotifications.helpers';
 
 // ---------------------------------------------------------------------------
@@ -40,47 +41,18 @@ const CODE_PREFIX = 'qr-login:code:';
 const RATE_PREFIX = 'qr-login:rate:';
 
 /** Rate limiting */
-const CREATE_RATE_LIMIT = 10;       // max session creations per window
-const CREATE_RATE_WINDOW = 600;     // 10-minute window (seconds)
-const LOOKUP_RATE_LIMIT = 20;       // max lookups per window
-const LOOKUP_RATE_WINDOW = 60;      // 1-minute window (seconds)
-const APPROVE_RATE_LIMIT = 5;       // max approve attempts per session
-const NOTIFY_RATE_LIMIT = 3;        // max notify calls per window
-const NOTIFY_RATE_WINDOW = 300;     // 5-minute window (seconds)
+const CREATE_RATE_LIMIT = 10; // max session creations per window
+const CREATE_RATE_WINDOW = 600; // 10-minute window (seconds)
+const LOOKUP_RATE_LIMIT = 20; // max lookups per window
+const LOOKUP_RATE_WINDOW = 60; // 1-minute window (seconds)
+const APPROVE_RATE_LIMIT = 5; // max approve attempts per session
+const NOTIFY_RATE_LIMIT = 3; // max notify calls per window
+const NOTIFY_RATE_WINDOW = 300; // 5-minute window (seconds)
 
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
-/**
- * Check and increment a rate-limit counter in Redis.
- * Returns true if the request is allowed, false if rate-limited.
- *
- * Uses atomic INCR + EXPIRE to avoid TOCTOU races where two concurrent
- * requests could both read the same counter value and both pass.
- */
-const checkRateLimit = async (
-    key: string,
-    maxAttempts: number,
-    windowSeconds: number
-): Promise<boolean> => {
-    const fullKey = `${RATE_PREFIX}${key}`;
-    const redis = cache.redis ?? cache.node;
-
-    // INCR is atomic — returns the new value after incrementing.
-    // If the key doesn't exist, Redis creates it with value 1.
-    const current = await redis.incr(fullKey);
-
-    // First request for this window — set the TTL
-    if (current === 1) {
-        await redis.expire(fullKey, windowSeconds);
-    }
-
-    if (current > maxAttempts) return false;
-
-    return true;
-};
-
 const generateSessionId = (): string => crypto.randomUUID();
 
 const generateShortCode = (): string => {
@@ -149,7 +121,14 @@ export const qrLoginRouter = t.router({
             // Rate limit by IP — max 10 sessions per 10 minutes
             const clientIp = ctx.clientIp ?? 'unknown';
 
-            if (!(await checkRateLimit(`create:${clientIp}`, CREATE_RATE_LIMIT, CREATE_RATE_WINDOW))) {
+            if (
+                !(await checkRateLimit(
+                    `create:${clientIp}`,
+                    CREATE_RATE_LIMIT,
+                    CREATE_RATE_WINDOW,
+                    RATE_PREFIX
+                ))
+            ) {
                 throw new Error('Too many session requests. Please try again later.');
             }
 
@@ -215,7 +194,14 @@ export const qrLoginRouter = t.router({
             if (/^\d{8}$/.test(input.lookup)) {
                 const clientIp = ctx.clientIp ?? 'unknown';
 
-                if (!(await checkRateLimit(`lookup:${clientIp}`, LOOKUP_RATE_LIMIT, LOOKUP_RATE_WINDOW))) {
+                if (
+                    !(await checkRateLimit(
+                        `lookup:${clientIp}`,
+                        LOOKUP_RATE_LIMIT,
+                        LOOKUP_RATE_WINDOW,
+                        RATE_PREFIX
+                    ))
+                ) {
                     throw new Error('Too many lookup attempts. Please try again later.');
                 }
             }
@@ -281,7 +267,14 @@ export const qrLoginRouter = t.router({
         .output(z.object({ success: z.boolean() }))
         .mutation(async ({ input, ctx: _ctx }) => {
             // Rate limit approve attempts per session to prevent brute-force
-            if (!(await checkRateLimit(`approve:${input.sessionId}`, APPROVE_RATE_LIMIT, SESSION_TTL_SECONDS))) {
+            if (
+                !(await checkRateLimit(
+                    `approve:${input.sessionId}`,
+                    APPROVE_RATE_LIMIT,
+                    SESSION_TTL_SECONDS,
+                    RATE_PREFIX
+                ))
+            ) {
                 throw new Error('Too many approve attempts for this session.');
             }
 
@@ -326,7 +319,7 @@ export const qrLoginRouter = t.router({
                 method: 'POST',
                 path: '/qr-login/notify',
                 tags: ['QR Login'],
-                summary: 'Send a device link push notification to the user\'s other devices',
+                summary: "Send a device link push notification to the user's other devices",
             },
         })
         .input(
@@ -347,21 +340,26 @@ export const qrLoginRouter = t.router({
         .output(z.object({ sent: z.boolean(), deviceCount: z.number() }))
         .mutation(async ({ input, ctx: _ctx }) => {
             // Rate limit notify calls per session
-            if (!(await checkRateLimit(`notify:${input.sessionId}`, NOTIFY_RATE_LIMIT, NOTIFY_RATE_WINDOW))) {
+            if (
+                !(await checkRateLimit(
+                    `notify:${input.sessionId}`,
+                    NOTIFY_RATE_LIMIT,
+                    NOTIFY_RATE_WINDOW,
+                    RATE_PREFIX
+                ))
+            ) {
                 return { sent: false, deviceCount: 0 };
             }
 
             // Verify the auth token and get the user
-            const user = await verifyAuthToken(input.authToken, input.providerType as AuthProviderType);
-
-            const contactMethod = getContactMethodFromUser(user);
-
-            if (!contactMethod) {
-                throw new Error('User must have an email or phone number');
-            }
-
-            // Look up the user's DID from their key record
-            const userKey = await findUserKeyByContactMethod(contactMethod);
+            const user = await verifyAuthToken(
+                input.authToken,
+                input.providerType as AuthProviderType
+            );
+
+            // Provider identity is immutable; a recycled contact method must
+            // never receive notifications for a previous owner's DID.
+            const userKey = await findUserKeyByAuthProvider(input.providerType, user.id);
 
             if (!userKey?.primaryDid) {
                 return { sent: false, deviceCount: 0 };

package/src/services/delivery/adapters/postmark.adapter.ts

@@ -34,6 +34,7 @@ const LOCAL_TEMPLATE_ALIASES: Record<string, TemplateId> = {
     'guardian-approval': 'guardian-approval',
     'account-approved': 'account-approved',
     'contact-method-verification': 'contact-method-verification',
+    'account-sign-in-changed': 'account-sign-in-changed',
 };
 
 /** Whether the given alias is a sentinel we registered (vs. a real Postmark alias). */
@@ -166,9 +167,13 @@ export class PostmarkAdapter implements DeliveryService {
                     recipient: model.recipient as { name?: string } | undefined,
                 };
 
+            case 'account-sign-in-changed':
+                return {};
+
             case 'recovery-key':
                 return {
                     recoveryKey: (model.recoveryKey as string) ?? '',
+                    confirmationCode: (model.confirmationCode as string) ?? '',
                 };
 
             case 'endorsement-request':

package/src/services/escrow-enclave/README.md

@@ -0,0 +1,51 @@
+# Escrow release policies
+
+The same sealed recovery material supports a delayed `hold` policy and an optional
+immediate `pin` policy. PIN verification and release are a single enclave operation;
+a PIN hold cannot release without a matching proof, even after its release time.
+The verifier is never stored in plaintext in MongoDB, logged, or included in the
+release payload. A leaked database alone does not expose an offline PIN oracle.
+
+## Software-mode trust boundary
+
+The software enclave runs in the host process: the host already controls its keys,
+clock, and execution. A host-owned MongoDB attempt counter does not weaken that
+existing host-trusted model, but does not protect against a malicious host either.
+The API atomically reserves one of ten lifetime attempts before claiming the hold
+and calling the enclave. Failed releases burn the single-use hold. Exhaustion
+disables PIN recovery and cancels pending PIN holds; delayed recovery remains
+available. Successful PIN recovery does not replenish the lifetime budget; authenticated enrollment
+with a new PIN starts a fresh counter. Setting or changing a PIN requires client share
+rotation. Inbox compromise plus a correct PIN guess can recover the account
+(at most 10/1,000,000 for a uniformly random six-digit PIN).
+
+## Nitro requirement
+
+The real Nitro enclave application lives on a separate branch and **must implement
+`carryPinVerifier`** with the same contract before PIN carry is available there:
+
+```ts
+carryPinVerifier({ sourceEnvelope, targetEnvelope, expectedDid,
+    sourceShareVersion, targetShareVersion }): Promise<{ envelope }>
+```
+
+Decrypt both envelopes inside the enclave. Require both DIDs to equal `expectedDid`,
+both versions to match their expected versions, a strictly increasing target version,
+a source PIN verifier, and no target verifier. Reject mismatches with `EscrowBlobError`
+(`Invalid escrow payload.`). Seal target plaintext plus the source verifier to the
+current enclave key with fresh ephemeral key and IV, using the existing envelope
+format. Never return or log plaintext or the verifier.
+
+Enrollment attempts carry only for PIN-less requests with an unlocked PIN matching
+the previous blob's version and current enclave key. Persistence compares the complete
+old `escrowBlob` and `escrowPin` subdocuments, auth-provider identity, current share
+version, and absent opt-out marker atomically. This guards salt, counters, lock state,
+and ciphertext against concurrent changes. Carry preserves salt, enabledAt and both
+attempt counters, changing only the PIN share version. Unavailable/failed carry or a
+lost compare-and-swap falls back to normal PIN-less enrollment with a secret-free warning.
+Explicit new PIN enrollment is unchanged; explicit removal sends `clearPin: true`
+to bypass carry (it cannot be combined with `pinSalt`).
+
+TODO(escrow-nitro): Move the counter into enclave-internal, replicated state with
+decrement-before-decrypt semantics and rollback protection. Do not reuse the
+host-owned counter as the security boundary for a Nitro implementation.

package/src/services/escrow-enclave/index.ts

@@ -0,0 +1,36 @@
+import {
+    environment,
+    parseLcaApiEnvironment,
+    parseEscrowPrivateKeys,
+    type LcaApiEnvironment,
+} from '@environment';
+import { SoftwareEnclave } from './softwareEnclave';
+import { EscrowUnavailableError, type EscrowEnclave } from './types';
+
+export * from './types';
+export * from './softwareEnclave';
+export * from './notifications';
+
+let enclave: EscrowEnclave | undefined;
+let config: LcaApiEnvironment = environment;
+
+export const isEscrowEnabled = (): boolean => Boolean(config.ESCROW_ENCLAVE_MODE);
+export const getEscrowHoldDurationMs = (): number => config.ESCROW_HOLD_DURATION_MS;
+export const getEscrowHoldRestartMinAgeMs = (): number => config.ESCROW_HOLD_RESTART_MIN_AGE_MS;
+export const getEscrowEnclave = (): EscrowEnclave => {
+    if (!isEscrowEnabled()) throw new EscrowUnavailableError();
+    if (enclave) return enclave;
+    if (config.ESCROW_ENCLAVE_MODE !== 'software') throw new EscrowUnavailableError();
+    enclave = new SoftwareEnclave({
+        privateKeys: parseEscrowPrivateKeys(config.ESCROW_ENCLAVE_SOFTWARE_PRIVATE_KEYS_JSON ?? ''),
+        activeKeyId: config.ESCROW_ENCLAVE_ACTIVE_KEY_ID ?? '',
+    });
+    return enclave;
+};
+
+/** Reset both singleton and environment snapshot after test environment changes. */
+export const __setEscrowEnclaveForTests = (replacement: EscrowEnclave | undefined): void => {
+    if (environment.NODE_ENV !== 'test') throw new EscrowUnavailableError();
+    config = parseLcaApiEnvironment(process.env);
+    enclave = replacement;
+};

package/src/services/escrow-enclave/notifications.ts

@@ -0,0 +1,14 @@
+import type { EscrowHold } from '../../models/EscrowHold';
+import type { MongoUserKeyType } from '../../models/UserKey';
+
+export interface EscrowHoldEvent {
+    kind: 'started' | 'cancelled' | 'completed';
+    hold: EscrowHold;
+    userKey: MongoUserKeyType;
+    reason?: 'superseded';
+}
+
+/** Placeholder for notification fan-out. Never log the supplied account or hold. */
+export const notifyEscrowHoldEvent = async (event: EscrowHoldEvent): Promise<void> => {
+    console.info('[Escrow hold notification]', { kind: event.kind, reason: event.reason });
+};

package/src/services/escrow-enclave/softwareEnclave.test.ts

@@ -0,0 +1,249 @@
+import { describe, it, expect } from 'vitest';
+import {
+    encryptEscrowBlob,
+    generateEscrowKeyPair,
+    openEscrowRelease,
+} from '@learncard/sss-key-manager';
+import { SoftwareEnclave } from './softwareEnclave';
+import {
+    EscrowBlobError,
+    EscrowPolicyError,
+    EscrowPinMismatchError,
+    type EscrowHoldForEnclave,
+} from './types';
+
+describe('software enclave', () => {
+    it.each([
+        'success',
+        'source DID',
+        'target DID',
+        'expected DID',
+        'equal version',
+        'lower version',
+        'source version',
+        'target version',
+        'missing PIN',
+        'target PIN',
+    ])('carries the sealed verifier with strict binding: %s', async scenario => {
+        const keys = await generateEscrowKeyPair();
+        const client = await generateEscrowKeyPair();
+        const enclave = new SoftwareEnclave({
+            privateKeys: { test: keys.privateKey },
+            activeKeyId: 'test',
+        });
+        const did = 'did:key:test';
+        const pinVerifier = 'ab'.repeat(32);
+        const targetVersion =
+            scenario === 'equal version' ? 2 : scenario === 'lower version' ? 1 : 3;
+        const sourceEnvelope = await encryptEscrowBlob(
+            {
+                recoveryShare: 'ab'.repeat(33),
+                did: scenario === 'source DID' ? 'did:key:other' : did,
+                shareVersion: 2,
+                ...(scenario === 'missing PIN' ? {} : { pinVerifier }),
+            },
+            keys.publicKey,
+            'test'
+        );
+        const target = {
+            recoveryShare: 'cd'.repeat(33),
+            did: scenario === 'target DID' ? 'did:key:other' : did,
+            shareVersion: targetVersion,
+            ...(scenario === 'target PIN' ? { pinVerifier } : {}),
+        };
+        const targetEnvelope = await encryptEscrowBlob(target, keys.publicKey, 'test');
+        const result = enclave.carryPinVerifier({
+            sourceEnvelope,
+            targetEnvelope,
+            expectedDid: scenario === 'expected DID' ? 'did:key:other' : did,
+            sourceShareVersion: scenario === 'source version' ? 1 : 2,
+            targetShareVersion: scenario === 'target version' ? 4 : targetVersion,
+        });
+        if (scenario !== 'success') {
+            await expect(result).rejects.toBeInstanceOf(EscrowBlobError);
+            return;
+        }
+        const { envelope } = await result;
+        expect(envelope.ciphertext).not.toBe(targetEnvelope.ciphertext);
+        expect(
+            await enclave.verifyEscrowBlob({ envelope, expectedDid: did, expectedShareVersion: 3 })
+        ).toEqual({ ok: true, hasPin: true });
+        const { sealed } = await enclave.releaseEscrow({
+            envelope,
+            expectedDid: did,
+            pinProof: pinVerifier,
+            clientEphemeralPublicKey: client.publicKey,
+            hold: {
+                _id: 'carry',
+                status: 'pending',
+                releasePolicy: 'pin',
+                releaseAfter: new Date(0),
+                primaryDid: did,
+                shareVersion: 3,
+                clientEphemeralPublicKey: client.publicKey,
+            },
+        });
+        expect(await openEscrowRelease(sealed, client.privateKey)).toEqual({
+            ...target,
+            version: 1,
+            holdId: 'carry',
+        });
+    });
+
+    it('derives the attestation key, verifies enrollment, and enforces release policy', async () => {
+        const keys = await generateEscrowKeyPair();
+        const client = await generateEscrowKeyPair();
+        const enclave = new SoftwareEnclave({
+            privateKeys: { test: keys.privateKey },
+            activeKeyId: 'test',
+        });
+        const attestation = await enclave.getAttestation();
+        expect(attestation.publicKey).toBe(keys.publicKey);
+        expect(JSON.parse(Buffer.from(attestation.document, 'base64').toString())).toEqual({
+            mode: 'software',
+            keyId: 'test',
+            publicKey: keys.publicKey,
+            issuedAt: attestation.issuedAt,
+        });
+        const plaintext = { recoveryShare: 'ab'.repeat(33), did: 'did:key:test', shareVersion: 1 };
+        const envelope = await encryptEscrowBlob(plaintext, attestation.publicKey, 'test');
+        expect(
+            await enclave.verifyEscrowBlob({
+                envelope,
+                expectedDid: plaintext.did,
+                expectedShareVersion: 1,
+            })
+        ).toEqual({ ok: true, hasPin: false });
+        expect(
+            await enclave.verifyEscrowBlob({
+                envelope,
+                expectedDid: 'did:key:wrong',
+                expectedShareVersion: 1,
+            })
+        ).toMatchObject({ ok: false });
+        const hold: EscrowHoldForEnclave = {
+            _id: 'test-hold',
+            primaryDid: plaintext.did,
+            shareVersion: 1,
+            status: 'pending',
+            releaseAfter: new Date(1000),
+            releasePolicy: 'hold',
+            clientEphemeralPublicKey: client.publicKey,
+        };
+        const request = {
+            envelope,
+            hold,
+            clientEphemeralPublicKey: client.publicKey,
+            expectedDid: plaintext.did,
+        };
+        await expect(
+            enclave.releaseEscrow({ ...request, now: new Date(999) })
+        ).rejects.toBeInstanceOf(EscrowPolicyError);
+        for (const changed of [
+            { status: 'cancelled' as const },
+            { shareVersion: 2 },
+            { primaryDid: 'did:key:wrong' },
+        ]) {
+            await expect(
+                enclave.releaseEscrow({
+                    ...request,
+                    hold: { ...hold, ...changed },
+                    now: new Date(1000),
+                })
+            ).rejects.toBeInstanceOf(EscrowPolicyError);
+        }
+        await expect(
+            enclave.releaseEscrow({ ...request, expectedDid: 'did:key:wrong', now: new Date(1000) })
+        ).rejects.toBeInstanceOf(EscrowPolicyError);
+        await expect(
+            enclave.releaseEscrow({
+                ...request,
+                clientEphemeralPublicKey: keys.publicKey,
+                now: new Date(1000),
+            })
+        ).rejects.toBeInstanceOf(EscrowPolicyError);
+        const released = await enclave.releaseEscrow({ ...request, now: new Date(1000) });
+        expect(await openEscrowRelease(released.sealed, client.privateKey)).toEqual({
+            ...plaintext,
+            version: 1,
+            holdId: hold._id,
+        });
+        await expect(
+            enclave.verifyEscrowBlob({
+                envelope: { ...envelope, keyId: 'unknown' },
+                expectedDid: plaintext.did,
+                expectedShareVersion: 1,
+            })
+        ).rejects.toBeInstanceOf(EscrowBlobError);
+    });
+
+    it.each([
+        { policy: 'pin' as const, verifier: true, proof: 'ab'.repeat(32), error: undefined },
+        {
+            policy: 'pin' as const,
+            verifier: true,
+            proof: 'cd'.repeat(32),
+            error: EscrowPinMismatchError,
+        },
+        { policy: 'pin' as const, verifier: true, proof: 'ab', error: EscrowPinMismatchError },
+        { policy: 'pin' as const, verifier: true, proof: undefined, error: EscrowPolicyError },
+        {
+            policy: 'pin' as const,
+            verifier: false,
+            proof: 'ab'.repeat(32),
+            error: EscrowPolicyError,
+        },
+        { policy: 'hold' as const, verifier: true, proof: 'cd'.repeat(32), error: undefined },
+    ])(
+        'checks policy/proof case %# without exposing the verifier',
+        async ({ policy, verifier, proof, error }) => {
+            const keys = await generateEscrowKeyPair();
+            const client = await generateEscrowKeyPair();
+            const enclave = new SoftwareEnclave({
+                privateKeys: { test: keys.privateKey },
+                activeKeyId: 'test',
+            });
+            const plaintext = {
+                recoveryShare: 'ab'.repeat(33),
+                did: 'did:key:test',
+                shareVersion: 1,
+            };
+            const envelope = await encryptEscrowBlob(
+                { ...plaintext, ...(verifier ? { pinVerifier: 'ab'.repeat(32) } : {}) },
+                keys.publicKey,
+                'test'
+            );
+            expect(
+                await enclave.verifyEscrowBlob({
+                    envelope,
+                    expectedDid: plaintext.did,
+                    expectedShareVersion: 1,
+                })
+            ).toEqual({ ok: true, hasPin: verifier });
+            const request = {
+                envelope,
+                expectedDid: plaintext.did,
+                clientEphemeralPublicKey: client.publicKey,
+                pinProof: proof,
+                hold: {
+                    _id: 'pin-hold',
+                    status: 'pending' as const,
+                    primaryDid: plaintext.did,
+                    shareVersion: 1,
+                    releasePolicy: policy,
+                    releaseAfter: new Date(0),
+                    clientEphemeralPublicKey: client.publicKey,
+                },
+            };
+            if (error) await expect(enclave.releaseEscrow(request)).rejects.toBeInstanceOf(error);
+            else {
+                const result = await enclave.releaseEscrow(request);
+                expect(await openEscrowRelease(result.sealed, client.privateKey)).toEqual({
+                    ...plaintext,
+                    version: 1,
+                    holdId: 'pin-hold',
+                });
+            }
+        }
+    );
+});