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

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

@@ -0,0 +1,401 @@
+import { DatabaseContext } from '../../utils/index.js'
+import { ClaimMapping, ClaimMappingRule, DEFAULT_SYNC_POLICY, DEFAULT_UNMATCHED } from './ClaimMapping.js'
+import { evaluateClaimMapping, MappedMembership } from './ClaimMappingEvaluator.js'
+import { validateClaimMappingMembership } from './ClaimMappingValidation.js'
+import { ProjectSchemaResolver } from '../../type/index.js'
+import { Acl, ProjectRole } from '@contember/schema'
+import { MembershipResolver } from '@contember/schema-utils'
+import { ProjectBySlugQuery, ProjectMembershipByIdentityQuery } from '../../queries/index.js'
+import { CreateOrUpdateProjectMembershipCommand, RemoveProjectMembershipCommand } from '../../commands/index.js'
+
+export type ClaimMappingSnapshot = {
+	readonly memberships: readonly MappedMembership[]
+}
+
+export type ClaimMappingAudit = {
+	readonly before: ClaimMappingSnapshot
+	readonly after: ClaimMappingSnapshot
+	readonly syncPolicy: NonNullable<ClaimMapping['syncPolicy']>
+	readonly unmatched: NonNullable<ClaimMapping['unmatched']>
+}
+
+export type ClaimMappingSyncResult = {
+	/** Membership before/after delta — present only when the apply actually changed grants. */
+	readonly audit: ClaimMappingAudit | null
+	/** True when the apply-time safety backstop dropped one or more configured rules (a fail-open marker for the caller's audit). */
+	readonly droppedUnsafeRules: boolean
+}
+
+/**
+ * Applies an IdP's `claimMapping` (A09) after a person has been resolved: evaluates the declarative
+ * rules against the IdP claims and grants the resulting project memberships, honouring the per-IdP
+ * `syncPolicy` (`always` vs `sticky`) and `unmatched` (`keep` vs `remove`) settings. The mapping
+ * grants project memberships only — never global/tenant roles (see {@link ClaimMapping}).
+ *
+ * Runs at sign-in (inside the sign-in transaction) and, for `always` mappings, again on each OIDC
+ * session refresh (see `IdpSessionRevalidator`). Returns a {@link ClaimMappingSyncResult}: an
+ * `{ before, after }` audit delta (`null` when nothing changed) plus `droppedUnsafeRules` (true when the
+ * apply-time safety backstop dropped a configured rule). The caller emits the `idp_role_mapped` audit
+ * from the delta and the `idp_role_mapping_failed` fail-open marker from `droppedUnsafeRules` — audit
+ * lives at the caller layer, never here.
+ *
+ * The caller parses the mapping (via {@link parseClaimMapping}) and decides the fail-open policy: a
+ * malformed config is caught by the caller before this runs, while a DB error raised here propagates
+ * so the surrounding transaction rolls back the partial apply (no half-applied grants).
+ */
+export class IDPClaimSyncService {
+	constructor(
+		private readonly projectSchemaResolver: ProjectSchemaResolver,
+	) {
+	}
+
+	async sync(
+		db: DatabaseContext,
+		mapping: ClaimMapping,
+		claims: Record<string, unknown>,
+		identity: { id: string },
+		isNewPerson: boolean,
+		options: { allowRemoval?: boolean } = {},
+	): Promise<ClaimMappingSyncResult> {
+		if (mapping.rules.length === 0) {
+			return { audit: null, droppedUnsafeRules: false }
+		}
+
+		const syncPolicy = mapping.syncPolicy ?? DEFAULT_SYNC_POLICY
+		// `unmatched: 'remove'` reconciliation is only safe when the claim surface is COMPLETE: a rule that
+		// matched at sign-in but is missing from a partial surface would strip a legitimate membership with no
+		// IdP change. At sign-in the surface is always complete, so the caller leaves removal enabled. On the
+		// OIDC refresh path the caller passes `allowRemoval` per surface completeness (see IdpSessionRevalidator):
+		// a `method: 'refresh'` that rebuilt sign-in's id-token + userinfo surface enables removal (refresh then
+		// reconciles exactly like sign-in); a partial surface (userinfo-only probe, or a failed userinfo fetch)
+		// disables it so refresh stays additive-only. The audit below reflects this effective value.
+		const unmatched = options.allowRemoval === false ? 'keep' : (mapping.unmatched ?? DEFAULT_UNMATCHED)
+
+		// `sticky`: only apply at account creation; an existing account keeps whatever it has. This is
+		// also what bounds refresh-sync to `always` mappings — a refresh passes `isNewPerson: false`.
+		if (syncPolicy === 'sticky' && !isNewPerson) {
+			return { audit: null, droppedUnsafeRules: false }
+		}
+
+		// Apply-time safety backstop (A09): re-validate each granted membership against the project's LIVE
+		// ACL schema and drop any that fails (fail-closed) — condition-injection above all, but ANY error
+		// (unknown role/variable, a malformed condition value, an unsafe predefined). Config-time validation
+		// (`IDPManager.assertValidClaimMapping`) is the primary guard, but it is skipped when the target
+		// project does not exist yet, is never re-run when it is later created, and a variable's ACL type can
+		// drift (e.g. entity → condition) after the mapping was authored. A dropped rule is removed from BOTH
+		// the granted set and the removal vocabulary below (both derived from `rules`), so an unsafe rule
+		// neither grants nor drives reconciliation. The caller is told a drop happened (`droppedUnsafeRules`)
+		// so it can emit the `idp_role_mapping_failed` fail-open marker.
+		const { safe: rules, dropped, aclByProject } = await this.dropUnsafeRules(db, mapping.rules)
+
+		// Apply-time safety backstop, part 2 (A09): RUNTIME re-validation of the EVALUATED memberships.
+		// `dropUnsafeRules` above only sees each rule's static CONFIG shape, so — like config-time validation —
+		// it tolerates a missing membership variable (an A09 grant may set only some of a role's variables).
+		// Once the claims are evaluated we know each membership EXACTLY as it would be written, and can
+		// fail-close on the one case that tolerance makes unsafe: an `admin` grant whose claim-derived scoping
+		// variable resolved empty, which would otherwise persist a bare, UNSCOPED `admin` membership (see
+		// {@link dropUnsafeEvaluatedMemberships}). Both drop sets feed the `droppedUnsafeRules` fail-open marker.
+		const evaluated = evaluateClaimMapping({ ...mapping, rules }, claims)
+		const { safe: memberships, dropped: droppedMemberships } = this.dropUnsafeEvaluatedMemberships(evaluated, aclByProject)
+		const droppedUnsafeRules = dropped.length > 0 || droppedMemberships.length > 0
+
+		// The mapping's membership "vocabulary": every (project, role) any rule could grant a membership
+		// for. Removal is strictly bounded to this set so memberships and variable names managed outside
+		// the mapping are never stripped, even under `unmatched: 'remove'`.
+		const vocabularyMemberships = new Map<string, Set<string>>()
+		for (const rule of rules) {
+			if (rule.grantMembership) {
+				const roles = vocabularyMemberships.get(rule.grantMembership.project) ?? new Set<string>()
+				roles.add(rule.grantMembership.role)
+				vocabularyMemberships.set(rule.grantMembership.project, roles)
+			}
+		}
+		const before = await this.snapshot(db, identity.id, vocabularyMemberships)
+
+		await this.applyMemberships(db, identity.id, memberships, vocabularyMemberships, unmatched)
+
+		const after = await this.snapshot(db, identity.id, vocabularyMemberships)
+
+		if (snapshotEquals(before, after)) {
+			return { audit: null, droppedUnsafeRules }
+		}
+
+		return { audit: { before, after, syncPolicy, unmatched }, droppedUnsafeRules }
+	}
+
+	/**
+	 * Partition rules into those safe to apply and those dropped by the apply-time safety backstop. A rule
+	 * is dropped when its granted membership produces ANY validation error against the project's CURRENT ACL
+	 * schema (fail-closed) — condition-injection above all, but also an unknown role/variable, a malformed
+	 * condition value, or a forbidden predefined variable. A validation throw is treated as unsafe (we cannot
+	 * prove the grant safe). Schemas (and, when needed, project existence) are resolved at most once per
+	 * project. The dropped set is returned so the caller can emit a fail-open audit marker.
+	 *
+	 * When `getSchema` returns no ACL it does NOT mean "the project does not exist": it returns undefined both
+	 * for a project that has no row yet AND for one whose row exists but whose container / content schema is
+	 * momentarily unresolvable (mid-provisioning, transient). The two need OPPOSITE handling, so we
+	 * disambiguate via the tenant `project` table:
+	 *   - no project row → the grant is genuinely inert (`applyMemberships` resolves the same slug and skips
+	 *     it, so nothing is written). KEEP the rule for when the project is created later.
+	 *   - project row EXISTS but the ACL is unresolvable → `applyMemberships` WOULD still write the membership
+	 *     (it resolves the slug from the tenant `project` table, independent of the content schema), so an
+	 *     UNVALIDATED grant — including a claim-derived value targeting a `condition` ACL variable — could
+	 *     land. Fail closed: DROP the rule (it re-applies on a later sign-in once the schema resolves). This
+	 *     matches the direct add-member path, which refuses a membership whose project schema can't be resolved.
+	 *
+	 * Returns the per-project ACL map it built (`aclByProject`) so the runtime backstop
+	 * ({@link dropUnsafeEvaluatedMemberships}) can re-use it without re-resolving any schema.
+	 */
+	private async dropUnsafeRules(
+		db: DatabaseContext,
+		rules: readonly ClaimMappingRule[],
+	): Promise<{ safe: ClaimMappingRule[]; dropped: ClaimMappingRule[]; aclByProject: Map<string, Acl.Schema | null> }> {
+		const aclByProject = new Map<string, Acl.Schema | null>()
+		const projectExistsBySlug = new Map<string, boolean>()
+		const safe: ClaimMappingRule[] = []
+		const dropped: ClaimMappingRule[] = []
+		for (const rule of rules) {
+			const membership = rule.grantMembership
+			if (!membership) {
+				safe.push(rule)
+				continue
+			}
+			if (!aclByProject.has(membership.project)) {
+				const schema = await this.projectSchemaResolver.getSchema(membership.project)
+				aclByProject.set(membership.project, schema?.acl ?? null)
+			}
+			const acl = aclByProject.get(membership.project) ?? null
+			if (acl === null) {
+				if (!projectExistsBySlug.has(membership.project)) {
+					const project = await db.queryHandler.fetch(new ProjectBySlugQuery(membership.project))
+					projectExistsBySlug.set(membership.project, project != null)
+				}
+				// project row exists but its ACL is unresolvable → can't prove the grant safe → drop (fail-closed);
+				// no row yet → genuinely inert, keep for a project created later.
+				if (projectExistsBySlug.get(membership.project)) {
+					dropped.push(rule)
+				} else {
+					safe.push(rule)
+				}
+				continue
+			}
+			let unsafe: boolean
+			try {
+				unsafe = validateClaimMappingMembership(acl, membership).length > 0
+			} catch {
+				unsafe = true
+			}
+			if (unsafe) {
+				dropped.push(rule)
+			} else {
+				safe.push(rule)
+			}
+		}
+		return { safe, dropped, aclByProject }
+	}
+
+	/**
+	 * RUNTIME companion to {@link dropUnsafeRules} (A09 apply-time backstop, part 2). `dropUnsafeRules`
+	 * validates each rule's static CONFIG shape and — like config-time validation — TOLERATES a missing
+	 * membership variable (`VARIABLE_EMPTY`): an A09 grant may legitimately set only some of a role's
+	 * variables. For an ordinary role that tolerance is safe: a variable that resolves to no value just
+	 * narrows CONTENT access (the membership resolver maps it to `{ never: true }` — strictly LESS access,
+	 * never more), and a role's tenant permissions are matched against that role's OWN tenant rule (a
+	 * missing variable there denies, never escalates).
+	 *
+	 * The ONE role that breaks the assumption is the project `admin` role: {@link ProjectScope} grants the
+	 * PROJECT_ADMIN tenant role (project secrets, member management, IdP config, deploy, …) to ANY identity
+	 * holding an `admin` membership in the project — keyed on the role NAME alone, independent of the
+	 * membership's variables. So when a claim-derived variable meant to SCOPE an `admin` grant resolves
+	 * empty, `applyMemberships` drops the empty variable before the write and persists a BARE `admin`
+	 * membership — i.e. UNSCOPED project-admin, even though the operator intended a scoped grant, and a
+	 * membership the direct add-member path ({@link MembershipResolver}, via `MembershipValidator`) would
+	 * REJECT as `VARIABLE_EMPTY`. (`admin` is the only role-name-based grant in the whole authorization
+	 * layer; every other privilege is gated by ACL variables/predicates, so it cannot be widened this way.)
+	 *
+	 * So, fail-closed, we re-validate every evaluated `admin` grant EXACTLY as it would be written (empty
+	 * variables filtered out, as `applyMemberships` does) against the live ACL and DROP it if the resolver
+	 * reports any error — i.e. if a required (non-fallback) `admin` variable would be absent. Under `keep`
+	 * the bare grant is then never written; under `remove` it is absent from the granted set, so
+	 * reconciliation revokes any pre-existing one. Non-`admin` grants are left untouched (their partial
+	 * grants stay valid). The drop folds into `droppedUnsafeRules`, so the caller still emits the
+	 * `idp_role_mapping_failed` fail-open marker.
+	 */
+	private dropUnsafeEvaluatedMemberships(
+		memberships: readonly MappedMembership[],
+		aclByProject: ReadonlyMap<string, Acl.Schema | null>,
+	): { safe: MappedMembership[]; dropped: MappedMembership[] } {
+		const resolver = new MembershipResolver()
+		const safe: MappedMembership[] = []
+		const dropped: MappedMembership[] = []
+		for (const membership of memberships) {
+			const acl = aclByProject.get(membership.project) ?? null
+			// Only `admin` is privileged by role name independent of its variables (see above). A null ACL means
+			// the project has no row yet — an existing-but-unresolvable project had its rule dropped upstream, so
+			// it never reaches here — so the grant is inert (`applyMemberships` skips the missing project): keep it.
+			if (membership.role !== ProjectRole.ADMIN || acl === null) {
+				safe.push(membership)
+				continue
+			}
+			// Validate the membership as it will be persisted: `applyMemberships` filters out empty-valued
+			// variables before the write, so an unset required (non-fallback) variable surfaces here as
+			// `VARIABLE_EMPTY`, exactly as the direct add-member path reports and rejects it. Any error ⇒ unsafe.
+			const written: Acl.Membership = {
+				role: membership.role,
+				variables: membership.variables.filter(it => it.values.length > 0).map(it => ({ name: it.name, values: [...it.values] })),
+			}
+			let unsafe: boolean
+			try {
+				unsafe = resolver.resolve(acl, [written], MembershipResolver.UnknownIdentity, false).errors.length > 0
+			} catch {
+				unsafe = true
+			}
+			if (unsafe) {
+				dropped.push(membership)
+			} else {
+				safe.push(membership)
+			}
+		}
+		return { safe, dropped }
+	}
+
+	// Membership writes are driven through the low-level commands directly (as InviteManager also does),
+	// not via ProjectMemberManager (the "normal" add/update-member path): A09 needs semantics that path does
+	// not offer — empty-value hard-delete avoidance under `keep`, and vocabulary-bounded removal under `remove`.
+	private async applyMemberships(
+		db: DatabaseContext,
+		identityId: string,
+		grantedMemberships: readonly MappedMembership[],
+		vocabularyMemberships: ReadonlyMap<string, ReadonlySet<string>>,
+		unmatched: NonNullable<ClaimMapping['unmatched']>,
+	): Promise<void> {
+		// Group granted memberships by project so each project is resolved (slug -> id) only once.
+		const byProject = new Map<string, MappedMembership[]>()
+		for (const membership of grantedMemberships) {
+			const list = byProject.get(membership.project) ?? []
+			list.push(membership)
+			byProject.set(membership.project, list)
+		}
+
+		// Under `remove`, reconcile every project in the mapping's membership vocabulary — not only the
+		// projects granted this sign-in — so a membership whose claim disappeared entirely (its project is
+		// then absent from `byProject`) is still revoked. `keep` only ever touches the projects it grants.
+		const projectSlugs = unmatched === 'remove'
+			? new Set([...vocabularyMemberships.keys(), ...byProject.keys()])
+			: new Set(byProject.keys())
+
+		for (const projectSlug of projectSlugs) {
+			const project = await db.queryHandler.fetch(new ProjectBySlugQuery(projectSlug))
+			if (!project) {
+				// Mapping references a project that does not exist (or was deleted) — skip it rather
+				// than fail the whole sign-in. The audit's before/after won't reflect it.
+				continue
+			}
+
+			const memberships = byProject.get(projectSlug) ?? []
+			const grantedRoles = new Set(memberships.map(it => it.role))
+
+			if (unmatched === 'remove') {
+				// Removal is bounded to the mapping's own membership vocabulary (project::role named by some
+				// rule): a role the mapping could grant but doesn't this sign-in is stripped, while a
+				// membership role no rule names (managed outside the mapping) is left untouched.
+				const vocabularyRoles = vocabularyMemberships.get(projectSlug) ?? new Set<string>()
+				const existing = await db.queryHandler.fetch(new ProjectMembershipByIdentityQuery({ id: project.id }, [identityId]))
+				for (const membership of existing) {
+					if (vocabularyRoles.has(membership.role) && !grantedRoles.has(membership.role)) {
+						await db.commandBus.execute(new RemoveProjectMembershipCommand(project.id, identityId, membership.role))
+					}
+				}
+			}
+
+			for (const membership of memberships) {
+				// Under `remove` the IdP is the source of truth, and the system does NOT allow an empty membership
+				// variable — the direct add-member path hard-deletes a membership whose variable resolves to no
+				// values (`CreateOrUpdateProjectMembershipCommand` deletes such a row), and the membership
+				// resolver reports a missing/empty variable as VARIABLE_EMPTY. So a DECLARED variable that resolves
+				// to no values means the grant is empty-scoped and meaningless: REVOKE the whole membership,
+				// consistently with that invariant, rather than leaving a role with a missing/empty variable. (CORR-1:
+				// clearing the variable to `[]` instead would, for a `condition` variable, parse to `{ or: [] }` =
+				// allow-all — the opposite of revoking.) Under `keep` we never revoke, so an empty variable is simply
+				// not applied below and the grant stays.
+				if (unmatched === 'remove' && membership.variables.some(it => it.values.length === 0)) {
+					await db.commandBus.execute(new RemoveProjectMembershipCommand(project.id, identityId, membership.role))
+					continue
+				}
+
+				await db.commandBus.execute(
+					new CreateOrUpdateProjectMembershipCommand(
+						project.id,
+						identityId,
+						{
+							role: membership.role,
+							// Drop variables with no values: an unset variable simply isn't applied (a role with no
+							// variables is fine — it sends none). Under `keep` this is the only empty-handling; under
+							// `remove` an empty DECLARED variable already revoked the whole membership above. Because the
+							// filtered list never carries an empty `set`, the command's hard-delete-on-empty never fires
+							// here — so `keep` never revokes a grant, and `remove`'s revocation stays explicit above.
+							variables: membership.variables
+								.filter(it => it.values.length > 0)
+								.map(it => ({ name: it.name, set: [...it.values] })),
+						},
+					),
+				)
+			}
+		}
+	}
+
+	/**
+	 * Snapshot the identity's mapping-relevant memberships for the audit delta: its memberships (with
+	 * variable values) for exactly the (project, role) pairs in the mapping's vocabulary. Bounding is by
+	 * (project, role) — a membership whose ROLE no rule names is excluded entirely — which keeps the audit
+	 * consistent with the (also vocabulary-bounded) reconciliation. NOTE the bound is per-(project, role),
+	 * NOT per-variable-name: for an in-vocabulary membership ALL its variables are snapshotted, including any
+	 * variable managed OUTSIDE the mapping on that same role (e.g. an admin-set `condition` filter), and a
+	 * `passthrough` variable's value IS the verbatim external claim value. So the idp_role_mapped event_data
+	 * can disclose claim-derived / admin-managed variable values for a mapped role to system:viewAuthLog
+	 * readers — by design (the recorded value is the ACL grant being audited). Variable values are included
+	 * so a sign-in that only changes a claim-derived membership variable — itself a row-level ACL grant — is
+	 * still detected as a change and audited.
+	 */
+	private async snapshot(
+		db: DatabaseContext,
+		identityId: string,
+		vocabularyMemberships: ReadonlyMap<string, ReadonlySet<string>>,
+	): Promise<ClaimMappingSnapshot> {
+		const memberships: MappedMembership[] = []
+		for (const [slug, roles] of vocabularyMemberships) {
+			const project = await db.queryHandler.fetch(new ProjectBySlugQuery(slug))
+			if (!project) {
+				continue
+			}
+			const rows = await db.queryHandler.fetch(new ProjectMembershipByIdentityQuery({ id: project.id }, [identityId]))
+			for (const row of rows) {
+				// Only the roles the mapping itself could grant: a membership role no rule names (managed outside
+				// the mapping) is neither reconciled nor disclosed in the audit delta.
+				if (roles.has(row.role)) {
+					memberships.push({ project: slug, role: row.role, variables: row.variables })
+				}
+			}
+		}
+
+		return { memberships: sortMemberships(memberships) }
+	}
+}
+
+// Stable ordering (memberships by project+role, variables by name, values sorted) so `snapshotEquals`
+// compares by content, not by the DB's row/array order. Assumes variable `values` are always JSON
+// string arrays (which they are — the membership commands only ever store `string[]`); a non-string
+// element would make the default sort order-unstable and the JSON.stringify comparison spurious, so
+// keep variable values string-typed.
+const sortMemberships = (memberships: readonly MappedMembership[]): readonly MappedMembership[] =>
+	[...memberships]
+		.map(membership => ({
+			project: membership.project,
+			role: membership.role,
+			variables: [...membership.variables]
+				.map(variable => ({ name: variable.name, values: [...variable.values].sort() }))
+				.sort((a, b) => a.name.localeCompare(b.name)),
+		}))
+		.sort((a, b) => a.project.localeCompare(b.project) || a.role.localeCompare(b.role))
+
+const snapshotEquals = (a: ClaimMappingSnapshot, b: ClaimMappingSnapshot): boolean => JSON.stringify(a) === JSON.stringify(b)

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

