flex-auth/INTENT.md

# Flex-Auth Intent

> **NetKingdom layering review — 2026-08-28.** This repository's role was reviewed
> against the NetKingdom IT-security layer model: **Taxonomy → Tooling → Engines →
> Staff**, layered by determinism and by the kind of artifact each layer produces.
> Findings and the argument behind them:
> `gate-house/history/2026-08-28-security-layer-model-and-gate-house-recut.md`.
> The model is `net-kingdom/canon/standards/security-layer-model_v0.1.md` (proposed),
> ratified by `gate-house/decisions/decisions.md` GH-DEC-2026-001.
>
> The layer rule that binds every repository: **Staff never touches tooling
> directly. It acts only through engine APIs.**
>
> **This repository is Engine — and the only policy decision point in NetKingdom.**
> Reframed on 2026-08-28 per `gate-house/decisions/decisions.md` GH-DEC-2026-001:
> "control plane" dropped as Staff vocabulary, the layer and the exclusive
> decision-point role stated, policy authoring separated from policy evaluation,
> gate-house's authority context adopted as input claims, and the access
> lane/rule demarcation recorded.
>
> *Reframe applied. **Assent given on 2026-08-28** — `decisions/decisions.md`
> FLEX-DEC-2026-001, answering intake `FLEX-IN-0001`: flex-auth assents to the Engine
> framing, to `access-engine` as the ruled name, and to the authoring/evaluation
> split. One item remains: the rename itself, a separate governed migration — it
> touches `FLEX-WP` prefix ownership, State Hub identifiers, ops-warden's routing
> tables, zone-engine's binding boundary text, and secrets-engine integrations —
> and is not authorized by GH-DEC-2026-001. flex-auth adds two conditions on it
> (FLEX-DEC-2026-001 item 2): repository identity and runtime identity rename in
> separate revertible steps, repository first, because the enforcing ops-warden
> pin binds tokens to the protected-system name; and `FLEX-WP` prefix ownership
> stays with the repository.*
>
> **Known non-conformance — registry provenance.** Standard §6 holds that
> compiled data determining an outcome is still deciding, and that provenance
> must stay reconstructable from the decision. `DecisionProvenance` carries the
> evaluator, mode, policy package, policy version, and directory ETag, but no
> digest of the registry snapshot. A decision that turned on registry content
> cannot be replayed from its own provenance. flex-auth accepts this as its own
> gap rather than claiming conformance; until it is closed, outcome-determining
> content belongs in the versioned policy package, not the registry — for
> zone-engine's zone stance, for gate-house's authority ceilings, and for
> everyone else on the same terms.

> This file captures **why this repository exists**, the **direction it is
> moving toward**, and the **kind of system it is meant to become**.
> It is intentionally **aspirational and stable**, not a description of
> current implementation.

## Intent

Flex-auth is a policy-as-code authorization registry and **decision engine**
for organizations that want to grow from simple access rules into
enterprise-grade authorization without giving up clear ownership, local
development ergonomics, or inspectable policy decisions.

It is an **Engine** in the NetKingdom security layer model
(`net-kingdom/canon/standards/security-layer-model_v0.1.md`): a deterministic
API for a modeled concept, where the same authoritative input state yields the
same result. It is deliberately not described as a control plane — that is
Staff-layer vocabulary, and flex-auth is not Staff.

Within NetKingdom it is **the only policy decision point** (standard §6). No
other repository, in any layer, may render or cache an authorization decision.

It is the **authorization layer** in the path from verified identity to
protected resources:

```text
verified identity claims
  -> flex-auth policy-as-code and authorization registry
  -> protected systems and their resources
```

Flex-auth should run usefully on its own, and should also be able to delegate
to or coordinate established authorization engines — relationship/graph
engines, rule and attribute policy engines, and directory systems — without
binding its own model to any one of them.

## Why This Exists

Most organizations start with coarse roles, groups, and application-specific
conditionals. Over time they need richer policy:

- resource hierarchies and inherited access
- project/team/tenant boundaries
- relationship-based authorization
- attribute and context based rules
- emergency/break-glass controls
- policy tests and reviewable changes
- durable decision logs and explainability
- integration with identity, MFA, service accounts, and directory groups

Flex-auth should give those organizations a path that starts small and grows
cleanly instead of forcing an early leap into a large IAM platform or letting
authorization logic sprawl across applications.

## Responsibility Boundary

Flex-auth consumes **verified identity claims** as normative input and never
re-defines them. Identity proves who an actor is and how they were
authenticated; flex-auth decides what that actor is allowed to do.

### The Identity Layer Owns Identity

- Authentication, login, MFA, and token issuance and lifecycle.
- The canonical identity claim contract and required claims.
- Coarse roles, scopes, and assurance claims.

### Flex-Auth Owns the Decision

- **Evaluation — exclusively.** Rendering the decision, in-path, deterministically.
- Protected-system registration.
- Resource namespaces and resource hierarchy.
- Canonical action vocabulary.
- The policy-as-code mechanism: package format, tests, versions, and rollout.
- Mapping enterprise groups, app roles, scopes, tenants, and assurance claims
  into resource-specific authorization.
