@contember/engine-tenant-api 2.1.0-rc.3 → 2.2.0-alpha.10

package/src/model/service/EmailChangeManager.ts

@@ -0,0 +1,181 @@
+import { Response, ResponseError, ResponseOk } from '../utils/Response.js'
+import { UserMailer } from '../mailing/index.js'
+import { PersonQuery, PersonRow } from '../queries/index.js'
+import { PermissionContext, PermissionContextFactory } from '../authorization/index.js'
+import { ProjectManager } from './ProjectManager.js'
+import { ApiKeyManager } from './apiKey/index.js'
+import { EmailValidator, EmailValidatorError } from './EmailValidator.js'
+import { DatabaseContext } from '../utils/index.js'
+import { ImplementationException } from '../../exceptions.js'
+import { getPreferredProject } from './helpers/getPreferredProject.js'
+import { CreatePersonTokenCommand, InvalidateTokenCommand, MarkEmailVerifiedCommand } from '../commands/index.js'
+import { PersonTokenQuery } from '../queries/personToken/PersonTokenQuery.js'
+import { NextMailAttemptQuery } from '../queries/authLog/NextMailAttemptQuery.js'
+import { validateToken } from '../utils/index.js'
+import { normalizeEmail } from '../utils/email.js'
+import { PersonToken } from '../type/index.js'
+import { UniqueViolationError } from '@contember/database'
+import { AuthLogService } from './AuthLogService.js'
+
+interface MailOptions {
+	project?: string
+	mailVariant?: string
+}
+
+export class EmailChangeManager {
+	constructor(
+		private readonly mailer: UserMailer,
+		private readonly projectManager: ProjectManager,
+		private readonly emailValidator: EmailValidator,
+		private readonly apiKeyManager: ApiKeyManager,
+		private readonly permissionContextFactory: PermissionContextFactory,
+	) {}
+
+	/**
+	 * Request an e-mail change. Validation and rate-limiting run BEFORE any
+	 * write, so a rejected request never leaves a half-applied profile (e.g. a
+	 * persisted name change without the e-mail change going through). Any
+	 * immediate side-changes the caller wants applied atomically with the token
+	 * (the name change) are passed via `applyWithinTransaction`.
+	 */
+	public async requestEmailChange(
+		dbContext: DatabaseContext,
+		permissionContext: PermissionContext,
+		person: PersonRow,
+		newEmail: string,
+		mailOptions: MailOptions = {},
+		applyWithinTransaction?: (db: DatabaseContext) => Promise<void>,
+	): Promise<RequestEmailChangeResponse> {
+		const normalizedNewEmail = normalizeEmail(newEmail)
+		const validationError = await this.emailValidator.validateEmail(dbContext, normalizedNewEmail)
+		if (validationError !== null) {
+			return new ResponseError(validationError.error, validationError.errorMessage)
+		}
+
+		// Per-recipient exponential backoff: an authenticated user (or a hijacked
+		// session) must not be able to flood an arbitrary address with
+		// "confirm your new e-mail" mails. Keyed on the normalized NEW address so
+		// the `email_change_init` auth-log entries (written with the same
+		// normalized address) actually drive the backoff. Reuses login_* config.
+		const retryAfter = await dbContext.queryHandler.fetch(
+			new NextMailAttemptQuery(normalizedNewEmail, 'email_change_init', 'email_change_complete'),
+		)
+		if (retryAfter > 0) {
+			return new ResponseError('RATE_LIMIT_EXCEEDED', 'Too many e-mail change requests for this address.')
+		}
+
+		const projects = await this.projectManager.getProjectsByIdentity(dbContext, person.identity_id, permissionContext)
+		const project = getPreferredProject(projects, mailOptions.project ?? null)
+
+		await dbContext.transaction(async db => {
+			if (applyWithinTransaction) {
+				await applyWithinTransaction(db)
+			}
+			const result = await db.commandBus.execute(
+				CreatePersonTokenCommand.createEmailChangeRequest(person.id, normalizedNewEmail),
+			)
+			// The verification link goes to the NEW address — clicking it proves
+			// ownership of the address being switched to, which is the whole point.
+			await this.mailer.sendEmailChangeVerifyEmail(
+				db,
+				{
+					email: normalizedNewEmail,
+					token: result.token,
+					project: project?.name,
+					projectSlug: project?.slug,
+				},
+				{
+					variant: mailOptions.mailVariant || '',
+					projectId: project?.id ?? null,
+				},
+			)
+		})
+		return new ResponseOk(null)
+	}
+
+	public async confirmEmailChange(dbContext: DatabaseContext, token: string): Promise<ConfirmEmailChangeResponse> {
+		const tokenRow = await dbContext.queryHandler.fetch(PersonTokenQuery.byToken(token, 'email_change'))
+		const validation = validateToken({ entry: tokenRow, token, validationType: 'token' })
+		if (!validation.ok) {
+			// Tie the failure to a person/token in the audit log when we can, even
+			// for an invalid/expired token (matches verifyEmail / password reset).
+			return new ResponseError(validation.error, validation.errorMessage, {
+				[AuthLogService.Key]: new AuthLogService.Bag(
+					tokenRow ? { personId: tokenRow.person_id, tokenId: tokenRow.id } : {},
+				),
+			})
+		}
+		const authLogData = new AuthLogService.Bag({
+			personId: validation.result.person_id,
+			tokenId: validation.result.id,
+		})
+		const newEmail = validation.result.meta?.email
+		if (!newEmail) {
+			throw new ImplementationException('email_change token is missing its email payload')
+		}
+
+		const person = await dbContext.queryHandler.fetch(PersonQuery.byId(validation.result.person_id))
+		if (!person) {
+			throw new ImplementationException()
+		}
+
+		// Re-check uniqueness at confirmation time: another account may have
+		// claimed the address between request and confirmation.
+		const validationError = await this.emailValidator.validateEmail(dbContext, newEmail)
+		if (validationError !== null) {
+			return new ResponseError(validationError.error, validationError.errorMessage, {
+				[AuthLogService.Key]: authLogData,
+			})
+		}
+
+		const oldEmail = person.email
+		try {
+			await dbContext.transaction(async db => {
+				await db.commandBus.execute(new InvalidateTokenCommand(validation.result.id))
+				await db.commandBus.execute(new MarkEmailVerifiedCommand(person.id, newEmail))
+				// An email change is a takeover-grade event: drop every existing
+				// session so a stale attacker session cannot ride the new address.
+				await this.apiKeyManager.disableIdentityApiKeys(db, person.identity_id)
+			})
+		} catch (e) {
+			// The uniqueness re-check above narrows but cannot fully close the
+			// window: another account may claim the address between the check and
+			// this UPDATE. The unique index is the real guard — translate its
+			// violation into a clean error instead of leaking a 500.
+			if (e instanceof UniqueViolationError) {
+				return new ResponseError('EMAIL_ALREADY_EXISTS', `User with email ${newEmail} already exists`, {
+					[AuthLogService.Key]: authLogData,
+				})
+			}
+			throw e
+		}
+
+		if (oldEmail) {
+			// Resolve the person's preferred project so a per-project
+			// EMAIL_CHANGE_NOTIFY template (and branding) is honoured, mirroring
+			// requestEmailChange. The token carries no project, so derive it from the
+			// person's own identity.
+			const permissionContext = this.permissionContextFactory.create(dbContext, {
+				id: person.identity_id,
+				roles: person.roles,
+			})
+			const projects = await this.projectManager.getProjectsByIdentity(dbContext, person.identity_id, permissionContext)
+			const project = getPreferredProject(projects, null)
+			await this.mailer.sendEmailChangeNotifyEmail(
+				dbContext,
+				{ email: oldEmail, newEmail, project: project?.name, projectSlug: project?.slug },
+				{ projectId: project?.id ?? null, variant: '' },
+			)
+		}
+
+		return new ResponseOk({ personId: person.id, newEmail, [AuthLogService.Key]: authLogData })
+	}
+}
+
+export type RequestEmailChangeResponse = Response<null, EmailValidatorError | 'RATE_LIMIT_EXCEEDED'>
+
+export type ConfirmEmailChangeResponse = Response<
+	{ personId: string; newEmail: string; [AuthLogService.Key]: AuthLogService.Bag },
+	PersonToken.TokenValidationError | EmailValidatorError,
+	{ [AuthLogService.Key]: AuthLogService.Bag }
+>

