diff --git a/ArchitectureBlueprint.md b/ArchitectureBlueprint.md index 79fa295..bf9d727 100644 --- a/ArchitectureBlueprint.md +++ b/ArchitectureBlueprint.md @@ -3,46 +3,9 @@ **Repository:** `gate-house` **Project family:** NetKingdom **Artifact:** `ArchitectureBlueprint.md` -**Status:** Partly withdrawn — see the status banner below +**Status:** Initial architecture blueprint **Version:** 0.1 -**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. +**Date:** 2026-08-24 --- @@ -663,9 +626,6 @@ 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] @@ -708,9 +668,6 @@ 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: @@ -920,9 +877,6 @@ 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 @@ -1002,9 +956,6 @@ 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 @@ -1531,9 +1482,6 @@ 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 @@ -1564,9 +1512,6 @@ 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 @@ -1806,9 +1751,6 @@ 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: @@ -1855,9 +1797,6 @@ 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 cadcaa6..1a41229 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -9,38 +9,28 @@ 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. -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. +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. ## What Gate House is -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. +Gate House is the **deterministic authority plane** for NetKingdom — the reference +implementation of the Active Secrets Management (ASM) Plane. It answers exactly one question: -> **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.** +> 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 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: +The maxim that governs every design decision here: > **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 @@ -49,23 +39,19 @@ estate's layering rule: 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. **`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. +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. -When these conflict: the decision record wins over everything, then the Canon, then INTENT, -then the Blueprint. Fix the lower document rather than diverging. +When these conflict, the Canon wins over INTENT, and INTENT wins over the Blueprint. Fix the +lower document rather than diverging. -## The doctrine Gate House maintains +## Invariants that constrain any implementation -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: +These are load-bearing. Code or design that violates one is wrong even if it works: - **No privilege from cognition.** An LLM deciding an action is appropriate never makes it authorized. The final privilege boundary is deterministic policy. @@ -77,10 +63,10 @@ repositories implement them. A document or proposal that violates one is wrong: - **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.** No stage after the authority ceiling may - expand beyond it. (Evaluation itself is access-engine's; Gate House states the property.) +- **Evaluation is monotonic toward restriction** (Blueprint §13). No stage after the authority + ceiling may expand beyond it. - **Fail closed.** Unavailable policy engine, unresolvable context, unavailable audit, or - stale authoritative state → DENY. + stale authoritative state → DENY. Per-dependency semantics are in Blueprint §28. - **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 @@ -90,8 +76,6 @@ repositories implement them. A document or proposal that violates one is wrong: - **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 @@ -116,36 +100,30 @@ 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 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. +- **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"). - 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 `GRANT`, `DENY`, `REQUIRE_APPROVAL`, `DEFER` — rendered by - access-engine, named here. +- Decision types are the four in Blueprint §9: `GRANT`, `DENY`, `REQUIRE_APPROVAL`, `DEFER`. ## 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/`, 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. +- 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). diff --git a/README.md b/README.md index 7080f12..b765ffb 100644 --- a/README.md +++ b/README.md @@ -1,187 +1,623 @@ # Gate House -**The council where NetKingdom's security and defence doctrine is established, documented, taught, and supervised.** +**Deterministic authority control system for human and agentic coding and operations.** -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. +Gate House is a NetKingdom security control-plane project and the reference implementation of the **Active Secrets Management (ASM) Plane**. -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. +Think of Gate House as observability for vault managed secrets based on sound governance policy best practices. -> **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.** +Its job is deliberately narrow: -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. +> **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. --- -## Where it sits +## Why? -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). +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 ```text -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 + 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 │ +└──────────────────────────────────────────┘ ``` -Read by determinism, those layers reproduce the Canon's three planes — which is -the point: +A short version: > **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 -- **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.** +Gate House owns the deterministic authority decision. -## 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: +It should answer questions such as: ```text -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 +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 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 + +Gate House is intentionally **not** a security monolith. + +| System | Responsibility | +|---|---| +| **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 | + +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 ``` --- -## Repository map +## Agentic Operating Modes -| Path | What it is | -|---|---| -| [`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 | +Gate House treats two agentic modes as distinct security regimes. -**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. +### 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. --- -> **Agents decide what to attempt. Engines decide what may cross the boundary. -> Gate House decides what the boundary is for.** +## 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.** diff --git a/workplans/GH-WP-0001-foundation.md b/workplans/GH-WP-0001-foundation.md index d351212..e1684bd 100644 --- a/workplans/GH-WP-0001-foundation.md +++ b/workplans/GH-WP-0001-foundation.md @@ -4,68 +4,56 @@ type: workplan title: "Foundation" domain: infotech repo: gate-house -status: active +status: proposed state_hub_workstream_id: "2ec4cf1a-a73f-5793-9738-8d8019cccca8" -updated: "2026-08-28" --- # Foundation -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. +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. ```task id: GH-WP-0001-T01 -status: done +status: todo priority: high state_hub_task_id: "af0fa778-89a8-52cf-a73a-021082a98cad" ``` Establish the repository baseline: classification, scope, agent instructions, -workplan spine. Done — `rmgr conform` passes with no findings. +workplan spine. ```task id: GH-WP-0001-T02 -status: done +status: todo priority: high state_hub_task_id: "6dd21d86-6546-58a7-b59e-fa1db72aae90" ``` -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). +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. ```task id: GH-WP-0001-T03 -status: progress +status: todo priority: high state_hub_task_id: "12f651be-1c07-587b-a781-4472e189e218" ``` -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. +Define the canonical authorization request and decision schemas from +`ArchitectureBlueprint.md` §7 and §8. ```task id: GH-WP-0001-T04 status: todo -priority: high +priority: medium state_hub_task_id: "7903d142-9763-5b3f-839d-2a1599130a2b" ``` -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. +Implement the `/authorize` service skeleton with static policy and the +evaluation order in `ArchitectureBlueprint.md` §13, monotonic toward restriction. ```task id: GH-WP-0001-T05 @@ -74,11 +62,8 @@ priority: medium state_hub_task_id: "010e3162-cab1-5644-b262-b0d1d7d676f8" ``` -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. +Emit structured decision evidence for every authorization call, per +`ArchitectureBlueprint.md` §24. ```task id: GH-WP-0001-T06 @@ -87,7 +72,5 @@ priority: medium state_hub_task_id: "8cc018e1-2787-5435-9c2c-c2b01cf75ae4" ``` -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. +Seed the adversarial test suite with the fail-closed and self-escalation cases +(Canon T-04, T-09; `ArchitectureBlueprint.md` §34.4, §34.8).