coulomb/gate-house
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Rewrite README against the re-cut

Browse source 
The README described the withdrawn engine framing and stated "Gate House
authorizes", contradicting INTENT.md. It now leads with the Staff-layer
doctrine council role, the layer model, and the INV-02 argument for why
Gate House is not the decision point.

Its one already-correct sentence — Gate House as observability for governed
secrets under sound governance policy — is what the rewrite builds on.

Flags the Blueprint as predating the re-cut so readers are not misled by it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Assistant: claude-code
Assistant-Model: opus
Assistant-Process: 2564823@bnt-lap001
Assistant-Session: 2a7ed827-4928-4b9f-8613-9135c9cadfe9
This commit is contained in:
tegwick 2026-08-28 21:21:51 +02:00
parent 7b2d2eff91
commit f4353fddbc
1 changed files with 154 additions and 590 deletions
Download patch file Download diff file Expand all files Collapse all files

744
README.md
View file

@ -1,623 +1,187 @@
# Gate House
**Deterministic authority control system for human and agentic coding and operations.**
**The council where NetKingdom's security and defence doctrine is established, documented, taught, and supervised.**
Gate House is a NetKingdom security control-plane project and the reference implementation of the **Active Secrets Management (ASM) Plane**.
Gate House is a NetKingdom **Staff**-layer repository and the home of the
Active Secrets Management (ASM) Canon. It is the headquarters of the
operational staff that does the chores of IT security in NetKingdom.
Think of Gate House as observability for vault managed secrets based on sound governance policy best practices.
A word about the name, because it argues the other way. A gate house sounds
like the thing requests pass through. It is not. In a real castle the gate
house is where the guard is quartered, the watch is set, and the porter's rules
are posted — the rules of entry are decided there, and the gate itself is held
by someone else.
Its job is deliberately narrow:
> **Gate House does not stand in the gate. It decides what the gate is for, who
> may be asked to open it, and how we know it held.**
> **Gate House decides whether a human, workload, or agent is allowed to perform a requested action against a protected resource — under explicit, deterministic, auditable rules.**
It does **not** replace an identity provider, secrets vault, policy engine, operations framework, or adaptive security system. It connects those responsibilities through a common authority model.
Its artifacts are specifications, decisions, workplans, and tasks. It holds no
runtime position, renders no authorization decision, and stores no state that
anything depends on at runtime.
---
## Why?
## Where it sits
Agentic development changes the operational risk profile of software engineering.
Human-only development is naturally rate-limited by human execution.
Interactive coding agents increase change velocity while a developer or operator remains actively involved.
Autonomous agents remove much of that human friction entirely and therefore require explicit identities, mandates, authority ceilings, budgets, circuit breakers, and governance.
At the same time, modern tooling such as MCP makes infrastructure capabilities increasingly easy for agents to discover and invoke.
The central Gate House rule is therefore:
> **Tool availability is not permission.**
And more generally:
> **Cognition may be probabilistic. Authority must be deterministically constrained.**
---
## Core Architecture
NetKingdom's IT security is layered by determinism and by the kind of artifact
each layer produces — see
[`net-kingdom/canon/standards/security-layer-model_v0.1.md`](../net-kingdom/canon/standards/security-layer-model_v0.1.md).
```text
Cognitive Plane
┌──────────────────────────────────────────┐
│ humans │
│ LLMs / coding agents │
│ operations agents │
│ MCP / A2A │
│ King's Guard │
└───────────────────┬──────────────────────┘
│ request
▼
══════════════════════════════════════════════
GATE HOUSE
┌──────────────────────────────────────────┐
│ principal │
│ actor │
│ tenant / environment │
│ mandate / delegation │
│ resource / action │
│ policy │
│ approval │
│ posture │
│ TTL / quotas / budgets │
│ authority ceiling │
└───────────────────┬──────────────────────┘
│ GRANT / DENY
▼
══════════════════════════════════════════════
Execution Plane
┌──────────────────────────────────────────┐
│ Git / CI/CD │
│ Kubernetes │
│ cloud APIs │
│ databases │
│ SaaS / production services │
└──────────────────────────────────────────┘
Taxonomy cross-cutting language info-tech-canon, net-kingdom canon
Tooling deterministic state key-cape (authelia, lldap, privacy-idea), OpenBao
Engines deterministic APIs user / tenant / zone / secrets / access-engine
Staff interactive, non-deterministic gate-house, ops-mason, ops-warden,
kings-guard, whitehat-security
```
A short version:
Read by determinism, those layers reproduce the Canon's three planes — which is
the point:
> **Cognition proposes. Authority disposes. Infrastructure executes.**
The rule that binds every repository:
> **Staff never touches Tooling directly. It acts only through Engine APIs.**
## Why Gate House is not the decision point
Gate House was seeded as a deterministic authority plane — an `/authorize` API,
grant storage, a revocation service. That was withdrawn on its own argument:
> **A decision point inside Gate House would place the deterministic authority
> boundary inside the non-deterministic management layer, violating INV-02, "No
> Privilege from Cognition" — the first invariant this repository exists to
> defend.**
NetKingdom already has a policy decision point: `access-engine` (currently
`flex-auth`). It stays the only one. Gate House writes the doctrine that
decision point implements, and checks that it did.
The boundary, in one line:
> **The mandate and the operating mode are Gate House's. The decision is
> access-engine's. The credential is secrets-engine's. The perimeter is
> ops-mason's and ops-warden's.**
---
## What Gate House Owns
## What Gate House owns
Gate House owns the deterministic authority decision.
- **The doctrine** — the ASM Canon, its invariants, and the argument behind
them. Invariants graduate into `net-kingdom/canon/standards/`.
- **The authority context** — principal, actor, runtime identity, tenant,
environment, mandate, task, operating mode. Defined here, consumed by
access-engine as input claims.
- **The agentic operating modes** — assistant and autonomous as distinct
security regimes.
- **Mandates, authority ceilings, and kill switches** for autonomous actors, as
a model and a governance obligation.
- **The Change Dynamics Envelope** — how much change the organization tolerates.
- **The MCP doctrine** — tool availability is not permission.
- **The posture contract** with kings-guard, including its asymmetry.
- **Conformance review** — whether authority in practice matches the declared
mandate and ceiling.
- **The assurance specifications** T-01…T-10, executed by whitehat-security.
- **The security curriculum.**
It should answer questions such as:
## What Gate House does not own
The authorization decision or any `/authorize` surface; policy engines,
packages, or rollout; grants, credentials, leases, or revocation; identity,
tenancy, zone, or user lifecycle; secret storage or PKI; anomaly detection or
threat intelligence; access lanes, SSH certificates, or host hardening;
deployment or remediation execution; and other repositories' workplans.
| Component | Layer | Responsibility |
|---|---|---|
| info-tech-canon | Taxonomy | ecosystem-wide semantic contracts |
| net-kingdom | Taxonomy | NetKingdom standards of record |
| key-cape | Tooling | packaged identity tooling; IAM profile; authentication |
| OpenBao | Tooling | secret storage, leases, PKI |
| user-engine | Engine | users, accounts, memberships |
| tenant-engine | Engine | tenant-as-an-entity facts |
| zone-engine | Engine | zone identity and membership |
| secrets-engine | Engine | credential abstraction, custody, lifecycle |
| **access-engine** | Engine | **the decision — the only decision point** |
| **gate-house** | **Staff** | **doctrine, authority context, conformance, curriculum** |
| ops-mason | Staff | builds and tears down access routes and perimeters |
| ops-warden | Staff | operational access lanes, stewardship, runbooks |
| kings-guard | Staff | adaptive defence, observation, containment |
| whitehat-security | Staff | offensive validation |
Two words that must not drift: **ops-warden and ops-mason own access lanes** —
how a worker reaches a host. **access-engine owns access rules** — whether they
may.
---
## The doctrine in fifteen lines
1. No privilege from cognition.
2. Every privileged action crosses a deterministic authority boundary.
3. Tool availability is not permission.
4. Principal and actor remain distinguishable.
5. Assistant and autonomous operation are different security modes.
6. Autonomous agents use independent identities and explicit mandates.
7. Authority is least-privileged, scoped, and time-bounded.
8. Delegation attenuates.
9. Security posture may reduce authority but must not expand it.
10. Emergency revocation works without agent cooperation.
11. Agents do not casually modify the policies defining their own ceiling.
12. Credentials are ephemeral implementation artifacts of authorization.
13. Audit evidence is protected from the actor being audited.
14. Failure of critical policy or authorization dependencies fails closed.
15. Production guarantees must survive incorrect agent behavior.
## Agentic operating modes
The distinction Gate House exists to keep sharp.
**Assistant** — a human is engaged and can redirect or stop at human latency.
The human remains the principal; the agent remains a visible actor. *A human
disconnecting must never silently promote the session into autonomous
privileged operation.*
**Autonomous** — a scheduled or triggered agent acts without supervision, and
therefore requires unique identity, a named owner, an explicit mandate, an
authority ceiling, runtime and concurrency limits, budgets, an independent kill
switch, and audit reconstruction.
## The conformance loop
Doctrine that no engine implements is fiction. Gate House is only real if this
turns:
```text
WHO
principal
actor
runtime identity
WHERE
tenant
environment
resource
WHAT
requested operation
WHY
task
mandate
delegation
UNDER WHICH CONDITIONS
policy
approval
posture
quotas
budgets
UNTIL WHEN
TTL
→ GRANT or DENY
gate-house asserts an invariant
→ the engines implement it
→ whitehat-security tries to break it
→ kings-guard observes it in operation
→ findings return to gate-house as doctrine change
```
Gate House should provide:
- deterministic authorization;
- principal/actor separation;
- delegation and attenuation;
- authority ceilings;
- tenant and environment constraints;
- task- and resource-scoped grants;
- short-lived authority;
- approval binding;
- posture-dependent restrictions;
- quotas and change-rate controls;
- independent circuit breakers;
- credential-binding integration;
- explainable decisions;
- protected audit evidence.
---
## What Gate House Does Not Own
## Repository map
Gate House is intentionally **not** a security monolith.
| System | Responsibility |
| Path | What it is |
|---|---|
| **User Engine** | users, identities, memberships |
| **Tenant Engine** | tenant and organizational boundaries |
| **Key Cape** | authentication and federation |
| **Gate House** | deterministic authorization |
| **Secrets Engine** | credential abstraction and lifecycle orchestration |
| **OpenBao** | secret storage, PKI, leases, dynamic secret engines |
| **Ops Warden** | operational execution |
| **Ops Mason** | construction, reconciliation, recovery |
| **King's Guard** | adaptive security observation and response |
| **Whitehat Security** | adversarial testing and validation |
| [`INTENT.md`](INTENT.md) | why this repository exists; the re-cut in full |
| [`SCOPE.md`](SCOPE.md) | in scope / out of scope |
| [`spec/ActiveSecretsManagementCanon_v0.3.md`](spec/ActiveSecretsManagementCanon_v0.3.md) | the working canon — invariants, controls, profiles, assurance tests |
| [`ArchitectureBlueprint.md`](ArchitectureBlueprint.md) | architecture; **predates the re-cut and is being revised** |
| [`decisions/decisions.md`](decisions/decisions.md) | decision records — start with GH-DEC-2026-001 |
| [`history/`](history/) | reference notes; the 2026-08-28 review is the origin of the current shape |
| [`workplans/`](workplans/) | work in flight |
A useful shorthand:
```text
User Engine identifies
Tenant Engine contextualizes
Key Cape authenticates
Gate House authorizes
Secrets Engine provisions
OpenBao protects
Ops Warden operates
Ops Mason constructs / restores
King's Guard observes / defends / adapts
Whitehat Security attacks / validates
```
**Status.** Specification-only; no code, by design. `INTENT.md`, the decision
record, and the canon standard reflect the current shape.
`ArchitectureBlueprint.md` still describes the withdrawn engine framing in its
component, evaluation-order, API, and storage sections; its domain model,
operating modes, change dynamics, MCP integration, and test program survive.
---
## Agentic Operating Modes
Gate House treats two agentic modes as distinct security regimes.
### Agent Assistant Coding
A human developer or operator remains actively engaged with the agent.
```text
human principal
↓
assistant agent
↓
Gate House
↓
bounded delegated authority
↓
execution
```
The human remains the primary operational principal, but Gate House should preserve the agent as an actor where practical.
A human session ending must not silently convert the workflow into privileged autonomy.
### Autonomous Agent Coding
A scheduled or triggered agent operates without continuous human supervision.
```text
governance mandate
↓
agent/workload identity
↓
Gate House
↓
task-scoped authority
↓
execution
```
Autonomous agents require:
- unique identity;
- named owner;
- explicit mandate;
- explicit authority ceiling;
- runtime limit;
- credential TTL;
- concurrency limit;
- token/compute/tool-call budgets;
- independent kill switch;
- audit trail;
- lifecycle termination.
---
## Deterministic Security Substrate
Gate House follows one non-negotiable design rule:
> **No protected action succeeds merely because an intelligent system believes it should.**
An LLM may decide:
> "I should restart the production service."
It may not decide:
> "Therefore I am authorized to restart the production service."
Authorization belongs to deterministic policy enforcement.
That policy may be dynamic:
```text
ALLOW production.restart
IF
actor.role == "operations-agent"
AND environment == "production"
AND service.team == actor.team
AND incident.status == "active"
AND approval.valid == true
AND approval.action == request.action
AND approval.target == request.target
AND now < approval.expiry
```
For the same authoritative input state, the result must be reproducible and auditable.
---
## King's Guard Integration
King's Guard is the adaptive security system around Gate House.
King's Guard may detect:
- anomalous tool usage;
- unexpected behavioral drift;
- compromised workloads;
- unusual change velocity;
- cross-tenant disturbance;
- declining confidence in an actor.
It may then publish a bounded posture signal.
Example:
```text
actor: agent-934
posture: DEGRADED
confidence: 0.72
reason: anomalous-tool-usage
```
Gate House converts that posture into deterministic authority consequences:
```text
IF posture == DEGRADED
THEN
deny production.write
allow production.read
require step_up for staging.write
```
Adaptive systems may automatically **reduce** authority.
They must not probabilistically manufacture additional authority.
---
## Secrets Engine and OpenBao Integration
Gate House separates authorization from credential materialization.
```text
agent requests DB read
│
▼
Gate House
│
GRANT SELECT
orders-prod
TTL 15m
│
▼
Secrets Engine
│
choose credential mechanism
│
▼
OpenBao
│
issue leased credential
│
▼
execution gateway
```
The credential is an implementation artifact of the grant.
This keeps organizational authorization outside the vault itself while still using OpenBao as the protected credential engine.
---
## Domain Model
Initial concepts:
- **Principal** — who authority originates from;
- **Actor** — who attempts the action;
- **Runtime Identity** — concrete executing workload;
- **Mandate** — standing organizational authorization;
- **Delegation** — scoped transfer of authority;
- **Authority Ceiling** — maximum authority an actor can obtain;
- **Grant** — positive scoped authorization;
- **Denial** — negative authorization decision;
- **Approval** — independent authorization artifact;
- **Posture** — trusted security-state input;
- **Credential Binding** — mapping from grant to technical credential;
- **Decision Evidence** — audit record of why a decision occurred.
---
## Example Authority Request
Conceptually:
```yaml
principal:
id: user:alice@example
actor:
id: agent:deploy-agent-22
runtime:
id: spiffe://netkingdom/prod/deployer/22
tenant: tenant:acme
environment: production
task:
id: release-7.2.1
request:
action: production.deploy
resource: cluster/payments
mandate:
id: release-automation
approval:
id: approval-9432
constraints:
ttl: 20m
max_mutations: 1
```
Possible decision:
```yaml
decision: GRANT
policy_version: authz-2026-08-24
authority:
action: production.deploy
resource: cluster/payments
expires_in: 20m
mutation_limit: 1
credential_binding:
type: aws-sts
provider: secrets-engine
```
The exact wire format is not fixed yet.
---
## Change Dynamics
Agentic systems change infrastructure faster than humans can.
Gate House should therefore support a **Change Dynamics Envelope**.
Potential dimensions:
- concurrent mutating agents;
- maximum actions per grant;
- maximum resources per task;
- task duration;
- credential TTL;
- agent-chain depth;
- deployment frequency;
- destructive-action quota;
- token and compute spend;
- external-service spend;
- read/write separation.
Budgets are useful blast-radius controls.
They are not authorization.
---
## Circuit Breakers
Autonomous write authority should be independently suspendable.
```text
NORMAL
↓
threshold / invariant violation
↓
AUTONOMOUS WRITE DISABLED
↓
READ / DIAGNOSE AVAILABLE
↓
STEP-UP / HUMAN INTERVENTION
```
When degraded, preserve observability before mutation authority.
---
## Initial Reference Scenarios
### 1. Human-Assisted Kubernetes Diagnostics
A developer uses a coding agent to inspect production logs.
- human principal retained;
- agent actor visible;
- read-only authority;
- short TTL;
- no mutation rights;
- auditable tool use.
### 2. Autonomous Release Agent
A scheduled agent deploys an approved release.
- independent workload identity;
- release mandate;
- workload federation;
- production deployment only;
- no IAM modification;
- bounded runtime;
- complete audit chain.
### 3. Dynamic Database Access
An agent requests temporary `SELECT` access.
- Gate House authorizes;
- Secrets Engine materializes;
- OpenBao generates leased credentials;
- credentials are kept outside LLM context;
- lease expires automatically.
### 4. King's Guard Containment
King's Guard marks an actor as degraded.
- Gate House removes write authority;
- Ops Warden performs authorized containment;
- King's Guard verifies the result.
### 5. Policy Self-Escalation
An agent attempts to broaden its own permission boundary.
- Gate House denies;
- event is audited;
- security telemetry may be forwarded to King's Guard.
---
## Initial Implementation Areas
The first prototype will likely need:
```text
gate-house/
├── api/
│ ├── authorization-request
│ ├── decision
│ └── grant
├── domain/
│ ├── principal
│ ├── actor
│ ├── mandate
│ ├── delegation
│ ├── authority
│ └── posture
├── policy/
│ ├── engine
│ ├── policies
│ └── test
├── grants/
│ ├── issuance
│ ├── ttl
│ └── revocation
├── approvals/
├── limits/
│ ├── quota
│ ├── budget
│ └── concurrency
├── integrations/
│ ├── user-engine
│ ├── tenant-engine
│ ├── key-cape
│ ├── secrets-engine
│ ├── openbao
│ ├── kings-guard
│ └── ops-warden
├── audit/
├── test/
│ ├── deterministic
│ ├── adversarial
│ └── integration
└── docs/
```
This is a direction, not yet a mandatory repository structure.
---
## Design Principles
1. **Small control plane, explicit boundaries.**
2. **Deterministic final authorization.**
3. **Least authority by default.**
4. **Principal and actor are not collapsed.**
5. **Delegation attenuates.**
6. **Credentials are implementation artifacts, not authority.**
7. **Short-lived authority beats standing privilege.**
8. **Tool discovery never implies authorization.**
9. **Adaptive security may restrict; it does not invent privilege.**
10. **Agents cannot casually edit their own authority ceiling.**
11. **Emergency controls do not depend on agent cooperation.**
12. **Security decisions are explainable and auditable.**
13. **Production guarantees must survive incorrect agent behavior.**
---
## Non-Goals for the First Prototype
The first implementation does not need to:
- implement a new identity provider;
- replace OpenBao;
- implement a complete secrets manager;
- implement King's Guard;
- implement a general SIEM;
- perform anomaly detection;
- solve every cloud authorization model;
- become an IAM suite;
- invent a new policy language;
- support every agent protocol;
- provide autonomous remediation.
It should prove that a clean deterministic authority plane can coordinate these systems.
---
## Success
Gate House succeeds when a developer can look at any privileged action and answer:
> **Who acted? On whose behalf? Under which mandate? Against what resource? For what action? Under which policy and constraints? For how long? And why was it allowed?**
And when the system can also prove:
> **An agent could not have exceeded that authority merely by deciding to do so.**
---
## Status
Gate House is currently at the **reference architecture / research prototype** stage.
The Active Secrets Management Canon provides the initial conceptual baseline. The next step is to turn the authority model into executable contracts, policy decisions, and end-to-end reference scenarios.
---
## Motto
> **Agents decide what to attempt. Gate House decides what may cross the boundary.**
> **Agents decide what to attempt. Engines decide what may cross the boundary.
> Gate House decides what the boundary is for.**