Don't nag reconnect for spec-derived OAuth scope catalogs

An OpenAPI source declares the full per-operation scope catalog (PostHog
declares ~200). Those are requested broadly to unlock as many tools as
possible, but a provider that narrows the grant to the user's actual access
is healthy, not in need of reconnect. Only treat custom (user-configured)
scopes as required, never the spec catalog, via reconsentRequiredScopes.

Also fixes a garbled reconnect message in the accounts list.

Author: RhysSullivan

packages/react/src/components/accounts-section.tsx

@@ -2,7 +2,11 @@ import { useEffect, useMemo, useState } from "react";
 import { useAtomValue, useAtomSet } from "@effect/atom-react";
 import * as AsyncResult from "effect/unstable/reactivity/AsyncResult";
 import * as Exit from "effect/Exit";
-import { IntegrationSlug, type Connection, type Owner } from "@executor-js/sdk/shared";
+import {
+  IntegrationSlug,
+  type Connection,
+  type Owner,
+} from "@executor-js/sdk/shared";
 import type { IntegrationAccountHandoff } from "@executor-js/sdk/client";
 import { toast } from "sonner";
 
@@ -22,6 +26,7 @@ import {
   connectionNeedsReconsent,
   oauthReconnectPayload,
   reconnectMode,
+  reconsentRequiredScopes,
 } from "../plugins/oauth-reconnect";
 import { useOAuthPopupFlow } from "../plugins/oauth-sign-in";
 import { AddAccountModal } from "./add-account-modal";
