diff --git a/CLAUDE.md b/CLAUDE.md index 1a41229..cadcaa6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -9,28 +9,38 @@ test runner, or dependency manifest — the repo is Markdown documents plus its baseline. Do not invent build/lint/test commands; if asked to "run tests", say there is nothing to run yet. The only commands that work today are the repo-manager ones below. -The first executable work is defined by milestone **M0** in the Blueprint (§41): a service -skeleton with `/authorize`, canonical request/decision schemas, static policy, and structured -audit output. +It is specification-only **by design**, not by earliness. Gate House is a Staff-layer +repository: its artifacts are specifications, decisions, workplans, and tasks. Do not +propose building a service here. Milestone M0 in the Blueprint (an `/authorize` skeleton) +has lapsed — see the re-cut below. ## What Gate House is -Gate House is the **deterministic authority plane** for NetKingdom — the reference -implementation of the Active Secrets Management (ASM) Plane. It answers exactly one question: +Gate House is the **council where NetKingdom's security and defence doctrine is +established, documented, taught, and supervised** — a **Staff**-layer repository in the +NetKingdom security layer model (`net-kingdom/canon/standards/security-layer-model_v0.1.md`). +It holds no runtime position and renders no authorization decision. -> may this principal/actor, in this tenant and environment, perform this action on this -> resource, under this mandate, with these constraints, until when → GRANT or DENY. +> **The mandate and the operating mode are Gate House's. The decision is access-engine's. +> The credential is secrets-engine's. The perimeter is ops-mason's and ops-warden's.** -The maxim that governs every design decision here: +**The re-cut (2026-08-28) is the single most important thing to know here.** Gate House was +seeded as a deterministic authority plane — `/authorize`, grant storage, revocation — and +that framing was withdrawn on its own argument: a decision point inside Gate House would put +the deterministic authority boundary inside the non-deterministic management layer, +violating INV-02, the first invariant this repo defends. `access-engine` (currently +`flex-auth`) is the only policy decision point in NetKingdom. + +Read `decisions/decisions.md` GH-DEC-2026-001 and +`history/2026-08-28-security-layer-model-and-gate-house-recut.md` before proposing any +architecture change. If a proposal has Gate House deciding, storing, evaluating, or +enforcing anything at request time, it is wrong regardless of how well it is built. + +The maxim that governs every design decision here — and, read across the layers, the +estate's layering rule: > **Cognition proposes. Authority disposes. Infrastructure executes.** -Gate House deliberately does **not** own identity lifecycle, tenancy lifecycle, -authentication, secret storage, PKI, anomaly detection, or execution. Those belong to sibling -NetKingdom systems (User Engine, Tenant Engine, Key Cape, Secrets Engine, OpenBao, Ops Warden, -Ops Mason, King's Guard, Whitehat Security). When a proposed feature starts absorbing one of -those responsibilities, that is a design error, not a scope extension. - ## Document hierarchy — read in this order 1. **`spec/ActiveSecretsManagementCanon_v0.3.md`** — the normative standard Gate House @@ -39,19 +49,23 @@ those responsibilities, that is a design error, not a scope extension. edited to accommodate Gate House. 2. **`INTENT.md`** — mission, scope boundaries, domain concepts, the 15 numbered Core Rules, use cases `UC-01`…`UC-05`, success criteria. This is the "why". -3. **`ArchitectureBlueprint.md`** — the "how". Domain model (§6), canonical authorization - request (§7) and decision (§8), component architecture (§10–11), policy evaluation order - (§13), integration contracts (§16–19), failure modes (§28), API surface (§26), ADR backlog - (§40), milestones M0–M8 (§41), architectural invariants `A-01`…`A-15` (§43). -4. **`README.md`** — public-facing summary. Keep it consistent with the above; it is a - derivative, not a source of truth. +3. **`decisions/decisions.md`** — decision records. GH-DEC-2026-001 ratifies the layer + model, the re-cut, and the access-engine reframing. Binding. +4. **`ArchitectureBlueprint.md`** — **predates the re-cut and is only partly valid.** Its + component architecture (§10–11), policy evaluation order (§13), API surface (§26), and + storage model (§25) describe an engine and are withdrawn; ADR-003 and milestones M0, M3, + M4 have lapsed. Its domain model (§6), authority context (§7), operating modes (§14–15), + change dynamics (§20), MCP integration (§19), and security test program (§34) survive. + Do not cite it without checking a section against INTENT first. +5. **`README.md`** — public-facing summary. A derivative, not a source of truth. -When these conflict, the Canon wins over INTENT, and INTENT wins over the Blueprint. Fix the -lower document rather than diverging. +When these conflict: the decision record wins over everything, then the Canon, then INTENT, +then the Blueprint. Fix the lower document rather than diverging. -## Invariants that constrain any implementation +## The doctrine Gate House maintains -These are load-bearing. Code or design that violates one is wrong even if it works: +These are load-bearing. Gate House authors and maintains them; the engines and Staff +repositories implement them. A document or proposal that violates one is wrong: - **No privilege from cognition.** An LLM deciding an action is appropriate never makes it authorized. The final privilege boundary is deterministic policy. @@ -63,10 +77,10 @@ These are load-bearing. Code or design that violates one is wrong even if it wor - **Posture may only restrict.** King's Guard (or any adaptive input) can reduce authority or demand step-up; it can never manufacture privilege. See Blueprint §16.2 for the explicitly forbidden pattern. -- **Evaluation is monotonic toward restriction** (Blueprint §13). No stage after the authority - ceiling may expand beyond it. +- **Evaluation is monotonic toward restriction.** No stage after the authority ceiling may + expand beyond it. (Evaluation itself is access-engine's; Gate House states the property.) - **Fail closed.** Unavailable policy engine, unresolvable context, unavailable audit, or - stale authoritative state → DENY. Per-dependency semantics are in Blueprint §28. + stale authoritative state → DENY. - **Assistant mode and Autonomous mode are different security regimes.** A human session ending must never silently promote the workflow to privileged autonomy. - **Agents cannot edit their own authority ceiling**; policy self-modification is a separately @@ -76,6 +90,8 @@ These are load-bearing. Code or design that violates one is wrong even if it wor - **Credentials are implementation artifacts of a grant**, materialized by Secrets Engine / OpenBao *after* authority exists — never the source of authority, never placed in model context. +- **Staff never touches Tooling directly.** It acts only through Engine APIs. This binds + Gate House itself: no direct database, OpenBao, or cluster client belongs in this repo. ## Repo-manager registration @@ -100,30 +116,36 @@ the file, commit, then sync. `SCOPE.md` is derived from `INTENT.md` — keep the ADRs (`ADR-nnn`), and milestones (`M0`–`M8`) are referenced across documents. Reuse the existing id when writing about a concept; append rather than renumber. - **Canon prose is normative** — preserve MUST/SHOULD/MAY exactly when editing it. -- **Domain vocabulary is fixed** by Blueprint §6 and INTENT's Domain Concepts: principal, - actor, runtime identity, tenant, environment, mandate, delegation, authority ceiling, - action, resource, grant, denial, approval, posture, credential binding, decision evidence. - Use these terms rather than synonyms ("user", "role", "token", "permission"). +- **Domain vocabulary is fixed** by INTENT's Domain Vocabulary: principal, actor, runtime + identity, mandate, delegation, authority ceiling, operating mode, posture, change dynamics + envelope, decision evidence. Use these rather than synonyms ("user", "role", "token", + "permission"). Two demarcations are normative: **access lane** (ops-warden, ops-mason) is + not **access rule** (access-engine); **doctrine** (gate-house) is not **runbook** (the lane + owner). "Control plane" is Engine vocabulary — do not apply it to Gate House. - Documents carry a frontmatter-style header block (Repository / Project family / Status / Version / Date). Keep it, and bump Status/Version/Date on substantive edits. - Diagrams and schema examples are plain ```text``` or ```yaml``` fenced blocks — no Mermaid. -- Decision types are the four in Blueprint §9: `GRANT`, `DENY`, `REQUIRE_APPROVAL`, `DEFER`. +- Decision types are `GRANT`, `DENY`, `REQUIRE_APPROVAL`, `DEFER` — rendered by + access-engine, named here. ## Where new work goes - `README.md`, `INTENT.md`, and `ArchitectureBlueprint.md` live at the repo root, matching the Blueprint's own reference layout (§32). External standards Gate House conforms to — the Canon — live in `spec/`. -- ADRs → `docs/adr/`, drawn from the backlog in Blueprint §40 (ADR-001 through ADR-014). -- Implementation, when it starts, should follow the reference layout in Blueprint §32 - (`api/`, `domain/`, `policy/`, `grants/`, `approvals/`, `limits/`, `integrations/`, `audit/`, - `test/{unit,integration,adversarial,scenarios}`, `deploy/`). That layout is explicitly - labelled a direction, not a constraint — deviate deliberately and say why. -- Technology is intentionally unfixed (Blueprint §31): HTTP/JSON first, OPA/Rego or Cedar as - policy candidates, PostgreSQL for grants/mandates/revocation, OIDC + SPIFFE/SPIRE for - identity. Do not hard-code a choice into the conceptual model — the domain model must not - depend on one policy engine. -- Adversarial tests are a first-class deliverable, not an afterthought: Canon `T-01`…`T-10` - and Blueprint §34 (malicious model, prompt injection, human disconnect, policy - self-modification, approval replay, cross-tenant, MCP token passthrough, audit loss, - circuit breaker). +- ADRs → `docs/adr/`, from the Blueprint §40 backlog. ADR-003 (policy engine selection) has + lapsed with the re-cut; ADR-001, ADR-002, ADR-006, ADR-009, ADR-010, ADR-013, ADR-014 + remain meaningful as contract and doctrine. +- Decision records → `decisions/decisions.md`, via `rmgr decision create|resolve`. Never + hand-write the YAML block; the tool mints identifiers and commits. +- History and reference notes → `history/YYYY-MM-DD-.md`, matching the convention in + ops-warden, zone-engine, and secrets-engine. +- Doctrine that stabilizes graduates into `net-kingdom/canon/standards/`, owned by gate-house + and published by net-kingdom. `security-layer-model_v0.1.md` is the first. +- **No implementation layout.** Blueprint §32's reference tree (`api/`, `policy/`, `grants/`, + `deploy/`, …) described the withdrawn engine and does not apply. If work here starts + producing services, schemas that resolve, or anything evaluated at request time, stop — + that belongs to an engine. +- Assurance tests `T-01`…`T-10` are **specifications** authored here and executed by + whitehat-security. Writing the specification is Gate House's job; running the attack and + judging whether the control held is not.