@@ -7,6 +7,9 @@ import { CreateIdpCommand } from '../../commands/idp/CreateIdpCommand.js'
 import { IDPHandlerRegistry } from './IDPHandlerRegistry.js'
 import { IdentityProviderNotFoundError } from './IdentityProviderNotFoundError.js'
 import { InvalidIDPConfigurationError } from './InvalidIDPConfigurationError.js'
+import { findClaimMappingShapeErrors, findRemovedRuleKeys, isRecord, parseClaimMapping } from './ClaimMapping.js'
+import { validateClaimMappingMembership } from './ClaimMappingValidation.js'
+import { ProjectSchemaResolver } from '../../type/index.js'
 import { DisableIdpCommand } from '../../commands/idp/DisableIdpCommand.js'
 import { EnableIdpCommand } from '../../commands/idp/EnableIdpCommand.js'
 import { UpdateIdpCommand, UpdateIdpData } from '../../commands/idp/UpdateIdpCommand.js'
@@ -15,6 +18,7 @@ import { IdentityProviderDto } from '../../queries/idp/types.js'
 export class IDPManager {
 	constructor(
 		private readonly idpRegistry: IDPHandlerRegistry,
+		private readonly projectSchemaResolver: ProjectSchemaResolver,
 	) {
 	}
 
@@ -22,7 +26,8 @@ export class IDPManager {
 		return await db.transaction(async (db): Promise<RegisterIDPResponse> => {
 			try {
 				const providerService = this.idpRegistry.getHandler(idp.type)
-				providerService.validateConfiguration(idp.configuration)
+				this.assertNoUnknownConfigurationKeys(providerService.validateConfiguration(idp.configuration), idp.configuration)
+				await this.assertValidClaimMapping(idp.configuration)
 			} catch (e) {
 				if (e instanceof IdentityProviderNotFoundError) {
 					return new ResponseError('UNKNOWN_TYPE', `IDP type ${idp.type} not found`)
@@ -75,31 +80,16 @@ export class IDPManager {
 				return new ResponseError('NOT_FOUND', `IDP ${slug} not found`)
 			}
 
-			const newConfiguration = (() => {
-				if (!data.configuration) {
-					return existing.configuration
-				}
-				if (!mergeConfiguration) {
-					return data.configuration
-				}
-
-				const newConfiguration = { ...existing.configuration }
-				for (const [key, value] of Object.entries(data.configuration)) {
-					if (value === null) {
-						delete newConfiguration[key]
-					} else {
-						newConfiguration[key] = value
-					}
-				}
-
-				return newConfiguration
-			})()
+			const newConfiguration = !data.configuration
+				? existing.configuration
+				: (mergeConfiguration ? deepMergeConfiguration(existing.configuration, data.configuration) : data.configuration)
 
 			try {
 				const type = data.type ?? existing.type
 				const providerService = this.idpRegistry.getHandler(type)
 				if (data.configuration !== undefined || type !== existing.type) {
-					providerService.validateConfiguration(newConfiguration)
+					this.assertNoUnknownConfigurationKeys(providerService.validateConfiguration(newConfiguration), newConfiguration)
+					await this.assertValidClaimMapping(newConfiguration)
 				}
 			} catch (e) {
 				if (e instanceof InvalidIDPConfigurationError) {
@@ -119,6 +109,89 @@ export class IDPManager {
 		})
 	}
 
+	/**
+	 * Reject top-level `configuration` keys the provider does not recognise.
+	 *
+	 * Every provider configuration is parsed with `Typesafe.partial`, which silently DROPS unknown
+	 * properties. Without this check `addIDP` / `updateIDP` answer `ok` to a configuration the
+	 * provider will never act on — a typo like `fetchUserinfo` (lowercase i) reads as a successfully
+	 * applied setting while the option stays off, and an option that a given engine version does not
+	 * support yet looks indistinguishable from one that works.
+	 *
+	 * The parsed result carries exactly the keys the provider understood, so the difference against
+	 * the submitted object is the set of ignored keys. All of them are reported at once (rather than
+	 * the first, as `Typesafe.noExtraProps` would) so a configuration with several typos takes one
+	 * round trip to fix, matching {@link findRemovedRuleKeys}.
+	 *
+	 * Only the top level is checked: nested shapes that need strictness validate themselves
+	 * (`claimMapping` via {@link parseClaimMapping}). Reading a stored configuration is deliberately
+	 * left untouched — this runs at write time only, so a row written before this check keeps
+	 * authenticating instead of locking its users out.
+	 */
+	private assertNoUnknownConfigurationKeys(parsed: {}, submitted: Record<string, unknown>): void {
+		const known = new Set(Object.keys(parsed))
+		const unknown = Object.keys(submitted).filter(key => !known.has(key))
+		if (unknown.length > 0) {
+			throw new InvalidIDPConfigurationError(
+				`unknown configuration ${unknown.length === 1 ? 'property' : 'properties'} ${unknown.join(', ')}; `
+					+ `remove ${unknown.length === 1 ? 'it' : 'them'} or check the spelling — the provider would ignore ${unknown.length === 1 ? 'it' : 'them'}`,
+			)
+		}
+	}
+
+	/**
+	 * Validate the optional A09 `claimMapping` embedded in an IdP `configuration`: reject a removed
+	 * `grantRoles` (global-role mapping was dropped — see {@link parseClaimMapping}), reject a
+	 * malformed shape, and validate each granted membership's role against the target project's ACL
+	 * schema (mirroring the direct add-member path). Throws {@link InvalidIDPConfigurationError},
+	 * surfaced as `INVALID_CONFIGURATION`.
+	 */
+	private async assertValidClaimMapping(configuration: Record<string, unknown>): Promise<void> {
+		const removed = findRemovedRuleKeys(configuration)
+		if (removed.length > 0) {
+			throw new InvalidIDPConfigurationError(
+				`claimMapping no longer supports ${removed.join(', ')} (global-role mapping was removed); grant a project membership via grantMembership instead`,
+			)
+		}
+		let mapping
+		try {
+			mapping = parseClaimMapping(configuration)
+		} catch (e) {
+			throw new InvalidIDPConfigurationError(`Invalid claimMapping: ${e instanceof Error ? e.message : String(e)}`)
+		}
+		if (!mapping) {
+			return
+		}
+		// Reject contradictory / empty-by-construction rule shapes (a rule setting both equals+contains; a
+		// variable's `from.where` without `from.pick`) before the per-project ACL checks, so a
+		// misconfiguration is caught even when the target project does not exist yet (ACL loop skipped).
+		const shapeErrors = findClaimMappingShapeErrors(mapping)
+		if (shapeErrors.length > 0) {
+			throw new InvalidIDPConfigurationError(shapeErrors[0])
+		}
+		// Validate each granted membership's role AND its variables against the target project's ACL schema,
+		// via the shared {@link validateClaimMappingMembership} (the same checks `IDPClaimSyncService`
+		// re-runs at apply time, so the two enforcement points can't drift). A project that does not (yet)
+		// exist is skipped — it may be created later, and a sign-in referencing a missing project is
+		// harmless (the grant is skipped). NOTE: this validation runs only here at add/update time and is
+		// NOT re-checked when the project/role appears later; the unsafe-condition-variable case is caught
+		// again at apply time by `IDPClaimSyncService`, but other drift (unknown role/variable) is not.
+		for (const rule of mapping.rules) {
+			const membership = rule.grantMembership
+			if (!membership) {
+				continue
+			}
+			const schema = await this.projectSchemaResolver.getSchema(membership.project)
+			if (!schema) {
+				continue
+			}
+			const errors = validateClaimMappingMembership(schema.acl, membership)
+			if (errors.length > 0) {
+				throw new InvalidIDPConfigurationError(errors[0].message)
+			}
+		}
+	}
+
 	public async listIDP(db: DatabaseContext): Promise<IdentityProviderDto[]> {
 		const result = await db.queryHandler.fetch(new IdentityProvidersQuery())
 		return result.map(it => {
@@ -132,6 +205,38 @@ export class IDPManager {
 	}
 }
 
+/**
+ * Recursively merge configurer-supplied `updates` into the stored `base` configuration (the
+ * `mergeConfiguration: true` path of {@link IDPManager.updateIDP}), returning a new object:
+ * - a plain-object value is merged INTO an existing plain-object value at the same key, so updating one
+ *   field of a nested config object preserves its siblings. This matters for `configuration.claimMapping`,
+ *   which holds two independent concerns in one object — the OIDC identity-remap (`email` / `name` /
+ *   `externalIdentifier` / `attributesKey`) and the A09 `rules` — so a shallow replace of `claimMapping`
+ *   while updating one would silently wipe the other.
+ * - any non-object value (including ARRAYS, e.g. the A09 `rules` list) REPLACES wholesale — arrays are
+ *   never merged element-wise.
+ * - a `null` value DELETES the key (the established "send null to unset" convention).
+ * - `__proto__` / `constructor` / `prototype` keys are skipped at EVERY level: they are never a legitimate
+ *   config field and writing one through could pollute the object's prototype.
+ */
+const deepMergeConfiguration = (base: Record<string, unknown>, updates: Record<string, unknown>): Record<string, unknown> => {
+	const result: Record<string, unknown> = { ...base }
+	for (const [key, value] of Object.entries(updates)) {
+		if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
+			continue
+		}
+		if (value === null) {
+			delete result[key]
+		} else if (isRecord(value)) {
+			const existingChild = result[key]
+			result[key] = deepMergeConfiguration(isRecord(existingChild) ? existingChild : {}, value)
+		} else {
+			result[key] = value
+		}
+	}
+	return result
+}
+
 export type RegisterIDPResponse = Response<null, AddIdpErrorCode>
 export type DisableIDPResponse = Response<null, DisableIdpErrorCode>
 export type EnableIDPResponse = Response<null, EnableIdpErrorCode>

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

@@ -54,6 +54,13 @@ export type RevalidationResult =
 		status: 'valid'
 		/** Fresh claims, if the revalidation method returned any (e.g. userinfo). */
 		claims?: Record<string, unknown>
+		/**
+		 * Whether `claims` represent the IdP's COMPLETE claim surface — the same one sign-in sees — so a
+		 * claim-mapping reconciliation may safely remove memberships under `unmatched: "remove"`. A partial
+		 * surface (a userinfo-only probe, or a refresh whose userinfo fetch failed) leaves this false, and the
+		 * caller keeps refresh-time sync additive-only to avoid stripping a grant the IdP still asserts.
+		 */
+		claimsComplete?: boolean
 		/** Updated session state to persist (e.g. a rotated refresh token). */
 		idpSession?: IDPSessionState
 	}