Files

tegwick 55120ec20a 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>

2026-05-16 01:54:44 +02:00

3.6 KiB

Raw Blame History

ADR-0001: Implementation Language and Repo Skeleton

Date: 2026-05-15 Status: Accepted Deciders: Bernd, with assessment from Claude (Opus 4.7) Supersedes: —

Context

flex-auth is a policy-as-code authorization registry and control plane. It must run as a CLI and, later, a service. Its peers in the NetKingdom ecosystem are written in a mix of languages: key-cape is Go, ops-bridge and ops-warden are Python, the State Hub itself is Python. There is a recorded State Hub decision noting that Go was the right call for key-cape because of orchestration-heavy HTTP adapter code, fast iteration, and clean domain boundaries.

flex-auth shares the relevant traits with key-cape: HTTP/gRPC adapters to multiple PDPs and directory backends, latency-sensitive check paths, and a need to ship a single static binary for local-development ergonomics.

Decision

Language: Go.
Module path: github.com/netkingdom/flex-auth (placeholder; adjust if the repo moves under a different GitHub org during publication).
Minimum Go version: matching key-cape at time of skeleton landing.

Repo layout:

cmd/flex-auth/        CLI entrypoint
cmd/flex-authd/       service entrypoint (added when the service layer lands)
internal/registry/    resource / subject / relationship store
internal/policy/      policy package model, Rego evaluation, fixtures
internal/decision/    check, batch_check, list_allowed, explain, decision log
internal/audit/       compact decision-envelope persistence
internal/adapters/    pluggable PDP and directory adapters (later WPs)
pkg/api/              public types and OpenAPI schemas
schemas/              JSON Schema for manifests and envelopes
examples/             runnable example manifests, policies, fixtures
docs/adr/             this ADR series

Build, lint, test: Makefile targets build, test, lint, tidy, sbom. Linting via golangci-lint. Tests via the standard go test ./... plus contract fixtures.
SBOM: generate on each release tag and on make sbom; register via the State Hub ingest_sbom_tool so last_sbom_at stops being null.

Rationale

Aligns with the only language decision in the NetKingdom ecosystem that has already been validated in production (KeyCape v0.1).
Single static binary makes the standalone-first mode trivial to ship for local development across NetKingdom repos.
Strong concurrency primitives suit batch-check and list-allowed paths.
Excellent OPA tooling for Go (open-policy-agent/opa/rego) means the Rego evaluator chosen in ADR-0002 has first-class library support.
Topaz (the target alignment from ADR-0003) is Go-native — adapter work in FLEX-WP-0004 stays in the same language.

Consequences

New flex-auth contributors need Go in their toolchain. Python is still used elsewhere in the ecosystem; cross-repo work that hits the State Hub or ops-bridge must accept the language switch.
The Go decision is reversible while the repo is empty. Once cmd/ and internal/ have been populated by FLEX-WP-0005 T01, reversal becomes expensive — flag any reservations during the skeleton task, not later.

Out of Scope

Database choice (SQLite vs Postgres vs file-backed) is settled in FLEX-WP-0002 T02 and recorded in a later ADR.
Service framework (net/http vs Connect vs gRPC) is deferred to the service-skeleton task in FLEX-WP-0002 T07.

ADR-0002: Rego-in-Markdown policy format.
ADR-0003: Topaz-aligned MVP.
State Hub recorded decision: "Implementation language for KeyCape: Go" (resolved 2026-03-25).

3.6 KiB Raw Blame History