diff --git a/README.md b/README.md index 2d986de..5752e4a 100644 --- a/README.md +++ b/README.md @@ -170,6 +170,8 @@ gate-house asserts an invariant | [`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 | +| [`docs/contracts/authority-context.md`](docs/contracts/authority-context.md) | normative authority-context vocabulary consumed by access-engine | +| [`docs/adr/`](docs/adr/) | architecture decisions for Gate House doctrine and contracts | | [`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 | diff --git a/docs/adr/ADR-001-canonical-authority-context-contract.md b/docs/adr/ADR-001-canonical-authority-context-contract.md new file mode 100644 index 0000000..48efcb2 --- /dev/null +++ b/docs/adr/ADR-001-canonical-authority-context-contract.md @@ -0,0 +1,83 @@ +# ADR-001 — Canonical authority context contract + +**Repository:** gate-house +**Status:** accepted +**Date:** 2026-09-01 +**Workplan:** GH-WP-0001-T04 + +## Context + +Gate House owns the vocabulary of an agentic authority request, while +access-engine is NetKingdom's only policy decision point. The surviving +`ArchitectureBlueprint.md` material named the required concepts, but left them +inside an obsolete canonical authorization-request example that also portrayed +Gate House as an in-path service. + +Without a standalone contract, consumers can collapse identity roles, infer an +operating mode, treat caller-supplied context as verified fact, or implement +incompatible field meanings. Conversely, prescribing an access-engine API or +executable policy schema here would recreate the Staff/Engine boundary error +resolved by GH-DEC-2026-001. + +## Decision + +Gate House publishes +[`authority-context.v1`](../contracts/authority-context.md) as a logical claims +contract. + +The contract defines eight claims: + +1. principal; +2. actor; +3. runtime identity; +4. tenant; +5. environment; +6. mandate; +7. task; +8. operating mode. + +It defines their meanings, source and binding expectations, mode-specific +requiredness, fail-closed conditions, evidence obligations, and versioning. + +The contract is deliberately not a wire format, token, API, policy package, or +runtime resolver. Access-engine owns those representations and the +deterministic interpretation of the context alongside verified identity +claims, action, resource, approval, posture, and other policy inputs. + +No field grants authority by being present. Caller assertion and authoritative +evidence must remain distinguishable, and security-critical resolution failure +fails closed. + +## Consequences + +- Access-engine has a stable semantic target without Gate House taking a + runtime position. +- Identity, tenancy, zone, and mandate sources remain owned by their respective + authorities; this contract only says what access-engine must be able to + express and bind. +- Transport-specific schemas may differ, but their mappings must preserve the + logical claims and invariants. +- New authorization-significant claims, modes, or semantic changes require a + new contract version and Gate House review. +- The obsolete Blueprint example remains historical input until GH-WP-0001-T05 + revises that document; this contract is the current authority-context record. + +## Alternatives rejected + +### Publish a Gate House `/authorize` schema + +Rejected because Gate House is Staff and holds no request-time position. +Owning an endpoint or executable decision schema here would contradict +GH-DEC-2026-001 and INV-02. + +### Let each consumer infer the vocabulary + +Rejected because principal/actor collapse, mode ambiguity, and unverified +caller context are precisely the semantic failures the doctrine must prevent. + +### Put every claim into a credential + +Rejected because credentials are implementation artifacts of authorization, +not the source of authority. The context need only remain linked across the +authoritative systems and decision evidence. + diff --git a/docs/adr/ADR-002-principal-actor-runtime-identity-model.md b/docs/adr/ADR-002-principal-actor-runtime-identity-model.md new file mode 100644 index 0000000..7782cf2 --- /dev/null +++ b/docs/adr/ADR-002-principal-actor-runtime-identity-model.md @@ -0,0 +1,82 @@ +# ADR-002 — Principal, actor, and runtime identity model + +**Repository:** gate-house +**Status:** accepted +**Date:** 2026-09-01 +**Workplan:** GH-WP-0001-T04 + +## Context + +Agentic execution introduces at least three identity questions: + +- on whose behalf does authority originate; +- who is directly attempting the action; +- which concrete workload instance will execute it. + +A single `subject`, `user`, or service-account field cannot answer all three. +Collapsing them permits invisible impersonation, obscures delegation, makes a +reusable service identity look like a concrete runtime, and prevents evidence +from showing whether a human, agent, or workload actually acted. + +The roles can sometimes resolve to the same underlying subject in a direct, +non-delegated operation. That does not make the roles synonymous. + +## Decision + +Principal, actor, and runtime identity are separate semantic roles throughout +authority input and decision evidence: + +- **Principal** is the human, organization, workload, or system on whose behalf + authority originates. +- **Actor** is the entity directly attempting the action and authenticating as + itself. +- **Runtime identity** is the concrete workload instance performing execution. + +Implementations must preserve the three roles independently and bind each to +the appropriate authoritative evidence. They must not fill one missing role by +copying another, use impersonation to hide the actor, or replace a concrete +runtime identity with a reusable actor/service name. + +In Assistant mode, the active supervising human is principal and the agent is +actor. In Autonomous mode, the autonomous actor has an independent identity, +and its principal relationship is established through the organizational +context and governed mandate. Both modes identify the concrete runtime. + +Delegation preserves the originating principal and authenticates the actor as +itself. Delegated and child authority attenuate; identity linkage never widens +the authority ceiling. + +The roles need not all be embedded in one token. They must remain verifiably +linked across identity, authorization, credential issuance, execution, and +decision evidence. + +## Consequences + +- Policies can distinguish who benefits, who requests, and which workload + executes. +- Assistant actions remain attributable to both the supervising human and the + assisting agent. +- Autonomous actors cannot rely on a borrowed human identity or a shared + generic machine identity to erase accountability. +- Runtime replacement or replay can be evaluated separately from actor + identity. +- Existing transports with one subject field need an explicit mapping or an + extension before they can conform to `authority-context.v1`. + +## Alternatives rejected + +### One canonical subject + +Rejected because it erases delegation and cannot represent the agentic chain +without overloading one identifier. + +### Principal and actor only + +Rejected because a stable actor identity does not identify the concrete +workload instance that executed a particular action. + +### Treat runtime identity as audit-only metadata + +Rejected because runtime identity can be security-relevant policy input and +must be bound before a positive decision when policy depends on it. +Reconstructing it after execution is too late to enforce the boundary. diff --git a/docs/contracts/authority-context.md b/docs/contracts/authority-context.md new file mode 100644 index 0000000..bb70271 --- /dev/null +++ b/docs/contracts/authority-context.md @@ -0,0 +1,233 @@ +# Authority context contract + +**Repository:** gate-house +**Consumer:** access-engine (currently flex-auth) +**Status:** normative for GH-WP-0001-T04 +**Version:** authority-context.v1 +**Date:** 2026-09-01 +**Records:** [ADR-001](../adr/ADR-001-canonical-authority-context-contract.md), [ADR-002](../adr/ADR-002-principal-actor-runtime-identity-model.md) + +This contract defines the context an agentic authority request must be able to +express. Gate House owns the vocabulary and its invariants. Access-engine owns +the request representation, authoritative resolution, policy evaluation, and +decision. + +The contract is a logical claims contract, not a wire format, token format, API, +or executable schema. Conforming transports may represent it differently, but +must preserve these meanings and relationships. + +## Boundary + +Authority context is one input to an authorization decision. It is composed +with: + +- verified identity claims from the estate's identity authorities; +- the requested action, resource, and normalized parameters; +- applicable policy, approval, posture, quotas, budgets, and authority ceiling; +- authoritative tenant, environment, and resource facts. + +No authority-context field grants authority by its presence. In particular, a +declared principal, mandate, task, or operating mode is not proof that the +declaration is valid. Access-engine must bind or resolve security-relevant +claims to authoritative evidence before using them in a positive decision. + +Gate House does not receive this context in-path, resolve it, or render a +decision. + +## Logical envelope + +`authority-context.v1` has this logical shape: + +```yaml +schema_version: authority-context.v1 +request_id: req-01JQY6M4N6V5 + +authority_context: + principal: + id: user:alice@example + kind: human + actor: + id: agent:release-assistant + kind: agent + runtime_identity: + id: spiffe://netkingdom/prod/release-assistant/7f91 + tenant: + id: tenant:acme + environment: + id: production + mandate: null + task: + id: release:payments:7.2.1 + kind: release + operating_mode: assistant +``` + +The surrounding authorization request carries evidence for these claims. The +logical separation is intentional: + +```yaml +verified_identity_claims: + principal: identity-claim-ref:human-session-779381 + actor: identity-claim-ref:agent-session-22 + runtime_identity: identity-claim-ref:workload-attestation-7f91 +``` + +The `identity-claim-ref:*` values are illustrative references, not a prescribed +format. Identity-claim schemas and issuers are owned by the identity estate, +not by this contract. + +## Claims + +| Claim | Meaning | Authority source or binding requirement | +| --- | --- | --- | +| `principal` | Human, organization, workload, or system on whose behalf authority originates. | Bound to verified identity, an authenticated delegation, or an authoritative relationship such as a mandate. | +| `actor` | Entity directly attempting the action. | Bound to the authenticated actor identity. A caller-supplied alias is insufficient. | +| `runtime_identity` | Concrete workload instance performing execution. | Bound to verified workload identity or attestation. It is not a reusable service name. | +| `tenant` | Security and organizational domain in which the action occurs. | Resolved against authoritative tenant and resource facts. Caller declaration alone is insufficient. | +| `environment` | Governed operational environment containing the target. | Resolved from authoritative resource or zone facts. Free-form caller labels are insufficient. | +| `mandate` | Versioned reference to the standing organizational authorization defining why an autonomous actor exists. | Required and authoritatively resolved in Autonomous mode. It is neither a credential nor a grant. | +| `task` | Stable reference to the bounded unit of work for which authority is requested. | Bound to the workflow or orchestration record where one exists. Human-readable text alone must not widen authority. | +| `operating_mode` | Security regime under which the request runs: `assistant` or `autonomous`. | Declared explicitly and checked against session, identity, and mandate evidence. It must not be inferred merely to make a request pass. | + +Identifiers are opaque, stable identifiers in the namespace of their owning +system. Display names and mutable labels may accompany them, but must not +replace them in policy or decision evidence. + +`kind` values classify the identifier; they do not imply permissions. The +canonical principal kinds are `human`, `organization`, `workload`, and +`system`. The canonical actor kinds are `human`, `agent`, `workload`, and +`system`. A transport may use a controlled extension, but access-engine must +not give an unknown kind authorization significance until policy recognizes it. + +## Requiredness by operating mode + +The contract concerns agentic authority requests. Both modes require explicit +context rather than reconstructing it later from logs. + +| Claim | Assistant | Autonomous | +| --- | --- | --- | +| `principal` | Required; the actively supervising human principal. | Required; the organization, workload, or system on whose behalf the mandate exists. | +| `actor` | Required; the assisting agent, distinct in role from the human principal. | Required; the autonomous actor with its own identity. | +| `runtime_identity` | Required for the concrete agent workload/session. | Required for the concrete workload instance. | +| `tenant` | Required for tenant-scoped action; otherwise an explicit estate-defined non-tenant scope is required. | Same. | +| `environment` | Required. | Required. | +| `mandate` | Optional; it must not replace live human supervision or authorize continuation after disconnect. | Required, including an immutable version or revision when mandates are mutable. | +| `task` | Required. | Required and bounded by the mandate. | +| `operating_mode` | Required; exactly `assistant`. | Required; exactly `autonomous`. | + +An omitted tenant is not a wildcard. A non-tenant request must carry an +explicit scope defined by estate policy; access-engine decides whether that +scope is recognized. + +## Identity-role invariants + +Principal, actor, and runtime identity are separate semantic roles even when a +non-delegated operation legitimately gives two roles the same underlying +subject. Conforming implementations must: + +1. preserve all three roles independently in policy input and decision + evidence; +2. never copy the actor into a missing principal field, or the reverse; +3. never replace runtime identity with a reusable actor or service identifier; +4. represent delegation without impersonation: the principal remains visible + while the actor authenticates as itself; +5. ensure delegated or child authority does not exceed the authority available + to its parent; +6. treat a mismatch between a declared role and authoritative identity evidence + as a denial condition. + +The model does not require every credential or token to carry every role. It +requires the roles to remain linked across identity, authorization, credential +issuance, execution, and decision evidence so the chain can be reconstructed. + +## Operating-mode invariants + +### Assistant + +- A verified, active human session supplies the principal. +- The agent remains identifiable as actor and by runtime identity. +- Ending or losing the human session must not change the mode to Autonomous. +- A mandate, if present, cannot substitute for active supervision. +- A continuation requiring privilege after supervision ends requires a new + Autonomous request under a governed mandate and independent identity. + +### Autonomous + +- The actor uses an independent identity; no borrowed human credential may + stand in for it. +- The request names an explicit, current mandate and a task within it. +- The mandate resolves to a named owner, authority ceiling, environment and + resource bounds, lifecycle, and termination path. +- Runtime, concurrency, credential TTL, and applicable change-dynamics bounds + are separate policy inputs or mandate facts; naming the mandate does not + satisfy them by itself. + +A mode transition is governance-sensitive. It is not an update to an in-flight +context object and must not be implemented as fallback behavior. + +## Resolution and failure semantics + +For a protected operation, access-engine must fail closed when: + +- a required claim is absent, malformed, or uses an unsupported contract + version; +- an identity role cannot be bound to verified identity evidence; +- authoritative and caller-supplied values conflict; +- tenant, environment, mandate, or task resolution is security-critical and + unavailable or stale beyond policy; +- an Autonomous mandate is absent, expired, revoked, ambiguous, or does not + cover the task; +- Assistant supervision is absent or no longer active; +- the operating mode is unknown or inconsistent with the evidence; +- resolving delegation would widen authority or erase the principal/actor + distinction. + +`DEFER` may be used only for non-security-critical enrichment. It is not a +fallback for missing evidence needed to decide a protected operation. + +Unknown extension claims have no authorization effect until this contract and +access-engine policy recognize them. A consumer must not silently reinterpret +a known claim or treat an unknown value as a wildcard. + +## Decision evidence + +For each decision, the evidence must retain: + +- the contract version and request identifier; +- the resolved values of all eight authority-context claims; +- the authoritative source or evidence reference used for each + security-relevant resolution; +- the declared and evaluated operating mode; +- mandate and task versions where applicable; +- any conflict, omission, or stale-input reason contributing to a non-grant + decision; +- the access-engine policy identifier and version that interpreted the context. + +This is an attribution and reconstruction obligation, not a claim that an +archive proves an event was emitted. Audit completeness remains the emitting +system's obligation. + +## Versioning + +- `authority-context.v1` fixes the meanings of the eight claims and the two + operating-mode values. +- Additive metadata may be transported without changing the version only when + it cannot affect authorization under v1. +- A semantic change, new mode, changed requiredness, or new claim intended to + affect authorization requires a new contract version and Gate House review. +- Access-engine must reject unsupported major versions for protected + operations; it must not guess at compatibility. + +## Conformance statements + +An access-engine representation conforms when it can demonstrate that: + +- every logical claim maps to an unambiguous input field; +- authoritative evidence is distinguishable from caller assertion; +- the requiredness and failure rules above are enforced; +- principal, actor, and runtime identity remain separate through decision + evidence; +- Assistant and Autonomous requests cannot silently fall back into one + another; +- no claim in this contract grants authority without deterministic policy. + diff --git a/workplans/GH-WP-0001-foundation.md b/workplans/GH-WP-0001-foundation.md index d8a4494..623ce30 100644 --- a/workplans/GH-WP-0001-foundation.md +++ b/workplans/GH-WP-0001-foundation.md @@ -6,7 +6,7 @@ domain: infotech repo: gate-house status: active state_hub_workstream_id: "2ec4cf1a-a73f-5793-9738-8d8019cccca8" -updated: "2026-08-28" +updated: "2026-09-01" --- # Foundation @@ -67,7 +67,7 @@ the standard from `proposed` to `accepted` once the three have answered. ```task id: GH-WP-0001-T04 -status: todo +status: done priority: high state_hub_task_id: "7903d142-9763-5b3f-839d-2a1599130a2b" ``` @@ -78,6 +78,13 @@ access-engine consumes as input claims alongside verified identity claims. Record it as ADR-001 and ADR-002. This is the deliverable that makes the doctrine consumable rather than descriptive. +Done — `docs/contracts/authority-context.md` publishes +`authority-context.v1` as the logical claims contract, with mode-specific +requiredness, authoritative binding, fail-closed, evidence, and versioning +rules. `docs/adr/ADR-001-canonical-authority-context-contract.md` and +`docs/adr/ADR-002-principal-actor-runtime-identity-model.md` record the contract +boundary and the three-role identity model. + ```task id: GH-WP-0001-T05 status: todo