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

package/src/model/service/PasswordlessSignInManager.ts

@@ -1,32 +1,42 @@
-import { ApiKeyManager } from './apiKey'
-import { ConfigurationQuery, PersonQuery, PersonRow } from '../queries'
-import { Response, ResponseError, ResponseOk } from '../utils/Response'
+import { ApiKeyManager } from './apiKey/index.js'
+import { ConfigurationQuery, PersonQuery, PersonRow } from '../queries/index.js'
+import { Response, ResponseError, ResponseOk } from '../utils/Response.js'
 import {
 	ActivatePasswordlessOtpErrorCode,
-	ConfigPolicy,
 	InitSignInPasswordlessErrorCode,
 	InitSignInPasswordlessResult,
 	SignInPasswordlessErrorCode,
-} from '../../schema'
-import { DatabaseContext, validateToken } from '../utils'
-import { UserMailer } from '../mailing'
-import { ActivateOtpCommand, CreatePersonTokenCommand, IncreaseOtpAttemptCommand, InvalidateTokenCommand } from '../commands'
-import { getPreferredProject } from './helpers/getPreferredProject'
-import { ProjectManager } from './ProjectManager'
-import { PermissionContext } from '../authorization'
-import { PersonTokenQuery } from '../queries/personToken/PersonTokenQuery'
-import { ImplementationException } from '../../exceptions'
-import { OtpAuthenticator } from './OtpAuthenticator'
-import { PersonToken } from '../type'
-import { AuthLogService } from './AuthLogService'
-import { intervalToSeconds } from '../utils/interval'
+} from '../../schema/index.js'
+import { DatabaseContext, validateToken } from '../utils/index.js'
+import { UserMailer } from '../mailing/index.js'
+import {
+	ActivateOtpCommand,
+	ApiKeyRequestInfo,
+	CreatePersonTokenCommand,
+	IncreaseOtpAttemptCommand,
+	InvalidateTokenCommand,
+	MarkEmailVerifiedCommand,
+} from '../commands/index.js'
+import { getPreferredProject } from './helpers/getPreferredProject.js'
+import { isPasswordlessEnabled } from './helpers/isPasswordlessEnabled.js'
+import { ProjectManager } from './ProjectManager.js'
+import { PermissionContext } from '../authorization/index.js'
+import { PersonTokenQuery } from '../queries/personToken/PersonTokenQuery.js'
+import { ImplementationException } from '../../exceptions.js'
+import { OtpManager } from './OtpManager.js'
+import { BackupCodeManager } from './BackupCodeManager.js'
+import { PersonToken } from '../type/index.js'
+import { AuthLogService } from './AuthLogService.js'
+import { intervalToSeconds } from '../utils/interval.js'
+import { NextMailAttemptQuery } from '../queries/authLog/NextMailAttemptQuery.js'
 
 class PasswordlessSignInManager {
 	constructor(
 		private readonly apiKeyManager: ApiKeyManager,
 		private readonly mailer: UserMailer,
 		private readonly projectManager: ProjectManager,
-		private readonly otpAuthenticator: OtpAuthenticator,
+		private readonly otpManager: OtpManager,
+		private readonly backupCodeManager: BackupCodeManager,
 	) {}
 
 	async initSignInPasswordless({ db, permissionContext, mailVariant, mailProject, email }: {
@@ -37,7 +47,7 @@ class PasswordlessSignInManager {
 		mailProject?: string
 	}): Promise<PasswordlessSignInManager.InitSignInPasswordlessResponse> {
 		return db.transaction(async (db): Promise<PasswordlessSignInManager.InitSignInPasswordlessResponse> => {
-			const configuration = await db.queryHandler.fetch(new ConfigurationQuery())
+			const configuration = await db.queryHandler.fetch(new ConfigurationQuery(db.providers))
 			if (configuration.passwordless.enabled === 'never') {
 				return new ResponseError('PASSWORDLESS_DISABLED', 'Passwordless sign-in is disabled', {
 					[AuthLogService.Key]: new AuthLogService.Bag({}),
@@ -52,7 +62,7 @@ class PasswordlessSignInManager {
 					}),
 				})
 			}
-			if (!this.isEnabled(configuration.passwordless.enabled, person.passwordless_enabled)) {
+			if (!isPasswordlessEnabled(configuration.passwordless.enabled, person.passwordless_enabled)) {
 				return new ResponseError('PASSWORDLESS_DISABLED', 'Passwordless sign-in is disabled for this person', {
 					[AuthLogService.Key]: new AuthLogService.Bag({
 						personInput: email,
@@ -61,6 +71,26 @@ class PasswordlessSignInManager {
 				})
 			}
 
+			// Per-email exponential backoff on outbound mails — bound the spam
+			// pressure on a real user even if attackers spray the endpoint.
+			// Reuses login_* backoff config against person_auth_log.
+			const nextAllowed = await db.queryHandler.fetch(
+				new NextMailAttemptQuery(email, 'passwordless_login_init', 'passwordless_login'),
+			)
+			if (nextAllowed > new Date()) {
+				const retryAfterSeconds = Math.max(1, Math.ceil((nextAllowed.getTime() - Date.now()) / 1000))
+				return new ResponseError(
+					'RATE_LIMIT_EXCEEDED',
+					`Too many passwordless sign-in requests for this email. Retry after ${retryAfterSeconds}s.`,
+					{
+						[AuthLogService.Key]: new AuthLogService.Bag({
+							personInput: email,
+							personId: person.id,
+						}),
+					},
+				)
+			}
+
 			const createTokenCommand = CreatePersonTokenCommand.createPasswordlessRequest(
 				person.id,
 				intervalToSeconds(configuration.passwordless.expiration) / 60,
@@ -108,13 +138,16 @@ class PasswordlessSignInManager {
 		return urlObj.toString()
 	}
 
-	async signInPasswordless({ db, expiration, token, requestId, mfaOtp, validationType }: {
+	async signInPasswordless({ db, expiration, token, requestId, mfaOtp, backupCode, validationType, requestInfo, trustForwardedInfo }: {
 		db: DatabaseContext
 		validationType: PersonToken.ValidationType
 		requestId: string
 		token: string
 		mfaOtp?: string
+		backupCode?: string
 		expiration?: number
+		requestInfo?: ApiKeyRequestInfo
+		trustForwardedInfo?: boolean
 	}): Promise<PasswordlessSignInManager.SignInPasswordlessResponse> {
 		return db.transaction(async (db): Promise<PasswordlessSignInManager.SignInPasswordlessResponse> => {
 			const tokenResult = await db.queryHandler.fetch(PersonTokenQuery.byId(requestId, 'passwordless'))
@@ -152,8 +185,28 @@ class PasswordlessSignInManager {
 				})
 			}
 
-			if (personRow.otp_uri && personRow.otp_activated_at) {
-				if (!mfaOtp) {
+			let usedBackupCode = false
+			if (personRow.otp_secret && personRow.otp_activated_at) {
+				if (mfaOtp) {
+					if (!await this.otpManager.verifyOtp(db, personRow, mfaOtp)) {
+						return new ResponseError('INVALID_OTP_TOKEN', 'OTP token validation has failed', {
+							[AuthLogService.Key]: new AuthLogService.Bag({
+								personId: personRow.id,
+								tokenId: tokenResult?.id,
+							}),
+						})
+					}
+				} else if (backupCode) {
+					if (!await this.backupCodeManager.verifyAndConsume(db, personRow, backupCode)) {
+						return new ResponseError('INVALID_OTP_TOKEN', 'OTP token validation has failed', {
+							[AuthLogService.Key]: new AuthLogService.Bag({
+								personId: personRow.id,
+								tokenId: tokenResult?.id,
+							}),
+						})
+					}
+					usedBackupCode = true
+				} else {
 					return new ResponseError('OTP_REQUIRED', `2FA is enabled. OTP token is required`, {
 						[AuthLogService.Key]: new AuthLogService.Bag({
 							personId: personRow.id,
@@ -161,26 +214,35 @@ class PasswordlessSignInManager {
 						}),
 					})
 				}
-
-				if (!this.otpAuthenticator.validate({ uri: personRow.otp_uri }, mfaOtp)) {
-					return new ResponseError('INVALID_OTP_TOKEN', 'OTP token validation has failed', {
-						[AuthLogService.Key]: new AuthLogService.Bag({
-							personId: personRow.id,
-							tokenId: tokenResult?.id,
-						}),
-					})
-				}
 			}
+			// NOTE: passwordless sign-in does NOT enforce mandatory-MFA enrollment.
+			// A person with no MFA factor is let through even when an auth_policy would
+			// require MFA — enroll-via-sign-in is password-only, and passwordless email
+			// access is itself a possession factor. An existing factor (TOTP/backup
+			// code, handled above) is still verified. Documented limitation (A06).
 
 			await db.commandBus.execute(new InvalidateTokenCommand(tokenValidationResult.result.id))
-			const sessionToken = await this.apiKeyManager.createSessionApiKey(db, personRow.identity_id, expiration)
+			// Receiving and clicking the magic link proves ownership of the address,
+			// so a successful passwordless sign-in also satisfies the e-mail
+			// verification requirement. Without this, a required-but-unverified
+			// account could obtain a session here while being blocked from password
+			// sign-in (SignInManager) — an inconsistent, exploitable gap.
+			const emailVerifiedNow = personRow.email_verified_at === null
+			if (emailVerifiedNow) {
+				await db.commandBus.execute(new MarkEmailVerifiedCommand(personRow.id))
+			}
+			const sessionToken = await this.apiKeyManager.createSessionApiKey(db, personRow.identity_id, expiration, requestInfo, trustForwardedInfo)
 
 			return new ResponseOk({
 				person: personRow,
 				token: sessionToken,
+				usedBackupCode,
 				[AuthLogService.Key]: new AuthLogService.Bag({
 					personId: personRow.id,
 					tokenId: tokenResult?.id,
+					// Record that this sign-in also satisfied e-mail verification, so
+					// the audit trail shows when/how the address became verified.
+					eventData: emailVerifiedNow ? { emailVerified: true } : undefined,
 				}),
 			})
 		})
@@ -221,19 +283,6 @@ class PasswordlessSignInManager {
 			})
 		})
 	}
-
-	private isEnabled(globalValue: ConfigPolicy, personValue: boolean | null): boolean {
-		switch (globalValue) {
-			case 'always':
-				return true
-			case 'never':
-				return false
-			case 'optIn':
-				return personValue === true
-			case 'optOut':
-				return personValue !== false
-		}
-	}
 }
 
 namespace PasswordlessSignInManager {
@@ -250,6 +299,8 @@ namespace PasswordlessSignInManager {
 	interface SignInPasswordlessResult {
 		readonly person: PersonRow
 		readonly token: string
+		/** True when MFA was satisfied by consuming a backup code (instead of a TOTP token). */
+		readonly usedBackupCode?: boolean
 		[AuthLogService.Key]: AuthLogService.Bag
 	}
 	export type SignInPasswordlessResponse = Response<SignInPasswordlessResult, SignInPasswordlessErrorCode, {

package/src/model/service/PersonAccessManager.ts

@@ -1,9 +1,9 @@
-import { PersonQuery, PersonRow } from '../queries'
-import { DatabaseContext } from '../utils'
-import { DisablePersonCommand } from '../commands/person/DisablePersonCommand'
-import { ApiKeyManager } from './apiKey'
-import { Response, ResponseError, ResponseOk } from '../utils/Response'
-import { DisablePersonErrorCode } from '../../schema'
+import { PersonQuery, PersonRow } from '../queries/index.js'
+import { DatabaseContext } from '../utils/index.js'
+import { DisablePersonCommand } from '../commands/person/DisablePersonCommand.js'
+import { ApiKeyManager } from './apiKey/index.js'
+import { Response, ResponseError, ResponseOk } from '../utils/Response.js'
+import { DisablePersonErrorCode } from '../../schema/index.js'
 
 class PersonAccessManager {
 	constructor(private readonly apiKeyManager: ApiKeyManager) {}

package/src/model/service/PersonManager.ts

@@ -1,9 +1,10 @@
-import { ChangeProfileCommand, ChangeProfileData } from '../commands/person/ChangeProfileCommand'
-import { Response, ResponseError, ResponseOk } from '../utils/Response'
-import { PersonQuery, PersonRow } from '../queries'
-import { DatabaseContext } from '../utils'
-import { EmailValidator, EmailValidatorError } from './EmailValidator'
-import { TogglePersonPasswordlessCommand } from '../commands'
+import { ChangeProfileCommand, ChangeProfileData } from '../commands/person/ChangeProfileCommand.js'
+import { Response, ResponseError, ResponseOk } from '../utils/Response.js'
+import { PersonListRow, PersonQuery, PersonRow, PersonsQuery, PersonsQueryFilter } from '../queries/index.js'
+import { DatabaseContext } from '../utils/index.js'
+import { EmailValidator, EmailValidatorError } from './EmailValidator.js'
+import { TogglePersonPasswordlessCommand } from '../commands/index.js'
+import { normalizeEmail } from '../utils/email.js'
 
 class PersonManager {
 	constructor(
@@ -17,14 +18,31 @@ class PersonManager {
 		)
 	}
 
+	async listPersons(
+		dbContext: DatabaseContext,
+		filter: PersonsQueryFilter = {},
+		limit?: number | null,
+		offset?: number | null,
+	): Promise<PersonListRow[]> {
+		return await dbContext.queryHandler.fetch(new PersonsQuery(filter, limit, offset))
+	}
+
 	async changeProfile(dbContext: DatabaseContext, person: PersonRow, data: ChangeProfileData): Promise<PersonManager.ProfileChangeResponse> {
-		if (data.email !== undefined && person.email !== data.email) {
-			const validationError = await this.emailValidator.validateEmail(dbContext, data.email)
+		// Compare normalized: a case-/whitespace-only edit is not a real change, so
+		// it neither needs re-validation nor should drop the verified status.
+		const emailChanging = data.email !== undefined && person.email !== normalizeEmail(data.email)
+		if (emailChanging) {
+			const validationError = await this.emailValidator.validateEmail(dbContext, data.email!)
 			if (validationError !== null) {
 				return new ResponseError(validationError.error, validationError.errorMessage)
 			}
 		}
-		await dbContext.commandBus.execute(new ChangeProfileCommand(person.id, data))
+		// On a real e-mail change via the direct path (admin changeProfile, or
+		// changeMyProfile when no verification applies) the new address has not
+		// been proven, so any prior verification no longer holds — clear it. For
+		// verification-required accounts this re-arms the sign-in gate; for the
+		// rest email_verified_at was already null, so it is a harmless no-op.
+		await dbContext.commandBus.execute(new ChangeProfileCommand(person.id, data, emailChanging))
 		return new ResponseOk(null)
 	}
 

package/src/model/service/ProjectManager.ts

@@ -1,15 +1,15 @@
-import { AddProjectMemberCommand, CreateProjectCommand, SetProjectSecretCommand, UpdateProjectCommand } from '../commands'
-import { PermissionContext } from '../authorization'
-import { Project, ProjectInitializer, ProjectWithSecrets } from '../type'
-import { ProjectBySlugQuery, ProjectsByIdentityQuery, ProjectsQuery, ProjectUpdateTimestampQuery } from '../queries'
-import { SecretsManager } from './SecretsManager'
-import { DatabaseContext, TokenHash } from '../utils'
-import { createSetMembershipVariables } from './membershipUtils'
-import { ImplementationException } from '../../exceptions'
+import { AddProjectMemberCommand, CreateProjectCommand, SetProjectSecretCommand, UpdateProjectCommand } from '../commands/index.js'
+import { PermissionContext } from '../authorization/index.js'
+import { Project, ProjectInitializer, ProjectWithSecrets } from '../type/index.js'
+import { ProjectBySlugQuery, ProjectsByIdentityQuery, ProjectsQuery, ProjectUpdateTimestampQuery } from '../queries/index.js'
+import { SecretsManager } from './SecretsManager.js'
+import { DatabaseContext, TokenHash } from '../utils/index.js'
+import { createSetMembershipVariables } from './membershipUtils.js'
+import { ImplementationException } from '../../exceptions.js'
 import { ProjectRole } from '@contember/schema'
-import { ApiKeyService, CreateApiKeyResult } from './apiKey'
-import { Response, ResponseError, ResponseOk } from '../utils/Response'
-import { CreateProjectResponseErrorCode } from '../../schema'
+import { ApiKeyService, CreateApiKeyResult } from './apiKey/index.js'
+import { Response, ResponseError, ResponseOk } from '../utils/Response.js'
+import { CreateProjectResponseErrorCode } from '../../schema/index.js'
 import { Logger } from '@contember/logger'
 
 export class ProjectManager {

package/src/model/service/ProjectMemberManager.ts

@@ -5,15 +5,15 @@ import {
 	RemoveProjectMemberResponse,
 	UpdateProjectMemberCommand,
 	UpdateProjectMemberResponse,
-} from '../commands'
-import { ProjectMembershipByIdentityQuery, ProjectMembersQuery } from '../queries'
-import { AddProjectMemberErrorCode, ProjectMembersInput } from '../../schema'
-import { AccessVerifier, PermissionActions, TenantRole } from '../authorization'
-import { indexListBy, notEmpty } from '../../utils/array'
-import { createSetMembershipVariables } from './membershipUtils'
+} from '../commands/index.js'
+import { ProjectMembershipByIdentityQuery, ProjectMembersQuery } from '../queries/index.js'
+import { AddProjectMemberErrorCode, ProjectMembersInput } from '../../schema/index.js'
+import { AccessVerifier, PermissionActions, TenantRole } from '../authorization/index.js'
+import { indexListBy, notEmpty } from '../../utils/array.js'
+import { createSetMembershipVariables } from './membershipUtils.js'
 import { Acl, ProjectRole } from '@contember/schema'
-import { Response } from '../utils/Response'
-import { DatabaseContext } from '../utils'
+import { Response } from '../utils/Response.js'
+import { DatabaseContext } from '../utils/index.js'
 
 export class ProjectMemberManager {
 	async addProjectMember(

package/src/model/service/RateLimiter.ts

@@ -0,0 +1,97 @@
+import { DatabaseContext } from '../utils/index.js'
+import { Providers } from '../providers.js'
+import { Config } from '../type/Config.js'
+import { RateLimitCountQuery } from '../queries/rateLimit/RateLimitCountQuery.js'
+import { RecordRateLimitEventCommand } from '../commands/rateLimit/RecordRateLimitEventCommand.js'
+import { RateLimitScope } from '../type/RateLimit.js'
+import { intervalToSeconds } from '../utils/interval.js'
+
+export interface RateLimitWindow {
+	readonly limit: number
+	readonly window: {/* IPostgresInterval shape */}
+}
+
+export interface RateLimitDecision {
+	readonly ok: boolean
+	readonly retryAfterSeconds?: number
+}
+
+/**
+ * Sliding-window rate limiter backed by the `rate_limit_event` table.
+ *
+ * Cost: one COUNT(*) and (on success) one INSERT per check. The event row is
+ * recorded only when the call passes — denied calls do not extend the window,
+ * matching the spec's "max N successful attempts per window".
+ *
+ * The raw key (IP, email, ...) is hashed with the configured provider so the
+ * raw value is not stored at rest. Note this is pseudonymization, not strong
+ * anonymization: an unsalted SHA-256 of a low-entropy input (e.g. an IPv4
+ * address) is recoverable by brute force, so treat key_hash as sensitive.
+ */
+export class RateLimiter {
+	constructor(
+		private readonly providers: Pick<Providers, 'hash' | 'now'>,
+	) {}
+
+	private hashKey(key: string): Buffer {
+		return this.providers.hash(key, 'sha256')
+	}
+
+	private resolveWindow(scope: RateLimitScope, config: Config): { limit: number; windowSeconds: number } {
+		const r = config.rateLimits
+		switch (scope) {
+			case 'sign_up_per_ip':
+				return { limit: r.signUpPerIp.limit, windowSeconds: intervalToSeconds(r.signUpPerIp.window as any) }
+			case 'login_per_ip':
+				return { limit: r.loginPerIp.limit, windowSeconds: intervalToSeconds(r.loginPerIp.window as any) }
+			case 'password_reset_per_ip':
+				return { limit: r.passwordResetPerIp.limit, windowSeconds: intervalToSeconds(r.passwordResetPerIp.window as any) }
+			case 'passwordless_init_per_ip':
+				return { limit: r.passwordlessInitPerIp.limit, windowSeconds: intervalToSeconds(r.passwordlessInitPerIp.window as any) }
+			case 'email_otp_per_person':
+				return { limit: r.emailOtpPerPerson.limit, windowSeconds: intervalToSeconds(r.emailOtpPerPerson.window as any) }
+			case 'email_verification_per_ip':
+				return { limit: r.emailVerificationPerIp.limit, windowSeconds: intervalToSeconds(r.emailVerificationPerIp.window as any) }
+		}
+	}
+
+	/**
+	 * Check whether the next attempt fits within the configured window without
+	 * recording it. Use {@link record} after a successful gating decision.
+	 */
+	async check(db: DatabaseContext, scope: RateLimitScope, key: string, config: Config): Promise<RateLimitDecision> {
+		const { limit, windowSeconds } = this.resolveWindow(scope, config)
+		if (limit <= 0 || windowSeconds <= 0) {
+			return { ok: true }
+		}
+		const windowStart = new Date(this.providers.now().getTime() - windowSeconds * 1000)
+		const count = await db.queryHandler.fetch(new RateLimitCountQuery(scope, this.hashKey(key), windowStart))
+		if (count < limit) {
+			return { ok: true }
+		}
+		return { ok: false, retryAfterSeconds: windowSeconds }
+	}
+
+	async record(db: DatabaseContext, scope: RateLimitScope, key: string): Promise<void> {
+		await db.commandBus.execute(new RecordRateLimitEventCommand(scope, this.hashKey(key)))
+	}
+
+	/**
+	 * Combined check + record. Returns the decision; only records on success.
+	 *
+	 * Not atomic: the COUNT and the INSERT are separate statements, so under
+	 * concurrent requests for the same key a few attempts beyond the limit can
+	 * slip through (the window is a soft ceiling). That is acceptable for abuse
+	 * mitigation — do not rely on it as a hard quota.
+	 */
+	async consume(db: DatabaseContext, scope: RateLimitScope, key: string | null | undefined, config: Config): Promise<RateLimitDecision> {
+		if (!key) {
+			return { ok: true }
+		}
+		const decision = await this.check(db, scope, key, config)
+		if (decision.ok) {
+			await this.record(db, scope, key)
+		}
+		return decision
+	}
+}

package/src/model/service/RolesManager.ts

@@ -1,7 +1,7 @@
-import { DatabaseContext } from '../utils'
-import { PatchIdentityGlobalRoles } from '../commands'
-import { Response, ResponseError, ResponseOk } from '../utils/Response'
-import { TenantRole } from '../authorization'
+import { DatabaseContext } from '../utils/index.js'
+import { PatchIdentityGlobalRoles } from '../commands/index.js'
+import { Response, ResponseError, ResponseOk } from '../utils/Response.js'
+import { TenantRole } from '../authorization/index.js'
 
 export class RolesManager {
 	async addGlobalRoles(dbContext: DatabaseContext, identityId: string, roles: readonly string[]): Promise<Response<null, GlobalRolesErrorCode>> {

package/src/model/service/SecretsManager.ts

@@ -1,7 +1,7 @@
-import { SetProjectSecretCommand, UpdateProjectCommand } from '../commands'
-import { Providers } from '../providers'
-import { ProjectSecretsQuery } from '../queries'
-import { DatabaseContext } from '../utils'
+import { SetProjectSecretCommand, UpdateProjectCommand } from '../commands/index.js'
+import { Providers } from '../providers.js'
+import { ProjectSecretInfoRow, ProjectSecretKeysQuery, ProjectSecretsQuery } from '../queries/index.js'
+import { DatabaseContext } from '../utils/index.js'
 
 export class SecretsManager {
 	constructor(private providers: Providers) {}
@@ -10,6 +10,11 @@ export class SecretsManager {
 		await this.setSecrets(dbContext, projectId, [{ key, value: Buffer.from(value) }])
 	}
 
+	/** Lists secret keys (with timestamps) without decrypting any values. */
+	public async listSecretKeys(dbContext: DatabaseContext, projectId: string): Promise<ProjectSecretInfoRow[]> {
+		return await dbContext.queryHandler.fetch(new ProjectSecretKeysQuery(projectId))
+	}
+
 	public async readSecrets(dbContext: DatabaseContext, projectId: string): Promise<Record<string, string>> {
 		const result = await dbContext.queryHandler.fetch(new ProjectSecretsQuery(projectId, this.providers))
 		const forUpdate = result.filter(it => it.needsReEncrypt)