@stamhoofd/backend 2.137.4 → 2.138.0

package/src/endpoints/auth/CreateTokenEndpoint.ts

@@ -1,15 +1,20 @@
 import type { DecodedRequest, Request } from '@simonbackx/simple-endpoints';
 import { Endpoint, Response } from '@simonbackx/simple-endpoints';
 import { SimpleError } from '@simonbackx/simple-errors';
-import { EmailVerificationCode, PasswordToken, Platform, Token, User } from '@stamhoofd/models';
-import type { ChallengeGrantStruct, PasswordGrantStruct, PasswordTokenGrantStruct, RefreshTokenGrantStruct, RequestChallengeGrantStruct } from '@stamhoofd/structures';
-import { CreateTokenStruct, LoginMethod, SignupResponse, Token as TokenStruct } from '@stamhoofd/structures';
+import { EmailVerificationCode, MFATOTP, MFAToken, PasswordToken, Platform, Token, User, WebauthnCredential } from '@stamhoofd/models';
+import type { ChallengeGrantStruct, MFAGrantStruct, PasswordGrantStruct, PasswordTokenGrantStruct, RefreshTokenGrantStruct, RequestChallengeGrantStruct } from '@stamhoofd/structures';
+import { CreateTokenStruct, LoginMethod, MFAMethodType, SignupResponse, Token as TokenStruct } from '@stamhoofd/structures';
 
 import { Context } from '../../helpers/Context.js';
+import { RecoveryCodeHelper } from '../../helpers/RecoveryCodeHelper.js';
+import { TOTPHelper } from '../../helpers/TOTPHelper.js';
+import { mfaVerificationRateLimiter, TwoFactorHelper } from '../../helpers/TwoFactorHelper.js';
+import { WebauthnHelper } from '../../helpers/WebauthnHelper.js';
+import { VerificationCodeService } from '../../services/VerificationCodeService.js';
 
 type Params = Record<string, never>;
 type Query = undefined;
-type Body = RequestChallengeGrantStruct | ChallengeGrantStruct | RefreshTokenGrantStruct | PasswordTokenGrantStruct | PasswordGrantStruct;
+type Body = RequestChallengeGrantStruct | ChallengeGrantStruct | RefreshTokenGrantStruct | PasswordTokenGrantStruct | PasswordGrantStruct | MFAGrantStruct;
 type ResponseBody = TokenStruct;
 
 export class CreateTokenEndpoint extends Endpoint<Params, Query, Body, ResponseBody> {
@@ -81,6 +86,8 @@ export class CreateTokenEndpoint extends Endpoint<Params, Query, Body, ResponseB
                     });
                 }
 
+                await oldToken.user.markActive();
+
                 const st = new TokenStruct(token);
                 return new Response(st);
             }
@@ -127,7 +134,7 @@ export class CreateTokenEndpoint extends Endpoint<Params, Query, Body, ResponseB
                 // if not: throw a validation error (e-mail validation is required)
                 if (!user.verified) {
                     const code = await EmailVerificationCode.createFor(user, user.email);
-                    code.send(user, organization, request.i18n).catch(console.error);
+                    VerificationCodeService.send(code, user, organization, request.i18n).catch(console.error);
 
                     throw new SimpleError({
                         code: 'verify_email',
@@ -140,7 +147,12 @@ export class CreateTokenEndpoint extends Endpoint<Params, Query, Body, ResponseB
                     });
                 }
 
-                const token = await Token.createToken(user);
+                // Second factor / forced enrollment: block the session until the user
+                // completes (or first sets up) a second factor. Shared with every other
+                // grant that mints a session from a single primary credential.
+                await TwoFactorHelper.assertSecondFactorOrThrow(user, organization, request.request.getVersion());
+
+                const token = await Token.createToken(user, new Date());
 
                 if (!token) {
                     throw new SimpleError({
@@ -151,6 +163,110 @@ export class CreateTokenEndpoint extends Endpoint<Params, Query, Body, ResponseB
                     });
                 }
 
