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

package/src/model/service/apiKey/ApiKeyManager.ts

@@ -1,36 +1,57 @@
 import {
+	ApiKeyRequestInfo,
 	CreateApiKeyCommand,
 	DisableApiKeyCommand,
 	DisableIdentityApiKeysCommand,
 	DisableOneOffApiKeyCommand,
 	ProlongApiKeyCommand,
-} from '../../commands'
-import { ApiKey } from '../../type'
+} from '../../commands/index.js'
+import { ApiKey } from '../../type/index.js'
 
-import { Response, ResponseError, ResponseOk } from '../../utils/Response'
-import { DatabaseContext, TokenHash } from '../../utils'
-import { ApiKeyService, CreateApiKeyResponse } from './ApiKeyService'
+import { Response, ResponseError, ResponseOk } from '../../utils/Response.js'
+import { DatabaseContext, TokenHash } from '../../utils/index.js'
+import { ApiKeyService, CreateApiKeyResponse } from './ApiKeyService.js'
 import assert from 'node:assert'
 import { Acl } from '@contember/schema'
-import { ApiKeyByIdQuery, ApiKeyByTokenQuery, ApiKeyRow, ConfigurationQuery } from '../../queries'
+import { ApiKeyByIdQuery, ApiKeyByTokenQuery, ApiKeyRow, ConfigurationQuery, IdentityQuery } from '../../queries/index.js'
 import PostgresInterval from 'postgres-interval'