package/src/model/service/EmailOtpManager.ts

@@ -0,0 +1,105 @@
+import { PersonRow } from '../queries/index.js'
+import { DatabaseContext, MAX_OTP_ATTEMPTS, validateToken } from '../utils/index.js'
+import { Providers } from '../providers.js'
+import { UserMailer } from '../mailing/index.js'
+import { ClaimOtpAttemptCommand, InvalidateEmailOtpTokensCommand, InvalidateTokenCommand, SaveEmailOtpTokenCommand } from '../commands/index.js'
+import { PersonTokenQuery } from '../queries/personToken/PersonTokenQuery.js'
+import { RateLimitDecision, RateLimiter } from './RateLimiter.js'
+import { RateLimitScopes } from '../type/RateLimit.js'
+import { Config } from '../type/Config.js'
+
+/** Email-OTP codes are short-lived numeric codes delivered by email. */
+const EMAIL_OTP_EXPIRATION_MINUTES = 10
+const EMAIL_OTP_DIGITS = 6
+
+/**
+ * Email OTP as a second factor (A05). Opt-in per person via
+ * `person_mfa.email_otp_enabled`. The emitted code is a 6-digit numeric code,
+ * transported through a short-lived `mfa_email_otp` person_token (the code's hash
+ * lives in `otp_hash`), validated through the shared `'otp'` token path (max 3
+ * attempts). Behavior for anyone who hasn't enabled it is unchanged.
+ */
+export class EmailOtpManager {
+	constructor(
+		private readonly mailer: UserMailer,
+		private readonly providers: Pick<Providers, 'randomBytes' | 'now' | 'uuid'>,
+		private readonly rateLimiter: RateLimiter,
+	) {}
+
+	/**
+	 * Generates a fresh code, invalidates any prior unused email-OTP tokens for the
+	 * person, persists the new one and emails the code. Must run inside the request's
+	 * db context (it issues commands + sends mail).
+	 *
+	 * Gated by the per-person `email_otp_per_person` rate limit so an attacker who
+	 * knows the password cannot re-issue codes to reset the per-code 3-attempt
+	 * counter, nor email-bomb a person. When the limit is hit nothing is sent and
+	 * the returned decision is `ok: false` (the caller decides how to surface it);
+	 * a previously emailed, still-valid code remains usable.
+	 */
+	async sendCode(dbContext: DatabaseContext, person: PersonRow, config: Config): Promise<RateLimitDecision> {
+		const decision = await this.rateLimiter.consume(dbContext, RateLimitScopes.emailOtpPerPerson, person.id, config)
+		if (!decision.ok) {
+			return decision
+		}
+		const code = await this.generateCode()
+		// Only the latest emailed code may ever verify.
+		await dbContext.commandBus.execute(new InvalidateEmailOtpTokensCommand(person.id))
+		await dbContext.commandBus.execute(new SaveEmailOtpTokenCommand(person.id, code, EMAIL_OTP_EXPIRATION_MINUTES))
+		await this.mailer.sendEmailOtpEmail(dbContext, {
+			email: person.email ?? '',
+			code,
+		}, {
+			variant: '',
+			projectId: null,
+		})
+		return decision
+	}
+
+	/**
+	 * Fetches the latest unused email-OTP token for the person and validates the
+	 * supplied code via the shared `'otp'` path; on success, consumes (invalidates)
+	 * the token. Returns whether the code was accepted.
+	 *
+	 * The per-code attempt budget is reserved up front via {@link ClaimOtpAttemptCommand}
+	 * — a single conditional UPDATE that increments `otp_attempts` only while it is
+	 * still below {@link MAX_OTP_ATTEMPTS}. Because that UPDATE serializes concurrent
+	 * writers on the row, N parallel guesses can never collectively exceed the cap;
+	 * a plain read-then-increment let them all pass with a stale counter.
+	 */
+	async verifyAndConsume(dbContext: DatabaseContext, person: PersonRow, code: string): Promise<boolean> {
+		const tokenResult = await dbContext.queryHandler.fetch(PersonTokenQuery.latestUnusedByPerson(person.id, 'mfa_email_otp'))
+		if (!tokenResult) {
+			return false
+		}
+		// Atomically reserve a guess slot before comparing the code. A false result
+		// means the token was already used/replaced or the attempt cap is exhausted.
+		const reserved = await dbContext.commandBus.execute(new ClaimOtpAttemptCommand(tokenResult.id, MAX_OTP_ATTEMPTS))
+		if (!reserved) {
+			return false
+		}
+		// otp_hash and expires_at are immutable for a token, so validating against the
+		// pre-claim snapshot is correct; the attempt has already been counted.
+		const validation = validateToken({
+			entry: tokenResult,
+			token: code,
+			validationType: 'otp',
+		})
+		if (!validation.ok) {
+			return false
+		}
+		await dbContext.commandBus.execute(new InvalidateTokenCommand(validation.result.id))
+		return true
+	}
+
+	private async generateCode(): Promise<string> {
+		// Rejection-free uniform-ish digits is acceptable here: this is a second factor
+		// behind a valid password, short-lived, and capped at 3 attempts.
+		const bytes = await this.providers.randomBytes(EMAIL_OTP_DIGITS)
+		let code = ''
+		for (let i = 0; i < EMAIL_OTP_DIGITS; i++) {
+			code += (bytes[i] % 10).toString()
+		}
+		return code
+	}
+}

