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

package/src/schema/tenant.graphql.ts

@@ -17,12 +17,13 @@ const schema: DocumentNode = gql`
 		me: Identity!
 		personById(id: String!): Person
 		"""
-		List persons across the tenant. SUPER_ADMIN sees every person; otherwise
-		the result is scoped to persons who are members of a project the caller may
-		view members of (i.e. the same persons reachable via \`project.members\`),
-		so a PROJECT_ADMIN sees only their projects' members. \`filter\` matches by
-		e-mail (case-insensitive), \`personId\`, or \`identityId\`; \`limit\`/\`offset\`
-		paginate. Returns an empty list when the caller may not list anyone.
+		List persons across the tenant. Requires the \`person:list\` permission —
+		held by SUPER_ADMIN and PROJECT_ADMIN, and grantable to a custom role — which
+		lists every person. Without it the result is scoped to persons who are members
+		of a project the caller may view members of (i.e. the same persons reachable
+		via \`project.members\`). \`filter\` matches by e-mail (case-insensitive),
+		\`personId\`, or \`identityId\`; \`limit\`/\`offset\` paginate. Returns an empty
+		list when the caller may not list anyone.
 		"""
 		persons(filter: PersonsFilter, limit: Int, offset: Int): [Person!]!
 		projects: [Project!]!
@@ -31,8 +32,8 @@ const schema: DocumentNode = gql`
 		"""
 		List global (project-independent) permanent API keys — those created via
 		\`createGlobalApiKey\`, whose identity carries global roles and no project
-		membership. Requires the \`apiKey:list\` permission — by default granted
-		only to SUPER_ADMIN via the wildcard ALL-resource/ALL-privilege grant.
+		membership. Requires the \`apiKey:list\` permission — granted to SUPER_ADMIN
+		and PROJECT_ADMIN by default, and grantable to a custom role.
 		Returns an empty list when the caller may not list them. To list a
 		project's keys use \`project.apiKeys\`.
 		"""
@@ -53,10 +54,24 @@ const schema: DocumentNode = gql`
 		"""
 		authPolicies: [AuthPolicy!]!
 
+		"""
+		List custom roles (runtime-defined global roles carrying a bundle of tenant
+		permissions). Requires the \`customRole:view\` permission — granted to
+		SUPER_ADMIN and PROJECT_ADMIN by default, and itself grantable to a custom
+		role. Managing definitions needs \`customRole:manage\`, which is not grantable.
+		"""
+		customRoles: [CustomRole!]!
+
+		"""
+		List exact permission definitions grantable to a custom role. Requires
+		the \`customRole:view\` permission.
+		"""
+		customRolePermissions: [CustomRolePermissionDefinition!]!
+
 		"""
 		Read the tenant audit log (\`person_auth_log\`). Requires the
-		\`system:viewAuthLog\` permission — by default granted only to
-		SUPER_ADMIN via the wildcard ALL-resource/ALL-privilege grant.
+		\`system:viewAuthLog\` permission — granted to SUPER_ADMIN and
+		PROJECT_ADMIN by default, and grantable to a custom role.
 		Ordered by created_at DESC. Page size is capped server-side
 		(default 100, max 500); \`hasMore\` indicates a further page exists.
 		"""
@@ -119,6 +134,7 @@ const schema: DocumentNode = gql`
 		disableEmailOtp: DisableEmailOtpResponse
 
 		disablePerson(personId: String!): DisablePersonResponse
+		enablePerson(personId: String!): EnablePersonResponse
 		forceSignOutPerson(personId: String!, reason: String): ForceSignOutPersonResponse
 		resetPersonMfa(personId: String!): ResetPersonMfaResponse
 		revokeSession(sessionId: String!): RevokeSessionResponse
