generated from coulomb/repo-seed
104 lines
3.2 KiB
Markdown
104 lines
3.2 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
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.
|