88 lines
3.8 KiB
Markdown
88 lines
3.8 KiB
Markdown
|
# ADR-0003: Topaz-Aligned MVP
|
|||
|
|
|
|||
|
|
Date: 2026-05-15
|
|||
|
|
Status: Accepted
|
|||
|
|
Deciders: Bernd, with assessment from Claude (Opus 4.7)
|
|||
|
|
Supersedes: implicit "standalone first, evaluate Topaz later" sequencing
|
|||
|
|
in the original FLEX-WP-0004 P4.1.
|
|||
|
|
|
|||
|
|
## Context
|
|||
|
|
|
|||
|
|
The pre-implementation assessment names a primary threat: the
|
|||
|
|
"thin-wrapper-around-Topaz" trap. Topaz already combines OPA/Rego
|
|||
|
|
evaluation with a local directory inspired by Zanzibar (users, groups,
|
|||
|
|
resources, relations) and a local deployment story. If flex-auth's
|
|||
|
|
standalone core reimplements 60% of Topaz badly and then adapts to Topaz
|
|||
|
|
anyway, the abstraction earns no product value.
|
|||
|
|
|
|||
|
|
ADR-0002 commits to Rego from day one. That removes the largest source
|
|||
|
|
of friction between the standalone evaluator and Topaz, because the
|
|||
|
|
policy language is identical.
|
|||
|
|
|
|||
|
|
The remaining question is sequencing. The original workplans placed the
|
|||
|
|
Topaz evaluation at FLEX-WP-0004 P4.1, *after* the standalone core
|
|||
|
|
shapes its registry, check API, and decision log. That sequencing is
|
|||
|
|
inverted: by the time the spike runs, the core has already made shape
|
|||
|
|
decisions that the Topaz adapter will then have to translate.
|
|||
|
|
|
|||
|
|
## Decision
|
|||
|
|
|
|||
|
|
- **flex-auth's actual product surface is registry + audit + explain +
|
|||
|
|
multi-consumer + literate policy packages.** The PDP is an
|
|||
|
|
implementation detail behind a stable contract.
|
|||
|
|
- **Shape the standalone core to be Rego/Topaz-aligned from day one.**
|
|||
|
|
Concretely:
|
|||
|
|
- The standalone evaluator embeds the OPA Rego library and evaluates
|
|||
|
|
the same Rego modules a Topaz deployment would.
|
|||
|
|
- The registry's resource/subject/relation model uses vocabulary that
|
|||
|
|
maps trivially onto Topaz directory objects and relations.
|
|||
|
|
- The decision envelope carries the same provenance fields whether
|
|||
|
|
evaluation is local or delegated.
|
|||
|
|
- **The Topaz evaluation spike moves earlier.** It runs in
|
|||
|
|
FLEX-WP-0005 (Foundations), not FLEX-WP-0004, so its findings inform
|
|||
|
|
the registry, policy loader, and check API before they are written.
|
|||
|
|
- **FLEX-WP-0004 keeps Topaz only as one delegated-mode adapter**
|
|||
|
|
alongside OpenFGA, SpiceDB, OPA-as-remote, Cedar, and Keycloak
|
|||
|
|
Authorization Services. Topaz is no longer the sole evaluation
|
|||
|
|
question of FLEX-WP-0004.
|
|||
|
|
|
|||
|
|
## Rationale
|
|||
|
|
|
|||
|
|
- Aligning vocabulary up front is cheap; aligning it retroactively is
|
|||
|
|
not.
|
|||
|
|
- The standalone mode remains genuinely useful (zero external services,
|
|||
|
|
single binary, fixtures-first development) while staying Topaz-shaped
|
|||
|
|
internally.
|
|||
|
|
- Topaz remains an opinionated, single-vendor product. The product
|
|||
|
|
surface (registry, audit, explain, multi-consumer) is where flex-auth
|
|||
|
|
competes; the evaluation engine is where flex-auth integrates.
|
|||
|
|
|
|||
|
|
## Consequences
|
|||
|
|
|
|||
|
|
- The Topaz spike (FLEX-WP-0005 T04) becomes a hard prerequisite for
|
|||
|
|
FLEX-WP-0002 P2.1 schemas. Its output is a mapping document showing
|
|||
|
|
how flex-auth resources/relations correspond to Topaz directory
|
|||
|
|
objects/relations, plus a recommendation on whether to embed Topaz's
|
|||
|
|
directory contracts directly or restate them.
|
|||
|
|
- FLEX-WP-0004 is slimmed (Topaz evaluation moves out, leaving the
|
|||
|
|
Topaz adapter implementation in T01 and the relationship/rule/
|
|||
|
|
Keycloak/directory adapter work in T02–T06).
|
|||
|
|
- Keycloak Authorization Services remains an adapter path for
|
|||
|
|
Keycloak-centric deployments — flex-auth is the canonical PAP/PDP,
|
|||
|
|
Keycloak AuthZ is one delegated PDP option.
|
|||
|
|
|
|||
|
|
## Out of Scope
|
|||
|
|
|
|||
|
|
- The exact wire protocol of the Topaz adapter (gRPC vs HTTP vs library
|
|||
|
|
embed) is decided in FLEX-WP-0004 T01.
|
|||
|
|
- The directory-store implementation in standalone mode (SQLite vs
|
|||
|
|
file-backed vs in-memory) is decided in FLEX-WP-0002 T02.
|
|||
|
|
|
|||
|
|
## Related
|
|||
|
|
|
|||
|
|
- ADR-0001: Go implementation (matches Topaz's language).
|
|||
|
|
- ADR-0002: Rego-in-Markdown policy format (matches Topaz's policy
|
|||
|
|
language).
|
|||
|
|
- FLEX-WP-0005 T04: Topaz mapping spike.
|
|||
|
|
- FLEX-WP-0004: Delegated PDP and directory adapters.
|