diff --git a/ArchitectureBlueprint.md b/ArchitectureBlueprint.md index 79fa295..d9e480c 100644 --- a/ArchitectureBlueprint.md +++ b/ArchitectureBlueprint.md @@ -1,2573 +1,622 @@ -# Gate House — Architecture Blueprint +# Gate House — Architecture Doctrine Blueprint -**Repository:** `gate-house` -**Project family:** NetKingdom -**Artifact:** `ArchitectureBlueprint.md` -**Status:** Partly withdrawn — see the status banner below -**Version:** 0.1 -**Date:** 2026-08-24 -**Reviewed:** 2026-08-28 (GH-DEC-2026-001) +**Repository:** `gate-house` +**Project family:** NetKingdom +**Artifact:** `ArchitectureBlueprint.md` +**Status:** Current — doctrine architecture; no runtime role +**Version:** 0.2 +**Date:** 2026-09-01 +**Decision:** `decisions/decisions.md` GH-DEC-2026-001 --- ---- +## 1. Purpose and authority -> ## ⚠ 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. +This document describes the architecture of NetKingdom security doctrine: the +responsibility boundaries, semantic contracts, invariants, and conformance +loop Gate House maintains. It does not specify a Gate House service. Gate House +has no request-time position, stores no runtime state, and renders no +authorization decision. ---- +The v0.1 Blueprint described Gate House as a deterministic authority plane. +That design was withdrawn by GH-DEC-2026-001 because it put the deterministic +decision point inside a non-deterministic Staff repository. Its disposition is +recorded in +[`history/2026-09-01-authority-plane-blueprint-retirement.md`](history/2026-09-01-authority-plane-blueprint-retirement.md), +and the complete historical text remains available at Git object +`75ce372:ArchitectureBlueprint.md`. -## 1. Purpose +This document is subordinate, in order, to: -This document translates the Gate House intent into a practical architecture for a first reference implementation. +1. `decisions/decisions.md`; +2. `spec/ActiveSecretsManagementCanon_v0.3.md`; +3. `INTENT.md`; +4. the accepted NetKingdom security-layer standard. -Gate House is the **deterministic authority plane** for human, workload, and agent-active NetKingdom environments. It is the reference implementation of the Active Secrets Management (ASM) Plane. - -Its central responsibility is: - -> **Decide whether a requested action is allowed, under explicit and reproducible rules, and represent that decision as bounded authority that downstream systems can enforce.** - -Gate House does not replace identity systems, secrets backends, policy engines, runtime execution systems, or adaptive security systems. It coordinates them around a canonical authority model. +Where they conflict, the higher artifact wins and this Blueprint must be +corrected. The architectural maxim is: > **Cognition proposes. Authority disposes. Infrastructure executes.** ---- +## 2. Architectural shape -# 2. Architectural Goals - -Gate House should optimize for the following properties. - -## 2.1 Deterministic final authorization - -The final decision to grant or deny protected authority must be made by deterministic mechanisms. - -LLMs, agents, probabilistic classifiers, or adaptive systems may contribute context or request actions, but they must not be able to manufacture authority by themselves. - -## 2.2 Explicit identity chain - -The system should distinguish: - -- the **principal** on whose behalf authority originates; -- the **actor** directly requesting or performing the action; -- the **runtime identity** of the executing workload; -- the **tenant** and organizational context; -- the **mandate** or delegated purpose under which the action is attempted. - -## 2.3 Least authority - -Authority should be: - -- task-scoped; -- action-scoped; -- resource-scoped; -- tenant-scoped; -- environment-scoped; -- time-bounded; -- quota-bounded where appropriate. - -## 2.4 Short-lived authority - -Standing credentials and standing privilege should be minimized. - -Gate House should prefer issuance of short-lived authorization grants and rely on the Secrets Engine/OpenBao or cloud-native STS mechanisms to materialize them as short-lived credentials where necessary. - -## 2.5 Explicit agentic operating modes - -The system must support and distinguish: - -- **Agent Assistant Coding** — human-supervised; -- **Autonomous Agent Coding** — independently operating under explicit mandate. - -The transition from Assistant to Autonomous mode is an explicit governance event. - -## 2.6 Safe autonomy - -Autonomous agents must be independently stoppable. - -Gate House should support deterministic: - -- expiry; -- revocation; -- concurrency limits; -- action quotas; -- environment restrictions; -- circuit breakers; -- step-up authorization. - -## 2.7 Explainability and evidence - -Every material authorization decision should be reconstructable: - -> Who acted? On whose behalf? Under which mandate? Against which resource? For which action? Under which policy and constraints? For how long? And why was it allowed or denied? - -## 2.8 Composability - -Gate House should be a small control plane with explicit integration contracts. - -It should avoid becoming: - -- an IAM suite; -- another secret manager; -- a SIEM; -- an incident platform; -- a workflow engine; -- an agent runtime. - ---- - -# 3. Non-Goals - -The first Gate House implementation will not attempt to: - -- replace OpenBao; -- replace Key Cape; -- replace User Engine; -- replace Tenant Engine; -- implement King's Guard; -- implement a general secrets scanner; -- implement a general policy language; -- implement a general-purpose workflow engine; -- implement full cloud IAM abstraction; -- implement autonomous remediation; -- become the system of record for every security policy in NetKingdom. - -Its job is to provide the deterministic authority contract connecting these systems. - ---- - -# 4. System Context - -```mermaid -flowchart TB - H[Human Developer / Operator] - AA[Assistant Agent] - AU[Autonomous Agent] - KG[King's Guard] - KC[Key Cape] - UE[User Engine] - TE[Tenant Engine] - - GH[Gate House] - - SE[Secrets Engine] - OB[OpenBao] - OW[Ops Warden] - OM[Ops Mason] - - K8S[Kubernetes] - CLOUD[Cloud APIs] - DB[Databases] - GIT[Git / CI/CD] - SAAS[SaaS / External APIs] - - WH[Whitehat Security] - AUD[Audit / Evidence Store] - - H --> KC - KC --> GH - UE --> GH - TE --> GH - - H --> AA - AA --> GH - AU --> GH - - KG --> GH - - GH --> SE - SE --> OB - - GH --> OW - GH --> OM - - OW --> K8S - OW --> CLOUD - OW --> DB - OM --> K8S - OM --> CLOUD - - GH --> GIT - GH --> SAAS - - GH --> AUD - KG --> AUD - OW --> AUD - OM --> AUD - - WH --> GH - WH --> KG -``` - ---- - -# 5. Three-Plane Model - -Gate House is easiest to reason about as the center of three planes. - -## 5.1 Cognitive Plane - -The Cognitive Plane determines what might usefully happen next. - -Examples: - -- humans; -- LLMs; -- coding agents; -- operations agents; -- planners; -- MCP clients; -- A2A agents; -- King's Guard risk analysis. - -The Cognitive Plane can request authority. - -It cannot grant authority. - -## 5.2 Authority Plane - -Gate House belongs to the Authority Plane. - -The Authority Plane evaluates: - -- authenticated identity; -- principal; -- actor; -- runtime identity; -- tenant; -- environment; -- task; -- mandate; -- delegation; -- requested action; -- requested resource; -- policy; -- approval; -- posture; -- TTL; -- quotas; -- budgets; -- authority ceiling. - -It produces: - -- `GRANT`; -- `DENY`; -- `REQUIRE_APPROVAL`; -- optionally `DEFER` for non-security-critical upstream enrichment. - -Security-critical ambiguity should normally fail closed. - -## 5.3 Execution Plane - -The Execution Plane changes system state. - -Examples: - -- Git; -- CI/CD; -- Kubernetes; -- cloud APIs; -- databases; -- SaaS; -- production services; -- Ops Warden; -- Ops Mason. - -Gate House should not perform most execution itself. - -Instead it should issue or represent authority that execution systems can enforce. - ---- - -# 6. Core Domain Model - -The domain model is intentionally small. - -## 6.1 Principal - -The human, organization, workload, or system on whose behalf authority originates. - -Examples: +NetKingdom separates security responsibilities by determinism and artifact: ```text -user:alice@example -service:release-controller -org:acme -tenant:acme -``` - -## 6.2 Actor - -The entity directly requesting or performing the action. - -Examples: - -```text -agent:deploy-agent-22 -workload:ci/github/actions/release -human:alice@example -``` - -## 6.3 Runtime Identity - -The concrete workload instance performing execution. - -Examples: - -```text -spiffe://netkingdom/prod/deployer/22 -k8s://cluster-a/ns-release/sa-deployer/pod-7f91 -aws://sts/role-session/... -``` - -## 6.4 Tenant - -The security and organizational domain in which the action occurs. - -Examples: - -```text -tenant:acme -tenant:internal -tenant:platform -``` - -## 6.5 Environment - -Operational environment. - -Examples: - -```text -dev -test -staging -production -``` - -## 6.6 Mandate - -A standing organizational authorization defining what an autonomous actor exists to do. - -Examples: - -```text -mandate:release-automation -mandate:vulnerability-remediation -mandate:production-diagnostics -``` - -A mandate is **not** a credential. - -It is a policy-recognized declaration of intended authority. - -## 6.7 Delegation - -A scoped transfer of authority from a principal to an actor. - -Delegation should normally attenuate: - -```text -child_authority ⊆ parent_authority -``` - -## 6.8 Authority Ceiling - -The maximum authority an actor can ever obtain under deterministic policy. - -An agent may use less authority than its ceiling. - -It may not reason itself into more. - -## 6.9 Action - -A canonical operation. - -Examples: - -```text -kubernetes.pod.read -kubernetes.deployment.restart -database.select -database.schema.modify -cloud.iam.role.modify -git.repository.write -release.deploy -``` - -## 6.10 Resource - -A canonical target. - -Examples: - -```text -k8s://cluster-a/ns/payments/deployment/api -db://orders-prod/schema/public/table/orders -aws://123456789012/eks/cluster-a -git://github/acme/payments -``` - -## 6.11 Grant - -A positive authorization result. - -A grant should be: - -- immutable after issuance; -- scoped; -- versioned; -- time-bounded; -- independently revocable where practical. - -## 6.12 Denial - -A negative authorization decision. - -A denial should include: - -- machine-readable reason; -- policy reference; -- evaluated constraints; -- optional remediation/approval hints. - -## 6.13 Approval - -An independent authorization artifact required for higher-risk actions. - -Approvals should be: - -- actor-bound; -- resource-bound; -- action-bound; -- parameter-bound; -- time-bound; -- replay-resistant. - -## 6.14 Posture - -A bounded security-state input. - -Typical source: - -- King's Guard. - -Examples: - -```text -HEALTHY -DEGRADED -SUSPICIOUS -CONTAIN -BLOCKED -``` - -Gate House should interpret posture through deterministic policy. - -## 6.15 Credential Binding - -The mapping from an authority grant to the technical credential mechanism used by a target system. - -Examples: - -```text -aws-sts-role -openbao-database-lease -openbao-pki-certificate -oauth-token-exchange -kubernetes-service-account-token -``` - -## 6.16 Decision Evidence - -The authoritative record of: - -- request; -- identities; -- evaluated policy; -- policy version; -- result; -- constraints; -- grant ID; -- approval ID; -- posture input; -- timestamps. - ---- - -# 7. Canonical Authorization Request - -A canonical request should be expressive enough for human, workload, and agent contexts without requiring every field in every scenario. - -Example: - -```yaml -request_id: req-01J6A8A1FJ3P - -principal: - id: user:alice@example - type: human - -actor: - id: agent:deploy-agent-22 - type: agent - -runtime: - id: spiffe://netkingdom/prod/deployer/22 - -tenant: - id: tenant:acme - -environment: production - -task: - id: release-7.2.1 - type: release - -mandate: - id: release-automation - -delegation: - mode: assistant - parent_session: session-01J6A7 - -request: - action: production.deploy - resource: k8s://cluster-a/ns/payments/deployment/api - -parameters: - image: registry.example/payments:7.2.1 - replicas: 6 - -approval: - id: approval-9432 - -posture: - actor: HEALTHY - resource: HEALTHY - -constraints: - requested_ttl: 20m - max_mutations: 1 - -context: - trace_id: 4bf92f3577b34da6a3ce929d0e0e4736 - source: mcp://ops-warden -``` - ---- - -# 8. Canonical Decision - -Example: - -```yaml -decision_id: dec-01J6A8AJ4YQW -request_id: req-01J6A8A1FJ3P - -decision: GRANT - -policy: - bundle: production-release - version: 2026-08-24.3 - -authority: - grant_id: grant-01J6A8AXK0N2 - action: production.deploy - resource: k8s://cluster-a/ns/payments/deployment/api - expires_at: 2026-08-24T20:22:00+02:00 - mutation_limit: 1 - -credential_binding: - type: kubernetes-execution-token - provider: secrets-engine - audience: ops-warden - -obligations: - - immutable_audit - - emit_deployment_evidence - - revoke_after_first_success - -explanation: - code: RELEASE_MANDATE_APPROVED - message: > - Actor is operating under the release-automation mandate, - approval matches resource and parameters, and current posture - permits one production deployment. - -evidence: - policy_hash: sha256:... - input_hash: sha256:... -``` - ---- - -# 9. Decision Types - -The first implementation should support at least four outcomes. - -## 9.1 GRANT - -The request is authorized under explicit constraints. - -## 9.2 DENY - -The request is not authorized. - -## 9.3 REQUIRE_APPROVAL - -The request may proceed only after acquisition of a separately governed approval artifact. - -This is preferable to returning a soft "maybe". - -## 9.4 DEFER - -Optional. - -Used only for non-security-critical enrichment, such as waiting for authoritative tenant metadata. - -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] - NORM[Request Normalizer] - CTX[Context Resolver] - POLICY[Policy Decision Service] - CEIL[Authority Ceiling Evaluator] - APPR[Approval Validator] - POST[Posture Interpreter] - LIMIT[Limits / Change Dynamics] - GRANT[Grant Service] - CRED[Credential Binding Adapter] - REVOKE[Revocation Service] - AUDIT[Audit / Evidence Service] - CACHE[Policy & Context Cache] - - API --> NORM - NORM --> CTX - CTX --> POLICY - - POLICY --> CEIL - POLICY --> APPR - POLICY --> POST - POLICY --> LIMIT - - CEIL --> GRANT - APPR --> GRANT - POST --> GRANT - LIMIT --> GRANT - - GRANT --> CRED - GRANT --> AUDIT - REVOKE --> AUDIT - - CACHE --> CTX - CACHE --> POLICY -``` - ---- - -# 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: - -- receive authorization requests; -- validate schema; -- enforce authentication of calling systems; -- attach correlation metadata; -- return normalized decisions. - -The API should not embed business policy. - -## 11.2 Request Normalizer - -Responsibilities: - -- canonicalize resource identifiers; -- canonicalize actions; -- normalize parameters; -- remove ambiguity before policy evaluation; -- ensure parameter-bound approvals compare normalized values. - -Example: - -```text -kubectl rollout restart deployment api -n payments -``` - -may normalize to: - -```text -action: kubernetes.deployment.restart -resource: k8s://cluster-a/ns/payments/deployment/api -``` - -## 11.3 Context Resolver - -Fetches authoritative context from trusted systems. - -Potential sources: - -- User Engine; -- Tenant Engine; -- Key Cape; -- Mandate registry; -- King's Guard; -- environment/resource registry. - -The resolver should distinguish: - -- authoritative context; -- advisory context; -- stale context. - -Security-critical missing context should fail closed. - -## 11.4 Policy Decision Service - -Evaluates deterministic authorization logic. - -The first implementation should make the policy backend pluggable. - -Potential engines: - -- OPA/Rego; -- Cedar; -- native evaluator. - -The domain model must not depend on one policy language. - -## 11.5 Authority Ceiling Evaluator - -Ensures that requested authority does not exceed: - -- actor ceiling; -- mandate ceiling; -- delegation ceiling; -- tenant ceiling; -- environment ceiling; -- parent-agent ceiling. - -This should be a mandatory layer even if policy already encodes similar logic. - -Defense in depth is appropriate at the authority boundary. - -## 11.6 Approval Validator - -Validates step-up authorization artifacts. - -Should verify: - -- issuer; -- actor; -- principal; -- action; -- resource; -- normalized parameters; -- issuance time; -- expiry; -- nonce/replay properties; -- approval class. - -## 11.7 Posture Interpreter - -Converts trusted adaptive-security posture into deterministic restrictions. - -Example: - -```yaml -posture: - actor: DEGRADED -``` - -may resolve into: - -```yaml -restrictions: - deny: - - production.write - require_approval: - - staging.write -``` - -The Posture Interpreter must not call an LLM to determine whether authority exists. - -## 11.8 Limits / Change Dynamics Controller - -Evaluates operational limits: - -- concurrent grants; -- concurrent mutating actors; -- per-task mutation count; -- runtime; -- deployment frequency; -- destructive action quota; -- token/compute budget; -- agent-chain depth. - -This is not the primary authorization layer. - -It is a secondary blast-radius layer. - -## 11.9 Grant Service - -Issues immutable grant records. - -Responsibilities: - -- assign grant IDs; -- enforce TTL; -- encode authority scope; -- attach obligations; -- register revocation state; -- optionally mint signed grant artifacts. - -## 11.10 Credential Binding Adapter - -Maps grants to credential mechanisms. - -It should not contain the actual secret backend logic. - -Instead it should delegate to Secrets Engine. - -Example: - -```text -grant - ↓ -credential binding request - ↓ -Secrets Engine - ↓ -OpenBao / AWS STS / OAuth / PKI -``` - -## 11.11 Revocation Service - -Supports: - -- grant revocation; -- actor suspension; -- mandate suspension; -- tenant freeze; -- emergency kill switch; -- propagation to credential providers. - -Revocation should not depend on the affected agent cooperating. - -## 11.12 Audit / Evidence Service - -Records: - -- request; -- normalized request; -- identity chain; -- context versions; -- policy version; -- decision; -- grant; -- revocation; -- credential binding metadata; -- execution references where available. - -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 - -Hard global rules. - -Examples: - -```text -deny if tenant is unresolved -deny if production action has no authenticated actor -deny if autonomous actor has no mandate -deny if child authority exceeds parent authority -deny if actor attempts to modify its own authority ceiling -deny if audit subsystem is unavailable for critical actions -``` - -These should be difficult to override. - -## 12.2 Environment Policy - -Examples: - -```text -production -staging -development -``` - -Production should require stronger controls. - -## 12.3 Tenant Policy - -Per-tenant restrictions. - -Important for multi-tenancy. - -## 12.4 Mandate Policy - -Defines what autonomous actor classes are intended to do. - -## 12.5 Resource Policy - -Specific restrictions for: - -- Kubernetes clusters; -- databases; -- cloud accounts; -- repositories; -- SaaS APIs. - -## 12.6 Posture Policy - -Maps King's Guard state to authority consequences. - -## 12.7 Approval Policy - -Defines which action classes require: - -- human approval; -- dual approval; -- break-glass; -- step-up MFA; -- parameter-bound authorization. - -## 12.8 Change Dynamics Policy - -Constrains: - -- concurrency; -- rate; -- budget; -- runtime; -- action quotas. - ---- - -# 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 -1. authenticate caller -2. normalize request -3. resolve principal / actor / tenant / runtime -4. verify operating mode -5. verify mandate / delegation -6. enforce authority ceiling -7. evaluate hard invariants -8. evaluate environment + tenant + resource policy -9. apply posture restrictions -10. validate approval -11. apply change-dynamics limits -12. derive obligations -13. GRANT or DENY -14. emit evidence -``` - -Where possible, evaluation should be monotonic toward restriction: - -```text -initial possible authority +Taxonomy names the concepts and semantic contracts ↓ -identity constraints - ↓ -mandate constraints - ↓ -tenant constraints - ↓ -resource constraints - ↓ -posture constraints - ↓ -approval constraints - ↓ -limits - ↓ -final authority +Tooling holds consistent, performant, scalable state + ↑ +Engines expose deterministic APIs over modeled concepts + ↑ +Staff proposes doctrine, plans, changes, and supervision ``` -No later stage should silently expand beyond an earlier hard ceiling. +The arrows are dependency direction, not authority flow. Staff acts through +Engine APIs and never reaches Tooling directly. ---- +For a protected action, the architecture is: -# 14. Assistant Mode Architecture - -## 14.1 Intent - -Assistant mode keeps the human as primary principal while preserving the agent as actor. - -```mermaid -sequenceDiagram - participant H as Human - participant A as Assistant Agent - participant K as Key Cape - participant G as Gate House - participant O as Ops Warden - participant R as Resource - - H->>K: authenticate - K-->>H: human session - H->>A: request task - A->>G: request action(principal=H, actor=A) - G->>G: deterministic policy evaluation - G-->>A: scoped grant - A->>O: execute with grant - O->>R: perform authorized action - R-->>O: result - O-->>G: execution evidence +```text +human / agent / workload proposes an action + ↓ +identity and context engines supply authoritative facts + ↓ +access-engine renders a deterministic decision + ↓ GRANT only +secrets-engine materializes target-specific authority when needed + ↓ +ops-warden / resource-side enforcement executes within the grant + ↓ +evidence sources emit records; audit-core protects accepted records + ↓ +kings-guard observes posture and findings; whitehat-security challenges controls ``` -## 14.2 Assistant-Mode Requirements +Gate House is outside this runtime path. It specifies what each boundary must +mean and reviews whether the path conforms. -- human session must be active; -- human principal must remain identifiable; -- agent should not inherit every human credential; -- privileged grants should be short-lived; -- human session termination should invalidate or shorten associated authority; -- irreversible actions may require explicit confirmation; -- agent must not silently continue as autonomous actor. +### 2.1 Responsibility boundary ---- +| Component | Architectural responsibility | +| --- | --- | +| info-tech-canon / NetKingdom canon | shared terminology and standards of record | +| key-cape | authentication, federation, and identity tooling profile | +| user-engine | authoritative user, account, and membership facts | +| tenant-engine | authoritative tenant and organizational facts | +| zone-engine | authoritative zone identity and membership facts | +| access-engine | the only policy decision point; evaluates access rules | +| secrets-engine | credential abstraction, custody, and lifecycle | +| OpenBao | protects and issues secret, lease, and PKI material | +| ops-mason / ops-warden | construct and operate access lanes and perimeters | +| kings-guard | observation, bounded posture, findings, and containment requests | +| whitehat-security | adversarial execution of assurance specifications | +| Gate House | doctrine, authority context, invariants, conformance, and curriculum | -# 15. Autonomous Mode Architecture +Two boundaries are lexical as well as architectural: -```mermaid -sequenceDiagram - participant T as Trigger/Scheduler - participant A as Autonomous Agent - participant K as Workload Identity - participant G as Gate House - participant S as Secrets Engine - participant O as Ops Warden - participant R as Resource +- an **access lane** says how a worker reaches a host and belongs to ops-mason + and ops-warden; +- an **access rule** says whether an action may occur and belongs to + access-engine. - T->>A: start task - A->>K: attest workload identity - K-->>A: short-lived identity - A->>G: request action(actor=A, mandate=M) - G->>G: evaluate mandate + ceiling + policy - G-->>A: grant - A->>S: request credential binding(grant) - S-->>A: short-lived execution credential - A->>O: execute - O->>R: protected action - O-->>G: evidence +## 3. Core domain model + +Gate House fixes the following meanings. Owning engines choose storage and wire +representations without changing the semantics. + +| Term | Meaning | +| --- | --- | +| **Principal** | Human, organization, workload, or system on whose behalf authority originates. | +| **Actor** | Entity directly attempting the action. | +| **Runtime Identity** | Concrete workload instance performing execution. | +| **Tenant** | Security and organizational domain in which the action occurs. | +| **Environment** | Governed operational environment containing the target. | +| **Mandate** | Standing organizational authorization defining what an autonomous actor is intended to do. | +| **Delegation** | Scoped transfer of authority that preserves principal and actor and does not widen authority. | +| **Authority Ceiling** | Maximum authority an actor can obtain. | +| **Operating Mode** | Assistant or Autonomous security regime. | +| **Task** | Bounded unit of work for which authority is requested. | +| **Action** | Canonical operation requested of a protected resource. | +| **Resource** | Canonical target of an action. | +| **Posture** | Bounded security-state input from a trusted source. | +| **Decision Evidence** | Record of the identities, inputs, policy, conditions, and result that produced a decision. | +| **Credential Binding** | Mapping from granted authority to the mechanism a target accepts. | + +A mandate is not a credential, a task is not a mandate, identity is not +authorization, and a credential is not the source of authority. + +Access-engine renders `GRANT`, `DENY`, `REQUIRE_APPROVAL`, or `DEFER`. +Gate House defines the vocabulary and invariants of those outcomes but neither +evaluates nor emits them. + +## 4. Authority context contract + +The normative logical contract is +[`authority-context.v1`](docs/contracts/authority-context.md), recorded by +[ADR-001](docs/adr/ADR-001-canonical-authority-context-contract.md) and +[ADR-002](docs/adr/ADR-002-principal-actor-runtime-identity-model.md). + +Every agentic authority request must be able to express: + +```text +principal +actor +runtime identity +tenant +environment +mandate +task +operating mode ``` -## 15.1 Autonomous-Mode Requirements +These are input claims alongside verified identity claims, requested action and +resource, authoritative resource facts, policy, approval, posture, and limits. +No field grants authority by being present. Caller assertion must remain +distinguishable from authoritative evidence. -Every autonomous agent must have: +Principal, actor, and runtime identity are separate semantic roles. They may +resolve to the same subject in a legitimate direct operation, but a consumer +must not copy one into a missing role or use one generic identifier to erase +delegation and runtime attribution. -- unique identity; -- named governance owner; -- explicit mandate; -- authority ceiling; -- lifecycle; -- runtime limit; -- task budget; -- concurrency limit; -- revocation path; -- audit trace; +Missing, conflicting, stale, or unresolvable security-critical context fails +closed. `DEFER` is reserved for non-security-critical enrichment and is not a +substitute for evidence needed to decide a protected operation. + +## 5. Agentic operating modes + +Operating mode is a security regime, not a deployment label. + +### 5.1 Assistant + +A human is actively engaged and can observe, redirect, approve, or stop at +human latency. + +- the human remains principal; +- the agent remains an identifiable actor; +- the concrete agent session or workload remains identifiable as runtime; +- privileged authority is bound to active supervision and short lifetime; +- the human's reusable credentials are not copied into agent context; +- interruption and confirmation remain available for high-impact actions. + +Human disconnect, session timeout, or loss of supervision must not silently +convert an Assistant workflow into privileged Autonomous operation. + +### 5.2 Autonomous + +A scheduled, triggered, or event-driven actor runs without continuous human +supervision. + +It requires: + +- a unique actor identity and concrete runtime identity; +- a named governance owner; +- an explicit, current mandate and bounded task; +- an authority ceiling and tenant, environment, resource, and action bounds; +- runtime, concurrency, tool-call, token, compute, and credential-TTL bounds; +- an independent kill switch and lifecycle termination path; +- protected evidence sufficient for reconstruction; - no borrowed human credential. ---- +### 5.3 Transition -# 16. King's Guard Integration +A transition from Assistant to Autonomous is a governed change. It requires a +new authority request under the Autonomous requirements; it is not a mutation +or fallback of an in-flight Assistant context. -King's Guard is an adaptive security system. +## 6. Mandates, delegation, and ceilings -Gate House should consume King's Guard output as **bounded posture input**. - -## 16.1 Accepted Pattern - -```text -King's Guard: - actor = agent-934 - posture = DEGRADED - confidence = 0.72 - reason = anomalous-tool-usage -``` - -Gate House policy: - -```text -IF actor.posture == DEGRADED -THEN - deny production.write - allow production.read - require approval for staging.write -``` - -## 16.2 Forbidden Pattern - -```text -King's Guard: - "This looks safe enough. - Give agent-934 admin." -``` - -Adaptive systems may restrict or request authority changes. - -They must not bypass Gate House. - -## 16.3 Containment Flow - -```mermaid -sequenceDiagram - participant KG as King's Guard - participant GH as Gate House - participant OW as Ops Warden - participant R as Resource - - KG->>GH: posture update: CONTAIN actor-X - GH->>GH: deterministic containment policy - GH-->>OW: authorized containment grant - OW->>R: isolate / suspend / revoke - OW-->>KG: containment result - KG->>KG: validate outcome -``` - ---- - -# 17. Secrets Engine and OpenBao Integration - -Gate House should not directly become a secrets backend. - -## 17.1 Separation of Responsibilities - -```text -Gate House: - "This authority is allowed." - -Secrets Engine: - "This is how the target system expects authority to be represented." - -OpenBao: - "This is how the required credential is securely issued and leased." -``` - -## 17.2 Example - -Request: - -```text -database.select -db://orders-prod -TTL 15m -``` - -Gate House: - -```text -GRANT -``` - -Secrets Engine: - -```text -binding = openbao.database.dynamic -role = orders-readonly -ttl = 15m -``` - -OpenBao: - -```text -username = v-gh-... -password = ... -lease = 15m -``` - -The credential should ideally be consumed by a trusted execution layer and not placed into LLM context. - ---- - -# 18. Execution Gateway Pattern - -Where possible, Gate House should encourage a brokered execution model. - -Preferred: - -```text -Agent - ↓ request -Gate House - ↓ grant -Execution Gateway / Ops Warden - ↓ obtains credential -Target System -``` - -Less preferred: - -```text -Agent - ↓ -raw reusable credential - ↓ -Target System -``` - -Benefits: - -- fewer secrets in model context; -- easier audit; -- easier revocation; -- target-specific enforcement; -- reduced exfiltration risk. - ---- - -# 19. MCP Integration - -MCP is treated as a capability interface, not an authorization system. - -## 19.1 MCP Tool Registration - -Tool metadata may define: - -- action identifier; -- resource schema; -- parameter schema; -- risk class; -- reversibility; -- required grant class. - -Example: - -```yaml -tool: restart_service -action: kubernetes.deployment.restart -risk: privileged-write -reversible: true -authorization: - gate_house: required -``` - -## 19.2 Invocation Flow - -```text -LLM selects tool - ↓ -MCP server constructs normalized authority request - ↓ -Gate House - ↓ -GRANT / DENY - ↓ -MCP server executes only if granted -``` - -## 19.3 Token Handling - -Inbound tokens should not be blindly forwarded to downstream resources. - -Downstream credentials should be separately issued or exchanged and audience-bound. - ---- - -# 20. Change Dynamics Envelope - -Gate House should model agentic operational velocity as a security concern. - -## 20.1 Envelope Dimensions - -Possible controls: - -```yaml -change_dynamics: - max_concurrent_mutations: 2 - max_actions_per_grant: 1 - max_resources_per_task: 5 - max_runtime: 30m - max_agent_chain_depth: 3 - max_destructive_actions: 0 - max_deployments_per_hour: 4 - token_budget_eur: 10 - compute_budget_cpu_minutes: 120 -``` - -## 20.2 Hard vs Soft Limits - -Hard: - -- destructive action quota; -- production concurrency; -- authority ceiling; -- environment boundary. - -Soft/advisory: - -- cost warning; -- anomaly score; -- human attention recommendation. - -Security-critical limits should be deterministic. - ---- - -# 21. Circuit Breaker Architecture - -Gate House should support independent suspension primitives. - -Examples: - -```text -suspend actor -suspend mandate -suspend tenant writes -suspend production writes -revoke grant -revoke all grants for runtime -switch environment to read-only -require approval for all mutations -``` - -## 21.1 Circuit Breaker Sources - -Potential sources: - -- King's Guard; -- human operator; -- incident automation; -- budget threshold; -- audit failure; -- policy subsystem failure; -- anomaly threshold mapped by deterministic policy. - -## 21.2 Safe Degraded Mode - -Preferred sequence: - -```text -NORMAL - ↓ -RESTRICTED - ↓ -READ_ONLY - ↓ -BLOCKED -``` - -Observability should usually remain available longer than mutation authority. - ---- - -# 22. Multi-Tenant Model - -Gate House is intended for multi-tenant environments. - -Tenant context must be explicit. - -## 22.1 Rules - -- every protected request should resolve to a tenant or explicitly be platform-scoped; -- cross-tenant authority must be exceptional; -- tenant isolation policy must be evaluated before resource policy; -- ambiguous tenant context should fail closed; -- audit evidence must retain tenant context; -- King's Guard signals must not accidentally leak tenant-private information across boundaries. - -## 22.2 Platform Operations - -Platform-level actors should use explicit platform mandates rather than implicit global authority. - -Example: - -```text -mandate: platform-maintenance -scope: - tenants: "*" -constraints: - action_class: infrastructure-only - customer_data_access: denied -``` - ---- - -# 23. Policy Self-Modification Protection - -A major agentic failure mode is self-escalation. - -Gate House must treat modifications to: - -- authority ceilings; -- policy bundles; -- identity trust; -- tenant mappings; -- approval rules; -- audit configuration; -- credential backends; -- circuit breakers; - -as control-plane changes requiring stronger authorization than ordinary workload changes. - -Example invariant: - -```text -IF actor == subject_of_policy_change -AND change would expand actor authority -THEN require independent governance principal -``` - ---- - -# 24. Audit Architecture - -## 24.1 Event Types - -At minimum: - -```text -AUTH_REQUEST_RECEIVED -AUTH_CONTEXT_RESOLVED -AUTH_DECISION -GRANT_ISSUED -GRANT_REVOKED -APPROVAL_VALIDATED -POSTURE_APPLIED -CREDENTIAL_BINDING_REQUESTED -CREDENTIAL_BINDING_ISSUED -EXECUTION_STARTED -EXECUTION_COMPLETED -CIRCUIT_BREAKER_TRIGGERED -POLICY_CHANGED -``` - -## 24.2 Evidence Requirements - -Privileged action evidence should support reconstruction of: - -- principal; -- actor; -- runtime; -- tenant; -- task; -- mandate; -- resource; -- action; -- parameters hash; -- approval; -- posture; -- policy version; -- grant; -- credential binding; -- execution result. - -## 24.3 Tamper Resistance - -The actor being audited should not have authority to erase the authoritative audit record. - -Gate House may write to: - -- append-only event store; -- external SIEM; -- immutable object storage; -- signed evidence log. - -The first implementation may use ordinary storage but should preserve the interface for stronger backends. - ---- - -# 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 - -Likely: - -- mandates; -- grant metadata; -- revocation state; -- policy references; -- approval references; -- audit metadata; -- limits/counters. - -## 25.2 Avoid Storing - -Prefer not to store: - -- raw secret values; -- cloud access keys; -- database passwords; -- OAuth refresh tokens; -- full sensitive payloads unless required. - -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 - -```text -POST /v1/authorize -``` - -Returns: - -```text -GRANT -DENY -REQUIRE_APPROVAL -``` - -## 26.2 Grant Introspection - -```text -GET /v1/grants/{grant_id} -``` - -Used by execution gateways. - -## 26.3 Revocation - -```text -POST /v1/grants/{grant_id}/revoke -POST /v1/actors/{actor_id}/suspend -POST /v1/mandates/{mandate_id}/suspend -``` - -## 26.4 Posture - -```text -POST /v1/posture -``` - -Trusted integrations only. - -## 26.5 Mandates - -```text -POST /v1/mandates -GET /v1/mandates/{id} -``` - -Initial implementation may keep mandates static/config-driven. - -## 26.6 Decision Explain - -```text -GET /v1/decisions/{decision_id} -``` - -Returns machine- and human-readable explanation. - ---- - -# 27. Trust Boundaries - -```mermaid -flowchart TB - subgraph Untrusted["Potentially Probabilistic / Untrusted"] - LLM[LLM / Agent] - MCP[MCP Client] - end - - subgraph TrustedIdentity["Trusted Identity Sources"] - KC[Key Cape] - UE[User Engine] - TE[Tenant Engine] - end - - subgraph GateHouse["Gate House Trust Boundary"] - API[API] - POL[Policy] - GRT[Grant Service] - AUD[Audit] - end - - subgraph Credential["Credential Boundary"] - SE[Secrets Engine] - OB[OpenBao] - end - - subgraph Execution["Protected Execution"] - OW[Ops Warden] - RES[Resources] - end - - LLM --> API - MCP --> API - KC --> API - UE --> API - TE --> API - API --> POL - POL --> GRT - GRT --> SE - SE --> OB - GRT --> OW - OW --> RES - GRT --> AUD -``` - -Gate House must not blindly trust identity fields supplied by the agent request. - -Identity and tenant claims should come from authenticated or independently resolved sources. - ---- - -# 28. Failure Modes - -## 28.1 Policy Engine Unavailable - -Production writes: - -```text -DENY -``` - -Read-only diagnostics may optionally use cached policy if policy explicitly permits. - -## 28.2 King's Guard Unavailable - -Do not grant additional authority. - -Use last-known-good restrictive posture or configured fallback. - -## 28.3 Audit Unavailable - -For privileged production mutation: - -```text -DENY -``` - -or use redundant audit path. - -## 28.4 Secrets Engine Unavailable - -Authorization may still return a grant, but execution requiring credentials cannot proceed. - -Gate House should distinguish: - -```text -authority granted -credential unavailable -``` - -## 28.5 User Engine / Tenant Engine Unavailable - -If identity or tenant context is security-critical and cannot be resolved: - -```text -DENY -``` - -## 28.6 Stale Context - -Every externally resolved context item should have: - -- source; -- version; -- fetched time; -- expiry/staleness policy. - ---- - -# 29. Caching - -Caching is useful but dangerous at authorization boundaries. - -## 29.1 Cacheable - -Potentially: - -- static resource metadata; -- policy bundles; -- tenant membership with short TTL; -- mandate definitions; -- public key sets. - -## 29.2 Avoid Long-Lived Caching - -Avoid long-lived caching of: - -- revocation state; -- incident posture; -- emergency suspension; -- approvals; -- human session presence. - -## 29.3 Cache Rule - -A cache may improve availability. - -It must not silently expand authority after source-of-truth changes. - ---- - -# 30. Deployment Model - -The first reference implementation should target Kubernetes. - -## 30.1 Suggested Services - -Minimal deployment: - -```text -gate-house-api -gate-house-policy -gate-house-grants -gate-house-audit -``` - -The first prototype may combine these into one process with clear internal module boundaries. - -## 30.2 Production Direction - -Later: - -- multiple replicas; -- stateless decision path; -- durable grant/revocation store; -- dedicated audit sink; -- independent policy bundle distribution; -- mTLS or workload identity; -- namespace/network isolation; -- protected admin/control API. - -## 30.3 Workload Identity - -Gate House itself should authenticate downstream services using workload identity rather than static credentials wherever possible. - ---- - -# 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: - -## 31.1 API - -- HTTP/JSON for initial interoperability; -- gRPC later if useful for high-volume decision calls. - -## 31.2 Policy - -- OPA/Rego is a strong initial candidate; -- Cedar is worth benchmarking for typed authorization semantics; -- native policy layer may be appropriate for hard invariants. - -A hybrid model may eventually be useful: - -```text -hard invariants: native -organizational policy: OPA/Cedar -``` - -## 31.3 Storage - -Potential: - -- PostgreSQL for grants, mandates, revocation, audit metadata; -- append-only event store later. - -## 31.4 Identity - -- OIDC; -- SPIFFE/SPIRE; -- Kubernetes projected service-account tokens; -- cloud workload identity. - -## 31.5 Secrets - -- Secrets Engine abstraction; -- OpenBao backend; -- cloud-native STS backends. - ---- - -# 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 -├── INTENT.md -├── ArchitectureBlueprint.md -├── docs/ -│ ├── adr/ -│ ├── concepts/ -│ ├── flows/ -│ └── threat-model/ -├── api/ -│ ├── openapi/ -│ └── schemas/ -├── domain/ -│ ├── identity/ -│ ├── authority/ -│ ├── delegation/ -│ ├── mandate/ -│ ├── posture/ -│ └── grant/ -├── policy/ -│ ├── invariants/ -│ ├── bundles/ -│ ├── engine/ -│ └── tests/ -├── grants/ -│ ├── issuance/ -│ ├── revocation/ -│ └── introspection/ -├── approvals/ -├── limits/ -│ ├── quota/ -│ ├── budget/ -│ └── concurrency/ -├── integrations/ -│ ├── user-engine/ -│ ├── tenant-engine/ -│ ├── key-cape/ -│ ├── secrets-engine/ -│ ├── openbao/ -│ ├── kings-guard/ -│ ├── ops-warden/ -│ └── mcp/ -├── audit/ -├── cmd/ -├── internal/ -├── test/ -│ ├── unit/ -│ ├── integration/ -│ ├── adversarial/ -│ └── scenarios/ -└── deploy/ - ├── kubernetes/ - └── helm/ -``` - -This is a reference layout, not yet a constraint. - ---- - -# 33. Initial End-to-End Scenarios - -## Scenario 1 — Human-Assisted Kubernetes Read - -Goal: - -- prove principal/actor separation; -- prove assistant-mode session binding; -- prove read-only grant. - -Flow: - -```text -human SSO -→ assistant agent -→ Gate House -→ read-only grant -→ Ops Warden -→ Kubernetes logs -``` - -Success criteria: - -- no production write; -- grant expires with session; -- audit reconstructs human + agent. - -## Scenario 2 — Autonomous Release - -Goal: - -- prove workload identity; -- prove mandate; -- prove production deployment scope. - -Flow: - -```text -scheduler -→ release agent -→ workload identity -→ Gate House -→ production.deploy grant -→ Ops Warden -→ Kubernetes -``` - -Success criteria: - -- no IAM modification; -- one deployment only; -- short TTL; -- independent revocation. - -## Scenario 3 — Dynamic DB Credential - -Goal: - -- prove authority-to-credential separation. - -Flow: - -```text -agent -→ Gate House -→ GRANT database.select -→ Secrets Engine -→ OpenBao -→ dynamic DB credential -→ execution gateway -``` - -Success criteria: - -- credential not exposed to model; -- credential TTL <= grant TTL; -- credential revoked with grant. - -## Scenario 4 — King's Guard Restriction - -Goal: - -- prove adaptive input cannot grant privilege. - -Flow: - -```text -King's Guard posture = DEGRADED -→ Gate House -→ deny production.write -→ allow read -``` - -Success criteria: - -- deterministic restriction; -- no model reasoning in authorization path. - -## Scenario 5 — Self-Escalation Attempt - -Goal: - -- prove control-plane protection. - -Flow: - -```text -agent -→ request policy change -→ attempt to expand own authority -→ Gate House -→ DENY / independent governance required -``` - ---- - -# 34. Security Test Program - -The reference implementation should include adversarial tests from the beginning. - -## 34.1 Malicious Model Test - -Assume agent intentionally requests maximum destructive access. - -Expected: - -```text -authority ceiling holds -``` - -## 34.2 Prompt Injection Test - -Assume tool description tells agent to dump credentials. - -Expected: - -```text -no reusable credentials available in model context -``` - -## 34.3 Human Disconnect Test - -Terminate Assistant session. - -Expected: - -```text -associated privileged grants expire or are revoked -``` - -## 34.4 Policy Self-Modification Test - -Agent attempts own privilege expansion. - -Expected: - -```text -DENY -``` - -## 34.5 Approval Replay Test - -Reuse approval for different parameters. - -Expected: - -```text -DENY -``` - -## 34.6 Cross-Tenant Test - -Attempt resource access in another tenant. - -Expected: - -```text -DENY -``` - -## 34.7 MCP Token Passthrough Test - -Attempt reuse of inbound token against downstream resource. - -Expected: - -```text -DENY / separate credential required -``` - -## 34.8 Audit Loss Test - -Disable audit sink. - -Expected: - -```text -privileged mutation fails closed -``` - -## 34.9 Circuit Breaker Test - -Suspend actor while task is active. - -Expected: - -```text -new actions denied -active grants revoked where possible -``` - ---- - -# 35. Performance Targets - -Security correctness is primary, but authorization cannot become an operational bottleneck. - -Initial qualitative targets: - -- local/cached authorization decision: low tens of milliseconds; -- external context lookups should be minimized; -- grants should be cacheable by execution gateways until expiry/revocation; -- revocation propagation should be near-real-time for privileged actors; -- audit should be asynchronous where safe but durable before returning success for critical actions. - -Exact SLOs should be established after the first benchmark prototype. - ---- - -# 36. Availability Model - -Gate House is a security-critical dependency. - -Production architecture should eventually target: - -- multiple replicas; -- redundant policy engine; -- redundant audit path; -- durable revocation store; -- clear fail-closed semantics. - -Availability must not be improved by silently bypassing authorization. - -A preferred degradation model is: - -```text -full authority - ↓ -cached read-only - ↓ -diagnostic-only - ↓ -deny privileged action -``` - ---- - -# 37. Observability - -Gate House should expose: - -## Metrics - -- authorization requests; -- grants; -- denials; -- approval-required decisions; -- decision latency; -- context lookup latency; -- policy errors; -- active grants; -- revoked grants; -- actor suspensions; -- mandate suspensions; -- circuit-breaker activations; -- cache hit rate; -- audit failures; -- cross-tenant denial count. - -## Traces - -Trace: - -```text -request -→ normalization -→ context resolution -→ policy -→ grant -→ credential binding -→ execution -``` - -## Logs - -Logs must avoid: - -- raw credentials; -- sensitive approval payloads; -- unnecessary customer data. - ---- - -# 38. Administrative Interfaces - -The admin/control path is itself a privileged security surface. - -Initial administrative functions: - -- register/update mandate; -- suspend actor; -- suspend mandate; -- revoke grant; -- set emergency environment restriction; -- inspect decision; -- inspect policy version. - -Administrative access should: - -- require strong authentication; -- be separately authorized; -- be audited; -- never be available to ordinary agent workload identities. - ---- - -# 39. Governance Integration - -Gate House should make governance machine-readable where practical. - -A mandate record may include: +A mandate is a governed declaration of why an autonomous actor exists. A +logical mandate includes, at minimum: ```yaml id: mandate:release-automation +revision: 7 owner: team:platform-release purpose: deploy approved releases operating_mode: autonomous - +lifecycle: + starts_at: 2026-09-01T00:00:00Z + expires_at: 2026-12-01T00:00:00Z + termination_ref: kill-switch:release-automation authority_ceiling: - actions: - - production.deploy - resources: - - k8s://cluster-a/ns/payments/* - denied_actions: - - cloud.iam.* - - kubernetes.rbac.modify - + tenants: [tenant:platform] + environments: [production] + actions: [release.deploy] + resources: [k8s://cluster-a/ns/payments/*] constraints: max_runtime: 30m max_concurrency: 1 max_mutations_per_task: 1 ``` -This becomes a bridge between organizational governance and runtime enforcement. +This is a logical governance shape, not a Gate House storage schema. +Access-engine owns how the authoritative mandate reference becomes policy +input. ---- - -# 40. Architecture Decision Records to Create Early - -Recommended ADRs: +Delegation attenuates: ```text -ADR-001 Canonical Authority Request Schema -ADR-002 Principal / Actor / Runtime Identity Model -ADR-003 Policy Engine Selection -ADR-004 Grant Representation and Signing -ADR-005 Revocation Semantics -ADR-006 Posture Input Contract with King's Guard -ADR-007 Credential Binding Contract with Secrets Engine -ADR-008 Audit Evidence Model -ADR-009 Assistant Session Binding -ADR-010 Autonomous Mandate Model -ADR-011 Multi-Tenant Isolation Rules -ADR-012 Failure / Fail-Closed Semantics -ADR-013 MCP Authorization Integration -ADR-014 Policy Self-Modification Protection +child authority ⊆ delegated authority ⊆ principal authority ⊆ authority ceiling ``` ---- +No agent reasoning, tool availability, approval, posture, budget, or child +delegation may widen the ceiling. -# 41. Prototype Milestones +## 7. Deterministic authority boundary -## M0 — Executable Skeleton +Every privileged action crosses an access-engine or resource-side deterministic +authority boundary. The same authoritative input state and policy version must +produce the same decision. -Deliver: - -- service skeleton; -- `/authorize`; -- canonical request schema; -- canonical decision schema; -- static policy; -- structured audit. - -Success: +The decision must be able to account for: ```text -request → deterministic GRANT/DENY +WHO principal, actor, runtime identity +WHERE tenant, environment, zone, resource +WHAT action and normalized parameters +WHY task, mandate, delegation +UNDER WHICH policy, approval, posture, quotas, budgets, ceiling +UNTIL WHEN expiry and credential TTL ``` -## M1 — Identity and Tenant Context +Evaluation is monotonic toward restriction: after application of the authority +ceiling, no later input may create authority beyond it. This is a property Gate +House specifies and access-engine implements; it is not a prescribed policy +algorithm or evaluation order. -Deliver: +Approval is an independently governed, actor/action/resource/parameter/time +binding. It can satisfy an explicit approval requirement but cannot exceed the +authority ceiling or compensate for invalid identity, mandate, tenant, or +environment context. -- principal; -- actor; -- runtime identity; -- tenant; -- assistant/autonomous mode. +## 8. Posture and containment contract -Success: +King's Guard publishes bounded posture observations. Access-engine maps trusted +posture to deterministic restrictions. Gate House owns the asymmetry: + +> **Posture may reduce authority, require stronger authorization, or request +> containment. It must not probabilistically manufacture additional +> authority.** + +Accepted direction: ```text -same actor receives different decisions depending on principal / tenant / mode +King's Guard observes DEGRADED / SUSPICIOUS / CONTAIN + ↓ bounded posture with source, subject, freshness, and reason +access-engine applies a versioned deterministic rule + ↓ +authority stays equal or becomes narrower ``` -## M2 — Mandates and Authority Ceilings - -Deliver: - -- autonomous mandate model; -- authority ceiling; -- delegation attenuation. - -Success: +Forbidden direction: ```text -agent cannot exceed mandate +adaptive system says “looks safe” + ↓ +new or wider authority ``` -## M3 — Grant Lifecycle +A containment request does not authorize containment. Access-engine decides +whether it may occur; ops-warden or the responsible Engine performs the +authorized action. If posture is unavailable or stale, configured fallback +must not expand authority over the last authoritative state or baseline policy. -Deliver: +## 9. Authority, credentials, and execution -- grant issuance; -- TTL; -- introspection; -- revocation; -- actor suspension. - -Success: +The responsibility chain is: ```text -granted authority can be independently revoked +access-engine decides whether authority exists +secrets-engine selects how granted authority is materialized +OpenBao protects and issues credential material +ops-warden operates the access lane or trusted execution path +resource independently enforces the presented authority ``` -## M4 — Secrets Binding +Credential invariants: -Deliver: +- credentials are issued only after authority exists; +- credential scope and audience do not exceed the grant; +- credential lifetime does not exceed the authority lifetime; +- revocation and expiry semantics remain linked; +- raw reusable credentials do not enter model context; +- trusted brokered execution is preferred to disclosing credentials to an + agent; +- Gate House never accesses OpenBao or another Tooling system directly. -- Secrets Engine integration; -- OpenBao dynamic database credential scenario. +An unavailable credential mechanism means execution cannot proceed. It does +not cause another component to invent authority or silently substitute a +broader credential. -Success: +## 10. MCP and tooling doctrine + +MCP is a capability interface, not an authority system. Tool discovery means +that an operation exists; it does not mean the actor may invoke it. + +A sensitive tool definition should provide enough stable metadata for a PEP to +construct a normalized request: + +```yaml +tool: restart_service +action: kubernetes.deployment.restart +resource_schema: k8s-resource.v1 +parameter_schema: restart-service.v1 +risk_class: privileged-write +reversible: true +``` + +The enforcement path is: ```text -authority → ephemeral credential → expiry/revocation +agent selects tool + ↓ +MCP server / resource PEP constructs normalized request + ↓ +access-engine decision + ↓ GRANT only +separately issued, resource- and audience-bound authority + ↓ +tool execution and evidence emission ``` -## M5 — Agent Assistant Scenario +Inbound-token passthrough is forbidden by default. The downstream resource +must receive authority intended for that resource, not whatever ambient token +the caller happened to possess. -Deliver: +## 11. Change Dynamics Envelope -- human principal; -- agent actor; -- session binding; -- disconnect revocation. +Agentic systems can exceed human review speed even while each individual action +looks ordinary. The Change Dynamics Envelope bounds the cumulative rate, scope, +concurrency, and duration of change. -Success: +Dimensions include: + +- concurrent mutating actors and actions per grant; +- resources per task and mutations per resource; +- task duration, credential TTL, and agent-chain depth; +- deployment frequency and destructive-action quota; +- tenant, environment, repository, and resource-class boundaries; +- read/write and reversible/irreversible action separation; +- token, compute, tool-call, and external-service spend. + +Hard limits such as authority ceilings, production concurrency, destructive +quotas, and environment boundaries are deterministic enforcement inputs. Soft +signals such as cost warnings and anomaly recommendations may ask for review or +reduce authority, but do not grant it. + +Economic budgets are useful blast-radius controls. They are never +authorization. + +### 11.1 Independent stop paths + +Autonomous write authority must be stoppable without actor cooperation. +Depending on the owning Engine, the deterministic mechanisms may suspend an +actor or mandate, revoke grants and credentials, restrict an environment to +read-only, or require approval for mutations. + +Degradation moves toward restriction: ```text -human-supervised authority stops with supervision +NORMAL → RESTRICTED → READ_ONLY → BLOCKED ``` -## M6 — Autonomous Release Scenario +Diagnostic visibility should remain available longer than mutation authority +where policy can safely separate them. -Deliver: +## 12. Tenant isolation and policy self-modification -- workload identity; -- autonomous mandate; -- deployment grant; -- quota; -- runtime budget. +Tenant context is explicit for protected actions. An omitted tenant is not a +wildcard, and a platform actor does not receive implicit cross-tenant authority. +Tenant, environment, resource, and action bounds compose by intersection. -Success: +Changes to authority ceilings, policy packages, identity trust, tenant mapping, +approval rules, posture mapping, audit configuration, credential bindings, or +kill switches require stronger and independently governed authorization than +ordinary workload changes. -```text -scheduled agent deploys but cannot alter IAM/policy -``` +An actor must not have routine authority to widen the policy that constrains +itself. An attempted self-escalation is denied and emitted as high-value +security evidence. -## M7 — King's Guard Posture +## 13. Decision evidence and audit -Deliver: +Decision evidence must support reconstruction of: -- posture API; -- deterministic posture restrictions; -- circuit breaker. +- principal, actor, runtime identity, tenant, environment, task, and mandate; +- action, resource, and normalized-parameter digest; +- operating mode, approval, and posture inputs; +- authority ceiling, quotas, budgets, and expiry; +- policy identifier and version; +- decision, reason, grant or approval references, and credential binding; +- execution target, result, and relevant state transition. -Success: +The actor being audited must not be able to alter or erase authoritative +evidence. Each owning system emits evidence for its own state transitions; +Gate House is not a central runtime audit writer. -```text -adaptive risk signal reduces authority without granting privilege -``` +### 13.1 Completeness bound -## M8 — Adversarial Security Suite +An append-only archive with a verified hash chain proves that records it holds +were not altered or truncated after arrival. It cannot prove a record was ever +sent. Therefore: -Deliver: +- completeness is the emitting system's obligation; +- load-bearing evidence emission is atomic with the state change, normally by + a local transactional outbox; +- heartbeat and reconciliation make silent omission detectable where required; +- no conformance claim says merely that “the audit record proves it happened.” -- self-escalation; -- cross-tenant; -- token misuse; -- approval replay; -- audit outage; -- circuit breaker tests. +The approval evidence contracts are the reference application: -Success: +- [`approval-outbox.md`](docs/contracts/approval-outbox.md); +- [`approval-emission-detection.md`](docs/contracts/approval-emission-detection.md); +- [`approval-consumption.md`](docs/contracts/approval-consumption.md). -```text -incorrect/malicious agent behavior does not cross configured authority boundaries -``` +## 14. Failure semantics ---- +Security-critical ambiguity fails closed. -# 42. Longer-Term Evolution +| Failure | Required architectural outcome | +| --- | --- | +| access-engine or required policy unavailable | Protected operation denied. | +| identity, tenant, environment, mandate, or delegation unresolved | Denied when the fact is security-critical. | +| posture unavailable or stale | Configured restrictive fallback; never additional authority. | +| approval unavailable, invalid, revoked, consumed, or mismatched | Approval-dependent operation denied. | +| credential materialization unavailable | No credential-dependent execution; the decision is not widened or replaced. | +| protected evidence cannot be durably coupled to a state change | That state change does not commit. | +| evidence archive unavailable after a local outbox commit | Retry asynchronously; do not roll back the committed safety action. | +| stale cache conflicts with newer restriction or revocation | New authority denied; caches must not outlive their safe staleness policy. | -Possible later capabilities: +Fail closed does not mean one global availability rule. Each state owner must +make the safety transition and its evidence atomic locally so an unavailable +archive cannot block emergency revocation. -- signed portable grants; -- token exchange; -- cross-domain delegation; -- policy simulation; -- policy impact analysis; -- temporal authorization; -- graph-based delegation chains; -- distributed revocation; -- tenant-local policy extensions; -- confidential-computing attestation; -- agent reputation/posture inputs; -- capability-based authorization; -- formal verification of hard invariants; -- high-assurance decision replay; -- multi-region authority plane. +## 15. Architectural invariants -These should only be introduced if they preserve the small and explicit responsibility boundary. +These stable identifiers retain the v0.1 Blueprint's invariant lineage, now +stated against the correct ownership boundary. ---- - -# 43. Architectural Invariants - -Gate House should preserve the following invariants throughout implementation. - -### A-01 +### A-01 — No probabilistic privilege No LLM or statistical component is the final source of privilege. -### A-02 +### A-02 — Explicit actor Every privileged action resolves to an explicit actor. -### A-03 +### A-03 — Autonomous mandate -Autonomous actions resolve to an explicit mandate. +Every autonomous privileged action resolves to an explicit current mandate. -### A-04 +### A-04 — Attenuating delegation -Delegated authority cannot silently exceed parent authority. +Delegated authority does not exceed parent authority or the authority ceiling. -### A-05 +### A-05 — Explicit tenant scope -Tenant context is explicit for protected actions. +Every protected action has explicit tenant or estate-defined non-tenant scope. -### A-06 +### A-06 — Deterministic protected boundary -Production mutations require deterministic policy evaluation. +Production mutations cross deterministic access-engine or resource-side +policy enforcement. -### A-07 +### A-07 — Bounded lifetime -A grant cannot outlive its configured TTL. +Authority and its credential material do not outlive their configured expiry. -### A-08 +### A-08 — Independent revocation -Revocation does not depend on the affected agent cooperating. +Emergency reduction or revocation does not depend on the affected actor +cooperating. -### A-09 +### A-09 — Restrictive posture -Adaptive posture may restrict authority but cannot probabilistically create new authority. +Adaptive posture may restrict authority but cannot probabilistically create +new authority. -### A-10 +### A-10 — Credential separation -Credentials are not treated as the source of authority. +Credentials represent granted authority; they are not its source. -### A-11 +### A-11 — Protected ceiling -Agents cannot normally change the controls that define their own authority ceiling. +Actors cannot ordinarily modify the controls defining their own authority +ceiling. -### A-12 +### A-12 — Actor-resistant evidence -Audit evidence is independent of the actor being audited. +Authoritative evidence is protected from the actor being audited, subject to +the completeness bound in §13.1. -### A-13 +### A-13 — Restrictive failure -Failure of security-critical dependencies does not silently expand authority. +Failure of a security-critical dependency does not silently expand authority. -### A-14 +### A-14 — No accidental autonomy -Assistant sessions do not silently become autonomous sessions. +Assistant sessions do not silently become Autonomous sessions. -### A-15 +### A-15 — Incorrect-agent tolerance -If every agent behaves incorrectly, deterministic authority boundaries still hold. +Deterministic boundaries continue to hold when every agent behaves incorrectly. ---- +## 16. Conformance architecture -# 44. Blueprint Summary - -Gate House should be implemented as a small, composable, deterministic authority control plane. - -Its core path is: +Gate House doctrine is real only when the loop turns: ```text -authenticated context - ↓ -principal + actor + runtime - ↓ -tenant + environment - ↓ -mandate / delegation - ↓ -action + resource + parameters - ↓ -authority ceiling - ↓ -deterministic policy - ↓ -posture restrictions - ↓ -approval - ↓ -change-dynamics limits - ↓ -GRANT / DENY - ↓ -credential binding - ↓ -execution - ↓ -audit / evidence +Gate House asserts an invariant or contract + ↓ +owning Engines and Staff repositories implement it + ↓ +whitehat-security executes the assurance specification + ↓ +kings-guard observes behavior and findings + ↓ +findings return to Gate House as doctrine change ``` -The architecture should make one property easy to demonstrate: +The Canon's T-01…T-10 are specifications owned by Gate House and executed by +whitehat-security. They cover malicious-model behavior, credential +exfiltration, human disconnect, policy self-modification, confused-deputy +behavior, approval replay, circuit breakers, evidence reconstruction, audit +failure, and revocation closure. -> **An intelligent system may request anything. It can only cause the protected system to do what deterministic authority policy permits.** +The reference scenarios are: -That is the architectural essence of Gate House. +- UC-01 — human-assisted read; +- UC-02 — autonomous release; +- UC-03 — dynamic database access; +- UC-04 — containment; +- UC-05 — self-escalation attempt. + +Passing prose review is insufficient. A conformance report names the invariant, +owning implementation, test or observation, evidence bound, result, and finding +return path. + +## 17. ADR disposition and remaining doctrine work + +| ADR | Disposition | +| --- | --- | +| ADR-001 | Accepted — canonical authority-context contract. | +| ADR-002 | Accepted — principal / actor / runtime identity model. | +| ADR-003 | Lapsed — policy-engine selection belongs to access-engine. | +| ADR-004, ADR-005, ADR-008, ADR-011, ADR-012 | Engine implementation decisions; no Gate House runtime ADR. Their doctrine survives in invariants and contracts. | +| ADR-006 | Still meaningful — posture input contract with kings-guard. | +| ADR-007 | Credential separation is doctrine here; materialization implementation belongs to secrets-engine. | +| ADR-009 | Still meaningful — Assistant session binding. | +| ADR-010 | Still meaningful — Autonomous mandate model. | +| ADR-013 | Still meaningful — MCP authorization integration. | +| ADR-014 | Still meaningful — policy self-modification protection. | + +Future ADRs in Gate House decide doctrine and responsibility boundaries. They +must not select an Engine's implementation technology or create a Gate House +runtime surface. + +## 18. Blueprint summary + +Gate House establishes the security doctrine that makes the runtime chain +coherent. It does not join that chain as a service. + +```text +agent decides what to attempt + ↓ +engines establish identity and context + ↓ +access-engine decides what may cross + ↓ +secrets-engine materializes bounded authority + ↓ +the perimeter and resource enforce it + ↓ +evidence and adversarial review show whether the doctrine held +``` + +> **The mandate and 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.** diff --git a/CLAUDE.md b/CLAUDE.md index 7d1f43b..95d83ac 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -51,12 +51,12 @@ estate's layering rule: 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. +4. **`ArchitectureBlueprint.md`** — the current doctrine architecture: responsibility + boundaries, domain model, authority context, operating modes, posture and credential + contracts, MCP doctrine, change dynamics, audit, invariants, and conformance. The + withdrawn v0.1 authority-plane design is mapped in + `history/2026-09-01-authority-plane-blueprint-retirement.md` and remains available at + Git object `75ce372:ArchitectureBlueprint.md` for historical review only. 5. **`README.md`** — public-facing summary. A derivative, not a source of truth. When these conflict: the decision record wins over everything, then the Canon, then INTENT, @@ -75,7 +75,7 @@ repositories implement them. A document or proposal that violates one is wrong: - **Principal, actor, and runtime identity stay distinct** and are never collapsed into one field. Delegation attenuates and never widens. - **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 + demand step-up; it can never manufacture privilege. See Blueprint §8 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.) @@ -115,8 +115,9 @@ the file, commit, then sync. `SCOPE.md` is derived from `INTENT.md` — keep the ## Conventions - **Stable identifiers.** Invariants (`INV-nn`, `A-nn`), tests (`T-nn`), use cases (`UC-nn`), - ADRs (`ADR-nnn`), and milestones (`M0`–`M8`) are referenced across documents. Reuse the - existing id when writing about a concept; append rather than renumber. + and ADRs (`ADR-nnn`) are referenced across documents. Reuse the existing id when writing + about a concept; append rather than renumber. The v0.1 milestones (`M0`–`M8`) are + historical and must not be revived as Gate House implementation milestones. - **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 @@ -132,12 +133,12 @@ the file, commit, then sync. `SCOPE.md` is derived from `INTENT.md` — keep the ## 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. +- `README.md`, `INTENT.md`, and `ArchitectureBlueprint.md` live at the repo root. External + standards Gate House conforms to — the Canon — live in `spec/`. +- ADRs → `docs/adr/`, with disposition recorded in Blueprint §17. 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 @@ -147,10 +148,10 @@ the file, commit, then sync. `SCOPE.md` is derived from `INTENT.md` — keep the 2026-08-29 after seven versions; four repositories assented and each returned findings that changed it. Its working form is `net-kingdom/SECURITY-COMPANION.md` — read that first. For how to get something done in the estate, ask ops-warden, not this repo. -- **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. +- **No implementation layout.** The v0.1 Blueprint'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 5752e4a..79639bc 100644 --- a/README.md +++ b/README.md @@ -172,16 +172,15 @@ gate-house asserts an invariant | [`spec/ActiveSecretsManagementCanon_v0.3.md`](spec/ActiveSecretsManagementCanon_v0.3.md) | the working canon — invariants, controls, profiles, assurance tests | | [`docs/contracts/authority-context.md`](docs/contracts/authority-context.md) | normative authority-context vocabulary consumed by access-engine | | [`docs/adr/`](docs/adr/) | architecture decisions for Gate House doctrine and contracts | -| [`ArchitectureBlueprint.md`](ArchitectureBlueprint.md) | architecture; **predates the re-cut and is being revised** | +| [`ArchitectureBlueprint.md`](ArchitectureBlueprint.md) | current doctrine architecture and responsibility contracts | | [`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 | **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. +record, the canon standard, and `ArchitectureBlueprint.md` reflect the current +shape. The withdrawn authority-plane design is preserved under `history/` and +in Git, not in the working architecture. --- diff --git a/WORK-RECORDS.md b/WORK-RECORDS.md index 8a2c6c1..1a605cc 100644 --- a/WORK-RECORDS.md +++ b/WORK-RECORDS.md @@ -13,7 +13,7 @@ | task | GH-WP-0001-T01 | done | — | workplans/GH-WP-0001-foundation.md | | task | GH-WP-0001-T02 | done | — | workplans/GH-WP-0001-foundation.md | | task | GH-WP-0001-T03 | done | — | workplans/GH-WP-0001-foundation.md | -| task | GH-WP-0001-T04 | todo | — | workplans/GH-WP-0001-foundation.md | +| task | GH-WP-0001-T04 | done | — | workplans/GH-WP-0001-foundation.md | | task | GH-WP-0001-T05 | todo | — | workplans/GH-WP-0001-foundation.md | | task | GH-WP-0001-T06 | todo | — | workplans/GH-WP-0001-foundation.md | | task | GH-WP-0002-T01 | done | — | workplans/GH-WP-0002-approval-evidence-integrity.md | diff --git a/history/2026-09-01-authority-plane-blueprint-retirement.md b/history/2026-09-01-authority-plane-blueprint-retirement.md new file mode 100644 index 0000000..e867d96 --- /dev/null +++ b/history/2026-09-01-authority-plane-blueprint-retirement.md @@ -0,0 +1,76 @@ +# Authority-plane Blueprint retirement + +**Repository:** `gate-house` +**Project family:** NetKingdom +**Status:** Design history; non-normative +**Date:** 2026-09-01 +**Decision:** `decisions/decisions.md` GH-DEC-2026-001 +**Workplan:** GH-WP-0001-T05 + +## Purpose + +This note records the retirement of `ArchitectureBlueprint.md` v0.1 and the +disposition of its sections. It prevents withdrawn engine design from remaining +in the working architecture while preserving the original argument and text. + +The complete pre-revision document is recoverable without copying 2,500 lines +of obsolete direction into current documentation: + +```text +git show 75ce372:ArchitectureBlueprint.md +``` + +Commit `75ce372` is the T04 completion and contains the last complete v0.1 +Blueprint before T05 began. + +## Why it was retired + +Version 0.1 described Gate House as a deterministic authority plane with an +`/authorize` API, policy evaluation, grants, revocation, storage, deployment, +and operational targets. GH-DEC-2026-001 rejected that placement: Gate House is +non-deterministic Staff, while access-engine is the only policy decision point. + +Building the old design in this repository would have violated the doctrine's +first boundary in its own home: cognition would have acquired a path to +privilege. + +## Section disposition + +| v0.1 section | Disposition in v0.2 | +| --- | --- | +| §1–4 purpose, goals, non-goals, context | Rewritten around a Staff-layer doctrine artifact and the estate responsibility boundary. | +| §5 three-plane model | Replaced by the accepted Taxonomy → Tooling → Engines → Staff layer model. Gate House's former Authority Plane placement is withdrawn. | +| §6 core domain model | Retained and tightened in v0.2 §3. Runtime-owned grant and decision terms are explicitly attributed to access-engine. | +| §7 canonical authorization request | Replaced by `docs/contracts/authority-context.md`; no Gate House wire format or endpoint. | +| §8–9 canonical decision and decision types | Decision vocabulary retained; schema and emission belong to access-engine. | +| §10–13 components, policy architecture, evaluation order | Withdrawn as access-engine implementation design. The monotonic-restriction invariant survives without prescribing an algorithm. | +| §14–15 Assistant and Autonomous modes | Retained as security regimes in v0.2 §5. Gate House is removed from runtime flows. | +| §16 King's Guard integration | Retained as the restrictive posture and containment contract in v0.2 §8. | +| §17 secrets/OpenBao integration | Retained as responsibility and credential-separation doctrine in v0.2 §9. Direct Gate House integration is withdrawn. | +| §18 execution gateway | Retained as a preference for trusted brokered execution, owned by the execution and credential repositories. | +| §19 MCP integration | Retained as capability-not-authority doctrine in v0.2 §10. | +| §20–21 change dynamics and circuit breakers | Retained as the Change Dynamics Envelope and independent stop-path obligations in v0.2 §11. Runtime mechanisms belong to Engines. | +| §22 multi-tenancy | Retained as explicit-scope doctrine in v0.2 §12. | +| §23 policy self-modification | Retained as independent-governance doctrine in v0.2 §12. | +| §24 audit architecture | Retained in v0.2 §13, corrected with the archive-completeness bound and per-source emission ownership. Gate House as audit writer is withdrawn. | +| §25–26 storage and API | Withdrawn completely as Gate House runtime design. | +| §27 trust boundaries | Replaced by v0.2 §2. Gate House is outside the runtime trust path. | +| §28 failure modes | Retained as cross-component doctrine in v0.2 §14, with local-outbox revocation semantics from GH-DEC-2026-002. | +| §29 caching | Implementation ownership moved to consuming Engines; only the no-expansion-on-staleness rule survives. | +| §30–32 deployment, technology, repository layout | Withdrawn completely. Gate House is specification-only. | +| §33 end-to-end scenarios | Reconciled to INTENT's UC-01…UC-05 and referenced by v0.2 §16. | +| §34 security test program | Reconciled to the Canon's T-01…T-10. Gate House specifies; whitehat-security executes. | +| §35–38 performance, availability, observability, admin UI | Withdrawn as service requirements. Cross-estate evidence and failure obligations survive without Gate House SLOs or interfaces. | +| §39 governance integration | Mandate model retained as a logical governance shape in v0.2 §6, not a Gate House database schema. | +| §40 ADR backlog | Reclassified in v0.2 §17. ADR-003 lapsed; Engine implementation choices moved to their owning repositories. | +| §41 prototype milestones | M0, M3, and M4 lapsed. Remaining concerns are doctrine, owning-repository work, or assurance targets rather than Gate House implementation milestones. | +| §42 longer-term evolution | Replaced by INTENT success criteria and the conformance loop. | +| §43 invariants | Stable A-01…A-15 identifiers retained and corrected for ownership in v0.2 §15. | +| §44 summary | Replaced: Gate House establishes doctrine and no longer appears in the request path. | + +## What retirement means + +The v0.1 text remains useful evidence of why the boundary was redrawn. It is +not an implementation backlog. Citations to it must identify it as historical; +new architecture and workplans cite v0.2, the authority-context contract, the +Canon, or the governing decision. diff --git a/workplans/GH-WP-0001-foundation.md b/workplans/GH-WP-0001-foundation.md index 623ce30..de13e4a 100644 --- a/workplans/GH-WP-0001-foundation.md +++ b/workplans/GH-WP-0001-foundation.md @@ -87,7 +87,7 @@ boundary and the three-role identity model. ```task id: GH-WP-0001-T05 -status: todo +status: done priority: medium state_hub_task_id: "010e3162-cab1-5644-b262-b0d1d7d676f8" ``` @@ -98,6 +98,12 @@ doctrine, change dynamics, audit, architectural invariants — into doctrine for and retire the withdrawn sections from the working document into design history. Currently marked in place with a status banner. +Done — `ArchitectureBlueprint.md` v0.2 is a current doctrine architecture with +no Gate House runtime role. The complete v0.1 remains recoverable at Git object +`75ce372:ArchitectureBlueprint.md`; its section-by-section disposition is in +`history/2026-09-01-authority-plane-blueprint-retirement.md`. Derivative README +and agent guidance now point to the current document. + ```task id: GH-WP-0001-T06 status: todo