# Directory Group Resolver Adapters

Status: implemented for FLEX-WP-0004 P4.5.

## Role

Directory resolvers enrich flex-auth subjects with group and role
evidence from external identity systems. They do not decide access by
themselves. They feed the standalone, relationship, rule, Topaz, or
Keycloak decision paths with fresh subject metadata and provenance.

## Resolver Sources

Implemented resolver boundaries:

- Microsoft Graph group overage (`GraphResolver`)
- SCIM provisioning (`SCIMResolver`)
- LDAP/Active Directory (`LDAPResolver`)
- Keycloak admin API (`KeycloakResolver`)

Each resolver returns `ResolveResult` with normalized groups, roles,
freshness, overage, and metadata.

## Freshness

Every result carries:

- source
- retrieval time
- max age
- expiry time
- stale flag

Decision adapters can use this metadata to deny stale directory evidence
or to include freshness diagnostics in the decision envelope.

## Overage

Graph tokens can omit groups and instead emit overage indicators such
as `_claim_names.groups` or `hasgroups=true`. The Graph resolver records
that condition in `OverageMetadata` so downstream policy can distinguish
"no groups" from "groups omitted, lookup required".

## CARING Provenance

Each `GroupGrant` and `RoleGrant` identifies:

- source provider
- originating claim name
- organization relation
- subject type
- optional CARING descriptor

This makes it possible to explain that a canonical role or group came
from Graph, SCIM, LDAP/AD, or Keycloak rather than from an opaque token
claim. The source remains inspectable in CARING conformance reviews.

## Subject Enrichment

`MergeResults` deduplicates groups and roles across providers while
preserving freshness, overage, and descriptors. `ApplyToSubject` returns
a subject with resolved groups/roles and directory metadata attached.

The enriched subject can then flow through any flex-auth decision path
without changing protected-system request or decision contracts.