diff --git a/.repo-classification.yaml b/.repo-classification.yaml new file mode 100644 index 0000000..9963d67 --- /dev/null +++ b/.repo-classification.yaml @@ -0,0 +1,7 @@ +repo_classification: + category: project + domain: infotech + secondary_domains: [] + capability_tags: + - governance + - policy diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..0dc2720 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,4 @@ +# Agent instructions — zone-engine + +Orient: GOAL.md → SCOPE.md → workplans/. +Workplan prefix: `ZONE-WP-`. diff --git a/GOAL.md b/GOAL.md new file mode 100644 index 0000000..1f1906f --- /dev/null +++ b/GOAL.md @@ -0,0 +1,49 @@ +--- +repo: zone-engine +repo_flavor: project +project_status: draft +started: "2026-08-19" +--- + +# Goal — zone-engine + +## Outcome + +Enforcement rigidity is a declared, reviewable property of a named zone rather +than a boolean per repo. A control can be turned on for the band of the estate +that wants its failure mode, and left advisory where that failure mode would +stop the work. Deep refactors get relaxed rigidity through an exception that +expires on its own. + +## Invariants + +- **`flex-auth` remains the only policy decision point.** Zone membership + reaches it by compilation into the registry it already consumes. Nothing this + repo builds sits synchronously in a decision path. +- **A zone that can be quietly widened is not a boundary.** Every change of + stance is observable, and every exception has an enforced expiry. +- **Accuracy, not altitude** (`tenancy-posture_v0.1` §6). A repo declaring a + stricter zone than it can evidence is the failure to design against, because + it looks like progress. +- **Placement is not posture.** Reefs are a separate axis and stay separate. +- **The model precedes the schema.** No API, no storage, no wire format until + `ZONE-WP-0001` has partitioned the real estate. + +## Success gates + +1. The model partitions today's estate — the 27 ops-warden catalog lanes, the + actor inventory, the posture-carrying workloads — without a residue of + unexplained exceptions. +2. A canon standard is drafted and offered to `net-kingdom`, in the family of + `tenancy-posture_v0.1`. +3. At least two repos declare zones and are read by a third — a model only its + author honours is not adopted. +4. `ops-warden`'s `policy.enabled` is retired in favour of a zone-aware control, + closing `WARDEN-WP-0031-T05`. +5. Whether a runtime is needed is answered on evidence from the exception + lifecycle, not assumed. + +## Project retirement + +Archive when the standard is canon, the declarations are live, and either a +runtime exists with an owner or the decision that none is needed is recorded. diff --git a/README.md b/README.md index 6bb64b4..27767f4 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,17 @@ # zone-engine -Headless multi-application, multi-tenant security zone mangement engine. \ No newline at end of file +Headless authority for **security zones** — named bands of the estate with +different enforcement rigidity, and the lifecycle of time-boxed exceptions to +them. + +A zone answers a question no existing axis answers: *is this control enforced +here, and what happens when it fails?* NetKingdom can already say how exposed a +workload is (environment posture), how ready it is (workload maturity `M0`–`M3`), +and what state the organization is in (`organization_posture`). All three +describe. None decides. + +`zone-engine` is **not** a policy decision point. `flex-auth` remains the only +PDP; zone membership reaches it by compilation into the registry it already +consumes, never by a synchronous lookup in the decision path. + +Orient: `GOAL.md` → `SCOPE.md` → `workplans/`. diff --git a/SCOPE.md b/SCOPE.md new file mode 100644 index 0000000..c9d153d --- /dev/null +++ b/SCOPE.md @@ -0,0 +1,101 @@ +# SCOPE + +> What this repository is about, when it is relevant, and when it is not. +> Direction lives in `GOAL.md`. + +--- + +## One-liner + +Authority for security zones — the bands of enforcement rigidity that scope +*where* a control is enforced, and the lifecycle of time-boxed exceptions that +relax them during deep refactors without leaving a permanent hole. + +--- + +## Why this exists + +Enforcement controls in this estate have been repo-wide booleans. ops-warden's +flex-auth pre-sign gate (`policy.enabled` with `fail_closed: true`) was the +first to become flippable, and flipping it would have made flex-auth a hard +dependency of every `warden sign` — including the SSH certificates the +ops-bridge tunnels depend on, one of which carries the policy call itself. + +Across an estate under continuous deep refactor, uniform enforcement hardens +exactly the access needed to perform the refactor. That is not security; it is +an outage with good intentions. The flip was deferred under ops-warden's +`ADR-0006` — *enforcement is zone-scoped, never a global flag* — and this repo +is what that ADR defers to. + +--- + +## In scope + +- **Zone identity and membership.** What zones exist, and what puts a lane, + actor, or workload in one. Derived from declared posture where possible + rather than a fourth hand-maintained list. +- **Enforcement stance per control per zone** — enforced / advisory / exempt, + and the failure mode (fail-closed or fail-open) that goes with it. The failure + mode is the part with teeth. +- **Time-boxed exception lifecycle** — a relaxation with an expiry that is + enforced by something rather than intended, plus the record of who widened + what, when, and until when. +- **The declaration format** repos use to state their zones, following + `tenancy.yaml` and its rule: *accuracy, not altitude*. +- **Drafting the canon standard** for the model, offered to `net-kingdom` for + publication the way `tenant-engine` and `user-engine` have boundary contracts + in canon. + +## Out of scope + +- **Authorization decisions.** `flex-auth` is the PDP and stays the only one. + A second decision point is the split-brain this repo must not create. +- **Network segmentation.** "Zone" is overloaded; this is about enforcement + rigidity, not routing or NetworkPolicy. The two must not be conflated. +- **Substrate placement.** Reefs (`reef-railiance`, `reef-storage`) answer + *where does it run*; a zone answers *how rigidly is it governed*. Correlated, + not the same axis — and per repo-manager's rule, topology is not readiness. +- **Identity, secrets, tenancy.** `key-cape`, OpenBao / `secrets-engine`, + `tenant-engine`. +- **Implementing any specific control.** Owners keep their own controls; this + repo says where they bite. +- **Publishing canon.** `net-kingdom` owns canon; `policy-nexus` publishes. + +--- + +## Relationship to what already exists + +| Mechanism | Owner | Relationship | +| --- | --- | --- | +| `tenancy-posture_v0.1` (six axes, per-repo `tenancy.yaml`) | net-kingdom canon | **Structural model to follow** — graduated levels, declared conformance, review dates, "accuracy not altitude". Its §14 stance is *structure, not tooling*, which is why this repo starts as a model and not an API | +| Environment posture + workload maturity `M0`–`M3` | ops-warden (WP-0015) | Inputs a zone may derive membership from | +| `organization_posture: build` | ops-warden (WP-0029) | Candidate to fold in rather than run alongside | +| Reefs / `bound_reefs` | repo-manager | Correlated substrate axis; must be reconciled, not duplicated | +| Compiled registry snapshot | flex-auth | **How zone membership reaches the PDP.** flex-auth is latency-critical; compilation, not runtime lookup | +| `warden plan` verdicts + `reasons` | ops-warden (WP-0029) | Existing verdict machinery to extend, not parallel | + +--- + +## Current state (2026-08-19) + +Seeded. No model, no schema, no runtime. `ZONE-WP-0001` derives the model from +the real estate and drafts the canon standard; a runtime is earned only if the +exception lifecycle proves to need one. + +Deliberately empty of schema — an empty engine that ships a schema first ends up +defining the model by accident. + +--- + +## Relevant when + +- A control is about to be enabled and the question "enforced *where*?" has no + answer +- A deep refactor needs relaxed rigidity in a band of the estate, with an expiry +- A repo needs to declare which zone its lanes sit in + +## Not relevant when + +- Asking whether a specific request is allowed (→ `flex-auth`) +- Placing a workload on a substrate (→ `repo-manager` reefs) +- Anything about network reachability diff --git a/workplans/ZONE-WP-0001-security-zone-model.md b/workplans/ZONE-WP-0001-security-zone-model.md new file mode 100644 index 0000000..95e0a41 --- /dev/null +++ b/workplans/ZONE-WP-0001-security-zone-model.md @@ -0,0 +1,183 @@ +--- +id: ZONE-WP-0001 +type: workplan +title: "The security zone model — derive it from the estate, draft it as canon" +domain: infotech +repo: zone-engine +status: proposed +owner: zone-engine +topic_slug: netkingdom +planning_priority: P1 +created: "2026-08-19" +updated: "2026-08-19" +--- + +# ZONE-WP-0001 — The security zone model + +Ported from `WARDEN-WP-0032` (ops-warden), which deferred `policy.enabled: true` +under `ADR-0006` and named this repo as its successor. ops-warden keeps only its +consumer-side task. + +**This workplan produces a model and a canon draft. It does not produce an API, +a schema, or storage.** An engine that ships a schema before it has partitioned +the real estate defines the model by accident, through whatever its first wire +format happened to be. Whether a runtime is warranted is an *output* of T02–T03, +not an assumption of T01. + +## The gap in one table + +| Axis | Shipped | Answers | +| --- | --- | --- | +| Environment posture (`dev`/`test`/`prod`) | ops-warden WP-0015 | Where does this run? | +| Workload maturity (`M0`–`M3`) | ops-warden WP-0015 | How ready is this workload? | +| `organization_posture: build` | ops-warden WP-0029 | What state is the org in? | +| **Enforcement stance** | **missing** | **Is this control enforced here, and what happens when it fails?** | + +The first three describe. Nothing decides. That is why `policy.enabled` is a +repo-wide boolean, and why turning it on would have hardened the access needed +to perform the refactors currently underway. + +## Do not reinvent these + +**`net-kingdom/canon/standards/tenancy-posture_v0.1.md`** — the structural model +to follow: orthogonal axes, graduated levels, a per-repo declaration +(`tenancy.yaml`) with current/implemented/target vectors, evidence, and a review +date; §6 *conformance is accuracy, not altitude*; §14 adoption stance +*structure, not tooling*. That last one is why this workplan is shaped as it is. + +**Reefs** (`repo-manager/docs/RailianceAppDeploymentGuide.md`) — `reef-railiance` +carries a single-node/shared-control-plane residual risk requiring explicit +acceptance. Substrate placement with risk attached is *adjacent* to a zone and +must be reconciled with it, not duplicated. repo-manager's own rule — *topology +is not readiness* — restates here as **placement is not posture**. + +**flex-auth** — the PDP, `service_class: latency-critical`, already consuming a +compiled registry snapshot built by +`ops-warden/scripts/build_flex_auth_registry.py`. Zone membership reaches the +decision point by **compilation**. A synchronous zone lookup in the decision +path would be a regression dressed as an architecture. + +**`warden plan`** (ops-warden WP-0029) — already returns +`autonomous`/`founder_required`/`unroutable` from properties of the thing, with +the `reasons` that produced the verdict. Zone-aware enforcement extends that +machinery; it does not grow a second vocabulary beside it. + +## Tasks + +```task +id: ZONE-WP-0001-T01 +status: todo +priority: high +``` + +**Confirm ownership on the record, and say what publishes where.** This repo was +seeded on a recommendation, not yet on agreement. Take to `net-kingdom` (canon) +and `flex-auth` (the enforcing PDP): zone-engine owns the model and the +exception lifecycle; canon publishes the standard, in the family of +`tenancy-posture_v0.1` and the `*-engine` boundary contracts; flex-auth stays +the only PDP and consumes compiled membership. + +If either disagrees, the model moves and this repo is archived rather than kept +for its own sake. Record the outcome either way. + +```task +id: ZONE-WP-0001-T02 +status: todo +priority: high +``` + +**Derive the zones from the real estate.** Walk ops-warden's 27 catalog lanes, +the `adm`/`agt`/`atm` actor inventory, and the workloads carrying posture +descriptors. The model's test is that it partitions what exists without a +residue of unexplained exceptions — and the exceptions found are the most +informative output, not noise to tidy away. + +Answer explicitly: + +- Is a zone a property of the **actor**, the **lane**, the **workload**, or the + **moment**? The CoulombCore decommission and the issue-core move show the last + is real and hardest to model. A time-boxed relaxation is a *different object* + from a standing zone; conflating them yields a permanent hole with a + temporary-sounding name. +- Do zones **compose with or fold in** the three existing axes? A fourth + independent axis multiplies states; absorbing `organization_posture` may be + the honest move. +- How do zones relate to **reefs**? State it in the model rather than leaving + readers to guess. + +```task +id: ZONE-WP-0001-T03 +status: todo +priority: high +``` + +**Model stance and failure mode, per control per zone.** Enforced / advisory / +exempt, *and* fail-closed or fail-open. The failure mode is where the bite is: +`fail_closed` is what turns a dead tunnel into an outage, and is precisely why +the ops-warden flip was deferred. + +Controls in scope at minimum: the flex-auth pre-sign gate (`policy.enabled`, +`fail_closed`), the agent read-boundary on `risk: high` lanes (ops-warden +`ADR-0004`), and the `warden plan` escalation verdicts. + +```task +id: ZONE-WP-0001-T04 +status: todo +priority: high +``` + +**Design the time-boxed exception — this is the load-bearing task.** A standing +classification needs no engine; canon plus a declaration file covers it. An +exception with an expiry is *state*, and state wants an owner. Whether this repo +earns a runtime is decided here. + +Must specify: who may grant, against which zone and control, for how long, with +what recorded justification; how expiry is **enforced rather than intended**; +how an active exception is visible to someone who did not grant it; and what +happens at expiry — auto-revert, or block until renewed. + +If T04 concludes the lifecycle can live as reviewed declarations in git, say so +plainly and drop the runtime. That is a valid and cheaper outcome. + +```task +id: ZONE-WP-0001-T05 +status: todo +priority: medium +``` + +**Declaration format and conformance rule.** Follow `tenancy.yaml`: per-repo, +with evidence, `reviewed`, and `review_due`; carry over *accuracy, not +altitude*. Include how a zone assignment changes and how that change is +observed — a zone that can be quietly widened is not a boundary. + +```task +id: ZONE-WP-0001-T06 +status: todo +priority: medium +``` + +**Draft the canon standard and offer it.** `security-zones_v0.1.md` for +`net-kingdom/canon/standards/`, drafted here, published there. Owner-driven +landing, as ops-warden's WP-0015 maturity model was. + +```task +id: ZONE-WP-0001-T07 +status: todo +priority: medium +``` + +**Prove it on two consumers.** A model only its author honours is not adopted. +The first is ops-warden: retire `policy.enabled` for a zone-aware control, +closing `WARDEN-WP-0031-T05`. Re-run +`ops-warden/scripts/check_policy_caller_identity.py` first — the 2026-08-19 +evidence (`decision:f3f7c88f9585582a`) will be stale, and re-establishing it is +cheap by design. The second consumer comes from T01. + +## Related + +- ops-warden `ADR-0006` — enforcement is zone-scoped, never a global flag +- ops-warden `WARDEN-WP-0032` — the ops-warden-side stub this was ported from +- ops-warden `WARDEN-WP-0031` — the deferred flip, and the readiness evidence +- flex-auth `FLEX-WP-0016` — the enforcing pin with no enforcing consumer +- `net-kingdom/canon/standards/tenancy-posture_v0.1.md` +- `repo-manager/docs/RailianceAppDeploymentGuide.md` — reefs