+                await user.markActive();
+
+                const st = new TokenStruct(token);
+                return new Response(st);
+            }
+
+            case 'mfa': {
+                const mfaToken = await MFAToken.getValid(request.body.mfaToken, 'login');
+                if (!mfaToken) {
+                    throw new SimpleError({
+                        code: 'invalid_mfa_token',
+                        message: 'The MFA session is invalid or expired',
+                        human: $t('%ZhJ'),
+                        statusCode: 400,
+                    });
+                }
+
+                const user = await User.getByID(mfaToken.userId);
+                if (!user) {
+                    await mfaToken.consume();
+                    throw new SimpleError({
+                        code: 'invalid_mfa_token',
+                        message: 'The MFA session is invalid or expired',
+                        human: $t('%ZhJ'),
+                        statusCode: 400,
+                    });
+                }
+
+                // Scope check (same rules as refresh/password_token)
+                if ((organization && user.organizationId && user.organizationId !== organization.id) || (!organization && user.organizationId)) {
+                    throw new SimpleError({
+                        code: 'invalid_mfa_token',
+                        message: 'The MFA session is invalid or expired',
+                        human: $t('%ZhJ'),
+                        statusCode: 400,
+                    });
+                }
+
+                // Aggregate brute-force protection across ALL of this user's MFA tokens
+                // (the per-token counter alone can be bypassed by minting new tokens).
+                // This MUST run before verification so that, once the limit is hit, even a
+                // correct code is rejected — otherwise a lucky/leaked code would still let
+                // an attacker through after unlimited guesses.
+                mfaVerificationRateLimiter.track(user.id);
+
+                let verified = false;
+                if (request.body.method === MFAMethodType.TOTP) {
+                    const code = request.body.code ?? '';
+                    for (const totp of await MFATOTP.getConfirmedForUser(user.id)) {
+                        const counter = TOTPHelper.verify(code, totp.secret);
+                        if (counter === null) {
+                            continue;
+                        }
+                        // Claiming the step counter both rejects a still-valid code that was
+                        // accepted before (replay) and settles two requests that submit the
+                        // same code at the same time: only one of them gets the claim.
+                        if (await totp.claimCounter(counter)) {
+                            verified = true;
+                            break;
+                        }
+                    }
+                } else if (request.body.method === MFAMethodType.RecoveryCode) {
+                    verified = await RecoveryCodeHelper.consume(user.id, request.body.code ?? '');
+                } else if (request.body.method === MFAMethodType.Passkey) {
+                    const assertion = request.body.assertion;
+                    const credentialId = assertion?.id;
+                    if (mfaToken.webauthnChallenge && assertion && credentialId) {
+                        const credential = await WebauthnCredential.getByCredentialId(credentialId);
+                        if (credential && credential.userId === user.id) {
+                            const newCounter = await WebauthnHelper.verifyAuthentication(assertion, mfaToken.webauthnChallenge, credential);
+                            if (newCounter !== null) {
+                                credential.counter = newCounter;
+                                credential.lastUsedAt = new Date();
+                                await credential.save();
+                                verified = true;
+                            }
+                        }
+                    }
+                }
+
+                if (!verified) {
+                    const locked = await mfaToken.registerFailedAttempt();
+                    throw new SimpleError({
+                        code: locked ? 'too_many_attempts' : 'invalid_mfa_code',
+                        message: locked ? 'Too many attempts' : 'Invalid code',
+                        human: locked ? $t('%ZhT') : $t('%Zgp'),
+                        statusCode: locked ? 429 : 400,
+                        field: 'code',
+                    });
+                }
+
+                if (!await mfaToken.consume()) {
+                    // Another request already completed this challenge.
+                    throw new SimpleError({
+                        code: 'invalid_mfa_token',
+                        message: 'The MFA session is invalid or expired',
+                        human: $t('%ZhJ'),
+                        statusCode: 400,
+                    });
+                }
+
+                const token = await Token.createToken(user, new Date());
+                await user.markActive();
+
                 const st = new TokenStruct(token);
                 return new Response(st);
             }
@@ -187,8 +303,18 @@ export class CreateTokenEndpoint extends Endpoint<Params, Query, Body, ResponseB
                     });
                 }
 
+                // A valid password-reset/magic-link token is a single primary credential:
+                // enforce the same second-factor gate as the password grant, otherwise
+                // anyone with a reset link (i.e. email access) could bypass the user's 2FA
+                // and even wipe their factors with the resulting fresh session.
+                //
+                // Forced enrollment (the user has no factor yet) additionally returns a
+                // temporary session token: this flow is also used to choose a first
+                // password (invites), which the client can only do with a session.
+                await TwoFactorHelper.assertSecondFactorOrThrow(passwordToken.user, organization, request.request.getVersion(), { allowTemporarySession: true });
+
                 // Important to create a new token before adjusting the old token
-                const token = await Token.createToken(passwordToken.user);
+                const token = await Token.createToken(passwordToken.user, new Date());
 
                 // TODO: make token short lived until renewal
 
@@ -210,6 +336,8 @@ export class CreateTokenEndpoint extends Endpoint<Params, Query, Body, ResponseB
                     await token.user.save();
                 }
 
+                await token.user.markActive();
+
                 const st = new TokenStruct(token);
                 return new Response(st);
             }