-import { Config } from '../../type/Config'
-import { intervalToSeconds } from '../../utils/interval'
+import { Config } from '../../type/Config.js'
+import { intervalToPostgres, intervalToSeconds } from '../../utils/interval.js'
+import { AuthPolicyResolver } from '../AuthPolicyResolver.js'
+import { AuthLogService } from '../AuthLogService.js'
+import { IdpSessionRevalidator } from '../idp/IdpSessionRevalidator.js'
+import { UnpersistedApiKeyManager } from './UnpersistedApiKeyManager.js'
+import { GlobalRoleValidator } from '../GlobalRoleValidator.js'
+import { Connection } from '@contember/database'
 
 export class ApiKeyManager {
 	constructor(
 		private readonly apiKeyService: ApiKeyService,
+		private readonly authPolicyResolver: AuthPolicyResolver,
+		private readonly authLogService: AuthLogService,
+		private readonly unpersistedApiKeyManager: UnpersistedApiKeyManager = new UnpersistedApiKeyManager(),
+		private readonly idpSessionRevalidator?: IdpSessionRevalidator,
+		private readonly globalRoleValidator: GlobalRoleValidator = new GlobalRoleValidator(),
 	) {}
 
 	async verifyAndProlong(
 		dbContext: DatabaseContext,
 		readDbContext: DatabaseContext,
 		token: string,
+		requestInfo?: ApiKeyRequestInfo,
+		forwardedInfo?: ApiKeyRequestInfo,
 	): Promise<VerifyResponse> {
-		const apiKeyRow = await readDbContext.queryHandler.fetch(new ApiKeyByTokenQuery(token))
-		if (apiKeyRow === null) {
+		const unpersistedResult = this.unpersistedApiKeyManager.verify(token)
+		if (unpersistedResult !== null) {
+			// Configured (unpersisted) root token: no DB row to prolong/track.
+			return new ResponseOk(unpersistedResult)
+		}
+
+		const fetchedApiKey = await this.fetchApiKeyByToken(dbContext, readDbContext, token)
+		if (fetchedApiKey === null) {
 			return new ResponseError(VerifyErrorCode.NOT_FOUND, 'API key was not found')
 		}
+		const apiKeyRow = fetchedApiKey.row
 
 		if (apiKeyRow.disabled_at !== null) {
 			return new ResponseError(
@@ -39,9 +60,69 @@ export class ApiKeyManager {
 			)
 		}
 
-		const now = new Date()
-		if (apiKeyRow.expires_at !== null && apiKeyRow.expires_at <= now) {
-			return new ResponseError(VerifyErrorCode.DISABLED, `API key expired at ${apiKeyRow.expires_at.toISOString()}`)
+		// A19 time gates are computed on the DATABASE clock by ApiKeyByTokenQuery
+		// (is_expired / is_max_expired / is_idle_expired against NOW()), so app/DB clock
+		// skew — or skew between engine instances — can't weaken them. The idle slack
+		// (PROLONG_THROTTLE_MS) is folded into the SQL too. See engine-tenant-api/CLAUDE.md.
+		if (apiKeyRow.is_expired) {
+			return new ResponseError(VerifyErrorCode.DISABLED, `API key expired at ${apiKeyRow.expires_at?.toISOString()}`)
+		}
+
+		// Absolute hard cap (defensive — the prolong clamp should already keep
+		// expires_at <= max_expires_at, but enforce it here regardless).
+		if (apiKeyRow.is_max_expired) {
+			await dbContext.commandBus.execute(new DisableApiKeyCommand(apiKeyRow.id))
+			return new ResponseError(
+				VerifyErrorCode.DISABLED,
+				`API key reached its maximum lifetime at ${apiKeyRow.max_expires_at?.toISOString()}`,
+			)
+		}
+
+		// Idle timeout. Reject + disable when the session has been idle longer than the
+		// policy's idle_timeout. A null idle_timeout (today's default) or a never-used
+		// key (last_used_at null) are never idle-expired — the SQL encodes both.
+		if (apiKeyRow.is_idle_expired) {
+			await dbContext.commandBus.execute(new DisableApiKeyCommand(apiKeyRow.id))
+			try {
+				await this.authLogService.logSessionEvent(dbContext, {
+					type: 'session_expired_idle',
+					identityId: apiKeyRow.identity_id,
+					personId: apiKeyRow.person_id,
+					ipAddress: requestInfo?.ip,
+					userAgent: requestInfo?.userAgent,
+					success: false,
+					eventData: {
+						lastUsedAt: apiKeyRow.last_used_at?.toISOString() ?? null,
+						idleTimeout: String(apiKeyRow.idle_timeout),
+					},
+				})
+			} catch {
+				/* best-effort: auth path must stay resilient */
+			}
+			return new ResponseError(
+				VerifyErrorCode.DISABLED,
+				`API key was idle since ${apiKeyRow.last_used_at?.toISOString()} and exceeded the idle timeout`,
+			)
+		}
+
+		const effectiveInfo: ApiKeyRequestInfo | undefined = apiKeyRow.trust_forwarded_info && forwardedInfo
+			? {
+				ip: forwardedInfo.ip ?? requestInfo?.ip,
+				userAgent: forwardedInfo.userAgent ?? requestInfo?.userAgent,
+			}
+			: requestInfo
+
+		// Re-validate IdP-backed sessions against their identity provider (A24). In the
+		// default `background` mode this returns immediately and revalidates after the
+		// response (revocation lands on the next request); in `blocking` mode it can revoke
+		// the current request. No-op for password sessions and IdPs without revalidation.
+		// `effectiveInfo` is passed so the audit entries record the originating request's IP/UA.
+		// The idp_session row is written together with the api_key, so it is read from where the key was found.
+		if (this.idpSessionRevalidator) {
+			const outcome = await this.idpSessionRevalidator.revalidate(dbContext, fetchedApiKey.sourceDbContext, apiKeyRow, effectiveInfo)
+			if (outcome === 'revoked') {
+				return new ResponseError(VerifyErrorCode.DISABLED, 'IdP session was revoked')
+			}
 		}
 
 		// Detached (runs after the response), so a rejection here would be an unhandledRejection and can take the
@@ -53,25 +134,137 @@ export class ApiKeyManager {
 					apiKeyRow.type,
 					apiKeyRow.expiration,
 					apiKeyRow.expires_at,
+					effectiveInfo,
+					{
+						lastIp: apiKeyRow.last_ip,
+						lastUserAgent: apiKeyRow.last_user_agent,
+						lastUsedAt: apiKeyRow.last_used_at,
+					},
+					apiKeyRow.max_expires_at,
 				),
 			).catch(() => {})
 		})
 
-		return new ResponseOk(new VerifyResult(apiKeyRow.identity_id, apiKeyRow.id, apiKeyRow.roles, apiKeyRow.person_id))
+		return new ResponseOk(
+			new VerifyResult(
+				apiKeyRow.identity_id,
+				apiKeyRow.id,
+				apiKeyRow.roles,
+				apiKeyRow.person_id,
+				apiKeyRow.trust_forwarded_info,
+			),
+		)
 	}
 
-	async createSessionApiKey(dbContext: DatabaseContext, identityId: string, expiration?: number): Promise<string> {
-		const config = await dbContext.queryHandler.fetch(new ConfigurationQuery())
-		const expirationResolved = expiration ?? (intervalToSeconds(config.login.defaultTokenExpiration) / 60)
-		const expirationCapped = config.login.maxTokenExpiration
-			? Math.min(expirationResolved, intervalToSeconds(config.login.maxTokenExpiration) / 60)
-			: expirationResolved
-		const command = new CreateApiKeyCommand({ type: ApiKey.Type.SESSION, identityId, expiration: expirationCapped })
-		const token = (await dbContext.commandBus.execute(command)).token
-		assert(token !== undefined)
+	private async fetchApiKeyByToken(dbContext: DatabaseContext, readDbContext: DatabaseContext, token: string): Promise<FetchedApiKey | null> {
+		const query = new ApiKeyByTokenQuery(token)
+		const replicaRow = await readDbContext.queryHandler.fetch(query)
+		if (replicaRow !== null) {
+			return { row: replicaRow, sourceDbContext: readDbContext }
+		}
+		if (readDbContext.client.connection === dbContext.client.connection) {
+			return null
+		}
+		// A token issued moments ago (sign-in, createSessionToken) may not have reached the read replica yet.
+		const primaryRow = await dbContext.queryHandler.fetch(query)
+		return primaryRow !== null ? { row: primaryRow, sourceDbContext: dbContext } : null
+	}
+
+	async createSessionApiKey(
+		dbContext: DatabaseContext,
+		identityId: string,
+		expiration?: number,
+		requestInfo?: ApiKeyRequestInfo,
+		trustForwardedInfo?: boolean,
+	): Promise<string> {
+		const { token } = await this.createSessionApiKeyWithId(dbContext, identityId, expiration, requestInfo, trustForwardedInfo)
 		return token
 	}
 
+	/**
+	 * Like {@link createSessionApiKey} but also returns the api_key id — needed when the
+	 * caller has to bind another row to the session (e.g. an `idp_session` for IdP
+	 * re-validation).
+	 */
+	async createSessionApiKeyWithId(
+		dbContext: DatabaseContext,
+		identityId: string,
+		expiration?: number,
+		requestInfo?: ApiKeyRequestInfo,
+		trustForwardedInfo?: boolean,
+	): Promise<{ id: string; token: string }> {
+		const config = await dbContext.queryHandler.fetch(new ConfigurationQuery(dbContext.providers))
+
+		// A19: snapshot the effective session policy onto the api_key at sign-in.
+		// With no matching policy, every field is null/baseline and the result is
+		// byte-for-byte today's behavior.
+		const [identityRow] = await dbContext.queryHandler.fetch(new IdentityQuery([identityId]))
+		const globalRoles = identityRow?.roles ?? []
+		const policy = await this.authPolicyResolver.resolveForIdentity(dbContext, identityId, globalRoles)
+
+		const defaultExpirationMinutes = intervalToSeconds(config.login.defaultTokenExpiration) / 60
+		// remember_me_allowed === false: ignore a client-supplied longer lifetime and
+		// force the default. (true/null leave the requested expiration untouched.)
+		const requestedMinutes = policy.rememberMeAllowed === false
+			? defaultExpirationMinutes
+			: (expiration ?? defaultExpirationMinutes)
+
+		// Cap by maxTokenExpiration (existing behavior) AND by the policy's
+		// tokenExpiration (A19) — strictest wins.
+		let expirationCapped = config.login.maxTokenExpiration
+			? Math.min(requestedMinutes, intervalToSeconds(config.login.maxTokenExpiration) / 60)
+			: requestedMinutes
+		if (policy.tokenExpiration) {
+			expirationCapped = Math.min(expirationCapped, intervalToSeconds(policy.tokenExpiration) / 60)
+		}
+
+		// Absolute hard cap as a lifetime in seconds; CreateApiKeyCommand writes it as
+		// now() + interval on the DB clock. NULL = uncapped sliding window (today's behavior).
+		const maxExpirationSeconds = policy.tokenExpiration
+			? intervalToSeconds(policy.tokenExpiration)
+			: null
+
+		const command = new CreateApiKeyCommand({
+			type: ApiKey.Type.SESSION,
+			identityId,
+			expiration: expirationCapped,
+			requestInfo,
+			trustForwardedInfo,
+			idleTimeout: policy.idleTimeout ? intervalToPostgres(policy.idleTimeout) : null,
+			maxExpirationSeconds,
+		})
+		const { id, token } = await dbContext.commandBus.execute(command)
+		assert(token !== undefined)
+
+		// A19: audit only when a policy is actually in effect. With zero auth_policy
+		// rows the resolved policy is inert and no extra insert happens.
+		const policyApplied = policy.mfaRequired === true
+			|| policy.tokenExpiration !== null
+			|| policy.idleTimeout !== null
+			|| policy.rememberMeAllowed !== null
+		if (policyApplied) {
+			try {
+				await this.authLogService.logSessionEvent(dbContext, {
+					type: 'session_policy_applied',
+					identityId,
+					ipAddress: requestInfo?.ip,
+					userAgent: requestInfo?.userAgent,
+					success: true,
+					eventData: {
+						tokenExpiration: policy.tokenExpiration ? intervalToPostgres(policy.tokenExpiration) : null,
+						idleTimeout: policy.idleTimeout ? intervalToPostgres(policy.idleTimeout) : null,
+						rememberMeAllowed: policy.rememberMeAllowed,
+						mfaRequired: policy.mfaRequired,
+					},
+				})
+			} catch {
+				/* best-effort: sign-in must not break on an audit failure */
+			}
+		}
+
+		return { id, token }
+	}
+
 	async findApiKey(dbContext: DatabaseContext, apiKeyId: string): Promise<ApiKeyRow | null> {
 		return await dbContext.queryHandler.fetch(
 			new ApiKeyByIdQuery(apiKeyId),
@@ -95,10 +288,15 @@ export class ApiKeyManager {
 		description: string,
 		roles: readonly string[],
 		tokenHash?: TokenHash,
+		trustForwardedInfo?: boolean,
 	): Promise<CreateApiKeyResponse> {
 		return await dbContext.transaction(async db => {
-			return await this.apiKeyService.createPermanentApiKey(db, description, roles, tokenHash)
-		})
+			const invalidRole = await this.globalRoleValidator.findInvalidRole(db, roles)
+			if (invalidRole !== null) {
+				return new ResponseError('INVALID_ROLE', `Role ${invalidRole} is not valid or globally assignable`)
+			}
+			return await this.apiKeyService.createPermanentApiKey(db, description, roles, tokenHash, trustForwardedInfo)
+		}, { isolation: 'readCommitted' })
 	}
 
 	async createProjectPermanentApiKey(
@@ -107,13 +305,19 @@ export class ApiKeyManager {
 		memberships: readonly Acl.Membership[],
 		description: string,
 		tokenHash?: TokenHash,
+		trustForwardedInfo?: boolean,
 	): Promise<CreateApiKeyResponse> {
 		return await dbContext.transaction(async db => {
-			return await this.apiKeyService.createProjectPermanentApiKey(db, projectId, memberships, description, tokenHash)
+			return await this.apiKeyService.createProjectPermanentApiKey(db, projectId, memberships, description, tokenHash, trustForwardedInfo)
 		})
 	}
 }
 
+type FetchedApiKey = {
+	row: ApiKeyRow
+	sourceDbContext: DatabaseContext
+}
+
 export type VerifyResponse = Response<VerifyResult, VerifyErrorCode>
 
 export class VerifyResult {
@@ -124,6 +328,7 @@ export class VerifyResult {
 		public readonly apiKeyId: string,
 		public readonly roles: string[],
 		public readonly personId: string | null,
+		public readonly trustForwardedInfo: boolean = false,
 	) {}
 }
 

package/src/model/service/apiKey/ApiKeyService.ts

@@ -1,10 +1,10 @@
-import { DatabaseContext, TokenHash } from '../../utils'
-import { AddProjectMemberCommand, CreateApiKeyCommand, CreateIdentityCommand } from '../../commands'
-import { ApiKey } from '../../type'
-import { createSetMembershipVariables } from '../membershipUtils'
-import { ImplementationException } from '../../../exceptions'
-import { Response, ResponseOk } from '../../utils/Response'
-import { ApiKeyWithToken } from '../../../schema'
+import { DatabaseContext, TokenHash } from '../../utils/index.js'
+import { AddProjectMemberCommand, CreateApiKeyCommand, CreateIdentityCommand } from '../../commands/index.js'
+import { ApiKey } from '../../type/index.js'
+import { createSetMembershipVariables } from '../membershipUtils.js'
+import { ImplementationException } from '../../../exceptions.js'
+import { Response, ResponseOk } from '../../utils/Response.js'
+import { ApiKeyWithToken, CreateApiKeyErrorCode } from '../../../schema/index.js'
 import { Acl } from '@contember/schema'
 
 export class ApiKeyService {
@@ -13,9 +13,17 @@ export class ApiKeyService {
 		description: string,
 		roles: readonly string[] = [],
 		tokenHash?: TokenHash,
+		trustForwardedInfo?: boolean,
 	) {
 		const identityId = await db.commandBus.execute(new CreateIdentityCommand(roles, description))
-		const apiKeyResult = await db.commandBus.execute(new CreateApiKeyCommand({ type: ApiKey.Type.PERMANENT, identityId, tokenHash }))
+		const apiKeyResult = await db.commandBus.execute(
+			new CreateApiKeyCommand({
+				type: ApiKey.Type.PERMANENT,
+				identityId,
+				tokenHash,
+				trustForwardedInfo,
+			}),
+		)
 
 		return new ResponseOk(new CreateApiKeyResult({ id: identityId, description }, apiKeyResult))
 	}
@@ -26,8 +34,9 @@ export class ApiKeyService {
 		memberships: readonly Acl.Membership[],
 		description: string,
 		tokenHash?: TokenHash,
+		trustForwardedInfo?: boolean,
 	) {
-		const response = await this.createPermanentApiKey(db, description, [], tokenHash)
+		const response = await this.createPermanentApiKey(db, description, [], tokenHash, trustForwardedInfo)
 
 		const addMemberResult = await db.commandBus.execute(
 			new AddProjectMemberCommand(projectId, response.result.identity.id, createSetMembershipVariables(memberships)),
@@ -39,7 +48,7 @@ export class ApiKeyService {
 	}
 }
 
-export type CreateApiKeyResponse = Response<CreateApiKeyResult, never>
+export type CreateApiKeyResponse = Response<CreateApiKeyResult, CreateApiKeyErrorCode>
 
 export class CreateApiKeyResult {
 	constructor(public readonly identity: { id: string; description?: string }, public readonly apiKey: { id: string; token?: string }) {
@@ -52,6 +61,7 @@ export class CreateApiKeyResult {
 			identity: {
 				...this.identity,
 				projects: [],
+				sessions: [],
 			},
 		}
 	}

package/src/model/service/apiKey/UnpersistedApiKeyManager.ts

@@ -0,0 +1,123 @@
+import { computeTokenHash, isTokenHash, timingSafeCompareHash, TokenHash } from '../../utils/index.js'
+import { TenantRole } from '../../authorization/index.js'
+import { VerifyResult } from './ApiKeyManager.js'
+
+/**
+ * Well-known identity id used for super-admin identities authenticated via an
+ * unpersisted (configured) root token. The id is stable so that audit logs and
+ * created entities consistently reference the same virtual identity, even
+ * though no row exists in the `identity` table.
+ */
+export const UNPERSISTED_ROOT_IDENTITY_ID = 'f3b2c4d6-0000-4000-8000-000000000001'
+
+/**
+ * Well-known identity id for the pre-sign-in caller of a first-party UI served by the engine (the
+ * management panel's login screen). It holds exactly {@link TenantRole.LOGIN} and exists only in
+ * memory, so the surface it opens is fixed by this file rather than by whatever token an operator
+ * happened to configure.
+ */
+export const UNPERSISTED_LOGIN_IDENTITY_ID = 'f3b2c4d6-0000-4000-8000-000000000002'
+
+const unpersistedIdentityIds: ReadonlySet<string> = new Set([UNPERSISTED_ROOT_IDENTITY_ID, UNPERSISTED_LOGIN_IDENTITY_ID])
+
+/**
+ * Whether an identity id is one of the virtual identities above, i.e. has no row in `identity`.
+ * Anything writing a foreign key to `identity` must ask first — see `AuthLogService`.
+ */
+export const isUnpersistedIdentityId = (identityId: string | undefined): boolean => identityId !== undefined && unpersistedIdentityIds.has(identityId)
+
+/**
+ * The pre-sign-in caller of an engine-served UI, as an already-verified result. There is no token to
+ * present: the surface is reached by being routed there, so nothing is compared and nothing is read
+ * from the database.
+ */
+export const createUnpersistedLoginVerifyResult = (): VerifyResult =>
+	new VerifyResult(UNPERSISTED_LOGIN_IDENTITY_ID, UNPERSISTED_LOGIN_IDENTITY_ID, [TenantRole.LOGIN], null, false)
+
+export interface UnpersistedApiKey {
+	readonly tokenHash: TokenHash
+	readonly identityId: string
+	readonly roles: readonly string[]
+}
+
+/**
+ * Verifies incoming tokens against a fixed set of root tokens configured out of
+ * band (env/config) instead of being stored in the database. This enables token
+ * rotation without database writes and avoids persisting the token hash.
+ *
+ * Token hashes are compared in constant time to avoid leaking information about
+ * the configured secret.
+ */
+export class UnpersistedApiKeyManager {
+	private readonly apiKeys: readonly UnpersistedApiKey[]
+
+	constructor(apiKeys: readonly UnpersistedApiKey[] = []) {
+		this.apiKeys = apiKeys
+	}
+
+	get isEmpty(): boolean {
+		return this.apiKeys.length === 0
+	}
+
+	verify(token: string): VerifyResult | null {
+		if (this.apiKeys.length === 0) {
+			return null
+		}
+		const tokenHash = computeTokenHash(token)
+		// Iterate over all configured keys (no early return) so that matching
+		// remains independent of the position of the matching key.
+		let matched: UnpersistedApiKey | null = null
+		for (const apiKey of this.apiKeys) {
+			if (timingSafeCompareHash(tokenHash, apiKey.tokenHash)) {
+				matched = apiKey
+			}
+		}
+		if (matched === null) {
+			return null
+		}
+		return new VerifyResult(
+			matched.identityId,
+			// There is no persisted api_key row, so there is no api key id.
+			matched.identityId,
+			[...matched.roles],
+			null,
+			false,
+		)
+	}
+
+	static createRootApiKey(tokenHash: TokenHash): UnpersistedApiKey {
+		return {
+			tokenHash,
+			identityId: UNPERSISTED_ROOT_IDENTITY_ID,
+			roles: [TenantRole.SUPER_ADMIN],
+		}
+	}
+
+	/**
+	 * Builds a manager for unpersisted super-admin root tokens from configured
+	 * plain tokens and/or pre-computed token hashes.
+	 */
+	static createForRootTokens(input: {
+		tokens?: readonly string[]
+		tokenHashes?: readonly string[]
+	}): UnpersistedApiKeyManager {
+		const hashes: TokenHash[] = []
+		for (const token of input.tokens ?? []) {
+			if (token.length === 0) {
+				continue
+			}
+			hashes.push(computeTokenHash(token))
+		}
+		for (const hash of input.tokenHashes ?? []) {
+			if (hash.length === 0) {
+				continue
+			}
+			const normalized = hash.toLowerCase()
+			if (!isTokenHash(normalized)) {
+				throw new Error(`Invalid unpersisted root token hash: expected a 64-character sha256 hex string.`)
+			}
+			hashes.push(normalized)
+		}
+		return new UnpersistedApiKeyManager(hashes.map(it => UnpersistedApiKeyManager.createRootApiKey(it)))
+	}
+}

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

@@ -1,2 +1,3 @@
-export * from './ApiKeyManager'
-export * from './ApiKeyService'
+export * from './ApiKeyManager.js'
+export * from './ApiKeyService.js'
+export * from './UnpersistedApiKeyManager.js'

package/src/model/service/captcha/CaptchaProvider.ts

@@ -0,0 +1,20 @@
+export interface CaptchaProviderHandler {
+	/**
+	 * Verify a client-submitted captcha token with the provider. Implementations
+	 * should never throw on remote failure — return `verifyError` so the caller
+	 * can decide whether to fail-open or fail-closed.
+	 */
+	verify(args: CaptchaVerifyArgs): Promise<CaptchaVerifyResult>
+}
+
+export interface CaptchaVerifyArgs {
+	readonly token: string
+	readonly secret: string
+	readonly remoteIp?: string
+	/** Score gate for v3-style providers; ignored by binary providers. */
+	readonly threshold: number | null
+}
+
+export type CaptchaVerifyResult =
+	| { ok: true; score?: number }
+	| { ok: false; reason: 'invalid' | 'low_score' | 'expired' | 'verify_error'; detail?: string }

package/src/model/service/captcha/CaptchaValidator.ts

@@ -0,0 +1,74 @@
+import { Config } from '../../type/Config.js'
+import { CaptchaProvider as CaptchaProviderKey } from '../../../schema/index.js'
+import { CaptchaProviderHandler, CaptchaVerifyResult } from './CaptchaProvider.js'
+
+/** Mutations that can be individually gated by captcha (config.captcha.protect). */
+export type CaptchaProtectedFlow = 'signUp' | 'passwordReset' | 'passwordlessInit' | 'emailVerification'
+
+export interface CaptchaConfig {
+	readonly provider: CaptchaProviderKey | null
+	readonly secret: string | null
+	readonly threshold: number | null
+	readonly protect: Record<CaptchaProtectedFlow, boolean>
+}
+
+export class CaptchaValidator {
+	constructor(
+		private readonly providers: Record<CaptchaProviderKey, CaptchaProviderHandler>,
+	) {}
+
+	/** True when the tenant has opted into captcha (provider+secret both set). */
+	public isEnabled(config: CaptchaConfig): boolean {
+		return config.provider !== null && config.secret !== null && config.secret !== ''
+	}
+
+	/**
+	 * True when captcha is configured AND enforced for the given flow. A single
+	 * provider/secret is shared; `config.captcha.protect` decides per-flow which
+	 * mutations actually require a token.
+	 */
+	public isEnabledFor(config: CaptchaConfig, flow: CaptchaProtectedFlow): boolean {
+		return this.isEnabled(config) && config.protect[flow]
+	}
+
+	/**
+	 * Extract just the captcha-relevant fields from a loaded tenant Config so
+	 * services only pass what they need.
+	 */
+	public extractConfig(config: Config): CaptchaConfig {
+		return {
+			provider: config.captcha.provider ?? null,
+			secret: config.captchaSecret,
+			threshold: config.captcha.threshold ?? null,
+			protect: {
+				signUp: config.captcha.protect.signUp,
+				passwordReset: config.captcha.protect.passwordReset,
+				passwordlessInit: config.captcha.protect.passwordlessInit,
+				emailVerification: config.captcha.protect.emailVerification,
+			},
+		}
+	}
+
+	async verify(args: {
+		config: CaptchaConfig
+		token: string | null | undefined
+		remoteIp?: string
+	}): Promise<CaptchaVerifyResult | { ok: true; skipped: true }> {
+		if (!this.isEnabled(args.config) || !args.config.provider || !args.config.secret) {
+			return { ok: true, skipped: true }
+		}
+		if (!args.token) {
+			return { ok: false, reason: 'invalid', detail: 'captcha token missing' }
+		}
+		const handler = this.providers[args.config.provider]
+		if (!handler) {
+			return { ok: false, reason: 'verify_error', detail: `no handler registered for provider ${args.config.provider}` }
+		}
+		return await handler.verify({
+			token: args.token,
+			secret: args.config.secret,
+			remoteIp: args.remoteIp,
+			threshold: args.config.threshold,
+		})
+	}
+}

package/src/model/service/captcha/HCaptchaProvider.ts

@@ -0,0 +1,31 @@
+import { CaptchaProviderHandler, CaptchaVerifyArgs, CaptchaVerifyResult } from './CaptchaProvider.js'
+
+/** hCaptcha. Binary success/failure — `threshold` is ignored. */
+export class HCaptchaProvider implements CaptchaProviderHandler {
+	constructor(
+		private readonly endpoint: string = 'https://hcaptcha.com/siteverify',
+		private readonly fetchImpl: typeof fetch = fetch,
+	) {}
+
+	async verify({ token, secret, remoteIp }: CaptchaVerifyArgs): Promise<CaptchaVerifyResult> {
+		const body = new URLSearchParams({ secret, response: token })
+		if (remoteIp) {
+			body.set('remoteip', remoteIp)
+		}
+		let payload: { success?: boolean; 'error-codes'?: string[] }
+		try {
+			const response = await this.fetchImpl(this.endpoint, {
+				method: 'POST',
+				headers: { 'content-type': 'application/x-www-form-urlencoded' },
+				body,
+			})
+			payload = await response.json() as typeof payload
+		} catch (e) {
+			return { ok: false, reason: 'verify_error', detail: e instanceof Error ? e.message : String(e) }
+		}
+		if (payload.success) {
+			return { ok: true }
+		}
+		return { ok: false, reason: 'invalid', detail: (payload['error-codes'] ?? []).join(',') }
+	}
+}