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

Complete GH-WP-0001-T04 authority context contract

Browse source 
Assistant: codex
Assistant-Model: gpt-5.6-sol
Assistant-Session: 01a05e30-2884-71b0-98d7-7edd16ae737b
This commit is contained in:
tegwick 2026-09-01 20:25:25 +02:00
parent 6076d5d9ba
commit 75ce37207f
5 changed files with 409 additions and 2 deletions
Download patch file Download diff file Expand all files Collapse all files

2
README.md
View file

@ -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 |

83
docs/adr/ADR-001-canonical-authority-context-contract.md Normal file
View file

@ -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.

82
docs/adr/ADR-002-principal-actor-runtime-identity-model.md Normal file
View file

@ -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.

233
docs/contracts/authority-context.md Normal file
View file

@ -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.

11
workplans/GH-WP-0001-foundation.md
View file

@ -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