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

package/src/model/commands/person/EnablePersonCommand.ts

@@ -0,0 +1,18 @@
+import { Command } from '../Command.js'
+import { UpdateBuilder } from '@contember/database'
+
+export class EnablePersonCommand implements Command<void> {
+	constructor(private readonly personId: string) {}
+
+	async execute({ db, providers }: Command.Args): Promise<void> {
+		await UpdateBuilder.create()
+			.table('person')
+			.values({
+				disabled_at: null,
+			})
+			.where({
+				id: this.personId,
+			})
+			.execute(db)
+	}
+}

package/src/model/commands/person/MarkEmailVerifiedCommand.ts

@@ -0,0 +1,30 @@
+import { Command } from '../Command.js'
+import { UpdateBuilder } from '@contember/database'
+import { ImplementationException } from '../../../exceptions.js'
+
+/**
+ * Marks the person's current email as verified. When `email` is given the
+ * address is swapped at the same time (email-change confirmation) — the new
+ * address is verified by construction, since the token was delivered to it.
+ */
+export class MarkEmailVerifiedCommand implements Command<void> {
+	constructor(
+		private readonly personId: string,
+		private readonly email?: string,
+	) {}
+
+	async execute({ db, providers }: Command.Args): Promise<void> {
+		const count = await UpdateBuilder.create()
+			.table('person')
+			.where({ id: this.personId })
+			.values({
+				email_verified_at: providers.now(),
+				...(this.email !== undefined ? { email: this.email } : {}),
+			})
+			.execute(db)
+
+		if (count === 0) {
+			throw new ImplementationException()
+		}
+	}
+}

package/src/model/commands/person/ResetPersonMfaCommand.ts

@@ -0,0 +1,36 @@
+import { Command } from '../Command.js'
+import { UpdateBuilder } from '@contember/database'
+
+/**
+ * Admin recovery: clears all of a person's MFA factors so a locked-out user can
+ * re-enroll. Clears the active and pending TOTP slots and disables email OTP in
+ * `person_mfa`, and clears `person.mfa_grace_until`. Backup codes are deleted
+ * separately (DeleteBackupCodesCommand).
+ */
+export class ResetPersonMfaCommand implements Command<void> {
+	constructor(private readonly personId: string) {}
+
+	async execute({ db }: Command.Args): Promise<void> {
+		await UpdateBuilder.create()
+			.table('person_mfa')
+			.where({ person_id: this.personId })
+			.values({
+				totp_secret: null,
+				totp_secret_version: null,
+				totp_activated_at: null,
+				totp_pending_secret: null,
+				totp_pending_version: null,
+				totp_pending_created_at: null,
+				email_otp_enabled: false,
+			})
+			.execute(db)
+
+		await UpdateBuilder.create()
+			.table('person')
+			.where({ id: this.personId })
+			.values({
+				mfa_grace_until: null,
+			})
+			.execute(db)
+	}
+}

package/src/model/commands/person/SetMfaGraceUntilCommand.ts

@@ -0,0 +1,22 @@
+import { Command } from '../Command.js'
+import { Literal, UpdateBuilder } from '@contember/database'
+
+/**
+ * Opens the MFA enrollment grace window by anchoring `person.mfa_grace_until` to
+ * `now() + graceSeconds` on the DATABASE clock, so the gate that reads it back
+ * (`PersonRow.is_in_grace`, evaluated against `now()`) can't be weakened by
+ * app/DB clock skew or skew between engine instances. See engine-tenant-api/CLAUDE.md.
+ */
+export class SetMfaGraceUntilCommand implements Command<void> {
+	constructor(private readonly personId: string, private readonly graceSeconds: number) {}
+
+	async execute({ db }: Command.Args): Promise<void> {
+		await UpdateBuilder.create()
+			.table('person')
+			.where({ id: this.personId })
+			.values({
+				mfa_grace_until: new Literal('now() + make_interval(secs => ?)', [this.graceSeconds]),
+			})
+			.execute(db)
+	}
+}

package/src/model/commands/person/TogglePersonPasswordlessCommand.ts

