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

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

@@ -4,7 +4,6 @@ import {
 	DisableApiKeyCommand,
 	DisableIdentityApiKeysCommand,
 	DisableOneOffApiKeyCommand,
-	PROLONG_THROTTLE_MS,
 	ProlongApiKeyCommand,
 } from '../../commands/index.js'
 import { ApiKey } from '../../type/index.js'
@@ -22,6 +21,8 @@ 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(
@@ -30,6 +31,7 @@ export class ApiKeyManager {
 		private readonly authLogService: AuthLogService,
 		private readonly unpersistedApiKeyManager: UnpersistedApiKeyManager = new UnpersistedApiKeyManager(),
 		private readonly idpSessionRevalidator?: IdpSessionRevalidator,
+		private readonly globalRoleValidator: GlobalRoleValidator = new GlobalRoleValidator(),
 	) {}
 
 	async verifyAndProlong(
@@ -45,10 +47,11 @@ export class ApiKeyManager {
 			return new ResponseOk(unpersistedResult)
 		}
 
-		const apiKeyRow = await readDbContext.queryHandler.fetch(new ApiKeyByTokenQuery(token))
-		if (apiKeyRow === null) {
+		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(
@@ -57,55 +60,49 @@ export class ApiKeyManager {
 			)
 		}
 
-		// Single injectable clock for all session-policy time math (matches issuance,
-		// which uses providers.now()), so the A19 idle/max logic is deterministically testable.
-		const now = dbContext.providers.now()
-		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()}`)
 		}
 
-		// A19: absolute hard cap (defensive — the prolong clamp should already keep
+		// Absolute hard cap (defensive — the prolong clamp should already keep
 		// expires_at <= max_expires_at, but enforce it here regardless).
-		if (apiKeyRow.max_expires_at !== null && apiKeyRow.max_expires_at <= now) {
+		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()}`,
+				`API key reached its maximum lifetime at ${apiKeyRow.max_expires_at?.toISOString()}`,
 			)
 		}
 