@@ -183,6 +199,11 @@ const schema: DocumentNode = gql`
 		updateAuthPolicy(id: String!, policy: AuthPolicyInput!): UpdateAuthPolicyResponse
 		deleteAuthPolicy(id: String!): DeleteAuthPolicyResponse
 
+		# === custom roles (runtime-defined global roles) ===
+		createCustomRole(slug: String!, grants: [CustomRoleGrantInput!]!, description: String): CreateCustomRoleResponse
+		updateCustomRole(slug: String!, grants: [CustomRoleGrantInput!], description: String): UpdateCustomRoleResponse
+		deleteCustomRole(slug: String!): DeleteCustomRoleResponse
+
 		addProjectMailTemplate(template: MailTemplate!): AddMailTemplateResponse
 		@deprecated(reason: "use addMailTemplate")
 
@@ -201,6 +222,7 @@ const schema: DocumentNode = gql`
 		login: ConfigLogin!
 		captcha: ConfigCaptcha!
 		rateLimits: ConfigRateLimits!
+		panel: ConfigPanel!
 	}
 
 	type ConfigSignup {
@@ -334,6 +356,21 @@ const schema: DocumentNode = gql`
 		window: Interval!
 	}
 
+	"""
+	Who may enter the management panel. This is an entry gate for the console
+	only, not an authorization system: everything done inside the panel still
+	goes through the tenant ACL, so being allowed in grants no extra rights.
+	An identity may enter when its global roles intersect globalRoles, or when
+	it holds a membership with one of projectRoles in at least one project.
+	Both lists empty means nobody can enter.
+	"""
+	type ConfigPanel {
+		"""Global roles (identity.roles) that may use the management panel."""
+		globalRoles: [String!]!
+		"""Project membership roles that may use the management panel, in any project."""
+		projectRoles: [String!]!
+	}
+
 	input ConfigInput {
 		signup: ConfigSignupInput
 		emailChange: ConfigEmailChangeInput
@@ -342,6 +379,7 @@ const schema: DocumentNode = gql`
 		login: ConfigLoginInput
 		captcha: ConfigCaptchaInput
 		rateLimits: ConfigRateLimitsInput
+		panel: ConfigPanelInput
 	}
 
 	input ConfigSignupInput {
@@ -426,6 +464,15 @@ const schema: DocumentNode = gql`
 		limit: Int
 		window: Interval
 	}
+
+	"""
+	Each list is replaced as a whole; omitting one leaves it unchanged. An empty
+	list closes the panel for that dimension.
+	"""
+	input ConfigPanelInput {
+		globalRoles: [String!]
+		projectRoles: [String!]
+	}
 	
 	type ConfigureResponse {
 		ok: Boolean!
@@ -464,6 +511,7 @@ const schema: DocumentNode = gql`
 	enum SignUpErrorCode {
 		EMAIL_ALREADY_EXISTS
 		INVALID_EMAIL_FORMAT
+		INVALID_ROLE
 		TOO_WEAK
 		INVALID_CAPTCHA
 		RATE_LIMIT_EXCEEDED
@@ -539,6 +587,11 @@ const schema: DocumentNode = gql`
 		MFA_ENROLLMENT_REQUIRED
 		EMAIL_NOT_VERIFIED
 		RATE_LIMIT_EXCEEDED
+		"""
+		The person is linked to an identity provider with
+		\`disableLocalAuthentication\`, so password sign-in is not available to them.
+		"""
+		IDP_REQUIRED
 	}
 
 	type SignInResult implements CommonSignInResult {
@@ -840,6 +893,11 @@ const schema: DocumentNode = gql`
 		NOT_A_PERSON
 		""" The person is not allowed to disconnect their last remaining sign-in method. """
 		LAST_AUTH_METHOD
+		"""
+		The provider has \`disableLocalAuthentication\`, so this connection is the only way
+		the person may sign in and cannot be removed by them — not even while the provider is disabled.
+		"""
+		IDP_REQUIRED
 	}
 
 	type IdentityProvider {
@@ -866,6 +924,13 @@ const schema: DocumentNode = gql`
 		Defaults to false.
 		"""
 		assumeEmailVerified: Boolean!
+		"""
+		When true, a person linked to this provider may authenticate ONLY through it:
+		password sign-in and passwordless sign-in are refused and no password-reset
+		mail is sent. Disabling the provider lifts the restriction, which is the
+		break-glass for an IdP outage. Defaults to false.
+		"""
+		disableLocalAuthentication: Boolean!
 	}
 
 	input IDPOptions {
@@ -874,6 +939,7 @@ const schema: DocumentNode = gql`
 		initReturnsConfig: Boolean
 		requireVerifiedEmail: Boolean
 		assumeEmailVerified: Boolean
+		disableLocalAuthentication: Boolean
 	}
 
 	# === passwordless sign in ===
@@ -895,6 +961,11 @@ const schema: DocumentNode = gql`
 		PASSWORDLESS_DISABLED
 		INVALID_CAPTCHA
 		RATE_LIMIT_EXCEEDED
+		"""
+		The person is linked to an identity provider with
+		\`disableLocalAuthentication\`, so passwordless sign-in is not available to them.
+		"""
+		IDP_REQUIRED
 	}
 	
 	type InitSignInPasswordlessResult {
@@ -932,6 +1003,11 @@ const schema: DocumentNode = gql`
 		OTP_REQUIRED
 		INVALID_OTP_TOKEN
 		MFA_ENROLLMENT_REQUIRED
+		"""
+		The person became linked to an identity provider with
+		\`disableLocalAuthentication\` after this magic link was issued.
+		"""
+		IDP_REQUIRED
 	}
 
 	type SignInPasswordlessResult implements CommonSignInResult {
@@ -1119,6 +1195,7 @@ const schema: DocumentNode = gql`
 	enum CreateApiKeyErrorCode {
 		PROJECT_NOT_FOUND
 		INVALID_MEMBERSHIP
+		INVALID_ROLE
 
 		VARIABLE_NOT_FOUND @deprecated
 		ROLE_NOT_FOUND @deprecated
@@ -1235,8 +1312,22 @@ const schema: DocumentNode = gql`
 		email: String
 		name: String
 		otpEnabled: Boolean!
+		""" The person's own opt-in flag; \`null\` means "follow the tenant policy". On its own it does not say whether passwordless sign-in works — see \`passwordlessAvailable\`. """
 		passwordlessEnabled: Boolean
 		"""
+		Whether passwordless sign-in is actually usable for this person right now: the tenant-wide
+		policy resolved against \`passwordlessEnabled\`, i.e. the very same decision \`signIn\` makes. A UI
+		offering an enable/disable toggle must branch on this — under an \`always\` or \`never\` policy the
+		raw opt-in flag says nothing about what will happen.
+		"""
+		passwordlessAvailable: Boolean!
+		"""
+		Whether \`passwordlessEnabled\` is what decides \`passwordlessAvailable\`. False under an \`always\`
+		or \`never\` policy, where the person's own flag is ignored — a UI should then report the state
+		rather than offer a toggle that changes nothing.
+		"""
+		passwordlessSelfManaged: Boolean!
+		"""
 		Whether e-mail based one-time-password 2FA is enabled for this person
 		(see \`initEmailOtp\` / \`confirmEmailOtp\` / \`disableEmailOtp\`). Independent
 		of \`otpEnabled\` (TOTP authenticator), so a UI can show each MFA method's
@@ -1244,15 +1335,21 @@ const schema: DocumentNode = gql`
 		"""
 		emailOtpEnabled: Boolean!
 		emailVerified: Boolean!
+		"""
+		When the account was disabled (see \`disablePerson\`), null while the person
+		is active. Read-only — flip it with \`disablePerson\` / \`enablePerson\`.
+		"""
+		disabledAt: DateTime
 		identity: Identity!
 
 		"""
 		External IdP connections of this person. Always visible for the calling
 		person (e.g. via \`me { person { identityProviders } }\`). For other
 		persons, visible to callers holding the \`person:viewIdp\` permission
-		against the target's roles — SUPER_ADMIN sees everyone; PROJECT_ADMIN
-		sees members whose roles fall within their allowed-input-roles. Returns
-		an empty list rather than throwing when the viewer lacks visibility.
+		against the target — SUPER_ADMIN sees everyone; PROJECT_ADMIN sees
+		everyone except identities holding \`super_admin\` or \`project_creator\`;
+		a custom role is further bounded by its configured target constraints.
+		Returns an empty list rather than throwing when the viewer lacks visibility.
 		"""
 		identityProviders: [PersonIdentityProvider!]!
 	}
