AAuth Supervision

1.1. The Supervisor

The AAuth Protocol concentrates the judgment about what an agent may do at the person server. The PS has the mission the person approved, the agent's justification for each request, the log of what the agent has done, and a channel to the person. It decides whether to issue a person token, whether to issue or federate an auth token, whether an agent may take an action no remote resource governs, and whether a mission proposal, update, or completion is acceptable.¶

The protocol calls the party that makes those decisions the Supervisor, and says that it is the person by default, or a supervision server the PS delegates to ([I-D.hardt-oauth-aauth-protocol], Roles). A person with one agent and a handful of missions answers each question themselves. A person with many agents working around the clock cannot, and an organization that governs its members' agents by policy will not. Supervision is the layer where a standing policy, a rules engine, or a model applying the person's preferences answers on the person's behalf, and asks the person only when it cannot.¶

1.2. What This Document Defines

This document defines the supervision server (SS) role and the protocol between a PS and an SS:¶

• Metadata the SS publishes so a PS can find its endpoints and, when it signs its decisions, its keys.¶
• Connect, by which a PS establishes that a person has chosen this SS.¶
• Supervision requests, which the PS makes for every act it would otherwise put to the person: a mission proposal, update, or completion; a person token, auth token, or permission request.¶
• Supervision decisions, the SS's answers: allow, deny, or ask the person; with clarification of the agent where the SS needs it.¶
• Events, by which the PS tells the SS what it did and what the person decided.¶

A PS that has an SS configured for an agent makes no supervision decision of its own for that agent. It relays, records, and enforces. That is the property this document is built around: the PS is the protocol party, and the SS is the policy party, and the person can change the second without touching the first.¶

1.3. Out of Scope

Revocation of missions, agents, and person tokens is at the PS, by the parties the AAuth Protocol names, and is not a supervision decision. Reading and managing missions by parties other than the owning agent is the PS's mission_control_endpoint, which a companion specification defines. How an SS forms its policy — from rules the person wrote, from what the person decided before, from a model — is the SS's own. This document defines what the SS is asked and what it may answer, not how it decides.¶

7.1. PS Authentication

Every request from the PS to the SS is a signed POST or GET with an HTTP Sig ([I-D.hardt-oauth-aauth-protocol], HTTP Message Signatures Profile). The PS signs as a server, under the jwks_uri Signature-Key scheme ([I-D.hardt-httpbis-signature-key]), naming its issuer and its person server metadata document:¶

Signature-Key: sig=jwks_uri;id="https://ps.example";
    dwk="aauth-person.json";kid="key-1"

The signature MUST cover content-digest and content-type on a request with a body, along with the base components. The SS verifies the signature and takes the PS's identity from it. The SS MUST accept requests only from a PS it has connected for the sub the request names Section 8, and answers others with unsupported_iss or unknown_sub Section 15.¶

The SS never makes a request of the PS Appendix A.4. Everything the SS has to say is a response.¶

7.2. Envelope

Every request body is a JSON object carrying the following members, in addition to those the endpoint defines:¶

• sdi (REQUIRED on a supervision request): The supervision decision identifier, minted by the PS, unique within it Section 7.3.¶
• id (REQUIRED on an event and on a report): An identifier for the event, minted by the PS, unique within it. (iss, id) is the deduplication key, where iss is the PS's verified identity.¶
• iat (REQUIRED): The time of the act at the PS, as seconds since the epoch. On a retried request it is unchanged; the signature's creation time is the time of delivery, not of the act.¶
• sub (REQUIRED): The person, as the directed identifier the PS derives for this SS as audience, by the same rule it derives a sub for any resource ([I-D.hardt-oauth-aauth-protocol], Directed Identifiers). (iss, sub) names one person at one PS, and it is the value the PS connected Section 8.¶
• agent (REQUIRED): The agent's identifier, aauth:local@domain, from the iss and sub of the agent token the agent presented.¶
• mission_s256 (OPTIONAL): The mission the act belongs to, when it names one.¶

Tokens the SS receives inside a request carry other directed identifiers for their own audiences. The SS keys its state on sub and treats identifiers inside forwarded tokens as opaque.¶

