RFC: define the verified approver assertion (MCP-SECURITY-GATEWAY-1.0 §4.3 and ADR-0030) #3918

Summary

Two places in AGT stop a risky action and wait for a person. The MCP gateway calls approval_callback and blocks. ADR-0030 suspends the decision and records the outcome in an approval chain. Both surfaces store who approved, and neither defines a way to check it. What stands behind the recorded name is the approval service's word for it. Authenticated transport proves which service sent the message. It does not prove which human, if any, was at the other end. The hash-linked chain then computes over that name faithfully, which makes the arithmetic sound and the input unverified.

This RFC proposes carrying a signature made by the approver's own authenticator, so a reader of the record can check it later without asking the approval service anything. Three separable pieces:

1. A timeout rule for approval_callback. Two paragraphs of spec text, independent of the rest.
2. A result object in place of the bare ApprovalStatus string, which makes PENDING usable.
3. An optional approver_evidence object on both surfaces, covering refusals as well as approvals, with one normative rule about how a runtime reads it.

Piece 3 is optional, and a deployment that omits it behaves exactly as it does today. Piece 1 is the only change that constrains an existing implementation, and it constrains it toward the fail-closed posture the spec already takes everywhere else.

Motivation

Three reasons this is worth doing now.

1. The repository already left this blank on purpose, and wrote down that it had.

