3.6 KiB
Relationship PDP Adapter Boundary
Status: implemented for FLEX-WP-0004 P4.2.
Role
The relationship PDP adapter is the common boundary for OpenFGA, SpiceDB, and other tuple-oriented authorization systems. These backends answer questions like:
is subject S related to object O through relation R?
flex-auth keeps the protected-system API stable. The adapter translates
CheckRequest, BatchCheckRequest, registry relationships, and
list_allowed queries into tuple checks, then wraps backend responses
back into the canonical DecisionEnvelope.
Tuple Mapping
Canonical flex-auth relationship facts map to:
| flex-auth | tuple field |
|---|---|
| resource type | object_type |
| resource id | object_id |
| action or relation | relation |
| subject type | subject_type |
| subject id | subject_id |
| group membership indirection | subject_relation=member |
Registry group and team membership become group#member tuples.
Resource parent edges become parent tuples. Resource owners become
owner_team tuples. Relationship facts keep conditions, provenance,
metadata, and CARING descriptors on the imported tuple so backend
results can preserve explanatory context.
Inheritance
Relationship backends represent inheritance differently:
- OpenFGA usually models it in the authorization model through rewrites.
- SpiceDB usually models it through relation definitions and caveats.
- flex-auth records inherited evidence in
TupleCheckResult.InheritedFrom.
The envelope does not expose backend-native rewrite syntax. It records the fact that inheritance participated through diagnostics and preserves the matched CARING descriptor from direct or inherited tuples.
Batch And List
BatchCheck preserves request order. If the backend returns a partial
batch, flex-auth emits fail-closed deny envelopes for the affected
resources.
ListAllowed returns a ListAllowedResult containing allow envelopes,
the backend consistency token, and diagnostics. It intentionally returns
envelopes instead of raw resource ids so downstream consumers keep the
same audit and CARING metadata they receive from single checks.
Consistency Metadata
Tuple backends expose different consistency tokens:
- OpenFGA: model id plus optional tuple-store continuation/freshness metadata.
- SpiceDB: zedtoken.
The adapter stores the backend token in
DecisionEnvelope.provenance.directory_etag. The field name is kept for
compatibility with the existing flex-auth envelope; for relationship PDPs
it means "relationship backend consistency token".
Failure Behavior
The adapter fails closed for:
- backend unavailable:
relationship_backend_unavailable - stale consistency token:
relationship_data_stale - partial backend result:
relationship_partial_result - untranslatable request:
relationship_request_incomplete
Each failure is a deny envelope with diagnostics.relationship_failure
and a CARING conformance finding. This keeps delegated tuple behavior
aligned with standalone fail-closed behavior.
CARING Preservation
Tuple systems do not understand CARING directly. flex-auth therefore keeps CARING metadata at the adapter boundary:
- request descriptor wins when supplied;
- backend result descriptor is next;
- matched tuple descriptor is next;
- inherited tuple descriptor is next;
- otherwise the envelope includes
RELATIONSHIP-CARING-DESCRIPTOR-MISSING.
The adapter copies scope, planes, capabilities, exposure modes, restrictions, derived capabilities, conformance findings, and exposure-event hooks into the decision envelope. Backend-native role or relation names should not leak into protected systems as a replacement for CARING canonical roles.