@contember/engine-tenant-api 2.2.0-alpha.3 → 2.2.0-alpha.6

package/src/model/service/IDPSignInManager.ts

@@ -11,11 +11,14 @@ import { TenantRole } from '../authorization/index.js'
 import { NoPassword } from '../dtos/index.js'
 import { IdentityProviderRow } from '../queries/idp/types.js'
 import { AuthLogService } from './AuthLogService.js'
+import { ClaimMappingAudit, IDPClaimSyncService } from './idp/IDPClaimSyncService.js'
+import { ClaimMapping, parseClaimMapping } from './idp/ClaimMapping.js'
 
 class IDPSignInManager {
 	constructor(
 		private readonly apiKeyManager: ApiKeyManager,
 		private readonly idpRegistry: IDPHandlerRegistry,
+		private readonly claimSyncService: IDPClaimSyncService,
 	) {}
 
 	async signInIDP(
@@ -85,6 +88,40 @@ class IDPSignInManager {
 				})
 			}
 
+			// A09 — map IdP claims to project memberships. Returns a `{ before, after }` delta only
+			// when something actually changed; the resolver emits the `idp_role_mapped` audit from it
+			// (audit stays at the resolver layer).
+			//
+			// Fail-open on a MALFORMED/out-of-band `claimMapping`: parsing is caught so a bad config can
+			// never lock the user out — sign-in proceeds without claim mapping and the resolver emits an
+			// `idp_role_mapping_failed` marker. A DB error during the apply itself is NOT caught: it
+			// propagates and rolls back the whole sign-in transaction, so a half-applied set of grants is
+			// never committed (failing sign-in on an infra error is the safe outcome).
+			let mapping: ClaimMapping | null = null
+			let claimMappingFailed = false
+			try {
+				mapping = parseClaimMapping(provider.configuration)
+			} catch {
+				claimMappingFailed = true
+			}
+			let claimMappingAudit: ClaimMappingAudit | null = null
+			if (mapping) {
+				const syncResult = await this.claimSyncService.sync(
+					db,
+					mapping,
+					claim,
+					{ id: personRow.identity_id },
+					resolved.isNewPerson === true,
+				)
+				claimMappingAudit = syncResult.audit
+				// The apply-time safety backstop dropped a configured rule (config-time validation was skipped, or
+				// the project's ACL drifted since): surface the same fail-open marker as a malformed config, so a
+				// silently-unapplied grant is visible to the operator. The resolver emits `idp_role_mapping_failed`.
+				if (syncResult.droppedUnsafeRules) {
+					claimMappingFailed = true
+				}
+			}
+
 			const { id: apiKeyId, token: sessionToken } = await this.apiKeyManager.createSessionApiKeyWithId(
 				db,
 				personRow.identity_id,
@@ -129,6 +166,9 @@ class IDPSignInManager {
 				person: personRow,
 				token: sessionToken,
 				idpResponse: claim,
+				claimMappingAudit,
+				claimMappingFailed,
+				identityProviderId: provider.id,
 				[AuthLogService.Key]: new AuthLogService.Bag({
 					personId: personRow.id,
 					identityProviderId: provider.id,
@@ -194,7 +234,7 @@ class IDPSignInManager {
 		if (provider.autoSignUp) {
 			const signedUpPerson = await this.signUp(db, claim, provider)
 			await this.saveIdpIdentifier(db, provider, claim, signedUpPerson)
-			return { person: signedUpPerson }
+			return { person: signedUpPerson, isNewPerson: true }
 		}
 
 		return { person: null }
@@ -229,6 +269,8 @@ namespace IDPSignInManager {
 		readonly person: PersonRow | null
 		readonly blockedReason?: 'idp_email_unverified'
 		readonly blockedPersonId?: string
+		/** True when the person row was just created by auto-sign-up (drives the `sticky` claim-mapping policy). */
+		readonly isNewPerson?: boolean
 	}
 
 	export type InitSignInIDPResponse = Response<InitSignInIdpResult, InitSignInIdpErrorCode>
@@ -237,6 +279,12 @@ namespace IDPSignInManager {
 		readonly person: PersonRow
 		readonly token: string
 		readonly idpResponse?: Record<string, unknown>
+		/** Identity provider the sign-in went through (for the resolver's audit). */
+		readonly identityProviderId?: string
+		/** Claim-mapping (A09) before/after delta — present only when a mapping changed grants. */
+		readonly claimMappingAudit?: ClaimMappingAudit | null
+		/** True when claim mapping failed and was skipped (fail-open) — drives the `idp_role_mapping_failed` audit. */
+		readonly claimMappingFailed?: boolean
 		[AuthLogService.Key]: AuthLogService.Bag
 	}
 

package/src/model/service/PanelAccessResolver.ts

@@ -0,0 +1,32 @@
+import { DatabaseContext } from '../utils/index.js'
+import { AllProjectRolesByIdentityQuery, ConfigurationQuery } from '../queries/index.js'
+import { Providers } from '../providers.js'
+
+/**
+ * Decides whether an identity may enter the management panel served by the engine.
+ *
+ * This is an **entry gate for the console, not an authorization system**: everything the panel shows
+ * still goes through the tenant ACL, and whoever gets in could equally call `/tenant` directly. Its
+ * job is to keep the console door shut for accounts that have no business there, so an admin surface
+ * on a public API port does not look like a leak.
+ *
+ * An identity is allowed when it holds one of `globalRoles`, or a membership with one of
+ * `projectRoles` in **any** project. Empty lists mean nobody.
+ */
+export class PanelAccessResolver {
+	constructor(private readonly providers: Providers) {}
+
+	async isAllowed(db: DatabaseContext, identityId: string, globalRoles: readonly string[]): Promise<boolean> {
+		const config = await db.queryHandler.fetch(new ConfigurationQuery(this.providers))
+		const policy = config.panel
+
+		if (policy.globalRoles.some(role => globalRoles.includes(role))) {
+			return true
+		}
+		if (policy.projectRoles.length === 0) {
+			return false
+		}
+		const projectRoles = await db.queryHandler.fetch(new AllProjectRolesByIdentityQuery(identityId))
+		return projectRoles.some(it => policy.projectRoles.includes(it.role))
+	}
+}

package/src/model/service/PasswordResetManager.ts

@@ -1,6 +1,6 @@
 import { Response, ResponseError, ResponseOk } from '../utils/Response.js'
 import { UserMailer } from '../mailing/index.js'
-import { ConfigurationQuery, PersonRow } from '../queries/index.js'
+import { ConfigurationQuery, LocalAuthDisablingIdpsQuery, PersonRow } from '../queries/index.js'
 import { PermissionContext } from '../authorization/index.js'
 import { ProjectManager } from './ProjectManager.js'
 import { DatabaseContext } from '../utils/index.js'
@@ -35,6 +35,14 @@ export class PasswordResetManager {
 			throw new ImplementationException()
 		}
 
+		// A person federated through a provider with `disableLocalAuthentication`
+		// cannot sign in with a password, so a reset mail would only offer them a
+		// credential the tenant refuses — and one more link worth phishing.
+		const exclusiveIdps = await dbContext.queryHandler.fetch(new LocalAuthDisablingIdpsQuery(person.id))
+		if (exclusiveIdps.length > 0) {
+			return
+		}
+
 		// Per-email exponential backoff on outbound mails — don't spam a real
 		// user with reset mails just because attackers keep poking the
 		// endpoint. Reuses login_* backoff config against person_auth_log.

package/src/model/service/PasswordlessSignInManager.ts

@@ -1,5 +1,5 @@
 import { ApiKeyManager } from './apiKey/index.js'
-import { ConfigurationQuery, PersonQuery, PersonRow } from '../queries/index.js'
+import { ConfigurationQuery, LocalAuthDisablingIdpsQuery, PersonQuery, PersonRow } from '../queries/index.js'
 import { Response, ResponseError, ResponseOk } from '../utils/Response.js'
 import {
 	ActivatePasswordlessOtpErrorCode,
@@ -62,6 +62,16 @@ class PasswordlessSignInManager {
 					}),
 				})
 			}
+			const exclusiveIdps = await db.queryHandler.fetch(new LocalAuthDisablingIdpsQuery(person.id))
+			if (exclusiveIdps.length > 0) {
+				return new ResponseError('IDP_REQUIRED', `Sign in using ${exclusiveIdps.join(' or ')}`, {
+					[AuthLogService.Key]: new AuthLogService.Bag({
+						personInput: email,
+						personId: person.id,
+					}),
+				})
+			}
+
 			if (!isPasswordlessEnabled(configuration.passwordless.enabled, person.passwordless_enabled)) {
 				return new ResponseError('PASSWORDLESS_DISABLED', 'Passwordless sign-in is disabled for this person', {
 					[AuthLogService.Key]: new AuthLogService.Bag({
@@ -185,6 +195,18 @@ class PasswordlessSignInManager {
 				})
 			}
 
+			// Re-checked here and not only at init: a link created while this magic link
+			// was in flight would otherwise still mint a locally authenticated session.
+			const exclusiveIdps = await db.queryHandler.fetch(new LocalAuthDisablingIdpsQuery(personRow.id))
+			if (exclusiveIdps.length > 0) {
+				return new ResponseError('IDP_REQUIRED', `Sign in using ${exclusiveIdps.join(' or ')}`, {
+					[AuthLogService.Key]: new AuthLogService.Bag({
+						personId: personRow.id,
+						tokenId: tokenResult?.id,
+					}),
+				})
+			}
+
 			let usedBackupCode = false
 			if (personRow.otp_secret && personRow.otp_activated_at) {
 				if (mfaOtp) {

package/src/model/service/PersonAccessManager.ts

@@ -1,14 +1,18 @@
+import { Logger } from '@contember/logger'
 import { PersonQuery, PersonRow } from '../queries/index.js'
 import { DatabaseContext } from '../utils/index.js'
 import { DisablePersonCommand } from '../commands/person/DisablePersonCommand.js'
+import { EnablePersonCommand } from '../commands/person/EnablePersonCommand.js'
 import { ApiKeyManager } from './apiKey/index.js'
 import { Response, ResponseError, ResponseOk } from '../utils/Response.js'
-import { DisablePersonErrorCode } from '../../schema/index.js'
+import { DisablePersonErrorCode, EnablePersonErrorCode } from '../../schema/index.js'
 
 class PersonAccessManager {
 	constructor(private readonly apiKeyManager: ApiKeyManager) {}
 
-	async disablePerson(dbContext: DatabaseContext, person: PersonRow): Promise<PersonDisableAccessResponse> {
+	async disablePerson(dbContext: DatabaseContext, person: PersonRow, logger: Logger): Promise<PersonDisableAccessResponse> {
+		// Retried: the api_key update races the target's own background session tracking and loses with a 40001,
+		// which would otherwise leave the person enabled behind an internal error. Nothing here escapes the transaction.
 		return await dbContext.transaction(async trx => {
 			if (person.disabled_at !== null) {
 				return new ResponseError('PERSON_ALREADY_DISABLED', 'Person is already disabled')
@@ -19,7 +23,18 @@ class PersonAccessManager {
 			await this.disableIdentityApiKeys(trx, person.identity_id)
 
 			return new ResponseOk(null)
-		})
+		}, { retry: { logger } })
+	}
+
+	async enablePerson(dbContext: DatabaseContext, person: PersonRow): Promise<PersonEnableAccessResponse> {
+		if (person.disabled_at === null) {
+			return new ResponseError('PERSON_ALREADY_ENABLED', 'Person is already enabled')
+		}
+
+		// Only clears the disabled flag — api keys revoked while disabling stay revoked, the person has to sign in again.
+		await dbContext.commandBus.execute(new EnablePersonCommand(person.id))
+
+		return new ResponseOk(null)
 	}
 
 	private async disablePersonAccount(dbContext: DatabaseContext, personId: string) {
@@ -32,5 +47,6 @@ class PersonAccessManager {
 }
 
 export type PersonDisableAccessResponse = Response<null, DisablePersonErrorCode>
+export type PersonEnableAccessResponse = Response<null, EnablePersonErrorCode>
 
 export { PersonAccessManager }

package/src/model/service/SignInManager.ts

@@ -1,6 +1,6 @@
 import { CreateSessionTokenErrorCode, MfaEnrollment, SignInErrorCode } from '../../schema/index.js'
 import { ApiKeyManager, AuthPolicyResolver, BackupCodeManager, EmailOtpManager, LoginRiskAnalyzer, OtpManager } from '../service/index.js'
-import { ConfigurationQuery, PersonQuery, PersonRow, PersonUniqueIdentifier } from '../queries/index.js'
+import { ConfigurationQuery, LocalAuthDisablingIdpsQuery, PersonQuery, PersonRow, PersonUniqueIdentifier } from '../queries/index.js'
 import { Config } from '../type/Config.js'
 import { Providers } from '../providers.js'
 import { DatabaseContext } from '../utils/index.js'
@@ -51,6 +51,14 @@ class SignInManager {
 				personId: person.id,
 			}),
 		}
+		// Refused before the password is even looked at: for a person federated
+		// through a provider with `disableLocalAuthentication`, a password is not a
+		// credential this tenant accepts, however it got set.
+		const exclusiveIdps = await dbContext.queryHandler.fetch(new LocalAuthDisablingIdpsQuery(person.id))
+		if (exclusiveIdps.length > 0) {
+			return new ResponseError('IDP_REQUIRED', `Sign in using ${exclusiveIdps.join(' or ')}`, authLogData)
+		}
+
 		if (!person.password_hash) {
 			return new ResponseError('NO_PASSWORD_SET', `No password set`, authLogData)
 		}

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

@@ -127,8 +127,10 @@ export class ApiKeyManager {
 			}
 		}
 
-		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 +144,7 @@ export class ApiKeyManager {
 					},
 					apiKeyRow.max_expires_at,
 				),
-			)
+			).catch(() => {})
 		})
 
 		return new ResponseOk(

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
+}