@@ -1,4 +1,4 @@
-import { Command } from '../Command'
+import { Command } from '../Command.js'
 import { UpdateBuilder } from '@contember/database'
 
 export class TogglePersonPasswordlessCommand implements Command<void> {

package/src/model/commands/person/index.ts

@@ -1,4 +1,7 @@
-export * from './ChangePasswordCommand'
-export * from './CreatePersonCommand'
-export * from './CreatePersonIdentityProviderIdentifierCommand'
-export * from './TogglePersonPasswordlessCommand'
+export * from './ChangePasswordCommand.js'
+export * from './CreatePersonCommand.js'
+export * from './ResetPersonMfaCommand.js'
+export * from './SetMfaGraceUntilCommand.js'
+export * from './CreatePersonIdentityProviderIdentifierCommand.js'
+export * from './MarkEmailVerifiedCommand.js'
+export * from './TogglePersonPasswordlessCommand.js'

package/src/model/commands/personToken/ActivateOtpCommand.ts

@@ -1,6 +1,6 @@
-import { Command } from '../Command'
+import { Command } from '../Command.js'
 import { UpdateBuilder } from '@contember/database'
-import { ImplementationException } from '../../../exceptions'
+import { ImplementationException } from '../../../exceptions.js'
 
 export class ActivateOtpCommand implements Command<void> {
 	constructor(

package/src/model/commands/personToken/ClaimOtpAttemptCommand.ts

@@ -0,0 +1,33 @@
+import { Command } from '../Command.js'
+import { Literal, Operator, UpdateBuilder } from '@contember/database'
+
+/**
+ * Atomically reserves one OTP guess slot for a `person_token`: increments
+ * `otp_attempts` only while the token is still unused and below `maxAttempts`,
+ * and reports whether a slot was actually reserved (affected-row count).
+ *
+ * Unlike a read-then-increment, the conditional UPDATE serializes concurrent
+ * writers on the row (under READ COMMITTED), so parallel guesses can never
+ * collectively exceed `maxAttempts`. A `false` result means the token was already
+ * used/replaced or the per-code attempt cap is exhausted.
+ */
+export class ClaimOtpAttemptCommand implements Command<boolean> {
+	constructor(
+		private readonly id: string,
+		private readonly maxAttempts: number,
+	) {}
+
+	async execute({ db }: Command.Args): Promise<boolean> {
+		const affected = await UpdateBuilder.create()
+			.table('person_token')
+			.values({
+				otp_attempts: new Literal('otp_attempts + 1'),
+			})
+			.where({ id: this.id })
+			.where(expr => expr.isNull('used_at'))
+			.where(expr => expr.compare('otp_attempts', Operator.lt, this.maxAttempts))
+			.execute(db)
+
+		return affected > 0
+	}
+}

package/src/model/commands/personToken/CreatePersonTokenCommand.ts

@@ -1,14 +1,20 @@
-import { Command } from '../Command'
-import { computeTokenHash, generateToken } from '../../utils'
-import { SavePersonTokenCommand } from './SavePersonTokenCommand'
-import { PersonToken } from '../../type'
-import { PASSWORD_RESET_EXPIRATION_MINUTES } from '../../consts/expirations'
+import { Command } from '../Command.js'
+import { computeTokenHash, generateToken } from '../../utils/index.js'
+import { SavePersonTokenCommand } from './SavePersonTokenCommand.js'
+import { PersonToken } from '../../type/index.js'
+import { JSONValue } from '@contember/schema'
+import {
+	EMAIL_CHANGE_EXPIRATION_MINUTES,
+	EMAIL_VERIFICATION_EXPIRATION_MINUTES,
+	PASSWORD_RESET_EXPIRATION_MINUTES,
+} from '../../consts/expirations.js'
 
 export class CreatePersonTokenCommand implements Command<CreatePersonTokenCommand.Result> {
 	private constructor(
 		private readonly personId: string,
 		private readonly type: PersonToken.Type,
 		private readonly expirationMinutes: number,
+		private readonly meta: JSONValue | null = null,
 	) {}
 
 	static createPasswordResetRequest(personId: string, expirationMinutes: number = PASSWORD_RESET_EXPIRATION_MINUTES): CreatePersonTokenCommand {
@@ -19,6 +25,25 @@ export class CreatePersonTokenCommand implements Command<CreatePersonTokenComman
 		return new CreatePersonTokenCommand(personId, 'passwordless', expirationMinutes)
 	}
 
+	static createEmailVerificationRequest(
+		personId: string,
+		email: string,
+		expirationMinutes: number = EMAIL_VERIFICATION_EXPIRATION_MINUTES,
+	): CreatePersonTokenCommand {
+		// Bind the token to the address it was issued for, so it can only verify
+		// that exact e-mail — not whatever the person's current address happens to
+		// be when the link is finally clicked (see EmailVerificationManager.verifyEmail).
+		return new CreatePersonTokenCommand(personId, 'email_verification', expirationMinutes, { email })
+	}
+
+	static createEmailChangeRequest(
+		personId: string,
+		newEmail: string,
+		expirationMinutes: number = EMAIL_CHANGE_EXPIRATION_MINUTES,
+	): CreatePersonTokenCommand {
+		return new CreatePersonTokenCommand(personId, 'email_change', expirationMinutes, { email: newEmail })
+	}
+
 	async execute({ db, providers, bus }: Command.Args): Promise<CreatePersonTokenCommand.Result> {
 		const token = await generateToken(providers)
 		const tokenHash = computeTokenHash(token)
@@ -28,6 +53,7 @@ export class CreatePersonTokenCommand implements Command<CreatePersonTokenComman
 				tokenHash,
 				this.type,
 				this.expirationMinutes,
+				this.meta,
 			),
 		)
 

package/src/model/commands/personToken/IncreaseOtpAttemptCommand.ts

@@ -1,6 +1,6 @@
-import { Command } from '../Command'
+import { Command } from '../Command.js'
 import { Literal, UpdateBuilder } from '@contember/database'
-import { ImplementationException } from '../../../exceptions'
+import { ImplementationException } from '../../../exceptions.js'
 
 export class IncreaseOtpAttemptCommand implements Command<void> {
 	constructor(

package/src/model/commands/personToken/InvalidateEmailOtpTokensCommand.ts

@@ -0,0 +1,21 @@
+import { Command } from '../Command.js'
+import { UpdateBuilder } from '@contember/database'
+
+/**
+ * Marks all still-unused `mfa_email_otp` tokens of a person as used. Called before
+ * issuing a fresh code so only the latest emailed code can ever verify.
+ */
+export class InvalidateEmailOtpTokensCommand implements Command<void> {
+	constructor(private readonly personId: string) {}
+
+	async execute({ db, providers }: Command.Args): Promise<void> {
+		await UpdateBuilder.create()
+			.table('person_token')
+			.where({ person_id: this.personId, type: 'mfa_email_otp' })
+			.where(expr => expr.isNull('used_at'))
+			.values({
+				used_at: providers.now(),
+			})
+			.execute(db)
+	}
+}

package/src/model/commands/personToken/InvalidateTokenCommand.ts

@@ -1,6 +1,6 @@
-import { Command } from '../Command'
+import { Command } from '../Command.js'
 import { UpdateBuilder } from '@contember/database'
-import { ImplementationException } from '../../../exceptions'
+import { ImplementationException } from '../../../exceptions.js'
 
 export class InvalidateTokenCommand implements Command<void> {
 	constructor(private readonly id: string) {}

package/src/model/commands/personToken/ResetPasswordCommand.ts

@@ -1,18 +1,17 @@
-import { Command } from '../Command'
-import { ChangePasswordCommand } from '../person/ChangePasswordCommand'
-import { Response, ResponseOk } from '../../utils/Response'
-import { PersonTokenQuery } from '../../queries/personToken/PersonTokenQuery'
-import { InvalidateTokenCommand } from './InvalidateTokenCommand'
-import { validateToken } from '../../utils'
-import { PersonToken } from '../../type'
+import { Command } from '../Command.js'
+import { ChangePasswordCommand } from '../person/ChangePasswordCommand.js'
+import { Response, ResponseOk } from '../../utils/Response.js'
+import { PersonTokenQuery } from '../../queries/personToken/PersonTokenQuery.js'
+import { InvalidateTokenCommand } from './InvalidateTokenCommand.js'
+import { validateToken } from '../../utils/index.js'
+import { PersonToken } from '../../type/index.js'
 
 export class ResetPasswordCommand implements Command<ResetPasswordCommandResponse> {
 	constructor(private readonly token: string, private readonly password: string) {}
 
-	async execute({ db, providers, bus }: Command.Args): Promise<ResetPasswordCommandResponse> {
-		const now = providers.now()
+	async execute({ db, bus }: Command.Args): Promise<ResetPasswordCommandResponse> {
 		const token = await db.createQueryHandler().fetch(PersonTokenQuery.byToken(this.token, 'password_reset'))
-		const tokenValidationResult = validateToken({ entry: token, token: this.token, now, validationType: 'token' })
+		const tokenValidationResult = validateToken({ entry: token, token: this.token, validationType: 'token' })
 		if (!tokenValidationResult.ok) {
 			return tokenValidationResult
 		}

package/src/model/commands/personToken/SaveEmailOtpTokenCommand.ts

@@ -0,0 +1,50 @@
+import { Command } from '../Command.js'
+import { InsertBuilder, Literal } from '@contember/database'
+import { plusMinutes } from '../../utils/time.js'
+import { computeTokenHash, generateToken, TokenHash } from '../../utils/index.js'
+
+/**
+ * Creates an `mfa_email_otp` person_token carrying a 6-digit code in `otp_hash`.
+ *
+ * Unlike the passwordless flow there is no magic-link step, so the code itself is
+ * the only secret — it is validated via {@link validateToken}'s `'otp'` path. The
+ * `token_hash` column is NOT NULL and UNIQUE, so we still fill it with a random,
+ * never-used token hash to satisfy the schema.
+ */
+export class SaveEmailOtpTokenCommand implements Command<SaveEmailOtpTokenCommand.Result> {
+	constructor(
+		private readonly personId: string,
+		private readonly code: string,
+		private readonly expirationMinutes: number,
+	) {}
+
+	async execute({ db, providers }: Command.Args): Promise<SaveEmailOtpTokenCommand.Result> {
+		const id = providers.uuid()
+		const tokenHash: TokenHash = computeTokenHash(await generateToken(providers))
+		const otpHash = computeTokenHash(this.code)
+		await InsertBuilder.create()
+			.into('person_token')
+			.values({
+				id: id,
+				token_hash: tokenHash,
+				person_id: this.personId,
+				// expires_at on the DATABASE clock — see SavePersonTokenCommand / CLAUDE.md.
+				expires_at: new Literal('now() + make_interval(secs => ?)', [this.expirationMinutes * 60]),
+				created_at: providers.now(),
+				used_at: null,
+				type: 'mfa_email_otp',
+				otp_hash: otpHash,
+			})
+			.execute(db)
+
+		// Display-only approximation; the DB-clock `expires_at` column is authoritative.
+		return { id, expiresAt: plusMinutes(providers.now(), this.expirationMinutes) }
+	}
+}
+
+namespace SaveEmailOtpTokenCommand {
+	export interface Result {
+		id: string
+		expiresAt: Date
+	}
+}

package/src/model/commands/personToken/SavePersonTokenCommand.ts

@@ -1,8 +1,9 @@
-import { Command } from '../Command'
-import { InsertBuilder } from '@contember/database'
-import { plusMinutes } from '../../utils/time'
-import { TokenHash } from '../../utils'
-import { PersonToken } from '../../type'
+import { Command } from '../Command.js'
+import { InsertBuilder, Literal } from '@contember/database'
+import { TokenHash } from '../../utils/index.js'
+import { PersonToken } from '../../type/index.js'
+import { JSONValue } from '@contember/schema'
+import { ImplementationException } from '../../../exceptions.js'
 
 class SavePersonTokenCommand implements Command<SavePersonTokenCommand.Result> {
 	constructor(
@@ -10,25 +11,33 @@ class SavePersonTokenCommand implements Command<SavePersonTokenCommand.Result> {
 		private readonly tokenHash: TokenHash,
 		private readonly type: PersonToken.Type,
 		private readonly expirationMinutes: number,
+		private readonly meta: JSONValue | null = null,
 	) {}
 
 	async execute({ db, providers }: Command.Args): Promise<SavePersonTokenCommand.Result> {
 		const id = providers.uuid()
-		const expiresAt = plusMinutes(providers.now(), this.expirationMinutes)
-		await InsertBuilder.create()
+		const result = await InsertBuilder.create()
 			.into('person_token')
 			.values({
 				id: id,
 				token_hash: this.tokenHash,
+				// expires_at is computed on the DATABASE clock so the expiry gate
+				// (PersonTokenQuery's `is_expired`, evaluated against NOW()) can never be
+				// weakened by app/DB clock skew. created_at stays on the app clock — it is
+				// display/ordering only, never compared. See engine-tenant-api/CLAUDE.md.
 				person_id: this.personId,
-				expires_at: expiresAt,
+				expires_at: new Literal('now() + make_interval(secs => ?)', [this.expirationMinutes * 60]),
 				created_at: providers.now(),
 				used_at: null,
 				type: this.type,
+				meta: this.meta,
 			})
+			.returning<{ expires_at: Date }>('expires_at')
 			.execute(db)
-
-		return { id, expiresAt }
+		if (result.length !== 1) {
+			throw new ImplementationException()
+		}
+		return { id, expiresAt: result[0].expires_at }
 	}
 }
 

package/src/model/commands/personToken/index.ts

@@ -1,6 +1,9 @@
-export * from './ActivateOtpCommand'
-export * from './CreatePersonTokenCommand'
-export * from './InvalidateTokenCommand'
-export * from './IncreaseOtpAttemptCommand'
-export * from './ResetPasswordCommand'
-export * from './SavePersonTokenCommand'
+export * from './ActivateOtpCommand.js'
+export * from './CreatePersonTokenCommand.js'
+export * from './InvalidateTokenCommand.js'
+export * from './InvalidateEmailOtpTokensCommand.js'
+export * from './IncreaseOtpAttemptCommand.js'
+export * from './ClaimOtpAttemptCommand.js'
+export * from './ResetPasswordCommand.js'
+export * from './SavePersonTokenCommand.js'
+export * from './SaveEmailOtpTokenCommand.js'

package/src/model/commands/project/CreateProjectCommand.ts

@@ -1,6 +1,6 @@
 import { InsertBuilder } from '@contember/database'
-import { Command } from '../Command'
-import { Project } from '../../type'
+import { Command } from '../Command.js'
+import { Project } from '../../type/index.js'
 import { ConflictActionType } from '@contember/database'
 
 export class CreateProjectCommand implements Command<string | null> {

package/src/model/commands/project/SetProjectSecretCommand.ts

@@ -1,4 +1,4 @@
-import { Command } from '../Command'
+import { Command } from '../Command.js'
 import { ConflictActionType, InsertBuilder } from '@contember/database'
 
 export class SetProjectSecretCommand implements Command<void> {

package/src/model/commands/project/UpdateProjectCommand.ts

@@ -1,6 +1,6 @@
 import { QueryBuilder, UpdateBuilder } from '@contember/database'
-import { Command } from '../Command'
-import { Project } from '../../type'
+import { Command } from '../Command.js'
+import { Project } from '../../type/index.js'
 
 export class UpdateProjectCommand implements Command<void> {
 	constructor(private projectId: string, private readonly data: Partial<Pick<Project, 'name' | 'config'>>) {}

package/src/model/commands/project/index.ts

@@ -1,3 +1,3 @@
-export * from './CreateProjectCommand'
-export * from './SetProjectSecretCommand'
-export * from './UpdateProjectCommand'
+export * from './CreateProjectCommand.js'
+export * from './SetProjectSecretCommand.js'
+export * from './UpdateProjectCommand.js'

package/src/model/commands/rateLimit/RecordRateLimitEventCommand.ts

@@ -0,0 +1,24 @@
+import { InsertBuilder } from '@contember/database'
+import { Command } from '../Command.js'
+import { RateLimitScope } from '../../type/RateLimit.js'
+
+export class RecordRateLimitEventCommand implements Command<void> {
+	constructor(
+		private readonly scope: RateLimitScope,
+		private readonly keyHash: Buffer,
+	) {}
+
+	async execute({ db, providers }: Command.Args): Promise<void> {
+		// occurred_at is left to its DB default (NOW()) so every rate-limit
+		// timestamp is on the database clock — the same clock the window is counted
+		// against (see RateLimitCountQuery). Never stamp it from the app clock.
+		await InsertBuilder.create()
+			.into('rate_limit_event')
+			.values({
+				id: providers.uuid(),
+				scope: this.scope,
+				key_hash: this.keyHash,
+			})
+			.execute(db)
+	}
+}

package/src/model/commands/rateLimit/index.ts

@@ -0,0 +1 @@
+export * from './RecordRateLimitEventCommand.js'

package/src/model/consts/expirations.ts

@@ -1,2 +1,4 @@
 export const PASSWORD_RESET_EXPIRATION_MINUTES = 60
 export const INVITATION_RESET_TOKEN_EXPIRATION_MINUTES = 60 * 24
+export const EMAIL_VERIFICATION_EXPIRATION_MINUTES = 60 * 24
+export const EMAIL_CHANGE_EXPIRATION_MINUTES = 60 * 24

package/src/model/dtos/Password.ts

@@ -1,4 +1,4 @@
-import { Providers } from '../providers'
+import { Providers } from '../providers.js'
 
 export type MaybePassword = Password | typeof NoPassword
 

package/src/model/dtos/index.ts

@@ -1 +1 @@
-export * from './Password'
+export * from './Password.js'

package/src/model/index.ts

@@ -1,9 +1,9 @@
-export * from './authorization'
-export * from './commands'
-export * from './dtos'
-export * from './queries'
-export * from './mailing'
-export * from './service'
-export * from './type'
-export * from './providers'
-export * from './utils'
+export * from './authorization/index.js'
+export * from './commands/index.js'
+export * from './dtos/index.js'
+export * from './queries/index.js'
+export * from './mailing/index.js'
+export * from './service/index.js'
+export * from './type/index.js'
+export * from './providers.js'
+export * from './utils/index.js'