@actuate-media/cms-core 0.37.0 → 0.38.0

package/dist/__tests__/api/totp-login.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=totp-login.test.d.ts.map

package/dist/__tests__/api/totp-login.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"totp-login.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/api/totp-login.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/api/totp-login.test.js

@@ -0,0 +1,115 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+import { handleActuateAPI } from '../../api/index.js';
+import { initDB } from '../../db.js';
+import { encryptSecret, encryptStringArray } from '../../security/secret-storage.js';
+import { createMfaPendingToken, computeRequestFingerprint } from '../../auth/mfa-pending.js';
+import { generateTOTPSecret } from '../../auth/totp.js';
+/**
+ * Contract test for the backup-code recovery path of POST /auth/totp/login.
+ *
+ * Backup codes are generated and shown at enrollment but, before this, were
+ * never consumed anywhere — a lost authenticator meant permanent lockout. This
+ * proves a valid code signs the user in, is single-use (consumed on success),
+ * and that an unknown code is rejected.
+ */
+const SECRET = 'a'.repeat(48);
+const ENCRYPTION_KEY = 'b'.repeat(64); // 32 bytes hex
+const BACKUP_CODES = ['aaaa1111', 'bbbb2222', 'cccc3333'];
+async function createMockDB(state) {
+    const totpSecret = await encryptSecret(generateTOTPSecret());
+    return {
+        user: {
+            findUnique: async () => ({
+                id: 'user-1',
+                email: 'admin@example.com',
+                name: 'Admin',
+                role: 'ADMIN',
+                totpSecret,
+                totpEnabled: true,
+                backupCodes: await encryptStringArray(state.backupCodes),
+                isActive: true,
+            }),
+            update: async ({ data }) => {
+                // The handler re-encrypts the remaining codes; decrypt-by-count is
+                // enough for the assertion (we only check how many remain).
+                state.backupCodes = state.backupCodes.slice(0, data.backupCodes.length);
+                return { id: 'user-1' };
+            },
+        },
+        document: {
+            findFirst: async () => ({ data: {} }),
+        },
+        session: {
+            findMany: async () => [],
+            create: async () => ({ id: 'sess-1' }),
+            updateMany: async () => ({ count: 0 }),
+        },
+        auditLog: {
+            create: async () => ({ id: 'log-1' }),
+        },
+    };
+}
+async function makePendingToken(ip, userAgent) {
+    const fingerprint = await computeRequestFingerprint(ip, userAgent);
+    return createMfaPendingToken({ userId: 'user-1', fingerprint }, SECRET);
+}
+beforeEach(() => {
+    delete globalThis.__actuateConfig;
+    process.env.CMS_SECRET = SECRET;
+    process.env.CMS_ENCRYPTION_KEY = ENCRYPTION_KEY;
+});
+describe('POST /auth/totp/login — backup code recovery', () => {
+    it('signs in with a valid backup code and consumes it (single-use)', async () => {
+        const ip = '203.0.113.10';
+        const ua = 'vitest-agent';
+        const state = { backupCodes: [...BACKUP_CODES] };
+        const db = await createMockDB(state);
+        initDB(db);
+        const handler = handleActuateAPI({ prismaClient: db, config: { collections: {} } });
+        const token = await makePendingToken(ip, ua);
+        const res = await handler(new Request('https://example.com/api/cms/auth/totp/login', {
+            method: 'POST',
+            headers: { 'x-real-ip': ip, 'user-agent': ua, 'content-type': 'application/json' },
+            body: JSON.stringify({ mfaPendingToken: token, code: 'BBBB-2222' }),
+        }));
+        expect(res.status).toBe(200);
+        expect(res.headers.get('set-cookie')).toContain('actuate_session=');
+        // The used code was removed — one fewer remains.
+        expect(state.backupCodes).toHaveLength(BACKUP_CODES.length - 1);
+    });
+    it('rejects an unknown code', async () => {
+        const ip = '203.0.113.11';
+        const ua = 'vitest-agent';
+        const state = { backupCodes: [...BACKUP_CODES] };
+        const db = await createMockDB(state);
+        initDB(db);
+        const handler = handleActuateAPI({ prismaClient: db, config: { collections: {} } });
+        const token = await makePendingToken(ip, ua);
+        const res = await handler(new Request('https://example.com/api/cms/auth/totp/login', {
+            method: 'POST',
+            headers: { 'x-real-ip': ip, 'user-agent': ua, 'content-type': 'application/json' },
+            body: JSON.stringify({ mfaPendingToken: token, code: 'deadbeef' }),
+        }));
+        expect(res.status).toBe(401);
+        expect(state.backupCodes).toHaveLength(BACKUP_CODES.length);
+    });
+    it('rejects a stale pending token from a different device fingerprint', async () => {
+        const state = { backupCodes: [...BACKUP_CODES] };
+        const db = await createMockDB(state);
+        initDB(db);
+        const handler = handleActuateAPI({ prismaClient: db, config: { collections: {} } });
+        // Token minted for one device, redeemed from another (different UA).
+        const token = await makePendingToken('203.0.113.12', 'device-a');
+        const res = await handler(new Request('https://example.com/api/cms/auth/totp/login', {
+            method: 'POST',
+            headers: {
+                'x-real-ip': '203.0.113.12',
+                'user-agent': 'device-b',
+                'content-type': 'application/json',
+            },
+            body: JSON.stringify({ mfaPendingToken: token, code: 'aaaa1111' }),
+        }));
+        expect(res.status).toBe(401);
+    });
+});
+//# sourceMappingURL=totp-login.test.js.map

