tegwick
80ffe729d4
GH-DEC-2026-017: the validator admitted {Staff, Engine, Tooling}, built from
section 4's catalog rows, and rejected Taxonomy, which section 3.1 defines.
railiance-master was conforming; the validator was the divergent artifact.
Now four tokens, ASCII case folded, section 4's spelling canonical, INTENT.md
governing while form disagreements are still reported, and every run states
its scope (section 11 binds section 4; volunteers are not non-conformances).
Also fixes the survey silently dropping audit-core's layer.yaml by decoding
peers into flex-auth's own struct.
GH-DEC-2026-018: flex-auth is a section 4 source of evidence. G2 closes as a
question and reopens as a dated gap (review 2026-10-19). cadence.yaml
publishes the per-event-class inventory: deny, redact, not_applicable and
audit_only rare load-bearing (heartbeat and reconciliation, rate forbidden);
allow volume load-bearing (expected-rate and reconciliation). INTENT.md
declares source_of_evidence and names it; tests assert both. Delivery is
FLEX-WP-0031.
FLEX-DEC-2026-015: resource.system follows the runtime, not the repository,
answering ops-warden's WARDEN-IN-0003.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Assistant: claude-code
Assistant-Model: opus
Assistant-Process: 63291@bnt-lap001
Assistant-Session: 8bd77868-ca68-4f49-bb1e-d539ecc0d703
349 lines
18 KiB
Markdown
349 lines
18 KiB
Markdown
# flex-auth Scope
|
|
|
|
## One-liner
|
|
|
|
flex-auth is a policy-as-code authorization registry and decision engine for
|
|
NetKingdom-aligned systems. Under the NetKingdom Security Layer Model
|
|
(declared 2026-08-29) it is **Engine / PDP** — the estate's only policy decision
|
|
point.
|
|
|
|
## Core Idea
|
|
|
|
flex-auth turns verified identity claims, resource manifests, relationship
|
|
facts, policy packages, and request context into inspectable authorization
|
|
decisions. It is intentionally separate from identity providers and from the
|
|
applications that enforce decisions.
|
|
|
|
The product should start as a useful standalone local authorization system,
|
|
then grow into delegated mode where Topaz, OpenFGA, SpiceDB, OPA, Cedar,
|
|
Keycloak Authorization Services, Entra, Graph, SCIM, LDAP, and similar systems
|
|
can be coordinated behind a stable flex-auth API.
|
|
|
|
## In Scope
|
|
|
|
- Protected-system registration.
|
|
- Resource namespaces, resource hierarchy, and action vocabularies.
|
|
- Subject, group, team, tenant, role, and service-account records needed for
|
|
authorization.
|
|
- Relationship facts and inherited access.
|
|
- Versioned policy packages with metadata, fixtures, validation, tests, and
|
|
activation state.
|
|
- Deterministic check, batch-check, list-allowed, explain, and decision-record
|
|
capabilities.
|
|
- Local decision logs with policy version and provenance.
|
|
- CLI and service entry points for local development and integration tests.
|
|
- Markitect as the first concrete protected-system consumer.
|
|
- Delegated PDP and directory adapter boundaries after the standalone core is
|
|
stable.
|
|
- The **decision-record schema**, published as flex-auth's own contract
|
|
(Security Layer Model §17).
|
|
- The **canonical request digest** as the published replay test for consumers
|
|
(§6.4.2) — `binding.submitted_request_digest`, over the request as sent.
|
|
`request_digest` is over the *enriched* request and is flex-auth's own
|
|
audit-replay identity, not a consumer check (`FLEX-DEC-2026-012`).
|
|
- **Decision lifetimes** on every allow, and **revocation visibility deadlines
|
|
stated per input class** (§9.7).
|
|
- **Registry-snapshot provenance**, so a decision that turned on registry
|
|
content is replayable from its own record (§6.1, §9.7.2).
|
|
|
|
## Out of Scope
|
|
|
|
- Acting as an identity provider.
|
|
- Replacing key-cape, NetKingdom SSO, Keycloak, Entra, or other identity
|
|
systems.
|
|
- Owning login, MFA, PKCE, token issuance, token lifecycle, or canonical
|
|
identity profile behavior.
|
|
- Embedding protected-system enforcement logic inside flex-auth.
|
|
- Making Markitect-specific assumptions part of the generic authorization
|
|
model.
|
|
- Forcing a single PDP backend or directory provider.
|
|
- Hiding policy behavior behind opaque administrative toggles.
|
|
- Expressing fail-open. When flex-auth is unreachable there is no evaluator in
|
|
the path; the residue is the consumer's declared stance (§9.3).
|
|
- Owning enforcement. A PEP's obligations under §6.4 are the consumer's,
|
|
including its published stance map.
|
|
- Owning the approval object, its storage, or its lifecycle — that is
|
|
`approval-engine`'s (§9.4). flex-auth validates approvals as input claims and
|
|
never mutates them.
|
|
- Owning evidence of authentication or assurance. flex-auth consumes assurance
|
|
claims and never redefines them; it owns evidence of the decision
|
|
(`FLEX-DEC-2026-002`, recorded as declined in §13).
|
|
- Authoring security doctrine. gate-house owns invariants, authority ceilings,
|
|
operating modes, and the authority context flex-auth consumes as claims.
|
|
|
|
## Relevant When
|
|
|
|
- A protected system needs resource-specific authorization decisions.
|
|
- A team needs policy-as-code packages that can be reviewed, tested, versioned,
|
|
and explained.
|
|
- Authorization must combine identity claims, groups, roles, tenants,
|
|
relationships, context, and resource metadata.
|
|
- A local development workflow needs deterministic authorization behavior
|
|
before enterprise PDP integrations exist.
|
|
- Markitect resources need central authorization decisions and durable audit
|
|
records.
|
|
- A delegated backend needs to be introduced without changing the
|
|
protected-system-facing API.
|
|
|
|
## Not Relevant When
|
|
|
|
- The task is only about authentication, login, token issuance, or MFA.
|
|
- The desired outcome can be handled by coarse identity-provider roles alone.
|
|
- The protected system only needs local development labels and no central
|
|
policy administration.
|
|
- A team is choosing identity-provider configuration rather than
|
|
resource-specific authorization.
|
|
|
|
## Current State
|
|
|
|
The standalone core is implemented and **all seven baseline workplans
|
|
(`FLEX-WP-0001` through `FLEX-WP-0007`) are complete.** 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, audit, Markitect, and
|
|
delegated-adapter internals. The standalone policy-as-code core (`FLEX-WP-0002`),
|
|
Markitect consumer integration (`FLEX-WP-0003`, manifest ingest, decisions, and
|
|
fixtures), and the delegated PDP/directory adapter shapes (`FLEX-WP-0004`,
|
|
Topaz/OpenFGA/OPA/Cedar/Keycloak/Entra tradeoffs documented with at least one
|
|
controlled adapter shape) all landed in May 2026.
|
|
|
|
Standalone decisions include a structured `binding` containing the normalized
|
|
subject, action, resource, context, and a full request digest. This makes the
|
|
execute-time decision contract inspectable without parsing reason or diagnostic
|
|
prose. Durable human approval lifecycle, supersession, and authenticated
|
|
multi-approver evidence are `approval-engine` responsibilities; the proposed
|
|
cross-system object is documented in
|
|
`schemas/action_authorization.schema.json` and is not yet a deployed
|
|
`approval-engine` endpoint.
|
|
|
|
**secrets-engine is a shipped consumer as of 2026-09-06** (`FLEX-WP-0021`):
|
|
`secrets-engine.catalog-lane.lifecycle` v2 over `resource.type:
|
|
secret-catalog-lane`, twelve actions delivered by secrets-engine rather than
|
|
inferred, `destroy` gated on a dual-control approval claim, and a dedicated
|
|
`flex-auth-secrets-engine` pin at
|
|
`http://flex-auth-secrets-engine.flex-auth.svc.cluster.local.:8080` —
|
|
trailing dot required, in-cluster only — with `callerAuth.mode: warn`. Adoption is not complete: secrets-engine is a CLI
|
|
rather than a workload, and the pin's default-deny ingress admits a pod, so an
|
|
operator-run access path is still undecided.
|
|
|
|
v1 of that package **had no tenant rule and allowed a foreign tenant**; v2
|
|
supersedes rather than amends it, because a fail-open correction must be visible
|
|
to a consumer as a version change (`FLEX-DEC-2026-008`). The sweep that finding
|
|
prompted shows `tenant-engine` unscoped on tenant as well, carried by
|
|
`FLEX-WP-0022`.
|
|
|
|
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-0006` published that gate and `FLEX-WP-0007`
|
|
deployed flex-auth as a reachable production runtime for it. The joint
|
|
OpenBao-backed smoke is verified (2026-06-29: vault-backed allow recorded
|
|
`decision:032b096c433ad80c`; TTL-over-max denied `ttl_out_of_bounds` by
|
|
flex-auth before OpenBao). `FLEX-WP-0016` then shipped an independently rollable
|
|
in-cluster ops-warden pin and moved it to `callerAuth.mode: enforce` once
|
|
ops-warden adopted a calling identity (`WARDEN-WP-0031`): anonymous `/v1/check`
|
|
is 401, a token bound to another protected system is 403.
|
|
|
|
Production `policy.enabled` is **deliberately off, and is not coming back as a
|
|
boolean.** ops-warden's `ADR-0009` (2026-08-22, superseding `ADR-0006`) settles it:
|
|
`policy.enabled` is one repo-wide flag, and with `fail_closed: true` it makes
|
|
flex-auth a hard dependency of every `warden sign` — including the SSH
|
|
certificates the ops-bridge tunnels depend on, one of which carries the policy
|
|
call itself. `ADR-0009` retires `policy.enabled` and the global `policy.fail_closed`
|
|
outright and replaces them with a total per-zone stance map in the consumer PEP
|
|
(`ops-warden/pep-stance.yaml`): open for `z0`-`z2` and `unknown`, closed for
|
|
`z3-critical`. That map is the reference shape for the Security Layer Model's
|
|
§6.4 obligation 3. It is no longer the only published one: `secrets-engine`
|
|
published `pep-stance.yaml` (total over catalog stage plus `unknown`, runtime-read
|
|
and test-pinned), so §13.1's register grew past the single row the standard
|
|
recorded as itself the finding. It now carries **five** — `ops-warden`,
|
|
`user-engine`, `tenant-engine`, `secrets-engine`, and `ops-mason` with no map at
|
|
all — two of them marked non-conformant. flex-auth reviewed the pair in
|
|
`docs/stance-register-review.md` — the first exercise of the aggregate-divergence
|
|
capability it claimed on 2026-08-29 — and found that the two maps take opposite
|
|
stances on `unknown` (`fail_open` vs `fail_closed`) and scope on different axes
|
|
(security-zone vs catalog-stage), which makes the rows conformant but not
|
|
comparable.
|
|
|
|
flex-auth reviewed the zone model as the PDP on 2026-08-19 and holds one
|
|
boundary: zone **membership** compiles into
|
|
the registry snapshot flex-auth already consumes (no schema change needed), while
|
|
per-zone **stance** belongs in the versioned policy package, because registry
|
|
content is absent from decision provenance. **Fail-open is not expressible by a
|
|
PDP at all** and stays a consumer-side setting. The enforcing pins stay
|
|
enforcing regardless — an enforcing pin with no enforcing consumer still turns
|
|
the anonymous path into a 401 rather than a decision.
|
|
|
|
**Layer position (declared 2026-08-29).** flex-auth is **Engine / PDP** under
|
|
the NetKingdom Security Layer Model, declared machine-readably in `INTENT.md`
|
|
frontmatter per §11. That declaration deliberately carries **no standard
|
|
version**: a layer is a boundary and does not change when the text is amended,
|
|
which is the distinction the standard itself draws when it says assent is *"to a
|
|
BOUNDARY, given at the version named. It is not assent to the current text."* The
|
|
absence is enforced by test in `internal/layer`, and raised to `gate-house` as
|
|
`FLEX-WP-0030` B4 in case §11 should say so generally.
|
|
|
|
Version-scoped state therefore lives in
|
|
`docs/conformance/security-layer-conformance.md` — a derived artifact that names
|
|
what it derives from and the version it was derived at, as §11 requires. It
|
|
carries the assent history (v0.4 `FLEX-DEC-2026-002`, v0.6 `FLEX-DEC-2026-003`,
|
|
v0.8 `FLEX-DEC-2026-011`) and the gap table below.
|
|
|
|
Findings of flex-auth's adopted into the standard: §9.3's two-owner split for
|
|
degraded mode, §6.4.2 scoped to the decision's own binding with the canonical
|
|
request digest as its mechanical test and negative caching ruled explicitly,
|
|
§9.7.2 split by role, §17 moving the decision-record schema to flex-auth, and
|
|
four more in the v0.8 round (`FLEX-DEC-2026-011`), of which F1 — that a decision
|
|
must be *attributable* to flex-auth and that a digest comparison does not
|
|
discharge it — was the finding of the round.
|
|
|
|
Conformance state is **not conforming on §11, held as three declared gaps**,
|
|
each with an owner and a route rather than a sentence. G2 is the non-conformance
|
|
(`GH-DEC-2026-018`):
|
|
|
|
| # | Gap | Owner | Route |
|
|
| --- | --- | --- | --- |
|
|
| G1 | Registry-snapshot digest absent from decision provenance (§9.7.2 conformance prerequisite) | `flex-auth` | `FLEX-WP-0019` |
|
|
| G2 | Emission guarantee declared per event class (`cadence.yaml`) but not delivered — no outbox, heartbeat, or audit-core sender registration. Review 2026-10-19 | `flex-auth` | `FLEX-WP-0031` |
|
|
| G3 | Published stance-register review stale — written at two register rows, §13.1 now carries five | `flex-auth` | `FLEX-WP-0029` |
|
|
|
|
G2 was held open as a question — is flex-auth a §4 *source of evidence*, or only
|
|
the producer of an artifact `audit-core` sources? — and `gate-house` ruled it
|
|
against flex-auth on 2026-09-21: a custodian is never the source of what it
|
|
holds. `audit-core` reached the same answer on its own authority. The
|
|
classification is flex-auth's and is published; the delivery is the gap, and it
|
|
fails closed (a missed detection, never a manufactured permission).
|
|
|
|
**Boundaries review (2026-09-21).** `FLEX-WP-0030` reviews flex-auth's boundary
|
|
against every security-relevant counterpart and raises five items: inconsistent
|
|
`layer:` casing across the estate against §11's mechanical-checkability claim
|
|
(B1); four security-relevant repositories with no layer declaration at all —
|
|
`gate-house`, `key-cape`, `ops-mason`, `net-kingdom` — of which `key-cape` is the
|
|
identity source whose claims flex-auth consumes as normative input, making that
|
|
boundary asserted from one side only (B2); G2 above (B3); B4; and canon naming
|
|
`access-engine` while the repository still answers to `flex-auth` (B5).
|
|
|
|
State Hub integration is present through:
|
|
|
|
- `.custodian-brief.md`
|
|
- `state_hub_workstream_id` fields in workplans
|
|
- `state_hub_task_id` fields in task blocks
|
|
- active State Hub dispatch for the `flex-auth` repo
|
|
|
|
## How It Fits
|
|
|
|
flex-auth sits between identity and protected systems:
|
|
|
|
```text
|
|
key-cape / NetKingdom SSO
|
|
-> verified identity claims
|
|
-> flex-auth authorization registry and policy decisions
|
|
-> protected systems such as Markitect
|
|
```
|
|
|
|
Identity systems establish who the caller is and provide coarse claims.
|
|
flex-auth decides what that caller can do to a specific resource under a
|
|
specific context. Protected systems enforce the decision and keep their own
|
|
local diagnostics.
|
|
|
|
## Terminology
|
|
|
|
- **Subject:** Human, service account, group, team, tenant, role, or emergency
|
|
principal.
|
|
- **Resource:** Protected object registered by a system.
|
|
- **Namespace:** Resource type and ownership boundary.
|
|
- **Action:** Operation requested against a resource.
|
|
- **Context:** Request, environment, assurance, workflow, or runtime
|
|
attributes.
|
|
- **Policy package:** Versioned policy-as-code bundle with metadata and tests.
|
|
- **Relationship fact:** Subject-resource or resource-resource relation.
|
|
- **Decision:** Allow, deny, redact, audit-only, or not-applicable outcome with
|
|
reason and provenance.
|
|
- **PDP:** Policy decision point, either flex-auth standalone logic or a
|
|
delegated backend.
|
|
- **PEP:** Policy enforcement point in the protected system.
|
|
|
|
## Related / Overlapping
|
|
|
|
- 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`).
|
|
- 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 **knowledge-pipeline** consumer. Integration is complete on
|
|
the flex-auth side (`FLEX-WP-0003` — resource-manifest ingest, Markitect-
|
|
compatible decisions, and fixtures); a live Markitect runtime calling the gate
|
|
in production is the next consumer milestone after ops-warden.
|
|
- 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
|
|
conversion.
|
|
- OpenFGA and SpiceDB: candidate relationship authorization backends.
|
|
- OPA and Cedar: candidate rule and typed-policy engines.
|
|
- Keycloak Authorization Services: adapter path for Keycloak-centric
|
|
deployments. Default architecture is "Keycloak as SSO only,
|
|
flex-auth owns authorization"; Keycloak AuthZ is one optional
|
|
delegated PDP.
|
|
- Entra, Graph, SCIM, LDAP, and Keycloak APIs: directory and group resolver
|
|
sources.
|
|
|
|
## Disjoint From
|
|
|
|
- **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.
|
|
|
|
## Provided Capabilities
|
|
|
|
```capability
|
|
type: orientation
|
|
title: Agent orientation
|
|
status: current
|
|
description: Repo intent, boundaries, research, workplan map, and State Hub agent brief are available for new coding agents.
|
|
```
|
|
|
|
```capability
|
|
type: workplan
|
|
title: Standalone policy core plan
|
|
status: current
|
|
description: Workplan for schemas, local registry, policy packages, check APIs, list/explain, decision log, CLI/service skeleton, tests, and examples.
|
|
```
|
|
|
|
```capability
|
|
type: workplan
|
|
title: Markitect consumer integration plan
|
|
status: current
|
|
description: Workplan for Markitect resource namespace, manifest import, action vocabulary, check fixtures, contract tests, and integration flow.
|
|
```
|
|
|
|
```capability
|
|
type: workplan
|
|
title: Delegated adapter plan
|
|
status: current
|
|
description: Workplan for Topaz evaluation, relationship PDP adapters, rule PDP adapters, Keycloak AuthZ path, directory resolvers, and operations docs.
|
|
```
|
|
|
|
```capability
|
|
type: contract
|
|
title: Decision-record contract
|
|
status: current
|
|
description: Published decision-record schema, the submitted-request digest as the replay test for consumers, request-enrichment precedence, and decision provenance — flex-auth's own contract under the Security Layer Model section 17.
|
|
```
|
|
|
|
```capability
|
|
type: orientation
|
|
title: Layer declaration
|
|
status: current
|
|
description: Machine-readable Engine/PDP boundary declaration in INTENT.md frontmatter, carrying no standard version by design, with version-stamped conformance state and three declared gaps (G2 a ruled §11 non-conformance) and a per-event-class emission declaration in cadence.yaml, per docs/conformance/security-layer-conformance.md, per Security Layer Model section 11.
|
|
```
|