flex-auth/INTENT.md

# Flex-Auth Intent

Date: 2026-05-04

## 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 belongs in the NetKingdom tooling landscape as the authorization counterpart
to key-cape/NetKingdom identity:

```text
key-cape / NetKingdom SSO
  -> verified OIDC/SAML identity claims
  -> flex-auth policy-as-code and authorization registry
  -> protected systems and knowledge tools
```

Flex-auth should run usefully on its own, but it should also delegate to or
coordinate with established authorization engines such as Topaz, OpenFGA,
SpiceDB, OPA, Cedar, Keycloak Authorization Services, and enterprise directory
systems.

## 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 SSO, 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

The identity contract flex-auth consumes is the **NetKingdom IAM Profile**
(`~/the-custodian/canon/standards/iam-profile_v0.1.md`), implemented by
key-cape in lightweight mode and by Keycloak in heavy mode. flex-auth
treats the profile as normative input and never re-defines it.

### key-cape / NetKingdom Owns Identity

- OIDC discovery and token issuance.
- Human login, MFA, PKCE, service accounts, token lifecycle.
- Canonical IAM profile and required claims.
- Coarse app 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 such as Markitect 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 enterprise policy
administration.

## Design Principles

- Policy is code: versioned, reviewed, tested, and explainable.
- Identity is not authorization: SSO claims are inputs, not final decisions.
- Start standalone, scale outward: a local flex-auth deployment should be
  useful before Topaz/OpenFGA/OPA integrations are 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,
  NetKingdom-managed deployments, and larger Keycloak/Entra 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 Keycloak/key-cape-like claims

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

## Delegated Mode

Delegated mode should let flex-auth coordinate established systems:

- Topaz for a local directory plus OPA/Rego policy evaluation.
- OpenFGA or SpiceDB for graph-heavy relationship authorization.
- OPA or Cedar for attribute/rule policies.
- Keycloak Authorization Services for Keycloak-centric deployments.
- Microsoft Graph or SCIM/LDAP/Keycloak APIs for directory group resolution.

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

## First Consumer: Markitect

Markitect is the first concrete consumer:

- Markitect registers knowledge bases, repositories, documents, sections,
  context packages, workflow artifacts, and exports.
- Markitect sends policy checks before returning query/search/context results.
- Markitect can redact or drop results based on decisions.
- flex-auth owns central policy administration and durable audit.

This first consumer should shape flex-auth around real Markdown knowledge
pipelines without making the policy service Markitect-specific.

## Non-Goals

- Flex-auth is not an identity provider.
- Flex-auth is not a replacement for key-cape or NetKingdom SSO.
- 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 Markitect resource manifest and policy adapter.
5. Evaluate Topaz as the first delegated backend.
6. Add OpenFGA/SpiceDB and OPA adapter spikes.
7. Add Keycloak/key-cape and Entra integration examples.