@contember/engine-tenant-api 2.1.0-rc.3 → 2.2.0-alpha.10

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