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

package/src/model/service/helpers/getPreferredProject.ts

@@ -1,4 +1,4 @@
-import { Project } from '../../type'
+import { Project } from '../../type/index.js'
 
 export const getPreferredProject = (projects: Project[], preferredProjectSlug: string | null): Project | null => {
 	if (projects.length === 1) {

package/src/model/service/helpers/isPasswordlessEnabled.ts

@@ -0,0 +1,21 @@
+import { ConfigPolicy } from '../../../schema/index.js'
+
+/**
+ * Resolves whether passwordless sign-in is effectively available for a person,
+ * combining the tenant-wide policy with the person's own flag. This is the same
+ * gate the passwordless sign-in flow applies, so any caller that reasons about a
+ * person's usable sign-in methods (e.g. the IdP disconnect lock-out check) stays
+ * consistent with what sign-in actually permits.
+ */
+export const isPasswordlessEnabled = (globalValue: ConfigPolicy, personValue: boolean | null): boolean => {
+	switch (globalValue) {
+		case 'always':
+			return true
+		case 'never':
+			return false
+		case 'optIn':
+			return personValue === true
+		case 'optOut':
+			return personValue !== false
+	}
+}

package/src/model/service/idp/BackchannelLogoutManager.ts

@@ -0,0 +1,125 @@
+import { DatabaseContext } from '../../utils/index.js'
+import { IdentityProviderBySlugQuery } from '../../queries/idp/IdentityProviderBySlugQuery.js'
+import { IdpSessionBySidRow, IdpSessionsBySidQuery } from '../../queries/idp/IdpSessionsBySidQuery.js'
+import { IdpSessionsBySubQuery } from '../../queries/idp/IdpSessionsBySubQuery.js'
+import { ApiKeyByIdQuery } from '../../queries/apiKey/ApiKeyQuery.js'
+import { DisableApiKeyCommand } from '../../commands/index.js'
+import { CreateAuthLogEntryCommand } from '../../commands/authLog/CreateAuthLogEntryCommand.js'
+import { IDPHandlerRegistry } from './IDPHandlerRegistry.js'
+import { IDPValidationError } from './IDPValidationError.js'
+
+export type BackchannelLogoutResult =
+	| { status: 'ok'; revokedCount: number }
+	| { status: 'provider_not_found' }
+	| { status: 'not_supported' }
+	| { status: 'invalid_token'; message: string }
+
+/**
+ * Handles an incoming OIDC Back-Channel Logout request (A10). Runs entirely on the HTTP auth path
+ * (no GraphQL resolver), so — like {@link IdpSessionRevalidator} — it owns its own audit write
+ * rather than deferring to a resolver. Flow:
+ *   1. resolve the IdP by slug (the back-channel endpoint carries a `?provider=` query param, since
+ *      the IdP only knows which client it is calling, not the Contember tenant/provider record);
+ *   2. validate the IdP-signed logout token and extract `sid` / `sub`;
+ *   3. look up the local federated session(s) the token targets and revoke their api_key(s).
+ *
+ * A logout token with a `sid` targets that single IdP session; a `sub`-only token (rare — most IdPs
+ * send a `sid`) targets *all* of that subject's federated sessions under the provider. Either way, a
+ * token that matches no live session is reported as `revokedCount: 0` and audited, not failed.
+ */
+export class BackchannelLogoutManager {
+	constructor(
+		private readonly idpRegistry: IDPHandlerRegistry,
+	) {}
+
+	async logout(db: DatabaseContext, providerSlug: string, logoutToken: string): Promise<BackchannelLogoutResult> {
+		const provider = await db.queryHandler.fetch(new IdentityProviderBySlugQuery(providerSlug))
+		if (!provider) {
+			return { status: 'provider_not_found' }
+		}
+
+		const handler = this.idpRegistry.getHandlerOrNull(provider.type)
+		if (!handler?.validateLogoutToken) {
+			return { status: 'not_supported' }
+		}
+
+		let config: {}
+		try {
+			config = handler.validateConfiguration(provider.configuration)
+		} catch (e) {
+			return { status: 'invalid_token', message: 'IdP configuration is invalid' }
+		}
+
+		let claims: { sid?: string; sub?: string }
+		try {
+			claims = await handler.validateLogoutToken(config, logoutToken)
+		} catch (e) {
+			return { status: 'invalid_token', message: e instanceof IDPValidationError ? e.message : 'Invalid logout token' }
+		}
+
+		const sessions = await this.resolveTargetSessions(db, provider.id, claims)
+		let revokedCount = 0
+		for (const session of sessions) {
+			const disabled = await db.commandBus.execute(new DisableApiKeyCommand(session.apiKeyId))
+			if (disabled) {
+				revokedCount++
+			}
+		}
+
+		await this.audit(db, provider.id, claims, revokedCount, sessions[0]?.apiKeyId)
+
+		return { status: 'ok', revokedCount }
+	}
+
+	private async resolveTargetSessions(
+		db: DatabaseContext,
+		identityProviderId: string,
+		claims: { sid?: string; sub?: string },
+	): Promise<IdpSessionBySidRow[]> {
+		// Prefer `sid` (targets one session); fall back to `sub` (targets all the subject's sessions).
+		if (claims.sid) {
+			return db.queryHandler.fetch(new IdpSessionsBySidQuery(identityProviderId, claims.sid))
+		}
+		if (claims.sub) {
+			return db.queryHandler.fetch(new IdpSessionsBySubQuery(identityProviderId, claims.sub))
+		}
+		return []
+	}
+
+	private async audit(
+		db: DatabaseContext,
+		identityProviderId: string,
+		claims: { sid?: string; sub?: string },
+		revokedCount: number,
+		targetApiKeyId: string | undefined,
+	): Promise<void> {
+		// Resolve the affected identity for the audit `invoked_by_id` from a targeted session, when
+		// one resolves. Otherwise leave it unset (→ NULL) — the provider id is NOT a valid identity id
+		// and inserting it would violate the `invoked_by_id` FK (the provider is recorded separately
+		// in `identity_provider_id`).
+		let invokedById: string | undefined
+		let personId: string | undefined
+		if (targetApiKeyId) {
+			const apiKeyRow = await db.queryHandler.fetch(new ApiKeyByIdQuery(targetApiKeyId))
+			if (apiKeyRow) {
+				invokedById = apiKeyRow.identity_id
+				personId = apiKeyRow.person_id ?? undefined
+			}
+		}
+
+		try {
+			await db.commandBus.execute(
+				new CreateAuthLogEntryCommand({
+					type: 'idp_backchannel_logout',
+					invokedById,
+					personId,
+					identityProviderId,
+					success: true,
+					eventData: { sid: claims.sid ?? null, sub: claims.sub ?? null, revokedCount },
+				}),
+			)
+		} catch {
+			// best-effort observability — never fail the logout because the audit write failed
+		}
+	}
+}

package/src/model/service/idp/IDPHandlerRegistry.ts

@@ -1,5 +1,5 @@
-import { IdentityProviderHandler } from './IdentityProviderHandler'
-import { IdentityProviderNotFoundError } from './IdentityProviderNotFoundError'
+import { IdentityProviderHandler } from './IdentityProviderHandler.js'
+import { IdentityProviderNotFoundError } from './IdentityProviderNotFoundError.js'
 
 export class IDPHandlerRegistry {
 	private providers: Record<string, IdentityProviderHandler<any>> = {}

package/src/model/service/idp/IDPManager.ts

@@ -1,16 +1,16 @@
-import { Response, ResponseError, ResponseOk } from '../../utils/Response'
-import { AddIdpErrorCode, DisableIdpErrorCode, EnableIdpErrorCode, UpdateIdpErrorCode } from '../../../schema'
-import { DatabaseContext } from '../../utils'
-import { IdentityProviderData } from '../../type'
-import { IdentityProviderBySlugQuery, IdentityProvidersQuery } from '../../queries'
-import { CreateIdpCommand } from '../../commands/idp/CreateIdpCommand'
-import { IDPHandlerRegistry } from './IDPHandlerRegistry'
-import { IdentityProviderNotFoundError } from './IdentityProviderNotFoundError'
-import { InvalidIDPConfigurationError } from './InvalidIDPConfigurationError'
-import { DisableIdpCommand } from '../../commands/idp/DisableIdpCommand'
-import { EnableIdpCommand } from '../../commands/idp/EnableIdpCommand'
-import { UpdateIdpCommand, UpdateIdpData } from '../../commands/idp/UpdateIdpCommand'
-import { IdentityProviderDto } from '../../queries/idp/types'
+import { Response, ResponseError, ResponseOk } from '../../utils/Response.js'
+import { AddIdpErrorCode, DisableIdpErrorCode, EnableIdpErrorCode, UpdateIdpErrorCode } from '../../../schema/index.js'
+import { DatabaseContext } from '../../utils/index.js'
+import { IdentityProviderData } from '../../type/index.js'
+import { IdentityProviderBySlugQuery, IdentityProvidersQuery } from '../../queries/index.js'
+import { CreateIdpCommand } from '../../commands/idp/CreateIdpCommand.js'
+import { IDPHandlerRegistry } from './IDPHandlerRegistry.js'
+import { IdentityProviderNotFoundError } from './IdentityProviderNotFoundError.js'
+import { InvalidIDPConfigurationError } from './InvalidIDPConfigurationError.js'
+import { DisableIdpCommand } from '../../commands/idp/DisableIdpCommand.js'
+import { EnableIdpCommand } from '../../commands/idp/EnableIdpCommand.js'
+import { UpdateIdpCommand, UpdateIdpData } from '../../commands/idp/UpdateIdpCommand.js'
+import { IdentityProviderDto } from '../../queries/idp/types.js'
 
 export class IDPManager {
 	constructor(

package/src/model/service/idp/IDPRevalidation.ts

@@ -0,0 +1,46 @@
+import * as Typesafe from '@contember/typesafe'
+
+/**
+ * Provider-agnostic re-validation settings, stored on an IdP's `configuration.revalidation`.
+ * Read both by the provider (to decide whether to capture session state at sign-in) and by
+ * the generic verify hook (`ApiKeyManager.verifyAndProlong`) to drive re-validation.
+ *
+ * The cadence is driven by the **access-token lifetime**, not a fixed interval: while the
+ * token is fresh the session is vouched-for and nothing happens; past `softRefreshThreshold`
+ * of its lifetime a proactive background (SWR) refresh kicks in; once the token has actually
+ * expired the refresh becomes blocking. See {@link IdpSessionRevalidator}.
+ *
+ * All fields optional; absent / `enabled: false` reproduces the pre-A24 behaviour exactly.
+ */
+export const IDPRevalidationConfig = Typesafe.partial({
+	enabled: Typesafe.boolean,
+	/**
+	 * Fraction (0–1) of the access-token lifetime after which a proactive background (SWR)
+	 * refresh starts — e.g. 0.5 = refresh once the token is half-expired. Default 0.5.
+	 */
+	softRefreshThreshold: Typesafe.number,
+	/**
+	 * Single-flight floor as a Postgres interval string: the minimum gap between revalidation
+	 * attempts, so a burst of requests past the threshold triggers only one refresh.
+	 * Default "10 seconds".
+	 */
+	minInterval: Typesafe.string,
+	/**
+	 * Throttle used when the IdP returns no token expiry (so the lifetime-based cadence can't
+	 * apply), as a Postgres interval string. Default "5 minutes".
+	 */
+	fallbackInterval: Typesafe.string,
+	/**
+	 * `auto` (default): SWR/background before expiry, blocking once expired. `blocking`: always
+	 * synchronous (zero revocation lag, at the cost of latency on the revalidation tick).
+	 */
+	mode: Typesafe.enumeration('auto', 'blocking'),
+	/** What to do when the IdP reports the session as gone. Currently only `revoke`. */
+	onFailure: Typesafe.enumeration('revoke'),
+})
+
+export type IDPRevalidationConfig = ReturnType<typeof IDPRevalidationConfig>
+
+export const REVALIDATION_DEFAULT_SOFT_THRESHOLD = 0.5
+export const REVALIDATION_DEFAULT_MIN_INTERVAL = '10 seconds'
+export const REVALIDATION_DEFAULT_FALLBACK_INTERVAL = '5 minutes'

package/src/model/service/idp/IdentityProviderHandler.ts

@@ -3,12 +3,65 @@ export interface InitIDPAuthResult {
 	sessionData: unknown
 }
 
+/**
+ * Provider-specific federated-session state persisted alongside a Contember session
+ * (see the `idp_session` table) so the session can be re-validated against the IdP
+ * after the initial sign-in. Opaque to the core — only the owning provider's
+ * `revalidate` interprets `tokens`. Token material is encrypted at rest.
+ */
+export type IDPSessionState = {
+	/** OIDC `sid` claim / SAML `SessionIndex`, when the IdP provides one. */
+	sessionId?: string
+	/** Provider-specific token payload (e.g. OIDC refresh/id token). Encrypted at rest. */
+	tokens?: Record<string, unknown>
+	/** IdP-asserted absolute expiry of the federated session, if known. */
+	expiresAt?: Date
+}
+
 export type IDPResponse = {
 	externalIdentifier: string
 	email?: string
 	name?: string
+	/** Whether the provider asserts the e-mail address is verified (OIDC `email_verified`). */
+	emailVerified?: boolean
+	/**
+	 * Federated-session state to persist for continuous re-validation. Present only when
+	 * the provider supports it and revalidation is enabled on the IdP configuration;
+	 * otherwise undefined and the session behaves like a plain password session.
+	 */
+	idpSession?: IDPSessionState
 } & Record<string, unknown>
 
+/** Input for building an RP-initiated (front-channel) logout redirect URL. */
+export type LogoutUrlRequest = {
+	/** The ID token issued at sign-in, used as `id_token_hint`. */
+	idToken?: string
+	/** Where the IdP should redirect the browser after it has logged the user out. */
+	postLogoutRedirectUri?: string
+}
+
+/** Claims extracted from a validated OIDC back-channel logout token (the subset we act on). */
+export type LogoutTokenClaims = {
+	/** The IdP session id (`sid`) the logout applies to, when the token targets a single session. */
+	sid?: string
+	/** The subject (`sub`) the logout applies to, when the token targets all the subject's sessions. */
+	sub?: string
+}
+
+/** Outcome of a federated-session re-validation against the IdP. */
+export type RevalidationResult =
+	| {
+		status: 'valid'
+		/** Fresh claims, if the revalidation method returned any (e.g. userinfo). */
+		claims?: Record<string, unknown>
+		/** Updated session state to persist (e.g. a rotated refresh token). */
+		idpSession?: IDPSessionState
+	}
+	| {
+		status: 'revoked'
+		reason: string
+	}
+
 export interface IdentityProviderHandler<Configuration extends {}> {
 	initAuth: (configuration: Configuration, data: unknown) => Promise<InitIDPAuthResult>
 
@@ -17,4 +70,26 @@ export interface IdentityProviderHandler<Configuration extends {}> {
 	validateConfiguration: (config: unknown) => Configuration
 
 	getPublicConfiguration?: (config: Configuration) => Partial<Configuration>
+
+	/**
+	 * Re-validate a previously established federated session against the IdP.
+	 * Present only on providers that support continuous re-validation (OIDC); absent on
+	 * providers that cannot (Apple, Facebook, SAML — which rely on a short max lifetime + SLO).
+	 */
+	revalidate?: (configuration: Configuration, session: IDPSessionState) => Promise<RevalidationResult>
+
+	/**
+	 * Build an RP-initiated (front-channel) logout redirect URL for this session (A10).
+	 * Returns null when the IdP advertises no `end_session_endpoint` — the caller then falls
+	 * back to a local-only logout. Present only on providers that support Single Logout (OIDC).
+	 */
+	buildLogoutUrl?: (configuration: Configuration, request: LogoutUrlRequest) => Promise<string | null>
+
+	/**
+	 * Validate an IdP-signed back-channel logout token (A10) and extract the targeted
+	 * `sid` / `sub`. Throws when the token is invalid (bad signature, wrong issuer/audience,
+	 * missing the back-channel `events` claim, etc.). Present only on providers that support
+	 * OIDC back-channel logout.
+	 */
+	validateLogoutToken?: (configuration: Configuration, logoutToken: string) => Promise<LogoutTokenClaims>
 }

package/src/model/service/idp/IdpSessionRevalidator.ts

@@ -0,0 +1,281 @@
+import { DatabaseContext } from '../../utils/index.js'
+import { ApiKeyRequestInfo } from '../../commands/index.js'
+import { ApiKeyRow } from '../../queries/apiKey/ApiKeyQuery.js'
+import { IdpSessionByApiKeyQuery, IdpSessionRow } from '../../queries/idp/IdpSessionByApiKeyQuery.js'
+import { IDPHandlerRegistry } from './IDPHandlerRegistry.js'
+import { ClaimIdpRevalidationCommand } from '../../commands/idp/ClaimIdpRevalidationCommand.js'
+import { UpdateIdpSessionCommand } from '../../commands/idp/UpdateIdpSessionCommand.js'
+import { DisableApiKeyCommand } from '../../commands/index.js'
+import { CreateAuthLogEntryCommand } from '../../commands/authLog/CreateAuthLogEntryCommand.js'
+import { REVALIDATION_DEFAULT_FALLBACK_INTERVAL, REVALIDATION_DEFAULT_MIN_INTERVAL, REVALIDATION_DEFAULT_SOFT_THRESHOLD } from './IDPRevalidation.js'
+import { IdentityProviderHandler, RevalidationResult } from './IdentityProviderHandler.js'
+
+export type RevalidationOutcome = 'valid' | 'revoked'
+
+type ResolvedRevalidationConfig = {
+	enabled: boolean
+	softThreshold: number
+	minInterval: string
+	fallbackInterval: string
+	mode: 'auto' | 'blocking'
+}
+
+/**
+ * Decision for the current request: whether to attempt a revalidation, and if so whether it
+ * must block the request. `claimInterval` is the single-flight floor for the atomic claim.
+ */
+type Decision = null | { blocking: boolean; claimInterval: string }
+
+/**
+ * Re-validates IdP-backed sessions against their identity provider on the verify hot path
+ * (A24). Invoked from `ApiKeyManager.verifyAndProlong`. Operates entirely through the supplied
+ * database contexts and the command bus, so it does not depend on `ApiKeyManager` (no DI cycle).
+ *
+ * The cadence is driven by the **access-token lifetime**, not a fixed interval:
+ *   - while the token is fresh (before `softRefreshThreshold` of its lifetime) → skip, free;
+ *   - past the threshold but not yet expired → a proactive **background (SWR)** refresh, so the
+ *     request keeps zero added latency and the token is renewed before it dies;
+ *   - once the token has actually expired → a **blocking** refresh (we can't serve a dead token).
+ * `mode: 'blocking'` forces every revalidation synchronous (zero revocation lag). When the IdP
+ * returns no token expiry, falls back to a plain `fallbackInterval` background throttle.
+ */
+export class IdpSessionRevalidator {
+	constructor(
+		private readonly idpRegistry: IDPHandlerRegistry,
+	) {
+	}
+
+	async revalidate(
+		dbContext: DatabaseContext,
+		readDbContext: DatabaseContext,
+		apiKeyRow: ApiKeyRow,
+		requestInfo?: ApiKeyRequestInfo,
+	): Promise<RevalidationOutcome> {
+		const row = await readDbContext.queryHandler.fetch(new IdpSessionByApiKeyQuery(apiKeyRow.id, readDbContext.providers))
+		if (!row) {
+			// not a federated session (password / IdP without revalidation) — fast no-op
+			return 'valid'
+		}
+
+		const config = this.resolveConfig(row.providerConfiguration)
+		if (!config.enabled) {
+			return 'valid'
+		}
+
+		// A disabled IdP no longer vouches for its sessions.
+		if (row.providerDisabledAt) {
+			await this.revoke(dbContext, apiKeyRow, row, 'idp_disabled', requestInfo)
+			return 'revoked'
+		}
+
+		const handler = this.idpRegistry.getHandlerOrNull(row.providerType)
+		if (!handler?.revalidate) {
+			// provider can't actively re-validate (e.g. SAML) — rely on expiry / SLO
+			return 'valid'
+		}
+
+		const decision = this.decide(row, config, dbContext.providers.now())
+		if (!decision) {
+			// token still fresh — vouched for, no IdP call
+			return 'valid'
+		}
+
+		// Atomic claim = single-flight. Loser (within the floor window, or lost the race) serves stale.
+		let claimed: boolean
+		try {
+			claimed = await dbContext.commandBus.execute(new ClaimIdpRevalidationCommand(row.id, decision.claimInterval))
+		} catch {
+			// invalid interval string or transient DB error — fail open, retry next request
+			return 'valid'
+		}
+		if (!claimed) {
+			return 'valid'
+		}
+
+		if (decision.blocking) {
+			return await this.runRevalidation(dbContext, handler, row, apiKeyRow, requestInfo)
+		}
+
+		// SWR: serve this request from the (still valid) token, refresh after the response.
+		// The work runs detached (after the response is sent), so any rejection — a transient
+		// DB error in the revoke / persist writes, a corrupt-config throw — must be swallowed
+		// here; otherwise it becomes an unhandledRejection and can take the worker down. The
+		// session is simply kept and re-tried on a later request (the claim floor throttles).
+		setImmediate(() => {
+			this.runRevalidation(dbContext, handler, row, apiKeyRow, requestInfo).catch(() => {})
+		})
+		return 'valid'
+	}
+
+	/**
+	 * Decide whether (and how) to revalidate, purely from timestamps — no interval parsing in
+	 * JS (the claim handles intervals in SQL). Returns null to skip.
+	 */
+	private decide(row: IdpSessionRow, config: ResolvedRevalidationConfig, now: Date): Decision {
+		const expiresAt = row.session.expiresAt
+		const obtainedAt = row.tokenObtainedAt
+
+		// No lifetime info from the IdP → plain background throttle on fallbackInterval.
+		if (!expiresAt || !obtainedAt) {
+			return { blocking: config.mode === 'blocking', claimInterval: config.fallbackInterval }
+		}
+
+		const lifetimeMs = expiresAt.getTime() - obtainedAt.getTime()
+		const softAtMs = obtainedAt.getTime() + lifetimeMs * config.softThreshold
+		const nowMs = now.getTime()
+
+		if (nowMs < softAtMs) {
+			return null // still within the trusted window
+		}
+
+		const expired = nowMs >= expiresAt.getTime()
+		return { blocking: config.mode === 'blocking' || expired, claimInterval: config.minInterval }
+	}
+
+	private async runRevalidation(
+		dbContext: DatabaseContext,
+		handler: IdentityProviderHandler<{}>,
+		row: IdpSessionRow,
+		apiKeyRow: ApiKeyRow,
+		requestInfo?: ApiKeyRequestInfo,
+	): Promise<RevalidationOutcome> {
+		let config: {}
+		try {
+			config = handler.validateConfiguration(row.providerConfiguration)
+		} catch {
+			// corrupt stored config — must NOT revoke; keep the session and retry later. Audit
+			// it so the operator can tell "vouched for" apart from "silently broken" (without an
+			// entry, a config typo disables re-validation invisibly for the life of every session).
+			await this.logRevalidationFailed(dbContext, apiKeyRow, row, 'config_invalid', requestInfo)
+			return 'valid'
+		}
+
+		let result: RevalidationResult
+		try {
+			result = await handler.revalidate!(config, row.session)
+		} catch {
+			// transient failure (network / IdP down) — must NOT revoke; keep the session and retry
+			// on a later request (the claim floor prevents hammering the IdP). Audited (throttled
+			// to one entry per claim window) so a prolonged IdP outage is visible rather than a
+			// silent fail-open.
+			await this.logRevalidationFailed(dbContext, apiKeyRow, row, 'revalidation_error', requestInfo)
+			return 'valid'
+		}
+
+		if (result.status === 'revoked') {
+			await this.revoke(dbContext, apiKeyRow, row, result.reason, requestInfo)
+			return 'revoked'
+		}
+
+		// Still valid — persist the rotated token (resets the lifetime reference) / refreshed
+		// expiry. A rotation is a real, low-frequency event (token-lifetime cadence), so we
+		// audit it as `idp_session_revalidated`; the no-op userinfo/introspection probes
+		// (no rotated session) are intentionally NOT logged to keep the audit log usable.
+		//
+		// The IdP has already vouched for the session, so these post-success writes are pure
+		// best-effort bookkeeping (they only reset the SWR cadence reference). A transient DB
+		// error or an `encrypt()` throw here must NOT fail the request — otherwise a blocking
+		// revalidation fails closed on a successful refresh, contradicting "fail open" (the SWR
+		// path already swallows this). Keep the existing row; the claim floor throttles a retry.
+		if (result.idpSession) {
+			try {
+				await dbContext.commandBus.execute(new UpdateIdpSessionCommand(row.id, result.idpSession))
+				await this.logRevalidated(dbContext, apiKeyRow, row, requestInfo)
+			} catch {
+				// fall through — session stays valid, persist retried on a later request
+			}
+		}
+		return 'valid'
+	}
+
+	private async logRevalidated(dbContext: DatabaseContext, apiKeyRow: ApiKeyRow, row: IdpSessionRow, requestInfo?: ApiKeyRequestInfo): Promise<void> {
+		await dbContext.commandBus.execute(
+			new CreateAuthLogEntryCommand({
+				type: 'idp_session_revalidated',
+				invokedById: apiKeyRow.identity_id,
+				personId: apiKeyRow.person_id ?? undefined,
+				identityProviderId: row.identityProviderId,
+				personTokenId: apiKeyRow.id,
+				success: true,
+				ipAddress: requestInfo?.ip,
+				userAgent: requestInfo?.userAgent,
+			}),
+		)
+	}
+
+	/**
+	 * Audit a fail-open: the IdP couldn't be consulted (transient outage) or the stored config is
+	 * corrupt, so we kept the session rather than revoking it. Naturally throttled to one entry
+	 * per claim window (we only reach here after a successful claim, which bumps
+	 * `last_validated_at`). The write is best-effort and self-contained — a failure to audit must
+	 * never propagate and fail a blocking verify request (the whole point of failing open).
+	 */
+	private async logRevalidationFailed(
+		dbContext: DatabaseContext,
+		apiKeyRow: ApiKeyRow,
+		row: IdpSessionRow,
+		errorCode: 'config_invalid' | 'revalidation_error',
+		requestInfo?: ApiKeyRequestInfo,
+	): Promise<void> {
+		try {
+			await dbContext.commandBus.execute(
+				new CreateAuthLogEntryCommand({
+					type: 'idp_session_revalidation_failed',
+					invokedById: apiKeyRow.identity_id,
+					personId: apiKeyRow.person_id ?? undefined,
+					identityProviderId: row.identityProviderId,
+					personTokenId: apiKeyRow.id,
+					// not a security failure (the session is kept) — a fail-open marker the operator
+					// can alert on. `success: true` keeps it out of the failed-login funnels.
+					success: true,
+					errorCode,
+					ipAddress: requestInfo?.ip,
+					userAgent: requestInfo?.userAgent,
+				}),
+			)
+		} catch {
+			// best-effort observability — never fail the request because the audit write failed
+		}
+	}
+
+	private async revoke(
+		dbContext: DatabaseContext,
+		apiKeyRow: ApiKeyRow,
+		row: IdpSessionRow,
+		reason: string,
+		requestInfo?: ApiKeyRequestInfo,
+	): Promise<void> {
+		await dbContext.commandBus.execute(new DisableApiKeyCommand(apiKeyRow.id))
+		await dbContext.commandBus.execute(
+			new CreateAuthLogEntryCommand({
+				type: 'idp_session_revoked',
+				invokedById: apiKeyRow.identity_id,
+				personId: apiKeyRow.person_id ?? undefined,
+				identityProviderId: row.identityProviderId,
+				personTokenId: apiKeyRow.id,
+				success: false,
+				errorCode: reason,
+				ipAddress: requestInfo?.ip,
+				userAgent: requestInfo?.userAgent,
+				// the action payload belongs in `event_data` (where every other audit event puts
+				// it and where the admin UI / AuthLogQueryResolver reads it); `metadata` is for
+				// transport context (forwarder IP/UA).
+				eventData: { reason },
+			}),
+		)
+	}
+
+	private resolveConfig(configuration: Record<string, unknown>): ResolvedRevalidationConfig {
+		const raw = (configuration.revalidation ?? {}) as Record<string, unknown>
+		const threshold = typeof raw.softRefreshThreshold === 'number' && raw.softRefreshThreshold > 0 && raw.softRefreshThreshold <= 1
+			? raw.softRefreshThreshold
+			: REVALIDATION_DEFAULT_SOFT_THRESHOLD
+		return {
+			enabled: raw.enabled === true,
+			softThreshold: threshold,
+			minInterval: typeof raw.minInterval === 'string' ? raw.minInterval : REVALIDATION_DEFAULT_MIN_INTERVAL,
+			fallbackInterval: typeof raw.fallbackInterval === 'string' ? raw.fallbackInterval : REVALIDATION_DEFAULT_FALLBACK_INTERVAL,
+			mode: raw.mode === 'blocking' ? 'blocking' : 'auto',
+		}
+	}
+}

package/src/model/service/idp/PersonIdentityProviderManager.ts

@@ -0,0 +1,54 @@
+import { Response, ResponseError, ResponseOk } from '../../utils/Response.js'
+import { DisconnectIdpErrorCode } from '../../../schema/index.js'
+import { DatabaseContext } from '../../utils/index.js'
+import { ConfigurationQuery, PersonIdentityProviderRow, PersonIdentityProvidersQuery, PersonRow } from '../../queries/index.js'
+import { DisconnectPersonIdentityProviderCommand } from '../../commands/idp/DisconnectPersonIdentityProviderCommand.js'
+import { isPasswordlessEnabled } from '../helpers/isPasswordlessEnabled.js'
+
+/**
+ * Manages the external IdP connections of the *currently authenticated* person.
+ *
+ * Lock-out policy: a person may always disconnect a provider as long as it does
+ * not remove their last remaining sign-in method. A connection is refused only
+ * when, after removal, the person would have no password, no passwordless
+ * sign-in enabled and no other *usable* IdP connection left — which would lock
+ * them out of their account entirely. Whether passwordless counts is decided by
+ * the same tenant policy the sign-in flow applies, and connections to disabled
+ * providers are not counted as a usable fallback (they cannot sign in).
+ */
+export class PersonIdentityProviderManager {
+	public async listPersonIdentityProviders(db: DatabaseContext, personId: string): Promise<PersonIdentityProviderRow[]> {
+		return await db.queryHandler.fetch(new PersonIdentityProvidersQuery(personId))
+	}
+
+	public async disconnectIdentityProvider(db: DatabaseContext, person: PersonRow, connectionId: string): Promise<DisconnectIDPResponse> {
+		return await db.transaction(async db => {
+			const connections = await db.queryHandler.fetch(new PersonIdentityProvidersQuery(person.id))
+			const connection = connections.find(it => it.id === connectionId)
+			if (!connection) {
+				return new ResponseError('NOT_FOUND', `You are not connected to the identity provider connection "${connectionId}".`)
+			}
+
+			const configuration = await db.queryHandler.fetch(new ConfigurationQuery(db.providers))
+			const hasPassword = person.password_hash !== null
+			const hasPasswordless = isPasswordlessEnabled(configuration.passwordless.enabled, person.passwordless_enabled)
+			const otherUsableConnections = connections.filter(it => it.id !== connection.id && it.identityProviderDisabledAt === null)
+			const wouldLockOut = !hasPassword && !hasPasswordless && otherUsableConnections.length === 0
+			if (wouldLockOut) {
+				return new ResponseError(
+					'LAST_AUTH_METHOD',
+					'Cannot disconnect the only remaining sign-in method. Set up a password or another sign-in method first.',
+				)
+			}
+
+			await db.commandBus.execute(new DisconnectPersonIdentityProviderCommand(person.id, connection.id))
+			return new ResponseOk({ slug: connection.identityProviderSlug })
+		})
+	}
+}
+
+export interface DisconnectIDPResult {
+	readonly slug: string
+}
+
+export type DisconnectIDPResponse = Response<DisconnectIDPResult, DisconnectIdpErrorCode>