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>
143 lines
7.0 KiB
Markdown
143 lines
7.0 KiB
Markdown
# flex-auth Pre-Implementation Assessment
|
|
|
|
Date: 2026-05-15
|
|
Author: Claude (Opus 4.7) with Bernd
|
|
Status: Accepted — feeds FLEX-WP-0005 Foundations and the refresh of FLEX-WP-0002/0004
|
|
|
|
## Purpose
|
|
|
|
Captures the SWOT and boundary review performed before flex-auth code work
|
|
begins. The conclusions of this assessment are turned into three ADRs
|
|
(`docs/adr/0001`-`0003`) and a new foundations workplan
|
|
(`workplans/FLEX-WP-0005`), which together precede the standalone core
|
|
(`FLEX-WP-0002`).
|
|
|
|
## Overall Verdict
|
|
|
|
The repository is planning-mature and code-blank. INTENT, SCOPE, the PRD,
|
|
the authorization-landscape research note, and the four initial workplans
|
|
are internally consistent and mirrored in the State Hub. `FLEX-WP-0001` is
|
|
done.
|
|
|
|
Starting implementation directly at `FLEX-WP-0002 P2.1` is reasonable in
|
|
shape but premature in detail: several decisions the workplans leave open
|
|
would be made implicitly by the first commit. Those decisions are pulled
|
|
forward into `FLEX-WP-0005` so the standalone core lands on settled
|
|
foundations.
|
|
|
|
## SWOT
|
|
|
|
### Strengths
|
|
|
|
- Ownership boundary stated and repeated consistently:
|
|
- **key-cape / NetKingdom SSO** owns identity.
|
|
- **flex-auth** owns authorization.
|
|
- **protected systems** own enforcement.
|
|
- Backend-neutral vocabulary commitment: Topaz, OpenFGA, SpiceDB, OPA,
|
|
Cedar, and Keycloak Authorization Services are framed as adapters, not
|
|
the product.
|
|
- Concrete first consumer (Markitect) with its side already in flight
|
|
(`MKTT-WP-0014`).
|
|
- Standalone-first mode keeps flex-auth useful before any enterprise PDP
|
|
is wired in.
|
|
- Hard problems named, not papered over: group overage, directory
|
|
freshness, fail-open vs fail-closed, stale/partial/uncertain decisions,
|
|
explain APIs, audit-only versus deny.
|
|
- State Hub integration in place from day one (workstream and task IDs
|
|
in workplan frontmatter, custodian brief committed, dispatch active).
|
|
|
|
### Weaknesses
|
|
|
|
- No implementation language or repo skeleton committed.
|
|
- Policy package format is described as "a simple declarative rule format
|
|
with room for OPA/Rego, Cedar, and Topaz later" — central artefact, but
|
|
unpinned.
|
|
- No ADRs. `net-kingdom/DECISIONS.md` and the key-cape spec habit are not
|
|
mirrored here yet.
|
|
- The `FlexAuthResourceManifest` is referenced as already implemented on
|
|
the Markitect side without being pinned in this repo. Cross-repo
|
|
contract drift risk.
|
|
- NetKingdom IAM Profile
|
|
(`~/the-custodian/canon/standards/iam-profile_v0.1.md`) is only cited
|
|
at the bottom of the research note — it is the upstream identity
|
|
contract flex-auth consumes and deserves first-class citation.
|
|
- No project skeleton, Makefile, lint, CI, or SBOM yet.
|
|
- Emergency principal / break-glass listed as a first-class subject type
|
|
with no mechanics described.
|
|
|
|
### Opportunities
|
|
|
|
- Markitect is aligned and waiting. Tight feedback loop available.
|
|
- `explain(decision_id)` is a real differentiator versus Topaz, Cerbos,
|
|
and OPA in isolation. Literate, reviewable policy packages amplify the
|
|
same lever.
|
|
- CLI-first standalone mode can ship usefully across NetKingdom repos
|
|
early, before service mode lands.
|
|
- Register flex-auth as a State Hub capability with extension points so
|
|
Markitect and later consumers discover it natively.
|
|
|
|
### Threats / Risks
|
|
|
|
- **Thin-wrapper-around-Topaz trap.** Topaz already combines OPA/Rego,
|
|
local directory, and relations. If the standalone core reimplements
|
|
60% of Topaz badly and then adapts to Topaz anyway, the abstraction
|
|
earns nothing. The escape is to make the *registry + audit + explain +
|
|
multi-consumer* surface the actual product, and to align the
|
|
standalone evaluator with Rego from day one so the later Topaz
|
|
adapter is a small step.
|
|
- Markitect-side manifest exists; flex-auth has not pinned it. Easy to
|
|
lock in the wrong shape.
|
|
- Schedule coupling: `FLEX-WP-0003` is blocked on `0002`. Every week of
|
|
core slippage is a week Markitect waits.
|
|
- "Yet another authz layer" perception if a bespoke rules format ships
|
|
before the Topaz/Rego direction is recorded.
|
|
|
|
## Boundary Review
|
|
|
|
| Repo | Owns | Overlap with flex-auth | Verdict |
|
|
| --- | --- | --- | --- |
|
|
| `key-cape` | OIDC/PKCE, MFA, token lifecycle, NetKingdom IAM Profile impl, coarse roles and scopes | flex-auth consumes verified claims as inputs; coarse roles live in key-cape, resource-specific decisions in flex-auth | Clean. IAM Profile citation made explicit. |
|
|
| `net-kingdom` | Security core, Keycloak (heavy mode), IAM Profile spec, canon | Keycloak Authorization Services is itself a PDP. flex-auth's research recommends "Keycloak as SSO only, flex-auth owns authorization" as the canonical pattern, with Keycloak AuthZ available as one adapter. | Pinned in ADR-003 / FLEX-WP-0004. Not a boundary problem, a recorded decision. |
|
|
| `ops-bridge` | SSH reverse tunnels, connectivity | Disclaims being a credential authority or policy engine. | No overlap. |
|
|
| `ops-warden` | SSH cert CA for `adm`/`agt`/`atm` actors; short-lived SSH certificates | Different identity universe (SSH actors, not OIDC subjects). An `agt` authenticated via warden SSH cert may later appear as a flex-auth subject in some flow, but the two surfaces do not collide. | No overlap. Boundary line added to SCOPE.md. |
|
|
|
|
## Refinements Adopted
|
|
|
|
1. **ADR-001** — Implementation language & repo skeleton: Go, aligned with
|
|
key-cape's vindicated language decision.
|
|
2. **ADR-002** — Policy-package format: Rego-in-Markdown, from day one.
|
|
Literate policy packages co-locate intent, rules, and tests.
|
|
3. **ADR-003** — MVP backend alignment: shape the standalone core to be
|
|
Rego/Topaz-aligned so the later Topaz adapter is a small step.
|
|
4. **FLEX-WP-0005 Foundations** is inserted between `0001` (done) and
|
|
`0002` (core). It performs the Topaz spike *before* the core's policy
|
|
loader and check API are written, pins the resource manifest schema,
|
|
and lands the repo skeleton.
|
|
5. **INTENT/SCOPE** cite the NetKingdom IAM Profile explicitly and record
|
|
the ops-warden boundary.
|
|
|
|
## Sequencing After Refinement
|
|
|
|
```text
|
|
FLEX-WP-0001 done Repo intent and authorization-landscape baseline
|
|
FLEX-WP-0005 todo P0 Foundations and Topaz alignment (ADRs, skeleton,
|
|
spike, manifest pinning)
|
|
FLEX-WP-0002 blocked Standalone policy-as-code core, Rego-in-Markdown
|
|
FLEX-WP-0003 blocked Markitect consumer integration
|
|
FLEX-WP-0004 blocked Delegated PDP and directory adapters (Topaz
|
|
evaluation now in 0005)
|
|
```
|
|
|
|
## Traceability
|
|
|
|
- `INTENT.md`, `SCOPE.md`, `README.md`, `.custodian-brief.md`
|
|
- `docs/ProductRequirementsDocument.md`
|
|
- `docs/flex-auth-authorization-registry-research.md`
|
|
- `docs/workplan-planning-map.md`
|
|
- `docs/adr/0001-implementation-language-and-skeleton.md` *(new)*
|
|
- `docs/adr/0002-rego-in-markdown-policy-format.md` *(new)*
|
|
- `docs/adr/0003-topaz-aligned-mvp.md` *(new)*
|
|
- `workplans/FLEX-WP-0001-…`, `0002-…`, `0003-…`, `0004-…`
|
|
- `workplans/FLEX-WP-0005-foundations-and-topaz-alignment.md` *(new)*
|
|
- NetKingdom IAM Profile: `~/the-custodian/canon/standards/iam-profile_v0.1.md`
|