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