flex-auth/INTENT.md

# Flex-Auth Intent

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

## First Consumer Pattern

The first concrete consumer is a knowledge and document management pipeline:

- 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

This first consumer should shape flex-auth around real document and knowledge
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.