-		// A19: 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.
-		if (apiKeyRow.idle_timeout !== null && apiKeyRow.last_used_at !== null) {
-			const idleMs = intervalToSeconds(apiKeyRow.idle_timeout) * 1000
-			// last_used_at is written at most once per PROLONG_THROTTLE_MS (tracking is
-			// throttled), so it can legitimately lag a continuously-active session by up
-			// to that window. Add the throttle as slack so a small idle_timeout can't
-			// idle-expire a session that is actually in use.
-			if (now.getTime() - apiKeyRow.last_used_at.getTime() > idleMs + PROLONG_THROTTLE_MS) {
-				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`,
-				)
+		// 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
@@ -120,15 +117,18 @@ export class ApiKeyManager {
 		// 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, readDbContext, apiKeyRow, effectiveInfo)
+			const outcome = await this.idpSessionRevalidator.revalidate(dbContext, fetchedApiKey.sourceDbContext, apiKeyRow, effectiveInfo)
 			if (outcome === 'revoked') {
 				return new ResponseError(VerifyErrorCode.DISABLED, 'IdP session was revoked')
 			}
 		}
 
-		setImmediate(async () => {
-			await dbContext.commandBus.execute(
+		// Detached (runs after the response), so a rejection here would be an unhandledRejection and can take the
+		// worker down. Tracking is best-effort — the next request writes it again.
+		setImmediate(() => {
+			dbContext.commandBus.execute(
 				new ProlongApiKeyCommand(
 					apiKeyRow.id,
 					apiKeyRow.type,
@@ -142,7 +142,7 @@ export class ApiKeyManager {
 					},
 					apiKeyRow.max_expires_at,
 				),
-			)
+			).catch(() => {})
 		})
 
 		return new ResponseOk(
@@ -156,6 +156,20 @@ export class ApiKeyManager {
 		)
 	}
 
+	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,
@@ -204,11 +218,10 @@ export class ApiKeyManager {
 			expirationCapped = Math.min(expirationCapped, intervalToSeconds(policy.tokenExpiration) / 60)
 		}
 
-		// Absolute hard cap: issued_at + policy.tokenExpiration. NULL = uncapped
-		// sliding window (today's behavior).
-		const issuedAt = dbContext.providers.now()
-		const maxExpiresAt = policy.tokenExpiration
-			? new Date(issuedAt.getTime() + intervalToSeconds(policy.tokenExpiration) * 1000)
+		// 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({
@@ -218,7 +231,7 @@ export class ApiKeyManager {
 			requestInfo,
 			trustForwardedInfo,
 			idleTimeout: policy.idleTimeout ? intervalToPostgres(policy.idleTimeout) : null,
-			maxExpiresAt,
+			maxExpirationSeconds,
 		})
 		const { id, token } = await dbContext.commandBus.execute(command)
 		assert(token !== undefined)
@@ -278,8 +291,12 @@ export class ApiKeyManager {
 		trustForwardedInfo?: boolean,
 	): Promise<CreateApiKeyResponse> {
 		return await dbContext.transaction(async db => {
+			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(
@@ -296,6 +313,11 @@ export class ApiKeyManager {
 	}
 }
 
+type FetchedApiKey = {
+	row: ApiKeyRow
+	sourceDbContext: DatabaseContext
+}
+
 export type VerifyResponse = Response<VerifyResult, VerifyErrorCode>
 
 export class VerifyResult {

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

@@ -4,7 +4,7 @@ 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 } from '../../../schema/index.js'
+import { ApiKeyWithToken, CreateApiKeyErrorCode } from '../../../schema/index.js'
 import { Acl } from '@contember/schema'
 
 export class ApiKeyService {
@@ -48,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 }) {

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

@@ -10,6 +10,30 @@ import { VerifyResult } from './ApiKeyManager.js'
  */
 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

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

@@ -0,0 +1,283 @@
+import * as Typesafe from '@contember/typesafe'
+
+/**
+ * Provider-agnostic mapping of IdP claims/attributes to Contember project memberships (A09).
+ * Stored on an IdP's `configuration.claimMapping`, so it rides inside the existing
+ * `identity_provider.configuration` JSONB and needs no schema change — `addIDP` / `updateIDP`
+ * already accept an opaque configuration object.
+ *
+ * The mapping grants **project memberships only** (a project role plus optional membership
+ * variables). It deliberately does NOT grant global/tenant roles: those are privilege-bearing
+ * and granting them from external claims would be a privilege-escalation path, so global-role
+ * mapping was dropped. A project membership stays within what the IdP configurer
+ * (`project_admin`, holding `IDP_ADD` / `IDP_UPDATE`) may already grant directly.
+ *
+ * Coexistence: the OIDC provider also uses `configuration.claimMapping` for an unrelated
+ * identity-field remap (`email` / `name` / `externalIdentifier` / `attributesKey`). A09 only
+ * looks at the `rules` field, so the two coexist in the same object — {@link parseClaimMapping}
+ * returns `null` when no `rules` are present (an OIDC-only remap) instead of rejecting it.
+ *
+ * Each rule inspects one `claim` from the IdP response (the raw claims flow through verbatim,
+ * since `IDPResponse` is `& Record<string, unknown>`) and, when it matches, grants a project
+ * membership. Rules are independent and additive — every matching rule contributes; a
+ * non-matching rule is simply skipped.
+ *
+ * Matching is declarative, never code:
+ * - `equals`   — the claim equals the value (scalar compare; for array claims, the value is one
+ *                of the elements).
+ * - `contains` — the claim contains the value: substring for string claims, membership for array
+ *                claims. This is the natural fit for multi-valued `groups`.
+ * - neither    — the rule matches whenever the claim is merely present (and truthy for booleans).
+ */
+/**
+ * Where a membership variable's values come from when they are not constant. Reads one `claim` from the
+ * IdP response — by exact name first (a URL-namespaced claim with literal dots works), then as a dot-path
+ * (nested claims like `profile.languages`) — and shapes the raw value(s) into a flat list of strings:
+ * - array claim       → its elements (`languages: ['cs','en']`)
+ * - `split`           → split a delimited string claim (`'cs,en'`, OIDC-style `'cs en'`) into elements
+ * - `pick` / `where`  → for an array-of-objects claim, keep elements matching `where` and take their
+ *                       `pick` field (`orgs: [{ code, role }]` → codes of the elements where role matches)
+ *
+ * The extracted raw values are then run through {@link ClaimMappingVariable}'s `map` / `passthrough`.
+ */
+export const ClaimValueSource = Typesafe.noExtraProps(Typesafe.intersection(
+	Typesafe.object({
+		/** Claim to read: the exact name first (URL-namespaced names work), then as a dot-path (e.g. `profile.languages`). */
+		claim: Typesafe.string,
+	}),
+	Typesafe.partial({
+		/** Split each string value on this delimiter (e.g. `,` or ` `): a scalar string claim and every string element of an array claim. A no-op for non-string values. */
+		split: Typesafe.string,
+		/** For an array-of-objects claim, take this (dot-path) field from each element. */
+		pick: Typesafe.string,
+		/** For an array-of-objects claim, keep only elements whose `field` equals `equals`. */
+		where: Typesafe.noExtraProps(Typesafe.object({
+			field: Typesafe.string,
+			equals: Typesafe.scalar,
+		})),
+	}),
+))
+
+export type ClaimValueSource = ReturnType<typeof ClaimValueSource>
+
+/**
+ * One membership variable to set on a granted membership. Either constant (`values`), claim-derived
+ * (`from`), or both — the two sets are unioned. When derived from a claim:
+ * - `map`         — lookup table from a raw claim value to the value(s) actually set, e.g.
+ *                   `{ cs: ['<locale-uuid>'] }`. A raw value absent from the map is dropped…
+ * - `passthrough` — …unless `passthrough` is `true`, in which case it is set verbatim. Off by
+ *                   default: raw external claim values then flow straight into row-level ACL
+ *                   variables, so enable it only when the variable legitimately holds claim values
+ *                   (not opaque ids), and prefer `map` / `allow` to bound what an IdP can inject.
+ * - `allow`       — optional allowlist applied to the claim-derived values (constants are never filtered).
+ */
+export const ClaimMappingVariable = Typesafe.noExtraProps(Typesafe.intersection(
+	Typesafe.object({
+		name: Typesafe.string,
+	}),
+	Typesafe.partial({
+		/** Constant values, set regardless of any claim (the original static form). */
+		values: Typesafe.array(Typesafe.string),
+		/** Derive (additional) values from a claim. */
+		from: ClaimValueSource,
+		/** Lookup table applied to each raw value from `from`. A raw value with no entry is dropped unless `passthrough`. */
+		map: Typesafe.record(Typesafe.string, Typesafe.array(Typesafe.string)),
+		/** When `true`, a raw value from `from` not present in `map` is set verbatim. See the security note above. */
+		passthrough: Typesafe.boolean,
+		/** Allowlist applied to the values derived from `from` (constants in `values` are unaffected). */
+		allow: Typesafe.array(Typesafe.string),
+	}),
+))
+
+export type ClaimMappingVariable = ReturnType<typeof ClaimMappingVariable>
+
+export const ClaimMappingMembership = Typesafe.noExtraProps(Typesafe.intersection(
+	Typesafe.object({
+		project: Typesafe.string,
+		role: Typesafe.string,
+	}),
+	Typesafe.partial({
+		/**
+		 * Membership variables to set. Each is constant (`values`, e.g. `[{ name: 'locale', values: ['cs'] }]`)
+		 * and/or claim-derived (`from`, e.g. map a `languages` claim through a lookup table to locale ids).
+		 */
+		variables: Typesafe.array(ClaimMappingVariable),
+	}),
+))
+
+export type ClaimMappingMembership = ReturnType<typeof ClaimMappingMembership>
+
+export const ClaimMappingRule = Typesafe.noExtraProps(Typesafe.intersection(
+	Typesafe.object({
+		/** Claim/attribute from the IdP response to inspect: the exact name first, then as a dot-path into nested objects. */
+		claim: Typesafe.string,
+	}),
+	Typesafe.partial({
+		/** Match when the claim equals this value (array claims: when it contains this element). */
+		equals: Typesafe.scalar,
+		/** Match when the claim contains this value (substring for strings, element for arrays). */
+		contains: Typesafe.scalar,
+		/** Project membership to grant when the rule matches. */
+		grantMembership: ClaimMappingMembership,
+	}),
+))
+
+export type ClaimMappingRule = ReturnType<typeof ClaimMappingRule>
+
+/**
+ * The validated A09 mapping. `rules` is required here — {@link parseClaimMapping} only returns a
+ * mapping once it has confirmed `rules` is present, and returns `null` otherwise (so an OIDC-only
+ * `claimMapping` is treated as "no role mapping", not an error).
+ */
+export const ClaimMapping = Typesafe.intersection(
+	Typesafe.object({
+		rules: Typesafe.array(ClaimMappingRule),
+	}),
+	Typesafe.partial({
+		/**
+		 * When to apply the mapping:
+		 * - `always` (default) — re-sync memberships on every sign-in (and on every OIDC session refresh).
+		 * - `sticky`           — apply only when the account is first created by auto-sign-up; existing
+		 *                        accounts (including one being linked to this IdP for the first time) are
+		 *                        left untouched.
+		 */
+		syncPolicy: Typesafe.enumeration('always', 'sticky'),
+		/**
+		 * How to treat existing grants the mapping does NOT (re)assign on this sign-in:
+		 * - `keep`   (default, safer) — leave pre-existing memberships untouched.
+		 * - `remove` — strip memberships that the mapping no longer grants (IdP becomes the source of
+		 *              truth). Only ever touches grants the mapping itself could have made; memberships
+		 *              outside the mapping's vocabulary are never removed.
+		 */
+		unmatched: Typesafe.enumeration('keep', 'remove'),
+	}),
+)
+
+export type ClaimMapping = ReturnType<typeof ClaimMapping>
+
+export const DEFAULT_SYNC_POLICY: NonNullable<ClaimMapping['syncPolicy']> = 'always'
+export const DEFAULT_UNMATCHED: NonNullable<ClaimMapping['unmatched']> = 'keep'
+
+export const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === 'object' && value !== null && !Array.isArray(value)
+
+/**
+ * Parse the optional A09 `claimMapping` out of an IdP `configuration` blob. Returns `null` when no
+ * A09 mapping is present — either no `claimMapping` at all, or a `claimMapping` that carries no
+ * `rules` (e.g. the OIDC identity-field remap, which shares this key). Returning `null` keeps both
+ * the pre-A09 sign-in path and the OIDC remap untouched.
+ *
+ * Only the A09 fields (`rules`, `syncPolicy`, `unmatched`) are validated; any other keys on the
+ * `claimMapping` object (the OIDC remap fields) are ignored, so the two features coexist. Throws via
+ * Typesafe when `rules` is present but structurally malformed (e.g. a rule missing its required
+ * `claim`), so an A09 misconfiguration surfaces loudly rather than silently dropping grants.
+ *
+ * The nested A09 schemas (rule / membership / variable / value-source) are wrapped in
+ * `Typesafe.noExtraProps`, so a typo'd key on any of them (e.g. `grantMembershp`, `equls`) is
+ * REJECTED, not silently stripped — a misconfiguration surfaces loudly instead of degrading into a
+ * grants-nothing or match-everyone rule. The one exception is the top-level `claimMapping` object
+ * itself: it is the key SHARED with the OIDC identity-remap (`email`/`name`/`externalIdentifier`/
+ * `attributesKey`), so this parse first projects only the A09 fields (`rules`/`syncPolicy`/`unmatched`)
+ * into a fresh object (above) and deliberately does NOT apply `noExtraProps` there — the OIDC remap
+ * fields must coexist. The `map` lookup table is likewise a `record` (arbitrary keys are legitimate),
+ * not a strict object. The removed `grantRoles` key is still caught separately by
+ * {@link findRemovedRuleKeys} (run before this parse) for a clearer message than the generic
+ * extra-property error `noExtraProps` would otherwise raise.
+ */
+export const parseClaimMapping = (configuration: Record<string, unknown>): ClaimMapping | null => {
+	const raw = configuration.claimMapping
+	if (!isRecord(raw) || raw.rules === undefined || raw.rules === null) {
+		return null
+	}
+	const input: Record<string, unknown> = { rules: raw.rules }
+	if (raw.syncPolicy !== undefined) {
+		input.syncPolicy = raw.syncPolicy
+	}
+	if (raw.unmatched !== undefined) {
+		input.unmatched = raw.unmatched
+	}
+	return ClaimMapping(input, ['claimMapping'])
+}
+
+/**
+ * The set of A09 rule keys that were removed when global-role mapping was dropped. Detected
+ * explicitly (rather than relying on Typesafe's generic "extra property" rejection) so a config
+ * that still tries to grant global roles gets an actionable error.
+ */
+const REMOVED_RULE_KEYS = ['grantRoles'] as const
+
+/**
+ * Returns the removed rule keys (currently only `grantRoles`) still present in a raw `claimMapping`,
+ * so config-time validation can reject them with a clear message pointing at `grantMembership`.
+ */
+export const findRemovedRuleKeys = (configuration: Record<string, unknown>): string[] => {
+	const raw = configuration.claimMapping
+	if (!isRecord(raw) || !Array.isArray(raw.rules)) {
+		return []
+	}
+	const found = new Set<string>()
+	for (const rule of raw.rules) {
+		if (isRecord(rule)) {
+			for (const key of REMOVED_RULE_KEYS) {
+				if (key in rule) {
+					found.add(key)
+				}
+			}
+		}
+	}
+	return [...found]
+}
+
+/**
+ * Semantic checks on a parsed mapping that the Typesafe shape cannot express. Returns one
+ * human-readable message per problem (empty = ok); run at config time (IdP add/update) so a
+ * contradictory rule is rejected loudly rather than silently mis-matching or granting nothing:
+ * - a rule may use at most one of `equals` / `contains` ({@link ruleMatches} only ever honours `equals`
+ *   when both are set, so the other would be silently ignored);
+ * - a rule's `equals` / `contains` must not be an empty string: an empty `contains` substring-matches EVERY
+ *   string claim (`'...'.includes('')` is always true), i.e. a match-everything grant to every user of the
+ *   IdP, and an empty `equals` is an always-no-op footgun — to match on the claim's mere presence, omit both;
+ * - a rule must carry a `grantMembership` — a rule with none matches but grants nothing. (A *misspelled*
+ *   `grantMembership`, e.g. `grantMembershp`, is now rejected earlier by `noExtraProps` during
+ *   {@link parseClaimMapping}; this check remains for a `grantMembership` that is genuinely OMITTED,
+ *   which the `partial` schema permits.)
+ * - a variable's `from.where` requires a `from.pick` — `where` filters elements but without `pick` there
+ *   is nothing to project, so the source can only ever resolve to no values;
+ * - a variable's `from.split` must not be the empty string — `''.split('')` explodes every claim value
+ *   into its individual characters (the same class of footgun as an empty `equals` / `contains`).
+ */
+export const findClaimMappingShapeErrors = (mapping: ClaimMapping): string[] => {
+	const errors: string[] = []
+	for (const rule of mapping.rules) {
+		if (rule.grantMembership === undefined) {
+			errors.push(
+				`claimMapping rule for claim '${rule.claim}' has no 'grantMembership', so it matches but grants nothing; add a 'grantMembership'`,
+			)
+		}
+		if (rule.equals !== undefined && rule.contains !== undefined) {
+			errors.push(`claimMapping rule for claim '${rule.claim}' sets both 'equals' and 'contains'; a rule may use at most one`)
+		}
+		if (typeof rule.equals === 'string' && rule.equals.trim() === '') {
+			errors.push(
+				`claimMapping rule for claim '${rule.claim}' has an empty 'equals' value; omit both 'equals' and 'contains' to match on the claim's mere presence, or set a non-empty value`,
+			)
+		}
+		if (typeof rule.contains === 'string' && rule.contains.trim() === '') {
+			errors.push(
+				`claimMapping rule for claim '${rule.claim}' has an empty 'contains' value, which would substring-match every string value of the claim (a match-everything grant); omit both 'equals' and 'contains' to match on the claim's mere presence, or set a non-empty value`,
+			)
+		}
+		for (const variable of rule.grantMembership?.variables ?? []) {
+			if (variable.from?.where !== undefined && variable.from.pick === undefined) {
+				errors.push(
+					`claimMapping variable '${variable.name}' uses 'from.where' without 'from.pick'; it can only ever resolve to no values — set 'pick' (the field to take from each matched element)`,
+				)
+			}
+			if (variable.from?.split === '') {
+				errors.push(
+					`claimMapping variable '${variable.name}' has an empty 'from.split' delimiter, which splits every claim value into its individual characters; omit 'split' to keep the value whole, or set a non-empty delimiter`,
+				)
+			}
+		}
+	}
+	return errors
+}