@contember/engine-tenant-api 2.1.0-beta.1 → 2.2.0-alpha.1

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 nextAllowed = await dbContext.queryHandler.fetch(
+			new NextMailAttemptQuery(normalizedNewEmail, 'email_change_init', 'email_change_complete'),
+		)
+		if (nextAllowed > dbContext.providers.now()) {
+			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, now: dbContext.providers.now(), 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,106 @@
+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,
+			now: this.providers.now(),
+			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 nextAllowed = await dbContext.queryHandler.fetch(
+			new NextMailAttemptQuery(person.email, 'email_verify_init', 'email_verify_complete'),
+		)
+		if (nextAllowed > dbContext.providers.now()) {
+			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, now: dbContext.providers.now(), 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/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
+	}
+}

package/src/model/service/IDPSignInManager.ts

@@ -1,14 +1,16 @@
-import { ApiKeyManager } from './apiKey'
-import { IdentityProviderBySlugQuery, PersonByIdPQuery, PersonQuery, PersonRow } from '../queries'
-import { IDPHandlerRegistry, IDPResponse, IDPResponseError, IDPValidationError } from './idp'
-import { Response, ResponseError, ResponseOk } from '../utils/Response'
-import { InitSignInIdpErrorCode, InitSignInIdpResult, SignInIdpErrorCode } from '../../schema'
-import { DatabaseContext } from '../utils'
-import { CreateIdentityCommand, CreatePersonCommand, CreatePersonIdentityProviderIdentifierCommand } from '../commands'
-import { TenantRole } from '../authorization'
-import { NoPassword } from '../dtos'
-import { IdentityProviderRow } from '../queries/idp/types'
-import { AuthLogService } from './AuthLogService'
+import { ApiKeyManager } from './apiKey/index.js'
+import { IdentityProviderBySlugQuery, PersonByIdPQuery, PersonQuery, PersonRow } from '../queries/index.js'
+import { IDPHandlerRegistry, IDPResponse, IDPResponseError, IDPValidationError } from './idp/index.js'
+import { Response, ResponseError, ResponseOk } from '../utils/Response.js'
+import { InitSignInIdpErrorCode, InitSignInIdpResult, SignInIdpErrorCode } from '../../schema/index.js'
+import { DatabaseContext } from '../utils/index.js'
+import { ApiKeyRequestInfo, CreateIdentityCommand, CreatePersonCommand, CreatePersonIdentityProviderIdentifierCommand } from '../commands/index.js'
+import { CreateIdpSessionCommand } from '../commands/idp/CreateIdpSessionCommand.js'
+import { CreateAuthLogEntryCommand } from '../commands/authLog/CreateAuthLogEntryCommand.js'
+import { TenantRole } from '../authorization/index.js'
+import { NoPassword } from '../dtos/index.js'
+import { IdentityProviderRow } from '../queries/idp/types.js'
+import { AuthLogService } from './AuthLogService.js'
 
 class IDPSignInManager {
 	constructor(
@@ -21,6 +23,8 @@ class IDPSignInManager {
 		idpSlug: string,
 		responseData: unknown,
 		expiration?: number,
+		requestInfo?: ApiKeyRequestInfo,
+		trustForwardedInfo?: boolean,
 	): Promise<IDPSignInManager.SignInIDPResponse> {
 		return dbContext.transaction(async (db): Promise<IDPSignInManager.SignInIDPResponse> => {
 			const provider = await db.queryHandler.fetch(new IdentityProviderBySlugQuery(idpSlug))
@@ -54,14 +58,19 @@ class IDPSignInManager {
 				}
 				throw e
 			}
-			const personRow = await this.resolvePerson(db, claim, provider)
+			const resolved = await this.resolvePerson(db, claim, provider)
+			const personRow = resolved.person
 
 			if (!personRow) {
+				// Keep the external error generic (no account-existence leak), but
+				// record the email-verification gate block distinctly in the audit
+				// log — it is a takeover-grade event, not an ordinary "not found".
 				return new ResponseError('PERSON_NOT_FOUND', `Person ${claim.email} not found`, {
 					[AuthLogService.Key]: new AuthLogService.Bag({
 						identityProviderId: provider.id,
 						personInput: claim.email,
-						personId: undefined,
+						personId: resolved.blockedPersonId,
+						eventData: resolved.blockedReason ? { reason: resolved.blockedReason } : undefined,
 					}),
 				})
 			}
@@ -76,7 +85,46 @@ class IDPSignInManager {
 				})
 			}
 
-			const sessionToken = await this.apiKeyManager.createSessionApiKey(db, personRow.identity_id, expiration)
+			const { id: apiKeyId, token: sessionToken } = await this.apiKeyManager.createSessionApiKeyWithId(
+				db,
+				personRow.identity_id,
+				expiration,
+				requestInfo,
+				trustForwardedInfo,
+			)
+
+			// Bind the federated-session state to this session so it can be re-validated
+			// against the IdP later. Present only when the provider supports it and
+			// revalidation is enabled on the IdP configuration (A24). Refresh tokens must be
+			// encrypted at rest, so when no encryption key is configured we skip persisting a
+			// token-bearing session (it would otherwise crash or store secrets in plaintext) —
+			// the session then behaves like a plain session with no re-validation.
+			if (claim.idpSession) {
+				const hasTokens = !!claim.idpSession.tokens && Object.keys(claim.idpSession.tokens).length > 0
+				if (!hasTokens || db.providers.encryptionEnabled) {
+					await db.commandBus.execute(new CreateIdpSessionCommand(apiKeyId, provider.id, claim.idpSession))
+				} else {
+					// Re-validation is enabled on this IdP but no encryption key is configured, so we
+					// won't store the token-bearing session — it silently degrades to a plain,
+					// non-revalidated session. Audit the downgrade (errorCode `encryption_disabled`)
+					// so the operator can see that a session they expected to be continuously
+					// re-validated is in fact not protected, instead of failing closed at sign-in.
+					await db.commandBus.execute(
+						new CreateAuthLogEntryCommand({
+							type: 'idp_session_revalidation_failed',
+							invokedById: personRow.identity_id,
+							personId: personRow.id,
+							identityProviderId: provider.id,
+							personTokenId: apiKeyId,
+							success: true,
+							errorCode: 'encryption_disabled',
+							ipAddress: requestInfo?.ip,
+							userAgent: requestInfo?.userAgent,
+						}),
+					)
+				}
+			}
+
 			return new ResponseOk({
 				person: personRow,
 				token: sessionToken,
@@ -116,28 +164,40 @@ class IDPSignInManager {
 		}
 	}
 
-	private async resolvePerson(db: DatabaseContext, claim: IDPResponse, provider: IdentityProviderRow): Promise<PersonRow | null> {
+	private async resolvePerson(db: DatabaseContext, claim: IDPResponse, provider: IdentityProviderRow): Promise<IDPSignInManager.ResolvePersonResult> {
 		const personByIdPQuery = new PersonByIdPQuery(provider.id, claim.externalIdentifier)
 		const personByIdp = await db.queryHandler.fetch(personByIdPQuery)
 		if (personByIdp) {
-			return personByIdp
+			return { person: personByIdp }
 		}
 
 		if (!provider.exclusive) {
-			const personByEmail = claim.email ? await db.queryHandler.fetch(PersonQuery.byEmail(claim.email)) : null
+			const personByEmail = typeof claim.email === 'string' && claim.email
+				? await db.queryHandler.fetch(PersonQuery.byEmail(claim.email))
+				: null
 			if (personByEmail) {
+				// Auto-linking an IdP identity to a pre-existing local account by
+				// e-mail is takeover-grade: if the provider returns an unverified
+				// (or attacker-controlled) e-mail, it could hijack the account. When
+				// the provider requires a verified e-mail, refuse to link — and to
+				// sign in — unless the address is asserted verified. `assumeEmailVerified`
+				// lets a trusted IdP that never emits the claim still satisfy the gate.
+				const emailVerified = provider.assumeEmailVerified || claim.emailVerified === true
+				if (provider.requireVerifiedEmail && !emailVerified) {
+					return { person: null, blockedReason: 'idp_email_unverified', blockedPersonId: personByEmail.id }
+				}
 				await this.saveIdpIdentifier(db, provider, claim, personByEmail)
-				return personByEmail
+				return { person: personByEmail }
 			}
 		}
 
 		if (provider.autoSignUp) {
 			const signedUpPerson = await this.signUp(db, claim, provider)
 			await this.saveIdpIdentifier(db, provider, claim, signedUpPerson)
-			return signedUpPerson
+			return { person: signedUpPerson }
 		}
 
-		return null
+		return { person: null }
 	}
 
 	private async signUp(db: DatabaseContext, { email, name, externalIdentifier }: IDPResponse, provider: IdentityProviderRow): Promise<PersonRow> {
@@ -165,6 +225,12 @@ class IDPSignInManager {
 }
 
 namespace IDPSignInManager {
+	export type ResolvePersonResult = {
+		readonly person: PersonRow | null
+		readonly blockedReason?: 'idp_email_unverified'
+		readonly blockedPersonId?: string
+	}
+
 	export type InitSignInIDPResponse = Response<InitSignInIdpResult, InitSignInIdpErrorCode>
 
 	interface SignInIDPResult {