# 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.