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