package/dist/__tests__/api/totp-login.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"totp-login.test.js","sourceRoot":"","sources":["../../../src/__tests__/api/totp-login.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/auth/totp.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=totp.test.d.ts.map

package/dist/__tests__/auth/totp.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"totp.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/auth/totp.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/auth/totp.test.js

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest';
+import { generateBackupCodes, generateTOTPSecret, generateTOTPUri, verifyTOTP, normalizeBackupCode, findBackupCodeMatch, } from '../../auth/totp.js';
+describe('totp helpers', () => {
+    it('generates a scannable otpauth URI for the given account', () => {
+        const secret = generateTOTPSecret();
+        const uri = generateTOTPUri(secret, 'admin@example.com');
+        expect(uri.startsWith('otpauth://totp/')).toBe(true);
+        expect(uri).toContain(`secret=${secret}`);
+        expect(uri).toContain('issuer=Actuate%20CMS');
+        expect(uri).toContain(encodeURIComponent('admin@example.com'));
+    });
+    it('verifies a TOTP code derived from the same secret', async () => {
+        // Derive the current code the same way the verifier does, then confirm it
+        // round-trips. Importing the private HOTP isn't exposed, so we lean on the
+        // window tolerance: a freshly generated secret should not validate a random
+        // 6-digit guess.
+        const secret = generateTOTPSecret();
+        expect(verifyTOTP('000000', secret)).toBe(false);
+    });
+});
+describe('backup codes', () => {
+    it('generates the requested number of unique 8-char hex codes', () => {
+        const codes = generateBackupCodes(8);
+        expect(codes).toHaveLength(8);
+        expect(new Set(codes).size).toBe(8);
+        for (const code of codes) {
+            expect(code).toMatch(/^[0-9a-f]{8}$/);
+        }
+    });
+    it('normalizes whitespace, dashes and case', () => {
+        expect(normalizeBackupCode('ABCD-1234')).toBe('abcd1234');
+        expect(normalizeBackupCode('  ab cd 12 34 ')).toBe('abcd1234');
+        expect(normalizeBackupCode('')).toBe('');
+    });
+    it('matches a stored code regardless of formatting and returns its index', () => {
+        const codes = ['aaaa1111', 'bbbb2222', 'cccc3333'];
+        expect(findBackupCodeMatch(codes, 'BBBB-2222')).toBe(1);
+        expect(findBackupCodeMatch(codes, ' cccc 3333 ')).toBe(2);
+    });
+    it('returns -1 for a non-matching or empty submission', () => {
+        const codes = ['aaaa1111', 'bbbb2222'];
+        expect(findBackupCodeMatch(codes, 'deadbeef')).toBe(-1);
+        expect(findBackupCodeMatch(codes, '')).toBe(-1);
+        expect(findBackupCodeMatch([], 'aaaa1111')).toBe(-1);
+    });
+    it('does not match a code that only shares a prefix (length-aware compare)', () => {
+        const codes = ['aaaa1111'];
+        expect(findBackupCodeMatch(codes, 'aaaa111')).toBe(-1);
+        expect(findBackupCodeMatch(codes, 'aaaa11110')).toBe(-1);
+    });
+});
+//# sourceMappingURL=totp.test.js.map

package/dist/__tests__/auth/totp.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"totp.test.js","sourceRoot":"","sources":["../../../src/__tests__/auth/totp.test.ts"],"names":[],"mappings":"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"}

