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

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
• decision effect, reason, obligations, diagnostics, provenance

P2.1 - Define canonical schemas

id: FLEX-WP-0002-T001
status: todo
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)
• policy package (Rego-in-Markdown envelope per ADR-002 — frontmatter schema, 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

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: todo
priority: high
state_hub_task_id: "d8045124-f0ae-495d-87b5-24fd9528ef93"

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

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

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

P2.4 - Implement deterministic check and batch_check APIs

id: FLEX-WP-0002-T004
status: todo
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, and provenance.

P2.5 - Implement list_allowed and explain

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

P2.6 - Add local decision log

id: FLEX-WP-0002-T006
status: todo
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, and emergency actions.

P2.7 - Add CLI and service skeleton

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

Provide command-line workflows for:

• validate manifests
• load registry data
• test policy packages
• 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, 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.