package/src/endpoints/auth/DeletePasskeyEndpoint.ts

@@ -0,0 +1,61 @@
+import type { DecodedRequest, Request } from '@simonbackx/simple-endpoints';
+import { Endpoint, Response } from '@simonbackx/simple-endpoints';
+import { SimpleError } from '@simonbackx/simple-errors';
+import { MFATOTP, WebauthnCredential } from '@stamhoofd/models';
+import type { MFAStatus } from '@stamhoofd/structures';
+import { MFAMethodType } from '@stamhoofd/structures';
+
+import { Context } from '../../helpers/Context.js';
+import { TwoFactorHelper } from '../../helpers/TwoFactorHelper.js';
+import { TwoFactorAuditLogService } from '../../services/TwoFactorAuditLogService.js';
+
+type Params = { id: string };
+type Query = undefined;
+type Body = undefined;
+type ResponseBody = MFAStatus;
+
+export class DeletePasskeyEndpoint extends Endpoint<Params, Query, Body, ResponseBody> {
+    protected doesMatch(request: Request): [true, Params] | [false] {
+        if (request.method !== 'DELETE') {
+            return [false];
+        }
+        const params = Endpoint.parseParameters(request.url, '/mfa/passkeys/@id', { id: String });
+        if (params) {
+            return [true, params as Params];
+        }
+        return [false];
+    }
+
+    async handle(request: DecodedRequest<Params, Query, Body>) {
+        const organization = await Context.setOptionalOrganizationScope();
+        const { user, token } = await Context.authenticateFresh({ allowWithoutAccount: true, allowUnscoped: true });
+
+        const credential = await WebauthnCredential.getByID(request.params.id);
+        if (!credential || credential.userId !== user.id) {
+            throw new SimpleError({
+                code: 'not_found',
+                message: 'Passkey not found',
+                human: $t('%Zho'),
+                statusCode: 404,
+            });
+        }
+
+        const confirmedTotp = await MFATOTP.getConfirmedForUser(user.id);
+        const passkeys = await WebauthnCredential.getForUser(user.id);
+        const remaining = confirmedTotp.length + passkeys.filter(p => p.id !== credential.id).length;
+        if (remaining === 0 && await TwoFactorHelper.isTwoFactorRequired(user, organization ?? Context.organization ?? null)) {
+            throw new SimpleError({
+                code: 'cannot_remove_last_factor',
+                message: 'Cannot remove the last two-factor method',
+                human: $t('%Zh4'),
+                statusCode: 400,
+            });
+        }
+
+        await credential.delete();
+
+        await TwoFactorAuditLogService.logMethodDeleted(user, MFAMethodType.Passkey, credential.name || credential.providerName || '');
+
+        return new Response(await TwoFactorHelper.completeRemoval(user, token));
+    }
+}

package/src/endpoints/auth/DeleteTOTPEndpoint.ts

@@ -0,0 +1,62 @@
+import type { DecodedRequest, Request } from '@simonbackx/simple-endpoints';
+import { Endpoint, Response } from '@simonbackx/simple-endpoints';
+import { SimpleError } from '@simonbackx/simple-errors';
+import { MFATOTP, WebauthnCredential } from '@stamhoofd/models';
+import type { MFAStatus } from '@stamhoofd/structures';
+import { MFAMethodType } from '@stamhoofd/structures';
+
+import { Context } from '../../helpers/Context.js';
+import { TwoFactorHelper } from '../../helpers/TwoFactorHelper.js';
+import { TwoFactorAuditLogService } from '../../services/TwoFactorAuditLogService.js';
+
+type Params = { id: string };
+type Query = undefined;
+type Body = undefined;
+type ResponseBody = MFAStatus;
+
+export class DeleteTOTPEndpoint extends Endpoint<Params, Query, Body, ResponseBody> {
+    protected doesMatch(request: Request): [true, Params] | [false] {
+        if (request.method !== 'DELETE') {
+            return [false];
+        }
+        const params = Endpoint.parseParameters(request.url, '/mfa/totp/@id', { id: String });
+        if (params) {
+            return [true, params as Params];
+        }
+        return [false];
+    }
+
+    async handle(request: DecodedRequest<Params, Query, Body>) {
+        const organization = await Context.setOptionalOrganizationScope();
+        const { user, token } = await Context.authenticateFresh({ allowWithoutAccount: true, allowUnscoped: true });
+
+        const totp = await MFATOTP.getByID(request.params.id);
+        if (!totp || totp.userId !== user.id) {
+            throw new SimpleError({
+                code: 'not_found',
+                message: 'TOTP authenticator not found',
+                human: $t('%ZgJ'),
+                statusCode: 404,
+            });
+        }
+
+        // Prevent removing the last factor when 2FA is required.
+        const confirmedTotp = await MFATOTP.getConfirmedForUser(user.id);
+        const passkeys = await WebauthnCredential.getForUser(user.id);
+        const remaining = confirmedTotp.filter(t => t.id !== totp.id).length + passkeys.length;
+        if (remaining === 0 && await TwoFactorHelper.isTwoFactorRequired(user, organization ?? Context.organization ?? null)) {
+            throw new SimpleError({
+                code: 'cannot_remove_last_factor',
+                message: 'Cannot remove the last two-factor method',
+                human: $t('%Zh4'),
+                statusCode: 400,
+            });
+        }
+
+        await totp.delete();
+
+        await TwoFactorAuditLogService.logMethodDeleted(user, MFAMethodType.TOTP, totp.name);
+
+        return new Response(await TwoFactorHelper.completeRemoval(user, token));
+    }
+}