7.3. Supervision Decision Identifier

The PS mints an sdi for each supervision request before it makes the request. The same sdi names the request in the PS's log, a retry of the request, the 202 and polls that follow it, the clarification round trips under it, the decision.resolved event that reports what the person decided after an ask, and the person_token.issued or auth_token.issued event for a token the decision allowed. A decision the SS never answered still has an sdi and a complete log entry.¶

7.4. Delivery

The PS delivers requests for one (sub, SS) pair in the order the acts occurred. The PS retries a request that did not receive a terminal response, under the same id or sdi, until it does. The SS deduplicates on (iss, id) and answers a repeated event with 201 and nothing new recorded. A repeated supervision request is answered per Section 9.3.¶

The PS SHOULD send Prefer: wait ([RFC7240]) on every supervision request, and a wait of 30 seconds is RECOMMENDED, so that an SS which decides within it never has to hold a pending record. An SS that cannot answer within the wait returns a deferred response Section 9.1.¶

9.1. Deferred Decisions

An SS that cannot answer within the PS's wait returns a 202 Accepted deferred response ([I-D.hardt-oauth-aauth-protocol], Deferred Responses) with Location and Retry-After. The PS polls the pending URL with a signed GET, signing under the same identity that made the request, and sends no body. The SS MUST verify that identity and MUST answer unknown_pending Section 15 to a poll from any other. The terminal response is the decision, and is signed when the SS signs Section 9.4.¶

The PS polls until it has a decision or until the agent's own pending request at the PS would expire. At that point the PS treats the SS as unavailable for this decision Section 13, and a decision the SS returns afterwards is discarded.¶

9.2. Clarification

An SS that needs the agent to answer a question before it decides returns 202 Accepted with requirement=clarification and a clarification body, exactly as [I-D.hardt-oauth-aauth-protocol], Clarification Required defines it, and with "decision": "clarify" in the body beside "status": "pending", so the four responses read alike:¶

HTTP/1.1 202 Accepted
Location: /pending/q7x2
Retry-After: 0
Cache-Control: no-store
AAuth-Requirement: requirement=clarification
Content-Type: application/json

{
  "sdi": "d-4d2a92",
  "status": "pending",
  "decision": "clarify",
  "clarification": "Is the fare refundable?",
  "timeout": 120
}

The PS relays the question to the agent on its own pending URL, and relays the agent's answer back by a signed POST to the SS's pending URL with an action of clarification_response or updated_request, or a signed DELETE when the agent cancels, per Agent Response to Clarification in that document. The SS then answers with a decision, or with a further clarification within the round limit the PS enforces.¶

Clarification is the SS speaking to the agent through the PS. It is never the SS speaking to the person; that is ask.¶

9.3. Idempotence

A repeated supervision request under an sdi the SS has already answered MUST be answered with the same decision, and where the SS signs, the same signed response. A repeated request under an sdi the SS is still deciding is answered 202 with the same Location. The SS keeps decisions it has given at least until the exp of any token the decision could have allowed, and MAY keep them longer.¶

9.4. Signed Decisions

An SS that publishes a jwks_uri signs the terminal response to every supervision request with an HTTP Message Signature ([RFC9421], Section 2.4 and Section 3), and identifies the signing key with a Signature-Key header on the response under the jwks_uri scheme, naming its issuer and this document's metadata file:¶

HTTP/1.1 200 OK
Content-Type: application/json
Content-Digest: sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=:
Signature-Key: sig=jwks_uri;id="https://ss.example";
    dwk="aauth-supervisor.json";kid="ss-key-1"
Signature-Input: sig=("@status" "content-type" "content-digest"
    "content-digest";req "@authority";req "@path";req);
    created=1790600030;keyid="ss-key-1"
Signature: sig=:...:

{
  "sdi": "d-4d2a91",
  "decision": "allow",
  "scope": "calendar.read"
}

The PS asks for the signature with Accept-Signature ([RFC9421], Section 5.1) on the request, naming the components it wants covered. The signature MUST cover @status, content-type, and content-digest, and SHOULD cover the request's content-digest, @authority, and @path as ;req components, which bind a synchronous decision to the request it answers. A decision returned at a pending URL is a response to the PS's GET, and its ;req components bind it to that poll; the binding to the supervision request is the sdi in the body.¶

