Initiated flex-auth with Scope and PRD

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