gate-house/ArchitectureBlueprint.md

# Gate House — Architecture Blueprint

**Repository:** `gate-house`  
**Project family:** NetKingdom  
**Artifact:** `ArchitectureBlueprint.md`  
**Status:** Initial architecture blueprint  
**Version:** 0.1  
**Date:** 2026-08-24

---

## 1. Purpose

This document translates the Gate House intent into a practical architecture for a first reference implementation.

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.

The architectural maxim is:

> **Cognition proposes. Authority disposes. Infrastructure executes.**

---

# 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:

```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

```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

## 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

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

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
    ↓
identity constraints
    ↓
mandate constraints
    ↓
tenant constraints
    ↓
resource constraints
    ↓
posture constraints
    ↓
approval constraints
    ↓
limits
    ↓
final authority
```

No later stage should silently expand beyond an earlier hard ceiling.

---

# 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
```

## 14.2 Assistant-Mode Requirements

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

---

# 15. Autonomous Mode Architecture

```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

    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
```

## 15.1 Autonomous-Mode Requirements

Every autonomous agent must have:

- unique identity;
- named governance owner;
- explicit mandate;
- authority ceiling;
- lifecycle;
- runtime limit;
- task budget;
- concurrency limit;
- revocation path;
- audit trace;
- no borrowed human credential.

---

# 16. King's Guard Integration

King's Guard is an adaptive security system.

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

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

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

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

```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:

```yaml
id: mandate:release-automation
owner: team:platform-release
purpose: deploy approved releases
operating_mode: autonomous

authority_ceiling:
  actions:
    - production.deploy
  resources:
    - k8s://cluster-a/ns/payments/*
  denied_actions:
    - cloud.iam.*
    - kubernetes.rbac.modify

constraints:
  max_runtime: 30m
  max_concurrency: 1
  max_mutations_per_task: 1
```

This becomes a bridge between organizational governance and runtime enforcement.

---

# 40. Architecture Decision Records to Create Early

Recommended ADRs:

```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
```

---

# 41. Prototype Milestones

## M0 — Executable Skeleton

Deliver:

- service skeleton;
- `/authorize`;
- canonical request schema;
- canonical decision schema;
- static policy;
- structured audit.

Success:

```text
request → deterministic GRANT/DENY
```

## M1 — Identity and Tenant Context

Deliver:

- principal;
- actor;
- runtime identity;
- tenant;
- assistant/autonomous mode.

Success:

```text
same actor receives different decisions depending on principal / tenant / mode
```

## M2 — Mandates and Authority Ceilings

Deliver:

- autonomous mandate model;
- authority ceiling;
- delegation attenuation.

Success:

```text
agent cannot exceed mandate
```

## M3 — Grant Lifecycle

Deliver:

- grant issuance;
- TTL;
- introspection;
- revocation;
- actor suspension.

Success:

```text
granted authority can be independently revoked
```

## M4 — Secrets Binding

Deliver:

- Secrets Engine integration;
- OpenBao dynamic database credential scenario.

Success:

```text
authority → ephemeral credential → expiry/revocation
```

## M5 — Agent Assistant Scenario

Deliver:

- human principal;
- agent actor;
- session binding;
- disconnect revocation.

Success:

```text
human-supervised authority stops with supervision
```

## M6 — Autonomous Release Scenario

Deliver:

- workload identity;
- autonomous mandate;
- deployment grant;
- quota;
- runtime budget.

Success:

```text
scheduled agent deploys but cannot alter IAM/policy
```

## M7 — King's Guard Posture

Deliver:

- posture API;
- deterministic posture restrictions;
- circuit breaker.

Success:

```text
adaptive risk signal reduces authority without granting privilege
```

## M8 — Adversarial Security Suite

Deliver:

- self-escalation;
- cross-tenant;
- token misuse;
- approval replay;
- audit outage;
- circuit breaker tests.

Success:

```text
incorrect/malicious agent behavior does not cross configured authority boundaries
```

---

# 42. Longer-Term Evolution

Possible later capabilities:

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

These should only be introduced if they preserve the small and explicit responsibility boundary.

---

# 43. Architectural Invariants

Gate House should preserve the following invariants throughout implementation.

### A-01

No LLM or statistical component is the final source of privilege.

### A-02

Every privileged action resolves to an explicit actor.

### A-03

Autonomous actions resolve to an explicit mandate.

### A-04

Delegated authority cannot silently exceed parent authority.

### A-05

Tenant context is explicit for protected actions.

### A-06

Production mutations require deterministic policy evaluation.

### A-07

A grant cannot outlive its configured TTL.

### A-08

Revocation does not depend on the affected agent cooperating.

### A-09

Adaptive posture may restrict authority but cannot probabilistically create new authority.

### A-10

Credentials are not treated as the source of authority.

### A-11

Agents cannot normally change the controls that define their own authority ceiling.

### A-12

Audit evidence is independent of the actor being audited.

### A-13

Failure of security-critical dependencies does not silently expand authority.

### A-14

Assistant sessions do not silently become autonomous sessions.

### A-15

If every agent behaves incorrectly, deterministic authority boundaries still hold.

---

# 44. Blueprint Summary

Gate House should be implemented as a small, composable, deterministic authority control plane.

Its core path is:

```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
```

The architecture should make one property easy to demonstrate:

> **An intelligent system may request anything. It can only cause the protected system to do what deterministic authority policy permits.**

That is the architectural essence of Gate House.