The PS MUST verify the signature against the key set the SS's metadata names, and MUST verify that the id in the response's Signature-Key is the issuer of the SS it called. A signed response that fails either check is treated as server_error. An unsigned terminal response from an SS that publishes a jwks_uri is likewise treated as server_error.¶

The PS records the exchange, the request as it signed it and the response as it received it, as the log entry for the decision. The response identifies its signer in itself, so the entry can be verified later without knowing which SS was configured at the time.¶

Editor's Note: [I-D.hardt-httpbis-signature-key] defines Signature-Key as a request header. Its use on a signed response, identifying the responder, is proposed in that document's issue tracker (issue 43) and this section depends on it.¶

10.1. Proposal

The PS forwards the agent's proposal:¶

POST /mission HTTP/1.1
Host: ss.example
Content-Type: application/json
Prefer: wait=30
Accept-Signature: sig=("@status" "content-type" "content-digest"
    "content-digest";req "@authority";req "@path";req)
Signature-Key: sig=jwks_uri;id="https://ps.example";
    dwk="aauth-person.json";kid="key-1"

{
  "sdi": "d-7a1c02",
  "iat": 1790600000,
  "sub": "8f14e45fceea167a5a36dedd4bea2543",
  "agent": "aauth:assistant@agent.example",
  "agent_token": "eyJhbGc...",
  "description": "# Plan Japan Vacation\n\nPlan and book a trip to Japan next month for 2 adults. Budget around $5k. Propose an itinerary before booking.",
  "tools": [
    { "name": "WebSearch", "description": "Search the web" },
    { "name": "BookFlight", "description": "Book flights" }
  ],
  "resources": [
    "https://flights.example",
    "https://hotels.example"
  ]
}

• agent_token (REQUIRED): The agent token the agent presented. It carries whatever posture claims the agent provider put in it, and the SS is the party that evaluates them.¶
• description, tools, resources: As the agent sent them.¶

An allow carries the approved mission, in the members the PS writes into the mission blob:¶

{
  "sdi": "d-7a1c02",
  "decision": "allow",
  "description": "# Plan Japan Vacation\n\nPlan and book a trip to Japan next month for 2 adults. Budget $5,000. Propose an itinerary before booking. Do not book non-refundable fares.",
  "approved_tools": [
    { "name": "WebSearch", "description": "Search the web" }
  ],
  "approved_resources": [
    "https://flights.example",
    "https://hotels.example"
  ],
  "expires_at": "2026-11-01T00:00:00Z"
}

• description (REQUIRED): The approved description. It MAY differ from the proposal.¶
• approved_tools (OPTIONAL): A subset of, or a refinement of, the proposed tools. Absent means none are pre-approved.¶
• approved_resources (OPTIONAL): The resources the PS is to issue person tokens for at approval.¶
• expires_at (OPTIONAL): When the mission expires.¶

The PS assembles the mission blob from these, computes s256, issues the person tokens, records the mission, and returns the approval to the agent, all as the AAuth Protocol defines. The SS refines; the PS builds.¶

An ask MAY carry the same members under proposed. The PS presents them to the person as the supervisor's proposed refinement, the person confirms or edits them, and the PS builds the blob from what the person approved.¶

A deny ends the proposal. The PS returns the denial to the agent with the reason, if any.¶

10.2. Approved

Once the PS has built and recorded the mission, it reports it:¶

{
  "action": "approved",
  "id": "e-9b2f",
  "sdi": "d-7a1c02",
  "iat": 1790600045,
  "sub": "8f14e45fceea167a5a36dedd4bea2543",
  "agent": "aauth:assistant@agent.example",
  "s256": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk",
  "mission": "eyJhZ2VudCI6ImFhdXRoOmFzc2lzdGFudEBhZ2VudC5leGFtcGxlIiwiYXBwcm92..."
}

• sdi: The proposal decision this approval followed from.¶
• s256 and mission: The mission identifier and the blob bytes, as returned to the agent. The SS SHOULD verify that s256 is the digest of mission.¶

