DEV Community: DarkEdges

Missions, consent and three tokens: how the AAuth person server decides

DarkEdges — Sun, 25 Oct 2026 09:12:50 +0000

Part 2 ended with SearchCo answering 401 requirement=person-token: it knows which agent is calling, and now wants to know who for. This part covers the rest of a hop, and the mission that every decision is checked against.

darkedges / aauth-lab

AAuth (draft-hardt-oauth-aauth-protocol-11) version of the Relay Biscuit lab, with a side-by-side comparison

Relay — AAuth network lab

The Relay Biscuit lab rebuilt on AAuth. It has the same operators, scenarios, budget rules and UI. Biscuit attenuation is replaced by AAuth's signed HTTP requests, person-server tokens and call chaining. Signatures, tokens and HTTP exchanges are real. Operators, work and credits are simulated.

Live demo: aauth.demos.darkedges.com

See COMPARISON.md for a side-by-side analysis of the two solutions.

Run locally

Use Node.js 22 or newer and pnpm 11:

pnpm install
pnpm dev

Open http://127.0.0.1:8796. The Biscuit lab uses 8795, so both labs can run side by side. On Windows, run ./start.ps1. The interface starts a demo run automatically.

pnpm check   # behaviour, spec-conformance, reference-client interop and debug formatting tests

How the AAuth version works

Each run creates fresh Ed25519 keys and a fresh set of origins, such as https://search.<tag>.relay.example. Requests between parties are real Request/Response objects routed in-process to that…

View on GitHub

The mission

Before any work starts, Alice's assistant proposes a mission to her person server (PS). It is a short, signed POST:

{
  "description": "# Research a topic\n\nPlan the work, research, search sources and run compute, billed to my organization.",
  "tools": [{ "name": "Delegate", "description": "Hand research tasks to Relay operators" }],
  "resources": ["https://planner.example"],
  "relay": { "payer": "alice-org", "budget": 100, "scopes": { "https://search.example": ["search"], "…": [] } }
}

description, tools and resources come from the draft. relay is the lab's extension: who pays, how much, and which scopes the PS may issue to each company. The draft allows extra members, and section C.1.10 is explicit that tools and resources are a record of what the agent said it would do, not limits the PS has to enforce. The lab's PS enforces relay instead.

Consent is a deferred response

Only Alice can approve a mission, and she isn't sitting inside the HTTP request. So the PS answers straight away with 202 Accepted:

HTTP/1.1 202 Accepted
AAuth-Requirement: requirement=interaction; url="https://ps.example/interact"; code="NTAY-S7A3"
Location: https://ps.example/pending/UAoyqZ00s8O-skbMstbB7w
Retry-After: 0
Cache-Control: no-store

{"status":"pending","requirement":"interaction","code":"NTAY-S7A3","timeout":600}

The assistant shows Alice the URL and the code. The code is eight Crockford base32 characters, so it is easy to read aloud and compare on screen. Meanwhile the assistant polls the Location with signed GET requests:

GET /pending/…  → 202 {"status":"interacting"}   Alice has opened the page
GET /pending/…  → 200 { s256, mission, person_tokens }

The PS checks every poll is signed by the agent that made the original request, and answers 410 Gone once the result has been collected. If Alice declines, the poll returns 403 denied and the assistant stops.

The 200 carries the approved mission as base64url bytes, its s256 (the SHA-256 of those exact bytes), and a person token for each resource the mission named. The assistant checks the hash against the bytes before using it:

if (await digest(new TextDecoder().decode(base64url.decode(answer.data.mission))) !== answer.data.s256) throw new Error('Mission bytes do not match s256');

From here on, every token in the run carries mission_s256. That hash is how the PS, and anyone else who fetches the mission, knows which approval a request belongs to.

In the lab, Alice's browser session is simulated: she opens the URL and approves (or declines, if you pick that option). The 202, the code and the signed polls are real.

Token one: the person token

The person token says who the agent is acting for, at one specific resource. Here is the one ResearchCo presents to SearchCo:

{ "alg": "Ed25519", "typ": "aa-person+jwt", "kid": "ps-1" }
{
  "iss": "https://ps.example",
  "dwk": "aauth-person.json",
  "aud": "https://search.example",
  "sub": "0_I1miUFWgU1z6VmwgCDnI",
  "cnf": { "jwk": { "…": "ResearchCo's signing key" } },
  "mission_s256": "UBwsblTo4WYic7rJjRutN63H4ftxVCWS-ll8eehE6jE",
  "jti": "pt-4c1eb61e",
  "exp": 1792880414
}

Two details matter:

sub is directed. The PS gives Alice a different identifier at each resource, so SearchCo and ComputeCo can't match her up between them.
It authorizes nothing. A person token has no scope. It only identifies the person, so the resource can say what it needs.

Token two: the resource token

ResearchCo repeats its call with the person token. SearchCo verifies it, then answers with a second challenge:

HTTP/1.1 401 Unauthorized
AAuth-Requirement: requirement=auth-token; resource-token="eyJhbGciOiJFZDI1NTE5IiwidHlwIjoiYWEtcmVzb3…"

The resource token is SearchCo's request to the PS, addressed to it (aud):

{
  "iss": "https://search.example",
  "aud": "https://ps.example",
  "sub": "0_I1miUFWgU1z6VmwgCDnI",
  "scope": "search email",
  "account": "alice-org",
  "agent_jkt": "z6mEDnxVP4k0Op6Yn9LN7-DS8ucrLW0m3MXBj5eqnE4",
  "presented_jti": "pt-4c1eb61e",
  "mission_s256": "UBwsblTo4WYic7rJjRutN63H4ftxVCWS-ll8eehE6jE",
  "exp": 1792879815
}

It names the scope SearchCo needs, the billing account the caller asked for, the thumbprint of the caller's key (agent_jkt) and the person token it was issued against (presented_jti). It lives for five minutes. The lab builds it with one library call:

const resourceToken = await createResourceToken({ resource: this.id, audience: token.iss, presentedToken: token,
  agentJkt: signature.thumbprint, scope, account, kid: this.kid }, sign);

Token three: the auth token

ResearchCo sends the resource token and the person token to the PS. This is where authorization is decided. The PS first checks the resource token is genuine and matches what was presented (section 6.7.2 of the draft):

the resource token is signed by the resource named in its iss, and addressed to this PS;
agent_jkt is the key signing this request;
the person token was issued by this PS, to the resource that issued the resource token, bound to the same key;
presented_jti, sub, mission_s256 and tenant all match.

The mission_s256 check matters more than it looks. Without it, an agent could ask a resource for a token, strip the mission hash, and get an auth token that isn't bound to any approval. The lab has a test for exactly that.

Then the PS applies its own policy to the mission. In the lab, that means two checks from the relay extension:

for (const scope of resourceToken.scope.split(' ').filter(value => !IDENTITY_SCOPES.has(value))) {
  checks.push(row(`relay.scopes[${label}] ∋ "${scope}"`, allowed.includes(scope), 'PS policy · lab extension', allowed));
}
checks.push(row(`account "${resourceToken.account}" == relay.payer "${mission.blob.relay.payer}"`,
  resourceToken.account === mission.blob.relay.payer, 'PS policy · lab extension'));

If both pass, the PS mints the auth token:

{ "typ": "aa-auth+jwt" }
{
  "iss": "https://ps.example",
  "aud": "https://search.example",
  "sub": "0_I1miUFWgU1z6VmwgCDnI",
  "scope": "search email",
  "account": "alice-org",
  "email": "alice@alice-org.example",
  "mission_s256": "UBwsblTo4WYic7rJjRutN63H4ftxVCWS-ll8eehE6jE",
  "cnf": { "jwk": { "…": "ResearchCo's signing key" } },
  "exp": 1792880414
}

The PS released email because SearchCo asked for the email scope. The token can't outlive the agent token, the person token or the mission.

ResearchCo presents it on the third call, and SearchCo checks it against its own policy: does it accept work for this person, does the scope include the action, does it offer that action, and does the account match the payer in the request.

Three scenarios, three places they fail

Change payer. ResearchCo asks SearchCo to bill mallory-org. SearchCo dutifully puts account: mallory-org in the resource token, and the PS refuses:

{"error":"denied","detail":"Mission evaluation failed: account \"mallory-org\" == relay.payer \"alice-org\"","mission_checks":[…]}

SearchCo never receives an auth token, so it can't be talked into billing anyone.

Forbidden operation. ResearchCo asks for delete. SearchCo really does offer delete, but the mission only allows search there, so the PS refuses with relay.scopes[SearchCo] ∋ "delete" failing.

Untrusted issuer. ResearchCo skips the PS and presents an auth token signed by a rogue key, claiming to come from Alice's PS. SearchCo fetches the PS's real keys, the signature fails, and the call is rejected. This is the one scenario the receiver catches rather than the PS.

All errors use the draft's format: application/problem+json with an AAuth error code, and denied for policy refusals.

So far every hop looks like the Assistant calling PlannerCo. Part 4 covers what changes when PlannerCo passes work on to ResearchCo, and ResearchCo to SearchCo: call chaining with upstream_token.

Call chaining in AAuth: passing authority on with upstream tokens

DarkEdges — Sun, 25 Oct 2026 09:12:16 +0000

Part 3 followed one hop: the Assistant calling PlannerCo with tokens from Alice's person server. But PlannerCo doesn't do the research itself. It hands it to ResearchCo, which hands the search to SearchCo. This part covers how authority travels down that chain.

darkedges / aauth-lab

AAuth (draft-hardt-oauth-aauth-protocol-11) version of the Relay Biscuit lab, with a side-by-side comparison

Relay — AAuth network lab

Live demo: aauth.demos.darkedges.com

See COMPARISON.md for a side-by-side analysis of the two solutions.

Run locally

Use Node.js 22 or newer and pnpm 11:

pnpm install
pnpm dev

Open http://127.0.0.1:8796. The Biscuit lab uses 8795, so both labs can run side by side. On Windows, run ./start.ps1. The interface starts a demo run automatically.

pnpm check   # behaviour, spec-conformance, reference-client interop and debug formatting tests

How the AAuth version works

View on GitHub

The problem

When ResearchCo calls SearchCo, it needs a person token and an auth token for SearchCo. But ResearchCo has never met Alice. No one connected ResearchCo to her person server, and Alice didn't approve anything with ResearchCo directly.

What ResearchCo does have is the auth token PlannerCo presented to it. That token proves Alice's PS authorized PlannerCo to call ResearchCo, under Alice's mission. AAuth's answer is to show that token to the PS as evidence.

upstream_token

When an intermediary needs a token for the next resource, it passes the token it received as upstream_token. It signs the request with its own agent token, as always:

POST /person-token
Signature-Key: sig=jwt;jwt="<ResearchCo's agent token>"

{ "resource": "https://search.example", "upstream_token": "<the auth token PlannerCo presented>" }

There is no mission_s256 in this request. The upstream token already carries it.

It sends the same upstream_token again when it exchanges SearchCo's resource token for an auth token, alongside the resource token and the person token it presented:

{ "resource_token": "…", "presented_token": "…", "upstream_token": "…" }

What the person server checks

Section 9.4.5 of the draft lists what the PS must verify before it trusts an upstream token. In the lab:

async upstream(caller, raw) {
  const { payload, ps } = await this.ownToken(raw, 'upstream_token');
  if (ps !== this.id) throw new Refusal('invalid_upstream_token', 'upstream_token does not name this PS');
  if (payload.aud !== caller.agent.iss) throw new Refusal('invalid_upstream_token', `upstream_token aud ${payload.aud} is not the signing intermediary`);
  const record = this.issued.get(payload.jti);
  if (!record) throw new Refusal('invalid_upstream_token', 'This PS cannot identify the calling agent the upstream token was issued to');
  const person = this.directed.get(`${payload.aud}|${payload.sub}`);
  if (!person) throw new Refusal('invalid_upstream_token', 'This PS holds no record of the person at the upstream resource');
  return { payload, person, callingAgent: record.agent };
}

In words:

It is one of this PS's own tokens, a person token or an auth token, correctly signed and not expired.
It was addressed to the intermediary that is now signing. PlannerCo's token to ResearchCo has aud set to ResearchCo. If SearchCo got hold of it and tried to use it, the aud wouldn't match SearchCo's signing identity and the PS would refuse.
The PS knows which agent it issued that token to. That's how it identifies the calling agent one step up, even though the token itself doesn't name it.
The PS knows which person the token's sub refers to at the upstream resource.