package/src/model/service/EmailValidator.ts

@@ -1,22 +1,21 @@
-import { DatabaseContext } from '../utils'
-import { validateEmail } from '../utils/email'
-import { ResponseError } from '../utils/Response'
-import { PersonQuery } from '../queries'
+import { DatabaseContext } from '../utils/index.js'
+import { validateEmail } from '../utils/email.js'
+import { ResponseError } from '../utils/Response.js'
+import { PersonQuery, PersonRow } from '../queries/index.js'
 
 export class EmailValidator {
 	public async validateEmail(db: DatabaseContext, email: string): Promise<ResponseError<EmailValidatorError> | null> {
 		if (!validateEmail(email.trim())) {
 			return new ResponseError('INVALID_EMAIL_FORMAT', 'E-mail address is not in a valid format')
 		}
-		if (await this.isEmailAlreadyUsed(db, email)) {
+		if (await this.findExistingPerson(db, email) !== null) {
 			return new ResponseError('EMAIL_ALREADY_EXISTS', `User with email ${email} already exists`)
 		}
 		return null
 	}
 
-	private async isEmailAlreadyUsed(db: DatabaseContext, email: string): Promise<boolean> {
-		const personOrNull = await db.queryHandler.fetch(PersonQuery.byEmail(email))
-		return personOrNull !== null
+	public async findExistingPerson(db: DatabaseContext, email: string): Promise<PersonRow | null> {
+		return await db.queryHandler.fetch(PersonQuery.byEmail(email))
 	}
 }
 

package/src/model/service/EmailVerificationManager.ts

@@ -0,0 +1,118 @@
+import { Response, ResponseError, ResponseOk } from '../utils/Response.js'
+import { UserMailer } from '../mailing/index.js'
+import { PersonQuery, PersonRow } from '../queries/index.js'
+import { PermissionContext } from '../authorization/index.js'
+import { ProjectManager } from './ProjectManager.js'
+import { DatabaseContext } from '../utils/index.js'
+import { ImplementationException } from '../../exceptions.js'
+import { getPreferredProject } from './helpers/getPreferredProject.js'
+import { CreatePersonTokenCommand, InvalidateTokenCommand, MarkEmailVerifiedCommand } from '../commands/index.js'
+import { PersonTokenQuery } from '../queries/personToken/PersonTokenQuery.js'
+import { NextMailAttemptQuery } from '../queries/authLog/NextMailAttemptQuery.js'
+import { validateToken } from '../utils/index.js'
+import { PersonToken } from '../type/index.js'
+import { AuthLogService } from './AuthLogService.js'
+
+interface MailOptions {
+	project?: string
+	mailVariant?: string
+}
+
+export class EmailVerificationManager {
+	constructor(
+		private readonly mailer: UserMailer,
+		private readonly projectManager: ProjectManager,
+	) {}
+
+	/**
+	 * Sends a verification mail unless the per-email backoff says to hold off.
+	 * Returns whether a mail was actually sent, so the caller only records an
+	 * `email_verify_init` audit entry for mails that really went out — otherwise
+	 * a throttled attempt would both tell the user to check their inbox and log
+	 * a phantom init that pushes the backoff out further.
+	 */
+	public async sendVerificationEmail(
+		dbContext: DatabaseContext,
+		permissionContext: PermissionContext,
+		person: PersonRow,
+		mailOptions: MailOptions = {},
+	): Promise<boolean> {
+		if (!person.email) {
+			throw new ImplementationException()
+		}
+
+		// Per-email exponential backoff on outbound mails, so a resend button
+		// (or an attacker poking the endpoint) can't be used to flood the
+		// mailbox. Reuses the login_* backoff config against person_auth_log.
+		const retryAfter = await dbContext.queryHandler.fetch(
+			new NextMailAttemptQuery(person.email, 'email_verify_init', 'email_verify_complete'),
+		)
+		if (retryAfter > 0) {
+			return false
+		}
+
+		const result = await dbContext.commandBus.execute(CreatePersonTokenCommand.createEmailVerificationRequest(person.id, person.email))
+		const projects = await this.projectManager.getProjectsByIdentity(dbContext, person.identity_id, permissionContext)
+		const project = getPreferredProject(projects, mailOptions.project ?? null)
+
+		await this.mailer.sendEmailVerificationEmail(
+			dbContext,
+			{
+				email: person.email,
+				token: result.token,
+				project: project?.name,
+				projectSlug: project?.slug,
+			},
+			{
+				variant: mailOptions.mailVariant || '',
+				projectId: project?.id ?? null,
+			},
+		)
+		return true
+	}
+
+	public async verifyEmail(dbContext: DatabaseContext, token: string): Promise<VerifyEmailResponse> {
+		const tokenRow = await dbContext.queryHandler.fetch(PersonTokenQuery.byToken(token, 'email_verification'))
+		const validation = validateToken({ entry: tokenRow, token, validationType: 'token' })
+		if (!validation.ok) {
+			// Carry whatever we know about the subject so the audit log can tie the
+			// failure to a person/token even on an invalid/expired token (matches
+			// PasswordResetManager — see email_verify_complete audit entry).
+			return new ResponseError(validation.error, validation.errorMessage, {
+				[AuthLogService.Key]: new AuthLogService.Bag(
+					tokenRow ? { personId: tokenRow.person_id, tokenId: tokenRow.id } : {},
+				),
+			})
+		}
+		const authLogData = new AuthLogService.Bag({
+			personId: validation.result.person_id,
+			tokenId: validation.result.id,
+		})
+		const person = await dbContext.queryHandler.fetch(PersonQuery.byId(validation.result.person_id))
+		if (!person) {
+			throw new ImplementationException()
+		}
+		// Bind the token to the address it was issued for: if the person's e-mail
+		// changed after the token was minted (an admin profile edit, or a separate
+		// email-change flow), a stale verification link must not stamp the new,
+		// unproven address as verified. Tokens issued before this binding carry no
+		// email payload — fall back to the legacy behaviour for those.
+		const issuedFor = validation.result.meta?.email
+		if (issuedFor != null && issuedFor !== person.email) {
+			return new ResponseError('TOKEN_INVALID', 'Verification token was issued for a different e-mail address', {
+				[AuthLogService.Key]: authLogData,
+			})
+		}
+		return await dbContext.transaction(async db => {
+			await db.commandBus.execute(new InvalidateTokenCommand(validation.result.id))
+			await db.commandBus.execute(new MarkEmailVerifiedCommand(validation.result.person_id))
+			return new ResponseOk({ [AuthLogService.Key]: authLogData })
+		})
+	}
+}
+
+export type VerifyEmailResponse = Response<
+	{ [AuthLogService.Key]: AuthLogService.Bag },
+	PersonToken.TokenValidationError,
+	{ [AuthLogService.Key]: AuthLogService.Bag }
+>

package/src/model/service/GlobalRoleValidator.ts

@@ -0,0 +1,30 @@
+import { LockType } from '@contember/database'
+import { BUILTIN_TENANT_ROLES, GLOBALLY_ASSIGNABLE_BUILTIN_ROLES } from '../authorization/CustomRolePermissions.js'
+import { CustomRolesQuery } from '../queries/index.js'
+import { DatabaseContext } from '../utils/index.js'
+
+export class GlobalRoleValidator {
+	async findInvalidRole(
+		db: DatabaseContext,
+		roles: readonly string[],
+		additionallyActiveRoles: ReadonlySet<string> = new Set(),
+	): Promise<string | null> {
+		const invalidBuiltin = roles.find(role => BUILTIN_TENANT_ROLES.has(role) && !GLOBALLY_ASSIGNABLE_BUILTIN_ROLES.has(role))
+		if (invalidBuiltin !== undefined) {
+			return invalidBuiltin
+		}
+		const customCandidates = [
+			...new Set(
+				roles.filter(role => !BUILTIN_TENANT_ROLES.has(role) && !additionallyActiveRoles.has(role)),
+			),
+		].sort()
+		if (customCandidates.length === 0) {
+			return null
+		}
+		const customRoles = await db.queryHandler.fetch(
+			new CustomRolesQuery({ slugs: customCandidates, lock: LockType.forShare }),
+		)
+		const existingSlugs = new Set(customRoles.map(role => role.slug))
+		return customCandidates.find(role => !existingSlugs.has(role)) ?? null
+	}
+}

package/src/model/service/HibpChecker.ts

@@ -0,0 +1,59 @@
+import { createHash } from 'node:crypto'
+
+/**
+ * Looks up a password in the Have-I-Been-Pwned passwords corpus using its
+ * k-anonymity API: the client sends only the first 5 hex chars of the SHA-1
+ * hash, the server returns all matching suffixes plus counts.
+ *
+ * https://haveibeenpwned.com/API/v3#PwnedPasswords
+ *
+ * Implementations are expected to be fail-open: when the upstream is down or
+ * misbehaves, `isCompromised` should resolve to `false`, never throw.
+ */
+export interface HibpChecker {
+	isCompromised(password: string): Promise<boolean>
+}
+
+export class HttpHibpChecker implements HibpChecker {
+	constructor(
+		private readonly endpoint: string = 'https://api.pwnedpasswords.com/range/',
+		private readonly fetchImpl: typeof fetch = fetch,
+		private readonly timeoutMs: number = 1500,
+	) {}
+
+	async isCompromised(password: string): Promise<boolean> {
+		const sha1 = createHash('sha1').update(password, 'utf8').digest('hex').toUpperCase()
+		const prefix = sha1.slice(0, 5)
+		const suffix = sha1.slice(5)
+		const controller = new AbortController()
+		const timer = setTimeout(() => controller.abort(), this.timeoutMs)
+		try {
+			const response = await this.fetchImpl(`${this.endpoint}${prefix}`, {
+				headers: { 'Add-Padding': 'true' },
+				signal: controller.signal,
+			})
+			if (!response.ok) {
+				return false
+			}
+			const body = await response.text()
+			for (const line of body.split('\n')) {
+				const [hashSuffix, countStr] = line.trim().split(':')
+				if (hashSuffix === suffix && Number(countStr) > 0) {
+					return true
+				}
+			}
+			return false
+		} catch {
+			return false
+		} finally {
+			clearTimeout(timer)
+		}
+	}
+}
+
+/** Disabled checker — used when HIBP integration is turned off in tenant config. */
+export class NoopHibpChecker implements HibpChecker {
+	async isCompromised(_password: string): Promise<boolean> {
+		return false
+	}
+}