interaction_endpoint: define error code for 'PS cannot perform the interaction'

[dickhardt]

Two pieces — both around interaction_endpoint

1. Define the agent's "try PS first" flow

The spec today (§requirement-responses:895) says when an agent receives 202 + AAuth-Requirement: requirement=interaction; url=…, it directs the user to that URL itself. There's no step where the agent first asks the PS to drive the interaction.

We should specify that the agent SHOULD POST the interaction to the PS's interaction_endpoint before driving the URL itself, so the PS can use any direct user-reach channels it has (live web session, registered mobile push). The agent only drives the URL directly when the PS reports it cannot.

Flow becomes:

1. Agent receives 202 + AAuth-Requirement: requirement=interaction; url=…; code=… from a resource (or AS or PS).
2. Agent POSTs {type: "interaction", url, code, …} to PS's interaction_endpoint.
3. PS attempts to reach the user via its channels.
4. PS returns 202 + Location: (deferred poll) on success, OR the new error below on failure.
5. On the error, agent drives the URL directly (browser-open, QR, etc.).

2. Define the error for "PS cannot perform the interaction"

The existing interaction_required error (§polling-error-codes:2016) doesn't fit: it means "interaction is needed but no party can drive it" — a terminal two-sided failure. Our case is one-sided: the agent can drive the interaction, it just preferred the PS try first.

Proposed new error:

code	HTTP	meaning
interaction_unavailable	4xx (TBD)	The PS has no channel available to reach the user for this interaction. The agent should fall back to driving the URL directly.

Name and exact HTTP status open for discussion. Some 4xx options: 400, 409 Conflict, 422 Unprocessable Entity, 424 Failed Dependency. (5xx feels wrong since it's not a server fault — it's expected protocol state.)

interaction_required keeps its existing meaning unchanged.

Related

• #33 — interaction_endpoint completion-polling clarification (same endpoint, different ambiguity)
• hellocoop/Wallet#4055 — Wallet implementation of interaction_endpoint, which needs both the new flow and the new error code
• Driver: Ponte's agent (praca) needs this to do PS-first interaction-driving with graceful fallback to local browser open / QR