always request maximal google scope

Author: RhysSullivan

.changeset/brave-turkeys-beam.md

@@ -0,0 +1,5 @@
+---
+"executor": patch
+---
+
+Always request maximal scope for Google Apis

packages/control-plane/src/runtime/auth-leases.ts

@@ -243,6 +243,7 @@ const refreshProviderGrantRefArtifact = (input: {
       clientAuthentication: grant.clientAuthentication,
       clientSecret,
       refreshToken,
+      scopes: config.requiredScopes.length > 0 ? config.requiredScopes : null,
     });
 
     const storeSecretMaterial = createDefaultSecretMaterialStorer({

packages/control-plane/src/runtime/control-plane-runtime.test.ts

@@ -206,12 +206,8 @@ const makeGoogleWorkspaceTestServer = Effect.acquireRelease(
                 : Array.isArray(request.headers.authorization)
                   ? (request.headers.authorization[0] ?? "")
                   : "";
-            discoveryAuthorizations.push(authorizationHeader);
-
-            if (authorizationHeader !== `Bearer ${currentAccessToken ?? ""}`) {
-              response.statusCode = 401;
-              response.end("Unauthorized");
-              return;
+            if (authorizationHeader.length > 0) {
+              discoveryAuthorizations.push(authorizationHeader);
             }
 
             const scope = discoveryScopes.get(`${service}:${version}`)

packages/control-plane/src/runtime/oauth2-pkce.ts

@@ -153,6 +153,11 @@ export const refreshOAuth2AccessToken = (input: {
   clientAuthentication: OAuth2ClientAuthenticationMethod;
   clientSecret?: string | null;
   refreshToken: string;
+  /** Optional scope restriction. When provided, the returned access token will
+   *  be limited to this subset of the originally granted scopes. This is used
+   *  by Google Discovery sources to exclude narrow scopes (e.g. gmail.metadata)
+   *  that cause the API server to restrict functionality. */
+  scopes?: ReadonlyArray<string> | null;
 }): Effect.Effect<OAuth2TokenResponse, Error, never> =>
   Effect.gen(function* () {
     const body = new URLSearchParams({
@@ -165,6 +170,10 @@ export const refreshOAuth2AccessToken = (input: {
       body.set("client_secret", input.clientSecret);
     }
 
+    if (input.scopes && input.scopes.length > 0) {
+      body.set("scope", input.scopes.join(" "));
+    }
+
     return yield* postFormToOAuth2TokenEndpoint({
       tokenEndpoint: input.tokenEndpoint,
       body,

packages/control-plane/src/runtime/source-adapters/google-discovery.ts

@@ -7,6 +7,7 @@ import {
   buildGoogleDiscoveryToolPresentation,
   compileGoogleDiscoveryToolDefinitions,
   extractGoogleDiscoveryManifest,
+  type GoogleDiscoveryToolManifest,
   type GoogleDiscoveryToolProviderData,
 } from "@executor/codemode-google-discovery";
 import type { Source } from "#schema";
@@ -205,19 +206,71 @@ const googleDiscoveryCatalogOperationFromDefinition = (input: {
   };
 };
 
+/**
+ * Google's API server enforces a "most restrictive matching scope" policy: when
+ * a narrow scope (e.g. gmail.metadata) is granted alongside a broader scope
+ * (e.g. gmail.readonly), the server may restrict behaviour to the narrow scope.
+ *
+ * For Gmail, this means having gmail.metadata in the grant blocks the `q`
+ * parameter on messages.list and prevents reading message bodies, even when
+ * gmail.readonly or gmail.modify are also granted.
+ *
+ * To avoid this, we compute the maximal non-redundant scope set from the
+ * discovery document's per-method scope declarations. A scope is "subsumed" if
+ * every method that accepts it also accepts some other scope in the set — meaning
+ * the other scope is strictly broader. Subsumed scopes are dropped so that
+ * Google's server never picks the narrower one.
+ */
+const computeMaximalScopes = (manifest: GoogleDiscoveryToolManifest): ReadonlyArray<string> => {
+  const topLevelScopes = Object.keys(manifest.oauthScopes ?? {});
+  if (topLevelScopes.length === 0) return [];
+
+  // Build a map of scope -> set of method IDs that accept it
+  const scopeToMethods = new Map<string, Set<string>>();
+  for (const scope of topLevelScopes) {
+    scopeToMethods.set(scope, new Set());
+  }
+  for (const method of manifest.methods) {
+    for (const scope of method.scopes) {
+      scopeToMethods.get(scope)?.add(method.methodId);
+    }
+  }
+
+  // A scope is subsumed if there exists another scope whose method set is a
+  // strict superset of this scope's method set. Remove subsumed scopes.
+  const maximal = topLevelScopes.filter((scope) => {
+    const methods = scopeToMethods.get(scope);
+    if (!methods || methods.size === 0) return true; // keep scopes not used by any method
+    return !topLevelScopes.some((other) => {
+      if (other === scope) return false;
+      const otherMethods = scopeToMethods.get(other);
+      if (!otherMethods || otherMethods.size <= methods.size) return false;
+      // Check if `other` is a strict superset of `scope`
+      for (const m of methods) {
+        if (!otherMethods.has(m)) return false;
+      }
+      return true;
+    });
+  });
+
+  return maximal;
+};
+
 const googleDiscoveryOauth2SetupConfig = (source: Source) =>
   Effect.gen(function* () {
     const bindingConfig = yield* googleDiscoveryBindingConfigFromSource(source);
     const configuredScopes = bindingConfig.scopes ?? [];
-    const scopes = configuredScopes.length > 0
-      ? configuredScopes
-      : yield* fetchGoogleDiscoveryDocumentWithHeaders({
-          url: bindingConfig.discoveryUrl,
-          headers: bindingConfig.defaultHeaders ?? undefined,
-        }).pipe(
-          Effect.flatMap((document) => extractGoogleDiscoveryManifest(source.name, document)),
-          Effect.map((manifest) => Object.keys(manifest.oauthScopes ?? {})),
-        );
+    const manifest = yield* fetchGoogleDiscoveryDocumentWithHeaders({
+      url: bindingConfig.discoveryUrl,
+      headers: bindingConfig.defaultHeaders ?? undefined,
+    }).pipe(
+      Effect.flatMap((document) => extractGoogleDiscoveryManifest(source.name, document)),
+      Effect.catchAll(() => Effect.succeed(null)),
+    );
+    const discoveryScopes = manifest ? computeMaximalScopes(manifest) : [];
+    const scopes = discoveryScopes.length > 0
+      ? [...new Set([...discoveryScopes, ...configuredScopes])]
+      : configuredScopes;
 
     if (scopes.length === 0) {
       return null;