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

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

@@ -9,6 +9,10 @@ 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'
+import { IDPClaimSyncService } from './IDPClaimSyncService.js'
+import { Logger } from '@contember/logger'
+import { parseClaimMapping } from './ClaimMapping.js'
+import { JSONValue } from '@contember/schema'
 
 export type RevalidationOutcome = 'valid' | 'revoked'
 
@@ -42,6 +46,8 @@ type Decision = null | { blocking: boolean; claimInterval: string }
 export class IdpSessionRevalidator {
 	constructor(
 		private readonly idpRegistry: IDPHandlerRegistry,
+		private readonly claimSyncService: IDPClaimSyncService,
+		private readonly logger: Logger,
 	) {
 	}
 
@@ -84,7 +90,8 @@ export class IdpSessionRevalidator {
 		let claimed: boolean
 		try {
 			claimed = await dbContext.commandBus.execute(new ClaimIdpRevalidationCommand(row.id, decision.claimInterval))
-		} catch {
+		} catch (e) {
+			this.logger.warn(e, { message: 'IdP session revalidation: claim failed', idpSessionId: row.id })
 			// invalid interval string or transient DB error — fail open, retry next request
 			return 'valid'
 		}
@@ -102,7 +109,9 @@ export class IdpSessionRevalidator {
 		// 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(() => {})
+			this.runRevalidation(dbContext, handler, row, apiKeyRow, requestInfo).catch(e => {
+				this.logger.error(e, { message: 'IdP session revalidation: background run failed', idpSessionId: row.id })
+			})
 		})
 		return 'valid'
 	}
