Complete GH-WP-0001-T04 authority context contract
Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a05e30-2884-71b0-98d7-7edd16ae737b
This commit is contained in:
parent
6076d5d9ba
commit
75ce37207f
5 changed files with 409 additions and 2 deletions
233
docs/contracts/authority-context.md
Normal file
233
docs/contracts/authority-context.md
Normal 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.
|
||||
|
||||
Loading…
Add table
Add a link
Reference in a new issue