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 as currently stated is `gate-house/INTENT.md` § "Where Gate House Sits";
> it is ruled to become a `net-kingdom/canon/standards/` standard, not yet written.
>
> 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.** The largest adaptation of the review. (1) **Rename to `access-engine`** — ruled, with sequence: reframe this INTENT first, rename second as a governed migration, since the rename touches `FLEX-WP` prefix ownership, State Hub identifiers, ops-warden's tables, zone-engine's binding boundary text, and secrets-engine integrations. `auth-engine` was rejected because key-cape owns authentication and `auth-` keeps the ambiguity. (2) **Drop the "control plane" self-description** — that is Staff vocabulary for an Engine-layer repository. (3) **Split policy authoring from policy evaluation**: authoring, governing, and versioning policy is Staff work (gate-house); evaluating it deterministically and in-path is this repository's, and stays exclusively so. This is the constructive resolution of the `FLEX-WP-0017` overlap — gate-house designs the approval contract, access-engine validates approvals at decision time. (4) Consume gate-house's **authority context** (principal / actor / runtime identity / mandate / operating mode) as input claims. (5) Record the demarcation: **ops-warden and ops-mason own access lanes; access-engine owns access rules.**
>
> *This note records what should change. The body below is not yet adapted.*

> 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 control plane 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 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 Authorization

- Protected-system registration.
- Resource namespaces and resource hierarchy.
- Canonical action vocabulary.
- Policy-as-code packages, 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.

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

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