diff --git a/.repo-classification.yaml b/.repo-classification.yaml new file mode 100644 index 0000000..a7dd5a1 --- /dev/null +++ b/.repo-classification.yaml @@ -0,0 +1,26 @@ +repo_classification: + standard: Repo Classification Standard + version: "1.0" + classified_at: "2026-08-24" + classified_by: human + category: tooling + domain: infotech + secondary_domains: + - agents + capability_tags: + - access-control + - identity + - governance + - platform + - evidence + business_stake: + - technology + - operations + business_mechanics: + - control + - operation + notes: >- + Deterministic authority plane for human, workload, and agent actions + across NetKingdom, and the reference implementation of the Active + Secrets Management (ASM) Plane. Long-lived control-plane component + reused across the ecosystem; not a domain hub, not a secrets manager. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..7e868cb --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,4 @@ +# Agent instructions — gate-house + +Orient: INTENT.md → SCOPE.md → workplans/. +Workplan prefix: `GH-WP-`. diff --git a/spec/ArchitectureBlueprint.md b/ArchitectureBlueprint.md similarity index 100% rename from spec/ArchitectureBlueprint.md rename to ArchitectureBlueprint.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..1a41229 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,129 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Repository status + +`gate-house` is currently **specification-only**. There is no source code, build system, +test runner, or dependency manifest — the repo is Markdown documents plus its repo-manager +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. + +## 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: + +> 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 maxim that governs every design decision here: + +> **Cognition proposes. Authority disposes. Infrastructure executes.** + +Gate House deliberately does **not** own identity lifecycle, tenancy lifecycle, +authentication, secret storage, PKI, anomaly detection, or execution. Those belong to sibling +NetKingdom systems (User Engine, Tenant Engine, Key Cape, Secrets Engine, OpenBao, Ops Warden, +Ops Mason, King's Guard, Whitehat Security). When a proposed feature starts absorbing one of +those responsibilities, that is a design error, not a scope extension. + +## Document hierarchy — read in this order + +1. **`spec/ActiveSecretsManagementCanon_v0.3.md`** — the normative standard Gate House + implements. Uses RFC-style MUST/SHOULD/MAY. Owns the numbered invariants `INV-01`…`INV-12` + and the assurance tests `T-01`…`T-10`. Gate House conforms to the Canon; the Canon is not + 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. + +When these conflict, the Canon wins over INTENT, and INTENT wins over the Blueprint. Fix the +lower document rather than diverging. + +## Invariants that constrain any implementation + +These are load-bearing. Code or design that violates one is wrong even if it works: + +- **No privilege from cognition.** An LLM deciding an action is appropriate never makes it + authorized. The final privilege boundary is deterministic policy. +- **Tool availability is not permission.** MCP tool registration/discovery means the operation + exists, not that invoking it is allowed. No token passthrough — downstream authority is + separately issued and bound to the target resource. +- **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 + forbidden pattern. +- **Evaluation is monotonic toward restriction** (Blueprint §13). No stage after the authority + ceiling may expand beyond it. +- **Fail closed.** Unavailable policy engine, unresolvable context, unavailable audit, or + stale authoritative state → DENY. Per-dependency semantics are in Blueprint §28. +- **Assistant mode and Autonomous mode are different security regimes.** A human session + ending must never silently promote the workflow to privileged autonomy. +- **Agents cannot edit their own authority ceiling**; policy self-modification is a separately + governed path and high-value security telemetry. +- **Audit evidence is protected from the actor being audited**, and every privileged action + must be reconstructable from it. +- **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. + +## Repo-manager registration + +Registered with repo-manager as `category: tooling`, `domain: infotech` (secondary: `agents`), +workplan prefix **`GH-WP`** (owned in `~/repo-manager/config/workplan-prefix-registry.yaml`). +`.repo-classification.yaml`, `SCOPE.md`, `AGENTS.md`, and `workplans/` are that baseline. + +```bash +rmgr conform --path . # check against tooling-flavor standards +rmgr observe --path . # snapshot JSON +rmgr workplan update --path . --workplan-id GH-WP-0001 --status active +rmgr update-task-status --path . --task-id GH-WP-0001-T01 --status progress +``` + +`rmgr` lives at `~/repo-manager/.venv/bin/rmgr`. Workplan and task state is edited through +these commands (file + git commit), not by hand-registering anything in the State Hub: write +the file, commit, then sync. `SCOPE.md` is derived from `INTENT.md` — keep them consistent. + +## 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. +- **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"). +- 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`. + +## 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). diff --git a/SCOPE.md b/SCOPE.md new file mode 100644 index 0000000..4ab8645 --- /dev/null +++ b/SCOPE.md @@ -0,0 +1,38 @@ +# Scope + +Derived from `INTENT.md`. Gate House is deliberately narrow: it decides whether +a requested action is authorized, and represents that decision as bounded, +time-limited authority that downstream systems enforce. + +## In scope + +- deterministic authorization decisions (`GRANT` / `DENY` / `REQUIRE_APPROVAL` / `DEFER`) +- principal / actor / runtime-identity separation +- mandates, delegation, and attenuation +- authority ceilings +- tenant-, environment-, resource-, task-, and time-scoped grants +- approval binding and step-up requirements +- posture intake from King's Guard, restricting only +- change-dynamics limits: quotas, budgets, concurrency, circuit breakers +- credential-binding contract to Secrets Engine / OpenBao +- emergency revocation independent of the actor +- decision evidence, explainability, and protected audit +- policy and decision versioning; fail-closed semantics + +## Out of scope + +Owned elsewhere in NetKingdom — see the responsibility table in `INTENT.md`: + +- human identity lifecycle and memberships — User Engine +- tenant and organizational boundaries — Tenant Engine +- authentication and federation — Key Cape +- credential abstraction and lifecycle orchestration — Secrets Engine +- secret storage, PKI, leases, dynamic secret engines — OpenBao +- operational execution — Ops Warden +- construction, reconciliation, recovery — Ops Mason +- anomaly detection, behavioral risk inference, security memory — King's Guard +- adversarial testing and attack simulation — Whitehat Security + +Also out of scope: inventing a new policy language, becoming an IAM suite, +secret scanning, SIEM, autonomous remediation, and supporting every agent +protocol. See "Non-Goals for the First Prototype" in `ArchitectureBlueprint.md` §3. diff --git a/workplans/GH-WP-0001-foundation.md b/workplans/GH-WP-0001-foundation.md new file mode 100644 index 0000000..afb9392 --- /dev/null +++ b/workplans/GH-WP-0001-foundation.md @@ -0,0 +1,69 @@ +--- +id: GH-WP-0001 +type: workplan +title: "Foundation" +domain: infotech +repo: gate-house +status: proposed +--- + +# Foundation + +Establish the repository baseline and reach milestone **M0 — Executable Skeleton** +as defined in `ArchitectureBlueprint.md` §41: a request must produce a +deterministic `GRANT` / `DENY` with structured audit evidence. + +```task +id: GH-WP-0001-T01 +status: todo +priority: high +``` + +Establish the repository baseline: classification, scope, agent instructions, +workplan spine. + +```task +id: GH-WP-0001-T02 +status: todo +priority: high +``` + +Record the early ADRs that gate implementation choices — ADR-001 canonical +authority request schema, ADR-002 principal/actor/runtime identity model, +ADR-003 policy engine selection. Backlog in `ArchitectureBlueprint.md` §40. + +```task +id: GH-WP-0001-T03 +status: todo +priority: high +``` + +Define the canonical authorization request and decision schemas from +`ArchitectureBlueprint.md` §7 and §8. + +```task +id: GH-WP-0001-T04 +status: todo +priority: medium +``` + +Implement the `/authorize` service skeleton with static policy and the +evaluation order in `ArchitectureBlueprint.md` §13, monotonic toward restriction. + +```task +id: GH-WP-0001-T05 +status: todo +priority: medium +``` + +Emit structured decision evidence for every authorization call, per +`ArchitectureBlueprint.md` §24. + +```task +id: GH-WP-0001-T06 +status: todo +priority: medium +``` + +Seed the adversarial test suite with the fail-closed and self-escalation cases +(Canon T-04, T-09; `ArchitectureBlueprint.md` §34.4, §34.8).