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

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

## P2.1 - Define canonical schemas

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

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

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

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

## P2.5 - Implement list_allowed and explain

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

## P2.6 - Add local decision log

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

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

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