generated from coulomb/repo-seed
Land foundations: assessment, ADR-001/002/003, FLEX-WP-0005, Go skeleton
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>
This commit is contained in:
142
docs/pre-implementation-assessment.md
Normal file
142
docs/pre-implementation-assessment.md
Normal file
@@ -0,0 +1,142 @@
|
||||
# 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`
|
||||
Reference in New Issue
Block a user