The SS answers 201 Created. From here the SS has the exact bytes every later mission_s256 refers to.¶

10.3. Update

The PS forwards the agent's update to {mission_endpoint}/{mission_s256} with action: update and the agent's description. The SS answers with a decision. On allow, the PS accepts the update, appends it to the mission log, and returns its s256 to the agent. On ask, the person reviews it at the PS. The decision MAY narrow nothing: an update is accepted or not.¶

10.4. Completion

The PS forwards the agent's completion proposal with action: completion and the agent's summary. On allow, the PS terminates the mission with reason completed and returns 200 OK to the agent, and then reports the termination Section 10.5. On ask, the person reviews the summary at the PS, and may question the agent through clarification chat there before accepting; the PS reports the outcome in decision.resolved. On deny, the mission stays active and the agent is told.¶

10.5. Terminated

When a mission ends for any reason, the PS reports it with action: terminated and a reason from the termination reasons of [I-D.hardt-oauth-aauth-protocol], Mission Management. The SS answers 201 Created and MAY discard what it holds for the mission.¶

11.1. Person Token

{
  "sdi": "d-4d2a91",
  "act": "person_token",
  "iat": 1790600100,
  "sub": "8f14e45fceea167a5a36dedd4bea2543",
  "agent": "aauth:assistant@agent.example",
  "mission_s256": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk",
  "agent_token": "eyJhbGc...",
  "resource": "https://calendar.example",
  "upstream_token": "eyJhbGc..."
}

• resource (REQUIRED): The resource the person token is for.¶
• agent_token (REQUIRED): The agent token presented.¶
• upstream_token (OPTIONAL): Present when the request is part of a call chain, as the agent sent it.¶
• subagent_token (OPTIONAL): Present when a parent agent requests for a sub-agent, as the agent sent it.¶

An allow MAY carry exp, a time no later than which the issued token's exp MUST be.¶

11.2. Auth Token

{
  "sdi": "d-4d2a92",
  "act": "auth_token",
  "iat": 1790600200,
  "sub": "8f14e45fceea167a5a36dedd4bea2543",
  "agent": "aauth:assistant@agent.example",
  "mission_s256": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk",
  "agent_token": "eyJhbGc...",
  "resource_token": "eyJhbGc...",
  "presented_token": "eyJhbGc...",
  "justification": "I need to read your calendar to find a week with no meetings."
}

• resource_token, presented_token (REQUIRED): As the agent sent them. The resource token carries the resource, the scope it requires, and any budget or other requirement the resource attached.¶
• upstream_token, subagent_token (OPTIONAL): As above.¶
• justification (OPTIONAL): The agent's justification, as it sent it.¶

An allow MAY carry scope, a scope narrower than the resource token requested, and exp. The PS applies them to the auth token it issues, or passes them to the AS it federates with where the AS accepts them; how a PS narrows a federated request is the AS's business and is not treated here.¶

11.3. Permission

{
  "sdi": "d-4d2a93",
  "act": "permission",
  "iat": 1790600300,
  "sub": "8f14e45fceea167a5a36dedd4bea2543",
  "agent": "aauth:assistant@agent.example",
  "mission_s256": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk",
  "action": "SendEmail",
  "description": "Send the proposed itinerary to the user",
  "parameters": {
    "to": "user@example.com",
    "subject": "Japan trip itinerary"
  }
}

• action, description, parameters: As the agent sent them to the PS's permission endpoint.¶

An allow becomes permission: granted to the agent; a deny becomes permission: denied with the reason.¶

12.1. Decision Resolved

After an ask, and after any decision the PS put to the person because the SS was unavailable Section 13, the PS reports what the person decided:¶

{
  "event": "decision.resolved",
  "id": "e-c3d4",
  "sdi": "d-4d2a91",
  "iat": 1790600130,
  "sub": "8f14e45fceea167a5a36dedd4bea2543",
  "agent": "aauth:assistant@agent.example",
  "mission_s256": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk",
  "answer": "allow",
  "apply": "mission",
  "recommendation": "deny",
  "transcript": [
    { "from": "person", "text": "Is this fare refundable?" },
    { "from": "agent", "text": "Yes, fully refundable until 48 hours before departure." }
  ]
}

