flex-auth/workplans/FLEX-WP-0005-foundations-and-topaz-alignment.md

---
id: FLEX-WP-0005
type: workplan
title: "Foundations and Topaz Alignment"
domain: netkingdom
status: done
owner: flex-auth
topic_slug: flex-auth
planning_priority: P0
planning_order: 15
depends_on_workplans:
  - FLEX-WP-0001
created: "2026-05-15"
updated: "2026-05-15"
state_hub_workstream_id: "e37d42a9-0018-4a67-a672-ff4e9716b338"
---

# FLEX-WP-0005: Foundations and Topaz Alignment

## Purpose

Land the decisions, skeleton, and Topaz mapping that the standalone core
(`FLEX-WP-0002`) needs before its first task can be written without
leaving load-bearing assumptions implicit.

This workplan is inserted between `FLEX-WP-0001` (done) and
`FLEX-WP-0002` (core) following the pre-implementation assessment
captured in `docs/pre-implementation-assessment.md`.

## Sequencing Rationale

- The pre-implementation assessment names a primary threat: the
  "thin-wrapper-around-Topaz" trap. Aligning vocabulary up front is
  cheap; aligning it retroactively is not. The Topaz spike therefore
  moves out of `FLEX-WP-0004` and into this workplan.
- The Markitect `FlexAuthResourceManifest` exists in `MKTT-WP-0014`
  without a flex-auth-side pin. This workplan pins it before `0003`
  starts importing it.
- Project skeleton, lint, build, and SBOM bring the repo to the same
  baseline as the other NetKingdom repos so `0002` can land code rather
  than scaffolding.

## P5.1 - Record ADR-001 / ADR-002 / ADR-003

```task
id: FLEX-WP-0005-T001
status: done
priority: high
state_hub_task_id: "8193a278-a044-4397-a4a8-232104374cdc"
```

Author the three ADRs that close the open decisions identified in the
pre-implementation assessment:

- ADR-001 — Implementation language and repo skeleton (Go).
- ADR-002 — Rego-in-Markdown policy package format.
- ADR-003 — Topaz-aligned MVP.

Each ADR is recorded as a `decision_type=made` event in the State Hub
and linked back from this workplan task.

Exit: the three ADRs exist in `docs/adr/`, are referenced from
`pre-implementation-assessment.md`, and are mirrored as State Hub
decisions.

## P5.2 - Land Go project skeleton

```task
id: FLEX-WP-0005-T002
status: done
priority: high
state_hub_task_id: "8ac73c33-6d36-4963-990d-28b0d1d60947"
```

Establish the repo skeleton described in ADR-001:

- `cmd/flex-auth/` with a minimal `main.go` printing version and exit.
- `internal/` package tree (`registry/`, `policy/`, `decision/`,
  `audit/`, `adapters/`) with package docs and no business logic yet.
- `pkg/api/` with placeholder type definitions for the canonical
  envelopes (filled in by `FLEX-WP-0002 P2.1`).
- `Makefile` targets: `build`, `test`, `lint`, `tidy`, `sbom`, `fmt`.
- `golangci.yml` configuration mirroring key-cape's lint baseline where
  reasonable.
- `go.mod` with the chosen module path and pinned Go version.
- CI configuration (GitHub Actions or equivalent) running
  `make lint test build`.

Exit: `make ci` (vet + lint + test + build) succeeds locally on a fresh
clone; GitHub Actions CI is green. SBOM generation works via
`make sbom` (cyclonedx-gomod), but `ingest_sbom_tool` requires a
non-empty dependency source — that step is deferred to the first task
that adds an external dependency (`FLEX-WP-0002 P2.3`, which pulls in
the OPA Rego library), where it lands as part of the dep-introduction
checklist.

## P5.3 - Pin FlexAuthResourceManifest schema

```task
id: FLEX-WP-0005-T003
status: done
priority: high
state_hub_task_id: "80285e1e-16ec-4f4e-b491-1e79f200219f"
```

Pin the resource-manifest shape that Markitect's `MKTT-WP-0014` already
emits, so `FLEX-WP-0003 P3.2` imports a known shape and Markitect knows
it is producing the right thing.

