From 9f7df24c735b6e12ed79961ac94e4db2ed2a2842 Mon Sep 17 00:00:00 2001 From: tegwick Date: Fri, 28 Aug 2026 19:55:40 +0200 Subject: [PATCH] Record security layer model and gate-house re-cut MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reference note from the 2026-08-28 review of INTENT.md across the security estate. Establishes the four-layer model (taxonomy / tooling / engines / helpers), distinguished by determinism and artifact kind, and its self-similarity to the ASM Canon's three planes. Key finding: gate-house's authority-plane framing places a deterministic decision point inside the non-deterministic management layer, violating INV-02, and collides with flex-auth's declared ownership of authorization. zone-engine §5 already ruled that flex-auth is the only policy decision point. Re-cuts gate-house as the doctrine and conformance council. Not canon and not a decision record; the decisions it recommends still have to be written and assented to. Co-Authored-By: Claude Opus 5 Assistant: claude-code Assistant-Model: opus Assistant-Process: 2564823@bnt-lap001 Assistant-Session: 2a7ed827-4928-4b9f-8613-9135c9cadfe9 --- ...curity-layer-model-and-gate-house-recut.md | 222 ++++++++++++++++++ 1 file changed, 222 insertions(+) create mode 100644 history/2026-08-28-security-layer-model-and-gate-house-recut.md diff --git a/history/2026-08-28-security-layer-model-and-gate-house-recut.md b/history/2026-08-28-security-layer-model-and-gate-house-recut.md new file mode 100644 index 0000000..908df43 --- /dev/null +++ b/history/2026-08-28-security-layer-model-and-gate-house-recut.md @@ -0,0 +1,222 @@ +# NetKingdom IT-security layer model, and the gate-house re-cut + +**Recorded:** 2026-08-28 +**Audience:** gate-house, flex-auth, ops-warden, ops-mason, kings-guard, whitehat-security, net-kingdom canon +**Sources:** `INTENT.md` of net-kingdom, info-tech-canon, key-cape, user-engine, tenant-engine, zone-engine, secrets-engine, flex-auth, ops-mason, ops-warden, kings-guard, whitehat-security, gate-house; `net-kingdom/canon/standards/`; State Hub domain summary for `infotech` (2026-08-28) +**Status:** Reference note. Records the outcome of a working discussion. Not canon, not a decision record — the decisions it recommends are listed in §9 and still have to be written and assented to. + +--- + +## 1. Executive summary + +gate-house was seeded describing itself as a deterministic authority plane: a +policy decision point with `/authorize`, `GRANT`/`DENY`, grant storage, a +revocation service, and an ADR to select a policy engine. A review of the +security estate's `INTENT.md` files established that this is the wrong role for +the repository, that it collides with `flex-auth`, and that the estate had +already ruled on the underlying question in `zone-engine`. + +The discussion produced a four-layer model of NetKingdom IT security, +distinguished by **determinism and artifact kind**. Under that model gate-house +belongs to the top, interactive layer — the council where security and defence +doctrine is established, documented, taught, and supervised — and explicitly +not to the deterministic decision path. + +No code exists in gate-house. The re-cut costs nothing but documents. + +--- + +## 2. The layer model + +| Layer | Character | Artifacts | Members (security estate) | +|---|---|---|---| +| **Aspects / taxonomy** | cross-cutting language | terms, semantic contracts | info-tech-canon | +| **Tooling** | deterministic infrastructure; consistent, performant, scalable state | data structures, persistence | authelia, lldap, privacy-idea → packaged as key-cape; OpenBao | +| **Engines** | deterministic APIs for a modeled concept | interfaces, contracts | user-engine, tenant-engine, zone-engine, secrets-engine, flex-auth, role (future) | +| **Helpers** | interactive, non-deterministic; management, operations, change, innovation, controlling | specifications, decisions, workplans, tasks | gate-house, ops-mason, ops-warden, kings-guard, whitehat-security | + +The layer boundary is defined by what a layer *produces* and how deterministic +it is, not by technical tier. Engines model a concept and expose it +deterministically; new concepts get new engines as they become relevant. +Helpers work through agentic capability — assistants and autonomous agents — +and their output is specification and decision, not state. + +## 3. Why the model is load-bearing: it is self-similar to the Canon + +Read by determinism, the layers reproduce the three planes of the Active +Secrets Management Canon: + +```text +Helpers interactive, non-deterministic ≈ Cognitive Plane +Engines deterministic APIs ≈ Authority Plane +Tooling deterministic state ≈ Execution Plane +Taxonomy cross-cutting language +``` + +*Cognition proposes. Authority disposes. Infrastructure executes.* stops being +a security maxim and becomes the layering rule of the estate. NetKingdom's +structure is an instance of the principle its security canon teaches. + +This yields the argument that settles gate-house's role: + +> **If gate-house implemented `/authorize`, it would place the deterministic +> authority boundary inside the non-deterministic management layer — violating +> INV-02 ("No Privilege from Cognition"), its own first invariant.** + +The repository would be the clearest available counterexample to the canon it +hosts. This is not a turf dispute with `flex-auth`; it is internal incoherence. + +## 4. The invariant that makes the layering checkable + +A taxonomy that only labels decays. The model carries one falsifiable rule: + +> **Helpers never touch tooling directly. They act only through engine APIs.** + +This is the architectural form of "no privilege from cognition". It is why +kings-guard — agentic, therefore a Helper — may contain a threat only by +calling an engine, never by reaching into OpenBao itself; and why an autonomous +coding agent gets no shortcut. It is greppable: a Helper repo holding a direct +database or OpenBao client is violating the model. + +## 5. Findings from the INTENT review + +**5.1 gate-house already contradicts itself.** `README.md` line 7 — *"Think of +Gate House as observability for vault managed secrets based on sound governance +policy best practices"* — is a Helpers-layer sentence, and the only one in the +repository. Everything after it describes a runtime decision point. + +**5.2 Direct collision with flex-auth.** `flex-auth/INTENT.md` carries a +section titled **"Flex-Auth Owns Authorization"**, claiming canonical action +vocabulary, policy-as-code packages, PDP adapter coordination, and *"decision +logging, explanations, and audit export"*. gate-house's INTENT claims each of +these, and its shorthand line "**Gate House authorizes**" contradicts +flex-auth's *"flex-auth decides what that actor is allowed to do"*. + +**5.3 The estate already ruled.** `zone-engine/INTENT.md` §5, after flex-auth +pushed back on review of a first draft that got it wrong: + +> *"`flex-auth` is the policy decision point. It stays the only one."* + +and §7, naming the failure mode: + +> *"It becomes a second decision point. The failure would not announce itself; +> it would arrive as a small convenience."* + +zone-engine's resolution is the precedent: *"The honest outcome is canon plus +offline conformance tooling, not an engine."* + +**5.4 gate-house is invisible to the estate, in both directions.** There is no +mention of gate-house or the ASM Canon anywhere in `net-kingdom/canon/`. +ops-warden's "NetKingdom Security Literacy" table enumerates every plane and +routes *"Policy decision — may actor X access resource Y"* to flex-auth; +gate-house does not appear. Conversely gate-house's own responsibility table +omits flex-auth, zone-engine, and info-tech-canon. The collision was unrecorded +on both sides, which is why it surfaced only now. + +**5.5 What is genuinely gate-house's, and unowned.** Removing the decision +point leaves substance with no other home: assistant vs autonomous as distinct +security regimes; the principal / actor / runtime-identity triple; mandates, +authority ceilings, and kill switches; the Change Dynamics Envelope; the MCP +doctrine that tool availability is not permission; the posture→authority +asymmetry shared with kings-guard; the ASM Canon itself; and the assurance +tests T-01…T-10 as specifications. + +## 6. The re-cut + +gate-house is the council where security and defence doctrine is established, +documented, taught, and supervised — the headquarters of the operational staff +that does the chores of IT security in NetKingdom. The name is retained. + +Boundary, in one line: + +> **The mandate and the operating mode are gate-house's. The decision is the +> authorization engine's. The credential is secrets-engine's. The perimeter is +> ops-mason's and ops-warden's.** + +**gate-house owns:** the authority context schema (principal / actor / runtime +/ tenant / mandate / task / mode) consumed by the authorization engine as input +claims; the invariants as canon, federated into `net-kingdom/canon/standards/`; +conformance review — whether an actor's actual authority matches its declared +mandate and ceiling; the assurance-test specifications, executed by +whitehat-security; and the security curriculum. + +**gate-house stops owning:** `/authorize`, the policy evaluation order, policy +engine selection, grant storage, and the revocation service. + +## 7. Two boundaries this clarifies + +**7.1 Policy authoring vs policy evaluation.** flex-auth today claims both +*"policy-as-code packages, tests, versions, and rollout"* and the evaluation +itself. Under the model these are different layers: authoring and governing +policy is Helpers work; evaluating it deterministically and in-path is Engine +work. This resolves the `FLEX-WP-0017` overlap constructively — designing the +approval contract (what must bind to an approval, what an authority ceiling +means) is gate-house; validating an approval at decision time is the engine's. + +**7.2 Doctrine vs runbook.** gate-house owns doctrine and curriculum; +ops-warden owns the lanes it stewards and their runbooks. That ops-warden had +to grow its own "Security Literacy" section is evidence the curriculum had no +owner. + +## 8. Risks and falsifiers + +- **HQ becomes a paper generator.** Doctrine no engine implements is fiction. + gate-house needs a conformance loop — it asserts invariants, whitehat tests + them, kings-guard observes, results return — or it fails as architecture + boards fail. +- **Workplan absorption.** An HQ that "manages the chores" drifts toward + hosting workplans for secrets-engine and ops-warden. ADR-007 and repo-manager + place work structure in the repo doing the work. gate-house sets doctrine and + reviews conformance; it must not become the second decision point in + management clothing. +- **The name argues against the role.** A gatehouse is where requests pass + through; it reads as an enforcement point. Historically it also housed the + guard and the porter's rules, so "where entry doctrine is set and the watch + is briefed" is defensible — but only if `INTENT.md` says so in the first + paragraph, or every reader re-derives the PDP misreading. + +## 9. Open questions, not decided here + +1. **Layer name.** "Helpers" is the working term; it undersells a layer holding + architecture, doctrine, controlling, and change. "Staff" — the general-staff + sense of plans and doctrine without execution — was proposed and fits the + kingdom metaphor. Undecided. +2. **flex-auth reframing.** Renaming to an `*-engine` form is agreed in + principle to make its layer and role legible. The specific name is open: + `auth-` is ambiguous between authentication and authorization, and key-cape + owns authentication, so `auth-engine` preserves the confusion the rename + should remove. `authz-engine` and `access-engine` were the alternatives + raised. **Sequence: reframe the INTENT first, rename second** — the rename + touches `FLEX-WP` prefix ownership, State Hub identifiers, ops-warden's + tables, zone-engine's binding boundary text, and secrets-engine + integrations, so it is a governed migration, not a `git mv`. +3. Whether the layer model itself is written into net-kingdom canon or + info-tech-canon. + +## 10. Consequences for existing gate-house artifacts + +- `INTENT.md` — major remake; the re-cut in §6 replaces the authority-plane + framing. +- `README.md` — the "observability … governance best practices" sentence is the + correct one and should lead. +- `ArchitectureBlueprint.md` — the component architecture (§10–11), policy + evaluation order (§13), API surface (§26), and storage model (§25) describe an + engine and do not survive the re-cut. The domain model (§6), canonical + authority context (§7), operating modes (§14–15), change dynamics (§20), MCP + integration (§19), and the security test program (§34) do. +- ADR-003 (policy engine selection) falls away; ADR-001, ADR-002, ADR-006, + ADR-009, ADR-010, ADR-013 and ADR-014 remain meaningful as contract and + doctrine. +- Milestones M0, M3, and M4 lapse. `GH-WP-0001-T04` (`/authorize` skeleton) + should not be built; `GH-WP-0001` needs rewriting against the re-cut before + it is promoted to active. + +## 11. Next steps + +1. Rewrite `gate-house/INTENT.md` against §6. +2. Write the decision record covering the layer model, the gate-house re-cut, + and the flex-auth reframing as three linked rulings — the second does not + hold without the first. +3. Adapt the other `INTENT.md` files that need clarification, and seek assent + from flex-auth and ops-warden for the boundaries in §7. +4. Rewrite `GH-WP-0001`; revise the Blueprint per §10.