flex-auth/docs/rule-pdp-adapter-boundary.md

Rule PDP Adapter Boundary

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

Role

The rule PDP adapter is the common boundary for OPA/Rego, Cedar-style policy services, and other engines that evaluate a policy language over a structured request. It is separate from the relationship-PDP boundary: relationship backends answer tuple reachability questions, while rule backends evaluate policy logic over subject, action, resource, context, and CARING metadata.

Canonical Input

All rule backends receive the same canonical input shape:

input.subject
input.action
input.resource
input.context
input.caring_context
input.policy.package
input.policy.version

OPA/Rego can consume this shape directly. Cedar adapters translate the same fields into principal/action/resource/context entities at the backend boundary. Protected systems do not see backend-native input syntax.

Policy Artifacts

PolicyArtifactFromPackage converts a validated Rego-in-Markdown package into a delegated artifact:

• language=rego
• package id and version from frontmatter
• extracted Rego module unchanged
• test blocks and fixtures preserved
• CARING policy metadata preserved

Cedar and other rule engines use the same PolicyArtifact envelope, but may reject unsupported artifacts with rule_policy_unsupported.

Fixtures

EvaluateFixtures runs api.PolicyFixture values through the delegated adapter and compares the returned effect, reason, and obligations. This keeps delegated backends honest against the same fixtures used by the standalone evaluator.

Obligations And Diagnostics

Rule backends can return obligations such as masking, audit, or approval requirements. The adapter copies them into the canonical DecisionEnvelope. Backend diagnostics are preserved and supplemented with:

• adapter=rule
• backend name
• delegated mode
• language
• policy package and version
• fail-closed reason when present

Versioning

The envelope records backend policy version in matched_policy_version and provenance.policy_version. A backend may return a newer concrete revision than the request asked for; the adapter records what actually matched.

Failure Behavior

The adapter fails closed for:

• backend unavailable: rule_backend_unavailable
• stale policy: rule_policy_stale
• partial result: rule_partial_result
• invalid input: rule_request_incomplete
• unsupported policy artifact: rule_policy_unsupported

Each failure returns a deny envelope with diagnostics.rule_failure and a CARING conformance finding.

CARING Preservation

Rule engines vary in how much of CARING they can represent natively. flex-auth keeps CARING outside the backend-specific language contract:

• request descriptor wins;
• backend result descriptor is next;
• policy frontmatter supplies profile and expected dimensions;
• gaps become RULE-CARING-METADATA-GAP or RULE-CARING-DESCRIPTOR-MISSING findings.

The decision envelope preserves descriptor, scope, planes, capabilities, exposure modes, restrictions, derived capabilities, conformance findings, exposure-event hooks, obligations, and diagnostics. Backend-native policy names should never replace canonical CARING roles in protected-system responses.