Steps:

1. Read the Markitect-side emitter and any contract fixtures in
   `markitect-*` repos.
2. Capture the agreed shape as `schemas/resource_manifest.schema.json`
   plus an example in `examples/markitect/resource_manifest.yaml`.
3. Add a Go type in `pkg/api/` matching the schema, with golden tests.
4. Cross-link from `MKTT-WP-0014` (interface change registered through
   the State Hub) so Markitect knows the pin is canonical.

Exit: the schema, example, and Go type are in this repo; an
`interface_change` event is registered with the State Hub naming
flex-auth as the canonical owner of the manifest shape.

## P5.4 - Topaz alignment spike

```task
id: FLEX-WP-0005-T004
status: done
priority: high
state_hub_task_id: "b8a314c3-e98e-4093-bb11-ab8546b8d79b"
```

Spike Topaz to validate the alignment commitment in ADR-003. Produce a
mapping document showing how flex-auth's resource, subject, group,
team, and relationship vocabulary corresponds to Topaz directory objects
and relations, plus how flex-auth policy packages (Rego-in-Markdown)
correspond to Topaz policy modules.

Output:

- `docs/topaz-mapping-spike.md` covering directory objects, relations,
  user/group representation, Rego module shape, decision envelope
  shape, and adapter wire-protocol candidates.
- A small runnable example (`examples/topaz/`) deploying Topaz locally
  via docker-compose and evaluating a fixture package end-to-end.
- A recommendation on whether to embed Topaz's directory schema
  directly in flex-auth's canonical schemas (P2.1) or restate it, with
  trade-offs.

Exit: the mapping document is committed, reviewed, and referenced from
both `FLEX-WP-0002 P2.1` and `FLEX-WP-0004 T001`.

## P5.5 - Cite NetKingdom IAM Profile and pin claim consumption

```task
id: FLEX-WP-0005-T005
status: done
priority: medium
state_hub_task_id: "b31dab7b-e72c-4abe-b6d5-f5875fd0c25a"
```

The NetKingdom IAM Profile
(`~/the-custodian/canon/standards/iam-profile_v0.1.md`) defines the
identity contract flex-auth consumes. Pin the consumption surface:

1. Update `INTENT.md` and `SCOPE.md` to cite the profile as a normative
   upstream.
2. Document required, optional, and tolerated claims in
   `docs/iam-profile-consumption.md`.
3. Add a fixture set under `examples/claims/` showing key-cape
   lightweight-mode and Keycloak heavy-mode claim envelopes that
   flex-auth must accept without code changes.

Exit: a future Rego rule can rely on a documented, stable input shape
for claims.

## P5.6 - Confirm ops-warden boundary

```task
id: FLEX-WP-0005-T006
status: done
priority: low
state_hub_task_id: "dcd45a14-20fc-49d0-b869-08cda85fcbc5"
```

Add a one-paragraph clarification in `SCOPE.md` stating that ops-warden
(SSH cert CA for ops actors) and flex-auth (resource authorization for
protected systems) operate on disjoint identity surfaces, and note the
plausible-but-not-yet-required bridging case (an `agt` actor appearing
as a flex-auth subject in some future flow).

Exit: SCOPE.md has the clarification; no code changes required.

## Exit Criteria

- ADR-001, ADR-002, ADR-003 are committed and recorded in the State
  Hub.
- The Go skeleton compiles, lints, tests, and publishes an SBOM.
- The `FlexAuthResourceManifest` schema is pinned and Markitect is
  notified via a registered interface change.
- The Topaz alignment spike has produced a mapping document and a
  runnable example, both referenced from `FLEX-WP-0002 P2.1`.
- The NetKingdom IAM Profile citation is in place and claim-consumption
  fixtures exist.
- The ops-warden boundary is documented in `SCOPE.md`.

## State Hub Mirror

- This workstream blocks `FLEX-WP-0002`.
- `FLEX-WP-0002` keeps its existing dependency on `FLEX-WP-0001`, but
  gains a new dependency on this workstream.
- `FLEX-WP-0004` loses its Topaz-evaluation dependency on `FLEX-WP-0002`
  for the spike portion (the adapter still depends on the core).