flex-auth/docs/pre-implementation-assessment.md

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

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