From 1c8fd17589c370f7b90a3b68152c6d2c39507d54 Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 4 May 2026 19:16:26 +0200 Subject: [PATCH] Initiated flex-auth with Scope and PRD --- README.md | 4 + SCOPE.md | 162 +++++++++++++ docs/ProductRequirementsDocument.md | 351 ++++++++++++++++++++++++++++ 3 files changed, 517 insertions(+) create mode 100644 SCOPE.md create mode 100644 docs/ProductRequirementsDocument.md diff --git a/README.md b/README.md index 8bb741e..bafdfb4 100644 --- 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). diff --git a/SCOPE.md b/SCOPE.md new file mode 100644 index 0000000..29a2362 --- /dev/null +++ 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. +``` diff --git a/docs/ProductRequirementsDocument.md b/docs/ProductRequirementsDocument.md new file mode 100644 index 0000000..683f2b2 --- /dev/null +++ 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.