From dd0b9663c4b5d51e44a584bf4062c05f43283d3c Mon Sep 17 00:00:00 2001 From: tegwick Date: Sun, 17 May 2026 04:15:38 +0200 Subject: [PATCH] Refine workplans for CARING profile --- README.md | 3 + docs/caring-architecture-blueprint.md | 203 ++++++++++++++++++ docs/workplan-planning-map.md | 24 ++- ...-WP-0002-standalone-policy-as-code-core.md | 52 ++++- ...-WP-0003-markitect-consumer-integration.md | 25 ++- ...04-delegated-pdp-and-directory-adapters.md | 19 +- 6 files changed, 306 insertions(+), 20 deletions(-) create mode 100644 docs/caring-architecture-blueprint.md diff --git a/README.md b/README.md index 42cc90b..89ef73b 100644 --- a/README.md +++ b/README.md @@ -14,5 +14,8 @@ The 2026-05-15 pre-implementation assessment that shapes the current sequencing is in [docs/pre-implementation-assessment.md](docs/pre-implementation-assessment.md). +The CARING reference-implementation approach is captured in +[docs/caring-architecture-blueprint.md](docs/caring-architecture-blueprint.md). + Workplans live in [workplans/](workplans/), with sequencing captured in [docs/workplan-planning-map.md](docs/workplan-planning-map.md). diff --git a/docs/caring-architecture-blueprint.md b/docs/caring-architecture-blueprint.md new file mode 100644 index 0000000..a41119c --- /dev/null +++ b/docs/caring-architecture-blueprint.md @@ -0,0 +1,203 @@ +# CARING Architecture Blueprint For Flex-Auth + +Date: 2026-05-17 +Status: Draft architecture blueprint +Source standard: CARING 0.4.0-RC2 (`/home/worsch/helix-forge/wiki/CaringStandardRc2.md`) + +## Purpose + +This blueprint describes how flex-auth can serve as the practical, +efficient reference implementation of the CARING standard while keeping +the core authorization path small enough to build and operate. + +CARING remains the semantic standard. Flex-auth implements the subset +needed to make CARING descriptors, policy conformance, decisions, +explanations, and audit events executable. + +## Architecture Position + +CARING answers: + +```text +What access semantics should a system expose, validate, explain, and audit? +``` + +Flex-auth answers: + +```text +Given a subject, action, resource, context, policy package, and registry +state, what decision should protected systems enforce? +``` + +The reference implementation relationship is: + +```text +CARING standard + -> flex-auth CARING profile schemas + -> policy packages and conformance checks + -> check/batch/list/explain APIs + -> decision and exposure-event audit records +``` + +## Minimal CARING Profile + +The first implementation should pin a `caring_profile` version and define +the following canonical fields in flex-auth API and schema artifacts: + +```text +subject_type +organization_relation +canonical_role +scope +plane +capabilities +exposure_mode +conditions +lifecycle_state +restrictions +exposure_event +derived_capabilities +access_path +``` + +The core does not need to implement every CARING benchmark or native-system +mapping immediately. It only needs the descriptor shape, enums, validation, +and a place in decisions and audit records. + +## Core Data Types + +`pkg/api` should expose: + +```text +CaringProfile +CaringAccessDescriptor +CaringConformanceFinding +CaringExposureEvent +CaringRestriction +CaringDerivedCapability +``` + +These types should be referenced by: + +```text +SubjectManifest +ResourceManifest +RelationshipFact +PolicyPackageMetadata +CheckRequest +DecisionEnvelope +AuditEvent +``` + +The `ResourceManifest` remains consumer-owned and lightweight. CARING +classification should be optional on resources at first, with policy +packages allowed to require specific fields for a protected system. + +## Decision Pipeline + +The efficient runtime path is: + +```text +1. Normalize identity claims into a Subject. +2. Load registry facts for resource, relationships, tenant, and groups. +3. Build a CheckRequest with CARING context. +4. Evaluate restrictions first. +5. Evaluate scoped policy package rules. +6. Produce a DecisionEnvelope. +7. Attach CARING conformance findings and provenance. +8. Persist audit/exposure-event records when required. +``` + +CARING conformance should not block the fast allow/deny path unless a +policy marks a finding as enforcement-grade. Most early findings should +be diagnostics, warnings, or audit requirements. + +## Conformance Model + +Flex-auth should support two CARING modes: + +```text +descriptive + Map existing local roles, policy objects, and grants into CARING + descriptors. Report ambiguity, bundling, missing scope, missing plane, + induced access, and exposure gaps. + +prescriptive + Validate new policy packages and manifests against a CARING profile. + Fail on required fields, restriction precedence, tenant-boundary + violations, and explicit policy-plane or secret-plane violations. +``` + +The conformance output should use stable severities: + +```text +info +warning +violation +blocked +``` + +## Policy Package Shape + +Rego-in-Markdown policy packages should carry CARING frontmatter: + +```yaml +caring: + profile: caring-0.4.0-rc2 + canonical_roles: [Doer] + organization_relations: [Customer] + planes: [Data] + capabilities: [View] + exposure_modes: [Masked, Plaintext] + conditions: [PurposeBound, Logged] + restrictions: [ExportBlocked, CrossTenantBlocked] +``` + +The policy evaluator should provide this metadata to Rego and copy the +matched CARING descriptor into the decision envelope. + +## Reference Implementation Boundaries + +Flex-auth should implement: + +```text +CARING descriptor schemas +CARING-aware policy package validation +CARING-aware decision envelopes +CARING explain output +CARING exposure-event audit records +CARING conformance fixtures +``` + +Flex-auth should not own: + +```text +The CARING standard text +The NetKingdom IAM Profile +Identity-provider role issuance +Consumer-specific product semantics +Full benchmark mappings for every native access system +``` + +## Implementation Slices + +1. Pin the CARING profile and descriptors in `FLEX-WP-0002 P2.1`. +2. Add registry fields and validation in `FLEX-WP-0002 P2.2`. +3. Add policy frontmatter and diagnostics in `FLEX-WP-0002 P2.3`. +4. Attach CARING metadata to `check` and `batch_check` in `FLEX-WP-0002 P2.4`. +5. Use CARING language in `list_allowed` and `explain` in `FLEX-WP-0002 P2.5`. +6. Persist CARING exposure events in `FLEX-WP-0002 P2.6`. +7. Map Markitect fixtures as the first consumer benchmark in `FLEX-WP-0003`. +8. Require delegated adapters in `FLEX-WP-0004` to preserve CARING envelope + fields even when backend-native semantics differ. + +## Open Design Choices + +The first implementation should decide: + +```text +Whether CARING enum values are strict or extension-friendly. +Whether conformance findings are always non-blocking by default. +How much derived-capability analysis belongs in core versus adapters. +How to version profile changes after CARING leaves RC status. +``` diff --git a/docs/workplan-planning-map.md b/docs/workplan-planning-map.md index 6f8ff04..a013642 100644 --- a/docs/workplan-planning-map.md +++ b/docs/workplan-planning-map.md @@ -1,6 +1,6 @@ # Flex-Auth Workplan Planning Map -Date: 2026-05-15 +Date: 2026-05-17 ## Purpose @@ -20,10 +20,10 @@ This document captures the current sequencing view for flex-auth workplans. | Workplan | Priority | Status | Depends On | Current View | | --- | --- | --- | --- | --- | | `FLEX-WP-0001` | complete | done | none | Repo intent, boundaries, and authorization landscape research are complete. | -| `FLEX-WP-0005` | P0 | todo | `FLEX-WP-0001` | Foundations and Topaz alignment: ADR-001/002/003, Go skeleton, `FlexAuthResourceManifest` schema pin, Topaz mapping spike, IAM Profile citation, ops-warden boundary clarification. | -| `FLEX-WP-0002` | P0 | blocked | `FLEX-WP-0001`, `FLEX-WP-0005` | Standalone policy-as-code core: schemas, local registry, Rego-in-Markdown policy packages, check APIs, explanations, decision log, CLI/service skeleton, tests. | -| `FLEX-WP-0003` | P1 | blocked | `FLEX-WP-0002` | Markitect consumer integration: resource namespace, manifest import, action vocabulary, decision fixtures, integration docs. | -| `FLEX-WP-0004` | P2 | blocked | `FLEX-WP-0002`, `FLEX-WP-0005` | Delegated PDP and directory adapters: Topaz adapter implementation (evaluation already done in `0005`), OpenFGA/SpiceDB, OPA/Cedar, Keycloak Authorization Services, Entra/Graph/SCIM. | +| `FLEX-WP-0005` | complete | done | `FLEX-WP-0001` | Foundations and Topaz alignment are complete: ADR-001/002/003, Go skeleton, `FlexAuthResourceManifest` schema pin, Topaz mapping spike, IAM Profile citation, ops-warden boundary clarification. | +| `FLEX-WP-0002` | P0 | ready | `FLEX-WP-0001`, `FLEX-WP-0005` | Standalone policy-as-code core: schemas, local registry, CARING profile/descriptors, Rego-in-Markdown policy packages, check APIs, explanations, decision log, CLI/service skeleton, tests. | +| `FLEX-WP-0003` | P1 | blocked | `FLEX-WP-0002` | Markitect consumer integration and first CARING benchmark: resource namespace, manifest import, action vocabulary, descriptor fixtures, decision fixtures, integration docs. | +| `FLEX-WP-0004` | P2 | blocked | `FLEX-WP-0002`, `FLEX-WP-0005` | Delegated PDP and directory adapters: Topaz adapter implementation (evaluation already done in `0005`), OpenFGA/SpiceDB, OPA/Cedar, Keycloak Authorization Services, Entra/Graph/SCIM, CARING envelope preservation. | ## Dependency Notes @@ -33,18 +33,30 @@ It pulls forward the decisions the original `0002` left implicit (language, policy format, evaluator alignment) and runs the Topaz mapping spike before the core's schemas and check API are written. +`docs/caring-architecture-blueprint.md` adds the 2026-05-17 CARING +refinement: CARING remains the semantic standard, while flex-auth becomes +the practical reference implementation for descriptors, conformance +findings, decision metadata, explain output, and exposure-event audit +records. This refinement changes the shape of `FLEX-WP-0002` but does not +add a new predecessor workplan. + `FLEX-WP-0002` comes after `0005` so the standalone evaluator embeds the OPA Rego library and produces decision envelopes shaped to match the -delegated-mode envelopes added later. +delegated-mode envelopes added later. It now also pins the executable +CARING profile in the same schema slice. `FLEX-WP-0003` follows the core. Markitect has already completed its side of the contract in `MKTT-WP-0014`; flex-auth pins the manifest in `FLEX-WP-0005 T03` and implements the service-side registry and decision behavior in `0003`. +It also becomes the first consumer benchmark for proving local roles and +resource semantics can map cleanly into CARING dimensions. `FLEX-WP-0004` waits for the standalone core for the same reason as before, but its Topaz evaluation task moved to `0005 T04`; this workplan now implements the Topaz adapter against the spike's output. +Delegated adapters must preserve flex-auth's CARING descriptor and +conformance fields even when backend-native role semantics differ. ## State Hub Mirror diff --git a/workplans/FLEX-WP-0002-standalone-policy-as-code-core.md b/workplans/FLEX-WP-0002-standalone-policy-as-code-core.md index 03ce0f8..aa2c8d6 100644 --- a/workplans/FLEX-WP-0002-standalone-policy-as-code-core.md +++ b/workplans/FLEX-WP-0002-standalone-policy-as-code-core.md @@ -12,7 +12,7 @@ depends_on_workplans: - FLEX-WP-0001 - FLEX-WP-0005 created: "2026-05-04" -updated: "2026-05-15" +updated: "2026-05-17" state_hub_workstream_id: "aa60e183-9a87-4e03-99b0-15786bfa11ae" --- @@ -38,6 +38,12 @@ external policy engines. > Topaz mapping spike. Tasks below have been updated to consume those > outputs rather than re-decide them. +> **CARING note (2026-05-17).** The core now also consumes the CARING +> 0.4.0-RC2 standard as a governance profile, not as an identity source. +> `docs/caring-architecture-blueprint.md` defines the implementation +> approach: CARING supplies descriptor and conformance vocabulary, while +> flex-auth remains the efficient runtime authorization engine. + ## Design Direction The core should define flex-auth's own stable vocabulary: @@ -54,6 +60,7 @@ Backends may change later, but these envelopes must stay stable: - subject/group/team/tenant identity - relationship facts - policy package and version +- CARING access descriptor and conformance profile - decision effect, reason, obligations, diagnostics, provenance ## P2.1 - Define canonical schemas @@ -73,13 +80,18 @@ Define machine-readable schemas for: - subject/group/team manifest (vocabulary aligned with the Topaz mapping produced in `FLEX-WP-0005 T04`) - relationship fact manifest (same alignment note) +- CARING profile and access descriptor (subject type, organization + relation, canonical role, scope, plane, capability, exposure mode, + condition, lifecycle state, restriction, exposure event, derived + capability, and access path) - policy package (Rego-in-Markdown envelope per ADR-002 — frontmatter - schema, fenced `rego` / `rego test` / `yaml fixture` blocks) + schema, CARING conformance metadata, fenced `rego` / `rego test` / + `yaml fixture` blocks) - policy fixture/test case - check request - decision envelope (provenance fields identical for local and - delegated evaluation per ADR-003) -- audit event + delegated evaluation per ADR-003, plus CARING descriptor and findings) +- audit event and CARING exposure event Output: docs, JSON Schema files in `schemas/`, runnable examples in `examples/`, and validation tests in `internal/policy/` and @@ -95,7 +107,7 @@ state_hub_task_id: "d8045124-f0ae-495d-87b5-24fd9528ef93" ``` Implement a local registry for systems, resources, subjects, groups, teams, -tenants, and relationships. +tenants, relationships, and CARING descriptor assignments. Start with a deterministic file-backed or SQLite-backed store that supports tests and local development. @@ -124,10 +136,17 @@ The evaluator embeds the OPA Rego library directly flex-auth evaluates locally can be served unchanged to a delegated Topaz/OPA backend in FLEX-WP-0004. +Policy frontmatter should declare the CARING profile it targets and the +roles, scopes, planes, capabilities, exposure modes, conditions, and +restrictions it governs. Validation should report CARING conformance +findings as diagnostics first; findings become enforcement-grade only +when a policy explicitly opts in. + Output: a Markdown-to-Rego extractor, a package validator with useful diagnostics for malformed frontmatter / unparseable rules / failing -tests / failing fixtures, and golden tests on at least three real -package examples (one allow, one deny, one redact-with-obligation). +tests / failing fixtures / CARING metadata mismatches, and golden tests +on at least three real package examples (one allow, one deny, one +redact-with-obligation). ## P2.4 - Implement deterministic check and batch_check APIs @@ -146,7 +165,9 @@ 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. +resource metadata, subject metadata, obligations, diagnostics, provenance, +matched CARING descriptor, evaluated restrictions, exposure mode, and +conformance findings. ## P2.5 - Implement list_allowed and explain @@ -165,7 +186,10 @@ explain(decision_id) ``` Use the same decision model as `check` and keep explanations useful for policy -authors and protected-system developers. +authors and protected-system developers. Explanations should use CARING +language where it clarifies the result, for example "Customer Doer may +View this Data Plane resource in Tenant Alpha, but Exportable exposure is +blocked." ## P2.6 - Add local decision log @@ -177,7 +201,9 @@ 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. +experiments. Always record denies, redactions, exports, emergency actions, +and CARING exposure events such as support access, break-glass access, +induced access, and privilege-escalation findings. ## P2.7 - Add CLI and service skeleton @@ -193,6 +219,7 @@ Provide command-line workflows for: - validate manifests - load registry data - test policy packages +- validate CARING profiles and access descriptors - check one request - batch check - explain a decision @@ -209,7 +236,8 @@ state_hub_task_id: "6cbe572a-2877-4936-8ef3-63b79900fae2" ``` Add examples for local users, groups, teams, project resources, inherited -relationships, and policy fixtures. +relationships, CARING access descriptors, exposure events, and policy +fixtures. ## Exit Criteria @@ -218,3 +246,5 @@ relationships, and policy fixtures. - 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. +- CARING 0.4.0-RC2 is pinned as an executable conformance profile with + schemas, examples, decision metadata, and audit/exposure-event support. diff --git a/workplans/FLEX-WP-0003-markitect-consumer-integration.md b/workplans/FLEX-WP-0003-markitect-consumer-integration.md index 7d7aa97..e2ac2e7 100644 --- a/workplans/FLEX-WP-0003-markitect-consumer-integration.md +++ b/workplans/FLEX-WP-0003-markitect-consumer-integration.md @@ -13,7 +13,7 @@ depends_on_workplans: related_workplans: - MKTT-WP-0014 created: "2026-05-04" -updated: "2026-05-04" +updated: "2026-05-17" state_hub_workstream_id: "c0a6c9f6-bb6b-416d-b537-f30504c63d75" --- @@ -29,6 +29,11 @@ resource manifests, local decision-log sink, workflow declarations, and CLI inspection. This flex-auth workplan implements the service-side contract that Markitect can call. +This workplan is also the first concrete CARING benchmark for flex-auth. +Markitect resource/action fixtures should prove that a protected system can +map local resource semantics into CARING access descriptors without making +Markitect-specific assumptions part of the generic core. + ## P3.1 - Define Markitect resource namespace ```task @@ -50,7 +55,8 @@ knowledge_base ``` Output: namespace docs, schema examples, and compatibility notes for -Markitect frontmatter and backend metadata. +Markitect frontmatter and backend metadata. The namespace docs must map +each resource level to CARING scope and plane values. ## P3.2 - Import Markitect resource manifests @@ -65,6 +71,8 @@ Accept the Markitect-side `FlexAuthResourceManifest` shape and import it into the flex-auth registry. Output: importer, validation diagnostics, example fixtures, and tests. +Diagnostics should include missing or ambiguous CARING classification when a +manifest cannot be mapped cleanly enough for conformance checks. ## P3.3 - Define Markitect action vocabulary @@ -87,6 +95,9 @@ Define actions: - `admin` Map these actions to Markitect policy-gateway decisions. +Also map each action to CARING capabilities and exposure modes, keeping +`view`/`read` separate from `export`, and keeping plaintext, masked, and +metadata-only exposure explicit. ## P3.4 - Implement Markitect check fixtures @@ -105,6 +116,9 @@ Create fixtures that mirror Markitect examples: - restricted export requires steward role and MFA - context package activation includes policy version and freshness metadata +Each fixture should include the expected CARING descriptor, conformance +finding set, and exposure/audit behavior. + ## P3.5 - Add Markitect adapter contract tests ```task @@ -124,6 +138,7 @@ Add tests that produce flex-auth decisions in the shape Markitect expects: - policy version - resource metadata - obligations/diagnostics +- CARING descriptor and conformance findings ## P3.6 - Document integration flow @@ -142,9 +157,15 @@ Document how Markitect should: 4. Record decision ids. 5. Explain decisions back to users. +The documented flow should explain how Markitect local roles, groups, +frontmatter, and workflow states map into CARING dimensions before they +become flex-auth decisions. + ## 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. +- Markitect local semantics can be represented as CARING descriptors and + conformance findings without custom core concepts. diff --git a/workplans/FLEX-WP-0004-delegated-pdp-and-directory-adapters.md b/workplans/FLEX-WP-0004-delegated-pdp-and-directory-adapters.md index 7453bd6..5bc9fa6 100644 --- a/workplans/FLEX-WP-0004-delegated-pdp-and-directory-adapters.md +++ b/workplans/FLEX-WP-0004-delegated-pdp-and-directory-adapters.md @@ -13,7 +13,7 @@ depends_on_workplans: related_workplans: - FLEX-WP-0003 created: "2026-05-04" -updated: "2026-05-15" +updated: "2026-05-17" state_hub_workstream_id: "99a82976-d376-42b0-89cc-c44e01c0bec6" --- @@ -35,6 +35,11 @@ vocabulary are stable. > speaks Rego, so adapter work focuses on directory delegation, wire > protocol, and consistency metadata rather than re-deciding fit. +> **CARING note (2026-05-17).** Delegated adapters must preserve the +> CARING decision envelope fields defined by the standalone core. Backend +> native semantics may differ, but protected systems should still see the +> same descriptor, exposure, restriction, conformance, and audit shape. + ## P4.1 - Implement Topaz adapter ```task @@ -61,6 +66,9 @@ Scope: - Failure modes: Topaz unavailable, stale directory, partial result — each produces a decision envelope that the standalone code path could also have produced. +- CARING preservation: delegated decisions include the same CARING + descriptor, restriction precedence, exposure mode, conformance findings, + and exposure-event hooks as standalone decisions. Output: adapter package under `internal/adapters/topaz/`, end-to-end integration test using the `examples/topaz/` docker-compose from the @@ -83,6 +91,8 @@ Define and implement adapter contracts for OpenFGA and SpiceDB-style checks: - batch/list operations - consistency metadata - error and stale-data diagnostics +- preservation of CARING scope, plane, capability, exposure, and derived + capability metadata across tuple-oriented backends ## P4.3 - Add rule PDP adapter boundary @@ -99,6 +109,8 @@ Define and implement adapter contracts for OPA/Rego and Cedar-style policies: - policy package versioning - test fixtures - obligations and diagnostics +- CARING frontmatter and conformance findings when backend-native policy + languages cannot represent every descriptor dimension directly ## P4.4 - Add Keycloak Authorization Services adapter path @@ -130,6 +142,9 @@ Implement directory group resolver patterns for: - Keycloak admin API Each resolver must expose freshness, source, and overage metadata. +Resolvers must also identify which organization relation, subject type, +group, or role claim was derived from the external directory so CARING +descriptor provenance remains inspectable. ## P4.6 - Add delegated-mode operations docs @@ -151,3 +166,5 @@ consistency, and audit behavior for delegated backends. - Backend changes do not alter the protected-system-facing flex-auth API. - Topaz/OpenFGA/OPA/Cedar/Keycloak/Entra tradeoffs are documented with practical guidance. +- Delegated backends preserve CARING descriptor and conformance metadata + instead of leaking backend-native role semantics into protected systems.