Workplan sketch out and statehub registration

2026-05-04 18:15:59 +02:00
parent 8f3437a2c3
commit f2531ed8c9
6 changed files with 614 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -5,3 +5,6 @@ systems.

 Start with [INTENT.md](INTENT.md) for the project boundary and direction.
 Research notes live in [docs/](docs/).
+
+Initial workplans live in [workplans/](workplans/), with sequencing captured
+in [docs/workplan-planning-map.md](docs/workplan-planning-map.md).
--- a/docs/workplan-planning-map.md
+++ b/docs/workplan-planning-map.md
@@ -0,0 +1,46 @@
+# Flex-Auth Workplan Planning Map
+
+Date: 2026-05-04
+
+## Purpose
+
+This document captures the initial sequencing view for flex-auth workplans.
+
+## Priority Scale
+
+| Priority | Meaning |
+| --- | --- |
+| `P0` | Current mainline implementation work. |
+| `P1` | Next integration work once core contracts exist. |
+| `P2` | Delegated/backend expansion after core shape stabilizes. |
+| `complete` | Finished foundation or completed decision work. |
+
+## Current Ordering
+
+| Workplan | Priority | Status | Depends On | Current View |
+| --- | --- | --- | --- | --- |
+| `FLEX-WP-0001` | complete | done | none | Repo intent, boundaries, and authorization landscape research are complete. |
+| `FLEX-WP-0002` | P0 | todo | `FLEX-WP-0001` | Standalone policy-as-code core: schemas, local registry, policy packages, check APIs, explanations, decision log, CLI/service skeleton, tests. |
+| `FLEX-WP-0003` | P1 | todo | `FLEX-WP-0002` | Markitect consumer integration: resource namespace, manifest import, action vocabulary, decision fixtures, integration docs. |
+| `FLEX-WP-0004` | P2 | todo | `FLEX-WP-0002` | Delegated PDP and directory adapters: Topaz, OpenFGA/SpiceDB, OPA/Cedar, Keycloak Authorization Services, Entra/Graph/SCIM. |
+
+## Dependency Notes
+
+`FLEX-WP-0002` should come first because the protected-system-facing API must
+be stable before flex-auth delegates decisions to external engines.
+
+`FLEX-WP-0003` follows the core and uses Markitect as the first concrete
+consumer. Markitect has already completed its side of the initial contract in
+`MKTT-WP-0014`, but flex-auth must still implement the service-side registry
+and decision behavior.
+
+`FLEX-WP-0004` should wait for the standalone core so delegated engines do not
+define the whole architecture accidentally.
+
+## State Hub Mirror
+
+Native State Hub dependency edges should mirror:
+
+- `FLEX-WP-0002 -> FLEX-WP-0001`
+- `FLEX-WP-0003 -> FLEX-WP-0002`
+- `FLEX-WP-0004 -> FLEX-WP-0002`
--- a/workplans/FLEX-WP-0001-repo-intent-and-architecture-baseline.md
+++ b/workplans/FLEX-WP-0001-repo-intent-and-architecture-baseline.md
@@ -0,0 +1,97 @@
+---
+id: FLEX-WP-0001
+type: workplan
+title: "Repo Intent and Authorization Architecture Baseline"
+domain: netkingdom
+status: done
+owner: flex-auth
+topic_slug: flex-auth
+planning_priority: complete
+planning_order: 10
+created: "2026-05-04"
+updated: "2026-05-04"
+state_hub_workstream_id: "4dbefd19-bb7d-405c-9a50-e7dbd11cf4d9"
+---
+
+# FLEX-WP-0001: Repo Intent and Authorization Architecture Baseline
+
+## Purpose
+
+Fixate flex-auth as the NetKingdom-side policy-as-code authorization registry
+and control plane, distinct from key-cape identity and from protected systems
+such as Markitect.
+
+## Implementation Summary
+
+Completed the initial project baseline:
+
+- `INTENT.md` defines purpose, scope, responsibility boundaries, design
+  principles, core concepts, standalone/delegated modes, first consumer, and
+  non-goals.
+- `docs/flex-auth-authorization-registry-research.md` captures product and
+  component research across Keycloak Authorization Services, Entra, Topaz,
+  OpenFGA, SpiceDB, OPA/OPAL, Cedar, Cerbos, Casbin, Oso, and related
+  authorization patterns.
+- `README.md` points newcomers at intent and research.
+- The repo has been registered in State Hub under the NetKingdom authorization
+  area.
+
+## P1.1 - Define project intent
+
+```task
+id: FLEX-WP-0001-T001
+status: done
+priority: high
+state_hub_task_id: "5af30b01-ea72-4f87-b74e-a595fd3a5bd7"
+```
+
+Define flex-auth as a policy-as-code authorization registry and control plane
+that can run standalone or coordinate with Topaz, OpenFGA, SpiceDB, OPA, Cedar,
+Keycloak Authorization Services, Entra/Graph, and directory systems.
+
+## P1.2 - Define responsibility boundaries
+
+```task
+id: FLEX-WP-0001-T002
+status: done
+priority: high
+state_hub_task_id: "145ec0ec-130a-4209-9028-1ae06e3664e3"
+```
+
+Capture boundaries:
+
+- key-cape/NetKingdom owns identity.
+- flex-auth owns authorization registry, policy packages, relationships,
+  decision logging, and PDP coordination.
+- protected systems own enforcement.
+
+## P1.3 - Capture open-source and enterprise landscape
+
+```task
+id: FLEX-WP-0001-T003
+status: done
+priority: high
+state_hub_task_id: "c52a9e3e-e264-418d-b462-d5a9d6e22b30"
+```
+
+Document relevant concepts and lessons from current authorization tools and
+enterprise IAM patterns.
+
+## P1.4 - Establish first-consumer architecture
+
+```task
+id: FLEX-WP-0001-T004
+status: done
+priority: medium
+state_hub_task_id: "7756c4c5-598a-4894-9352-6e7145cb3522"
+```
+
+Use Markitect as the first concrete protected-system consumer while keeping
+the flex-auth model generic enough for other systems.
+
+## Exit Criteria
+
+- Repository purpose is explicit.
+- Boundaries are clear enough to prevent identity and protected-system logic
+  from creeping into flex-auth.
+- Initial research informs implementation workplans.
--- a/workplans/FLEX-WP-0002-standalone-policy-as-code-core.md
+++ b/workplans/FLEX-WP-0002-standalone-policy-as-code-core.md
@@ -0,0 +1,190 @@
+---
+id: FLEX-WP-0002
+type: workplan
+title: "Standalone Policy-as-Code Core"
+domain: netkingdom
+status: todo
+owner: flex-auth
+topic_slug: flex-auth
+planning_priority: P0
+planning_order: 20
+depends_on_workplans:
+  - FLEX-WP-0001
+created: "2026-05-04"
+updated: "2026-05-04"
+state_hub_workstream_id: "aa60e183-9a87-4e03-99b0-15786bfa11ae"
+---
+
+# FLEX-WP-0002: Standalone Policy-as-Code Core
+
+## Purpose
+
+Implement the standalone flex-auth core: resource registry, subject/group/team
+registry, relationship facts, policy packages, deterministic check APIs,
+decision envelopes, explainability, local decision logs, and CLI/service entry
+points.
+
+This is the first implementation workplan. It should produce a useful local
+authorization system before delegating to Topaz, OpenFGA, OPA, or other
+external policy engines.
+
+## Design Direction
+
+The core should define flex-auth's own stable vocabulary:
+
+```text
+subject + action + resource + context + policy version -> decision
+```
+
+Backends may change later, but these envelopes must stay stable:
+
+- protected system
+- resource namespace and hierarchy
+- action vocabulary
+- subject/group/team/tenant identity
+- relationship facts
+- policy package and version
+- decision effect, reason, obligations, diagnostics, provenance
+
+## P2.1 - Define canonical schemas
+
+```task
+id: FLEX-WP-0002-T001
+status: todo
+priority: high
+state_hub_task_id: "534e5251-8529-48fe-8cf8-b3b6bc4ec1f4"
+```
+
+Define machine-readable schemas for:
+
+- protected system manifest
+- resource manifest
+- subject/group/team manifest
+- relationship fact manifest
+- policy package
+- policy fixture/test case
+- check request
+- decision envelope
+- audit event
+
+Output: docs, examples, schema files, and validation tests.
+
+## P2.2 - Implement local registry store
+
+```task
+id: FLEX-WP-0002-T002
+status: todo
+priority: high
+state_hub_task_id: "d8045124-f0ae-495d-87b5-24fd9528ef93"
+```
+
+Implement a local registry for systems, resources, subjects, groups, teams,
+tenants, and relationships.
+
+Start with a deterministic file-backed or SQLite-backed store that supports
+tests and local development.
+
+## P2.3 - Implement policy package loader and validator
+
+```task
+id: FLEX-WP-0002-T003
+status: todo
+priority: high
+state_hub_task_id: "09be0f25-e5ba-42b5-8b2f-36fd0ef2fe6b"
+```
+
+Load policy-as-code packages with metadata, rules, fixtures, tests, and
+activation metadata.
+
+The first implementation may use a simple declarative rule format as long as
+the package boundary leaves room for OPA/Rego, Cedar, and Topaz later.
+
+## P2.4 - Implement deterministic check and batch_check APIs
+
+```task
+id: FLEX-WP-0002-T004
+status: todo
+priority: high
+state_hub_task_id: "f6427575-00af-4f3e-ab30-5b9a158343ef"
+```
+
+Implement:
+
+```text
+check(subject, action, resource, context) -> decision
+batch_check(subject, action, resources, context) -> decisions
+```
+
+Decisions must include effect, reason, matched policy version, matched rule,
+resource metadata, subject metadata, obligations, diagnostics, and provenance.
+
+## P2.5 - Implement list_allowed and explain
+
+```task
+id: FLEX-WP-0002-T005
+status: todo
+priority: medium
+state_hub_task_id: "e8fcbabd-4eb6-41d2-a4d5-6f40cc245a7e"
+```
+
+Implement:
+
+```text
+list_allowed(subject, action, resource_type, filters, context)
+explain(decision_id)
+```
+
+Use the same decision model as `check` and keep explanations useful for policy
+authors and protected-system developers.
+
+## P2.6 - Add local decision log
+
+```task
+id: FLEX-WP-0002-T006
+status: todo
+priority: medium
+state_hub_task_id: "2def10c1-4b5f-44a8-8e6b-4c8592fffd43"
+```
+
+Persist compact JSONL or SQLite decision logs for local development and audit
+experiments. Always record denies, redactions, exports, and emergency actions.
+
+## P2.7 - Add CLI and service skeleton
+
+```task
+id: FLEX-WP-0002-T007
+status: todo
+priority: high
+state_hub_task_id: "ee9ae6dd-c31f-4d4e-b238-533a2b8040d4"
+```
+
+Provide command-line workflows for:
+
+- validate manifests
+- load registry data
+- test policy packages
+- check one request
+- batch check
+- explain a decision
+
+Add a minimal service skeleton only after CLI/library behavior is stable.
+
+## P2.8 - Add tests and examples
+
+```task
+id: FLEX-WP-0002-T008
+status: todo
+priority: high
+state_hub_task_id: "6cbe572a-2877-4936-8ef3-63b79900fae2"
+```
+
+Add examples for local users, groups, teams, project resources, inherited
+relationships, and policy fixtures.
+
+## Exit Criteria
+
+- flex-auth can run standalone for local development.
+- Policy packages are versioned, validated, and testable.
+- Resource registration and relationship facts can drive authorization.
+- `check`, `batch_check`, `list_allowed`, and `explain` are implemented.
+- Decision output is stable enough for protected systems to integrate against.
--- a/workplans/FLEX-WP-0003-markitect-consumer-integration.md
+++ b/workplans/FLEX-WP-0003-markitect-consumer-integration.md
@@ -0,0 +1,150 @@
+---
+id: FLEX-WP-0003
+type: workplan
+title: "Markitect Consumer Integration"
+domain: netkingdom
+status: todo
+owner: flex-auth
+topic_slug: flex-auth
+planning_priority: P1
+planning_order: 30
+depends_on_workplans:
+  - FLEX-WP-0002
+related_workplans:
+  - MKTT-WP-0014
+created: "2026-05-04"
+updated: "2026-05-04"
+state_hub_workstream_id: "c0a6c9f6-bb6b-416d-b537-f30504c63d75"
+---
+
+# FLEX-WP-0003: Markitect Consumer Integration
+
+## Purpose
+
+Make Markitect the first concrete protected-system consumer of flex-auth.
+
+Markitect already has a local enterprise integration boundary in
+`MKTT-WP-0014`: identity claim normalization fixtures, policy-subject mapping,
+resource manifests, local decision-log sink, workflow declarations, and CLI
+inspection. This flex-auth workplan implements the service-side contract that
+Markitect can call.
+
+## P3.1 - Define Markitect resource namespace
+
+```task
+id: FLEX-WP-0003-T001
+status: todo
+priority: high
+state_hub_task_id: "53f2fa67-780b-4e40-bbda-e669e4cecc32"
+```
+
+Define resource types and hierarchy for Markitect:
+
+```text
+knowledge_base
+  -> repository
+  -> document/path
+  -> section/span
+  -> context_package
+  -> workflow_artifact/export
+```
+
+Output: namespace docs, schema examples, and compatibility notes for
+Markitect frontmatter and backend metadata.
+
+## P3.2 - Import Markitect resource manifests
+
+```task
+id: FLEX-WP-0003-T002
+status: todo
+priority: high
+state_hub_task_id: "90082eaf-37f5-492f-a884-ff8eec0eccaa"
+```
+
+Accept the Markitect-side `FlexAuthResourceManifest` shape and import it into
+the flex-auth registry.
+
+Output: importer, validation diagnostics, example fixtures, and tests.
+
+## P3.3 - Define Markitect action vocabulary
+
+```task
+id: FLEX-WP-0003-T003
+status: todo
+priority: high
+state_hub_task_id: "cfc78bbb-5425-4780-a860-9109df62ea37"
+```
+
+Define actions:
+
+- `read`
+- `query`
+- `search`
+- `package`
+- `activate_context`
+- `export`
+- `workflow_run`
+- `admin`
+
+Map these actions to Markitect policy-gateway decisions.
+
+## P3.4 - Implement Markitect check fixtures
+
+```task
+id: FLEX-WP-0003-T004
+status: todo
+priority: high
+state_hub_task_id: "1d5de3b2-c581-4ca3-9107-93211eb02c6b"
+```
+
+Create fixtures that mirror Markitect examples:
+
+- public document allow
+- internal document deny
+- internal document allow for reader group
+- restricted export requires steward role and MFA
+- context package activation includes policy version and freshness metadata
+
+## P3.5 - Add Markitect adapter contract tests
+
+```task
+id: FLEX-WP-0003-T005
+status: todo
+priority: medium
+state_hub_task_id: "f9297b0d-69dc-495c-a650-ca671f2c59c7"
+```
+
+Add tests that produce flex-auth decisions in the shape Markitect expects:
+
+- `allow`
+- `deny`
+- `redact`
+- `audit_denied`
+- reason and rule id
+- policy version
+- resource metadata
+- obligations/diagnostics
+
+## P3.6 - Document integration flow
+
+```task
+id: FLEX-WP-0003-T006
+status: todo
+priority: medium
+state_hub_task_id: "e34b0303-4416-40a3-8b34-e0e80d644aea"
+```
+
+Document how Markitect should:
+
+1. Publish resources.
+2. Submit check or batch_check requests.
+3. Enforce allow/deny/redact.
+4. Record decision ids.
+5. Explain decisions back to users.
+
+## Exit Criteria
+
+- flex-auth can ingest Markitect resource manifests.
+- flex-auth can return Markitect-compatible decisions.
+- Markitect examples can be represented in flex-auth fixtures.
+- Integration remains generic enough for other protected systems.
--- a/workplans/FLEX-WP-0004-delegated-pdp-and-directory-adapters.md
+++ b/workplans/FLEX-WP-0004-delegated-pdp-and-directory-adapters.md
@@ -0,0 +1,128 @@
+---
+id: FLEX-WP-0004
+type: workplan
+title: "Delegated PDP and Directory Adapters"
+domain: netkingdom
+status: todo
+owner: flex-auth
+topic_slug: flex-auth
+planning_priority: P2
+planning_order: 40
+depends_on_workplans:
+  - FLEX-WP-0002
+related_workplans:
+  - FLEX-WP-0003
+created: "2026-05-04"
+updated: "2026-05-04"
+state_hub_workstream_id: "99a82976-d376-42b0-89cc-c44e01c0bec6"
+---
+
+# FLEX-WP-0004: Delegated PDP and Directory Adapters
+
+## Purpose
+
+Let flex-auth coordinate established authorization and directory systems while
+remaining the stable control plane for protected systems.
+
+The standalone core must work first. This workplan adds delegated backends and
+provider examples after flex-auth's own request, decision, registry, and audit
+vocabulary are stable.
+
+## P4.1 - Evaluate Topaz as MVP delegated backend
+
+```task
+id: FLEX-WP-0004-T001
+status: todo
+priority: high
+state_hub_task_id: "9046418c-2b78-42c6-8bfa-76d6ed0050dd"
+```
+
+Evaluate Topaz because it combines a local directory, relation modeling, and
+OPA/Rego policy evaluation.
+
+Output: spike notes, mapping examples, pros/cons, and recommendation.
+
+## P4.2 - Add relationship PDP adapter boundary
+
+```task
+id: FLEX-WP-0004-T002
+status: todo
+priority: high
+state_hub_task_id: "b77a0b70-b492-46ba-badf-8c2eebe006aa"
+```
+
+Define and implement adapter contracts for OpenFGA and SpiceDB-style checks:
+
+- tuple/resource mapping
+- inherited access
+- batch/list operations
+- consistency metadata
+- error and stale-data diagnostics
+
+## P4.3 - Add rule PDP adapter boundary
+
+```task
+id: FLEX-WP-0004-T003
+status: todo
+priority: high
+state_hub_task_id: "4e4e5e45-c05a-4a31-8126-f0c7676b1e6c"
+```
+
+Define and implement adapter contracts for OPA/Rego and Cedar-style policies:
+
+- principal/action/resource/context mapping
+- policy package versioning
+- test fixtures
+- obligations and diagnostics
+
+## P4.4 - Add Keycloak Authorization Services adapter path
+
+```task
+id: FLEX-WP-0004-T004
+status: todo
+priority: medium
+state_hub_task_id: "8d3bbc28-985b-4dd7-9fb8-f9a858eb5a6b"
+```
+
+Document and spike Keycloak Authorization Services integration for
+Keycloak-centric deployments without making Keycloak the only resource-policy
+source of truth.
+
+## P4.5 - Add Entra/Graph and SCIM group resolver adapters
+
+```task
+id: FLEX-WP-0004-T005
+status: todo
+priority: medium
+state_hub_task_id: "4fc3fb91-8763-453e-8e54-36178cb11efd"
+```
+
+Implement directory group resolver patterns for:
+
+- Microsoft Graph group overage
+- SCIM provisioning
+- LDAP/AD
+- Keycloak admin API
+
+Each resolver must expose freshness, source, and overage metadata.
+
+## P4.6 - Add delegated-mode operations docs
+
+```task
+id: FLEX-WP-0004-T006
+status: todo
+priority: medium
+state_hub_task_id: "491260f9-b4d7-46fe-8220-d358597db33a"
+```
+
+Document deployment, failure modes, caching, fail-closed/fail-open policy,
+consistency, and audit behavior for delegated backends.
+
+## Exit Criteria
+
+- flex-auth can delegate decisions to at least one external PDP in a controlled
+  adapter shape.
+- Directory group freshness and overage are explicit.
+- Backend changes do not alter the protected-system-facing flex-auth API.
+- Topaz/OpenFGA/OPA/Cedar/Keycloak/Entra tradeoffs are documented with
+  practical guidance.