• answer (REQUIRED): allow or deny, or abandoned when the person did not answer before the request expired.¶
• apply (OPTIONAL): The reach the person gave their answer Section 12.2. Absent means once.¶
• recommendation (OPTIONAL): The recommendation the SS gave in its ask, echoed so the SS can compare its policy with the person's answer.¶
• proposed (OPTIONAL): For a mission proposal, the refinement as the person approved it, after any edits.¶
• transcript (OPTIONAL): The clarification chat between the person and the agent at the PS, if any, in order. Each entry has from, one of person or agent, and text, Markdown.¶
• supervisor (OPTIONAL): unavailable when the PS put the act to the person because it could not reach the SS. There is no recommendation in that case.¶
• reason (OPTIONAL): A reason the person gave, Markdown. A PS MAY offer the person a reason field and MUST NOT require one.¶

12.2. Reach of an Answer

When the PS puts an act to the person after an ask, it MAY offer them a choice of how far their answer reaches. The person's choice comes back to the SS as apply in decision.resolved, and the SS remembers and applies it to later acts Appendix A.1. The PS applies nothing.¶

The SS knows what its policy can match on and the PS does not, so the SS names the choices. An ask MAY carry apply_options, an array of objects each with a value the SS will recognize and a label, Markdown, the PS shows the person:¶

{
  "sdi": "d-4d2a91",
  "decision": "ask",
  "summary": "The agent wants to book a $3,200 refundable fare.",
  "apply_options": [
    { "value": "once", "label": "This booking only" },
    { "value": "refundable-under-4k", "label": "Any refundable fare under $4,000 on this trip" },
    { "value": "mission", "label": "Anything else this agent asks on this trip" }
  ]
}

The PS presents the labels and returns the chosen value as apply. When an ask carries no apply_options, the PS MAY offer these three, whose meaning is fixed:¶

• once: this act only.¶
• mission: every act of this kind under this mission, until it terminates.¶
• always: every act of this kind by this agent, under any mission or none, until the person changes it.¶

What "this kind" means for mission and always is the SS's to determine, since the SS applies it. A PS that offers them SHOULD word them as above and no more precisely.¶

16.1. The Supervisor Holds the Person's Authority

An SS decides, on the person's behalf, what every agent routed to it may do. A compromised SS can allow anything the person could allow, and can deny everything. That is the same authority a compromised PS has over consent, held by a second party. A person choosing an SS is choosing who exercises their judgment, and a PS SHOULD make that plain when the person registers one.¶

The SS cannot act; it can only answer. It issues no tokens, reaches no resource, and calls no one Appendix A.4. Everything it allows is issued by the PS, bounded by what the agent asked for, and revocable at the PS by the parties the AAuth Protocol names.¶

16.2. Forwarded Tokens

Supervision requests carry the agent token, the resource token, and the presented token as the agent sent them. Each is bound to the agent's key by its cnf and is of no use to a holder without that key. An SS learns from them; it cannot present them. Events name issued tokens by jti only.¶

16.3. Connect

The interaction at connect is the person confirming, at a server they chose, that a PS speaks for them there. An attacker who could complete that interaction for a sub the person did not initiate would have a PS they control accepted as the person's. The SS MUST show the connecting PS's issuer and name on the confirmation, and SHOULD show the code, so the person can recognize a connect they did not start. Interaction Code Misdirection in the AAuth Protocol applies.¶

16.4. Response Authenticity

Over TLS to an origin the PS resolved from the person's registration, an unsigned decision is authentic when it arrives. A signed decision is authentic afterwards, when the log entry is read by someone who was not on the connection. A PS that will ever have to show what its supervisor said SHOULD require an SS with a jwks_uri. The check that the response's id is the SS the PS called Section 9.4 is what stops one SS's signed decision being presented as another's.¶

16.5. Egress

The person names the SS, and anyone can run one. A PS that posted to whatever endpoint an SS's metadata named could be induced to send signed requests to addresses it should not reach. The egress admission rules of [I-D.hardt-httpbis-signature-key] apply before the PS fetches the SS's metadata or calls an endpoint in it.¶

