diff --git a/ArchitectureBlueprint.md b/ArchitectureBlueprint.md index 3c38f4a..968e942 100644 --- a/ArchitectureBlueprint.md +++ b/ArchitectureBlueprint.md @@ -4,8 +4,8 @@ **Project family:** NetKingdom **Artifact:** `ArchitectureBlueprint.md` **Status:** Current — doctrine architecture; no runtime role -**Version:** 0.3 -**Date:** 2026-09-10 +**Version:** 0.4 +**Date:** 2026-10-22 **Decision:** `decisions/decisions.md` GH-DEC-2026-001 --- @@ -87,12 +87,12 @@ mean and reviews whether the path conforms. | --- | --- | | 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 | +| user-engine | authoritative processor of user, account, and membership facts; the records stay in Tooling | +| tenant-engine | authoritative processor of tenant and organizational facts; the records stay in Tooling | +| zone-engine | authoritative processor of zone identity and membership facts; the records stay in Tooling | | 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 | +| secrets-engine | processor for credential lifecycle; OpenBao holds the credential records | +| OpenBao | Tooling store: 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 | @@ -105,6 +105,36 @@ Two boundaries are lexical as well as architectural: - an **access rule** says whether an action may occur and belongs to access-engine. +### 2.2 Engine + +An engine is the deterministic processor for one domain, as proposed in +[ADR-015](docs/adr/ADR-015-engine-is-a-processor.md). The canon states the +domain. The engine implements it. Tooling holds the records. The engine owns +the record type and is the only admitted client of its store. + +One library has three manifestations. The library performs the domain +operations. The CLI runs that library in a process. A service is the same +process kept running for one scoped environment. At start, that process is +injected with the credential for that environment alone. The credential is how +the process reads its inputs and writes its outputs. Callers do not receive it. + +An operator is a Staff actor who starts or calls an engine. Authentication +establishes who the operator is. Permission to use one named instance, or a +named set of instances, is an access rule rendered by access-engine. The +engine enforces that result and does not decide it. Holding the use-privilege +does not confer the injected credential, and it does not authorize every +operation the domain can perform. The engine still applies its deterministic +rules to each call. + +An operator who is allowed to delegate may assign a task to another operator +who is allowed to use an engine the delegator cannot use. The delegate uses +the engine. The delegator does not gain that use-privilege or the injected +credential. Engines stay stringent. Operators stay flexible. An operator's +reliability does not relax an engine check. + +Until ADR-015 is accepted, this section records the proposed doctrine. The +security-layer standard is amended only after acceptance. + ## 3. Core domain model Gate House fixes the following meanings. Owning engines choose storage and wire @@ -335,6 +365,11 @@ An unavailable credential mechanism means execution cannot proceed. It does not cause another component to invent authority or silently substitute a broader credential. +The credential injected into an engine instance is that instance's +encapsulated privilege, defined in §2.2. It authorizes the process toward its +store for one scoped environment. It is not the operator's authority to use +the instance, and it is not issued to the operator. + ## 10. MCP and tooling doctrine MCP is a capability interface, not an authority system. Tool discovery means @@ -707,6 +742,7 @@ return path. | ADR-010 | Still meaningful — Autonomous mandate model. | | ADR-013 | Still meaningful — MCP authorization integration. | | ADR-014 | Still meaningful — policy self-modification protection. | +| ADR-015 | Proposed — an engine is a processor; an operator's use-privilege is separate from the credentials injected into the instance. | Future ADRs in Gate House decide doctrine and responsibility boundaries. They must not select an Engine's implementation technology or create a Gate House diff --git a/docs/adr/ADR-015-engine-is-a-processor.md b/docs/adr/ADR-015-engine-is-a-processor.md new file mode 100644 index 0000000..254e252 --- /dev/null +++ b/docs/adr/ADR-015-engine-is-a-processor.md @@ -0,0 +1,131 @@ +# ADR-015 — Engine as processor and operator use-privilege + +**Repository:** gate-house +**Status:** proposed +**Date:** 2026-10-22 + +## Context + +The security-layer standard defines an Engine as a deterministic API for a +modeled concept. It types that layer into PDP, PIP, Evidence, and Lifecycle. +It does not say whether an engine is a library, a command, or a service, or +where the records of the concept live. + +Repository intents filled that gap in incompatible ways. Some engines describe +themselves as the store of their facts. `secrets-engine` describes itself as a +processor over OpenBao: the vault holds the credential records, and the engine +turns an already-rendered access decision into a scoped change and a one-shot +delivery. The same estate also needs a rule for who may start that process. +The process holds credentials the calling operator must not hold. Without a +separate use-privilege, "the operator uses the engine" collapses into "the +operator receives the engine's credentials," or into the engine deciding for +itself who may call it. + +## Decision + +An engine is a deterministic processor for one domain. It implements that +domain from its canon. It does not hold the domain's records. Tooling holds +the records. The engine owns the record type: the schema, the invariants, and +the legal transitions. It is the only admitted client of its store. + +The implementation has three manifestations of one library: + +1. **Library.** The domain operations: validate, explain, plan, and compute + the next state. A caller may use these pure operations without receiving a + store credential. +2. **CLI.** The library in a process. At start, the process is injected with + the credential for one scoped environment. That credential lets the process + read its inputs and write its outputs. It is not returned to the caller. +3. **Service.** The same process, kept running for a scoped environment that + needs a standing processor. A service is not a second implementation and + does not receive the credentials of any other environment. + +`secrets-engine` is the reference shape. OpenBao is the store. The engine is +the lifecycle processor. Build, test, and production are different scoped +environments and different processes. + +### Authentication and the operator + +An **operator** is a Staff actor, human or agent, who starts or calls an +engine. Authentication, by key-cape, establishes who the operator is. It does +not grant use of an engine. + +Two privileges stay distinct. + +- The **encapsulated privilege** is the credential injected into one engine + instance at start. It is how that process reads its inputs and writes its + outputs. The operator does not possess it, see it, or reuse it outside the + process. +- The **use-privilege** is permission to start and call one named engine + instance, or a named set of instances. `access-engine` renders that + permission. The engine enforces the rendered result and does not decide it. + A use-privilege is not a grant of the encapsulated credential, and it is not + permission for every operation the domain can perform. The engine still + applies its own deterministic rules to each call, including any decision + record that domain requires. + +Starting an instance and calling it both require a use-privilege for that +instance. The operator who starts it is the operator under whose use the +process is injected. One process is injected for one scoped environment. + +### Delegation between operators + +An operator who is allowed to delegate tasks may assign a task to another +operator who holds a use-privilege the delegator does not hold. The delegate +uses the engine. The delegator does not gain the use-privilege and does not +gain the encapsulated credential. + +Delegation assigns work. It does not transfer either privilege. The delegate +must already hold the use-privilege. The assignment cannot widen what the +delegate is allowed to do, and it cannot authorize an operation the engine's +own rules refuse. Engines stay deterministic and stringent. Operators stay +flexible. Reliability of an operator is a Staff expectation. It does not relax +an engine check. + +## Consequences + +- An engine intent that says the running service is the store of record is + aligned later: the database, the vault, or the log is Tooling, and the + engine remains the only admitted client and the owner of the record type. +- `user-engine`, `tenant-engine`, `approval-engine`, and the access decision + log are processors over records in Tooling. Approval consumption remains one + transaction that the engine opens against its store. A user or tenant fact + remains readable only through the engine. +- `audit-core` appends and verifies. The tamper-evident store is Tooling. +- A Deployment exists when a scoped environment keeps the process running. A + one-task environment manifests the same binary as a CLI. Absence of a + Deployment does not make the engine incomplete. +- This ADR selects no database, framework, or hosting technology, and it + creates no Gate House runtime surface. +- Acceptance of this ADR is a later edit of its status. The security-layer + standard's engine section is amended only after that acceptance. + +## Alternatives rejected + +### The engine holds the records + +Rejected because the layer cut already gives persistence to Tooling. Putting +the store inside the engine makes the process the system of record and invites +every other engine intent to do the same. + +### The operator receives the encapsulated credential + +Rejected because the operator could then bypass the processor and call Tooling +directly. That is the failure the use-privilege exists to prevent. + +### The engine decides who may use it + +Rejected because that decision is an access rule. An engine that renders it +becomes a second policy decision point. + +### Delegation transfers the delegate's privileges to the delegator + +Rejected because assigning a task would then widen the delegator. The +delegate already holds the use-privilege. The delegator remains without it. + +### Library only, or service only + +Rejected because the domain implementation, the process boundary, and the +standing manifestation are one implementation. Collapsing them either gives +callers the store credential inside a library, or forces a Deployment for a +one-task environment.