@aauth/proxy 0.5.0 → 2.0.0

package/dist/agent.js

@@ -1,43 +1,101 @@
-// agent proxy — the user's AAuth agent. v0 core: the authorize-first R3 invoke flow
-// against the resource proxy, exchanging at the PS.
+// agent proxy — the user's AAuth agent. The invoke flow against an AAuth
+// resource, obtaining person tokens and auth tokens at the PS.
 //
-// invoke() is non-blocking: when an interaction is required (PS consent or the
-// resource's OAuth bootstrap) it RETURNS the interaction (url + code + poll URL)
-// rather than completing it, so a caller — the MCP server — can surface the URL
-// to the user. invokeComplete() drives it to completion for programmatic use,
-// performing the interaction via a callback and polling.
+// The shape of the flow is the one the protocol describes: pick an opening
+// credential from what the resource declared, make the request, read any
+// AAuth-Requirement, satisfy it, retry. The declaration only saves round trips —
+// the runtime requirement is authoritative and can escalate at any point.
 //
-// Built directly on @hellocoop/httpsig (the @aauth/mcp-agent package is
-// 401-challenge-driven and has no R3/authorize-first path, mirroring the
+// invoke() is non-blocking: when an interaction is required (PS consent, a person
+// token the PS wants the user to approve, or the resource's own OAuth bootstrap)
+// it RETURNS the interaction (url + code + poll URL) rather than completing it,
+// so a caller — the MCP server — can surface the URL to the user.
+// invokeComplete() drives it to completion for programmatic use, performing the
+// interaction via a callback and polling.
+//
+// Built directly on @hellocoop/httpsig (the @aauth/agent package is
+// 401-challenge-driven and has no authorize-first path, mirroring the
 // resource-side finding).
 import { fetch as signedFetch } from '@hellocoop/httpsig';
+import { planAccessMode } from './access-mode.js';
+import { agentTokenPs, jwkThumbprint } from './jwt.js';
 import { routeOperation } from './resource.js';
