generated from coulomb/repo-seed
tegwick
55120ec20a
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>
84 lines
3.6 KiB
Markdown
84 lines
3.6 KiB
Markdown
# 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:**
|
|
|
|
```text
|
|
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.
|
|
|
|
## Related
|
|
|
|
- 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).
|