From f4353fddbc28c865a95c241549c6bd50bcbcb646 Mon Sep 17 00:00:00 2001 From: tegwick Date: Fri, 28 Aug 2026 21:21:51 +0200 Subject: [PATCH 1/4] Rewrite README against the re-cut MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The README described the withdrawn engine framing and stated "Gate House authorizes", contradicting INTENT.md. It now leads with the Staff-layer doctrine council role, the layer model, and the INV-02 argument for why Gate House is not the decision point. Its one already-correct sentence — Gate House as observability for governed secrets under sound governance policy — is what the rewrite builds on. Flags the Blueprint as predating the re-cut so readers are not misled by it. Co-Authored-By: Claude Opus 5 Assistant: claude-code Assistant-Model: opus Assistant-Process: 2564823@bnt-lap001 Assistant-Session: 2a7ed827-4928-4b9f-8613-9135c9cadfe9 --- README.md | 744 +++++++++++------------------------------------------- 1 file changed, 154 insertions(+), 590 deletions(-) diff --git a/README.md b/README.md index b765ffb..7080f12 100644 --- a/README.md +++ b/README.md @@ -1,623 +1,187 @@ # Gate House -**Deterministic authority control system for human and agentic coding and operations.** +**The council where NetKingdom's security and defence doctrine is established, documented, taught, and supervised.** -Gate House is a NetKingdom security control-plane project and the reference implementation of the **Active Secrets Management (ASM) Plane**. +Gate House is a NetKingdom **Staff**-layer repository and the home of the +Active Secrets Management (ASM) Canon. It is the headquarters of the +operational staff that does the chores of IT security in NetKingdom. -Think of Gate House as observability for vault managed secrets based on sound governance policy best practices. +A word about the name, because it argues the other way. A gate house sounds +like the thing requests pass through. It is not. In a real castle the gate +house is where the guard is quartered, the watch is set, and the porter's rules +are posted — the rules of entry are decided there, and the gate itself is held +by someone else. -Its job is deliberately narrow: +> **Gate House does not stand in the gate. It decides what the gate is for, who +> may be asked to open it, and how we know it held.** -> **Gate House decides whether a human, workload, or agent is allowed to perform a requested action against a protected resource — under explicit, deterministic, auditable rules.** - -It does **not** replace an identity provider, secrets vault, policy engine, operations framework, or adaptive security system. It connects those responsibilities through a common authority model. +Its artifacts are specifications, decisions, workplans, and tasks. It holds no +runtime position, renders no authorization decision, and stores no state that +anything depends on at runtime. --- -## Why? +## Where it sits -Agentic development changes the operational risk profile of software engineering. - -Human-only development is naturally rate-limited by human execution. - -Interactive coding agents increase change velocity while a developer or operator remains actively involved. - -Autonomous agents remove much of that human friction entirely and therefore require explicit identities, mandates, authority ceilings, budgets, circuit breakers, and governance. - -At the same time, modern tooling such as MCP makes infrastructure capabilities increasingly easy for agents to discover and invoke. - -The central Gate House rule is therefore: - -> **Tool availability is not permission.** - -And more generally: - -> **Cognition may be probabilistic. Authority must be deterministically constrained.** - ---- - -## Core Architecture +NetKingdom's IT security is layered by determinism and by the kind of artifact +each layer produces — see +[`net-kingdom/canon/standards/security-layer-model_v0.1.md`](../net-kingdom/canon/standards/security-layer-model_v0.1.md). ```text - Cognitive Plane -┌──────────────────────────────────────────┐ -│ humans │ -│ LLMs / coding agents │ -│ operations agents │ -│ MCP / A2A │ -│ King's Guard │ -└───────────────────┬──────────────────────┘ - │ request - ▼ -══════════════════════════════════════════════ - GATE HOUSE -┌──────────────────────────────────────────┐ -│ principal │ -│ actor │ -│ tenant / environment │ -│ mandate / delegation │ -│ resource / action │ -│ policy │ -│ approval │ -│ posture │ -│ TTL / quotas / budgets │ -│ authority ceiling │ -└───────────────────┬──────────────────────┘ - │ GRANT / DENY - ▼ -══════════════════════════════════════════════ - Execution Plane -┌──────────────────────────────────────────┐ -│ Git / CI/CD │ -│ Kubernetes │ -│ cloud APIs │ -│ databases │ -│ SaaS / production services │ -└──────────────────────────────────────────┘ +Taxonomy cross-cutting language info-tech-canon, net-kingdom canon +Tooling deterministic state key-cape (authelia, lldap, privacy-idea), OpenBao +Engines deterministic APIs user / tenant / zone / secrets / access-engine +Staff interactive, non-deterministic gate-house, ops-mason, ops-warden, + kings-guard, whitehat-security ``` -A short version: +Read by determinism, those layers reproduce the Canon's three planes — which is +the point: > **Cognition proposes. Authority disposes. Infrastructure executes.** +The rule that binds every repository: + +> **Staff never touches Tooling directly. It acts only through Engine APIs.** + +## Why Gate House is not the decision point + +Gate House was seeded as a deterministic authority plane — an `/authorize` API, +grant storage, a revocation service. That was withdrawn on its own argument: + +> **A decision point inside Gate House would place the deterministic authority +> boundary inside the non-deterministic management layer, violating INV-02, "No +> Privilege from Cognition" — the first invariant this repository exists to +> defend.** + +NetKingdom already has a policy decision point: `access-engine` (currently +`flex-auth`). It stays the only one. Gate House writes the doctrine that +decision point implements, and checks that it did. + +The boundary, in one line: + +> **The mandate and the operating mode are Gate House's. The decision is +> access-engine's. The credential is secrets-engine's. The perimeter is +> ops-mason's and ops-warden's.** + --- -## What Gate House Owns +## What Gate House owns -Gate House owns the deterministic authority decision. +- **The doctrine** — the ASM Canon, its invariants, and the argument behind + them. Invariants graduate into `net-kingdom/canon/standards/`. +- **The authority context** — principal, actor, runtime identity, tenant, + environment, mandate, task, operating mode. Defined here, consumed by + access-engine as input claims. +- **The agentic operating modes** — assistant and autonomous as distinct + security regimes. +- **Mandates, authority ceilings, and kill switches** for autonomous actors, as + a model and a governance obligation. +- **The Change Dynamics Envelope** — how much change the organization tolerates. +- **The MCP doctrine** — tool availability is not permission. +- **The posture contract** with kings-guard, including its asymmetry. +- **Conformance review** — whether authority in practice matches the declared + mandate and ceiling. +- **The assurance specifications** T-01…T-10, executed by whitehat-security. +- **The security curriculum.** -It should answer questions such as: +## What Gate House does not own + +The authorization decision or any `/authorize` surface; policy engines, +packages, or rollout; grants, credentials, leases, or revocation; identity, +tenancy, zone, or user lifecycle; secret storage or PKI; anomaly detection or +threat intelligence; access lanes, SSH certificates, or host hardening; +deployment or remediation execution; and other repositories' workplans. + +| Component | Layer | Responsibility | +|---|---|---| +| info-tech-canon | Taxonomy | ecosystem-wide semantic contracts | +| net-kingdom | Taxonomy | NetKingdom standards of record | +| key-cape | Tooling | packaged identity tooling; IAM profile; authentication | +| OpenBao | Tooling | secret storage, leases, PKI | +| user-engine | Engine | users, accounts, memberships | +| tenant-engine | Engine | tenant-as-an-entity facts | +| zone-engine | Engine | zone identity and membership | +| secrets-engine | Engine | credential abstraction, custody, lifecycle | +| **access-engine** | Engine | **the decision — the only decision point** | +| **gate-house** | **Staff** | **doctrine, authority context, conformance, curriculum** | +| ops-mason | Staff | builds and tears down access routes and perimeters | +| ops-warden | Staff | operational access lanes, stewardship, runbooks | +| kings-guard | Staff | adaptive defence, observation, containment | +| whitehat-security | Staff | offensive validation | + +Two words that must not drift: **ops-warden and ops-mason own access lanes** — +how a worker reaches a host. **access-engine owns access rules** — whether they +may. + +--- + +## The doctrine in fifteen lines + +1. No privilege from cognition. +2. Every privileged action crosses a deterministic authority boundary. +3. Tool availability is not permission. +4. Principal and actor remain distinguishable. +5. Assistant and autonomous operation are different security modes. +6. Autonomous agents use independent identities and explicit mandates. +7. Authority is least-privileged, scoped, and time-bounded. +8. Delegation attenuates. +9. Security posture may reduce authority but must not expand it. +10. Emergency revocation works without agent cooperation. +11. Agents do not casually modify the policies defining their own ceiling. +12. Credentials are ephemeral implementation artifacts of authorization. +13. Audit evidence is protected from the actor being audited. +14. Failure of critical policy or authorization dependencies fails closed. +15. Production guarantees must survive incorrect agent behavior. + +## Agentic operating modes + +The distinction Gate House exists to keep sharp. + +**Assistant** — a human is engaged and can redirect or stop at human latency. +The human remains the principal; the agent remains a visible actor. *A human +disconnecting must never silently promote the session into autonomous +privileged operation.* + +**Autonomous** — a scheduled or triggered agent acts without supervision, and +therefore requires unique identity, a named owner, an explicit mandate, an +authority ceiling, runtime and concurrency limits, budgets, an independent kill +switch, and audit reconstruction. + +## The conformance loop + +Doctrine that no engine implements is fiction. Gate House is only real if this +turns: ```text -WHO - principal - actor - runtime identity - -WHERE - tenant - environment - resource - -WHAT - requested operation - -WHY - task - mandate - delegation - -UNDER WHICH CONDITIONS - policy - approval - posture - quotas - budgets - -UNTIL WHEN - TTL - -→ GRANT or DENY +gate-house asserts an invariant + → the engines implement it + → whitehat-security tries to break it + → kings-guard observes it in operation + → findings return to gate-house as doctrine change ``` -Gate House should provide: - -- deterministic authorization; -- principal/actor separation; -- delegation and attenuation; -- authority ceilings; -- tenant and environment constraints; -- task- and resource-scoped grants; -- short-lived authority; -- approval binding; -- posture-dependent restrictions; -- quotas and change-rate controls; -- independent circuit breakers; -- credential-binding integration; -- explainable decisions; -- protected audit evidence. - --- -## What Gate House Does Not Own +## Repository map -Gate House is intentionally **not** a security monolith. - -| System | Responsibility | +| Path | What it is | |---|---| -| **User Engine** | users, identities, memberships | -| **Tenant Engine** | tenant and organizational boundaries | -| **Key Cape** | authentication and federation | -| **Gate House** | deterministic authorization | -| **Secrets Engine** | credential abstraction and lifecycle orchestration | -| **OpenBao** | secret storage, PKI, leases, dynamic secret engines | -| **Ops Warden** | operational execution | -| **Ops Mason** | construction, reconciliation, recovery | -| **King's Guard** | adaptive security observation and response | -| **Whitehat Security** | adversarial testing and validation | +| [`INTENT.md`](INTENT.md) | why this repository exists; the re-cut in full | +| [`SCOPE.md`](SCOPE.md) | in scope / out of scope | +| [`spec/ActiveSecretsManagementCanon_v0.3.md`](spec/ActiveSecretsManagementCanon_v0.3.md) | the working canon — invariants, controls, profiles, assurance tests | +| [`ArchitectureBlueprint.md`](ArchitectureBlueprint.md) | architecture; **predates the re-cut and is being revised** | +| [`decisions/decisions.md`](decisions/decisions.md) | decision records — start with GH-DEC-2026-001 | +| [`history/`](history/) | reference notes; the 2026-08-28 review is the origin of the current shape | +| [`workplans/`](workplans/) | work in flight | -A useful shorthand: - -```text -User Engine identifies -Tenant Engine contextualizes -Key Cape authenticates -Gate House authorizes -Secrets Engine provisions -OpenBao protects -Ops Warden operates -Ops Mason constructs / restores -King's Guard observes / defends / adapts -Whitehat Security attacks / validates -``` +**Status.** Specification-only; no code, by design. `INTENT.md`, the decision +record, and the canon standard reflect the current shape. +`ArchitectureBlueprint.md` still describes the withdrawn engine framing in its +component, evaluation-order, API, and storage sections; its domain model, +operating modes, change dynamics, MCP integration, and test program survive. --- -## Agentic Operating Modes - -Gate House treats two agentic modes as distinct security regimes. - -### Agent Assistant Coding - -A human developer or operator remains actively engaged with the agent. - -```text -human principal - ↓ -assistant agent - ↓ -Gate House - ↓ -bounded delegated authority - ↓ -execution -``` - -The human remains the primary operational principal, but Gate House should preserve the agent as an actor where practical. - -A human session ending must not silently convert the workflow into privileged autonomy. - -### Autonomous Agent Coding - -A scheduled or triggered agent operates without continuous human supervision. - -```text -governance mandate - ↓ -agent/workload identity - ↓ -Gate House - ↓ -task-scoped authority - ↓ -execution -``` - -Autonomous agents require: - -- unique identity; -- named owner; -- explicit mandate; -- explicit authority ceiling; -- runtime limit; -- credential TTL; -- concurrency limit; -- token/compute/tool-call budgets; -- independent kill switch; -- audit trail; -- lifecycle termination. - ---- - -## Deterministic Security Substrate - -Gate House follows one non-negotiable design rule: - -> **No protected action succeeds merely because an intelligent system believes it should.** - -An LLM may decide: - -> "I should restart the production service." - -It may not decide: - -> "Therefore I am authorized to restart the production service." - -Authorization belongs to deterministic policy enforcement. - -That policy may be dynamic: - -```text -ALLOW production.restart -IF - actor.role == "operations-agent" -AND environment == "production" -AND service.team == actor.team -AND incident.status == "active" -AND approval.valid == true -AND approval.action == request.action -AND approval.target == request.target -AND now < approval.expiry -``` - -For the same authoritative input state, the result must be reproducible and auditable. - ---- - -## King's Guard Integration - -King's Guard is the adaptive security system around Gate House. - -King's Guard may detect: - -- anomalous tool usage; -- unexpected behavioral drift; -- compromised workloads; -- unusual change velocity; -- cross-tenant disturbance; -- declining confidence in an actor. - -It may then publish a bounded posture signal. - -Example: - -```text -actor: agent-934 -posture: DEGRADED -confidence: 0.72 -reason: anomalous-tool-usage -``` - -Gate House converts that posture into deterministic authority consequences: - -```text -IF posture == DEGRADED -THEN - deny production.write - allow production.read - require step_up for staging.write -``` - -Adaptive systems may automatically **reduce** authority. - -They must not probabilistically manufacture additional authority. - ---- - -## Secrets Engine and OpenBao Integration - -Gate House separates authorization from credential materialization. - -```text -agent requests DB read - │ - ▼ - Gate House - │ - GRANT SELECT - orders-prod - TTL 15m - │ - ▼ - Secrets Engine - │ - choose credential mechanism - │ - ▼ - OpenBao - │ - issue leased credential - │ - ▼ - execution gateway -``` - -The credential is an implementation artifact of the grant. - -This keeps organizational authorization outside the vault itself while still using OpenBao as the protected credential engine. - ---- - -## Domain Model - -Initial concepts: - -- **Principal** — who authority originates from; -- **Actor** — who attempts the action; -- **Runtime Identity** — concrete executing workload; -- **Mandate** — standing organizational authorization; -- **Delegation** — scoped transfer of authority; -- **Authority Ceiling** — maximum authority an actor can obtain; -- **Grant** — positive scoped authorization; -- **Denial** — negative authorization decision; -- **Approval** — independent authorization artifact; -- **Posture** — trusted security-state input; -- **Credential Binding** — mapping from grant to technical credential; -- **Decision Evidence** — audit record of why a decision occurred. - ---- - -## Example Authority Request - -Conceptually: - -```yaml -principal: - id: user:alice@example -actor: - id: agent:deploy-agent-22 -runtime: - id: spiffe://netkingdom/prod/deployer/22 - -tenant: tenant:acme -environment: production - -task: - id: release-7.2.1 - -request: - action: production.deploy - resource: cluster/payments - -mandate: - id: release-automation - -approval: - id: approval-9432 - -constraints: - ttl: 20m - max_mutations: 1 -``` - -Possible decision: - -```yaml -decision: GRANT -policy_version: authz-2026-08-24 - -authority: - action: production.deploy - resource: cluster/payments - expires_in: 20m - mutation_limit: 1 - -credential_binding: - type: aws-sts - provider: secrets-engine -``` - -The exact wire format is not fixed yet. - ---- - -## Change Dynamics - -Agentic systems change infrastructure faster than humans can. - -Gate House should therefore support a **Change Dynamics Envelope**. - -Potential dimensions: - -- concurrent mutating agents; -- maximum actions per grant; -- maximum resources per task; -- task duration; -- credential TTL; -- agent-chain depth; -- deployment frequency; -- destructive-action quota; -- token and compute spend; -- external-service spend; -- read/write separation. - -Budgets are useful blast-radius controls. - -They are not authorization. - ---- - -## Circuit Breakers - -Autonomous write authority should be independently suspendable. - -```text -NORMAL - ↓ -threshold / invariant violation - ↓ -AUTONOMOUS WRITE DISABLED - ↓ -READ / DIAGNOSE AVAILABLE - ↓ -STEP-UP / HUMAN INTERVENTION -``` - -When degraded, preserve observability before mutation authority. - ---- - -## Initial Reference Scenarios - -### 1. Human-Assisted Kubernetes Diagnostics - -A developer uses a coding agent to inspect production logs. - -- human principal retained; -- agent actor visible; -- read-only authority; -- short TTL; -- no mutation rights; -- auditable tool use. - -### 2. Autonomous Release Agent - -A scheduled agent deploys an approved release. - -- independent workload identity; -- release mandate; -- workload federation; -- production deployment only; -- no IAM modification; -- bounded runtime; -- complete audit chain. - -### 3. Dynamic Database Access - -An agent requests temporary `SELECT` access. - -- Gate House authorizes; -- Secrets Engine materializes; -- OpenBao generates leased credentials; -- credentials are kept outside LLM context; -- lease expires automatically. - -### 4. King's Guard Containment - -King's Guard marks an actor as degraded. - -- Gate House removes write authority; -- Ops Warden performs authorized containment; -- King's Guard verifies the result. - -### 5. Policy Self-Escalation - -An agent attempts to broaden its own permission boundary. - -- Gate House denies; -- event is audited; -- security telemetry may be forwarded to King's Guard. - ---- - -## Initial Implementation Areas - -The first prototype will likely need: - -```text -gate-house/ -├── api/ -│ ├── authorization-request -│ ├── decision -│ └── grant -├── domain/ -│ ├── principal -│ ├── actor -│ ├── mandate -│ ├── delegation -│ ├── authority -│ └── posture -├── policy/ -│ ├── engine -│ ├── policies -│ └── test -├── grants/ -│ ├── issuance -│ ├── ttl -│ └── revocation -├── approvals/ -├── limits/ -│ ├── quota -│ ├── budget -│ └── concurrency -├── integrations/ -│ ├── user-engine -│ ├── tenant-engine -│ ├── key-cape -│ ├── secrets-engine -│ ├── openbao -│ ├── kings-guard -│ └── ops-warden -├── audit/ -├── test/ -│ ├── deterministic -│ ├── adversarial -│ └── integration -└── docs/ -``` - -This is a direction, not yet a mandatory repository structure. - ---- - -## Design Principles - -1. **Small control plane, explicit boundaries.** -2. **Deterministic final authorization.** -3. **Least authority by default.** -4. **Principal and actor are not collapsed.** -5. **Delegation attenuates.** -6. **Credentials are implementation artifacts, not authority.** -7. **Short-lived authority beats standing privilege.** -8. **Tool discovery never implies authorization.** -9. **Adaptive security may restrict; it does not invent privilege.** -10. **Agents cannot casually edit their own authority ceiling.** -11. **Emergency controls do not depend on agent cooperation.** -12. **Security decisions are explainable and auditable.** -13. **Production guarantees must survive incorrect agent behavior.** - ---- - -## Non-Goals for the First Prototype - -The first implementation does not need to: - -- implement a new identity provider; -- replace OpenBao; -- implement a complete secrets manager; -- implement King's Guard; -- implement a general SIEM; -- perform anomaly detection; -- solve every cloud authorization model; -- become an IAM suite; -- invent a new policy language; -- support every agent protocol; -- provide autonomous remediation. - -It should prove that a clean deterministic authority plane can coordinate these systems. - ---- - -## Success - -Gate House succeeds when a developer can look at any privileged action and answer: - -> **Who acted? On whose behalf? Under which mandate? Against what resource? For what action? Under which policy and constraints? For how long? And why was it allowed?** - -And when the system can also prove: - -> **An agent could not have exceeded that authority merely by deciding to do so.** - ---- - -## Status - -Gate House is currently at the **reference architecture / research prototype** stage. - -The Active Secrets Management Canon provides the initial conceptual baseline. The next step is to turn the authority model into executable contracts, policy decisions, and end-to-end reference scenarios. - ---- - -## Motto - -> **Agents decide what to attempt. Gate House decides what may cross the boundary.** +> **Agents decide what to attempt. Engines decide what may cross the boundary. +> Gate House decides what the boundary is for.** From ebe603205984e95e7dbf9088ed267df59a4b4825 Mon Sep 17 00:00:00 2001 From: tegwick Date: Fri, 28 Aug 2026 21:22:51 +0200 Subject: [PATCH 2/4] Update CLAUDE.md for the re-cut MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The guidance still described Gate House as the deterministic authority plane and pointed agents at the Blueprint's component architecture and reference implementation layout — it would have actively misled the next session. - Lead with the re-cut and the INV-02 argument, and say plainly that any proposal having Gate House decide, store, evaluate, or enforce at request time is wrong regardless of how well built. - Add the decision record to the document hierarchy, above the Canon, and mark the Blueprint as partly withdrawn with the surviving sections named. - Reframe the invariants as doctrine Gate House authors rather than constraints on code it writes; add the Staff/Tooling rule as binding on this repo itself. - Record the normative demarcations: access lane vs access rule, doctrine vs runbook, control plane as Engine vocabulary. - Replace the implementation-layout guidance with where doctrine artifacts go, and note that T-01…T-10 are specifications executed by whitehat. Co-Authored-By: Claude Opus 5 Assistant: claude-code Assistant-Model: opus Assistant-Process: 2564823@bnt-lap001 Assistant-Session: 2a7ed827-4928-4b9f-8613-9135c9cadfe9 --- CLAUDE.md | 112 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 67 insertions(+), 45 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 1a41229..cadcaa6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -9,28 +9,38 @@ test runner, or dependency manifest — the repo is Markdown documents plus its baseline. Do not invent build/lint/test commands; if asked to "run tests", say there is nothing to run yet. The only commands that work today are the repo-manager ones below. -The first executable work is defined by milestone **M0** in the Blueprint (§41): a service -skeleton with `/authorize`, canonical request/decision schemas, static policy, and structured -audit output. +It is specification-only **by design**, not by earliness. Gate House is a Staff-layer +repository: its artifacts are specifications, decisions, workplans, and tasks. Do not +propose building a service here. Milestone M0 in the Blueprint (an `/authorize` skeleton) +has lapsed — see the re-cut below. ## What Gate House is -Gate House is the **deterministic authority plane** for NetKingdom — the reference -implementation of the Active Secrets Management (ASM) Plane. It answers exactly one question: +Gate House is the **council where NetKingdom's security and defence doctrine is +established, documented, taught, and supervised** — a **Staff**-layer repository in the +NetKingdom security layer model (`net-kingdom/canon/standards/security-layer-model_v0.1.md`). +It holds no runtime position and renders no authorization decision. -> may this principal/actor, in this tenant and environment, perform this action on this -> resource, under this mandate, with these constraints, until when → GRANT or DENY. +> **The mandate and the operating mode are Gate House's. The decision is access-engine's. +> The credential is secrets-engine's. The perimeter is ops-mason's and ops-warden's.** -The maxim that governs every design decision here: +**The re-cut (2026-08-28) is the single most important thing to know here.** Gate House was +seeded as a deterministic authority plane — `/authorize`, grant storage, revocation — and +that framing was withdrawn on its own argument: a decision point inside Gate House would put +the deterministic authority boundary inside the non-deterministic management layer, +violating INV-02, the first invariant this repo defends. `access-engine` (currently +`flex-auth`) is the only policy decision point in NetKingdom. + +Read `decisions/decisions.md` GH-DEC-2026-001 and +`history/2026-08-28-security-layer-model-and-gate-house-recut.md` before proposing any +architecture change. If a proposal has Gate House deciding, storing, evaluating, or +enforcing anything at request time, it is wrong regardless of how well it is built. + +The maxim that governs every design decision here — and, read across the layers, the +estate's layering rule: > **Cognition proposes. Authority disposes. Infrastructure executes.** -Gate House deliberately does **not** own identity lifecycle, tenancy lifecycle, -authentication, secret storage, PKI, anomaly detection, or execution. Those belong to sibling -NetKingdom systems (User Engine, Tenant Engine, Key Cape, Secrets Engine, OpenBao, Ops Warden, -Ops Mason, King's Guard, Whitehat Security). When a proposed feature starts absorbing one of -those responsibilities, that is a design error, not a scope extension. - ## Document hierarchy — read in this order 1. **`spec/ActiveSecretsManagementCanon_v0.3.md`** — the normative standard Gate House @@ -39,19 +49,23 @@ those responsibilities, that is a design error, not a scope extension. edited to accommodate Gate House. 2. **`INTENT.md`** — mission, scope boundaries, domain concepts, the 15 numbered Core Rules, use cases `UC-01`…`UC-05`, success criteria. This is the "why". -3. **`ArchitectureBlueprint.md`** — the "how". Domain model (§6), canonical authorization - request (§7) and decision (§8), component architecture (§10–11), policy evaluation order - (§13), integration contracts (§16–19), failure modes (§28), API surface (§26), ADR backlog - (§40), milestones M0–M8 (§41), architectural invariants `A-01`…`A-15` (§43). -4. **`README.md`** — public-facing summary. Keep it consistent with the above; it is a - derivative, not a source of truth. +3. **`decisions/decisions.md`** — decision records. GH-DEC-2026-001 ratifies the layer + model, the re-cut, and the access-engine reframing. Binding. +4. **`ArchitectureBlueprint.md`** — **predates the re-cut and is only partly valid.** Its + component architecture (§10–11), policy evaluation order (§13), API surface (§26), and + storage model (§25) describe an engine and are withdrawn; ADR-003 and milestones M0, M3, + M4 have lapsed. Its domain model (§6), authority context (§7), operating modes (§14–15), + change dynamics (§20), MCP integration (§19), and security test program (§34) survive. + Do not cite it without checking a section against INTENT first. +5. **`README.md`** — public-facing summary. A derivative, not a source of truth. -When these conflict, the Canon wins over INTENT, and INTENT wins over the Blueprint. Fix the -lower document rather than diverging. +When these conflict: the decision record wins over everything, then the Canon, then INTENT, +then the Blueprint. Fix the lower document rather than diverging. -## Invariants that constrain any implementation +## The doctrine Gate House maintains -These are load-bearing. Code or design that violates one is wrong even if it works: +These are load-bearing. Gate House authors and maintains them; the engines and Staff +repositories implement them. A document or proposal that violates one is wrong: - **No privilege from cognition.** An LLM deciding an action is appropriate never makes it authorized. The final privilege boundary is deterministic policy. @@ -63,10 +77,10 @@ These are load-bearing. Code or design that violates one is wrong even if it wor - **Posture may only restrict.** King's Guard (or any adaptive input) can reduce authority or demand step-up; it can never manufacture privilege. See Blueprint §16.2 for the explicitly forbidden pattern. -- **Evaluation is monotonic toward restriction** (Blueprint §13). No stage after the authority - ceiling may expand beyond it. +- **Evaluation is monotonic toward restriction.** No stage after the authority ceiling may + expand beyond it. (Evaluation itself is access-engine's; Gate House states the property.) - **Fail closed.** Unavailable policy engine, unresolvable context, unavailable audit, or - stale authoritative state → DENY. Per-dependency semantics are in Blueprint §28. + stale authoritative state → DENY. - **Assistant mode and Autonomous mode are different security regimes.** A human session ending must never silently promote the workflow to privileged autonomy. - **Agents cannot edit their own authority ceiling**; policy self-modification is a separately @@ -76,6 +90,8 @@ These are load-bearing. Code or design that violates one is wrong even if it wor - **Credentials are implementation artifacts of a grant**, materialized by Secrets Engine / OpenBao *after* authority exists — never the source of authority, never placed in model context. +- **Staff never touches Tooling directly.** It acts only through Engine APIs. This binds + Gate House itself: no direct database, OpenBao, or cluster client belongs in this repo. ## Repo-manager registration @@ -100,30 +116,36 @@ the file, commit, then sync. `SCOPE.md` is derived from `INTENT.md` — keep the ADRs (`ADR-nnn`), and milestones (`M0`–`M8`) are referenced across documents. Reuse the existing id when writing about a concept; append rather than renumber. - **Canon prose is normative** — preserve MUST/SHOULD/MAY exactly when editing it. -- **Domain vocabulary is fixed** by Blueprint §6 and INTENT's Domain Concepts: principal, - actor, runtime identity, tenant, environment, mandate, delegation, authority ceiling, - action, resource, grant, denial, approval, posture, credential binding, decision evidence. - Use these terms rather than synonyms ("user", "role", "token", "permission"). +- **Domain vocabulary is fixed** by INTENT's Domain Vocabulary: principal, actor, runtime + identity, mandate, delegation, authority ceiling, operating mode, posture, change dynamics + envelope, decision evidence. Use these rather than synonyms ("user", "role", "token", + "permission"). Two demarcations are normative: **access lane** (ops-warden, ops-mason) is + not **access rule** (access-engine); **doctrine** (gate-house) is not **runbook** (the lane + owner). "Control plane" is Engine vocabulary — do not apply it to Gate House. - Documents carry a frontmatter-style header block (Repository / Project family / Status / Version / Date). Keep it, and bump Status/Version/Date on substantive edits. - Diagrams and schema examples are plain ```text``` or ```yaml``` fenced blocks — no Mermaid. -- Decision types are the four in Blueprint §9: `GRANT`, `DENY`, `REQUIRE_APPROVAL`, `DEFER`. +- Decision types are `GRANT`, `DENY`, `REQUIRE_APPROVAL`, `DEFER` — rendered by + access-engine, named here. ## Where new work goes - `README.md`, `INTENT.md`, and `ArchitectureBlueprint.md` live at the repo root, matching the Blueprint's own reference layout (§32). External standards Gate House conforms to — the Canon — live in `spec/`. -- ADRs → `docs/adr/`, drawn from the backlog in Blueprint §40 (ADR-001 through ADR-014). -- Implementation, when it starts, should follow the reference layout in Blueprint §32 - (`api/`, `domain/`, `policy/`, `grants/`, `approvals/`, `limits/`, `integrations/`, `audit/`, - `test/{unit,integration,adversarial,scenarios}`, `deploy/`). That layout is explicitly - labelled a direction, not a constraint — deviate deliberately and say why. -- Technology is intentionally unfixed (Blueprint §31): HTTP/JSON first, OPA/Rego or Cedar as - policy candidates, PostgreSQL for grants/mandates/revocation, OIDC + SPIFFE/SPIRE for - identity. Do not hard-code a choice into the conceptual model — the domain model must not - depend on one policy engine. -- Adversarial tests are a first-class deliverable, not an afterthought: Canon `T-01`…`T-10` - and Blueprint §34 (malicious model, prompt injection, human disconnect, policy - self-modification, approval replay, cross-tenant, MCP token passthrough, audit loss, - circuit breaker). +- ADRs → `docs/adr/`, from the Blueprint §40 backlog. ADR-003 (policy engine selection) has + lapsed with the re-cut; ADR-001, ADR-002, ADR-006, ADR-009, ADR-010, ADR-013, ADR-014 + remain meaningful as contract and doctrine. +- Decision records → `decisions/decisions.md`, via `rmgr decision create|resolve`. Never + hand-write the YAML block; the tool mints identifiers and commits. +- History and reference notes → `history/YYYY-MM-DD-.md`, matching the convention in + ops-warden, zone-engine, and secrets-engine. +- Doctrine that stabilizes graduates into `net-kingdom/canon/standards/`, owned by gate-house + and published by net-kingdom. `security-layer-model_v0.1.md` is the first. +- **No implementation layout.** Blueprint §32's reference tree (`api/`, `policy/`, `grants/`, + `deploy/`, …) described the withdrawn engine and does not apply. If work here starts + producing services, schemas that resolve, or anything evaluated at request time, stop — + that belongs to an engine. +- Assurance tests `T-01`…`T-10` are **specifications** authored here and executed by + whitehat-security. Writing the specification is Gate House's job; running the attack and + judging whether the control held is not. From e9f29e65513bcb3b1f9a4f6039f1a1725785eefe Mon Sep 17 00:00:00 2001 From: tegwick Date: Fri, 28 Aug 2026 21:23:32 +0200 Subject: [PATCH 3/4] Mark the Blueprint as partly withdrawn MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The blueprint predates the re-cut and describes Gate House as a running engine. Rather than delete it, mark it — the estate's precedent (zone-engine) is to retain superseded argument as design history. Adds a status banner with a per-section table separating what survives (domain model, authority context, operating modes, posture and credential contracts, MCP doctrine, change dynamics, audit, test program, architectural invariants) from what is withdrawn (component and policy architecture, evaluation order, storage, API surface, caching, deployment, technology direction, reference repository layout, performance, availability, admin interfaces) and what has lapsed (ADR-003; milestones M0, M3, M4). Inline markers on the eight sections most likely to be cited. A revision folding the surviving material into doctrine form is outstanding. Co-Authored-By: Claude Opus 5 Assistant: claude-code Assistant-Model: opus Assistant-Process: 2564823@bnt-lap001 Assistant-Session: 2a7ed827-4928-4b9f-8613-9135c9cadfe9 --- ArchitectureBlueprint.md | 65 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 63 insertions(+), 2 deletions(-) diff --git a/ArchitectureBlueprint.md b/ArchitectureBlueprint.md index bf9d727..79fa295 100644 --- a/ArchitectureBlueprint.md +++ b/ArchitectureBlueprint.md @@ -3,9 +3,46 @@ **Repository:** `gate-house` **Project family:** NetKingdom **Artifact:** `ArchitectureBlueprint.md` -**Status:** Initial architecture blueprint +**Status:** Partly withdrawn — see the status banner below **Version:** 0.1 -**Date:** 2026-08-24 +**Date:** 2026-08-24 +**Reviewed:** 2026-08-28 (GH-DEC-2026-001) + +--- + +--- + +> ## ⚠ Status: partly withdrawn — 2026-08-28 +> +> This blueprint predates the Gate House re-cut and describes a deterministic +> authority plane: a policy decision point with an `/authorize` API, grant +> storage, and a revocation service. **That framing was withdrawn** by +> `decisions/decisions.md` GH-DEC-2026-001, on the ground that a decision point +> inside Gate House would place the deterministic authority boundary inside the +> non-deterministic management layer, violating INV-02. `access-engine` +> (currently `flex-auth`) is the only policy decision point in NetKingdom. +> +> The engine-describing sections are retained as **design history**, not as +> direction. Do not build from them, and check any section against `INTENT.md` +> before citing it. +> +> | Sections | Status | +> |---|---| +> | §6 domain model, §7 authority context | **survives** — now the authority context consumed by access-engine | +> | §14–15 operating modes | **survives** — assistant and autonomous as security regimes | +> | §16 posture, §17 credential separation | **survives** as contracts with kings-guard and secrets-engine | +> | §19 MCP integration, §20 change dynamics, §21 circuit breakers | **survives** as doctrine | +> | §23 policy self-modification, §24 audit architecture | **survives** as doctrine | +> | §34 security test program, §43 architectural invariants | **survives** — §34 as specifications executed by whitehat-security | +> | §8–9 decision schema and types | **moves** — the vocabulary stands, ownership is access-engine's | +> | §10–13 component architecture, policy architecture, evaluation order | **withdrawn** | +> | §25 storage, §26 API surface, §29 caching, §30 deployment | **withdrawn** | +> | §31 technology direction, §32 reference repository structure | **withdrawn** | +> | §35 performance, §36 availability, §38 administrative interfaces | **withdrawn** | +> | §40 ADR-003 (policy engine selection) | **lapsed** | +> | §41 milestones M0, M3, M4 | **lapsed** | +> +> A revision folding the surviving material into doctrine form is outstanding. --- @@ -626,6 +663,9 @@ A request must not be allowed to cross a privileged boundary while unresolved. # 10. Internal Component Architecture +> **Withdrawn 2026-08-28** (GH-DEC-2026-001). Retained as design history: this describes Gate House as a running engine. The decision point is `access-engine`. + + ```mermaid flowchart LR API[Authorization API] @@ -668,6 +708,9 @@ flowchart LR # 11. Component Responsibilities +> **Withdrawn 2026-08-28** (GH-DEC-2026-001). Retained as design history: this describes Gate House as a running engine. The decision point is `access-engine`. + + ## 11.1 Authorization API Responsibilities: @@ -877,6 +920,9 @@ Audit storage should be independently controlled. # 12. Policy Architecture +> **Withdrawn 2026-08-28** (GH-DEC-2026-001). Retained as design history: this describes Gate House as a running engine. The decision point is `access-engine`. + + Gate House should separate policy into layers. ## 12.1 Baseline Invariants @@ -956,6 +1002,9 @@ Constrains: # 13. Policy Evaluation Order +> **Withdrawn 2026-08-28** (GH-DEC-2026-001). Retained as design history: this describes Gate House as a running engine. The decision point is `access-engine`. + + A simple initial evaluation order is desirable. ```text @@ -1482,6 +1531,9 @@ The first implementation may use ordinary storage but should preserve the interf # 25. Data Storage +> **Withdrawn 2026-08-28** (GH-DEC-2026-001). Retained as design history: this describes Gate House as a running engine. The decision point is `access-engine`. + + Gate House should minimize durable sensitive state. ## 25.1 Durable State @@ -1512,6 +1564,9 @@ Credential material belongs in Secrets Engine/OpenBao or equivalent backends. # 26. API Surface +> **Withdrawn 2026-08-28** (GH-DEC-2026-001). Retained as design history: this describes Gate House as a running engine. The decision point is `access-engine`. + + Initial APIs should remain small. ## 26.1 Authorization @@ -1751,6 +1806,9 @@ Gate House itself should authenticate downstream services using workload identit # 31. Technology Direction +> **Withdrawn 2026-08-28** (GH-DEC-2026-001). Retained as design history: this describes Gate House as a running engine. The decision point is `access-engine`. + + The architecture should remain implementation-neutral initially. Potential choices: @@ -1797,6 +1855,9 @@ Potential: # 32. Reference Repository Structure +> **Withdrawn 2026-08-28** (GH-DEC-2026-001). Retained as design history: this describes Gate House as a running engine. The decision point is `access-engine`. + + ```text gate-house/ ├── README.md From 81f9fce82b5d7cf70ac77ce3a91bf149e2b6ff06 Mon Sep 17 00:00:00 2001 From: repo-manager Date: Fri, 28 Aug 2026 21:24:07 +0200 Subject: [PATCH 4/4] repo.work.update_workplan GH-WP-0001 (update) correlation_id: a1e9a76e-93d5-4bcb-a843-56e168041b26 reason: rmgr CLI source: repo-manager Assistant: claude-code Assistant-Model: opus Assistant-Process: 2564823@bnt-lap001 Assistant-Session: 2a7ed827-4928-4b9f-8613-9135c9cadfe9 --- workplans/GH-WP-0001-foundation.md | 57 +++++++++++++++++++----------- 1 file changed, 37 insertions(+), 20 deletions(-) diff --git a/workplans/GH-WP-0001-foundation.md b/workplans/GH-WP-0001-foundation.md index e1684bd..d351212 100644 --- a/workplans/GH-WP-0001-foundation.md +++ b/workplans/GH-WP-0001-foundation.md @@ -4,56 +4,68 @@ type: workplan title: "Foundation" domain: infotech repo: gate-house -status: proposed +status: active state_hub_workstream_id: "2ec4cf1a-a73f-5793-9738-8d8019cccca8" +updated: "2026-08-28" --- # Foundation -Establish the repository baseline and reach milestone **M0 — Executable Skeleton** -as defined in `ArchitectureBlueprint.md` §41: a request must produce a -deterministic `GRANT` / `DENY` with structured audit evidence. +Establish Gate House as the Staff-layer doctrine council: the layer model in +canon, the re-cut recorded, the authority context published as a contract +access-engine consumes, and the conformance loop turning. + +Rewritten 2026-08-28 against `decisions/decisions.md` GH-DEC-2026-001. The +previous plan targeted Blueprint milestone **M0** — an `/authorize` skeleton — +which lapsed with the re-cut. No service is built in this repository. ```task id: GH-WP-0001-T01 -status: todo +status: done priority: high state_hub_task_id: "af0fa778-89a8-52cf-a73a-021082a98cad" ``` Establish the repository baseline: classification, scope, agent instructions, -workplan spine. +workplan spine. Done — `rmgr conform` passes with no findings. ```task id: GH-WP-0001-T02 -status: todo +status: done priority: high state_hub_task_id: "6dd21d86-6546-58a7-b59e-fa1db72aae90" ``` -Record the early ADRs that gate implementation choices — ADR-001 canonical -authority request schema, ADR-002 principal/actor/runtime identity model, -ADR-003 policy engine selection. Backlog in `ArchitectureBlueprint.md` §40. +Settle the boundary with access-engine and the security estate, and record it. +Done — the review is in `history/2026-08-28-security-layer-model-and-gate-house-recut.md`, +the ruling in GH-DEC-2026-001, and the model in +`net-kingdom/canon/standards/security-layer-model_v0.1.md` (proposed). ```task id: GH-WP-0001-T03 -status: todo +status: progress priority: high state_hub_task_id: "12f651be-1c07-587b-a781-4472e189e218" ``` -Define the canonical authorization request and decision schemas from -`ArchitectureBlueprint.md` §7 and §8. +Obtain assent for the two boundaries that move vocabulary away from repositories +currently using it: flex-auth (Engine framing, rename, authoring/evaluation +split — INTENT reframed, rename outstanding) and kings-guard plus ops-warden +("control plane" and the security curriculum). Promote the standard from +`proposed` to `accepted` once assent lands. ```task id: GH-WP-0001-T04 status: todo -priority: medium +priority: high state_hub_task_id: "7903d142-9763-5b3f-839d-2a1599130a2b" ``` -Implement the `/authorize` service skeleton with static policy and the -evaluation order in `ArchitectureBlueprint.md` §13, monotonic toward restriction. +Publish the **authority context** as a contract: principal, actor, runtime +identity, tenant, environment, mandate, task, operating mode — the vocabulary +access-engine consumes as input claims alongside verified identity claims. +Record it as ADR-001 and ADR-002. This is the deliverable that makes the +doctrine consumable rather than descriptive. ```task id: GH-WP-0001-T05 @@ -62,8 +74,11 @@ priority: medium state_hub_task_id: "010e3162-cab1-5644-b262-b0d1d7d676f8" ``` -Emit structured decision evidence for every authorization call, per -`ArchitectureBlueprint.md` §24. +Revise `ArchitectureBlueprint.md`: fold the surviving material — domain model, +authority context, operating modes, posture and credential contracts, MCP +doctrine, change dynamics, audit, architectural invariants — into doctrine form, +and retire the withdrawn sections from the working document into design history. +Currently marked in place with a status banner. ```task id: GH-WP-0001-T06 @@ -72,5 +87,7 @@ priority: medium state_hub_task_id: "8cc018e1-2787-5435-9c2c-c2b01cf75ae4" ``` -Seed the adversarial test suite with the fail-closed and self-escalation cases -(Canon T-04, T-09; `ArchitectureBlueprint.md` §34.4, §34.8). +Close the conformance loop. Hand the assurance specifications T-01…T-10 to +whitehat-security as executable targets, agree the posture and findings return +path with kings-guard, and establish how conformance review reports back. Until +this turns, Gate House is a paper generator by its own falsifier.