diff --git a/README.md b/README.md index 44b3dcb..8bb741e 100644 --- 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). diff --git a/docs/workplan-planning-map.md b/docs/workplan-planning-map.md new file mode 100644 index 0000000..82fcf34 --- /dev/null +++ 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` diff --git a/workplans/FLEX-WP-0001-repo-intent-and-architecture-baseline.md b/workplans/FLEX-WP-0001-repo-intent-and-architecture-baseline.md new file mode 100644 index 0000000..05921db --- /dev/null +++ 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. diff --git a/workplans/FLEX-WP-0002-standalone-policy-as-code-core.md b/workplans/FLEX-WP-0002-standalone-policy-as-code-core.md new file mode 100644 index 0000000..336a82d --- /dev/null +++ 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. diff --git a/workplans/FLEX-WP-0003-markitect-consumer-integration.md b/workplans/FLEX-WP-0003-markitect-consumer-integration.md new file mode 100644 index 0000000..7d7aa97 --- /dev/null +++ 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. diff --git a/workplans/FLEX-WP-0004-delegated-pdp-and-directory-adapters.md b/workplans/FLEX-WP-0004-delegated-pdp-and-directory-adapters.md new file mode 100644 index 0000000..0ba41e9 --- /dev/null +++ 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.