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:

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

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.