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 | 8 | ToolResult, |
| 9 | 9 | authToolFailure, |
| 10 | 10 | classifyHttpStatus, |
| 11 | + detectInsufficientScope, | |
| 11 | 12 | sortHealthCheckCandidatesByIdentity, |
| 12 | 13 | extractIdentity, |
| 13 | 14 | extractResponseFields, |
| @@ -722,6 +723,28 @@ export const invokeOpenApiBackedTool = (input: { · 708 unmodified lines | ||
| 722 | 723 | const ok = result.status >= 200 && result.status < 300; |
| 723 | 724 | if (!ok) { |
| 724 | 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 | 748 | return openApiAuthToolFailure({ |
| 726 | 749 | code: "connection_rejected", |
| 727 | 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 | 325 | it.effect("upstream returns malformed JSON despite Content-Type: application/json", () => |
| 223 | 326 | Effect.gen(function* () { |
| 224 | 327 | const server = yield* startScriptedServer(() => ({ |