The Budget HTTP Authentication Scheme and 427 Budget Required Status Code
draft-mcgraw-httpapi-agent-budget-01
This document is an Internet-Draft (I-D).
Anyone may submit an I-D to the IETF.
This I-D is not endorsed by the IETF and has no formal standing in the
IETF standards process.
The information below is for an old version of the document.
| Document | Type |
This is an older version of an Internet-Draft whose latest revision state is "Active".
|
|
|---|---|---|---|
| Author | John Paul McGraw, Jr. | ||
| Last updated | 2026-06-10 (Latest revision 2026-05-05) | ||
| RFC stream | (None) | ||
| Formats | |||
| Stream | Stream state | (No stream defined) | |
| Consensus boilerplate | Unknown | ||
| RFC Editor Note | (None) | ||
| IESG | IESG state | I-D Exists | |
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-mcgraw-httpapi-agent-budget-01
HTTPAPI J. McGraw
Internet-Draft TaskHawk
Intended status: Standards Track 10 June 2026
Expires: 12 December 2026
The Budget HTTP Authentication Scheme and 427 Budget Required Status
Code
draft-mcgraw-httpapi-agent-budget-01
Abstract
Delegated software requesters are increasingly authorized to consume
paid or metered services, allocate account credits, or commit bounded
resources on behalf of human or organizational principals. Existing
HTTP authentication mechanisms indicate whether a requester holds a
credential, while RateLimit fields communicate server-advertised
quota and current service-limit information. Neither mechanism
directly conveys that the requester has been authorized by its
principal to consume or commit resources within a bounded limit
before a request is processed.
This document defines the 427 (Budget Required) HTTP status code, the
"Budget" HTTP authentication scheme, the Budget-Attestation HTTP
field, and a CBOR/COSE Budget-Attestation envelope. The mechanism is
algorithm-agile; the initial cose-ml-dsa profile uses existing JOSE
and COSE serializations for ML-DSA, with ML-DSA-65 as the baseline
algorithm and ML-DSA-87 available as a high-assurance deployment
policy option. An optional rail-keyed SLH-DSA signature can be used
by deployments that bind a budget attestation to a settlement rail.
This document does not define payment semantics and does not depend
on the HTTP 402 (Payment Required) status code.
About This Document
This note is to be removed before publishing as an RFC.
Status information for this document may be found at
https://datatracker.ietf.org/doc/draft-mcgraw-httpapi-agent-budget/.
Discussion of this document takes place on the HTTPAPI Working Group
mailing list (mailto:httpapi@ietf.org), which is archived at
https://mailarchive.ietf.org/arch/browse/httpapi/. Subscribe at
https://www.ietf.org/mailman/listinfo/httpapi/.
McGraw Expires 12 December 2026 [Page 1]
Internet-Draft Budget Required June 2026
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on 12 December 2026.
Copyright Notice
Copyright (c) 2026 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components
extracted from this document must include Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Conventions and Definitions . . . . . . . . . . . . . . . 4
1.2. Applicability . . . . . . . . . . . . . . . . . . . . . . 5
1.3. Relationship to RateLimit Fields . . . . . . . . . . . . 5
1.4. Relationship to HTTP Message Signatures . . . . . . . . . 7
1.5. Relationship to HTTP 402 . . . . . . . . . . . . . . . . 7
2. Overview of Operation . . . . . . . . . . . . . . . . . . . . 7
3. The 427 (Budget Required) Status Code . . . . . . . . . . . . 9
3.1. Budget Error Tokens . . . . . . . . . . . . . . . . . . . 10
4. The "Budget" Authentication Scheme . . . . . . . . . . . . . 10
4.1. Challenge Syntax . . . . . . . . . . . . . . . . . . . . 10
4.2. Credentials Syntax . . . . . . . . . . . . . . . . . . . 11
4.3. Multi-Scheme Composition and the Budget-Attestation
Field . . . . . . . . . . . . . . . . . . . . . . . . . . 12
5. The Budget-Attestation Envelope . . . . . . . . . . . . . . . 13
McGraw Expires 12 December 2026 [Page 2]
Internet-Draft Budget Required June 2026
5.1. Primary Signature . . . . . . . . . . . . . . . . . . . . 14
5.2. Operator Key Discovery and Trust . . . . . . . . . . . . 14
5.3. Optional Rail-Keyed Signature . . . . . . . . . . . . . . 15
5.4. Verification . . . . . . . . . . . . . . . . . . . . . . 15
6. Versioning . . . . . . . . . . . . . . . . . . . . . . . . . 16
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16
7.1. HTTP Status Code . . . . . . . . . . . . . . . . . . . . 16
7.2. HTTP Authentication Scheme . . . . . . . . . . . . . . . 16
7.3. HTTP Field Name . . . . . . . . . . . . . . . . . . . . . 17
7.4. Budget Error Token Registry . . . . . . . . . . . . . . . 17
7.5. Media Type . . . . . . . . . . . . . . . . . . . . . . . 18
8. Security Considerations . . . . . . . . . . . . . . . . . . . 19
9. Privacy Considerations . . . . . . . . . . . . . . . . . . . 21
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 21
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 21
11.1. Normative References . . . . . . . . . . . . . . . . . . 21
11.2. Informative References . . . . . . . . . . . . . . . . . 22
Appendix A. Implementation Status . . . . . . . . . . . . . . . 23
A.1. Kevros . . . . . . . . . . . . . . . . . . . . . . . . . 23
Appendix B. Changes Since -00 . . . . . . . . . . . . . . . . . 24
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 24
1. Introduction
Delegated software requesters acting on behalf of human or
organizational principals increasingly make HTTP requests that may
incur cost, consume metered service units, or trigger settlement
through an out-of-band rail. HTTP authentication [RFC9110] addresses
whether a requester holds a usable credential. RateLimit fields
[I-D.ietf-httpapi-ratelimit-headers] communicate server-defined quota
policies and current service-limit information. Budget authorization
addresses a distinct requirement: proving that the requester has been
granted bounded authority by its principal to spend or consume a
specified amount for a class of requests.
This document defines:
* The 427 (Budget Required) HTTP status code (Section 3), used by an
origin server or gateway to indicate that the request will not be
processed until the requester presents a valid Budget-Attestation.
* The "Budget" HTTP authentication scheme (Section 4), used in the
WWW-Authenticate response field of a 427 response and in the
Authorization request field of a subsequent request.
* The Budget-Attestation HTTP field (Section 4.3), used when Budget
authority is additive to another origin-server authentication
mechanism already carried in Authorization.
McGraw Expires 12 December 2026 [Page 3]
Internet-Draft Budget Required June 2026
* The Budget-Attestation envelope (Section 5), a CBOR-encoded
[RFC8949], COSE-signed [RFC9052] structure that carries semantic
claims about issuer, requester, expiry, request binding, permitted
rails, and amount.
The Budget status code and authentication scheme are algorithm-agile.
The initial cose-ml-dsa profile uses ML-DSA algorithm identifiers
serialized for JOSE and COSE by [RFC9964], using the ML-DSA algorithm
specified in [FIPS204]. Implementations of this profile MUST support
ML-DSA-65 and MAY support ML-DSA-87. A deployment MAY require ML-
DSA-87 or another registered algorithm by local policy. A deployment
MAY add an optional rail-keyed signature using SLH-DSA, aligned with
the JOSE and COSE SLH-DSA work in [I-D.ietf-cose-sphincs-plus] and
the SLH-DSA algorithm specified in [FIPS205]. That optional
signature is not a replacement for the primary signature.
This document does not define a payment protocol. Settlement rails
such as L402 [L402], x402 [X402], card payments, or other systems can
use Budget-Attestation as input to their own policy and settlement
flows; however, their settlement semantics are outside the scope of
this document. In particular, this document does not depend on,
redefine, or reserve any semantics for HTTP 402 (Payment Required).
Scope and modularization: Sections 3 and 4 define the HTTP status
code, authentication challenge, credential syntax, and HTTP field
semantics. Section 5 defines an initial COSE/CBOR Budget-Attestation
profile to demonstrate an interoperable cryptographic binding for
that HTTP mechanism. During standards progression, the Working Group
can move the COSE/CBOR profile into a companion document for review
by the COSE or OAuth communities without changing the core HTTP
semantics defined by the status code, authentication scheme, and
field carriage.
1.1. Conventions and Definitions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
Operator: An entity that issues Budget-Attestations on behalf of a
principal.
Delegated Requester: A client, workload, device, job, agent, or
other software component that presents a Budget-Attestation issued
by an Operator in order to make HTTP requests within delegated
bounds.
McGraw Expires 12 December 2026 [Page 4]
Internet-Draft Budget Required June 2026
Agent: A delegated requester. The term "agent" remains the
motivating deployment case and appears in existing claim names for
wire compatibility; it is not a protocol requirement for any
specific architecture.
Verifier: An origin server, gateway, or intermediary that receives a
Budget-Attestation, validates its signatures and claims, and
decides whether to process the bearing request.
Budget-Attestation: The CBOR-encoded, COSE-signed envelope defined
in Section 5.
Settlement Rail: An out-of-band protocol or payment system used to
transfer value or record resource consumption. Rail names can
appear as claims in a Budget-Attestation. This document does not
define how any settlement rail operates.
Rail-Keyed Signature: An optional additional signature over the
Budget-Attestation envelope, intended to bind a deployment's rail-
specific policy to the same claims that the primary Operator
signature covers.
1.2. Applicability
Budget is a general HTTP mechanism for delegated, bounded spend or
resource authority. Autonomous software agents are the motivating
deployment case; however, the mechanism also applies to service
workloads, CI/CD jobs, IoT or fleet devices, batch systems, scheduled
data processors, and other delegated requesters that need to prove
bounded authority before a protected request is processed.
The agent claim carries the delegated requester identifier.
Deployments MAY populate it with an agent identifier, service-account
identifier, workload identity, device identifier, job identifier, or
privacy-preserving alias. The claim name is retained for
compatibility with existing agent_id deployments and does not require
the requester to be an AI system. A future revision MAY define a
neutral alias for this claim; doing so needs a wire-compatibility
plan so existing deterministic encodings and signed bytes are not
broken unnecessarily.
1.3. Relationship to RateLimit Fields
RateLimit fields describe service limits from the server to the
client. They tell the client what quota policy applies and what
capacity is currently available under that server-defined policy.
They are useful for throttling, backoff, and avoiding 429 responses.
McGraw Expires 12 December 2026 [Page 5]
Internet-Draft Budget Required June 2026
Budget-Attestation travels in the opposite direction. It is a
client-presented credential showing that an Operator authorized an
Agent to spend or consume up to stated bounds. It is evaluated
before the Verifier processes the protected request.
This document defines a separate mechanism rather than extending
RateLimit because a signed, bearer-presented authority object has
different issuer, freshness, replay, and verification semantics from
server-advertised quota metadata. Extending RateLimit-Policy would
change the issuer and trust model of RateLimit from server-authored
quota advertisement into principal-authored spending authorization,
which is a different protocol semantic rather than a new quota
parameter.
The mechanisms are complementary:
* A server MAY return RateLimit fields on 200, 427, 429, or other
responses when it wants to communicate server-side quota state.
* A server MUST NOT treat RateLimit fields as a substitute for
Budget-Attestation, because RateLimit fields are not signed
authority from the Agent's principal.
* A Budget-Attestation MUST NOT be interpreted as a server quota
promise. It only states the Agent's delegated budget or resource
authority.
+===========+============================+==========================+
| Property | RateLimit fields | Budget-Attestation |
+===========+============================+==========================+
| Direction | Server to client | Client to verifier |
+-----------+----------------------------+--------------------------+
| Issuer | Resource server or | Operator acting for the |
| | gateway | principal |
+-----------+----------------------------+--------------------------+
| Integrity | HTTP field semantics | COSE/JOSE signature |
+-----------+----------------------------+--------------------------+
| Purpose | Advertise quota and | Prove delegated spending |
| | current service limits | or resource authority |
+-----------+----------------------------+--------------------------+
| Failure | Client might be | Request fails before |
| mode | throttled | protected processing |
+-----------+----------------------------+--------------------------+
Table 1
McGraw Expires 12 December 2026 [Page 6]
Internet-Draft Budget Required June 2026
1.4. Relationship to HTTP Message Signatures
[RFC9421] defines signatures over components of individual HTTP
messages. Budget-Attestation signs a portable authority object whose
claims can be evaluated independently of a single HTTP message. The
two mechanisms can be composed: an Agent can send an HTTP-message
signature that covers the request as transmitted and a Budget-
Attestation that covers delegated budget authority.
1.5. Relationship to HTTP 402
HTTP 402 (Payment Required) is reserved by HTTP Semantics [RFC9110].
Some deployed payment systems use 402 responses as part of their own
settlement flows. This document neither depends on those deployments
nor defines their semantics.
An implementation MAY use Budget-Attestation before invoking a
settlement rail. Whether that later settlement interaction uses HTTP
402, a 401 challenge, a signed request body, or another transport is
out of scope for this document.
2. Overview of Operation
A protected origin determines that a request requires budget
authority and that no acceptable Budget credential is present:
GET /research/papers/12345 HTTP/1.1
Host: api.example
It returns:
McGraw Expires 12 December 2026 [Page 7]
Internet-Draft Budget Required June 2026
HTTP/1.1 427 Budget Required
Date: Tue, 02 Jun 2026 18:00:00 GMT
Cache-Control: no-store
Content-Type: application/problem+json
Protocol-427-Version: 1
WWW-Authenticate: Budget realm="api.example",
alg="ML-DSA-65",
rails="x402 l402 mpp",
nonce="QMjVqg5Xb6yV0bO_t9X8gQ",
max-age=300
{
"type": "https://example.com/problems/budget-required",
"title": "Budget attestation required",
"status": 427,
"detail": "A valid Budget-Attestation is required.",
"budget_requirements": {
"min_amount": "2.50",
"currency": "USD",
"accepted_rails": ["x402", "l402", "mpp"],
"attestation_required": true,
"verifier_required": true,
"discovery_uri": "/.well-known/agent-budget",
"nonce": "QMjVqg5Xb6yV0bO_t9X8gQ",
"protocol_version": "1",
"implementation_version": "0.2.2",
"max_age": 300
}
}
The Agent obtains a Budget-Attestation from its Operator by means
outside this document and retries using body carriage:
POST /research/papers/12345 HTTP/1.1
Host: api.example
Content-Type: application/budget-attestation+cose
Content-Length: 4217
[COSE_Sign1 Budget-Attestation bytes]
If the attestation is valid for the request and local policy, the
Verifier processes the request normally. If validation fails, the
Verifier returns 427 again and SHOULD include a reason extension
member in the Problem Details body.
McGraw Expires 12 December 2026 [Page 8]
Internet-Draft Budget Required June 2026
3. The 427 (Budget Required) Status Code
The 427 (Budget Required) status code indicates that the requester
must present a valid Budget-Attestation before the request can be
processed. It differs from 401 (Unauthorized) because a requester
can be authenticated and still lack budget authority. It differs
from 429 (Too Many Requests) because 427 is not a statement about
server-side quota exhaustion. It differs from 402 (Payment Required)
because 427 asks for evidence of delegated spending or resource
authority, not for immediate payment.
A 427 response MUST include a WWW-Authenticate response field
containing at least one Budget challenge. A 427 response SHOULD
include Cache-Control: no-store as defined by HTTP caching [RFC9111].
A 427 response that contains a nonce, requester-specific policy, or
other policy-sensitive material MUST include Cache-Control: no-store.
A 427 response SHOULD include an application/problem+json or
application/problem+cbor body using [RFC9457].
The 427 status code is distinct from existing alternatives. A 403
response is a general authorization refusal and does not define a
machine-actionable challenge for acquiring a principal-signed
delegation credential. A 402 response is payment-specific and would
conflate Budget-Attestation with immediate settlement behavior that
this document explicitly leaves out of scope. The 427 response
defines a separate automated state transition: a delegated requester
receives a Budget challenge, obtains a bounded authority object from
its Operator, and retries without converting the exchange into a hard
authorization denial or an in-band payment flow.
Some deployment paths might contain intermediaries that do not pass
an unrecognized 427 status code reliably. A deployment profile MAY
use a 403 (Forbidden) response as a compatibility fallback only when
the response carries the same Budget challenge information that a 427
response would have carried, including a WWW-Authenticate field with
a Budget challenge and an application/problem+json or application/
problem+cbor body containing a budget_requirements object. A client
that implements this fallback MUST NOT treat arbitrary 403 responses
as Budget challenges; it MAY treat a 403 response as equivalent to
427 only when the Budget challenge and Problem Details budget
requirements are both present.
McGraw Expires 12 December 2026 [Page 9]
Internet-Draft Budget Required June 2026
3.1. Budget Error Tokens
When a Verifier returns a 427 response because a presented Budget
credential failed validation, the Problem Details object SHOULD
contain a reason extension member. The value of this member is a
token identifying the validation failure. This document defines the
following initial tokens:
* token_expired: The presented Budget-Attestation exp timestamp is
in the past relative to the Verifier's clock.
* nonce_stale: The nonce in the attestation does not match a valid,
unexpired challenge window.
* nonce_replay: The nonce has already been accepted by the Verifier
within its replay-tracking window.
* bad_signature: Cryptographic validation of the primary signature
or a required rail-keyed signature failed.
* untrusted_issuer: The iss claim identifies an issuer for which the
Verifier has no explicit trust relationship.
* budget_insufficient: The authorized amt claim does not satisfy the
budget requirement advertised by the resource server.
* version_unsupported: The version claim or Protocol-427-Version
field is not supported by the Verifier.
* binding_mismatch: The request target URI, method, origin, or body
digest does not match the signed rb object.
4. The "Budget" Authentication Scheme
The Budget authentication scheme is used in WWW-Authenticate and
Authorization fields.
4.1. Challenge Syntax
The Budget authentication scheme challenge uses the auth-param syntax
defined by [RFC9110], Section 11.2:
budget-challenge = "Budget" 1*SP 1#auth-param
The realm and nonce parameters are REQUIRED. The alg parameter
identifies acceptable primary signature algorithms. The rails
parameter identifies settlement rail names acceptable to the
Verifier; rail semantics remain out of scope for this document.
McGraw Expires 12 December 2026 [Page 10]
Internet-Draft Budget Required June 2026
The nonce parameter MUST contain at least 128 bits of unpredictable
entropy and MUST be generated by the Verifier for the protection
space identified by realm. A Verifier MUST accept a nonce at most
once. Replay of a nonce, absence of nonce state, or loss of the
replay cache MUST cause the Verifier to reject the request.
To reduce outstanding-challenge state, Verifiers SHOULD support self-
authenticating nonce constructions. A self-authenticating nonce
contains unpredictable bytes and integrity-protected metadata such as
protection space, issuance time, key identifier, and policy binding.
The nonce is authenticated with a server-held secret, for example
using an HMAC or AEAD construction, and MUST NOT reveal that secret
to clients. This construction allows a Verifier to validate the
origin and age of a returned nonce without storing every issued
challenge. It does not remove the requirement to enforce at-most-
once acceptance; Verifiers still need accepted-nonce replay tracking
or an equivalent replay-detection mechanism until the challenge can
no longer be accepted.
The max-age parameter, when present, is the validity window in
seconds for the challenge parameters and nonce. It does not extend
the Budget-Attestation lifetime. A Verifier MUST reject a Budget-
Attestation whose nonce is older than max-age for the corresponding
challenge. If max-age is omitted, Verifiers SHOULD apply a local
default and that default SHOULD NOT exceed 900 seconds.
4.2. Credentials Syntax
budget-credentials = "Budget" 1*SP budget-token
budget-token = token68
The credential token carries base64url-encoded COSE/CBOR. If the
encoded envelope would exceed practical HTTP field size limits, the
Agent MUST send the envelope in a request body with media type
application/budget-attestation+cose. Implementations of the cose-ml-
dsa profile MUST support request-body carriage. Requesters using
that profile SHOULD use body carriage by default because ML-DSA-
backed COSE envelopes are large before base64url expansion and can
exceed field-size limits enforced by intermediaries. A deployment
profile MAY permit field carriage with Authorization: Budget only
when it defines accepted field-size limits and failure behavior. A
Verifier MAY reject oversized field-carried credentials before CBOR
or COSE decoding. A deployment MAY bind the body-carried envelope to
the request using a digest claim in the envelope's request-binding
structure.
McGraw Expires 12 December 2026 [Page 11]
Internet-Draft Budget Required June 2026
4.3. Multi-Scheme Composition and the Budget-Attestation Field
The Budget-Attestation field carries a Budget-Attestation when the
request already uses Authorization for another origin-server
credential or when a deployment wants Budget authority to be visibly
additive to another authentication scheme.
The field value is a Structured Field Item [RFC9651] whose bare item
is a Byte Sequence containing the COSE/CBOR Budget-Attestation
envelope.
Budget-Attestation: :2BhA...base64-cose...kQ:
If both Authorization: Budget and Budget-Attestation are present, the
Verifier MUST reject the request unless a deployment profile
explicitly defines how the two credentials compose. This avoids
ambiguity about which signed authority object is authoritative.
The Authorization field MUST NOT be used to concatenate a non-Budget
credential and a Budget credential into a single field value unless a
future HTTP authentication scheme explicitly defines such
composition. When identity authentication uses Authorization, Budget
authority SHOULD be carried in the request body for the cose-ml-dsa
profile or, for bounded low-footprint deployments, in the Budget-
Attestation field.
When a request carries both an identity credential and a Budget-
Attestation, the Verifier MUST evaluate the identity authentication
layer and the budget delegation layer independently. Failure of the
identity authentication layer is handled according to that
authentication scheme, typically with 401 or 403. Failure of the
budget delegation layer is handled with 427, or with the 403
compatibility fallback defined in Section 3.
The Budget-Attestation field is not the general-purpose carriage path
for multi-kilobyte post-quantum attestations. Implementations of the
cose-ml-dsa profile MUST support body carriage with media type
application/budget-attestation+cose. A deployment profile MAY permit
Budget-Attestation field carriage only when it defines accepted
field-size limits and failure behavior. If the target request also
needs an unrelated representation body, that packaging profile MUST
define how the Budget-Attestation and application representation are
bound to each other.
McGraw Expires 12 December 2026 [Page 12]
Internet-Draft Budget Required June 2026
5. The Budget-Attestation Envelope
The Budget-Attestation envelope is a COSE object [RFC9052] carrying a
CBOR claims set. The claims set is encoded using deterministic CBOR
[RFC8949]. Encoders MUST follow the core deterministic encoding
requirements of [RFC8949], Section 4.2.1. Verifiers MUST reject non-
deterministic encodings and MUST verify signatures over the exact
received deterministic encoding, not over a locally reserialized
variant. This document defines the logical claims below using CDDL
[RFC8610]; exact COSE encoding details can be profiled further during
Working Group review.
Budget-Claims = {
"version" => uint,
"iss" => tstr,
"agent" => tstr,
"iat" => uint,
"exp" => uint,
"nonce" => bstr .size (16..64),
"kid" => tstr,
"rb" => Request-Binding,
"rails" => [+ tstr],
? "cb" => Channel-Binding,
? "amt" => { + tstr => uint }
}
Request-Binding = {
"method" => tstr,
"uri-h" => bstr .size 32,
"origin" => tstr,
? "body-h" => bstr .size 32
}
Channel-Binding = {
"type" => tstr,
"value" => bstr
}
The amt claim carries the delegated amount bound inside the signed
attestation. A 427 response can separately advertise min-budget in
its Problem Details body; that response member is an input to client
policy and does not become authoritative unless it is reflected in a
signed amt claim.
The CDDL above uses text claim names for readability in this early
revision. A future revision can assign integer claim labels to
reduce wire size without changing the semantics of the claims.
McGraw Expires 12 December 2026 [Page 13]
Internet-Draft Budget Required June 2026
The optional cb claim is reserved for binding an attestation to an
external channel-binding value such as a TLS exporter. This document
defines the claim container but does not define mandatory channel-
binding types. A Verifier MUST reject a cb claim whose type it does
not understand or whose value does not match the locally computed
channel-binding value for that type.
5.1. Primary Signature
Every Budget-Attestation MUST contain exactly one primary Operator
signature. The primary signature MUST use an ML-DSA algorithm
identifier registered for JOSE or COSE by [RFC9964].
The Budget status code and authentication scheme are algorithm-agile.
The cose-ml-dsa profile defined by this document has the following
interoperability requirements:
* Implementations of this profile MUST support ML-DSA-65.
* Implementations MAY support ML-DSA-87.
* Deployments MAY require ML-DSA-87 or another registered algorithm
by local policy.
* Verifiers MUST validate that the signed protected-header algorithm
matches local policy and MUST reject algorithm downgrades.
Future documents can define additional Budget-Attestation profiles
using other COSE or JOSE algorithm identifiers without changing the
semantics of the 427 status code or the Budget authentication scheme.
5.2. Operator Key Discovery and Trust
A Verifier MUST establish trust in an Operator public key before
accepting a Budget-Attestation signed by that key. Trust can be
established through local configuration, an authenticated out-of-band
agreement, or an issuer-controlled HTTPS key-set endpoint. A
Verifier MUST NOT treat an untrusted iss value or arbitrary key URL
in an attestation as sufficient authority to trust a key.
One interoperable deployment profile is an issuer-controlled HTTPS
key-set URI, for example https://example.com/.well-known/budget-
issuer-keys, returning a COSE_KeySet with media type application/
cose-key-set. A Verifier using this profile MUST authenticate the
HTTPS origin, MUST require each accepted key to carry a key
identifier usable as kid, MUST bind each key to the expected issuer
and algorithm policy, and MUST reject the request if the key set is
unavailable or omits the referenced key. Cached key material MUST
McGraw Expires 12 December 2026 [Page 14]
Internet-Draft Budget Required June 2026
NOT be used beyond its authenticated freshness lifetime. Key
rotation SHOULD provide overlap between old and new keys for already-
issued attestations.
5.3. Optional Rail-Keyed Signature
A Budget-Attestation MAY contain an additional rail-keyed signature.
A rail-keyed signature MUST NOT replace the primary Operator
signature and MUST NOT be accepted when the primary signature fails.
When a deployment uses SLH-DSA for rail-keyed signatures, it SHOULD
use the JOSE or COSE serializations defined by
[I-D.ietf-cose-sphincs-plus] once those registrations are available.
Until then, private-use algorithm identifiers MUST be treated as
deployment-specific and MUST NOT be advertised as interoperable.
Because SLH-DSA signatures can be tens of kilobytes, an attestation
that contains a rail-keyed SLH-DSA signature MUST be carried in a
request body using application/budget-attestation+cose rather than in
an HTTP field.
5.4. Verification
A Verifier processing a Budget-Attestation MUST:
1. Decode the CBOR envelope and reject non-deterministic or
malformed encodings.
2. Verify that the version is supported.
3. Verify the primary signature against an Operator key authorized
for the issuer and kid.
4. Verify iat, exp, clock skew, and maximum lifetime. Verifiers
MUST reject attestations where exp - iat exceeds 900 seconds and
SHOULD apply no more than 60 seconds of clock-skew tolerance
unless local policy is stricter. Operators and Verifiers SHOULD
synchronize clocks using an authenticated time source suitable
for the deployment.
5. Verify that nonce matches a live challenge and has not been used
before.
6. Verify request binding against the bearing request, including
method, origin, target URI hash, and body hash when present.
7. Verify rail policy if a rails claim is present.
McGraw Expires 12 December 2026 [Page 15]
Internet-Draft Budget Required June 2026
8. Verify any rail-keyed signature required by local policy.
Failure at any step MUST cause the Verifier to reject the request.
6. Versioning
This document defines version 1 of the Budget authentication scheme
and Budget-Attestation envelope. A 427 response MUST include a
Protocol-427-Version response field containing a Structured Field
Integer [RFC9651].
A client that receives an unknown Protocol-427-Version value MUST NOT
guess at wire compatibility. It MAY retry using a version it
supports only when the server advertises that version through local
policy or a future version-negotiation mechanism. A server that
receives a Budget credential or Protocol-427-Version request value
for an unsupported version MUST reject the request with 427 and a
version_unsupported reason code, unless a future revision defines a
different upgrade response.
7. IANA Considerations
This section follows the guidance in [RFC8126] and [RFC9205]. The
requested registrations use the existing HTTP and media-type
registries.
7.1. HTTP Status Code
IANA is asked to register the following entry in the "Hypertext
Transfer Protocol (HTTP) Status Code Registry" defined by [RFC9110]:
+=============+===================+==========================+
| Status Code | Short Description | Reference |
+=============+===================+==========================+
| 427 | Budget Required | This document, Section 3 |
+-------------+-------------------+--------------------------+
Table 2
7.2. HTTP Authentication Scheme
IANA is asked to register the following entry in the "Hypertext
Transfer Protocol (HTTP) Authentication Scheme Registry" defined by
[RFC9110]:
McGraw Expires 12 December 2026 [Page 16]
Internet-Draft Budget Required June 2026
+================+===========+======================================+
| Authentication | Reference | Notes |
| Scheme Name | | |
+================+===========+======================================+
| Budget | This | Origin-server authentication |
| | document, | using WWW-Authenticate and |
| | Section 4 | Authorization; not defined |
| | | for proxy authentication |
+----------------+-----------+--------------------------------------+
Table 3
7.3. HTTP Field Name
IANA is asked to register the following entry in the "Hypertext
Transfer Protocol (HTTP) Field Name Registry":
+=============+=========+============+===========+==================+
| Field Name |Status | Structured | Reference | Comments |
| | | Type | | |
+=============+=========+============+===========+==================+
| Protocol- |permanent| Integer | This | Version of the |
| 427-Version | | | document, | Budget |
| | | | Section 6 | authentication |
| | | | | scheme and |
| | | | | Budget- |
| | | | | Attestation |
| | | | | envelope |
+-------------+---------+------------+-----------+------------------+
| Budget- |permanent| Byte | This | Additive |
| Attestation | | Sequence | document, | carriage of a |
| | | | Section | Budget- |
| | | | 4.3 | Attestation |
| | | | | when |
| | | | | Authorization |
| | | | | is used by |
| | | | | another origin- |
| | | | | server scheme |
+-------------+---------+------------+-----------+------------------+
Table 4
7.4. Budget Error Token Registry
IANA is asked to create a "Budget Error Tokens" registry for tokens
used in the Problem Details reason extension member defined by
Section 3.1. The registration policy is Specification Required
[RFC8126].
McGraw Expires 12 December 2026 [Page 17]
Internet-Draft Budget Required June 2026
Initial registrations are:
+=====================+================================+===========+
| Token | Description | Reference |
+=====================+================================+===========+
| token_expired | The attestation expired. | Section |
| | | 3.1 |
+---------------------+--------------------------------+-----------+
| nonce_stale | The nonce is outside the | Section |
| | accepted challenge window. | 3.1 |
+---------------------+--------------------------------+-----------+
| nonce_replay | The nonce was already accepted | Section |
| | in the replay-tracking window. | 3.1 |
+---------------------+--------------------------------+-----------+
| bad_signature | A required signature failed | Section |
| | validation. | 3.1 |
+---------------------+--------------------------------+-----------+
| untrusted_issuer | The issuer is not trusted by | Section |
| | the Verifier. | 3.1 |
+---------------------+--------------------------------+-----------+
| budget_insufficient | The signed budget bounds do | Section |
| | not satisfy the resource | 3.1 |
| | requirement. | |
+---------------------+--------------------------------+-----------+
| version_unsupported | The protocol or attestation | Section |
| | version is unsupported. | 3.1 |
+---------------------+--------------------------------+-----------+
| binding_mismatch | The signed request binding | Section |
| | does not match the bearing | 3.1 |
| | request. | |
+---------------------+--------------------------------+-----------+
Table 5
7.5. Media Type
IANA is asked to register the following media type in the "Media
Types" registry using the template from [RFC6838]:
Type name: application
Subtype name: budget-attestation+cose
Required parameters: N/A
Optional parameters: cose-type, with the same semantics as the cose-
type parameter for application/cose in [RFC9052].
McGraw Expires 12 December 2026 [Page 18]
Internet-Draft Budget Required June 2026
Encoding considerations: binary
Security considerations: See Section 8.
Interoperability considerations: Implementations need to support
COSE processing, deterministic CBOR, and the algorithm identifiers
profiled by this document.
Published specification: This document.
Applications that use this media type: HTTP clients, gateways, and
origin servers that exchange Budget-Attestation envelopes.
Fragment identifier considerations: This media type does not support
fragment identifiers.
Additional information: Deprecated alias names for this type: N/A;
Magic number(s): N/A; File extension(s): N/A; Macintosh file type
code(s): N/A.
Person & email address to contact for further information: John
McGraw, j.mcgraw@taskhawktech.com
Intended usage: COMMON
Restrictions on usage: N/A
Author: John McGraw
Change controller: IESG
Provisional registration? No
8. Security Considerations
Budget-Attestation is a bearer credential until verified. HTTP
exchanges carrying it MUST use TLS. Servers SHOULD scrub
Authorization field values, Budget-Attestation field values, and
body-carried Budget credential values from logs.
Verifiers MUST validate every check in Section 5 before processing
the protected request. Missing keys, unavailable verification
dependencies, malformed CBOR, non-deterministic CBOR, expired
attestations, signature failures, nonce replay, unsupported versions,
and loss of nonce state all require request rejection.
McGraw Expires 12 December 2026 [Page 19]
Internet-Draft Budget Required June 2026
The COSE or JOSE algorithm identifier is part of the signed protected
metadata. Verifiers MUST compare it against configured policy and
MUST NOT let a challenge parameter or client preference downgrade the
algorithm.
Rail-keyed signatures are additive. They do not create authority
without a valid primary Operator signature.
Key lifecycle is security-critical. Operators SHOULD rotate signing
keys on a predictable schedule, publish revocation information
through the same trust channel used for key distribution, and avoid
issuing attestations whose lifetime extends beyond the authenticated
lifetime of the signing key. Verifiers MUST reject attestations
signed by revoked, expired, or unexpected keys.
Large post-quantum signatures can create denial-of-service pressure
on HTTP parsers, HTTP field-section processing, and COSE libraries.
ML-DSA-backed COSE envelopes are commonly too large to assume safe
carriage through general-purpose HTTP fields after base64url
expansion. Implementations MUST apply size limits before decoding,
MUST bound CBOR nesting depth and map sizes, and SHOULD reject
duplicate or unknown critical protected parameters before expensive
signature verification.
Verifier nonce state can itself become a resource-exhaustion target.
Verifiers MUST bound the number of outstanding nonces per issuer,
protection space, and client identity signal available to the
deployment, and MUST expire unused nonces no later than their
challenge max-age. When nonce state reaches a configured limit, the
Verifier MUST reject requests that depend on an untracked nonce or
shed unauthenticated challenge issuance rather than accept a request
with an untracked nonce. At high scale, deployments SHOULD use self-
authenticating nonces as described in Section 4 so challenge issuance
does not require allocating distributed state for every
unauthenticated request. Such constructions reduce outstanding-
challenge state but do not remove the need for bounded accepted-nonce
replay tracking when at-most-once acceptance is required.
This version defines an optional cb claim container for deployments
that need binding to a particular TLS session or exporter value.
Specific channel-binding types are not mandatory-to-implement in this
revision and need profiling before they can be assumed interoperable.
In the absence of channel binding, short lifetimes, single-use
nonces, request binding, and replay-cache enforcement are mandatory
replay controls.
McGraw Expires 12 December 2026 [Page 20]
Internet-Draft Budget Required June 2026
9. Privacy Considerations
These considerations are informed by the privacy guidance in
[RFC6973].
Budget-Attestations can reveal delegated requester identifiers,
issuer identifiers, rail preferences, and amount limits.
Implementations SHOULD use short lifetimes, random nonces, data
minimization in requester identifiers, and body carriage when field
logging by intermediaries would create avoidable privacy risk.
10. References
11. References
11.1. Normative References
[FIPS204] National Institute of Standards and Technology (NIST),
"Module-Lattice-Based Digital Signature Standard", FIPS
PUB 204, DOI 10.6028/NIST.FIPS.204, August 2024,
<https://nvlpubs.nist.gov/nistpubs/FIPS/
NIST.FIPS.204.pdf>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/rfc/rfc2119>.
[RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type
Specifications and Registration Procedures", BCP 13,
RFC 6838, DOI 10.17487/RFC6838, January 2013,
<https://www.rfc-editor.org/rfc/rfc6838>.
[RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for
Writing an IANA Considerations Section in RFCs", BCP 26,
RFC 8126, DOI 10.17487/RFC8126, June 2017,
<https://www.rfc-editor.org/rfc/rfc8126>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.
[RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data
Definition Language (CDDL): A Notational Convention to
Express Concise Binary Object Representation (CBOR) and
JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610,
June 2019, <https://www.rfc-editor.org/rfc/rfc8610>.
McGraw Expires 12 December 2026 [Page 21]
Internet-Draft Budget Required June 2026
[RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object
Representation (CBOR)", STD 94, RFC 8949,
DOI 10.17487/RFC8949, December 2020,
<https://www.rfc-editor.org/rfc/rfc8949>.
[RFC9052] Schaad, J., "CBOR Object Signing and Encryption (COSE):
Structures and Process", STD 96, RFC 9052,
DOI 10.17487/RFC9052, August 2022,
<https://www.rfc-editor.org/rfc/rfc9052>.
[RFC9110] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "HTTP Semantics", STD 97, RFC 9110,
DOI 10.17487/RFC9110, June 2022,
<https://www.rfc-editor.org/rfc/rfc9110>.
[RFC9111] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "HTTP Caching", STD 98, RFC 9111,
DOI 10.17487/RFC9111, June 2022,
<https://www.rfc-editor.org/rfc/rfc9111>.
[RFC9205] Nottingham, M., "Building Protocols with HTTP", BCP 56,
RFC 9205, DOI 10.17487/RFC9205, June 2022,
<https://www.rfc-editor.org/rfc/rfc9205>.
[RFC9457] Nottingham, M., Wilde, E., and S. Dalal, "Problem Details
for HTTP APIs", RFC 9457, DOI 10.17487/RFC9457, July 2023,
<https://www.rfc-editor.org/rfc/rfc9457>.
[RFC9651] Nottingham, M. and P. Kamp, "Structured Field Values for
HTTP", RFC 9651, DOI 10.17487/RFC9651, September 2024,
<https://www.rfc-editor.org/rfc/rfc9651>.
[RFC9964] Prorock, M. and O. Steele, "ML-DSA for JSON Object Signing
and Encryption (JOSE) and CBOR Object Signing and
Encryption (COSE)", RFC 9964, DOI 10.17487/RFC9964, May
2026, <https://www.rfc-editor.org/rfc/rfc9964>.
11.2. Informative References
[FIPS205] National Institute of Standards and Technology (NIST),
"Stateless Hash-Based Digital Signature Standard", FIPS
PUB 205, DOI 10.6028/NIST.FIPS.205, August 2024,
<https://nvlpubs.nist.gov/nistpubs/FIPS/
NIST.FIPS.205.pdf>.
[I-D.ietf-cose-sphincs-plus]
Prorock, M., Steele, O., and H. Tschofenig, "SLH-DSA for
JOSE and COSE", Work in Progress, Internet-Draft, draft-
McGraw Expires 12 December 2026 [Page 22]
Internet-Draft Budget Required June 2026
ietf-cose-sphincs-plus-08, 15 May 2026,
<https://datatracker.ietf.org/doc/html/draft-ietf-cose-
sphincs-plus-08>.
[I-D.ietf-httpapi-ratelimit-headers]
Polli, R., Ruiz, A. M., and D. Miller, "RateLimit header
fields for HTTP", Work in Progress, Internet-Draft, draft-
ietf-httpapi-ratelimit-headers-11, 23 May 2026,
<https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-
ratelimit-headers-11>.
[L402] Lightning Labs, "L402 Protocol Specification", 2024,
<https://github.com/lightninglabs/L402>.
[RFC6973] Cooper, A., Tschofenig, H., Aboba, B., Peterson, J.,
Morris, J., Hansen, M., and R. Smith, "Privacy
Considerations for Internet Protocols", RFC 6973,
DOI 10.17487/RFC6973, July 2013,
<https://www.rfc-editor.org/rfc/rfc6973>.
[RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running
Code: The Implementation Status Section", BCP 205,
RFC 7942, DOI 10.17487/RFC7942, July 2016,
<https://www.rfc-editor.org/rfc/rfc7942>.
[RFC9421] Backman, A., Ed., Richer, J., Ed., and M. Sporny, "HTTP
Message Signatures", RFC 9421, DOI 10.17487/RFC9421,
February 2024, <https://www.rfc-editor.org/rfc/rfc9421>.
[X402] Coinbase, Inc., "x402: An Open Standard for Internet-
Native Payments", 2025,
<https://www.x402.org/x402-whitepaper.pdf>.
Appendix A. Implementation Status
This appendix follows [RFC7942] and is to be removed before
publication as an RFC.
A.1. Kevros
TaskHawk Systems operates a Kevros implementation that emits 427
challenges, publishes discovery and health metadata for deployment
profiles, and records reason-coded audit events. Private no-spend
proof workflows exist for Budget-Attestation verification, but each
run is evidence only for the specific commit and deployment state
under test. Challenge emission, Budget-Attestation verification,
rail observation, settlement, and revenue are separate evidence lanes
and are not equivalent. This implementation is provided as
McGraw Expires 12 December 2026 [Page 23]
Internet-Draft Budget Required June 2026
implementation experience only; it is not required for
interoperability.
Appendix B. Changes Since -00
* Removed language implying HTTP 402 semantics are controlled by
deployed payment protocols.
* Added Section 1.2 and Section 1.3.
* Updated ML-DSA serialization references to [RFC9964] and changed
the initial cose-ml-dsa interoperability baseline to ML-DSA-65,
with ML-DSA-87 available as a high-assurance deployment policy
option.
* Kept rail-keyed SLH-DSA optional and body-carried.
* Made body carriage mandatory to implement for the cose-ml-dsa
profile and recommended by default for post-quantum Budget-
Attestation envelopes.
* Kept Authorization: Budget and Budget-Attestation as explicitly
bounded field-carriage options for deployment profiles that define
accepted field sizes and failure behavior.
* Added nonce replay, key-distribution, IANA, deterministic-CBOR,
and expanded security text based on review feedback.
* Aligned the attestation lifetime rule with implementation
behavior: exp - iat greater than 900 seconds is a verifier
rejection condition.
* Tightened Implementation Status to separate challenge emission,
Budget-Attestation verification, rail observation, settlement, and
revenue.
Author's Address
John Paul McGraw, Jr.
TaskHawk Systems LLC
Charlottesville, VA
United States of America
Email: j.mcgraw@taskhawktech.com
McGraw Expires 12 December 2026 [Page 24]