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

package/src/model/mailing/UserMailer.ts

@@ -1,12 +1,19 @@
-import { Mailer, TemplateRenderer } from '../../utils'
-import NewUserInvited from './templates/NewUserInvited.mustache'
-import ExistingUserInvited from './templates/ExistingUserInvited.mustache'
-import PasswordReset from './templates/PasswordReset.mustache'
-import PasswordlessSignIn from './templates/PasswordlessSignIn.mustache'
-import { MailTemplateData, MailTemplateIdentifier, MailType } from './type'
-import { MailTemplateQuery } from '../queries'
-import Layout from './templates/Layout.mustache'
-import { DatabaseContext } from '../utils'
+import { Mailer, TemplateRenderer } from '../../utils/index.js'
+import NewUserInvited from './templates/NewUserInvited.mustache.js'
+import ExistingUserInvited from './templates/ExistingUserInvited.mustache.js'
+import PasswordReset from './templates/PasswordReset.mustache.js'
+import PasswordlessSignIn from './templates/PasswordlessSignIn.mustache.js'
+import EmailOtp from './templates/EmailOtp.mustache.js'
+import ForcedSignOut from './templates/ForcedSignOut.mustache.js'
+import BackupCodesExhausted from './templates/BackupCodesExhausted.mustache.js'
+import EmailVerification from './templates/EmailVerification.mustache.js'
+import EmailChangeVerify from './templates/EmailChangeVerify.mustache.js'
+import EmailChangeNotify from './templates/EmailChangeNotify.mustache.js'
+import UnusualLogin from './templates/UnusualLogin.mustache.js'
+import { MailTemplateData, MailTemplateIdentifier, MailType } from './type.js'
+import { MailTemplateQuery } from '../queries/index.js'
+import Layout from './templates/Layout.mustache.js'
+import { DatabaseContext } from '../utils/index.js'
 import { Acl } from '@contember/schema'
 
 export class UserMailer {
@@ -64,6 +71,62 @@ export class UserMailer {
 		await this.sendMail(templateId, template, mailArguments)
 	}
 
+	async sendForcedSignOutEmail(
+		dbContext: DatabaseContext,
+		mailArguments: { email: string; reason: string | null },
+		customMailOptions: { projectId: string | null; variant: string },
+	): Promise<void> {
+		const templateId = { type: MailType.forcedSignOut, ...customMailOptions }
+		const template = (await this.getCustomTemplate(dbContext, templateId)) || {
+			subject: 'Your sessions have been signed out',
+			content: ForcedSignOut,
+			replyTo: null,
+		}
+		await this.sendMail(templateId, template, mailArguments)
+	}
+
+	async sendEmailVerificationEmail(
+		dbContext: DatabaseContext,
+		mailArguments: { email: string; token: string; project?: string; projectSlug?: string },
+		customMailOptions: { projectId: string | null; variant: string },
+	): Promise<void> {
+		const templateId = { type: MailType.emailVerification, ...customMailOptions }
+		const template = (await this.getCustomTemplate(dbContext, templateId)) || {
+			subject: 'Verify your e-mail address',
+			content: EmailVerification,
+			replyTo: null,
+		}
+		await this.sendMail(templateId, template, mailArguments)
+	}
+
+	async sendEmailChangeVerifyEmail(
+		dbContext: DatabaseContext,
+		mailArguments: { email: string; token: string; project?: string; projectSlug?: string },
+		customMailOptions: { projectId: string | null; variant: string },
+	): Promise<void> {
+		const templateId = { type: MailType.emailChangeVerify, ...customMailOptions }
+		const template = (await this.getCustomTemplate(dbContext, templateId)) || {
+			subject: 'Confirm your new e-mail address',
+			content: EmailChangeVerify,
+			replyTo: null,
+		}
+		await this.sendMail(templateId, template, mailArguments)
+	}
+
+	async sendEmailChangeNotifyEmail(
+		dbContext: DatabaseContext,
+		mailArguments: { email: string; newEmail: string; project?: string; projectSlug?: string },
+		customMailOptions: { projectId: string | null; variant: string },
+	): Promise<void> {
+		const templateId = { type: MailType.emailChangeNotify, ...customMailOptions }
+		const template = (await this.getCustomTemplate(dbContext, templateId)) || {
+			subject: 'Your e-mail address was changed',
+			content: EmailChangeNotify,
+			replyTo: null,
+		}
+		await this.sendMail(templateId, template, mailArguments)
+	}
+
 	async sendPasswordlessEmail(
 		dbContext: DatabaseContext,
 		mailArguments: { email: string; token: string; project?: string; projectSlug?: string; url?: string; requestId: string },
@@ -78,6 +141,48 @@ export class UserMailer {
 		await this.sendMail(templateId, template, mailArguments)
 	}
 
+	async sendEmailOtpEmail(
+		dbContext: DatabaseContext,
+		mailArguments: { email: string; code: string; project?: string; projectSlug?: string },
+		customMailOptions: { projectId: string | null; variant: string },
+	): Promise<void> {
+		const templateId = { type: MailType.emailOtp, ...customMailOptions }
+		const template = (await this.getCustomTemplate(dbContext, templateId)) || {
+			subject: 'Your verification code',
+			content: EmailOtp,
+			replyTo: null,
+		}
+		await this.sendMail(templateId, template, mailArguments)
+	}
+
+	async sendBackupCodesExhaustedEmail(
+		dbContext: DatabaseContext,
+		mailArguments: { email: string },
+		customMailOptions: { projectId: string | null; variant: string },
+	): Promise<void> {
+		const templateId = { type: MailType.backupCodesExhausted, ...customMailOptions }
+		const template = (await this.getCustomTemplate(dbContext, templateId)) || {
+			subject: 'You have no MFA backup codes left',
+			content: BackupCodesExhausted,
+			replyTo: null,
+		}
+		await this.sendMail(templateId, template, mailArguments)
+	}
+
+	async sendUnusualLoginEmail(
+		dbContext: DatabaseContext,
+		mailArguments: { email: string; geoCountry: string | null; ipAddress: string | null },
+		customMailOptions: { projectId: string | null; variant: string },
+	): Promise<void> {
+		const templateId = { type: MailType.unusualLogin, ...customMailOptions }
+		const template = (await this.getCustomTemplate(dbContext, templateId)) || {
+			subject: 'Unusual sign-in to your account',
+			content: UnusualLogin,
+			replyTo: null,
+		}
+		await this.sendMail(templateId, template, mailArguments)
+	}
+
 	private async sendMail(
 		templateId: MailTemplateIdentifier,
 		template: Pick<MailTemplateData, 'subject' | 'content' | 'replyTo'>,

package/src/model/mailing/index.ts

@@ -1,2 +1,2 @@
-export * from './UserMailer'
-export * from './type'
+export * from './UserMailer.js'
+export * from './type.js'

package/src/model/mailing/templates/BackupCodesExhausted.mustache.ts

@@ -0,0 +1,13 @@
+import Layout from './Layout.mustache.js'
+// language=Mustache
+export default Layout(`
+	<p>Hello,</p>
+	<p>
+		you just used the last of your MFA backup codes for your account ({{email}}).
+		You have no backup codes left.
+	</p>
+	<p>
+		To avoid being locked out if you lose access to your authenticator, please
+		sign in and regenerate a new set of backup codes.
+	</p>
+`)

package/src/model/mailing/templates/EmailChangeNotify.mustache.ts

@@ -0,0 +1,10 @@
+import Layout from './Layout.mustache.js'
+// language=Mustache
+export default Layout(`
+	<p>Hello,</p>
+	<p>
+		the e-mail address on your account was changed to {{newEmail}}.<br>
+		If you did not make this change, contact support immediately — your account
+		may have been compromised.
+	</p>
+`)

package/src/model/mailing/templates/EmailChangeVerify.mustache.ts

@@ -0,0 +1,12 @@
+import Layout from './Layout.mustache.js'
+// language=Mustache
+export default Layout(`
+	<p>Hello,</p>
+	<p>
+		a change of the e-mail address on your account to {{email}} was requested.<br>
+		To confirm this new address, copy &amp; paste the following token and follow
+		the instructions in the e-mail change interface:<br>
+		<code>{{token}}</code>
+	</p>
+	<p>If you did not request this change, you can ignore this e-mail.</p>
+`)

package/src/model/mailing/templates/EmailOtp.mustache.ts

@@ -0,0 +1,13 @@
+import Layout from './Layout.mustache.js'
+// language=Mustache
+export default Layout(`
+	<p>Hello,</p>
+	<p>
+		a sign-in to your account ({{email}}) requires a one-time verification code:
+	</p>
+	<p style="font-size: 24px; font-weight: bold; letter-spacing: 4px;">{{code}}</p>
+	<p>
+		Enter this code to finish signing in. It expires shortly. If you did not try to
+		sign in, you can safely ignore this email.
+	</p>
+`)

package/src/model/mailing/templates/EmailVerification.mustache.ts

@@ -0,0 +1,10 @@
+import Layout from './Layout.mustache.js'
+// language=Mustache
+export default Layout(`
+	<p>Hello,</p>
+	<p>
+		please confirm your e-mail address ({{email}}):<br>
+		Copy &amp; paste the following token and follow the instructions in the e-mail verification interface:<br>
+		<code>{{token}}</code>
+	</p>
+`)

package/src/model/mailing/templates/ExistingUserInvited.mustache.ts

@@ -1,4 +1,4 @@
-import Layout from './Layout.mustache'
+import Layout from './Layout.mustache.js'
 // language=Mustache
 export default Layout(`
 	<p>Hello,<br> you have been invited to contribute on project {{project}}.</p>

package/src/model/mailing/templates/ForcedSignOut.mustache.ts

@@ -0,0 +1,10 @@
+import Layout from './Layout.mustache.js'
+// language=Mustache
+export default Layout(`
+	<p>Hello,</p>
+	<p>
+		All your active sessions for {{email}} were signed out by an administrator.
+		{{#reason}}<br>Reason: {{reason}}{{/reason}}
+	</p>
+	<p>If you believe this was a mistake, please contact your administrator.</p>
+`)

package/src/model/mailing/templates/NewUserInvited.mustache.ts

@@ -1,4 +1,4 @@
-import Layout from './Layout.mustache'
+import Layout from './Layout.mustache.js'
 // language=Mustache
 export default Layout(`
 	<p>Hello,<br>you have been invited to contribute on project {{project}}.</p>

package/src/model/mailing/templates/PasswordReset.mustache.ts

@@ -1,4 +1,4 @@
-import Layout from './Layout.mustache'
+import Layout from './Layout.mustache.js'
 // language=Mustache
 export default Layout(`
 	<p>Hello,</p>

package/src/model/mailing/templates/PasswordlessSignIn.mustache.ts

@@ -1,4 +1,4 @@
-import Layout from './Layout.mustache'
+import Layout from './Layout.mustache.js'
 // language=Mustache
 export default Layout(`
 	<p>Hello,</p>

package/src/model/mailing/templates/UnusualLogin.mustache.ts

@@ -0,0 +1,17 @@
+import Layout from './Layout.mustache.js'
+// language=Mustache
+export default Layout(`
+	<p>Hello,</p>
+	<p>
+		We noticed a sign-in to your account ({{email}}) that looked unusual.
+	</p>
+	<ul>
+		{{#geoCountry}}<li>Country: {{geoCountry}}</li>{{/geoCountry}}
+		{{#ipAddress}}<li>IP address: {{ipAddress}}</li>{{/ipAddress}}
+	</ul>
+	<p>
+		If this was you, you can safely ignore this message. If you do not
+		recognize this activity, change your password as soon as possible and
+		review your active sessions.
+	</p>
+`)

package/src/model/mailing/type.ts

@@ -1,10 +1,17 @@
-import { MailType as SchemaMailType } from '../../schema'
+import { MailType as SchemaMailType } from '../../schema/index.js'
 
 export enum MailType {
 	existingUserInvited = 'existingUserInvited',
 	newUserInvited = 'newUserInvited',
 	passwordReset = 'passwordReset',
 	passwordlessSignIn = 'passwordlessSignIn',
+	forcedSignOut = 'forcedSignOut',
+	emailOtp = 'emailOtp',
+	backupCodesExhausted = 'backupCodesExhausted',
+	emailVerification = 'emailVerification',
+	emailChangeVerify = 'emailChangeVerify',
+	emailChangeNotify = 'emailChangeNotify',
+	unusualLogin = 'unusualLogin',
 }
 
 export const mailTypeFromSchemaToDb = (type: SchemaMailType): MailType => {
@@ -13,6 +20,13 @@ export const mailTypeFromSchemaToDb = (type: SchemaMailType): MailType => {
 		NEW_USER_INVITED: MailType.newUserInvited,
 		RESET_PASSWORD_REQUEST: MailType.passwordReset,
 		PASSWORDLESS_SIGN_IN: MailType.passwordlessSignIn,
+		FORCED_SIGN_OUT: MailType.forcedSignOut,
+		EMAIL_OTP: MailType.emailOtp,
+		BACKUP_CODES_EXHAUSTED: MailType.backupCodesExhausted,
+		EMAIL_VERIFICATION: MailType.emailVerification,
+		EMAIL_CHANGE_VERIFY: MailType.emailChangeVerify,
+		EMAIL_CHANGE_NOTIFY: MailType.emailChangeNotify,
+		UNUSUAL_LOGIN: MailType.unusualLogin,
 	}[type]
 }
 
@@ -22,6 +36,13 @@ export const mailTypeFromDbToSchema = (type: MailType): SchemaMailType => {
 		[MailType.newUserInvited]: 'NEW_USER_INVITED' as const,
 		[MailType.passwordReset]: 'RESET_PASSWORD_REQUEST' as const,
 		[MailType.passwordlessSignIn]: 'PASSWORDLESS_SIGN_IN' as const,
+		[MailType.forcedSignOut]: 'FORCED_SIGN_OUT' as const,
+		[MailType.emailOtp]: 'EMAIL_OTP' as const,
+		[MailType.backupCodesExhausted]: 'BACKUP_CODES_EXHAUSTED' as const,
+		[MailType.emailVerification]: 'EMAIL_VERIFICATION' as const,
+		[MailType.emailChangeVerify]: 'EMAIL_CHANGE_VERIFY' as const,
+		[MailType.emailChangeNotify]: 'EMAIL_CHANGE_NOTIFY' as const,
+		[MailType.unusualLogin]: 'UNUSUAL_LOGIN' as const,
 	}[type]
 }
 

package/src/model/providers.ts

@@ -10,4 +10,12 @@ export interface Providers {
 
 	encrypt: (value: Buffer) => Promise<{ value: Buffer; version: number }>
 	decrypt: (value: Buffer, version: number) => Promise<{ value: Buffer; needsReEncrypt: boolean }>
+	/**
+	 * Whether an encryption key is configured. When false, `encrypt` throws, so
+	 * secrets that can fall back to plaintext-at-rest (TOTP) must do so (version 0),
+	 * preserving pre-encryption behavior on deployments without a key. For the same
+	 * reason, token-bearing IdP sessions are skipped when no key is configured, since
+	 * refresh tokens must be encrypted at rest and must never be stored in plaintext.
+	 */
+	encryptionEnabled: boolean
 }

package/src/model/queries/apiKey/ApiKeyListQuery.ts

@@ -0,0 +1,67 @@
+import { DatabaseQuery, DatabaseQueryable, Operator, SelectBuilder } from '@contember/database'
+import { ApiKey } from '../../type/index.js'
+
+export interface ApiKeyListRow {
+	readonly id: string
+	readonly type: ApiKey.Type
+	readonly disabled_at: Date | null
+	readonly created_at: Date
+	readonly last_used_at: Date | null
+	readonly expires_at: Date | null
+	readonly identity_id: string
+	readonly description: string | null
+}
+
+const baseApiKeyListQuery = () =>
+	SelectBuilder.create<ApiKeyListRow>()
+		.select(['api_key', 'id'])
+		.select(['api_key', 'type'])
+		.select(['api_key', 'disabled_at'])
+		.select(['api_key', 'created_at'])
+		.select(['api_key', 'last_used_at'])
+		.select(['api_key', 'expires_at'])
+		.select(['api_key', 'identity_id'])
+		.select(['identity', 'description'])
+		.from('api_key')
+		.join('identity', 'identity', on => on.columnsEq(['api_key', 'identity_id'], ['identity', 'id']))
+		// Only integration keys — SESSION tokens are sign-in sessions (see Identity.sessions),
+		// ONE_OFF are sign-up artifacts; neither belongs in a key-management listing.
+		.where(it => it.compare(['api_key', 'type'], Operator.eq, ApiKey.Type.PERMANENT))
+		.orderBy(['api_key', 'created_at'], 'desc')
+
+/** Permanent API keys whose identity is a member of the given project. */
+export class ProjectApiKeysQuery extends DatabaseQuery<ApiKeyListRow[]> {
+	constructor(private readonly projectId: string) {
+		super()
+	}
+
+	async fetch({ db }: DatabaseQueryable): Promise<ApiKeyListRow[]> {
+		return await baseApiKeyListQuery()
+			.where(it =>
+				it.exists(qb =>
+					qb
+						.from('project_membership')
+						.where(expr => expr.columnsEq(['project_membership', 'identity_id'], ['api_key', 'identity_id']))
+						.where({ project_id: this.projectId })
+				)
+			)
+			.getResult(db)
+	}
+}
+
+/** Permanent API keys whose identity has no project membership — i.e. global keys from createGlobalApiKey. */
+export class GlobalApiKeysQuery extends DatabaseQuery<ApiKeyListRow[]> {
+	async fetch({ db }: DatabaseQueryable): Promise<ApiKeyListRow[]> {
+		return await baseApiKeyListQuery()
+			.where(it =>
+				it.not(not =>
+					not.exists(qb =>
+						qb
+							.from('project_membership')
+							.where(expr => expr.columnsEq(['project_membership', 'identity_id'], ['api_key', 'identity_id']))
+					)
+				)
+			)
+			.getResult(db)
+	}
+}

package/src/model/queries/apiKey/ApiKeyQuery.ts

@@ -1,6 +1,8 @@
-import { DatabaseQuery, DatabaseQueryable, Operator, SelectBuilder } from '@contember/database'
-import { ApiKey } from '../../type'
-import { computeTokenHash } from '../../utils'
+import { DatabaseQuery, DatabaseQueryable, Literal, Operator, SelectBuilder } from '@contember/database'
+import { ApiKey } from '../../type/index.js'
+import { computeTokenHash } from '../../utils/index.js'
+import { IPostgresInterval } from 'postgres-interval'
+import { PROLONG_THROTTLE_MS } from '../../commands/apiKey/ProlongApiKeyCommand.js'
 
 export class ApiKeyByIdQuery extends DatabaseQuery<null | ApiKeyRow> {
 	constructor(private readonly apiKeyId: string) {
@@ -42,6 +44,17 @@ export type ApiKeyRow = {
 	readonly expiration: number | null
 	readonly roles: string[]
 	readonly person_id: string | null
+	readonly last_ip: string | null
+	readonly last_user_agent: string | null
+	readonly last_used_at: Date | null
+	readonly trust_forwarded_info: boolean
+	readonly issued_at: Date | null
+	readonly idle_timeout: IPostgresInterval | null
+	readonly max_expires_at: Date | null
+	/** Time gates computed on the DB clock (against NOW()) so app/DB skew can't weaken them. */
+	readonly is_expired: boolean
+	readonly is_max_expired: boolean
+	readonly is_idle_expired: boolean
 }
 
 const apiKeyBaseQuery = SelectBuilder.create<null | ApiKeyRow>()
@@ -53,6 +66,24 @@ const apiKeyBaseQuery = SelectBuilder.create<null | ApiKeyRow>()
 	.select(['identity', 'roles'])
 	.select(['api_key', 'expiration'])
 	.select(['person', 'id'], 'person_id')
+	.select(['api_key', 'last_ip'])
+	.select(['api_key', 'last_user_agent'])
+	.select(['api_key', 'last_used_at'])
+	.select(['api_key', 'trust_forwarded_info'])
+	.select(['api_key', 'issued_at'])
+	.select(['api_key', 'idle_timeout'])
+	.select(['api_key', 'max_expires_at'])
+	// A19 time gates on the DB clock — see ApiKeyManager.verifyAndProlong / CLAUDE.md.
+	.select(new Literal('"api_key"."expires_at" is not null and "api_key"."expires_at" <= now()'), 'is_expired')
+	.select(new Literal('"api_key"."max_expires_at" is not null and "api_key"."max_expires_at" <= now()'), 'is_max_expired')
+	.select(
+		new Literal(
+			'"api_key"."idle_timeout" is not null and "api_key"."last_used_at" is not null'
+				+ ' and "api_key"."last_used_at" < now() - "api_key"."idle_timeout" - make_interval(secs => ?)',
+			[PROLONG_THROTTLE_MS / 1000],
+		),
+		'is_idle_expired',
+	)
 	.from('api_key')
 	.join('identity', 'identity', joinClause => joinClause.compareColumns(['api_key', 'identity_id'], Operator.eq, ['identity', 'id']))
 	.leftJoin(

package/src/model/queries/apiKey/ApiKeySessionsQuery.ts

@@ -0,0 +1,50 @@
+import { DatabaseQuery, DatabaseQueryable, Operator, SelectBuilder } from '@contember/database'
+import { ApiKey } from '../../type/index.js'
+
+export type ApiKeySessionRow = {
+	readonly id: string
+	readonly created_at: Date
+	readonly expires_at: Date | null
+	readonly last_used_at: Date | null
+	readonly last_ip: string | null
+	readonly last_user_agent: string | null
+	readonly created_ip: string | null
+	readonly created_user_agent: string | null
+	readonly trust_forwarded_info: boolean
+}
+
+export class ApiKeySessionsByIdentityQuery extends DatabaseQuery<readonly ApiKeySessionRow[]> {
+	constructor(
+		private readonly identityId: string,
+	) {
+		super()
+	}
+
+	async fetch({ db }: DatabaseQueryable): Promise<readonly ApiKeySessionRow[]> {
+		const rows = await SelectBuilder.create<ApiKeySessionRow>()
+			.select(['api_key', 'id'])
+			.select(['api_key', 'created_at'])
+			.select(['api_key', 'expires_at'])
+			.select(['api_key', 'last_used_at'])
+			.select(['api_key', 'last_ip'])
+			.select(['api_key', 'last_user_agent'])
+			.select(['api_key', 'created_ip'])
+			.select(['api_key', 'created_user_agent'])
+			.select(['api_key', 'trust_forwarded_info'])
+			.from('api_key')
+			.where(it => it.compare(['api_key', 'identity_id'], Operator.eq, this.identityId))
+			.where(it => it.compare(['api_key', 'type'], Operator.eq, ApiKey.Type.SESSION))
+			.where(it => it.isNull(['api_key', 'disabled_at']))
+			// expires_at compared on the DB clock (NOW()) — see CLAUDE.md.
+			.where(it =>
+				it.or(or =>
+					or.isNull(['api_key', 'expires_at'])
+						.raw('"api_key"."expires_at" > now()')
+				)
+			)
+			.orderBy(['api_key', 'created_at'], 'desc')
+			.getResult(db)
+
+		return rows
+	}
+}

package/src/model/queries/apiKey/index.ts

@@ -1 +1,3 @@
-export * from './ApiKeyQuery'
+export * from './ApiKeyQuery.js'
+export * from './ApiKeyListQuery.js'
+export * from './ApiKeySessionsQuery.js'

package/src/model/queries/authLog/AuthLogQuery.ts

@@ -0,0 +1,112 @@
+import { DatabaseQuery, DatabaseQueryable, Operator, SelectBuilder } from '@contember/database'
+import { JSONValue } from '@contember/schema'
+import { AuthActionType } from '../../type/AuthLog.js'
+
+export type AuthLogEntryRow = {
+	readonly id: string
+	readonly created_at: Date
+	readonly type: AuthActionType
+	readonly success: boolean
+	readonly invoked_by_id: string | null
+	readonly person_id: string | null
+	readonly target_person_id: string | null
+	readonly person_input_identifier: string | null
+	readonly error_code: string | null
+	readonly error_message: string | null
+	readonly ip_address: string | null
+	readonly user_agent: string | null
+	readonly identity_provider_id: string | null
+	readonly metadata: JSONValue | null
+	readonly event_data: JSONValue | null
+}
+
+export type AuthLogFilter = {
+	readonly types?: readonly AuthActionType[]
+	readonly success?: boolean
+	readonly invokedByIdentityId?: string
+	readonly personId?: string
+	readonly targetPersonId?: string
+	readonly personInputIdentifier?: string
+	readonly createdAfter?: Date
+	readonly createdBefore?: Date
+}
+
+const HARD_LIMIT = 500
+const DEFAULT_LIMIT = 100
+
+/**
+ * Reads `person_auth_log`. Returns one row beyond the requested limit when
+ * available so the resolver can set `hasMore` without a separate COUNT(*).
+ * Caller (resolver) is responsible for permission gating — this query does
+ * not enforce any visibility rules.
+ */
+export class AuthLogQuery extends DatabaseQuery<readonly AuthLogEntryRow[]> {
+	constructor(
+		private readonly filter: AuthLogFilter,
+		private readonly pagination: { limit?: number; offset?: number },
+	) {
+		super()
+	}
+
+	async fetch({ db }: DatabaseQueryable): Promise<readonly AuthLogEntryRow[]> {
+		const limit = Math.min(this.pagination.limit ?? DEFAULT_LIMIT, HARD_LIMIT)
+		const offset = Math.max(this.pagination.offset ?? 0, 0)
+
+		let qb = SelectBuilder.create<AuthLogEntryRow>()
+			.select(['person_auth_log', 'id'])
+			.select(['person_auth_log', 'created_at'])
+			.select(['person_auth_log', 'type'])
+			.select(['person_auth_log', 'success'])
+			.select(['person_auth_log', 'invoked_by_id'])
+			.select(['person_auth_log', 'person_id'])
+			.select(['person_auth_log', 'target_person_id'])
+			.select(['person_auth_log', 'person_input_identifier'])
+			.select(['person_auth_log', 'error_code'])
+			.select(['person_auth_log', 'error_message'])
+			.select(['person_auth_log', 'ip_address'])
+			.select(['person_auth_log', 'user_agent'])
+			.select(['person_auth_log', 'identity_provider_id'])
+			.select(['person_auth_log', 'metadata'])
+			.select(['person_auth_log', 'event_data'])
+			.from('person_auth_log')
+			.orderBy(['person_auth_log', 'created_at'], 'desc')
+			.orderBy(['person_auth_log', 'id'], 'desc')
+			.limit(limit + 1, offset)
+
+		const filter = this.filter
+		if (filter.types && filter.types.length > 0) {
+			qb = qb.where(it => it.in(['person_auth_log', 'type'], filter.types as string[]))
+		}
+		if (filter.success !== undefined) {
+			qb = qb.where(it => it.compare(['person_auth_log', 'success'], Operator.eq, filter.success!))
+		}
+		if (filter.invokedByIdentityId !== undefined) {
+			qb = qb.where(it => it.compare(['person_auth_log', 'invoked_by_id'], Operator.eq, filter.invokedByIdentityId!))
+		}
+		if (filter.personId !== undefined) {
+			qb = qb.where(it => it.compare(['person_auth_log', 'person_id'], Operator.eq, filter.personId!))
+		}
+		if (filter.targetPersonId !== undefined) {
+			qb = qb.where(it => it.compare(['person_auth_log', 'target_person_id'], Operator.eq, filter.targetPersonId!))
+		}
+		if (filter.personInputIdentifier !== undefined) {
+			qb = qb.where(it => it.compare(['person_auth_log', 'person_input_identifier'], Operator.eq, filter.personInputIdentifier!))
+		}
+		if (filter.createdAfter !== undefined) {
+			qb = qb.where(it => it.compare(['person_auth_log', 'created_at'], Operator.gte, filter.createdAfter!))
+		}
+		if (filter.createdBefore !== undefined) {
+			qb = qb.where(it => it.compare(['person_auth_log', 'created_at'], Operator.lt, filter.createdBefore!))
+		}
+
+		return await qb.getResult(db)
+	}
+
+	static get hardLimit(): number {
+		return HARD_LIMIT
+	}
+
+	static get defaultLimit(): number {
+		return DEFAULT_LIMIT
+	}
+}