@contember/engine-tenant-api 2.2.0-alpha.2 → 2.2.0-alpha.5

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

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

@@ -0,0 +1,226 @@
+import { ClaimMapping, ClaimMappingMembership, ClaimMappingRule, ClaimMappingVariable, ClaimValueSource, isRecord } from './ClaimMapping.js'
+
+export type MappedMembership = {
+	readonly project: string
+	readonly role: string
+	readonly variables: readonly { readonly name: string; readonly values: readonly string[] }[]
+}
+
+/**
+ * Evaluate every rule of a claim mapping against the claims of an IdP response and collect the union
+ * of granted project memberships (keyed implicitly by (project, role)). Pure: no DB, no side effects —
+ * the caller decides how to apply the result (and whether to add-only or replace, per `unmatched`).
+ */
+export const evaluateClaimMapping = (mapping: ClaimMapping, claims: Record<string, unknown>): MappedMembership[] => {
+	const membershipByKey = new Map<string, MappedMembership>()
+
+	for (const rule of mapping.rules) {
+		if (!ruleMatches(rule, resolvePath(claims, rule.claim))) {
+			continue
+		}
+		if (rule.grantMembership) {
+			const membership = toMembership(rule.grantMembership, claims)
+			// JSON-encode the (project, role) pair so the dedup key can't collide on a delimiter that a
+			// slug could itself contain (a plain `${project}::${role}` would fold `a::b`/`c` into `a`/`b::c`).
+			const key = JSON.stringify([membership.project, membership.role])
+			const existing = membershipByKey.get(key)
+			membershipByKey.set(key, existing ? mergeMembershipVariables(existing, membership) : membership)
+		}
+	}
+
+	return [...membershipByKey.values()]
+}
+
+const toMembership = (membership: ClaimMappingMembership, claims: Record<string, unknown>): MappedMembership => ({
+	project: membership.project,
+	role: membership.role,
+	// Union by name so a single grant that lists the same variable twice (e.g. two `locale` entries)
+	// combines their values into one entry, rather than emitting duplicate entries that would later race
+	// and clobber each other when each is written as a full-replace of the same (membership, variable).
+	variables: unionVariablesByName(
+		(membership.variables ?? []).map(variable => ({ name: variable.name, values: resolveVariableValues(variable, claims) })),
+	),
+})
+
+/**
+ * Merge two grants of the same (project, role) by unioning their membership variables per name — so
+ * several matching rules granting the same membership combine their variables (consistent with how
+ * global roles union), rather than the last rule silently overwriting the variables of the earlier ones.
+ */
+const mergeMembershipVariables = (a: MappedMembership, b: MappedMembership): MappedMembership => ({
+	project: a.project,
+	role: a.role,
+	variables: unionVariablesByName([...a.variables, ...b.variables]),
+})
+
+/**
+ * Union a list of membership variables by name: several entries for the same variable name — whether from
+ * one grant listing it twice or from several rules granting the same membership — combine their values into
+ * a single entry. Values are de-duplicated and SORTED so the result is canonical: the same effective grant
+ * always yields the same value array regardless of claim/rule order. That keeps the persisted JSON stable
+ * (no redundant rewrite when an IdP returns a multi-valued claim in a different order across sign-ins) and
+ * the audit delta order-insensitive. Variable entries keep first-seen order.
+ */
+const unionVariablesByName = (
+	variables: readonly { readonly name: string; readonly values: readonly string[] }[],
+): { name: string; values: string[] }[] => {
+	const valuesByName = new Map<string, Set<string>>()
+	for (const variable of variables) {
+		const values = valuesByName.get(variable.name) ?? new Set<string>()
+		for (const value of variable.values) {
+			values.add(value)
+		}
+		valuesByName.set(variable.name, values)
+	}
+	return [...valuesByName].map(([name, values]) => ({ name, values: [...values].sort() }))
+}
+
+/**
+ * Resolve a membership variable to its final string values: constant `values` (always kept) unioned
+ * with values derived from `from` (extracted from the claims, then mapped / passed through / allow-
+ * filtered). Pure; an empty result simply means the variable is not applied — `IDPClaimSyncService`
+ * drops empty-valued variables so an empty `set` never soft-deletes the membership.
+ */
+export const resolveVariableValues = (variable: ClaimMappingVariable, claims: Record<string, unknown>): string[] => {
+	const values = new Set<string>(variable.values ?? [])
+	if (variable.from) {
+		const allow = variable.allow ? new Set(variable.allow) : null
+		for (const raw of extractClaimValues(variable.from, claims)) {
+			// `raw` is an external claim value used as a `map` key — look it up as an OWN property only.
+			// A plain `map?.[raw]` would let a hostile claim like `__proto__` / `constructor` resolve to an
+			// inherited prototype member (a non-array object/function), which then slips past `?? []` and
+			// throws `not iterable` in the loop below — aborting the sign-in transaction.
+			const mapped = variable.map && Object.prototype.hasOwnProperty.call(variable.map, raw)
+				? variable.map[raw]
+				: (variable.passthrough ? [raw] : [])
+			for (const value of mapped) {
+				if (!allow || allow.has(value)) {
+					values.add(value)
+				}
+			}
+		}
+	}
+	return [...values]
+}
+
+/**
+ * Extract a flat, de-duplicated list of string values from a single claim per a {@link ClaimValueSource}:
+ * resolves the (possibly nested) claim, normalises scalar/array, optionally filters + projects an
+ * array of objects (`where` / `pick`), and optionally splits a delimited string (`split`). Non-scalar
+ * leaves (objects, null/undefined) are skipped; finite numbers are coerced to their string form.
+ */
+export const extractClaimValues = (source: ClaimValueSource, claims: Record<string, unknown>): string[] => {
+	const resolved = resolvePath(claims, source.claim)
+	const items: unknown[] = Array.isArray(resolved) ? resolved : [resolved]
+	const out: string[] = []
+	for (const item of items) {
+		let value: unknown = item
+		if (source.where !== undefined || source.pick !== undefined) {
+			if (!isRecord(item)) {
+				continue
+			}
+			if (source.where && !scalarEquals(resolvePath(item, source.where.field), source.where.equals)) {
+				continue
+			}
+			value = source.pick !== undefined ? resolvePath(item, source.pick) : undefined
+		}
+		if (typeof value === 'string' && source.split !== undefined) {
+			for (const part of value.split(source.split)) {
+				const trimmed = part.trim()
+				if (trimmed.length > 0) {
+					out.push(trimmed)
+				}
+			}
+			continue
+		}
+		const scalar = coerceToString(value)
+		if (scalar !== null) {
+			out.push(scalar)
+		}
+	}
+	return [...new Set(out)]
+}
+
+/**
+ * Resolve a claim name — a rule's `claim` and a variable's `from.claim` / `pick` / `where.field` all
+ * use this same lookup. The EXACT name is tried first, so a claim whose name literally contains dots
+ * (URL-namespaced, e.g. Auth0's `https://example.com/roles`) stays addressable and wins over a nested
+ * path of the same spelling; only then is the name treated as a dot-path into nested objects
+ * (`realm_access.roles`). Own-property only at every step: never descend into inherited members, so a
+ * claim object can't surface `Object.prototype` via a `__proto__` segment (and a configured path can't
+ * read a prototype member).
+ */
+const resolvePath = (root: unknown, path: string): unknown => {
+	if (isRecord(root) && Object.prototype.hasOwnProperty.call(root, path)) {
+		return root[path]
+	}
+	let current: unknown = root
+	for (const key of path.split('.')) {
+		if (!isRecord(current) || !Object.prototype.hasOwnProperty.call(current, key)) {
+			return undefined
+		}
+		current = current[key]
+	}
+	return current
+}
+
+const coerceToString = (value: unknown): string | null => {
+	if (typeof value === 'string') {
+		return value
+	}
+	if (typeof value === 'number' && Number.isFinite(value)) {
+		return String(value)
+	}
+	return null
+}
+
+const ruleMatches = (rule: ClaimMappingRule, claimValue: unknown): boolean => {
+	if (rule.equals !== undefined) {
+		return matchEquals(claimValue, rule.equals)
+	}
+	if (rule.contains !== undefined) {
+		return matchContains(claimValue, rule.contains)
+	}
+	// No condition: match on mere PRESENCE of a non-empty value. Treated as absent: `undefined` / `null`
+	// (claim not present), the boolean `false` (a `groups`-style flag only grants when truthy), an empty
+	// array (e.g. `groups: []` — the user is in no group), and an empty string. "Presence" therefore means
+	// the claim actually carries a value, not merely that the field exists but is empty.
+	if (claimValue === undefined || claimValue === null || claimValue === false || claimValue === '') {
+		return false
+	}
+	if (Array.isArray(claimValue)) {
+		return claimValue.length > 0
+	}
+	return true
+}
+
+const matchEquals = (claimValue: unknown, expected: string | number | boolean | null): boolean => {
+	if (Array.isArray(claimValue)) {
+		return claimValue.some(it => scalarEquals(it, expected))
+	}
+	return scalarEquals(claimValue, expected)
+}
+
+const matchContains = (claimValue: unknown, needle: string | number | boolean | null): boolean => {
+	// An empty-string needle would substring-match EVERY string claim (`s.includes('') === true`) — a
+	// match-everyone grant to every user of the IdP. Config-time validation rejects it, but a config planted
+	// out-of-band (a direct `identity_provider.configuration` JSONB edit) bypasses that guard; refuse it here
+	// too so the evaluator never honours a degenerate match-everyone rule, regardless of how it arrived (SEC-1).
+	if (needle === '') {
+		return false
+	}
+	if (Array.isArray(claimValue)) {
+		return claimValue.some(it => scalarEquals(it, needle))
+	}
+	if (typeof claimValue === 'string' && typeof needle === 'string') {
+		return claimValue.includes(needle)
+	}
+	return scalarEquals(claimValue, needle)
+}
+
+const scalarEquals = (value: unknown, expected: string | number | boolean | null): boolean => {
+	if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean' || value === null) {
+		return value === expected
+	}
+	return false
+}

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