@@ -142,7 +151,8 @@ export class IdpSessionRevalidator {
 		let config: {}
 		try {
 			config = handler.validateConfiguration(row.providerConfiguration)
-		} catch {
+		} catch (e) {
+			this.logger.warn(e, { message: 'IdP session revalidation: stored configuration is invalid', idpSessionId: row.id })
 			// 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).
@@ -153,7 +163,8 @@ export class IdpSessionRevalidator {
 		let result: RevalidationResult
 		try {
 			result = await handler.revalidate!(config, row.session)
-		} catch {
+		} catch (e) {
+			this.logger.warn(e, { message: 'IdP session revalidation: identity provider call failed', idpSessionId: row.id })
 			// 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
@@ -181,13 +192,101 @@ export class IdpSessionRevalidator {
 			try {
 				await dbContext.commandBus.execute(new UpdateIdpSessionCommand(row.id, result.idpSession))
 				await this.logRevalidated(dbContext, apiKeyRow, row, requestInfo)
-			} catch {
+			} catch (e) {
+				this.logger.error(e, { message: 'IdP session revalidation: persisting the rotated session failed', idpSessionId: row.id })
 				// fall through — session stays valid, persist retried on a later request
 			}
 		}
+
+		// A09 — re-apply the IdP's claim mapping when the refresh returned fresh claims, so an `always`
+		// mapping keeps an established session's project memberships in sync with the IdP's current claims
+		// without requiring a full re-login. `sticky` mappings self-skip (the sync passes isNewPerson=false).
+		// `claimsComplete` tells the sync whether the refresh rebuilt sign-in's full claim surface, so it can
+		// reconcile (incl. `unmatched: "remove"`) exactly like sign-in. Strictly fail-open — see `syncClaims`.
+		if (result.claims) {
+			await this.syncClaims(dbContext, row, apiKeyRow, result.claims, result.claimsComplete === true, requestInfo)
+		}
 		return 'valid'
 	}
 
+	/**
+	 * Re-apply the claim mapping on a successful refresh. Runs in its own transaction (atomic apply of
+	 * the membership changes) and never throws: the IdP has already vouched for the session, so a
+	 * malformed mapping or a transient apply error must not revoke or fail it. A real membership change
+	 * is audited as `idp_role_mapped`; a failure is audited as `idp_role_mapping_failed` (fail-open
+	 * marker), mirroring the sign-in path. `claimsComplete` carries whether the refresh rebuilt sign-in's
+	 * full claim surface (so removal reconciliation is safe) — see `allowRemoval` below.
+	 */
+	private async syncClaims(
+		dbContext: DatabaseContext,
+		row: IdpSessionRow,
+		apiKeyRow: ApiKeyRow,
+		claims: Record<string, unknown>,
+		claimsComplete: boolean,
+		requestInfo?: ApiKeyRequestInfo,
+	): Promise<void> {
+		try {
+			const mapping = parseClaimMapping(row.providerConfiguration)
+			if (!mapping) {
+				return
+			}
+			// Atomic apply in its own transaction (the verify path has no surrounding one). `always`-only:
+			// the sync passes isNewPerson=false, so a `sticky` mapping self-skips and returns a null audit.
+			// Refresh mirrors sign-in as closely as the claim surface allows: when the provider returned its
+			// COMPLETE surface (`claimsComplete` — `method: "refresh"` rebuilding sign-in's id-token + userinfo
+			// merge), `unmatched: "remove"` reconciliation runs here too. A partial surface (a userinfo-only
+			// probe, or a refresh whose userinfo fetch failed) passes `allowRemoval: false`, so refresh stays
+			// additive-only and a membership the IdP still asserts is never stripped off an incomplete surface.
+			const { audit, droppedUnsafeRules } = await dbContext.transaction(db =>
+				this.claimSyncService.sync(db, mapping, claims, { id: apiKeyRow.identity_id }, false, { allowRemoval: claimsComplete })
+			)
+			if (audit) {
+				await this.logRoleMapping(dbContext, apiKeyRow, row, 'idp_role_mapped', audit, requestInfo)
+			}
+			// The apply-time safety backstop dropped a configured rule — emit the fail-open marker so a broken
+			// mapping is visible on the refresh path too, mirroring sign-in (the marker carries no claim values).
+			if (droppedUnsafeRules) {
+				await this.logRoleMapping(dbContext, apiKeyRow, row, 'idp_role_mapping_failed', undefined, requestInfo)
+			}
+		} catch (e) {
+			this.logger.warn(e, { message: 'IdP session revalidation: claim mapping sync failed', idpSessionId: row.id })
+			// Strictly fail-open: a malformed mapping or a transient apply error must never revoke or
+			// fail an already-vouched-for session. The transaction rolls back any partial apply.
+			await this.logRoleMapping(dbContext, apiKeyRow, row, 'idp_role_mapping_failed', undefined, requestInfo)
+		}
+	}
+
+	private async logRoleMapping(
+		dbContext: DatabaseContext,
+		apiKeyRow: ApiKeyRow,
+		row: IdpSessionRow,
+		type: 'idp_role_mapped' | 'idp_role_mapping_failed',
+		eventData: JSONValue | undefined,
+		requestInfo?: ApiKeyRequestInfo,
+	): Promise<void> {
+		try {
+			await dbContext.commandBus.execute(
+				new CreateAuthLogEntryCommand({
+					type,
+					invokedById: apiKeyRow.identity_id,
+					personId: apiKeyRow.person_id ?? undefined,
+					// The membership change affects this session's own person — record it as the target too,
+					// so an admin querying membership changes by target_person_id sees IdP-driven grants/revokes
+					// (consistent with the project_membership_* audit events).
+					targetPersonId: apiKeyRow.person_id ?? undefined,
+					identityProviderId: row.identityProviderId,
+					success: true,
+					eventData,
+					ipAddress: requestInfo?.ip,
+					userAgent: requestInfo?.userAgent,
+				}),
+			)
+		} catch (e) {
+			this.logger.error(e, { message: `IdP session revalidation: writing the ${type} audit entry failed`, idpSessionId: row.id })
+			// best-effort audit — never fail the request because the audit write failed
+		}
+	}
+
 	private async logRevalidated(dbContext: DatabaseContext, apiKeyRow: ApiKeyRow, row: IdpSessionRow, requestInfo?: ApiKeyRequestInfo): Promise<void> {
 		await dbContext.commandBus.execute(
 			new CreateAuthLogEntryCommand({
@@ -195,10 +294,10 @@ export class IdpSessionRevalidator {
 				invokedById: apiKeyRow.identity_id,
 				personId: apiKeyRow.person_id ?? undefined,
 				identityProviderId: row.identityProviderId,
-				personTokenId: apiKeyRow.id,
 				success: true,
 				ipAddress: requestInfo?.ip,
 				userAgent: requestInfo?.userAgent,
+				eventData: { apiKeyId: apiKeyRow.id },
 			}),
 		)
 	}
@@ -224,16 +323,17 @@ export class IdpSessionRevalidator {
 					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,
+					eventData: { apiKeyId: apiKeyRow.id },
 				}),
 			)
-		} catch {
+		} catch (e) {
+			this.logger.error(e, { message: 'IdP session revalidation: writing the idp_session_revalidation_failed audit entry failed', idpSessionId: row.id })
 			// best-effort observability — never fail the request because the audit write failed
 		}
 	}
