coulomb/flex-auth
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Initiated flex-auth with Scope and PRD

Browse Source
This commit is contained in:
Bernd Worsch
2026-05-04 19:16:26 +02:00
parent f2531ed8c9
commit 1c8fd17589
3 changed files with 517 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
README.md
View File

@@ -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).

162
SCOPE.md Normal file
View File

@@ -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.
```

351
docs/ProductRequirementsDocument.md Normal file
View File

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