Initiated flex-auth with Scope and PRD

2026-05-04 19:16:26 +02:00
parent f2531ed8c9
commit 1c8fd17589
3 changed files with 517 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -6,5 +6,9 @@ systems.
 Start with [INTENT.md](INTENT.md) for the project boundary and direction.
 Research notes live in [docs/](docs/).
 The product boundary is captured in [SCOPE.md](SCOPE.md), and the current
 Product Requirements Document is
 [docs/ProductRequirementsDocument.md](docs/ProductRequirementsDocument.md).
 Initial workplans live in [workplans/](workplans/), with sequencing captured
 in [docs/workplan-planning-map.md](docs/workplan-planning-map.md).
--- a/SCOPE.md
+++ b/SCOPE.md
@@ -0,0 +1,162 @@
 # flex-auth Scope
 ## One-liner
 flex-auth is a policy-as-code authorization registry and control plane for
 NetKingdom-aligned systems.
 ## Core Idea
 flex-auth turns verified identity claims, resource manifests, relationship
 facts, policy packages, and request context into inspectable authorization
 decisions. It is intentionally separate from identity providers and from the
 applications that enforce decisions.
 The product should start as a useful standalone local authorization system,
 then grow into delegated mode where Topaz, OpenFGA, SpiceDB, OPA, Cedar,
 Keycloak Authorization Services, Entra, Graph, SCIM, LDAP, and similar systems
 can be coordinated behind a stable flex-auth API.
 ## In Scope
 - Protected-system registration.
 - Resource namespaces, resource hierarchy, and action vocabularies.
 - Subject, group, team, tenant, role, and service-account records needed for
  authorization.
 - Relationship facts and inherited access.
 - Versioned policy packages with metadata, fixtures, validation, tests, and
  activation state.
 - Deterministic check, batch-check, list-allowed, explain, and decision-record
  capabilities.
 - Local decision logs with policy version and provenance.
 - CLI and service entry points for local development and integration tests.
 - Markitect as the first concrete protected-system consumer.
 - Delegated PDP and directory adapter boundaries after the standalone core is
  stable.
 ## Out of Scope
 - Acting as an identity provider.
 - Replacing key-cape, NetKingdom SSO, Keycloak, Entra, or other identity
  systems.
 - Owning login, MFA, PKCE, token issuance, token lifecycle, or canonical
  identity profile behavior.
 - Embedding protected-system enforcement logic inside flex-auth.
 - Making Markitect-specific assumptions part of the generic authorization
  model.
 - Forcing a single PDP backend or directory provider.
 - Hiding policy behavior behind opaque administrative toggles.
 ## Relevant When
 - A protected system needs resource-specific authorization decisions.
 - A team needs policy-as-code packages that can be reviewed, tested, versioned,
  and explained.
 - Authorization must combine identity claims, groups, roles, tenants,
  relationships, context, and resource metadata.
 - A local development workflow needs deterministic authorization behavior
  before enterprise PDP integrations exist.
 - Markitect resources need central authorization decisions and durable audit
  records.
 - A delegated backend needs to be introduced without changing the
  protected-system-facing API.
 ## Not Relevant When
 - The task is only about authentication, login, token issuance, or MFA.
 - The desired outcome can be handled by coarse identity-provider roles alone.
 - The protected system only needs local development labels and no central
  policy administration.
 - A team is choosing identity-provider configuration rather than
  resource-specific authorization.
 ## Current State
 The repository contains the intent baseline, authorization landscape research,
 and initial workplans. `FLEX-WP-0001` is complete. Current implementation work
 starts with `FLEX-WP-0002`, the standalone policy-as-code core. Markitect
 consumer integration and delegated PDP/directory adapters are planned after
 the core contracts stabilize.
 State Hub integration is present through:
 - `.custodian-brief.md`
 - `state_hub_workstream_id` fields in workplans
 - `state_hub_task_id` fields in task blocks
 - active State Hub dispatch for the `flex-auth` repo
 ## How It Fits
 flex-auth sits between identity and protected systems:
 ```text
 key-cape / NetKingdom SSO
  -> verified identity claims
  -> flex-auth authorization registry and policy decisions
  -> protected systems such as Markitect
 ```
 Identity systems establish who the caller is and provide coarse claims.
 flex-auth decides what that caller can do to a specific resource under a
 specific context. Protected systems enforce the decision and keep their own
 local diagnostics.
 ## Terminology
 - **Subject:** Human, service account, group, team, tenant, role, or emergency
  principal.
 - **Resource:** Protected object registered by a system.
 - **Namespace:** Resource type and ownership boundary.
 - **Action:** Operation requested against a resource.
 - **Context:** Request, environment, assurance, workflow, or runtime
  attributes.
 - **Policy package:** Versioned policy-as-code bundle with metadata and tests.
 - **Relationship fact:** Subject-resource or resource-resource relation.
 - **Decision:** Allow, deny, redact, audit-only, or not-applicable outcome with
  reason and provenance.
 - **PDP:** Policy decision point, either flex-auth standalone logic or a
  delegated backend.
 - **PEP:** Policy enforcement point in the protected system.
 ## Related / Overlapping
 - key-cape / NetKingdom SSO: identity source and coarse claims provider.
 - Markitect: first protected-system consumer and policy enforcement point.
 - Topaz: candidate MVP delegated backend combining local directory and
  OPA/Rego evaluation.
 - OpenFGA and SpiceDB: candidate relationship authorization backends.
 - OPA and Cedar: candidate rule and typed-policy engines.
 - Keycloak Authorization Services: adapter path for Keycloak-centric
  deployments.
 - Entra, Graph, SCIM, LDAP, and Keycloak APIs: directory and group resolver
  sources.
 ## Provided Capabilities
 ```capability
 type: orientation
 title: Agent orientation
 status: current
 description: Repo intent, boundaries, research, workplan map, and State Hub agent brief are available for new coding agents.
 ```
 ```capability
 type: workplan
 title: Standalone policy core plan
 status: planned
 description: Workplan for schemas, local registry, policy packages, check APIs, list/explain, decision log, CLI/service skeleton, tests, and examples.
 ```
 ```capability
 type: workplan
 title: Markitect consumer integration plan
 status: planned
 description: Workplan for Markitect resource namespace, manifest import, action vocabulary, check fixtures, contract tests, and integration flow.
 ```
 ```capability
 type: workplan
 title: Delegated adapter plan
 status: planned
 description: Workplan for Topaz evaluation, relationship PDP adapters, rule PDP adapters, Keycloak AuthZ path, directory resolvers, and operations docs.
 ```