@@ -246,23 +346,28 @@ export class IdpSessionRevalidator {
 		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 },
-			}),
-		)
+		try {
+			await dbContext.commandBus.execute(
+				new CreateAuthLogEntryCommand({
+					type: 'idp_session_revoked',
+					invokedById: apiKeyRow.identity_id,
+					personId: apiKeyRow.person_id ?? undefined,
+					identityProviderId: row.identityProviderId,
+					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, apiKeyId: apiKeyRow.id },
+				}),
+			)
+		} catch (e) {
+			this.logger.error(e, { message: 'IdP session revalidation: writing the idp_session_revoked audit entry failed', idpSessionId: row.id })
+			// best-effort audit: the key is already disabled, so the request must still be answered
+			// as revoked rather than fail on the audit write
+		}
 	}
 
 	private resolveConfig(configuration: Record<string, unknown>): ResolvedRevalidationConfig {

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

@@ -29,6 +29,14 @@ export class PersonIdentityProviderManager {
 				return new ResponseError('NOT_FOUND', `You are not connected to the identity provider connection "${connectionId}".`)
 			}
 
+			// The link is what binds the person to the provider's policy, so they cannot remove it themselves.
+			if (connection.identityProviderDisableLocalAuthentication) {
+				return new ResponseError(
+					'IDP_REQUIRED',
+					`The identity provider "${connection.identityProviderSlug}" is the only way you may sign in; its connection cannot be removed.`,
+				)
+			}
+
 			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)

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

@@ -6,6 +6,10 @@ export * from './BackchannelLogoutManager.js'
 export * from './IDPRevalidation.js'
 export * from './IDPManager.js'
 export * from './PersonIdentityProviderManager.js'
+export * from './ClaimMapping.js'
+export * from './ClaimMappingEvaluator.js'
+export * from './ClaimMappingValidation.js'
+export * from './IDPClaimSyncService.js'
 export * from './IDPResponseError.js'
 export * from './IDPValidationError.js'
 export * from './InvalidIDPConfigurationError.js'

package/src/model/service/idp/providers/OIDCHelpers.ts

@@ -63,13 +63,136 @@ export type HandleOIDCResponseOptions = {
 	claimMapping?: OIDCClaimMapping
 }
 
-/** Read a claim by name, supporting dot-paths into nested objects (`a.b.c`). */
+/**
+ * Read a claim by name, supporting dot-paths into nested objects (`a.b.c`). Own-property only at every
+ * segment (mirrors `ClaimMappingEvaluator.resolvePath`): a configured path must never descend into an
+ * inherited member, so a `__proto__` / `constructor` segment cannot surface an `Object.prototype` value
+ * as the externalIdentifier / email / name.
+ */
 const getClaim = (source: Record<string, unknown>, path: string): unknown =>
 	path.split('.').reduce<unknown>(
-		(acc, key) => (acc != null && typeof acc === 'object' ? (acc as Record<string, unknown>)[key] : undefined),
+		(
+			acc,
+			key,
+		) => (acc != null && typeof acc === 'object' && Object.prototype.hasOwnProperty.call(acc, key) ? (acc as Record<string, unknown>)[key] : undefined),
 		source,
 	)
 
