Add Keycloak authorization adapter path

docs/keycloak-authz-adapter-path.md

@@ -0,0 +1,78 @@
+# Keycloak Authorization Services Adapter Path
+
+Status: implemented for FLEX-WP-0004 P4.4.
+
+## Role
+
+The Keycloak path is for deployments that already use Keycloak as the
+identity provider and want to evaluate some authorization decisions
+through Keycloak Authorization Services. flex-auth still remains the
+source of truth for protected-system resources, CARING descriptors, and
+decision envelopes.
+
+## Mapping
+
+flex-auth maps a check to Keycloak's UMA permission shape:
+
+| flex-auth | Keycloak |
+| --- | --- |
+| protected system | resource server / audience |
+| resource id | resource id |
+| action | scope |
+| subject | requesting party |
+| context and CARING descriptor | claim token |
+
+The adapter builds a permission as `resource_id#scope`, for example
+`document:internal-note#read`.
+
+## Resource Registration
+
+`ResourceRegistrationsFromManifest` converts a
+`ResourceManifest` into Keycloak resource registrations:
+
+- resource id and type are preserved;
+- manifest actions become scopes;
+- path becomes the URI;
+- labels, trust zone, owner, parent, system, and type are stored as
+  resource attributes.
+
+Keycloak can mirror these resources, but flex-auth keeps the original
+manifest as the canonical record.
+
+## Decision Wrapping
+
+Keycloak allow/deny results are wrapped into the standard
+`DecisionEnvelope`:
+
+- `provenance.evaluator=keycloak-authz`
+- `provenance.mode=delegated`
+- Keycloak RPT token id and permission appear in diagnostics
+- CARING descriptor and conformance findings are preserved
+
+Backend-native Keycloak policy names do not replace CARING canonical
+roles in protected-system responses.
+
+## Failure Behavior
+
+The adapter fails closed for:
+
+- Keycloak unavailable: `keycloak_unavailable`
+- stale policy state: `keycloak_policy_stale`
+- partial result: `keycloak_partial_result`
+- untranslatable request: `keycloak_request_incomplete`
+
+Each failure returns a deny envelope with `diagnostics.keycloak_failure`
+and a CARING conformance finding.
+
+## Boundaries
+
+This path intentionally does not make Keycloak the only policy source of
+truth. flex-auth continues to own:
+
+- resource manifests from protected systems;
+- CARING descriptors and conformance findings;
+- audit and explanation envelope shape;
+- adapter-neutral request/decision APIs.
+
+Keycloak is a delegated evaluator and resource mirror for Keycloak-heavy
+installations, not the canonical model for the whole product.