--- a/docs/ProductRequirementsDocument.md
+++ b/docs/ProductRequirementsDocument.md
@@ -0,0 +1,351 @@
 # flex-auth Product Requirements Document
 Date: 2026-05-04
 Status: Draft for alignment
 ## 1. Definition
 flex-auth is a policy-as-code authorization registry and control plane for
 organizations that need to grow from simple application roles into
 enterprise-grade, inspectable authorization.
 The product is expected to define and operate the authorization layer between
 verified identity claims and protected systems. It should let resource owners
 register protected systems and resources, publish reviewable policy packages,
 evaluate authorization requests, explain decisions, and preserve decision
 records for diagnostics and audit.
 This PRD defines what flex-auth must achieve within this repository's current
 boundary. It intentionally avoids prescribing internal architecture or
 implementation details beyond the product-level constraints already established
 by the repo.
 ## 2. Context
 NetKingdom-aligned systems separate identity from authorization:
 ```text
 key-cape / NetKingdom SSO
  -> verified OIDC/SAML identity claims
  -> flex-auth policy-as-code and authorization registry
  -> protected systems and knowledge tools
 ```
 Identity providers issue tokens, manage login, and provide coarse claims.
 Protected systems enforce allow, deny, redact, and audit outcomes at their own
 runtime boundaries. flex-auth exists between those responsibilities as the
 stable authorization product surface.
 The first concrete consumer is Markitect, which needs central authorization for
 knowledge bases, repositories, documents, sections, context packages, workflow
 artifacts, and exports. The product must use that consumer to validate real
 resource and decision needs without becoming Markitect-specific.
 ## 3. Product Intent
 flex-auth should provide a path that starts small and grows cleanly:
 - Local developers and small teams can run flex-auth in standalone mode.
 - Policy authors can version, review, validate, test, publish, and activate
  policy packages.
 - Protected systems can register resources and ask stable authorization
  questions.
 - Operators can inspect and export decision records with enough provenance to
  diagnose policy behavior.
 - Enterprise deployments can later delegate relationship, rule, or directory
  concerns to established backends without changing protected-system contracts.
 The product outcome is not merely a collection of adapters. The core value is a
 canonical, backend-neutral authorization model that keeps ownership clear as
 policy complexity grows.
 ## 4. Users and Stakeholders
 ### Primary Users
 - Protected-system developers integrating authorization checks.
 - Policy authors defining resource-specific access behavior.
 - Platform engineers operating local or shared flex-auth instances.
 - Product and architecture owners aligning identity, authorization, and
  protected-system boundaries.
 ### Secondary Users
 - Security reviewers inspecting policy behavior and audit records.
 - Support or operations staff diagnosing denied, redacted, stale, partial, or
  uncertain decisions.
 - Future backend integrators connecting Topaz, OpenFGA, SpiceDB, OPA, Cedar,
  Keycloak Authorization Services, Entra, Graph, SCIM, LDAP, or related
  systems.
 ## 5. In Scope
 ### Standalone Authorization Core
 - Protected-system manifests.
 - Resource manifests and resource hierarchies.
 - Subject, group, team, tenant, role, service-account, and emergency-principal
  representations needed for authorization.
 - Relationship fact manifests.
 - Canonical action vocabularies.
 - Check request and decision envelope definitions.
 - Deterministic `check` and `batch_check` behavior.
 - `list_allowed` for discoverable allowed resources.
 - `explain` for decision diagnostics.
 - Local registry storage suitable for development, tests, and small
  deployments.
 ### Policy-as-Code Lifecycle
 - Policy package metadata, validation, fixtures, tests, versions, and
  activation state.
 - Local policy package testing before activation.
 - Policy decision outputs that include effect, reason, matched policy version,
  matched rule, obligations, diagnostics, and provenance.
 ### Audit and Diagnostics
 - Local decision records.
 - Durable recording for denies, redactions, exports, and emergency actions.
 - Compact decision envelopes suitable for later audit export.
 - Clear diagnostics for stale, partial, uncertain, denied, and redacted
  results.
 ### Developer and Operator Experience
 - CLI workflows for validating manifests, loading registry data, testing
  policies, checking one request, batch checking, and explaining a decision.
 - A service entry point after library and CLI behavior are stable enough.
 - Examples and tests for local users, groups, teams, project resources,
  inherited relationships, and policy fixtures.
 ### First Consumer: Markitect
 - Markitect resource namespace and hierarchy.
 - Import of Markitect resource manifests into the flex-auth registry.
 - Markitect action vocabulary: `read`, `query`, `search`, `package`,
  `activate_context`, `export`, `workflow_run`, and `admin`.
 - Markitect-compatible decision fixtures and contract tests.
 - Integration documentation for publish, check, enforce, record, and explain
  flows.
 ### Future Delegated Mode
 - Adapter boundaries for relationship PDPs such as OpenFGA and SpiceDB.
 - Adapter boundaries for rule PDPs such as OPA/Rego and Cedar.
 - Topaz evaluation as the first delegated-backend candidate.
 - Keycloak Authorization Services adapter path for Keycloak-centric
  deployments.
 - Directory and group resolver patterns for Entra/Graph, SCIM, LDAP, and
  Keycloak APIs.
 - Operations documentation for caching, consistency, failure modes, and
  fail-open/fail-closed behavior.
 ## 6. Out of Scope
 - Acting as an identity provider.
 - Replacing key-cape, NetKingdom SSO, Keycloak, Entra, or other identity
  providers.
 - Owning login, MFA, PKCE, token issuance, token lifecycle, OIDC discovery, or
  canonical IAM profile behavior.
 - Making protected systems passive; they remain responsible for enforcement.
 - Embedding Markitect-specific policy administration into flex-auth's generic
  model.
 - Treating identity-provider roles, scopes, or groups as final
  resource-specific authorization by themselves.
 - Forcing all deployments to use Topaz, OpenFGA, SpiceDB, OPA, Cedar,
  Keycloak Authorization Services, Entra, or any other single backend.
 - Providing backlog, sprint, or task execution details beyond the existing
  workplans.
 - Defining detailed technical architecture, database schema internals, service
  framework choices, or deployment manifests in this PRD.
 ## 7. Functional Requirements
 ### FR1. Protected-System Registration
 flex-auth must let a protected system declare its identity, ownership, resource
 namespaces, action vocabulary, and integration metadata in a registered
 manifest.
 ### FR2. Resource Registration
 flex-auth must accept resource manifests that describe resource identity,
 namespace, hierarchy, owner metadata, policy labels, trust zones, and relevant
 provenance.
 ### FR3. Subject and Relationship Registration
 flex-auth must represent authorization-relevant subjects and relationships,
 including humans, service accounts, groups, teams, tenants, roles, emergency
 principals, subject-resource relations, and resource-resource relations.
 ### FR4. Policy Package Validation
 flex-auth must load policy packages with metadata, fixtures, test cases,
 version information, and activation metadata, and must reject invalid packages
 with useful diagnostics.
 ### FR5. Policy Package Testing
 flex-auth must support policy fixtures and test cases so policy authors can
 verify expected decisions before activation.
 ### FR6. Authorization Checks
 flex-auth must provide `check(subject, action, resource, context)` returning a
 decision envelope with effect, reason, policy version, matched rule,
 obligations, diagnostics, and provenance.
 ### FR7. Batch Authorization Checks
 flex-auth must provide `batch_check(subject, action, resources, context)` for
 query/search workflows where multiple resources must be evaluated together.
 ### FR8. Allowed Resource Listing
 flex-auth must provide `list_allowed(subject, action, resource_type, filters,
 context)` for workflows that need to discover resources a subject can access.
 ### FR9. Decision Explanation
 flex-auth must provide `explain(decision_id)` so developers, policy authors,
 and operators can understand why a decision was produced.
 ### FR10. Decision Recording
 flex-auth must record decisions with compact, durable metadata, always
 including denies, redactions, exports, and emergency actions.
 ### FR11. Markitect Compatibility
 flex-auth must represent Markitect resource manifests, resource hierarchy,
 action vocabulary, and decision shapes without making Markitect the only
 consumer model.
 ### FR12. Delegated Backend Readiness
 flex-auth must preserve a stable protected-system-facing contract when
 authorization evaluation is later delegated to external PDP or directory
 systems.
 ## 8. Non-Functional Requirements
 ### NFR1. Implementation Independence
 Product contracts must be expressed in backend-neutral vocabulary. External PDP
 engines are adapters, not product definitions.
 ### NFR2. Explainability
 Denied, redacted, stale, partial, uncertain, audit-only, and not-applicable
 decisions must produce useful diagnostics.
 ### NFR3. Local Usefulness
 Standalone mode must be useful for development, smaller deployments, and
 integration tests before delegated integrations are available.
 ### NFR4. Reviewability
 Policies must be versioned, testable, and suitable for code review.
 ### NFR5. Auditability
 Decision records must include policy version and enough provenance to support
 diagnostics and audit export.
 ### NFR6. Backend Portability
 The product must not require protected systems to change contracts when a PDP
 backend changes.
 ### NFR7. Operational Clarity
 Failure modes, caching behavior, consistency, stale directory data, group
 overage, and fail-open/fail-closed behavior must be explicit.
 ### NFR8. Ownership Clarity
 flex-auth must preserve clear boundaries between identity ownership,
 authorization ownership, and protected-system enforcement ownership.
 ## 9. Assumptions and Dependencies
 - Identity claims come from key-cape, NetKingdom SSO, Keycloak, Entra, or
  compatible identity systems.
 - Protected systems are able to extract resource metadata and enforce
  decisions locally.
 - Markitect remains the first concrete consumer for shaping realistic resource
  and workflow needs.
 - Delegated backends should be introduced only after standalone request,
  decision, registry, and audit vocabulary are stable.
 - Directory group membership can be stale, incomplete, or oversized for tokens;
  freshness and source metadata are therefore product requirements.
 - This repo currently contains planning and documentation artifacts, not an
  implemented service.
 ## 10. Success Criteria
 ### MVP Success
 - flex-auth can run standalone for local development.
 - Protected systems, resources, subjects, relationships, and policy packages
  can be validated and loaded.
 - `check`, `batch_check`, `list_allowed`, and `explain` are available.
 - Decision envelopes are stable and include actionable diagnostics.
 - Local decision logs record required high-value events.
 - CLI workflows cover validation, loading, policy testing, checking, batch
  checking, and explaining.
 - Tests and examples cover representative local users, groups, teams,
  resources, inheritance, and policy fixtures.
 ### First Consumer Success
 - Markitect resource manifests can be imported.
 - Markitect action vocabulary is represented.
 - Markitect-compatible decisions are produced for allow, deny, redact, and
  audit-denied cases.
 - Markitect integration docs cover publish, check, enforce, record, and explain
  flows.
 - The integration remains generic enough for another protected system to reuse
  the same flex-auth model.
 ### Expansion Success
 - Topaz has a clear MVP recommendation or rejection.
 - Relationship PDP and rule PDP adapter contracts are documented and tested at
  their boundaries.
 - Keycloak Authorization Services, Entra/Graph, SCIM, LDAP, and Keycloak API
  resolver paths are documented with explicit freshness and failure behavior.
 - Protected-system APIs remain stable as delegated mode is introduced.
 ## 11. Product Constraints
 - flex-auth must not collapse identity and authorization into one concern.
 - flex-auth must not let the first Markitect integration narrow the generic
  protected-system model.
 - flex-auth must keep policy behavior inspectable rather than relying on opaque
  administrative toggles.
 - flex-auth must treat roles, scopes, groups, tenants, claims, relationships,
  and context as authorization inputs, not as automatic final decisions.
 - flex-auth must be useful before enterprise infrastructure is available.
 - flex-auth must make uncertainty visible instead of silently hiding stale or
  partial authorization data.
 ## 12. Traceability
 This PRD is grounded in the current repository material:
 - `INTENT.md`
 - `docs/flex-auth-authorization-registry-research.md`
 - `docs/workplan-planning-map.md`
 - `workplans/FLEX-WP-0001-repo-intent-and-architecture-baseline.md`
 - `workplans/FLEX-WP-0002-standalone-policy-as-code-core.md`
 - `workplans/FLEX-WP-0003-markitect-consumer-integration.md`
 - `workplans/FLEX-WP-0004-delegated-pdp-and-directory-adapters.md`
 - `.custodian-brief.md`
 Downstream technical specifications, ADRs, schemas, backlog items, tests, and
 implementation tasks should derive from this document without treating it as a
 technical design.