+/**
+ * Lift a configured nested attributes object (`attributesKey`, notably Apereo CAS's `attributes`) to the
+ * top level so providers that nest their claims map without a code change. The nested attributes are
+ * UNSIGNED, so they are spread UNDER `source` — a signed top-level claim keeps precedence over an
+ * attributes-level value. Shared by the sign-in response handler ({@link handleOIDCResponse}) and the
+ * session-refresh path ({@link revalidateOIDC}) so BOTH see the same claim surface; without this, an
+ * `attributesKey` provider's A09 claim mapping would resolve at sign-in but silently not on refresh.
+ */
+export const liftNestedClaims = (source: Record<string, unknown>, attributesKey: string | undefined): Record<string, unknown> => {
+	if (!attributesKey) {
+		return source
+	}
+	const nested = Object.prototype.hasOwnProperty.call(source, attributesKey) ? source[attributesKey] : undefined
+	if (nested !== null && typeof nested === 'object' && !Array.isArray(nested)) {
+		return { ...nested, ...source }
+	}
+	return source
+}
+
+type NormalizedClaims = Record<string, unknown> & {
+	externalIdentifier: string
+	email: string | undefined
+	name: string | undefined
+	emailVerified: boolean
+}
+
+/**
+ * Build the normalized claim surface shared by sign-in ({@link handleOIDCResponse}) and session refresh
+ * ({@link revalidateOIDC}): lift any configured nested attributes object to the top level, then layer the
+ * mapped identity fields (`externalIdentifier` / `email` / `name` / `emailVerified`) over the raw claims.
+ * BOTH paths run this SAME normalization so an A09 claim-mapping rule resolves identically whether it
+ * targets a raw provider claim or one of the normalized identity fields — without it the two surfaces
+ * diverged (refresh saw the raw claim, sign-in the mapped value).
+ *
+ * `subFallback` is the signature-verified ID-token `sub`, used when a custom `externalIdentifier` mapping
+ * resolves to nothing: at sign-in it is guaranteed present; on refresh it is the refreshed id-token's `sub`
+ * (or, for the userinfo method, the userinfo `sub`). Throws (account-takeover guard) when the mapped
+ * subject is a non-scalar or resolves empty — the refresh caller catches this and skips the sync.
+ */
+const normalizeClaims = (
+	rawSource: Record<string, unknown>,
+	claimMapping: OIDCClaimMapping | undefined,
+	subFallback: string | undefined,
+): NormalizedClaims => {
+	const source = liftNestedClaims(rawSource, claimMapping?.attributesKey)
+
+	// The OIDC `email_verified` claim is a boolean per spec, but some providers send the
+	// string "true". userInfo (and any unwrapped attributes) take precedence over the ID token.
+	const rawEmailVerified = source.email_verified
+	const emailVerified = rawEmailVerified === true || rawEmailVerified === 'true'
+
+	// `externalIdentifier` is the federation key persisted in `person_identity_provider` and
+	// matched on the next sign-in, so it must be a stable scalar. A `claimMapping` that pointed
+	// it at an object/array would otherwise be coerced by `String(...)` to `'[object Object]'` /
+	// a comma-join — collapsing every user of the provider onto one key (account takeover). Fail
+	// closed instead. The default `sub` path is safe (openid-client guarantees `sub` is a string).
+	const mappedSubject = getClaim(source, claimMapping?.externalIdentifier ?? 'sub')
+	let externalIdentifier: string
+	if (mappedSubject === undefined || mappedSubject === null) {
+		externalIdentifier = subFallback ?? ''
+	} else if (typeof mappedSubject === 'string' || typeof mappedSubject === 'number') {
+		externalIdentifier = String(mappedSubject)
+	} else {
+		throw new IDPValidationError(`The mapped externalIdentifier claim is not a scalar value`)
+	}
+	if (externalIdentifier === '') {
+		throw new IDPValidationError(`The mapped externalIdentifier claim resolved to an empty value`)
+	}
+
+	// `email` / `name` are typed `string | undefined` on IDPResponse and feed the by-e-mail
+	// account lookup (which crashes on a non-string). `...source` already placed the raw claim
+	// of whatever type, so OVERWRITE (don't conditionally add) with the mapped value when it is
+	// a string, otherwise `undefined` — a non-string claim must not leak through `...source`.
+	const email = getClaim(source, claimMapping?.email ?? 'email')
+	const name = resolveName(source, claimMapping)
+
+	return {
+		...source,
+		externalIdentifier,
+		email: typeof email === 'string' ? email : undefined,
+		name,
+		emailVerified,
+	}
+}
+
+/**
+ * Resolve the display name, falling back to `given_name` + `family_name` when there is no usable
+ * `name` claim.
+ *
+ * `name` is optional in OIDC core and plenty of providers omit it while sending the parts — Apereo
+ * CAS and Entra ID do, and so does Keycloak under its default mappers. Without the fallback,
+ * `CreatePersonCommand` lands on its own last-resort default and a federated person ends up named
+ * after the local part of their e-mail (`jan.novak`) despite the IdP having reported "Jan Novák".
+ * A single-path `claimMapping.name` cannot express this: the value has to be composed from two
+ * claims, not selected from one.
+ *
+ * An explicitly configured `claimMapping.name` is honoured as-is, fallback included — mapping a
+ * claim is a statement about where the name lives, and quietly substituting a different source
+ * would defeat it. A blank claim counts as absent: an empty string is not a display name, and
+ * treating it as one would keep the fallback (and `CreatePersonCommand`'s) from ever running.
+ */
+const resolveName = (source: Record<string, unknown>, claimMapping: OIDCClaimMapping | undefined): string | undefined => {
+	const mapped = getClaim(source, claimMapping?.name ?? 'name')
+	if (typeof mapped === 'string' && mapped.trim() !== '') {
+		return mapped
+	}
+	if (claimMapping?.name !== undefined) {
+		return undefined
+	}
+	const parts = [getClaim(source, 'given_name'), getClaim(source, 'family_name')]
+		.filter((part): part is string => typeof part === 'string' && part.trim() !== '')
+		.map(part => part.trim())
+	return parts.length > 0 ? parts.join(' ') : undefined
+}
+
 export const handleOIDCResponse = async (
 	client: Client,
 	{ sessionData, redirectUrl, ...otherData }: OIDCResponseData,
@@ -87,58 +210,15 @@ export const handleOIDCResponse = async (
 		const oidcResult = returnOIDCResult ? result : {}
 		const idpSession = captureSession ? tokenSetToSessionState(result, typeof claims.sid === 'string' ? claims.sid : undefined) : undefined
 
-		// Merge ID-token claims with userInfo (userInfo wins, per spec). Then optionally lift a
-		// nested attributes object to the top level so providers that nest their claims (notably
-		// Apereo CAS userinfo, which returns them under `attributes`) map without a code change.
-		// The nested attributes are UNSIGNED, so they must not override a claim already present in
-		// the (signature-verified) ID-token / userInfo merge — spread them UNDER `source`, not over
-		// it, so a signed `sub` / `email_verified` keeps precedence over an attributes-level value.
-		let source: Record<string, unknown> = { ...claimsWithoutHashes, ...userInfo }
-		const attributesKey = claimMapping?.attributesKey
-		if (attributesKey) {
-			const nested = source[attributesKey]
-			if (nested && typeof nested === 'object' && !Array.isArray(nested)) {
-				source = { ...(nested as Record<string, unknown>), ...source }
-			}
-		}
-
-		// The OIDC `email_verified` claim is a boolean per spec, but some providers send the
-		// string "true". userInfo (and any unwrapped attributes) take precedence over the ID token.
-		const rawEmailVerified = source.email_verified
-		const emailVerified = rawEmailVerified === true || rawEmailVerified === 'true'
-
-		// `externalIdentifier` is the federation key persisted in `person_identity_provider` and
-		// matched on the next sign-in, so it must be a stable scalar. A `claimMapping` that pointed
-		// it at an object/array would otherwise be coerced by `String(...)` to `'[object Object]'` /
-		// a comma-join — collapsing every user of the provider onto one key (account takeover). Fail
-		// closed instead. The default `sub` path is safe (openid-client guarantees `sub` is a string).
-		const mappedSubject = getClaim(source, claimMapping?.externalIdentifier ?? 'sub')
-		let externalIdentifier: string
-		if (mappedSubject === undefined || mappedSubject === null) {
-			externalIdentifier = claims.sub
-		} else if (typeof mappedSubject === 'string' || typeof mappedSubject === 'number') {
-			externalIdentifier = String(mappedSubject)
-		} else {
-			throw new IDPValidationError(`The mapped externalIdentifier claim is not a scalar value`)
-		}
-		if (externalIdentifier === '') {
-			throw new IDPValidationError(`The mapped externalIdentifier claim resolved to an empty value`)
-		}
-
-		// `email` / `name` are typed `string | undefined` on IDPResponse and feed the by-e-mail
-		// account lookup (which crashes on a non-string). `...source` already placed the raw claim
-		// of whatever type, so OVERWRITE (don't conditionally add) with the mapped value when it is
-		// a string, otherwise `undefined` — a non-string claim must not leak through `...source`.
-		const email = getClaim(source, claimMapping?.email ?? 'email')
-		const name = getClaim(source, claimMapping?.name ?? 'name')
+		// Merge ID-token claims with userInfo (userInfo wins, per spec), then normalize the surface (lift
+		// nested attributes + map the identity fields). The refresh path runs the SAME normalization, so a
+		// claim mapping resolves identically at sign-in and on refresh. The default `sub` fallback is safe —
+		// openid-client guarantees `sub` is a string.
+		const normalized = normalizeClaims({ ...claimsWithoutHashes, ...userInfo }, claimMapping, claims.sub)
 
 		return {
 			...oidcResult,
-			...source,
-			externalIdentifier,
-			email: typeof email === 'string' ? email : undefined,
-			name: typeof name === 'string' ? name : undefined,
-			emailVerified,
+			...normalized,
 			...(idpSession ? { idpSession } : {}),
 		}
 	} catch (e: any) {
@@ -169,7 +249,9 @@ export const revalidateOIDC = async (
 	client: Client,
 	method: 'refresh' | 'userinfo' | 'introspection',
 	session: IDPSessionState,
+	options: { claimMapping?: OIDCClaimMapping; fetchUserInfo?: boolean } = {},
 ): Promise<RevalidationResult> => {
+	const { claimMapping, fetchUserInfo } = options
 	const tokens = session.tokens ?? {}
 	const refreshToken = typeof tokens.refresh_token === 'string' ? tokens.refresh_token : undefined
 	const accessToken = typeof tokens.access_token === 'string' ? tokens.access_token : undefined
@@ -180,14 +262,31 @@ export const revalidateOIDC = async (
 			}
 			const tokenSet = await client.refresh(refreshToken)
 			let claims: Record<string, unknown> | undefined
+			let claimsComplete = false
 			try {
-				claims = tokenSet.id_token ? tokenSet.claims() : undefined
+				// Reconstruct the SAME claim surface sign-in builds (handleOIDCResponse): the refreshed id-token
+				// claims merged with userInfo when `fetchUserInfo` is set — exactly as at sign-in — then the shared
+				// normalization (lift nested attributes + map identity fields). An `always` mapping therefore
+				// reconciles against an identical surface on refresh, so `claimsComplete` lets the caller enable
+				// `unmatched: "remove"` reconciliation here too (see IdpSessionRevalidator).
+				if (tokenSet.id_token) {
+					const idClaims = tokenSet.claims()
+					const userInfo = tokenSet.access_token && fetchUserInfo ? await client.userinfo(tokenSet) : {}
+					claims = normalizeClaims({ ...idClaims, ...userInfo }, claimMapping, typeof idClaims.sub === 'string' ? idClaims.sub : undefined)
+					claimsComplete = true
+				}
 			} catch {
+				// Building the surface failed (userinfo unreachable, a non-scalar `externalIdentifier`, …). The IdP
+				// already vouched for the session via the successful refresh, so KEEP it — just skip the claim sync
+				// this tick (no claims → no grant, no removal) and retry on a later refresh. Leaving claimsComplete
+				// false also guarantees a half-built surface can never drive a removal.
 				claims = undefined
+				claimsComplete = false
 			}
 			return {
 				status: 'valid',
 				claims,
+				claimsComplete,
 				// carry the stored tokens forward: a non-rotating IdP omits the refresh token here
 				idpSession: tokenSetToSessionState(tokenSet, session.sessionId, tokens),
 			}
@@ -197,7 +296,16 @@ export const revalidateOIDC = async (
 				return { status: 'revoked', reason: 'no_access_token' }
 			}
 			const userInfo = await client.userinfo(accessToken)
-			return { status: 'valid', claims: userInfo }
+			let claims: Record<string, unknown> | undefined
+			try {
+				claims = normalizeClaims(userInfo, claimMapping, typeof userInfo.sub === 'string' ? userInfo.sub : undefined)
+			} catch {
+				claims = undefined
+			}
+			// A userinfo probe carries no id-token claims, so its surface is NARROWER than sign-in's (id-token +
+			// userinfo): a rule keyed on an id-token-only claim would miss here. Keep refresh-time sync additive-only
+			// (`claimsComplete: false`) so `unmatched: "remove"` never strips a membership off this partial surface.
+			return { status: 'valid', claims, claimsComplete: false }
 		}
 		// introspection
 		const token = accessToken ?? refreshToken

package/src/model/service/idp/providers/OIDCProvider.ts

@@ -48,7 +48,10 @@ export class OIDCProvider implements IdentityProviderHandler<OIDCConfiguration>
 
 	public async revalidate(configuration: OIDCConfiguration, session: IDPSessionState): Promise<RevalidationResult> {
 		const client = await this.createOIDCClient(configuration)
-		return await revalidateOIDC(client, configuration.revalidation?.method ?? 'refresh', session)
+		return await revalidateOIDC(client, configuration.revalidation?.method ?? 'refresh', session, {
+			claimMapping: configuration.claimMapping,
+			fetchUserInfo: configuration.fetchUserInfo,
+		})
 	}
 
 	public async buildLogoutUrl(configuration: OIDCConfiguration, request: LogoutUrlRequest): Promise<string | null> {

package/src/model/service/index.ts

@@ -4,6 +4,8 @@ export * from './idp/index.js'
 
 export * from './AuthLogService.js'
 export * from './AuthPolicyManager.js'
+export * from './CustomRoleManager.js'
+export * from './GlobalRoleValidator.js'
 export * from './AuthPolicyResolver.js'
 export * from './BackupCodeManager.js'
 export * from './EmailChangeManager.js'
@@ -17,6 +19,7 @@ export * from './MailTemplateManager.js'
 export * from './MembershipValidator.js'
 export * from './OtpAuthenticator.js'
 export * from './OtpManager.js'
+export * from './PanelAccessResolver.js'
 export * from './PasswordChangeManager.js'
 export * from './PasswordResetManager.js'
 export * from './PersonAccessManager.js'

package/src/model/type/AuthLog.ts

@@ -16,6 +16,7 @@ export type AuthActionType =
 	| 'passwordless_login_exchange'
 	| 'passwordless_login'
 	| 'person_disable'
+	| 'person_enable'
 	| 'session_revoked_by_user'
 	| 'forced_sign_out'
 	| 'global_role_grant'
@@ -35,6 +36,8 @@ export type AuthActionType =
 	| 'idp_logout_initiated'
 	| 'idp_backchannel_logout'
 	| 'idp_disconnect'
+	| 'idp_role_mapped'
+	| 'idp_role_mapping_failed'
 	| 'project_create'
 	| 'project_update'
 	| 'project_secret_change'
@@ -50,5 +53,6 @@ export type AuthActionType =
 	| 'session_expired_idle'
 	| 'session_policy_applied'
 	| 'auth_policy_change'
+	| 'custom_role_change'
 	| 'unusual_login_detected'
 	| 'step_up_required'

package/src/model/type/Config.ts

@@ -48,6 +48,9 @@ export type ConfigRow = {
 	rate_limit_email_otp_per_person_window: IPostgresInterval
 	rate_limit_email_verification_per_ip_limit: number
 	rate_limit_email_verification_per_ip_window: IPostgresInterval
+	// Readonly: the GraphQL input renders list values as ReadonlyArray, which is written straight to these columns.
+	panel_global_roles: readonly string[]
+	panel_project_roles: readonly string[]
 }
 
 export type Config =

package/src/model/type/CustomRole.ts

@@ -0,0 +1,8 @@
+export type CustomRoleRow = {
+	readonly id: string
+	readonly slug: string
+	readonly description: string | null
+	readonly grants: unknown
+	readonly created_at: Date
+	readonly updated_at: Date
+}

package/src/model/type/IdentityProvider.ts

@@ -11,4 +11,6 @@ export interface IdentityProviderOptions {
 	initReturnsConfig: boolean
 	requireVerifiedEmail: boolean
 	assumeEmailVerified: boolean
+	/** A person linked to this provider may authenticate only through it. */
+	disableLocalAuthentication: boolean
 }

package/src/model/type/PersonToken.ts

@@ -17,6 +17,8 @@ export namespace PersonToken {
 		token_hash: string
 		used_at: null | Date
 		expires_at: Date
+		/** `expires_at <= now()` computed on the DB clock — the authoritative expiry gate. */
+		is_expired: boolean
 		person_id: string
 		otp_hash: string | null
 		otp_attempts: number

package/src/model/type/index.ts

@@ -1,6 +1,7 @@
 export * from './ApiKey.js'
 export * from './AuthPolicy.js'
 export * from './Config.js'
+export * from './CustomRole.js'
 export * from './IdentityProvider.js'
 export * from './Project.js'
 export * from './Variables.js'