17.1. What the Supervisor Sees

The SS sees everything the PS puts to it for the agents routed to it: mission text, justifications, the resources an agent reaches, the actions it takes, and what the person decides. That is the point; a supervisor that saw less could decide less. It is the person's own choice of a party to see it, made agent by agent Section 6, and the PS SHOULD say so when the person registers an SS.¶

17.2. Identifiers

The sub the PS sends is directed to the SS and appears nowhere else. Tokens forwarded in supervision requests carry directed identifiers for their own audiences, and the SS can trivially correlate them, since every request names the same sub. Nothing is gained by hiding that from the person's own supervisor, and nothing is lost by it: no other party receives the SS's sub.¶

17.3. Organizational Supervisors

Where an organization routes its people's agents to an SS it operates, the organization sees what the SS sees. The tenant at connect is how the SS knows it has that standing. What an organization may lawfully see of its members' agents is outside this document.¶

18.1. Well-Known URI Registration

This specification registers the following well-known URI per [RFC8615]:¶

A.1. Why the PS Never Decides

A PS that applied some of the person's standing decisions itself and forwarded the rest would hold part of the person's policy, and the SS the other part. The person could then not change their supervisor without losing what the PS held, and neither party would have the full record of how a decision was reached. Routing every act to the SS keeps the policy in one place, and makes the PS what the protocol wants it to be: the party that verifies, issues, and records, with no judgment of its own. The reach of an answer Section 12.2 is therefore delivered to the SS and applied there, and a person with no SS gets none.¶

A.2. Why Three Endpoints

One endpoint with a discriminator would carry everything, and an implementer writes one dispatch either way. The three are cut by what comes back: a mission-shaped answer, a decision, or an acknowledgment. Events are high-volume and fire-and-forget; decisions are few and latency-bound. Separate URLs let those be deployed, scaled, and rate-limited separately, and let the mission endpoint mirror the PS's own, so its shape is already known.¶

A.3. Why the PS Is Authoritative

A person may have no SS, one, or several, one per agent. Only the PS sees every act for the person, so only the PS can hold the whole record. The SS holds what it needs, and may drop a mission when it ends. Replay makes any SS current from the PS's record. An SS-held record would also require the PS to read from the SS, and the SS is a party the PS trusts to answer, not one it trusts to be reachable.¶

A.4. Why the SS Never Calls the PS

An SS that could call the PS would need keys the PS trusts, an authorization model at the PS for what an SS may do, and a way for the person to bound it. Everything the SS needs to say fits in a response: a decision, a refinement, a question for the agent. What it cannot do in a response, such as act between events, belongs to mission control, under the authorization model that document defines. An SS with no inbound calls also has no attack surface toward the PS beyond what it answers.¶

A.5. Why the sdi Is Minted by the PS

The PS's log entry for a decision begins before the SS has answered, and must be complete when the SS never does. An identifier the SS assigned would arrive, if at all, after the entry existed. Minting it at the PS makes one identifier cover the request, its retries, its polls, its clarifications, the person's answer, and the tokens issued, from the first moment.¶

A.6. Why Decisions Are Signed Responses, Not JWTs

A JWT would be a second encoding of a body that is already JSON, and a new token type. An HTTP Message Signature over the response leaves the body as it is, binds the decision to the request through ;req components, and, with Signature-Key on the response, makes the stored exchange say who signed it. The log entry is then the exchange itself, request and response, each carrying its signer's identity.¶

A.7. Why Interaction Relay Is an Event

When an agent asks the PS to relay an interaction, a resource or an AS has already decided the person is needed; the relay is not authorization. A deny from the SS could stop the PS relaying, but the protocol then has the agent direct the person itself, so the deny would remove the person's better channel and stop nothing. The SS is told, so an agent that keeps sending the person to interaction pages is visible in its record.¶

A.8. Why Routing, Not Fan-Out

Delivering the same act to two SSes raises which one decides and what the other is for. One deciding SS per agent answers the first, and a passive second supervisor is a PS configuration feature that adds nothing on the wire: an SS that only receives events already gets the same calls and answers 201. It can be added without changing this document.¶