Skip to content

concepts

Intended Documentation

Authority Runtime Pipeline

The end-to-end path a request takes through Intended — interpret, evaluate, issue, enforce, audit — with the real request shape, decision outcomes, and guarantees.

intermediate7 min readimplemented

Authority Runtime Pipeline#

The authority runtime pipeline is the path every request takes through Intended. A caller submits a proposed action; the runtime interprets it, evaluates it against policy, and — only if the result is approved — issues a signed Authority Token. The downstream system verifies that token locally before it executes. Every step is recorded in a tamper-evident audit log.

The operating rule the whole pipeline enforces is No Token, No Action.

The authority loop
A request flows through interpret, resolve, evaluate, issue, and enforce. Stage 3 produces one of three outcomes — APPROVED (200), ESCALATED (202), or DENIED (403). A token is minted only on APPROVED, and no action runs without it. Every stage writes to the hash-chained audit log.

Stage 3 is the decision point. Only APPROVED mints a token; ESCALATED and DENIED produce none. Enforcement is gated on a valid token.

The request: an Intent#

A request to the primary endpoint, POST /intent, is a structured Intent, not free text. The current contract is coupled to a concrete target (today, GitHub-shaped risk context); the load-bearing fields are:

FieldTypeNotes
tenantIdstringMust match the tenant your credential resolves to
actorobject{ id, type }, where type ∈ user · service · agent · system
targetSystemstringThe system the action targets (e.g. acme/platform-api)
proposedActionstringWhat the actor wants to do
riskContextobjectDeclared risk factors (below) plus target metadata
idempotencyKeystring?Optional; de-duplicates retried submissions

riskContext carries the inputs to the risk score: baseRiskScore (0–100), policyCompliant, requiresPrivilegedAccess, touchesProduction, containsSensitiveData, and a github block.

json
{
  "tenantId": "tenant_acme_prod",
  "actor": { "id": "svc-ci-bot", "type": "service" },
  "targetSystem": "acme/platform-api",
  "proposedAction": "dispatch release workflow",
  "riskContext": {
    "baseRiskScore": 42,
    "policyCompliant": true,
    "requiresPrivilegedAccess": false,
    "touchesProduction": false,
    "containsSensitiveData": false,
    "github": { "owner": "acme", "repo": "platform-api", "ref": "refs/heads/main", "workflowId": "release.yml" }
  }
}

Invalid bodies are rejected with 400 VALIDATION_ERROR (Zod field issues) before any evaluation runs.

Stage 1–2: Interpret#

The Large Intent Model (LIM) interprets the action and projects a set of signals onto the request — a confidence score, extracted risk signals (does this touch production, require privilege, handle sensitive data), an action classification, and process/sequence-conformance signals. LIM is an interpreter, not a single-label classifier: it can emit ranked hypotheses, but only the primary drives the decision (the alternatives are preserved in the audit record). The Enterprise Capability Engine then situates the interpreted intent in the tenant's business-capability context.

Stage 3: Evaluate#

The policy engine makes the decision. It is rule-based and deterministic, not a fixed checklist:

Load active policy sets

The engine loads the tenant's currently active, versioned policy sets. The exact versions are recorded for audit.

Match rules

Rules are filtered to those whose bindings match the intent (action, target, actor role, environment) and whose conditions hold. Conditions support operators EQ, NEQ, IN, NOT_IN, GT, GTE, LT, LTE, EXISTS.

Resolve by severity — most severe wins

Among matched rules, the most severe outcome wins: DENY > REQUIRE_APPROVAL > ESCALATE > ALLOW. If no rule matches, the result is DENY (fail-closed).

Apply LIM signals (upgrade-only)

LIM signals can only raise severity, never lower it: low interpretation confidence, a conflict between extracted risk and declared risk, or a low process-conformance score can turn an ALLOW into an ESCALATE or DENY — but nothing can turn a DENY into an ALLOW.

Record the trace

The full decision — matched rules, rationale, gate trace, risk score — is written to the audit log regardless of outcome.

Risk score#

The risk score is computed additively from riskContext and capped at 100:

riskScore = baseRiskScore
          + (requiresPrivilegedAccess ? 20 : 0)
          + (touchesProduction        ? 20 : 0)
          + (containsSensitiveData    ? 15 : 0)   // capped at 100

The modifier weights are tenant-overridable. Thresholds (defaults: escalate above 50–60, deny above 80) decide how the score influences the outcome.

The three outcomes#

POST /intent resolves to exactly one of three outcomes, each with a distinct HTTP status:

DecisionHTTPResult
APPROVED200Authority Token issued; execution attempted
ESCALATED202Human approval required; no token; escalationId returned
DENIED403Fail-closed; no token; no execution

Warning

The modern policy engine's internal enum is ALLOW / DENY / REQUIRE_APPROVAL / ESCALATE; the POST /intent response surfaces the legacy form APPROVED / ESCALATED / DENIED. REQUIRE_APPROVAL and ESCALATE both surface as ESCALATED. The standalone POST /authority/evaluate endpoint returns the four-value form directly. Keep the two vocabularies distinct when you parse responses.

If the loop itself fails for any reason, it fails closed: 500 AUTHORITY_LOOP_FAILED, no token.

Stage 4: Issue#

Only an APPROVED decision mints a token. The Authority Token is an Ed25519 JWT signed with the tenant's private key, carrying claims that bind it to this exact intent, tenant, adapter, and a single-use nonce, with a hard 300-second maximum lifetime. It is returned in the response as authorityDecisionToken. The full structure and verification model are in the Authority Token Model.

Response shape#

json
{
  "intentId": "8aa3f5f6-b1a9-4c5b-a29f-b489f7d0be58",
  "correlationId": "a9d903e0-8b45-4a2f-9d30-6f9ce7d04d78",
  "authorityDecision": {
    "decision": "APPROVED",
    "riskScore": 42,
    "policyCompliant": true,
    "rationale": ["policy set passed"],
    "gateTrace": [{ "gate": "policy", "outcome": "PASSED", "reason": "matched allow rule" }]
  },
  "authorityDecisionToken": "eyJhbGciOiJFZERTQSIsImtpZCI6...",
  "execution": { "attempted": true, "status": "executed", "adapterId": "github-actions-adapter" },
  "audit": { "entriesWritten": 5, "latestHash": "sha256:..." }
}

On an escalation the body instead carries escalationId and approvalRequestId, and authorityDecisionToken is null.

Stage 5: Enforce#

Enforcement happens at the boundary, in the adapter that executes the action — and it is fail-closed by construction. The connector SDK's BaseAdapter.execute() always validates the token first and never calls the concrete action if validation fails:

Decode the key id

The adapter reads the kid from the token header.

Fetch the tenant public key

It resolves the tenant's public key for that kid. Key id pinning is mandatory — an unknown or unpinned kid is rejected.

Verify the signature and claims

Ed25519 signature check, then assert the token's tenantId, adapterId, and adapterTarget match this execution, that decision === "APPROVED", and that the token has not expired.

Consume the nonce (single-use)

The nonce is atomically consumed in the database (unique per tenant). A replayed token whose nonce is already consumed is rejected.

Execute or reject

Only on success does the adapter run the action. Any failure returns { status: "rejected", reason } — there is no fallback path.

Tip

Verification is a local operation: the adapter needs only the tenant's public key (cacheable, rotatable by kid), not a callback to the runtime. This keeps the execution path fast and removes Intended as a runtime single point of failure.

Guarantees#

  • Fail-closed — no matching policy, an interpretation failure, or any loop error all resolve to deny. The system never defaults to allow.
  • Deterministic — the same intent against the same policy set yields the same decision; severity resolution and default-deny are fixed.
  • Auditable — every evaluation appends to the per-tenant, SHA-256 hash-chained audit log, linking intent, decision, policy versions, token, and execution under one correlationId.
  • Single-use authority — a token authorizes exactly one action and cannot be replayed; the nonce is consumed at enforcement.
  • Tenant isolation — policies, keys, and tokens never cross a tenant boundary.
Authority Runtime Pipeline | Intended