From b4520bd731f8bbcd69dc6a5d70ceb3ce19385ae9 Mon Sep 17 00:00:00 2001 From: tegwick Date: Sat, 27 Jun 2026 20:37:07 +0200 Subject: [PATCH] docs(intent/scope): align with ops-warden as first shipped consumer ops-warden's SSH signing policy gate (FLEX-WP-0006 finished, FLEX-WP-0007 deploying) makes it flex-auth's first shipped protected-system consumer. Update the intent baseline to match the implemented reality: - SCOPE Current State: standalone Go core + /v1/check is implemented; FLEX-WP-0001/0005/0006 complete, 0007 blocked only on T4 VAULT_TOKEN. - SCOPE Related/Overlapping + Disjoint From: ops-warden is now a consumer, not merely disjoint; the once-hypothetical "agt as flex-auth subject" flow is realized through the signing gate. Disjointness narrowed to the identity surface (warden issues certs, flex-auth never does). - INTENT Consumer Patterns: lead with the shipped action-gate shape (ops-warden), keep Markitect as the planned knowledge-pipeline consumer. Co-Authored-By: Claude Opus 4.8 --- INTENT.md | 29 +++++++++++++++++++++++++---- SCOPE.md | 48 ++++++++++++++++++++++++++++++++---------------- 2 files changed, 57 insertions(+), 20 deletions(-) diff --git a/INTENT.md b/INTENT.md index 4320cdf..8640a27 100644 --- a/INTENT.md +++ b/INTENT.md @@ -149,9 +149,29 @@ adopting their models as its own: Flex-auth remains the stable control plane even when the backend changes. -## First Consumer Pattern +## Consumer Patterns -The first concrete consumer is a knowledge and document management pipeline: +Two consumer shapes drive flex-auth, and the first one to ship deliberately +is not a document pipeline — proving the control plane stays generic. + +**First shipped consumer — an action gate (ops-warden SSH signing).** A +protected system asks flex-auth a single "may this actor perform this action +now?" question before doing irreversible work: + +- it registers a protected system, a resource type (`ssh-certificate`), and an + action (`sign`) +- it sends one policy check per request, passing subject, resource, and + context (actor type, principals, TTL, key fingerprint) +- it enforces the allow/deny decision and records the decision id for audit +- flex-auth owns the policy and durable decision log; the protected system + keeps custody of its own keys and secrets + +This first consumer validated that flex-auth's resource/action/context model, +`POST /v1/check` contract, and decision envelope work for a non-document, +high-stakes gate without any consumer-specific routes. + +**First knowledge-pipeline consumer (planned) — a document and knowledge +pipeline (Markitect):** - it registers knowledge bases, repositories, documents, sections, context packages, workflow artifacts, and exports @@ -159,8 +179,9 @@ The first concrete consumer is a knowledge and document management pipeline: - it can redact or drop results based on decisions - flex-auth owns central policy administration and durable audit -This first consumer should shape flex-auth around real document and knowledge -pipelines without making the policy service consumer-specific. +Together these shape flex-auth around real authorization needs — both +point-in-time action gates and result-filtering pipelines — without making the +policy service consumer-specific. ## Non-Goals diff --git a/SCOPE.md b/SCOPE.md index c12180b..5314da2 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -72,15 +72,22 @@ can be coordinated behind a stable flex-auth API. ## Current State -The repository contains the intent baseline, authorization landscape -research, initial workplans, and the pre-implementation assessment and -ADR set produced on 2026-05-15. `FLEX-WP-0001` is complete. Implementation -now proceeds through `FLEX-WP-0005 Foundations and Topaz Alignment` — -which lands the Go skeleton, pins the `FlexAuthResourceManifest` schema, -runs the Topaz mapping spike, and records ADR-001/002/003 — before the -standalone policy-as-code core in `FLEX-WP-0002`. Markitect consumer -integration and delegated PDP/directory adapters are planned after the -core contracts stabilize. +The standalone core is implemented. The repository carries the intent +baseline, authorization landscape research, ADR set, and a working Go +service (`cmd/flex-auth`) with `validate`, `load-registry`, `serve`, and +`POST /v1/check` plus registry, policy, decision, and audit internals. +`FLEX-WP-0001`, `FLEX-WP-0005` (foundations and Topaz alignment), and +`FLEX-WP-0006` (the ops-warden SSH signing policy gate) are complete. + +The **first shipped protected-system consumer is ops-warden**: its opt-in +pre-sign gate calls `POST /v1/check` for `resource.type: ssh-certificate`, +`action: sign` decisions (`examples/ops-warden/`, policy package, allow/deny +fixtures, and tests). `FLEX-WP-0007` deploys flex-auth as a reachable +production runtime for that gate; it is `blocked` only on T4 — the joint +OpenBao-backed smoke awaiting a refreshed scoped `VAULT_TOKEN` — with all +repo-side artifacts already published. Markitect consumer integration +(`FLEX-WP-0003`) and delegated PDP/directory adapters (`FLEX-WP-0004`) +remain planned on top of the stable core contracts. State Hub integration is present through: @@ -127,7 +134,15 @@ local diagnostics. - key-cape / NetKingdom SSO: identity source and coarse claims provider; flex-auth consumes the **NetKingdom IAM Profile** (`~/net-kingdom/canon/standards/iam-profile_v0.2.md`). -- Markitect: first protected-system consumer and policy enforcement point. +- ops-warden: first **shipped** protected-system consumer. Its opt-in + pre-sign gate calls flex-auth for `ssh-certificate` / `sign` decisions + before issuing a short-lived SSH certificate (`FLEX-WP-0006`, + `FLEX-WP-0007`). ops-warden owns the SSH CA, OpenBao signing, and actor + inventory; flex-auth owns the policy decision. ops-warden's routing + charter names flex-auth as the owner of every "may I perform action X?" + question. +- Markitect: first planned **knowledge-pipeline** consumer and policy + enforcement point (`FLEX-WP-0003`). - Topaz: aligned evaluator. Per ADR-003 the standalone core is shaped to match Topaz's Rego + directory model from day one; the Topaz adapter in `FLEX-WP-0004` is therefore a small step rather than a @@ -143,12 +158,13 @@ local diagnostics. ## Disjoint From -- **ops-warden** signs short-lived SSH certificates for ops actors - (`adm`/`agt`/`atm`). That is a separate identity surface — SSH certs, - not OIDC subjects — and ops-warden disclaims being a resource-policy - engine. flex-auth and ops-warden therefore do not overlap. (A future - flow could surface an `agt` actor as a flex-auth subject; nothing in - the current design requires it.) +- **ops-warden** is a flex-auth *consumer*, not an overlap (see Related / + Overlapping). The two remain disjoint on **identity surface**: ops-warden + issues SSH certificates for ops actors (`adm`/`agt`/`atm`) and is not a + resource-policy engine; flex-auth decides whether a given sign request is + allowed and never issues certificates. The once-hypothetical flow of + surfacing an `agt` actor as a flex-auth subject is now realized through + the signing policy gate. - **ops-bridge** owns SSH reverse-tunnel connectivity and explicitly disclaims being a credential authority or policy engine. No overlap.