A 403 whose body or WWW-Authenticate challenge names a scope shortfall (RFC 6750 insufficient_scope, Google ACCESS_TOKEN_SCOPE_INSUFFICIENT) cannot be fixed by re-running the same OAuth grant, but all three protocol plugins collapsed it into connection_rejected, whose recovery block tells the agent to call oauth.start and retry: an infinite loop through identical consent screens. Add an oauth_scope_insufficient failure code with its own recovery guidance (reconnect with broader access; deliberately no startOAuthTool hint), a shared detector in the core SDK, and detection at the three collapse sites: openapi (body + headers), graphql (body), mcp (the transport error message, the only place the 403 body survives). A 403 without a recognised scope signal keeps the existing classification. Fixes #1381
Showing the changes to packages/plugins/openapi/src (2 of 18 files). Show all
Unified · Split
| @@ -8,6 +8,7 @@ import { · 7 unmodified lines | |||
| 8 | ToolResult, | 8 | ToolResult, |
| 9 | authToolFailure, | 9 | authToolFailure, |
| 10 | classifyHttpStatus, | 10 | classifyHttpStatus, |
| 11 | detectInsufficientScope, | ||
| 11 | sortHealthCheckCandidatesByIdentity, | 12 | sortHealthCheckCandidatesByIdentity, |
| 12 | extractIdentity, | 13 | extractIdentity, |
| 13 | extractResponseFields, | 14 | extractResponseFields, |
| @@ -722,6 +723,28 @@ export const invokeOpenApiBackedTool = (input: { · 708 unmodified lines | |||
| 722 | const ok = result.status >= 200 && result.status < 300; | 723 | const ok = result.status >= 200 && result.status < 300; |
| 723 | if (!ok) { | 724 | if (!ok) { |
| 724 | if (result.status === 401 || result.status === 403) { | 725 | if (result.status === 401 || result.status === 403) { |
| 726 | // A 403 naming a scope shortfall (RFC 6750 insufficient_scope, | ||
| 727 | // Google's ACCESS_TOKEN_SCOPE_INSUFFICIENT) cannot be fixed by | ||
| 728 | // re-running the same grant, so it gets its own code and recovery | ||
| 729 | // guidance instead of the re-authenticate loop. | ||
| 730 | const insufficientScope = | ||
| 731 | result.status === 403 | ||
| 732 | ? detectInsufficientScope({ body: result.error, headers: result.headers }) | ||
| 733 | : null; | ||
| 734 | if (insufficientScope) { | ||
| 735 | const required = insufficientScope.requiredScopes; | ||
| 736 | return openApiAuthToolFailure({ | ||
| 737 | code: "oauth_scope_insufficient", | ||
| 738 | status: result.status, | ||
| 739 | message: `The connection "${input.credential.connection}" for "${integration}" is authorized, but its grant does not cover the scope this operation requires${required.length > 0 ? ` (${required.join(" ")})` : ""}. Re-authenticating with the same grant will return the same error; reconnect with broader access.`, | ||
| 740 | owner: input.credential.owner, | ||
| 741 | integration, | ||
| 742 | connection: String(input.credential.connection), | ||
| 743 | credentialKind: "oauth", | ||
| 744 | credentialLabel: "Upstream authorization", | ||
| 745 | details: result.error, | ||
| 746 | }); | ||
| 747 | } | ||
| 725 | return openApiAuthToolFailure({ | 748 | return openApiAuthToolFailure({ |
| 726 | code: "connection_rejected", | 749 | code: "connection_rejected", |
| 727 | status: result.status, | 750 | status: result.status, |
| @@ -219,6 +219,109 @@ describe("OpenAPI upstream failure modes", () => { · 218 unmodified lines | |||
| 219 | }), | 219 | }), |
| 220 | ); | 220 | ); |
| 221 | 221 | ||
| 222 | // A 403 that names a scope shortfall is unfixable by re-running the same | ||
| 223 | // grant: it must NOT be connection_rejected (whose recovery tells the agent | ||
| 224 | // to oauth.start the identical grant and loop on the identical 403). | ||
| 225 | it.effect( | ||
| 226 | "scope-insufficient 403 (Google ErrorInfo) is classified as oauth_scope_insufficient", | ||
| 227 | () => | ||
| 228 | Effect.gen(function* () { | ||
| 229 | const server = yield* startScriptedServer(() => ({ | ||
| 230 | status: 403, | ||
| 231 | headers: { "content-type": "application/json" }, | ||
| 232 | body: JSON.stringify({ | ||
| 233 | error: { | ||
| 234 | code: 403, | ||
| 235 | message: "Request had insufficient authentication scopes.", | ||
| 236 | status: "PERMISSION_DENIED", | ||
| 237 | details: [ | ||
| 238 | { | ||
| 239 | "@type": "type.googleapis.com/google.rpc.ErrorInfo", | ||
| 240 | reason: "ACCESS_TOKEN_SCOPE_INSUFFICIENT", | ||
| 241 | domain: "googleapis.com", | ||
| 242 | metadata: { service: "drive.googleapis.com" }, | ||
| 243 | }, | ||
| 244 | ], | ||
| 245 | }, | ||
| 246 | }), | ||
| 247 | })); | ||
| 248 | const { executor, address } = yield* buildExecutorForOpenApiServer(server); | ||
| 249 | |||
| 250 | const result = yield* executor.execute(address, {}); | ||
| 251 | |||
| 252 | expect(result).toMatchObject({ | ||
| 253 | ok: false, | ||
| 254 | error: { | ||
| 255 | code: "oauth_scope_insufficient", | ||
| 256 | status: 403, | ||
| 257 | message: expect.stringContaining("does not cover the scope"), | ||
| 258 | details: { | ||
| 259 | category: "authentication", | ||
| 260 | upstream: { status: 403 }, | ||
| 261 | }, | ||
| 262 | }, | ||
| 263 | }); | ||
| 264 | const recovery = ( | ||
| 265 | result as { | ||
| 266 | error: { details: { recovery: Record<string, string> } }; | ||
| 267 | } | ||
| 268 | ).error.details.recovery; | ||
| 269 | expect( | ||
| 270 | recovery.startOAuthTool, | ||
| 271 | "no oauth.start hint: re-running the identical grant cannot satisfy the scope", | ||
| 272 | ).toBeUndefined(); | ||
| 273 | expect(recovery.scopeInstructions).toBeDefined(); | ||
| 274 | }), | ||
| 275 | ); | ||
| 276 | |||
| 277 | it.effect( | ||
| 278 | "scope-insufficient 403 (RFC 6750 WWW-Authenticate challenge) is classified as oauth_scope_insufficient", | ||
| 279 | () => | ||
| 280 | Effect.gen(function* () { | ||
| 281 | const server = yield* startScriptedServer(() => ({ | ||
| 282 | status: 403, | ||
| 283 | headers: { | ||
| 284 | "content-type": "application/json", | ||
| 285 | "www-authenticate": | ||
| 286 | 'Bearer realm="api", error="insufficient_scope", scope="files.read"', | ||
| 287 | }, | ||
| 288 | body: '{"message":"forbidden"}', | ||
| 289 | })); | ||
| 290 | const { executor, address } = yield* buildExecutorForOpenApiServer(server); | ||
| 291 | |||
| 292 | const result = yield* executor.execute(address, {}); | ||
| 293 | |||
| 294 | expect(result).toMatchObject({ | ||
| 295 | ok: false, | ||
| 296 | error: { | ||
| 297 | code: "oauth_scope_insufficient", | ||
| 298 | status: 403, | ||
| 299 | // The challenge names the missing scope; the message carries it so | ||
| 300 | // the agent can tell the user exactly what to grant. | ||
| 301 | message: expect.stringContaining("files.read"), | ||
| 302 | }, | ||
| 303 | }); | ||
| 304 | }), | ||
| 305 | ); | ||
| 306 | |||
| 307 | it.effect("ordinary 403 without a scope signal stays connection_rejected", () => | ||
| 308 | Effect.gen(function* () { | ||
| 309 | const server = yield* startScriptedServer(() => ({ | ||
| 310 | status: 403, | ||
| 311 | headers: { "content-type": "application/json" }, | ||
| 312 | body: '{"error":{"status":"PERMISSION_DENIED","message":"Caller lacks permission"}}', | ||
| 313 | })); | ||
| 314 | const { executor, address } = yield* buildExecutorForOpenApiServer(server); | ||
| 315 | |||
| 316 | const result = yield* executor.execute(address, {}); | ||
| 317 | |||
| 318 | expect(result).toMatchObject({ | ||
| 319 | ok: false, | ||
| 320 | error: { code: "connection_rejected", status: 403 }, | ||
| 321 | }); | ||
| 322 | }), | ||
| 323 | ); | ||
| 324 | |||
| 222 | it.effect("upstream returns malformed JSON despite Content-Type: application/json", () => | 325 | it.effect("upstream returns malformed JSON despite Content-Type: application/json", () => |
| 223 | Effect.gen(function* () { | 326 | Effect.gen(function* () { |
| 224 | const server = yield* startScriptedServer(() => ({ | 327 | const server = yield* startScriptedServer(() => ({ |