Then it evaluates the new request against the same mission, exactly as in part 3.

The lab has conformance tests for the two interesting failures: an upstream token addressed to someone else, and a correctly signed upstream token the PS has no record of issuing. Both come back 400 invalid_upstream_token.

Lifetimes only shrink

A token issued with an upstream token can't outlive it:

const exp = Math.min(now() + 3600, caller.agent.exp, presented.payload.exp, upstream?.exp ?? Infinity, this.missionExp(mission));

So the whole chain expires no later than the first token, and no later than the mission. If Alice's mission ends, every token in the chain ends with it.

A new identifier at every hop

The person token PlannerCo got for ResearchCo has a sub that means Alice at ResearchCo. The one ResearchCo gets for SearchCo has a different sub, meaning Alice at SearchCo. The draft is strict about this: an issuer must not copy a directed sub from an upstream token into a token it issues.

The effect is that no two companies in the chain see the same identifier for Alice, so they can't use it to compare notes about her.

What an intermediary can't do

If you've used Biscuit, the obvious question is: can ResearchCo restrict what SearchCo may do?

No. The draft says downstream authorization "is not required to be a subset of the upstream scopes". A flight-booking service that calls a payment processor needs payment scopes it never had itself. So scopes don't narrow down the chain, and ResearchCo has no way to add restrictions of its own.

Every decision about what SearchCo may do is made by two parties:

The person server, against Alice's mission. In the lab, the mission's relay.scopes says SearchCo may be asked for search and nothing else.
SearchCo itself, with its local policy.

Section C.1.11 explains why there isn't even a record of the chain in the token: the immediate caller already identifies itself by signing, the parties further up are none of the downstream's business, and "the resource enforces, the person server attributes".

Caller trust, revisited

Part 2 showed that SearchCo can refuse ResearchCo on the identity request, and that nothing forces ResearchCo to make that request. Call chaining makes the gap concrete. Here is the lab's test, condensed:

// ResearchCo goes straight to a person token at SearchCo, which does not trust it.
if (to !== 'search') { /* normal identity call */ }
const person = await agent.send('ps', '/person-token', { body: { resource: target.id, upstream_token: upstream }, … });
const challenge = await agent.send(to, path, { token: person.data.person_token, … });
// …exchange the resource token, present the auth token…
assert.equal(run.tasks.find(task => task.provider === 'search').status, 'settled');

The run removes the ResearchCo to SearchCo trust edge, and the search still settles. SearchCo never saw anything naming ResearchCo.

The PS, however, knows exactly who asked. Every token request it handles is signed by an agent token, and its upstream check identifies the agent one step up. So "SearchCo only accepts work passed on by ResearchCo" is enforceable, but as a rule at the person server, not at SearchCo. That's the AAuth way of thinking: the resource enforces the request in front of it, and the person server owns the chain.

The lab keeps SearchCo's identity check, because it works whenever an agent behaves, and labels its limits clearly in the UI.

The library gap

The reference client, @aauth/agent, supports upstream_token on the person-token request but not on the auth-token request. exchangeToken has no option for it, and the high-level createAAuthFetch has no upstream option at all.

The lab's interop tests, which use the reference client as every agent, therefore call exchangeToken without upstream_token. The lab's PS accepts that, since the parameter is optional. But it then can't run the upstream checks at that step, or cap the auth token's lifetime at the upstream token's. I've reported it as aauth-dev/packages-js#37.

Part 5 covers the last company in every chain, the one that gets paid: how the clearinghouse bills Alice's organisation when no token names the company doing the work, and what changed when I ran the flow against a real person server.

Paying for it, and checking AAuth against a real person server

DarkEdges — Sun, 25 Oct 2026 09:11:05 +0000

The first four parts covered authority: who is calling, on whose behalf, and who decides. This last part covers money, and then checks the whole thing against the real world.

darkedges / aauth-lab

AAuth (draft-hardt-oauth-aauth-protocol-11) version of the Relay Biscuit lab, with a side-by-side comparison

Relay — AAuth network lab

Live demo: aauth.demos.darkedges.com

See COMPARISON.md for a side-by-side analysis of the two solutions.

Run locally

Use Node.js 22 or newer and pnpm 11:

pnpm install
pnpm dev

Open http://127.0.0.1:8796. The Biscuit lab uses 8795, so both labs can run side by side. On Windows, run ./start.ps1. The interface starts a demo run automatically.

pnpm check   # behaviour, spec-conformance, reference-client interop and debug formatting tests

How the AAuth version works

View on GitHub

The clearinghouse is just another resource

Every billable call goes to a shared clearinghouse: reserve credits before the work, settle after it, release them if the work fails. In the lab the clearinghouse is an ordinary AAuth resource. Each operator reaches it with the same five-step hop as any other call, passing its upstream token, so the PS authorizes every billing call against Alice's mission too. The scope is billing.

Before the first call, the clearinghouse funds the mission. It fetches the mission from the PS and checks the bytes against the hash:

async fund(s256) {
  const bytes = await (await fetch(`${this.demo.ps.id}/missions/${s256}`)).text();
  if (await digest(bytes) !== s256) throw new Error('Mission bytes do not match mission_s256');
  const { relay } = JSON.parse(bytes);
  Object.assign(this, { mission: s256, budget: relay.budget, payer: relay.payer });
}

On each call it takes the payer from the auth token's account claim, which the PS signed after checking it against the mission. Nothing in the request body can change who pays.

Who gets paid?

Here AAuth's privacy design gets in the way. The clearinghouse has to credit the company that did the work, but as part 2 explained, no token in the three-party flow names the calling agent.

The lab fills the gap with a small, clearly labelled extension: a provider assertion. The operator signs a short JWT with its agent-provider key, bound to the key that signs the request and to this one operation:

const assertion = await this.sign({ iss: this.id, operation_id: payload.operation_id, path,
  jkt: await calculateJwkThumbprint(this.signingPublic), iat: now(), exp: now() + 300 }, 'relay-billing+jwt');

The clearinghouse verifies it against the operator's published keys and checks the binding:

if (payload.jkt !== thumbprint || payload.path !== path || payload.operation_id !== operationId) throw new Error('Provider assertion is not bound to this request');

Because jkt must match the key that signed the HTTP request, an assertion can't be lifted from one request and replayed on another. This isn't part of AAuth. It's what a real billing service would need to add, and it's the clearest example in the lab of AAuth leaving agent identity to the application.

Reserve, execute, settle

The accounting is the same as in the Biscuit version of the lab, because none of it depends on the authorization protocol:

Reservations are serialised. JavaScript is single-threaded, but await points interleave requests. A promise queue makes each reservation's read-then-write atomic, so two 60-credit calls against 100 credits can't both succeed. The loser gets 402 insufficient_credits.
Retries are idempotent. A reservation is keyed by operation ID and fingerprinted. Repeating the same operation returns the existing result with duplicate: true. Reusing the ID with different details is a 409.
Failures release. If the work fails after reserving, the operator releases the reservation and the credits return to available.
Settlement needs a receipt. The operator signs a receipt bound to the reservation grant, and the clearinghouse only settles against it.

The retry scenario shows one AAuth-specific benefit: the second attempt reuses the cached auth token, so it needs no PS round trip at all.

Checking it against the real thing

A simulation can be wrong in ways its own tests won't catch. Everything so far runs against a person server I wrote. So I set up a real agent identity (part 2), and ran the AAuth walkthrough against Hellō's person server, person.hello.coop, and the public test resource whoami.aauth.dev.

The first call, signed with just the agent token, came back 200 with my agent's identifier. The second asked for my profile and walked the full three-party flow, pausing for me to approve in a browser. It ended with:

{
  "iss": "https://person.hello.coop",
  "sub": "sub_…",
  "name": "…",
  "email": "…",
  "email_verified": true
}

The live run confirmed the lab's model:

The challenge order is the same: agent token, then 401 requirement=person-token, then person token, then 401 requirement=auth-token with a resource token, then the auth token.
Token lifetimes are capped the same way. The person token and auth token both ended exactly when the agent token did.
The final response named me, but not my agent. The person token did carry my agent's identifier, in a Hellō-specific claim. The PS knows the agent; the resource doesn't.

It also differed in useful ways:

Hellō asked for consent at the person-token request, not at a mission. It doesn't publish a mission endpoint at all.
The later auth-token request came back 202 requirement=approval: the PS was deciding without needing me in a browser. The lab's PS decides those at once.
The profile came back as claims in the auth token, with a whoami scope, rather than as openid profile scopes.

The lab now copies the consent 202 and polling, and pnpm live runs the assistant's first hop both ways, in the lab and against the real services, and prints them side by side:

                         lab   live
  signed requests           7      5
  to the person server      4      2
  consent polls             2      0
  401 challenges            2      2

The difference is the mission. The live hop asks for a person token directly; the lab's hop gets one from the mission approval.

The live run also turned up two gaps in the reference libraries, both reported: exchangeToken can't send upstream_token (#37), and the --explain narration in @aauth/fetch sometimes describes a different message from the one on the wire (#38).

What a production version would need

The lab deliberately stops short of being a real system. To make it one you would need:

A real person server, with persistent missions, real consent screens, revocation and a mission log the person can read.
Persistent agent keys, published at stable agent-provider URLs and rotated, instead of fresh keys on every run.
Network transport between companies, where every PS call and key-discovery fetch is a round trip. The happy path makes 16 PS calls and 23 discovery fetches; caching helps the second number, not the first.
A decision about caller trust. If a company must only accept work from particular callers, enforce that at the person server, which sees every hop.
Durable accounting, with transactional reservations, reservation expiry and reconciliation.

Wrapping up

Across the five parts, we covered:

Agents that sign every request, with keys bound to self-published identities, and no bearer tokens anywhere.
A mission that the person approves once, with deferred consent, and whose hash every later token carries.
Three tokens per hop: a person token that says who for, a resource token that says what's needed, and an auth token the person server mints after checking both against the mission.
Call chaining, where intermediaries present upstream tokens and the person server, not the token, holds the chain.
A clearinghouse that bills the right payer and the right company, with the gaps AAuth leaves to the application filled in and labelled.

The most important lesson for me was where the decisions end up. Almost everything that matters, who pays, what's allowed, and even who may call whom, is decided by the person server. That gives you one accountable place, at the cost of putting it on every hop.

If you want the side-by-side with Biscuit, which makes the opposite trade, it's in COMPARISON.md.

Try to break it. Remove trust, swap payers, squeeze the budget, have Alice decline, and watch the Debug tab. If you find a way to get SearchCo to do work it shouldn't, please open an issue.

Code: github.com/darkedges/aauth-lab · Demo: aauth.demos.darkedges.com

Signed requests and agent identity in AAuth

DarkEdges — Sun, 25 Oct 2026 09:10:23 +0000

Part 1 introduced the network and the five steps of a hop. This part covers the first step and the thing every later step depends on: how an agent proves who it is.

darkedges / aauth-lab

AAuth (draft-hardt-oauth-aauth-protocol-11) version of the Relay Biscuit lab, with a side-by-side comparison

Relay — AAuth network lab

Live demo: aauth.demos.darkedges.com

See COMPARISON.md for a side-by-side analysis of the two solutions.

Run locally

Use Node.js 22 or newer and pnpm 11:

pnpm install
pnpm dev

Open http://127.0.0.1:8796. The Biscuit lab uses 8795, so both labs can run side by side. On Windows, run ./start.ps1. The interface starts a demo run automatically.

pnpm check   # behaviour, spec-conformance, reference-client interop and debug formatting tests

How the AAuth version works

View on GitHub

No bearer tokens

In OAuth as most people use it, a request carries Authorization: Bearer <token>, and whoever holds the token can use it. AAuth never sends a credential that works on its own. Every request is signed with the agent's private key, and every token the agent presents is bound to the matching public key.

That gives two properties at once:

A copied token is useless. It only works on requests signed by the key named inside it.
The receiver knows which key made the request, so it can tie the request to an identity without a separate login.

The three headers

Here is ResearchCo's first request to SearchCo, as recorded by the lab:

POST /tasks/search HTTP/1.1
Host: search.49ba54c6.relay.example
Content-Type: application/json
Content-Digest: sha-256=:…:
Signature-Input: sig=("@method" "@authority" "@path" "content-type" "signature-key" "content-digest");created=1792879515
Signature: sig=:LwNGjQhr2M7YekfJkCNS0OLxz4GZAe2xBVb…:
Signature-Key: sig=jwt;jwt="eyJhbGciOiJFZDI1NTE5IiwidHl…"

Signature-Input lists what the signature covers: the method, host and path, the content type, the body digest, and the Signature-Key header itself. Covering Signature-Key stops someone swapping in a different token.
Signature is the Ed25519 signature over those components (RFC 9421).
Signature-Key says where to find the key that verifies it. Here sig=jwt means the key is inside a JWT: the agent token.

POST requests to the person server always include content-digest, so the body can't be changed in transit. A signed GET with no body covers only the method, authority, path and signature-key.

The agent token

Decoded, ResearchCo's agent token looks like this:

{ "alg": "Ed25519", "typ": "aa-agent+jwt", "kid": "research-1" }
{
  "iss": "https://research.49ba54c6.relay.example",
  "dwk": "aauth-agent.json",
  "sub": "aauth:research@research.49ba54c6.relay.example",
  "ps": "https://ps.49ba54c6.relay.example",
  "cnf": { "jwk": { "kty": "OKP", "crv": "Ed25519", "x": "…" } },
  "jti": "agt-99716a01",
  "iat": 1792879514,
  "exp": 1792883114
}

iss is the agent provider, and dwk names its well-known document, so a verifier knows to fetch {iss}/.well-known/aauth-agent.json.
sub is the agent's identifier, in the form aauth:local@domain.
cnf.jwk is the public key the request must be signed with.
ps names the person server this agent works with.

In the lab each company is its own agent provider. It generates a provider key and a separate signing key, and signs its own agent token:

this.agentToken = await this.sign({ iss: this.id, dwk: DWK.agent, sub: this.sub, ps: this.demo.ps.id,
  cnf: { jwk: this.signingPublic }, jti: id('agt'), iat: now(), exp: now() + 3600 }, TOKEN_TYP.agent);

Signing a request is one call to the reference library:

const signedFetch = createSignedFetch(async () => ({ signingKey: this.signingPrivate, signatureKey: { type: 'jwt', jwt: token } }),
  { signBody: ps, onSigned: value => { sent = value; } });
const response = await signedFetch(`${target.id}${path}`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) });

The same function signs every request in the run. Only the token in Signature-Key changes from step to step: the agent token, then a person token, then an auth token.

Verifying on the receiving side

SearchCo checks two things, in order. First the HTTP signature, then the token:

const signature = await verifySignature({ method: request.method, authority: url.host, path: url.pathname, headers: request.headers, body: text });
if (!signature.verified) return problem(code, signature.error, 401, { 'signature-error': `error=${code}` });

const token = await verifyToken({ jwt: signature.jwt.raw, httpSignatureThumbprint: signature.thumbprint,
  resource: this.id, accept: ['agent', 'person', 'auth'] });

verifyToken fetches the issuer's well-known document, follows its jwks_uri, picks the key by kid, checks the JWT signature and expiry, and checks that the token's cnf key is the key that signed the request (by comparing thumbprints). Those fetches are the 23 "key discovery" entries in the lab's Debug tab. They are public and unsigned, and a real deployment caches them.

Identity-based access

With just the agent token, SearchCo knows who is calling. That is enough for some decisions, and the draft calls this identity-based access. In the lab, SearchCo uses it for caller trust:

if (token.type === 'agent') {
  const caller = this.demo.partyBySub(token.sub);
  if (!this.trusts(caller)) return { response: problem('denied', `${this.label} does not accept calls from ${token.sub}`, 403) };
  return { response: problem('person_token_required', 'Present a person token', 401, { 'aauth-requirement': buildAAuthHeader('person-token') }) };
}

Remove the ResearchCo to SearchCo trust edge in the demo and SearchCo answers 403 denied on this first request. No person server is contacted and no token is minted.

If SearchCo does trust the caller, it answers:

HTTP/1.1 401 Unauthorized
AAuth-Requirement: requirement=person-token
Content-Type: application/problem+json

{"error":"person_token_required","detail":"Present a person token"}

The caller now has to show who it is acting for.

A real agent identity

The lab's agents only exist inside one run. To check the lab against the real world, I also set up a real agent with the @aauth/bootstrap tool. It generated an Ed25519 key in the Windows keychain and printed the public key. I published that key and the agent metadata as two static files on Cloudflare Pages:

https://agent.demos.darkedges.com/.well-known/aauth-agent.json
https://agent.demos.darkedges.com/.well-known/jwks.json

That's all an agent provider needs. A signed request to the public test resource whoami.aauth.dev then came back with:

{
  "iss": "https://agent.demos.darkedges.com",
  "sub": "aauth:local@agent.demos.darkedges.com",
  "ps": "https://person.hello.coop"
}

The resource fetched my published key, checked the signature, and knew which agent was calling. There was no account to register and no client secret to exchange.

The catch: identity stops at the first request

Here is the part that surprised me. In AAuth's three-party flow, the agent identifier appears only on this first request. The person token, resource token and auth token that follow don't name the agent at all.

That is deliberate. Appendix C.1.6 of the draft explains that a person's relationship with a resource should survive a change of agent. If Alice switches assistants, SearchCo should still recognise her, not the assistant.

The consequence is that caller trust can only be enforced on the identity request, and nothing forces an agent to make it. The lab has a test where ResearchCo skips the identity call, goes straight to the person server for a person token, and is served by SearchCo even after SearchCo has stopped trusting it.

So "SearchCo only accepts work from ResearchCo" isn't a rule SearchCo can enforce on its own in AAuth. If you need it, it belongs at the person server, which sees every hop and knows which agent asked for each token. I'll come back to this in part 4.

Part 3 follows the request past the 401: how Alice approves a mission, and how the person, resource and auth tokens let her person server decide each hop.

Delegating work across companies with AAuth

DarkEdges — Sat, 24 Oct 2026 22:15:14 +0000

Alice wants a piece of work done, and her organisation pays for it. She gives the job to her assistant, an AI agent. The assistant hands it to a coordinator, and the coordinator splits it between other companies. Some of those companies pass part of the job on again.

Every company in that chain has to answer the same questions before it does any work:

Who is calling me, and do I accept work from them?
On whose behalf is this request, and did that person actually approve it?
Who pays, and is that the payer the person agreed to?
Is this action within what the person approved?
Is there still money left?

A bearer token or API key answers almost none of these. It says "the holder may do X", and anyone who copies it becomes the holder.

AAuth is an HTTP authorization protocol designed for agents. It is an IETF draft (this series uses draft 11) by Dick Hardt. I built AAuth Network Lab to see how far it gets on this problem, with real signatures and tokens and simulated companies. This series walks through how it works.

darkedges / aauth-lab

AAuth (draft-hardt-oauth-aauth-protocol-11) version of the Relay Biscuit lab, with a side-by-side comparison

Relay — AAuth network lab

Live demo: aauth.demos.darkedges.com

See COMPARISON.md for a side-by-side analysis of the two solutions.

Run locally

Use Node.js 22 or newer and pnpm 11:

pnpm install
pnpm dev

Open http://127.0.0.1:8796. The Biscuit lab uses 8795, so both labs can run side by side. On Windows, run ./start.ps1. The interface starts a demo run automatically.

pnpm check   # behaviour, spec-conformance, reference-client interop and debug formatting tests

How the AAuth version works

View on GitHub

Live demo: aauth.demos.darkedges.com

If you read my earlier Biscuit Trust Lab series (code), this is the same network, the same seven scenarios and the same clearinghouse, rebuilt on a different protocol. You don't need to have read it.

The network

