gate-house/docs/contracts/authority-context.md

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