flex-auth/workplans/FLEX-WP-0002-standalone-policy-as-code-core.md

---
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
  - FLEX-WP-0005
created: "2026-05-04"
updated: "2026-05-17"
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.

> **Sequencing note (2026-05-15).** This workplan now depends on
> `FLEX-WP-0005 Foundations and Topaz Alignment`. The foundations workplan
> records the three ADRs that pin language (Go, ADR-001), policy package
> format (Rego-in-Markdown, ADR-002), and evaluator alignment
> (Topaz-shaped from day one, ADR-003), lands the Go skeleton, pins the
> `FlexAuthResourceManifest` schema with Markitect, and produces the
> 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:

```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
- CARING access descriptor and conformance profile
- decision effect, reason, obligations, diagnostics, provenance

## P2.1 - Define canonical schemas

```task
id: FLEX-WP-0002-T001
status: done
priority: high
state_hub_task_id: "534e5251-8529-48fe-8cf8-b3b6bc4ec1f4"
```

Define machine-readable schemas for:

- protected system manifest
- resource manifest (consumes `FlexAuthResourceManifest` pinned in
  `FLEX-WP-0005 T03`)
- 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, 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, 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
`internal/registry/`.

## P2.2 - Implement local registry store

```task
id: FLEX-WP-0002-T002
status: done
priority: high
state_hub_task_id: "d8045124-f0ae-495d-87b5-24fd9528ef93"
```

Implement a local registry for systems, resources, subjects, groups, teams,
tenants, relationships, and CARING descriptor assignments.

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: done
priority: high
state_hub_task_id: "09be0f25-e5ba-42b5-8b2f-36fd0ef2fe6b"
```

Load policy-as-code packages with metadata, rules, fixtures, tests, and
activation metadata.

Per ADR-002, packages are Markdown documents with YAML frontmatter,
prose intent sections, fenced `rego` rule blocks, fenced `rego test`
blocks, and fenced `yaml fixture` blocks. The loader extracts and
concatenates the Rego blocks into one OPA module per package, runs
`opa parse` and `opa test`, and evaluates each declared fixture against
the module before marking the package `valid`.

The evaluator embeds the OPA Rego library directly
(`github.com/open-policy-agent/opa/rego`) so the same module that
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 / 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

```task
id: FLEX-WP-0002-T004
status: done
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, provenance,
matched CARING descriptor, evaluated restrictions, exposure mode, and
conformance findings.

## P2.5 - Implement list_allowed and explain

```task
id: FLEX-WP-0002-T005
status: done
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. 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

```task
id: FLEX-WP-0002-T006
status: done
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, 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

```task
id: FLEX-WP-0002-T007
status: done
priority: high
state_hub_task_id: "ee9ae6dd-c31f-4d4e-b238-533a2b8040d4"
```

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

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, CARING access descriptors, exposure events, 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.
- CARING 0.4.0-RC2 is pinned as an executable conformance profile with
  schemas, examples, decision metadata, and audit/exposure-event support.