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
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,
packages/plugins/openapi/src/sdk/upstream-failures.test.ts+103−0
@@ -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(() => ({

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