# 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`