Alice (person) / alice-org (payer)
  └─ Assistant (Alice's agent)
       └─ PlannerCo (coordinator)
            ├─ ResearchCo [5 credits]
            │    └─ SearchCo [10 credits]
            └─ ComputeCo [25 credits]

All billable calls → shared clearinghouse
Alice's person server issues every token

Alice approves a budget of 100 credits. The happy path costs 40: research 5, search 10, compute 25.

Seven scenarios try to break it:

Scenario	What goes wrong
Authorized delegation	Nothing. Three operations settle for 40 credits.
Change payer	ResearchCo asks SearchCo to bill `mallory-org`
Forbidden operation	ResearchCo asks SearchCo to `delete`, which SearchCo offers but Alice never approved
Untrusted issuer	ResearchCo presents a token signed by a rogue key claiming to be Alice's person server
Competing reservations	Two 60-credit calls race for a 100-credit budget
Retry	ResearchCo repeats a search with the same operation ID
Operation failure	SearchCo reserves credits, then fails

A trust editor lets you remove a "this company accepts calls from that company" relationship, or stop a company accepting Alice as a requester, and run again.

Four roles

AAuth gives every participant one of a few roles. In the lab:

Agents make requests. The Assistant, PlannerCo, ResearchCo and ComputeCo are all agents, because each calls someone else. An agent has a signing key and an agent token that binds that key to an identifier such as aauth:research@research.example.
Agent providers vouch for agents. An agent provider publishes /.well-known/aauth-agent.json and a JWKS, and signs agent tokens. In the lab each company is its own agent provider.
Resources receive requests. PlannerCo, ResearchCo, SearchCo, ComputeCo and the clearinghouse are resources. Intermediaries are both: a resource to their caller, an agent to the next company.
The person server (PS) represents Alice. It knows who she is, records what she approved, and issues the tokens that let agents act for her.

The important design choice is the last one. Authority doesn't live in a token that gets passed down the chain. It lives at the person server, and every hop asks it again.

One hop, five steps

Every call between two companies follows the same pattern. Here is ResearchCo calling SearchCo:

Identity call. ResearchCo signs the HTTP request with its own key (RFC 9421 HTTP Message Signatures) and puts its agent token in a Signature-Key header. SearchCo now knows who is calling. It answers 401 with AAuth-Requirement: requirement=person-token.
Person token. ResearchCo asks Alice's PS for a person token addressed to SearchCo. Because ResearchCo is an intermediary, it includes the token it was given by PlannerCo as upstream_token.
Resource token. ResearchCo repeats the call, presenting the person token. SearchCo answers 401 again with requirement=auth-token and a resource token saying what it needs: scope search email, billing account alice-org.
Auth token. ResearchCo takes the resource token to the PS. The PS checks it against what Alice approved, and either mints an auth token or refuses.
Authorized call. ResearchCo calls SearchCo a third time, presenting the auth token. SearchCo verifies it, applies its own policy, and does the work.

Every request in that list is signed by ResearchCo's key, and every token is bound to that key. A token copied off the wire is useless without the private key.

Before any of this, Alice approves a mission at her PS: what the assistant is trying to do, which tools it will use, and which services it will call. Every token in the run carries the mission's hash.

On the happy path that adds up to 40 signed HTTP requests, 16 of them to the person server.

What the lab adds on top of AAuth

AAuth defines the signatures, tokens and person server. It deliberately doesn't define payers, budgets or billing. The lab adds three things and labels each one as a lab extension in the UI:

A relay member in the mission that records the payer, the budget and the scopes the PS may issue for each company. The draft allows extra members in the mission.
A clearinghouse that reserves, settles and releases credits, the same as in the Biscuit lab.
A signed provider assertion on billing calls, because AAuth tokens don't name the calling agent and the clearinghouse needs to know who to pay. Part 5 explains why.

Try it

Open the demo and leave the defaults. Run the network.

The Debug tab lists every signed request in order, with the real Signature, Signature-Input and Signature-Key headers, the decoded token, the AAuth-Requirement challenge and a short narration of what happened. The Decision logic tab shows, for each company, which checks passed and where each fact came from: the HTTP signature, a token the PS signed, the company's own policy, or the mission.

Then try the guided exercises:

Protect the original payer. The PS refuses to mint the auth token. SearchCo never sees a request it could act on.
Remove a trust relationship. SearchCo refuses ResearchCo on the very first request, before anyone contacts the PS.
The person declines the mission. Alice says no at her PS, and nothing runs.

Run it locally

You need Node.js 22 and pnpm 11.

git clone https://github.com/darkedges/aauth-lab
cd aauth-lab
pnpm install
pnpm dev     # http://127.0.0.1:8796
pnpm check   # 33 tests: behaviour, spec conformance, reference-client interop

All parties run inside one Cloudflare Pages function. Each run creates fresh keys and fresh origins such as https://search.<tag>.relay.example, and requests between them are real Request and Response objects routed in process.

Signing and verification use the official libraries: @aauth/agent signs, @hellocoop/httpsig verifies, @aauth/resource verifies tokens and builds the challenges, and jose signs the tokens the PS mints.

Coming up in this series

This post: the problem, the network and the shape of a hop.
Signed requests and agent identity: RFC 9421 signatures, the Signature-Key header, agent tokens and key discovery.
Missions, consent and three tokens: how Alice approves the work, and how the PS decides each hop.
Call chaining: how intermediaries pass authority on with upstream_token, and what they can't do.
Paying for it, and checking against a real person server: billing without agent identity, and what a live run against Hellō's person server showed.

Same lab, different protocol: rebuilding the Biscuit trust lab on AAuth

DarkEdges — Sat, 24 Oct 2026 21:29:33 +0000

The first four parts of this series built a delegation network on Biscuit: Alice asks PlannerCo for research, PlannerCo hands work to ResearchCo and ComputeCo, ResearchCo hands search to SearchCo, and a clearinghouse bills Alice's organisation for all of it.

This part rebuilds the same lab on AAuth, an HTTP authorization protocol in which agents sign every request and a person server issues the tokens. It has the same operators, the same seven scenarios, the same trust editor and the same clearinghouse. Every scenario settles the same credits as the Biscuit version: 40 / 30 / 30 / 30 / 65 / 40 / 30.

What changes is where each decision is made, and what that costs.

darkedges / aauth-lab

AAuth (draft-hardt-oauth-aauth-protocol-11) version of the Relay Biscuit lab, with a side-by-side comparison

Relay — AAuth network lab

Live demo: aauth.demos.darkedges.com

See COMPARISON.md for a side-by-side analysis of the two solutions.

Run locally

Use Node.js 22 or newer and pnpm 11:

pnpm install
pnpm dev

Open http://127.0.0.1:8796. The Biscuit lab uses 8795, so both labs can run side by side. On Windows, run ./start.ps1. The interface starts a demo run automatically.

pnpm check   # behaviour, spec-conformance, reference-client interop and debug formatting tests

How the AAuth version works

View on GitHub

The one-line difference

Biscuit puts authority in the token. The clearinghouse mints a root token once. Each intermediary narrows it offline by appending blocks, and each receiver decides locally with Datalog.
AAuth puts authority in the person server. Every hop asks Alice's person server (PS) for a fresh, key-bound auth token. The PS decides against the mission Alice approved, and receivers verify the token and apply their own policy.

What one hop looks like

Before any work starts, the Assistant proposes a mission to Alice's PS: a description, the tools it will use and the resources it will call. Only Alice can approve it, so the PS answers 202 Accepted with an interaction URL, a code and a pending URL. The Assistant polls with signed GETs while Alice approves in her browser, then receives the mission and its mission_s256 hash. Every later token carries that hash.

Then every hop runs the same five steps:

Identity call. The caller signs the request (RFC 9421) with a self-issued agent token in the Signature-Key header. The receiver now knows who is calling, and answers 401 asking for a person token.
Person token. The caller asks the PS for a person token for that receiver. An intermediary passes the token it was given as upstream_token, which is how AAuth chains calls.
Resource token. The caller presents the person token. The receiver answers 401 again, this time with a resource token naming the scope and billing account it needs.
Auth token. The caller takes the resource token to the PS. The PS checks it against the mission and either mints an auth token or refuses.
Authorized call. The receiver verifies the auth token (issuer keys, audience, expiry, and that it is bound to the key signing the request), applies local policy, and does the work.

Nothing is simulated in the protocol: the signatures, tokens and HTTP exchanges are real, routed between independent origins inside one Cloudflare Pages function. The operators, the work and the credits are simulated, as before.

Where each scenario is stopped

Scenario	Biscuit lab	AAuth lab
Change the payer	SearchCo's Datalog compares the payer with the call	The PS refuses to mint the auth token: the account doesn't match the mission's payer. SearchCo never sees a token.
Forbidden operation	SearchCo's Datalog: no `right("delete")`	The PS refuses under its own policy, even though SearchCo offers `delete`
Untrusted issuer	Signature fails against the pinned root key	Signature fails against the PS's published keys
Remove caller trust	SearchCo's Datalog: `trusts_caller` missing	SearchCo returns `403` on the first, identity-only request
Budget race, retry, failure	Clearinghouse	Clearinghouse, unchanged

The pattern is clear: decisions that Biscuit spreads across receivers move to the PS in AAuth.

What AAuth gives you for free

Biscuit tokens are bearer tokens, and Biscuit blocks don't record who appended them. To know who was calling, the Biscuit lab had to invent two things: a separate Ed25519 signature over every call, and signed delegation envelopes chained by hash.

AAuth has proof of possession built in. Every request is signed, every token is bound to the key that signs the request, and an intermediary signs with its own agent token. A stolen AAuth token is useless without the key. That is AAuth's clearest advantage.

AAuth also makes the person part of the protocol. Biscuit has no notion of consent; the root token simply asserts requester("alice"). In AAuth, Alice approves a mission, the PS keeps a log of every token it issues or refuses under it, and each resource sees a different pseudonymous identifier for her, so SearchCo and ComputeCo can't correlate her.

What it takes away

Offline narrowing. Biscuit's defining feature is that ResearchCo can restrict what SearchCo may do without asking anyone, and SearchCo can check that offline. AAuth has no equivalent: an intermediary can't constrain its sub-delegate. Only the PS and the receiver decide.

Caller identity, on every call. This one surprised me. In the three-party flow, no token AAuth issues names the agent. That's deliberate (Appendix C.1.6 of the draft): Alice's relationship with a resource should survive a change of agent. A receiver can refuse a caller on the identity-only request, but nothing forces a caller to make that request first. The lab has a test showing that ResearchCo can skip it, go straight to a person token, and be served by SearchCo even after SearchCo's trust in ResearchCo is removed.

So the Biscuit lab's per-receiver "I trust this caller" rule has no binding equivalent in AAuth. That policy belongs at the PS, which sees every hop.

What it costs

On one happy-path run:

	Biscuit lab	AAuth lab
Calls to the issuer after minting	0	16 (PS), including 2 consent polls
Recorded exchanges	13 internal evaluations	40 signed HTTP requests, 14 of them `401` challenges
Key-discovery fetches	0 (root key pinned)	23
Mean run time (Node, in-process)	~35 ms	~150 ms

Everything runs in one process, so these count messages, not network latency. In a real deployment every PS call and discovery fetch is a round trip, and the PS has to be up for any work to happen. The flip side is revocation: the PS simply stops issuing, and tokens expire within the hour. Biscuit needs revocation identifiers distributed to every verifier.

Checked against a live person server

A simulation can be wrong in ways its own tests won't catch, so I also ran AAuth's official walkthrough with a real agent identity, Hellō's person server (person.hello.coop) and a real resource (whoami.aauth.dev). The lab now has a pnpm live command that runs the Assistant's first hop both ways and prints them side by side.

The live run confirmed the order of challenges, the token lifetimes, and the caller-identity point: the resource that served Alice never learned which agent called, while the PS did. It also showed things the lab now copies, like the consent 202 and polling, and things it doesn't, like a PS that defers later requests with requirement=approval instead of deciding at once.

It also turned up two gaps in the reference JavaScript libraries, now filed upstream: exchangeToken can't send upstream_token, so call chaining can't be completed through the library, and the --explain narration doesn't always match the wire.

When to pick which

Pick Biscuit for offline or partition-tolerant verification, for intermediaries that must narrow authority themselves, and for one uniform policy language in tokens and at receivers.
Pick AAuth for proof of possession on every request, for person consent and a central audit log, and for pseudonymous per-resource identifiers.

They also combine well. AAuth can carry who (a signed agent, a person, a mission) and Biscuit can carry what (offline-attenuable rights), for example as an AAuth resource that accepts a Biscuit as its scoped grant. These labs keep them separate so the differences stay visible.

Wrapping up

The headline is simple: Biscuit decides at the edges, AAuth decides in the middle. The more interesting result is the one I didn't expect going in: AAuth's privacy goal means receivers can't enforce which agent calls them, so "who may call me" becomes the person server's job.

The full side-by-side is in COMPARISON.md. Try both labs, run the same scenario in each, and compare the Debug tabs.

Code: github.com/darkedges/aauth-lab · Demo: aauth.demos.darkedges.com · Biscuit version: biscuits.demos.darkedges.com

Step-up MFA, attenuation, and what's honestly not done

DarkEdges — Sun, 04 Oct 2026 11:51:54 +0000

Repo: darkedges/pf12.3-biscuit-datalog-tokens

We've covered why a hybrid works, the token generator plugin, and the Terraform plus end-to-end test. Part 3 ended with alice holding orders:write and still getting a 403. This part unlocks that write, narrows the token in a few ways, and then says plainly what doesn't work yet.

1. Why the write was refused

orders-api's policy has three rules:

allow if scope("orders:read"), operation("read");
allow if scope("orders:write"), operation("write"), amr("mfa") trusting authority, ed25519/<attestation key>;
deny if true;

A write needs the scope and an amr("mfa") fact. It also has to be a fact the service trusts. trusting authority, ed25519/<key> means: look for amr("mfa") in the authority block (PingFederate's) or in a block signed by the attestation key, and nowhere else.

When no allow rule matches, Biscuit only reports that deny if true matched, which tells you nothing. So orders-api works out which requirement is missing and says so:

{
  "allowed": false,
  "operation": "write",
  "reason": "write requires amr(\"mfa\") signed by ed25519/59c06655… (step-up)",
  "resource": "/orders/123"
}

The gotcha in `trusting`

My first version of that rule was:

allow if scope("orders:write"), operation("write"), amr("mfa") trusting ed25519/<attestation key>;

It never matched, even with the attestation present. trusting replaces a rule's default scope; it doesn't add to it. Without authority in the list, the rule could no longer see scope("orders:write") in PingFederate's authority block. It failed silently, with no error. If you write Biscuit policies with third-party blocks, trusting authority, <key> is almost always what you mean.

2. Step-up: an attestation as a third-party block

Biscuit has a mechanism designed for exactly this: third-party blocks. The holder sends a request derived from its token to an attestor. The attestor signs a block (here containing amr("mfa")) bound to that specific token, and the holder appends it. Nobody else can move that block onto a different token, and the attestor never sees the token itself.

In the demo app, Add MFA attestation does exactly that. The Token tab then shows a second block:

1  third-party · attestation    signed by ed25519/59c06655…
   amr("mfa");

POST again and it's a 200. From the command line, make mfa followed by make call does the same.

The honest part: PingFederate isn't the attestor yet

The design I wanted was PingFederate signs the attestation, right after it has run MFA. It has the user's session and knows MFA happened, and it already holds signing keys. biscuit-java even has the API for it.

It doesn't work today. biscuit-java 4.0.1, the latest on Maven Central, still uses the legacy third-party request format, which carries a previousKey. biscuit-auth 6 (Rust, which orders-api and the demo app use) sends the newer format with a previous_signature, and rejects the legacy one. Hand a Rust-made request to biscuit-java and you get:

InvalidProtocolBufferException: Message missing required fields: previousKey

So the demo simulates PingFederate's attestor with a separate Ed25519 key in .keys/attestation.env, signing with biscuit-auth. The flow, the policy and the trust model are exactly what PingFederate would do. Only the signer is a stand-in.

There are three ways to get the real thing:

biscuit-java catches up with the newer third-party format. Then the attestor can be a small PingFederate endpoint or plugin.
A sidecar attestor next to PingFederate, using biscuit-auth. PingFederate decides that MFA happened; the sidecar signs.
Step up at the IdP and re-exchange. This works today, and it's the most "hybrid" option. Run MFA in PingFederate and put the amr claim in the JWT. Then make another token exchange and map amr into the authority block. The generator already allows an amr fact; it's in the default fact list. The cost is a round trip to PingFederate for step-up, which you'd make anyway for the MFA itself. The demo doesn't wire this up, because its HTML form login has no MFA, but nothing in the plugin stops it.

3. Attenuation: narrowing without asking

With the write unlocked, the demo app's Attenuate buttons append blocks that only ever narrow the token:

Button	Block appended	Effect
Read-only	`check if operation("read");`	POST → `403`, naming the failed check
Only this order	`check if resource($r), $r == "/orders/999";`	`/orders/999` → 200, `/orders/123` → 403
Expire in 60 s	`check if time($t), $t <= <now+60s>;`	Valid for a minute, even though PingFederate gave it five
Custom	your Datalog	e.g. `check if operation("read");`

None of these call PingFederate, and none need a key. This is the Trust Lab's delegation step, now on a token that started life in an enterprise IdP. A gateway can hand a downstream service a token that's read-only, for one order, for one minute, in microseconds.

Two properties are worth checking yourself in the app:

Values can't inject Datalog. The order ID and the time go into the block as parameters, not pasted text. Even so, the app only accepts order IDs of letters, digits, - and _.
A holder can't widen a token. Append a block that says amr("mfa"); scope("orders:admin"); yourself and POST: still 403. Facts in an ordinary appended block aren't trusted by the policy. Only the authority block and the attestation key are.

Seal finishes the token: no further blocks can be appended, and the app disables those buttons. Fresh Biscuit from PingFederate runs the exchange again.

4. Revocation and certificate binding

The standalone demo (make demo, 19 checks, no PingFederate needed) covers two things the web app doesn't:

Revocation. Each block has a revocation ID. Revoke the authority block's ID, which the plugin logs at mint time, and the original token and every narrowed copy fail. A token with a different ID is unaffected.
Certificate binding. A token minted with a cnf_x5t_s256 attribute only works when presented over the matching client certificate.

What is not proven

The prototype works end to end. That's different from being production-ready:

PingFederate as the MFA attestor: blocked by the biscuit-java format gap above; the demo simulates it.
Revocation distribution: orders-api reads revoked IDs from a file. Getting them to every service quickly, by push, pull or short lifetimes, is a design problem I haven't solved here.
Introspection: PingFederate can confirm a narrowed Biscuit's signature, but not whether it's authorized. That depends on request facts only the service has. active: true would mean "authentic and unexpired", nothing more.
Policy governance: each service carries its own Datalog. Keeping policies consistent across services needs version control, review and tests, like any other code.
Ecosystem: PingAccess and off-the-shelf gateways don't understand Biscuits. The hybrid sidesteps this by keeping JWTs at the edge, but it's a real limit on how far in the Biscuit can go.
Demo shortcuts: HS256 JWTs with a symmetric key, generated secrets in local Terraform state, self-signed TLS, and the root key in a PingFederate config field rather than an HSM.
Size: every block adds bytes. The demo's token grew from 436 bytes (one block) to about 1 KB (four blocks). Seal early if headers matter.

Back to the Trust Lab's list

Part 4 of the Trust Lab ended with what a production version would need. Here's where an IdP-minted root moves the needle, and where it doesn't:

Trust Lab production need	With PingFederate minting the root
Persistent keys with rotation	Better. The key lives in the IdP's encrypted config; `root_key_id` supports rotation
Revocation	Partly. IDs are logged at mint and revoking the authority block cascades; distribution is still open
Authenticated transports	Better. Certificate binding via `cnf_x5t_s256`
Payer consent	Possible. PingFederate's consent and authorization policies run before the exchange
Durable accounting, reconciliation	Unchanged; that's the clearinghouse's job, not the IdP's

Wrapping up

The thing I set out to test was whether an existing enterprise IdP could be the root of trust for Biscuits without giving up anything that makes either side useful. I think the answer is yes:

PingFederate keeps login, MFA, consent and client governance.
The edge keeps speaking OAuth.
One token exchange turns an access token into a capability that services can narrow, delegate and check offline.

Try to break it. Clone the repo, run make up tf-plan tf-apply web, and see if you can make orders-api accept a write it shouldn't. If you work on PingFederate or Biscuit, I'd especially like feedback on the fact vocabulary, the reserved names, and the step-up options. Open an issue on GitHub.

Thanks for reading the series.

Configuring PingFederate token exchange with Terraform, and testing it end to end

DarkEdges — Sun, 04 Oct 2026 11:51:35 +0000

Repo: darkedges/pf12.3-biscuit-datalog-tokens

Part 2 built a token generator plugin. On its own it does nothing: PingFederate needs a login, an access token manager, a client, a processor policy, a generator instance, a generator group and a mapping between them before a single Biscuit comes out.

This part configures all of that with Terraform, then runs the full flow in a browser: log in, exchange, call an API, get refused, and see why.

1. The stack

docker-compose.yaml runs two things:

pingfederate: PingFederate 12.3.3 with the getting-started server profile, built from the multi-stage Dockerfile from Part 2, so the plugin is already deployed.
terraform: a hashicorp/terraform container in a tools profile. It reaches the admin API at https://pingfederate:9999 on the compose network, so you don't need Terraform on your machine.

Everything runs through make:

make up          # build the image (plugin compiled and tested inside Docker) and start PingFederate
make tf-plan     # generate the Biscuit root key once, init, plan → terraform/tfplan
make tf-apply    # apply the saved plan
make tf-creds    # generated passwords for alice and bob, and the client secret
make web         # orders-api + the demo web app, prints "Ready" when 8090 is listening

2. What Terraform creates

Seventeen resources take a blank PingFederate to a working token exchange:

Piece	Resource
Demo users `alice` and `bob`, with generated passwords	`random_password` + `pingfederate_password_credential_validator`
HTML form login	`pingfederate_idp_adapter` + `pingfederate_oauth_idp_adapter_mapping`
Scopes `orders:read`, `orders:write`	`pingfederate_oauth_server_settings`
JWT access tokens carrying `username`	`pingfederate_oauth_access_token_manager` + `pingfederate_oauth_access_token_mapping`
Client `orders-web`: authorization code, refresh token, token exchange	`pingfederate_oauth_client`
Validates the incoming JWT	`pingfederate_idp_token_processor`
Picks `subject`, `client_id`, `scope`	`pingfederate_oauth_token_exchange_processor_policy`
The Biscuit generator instance	`restapi_object` → `/sp/tokenGenerators`
Routes the Biscuit token type to it	`restapi_object` → `/oauth/tokenExchange/generator/groups`
Policy attributes → generator contract	`pingfederate_oauth_token_exchange_token_generator_mapping`
Makes that group the default	`pingfederate_oauth_token_exchange_generator_settings`

The token exchange pipeline from Part 1 maps directly onto the last six rows.

Validating the subject token

The processor is PingFederate's built-in BearerAccessTokenTokenProcessor, pointed at the same access token manager that issued the JWT. PingFederate validates its own tokens, with no JWKS plumbing:

resource "pingfederate_idp_token_processor" "access_token" {
  processor_id = "biscuitAccessTokenProcessor"
  plugin_descriptor_ref = {
    id = "org.sourceid.wstrust.processor.oauth.BearerAccessTokenTokenProcessor"
  }
  configuration = {
    fields = [
      { name = "Access Token Manager", value = pingfederate_oauth_access_token_manager.jwt.manager_id },
      { name = "Scope value as single string", value = "true" },
    ]
  }
  # core: aud, authorization_details, client_id, expires_at, iss, scope; extended: username
}

The processor's core contract has client_id and scope, but not the user. The user arrives as the extended attribute username, which has to match the access token manager's contract.

The processor policy: what PingFederate lets through

This is the governance point from Part 1. The policy chooses which attributes go to the generator. This is where you'd add issuance criteria, such as "only this client" or "only if the token has this scope":

resource "pingfederate_oauth_token_exchange_processor_policy" "biscuit" {
  policy_id = "biscuitExchange"
  name      = "Access token to Biscuit"
  # "subject" is a built-in core attribute of every processor policy.
  attribute_contract = {
    extended_attributes = [{ name = "client_id" }, { name = "scope" }]
  }
  processor_mappings = [{
    subject_token_type      = "urn:ietf:params:oauth:token-type:access_token"
    subject_token_processor = { id = pingfederate_idp_token_processor.access_token.processor_id }
    attribute_contract_fulfillment = {
      subject   = { source = { type = "SUBJECT_TOKEN" }, value = "username" }
      client_id = { source = { type = "SUBJECT_TOKEN" }, value = "client_id" }
      scope     = { source = { type = "SUBJECT_TOKEN" }, value = "scope" }
    }
  }]
}

(The comment is there because I tried to declare subject myself, and the provider refuses: it's read-only.)

3. The provider gap: `restapi` for two objects

The PingFederate Terraform provider (1.10.0, the latest at the time of writing) has no resource for SP token generators or token exchange generator groups. Those are exactly the two objects this project needs.

Rather than shell out to scripts, I used the generic Mastercard/restapi provider against the admin API. Those objects still go through plan, apply and destroy like everything else. Abridged from token_exchange.tf, where the literals are variables:

resource "restapi_object" "biscuit_generator" {
  path      = "/sp/tokenGenerators"
  object_id = "biscuit"
  data = jsonencode({
    id                  = "biscuit"
    name                = "Biscuit token generator"
    pluginDescriptorRef = { id = "com.darkedges.pingfederate.biscuit.BiscuitTokenGenerator" }
    configuration = { fields = [
      { name = "Root Private Key", value = var.biscuit_root_private_key },
      { name = "Root Key ID", value = "1" },
      { name = "Issuer", value = var.pf_runtime_url },
      { name = "Token Lifetime (seconds)", value = "300" },
      { name = "Audiences", value = "orders-api" },
      { name = "Fact Attributes", value = "subject,client_id,scope" },
    ] }
    attributeContract = {
      coreAttributes     = [{ name = "subject" }]
      extendedAttributes = [{ name = "client_id" }, { name = "scope" }]
    }
  })
  ignore_server_additions = true
  ignore_changes_to       = ["configuration.fields", "attributeContract.extendedAttributes"]
}

Those last two lines took three plans to get right. After the first apply, every plan showed both objects changed, because PingFederate adds things:

location and lastModified fields;
an empty resourceUris list on the group;
the private key returned as encryptedValue instead of value;
extended attributes in a different order.

ignore_server_additions ignores fields the server adds but still detects changes to fields you set. Now a plan straight after an apply says No changes, and editing the Terraform still triggers an update.

The generator group is the piece that makes requested_token_type work:

resource "restapi_object" "biscuit_generator_group" {
  path      = "/oauth/tokenExchange/generator/groups"
  object_id = "biscuit"
  data = jsonencode({
    id   = "biscuit"
    name = "Biscuit"
    generatorMappings = [{
      requestedTokenType = "urn:darkedges:params:oauth:token-type:biscuit"
      tokenGenerator     = { id = restapi_object.biscuit_generator.object_id }
      defaultMapping     = true
    }]
  })
  ignore_server_additions = true
}

4. Smaller things worth knowing

The root key is generated by the plugin itself. make tf-plan runs the plugin jar's keygen inside the PingFederate container, so you don't need a JDK. It writes the result to a git-ignored terraform/biscuit.auto.tfvars. Terraform passes the private key to PingFederate, and the services get the public key.
The JWT symmetric key must be hex. With the access token manager's "Encoding" field left blank, PingFederate expects the HS256 key as hex. My first apply failed with Key with key id 'k1' is not valid hex, and random_bytes.hex fixed it.
Generated secrets live in Terraform state. Demo passwords, the client secret and the JWT key are random_* resources. That's fine for a lab, but in production you'd source them from a vault.
Destroy is clean. make tf-destroy removes all 17 resources in dependency order. PingFederate clears the default generator group reference itself when the group goes.

5. Testing it end to end

With PingFederate running and Terraform applied, make web starts two things: orders-api (Rust, biscuit-auth 6) on port 8091, and the demo web app on port 8090. It prints a "Ready" line only once both are listening.

Open http://localhost:8090 and log in as alice, with the password from make tf-creds. The app runs a standard authorization code flow against PingFederate's HTML form, then does the token exchange. The Token tab shows the Biscuit PingFederate minted:

issuer("https://localhost:9031");
user("alice");
client("orders-web");
scope("orders:read");
scope("orders:write");
check if time($t), $t <= 2026-10-04T11:23:13Z;
check if audience($a), {"orders-api"}.contains($a);

It's labelled authority · minted by PingFederate and marked signature verified against PingFederate's public key.

The HTTP activity tab lists every call in order, each with Request / Response tabs. The request is a runnable curl with Copy curl, and the response is the JSON with Copy response:

#	Call	Result
1	Authorization code → access token (JWT)	`200`, `token_type=Bearer`, `expires_in=3599`
2	Token exchange: JWT → Biscuit	`200`, `issued_token_type=…:biscuit`, `token_type=N_A`, `expires_in=299`
3	`GET /orders/123` with the Biscuit	`200`, `{"allowed": true, "user": "alice"}`
4	`POST /orders/123` with the Biscuit	`403`, `write requires amr("mfa") signed by ed25519/59c0… (step-up)`

Call 3 shows the point of the whole design: orders-api didn't call PingFederate. It verified the signature with the public key, added facts about the request (operation("read"), resource("/orders/123"), audience("orders-api"), the time), and evaluated its policy locally.

Call 4 is the cliffhanger. Alice has orders:write, but the policy also wants proof of MFA, as a block signed by a key PingFederate controls. That's Part 4.

Without a browser

The same flow runs from the command line, which is handy for CI or for seeing the raw calls:

make auto-login LOGIN_USER=bob   # fills in PingFederate's HTML form with curl
make exchange                    # JWT → Biscuit, prints its Datalog
make api-pf                      # orders-api in another terminal
make call                        # GET → 200, POST → 403

In Part 4 we unlock that write: a step-up MFA attestation appended as a third-party block, then attenuation and sealing in the demo app. Then the honest part: what this design doesn't solve yet, and the library gap that stops PingFederate from being the attestor today.

Building a PingFederate token generator that mints Biscuits

DarkEdges — Sun, 04 Oct 2026 11:51:23 +0000

Repo: darkedges/pf12.3-biscuit-datalog-tokens, plugin source in pf-biscuit-generator/

Part 1 argued for a hybrid: PingFederate issues JWTs at the edge, and token exchange turns them into Biscuits for everything inside. This part builds the one piece PingFederate doesn't ship, a token generator that mints a Biscuit.

It's a few hundred lines of Java. Most of the interesting decisions aren't in the Java, though. They're about what you let into the authority block.

1. The SDK contract

PingFederate's token exchange calls token generators through the same SDK interface its WS-Trust STS uses, org.sourceid.wstrust.plugin.generate.TokenGenerator. A generator does three things:

describes itself: its name, admin UI fields, the token type it produces, and its attribute contract;
receives configuration when an admin saves the instance;
generates a token from a map of attributes.

The descriptor is where the token type lives. That URN is what clients send as requested_token_type:

public static final String TOKEN_TYPE = "urn:darkedges:params:oauth:token-type:biscuit";

descriptor = new TokenPluginDescriptor(NAME, this, gui, TOKEN_TYPE, Set.of("subject"));
descriptor.setSupportsExtendedContract(true);

The core contract is just subject. The extended contract lets an admin add client_id, scope, group, amr or anything else the processor policy provides, without changing code.

The admin UI exposes six fields:

Field	Becomes
Root Private Key	The Ed25519 key that signs the authority block (an encrypted field)
Root Key ID	`root_key_id` in the token, for key rotation
Issuer	`issuer("…")`
Token Lifetime (seconds)	`check if time($t), $t <= <now + lifetime>`
Audiences	`check if audience($a), {…}.contains($a)`
Fact Attributes	Which contract attributes become facts

The plugin uses biscuit-java 4.0.1, the JVM implementation of Biscuit.

2. Attributes in, facts out, and never as strings

This is the first design rule, and it's easy to get wrong. The tempting implementation is string building:

// DON'T
token.add_authority_fact("user(\"" + subject + "\")");

If a subject ever contains alice"); scope("orders:admin, you've just let an attribute value write Datalog. In an IdP, attribute values come from directories, upstream federation partners and user-editable profiles. They aren't safe input.

So every value goes through biscuit-java's builder API as a string term. A term is data and is never parsed as Datalog:

token.set_context("pingfederate:token-exchange");
token.add_authority_fact(fact("issuer", List.of(string(issuer))));

for (Map.Entry<String, String> e : factAttributes.entrySet())
{
    for (String value : values(attributes, e.getKey()))
    {
        token.add_authority_fact(fact(e.getValue(), List.of(string(value))));
    }
}

The checks are built the same way: predicates, variables and expressions, not strings. Here's the expiry:

// check if time($t), $t <= <expiresAt>
token.add_authority_check(check(
        pred("time", List.of(var("t"))),
        new Expression.Binary(Expression.Op.LessOrEqual,
                new Expression.Value(var("t")),
                new Expression.Value(date(Date.from(expiresAt))))));

There's a unit test that mints a token for the subject mallory"); scope("orders:write. It checks that the result contains exactly one scope fact and that a write is still refused.

A small but useful detail: OAuth's scope arrives as one space-separated string. The minter splits it into one scope("…") fact per scope, so Datalog policies can match individual scopes.

3. The fact names a minter must refuse

The second design rule is subtler, and I think it's the most important thing in this article.

A Biscuit authorizer combines facts from two places:

the token, whose authority block is trusted;
the service itself, which adds ambient facts describing the request it's handling: time(...), operation("read"), resource("/orders/123"), audience("orders-api").

Then it runs a policy like:

allow if scope("orders:read"), operation("read");
allow if scope("orders:write"), operation("write"), amr("mfa") trusting authority, ed25519/<attestation key>;
deny if true;

By default, the authorizer trusts authority-block facts exactly as much as its own. So if any PingFederate attribute were ever mapped to a fact called operation, a token could carry operation("write") and satisfy the write rule on a read request. The token would be forging facts about the request.

So the minter has a reserved list, and refuses to start if an admin maps an attribute onto any of these names:

public static final Set<String> RESERVED_FACTS = Set.of(
        "time", "operation", "resource", "audience", "tls_client_cert_sha256", "issuer", "hop");

issuer is on the list because the plugin sets it from configuration. hop is reserved for services to tag delegation hops.

The broader lesson: the fact vocabulary is a contract between your IdP and every service that verifies its tokens. Which names the IdP asserts (user, client, scope, group, amr) and which names services assert (time, operation, resource) must never overlap. Write it down and version it.

4. Checks that bind the token

Beyond expiry and audience, the minter supports one more check: certificate binding, the Biscuit equivalent of RFC 8705's cnf.x5t#S256. If the processor policy supplies a cnf_x5t_s256 attribute, the authority block gets:

check if tls_client_cert_sha256($c), $c == "<thumbprint>";

The service adds tls_client_cert_sha256(...) from its mTLS handshake. A stolen token presented over a different client certificate fails the check. The standalone demo covers all three cases: no certificate, the wrong certificate, and the right one.

5. Getting the output right: what I disassembled

A generator returns a SecurityToken. For anything that isn't SAML, that means a BinarySecurityToken, an XML-era type with "encoded data" and an encoding type. The SDK doesn't document what the OAuth token exchange endpoint does with it. Would PingFederate base64 the data again? Decode it? Wrap it?

So I disassembled the class that builds the token exchange response in PingFederate 12.3.3, TokenGeneratorOutputGenerationStrategy, with javap -c. It does three things:

returns BinarySecurityToken.getEncodedData() verbatim as access_token;
sets token_type to N_A;
computes expires_in from getExpiryDate() if one is set.

That's good news: the Biscuit's native base64url serialization passes through untouched, and verifiers can read it directly. The generator sets the encoding type and the expiry date so expires_in is correct:

BinarySecurityToken bst = new BinarySecurityToken(XmlIDUtil.createID(), TOKEN_TYPE);
bst.setEncodingType(BinarySecurityToken.BASE64_URL_ENCODING_TYPE);
bst.setEncodedData(minted.token());
bst.setCreatedDate(new Date());
bst.setExpiryDate(Date.from(minted.expiresAt()));
return bst;

The same mint also logs the authority block's revocation ID along with the subject. Revoking that ID revokes the token and every narrowed copy made from it, because each appended block chains from the authority block. Logging it at mint time is what makes revocation possible later.

6. Keys and rotation

The root key is Ed25519, stored in an encrypted configuration field, so PingFederate replicates it across a cluster like any other secret. The plugin's jar is also a CLI, so you can generate the key with the same code that uses it:

java -jar pf.plugins.biscuit-token-generator.jar keygen
# private=49309A02…
# public=ed25519/0155b736…

The Root Key ID goes into each token. Verifiers look up the public key by that ID, which is how you rotate: publish the new public key, switch the generator to the new key ID, then retire the old key once no unexpired tokens use it.

One biscuit-java detail cost me a test run: Biscuit.from_b64url(token, publicKey) drops root_key_id. The overload that takes a KeyDelegate receives the ID, which is the one you want for rotation anyway.

7. Packaging: shading, and building against the image

Two practical problems:

Classpath clashes. PingFederate ships its own vavr (0.10.2) and protobuf, and biscuit-java needs slightly different versions. The plugin is a shaded jar with every dependency relocated under com.darkedges.pingfederate.biscuit.shaded.*, so it can't collide with the server's classpath.

Where the SDK comes from. The SDK jars aren't on Maven Central, so the Dockerfile takes them from the PingFederate image itself. A build stage copies /opt/server/server/default/lib out of pingidentity/pingfederate:2511-12.3.3, compiles and tests the plugin on JDK 11, and the final stage copies the jar into deploy/. The plugin always compiles against exactly the version it runs on.

There's one runtime gotcha with the Ping Docker images. The server runs from /opt/out/instance, and the startup hooks copy /opt/server into it only on a fresh volume. Rebuild the image while the volume persists and you're still running the old jar. The repo's make redeploy wipes the volume for that reason.

8. Tests and an interop check

The plugin has two test classes:

BiscuitMinterTest: authority facts, expiry, wrong audience, wrong key, attenuation, injection, the reserved-name refusal, and certificate binding.
BiscuitTokenGeneratorTest: drives the plugin through PingFederate's own SDK types, Configuration, TokenContext, AttributeValue and BinarySecurityToken, and verifies the output.

Two findings from writing them:

biscuit-java's default authorizer budget is 5 ms. A cold JVM blows through that on the first evaluation and throws a Timeout. Pass RunLimits explicitly.
The SDK test needs PingFederate internals. XmlIDUtil.createID() starts PingFederate's internal registry, which uses reflection that JDK 17+ blocks without --add-opens. I run the tests on JDK 11, as the Docker build does.

The interop check matters most: tokens minted by biscuit-java in PingFederate verify in biscuit-auth 6 (Rust) using only the public key. That's what Part 3's resource server uses.

The plugin is half the story. In Part 3 we configure PingFederate around it with Terraform: the login, the JWT token manager, the processor policy and the generator mapping. Two resources need the generic restapi provider, because the PingFederate provider has no resource for token generators. Then we test it end to end in a browser.

Who mints the first Biscuit? PingFederate, token exchange and a hybrid model

DarkEdges — Sun, 04 Oct 2026 11:51:04 +0000

Repo: darkedges/pf12.3-biscuit-datalog-tokens

In the Biscuit Trust Lab series, Alice asked PlannerCo to do some work. PlannerCo split it between ResearchCo and ComputeCo, ResearchCo passed part of it to SearchCo, and every hop narrowed the token it was handed. Nobody called home to ask permission, and nobody could widen what they'd been given.

There was one thing that series never answered: where did Alice's first token come from? In the lab, the platform minted it. In a real company, Alice doesn't exist until an identity provider says she does. She logs in with a password and probably MFA, against a directory the security team runs, through an IdP that every application already trusts.

This series is about closing that gap with PingFederate. Over four parts:

Who mints the first Biscuit? Why a hybrid of JWTs and Biscuits works, and how OAuth token exchange joins them (this article).
Building a PingFederate token generator that mints Biscuits: the SDK plugin, the Datalog design rules, and what I had to disassemble to get the output right.
Configuring the exchange with Terraform and testing it end to end: 17 resources, two of which the provider can't manage, and a demo app that shows every request and response.
Step-up MFA, attenuation, and what's honestly not done, including a library gap that stops PingFederate from being the MFA attestor today.

Two token models, two strengths

If you've read the Trust Lab, you know what Biscuits are good at. If you've run an IdP, you know what JWTs are good at. The problem is that they're good at different things:

	JWT access token from your IdP	Biscuit
Who can narrow it	Only the issuer, by minting a new one	Anyone holding it, offline, by appending a block
Can a holder widen it?	No (it's signed)	No (appended blocks can only add checks)
Authorization logic	Claims, interpreted by each service's code	Datalog policy, evaluated with the token's facts
Delegation across hops	Token exchange back at the IdP for each hop	Append and pass on
Who understands it	Everything: gateways, PingAccess, API managers, every OAuth library	Biscuit libraries only
Login, MFA, consent, client registration	Built into the IdP	Not its job

Neither column wins. JWTs are what the outside world speaks: browsers, mobile apps, API gateways, and the edge of your network all expect OAuth. Biscuits are better once the token is inside, moving between services or companies that need to narrow it as it goes.

The hybrid: JWTs at the edge, Biscuits inside

So don't choose. Let each format do what it's good at, and put a well-defined seam between them:

                north-south: standard OAuth                       east-west: capabilities
 Browser ──login──▶ PingFederate ──JWT──▶ client / gateway ──Biscuit──▶ service A ──narrowed Biscuit──▶ service B
                         ▲                     │
                         └── token exchange ───┘
                             (JWT in, Biscuit out)

The seam is OAuth 2.0 Token Exchange, RFC 8693. The client presents the JWT it already has as the subject_token and asks for a different kind of token back:

curl -k -X POST 'https://localhost:9031/as/token.oauth2' \
  -u "orders-web:$CLIENT_SECRET" \
  --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
  --data-urlencode "subject_token=$JWT" \
  --data-urlencode 'subject_token_type=urn:ietf:params:oauth:token-type:access_token' \
  --data-urlencode 'requested_token_type=urn:darkedges:params:oauth:token-type:biscuit'

And PingFederate answers:

{
  "access_token": "CAESiwMKoAIKBmlzc3VlcgoWaHR0cHM6Ly9sb2NhbGhvc3Q6OTAzMQoFYWxp…",
  "issued_token_type": "urn:darkedges:params:oauth:token-type:biscuit",
  "token_type": "N_A",
  "expires_in": 299
}

That access_token is a Biscuit, signed with an Ed25519 key that PingFederate holds. token_type: N_A is RFC 8693's way of saying "this isn't an OAuth access token in the usual sense". The requested token type is a URN I made up. RFC 8693 lets you define your own, and PingFederate routes on it.

Here's what's inside, its authority block:

issuer("https://localhost:9031");
user("alice");
client("orders-web");
scope("orders:read");
scope("orders:write");
check if time($t), $t <= 2026-10-04T11:23:13Z;
check if audience($a), {"orders-api"}.contains($a);

Everything in it came from PingFederate: the user it authenticated, the client it registered, the scopes it granted, the lifetime and audience policy it enforces. From here on, the Trust Lab mechanics apply unchanged: append a block, narrow it, pass it on.

Why this works as a hybrid

It's tempting to see token exchange as a workaround. I think it's the right design, for five reasons.

1. PingFederate stays the authority. Login, MFA, account lockout, consent, client registration, scope policy and auditing all stay where they are. The Biscuit doesn't replace any of it. It carries the result of it, signed by the same IdP that produced it.

2. Nothing at the edge has to change. Browsers, mobile apps, PingAccess and your API gateway keep speaking standard OAuth. Only the components that want offline narrowing ever see a Biscuit.

3. PingFederate decides what goes into the root token. Token exchange runs through a processor policy in PingFederate. It validates the incoming JWT, picks the attributes it trusts (subject, client, scope), and can refuse to issue at all. That's the hook for central governance: the set of facts in the authority block is controlled in one place, not by whoever builds a client.

4. Below the seam, delegation stops costing a round trip. With JWTs only, each hop that wants a narrower token has to go back to the IdP and exchange again. With a Biscuit, the hop appends check if operation("read") and moves on. PingFederate is consulted once, at the seam.

5. It answers the Trust Lab's production list. Part 4 of the Trust Lab ended with what a production version would need, including persistent keys with rotation and revocation. An IdP already has key management. Here the Biscuit carries a root_key_id so verifiers can pick the right key during rotation, and every mint logs the authority block's revocation ID.

Bridging back to the Trust Lab

Put Alice's company IdP in front of the Trust Lab scenario and the chain becomes:

Alice logs in to PingFederate at her company and gets a JWT, like any other OAuth app.
PlannerCo, a registered OAuth client, exchanges that JWT for a Biscuit. The authority block says user("alice"), client("plannerco"), and the scopes Alice's company allows.
PlannerCo attenuates and delegates to ResearchCo and ComputeCo, exactly as in Part 2 of the Trust Lab.
Each receiver checks the chain with PingFederate's public key and its own policy, like the receiver's authorizer in Part 3. None of them needs to call PingFederate.

The hands-on parts of this series use a smaller example from the repository so you can run it: users alice and bob, a client called orders-web, and an orders-api that lets you read with orders:read but only write with orders:write plus an MFA attestation. The mechanics are the same.

What's inside PingFederate

Token exchange in PingFederate is a small pipeline. It's worth seeing the parts before we build one of them:

subject_token (JWT)
   │
   ▼
Token processor ............ validates the JWT with the access token manager that issued it
   │
   ▼
Processor policy ........... picks subject, client_id, scope; can reject
   │
   ▼
Generator mapping .......... maps policy attributes onto the generator's contract
   │
   ▼
Token generator ............ ← this is the plugin: turns attributes into a Biscuit
   ▲
Generator group ............ routes requested_token_type=…:biscuit to the generator

Everything except the generator ships with PingFederate. The generator is a Java plugin written against the PingFederate SDK's TokenGenerator interface, and that's the subject of the next part.

What this doesn't do

I'd rather say this up front:

PingFederate can mint the root token, but it can't yet sign the MFA attestation block. The Java Biscuit library is a format version behind the Rust one for third-party blocks. Part 4 covers this and the workaround.
PingFederate can't introspect a narrowed Biscuit meaningfully. It can check the signature, but whether a request is authorized depends on facts only the receiving service has.
Off-the-shelf gateways don't understand Biscuits. That's why the hybrid keeps JWTs at the edge.

In Part 2 we build the token generator: the SDK interface, how attributes become Datalog facts without injection, which fact names a minter must refuse to issue, and the detail I only found by disassembling PingFederate's token exchange code.

If you want to jump ahead, the README gets you from git clone to a PingFederate-minted Biscuit in about ten commands.

Credits without a mutable token: reservations, idempotency and receipts

DarkEdges — Sun, 04 Oct 2026 06:23:20 +0000

The first three parts of this series covered authority: who may do what, on whose behalf, and who decides. This last part covers money.

darkedges / biscuit-trust-lab

An interactive Cloudflare Pages playground for exploring Biscuit delegation, Datalog authorization, trust between independent operators, and shared clearinghouse billing.

Relay — Biscuit network lab

A Cloudflare Pages demonstration of independent operators accepting delegated tasks, applying local Datalog policies, and billing the original payer through a shared clearinghouse. Biscuit tokens and Ed25519 signatures are real; operators, work, and credits are simulated.

Live demo: biscuits.demos.darkedges.com

Run locally

Use Node.js 22 or newer and pnpm 11:

pnpm install
pnpm dev

Open http://127.0.0.1:8795. On this development computer, pnpm dev:lan binds to 10.0.0.35:8795 for other devices on the same network. Change that address in package.json if your computer has a different LAN IP. The interface starts a demo run automatically.

On Windows, ./start.ps1 starts the Pages preview and installs dependencies if needed. Use ./start.ps1 -BindAddress 10.0.0.35 for LAN access.

Deploy to Cloudflare Pages

The Pages output directory is web, as declared in wrangler.jsonc. web/_worker.js handles /api/run and /api/health and forwards other requests to Pages assets. Dependencies, including Biscuit WebAssembly, are bundled…

View on GitHub

Why the balance isn't in the token

It's tempting to put budget(100) in the Biscuit and have each hop append spent(5). That doesn't work:

Tokens are immutable and copyable. Two holders of the same token can each spend "the remaining 95". Nothing in the token stops concurrent use.
Appended blocks can't change facts. A later block can't reduce an earlier balance. It can only add checks.
Spending is shared state. Search and compute run in parallel under the same request, so the shared budget has to live in one place.

So the token carries who pays and for which request (payer, request_id). A clearinghouse holds the ledger for that request. Authorization is local, and accounting is coordinated. That's the line in the footer of the demo.

Reserve → execute → settle (or release)

Each billable call goes through the same lifecycle:

The operator authorizes the call (part 3).
The clearinghouse authorizes it again, then reserves credits and returns a signed grant.
The operator does the work.
The operator signs a completion receipt bound to that grant, and the clearinghouse settles.
If the work fails, the clearinghouse releases the reservation instead.

Reserved and settled credits both count against the budget, so promised money can't be promised twice.

Serializing reservations in single-threaded JavaScript

JavaScript is single-threaded, so it might seem that a race can't happen. But reserveLocked contains awaits (SHA-256 fingerprinting and signing the grant) between reading the used total and recording the reservation. Two reservations can interleave at those points and both see the same available balance.

The lab chains reservations onto a promise queue:

reserve(payload) {
  const pending = this.reservationQueue.then(() => this.reserveLocked(payload));
  this.reservationQueue = pending.catch(() => {});
  return pending;
}

async reserveLocked(payload) {
  // ... payer/request/amount validation, idempotency (below)
  const used = [...this.operations.values()]
    .filter(row => row.status !== 'released')
    .reduce((total, row) => total + row.amount, 0);
  if (used + payload.amount > this.budget) throw new InsufficientCredits(payload.amount, this.budget - used);
  const grant = await this.identity.sign({ operation_id: payload.operation_id, request_id: this.requestId,
    payer: this.payer, provider: payload.provider, amount: payload.amount, fingerprint,
    available_before: this.budget - used });
  this.operations.set(payload.operation_id, { /* ... */ status: 'reserved', grant });
  return { grant, duplicate: false, status: 'reserved' };
}

.catch(() => {}) on the queue tail means one rejected reservation doesn't block the ones after it. The caller still receives the rejection through pending.

The competing-reservations scenario

With a 100-credit budget, research settles 5. Search and compute then each ask for 60 concurrently:

await Promise.all([
  this.execute(searchToken, [researchProof, searchProof], 'search', 60),
  this.execute(computeToken, [computeProof], 'compute', 60),
]);

Whichever reaches the queue first gets its 60. The other sees Insufficient credits: 60 requested, 35 available and is denied after passing Biscuit authorization. The decision view says so explicitly: "Biscuit allowed the call; the clearinghouse denied its credit reservation." Raise the budget to 125 and both succeed.

Idempotency: retries don't double-charge

Networks retry. The clearinghouse keys reservations by operation_id and fingerprints the full signed payload:

const fingerprint = await digest(payload);
const previous = this.operations.get(payload.operation_id);
if (previous) {
  if (previous.fingerprint !== fingerprint)
    throw new Rejected('Idempotency conflict: operation ID reused with different billing details');
  if (previous.status === 'released')
    throw new Rejected('This operation was released; create a new operation ID');
  return { grant: previous.grant, duplicate: true, status: previous.status };
}

There are three cases:

Same ID, same details. Return the existing grant. If it's already settled, the operator returns the existing result, with no new work and no new charge.
Same ID, different details. Conflict. Someone is trying to reuse an operation ID to change the amount, payer or action.
Same ID after release. Refuse. A failed operation needs a fresh ID, so a stale retry can't revive it.

The Retry scenario sends the search call twice. The ledger shows 3 operations and 40 credits settled, not 50.

Receipts: settle only what the provider claims it completed

Settlement needs evidence from the provider, bound to the specific reservation:

const receipt = await this.identities[provider].sign({
  operation_id: payload.operation_id, provider,
  grant_hash: await digest(grant), result: 'completed' });

async settle(receipt) {
  const provider = receipt.payload.provider;
  const proof = await verify(this.identities[provider], receipt);
  if (proof.result !== 'completed') throw new Rejected('Receipt does not prove completion');
  const row = this.operations.get(proof.operation_id);
  if (!row || row.provider !== provider || proof.grant_hash !== await digest(row.grant))
    throw new Rejected('Receipt is not bound to this provider and reservation');
  if (row.status === 'released') throw new Rejected('Cannot settle a released reservation');
  row.status = 'settled'; row.receipt = receipt;
}

A receipt from the wrong provider, for another reservation, or for a released reservation is rejected.

Be clear about what a receipt proves. It's the provider's signed claim that it completed the work. It doesn't prove the work was any good. That's a matter for disputes and reputation, not for cryptography.

The operation-failure scenario

Search reserves 10 credits, and then its simulated execution fails. The clearinghouse releases the reservation. Settled is 30, available is 70, and replaying the timeline shows reserved rising to 10 and falling back to 0. A test checks that every replay snapshot balances:

for (const event of run.events) {
  const ledger = event.snapshot.ledger;
  assert.equal(ledger.available + ledger.settled + ledger.reserved, ledger.budget);
}

Running it on Cloudflare Pages

The lab deploys as a single Pages project. web/_worker.js (advanced mode) handles /api/run and /api/health and passes everything else to static assets:

if (path === '/api/run' && request.method === 'POST') {
  const body = await request.text();
  if (body.length > 20_000) return Response.json({ error: 'Request is too large' }, { status: 413 });
  return Response.json(await runDemo(JSON.parse(body)));
}

Each request creates fresh keys, a new request ID and a request-local ledger. That keeps the demo stateless. It also means nothing persists between requests or across Cloudflare locations, which is fine for a lab and wrong for real money.

pnpm install
pnpm check          # node --test: real Biscuit decisions, concurrency, idempotency, release
pnpm run deploy     # wrangler pages deploy web

What a production version would need

The lab deliberately stops short of being a payment system. To make it real you would need:

Durable, centralized accounting. The serialized queue would become a transactional store, for example a Durable Object or a database row lock for each request.
Persistent issuer and operator keys, with rotation and published key sets, instead of fresh keys on every run.
Authenticated transports between operators, not in-process function calls.
Payer consent and quotes before a reservation, not a fixed price list.
Revocation. Biscuit revocation identifiers make this possible, but someone has to publish and check the list.
Reservation expiry, so abandoned reservations free their credits.
Reconciliation and dispute handling, because a receipt is a claim, not proof of quality.

Wrapping up

Across the four parts, we covered:

A Biscuit root grant whose authority block binds requester, payer, request and rights, and whose checks every use must pass.
Attenuation at each hop, narrowing what downstream operators can do without contacting the issuer.
Signed delegation envelopes that fill in what Biscuit doesn't record: who delegated to whom.
A local Datalog policy at each receiver, combining issuer facts, verified call facts and its own trust settings.
A clearinghouse that keeps money out of the token, with serialized reservations, idempotent retries, releases and receipt-bound settlement.

Try to break it. Change the trust graph, swap payers, squeeze the budget, and watch the Debug tab. If you find a way to get SearchCo to do work it shouldn't, please open an issue.

Code: github.com/darkedges/biscuit-trust-lab · Demo: biscuits.demos.darkedges.com

Local policy, shared facts: the receiver's Datalog authorizer

DarkEdges — Sun, 04 Oct 2026 06:23:03 +0000

So far in this series we've minted a root grant, narrowed it at each hop, and wrapped every delegation in a signed envelope. All of that tells the receiver what was delegated and by whom. It doesn't decide whether the receiver should do the work. That decision belongs to the receiver alone.

In Biscuit Trust Lab, each operator makes that decision with its own Biscuit authorizer.

darkedges / biscuit-trust-lab

An interactive Cloudflare Pages playground for exploring Biscuit delegation, Datalog authorization, trust between independent operators, and shared clearinghouse billing.

Relay — Biscuit network lab

Live demo: biscuits.demos.darkedges.com

Run locally

Use Node.js 22 or newer and pnpm 11:

pnpm install
pnpm dev

On Windows, ./start.ps1 starts the Pages preview and installs dependencies if needed. Use ./start.ps1 -BindAddress 10.0.0.35 for LAN access.

Deploy to Cloudflare Pages

View on GitHub

One policy, four sources of facts

Every operator runs the same policy:

allow if requester($r), accepts_requester($r),
    caller($c), service($s), trusts_caller($c, $s),
    payer($p), billing_payer($p),
    request_id($id), current_request($id),
    action($a), right($a), offers($a);

It's the same rule everywhere, but each operator evaluates it against different facts. Every predicate has a clear origin:

Fact	Comes from	Meaning
`requester`, `payer`, `request_id`, `right`	Biscuit authority block (signed by the clearinghouse)	What the original grant says
`caller`, `billing_payer`, `current_request`, `action`	Verified call (caller's Ed25519 signature checked)	What this call asks for
`service`	Receiving operator	Who I am
`accepts_requester`, `trusts_caller`, `offers`	Receiver's local policy	Whom I serve, whom I trust, what I do

Restrictions appended during delegation don't add facts. They add check if rules that must also pass (see part 2).

The policy reads almost like English. Allow the call if the original requester is someone I accept, the caller is someone I trust to send me work, the payer on the call is the payer on the grant, the call belongs to the granted request, and the action was granted and is something I offer.

Building the authorizer

Here's how the receiver assembles the authorizer in lib/relay.js:

const builder = new AuthorizerBuilder();
builder.addCode(POLICY);
// The policy is fixed source code. All added values come from validated names or JSON-quoted strings.
builder.addCode(`caller(${JSON.stringify(caller)}); service(${JSON.stringify(provider)});
  billing_payer(${JSON.stringify(payload.payer)});
  current_request(${JSON.stringify(payload.request_id)}); action(${JSON.stringify(payload.action)});
  offers(${JSON.stringify(provider)});`);
builder.merge(authorizer`time(${new Date()});`);
for (const who of this.accepts[provider]) builder.addCode(`accepts_requester(${JSON.stringify(who)});`);
for (const [source, target] of this.edges)
  if (target === provider) builder.addCode(`trusts_caller(${JSON.stringify(source)}, ${JSON.stringify(target)});`);

const built = builder.buildAuthenticated(verified);
built.authorizeWithLimits({ max_facts: 1000, max_iterations: 100, max_time_micro: 250000 });

A few things to notice:

buildAuthenticated(verified) only runs on a token that has already passed root-key verification and the chain checks from part 2.
authorizeWithLimits caps facts, iterations and time. Every authorizer that evaluates input from outside should do this.
Trust is local data. trusts_caller and accepts_requester come from each operator's own settings. In the UI you edit them in the trust graph and the requester checkboxes. The token never carries them.
The lab keeps offers simple: each operator offers exactly one action with the same name as itself (SearchCo offers search). A real operator would list its catalogue.

Reading the decision

authorize() returns allow or deny. For teaching, that isn't enough, so the lab asks Biscuit for the facts the authorizer can actually see, using a query rule for each predicate:

const rule = Rule.fromString(`inspected(${vars}) <- ${name}(${vars})`);
built.queryWithLimits(rule, LIMITS).map(fact => fact.terms());

It then compares the facts the call needed with the facts that are present, and labels each with its origin. That table is what you see when you click an operator under Granted permissions. A missing fact shows in red.

One caveat: the table is an explanation. Biscuit's own authorize() result is the only thing that decides permit or deny. The table is rebuilt from queried facts so a human can see why.

How each scenario fails

Change payer

ResearchCo signs a search call that names mallory-org as the payer:

payer("alice-org")            // authority block
billing_payer("mallory-org")  // from the verified call

This fails twice. The policy needs payer($p), billing_payer($p) to unify, and they don't. The root token's own check if billing_payer($p), payer($p) fails too. Even an operator with a careless policy would be stopped by the issuer's check. Search is denied before billing, so the ledger settles 30 instead of 40.

Forbidden operation

SearchCo receives action("delete"). The grant has no right("delete"), and SearchCo doesn't offer delete. ResearchCo's block check if action("search") also fails. Three independent reasons, one denial.

Missing caller trust

Remove the ResearchCo → SearchCo edge in the trust graph and run again. SearchCo's authorizer no longer has trusts_caller("research", "search"), so no policy matches:

{"FailedLogic":{"NoMatchingPolicy":{...}}}

ComputeCo is unaffected, because it trusts PlannerCo, which delegated compute directly. Changing trust at one operator only changes that operator's decisions.

Requester not accepted

Untick Alice for SearchCo, and accepts_requester("alice") disappears from SearchCo's authorizer. If PlannerCo stops accepting Alice, the run stops at ingress. PlannerCo runs a small authorizer of its own before delegating anything:

const planner = authorizer`allow if requester($r), accepts_requester($r);`;

When that fails, no tasks are created at all.

Untrusted issuer

As covered in part 2, a token minted with a different root key fails Biscuit.fromBase64(token, rootPublic) and never reaches Datalog. The decision view shows phase: verification rather than phase: datalog.

Two authorization boundaries

Every billable call is authorized twice: once by the receiving operator, and again on behalf of the clearinghouse before it reserves credits. The Debug tab shows them as separate entries. In the lab, the clearinghouse re-runs the same verification and the receiver's policy. In a real deployment it would hold its own policy, for example "only reserve for providers registered for this payer".

The tests check that a denied call never reaches billing:

const denied = await runDemo({ scenario: 'payer_swap' });
const search = denied.debug.filter(entry => entry.task_index === 1);
assert.equal(search.length, 1, 'Denied operator call must not reach billing');
assert.equal(search[0].outcome, 'denied');

Authorization says the call is allowed. It doesn't say the payer can afford it. In the final part we look at the clearinghouse: why the balance can't live in the token, how reservations stay safe under concurrency, how retries avoid double charging, and what a production version would need.

Code: github.com/darkedges/biscuit-trust-lab · Demo: biscuits.demos.darkedges.com

DEV Community: DarkEdges

Missions, consent and three tokens: how the AAuth person server decides

darkedges / aauth-lab

AAuth (draft-hardt-oauth-aauth-protocol-11) version of the Relay Biscuit lab, with a side-by-side comparison

Relay — AAuth network lab

Run locally

How the AAuth version works

The mission

Consent is a deferred response

Token one: the person token

Token two: the resource token

Token three: the auth token

Three scenarios, three places they fail

Next

Call chaining in AAuth: passing authority on with upstream tokens

darkedges / aauth-lab

AAuth (draft-hardt-oauth-aauth-protocol-11) version of the Relay Biscuit lab, with a side-by-side comparison

Relay — AAuth network lab

Run locally

How the AAuth version works

The problem

upstream_token

What the person server checks

Lifetimes only shrink

A new identifier at every hop

What an intermediary can't do

Caller trust, revisited

The library gap

Next

Paying for it, and checking AAuth against a real person server

darkedges / aauth-lab

AAuth (draft-hardt-oauth-aauth-protocol-11) version of the Relay Biscuit lab, with a side-by-side comparison

Relay — AAuth network lab

Run locally

How the AAuth version works

The clearinghouse is just another resource

Who gets paid?

Reserve, execute, settle

Checking it against the real thing

What a production version would need

Wrapping up

Signed requests and agent identity in AAuth

darkedges / aauth-lab

AAuth (draft-hardt-oauth-aauth-protocol-11) version of the Relay Biscuit lab, with a side-by-side comparison

Relay — AAuth network lab

Run locally

How the AAuth version works

No bearer tokens

The three headers

The agent token

Verifying on the receiving side

Identity-based access

A real agent identity

The catch: identity stops at the first request

Next

Delegating work across companies with AAuth

darkedges / aauth-lab

AAuth (draft-hardt-oauth-aauth-protocol-11) version of the Relay Biscuit lab, with a side-by-side comparison

Relay — AAuth network lab

Run locally

How the AAuth version works

The network

Four roles

One hop, five steps

What the lab adds on top of AAuth

Try it

Run it locally

Coming up in this series

Same lab, different protocol: rebuilding the Biscuit trust lab on AAuth

darkedges / aauth-lab

AAuth (draft-hardt-oauth-aauth-protocol-11) version of the Relay Biscuit lab, with a side-by-side comparison

Relay — AAuth network lab

Run locally

How the AAuth version works

The one-line difference

What one hop looks like

Where each scenario is stopped

What AAuth gives you for free

What it takes away

What it costs

The gotcha in `trusting`

3. The provider gap: `restapi` for two objects