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

id, type, title, domain, status, owner, topic_slug, planning_priority, planning_order, depends_on_workplans, created, updated, state_hub_workstream_id

id	type	title	domain	status	owner	topic_slug	planning_priority	planning_order	depends_on_workplans	created	updated	state_hub_workstream_id
FLEX-WP-0002	workplan	Standalone Policy-as-Code Core	netkingdom	todo	flex-auth	flex-auth	P0	20	FLEX-WP-0001 FLEX-WP-0005	2026-05-04	2026-05-17	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:

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

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

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

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

id: FLEX-WP-0002-T004
status: done
priority: high
state_hub_task_id: "f6427575-00af-4f3e-ab30-5b9a158343ef"

Implement:

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

id: FLEX-WP-0002-T005
status: done
priority: medium
state_hub_task_id: "e8fcbabd-4eb6-41d2-a4d5-6f40cc245a7e"

Implement:

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

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

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

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.