Refine workplans for CARING profile

2026-05-17 04:15:38 +02:00
parent f930e96568
commit dd0b9663c4
6 changed files with 306 additions and 20 deletions
--- 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).
--- a/docs/caring-architecture-blueprint.md
+++ 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.
+```
--- 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

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