From 15155c4c40497a566feda72dae283ec165212b70 Mon Sep 17 00:00:00 2001 From: tegwick Date: Fri, 15 May 2026 23:17:18 +0200 Subject: [PATCH] chore(consistency): sync task status from DB [auto] MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Updated by fix-consistency on 2026-05-15: - FLEX-WP-0005-T002: todo → in_progress --- ...WP-0005-foundations-and-topaz-alignment.md | 209 ++++++++++++++++++ 1 file changed, 209 insertions(+) create mode 100644 workplans/FLEX-WP-0005-foundations-and-topaz-alignment.md diff --git a/workplans/FLEX-WP-0005-foundations-and-topaz-alignment.md b/workplans/FLEX-WP-0005-foundations-and-topaz-alignment.md new file mode 100644 index 0000000..89869d6 --- /dev/null +++ b/workplans/FLEX-WP-0005-foundations-and-topaz-alignment.md @@ -0,0 +1,209 @@ +--- +id: FLEX-WP-0005 +type: workplan +title: "Foundations and Topaz Alignment" +domain: netkingdom +status: todo +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: in_progress +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 lint test build` succeeds locally on a fresh clone; CI is +green; an SBOM is published and ingested via `ingest_sbom_tool` so the +repo's `last_sbom_at` becomes non-null. + +## P5.3 - Pin FlexAuthResourceManifest schema + +```task +id: FLEX-WP-0005-T003 +status: todo +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: todo +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: todo +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: todo +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).