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:

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

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.