-function signWith(cfg, token) {
-    return (url, init = {}) => signedFetch(url, { ...init, signingKey: cfg.agentPrivateJwk, signatureKey: { type: 'jwt', jwt: token } });
+import { createMemoryPersonTokenStore } from './store.js';
+// The AAuth HTTP Message Signatures profile's base covered components. httpsig
+// applies these itself when no list is passed; we pass an explicit list whenever
+// something must be added to it.
+const BASE_GET = ['@method', '@authority', '@path', 'signature-key'];
+const BASE_BODY = ['@method', '@authority', '@path', 'content-type', 'signature-key'];
+function components(opts) {
+    const base = opts.hasBody ? [...BASE_BODY] : [...BASE_GET];
+    let extended = false;
+    if (opts.hasBody && opts.psOrAs) {
+        base.splice(base.indexOf('content-type') + 1, 0, 'content-digest');
+        extended = true;
+    }
+    if (opts.authorization) {
+        base.splice(base.length - 1, 0, 'authorization');
+        extended = true;
+    }
+    return extended ? base : undefined;
+}
+function signWith(cfg, cred, opts = {}) {
+    return (url, init = {}) => {
+        const headers = { ...(init.headers ?? {}) };
+        if (cred.kind === 'session')
+            headers.authorization = `AAuth ${cred.token}`;
+        const jwt = cred.kind === 'person' || cred.kind === 'auth' ? cred.jwt : cfg.agentToken;
+        const list = components({
+            hasBody: init.body !== undefined,
+            authorization: cred.kind === 'session',
+            psOrAs: opts.psOrAs,
+        });
+        return signedFetch(url, {
+            ...init,
+            headers,
+            signingKey: cfg.agentPrivateJwk,
+            signatureKey: { type: 'jwt', jwt },
+            ...(list ? { components: list } : {}),
+        });
+    };
 }
 export function makeAgentPoll(cfg) {
-    return (url) => signWith(cfg, cfg.agentToken)(url, { method: 'GET', headers: { Prefer: 'wait=20' } });
+    return (url) => signWith(cfg, { kind: 'agent' })(url, { method: 'GET', headers: { Prefer: 'wait=20' } });
 }
-function parseInteraction(requirement) {
-    if (!requirement || !requirement.includes('requirement=interaction'))
+// Parses the AAuth-Requirement header. Unrecognized `requirement=` values are
+// returned as-is: the caller decides, and treats anything it cannot satisfy as a
+// terminal response rather than guessing.
+function parseRequirement(headerValue) {
+    if (!headerValue)
         return undefined;
-    const url = /url="([^"]+)"/.exec(requirement)?.[1];
-    const code = /code="([^"]+)"/.exec(requirement)?.[1];
-    return url && code ? { url, code } : undefined;
-}
-// A per-call escalation challenge (W2): the resource returns 401 with
-// `requirement=auth-token; resource-token="…"` for a conditional/irreversible op.
-// The agent takes that resource token (which carries the call as r3_context) to
-// the PS for a per-call auth token, then retries.
-function parseAuthTokenChallenge(requirement) {
-    if (!requirement || !requirement.includes('requirement=auth-token'))
+    const requirement = /requirement=([A-Za-z0-9_-]+)/.exec(headerValue)?.[1];
+    if (!requirement)
         return undefined;
-    return /resource-token="([^"]+)"/.exec(requirement)?.[1];
+    return {
+        requirement,
+        resourceToken: /resource-token="([^"]+)"/.exec(headerValue)?.[1],
+        url: /url="([^"]+)"/.exec(headerValue)?.[1],
+        code: /code="([^"]+)"/.exec(headerValue)?.[1],
+        reason: /reason=([A-Za-z0-9_-]+)/.exec(headerValue)?.[1],
+    };
+}
+// A terminal challenge response, annotated with the challenge's `reason` when
+// one was sent so the caller (ultimately the LLM) sees `budget-exhausted` /
+// `insufficient-budget` instead of a bare status.
+async function terminalChallenge(res, req) {
+    const body = await safeBody(res);
+    return {
+        kind: 'result',
+        status: res.status,
+        body: req.reason ? { error: req.reason, detail: body } : body,
+    };
 }
 function interactionFrom(res) {
-    const parsed = parseInteraction(res.headers.get('aauth-requirement'));
+    const parsed = parseRequirement(res.headers.get('aauth-requirement'));
     const pollUrl = res.headers.get('location') ?? '';
-    return parsed && pollUrl ? { ...parsed, pollUrl } : undefined;
+    return parsed?.requirement === 'interaction' && parsed.url && parsed.code && pollUrl
+        ? { url: parsed.url, code: parsed.code, pollUrl }
+        : undefined;
 }
 async function safeBody(res) {
     const text = await res.text();
@@ -51,11 +109,108 @@ async function safeBody(res) {
 async function psMetadata(psUrl) {
     return (await (await fetch(`${psUrl.replace(/\/$/, '')}/.well-known/aauth-person.json`)).json());
 }
+// ── Per-config default stores ──
+//
+// Keyed on the ProxyConfig object, which the identity provider resolves
+// per-principal. A process-global cache would leak person and session tokens
+// across tenants in a multi-user host.
+const defaultPersonTokens = new WeakMap();
+const defaultSessionTokens = new WeakMap();
+function personTokenStore(cfg) {
+    if (cfg.personTokens)
+        return cfg.personTokens;
+    let store = defaultPersonTokens.get(cfg);
+    if (!store) {
+        store = createMemoryPersonTokenStore();
+        defaultPersonTokens.set(cfg, store);
+    }
+    return store;
+}
+function sessionTokenStore(cfg) {
+    if (cfg.sessionTokens)
+        return cfg.sessionTokens;
+    let store = defaultSessionTokens.get(cfg);
+    if (!store) {
+        const m = new Map();
+        store = {
+            async get(resource) {
+                return m.get(resource);
+            },
+            async set(resource, token) {
+                m.set(resource, token);
+            },
+        };
+        defaultSessionTokens.set(cfg, store);
+    }
+    return store;
+}
+/**
+ * Obtain a person token for one resource, from cache or from the PS.
+ *
+ * A resource MUST have verified a person token before it issues a resource token,
+ * and the agent MUST present one on every authorization endpoint request
+ * (protocol §Person Token, §Authorization Endpoint Request) — so this sits in
+ * front of the whole authorize-first path, not only of `person-token` resources.
+ *
+ * The PS MAY require the user to approve the agent acting at this resource before
+ * issuing, and answers `202` with `requirement=interaction`. That is surfaced
+ * like any other interaction; the caller drives it and retries, and the second
+ * request gets a `200`.
+ */
+export async function obtainPersonToken(cfg, ps, resource, missionS256) {
+    if (!ps.person_token_endpoint) {
+        return {
+            kind: 'result',
+            status: 0,
+            body: {
+                error: 'ps_missing_person_token_endpoint',
+                error_description: `${cfg.psUrl} publishes no person_token_endpoint; AAuth -11 requires one`,
+            },
+        };
+    }
+    const store = personTokenStore(cfg);
+    const jkt = await jwkThumbprint(cfg.agentPrivateJwk);
+    const key = { resource, ...(missionS256 ? { mission_s256: missionS256 } : {}) };
+    const cached = await store.get(key, jkt);
+    if (cached)
+        return { kind: 'token', personToken: cached };
+    const res = await signWith(cfg, { kind: 'agent' }, { psOrAs: true })(ps.person_token_endpoint, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+            resource,
+            ...(missionS256 ? { mission_s256: missionS256 } : {}),
+        }),
+    });
+    if (res.status === 202) {
+        const interaction = interactionFrom(res);
+        if (interaction)
+            return { kind: 'interaction', interaction };
+    }
+    if (!res.ok)
+        return { kind: 'result', status: res.status, body: await safeBody(res) };
+    const { person_token, expires_in } = (await res.json());
+    if (!person_token) {
+        return { kind: 'result', status: res.status, body: { error: 'ps_returned_no_person_token' } };
+    }
+    const expiresAt = Math.floor(Date.now() / 1000) + (expires_in ?? 3600);
+    await store.set(key, jkt, person_token, expiresAt);
+    return { kind: 'token', personToken: person_token };
+}
+/**
+ * Drop every cached person token. Call when the agent's signing key rotates —
+ * every person token binds the same key through `cnf`, so none of them survive.
+ * `obtainPersonToken` also detects rotation on its own via the key thumbprint;
+ * this is the explicit hook for a host that knows a rotation happened.
+ */
+export async function flushPersonTokens(cfg) {
+    await personTokenStore(cfg).flush();
+}
 // POST the interaction to the PS so it can try to reach the user (live web
 // session, registered mobile push). On 2xx the PS owns user-reach; the agent