@@ -0,0 +1,158 @@
+import { Acl } from '@contember/schema'
+import { getRoleVariables, MembershipResolver, MembershipValidationErrorType } from '@contember/schema-utils'
+import { ClaimMappingMembership, ClaimMappingVariable } from './ClaimMapping.js'
+
+/**
+ * Why a granted membership in an A09 claim mapping is invalid against a project's live ACL schema.
+ * Shared by config-time validation ({@link validateClaimMappingMembership} via
+ * `IDPManager.assertValidClaimMapping`, which rejects the whole IdP config) and the apply-time backstop
+ * (`IDPClaimSyncService`, which drops the unsafe grant), so the per-membership ACL validation can never
+ * drift between the two. NOTE this shared check is ONLY the per-membership ACL validation; the rule-shape
+ * checks (`findClaimMappingShapeErrors`) and the removed-key check (`findRemovedRuleKeys`, e.g. `grantRoles`)
+ * run at config time only — the apply-time backstop deliberately re-checks just the ACL safety of each
+ * grant, not the mapping's overall shape (a malformed shape can only arrive via an out-of-band JSONB edit
+ * that bypassed config validation; `evaluateClaimMapping` then honours whatever shape it finds).
+ */
+export enum ClaimMappingMembershipErrorType {
+	/** The granted role is not defined in the project ACL. */
+	roleNotFound = 'roleNotFound',
+	/** A membership variable is not defined for the granted role. */
+	variableNotFound = 'variableNotFound',
+	/** A predefined variable (identityID / personID) cannot be set — the runtime binds it to the signed-in identity. */
+	predefinedVariable = 'predefinedVariable',
+	/**
+	 * A claim-derived (`from`) value would be written into a `condition` ACL variable without being bounded
+	 * by an `allow` allowlist (or with `passthrough`). A condition variable's stored value is parsed as a
+	 * row-level ACL condition at every content request, so this is an arbitrary-condition injection vector.
+	 */
+	conditionInjection = 'conditionInjection',
+	/** A configured value targeting a `condition` variable is not a parseable ACL condition (it would deny at content time). */
+	conditionValueInvalid = 'conditionValueInvalid',
+}
+
+export interface ClaimMappingMembershipError {
+	readonly type: ClaimMappingMembershipErrorType
+	readonly message: string
+}
+
+/**
+ * Validate one A09 granted membership against a project's live ACL schema.
+ *
+ * The shared membership-shape checks (role exists, each set variable is defined for the role, a
+ * predefined variable cannot be set, a `condition` variable's stored value parses as an ACL condition)
+ * are DELEGATED to the very {@link MembershipResolver} the direct add-member path uses — so the IdP path
+ * cannot drift from it. Only the resolver's `VARIABLE_EMPTY` is excluded: A09 grants are *partial* (a
+ * rule sets only some of a role's variables), which is legitimate here but `VARIABLE_EMPTY` to the
+ * resolver. On top of the shared checks A09 adds one claim-aware guard the resolver cannot know about —
+ * the condition-injection guard (a claim-derived value must not flow unbounded into a `condition`
+ * variable). See {@link ClaimMappingMembershipErrorType}.
+ *
+ * Returns every problem found (empty array = valid). The caller decides the consequence: config-time
+ * validation throws on the first error (rejecting the whole IdP config), while the apply-time backstop
+ * (`IDPClaimSyncService`) drops any grant that produces an error.
+ *
+ * Role / variable lookups are own-property only, so a name like `constructor` / `toString` cannot
+ * resolve to an inherited Object.prototype member and pass as defined (the resolver and
+ * `getRoleVariables` are likewise own-property guarded).
+ */
+export const validateClaimMappingMembership = (acl: Acl.Schema, membership: ClaimMappingMembership): ClaimMappingMembershipError[] => {
+	const errors: ClaimMappingMembershipError[] = []
+	const roleExists = Object.prototype.hasOwnProperty.call(acl.roles, membership.role)
+	const roleVariables = roleExists ? getRoleVariables(membership.role, acl) : {}
+
+	// A09-specific, claim-aware injection guard — MembershipResolver does not see `from`/`passthrough`/
+	// `allow`. For a `condition` ACL variable, a claim-derived value is interpreted as a row-level ACL
+	// condition on every content request, so it must be bounded by an explicit `allow` allowlist and must
+	// not use `passthrough`. Constant `values` are configurer-controlled (their shape is validated by the
+	// resolver below). Only checkable when the role resolves; an unknown role is reported as roleNotFound.
+	if (roleExists) {
+		for (const variable of membership.variables ?? []) {
+			const aclVariable = Object.prototype.hasOwnProperty.call(roleVariables, variable.name) ? roleVariables[variable.name] : undefined
+			if (
+				aclVariable?.type === Acl.VariableType.condition && variable.from !== undefined && (variable.passthrough === true || variable.allow === undefined)
+			) {
+				errors.push({
+					type: ClaimMappingMembershipErrorType.conditionInjection,
+					message:
+						`claimMapping variable '${variable.name}' of role '${membership.role}' is a condition variable: a claim-derived value is interpreted as a row-level ACL condition, so it must be constrained by an 'allow' allowlist and must not use 'passthrough'`,
+				})
+			}
+		}
+	}
+
+	// Shared shape checks — delegate to MembershipResolver over the configurer-authored STATIC values the
+	// mapping can deposit into each variable (constants + every `map` output + the `allow` allowlist), so a
+	// malformed condition in ANY of them is rejected here rather than silently denying (`{ never: true }`)
+	// on every content request once granted. Raw claim-derived values are unknown at validation time and
+	// are bounded separately by the injection guard above.
+	const resolverMembership: Acl.Membership = {
+		role: membership.role,
+		variables: (membership.variables ?? []).map(variable => ({ name: variable.name, values: staticVariableValues(variable) })),
+	}
+	const result = new MembershipResolver().resolve(acl, [resolverMembership], MembershipResolver.UnknownIdentity, false)
+	for (const error of result.errors) {
+		const translated = translateResolverError(error.error, membership, error.variable, roleVariables)
+		if (translated) {
+			errors.push(translated)
+		}
+	}
+	return errors
+}
+
+/**
+ * Every configurer-authored value the mapping could store into a variable: constant `values`, every
+ * `map` output, and the `allow` allowlist (raw claim values are excluded — unknown at validation time
+ * and bounded by the injection guard). De-duplicated; fed to the resolver so each is shape-checked.
+ */
+const staticVariableValues = (variable: ClaimMappingVariable): string[] => [
+	...new Set([
+		...(variable.values ?? []),
+		...Object.values(variable.map ?? {}).flat(),
+		...(variable.allow ?? []),
+	]),
+]
+
+const translateResolverError = (
+	type: MembershipValidationErrorType,
+	membership: ClaimMappingMembership,
+	variableName: string | undefined,
+	roleVariables: Acl.Variables,
+): ClaimMappingMembershipError | null => {
+	const aclVariable = variableName && Object.prototype.hasOwnProperty.call(roleVariables, variableName) ? roleVariables[variableName] : undefined
+	switch (type) {
+		case MembershipValidationErrorType.ROLE_NOT_FOUND:
+			return {
+				type: ClaimMappingMembershipErrorType.roleNotFound,
+				message: `claimMapping grants role '${membership.role}' which is not defined in the ACL of project '${membership.project}'`,
+			}
+		case MembershipValidationErrorType.VARIABLE_NOT_FOUND:
+			// The resolver reports a (forbidden) predefined variable as VARIABLE_NOT_FOUND when not assumed;
+			// surface A09's clearer `predefinedVariable` message when that is the actual cause.
+			if (aclVariable?.type === Acl.VariableType.predefined) {
+				return {
+					type: ClaimMappingMembershipErrorType.predefinedVariable,
+					message: `claimMapping cannot set the predefined variable '${variableName}' of role '${membership.role}'`,
+				}
+			}
+			return {
+				type: ClaimMappingMembershipErrorType.variableNotFound,
+				message: `claimMapping sets variable '${variableName}' which is not defined for role '${membership.role}' in project '${membership.project}'`,
+			}
+		case MembershipValidationErrorType.VARIABLE_INVALID:
+			// A predefined variable can also raise VARIABLE_INVALID (its non-id value) — already reported as
+			// predefinedVariable above, so don't double-report it as a bad condition value.
+			if (aclVariable?.type === Acl.VariableType.predefined) {
+				return null
+			}
+			return {
+				type: ClaimMappingMembershipErrorType.conditionValueInvalid,
+				message:
+					`claimMapping variable '${variableName}' of role '${membership.role}' is a condition variable, but a configured value (a constant, a 'map' output, or an 'allow' entry) is not a valid condition`,
+			}
+		case MembershipValidationErrorType.VARIABLE_EMPTY:
+			// A09 intentionally tolerates partial grants — a rule may set only some of a role's variables.
+			return null
+		default:
+			return null
+	}
+}