@stamhoofd/backend 2.137.5 → 2.138.0

package/src/helpers/Context.ts

@@ -1,14 +1,14 @@
 import { DecodedRequest, Request } from '@simonbackx/simple-endpoints';
 import { isSimpleError, SimpleError } from '@simonbackx/simple-errors';
 import { I18n } from '@stamhoofd/backend-i18n';
-import type { User } from '@stamhoofd/models';
-import { Organization, Platform, RateLimiter, Token } from '@stamhoofd/models';
+import { MFAToken, Organization, Platform, RateLimiter, Token, User } from '@stamhoofd/models';
 import { AsyncLocalStorage } from 'async_hooks';
 
 import type { Decoder } from '@simonbackx/simple-encoding';
 import { AutoEncoder, field, StringDecoder } from '@simonbackx/simple-encoding';
 import { ApiUserRateLimits } from '@stamhoofd/structures';
 import { AdminPermissionChecker } from './AdminPermissionChecker.js';
+import { TwoFactorHelper } from './TwoFactorHelper.js';
 
 export const apiUserRateLimiter = new RateLimiter({
     limits: [
@@ -180,7 +180,7 @@ export class ContextInstance {
         if (STAMHOOFD.userMode === 'platform') {
             return null;
         }
-        return await this.setOrganizationScope(options);
+        return await this.setOptionalOrganizationScope(options);
     }
 
     async setOrganizationScope(options?: { willAuthenticate?: boolean }) {
@@ -223,7 +223,24 @@ export class ContextInstance {
         }
     }
 
-    async authenticate({ allowWithoutAccount = false, allowUnscoped = false }: { allowWithoutAccount?: boolean; allowUnscoped?: boolean } = {}): Promise<{ user: User; token: Token }> {
+    /**
+     * Identify the caller from the Authorization header without ever throwing: returns
+     * null when the request is unauthenticated or carries an invalid/expired token.
+     * Use this to give an already signed in user a smoother experience, never to grant
+     * access (there is no error to react to).
+     */
+    async optionalAuthenticatedUser(): Promise<User | null> {
+        try {
+            const { user } = await this.authenticate({ allowWithoutAccount: true });
+            return user;
+        } catch (e) {
+            return null;
+        }
+    }
+
+    async authenticate(options: { allowMFASetupToken: true; allowWithoutAccount?: boolean; allowUnscoped?: boolean }): Promise<{ user: User; token: Token } | { user: User; setupToken: MFAToken }>;
+    async authenticate(options?: { allowMFASetupToken?: false | undefined; allowWithoutAccount?: boolean; allowUnscoped?: boolean }): Promise<{ user: User; token: Token }>;
+    async authenticate({ allowWithoutAccount = false, allowUnscoped = false, allowMFASetupToken = false }: { allowMFASetupToken?: boolean; allowWithoutAccount?: boolean; allowUnscoped?: boolean } = {}): Promise<{ user: User; token: Token } | { user: User; setupToken: MFAToken }> {
         let header = this.request.headers.authorization;
 
         if (!header && this.request.method === 'POST') {
@@ -244,6 +261,12 @@ export class ContextInstance {
         }
 
         if (!header.startsWith('Bearer ')) {
+            if (allowMFASetupToken) {
+                const result = await this.authenticateMFASetup();
+                if (result) {
+                    return result;
+                }
+            }
             throw new SimpleError({
                 code: 'not_supported_authentication',
                 message: 'Authentication method not supported. Please authenticate with OAuth2',
@@ -320,6 +343,93 @@ export class ContextInstance {
         return { user, token };
     }
 
+    /**
+     * Like authenticate(), but additionally requires the access token to be "fresh"
+     * (minted by a real authentication within the FRESH_WINDOW, not via a refresh).
+     * Used to gate sensitive actions such as managing 2FA methods.
+     */
+    async authenticateFresh(options: { allowWithoutAccount?: boolean; allowUnscoped?: boolean } = {}): Promise<{ user: User; token: Token }> {
+        const result = await this.authenticate(options);
+        if (!result.token.isFresh()) {
+            throw new SimpleError({
+                code: 'require_fresh_auth',
+                message: 'A recent authentication is required for this action',
+                human: $t('%Zgs'),
+                statusCode: 403,
+            });
+        }
+        return result;
+    }
+
+    /**
+     * Authorize a 2FA enrollment/management action. Accepts either a fresh full session
+     * (Bearer access token) or a setup token (Authorization: MFASetup <token>) issued
+     * during forced enrollment, before a session exists.
+     */
+    async authenticateMFASetup(): Promise<{ user: User; setupToken: MFAToken } | null> {
+        const header = this.request.headers.authorization;
+        if (header && header.startsWith('MFASetup ')) {
+            const raw = header.substring('MFASetup '.length);
+            const setupToken = await MFAToken.getValid(raw, 'setup');
+            if (!setupToken) {
+                throw new SimpleError({
+                    code: 'mfa_setup_expired',
+                    message: 'The MFA setup session is invalid or expired',
+                    human: $t('%ZhJ'),
+                    statusCode: 401,
+                });
+            }
+            const user = await User.getByID(setupToken.userId);
+            if (!user) {
+                throw new SimpleError({
+                    code: 'mfa_setup_expired',
+                    message: 'The MFA setup session is invalid or expired',
+                    human: $t('%ZhJ'),
+                    statusCode: 401,
+                });
+            }
+
+            // A setup token is issued on the strength of a password alone, to bootstrap a
+            // *first* factor. If the user enrolled one in the meantime (e.g. from another
+            // device), it must stop being worth a session: otherwise someone who only
+            // knows the password keeps a 15 minute window in which they can enroll a
+            // factor of their own and sign in, even though the account is now protected.
+            if (await TwoFactorHelper.userHasFactors(user.id)) {
+                await setupToken.consume();
+                throw new SimpleError({
+                    code: 'mfa_setup_expired',
+                    message: 'The MFA setup session is no longer valid: the user already has a second factor',
+                    human: $t('%ZhJ'),
+                    statusCode: 401,
+                });
+            }
+
+            this.user = user;
+            await this.insecurelyAuthenticateAs(user);
+            return { user, setupToken };
+        }
+
+        return null;
+    }
+
+    /**
+     * Authorize a 2FA enrollment/management action. Accepts either a fresh full session
+     * (Bearer access token) or a setup token (Authorization: MFASetup <token>) issued
+     * during forced enrollment, before a session exists.
+     *
+     * Exactly one of `setupToken` / `token` is set: `token` is the session the request was
+     * made with, which enrollment keeps alive while signing out the user's other sessions.
+     */
+    async authenticateMFAEnrollment(): Promise<{ user: User; setupToken: MFAToken | null; token: Token | null }> {
+        const mfa = await this.authenticateMFASetup();
+        if (mfa) {
+            return { ...mfa, token: null };
+        }
+
+        const { user, token } = await this.authenticateFresh();
+        return { user, setupToken: null, token };
+    }
+
     async insecurelyAuthenticateAs(user: User) {
         this.#auth = new AdminPermissionChecker(user, await Platform.getSharedPrivateStruct(), this.organization);
 

package/src/helpers/EmailBuilder.test.ts

@@ -0,0 +1,287 @@
+import { EmailMocker } from '@stamhoofd/email';
+import { EmailContent, EmailTemplateType, Recipient, Replacement } from '@stamhoofd/structures';
+import { Country } from '@stamhoofd/types/Country';
+import { Language } from '@stamhoofd/types/Language';
+import { TestUtils } from '@stamhoofd/test-utils';
+import type { Organization, RegistrationPeriod } from '@stamhoofd/models';
+import { Email, EmailTemplateFactory, OrganizationFactory, RegistrationPeriodFactory } from '@stamhoofd/models';
+import { removeUnusedReplacements, sendEmailTemplate } from './EmailBuilder.js';
+
+describe('sendEmailTemplate with translations', () => {
+    let period: RegistrationPeriod;
+    let organization: Organization;
+
+    beforeAll(async () => {
+        period = await new RegistrationPeriodFactory({
+            startDate: new Date(2023, 0, 1),
+            endDate: new Date(2023, 11, 31),
+        }).create();
+    });
+
+    beforeEach(async () => {
+        organization = await new OrganizationFactory({ period }).create();
+    });
+
+    const type = EmailTemplateType.ForgotPassword;
+
+    test('each recipient receives the content in its own language, with the default as fallback', async () => {
+        await new EmailTemplateFactory({
+            organization,
+            type,
+            subject: 'Default subject',
+            html: '<p>Default html</p>',
+            text: 'Default text',
+            language: Language.Dutch,
+            translations: new Map([
+                [Language.French, EmailContent.create({ subject: 'Sujet français', html: '<p>Français</p>', text: 'Français' })],
+            ]),
+        }).create();
+
+        await sendEmailTemplate(organization, {
+            recipients: [
+                Recipient.create({ email: 'french@example.com', language: Language.French }),
+                Recipient.create({ email: 'dutch@example.com', language: Language.Dutch }),
+                Recipient.create({ email: 'english@example.com', language: Language.English }),
+                Recipient.create({ email: 'unknown@example.com' }),
+            ],
+            template: { type },
+            type: 'transactional',
+        });
+
+        const emails = await EmailMocker.transactional.getSucceededEmails();
+        expect(emails).toHaveLength(4);
+
+        const french = emails.find(e => e.to.includes('french@example.com'))!;
+        expect(french.subject).toBe('Sujet français');
+        expect(french.html).toContain('Français');
+
+        // Dutch is the default language: its content lives in the default content, not in the translations
+        const dutch = emails.find(e => e.to.includes('dutch@example.com'))!;
+        expect(dutch.subject).toBe('Default subject');
+        expect(dutch.html).toContain('Default html');
+
+        // English has no translation: falls back to the default content
+        const english = emails.find(e => e.to.includes('english@example.com'))!;
+        expect(english.subject).toBe('Default subject');
+        expect(english.html).toContain('Default html');
+
+        const unknown = emails.find(e => e.to.includes('unknown@example.com'))!;
+        expect(unknown.subject).toBe('Default subject');
+    });
+
+    test('generates recipient replacements in the recipient language', async () => {
+        // French must be a valid locale, otherwise it gets corrected to the default language
+        TestUtils.setEnvironment('locales', { [Country.Belgium]: [Language.Dutch, Language.French] });
+
+        // The unsubscribe URL is localized per recipient (it is not part of the translatable content)
+        await new EmailTemplateFactory({
+            organization,
+            type,
+            subject: 'Subject',
+            html: '<p>{{greeting}} {{unsubscribeUrl}}</p>',
+            text: '{{greeting}} {{unsubscribeUrl}}',
+        }).create();
+
+        await sendEmailTemplate(organization, {
+            recipients: [
+                Recipient.create({ email: 'french@example.com', language: Language.French }),
+                Recipient.create({ email: 'dutch@example.com', language: Language.Dutch }),
+                Recipient.create({ email: 'unknown@example.com' }),
+            ],
+            template: { type },
+            type: 'transactional',
+        });
+
+        const emails = await EmailMocker.transactional.getSucceededEmails();
+        const french = emails.find(e => e.to.includes('french@example.com'))!;
+        const dutch = emails.find(e => e.to.includes('dutch@example.com'))!;
+        const unknown = emails.find(e => e.to.includes('unknown@example.com'))!;
+
+        // The unsubscribe page URL points to the recipient's localized page
+        expect(french.html).toContain('/fr-BE/unsubscribe');
+        expect(dutch.html).toContain('/nl-BE/unsubscribe');
+        // No language set: falls back to the ambient (default) locale
+        expect(unknown.html).toContain('/nl-BE/unsubscribe');
+    });
+
+    test('a missing language never falls back to the translation of a different template', async () => {
+        // Platform level template with a French translation
+        await new EmailTemplateFactory({
+            type,
+            subject: 'Platform subject',
+            html: '<p>Platform html</p>',
+            text: 'Platform text',
+            language: Language.Dutch,
+            translations: new Map([
+                [Language.French, EmailContent.create({ subject: 'Sujet plateforme', html: '<p>Plateforme</p>', text: 'Plateforme' })],
+            ]),
+        }).create();
+
+        // Organization level template without any translations
+        await new EmailTemplateFactory({
+            organization,
+            type,
+            subject: 'Organization subject',
+            html: '<p>Organization html</p>',
+            text: 'Organization text',
+        }).create();
+
+        await sendEmailTemplate(organization, {
+            recipients: [
+                Recipient.create({ email: 'french@example.com', language: Language.French }),
+            ],
+            template: { type },
+            type: 'transactional',
+        });
+
+        const emails = await EmailMocker.transactional.getSucceededEmails();
+        expect(emails).toHaveLength(1);
+
+        // The organization template wins, and its default content is used for French:
+        // never the French translation of the platform template
+        expect(emails[0].subject).toBe('Organization subject');
+        expect(emails[0].html).toContain('Organization html');
+    });
+
+    test('setFromTemplate copies only the default language of the template onto the email if no language chosen for email', async () => {
+        await new EmailTemplateFactory({
+            organization,
+            type: EmailTemplateType.SavedMembersEmail,
+            subject: 'Default subject',
+            html: '<p>Default html</p>',
+            text: 'Default text',
+            language: Language.Dutch,
+            translations: new Map([
+                [Language.French, EmailContent.create({ subject: 'Sujet français', html: '<p>Français</p>', text: 'Français' })],
+            ]),
+        }).create();
+
+        const email = new Email();
+        email.organizationId = organization.id;
+        expect(await email.setFromTemplate(EmailTemplateType.SavedMembersEmail)).toBe(true);
+
+        expect(email.subject).toBe('Default subject');
+        expect(email.language).toBe(null);
+        expect(email.translations.size).toBe(0);
+    });
+
+    test('setFromTemplate copies only the correct language of the template onto the email', async () => {
+        await new EmailTemplateFactory({
+            organization,
+            type: EmailTemplateType.SavedMembersEmail,
+            subject: 'Default subject',
+            html: '<p>Default html</p>',
+            text: 'Default text',
+            language: Language.Dutch,
+            translations: new Map([
+                [Language.French, EmailContent.create({ subject: 'Sujet français', html: '<p>Français</p>', text: 'Français' })],
+            ]),
+        }).create();
+
+        const email = new Email();
+        email.language = Language.French;
+        email.organizationId = organization.id;
+        expect(await email.setFromTemplate(EmailTemplateType.SavedMembersEmail)).toBe(true);
+
+        expect(email.subject).toBe('Sujet français');
+        expect(email.language).toBe(Language.French);
+        expect(email.translations.size).toBe(0);
+    });
+
+    test('setFromTemplate copies only the default language of the template onto the email if languages match', async () => {
+        await new EmailTemplateFactory({
+            organization,
+            type: EmailTemplateType.SavedMembersEmail,
+            subject: 'Default subject',
+            html: '<p>Default html</p>',
+            text: 'Default text',
+            language: Language.Dutch,
+            translations: new Map([
+                [Language.French, EmailContent.create({ subject: 'Sujet français', html: '<p>Français</p>', text: 'Français' })],
+            ]),
+        }).create();
+
+        const email = new Email();
+        email.language = Language.Dutch;
+        email.organizationId = organization.id;
+        expect(await email.setFromTemplate(EmailTemplateType.SavedMembersEmail)).toBe(true);
+
+        expect(email.subject).toBe('Default subject');
+        expect(email.language).toBe(Language.Dutch);
+        expect(email.translations.size).toBe(0);
+    });
+
+    test('replaceAll is applied to the html of every language, not only the default', async () => {
+        await new EmailTemplateFactory({
+            organization,
+            type,
+            subject: 'Subject',
+            // The same placeholder appears in both the default and the translated html
+            html: '<p>Default __PLACEHOLDER__</p>',
+            text: 'Default __PLACEHOLDER__',
+            language: Language.Dutch,
+            translations: new Map([
+                [Language.French, EmailContent.create({ subject: 'Sujet', html: '<p>Français __PLACEHOLDER__</p>', text: 'Français __PLACEHOLDER__' })],
+            ]),
+        }).create();
+
+        await sendEmailTemplate(organization, {
+            recipients: [
+                Recipient.create({ email: 'french@example.com', language: Language.French }),
+                Recipient.create({ email: 'default@example.com' }),
+            ],
+            template: { type },
+            type: 'transactional',
+            replaceAll: [{ from: '__PLACEHOLDER__', to: 'REPLACED' }],
+        });
+
+        const emails = await EmailMocker.transactional.getSucceededEmails();
+        const french = emails.find(e => e.to.includes('french@example.com'))!;
+        const fallback = emails.find(e => e.to.includes('default@example.com'))!;
+
+        // The replaceAll must reach the translated html too, otherwise the placeholder leaks
+        expect(french.html).toContain('Français REPLACED');
+        expect(french.html).not.toContain('__PLACEHOLDER__');
+        expect(fallback.html).toContain('Default REPLACED');
+        expect(fallback.html).not.toContain('__PLACEHOLDER__');
+    });
+});
+
+describe('Email.getCombinedHtml', () => {
+    test('combines the default html with the html of every translation', () => {
+        const email = new Email();
+        email.html = '<p>Default {{signInUrl}}</p>';
+        email.translations = new Map([
+            [Language.French, EmailContent.create({ html: '<p>Français {{balanceTable}}</p>' })],
+        ]);
+
+        const combined = email.getCombinedHtml();
+        expect(combined).toContain('{{signInUrl}}');
+        expect(combined).toContain('{{balanceTable}}');
+    });
+
+    test('keeps a replacement that is only used inside a translation', () => {
+        const email = new Email();
+        // The default html uses signInUrl, only the French translation uses balanceTable
+        email.html = '<p>Default {{signInUrl}}</p>';
+        email.translations = new Map([
+            [Language.French, EmailContent.create({ html: '<p>Français {{balanceTable}}</p>' })],
+        ]);
+
+        const replacements = [
+            Replacement.create({ token: 'signInUrl', value: 'https://example.com' }),
+            Replacement.create({ token: 'balanceTable', value: '', html: '<table></table>' }),
+            Replacement.create({ token: 'outstandingBalance', value: '€ 10' }),
+        ];
+
+        // Using only the default html would wrongly strip balanceTable (used only by the translation)
+        const usingDefaultHtml = removeUnusedReplacements(email.html ?? '', replacements).map(r => r.token);
+        expect(usingDefaultHtml).not.toContain('balanceTable');
+
+        // Using the combined html keeps every replacement that any language needs, and still drops the truly unused one
+        const usingCombinedHtml = removeUnusedReplacements(email.getCombinedHtml(), replacements).map(r => r.token);
+        expect(usingCombinedHtml).toContain('signInUrl');
+        expect(usingCombinedHtml).toContain('balanceTable');
+        expect(usingCombinedHtml).not.toContain('outstandingBalance');
+    });
+});