flex-auth/SCOPE.md

# flex-auth Scope

## One-liner

flex-auth is a policy-as-code authorization registry and control plane for
NetKingdom-aligned systems.

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

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

## 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. 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, and audit internals.
`FLEX-WP-0001`, `FLEX-WP-0005` (foundations and Topaz alignment), and
`FLEX-WP-0006` (the ops-warden SSH signing policy gate) are complete.

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-0007` deploys flex-auth as a reachable
production runtime for that gate; it is `blocked` only on T4 — the joint
OpenBao-backed smoke awaiting a refreshed scoped `VAULT_TOKEN` — with all
repo-side artifacts already published. Markitect consumer integration
(`FLEX-WP-0003`) and delegated PDP/directory adapters (`FLEX-WP-0004`)
remain planned on top of the stable core contracts.

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 planned **knowledge-pipeline** consumer and policy
  enforcement point (`FLEX-WP-0003`).
- 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: planned
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: planned
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: planned
description: Workplan for Topaz evaluation, relationship PDP adapters, rule PDP adapters, Keycloak AuthZ path, directory resolvers, and operations docs.
```