History

Classify scope-insufficient 403s as oauth_scope_insufficient (#1385)

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

Rhys Sullivan committed 4 months ago

Commit eabb67a1 parent d90d8be18 files · +1594 −38Browse files

Showing the changes to packages/plugins/openapi/src (2 of 18 files). Show all

Unified · Split

2 files
  1. packages/plugins/openapi/src/sdk/backing.ts +23 −0
  2. packages/plugins/openapi/src/sdk/upstream-failures.test.ts +103 −0
packages/plugins/openapi/src/sdk/backing.ts+23−0
@@ -8,6 +8,7 @@ import { · 7 unmodified lines
88 ToolResult,
99 authToolFailure,
1010 classifyHttpStatus,
11+ detectInsufficientScope,
1112 sortHealthCheckCandidatesByIdentity,
1213 extractIdentity,
1314 extractResponseFields,
@@ -722,6 +723,28 @@ export const invokeOpenApiBackedTool = (input: { · 708 unmodified lines
722723 const ok = result.status >= 200 && result.status < 300;
723724 if (!ok) {
724725 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+ }
725748 return openApiAuthToolFailure({
726749 code: "connection_rejected",
727750 status: result.status,
packages/plugins/openapi/src/sdk/upstream-failures.test.ts+103−0
@@ -219,6 +219,109 @@ describe("OpenAPI upstream failure modes", () => { · 218 unmodified lines
219219 }),
220220 );
221221
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+
222325 it.effect("upstream returns malformed JSON despite Content-Type: application/json", () =>
223326 Effect.gen(function* () {
224327 const server = yield* startScriptedServer(() => ({

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

Select next item
j↓
Select previous item
k↑
Open selected item
Enter
Dismiss filters or clear selection
Esc

Repository code

Go to file
t