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