-// blocks on the resource pollUrl until the user completes there. On any
-// non-2xx (including the spec-pending interaction_unavailable error — see
-// AAuth#34) the agent falls back to driving the URL itself.
+// blocks on the pollUrl until the user completes there. On any non-2xx
+// (including the spec-pending interaction_unavailable error — see AAuth#34) the
+// agent falls back to driving the URL itself.
 async function relayInteractionToPS(signAgent, endpoint, interaction) {
     try {
         const res = await signAgent(endpoint, {
@@ -91,17 +246,22 @@ export async function pollUntilDone(poll, locationUrl, timeoutMs = 180_000, onPo
     }
     return res;
 }
-// Exchange a resource token at the PS for an auth token. capabilities tells the
+// Exchange a resource token at the PS for an auth token. `capabilities` tells the
 // PS the agent can relay interactions to the user, so it returns a 202 consent
 // interaction (surfaced for the caller to drive + retry) rather than requiring a
-// registered mobile device. On PS endpoints this is a token-request parameter,
+// registered mobile device. On PS endpoints this is a request-body parameter,
 // not a header (the AAuth-Capabilities header is for resource requests).
 //
-// cfg.psHints (if set) are spread into the body — all §8.1 optional params.
-// cfg.onAuthToken (if set) is called with the auth_token before it is returned.
-async function exchangeAtPS(signAgent, tokenEndpoint, resourceToken, cfg) {
+// The mission does not appear here: it travels in the person token's
+// `mission_s256`, which the resource copies into the resource token and the PS
+// into the auth token.
+//
+// cfg.psHints (if set) are spread into the body — all §Agent Token Request
+// optional params. cfg.onAuthToken (if set) is called with the auth_token before
+// it is returned.
+async function exchangeAtPS(cfg, authTokenEndpoint, resourceToken) {
     const { capabilities, ...otherHints } = cfg.psHints ?? {};
-    const res = await signAgent(tokenEndpoint, {
+    const res = await signWith(cfg, { kind: 'agent' }, { psOrAs: true })(authTokenEndpoint, {
         method: 'POST',
         headers: { 'content-type': 'application/json' },
         body: JSON.stringify({
@@ -122,10 +282,38 @@ async function exchangeAtPS(signAgent, tokenEndpoint, resourceToken, cfg) {
         await cfg.onAuthToken(auth_token);
     return { kind: 'token', authToken: auth_token };
 }
-// Resource-parameterized invoke. The new tool surface in server.ts calls into
-// this directly with an L1 entry from store.ts; the legacy invoke() below
-// wraps it for cfg.resourceProxyBase-based callers (tests, demo scripts).
-export async function invokeAtResource(cfg, l1, operationId, args = {}) {
+// ── Authorize-first ──
+/**
+ * POST the resource's authorization endpoint, declaring the operation, and take
+ * back a resource token. The request MUST present a person token via
+ * Signature-Key (protocol §Authorization Endpoint Request) — an agent token gets
+ * `requirement=person-token`.
+ */
+async function authorizeAtResource(cfg, endpoint, personToken, vocabulary, operationId) {
+    const res = await signWith(cfg, { kind: 'person', jwt: personToken })(endpoint, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+            r3_operations: {
+                vocabulary,
+                // Bare identifiers, scoped to the one discovery endpoint the resource
+                // advertises for this vocabulary (R3 -02 §Operation Identifier Scope).
+                operations: [{ operationId }],
+            },
+        }),
+    });
+    if (!res.ok)
+        return { kind: 'result', status: res.status, body: await safeBody(res) };
+    const { resource_token } = (await res.json());
+    if (!resource_token) {
+        // The resource handled authorization itself and issued no resource token.
+        return { kind: 'result', status: res.status, body: await safeBody(res) };
+    }
+    return { kind: 'resourceToken', resourceToken: resource_token };
+}
+// ── invoke ──
+const MAX_ROUNDS = 6;
+export async function invokeAtResource(cfg, l1, operationId, args = {}, opts = {}) {
     const route = await routeOperation(l1, operationId, args);
     if (route.plan.kind !== 'sync.request') {
         return {
@@ -136,112 +324,203 @@ export async function invokeAtResource(cfg, l1, operationId, args = {}) {
     }
     const plan = route.plan;
     const apiUrl = `${l1.origin}${plan.path}${plan.query ? `?${plan.query}` : ''}`;
-    const requestInit = {
+    // Fixed for the whole flow. A per-call retry MUST present exactly the
+    // parameters the proposal was approved for (R3 -02 §Per-Call Proposals step 3):
+    // the resource recovers the proposal by its hash and rejects any difference.
+    const init = {
         method: plan.method,
         ...(plan.headers ? { headers: plan.headers } : {}),
         ...(plan.body !== undefined ? { body: plan.body } : {}),
     };
-    // agent-token access mode: sign with the agent token + go. No PS exchange.
-    // If the resource returns a 401 auth-token challenge, escalate to the PS.
-    if (l1.access_mode === 'agent-token') {
-        const signAgent = signWith(cfg, cfg.agentToken);
-        let res = await signAgent(apiUrl, requestInit);
-        const challenge = res.status === 401 ? parseAuthTokenChallenge(res.headers.get('aauth-requirement')) : undefined;
-        if (challenge) {
-            const ps = await psMetadata(cfg.psUrl);
-            const ex = await exchangeAtPS(signAgent, ps.token_endpoint, challenge, cfg);
-            if (ex.kind !== 'token')
-                return ex;
-            res = await signWith(cfg, ex.authToken)(apiUrl, requestInit);
-            if (res.status === 202) {
-                const interaction = interactionFrom(res);
-                if (interaction)
-                    return { kind: 'interaction', interaction };
+    const missionS256 = opts.missionS256 ?? cfg.missionS256;
+    // Three-way access_mode plan against the mode that applies to THIS operation:
+    // its own annotation when it carries one, the resource-wide access_mode
+    // otherwise (R3 -02 §Applying Annotations).
+    const accessPlan = planAccessMode(route.accessMode, {
+        hasPersonServer: agentTokenPs(cfg.agentToken) !== undefined,
+    });
+    if (accessPlan.kind === 'unsatisfiable') {
+        return {
+            kind: 'skipped',
+            resource: l1.resource,
+            opId: operationId,
+            mode: accessPlan.mode,
+            reason: accessPlan.reason,
+        };
+    }
+    let ps;
+    const needPS = async () => {
+        ps ??= await psMetadata(cfg.psUrl);
+        return ps;
+    };
+    const sessions = sessionTokenStore(cfg);
+    // ── Opening credential ──
+    //
+    // The plan only decides where to start. Everything after this point is the
+    // requirement loop, which is identical in every mode.
+    let cred = { kind: 'agent' };
+    if (accessPlan.kind === 'satisfiable') {
+        switch (accessPlan.mode) {
+            case 'agent-token':
+                break;
+            case 'session-token': {
+                // Resource-managed. Present the session token if we already hold one;
+                // otherwise call with the agent token and let the resource start its own
+                // consent flow with a 202 interaction.
+                const held = await sessions.get(l1.resource);
+                if (held)
+                    cred = { kind: 'session', token: held };
+                break;
+            }
+            case 'person-token': {
+                const pt = await obtainPersonToken(cfg, await needPS(), l1.issuer, missionS256);
+                if (pt.kind !== 'token')
+                    return pt;
+                cred = { kind: 'person', jwt: pt.personToken };
+                break;
+            }
+            case 'auth-token':
+            case 'per-call': {
+                // Authorize-first when the resource publishes an authorization_endpoint:
+                // declare the operation, take back a resource token, exchange it at the
+                // PS. Without one, the resource issues resource tokens via 401 instead
+                // (protocol §Resource Access and Resource Tokens) — start with the
+                // person token and let the requirement loop pick up the challenge.
+                const pt = await obtainPersonToken(cfg, await needPS(), l1.issuer, missionS256);
+                if (pt.kind !== 'token')
+                    return pt;
+                cred = { kind: 'person', jwt: pt.personToken };
+                if (l1.authorization_endpoint) {
+                    const authz = await authorizeAtResource(cfg, l1.authorization_endpoint, pt.personToken, route.adapter.vocabUri, operationId);
+                    if (authz.kind !== 'resourceToken')
+                        return authz;
+                    const ex = await exchangeAtPS(cfg, (await needPS()).auth_token_endpoint, authz.resourceToken);
+                    if (ex.kind !== 'token')
+                        return ex;
+                    cred = { kind: 'auth', jwt: ex.authToken };
+                }
+                break;
             }
         }
-        return { kind: 'result', status: res.status, body: await safeBody(res) };
-    }
-    // aauth-access-token / auth-token: R3 flow.
-    if (!l1.authorization_endpoint) {
-        throw new Error(`resource ${l1.resource}: no authorization_endpoint (access_mode ${l1.access_mode} requires R3)`);
     }
-    const signAgent = signWith(cfg, cfg.agentToken);
-    const ps = await psMetadata(cfg.psUrl);
-    // 1. authorize-first: declare the operation, get a resource token.
-    const authzRes = await signAgent(l1.authorization_endpoint, {
-        method: 'POST',
-        headers: { 'content-type': 'application/json' },
-        body: JSON.stringify({
-            r3_operations: {
-                vocabulary: route.adapter.vocabUri,
-                // Entry shape is vocabulary-specific: {operationId} for plain openapi,
-                // {service, operationId} for openapi-gateway.
-                operations: [route.adapter.formatOperationEntry?.(operationId) ?? { operationId }],
-            },
-        }),
-    });
-    if (!authzRes.ok)
-        return { kind: 'result', status: authzRes.status, body: await safeBody(authzRes) };
-    const { resource_token } = (await authzRes.json());
-    // 2. exchange at the PS for an auth token (surface a consent interaction if any).
-    const ex = await exchangeAtPS(signAgent, ps.token_endpoint, resource_token, cfg);
-    if (ex.kind !== 'token')
-        return ex;
-    // 3. call the resource. Writes carry the body; the agent signs over it so the
-    // proxy's content-digest check (and the r3_context it packs on escalation)
-    // match the actual call.
-    const callWith = (token) => signWith(cfg, token)(apiUrl, requestInit);
-    let apiRes = await callWith(ex.authToken);
-    // First contact: a resource-issued interaction (e.g. OAuth bootstrap). Try
-    // the PS's interaction_endpoint first so it can use its own user-reach
-    // channels (live web session, mobile push). On any non-2xx — including the
-    // spec-pending interaction_unavailable error (AAuth#34) and any PS that
-    // hasn't implemented the endpoint yet — surface the interaction so the
-    // caller can drive it (layer 2: local OS open / layer 3: text+QR).
-    if (apiRes.status === 202) {
-        const interaction = interactionFrom(apiRes);
-        if (interaction) {
-            const engaged = ps.interaction_endpoint
-                ? await relayInteractionToPS(signAgent, ps.interaction_endpoint, interaction)
-                : false;
-            if (!engaged)
-                return { kind: 'interaction', interaction };
-            const poll = (url) => signWith(cfg, cfg.agentToken)(url, { method: 'GET', headers: { Prefer: 'wait=20' } });
-            const completed = await pollUntilDone(poll, interaction.pollUrl, 180_000);
-            if (completed.status === 202)
-                return { kind: 'interaction', interaction };
-            apiRes = await callWith(ex.authToken);
+    // ── Requirement loop ──
+    //
+    // Make the request, read any AAuth-Requirement, satisfy it, retry. `satisfied`
+    // stops the loop from chasing the same requirement twice with the same
+    // credential, which is what a resource that will never be satisfiable looks
+    // like from here.
+    const satisfied = new Set();
+    for (let round = 0; round < MAX_ROUNDS; round++) {
+        const res = await signWith(cfg, cred)(apiUrl, init);
+        // A resource MAY replace the agent's session token on any response.
+        const access = res.headers.get('aauth-access');
+        if (access) {
+            await sessions.set(l1.resource, access);
+            if (cred.kind !== 'auth' && cred.kind !== 'person')
+                cred = { kind: 'session', token: access };
         }
-    }
-    // Per-call escalation (W2): a conditional/irreversible op returns a 401
-    // auth-token challenge. Take its resource token (which carries the call as
-    // r3_context) to the PS for a per-call auth token, then retry the same call.
-    // If the PS needs consent first, it returns a 202 interaction we surface.
-    const challenge = apiRes.status === 401 ? parseAuthTokenChallenge(apiRes.headers.get('aauth-requirement')) : undefined;
-    if (challenge) {
-        const stepEx = await exchangeAtPS(signAgent, ps.token_endpoint, challenge, cfg);
-        if (stepEx.kind !== 'token')
-            return stepEx;
-        apiRes = await callWith(stepEx.authToken);
-        if (apiRes.status === 202) {
-            const interaction = interactionFrom(apiRes);
-            if (interaction)
-                return { kind: 'interaction', interaction };
+        const req = parseRequirement(res.headers.get('aauth-requirement'));
+        if (!req)
+            return { kind: 'result', status: res.status, body: await safeBody(res) };
+        const marker = `${req.requirement}:${cred.kind}`;
+        if (satisfied.has(marker)) {
+            // Same requirement, same credential kind, second time — e.g. the budget of
+            // the auth token we just re-acquired is exhausted again. Stop and surface
+            // the challenge (with its reason) rather than spin.
+            return terminalChallenge(res, req);
+        }
+        satisfied.add(marker);
+        switch (req.requirement) {
+            case 'agent-token': {
+                // The resource wants the agent's own identity token specifically.
+                if (cred.kind === 'agent') {
+                    return { kind: 'result', status: res.status, body: await safeBody(res) };
+                }
+                cred = { kind: 'agent' };
+                continue;
+            }
+            case 'person-token': {
+                const pt = await obtainPersonToken(cfg, await needPS(), l1.issuer, missionS256);
+                if (pt.kind !== 'token')
+                    return pt;
+                cred = { kind: 'person', jwt: pt.personToken };
+                continue;
+            }
+            case 'auth-token': {
+                // Also the per-call path: for an `r3_per_call` operation the resource
+                // builds a proposal from this call's concrete parameters, persists it
+                // under its hash, and returns a resource token carrying only the
+                // `r3_uri`/`r3_s256` reference. The agent exchanges it and retries the
+                // identical call (R3 -02 §Per-Call Proposals).
+                if (!req.resourceToken) {
+                    return terminalChallenge(res, req);
+                }
+                const ex = await exchangeAtPS(cfg, (await needPS()).auth_token_endpoint, req.resourceToken);
+                if (ex.kind !== 'token')
+                    return ex;
+                cred = { kind: 'auth', jwt: ex.authToken };
+                continue;
+            }
+            case 'interaction': {
+                const interaction = interactionFrom(res);
+                if (!interaction) {
+                    return { kind: 'result', status: res.status, body: await safeBody(res) };
+                }
+                // Try the PS's interaction endpoint first so it can use its own
+                // user-reach channels (live web session, mobile push). On any non-2xx —
+                // including the spec-pending interaction_unavailable error (AAuth#34)
+                // and any PS that hasn't implemented the endpoint yet — surface the
+                // interaction so the caller can drive it (layer 2: local OS open;
+                // layer 3: text + QR).
+                const meta = await needPS().catch(() => undefined);
+                const engaged = meta?.interaction_endpoint
+                    ? await relayInteractionToPS(signWith(cfg, { kind: 'agent' }), meta.interaction_endpoint, interaction)
+                    : false;
+                if (!engaged)
+                    return { kind: 'interaction', interaction };
+                const completed = await pollUntilDone(makeAgentPoll(cfg), interaction.pollUrl, 180_000);
+                if (completed.status === 202)
+                    return { kind: 'interaction', interaction };
+                const settled = completed.headers.get('aauth-access');
+                if (settled) {
+                    await sessions.set(l1.resource, settled);
+                    cred = { kind: 'session', token: settled };
+                }
+                continue;
+            }
+            default:
+                // A requirement value this build does not know. The agent MUST NOT
+                // treat the response as satisfiable; surface it verbatim.
+                return {
+                    kind: 'result',
+                    status: res.status,
+                    body: {
+                        error: 'unsupported_requirement',
+                        requirement: req.requirement,
+                        detail: await safeBody(res),
+                    },
+                };
         }
     }
-    return { kind: 'result', status: apiRes.status, body: await safeBody(apiRes) };
+    return {
+        kind: 'result',
+        status: 429,
+        body: { error: 'requirement_loop', detail: `${l1.resource} kept challenging after ${MAX_ROUNDS} rounds` },
+    };
 }
 // Drive invokeAtResource to completion: perform each interaction via
 // `onInteraction`, poll until it resolves, and retry. For programmatic / test
 // use; the MCP tool surface is non-blocking by design and surfaces interaction
 // URLs to the LLM caller instead.
-export async function invokeAtResourceComplete(cfg, l1, operationId, onInteraction, args = {}, maxRounds = 5, pollTimeoutMs = 180_000, onPoll) {
-    // Poll deferred URLs signed with the agent token (long-poll via Prefer: wait).
-    const poll = (url) => signWith(cfg, cfg.agentToken)(url, { method: 'GET', headers: { Prefer: 'wait=20' } });
+export async function invokeAtResourceComplete(cfg, l1, operationId, onInteraction, args = {}, maxRounds = 5, pollTimeoutMs = 180_000, onPoll, opts = {}) {
+    const poll = makeAgentPoll(cfg);
     for (let round = 0; round < maxRounds; round++) {
-        const result = await invokeAtResource(cfg, l1, operationId, args);
+        const result = await invokeAtResource(cfg, l1, operationId, args, opts);
         if (result.kind === 'result')
             return { status: result.status, body: result.body };
+        if (result.kind === 'skipped') {
+            return { status: 0, body: { error: 'access_mode_unsatisfiable', ...result } };
+        }
         await onInteraction(result.interaction.url, result.interaction.code);
         await pollUntilDone(poll, result.interaction.pollUrl, pollTimeoutMs, onPoll);
     }
@@ -250,6 +529,6 @@ export async function invokeAtResourceComplete(cfg, l1, operationId, onInteracti
 // Signed DELETE to an admin endpoint on the resource (e.g. /admin/tokens).
 // Uses the agent token so the resource can verify the caller owns the key.
 export async function deleteAtAdmin(cfg, l1, path) {
-    return signWith(cfg, cfg.agentToken)(`${l1.origin}${path}`, { method: 'DELETE' });
+    return signWith(cfg, { kind: 'agent' })(`${l1.origin}${path}`, { method: 'DELETE' });
 }
 //# sourceMappingURL=agent.js.map