ADR-0030 (#2953, merged 2026-06-11), from the proposing PR's own summary of what the ADR does:

• requires verified approver identity, durable pending state, replay protection, and execution-time revalidation;
• fails closed on timeout, restart, malformed responses, or binding mismatch;
• defines linked approval evidence without requiring signed receipts in the first implementation;

So verified approver identity is required, and the mechanism that would make it verifiable was left for later. This RFC is that later piece.

A reviewer on the same PR named the gap as a test case. Roman Pelevin, listing the negative matrix he wanted driving the implementation:

• return an approver string that is not bound to authenticated transport;

That test asks a good question and stops one step short. An approver string bound to authenticated transport is still a string the approval service chose.

The merged webhook contract (#3097) then stated the rule and left the mechanism open:

ADR-0030 section 5 supersedes that: a webhook is a transport, not an approver identity type, and the contract must carry the binding and refuse body-supplied identities that are not backed by a verified assertion.

The implementation honors that by refusing to trust an unverified identity, and delegates the judgment to a caller-supplied hook:

an approve is honoured only when the approver identity is verified by response_verifier

Nothing in the specification says what a verified assertion is, so response_verifier is a hole every operator fills privately. This RFC proposes the first defined format that fits it.

The audit schema already carries the field, unbacked. #2473, merged 2026-05-22:

• approver_did — DID of the approving principal (approval-chain identity)

and, from the same PR:

A new spec subsection §4.3.1 documents the v1.0 caveat (fields recorded but not yet hash-covered)

An identifier for the approver is already persisted. What is missing is anything that makes it more than a label.

2. Three things an operator cannot do today.

An auditor holding the sealed record can confirm the digest matches the action, the policy version, the chain integrity, and the expiry. Those checks are real, and they all pass while the approver claim goes unchecked.

First, nobody can prove a human was involved. An automated process holding the approval service's credentials satisfies every check on both surfaces. ADR-0030 keeps an LLM out of terminal resolution and the implementation enforces it, which is the right intent, and neither reaches a compromised or misconfigured approval service. #3805 raises the same defect against a different AGT record, the verifiable-compliance-receipt proposal, and states the consequence plainly:

every stated verification check (signature validity, chain integrity, policy binding) can pass in full for a receipt chain that is entirely self-signed [...] an auditor reading "signature valid, chain intact, policy hash matches" could reasonably read that as "this was checked," when the honest claim is closer to "this agent process didn't (visibly) lie to itself."

Read that against an approval chain instead of a receipt chain and nothing about it changes.

Second, the assurance label is self-issued. identity_assurance is a value the approval service applies to itself. A verifier cannot tell a strong credential from a weak one, or from none.

Third, a refusal carries no more weight than an approval. A DENIED result is as unbacked as an APPROVED one, which matters in the case where somebody later claims they refused.

3. The same distinction is already argued in this repository, for a different field.

#3658, on data residency:

ADR-0008 models residency as declared metadata (PolicyMetadata.processing_regions: list[str], AgentPolicyClaims.data_residency). A declared region string is unverifiable. Nothing binds it to evidence, and nothing carries it across more than one hop.

The declared-versus-verified distinction is where sovereignty claims actually fail. Deploying in an EU region is necessary and not sufficient.

Substitute the approver name for the region string and the passage needs no other edit. That RFC also says why leaving the weak form in place is worse than leaving the field empty:

Rejected because an unverifiable residency claim is worse than none: it creates documented, auditable confidence in a property nobody checked.

identity_assurance is that claim today. The compliance obligation sits in the same family, and #3658 made that point too:

AGT ships an Annex IV exporter (governance/annex_iv.py) and an evidence pipeline (governance/evidence_pipeline.py), so the toolkit already takes conformity documentation seriously. Residency is the one obligation in that family with no mechanism behind it.

Approver identity is the sibling case.

Worked example, which is the acceptance test I would want.

A gateway lists payments.transfer in sensitive_tools. An agent proposes a transfer of 40,000 to account A. Policy escalates. A person approves on a hardware authenticator.

• Re-presenting that approval for a transfer of 40,000 to account B fails, and fails at the digest rather than at a lookup.
• A verifier holding the sealed record, a published public key, and the action confirms that a specific enrolled credential authorized that specific action, with no live call to the gateway, the approval service, or any vendor.
• The same verifier reads approve or refuse out of the signature, not out of a field sitting beside it.
• A compromised approval service cannot manufacture a record that passes those checks.
• If the callback never answers, the call is blocked.

Where those stand today. The first already holds under ADR-0030, which binds the approval to the action digest and revalidates at execution. It has no equivalent on the gateway callback in §4.3, which returns a bare status with nothing to bind. The second, third, and fourth fail on both surfaces, because all three depend on evidence that does not exist. The fifth is unspecified.

So this is not a repair of the binding. The binding is correct. It is the approver claim inside it that nothing checks.

Detailed Design

What to add.

Two schema additions and one normative rule. The timeout rule is a fourth, separate item, and it has its own section below.

1. The callback returns an object instead of a bare status. PENDING blocks correctly today, and the caller cannot learn which approval it waits on, when the wait ends, or how to resume. A reason_code also separates three cases a blocked call currently collapses: a person refused, the request expired unanswered, and no eligible approver was reachable. The third is a staffing failure that presents identically to a security decision. A callback that returns a bare status string keeps working, read as {"status": "<value>"}.

2. That object carries optional approver_evidence, and so does ApprovalChainEntry. An array, because one stage can require several approvers. The first registered format is a WebAuthn assertion. The array is the extension point, so the design does not hard-code one credential technology.

Normative rule. When approver_evidence is present and verifies, the runtime MUST derive identity_assurance from the evidence and MUST NOT accept a transport-asserted value for that entry. Where policy requires evidence, absent, malformed, or failing evidence resolves to deny.

// approval_callback(agent_id, tool_name, params) -> ApprovalResult
{
  "status": "APPROVED",          // APPROVED | DENIED | PENDING, semantics unchanged
  "approval_id": "<string>",     // REQUIRED when status is PENDING
  "expires_at": "<RFC3339>",
  "redrive_url": "<uri>",
  "reason_code": "<string>",     // low-cardinality
  "approver_evidence": [ ]       // optional
}

"approver_evidence": [
  {
    "format": "webauthn.assertion/1",          // registry key
    "decision": "APPROVED",                    // or DENIED, and inside the digest
    "canonicalization_profile": "<string>",
    "credential_id": "<base64url>",
    "client_data_json": "<base64url>",         // carries challenge = nonce || op_hash
    "authenticator_data": "<base64url>",       // rpIdHash, flags (UP/UV/BE/BS), signCount
    "signature": "<base64url>",
    "aaguid": "<uuid>",
    "attestation_ref": "<uri|null>",
    "nonce": "<base64url>",
    "op_hash": "<base64url>",
    "assertion_at": "<RFC3339>",
    "co_signatures": [ ]                       // optional
  }
]

op_hash   = SHA-256( JCS( canonicalize({ profile, decision, fields }) ) )   // Unicode NFC
nonce     = 32 random bytes
challenge = nonce || op_hash

The timeout rule, which can land on its own.

§4.2 fails closed when no callback is configured. §4.4 fails closed on DENIED and PENDING. The spec says nothing about a configured callback that does not answer, which is the normal case when a human sits at the other end.

#3106 took this position for agent-mesh and merged it on 2026-07-01:

CallbackApproval.on_timeout implied timeout auto-approval, which is unsafe at a governance boundary (and was already a dead parameter: a timeout always denies).

Proposed text extends that to this spec:

A gateway MUST define a timeout for approval_callback. On timeout the gateway MUST treat the result as DENIED and MUST NOT permit the invocation to proceed. Where the configured approval mechanism involves a human, a gateway SHOULD return PENDING rather than holding the callback open, and SHOULD NOT require a synchronous response within a fixed sub-second budget.

This is separable from everything above and could merge alone.

Staging.

1. The timeout rule. Two paragraphs, independent of everything below.
2. The result object, with approver_evidence unpopulated. Makes PENDING usable and gives reason_code a home.
3. The evidence object and the normative rule, plus the webauthn.assertion/1 format and the profile registry.
4. SDK parity across the ports, following the pattern in feat: language parity for require_approval approval chains (TypeScript, .NET, Rust, Go) #3083.
5. Optional co-signature, and the rendering conformance profile if wanted.

Open questions. These are design details, not blockers. I would rather settle them in review than guess.

1. Should decision sit inside the hashed structure as proposed, or alongside it with a separate binding rule?
2. Where do the evidence-format registry and the canonicalization-profile registry live? These specs, a separate registry document, or the ACS manifest schema?
3. Where does the credential-to-identity mapping live? AgentMesh already binds a sponsor_email to every agent identity, and reusing that beats standing up a second registry.
4. Is a FIDO Metadata Service snapshot a runtime dependency the toolkit will take, or should AAGUID policy be host-supplied?

What we would contribute.

Token (tokencore.com) builds FIDO2/WebAuthn biometric hardware authenticators with match-on-chip fingerprint verification and device-bound credentials.

We will publish, under Apache 2.0, a reference approval_callback implementation and a conformance suite in the style of the 127 tests that shipped with #2363. The suite is the more useful artifact, because it lets a partner or an assessor hold any implementation to the same bar without reading anyone's source.

The proposal is vendor-neutral and satisfiable by any WebAuthn authenticator, including platform authenticators, at the assurance tier the evidence supports. We are offering the implementation and the test vectors, not asking for a vendor-specific path.

What I am asking for.

Three answers. The first is the only one that blocks anything.

1. A direction call: is verifiable approver evidence wanted in this repository at all? A no is a useful answer and I will stop there rather than keep refining it. A yes does not commit you to the field names above, which are a starting point for review and not the thing I am asking you to accept.

2. Where it belongs: this issue, or #3668. #3668 is open and asks for a principal on audit entries, which is the same problem from the audit side. I opened separately because this touches the gateway spec and ADR-0030 rather than the audit schema, and because the timeout rule has nothing to do with audit entries. If you would rather see one thread, say so and I will move the evidence half into #3668 and leave the timeout rule here.

3. Whether the timeout rule can proceed on its own. It is two paragraphs, it extends a position #3106 already merged, and it does not depend on anything else in this RFC. If the answer to question 1 is no, I would still like to know whether that piece is worth a PR.

If the direction call is yes, the next artifact from me is a docs(adr): propose ADR-00NN PR carrying the spec text for staging items 1 and 2, with the evidence object following once the registry questions above are settled. The Apache 2.0 conformance suite lands with it.

One timing question, so I do not land across work in flight. Is there anything currently moving through approval_protocol or mcp_gateway.py that this should sequence behind? I would rather wait than merge into a file somebody is mid-refactor on.

No urgency on my side. Happy to take any of this to a call if that is easier than issue comments.

Alternatives Considered

Declared-only, as the specification stands. The cheapest option, and it is what §4.3 and ADR-0030 specify today. Rejected for the reason #3658 gave when it faced the same choice for residency: an unverifiable claim is worse than none, because it creates documented, auditable confidence in a property nobody checked. If the project prefers this anyway, my strong suggestion is the one #3658 made in the same position, which is to label the field explicitly as declared-only in the spec text so identity_assurance cannot be mistaken for enforcement.

Leave it to implementation-level extensions, which §4.3 already allows. No spec change, no maintenance burden, and an operator who wants approver evidence can build it now. Rejected because that is the status quo, and the status quo is what produces the problem. Every operator who answers "who approved this" invents a private response shape, and none of them interoperate. #2473 added approver_did, #3668 proposes reason, argument digest and principal, and that is the same pressure surfacing twice in the audit schema. The hook already exists in response_verifier. The thing a private extension cannot supply is a shared definition of what that hook verifies, and the shared definition is the whole value.

Have the approval service sign a receipt, rather than the person. Much cheaper to deploy: no credential enrollment, no ceremony, no metadata service, and it does add real tamper-evidence over the current state. Rejected as an answer to this particular problem because it moves the signature without moving the trust. The approval service is the party under evaluation. #3805 quotes draft-etcheverry-action-ref-03 §5.2 on exactly this point: "The signer of the Decision record MUST be independent of the actor/executor whose action it authorizes." A service-signed receipt is a reasonable intermediate step, and it cannot carry the assurance tiers, so it should not be recorded as though it can.

Detect after the fact rather than bind before it. Reconciling approvals against executed actions afterwards is cheaper and needs no change to the approval path. Rejected because the hash-linked chain already provides tamper-evidence, and tamper-evidence is not the missing property. A chain proves nobody edited the record. It does not prove that anyone other than the acting service ever looked at the decision, and no amount of after-the-fact reading recovers a signature that was never taken.

Fold the whole thing into #3668. Attractive, and this one is a live question rather than a settled rejection, so it appears in the ask above as well. #3668 asks for reason, argument digest and principal on audit entries, which reaches the same problem from the audit side. I opened separately because the callback result shape and the timeout rule are not audit-schema changes, and because #3668 is scoped to agent-governance-opencode while this touches the gateway spec and ADR-0030. If maintainers would rather have one thread, say so and I will move the evidence half there and leave the timeout rule here.

Security Implications

What this does not prove.

#3658 set the convention for this section by stating its own limit in one line: "Hardware attestation proves what code is running. It does not prove where the machine is." The equivalent limit here is the display, not the geography.

A user-verification flag proves that an enrolled human, holding the credential, consented to a bound challenge. It does not prove the human saw the true action, because the action renders on a display outside the authenticator's trust boundary. A compromised approver host can misrepresent what is being approved. That is a property of any authenticator without a trusted display. W3C attempted transaction display in WebAuthn twice and abandoned it both times, which is why this scopes binding to named profiles instead of promising clear-signing of arbitrary API calls.

#3658 lands on "non-repudiation rather than prevention" as the honest description of what its split claim buys. The claim here is stronger than that, because the key sits with the person rather than with an operator who could sign either way, and it is still not proof that the person saw the true action. Two controls narrow the gap and are worth stating as expectations. Action content stays unreachable until the approver completes an authenticated ceremony, so a notification link on its own discloses nothing. And the notification carries a reference, a severity, and an expiry, with no action parameters.

Closing the remainder honestly takes a conformance profile for the rendering surface: what gets rendered, from which authority, in what order, with what truncation and homoglyph handling, plus a correspondence rule that every displayed material field is signed and every signed material field is displayed. Happy to contribute that if it is in scope.

New attack surface introduced.

Three things this adds that need treatment rather than assumption.

The canonicalization-profile registry becomes an integrity dependency inside the verification path. A substituted or wrongly resolved profile silently narrows what the signature covers, which is the false-accept case, and it is why the profile ID is inside the hashed structure and re-resolved from the evidence rather than from ambient configuration.

The FIDO Metadata Service becomes an availability dependency wherever AAGUID policy is enforced. A fail-closed posture there turns an MDS outage into a denial of every approval, which is a security control behaving as an availability incident. Open question 4 asks whether the toolkit wants that dependency at all, or whether AAGUID policy should be host-supplied.

Enrollment becomes the soft target. Evidence is only as good as the binding between a credential and a person, so whatever registers credentials inherits the trust that used to sit with the approval service. This RFC does not specify enrollment, and a deployment that gets enrollment wrong gets no benefit from the rest of it.

Out of scope, and worth naming so it is not assumed.

Per-action human approval does not fit workflows that propose actions at machine rate. The mechanism that resolves it is a bounded standing grant, where the digest covers a scope expression instead of a single action, with a maximum use count, a magnitude cap, a TTL, and a severity ceiling, all revocable, and no unbounded grant representable. It composes with the evidence object without changing it. Left out here to keep this reviewable.

Migration / Backward Compatibility

No breaking changes intended.

• approver_evidence is optional on both surfaces. Omitting it preserves current behavior exactly.
• A callback that returns a bare ApprovalStatus string keeps working, read as {"status": "<value>"}.
• Schema version bump on ApprovalChainEntry only. No change to ActionBinding, PolicyDecision, ApprovalRequest, or ApprovalResolution.
• Existing sealed entries keep verifying. An optional field that is absent changes no digest.
• The timeout rule is the only change that constrains an existing implementation. A gateway with no timeout today has to define one.

If that last item needs a migration path rather than a flag day, #3106 already set the shape for one in this project: warn by default, enforce under an opt-in strict mode, let an environment variable act as a floor that a per-handler setting cannot loosen, and make strict the default in a later major. Reusing that pattern rather than inventing a second one seems right.

Scope

Cross-package (2-3 packages)

Target Placement

Core (agent-os, agent-mesh, agent-hypervisor)

Prior Art

On #3668, the overlap is worth quoting, since it reaches the same problem from the audit side:

When an agent acts under delegated user identity, the target system may record the action as the human's.

Outside this repository, the relevant standards are W3C WebAuthn Level 3 for the assertion and its BE and BS flags, RFC 8785 JCS for canonicalization, which ADR-0030 already uses, and FIPS 201-3 with NIST SP 800-73 for the optional smart-card co-signature. Those are cited as credential and encoding standards, not as validation claims about any product.

Checklist

• I have searched existing issues and RFCs for duplicates
• I have read the ADR index (adr/index.md) for related decisions
• I am willing to implement this RFC or help review an implementation