tegwick
55120ec20a
Pre-implementation assessment and boundary review
(docs/pre-implementation-assessment.md) lead to three ADRs:
- ADR-001 Go + repo skeleton
- ADR-002 Rego-in-Markdown policy package format
- ADR-003 Topaz-aligned MVP (Topaz spike moves into foundations)
New workplan FLEX-WP-0005 (Foundations and Topaz Alignment) is inserted
between WP-0001 (done) and WP-0002 (core). WP-0002 pins Rego-in-Markdown
for P2.3; WP-0004 P4.1 refocused from Topaz evaluation to Topaz adapter.
Go skeleton at repo root: cmd/flex-auth + internal/{registry,policy,
decision,audit,adapters} + pkg/api + Makefile + .golangci.yml + GitHub
Actions CI. make ci green locally; bin/flex-auth --version works.
INTENT/SCOPE cite the NetKingdom IAM Profile and add the ops-warden /
ops-bridge disjoint-surface clarifications.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
3.8 KiB
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.