package/src/endpoints/auth/DeleteUserEndpoint.ts

@@ -1,7 +1,7 @@
 import type { DecodedRequest, Request } from '@simonbackx/simple-endpoints';
 import { Endpoint, Response } from '@simonbackx/simple-endpoints';
 
-import { getDefaultEmailFrom, sendEmailTemplate } from '@stamhoofd/models';
+import { getDefaultEmailFrom, sendEmailTemplate } from '../../helpers/EmailBuilder.js';
 import { EmailTemplateType, Recipient } from '@stamhoofd/structures';
 import { Context } from '../../helpers/Context.js';
 

package/src/endpoints/auth/ForgotPasswordEndpoint.ts

@@ -1,11 +1,13 @@
 import type { Decoder } from '@simonbackx/simple-encoding';
 import type { DecodedRequest, Request } from '@simonbackx/simple-endpoints';
 import { Endpoint, Response } from '@simonbackx/simple-endpoints';
-import { PasswordToken, Platform, sendEmailTemplate, User } from '@stamhoofd/models';
+import { Platform, User } from '@stamhoofd/models';
+import { sendEmailTemplate } from '../../helpers/EmailBuilder.js';
 import { EmailTemplateType, ForgotPasswordRequest, LoginMethod, Recipient, Replacement } from '@stamhoofd/structures';
 
 import { SimpleError } from '@simonbackx/simple-errors';
 import { Context } from '../../helpers/Context.js';
+import { PasswordForgotService } from '../../services/PasswordForgotService.js';
 
 type Params = Record<string, never>;
 type Query = undefined;
@@ -72,7 +74,7 @@ export class ForgotPasswordEndpoint extends Endpoint<Params, Query, Body, Respon
             return new Response(undefined);
         }
 