@@ -1305,17 +1402,69 @@ const schema: DocumentNode = gql`
 		Active SESSION-type api keys for this identity. Always visible for
 		the calling identity (e.g. via \`me { sessions }\`). For other identities,
 		visible to callers holding the \`person:viewSessions\` permission against
-		the target's roles — SUPER_ADMIN sees everyone; PROJECT_ADMIN sees
-		members whose roles fall within their allowed-input-roles. Returns an
+		the target — SUPER_ADMIN sees everyone; PROJECT_ADMIN sees everyone except
+		identities holding \`super_admin\` or \`project_creator\`; a custom role is
+		further bounded by its configured target constraints. Returns an
 		empty list rather than throwing when the viewer lacks visibility, so
 		batched identity queries do not abort on a single forbidden target.
 		"""
 		sessions: [SessionInfo!]!
 	}
 
+	"""
+	What the identity may do tenant-wide, evaluated against the same ACL the resolvers enforce.
+
+	This is for building a UI that does not offer what it cannot deliver — it is **not** a security
+	boundary, and answering \`true\` here grants nothing. Every operation is still checked when it is
+	called. The distinction matters because permission failure is not uniform across this API: some
+	queries answer an empty list, others throw, and every mutation throws, so a client cannot tell
+	"nothing to show" from "not yours to see" by trying.
+	"""
 	type IdentityGlobalPermissions {
 		canCreateProject: Boolean!
 		canDeployEntrypoint: Boolean!
+		""" Read \`configuration\`, which throws otherwise. The other configuration queries gate on their own actions. """
+		canViewConfiguration: Boolean!
+		""" Read \`identityProviders\`. """
+		canListIdentityProviders: Boolean!
+		""" Read \`mailTemplates\`. """
+		canListMailTemplates: Boolean!
+		"""
+		Write the tenant configuration (\`configure\`) and read \`authPolicies\`. The CLI is the usual write path.
+		"""
+		canManageConfiguration: Boolean!
+		""" Read \`authLog\`, which throws otherwise. """
+		canViewAuthLog: Boolean!
+		"""
+		List every person in the tenant. Without it \`persons\` still answers, narrowed to the members
+		of the projects the caller administers — so this marks a full listing, not access to one.
+		"""
+		canListPersons: Boolean!
+		""" Read \`globalApiKeys\`, which answers an empty list otherwise. """
+		canListGlobalApiKeys: Boolean!
+		canCreateGlobalApiKey: Boolean!
+	}
+
+	"""
+	What the calling identity may do in this project. Same contract as
+	\`IdentityGlobalPermissions\`: advisory, evaluated per caller, never a substitute for the checks in
+	the resolvers.
+	"""
+	type ProjectPermissions {
+		""" Read \`members\` and \`apiKeys\`; both answer an empty list otherwise. """
+		canViewMembers: Boolean!
+		""" Invite or add a member (\`invite\`, \`addProjectMember\`). Which roles may be granted is checked per membership. """
+		canAddMember: Boolean!
+		canUpdateMember: Boolean!
+		canRemoveMember: Boolean!
+		""" Read \`secrets\` (their names, never values); answers an empty list otherwise. """
+		canViewSecrets: Boolean!
+		""" Write a project secret (\`setProjectSecret\`). Distinct from viewing: a project admin commonly has one and not the other. """
+		canSetSecret: Boolean!
+		""" Create an API key scoped to this project. """
+		canCreateApiKey: Boolean!
+		""" Update the project itself (\`updateProject\`). """
+		canUpdate: Boolean!
 	}
 
 	type IdentityProjectRelation {
@@ -1350,6 +1499,8 @@ const schema: DocumentNode = gql`
 		+ SUPER_ADMIN by default); returns an empty list otherwise.
 		"""
 		secrets: [ProjectSecretInfo!]!
+		""" What the calling identity may do here. Advisory — for building the UI, not for enforcing it. """
+		permissions: ProjectPermissions!
 	}
 
 	""" Metadata about a project secret — never its value. """
@@ -1541,6 +1692,23 @@ const schema: DocumentNode = gql`
 		PERSON_NOT_FOUND
 	}
 
+	# === enablePerson ===
+
+	type EnablePersonResponse {
+		ok: Boolean!
+		error: EnablePersonError
+	}
+
+	type EnablePersonError {
+		code: EnablePersonErrorCode!
+		developerMessage: String!
+	}
+
+	enum EnablePersonErrorCode {
+		PERSON_ALREADY_ENABLED
+		PERSON_NOT_FOUND
+	}
+
 	# === forceSignOutPerson ===
 
 	type ForceSignOutPersonResponse {
@@ -1657,6 +1825,98 @@ const schema: DocumentNode = gql`
 		NOT_FOUND
 	}
 
+	# === custom roles (runtime-defined global roles) ===
+
+	type CustomRole {
+		slug: String!
+		description: String
+		grants: [CustomRoleGrant!]!
+	}
+
+	input CustomRoleGrantInput {
+		permission: String!
+		config: Json
+	}
+
+	type CustomRoleGrant {
+		permission: String!
+		config: Json
+	}
+
+	enum CustomRoleConfigurationKind {
+		NONE
+		ROLE_INPUT
+		TARGET_IDENTITY
+		ROLE_MUTATION
+		GLOBAL_API_KEY
+		CHANGE_PROFILE
+		CREATE_SESSION_TOKEN
+		MAIL_TEMPLATE_SCOPE
+	}
+
+	type CustomRolePermissionDefinition {
+		name: String!
+		configurationKind: CustomRoleConfigurationKind!
+		configurationRequired: Boolean!
+		defaultConfig: Json
+	}
+
+	type CreateCustomRoleResponse {
+		ok: Boolean!
+		error: CreateCustomRoleError
+	}
+
+	type CreateCustomRoleError {
+		code: CreateCustomRoleErrorCode!
+		developerMessage: String!
+	}
+
+	enum CreateCustomRoleErrorCode {
+		INVALID_SLUG
+		SLUG_ALREADY_EXISTS
+		SLUG_ALREADY_ASSIGNED
+		UNKNOWN_PERMISSION
+		DUPLICATE_PERMISSION
+		INVALID_PERMISSION_CONFIGURATION
+	}
+
+	type UpdateCustomRoleResponse {
+		ok: Boolean!
+		error: UpdateCustomRoleError
+	}
+
+	type UpdateCustomRoleError {
+		code: UpdateCustomRoleErrorCode!
+		developerMessage: String!
+	}
+
+	enum UpdateCustomRoleErrorCode {
+		NOT_FOUND
+		UNKNOWN_PERMISSION
+		DUPLICATE_PERMISSION
+		INVALID_PERMISSION_CONFIGURATION
+	}
+
+	type DeleteCustomRoleResponse {
+		ok: Boolean!
+		error: DeleteCustomRoleError
+	}
+
+	type DeleteCustomRoleError {
+		code: DeleteCustomRoleErrorCode!
+		developerMessage: String!
+	}
+
+	enum DeleteCustomRoleErrorCode {
+		NOT_FOUND
+		"""
+		Another custom role's grant configuration references this one. Remove the reference first —
+		deleting would leave that role un-resubmittable, and recreating this slug would silently
+		re-bind the reference to a different definition.
+		"""
+		ROLE_IN_USE
+	}
+
 	# === sessions ===
 
 	type SessionInfo {

package/tests/cases/integration/database/dbClock.test.ts

@@ -0,0 +1,171 @@
+import { expect, test } from 'bun:test'
+import crypto from 'node:crypto'
+import {
+	ApiKey,
+	computeTokenHash,
+	CreateApiKeyCommand,
+	DatabaseContext,
+	RateLimitCountQuery,
+	RecordRateLimitEventCommand,
+	SavePersonTokenCommand,
+} from '../../../../src/index.js'
+import type { Providers } from '../../../../src/index.js'
+import { ApiKeyByTokenQuery } from '../../../../src/model/queries/apiKey/ApiKeyQuery.js'
+import { PersonTokenQuery } from '../../../../src/model/queries/personToken/PersonTokenQuery.js'
+import { createConnection } from '../../../src/dbUtils.js'
+
+const APP_NOW = new Date('2000-01-01T00:00:00.000Z')
+const TOKEN_EXPIRATION_MINUTES = 15
+const databaseName = process.env.TEST_DB_NAME ?? ''
+
+const databaseConfigured = Boolean(
+	process.env.TEST_DB_HOST
+		&& process.env.TEST_DB_PORT
+		&& process.env.TEST_DB_USER
+		&& process.env.TEST_DB_PASSWORD
+		&& databaseName,
+)
+
+const createSkewedProviders = (uuid: string): Providers => ({
+	uuid: () => uuid,
+	now: () => APP_NOW,
+	randomBytes: async bytes => Buffer.alloc(bytes),
+	bcrypt: async value => value,
+	bcryptCompare: async () => true,
+	hash: (value, algorithm) => crypto.createHash(algorithm).update(value).digest(),
+	encrypt: async value => ({ value, version: 1 }),
+	decrypt: async value => ({ value, needsReEncrypt: false }),
+	encryptionEnabled: true,
+})
+
+const getDatabaseNow = async (db: DatabaseContext): Promise<Date> => {
+	const result = await db.client.query<{ now: Date }>('SELECT now() AS "now"')
+	return result.rows[0].now
+}
+
+test.skipIf(!databaseConfigured)('person token lifetime and expiry gate use the database clock', async () => {
+	const identityId = crypto.randomUUID()
+	const personId = crypto.randomUUID()
+	const tokenId = crypto.randomUUID()
+	const token = crypto.randomUUID()
+	const tokenHash = computeTokenHash(token)
+	const connection = createConnection(databaseName)
+	const db = new DatabaseContext(connection.createClient('tenant', { module: 'tenant-db-clock-test' }), createSkewedProviders(tokenId))
+
+	try {
+		await db.client.query(
+			'INSERT INTO "tenant"."identity" ("id", "parent_id", "roles", "description", "created_at") VALUES (?, ?, ?::jsonb, ?, ?)',
+			[identityId, null, JSON.stringify(['person']), 'DB clock integration test', APP_NOW],
+		)
+		await db.client.query(
+			'INSERT INTO "tenant"."person" ("id", "identity_id") VALUES (?, ?)',
+			[personId, identityId],
+		)
+
+		const databaseBeforeInsert = await getDatabaseNow(db)
+		const created = await db.commandBus.execute(
+			new SavePersonTokenCommand(personId, tokenHash, 'passwordless', TOKEN_EXPIRATION_MINUTES),
+		)
+		const databaseAfterInsert = await getDatabaseNow(db)
+		const lifetimeMs = TOKEN_EXPIRATION_MINUTES * 60 * 1000
+
+		expect(created).toEqual({ id: tokenId, expiresAt: expect.any(Date) })
+		expect(created.expiresAt.getTime()).toBeGreaterThanOrEqual(databaseBeforeInsert.getTime() + lifetimeMs)
+		expect(created.expiresAt.getTime()).toBeLessThanOrEqual(databaseAfterInsert.getTime() + lifetimeMs)
+		expect(created.expiresAt.getUTCFullYear()).not.toBe(APP_NOW.getUTCFullYear())
+
+		const active = await db.queryHandler.fetch(PersonTokenQuery.byToken(token, 'passwordless'))
+		expect(active?.is_expired).toBe(false)
+
+		await db.client.query(
+			'UPDATE "tenant"."person_token" SET "expires_at" = now() - interval \'1 second\' WHERE "id" = ?',
+			[tokenId],
+		)
+		const expired = await db.queryHandler.fetch(PersonTokenQuery.byToken(token, 'passwordless'))
+		expect(expired?.is_expired).toBe(true)
+	} finally {
+		await db.client.query('DELETE FROM "tenant"."person" WHERE "id" = ?', [personId])
+		await db.client.query('DELETE FROM "tenant"."identity" WHERE "id" = ?', [identityId])
+		await connection.end()
+	}
+})
+
+test.skipIf(!databaseConfigured)('rate-limit events and windows use the database clock', async () => {
+	const eventId = crypto.randomUUID()
+	const keyHash = crypto.randomBytes(32)
+	const connection = createConnection(databaseName)
+	const db = new DatabaseContext(connection.createClient('tenant', { module: 'tenant-db-clock-test' }), createSkewedProviders(eventId))
+
+	try {
+		const databaseBeforeInsert = await getDatabaseNow(db)
+		await db.commandBus.execute(new RecordRateLimitEventCommand('sign_up_per_ip', keyHash))
+		const databaseAfterInsert = await getDatabaseNow(db)
+		const inserted = await db.client.query<{ occurred_at: Date }>(
+			'SELECT "occurred_at" FROM "tenant"."rate_limit_event" WHERE "id" = ?',
+			[eventId],
+		)
+		const occurredAt = inserted.rows[0].occurred_at
+
+		expect(occurredAt.getTime()).toBeGreaterThanOrEqual(databaseBeforeInsert.getTime())
+		expect(occurredAt.getTime()).toBeLessThanOrEqual(databaseAfterInsert.getTime())
+		expect(occurredAt.getUTCFullYear()).not.toBe(APP_NOW.getUTCFullYear())
+		expect(await db.queryHandler.fetch(new RateLimitCountQuery('sign_up_per_ip', keyHash, 60))).toBe(1)
+	} finally {
+		await db.client.query('DELETE FROM "tenant"."rate_limit_event" WHERE "id" = ?', [eventId])
+		await connection.end()
+	}
+})
+
+test.skipIf(!databaseConfigured)('API key expiry and idle gates use the database clock', async () => {
+	const identityId = crypto.randomUUID()
+	const apiKeyId = crypto.randomUUID()
+	const token = crypto.randomUUID()
+	const tokenHash = computeTokenHash(token)
+	const connection = createConnection(databaseName)
+	const db = new DatabaseContext(connection.createClient('tenant', { module: 'tenant-db-clock-test' }), createSkewedProviders(apiKeyId))
+
+	try {
+		await db.client.query(
+			'INSERT INTO "tenant"."identity" ("id", "parent_id", "roles", "description", "created_at") VALUES (?, ?, ?::jsonb, ?, ?)',
+			[identityId, null, JSON.stringify([]), 'DB clock integration test', APP_NOW],
+		)
+		await db.commandBus.execute(
+			new CreateApiKeyCommand({
+				type: ApiKey.Type.SESSION,
+				identityId,
+				tokenHash,
+				expiration: TOKEN_EXPIRATION_MINUTES,
+				idleTimeout: '1 minute',
+				maxExpirationSeconds: 60 * 60,
+			}),
+		)
+
+		const active = await db.queryHandler.fetch(new ApiKeyByTokenQuery(token))
+		expect(active).toMatchObject({
+			id: apiKeyId,
+			is_expired: false,
+			is_max_expired: false,
+			is_idle_expired: false,
+		})
+		expect(active?.expires_at?.getUTCFullYear()).not.toBe(APP_NOW.getUTCFullYear())
+
+		await db.client.query(
+			`UPDATE "tenant"."api_key"
+			 SET "expires_at" = now() - interval '1 second',
+			     "max_expires_at" = now() - interval '1 second',
+			     "last_used_at" = now() - interval '3 minutes'
+			 WHERE "id" = ?`,
+			[apiKeyId],
+		)
+		const expired = await db.queryHandler.fetch(new ApiKeyByTokenQuery(token))
+		expect(expired).toMatchObject({
+			is_expired: true,
+			is_max_expired: true,
+			is_idle_expired: true,
+		})
+	} finally {
+		await db.client.query('DELETE FROM "tenant"."api_key" WHERE "id" = ?', [apiKeyId])
+		await db.client.query('DELETE FROM "tenant"."identity" WHERE "id" = ?', [identityId])
+		await connection.end()
+	}
+})

package/tests/cases/integration/mocked/antiAbuseSignUp.test.ts

@@ -10,8 +10,8 @@ const password = '123456'
 // Mirrors RateLimitCountQuery — whitespace/case are normalised by the matcher.
 const rateLimitCountSql = (args: { scope: string; keyHash: Buffer; count: number }): ExpectedQuery => ({
 	sql: `select count(*)::text as count from "tenant"."rate_limit_event"
-		where "scope" = ? and "key_hash" = ? and "occurred_at" >= ?`,
-	parameters: [args.scope, args.keyHash, (val: unknown) => val instanceof Date],
+		where "scope" = ? and "key_hash" = ? and occurred_at >= NOW() - make_interval(secs => ?)`,
+	parameters: [args.scope, args.keyHash, (val: unknown) => typeof val === 'number'],
 	response: { rows: [{ count: String(args.count) }] },
 })