generated from coulomb/repo-seed
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>
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.
|