-        const recoveryUrl = await PasswordToken.getPasswordRecoveryUrl(user, organization, request.i18n);
+        const recoveryUrl = await PasswordForgotService.getPasswordRecoveryUrl(user, organization, request.i18n);
 
         // Create e-mail builder
         await sendEmailTemplate(organization, {

package/src/endpoints/auth/GetMFAChallengeEndpoint.ts

@@ -0,0 +1,56 @@
+import type { Decoder } from '@simonbackx/simple-encoding';
+import type { DecodedRequest, Request } from '@simonbackx/simple-endpoints';
+import { Endpoint, Response } from '@simonbackx/simple-endpoints';
+import { SimpleError } from '@simonbackx/simple-errors';
+import { MFAToken } from '@stamhoofd/models';
+import type { MFAChallengeResponse } from '@stamhoofd/structures';
+import { MFAChallengeRequest } from '@stamhoofd/structures';
+
+import { Context } from '../../helpers/Context.js';
+import { TwoFactorHelper } from '../../helpers/TwoFactorHelper.js';
+
+type Params = Record<string, never>;
+type Query = undefined;
+type Body = MFAChallengeRequest;
+type ResponseBody = MFAChallengeResponse;
+
+/**
+ * Describe the second factors that can complete a pending login.
+ *
+ * Password logins receive this as the `meta` of the `require_mfa` error, but an SSO login
+ * ends in a browser redirect that can only carry the token itself. The client posts that
+ * token here to learn which methods it may offer.
+ *
+ * Holding the token means the primary credential was already accepted, and the response
+ * carries no secrets: only which method types are enrolled, plus fresh WebAuthn options.
+ */
+export class GetMFAChallengeEndpoint extends Endpoint<Params, Query, Body, ResponseBody> {
+    bodyDecoder = MFAChallengeRequest as Decoder<MFAChallengeRequest>;
+
+    protected doesMatch(request: Request): [true, Params] | [false] {
+        if (request.method !== 'POST') {
+            return [false];
+        }
+        const params = Endpoint.parseParameters(request.url, '/mfa/challenge', {});
+        if (params) {
+            return [true, params as Params];
+        }
+        return [false];
+    }
+
+    async handle(request: DecodedRequest<Params, Query, Body>) {
+        await Context.setOptionalOrganizationScope({ willAuthenticate: false });
+
+        const mfaToken = await MFAToken.getValid(request.body.token, 'login');
+        if (!mfaToken) {
+            throw new SimpleError({
+                code: 'invalid_mfa_token',
+                message: 'The MFA session is invalid or expired',
+                human: $t('%ZhJ'),
+                statusCode: 400,
+            });
+        }
+
+        return new Response(await TwoFactorHelper.describeLoginChallenge(mfaToken));
+    }
+}

package/src/endpoints/auth/GetMFAStatusEndpoint.ts

@@ -0,0 +1,31 @@
+import type { DecodedRequest, Request } from '@simonbackx/simple-endpoints';
+import { Endpoint, Response } from '@simonbackx/simple-endpoints';
+import type { MFAStatus } from '@stamhoofd/structures';
+
+import { Context } from '../../helpers/Context.js';
+import { TwoFactorHelper } from '../../helpers/TwoFactorHelper.js';
+
+type Params = Record<string, never>;
+type Query = undefined;
+type Body = undefined;
+type ResponseBody = MFAStatus;
+
+export class GetMFAStatusEndpoint extends Endpoint<Params, Query, Body, ResponseBody> {
+    protected doesMatch(request: Request): [true, Params] | [false] {
+        if (request.method !== 'GET') {
+            return [false];
+        }
+        const params = Endpoint.parseParameters(request.url, '/mfa', {});
+        if (params) {
+            return [true, params as Params];
+        }
+        return [false];
+    }
+
+    async handle(request: DecodedRequest<Params, Query, Body>) {
+        await Context.setOptionalOrganizationScope();
+        const { user } = await Context.authenticate({ allowWithoutAccount: true, allowUnscoped: true });
+
+        return new Response(await TwoFactorHelper.buildStatus(user));
+    }
+}

package/src/endpoints/auth/GetUserEndpoint.test.ts

@@ -1,6 +1,7 @@
 import { Request } from '@simonbackx/simple-endpoints';
-import { OrganizationFactory, Token, UserFactory } from '@stamhoofd/models';
+import { MemberFactory, OrganizationFactory, Token, UserFactory } from '@stamhoofd/models';
 
+import { MFATestHelper } from '../../../tests/helpers/MFATestHelper.js';
 import { testServer } from '../../../tests/helpers/TestServer.js';
 import { GetUserEndpoint } from './GetUserEndpoint.js';
 import { STExpect } from '@stamhoofd/test-utils';
@@ -22,6 +23,36 @@ describe('Endpoint.GetUser', () => {
         expect(response.body.id).toEqual(user.id);
     });
 
+    test('Two-factor authentication is reported on the user and on the accounts of a member', async () => {
+        const organization = await new OrganizationFactory({}).create();
+        const user = await new UserFactory({ organization }).create();
+        await new MemberFactory({ organization, user }).create();
+        await MFATestHelper.addConfirmedTOTP(user);
+
+        const token = await Token.createToken(user);
+        const r = Request.buildJson('GET', '/v1/user', organization.getApiHost());
+        r.headers.authorization = 'Bearer ' + token.accessToken;
+
+        const response = await testServer.test(endpoint, r);
+        expect(response.body.hasTwoFactor).toBe(true);
+
+        // The same flag is what MemberAccountBox shows for every account of a member.
+        const member = response.body.members.members.find(m => m.users.some(u => u.id === user.id));
+        expect(member?.users.find(u => u.id === user.id)?.hasTwoFactor).toBe(true);
+    });
+
+    test('A user without a second factor is not reported as having two-factor authentication', async () => {
+        const organization = await new OrganizationFactory({}).create();
+        const user = await new UserFactory({ organization }).create();
+        const token = await Token.createToken(user);
+
+        const r = Request.buildJson('GET', '/v1/user', organization.getApiHost());
+        r.headers.authorization = 'Bearer ' + token.accessToken;
+
+        const response = await testServer.test(endpoint, r);
+        expect(response.body.hasTwoFactor).toBe(false);
+    });
+
     test('Request user details when not signed in is not working', async () => {
         const organization = await new OrganizationFactory({}).create();
         const r = Request.buildJson('GET', '/v1/user', organization.getApiHost());