package/dist/api/handlers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../src/api/handlers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AA+/B5C,iFAAiF;AACjF,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C;AA8JD,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAS9E;AAiTD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA68UzD"}
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../src/api/handlers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AA+/B5C,iFAAiF;AACjF,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C;AA8JD,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAS9E;AAiTD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAi/UzD"}

package/dist/api/handlers.js

@@ -33,7 +33,7 @@ import { sendFormNotifications } from '../forms/notify.js';
 import { checkForUpdates } from '../upgrade/version-check.js';
 import { createUpgradePR } from '../upgrade/upgrade-pr.js';
 import { encryptField, decryptField } from '../security/encrypted-fields.js';
-import { encryptSecret, decryptSecret, encryptStringArray, } from '../security/secret-storage.js';
+import { encryptSecret, decryptSecret, encryptStringArray, decryptStringArray, } from '../security/secret-storage.js';
 import { createRateLimiter } from '../security/rate-limit.js';
 import { generateOpenAPISpec } from './openapi.js';
 import { createSSEPresenceAdapter } from '../presence/index.js';
@@ -1741,7 +1741,14 @@ export function registerCMSRoutes(router) {
                 return auth.error;
             const user = await db().user.findUnique({
                 where: { id: auth.session.userId },
-                select: { id: true, email: true, name: true, role: true, isActive: true },
+                select: {
+                    id: true,
+                    email: true,
+                    name: true,
+                    role: true,
+                    isActive: true,
+                    totpEnabled: true,
+                },
             });
             if (!user) {
                 return errorResponse('User not found', 404);
@@ -1915,6 +1922,7 @@ export function registerCMSRoutes(router) {
                     role: true,
                     totpSecret: true,
                     totpEnabled: true,
+                    backupCodes: true,
                     isActive: true,
                 },
             });
@@ -1922,7 +1930,34 @@ export function registerCMSRoutes(router) {
                 return errorResponse('Invalid request', 400);
             }
             const decryptedSecret = await decryptSecret(user.totpSecret);
-            const valid = verifyTOTP(body.code, decryptedSecret);
+            let valid = verifyTOTP(body.code, decryptedSecret);
+            let usedBackupCode = false;
+            // Backup-code fallback. A user who has lost their authenticator can sign
+            // in with one of the one-time recovery codes issued at enrollment. Each
+            // code is single-use: on a match we remove it and re-persist the
+            // remaining codes so it can never be replayed. We compare against every
+            // stored code in constant time to avoid leaking which/whether one matched.
+            const storedBackups = Array.isArray(user.backupCodes) ? user.backupCodes : [];
+            if (!valid && storedBackups.length > 0) {
+                try {
+                    const { findBackupCodeMatch } = await import('../auth/totp.js');
+                    const codes = await decryptStringArray(storedBackups);
+                    const matchIdx = findBackupCodeMatch(codes, body.code);
+                    if (matchIdx !== -1) {
+                        valid = true;
+                        usedBackupCode = true;
+                        const remaining = codes.filter((_, i) => i !== matchIdx);
+                        await db().user.update({
+                            where: { id: user.id },
+                            data: { backupCodes: await encryptStringArray(remaining) },
+                        });
+                    }
+                }
+                catch {
+                    // Decryption failure (e.g. the encryption key was rotated) — treat
+                    // as no match rather than throwing a 500 at the login screen.
+                }
+            }
             if (!valid) {
                 await logEvent({
                     event: 'login_failed',
@@ -1952,7 +1987,7 @@ export function registerCMSRoutes(router) {
                 userId: user.id,
                 ipAddress: isResolvedIp(ip) ? ip : undefined,
                 userAgent: userAgent ?? undefined,
-                details: { mfa: 'totp' },
+                details: { mfa: usedBackupCode ? 'backup_code' : 'totp' },
             });
             const isProduction = process.env.NODE_ENV === 'production';
             const sessionCookie = [