flex-auth/workplans/FLEX-WP-0004-delegated-pdp-and-directory-adapters.md

---
id: FLEX-WP-0004
type: workplan
title: "Delegated PDP and Directory Adapters"
domain: netkingdom
status: todo
owner: flex-auth
topic_slug: flex-auth
planning_priority: P2
planning_order: 40
depends_on_workplans:
  - FLEX-WP-0002
related_workplans:
  - FLEX-WP-0003
created: "2026-05-04"
updated: "2026-05-17"
state_hub_workstream_id: "99a82976-d376-42b0-89cc-c44e01c0bec6"
---

# FLEX-WP-0004: Delegated PDP and Directory Adapters

## Purpose

Let flex-auth coordinate established authorization and directory systems while
remaining the stable control plane for protected systems.

The standalone core must work first. This workplan adds delegated backends and
provider examples after flex-auth's own request, decision, registry, and audit
vocabulary are stable.

> **Scope change (2026-05-15).** Per ADR-003 and the pre-implementation
> assessment, the Topaz *evaluation* moved to `FLEX-WP-0005 T04` so its
> output can shape the standalone core. This workplan now implements the
> Topaz *adapter* against that mapping; the standalone evaluator already
> speaks Rego, so adapter work focuses on directory delegation, wire
> protocol, and consistency metadata rather than re-deciding fit.

> **CARING note (2026-05-17).** Delegated adapters must preserve the
> CARING decision envelope fields defined by the standalone core. Backend
> native semantics may differ, but protected systems should still see the
> same descriptor, exposure, restriction, conformance, and audit shape.

## P4.1 - Implement Topaz adapter

```task
id: FLEX-WP-0004-T001
status: todo
priority: high
state_hub_task_id: "9046418c-2b78-42c6-8bfa-76d6ed0050dd"
```

Implement the Topaz adapter behind flex-auth's stable PDP and directory
contracts. Consumes `docs/topaz-mapping-spike.md` produced in
`FLEX-WP-0005 T04`.

Scope:

- Wire-protocol selection (gRPC vs HTTP vs embedded library) with
  rationale recorded.
- Directory delegation: flex-auth registry writes flow into Topaz
  directory objects/relations; reads can be served from either side
  with documented consistency semantics.
- Policy delegation: a flex-auth package (Rego-in-Markdown) is
  decomposed and pushed to Topaz unchanged; decisions returned carry
  the same envelope shape as standalone evaluation.
- Failure modes: Topaz unavailable, stale directory, partial result —
  each produces a decision envelope that the standalone code path
  could also have produced.
- CARING preservation: delegated decisions include the same CARING
  descriptor, restriction precedence, exposure mode, conformance findings,
  and exposure-event hooks as standalone decisions.

Output: adapter package under `internal/adapters/topaz/`, end-to-end
integration test using the `examples/topaz/` docker-compose from the
spike, and an operations note covering startup, health checks, and
fail-closed defaults.

## P4.2 - Add relationship PDP adapter boundary

```task
id: FLEX-WP-0004-T002
status: todo
priority: high
state_hub_task_id: "b77a0b70-b492-46ba-badf-8c2eebe006aa"
```

Define and implement adapter contracts for OpenFGA and SpiceDB-style checks:

- tuple/resource mapping
- inherited access
- batch/list operations
- consistency metadata
- error and stale-data diagnostics
- preservation of CARING scope, plane, capability, exposure, and derived
  capability metadata across tuple-oriented backends

## P4.3 - Add rule PDP adapter boundary

```task
id: FLEX-WP-0004-T003
status: todo
priority: high
state_hub_task_id: "4e4e5e45-c05a-4a31-8126-f0c7676b1e6c"
```

Define and implement adapter contracts for OPA/Rego and Cedar-style policies:

- principal/action/resource/context mapping
- policy package versioning
- test fixtures
- obligations and diagnostics
- CARING frontmatter and conformance findings when backend-native policy
  languages cannot represent every descriptor dimension directly

## P4.4 - Add Keycloak Authorization Services adapter path

```task
id: FLEX-WP-0004-T004
status: todo
priority: medium
state_hub_task_id: "8d3bbc28-985b-4dd7-9fb8-f9a858eb5a6b"
```

Document and spike Keycloak Authorization Services integration for
Keycloak-centric deployments without making Keycloak the only resource-policy
source of truth.

## P4.5 - Add Entra/Graph and SCIM group resolver adapters

```task
id: FLEX-WP-0004-T005
status: todo
priority: medium
state_hub_task_id: "4fc3fb91-8763-453e-8e54-36178cb11efd"
```

Implement directory group resolver patterns for:

- Microsoft Graph group overage
- SCIM provisioning
- LDAP/AD
- Keycloak admin API

Each resolver must expose freshness, source, and overage metadata.
Resolvers must also identify which organization relation, subject type,
group, or role claim was derived from the external directory so CARING
descriptor provenance remains inspectable.

## P4.6 - Add delegated-mode operations docs

```task
id: FLEX-WP-0004-T006
status: todo
priority: medium
state_hub_task_id: "491260f9-b4d7-46fe-8220-d358597db33a"
```

Document deployment, failure modes, caching, fail-closed/fail-open policy,
consistency, and audit behavior for delegated backends.

## Exit Criteria

- flex-auth can delegate decisions to at least one external PDP in a controlled
  adapter shape.
- Directory group freshness and overage are explicit.
- Backend changes do not alter the protected-system-facing flex-auth API.
- Topaz/OpenFGA/OPA/Cedar/Keycloak/Entra tradeoffs are documented with
  practical guidance.
- Delegated backends preserve CARING descriptor and conformance metadata
  instead of leaking backend-native role semantics into protected systems.