@@ -79,7 +84,10 @@ function AccountRow(props: {
         <CardStackEntryTitle className="flex min-w-0 items-center gap-2">
           <span className="truncate">{displayLabel}</span>
           {needsReconsent ? (
-            <Badge variant="outline" className="shrink-0 border-border text-muted-foreground">
+            <Badge
+              variant="outline"
+              className="shrink-0 border-border text-muted-foreground"
+            >
               Reconnect to grant access
             </Badge>
           ) : null}
@@ -91,7 +99,8 @@ function AccountRow(props: {
         ) : null}
         {needsReconsent ? (
           <CardStackEntryDescription className="mt-1 text-xs text-muted-foreground">
-            This integration now needs access this connection wasn't granted.
+            This connection wasn't granted all the access this integration now
+            needs.
           </CardStackEntryDescription>
         ) : null}
       </CardStackEntryContent>
@@ -120,7 +129,11 @@ function AccountRow(props: {
             <DropdownMenuItem className="text-sm" onClick={props.onReconnect}>
               Reconnect
             </DropdownMenuItem>
-            <DropdownMenuItem variant="destructive" className="text-sm" onClick={props.onRemove}>
+            <DropdownMenuItem
+              variant="destructive"
+              className="text-sm"
+              onClick={props.onRemove}
+            >
               Remove
             </DropdownMenuItem>
           </DropdownMenuContent>
@@ -142,7 +155,9 @@ function OwnerAccounts(props: {
   readonly declaredScopes: readonly string[] | undefined;
 }) {
   const { integration, owner } = props;
-  const connections = useAtomValue(connectionsForIntegrationAtom({ integration, owner }));
+  const connections = useAtomValue(
+    connectionsForIntegrationAtom({ integration, owner }),
+  );
   const doRemove = useAtomSet(removeConnectionOptimistic(owner), {
     mode: "promiseExit",
   });
@@ -159,7 +174,9 @@ function OwnerAccounts(props: {
     startErrorMessage: "Failed to reconnect",
   });
 
-  const rows: readonly Connection[] = AsyncResult.isSuccess(connections) ? connections.value : [];
+  const rows: readonly Connection[] = AsyncResult.isSuccess(connections)
+    ? connections.value
+    : [];
   if (rows.length === 0) return null;
 
   const handleReconnect = async (connection: Connection) => {
@@ -168,7 +185,8 @@ function OwnerAccounts(props: {
     if (reconnectMode(connection) === "oauth") {
       const method = props.methods.find(
         (candidate: AuthMethod) =>
-          candidate.kind === "oauth" && String(candidate.template) === String(connection.template),
+          candidate.kind === "oauth" &&
+          String(candidate.template) === String(connection.template),
       );
       if (
         method?.oauth?.supportsDynamicRegistration === true ||
@@ -275,13 +293,18 @@ function OwnerAccounts(props: {
 
   return (
     <CardStack>
-      {props.showOwnerLabels ? <CardStackHeader>{ownerLabel(owner)}</CardStackHeader> : null}
+      {props.showOwnerLabels ? (
+        <CardStackHeader>{ownerLabel(owner)}</CardStackHeader>
+      ) : null}
       <CardStackContent>
         {rows.map((connection: Connection) => (
           <AccountRow
             key={`${connection.owner}:${connection.integration}:${connection.name}`}
             connection={connection}
-            needsReconsent={connectionNeedsReconsent(connection, props.declaredScopes)}
+            needsReconsent={connectionNeedsReconsent(
+              connection,
+              props.declaredScopes,
+            )}
             showOwnerLabel={props.showOwnerLabels}
             onEdit={() => props.onEdit(connection)}
             onReconnect={() => void handleReconnect(connection)}
@@ -312,10 +335,14 @@ export function AccountsSection(props: {
     removeCustomMethod,
   } = props;
   const [adding, setAdding] = useState(false);
-  const [editingConnection, setEditingConnection] = useState<Connection | null>(null);
-  const [reconnectHandoff, setReconnectHandoff] = useState<IntegrationAccountHandoff | null>(null);
+  const [editingConnection, setEditingConnection] = useState<Connection | null>(
+    null,
+  );
+  const [reconnectHandoff, setReconnectHandoff] =
+    useState<IntegrationAccountHandoff | null>(null);
   const ownerDisplay = useOwnerDisplay();
-  const canAddConnection = methods.length > 0 || createCustomMethod !== undefined;
+  const canAddConnection =
+    methods.length > 0 || createCustomMethod !== undefined;
 
   useEffect(() => {
     if (accountHandoff) {
@@ -326,11 +353,20 @@ export function AccountsSection(props: {
   // The integration's declared oauth scopes — what connections need granted. A
   // connection granted fewer is flagged to reconnect (e.g. after a service was
   // added widened the consent).
-  const declaredScopes = methods.find((m: AuthMethod) => m.kind === "oauth")?.oauth?.scopes;
+  //
+  // Spec-derived oauth scopes are the full per-operation catalog union (e.g. an
+  // OpenAPI source like PostHog declares hundreds of scopes). Those are requested
+  // broadly but not individually required: a provider that narrows the grant to
+  // the user's actual access is healthy, not in need of reconnect. So only treat
+  // CUSTOM (user-configured) scopes as required here; never the spec catalog.
+  const oauthMethod = methods.find((m: AuthMethod) => m.kind === "oauth");
+  const declaredScopes = reconsentRequiredScopes(oauthMethod);
 
   // Read both owners to decide between the grouped view and the empty CTA. The
   // grouped sub-components re-read these (effect-atom dedupes) and self-hide.
-  const orgConnections = useAtomValue(connectionsForIntegrationAtom({ integration, owner: "org" }));
+  const orgConnections = useAtomValue(
+    connectionsForIntegrationAtom({ integration, owner: "org" }),
+  );
   const userConnections = useAtomValue(
     connectionsForIntegrationAtom({ integration, owner: "user" }),
   );
@@ -341,12 +377,18 @@ export function AccountsSection(props: {
   useAtomSet(addConnectionOptimistic("user"));
 
   const totalCount = useMemo(() => {
-    const orgRows = AsyncResult.isSuccess(orgConnections) ? orgConnections.value.length : 0;
-    const userRows = AsyncResult.isSuccess(userConnections) ? userConnections.value.length : 0;
+    const orgRows = AsyncResult.isSuccess(orgConnections)
+      ? orgConnections.value.length
+      : 0;
+    const userRows = AsyncResult.isSuccess(userConnections)
+      ? userConnections.value.length
+      : 0;
     return orgRows + userRows;
   }, [orgConnections, userConnections]);
 
-  const loading = !AsyncResult.isSuccess(orgConnections) && !AsyncResult.isSuccess(userConnections);
+  const loading =
+    !AsyncResult.isSuccess(orgConnections) &&
+    !AsyncResult.isSuccess(userConnections);
 
   const modalState = reconnectHandoff ?? accountHandoff;
   const modal = (
@@ -378,7 +420,9 @@ export function AccountsSection(props: {
           onClick={() => {
             trackEvent("connection_add_opened", {
               integration_slug: String(integration),
-              has_oauth_method: methods.some((m: AuthMethod) => m.kind === "oauth"),
+              has_oauth_method: methods.some(
+                (m: AuthMethod) => m.kind === "oauth",
+              ),
               has_api_key_method: methods.some(
                 (m: AuthMethod) => m.kind !== "oauth" && m.kind !== "none",
               ),
@@ -398,7 +442,9 @@ export function AccountsSection(props: {
         </div>
       ) : totalCount === 0 ? (
         <div className="rounded-lg border border-dashed border-border/60 px-6 py-8 text-center">
-          <p className="text-sm font-medium text-foreground">No connections yet</p>
+          <p className="text-sm font-medium text-foreground">
+            No connections yet
+          </p>
           <p className="mt-1 text-sm text-muted-foreground">
             Add a connection to make this integration's tools available.
           </p>
@@ -409,7 +455,9 @@ export function AccountsSection(props: {
             onClick={() => {
               trackEvent("connection_add_opened", {
                 integration_slug: String(integration),
-                has_oauth_method: methods.some((m: AuthMethod) => m.kind === "oauth"),
+                has_oauth_method: methods.some(
+                  (m: AuthMethod) => m.kind === "oauth",
+                ),
                 has_api_key_method: methods.some(
                   (m: AuthMethod) => m.kind !== "oauth" && m.kind !== "none",
                 ),

packages/react/src/plugins/oauth-reconnect.test.ts

@@ -9,7 +9,12 @@ import {
   type Connection,
 } from "@executor-js/sdk/shared";
 
-import { missingScopes, oauthReconnectPayload, reconnectMode } from "./oauth-reconnect";
+import {
+  missingScopes,
+  oauthReconnectPayload,
+  reconnectMode,
+  reconsentRequiredScopes,
+} from "./oauth-reconnect";
 
 const connection = (overrides: Partial<Connection> = {}): Connection => ({
   owner: "user",
@@ -109,3 +114,29 @@ describe("missingScopes (Part 2 informational subset warning)", () => {
     ).toEqual([]);
   });
 });
+
+describe("reconsentRequiredScopes", () => {
+  it("treats spec-derived oauth scopes as NOT required (opportunistic catalog)", () => {
+    // An OpenAPI source (e.g. PostHog) declares the full per-operation scope
+    // catalog. A narrower grant is healthy and must not nag for reconnect.
+    expect(
+      reconsentRequiredScopes({
+        source: "spec",
+        oauth: { scopes: ["insight:read", "insight:write", "person:read"] },
+      }),
+    ).toBeUndefined();
+  });
+
+  it("keeps custom (user-configured) oauth scopes required", () => {
+    expect(
+      reconsentRequiredScopes({
+        source: "custom",
+        oauth: { scopes: ["read", "write"] },
+      }),
+    ).toEqual(["read", "write"]);
+  });
+
+  it("returns undefined when there is no oauth method", () => {
+    expect(reconsentRequiredScopes(undefined)).toBeUndefined();
+  });
+});

packages/react/src/plugins/oauth-reconnect.ts

@@ -28,7 +28,9 @@ export function reconnectMode(connection: Connection): ReconnectMode {
  *  connection are exactly the branded types `oauth.start` expects, so the same
  *  connection (owner/integration/name) is re-minted with a fresh refresh token
  *  and the widened scope union. Returns null for a non-OAuth connection. */
-export function oauthReconnectPayload(connection: Connection): OAuthStartPayload | null {
+export function oauthReconnectPayload(
+  connection: Connection,
+): OAuthStartPayload | null {
   if (connection.oauthClient == null) return null;
   return {
     client: connection.oauthClient,
@@ -59,7 +61,8 @@ const OAUTH_SCOPE_ALIASES: Readonly<Record<string, string>> = {
   "https://www.googleapis.com/auth/userinfo.profile": "profile",
 };
 
-const canonicalScope = (scope: string): string => OAUTH_SCOPE_ALIASES[scope] ?? scope;
+const canonicalScope = (scope: string): string =>
+  OAUTH_SCOPE_ALIASES[scope] ?? scope;
 
 /** Normalize a scope list: trim, canonicalize known provider aliases, drop
  *  empties, de-dupe (order-preserving). A scope set is compared as a SET —
@@ -91,8 +94,12 @@ export function missingScopes(
 
 /** The scopes a connection was actually GRANTED, parsed from its space-delimited
  *  `oauthScope` record. Empty for static creds / when the AS omitted scope. */
-export function connectionGrantedScopes(connection: Connection): readonly string[] {
-  return connection.oauthScope ? connection.oauthScope.split(/\s+/).filter(Boolean) : [];
+export function connectionGrantedScopes(
+  connection: Connection,
+): readonly string[] {
+  return connection.oauthScope
+    ? connection.oauthScope.split(/\s+/).filter(Boolean)
+    : [];
 }
 
 /** Whether an OAuth connection must RECONNECT to grant newly-needed access: the
@@ -106,5 +113,29 @@ export function connectionNeedsReconsent(
   declaredScopes: readonly string[] | undefined,
 ): boolean {
   if (connection.oauthClient == null) return false;
-  return missingScopes(declaredScopes, connectionGrantedScopes(connection)).length > 0;
+  return (
+    missingScopes(declaredScopes, connectionGrantedScopes(connection)).length >
+    0
+  );
+}
+
+/** The scopes that count as REQUIRED for a connection to be considered fully
+ *  granted, given the integration's oauth auth method.
+ *
+ *  Spec-derived oauth scopes are the full per-operation catalog union (an OpenAPI
+ *  source like PostHog declares hundreds): requested broadly to unlock as many
+ *  tools as possible, but none individually required. A provider that narrows the
+ *  grant to the user's actual access is healthy, so the spec catalog must NOT
+ *  drive a reconnect prompt. Custom (user-configured) scopes are intentional and
+ *  stay required. Feed the result to `connectionNeedsReconsent`. */
+export function reconsentRequiredScopes(
+  method:
+    | {
+        readonly source: "spec" | "custom";
+        readonly oauth?: { readonly scopes?: readonly string[] };
+      }
+    | undefined,
+): readonly string[] | undefined {
+  if (method == null || method.source === "spec") return undefined;
+  return method.oauth?.scopes;
 }