Budgets: the allocation model, omitted cost, required, and billing accounts

[dickhardt]

Review of -01 from @polvi-ish, who runs AuthGravity as a PS, tokenpony as the resource, and Harness News as an agent against an earlier budget draft. One framing gap and three concrete defects.

The framing gap

The granted budget is an allocation, not the person's ceiling. The PS holds a ceiling the agent is never told, and each auth token carries a slice of it. When the slice runs out — or the hour expires, whichever comes first — the agent returns, and the PS decides again with consumption records in hand.

That was the design throughout and it was nowhere in the document. The reviewer read it end to end and concluded a durable grant was missing, then proposed adding one. That is the correct reading of what was on the page.

Now stated in three places:

• Introduction — one paragraph, because that is where the misreading happened.
• PS Token Endpoint — expanded from "no new request parameter is defined" into what the PS is deciding (#ps-decision), the four inputs it reads (#ps-inputs), and its six responses (#ps-responses).
• #why-not-the-ceiling — the termination argument. Nobody knows at mission approval what the work will cost; a figure fixed up front is either too small to finish or too large to be a control.

#token-scope was rewritten from a disclaimer about the absent grant identifier into a statement of the mechanism, including the property that expiry is proportional to time and exhaustion to spend, so the check-in interval tracks whichever moves faster. A cheap mission reports hourly; an expensive one reports in minutes; nobody configures it.

requirement=clarification is named as a PS response. The PS previously had three moves on a budget escalation: grant less, decline, or terminate the mission. Granting less is silent — the agent cannot distinguish a PS applying pressure from a resource lowering its own offer. Clarification is the base protocol channel that lets the PS ask the agent to account for the spend before deciding. Nothing new to specify.

Three defects

1. cost had no carrier on some streamed responses. The member could go in the header or a trailer, and MUST NOT omit from both. A resource metering a streamed response on a runtime with no trailer support can use neither: cost is unknown when headers are written, and the trailer never happens. Every such response was non-conformant, and the runtimes in question are Workers, Deno, Bun, and undici.

New #cost-omitted permits omitting it, makes reserved REQUIRED in that case, and gives the recovery: cost = previous remaining + reserved − current remaining. The subtraction works because remaining is already net of reservations. Until the next response arrives the agent applies #ambiguous-failure, which already handles this exact shape.

Also removed the sentence in #ambiguous-failure claiming a resource emitting usage in its stream "is not excused from the trailer" — it contradicted the trailer's SHOULD and was read by the reviewer as the requirement.

2. required member on AAuth-Budget. A resource refusing under reason=insufficient-budget has computed the request's maximum cost — #overshoot requires it — but could report it only inside the resource token, whose aud is the PS. The agent knew what it had and not what the request needed, which makes the shrink-and-retry that #exhaustion offers a binary search rather than a calculation. It cannot derive the figure itself; the bound is the resource's own calculation and no resource is required to publish operation pricing.

#required-member also states why this is not the resource token's budget claim: that figure is a re-authorization offer addressed to the PS and should be larger, since sizing it to the refused request hands back a grant good for one call.

3. #billing-account. A metered resource charges an account, and nothing in a budget names one. sub is directed per PS. The section covers the three base-protocol answers — (iss, sub) or (iss, tenant, sub) lookup where the resource holds one account per person, the account parameter and claim where it holds several, and resource-initiated interaction where the person has no funded account yet. No new mechanism; the document was simply silent on a question every metered resource meets on its first request.

Resolved during review

The open question was whether the AS should be able to originate account rather than copy it from the resource token. Answered no by the implementer: one balance per person, bound on (ps, sub), and pooled or sponsored funding is resource-side state. The text says the AS copies it, matching the base protocol, and no base protocol change is needed.

Build

make draft-hardt-aauth-budgets.txt passes. All internal cross-references resolve.

[dickhardt]

The open question at the bottom of the description is closed — no base protocol change needed.

The four-party paragraph in #billing-account had the AS possibly setting the account claim, which conflicted with the base protocol having it copy the value from the resource token. Wrong framing: no claim is involved. The AS returns 202 with requirement=interaction on first sight of a sub, the person authenticates at the AS and creates or binds an account, and the AS holds the sub → account mapping from then on. That is the same one-time binding the AS already performs to establish trust with a person server — it just answers two questions at once.

Also added: because sub is directed per PS, a person arriving through two person servers presents two identifiers, and the binding interaction is what attaches both to one account. A resource that skips it bills two ledgers for one person.

[polvi-ish]

Read the branch against the thread; this is implementable as written. We're dropping TPX-A and porting tokenpony, AuthGravity, and Harness News to TPX + this draft. Three things:

Your open question: no, I don't need the AS to originate account. One balance per person, bound on (ps, sub). Sponsored or pooled funding is resource-side state keyed by mission_s256, no protocol change. Tighten the sentence to "the AS copies account from the resource token."

The tokenpony sketch, one correction: the Ed25519 key material, published JWKS, aa-resource+jwt minting on the 401, and an AS /token that verifies the PS and mints aa-auth+jwt already exist from TPX-A. What's actually new for us is the -11 surface (person tokens, presented_jti/sub/ps, authorization_endpoint, auth token via Signature-Key, 202 at the AS, usage_endpoint, budget_units, the header, the reason= 401s) and rekeying the ledger from mission to person. Standing mission-less tokens force the (ps, sub) → account binding anyway, so that order is right.

The explicit TPX statement isn't on the branch yet. Suggested for #inference: TPX is a complete deployment on its own and needs no person server; the two share no wire surface, only the meter; neither displaces the other.

Small: #cost-omitted is exact only for serial requests on one token (concurrent requests recover the sum), worth a sentence. The unit/decimals bullet in #aauth-budget-header still has the garbled "10^decimals to exactly the readers self-description serves" sentence.

Let us know once you're happy with the text and we'll port our side against it.

[dickhardt]

All four addressed, pushed.

account — tightened to "the AS copies account from the resource token," and added that a resource holding one balance per person needs none of it: binding on (iss, sub) is the whole mechanism and account never appears in its tokens. Open question removed from the description.

The sketch — thanks, that correction lands. I read the TPX-A appendix as a description of what the profile does rather than an inventory of what you'd already built, so I put the Ed25519 material, the JWKS, and the AS /token in the new column when they're existing code. Your list is the real one: the -11 surface plus the ledger rekey. And you're right that the standing mission-less token forces the (ps, sub) binding regardless, which fixes the order.

TPX standalone — added to #inference as its own paragraph:

Neither displaces the other. TPX is a complete deployment on its own. It requires no person server, no agent signing keys, and nothing from this document […] The two specifications share no wire surface — TPX carries its budget in an RFC 9396 authorization_details object on a refresh-token grant, this document carries one in a JWT claim and an HTTP response header — and a provider implementing both has one meter and one balance underneath two independent front doors.

It closes on the framing rather than a hierarchy: a person driving an app and an agent acting for that person are different situations, and the envelope follows from which one is happening.

#cost-omitted — caught. The subtraction is exact only for serial requests on one token; concurrent requests all move the same remaining, so the difference between two responses is the net of everything that settled in between. Added, along with the consequence — serialize on that token if you want per-request figures from a resource that omits cost, and don't bother if you only need the balance.

The unit/decimals sentence — it was garbled, now rewritten. The point it was failing to make: the readers those two members exist for are the ones that never parse a JWT, and those are exactly the readers that would misread an amount carrying a unit with no scale.

Also fixed my own error in the description — I had invented a surname for you. Apologies; it's your handle now.

Text is where I want it. Merging unless you spot something else.

[dickhardt]

Correcting myself: I said "text is where I want it, merging unless you spot something else." That was premature — the branch moved substantially afterward, and the usage endpoint in particular is not what you reviewed. Don't build against what you saw.

#usage-counters is reshaped. unit and decimals are stated once at the top of the response instead of per entry, and usage is consequently a plain counter object rather than an array. The response now echoes the scope key it was asked for, which it previously dropped, and carries aud naming the person server it was produced for. The request takes at most one scope key, and an OPTIONAL unit selects which unit to report in when a resource declares several.

New: a jkts query. The PS sends an array of JWK thumbprints and gets back what each key consumed. This is the per-agent visibility problem — allocations are ceilings, not figures, so a PS supervising several agents for one person could not learn how the spending divided among them. No calendar periods per key, since a key's spend is already bounded by tokens that live an hour. A resource SHOULD retain a key's figure for 24 hours after that key's last metered request; the PS accumulates beyond that, because it is the party that knows which keys belonged to which agent across rotations. An unrecognized or pruned key is omitted rather than reported as zero — a zero meaning "pruned" is a wrong answer to an allocation decision rather than a withheld one.

The usage response is signed, bound to the request, using the key material you already publish for resource tokens. Whether that is a MUST or a SHOULD is still open — see the thread; the current text says MUST and will likely soften to SHOULD with a PS-side MAY-require. Worth your opinion, since you would be implementing it.

Also since your review: revoking an auth token revokes its budget, pointing at the base protocol's revocation endpoint; a per-agent ceiling is stated to be a PS sizing decision rather than a resource-side key; and the no-unit-registry rationale now notes that a monetary unit SHOULD still be an ISO 4217 code.

Nothing is merged and nothing is on the datatracker — this whole family is editor's copy. Track the branch, not a published revision. I will say when it settles, and this time I will mean it.

[dickhardt]

Two follow-ups since my last note.

Signing is now RECOMMENDED, not MUST. You don't need to weigh in — the reasoning went: the figures are decision context rather than authorization, this would be the first response-side signature anywhere in AAuth (the profile is request-side throughout), and there is no useful action behind a PS refusing an unsigned response. Refusing leaves it with no figures rather than unattributable ones, which is worse. Signing still buys the thing worth having — the resource cannot later disown what it reported, or tell you one number and the biller another — so implement it if you're building the endpoint.

The unit request parameter is gone. I had added it so a resource metering one person in several units could be asked which to report. That case is marginal by the document's own non-goals, and it cost an error condition and an arbitrary "primary unit" rule. The response reports in the unit the resource meters in and names it, which for tokenpony is USD and always was.

The request rule is now: carry a scope key or jkts, may carry both, at most one scope key.

Still a PR, still nothing on the datatracker.