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:

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