@stamhoofd/backend 2.137.4 → 2.138.0

package/src/helpers/TwoFactorHelper.ts

@@ -0,0 +1,356 @@
+import { SimpleError } from '@simonbackx/simple-errors';
+import type { User } from '@stamhoofd/models';
+import { MFARecoveryCode, MFATOTP, MFAToken, Organization, Platform, RateLimiter, Token, WebauthnCredential } from '@stamhoofd/models';
+import type { User as UserStruct } from '@stamhoofd/structures';
+import { MFAChallengeResponse, MFAEnrollmentResult, MFAMethodType, MFASetupResponse, MFAStatus, PasskeyCredential, RecoveryCodes, TOTPCredential, Token as TokenStruct } from '@stamhoofd/structures';
+
+import type { PublicKeyCredentialRequestOptionsJSON } from '@simplewebauthn/server';
+
+import { RecoveryCodeHelper } from './RecoveryCodeHelper.js';
+import { WebauthnHelper } from './WebauthnHelper.js';
+import { Formatter, Sorter } from '@stamhoofd/utility';
+
+/**
+ * Aggregate brute-force protection for second-factor verification, keyed by user id.
+ * A single per-token try counter is not enough: an attacker who knows the password can
+ * mint unlimited login MFA tokens, so we also cap the total number of failed verification
+ * attempts per user across all of their tokens.
+ */
+export const mfaVerificationRateLimiter = new RateLimiter({
+    limits: [
+        {
+            limit: 10,
+            duration: 60 * 1000, // 10 failed attempts per minute
+        },
+        {
+            limit: 30,
+            duration: 60 * 60 * 1000, // 30 failed attempts per hour
+        },
+    ],
+});
+
+/**
+ * What still has to happen before a session may be issued for a user whose primary
+ * credential was just accepted.
+ */
+export type SecondFactorRequirement
+    = | { type: 'none' }
+        | { type: 'challenge'; challenge: MFAChallengeResponse }
+        | { type: 'setup'; setupToken: MFAToken };
+
+export class TwoFactorHelper {
+    /**
+     * Whether the user is required to have 2FA. Evaluated only on the password grant;
+     * SSO/Google logins are trusted to provide their own 2FA.
+     */
+    static async isTwoFactorRequired(user: User, organization: Organization | null): Promise<boolean> {
+        const perms = user.permissions;
+        if (!perms) {
+            return false;
+        }
+        // The platform can require 2FA for its users with platform permissions.
+        if (perms.globalPermissions !== null) {
+            const platform = await Platform.getSharedPrivateStruct();
+            if (platform.privateConfig.requireTwoFactor) {
+                return true;
+            }
+        }
+
+        // Organizations can require 2FA for their users with permissions.
+        //
+        // This looks at EVERY organization the user has permissions in, not only the one
+        // in scope. The scope is derived from the API host, so an admin could otherwise
+        // sidestep their organization's requirement by signing in on the platform
+        // (unscoped) host — the resulting session is not restricted to that host and
+        // gives them access to the organization anyway. For the same reason it also
+        // decides whether the last factor may be removed.
+        const organizationIds = [...perms.organizationPermissions.keys()];
+        if (organizationIds.length === 0) {
+            return false;
+        }
+
+        // Reuse the organization we already have in memory instead of fetching it again.
+        if (organization && organizationIds.includes(organization.id) && organization.privateMeta?.requireTwoFactor) {
+            return true;
+        }
+
+        const remaining = organizationIds.filter(id => id !== organization?.id);
+        if (remaining.length === 0) {
+            return false;
+        }
+
+        for (const other of await Organization.getByIDs(...remaining)) {
+            if (other.privateMeta?.requireTwoFactor) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /**
+     * What still has to happen before a session may be handed out, after a primary
+     * credential was accepted.
+     *
+     * `loginMethod` describes the credential that was just verified:
+     *  - 'password': a password, password token or email verification code. All of these
+     *    are single credentials owned by the user, so a required second factor must be
+     *    set up here if the user does not have one yet.
+     *  - 'sso': an external identity provider already authenticated the user, and is
+     *    trusted to apply its own second factor. An enrolled factor is still verified
+     *    (the user asked us to protect their account), but we do not force enrollment —
+     *    unless the account ALSO has a password, because then the password remains a way
+     *    in that bypasses whatever the provider enforces.
+     */
+    static async getSecondFactorRequirement(user: User, organization: Organization | null, { loginMethod }: { loginMethod: 'password' | 'sso' }): Promise<SecondFactorRequirement> {
+        if (await TwoFactorHelper.userHasFactors(user.id)) {
+            return { type: 'challenge', challenge: await TwoFactorHelper.createLoginChallenge(user) };
+        }
+
+        if (loginMethod === 'sso' && !user.hasPasswordBasedAccount()) {
+            return { type: 'none' };
+        }
+
+        if (await TwoFactorHelper.isTwoFactorRequired(user, organization)) {
+            return { type: 'setup', setupToken: await MFAToken.createFor(user.id, 'setup') };
+        }
+
+        return { type: 'none' };
+    }
+
+    /**
+     * Enforce the second-factor / forced-enrollment step after a successful primary
+     * authentication (password login, password-reset token, email verification). Throws a
+     * `require_mfa` or `require_mfa_setup` error when the user must still complete a second
+     * factor before a session may be issued; returns normally when the login may proceed.
+     *
+     * This MUST be called from every path that mints a full session from a single primary
+     * credential, otherwise that path becomes an MFA bypass. The SSO callback is a redirect
+     * instead of a request/response pair, so it uses getSecondFactorRequirement() directly.
+     *
+     * `allowTemporarySession` adds a normal session token to the forced-enrollment error.
+     * Only pass it for the password-token grant: the user has no second factor yet, so
+     * whoever holds the link could enroll one and get a session anyway, and the client
+     * needs a session to let the user choose a password before enrolling.
+     */
+    static async assertSecondFactorOrThrow(user: User, organization: Organization | null, version: number, { allowTemporarySession = false }: { allowTemporarySession?: boolean } = {}): Promise<void> {
+        const requirement = await TwoFactorHelper.getSecondFactorRequirement(user, organization, { loginMethod: 'password' });
+
+        if (requirement.type === 'challenge') {
+            throw new SimpleError({
+                code: 'require_mfa',
+                message: 'Two-factor authentication required',
+                human: $t('%ZhQ'),
+                meta: requirement.challenge.encode({ version }),
+                statusCode: 403,
+            });
+        }
+
+        if (requirement.type === 'setup') {
+            const temporaryToken = allowTemporarySession ? new TokenStruct(await Token.createToken(user, new Date())) : null;
+
+            throw new SimpleError({
+                code: 'require_mfa_setup',
+                message: 'Two-factor authentication setup required',
+                human: $t('%Zh8'),
+                meta: MFASetupResponse.create({
+                    setupToken: requirement.setupToken.token,
+                    token: temporaryToken,
+                    canUsePasskeys: user.canUsePasskeys(),
+                }).encode({ version }),
+                statusCode: 403,
+            });
+        }
+    }
+
+    static async userHasFactors(userId: string): Promise<boolean> {
+        const totp = await MFATOTP.getConfirmedForUser(userId);
+        if (totp.length > 0) {
+            return true;
+        }
+        const passkeys = await WebauthnCredential.getForUser(userId);
+        return passkeys.length > 0;
+    }
+
+    /**
+     * Which of these users have at least one enrolled factor.
+     *
+     * Batched on purpose: the admin lists show this for every row, so asking per user
+     * would be a query per row.
+     */
+    static async filterUserIdsWithFactors(userIds: string[]): Promise<Set<string>> {
+        const unique = Formatter.uniqueArray(userIds);
+        if (unique.length === 0) {
+            return new Set();
+        }
+
+        const [totp, passkeys] = await Promise.all([
+            MFATOTP.select().where('userId', unique).where('confirmedAt', '!=', null).fetch(),
+            WebauthnCredential.select().where('userId', unique).fetch(),
+        ]);
+
+        return new Set([...totp.map(t => t.userId), ...passkeys.map(p => p.userId)]);
+    }
+
+    /**
+     * Fill in `hasTwoFactor` on already built user structures. This is not part of
+     * User.getStructure() because it lives in other tables: it is loaded for all the
+     * users of a response at once.
+     */
+    static async fillTwoFactorStatus(users: UserStruct[]): Promise<void> {
+        if (users.length === 0) {
+            return;
+        }
+
+        const withFactors = await TwoFactorHelper.filterUserIdsWithFactors(users.map(u => u.id));
+        for (const user of users) {
+            user.hasTwoFactor = withFactors.has(user.id);
+        }
+    }
+
+    static async getEnrolledMethods(userId: string): Promise<{ methods: MFAMethodType[]; passkeys: WebauthnCredential[] }> {
+        const totp = await MFATOTP.getConfirmedForUser(userId);
+        const recovery = await MFARecoveryCode.getUnusedForUser(userId);
+
+        // Only passkeys of the RP ID we authenticate against can actually be used; the
+        // authenticator will not release the others.
+        const passkeys = WebauthnHelper.filterForCurrentRpID(await WebauthnCredential.getForUser(userId));
+
+        const methods: MFAMethodType[] = [];
+        if (totp.length > 0) {
+            methods.push(MFAMethodType.TOTP);
+        }
+        if (passkeys.length > 0) {
+            methods.push(MFAMethodType.Passkey);
+        }
+        if (recovery.length > 0) {
+            methods.push(MFAMethodType.RecoveryCode);
+        }
+        return { methods, passkeys };
+    }
+
+    /**
+     * Create a login MFA session token and the challenge payload returned to the client.
+     */
+    static async createLoginChallenge(user: User): Promise<MFAChallengeResponse> {
+        const { methods, passkeys } = await TwoFactorHelper.getEnrolledMethods(user.id);
+
+        let webauthnOptions: PublicKeyCredentialRequestOptionsJSON | null = null;
+        let challenge: string | null = null;
+        if (passkeys.length > 0) {
+            webauthnOptions = await WebauthnHelper.generateAuthentication(passkeys);
+            challenge = webauthnOptions.challenge;
+        }
+
+        const mfaToken = await MFAToken.createFor(user.id, 'login', challenge);
+
+        return MFAChallengeResponse.create({
+            token: mfaToken.token,
+            methods,
+            webauthnAuthenticationOptions: webauthnOptions,
+        });
+    }
+
+    /**
+     * Rebuild the challenge payload for a login MFA token that already exists.
+     *
+     * The SSO callback is a browser redirect, so it can only pass the token itself back to
+     * the client; the client then asks for the rest of the challenge. A new WebAuthn
+     * challenge is generated and stored on the token, replacing the previous one (the
+     * client never received it, and only the stored one is accepted).
+     */
+    static async describeLoginChallenge(mfaToken: MFAToken): Promise<MFAChallengeResponse> {
+        const { methods, passkeys } = await TwoFactorHelper.getEnrolledMethods(mfaToken.userId);
+
+        let webauthnOptions: PublicKeyCredentialRequestOptionsJSON | null = null;
+        if (passkeys.length > 0) {
+            webauthnOptions = await WebauthnHelper.generateAuthentication(passkeys);
+            mfaToken.webauthnChallenge = webauthnOptions.challenge;
+            await mfaToken.save();
+        }
+
+        return MFAChallengeResponse.create({
+            token: mfaToken.token,
+            methods,
+            webauthnAuthenticationOptions: webauthnOptions,
+        });
+    }
+
+    /**
+     * Finish an enrollment action. Generates recovery codes when this was the user's
+     * first factor, and (during forced enrollment) consumes the setup token and issues a
+     * full, fresh session token. `wasFirstFactor` must be computed before persisting the
+     * new factor.
+     *
+     * `currentToken` is the session the request was made with (null during forced
+     * enrollment, where there is no session yet). Every OTHER session of the user is
+     * signed out: enrolling a factor is how a user reacts to a suspected compromise, so it
+     * has to end the sessions they did not make this request from.
+     */
+    static async completeEnrollment(user: User, setupToken: MFAToken | null, wasFirstFactor: boolean, currentToken: Token | null): Promise<MFAEnrollmentResult> {
+        let recoveryCodes: RecoveryCodes | null = null;
+        if (wasFirstFactor) {
+            const codes = await RecoveryCodeHelper.regenerateForUser(user.id);
+            recoveryCodes = RecoveryCodes.create({ codes });
+        }
+
+        // Before minting the new session, so it is never signed out by its own enrollment.
+        await Token.deleteOtherSessions(user.id, currentToken?.accessToken ?? null);
+
+        let token: TokenStruct | null = null;
+        if (setupToken) {
+            await setupToken.consume();
+            const t = await Token.createToken(user, new Date());
+            await user.markActive();
+            token = new TokenStruct(t);
+        }
+
+        const status = await TwoFactorHelper.buildStatus(user);
+        return MFAEnrollmentResult.create({ status, token, recoveryCodes });
+    }
+
+    /**
+     * Clean up after a factor was deleted.
+     *
+     * Recovery codes exist to get back in when the enrolled factors are unavailable, so
+     * they are meaningless — and an unnecessary long-lived credential — once the last
+     * factor is gone. Every other session is signed out for the same reason enrollment
+     * does it: removing a factor is a security-relevant change to the account.
+     */
+    static async completeRemoval(user: User, currentToken: Token | null): Promise<MFAStatus> {
+        if (!(await TwoFactorHelper.userHasFactors(user.id))) {
+            await MFARecoveryCode.deleteForUser(user.id);
+        }
+
+        await Token.deleteOtherSessions(user.id, currentToken?.accessToken ?? null);
+
+        return await TwoFactorHelper.buildStatus(user);
+    }
+
+    static async buildStatus(user: User): Promise<MFAStatus> {
+        const userId = user.id;
+        const totp = await MFATOTP.getConfirmedForUser(userId);
+        const passkeys = await WebauthnCredential.getForUser(userId);
+        const recovery = await MFARecoveryCode.getUnusedForUser(userId);
+
+        return MFAStatus.create({
+            totp: totp.map(t => TOTPCredential.create({
+                id: t.id,
+                name: t.name,
+                createdAt: t.createdAt,
+                lastUsedAt: t.lastUsedAt,
+            })).sort((a, b) => Sorter.byDateValue(a.lastUsedAt ?? a.createdAt, b.lastUsedAt ?? b.createdAt)),
+            passkeys: passkeys.map(p => PasskeyCredential.create({
+                id: p.id,
+                name: p.name,
+                createdAt: p.createdAt,
+                lastUsedAt: p.lastUsedAt,
+                providerId: p.providerId,
+                providerName: p.providerName,
+                transports: p.transportsArray,
+            })).sort((a, b) => Sorter.byDateValue(a.lastUsedAt ?? a.createdAt, b.lastUsedAt ?? b.createdAt)),
+            hasRecoveryCodes: recovery.length > 0,
+            recoveryCodesRemaining: recovery.length,
+            canUsePasskeys: user.canUsePasskeys(),
+        });
+    }
+}

package/src/helpers/WebauthnHelper.ts

@@ -0,0 +1,211 @@
+import {
+    generateAuthenticationOptions,
+    generateRegistrationOptions,
+    verifyAuthenticationResponse,
+    verifyRegistrationResponse,
+} from '@simplewebauthn/server';
+import type { AuthenticationResponseJSON, AuthenticatorTransportFuture, RegistrationResponseJSON } from '@simplewebauthn/server';
+import type { User, WebauthnCredential } from '@stamhoofd/models';
+import type { WebauthnAuthenticationCredential, WebauthnRegistrationCredential } from '@stamhoofd/structures';
+import { getWebauthnRpId } from '@stamhoofd/structures';
+import aaguids from './data/aaguids.json' with { type: 'json' };
+const RP_NAME = 'Stamhoofd';
+
+const VALID_TRANSPORTS: AuthenticatorTransportFuture[] = ['ble', 'cable', 'hybrid', 'internal', 'nfc', 'smart-card', 'usb'];
+
+/**
+ * Narrow an untrusted string[] to valid AuthenticatorTransport values (no unchecked casts).
+ */
+function coerceTransports(transports: string[] | null | undefined): AuthenticatorTransportFuture[] | undefined {
+    if (!transports) {
+        return undefined;
+    }
+    const filtered = transports.filter((t): t is AuthenticatorTransportFuture => (VALID_TRANSPORTS as string[]).includes(t));
+    return filtered.length > 0 ? filtered : undefined;
+}
+
+/**
+ * The WebAuthn Relying Party ID new passkeys are registered against. Passkeys are bound to
+ * a single registrable domain, so we scope them to the dashboard domain (admin/staff
+ * logins). Shared with the client through @stamhoofd/structures, so both sides agree on
+ * which domain passkeys live on.
+ */
+function getRpID(): string {
+    const rpId = getWebauthnRpId();
+    if (!rpId) {
+        throw new Error('Dashboard domain is required for WebAuthn');
+    }
+    return rpId;
+}
+
+/**
+ * The RP ID an existing credential has to be verified against.
+ *
+ * Credentials created before the RP ID was stored per credential all used the platform RP
+ * ID of the time, so that is the fallback.
+ */
+function getCredentialRpID(credential: WebauthnCredential): string {
+    return credential.rpId ?? getRpID();
+}
+
+/**
+ * The origins a passkey for `rpId` may be presented from.
+ *
+ * The web apps run on https. The Capacitor app serves its web view from the same host but
+ * a custom scheme (see frontend/app/mobile/capacitor.config.json): iOS reports
+ * `capacitor://<host>`, while Android is configured with the https scheme and so already
+ * matches the first entry.
+ *
+ * Widening the origin does not widen who can use these passkeys: the app only gets to see
+ * them because it is listed in the associated domains (webcredentials) of the RP ID, which
+ * the operating system verifies before it releases a credential to any app.
+ */
+function getExpectedOrigins(rpId: string): string[] {
+    return ['https://' + rpId, 'capacitor://' + rpId];
+}
+
+export const WebauthnHelper = {
+    getRpID,
+    getExpectedOrigins,
+
+    async generateRegistration(user: User, existingCredentials: WebauthnCredential[]) {
+        return await generateRegistrationOptions({
+            rpName: RP_NAME,
+            rpID: getRpID(),
+            userName: user.email,
+            userID: new Uint8Array(Buffer.from(user.id)),
+            userDisplayName: user.name || user.email,
+            attestationType: 'direct',
+            excludeCredentials: existingCredentials.map(c => ({
+                id: c.credentialId,
+                transports: coerceTransports(c.transportsArray),
+            })),
+            authenticatorSelection: {
+                residentKey: 'preferred',
+                userVerification: 'preferred',
+            },
+        });
+    },
+
+    /**
+     * @returns the verified credential info to persist, or null when verification failed.
+     */
+    async verifyRegistration(credential: WebauthnRegistrationCredential, expectedChallenge: string) {
+        const response: RegistrationResponseJSON = {
+            id: credential.id,
+            rawId: credential.rawId,
+            type: 'public-key',
+            clientExtensionResults: {},
+            response: {
+                clientDataJSON: credential.response.clientDataJSON,
+                attestationObject: credential.response.attestationObject,
+                authenticatorData: credential.response.authenticatorData ?? undefined,
+                transports: coerceTransports(credential.response.transports),
+                publicKeyAlgorithm: credential.response.publicKeyAlgorithm ?? undefined,
+                publicKey: credential.response.publicKey ?? undefined,
+            },
+        };
+
+        const rpId = getRpID();
+
+        let verification: Awaited<ReturnType<typeof verifyRegistrationResponse>>;
+        try {
+            verification = await verifyRegistrationResponse({
+                response,
+                expectedChallenge,
+                expectedOrigin: getExpectedOrigins(rpId),
+                expectedRPID: rpId,
+                requireUserVerification: false,
+            });
+        } catch (e) {
+            // Malformed / tampered input makes the library throw; treat as a failed
+            // verification instead of surfacing a 500.
+            return null;
+        }
+
+        if (!verification.verified || !verification.registrationInfo) {
+            return null;
+        }
+
+        const { credential: verifiedCredential, credentialBackedUp, credentialDeviceType, aaguid } = verification.registrationInfo;
+        return {
+            rpId,
+            providerId: aaguid || null,
+            providerName: aaguids[aaguid]?.name || null,
+            credentialId: verifiedCredential.id,
+            publicKey: Buffer.from(verifiedCredential.publicKey).toString('base64url'),
+            counter: verifiedCredential.counter,
+            transports: verifiedCredential.transports ?? null,
+            backedUp: credentialBackedUp,
+            backupEligible: credentialDeviceType === 'multiDevice',
+        };
+    },
+
+    /**
+     * Only credentials of the RP ID we are authenticating against can take part: an
+     * authenticator will not release a passkey for a different domain. Today they all match,
+     * but this is what keeps the challenge correct once more than one domain is in play.
+     */
+    filterForCurrentRpID(credentials: WebauthnCredential[]): WebauthnCredential[] {
+        const rpId = getRpID();
+        return credentials.filter(c => getCredentialRpID(c) === rpId);
+    },
+
+    async generateAuthentication(credentials: WebauthnCredential[]) {
+        return await generateAuthenticationOptions({
+            rpID: getRpID(),
+            allowCredentials: WebauthnHelper.filterForCurrentRpID(credentials).map(c => ({
+                id: c.credentialId,
+                transports: coerceTransports(c.transportsArray),
+            })),
+            userVerification: 'preferred',
+        });
+    },
+
+    /**
+     * @returns the new signature counter on success, or null when verification failed.
+     */
+    async verifyAuthentication(credential: WebauthnAuthenticationCredential, expectedChallenge: string, storedCredential: WebauthnCredential): Promise<number | null> {
+        const response: AuthenticationResponseJSON = {
+            id: credential.id,
+            rawId: credential.rawId,
+            type: 'public-key',
+            clientExtensionResults: {},
+            response: {
+                clientDataJSON: credential.response.clientDataJSON,
+                authenticatorData: credential.response.authenticatorData,
+                signature: credential.response.signature,
+                userHandle: credential.response.userHandle ?? undefined,
+            },
+        };
+
+        // Verify against the RP ID this credential was created for, not the current one.
+        const rpId = getCredentialRpID(storedCredential);
+
+        let verification: Awaited<ReturnType<typeof verifyAuthenticationResponse>>;
+        try {
+            verification = await verifyAuthenticationResponse({
+                response,
+                expectedChallenge,
+                expectedOrigin: getExpectedOrigins(rpId),
+                expectedRPID: rpId,
+                credential: {
+                    id: storedCredential.credentialId,
+                    publicKey: new Uint8Array(Buffer.from(storedCredential.publicKey, 'base64url')),
+                    counter: storedCredential.counter,
+                    transports: coerceTransports(storedCredential.transportsArray),
+                },
+                requireUserVerification: false,
+            });
+        } catch (e) {
+            // Malformed / tampered input makes the library throw; treat as a failed
+            // verification instead of surfacing a 500.
+            return null;
+        }
+
+        if (!verification.verified) {
+            return null;
+        }
+        return verification.authenticationInfo.newCounter;
+    },
+};