flex-auth/docs/caring-architecture-blueprint.md

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:

What access semantics should a system expose, validate, explain, and audit?

Flex-auth answers:

Given a subject, action, resource, context, policy package, and registry
state, what decision should protected systems enforce?

The reference implementation relationship is:

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:

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:

CaringProfile
CaringAccessDescriptor
CaringConformanceFinding
CaringExposureEvent
CaringRestriction
CaringDerivedCapability

These types should be referenced by:

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:

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:

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:

info
warning
violation
blocked

Policy Package Shape

Rego-in-Markdown policy packages should carry CARING frontmatter:

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:

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:

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:

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.