- Relationship facts and inherited access.
- PDP adapter coordination.
- Decision logging, explanations, and audit export.

### Gate House Owns the Doctrine the Decision Serves

Authoring and governing security doctrine is Staff work. `gate-house` owns the
invariants policy must satisfy, the authority ceilings, the assistant and
autonomous operating modes, and the **authority context** — principal, actor,
runtime identity, tenant, mandate, operating mode — which flex-auth consumes as
input claims alongside verified identity claims.

The division is between *authoring the rules of the game* and *rendering a
result*: gate-house designs the approval contract and the invariants; flex-auth
validates approvals and renders decisions at request time. Neither can do the
other's half. Policy **content** for a given protected system remains authored
by that system's owner, within flex-auth's mechanism and gate-house's doctrine.

Gate House holds no runtime position and never renders a decision. A
deterministic authority boundary inside a non-deterministic layer would violate
the invariant the estate is built on.

One condition follows from that, drawn by flex-auth on review (FLEX-DEC-2026-001):
an authority ceiling that determines an outcome must reach the decision either
as an input claim on the request or as a rule in the versioned policy package,
so that its application is reconstructable from the decision record. A ceiling
that resolves an outcome before evaluation runs has decided early. This is not a
limit on gate-house's authorship — it is what keeps that authorship auditable at
decision time, and it is the same test flex-auth applied to zone-engine's zone
stance and, in the note above, to its own registry.

### Protected Systems Own Enforcement

Applications remain policy enforcement points. They extract resource
metadata, call flex-auth for decisions, enforce allow/deny/redact results,
and emit local diagnostics. They do not own central policy administration.

### Access Lanes Are Not Access Rules

The estate uses "access" for two different things, and the demarcation is
normative (standard §8):

- **ops-warden and ops-mason own access lanes** — how a worker reaches a host:
  routes, tunnels, SSH certificates, credential lanes.
- **flex-auth owns access rules** — whether an actor may act at all.

A lane delivers someone to the door. This repository decides whether the door
opens. Neither substitutes for the other, and neither owns the other's word.

## Design Principles

- Policy is code: versioned, reviewed, tested, and explainable.
- Identity is not authorization: identity claims are inputs, not final
  decisions.
- Start standalone, scale outward: a local flex-auth deployment should be
  useful before any external policy engine integration is available.
- Backend-neutral core: flex-auth has its own resource, action, request,
  decision, and audit vocabulary.
- Pluggable PDPs: relationship, rule, and directory engines are adapters, not
  hard dependencies.
- Fail visibly: denied, redacted, stale, partial, and uncertain decisions must
  produce useful diagnostics.
- Grow into enterprise: the same model should support local dev, small teams,
  and larger enterprise environments.

## First-Class Concepts

- Subject: human, service account, group, team, tenant, emergency principal.
- Resource: protected object registered by a system.
- Namespace: resource type and ownership boundary.
- Action: operation requested on a resource.
- Context: request, environment, assurance, workflow, or runtime attributes.
- Policy package: versioned policy-as-code bundle with tests and metadata.
- Relationship fact: subject-resource or resource-resource relation.
- Decision: allow, deny, redact, audit-only, or not-applicable with reason.
- Audit event: durable decision record with policy version and provenance.

## Initial API Shape

```text
register_system(system_manifest)
register_resource(resource_manifest)
sync_relationships(relationship_manifest)

check(subject, action, resource, context) -> decision
batch_check(subject, action, resources, context) -> decisions
list_allowed(subject, action, resource_type, filters, context) -> resources
explain(decision_id) -> explanation

publish_policy_package(package)
test_policy_package(package, fixtures)
activate_policy_version(policy_id, version)
record_decision(decision)
```

## Standalone Mode

Standalone flex-auth should provide:

- local resource registry
- local subject/group/team registry
- local relationship facts
- policy package validation
- deterministic check and batch-check APIs
- local decision log
- CLI and service mode
- test fixtures for representative identity claims

Standalone mode should be enough for development, smaller deployments, and
integration tests.

## Delegated Mode

Delegated mode should let flex-auth coordinate established systems without
adopting their models as its own:

- relationship/graph engines for relationship-heavy authorization
- rule and attribute policy engines for attribute/rule policies
- directory systems for group resolution
- a local directory plus policy-evaluation engine for self-contained
  delegated setups

Flex-auth remains the stable control plane even when the backend changes.

## Consumer Patterns

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
- it sends policy checks before returning query/search/context results
- it can redact or drop results based on decisions
- flex-auth owns central policy administration and durable audit

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

- Flex-auth is not an identity provider.
- Flex-auth is not a replacement for an identity or SSO system.
- Flex-auth is not a mandatory dependency for every local development use case.
- Flex-auth should not force one PDP backend.
- Flex-auth should not hide policy complexity behind opaque admin toggles.

## Early Work

1. Define the resource/action/decision model.
2. Define policy package structure and test fixtures.
3. Implement standalone registry and check API.
4. Add a first protected-system resource manifest and policy adapter.
5. Evaluate a delegated directory-plus-policy backend.
6. Add relationship-engine and rule-engine adapter spikes.
7. Add identity and enterprise-directory integration examples.