diff --git a/INTENT.md b/INTENT.md index 44decb4..4320cdf 100644 --- a/INTENT.md +++ b/INTENT.md @@ -1,6 +1,9 @@ # Flex-Auth Intent -Date: 2026-05-04 +> 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 @@ -9,20 +12,19 @@ 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: +It is the **authorization layer** in the path from verified identity to +protected resources: ```text -key-cape / NetKingdom SSO - -> verified OIDC/SAML identity claims +verified identity claims -> flex-auth policy-as-code and authorization registry - -> protected systems and knowledge tools + -> protected systems and their resources ``` -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. +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 @@ -36,7 +38,7 @@ conditionals. Over time they need richer policy: - emergency/break-glass controls - policy tests and reviewable changes - durable decision logs and explainability -- integration with SSO, MFA, service accounts, and directory groups +- 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 @@ -44,19 +46,17 @@ 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. +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. -### key-cape / NetKingdom Owns Identity +### The Identity Layer 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. +- 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 +### Flex-Auth Owns Authorization - Protected-system registration. - Resource namespaces and resource hierarchy. @@ -70,17 +70,17 @@ treats the profile as normative input and never re-defines it. ### 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. +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: SSO claims are inputs, not final decisions. +- Identity is not authorization: identity 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. + 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 @@ -88,7 +88,7 @@ administration. - 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. + and larger enterprise environments. ## First-Class Concepts @@ -131,40 +131,41 @@ Standalone flex-auth should provide: - deterministic check and batch-check APIs - local decision log - CLI and service mode -- test fixtures for Keycloak/key-cape-like claims +- 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: +Delegated mode should let flex-auth coordinate established systems without +adopting their models as its own: -- 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. +- 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 PDP backend changes. +Flex-auth remains the stable control plane even when the backend changes. -## First Consumer: Markitect +## First Consumer Pattern -Markitect is the first concrete consumer: +The first concrete consumer is a knowledge and document management pipeline: -- 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. +- 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 Markdown knowledge -pipelines without making the policy service Markitect-specific. +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 key-cape or NetKingdom SSO. +- 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. @@ -174,7 +175,7 @@ pipelines without making the policy service Markitect-specific. 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. +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.