Skip to content
ContractSpec
Start here

Core guide · Concepts · 3 min read

Authentication, policy and scoped approval

Give each decision a clear owner and prove that denied requests never reach the protected handler.

Source context

Source-guided · d58fa5b7

Repository links may require access. Source inspection is separate from a clean public-package installation.

AN INTERACTIVE READING MAP

Get the shape of this guide.

Move through the ideas, inspect their relationships, or make a focused reading path. The complete guide stays below.

READING SEQUENCE

Understand how the ideas connect

01 / READING POINT

Separate the decisions

Authentication establishes who is calling. Policy decides whether that subject may perform a particular operation in context. Scoped approval supplies evidence that a specific request or class of effects has been reviewed. A ceremony requirement can require additional, fresh verification at execution time.

These mechanisms answer different questions. An authenticated user is not automatically permitted to perform every action, and a visible review button is not an approval receipt.

1 / 4

0 points in your packet

Separate the decisions

Authentication establishes who is calling. Policy decides whether that subject may perform a particular operation in context. Scoped approval supplies evidence that a specific request or class of effects has been reviewed. A ceremony requirement can require additional, fresh verification at execution time.

These mechanisms answer different questions. An authenticated user is not automatically permitted to perform every action, and a visible review button is not an approval receipt.

QuestionMechanismHost responsibility
Who is calling?Authentication contextResolve identity through a trusted source
May this caller do this?Policy decisionSupply and test the decision implementation
Has this request been approved?Scoped approvalVerify the receipt against operation, subject, input and effects
Is fresh verification required?CeremonyClaim and complete the required host-bound ceremony

Declare the approval boundary explicitly

For an operation with execution.approval, the shared preparation path checks for approval evidence before handler entry. Missing evidence yields APPROVAL_REQUIRED with reason missing_receipt. If evidence exists but the host has no approval port, the reason is approval_runtime_unavailable.

Tags, presentation labels and MCP tool annotations describe an operation; they do not opt it into this enforcement. Configure the actual requirement and the trusted verifier.

Bind evidence to the request

The approval port receives the operation key and version, subject context, parsed input, required effects and requested cost. Use those values to decide whether the supplied evidence authorizes this invocation, rather than treating the presence of a token as permission.

Connect has its own request, scope, digest, expiry and durable signature checks. Use the appropriate host integration for the boundary you are implementing; do not assume two differently typed receipt systems are interchangeable.

Prove denial before success

Use a disposable handler with an invocation counter. Send valid input as an authenticated fixture subject without approval through REST and MCP. Assert the actual denial from each adapter and a counter that remains zero.

Then exercise the verifier you intend to ship: wrong subject, wrong scope or expiry should remain denied where those conditions apply. Only add an allowed path when its receipt is actually verified. A stub that always returns allow is useful for UI development, but it does not demonstrate authorization.

Find the point where the handler can begin.

Take an operation that explicitly requires approval. Change one condition and inspect the expected path from the captured runtime guide.

Which request are you inspecting?

A CONCRETE SITUATION

Input preparation stops the path early.

The request omits an input required by the operation schema.

01 / Input

Parse and validate the request against the declared schema.

What changes

The request cannot become a valid prepared input.

What stays explicit

No visible button or descriptive tag makes the missing value valid.

Follow the consequence

A denial test for approval should use otherwise valid input, so it actually reaches the approval boundary.

An authored situation, grounded in the linked source guides. Choosing a case explores its expected responsibilities; it does not execute an operation.