Support CIMD OAuth for API sources

Add OAuth Client ID Metadata Document (CIMD) support so an API source can be connected without Dynamic Client Registration or a manually registered app. When the authorization server advertises client_id_metadata_document_supported, the connect flow uses a public PKCE client whose client_id is this host's metadata-document URL, and the provider fetches that document to learn the client's redirect URIs. Also stops spec-derived OAuth scope catalogs (an OpenAPI source can declare hundreds of scopes) from triggering a spurious reconnect prompt when the provider grants a narrower set.

Author: RhysSullivan

packages/core/api/src/integrations/api.ts

@@ -47,9 +47,11 @@ const OAuthDescriptor = Schema.Struct({
   discoveryUrl: Schema.optional(Schema.String),
   authorizationUrl: Schema.optional(Schema.String),
   tokenUrl: Schema.optional(Schema.String),
+  resource: Schema.optional(Schema.NullOr(Schema.String)),
   scopes: Schema.optional(Schema.Array(Schema.String)),
   registrationEndpoint: Schema.optional(Schema.String),
   supportsDynamicRegistration: Schema.optional(Schema.Boolean),
+  supportsClientIdMetadataDocument: Schema.optional(Schema.Boolean),
 });
 
 /** A single declared auth method — mirrors the SDK's `AuthMethodDescriptor`. */

packages/core/api/src/oauth-popup.test.ts

@@ -235,44 +235,33 @@ describe("runOAuthCallback", () => {
     expect(received[1]!.callbackDomain).toBeNull();
   });
 
-  it("prefers `error` over `error_description` but falls back when absent", async () => {
-    const received: Array<{
-      state: string;
-      code: string | null;
-      error: string | null;
-      callbackDomain: string | null;
-    }> = [];
-    const complete = (params: {
-      state: string;
-      code: string | null;
-      error: string | null;
-      callbackDomain: string | null;
-    }) => {
-      received.push(params);
+  it("renders provider OAuth errors without invoking completeOAuth", async () => {
+    let completeCalls = 0;
+    const complete = () => {
+      completeCalls += 1;
       return Effect.succeed({
         kind: "oauth2" as const,
         accessTokenSecretId: "s",
         refreshTokenSecretId: null,
       });
     };
-    await Effect.runPromise(
-      runOAuthCallback<GoogleAuth, never, never>({
-        complete,
-        urlParams: { state: "s1", error: "access_denied" },
-        toErrorMessage: () => ({ short: "" }),
-        channelName: "c",
-      }),
-    );
-    await Effect.runPromise(
+    const html = await Effect.runPromise(
       runOAuthCallback<GoogleAuth, never, never>({
         complete,
-        urlParams: { state: "s2", error_description: "user cancelled" },
+        urlParams: {
+          state: "s1",
+          error: "invalid_scope",
+          error_description: "unknown scope wizard_session:write",
+        },
         toErrorMessage: () => ({ short: "" }),
         channelName: "c",
       }),
     );
-    expect(received[0]!.error).toBe("access_denied");
-    expect(received[1]!.error).toBe("user cancelled");
+    expect(completeCalls).toBe(0);
+    expect(html).toContain("<title>Connection failed</title>");
+    expect(html).toContain("OAuth provider rejected authorization");
+    expect(html).toContain("invalid_scope");
+    expect(html).toContain("unknown scope wizard_session:write");
   });
 
   it("renders a failure popup when completeOAuth fails and uses toErrorMessage", async () => {

packages/core/api/src/oauth-popup.ts

@@ -155,6 +155,17 @@ export type RunOAuthCallbackInput<TAuth, E, R> = {
   readonly channelName: string;
 };
 
+const providerErrorMessage = (params: OAuthCallbackUrlParams): PopupErrorMessage | null => {
+  const error = params.error ?? null;
+  const description = params.error_description ?? null;
+  const value = error ?? description;
+  if (!value) return null;
+  return {
+    short: "OAuth provider rejected authorization",
+    details: error && description && description !== error ? `${error}: ${description}` : value,
+  };
+};
+
 /**
  * Run a plugin's `completeOAuth` against URL params from the OAuth redirect,
  * wrap the success / failure in an `OAuthPopupResult`, and return the HTML
@@ -165,35 +176,49 @@ export type RunOAuthCallbackInput<TAuth, E, R> = {
  */
 export const runOAuthCallback = <TAuth, E, R>(
   input: RunOAuthCallbackInput<TAuth, E, R>,
-): Effect.Effect<string, never, R> =>
-  input
-    .complete({
-      state: input.urlParams.state,
-      code: input.urlParams.code ?? null,
-      error: input.urlParams.error ?? input.urlParams.error_description ?? null,
-      callbackDomain: input.urlParams.domain ?? input.urlParams.site ?? null,
-    })
-    .pipe(
-      Effect.map(
-        (auth): OAuthPopupResult<TAuth> => ({
-          type: OAUTH_POPUP_MESSAGE_TYPE,
-          ok: true,
-          sessionId: input.urlParams.state,
-          ...auth,
-        }),
-      ),
-      Effect.catchCause((cause) => {
-        const { short, details } = input.toErrorMessage(Cause.squash(cause));
-        return Effect.succeed<OAuthPopupResult<TAuth>>({
+): Effect.Effect<string, never, R> => {
+  const providerError = providerErrorMessage(input.urlParams);
+  const result =
+    providerError == null
+      ? input
+          .complete({
+            state: input.urlParams.state,
+            code: input.urlParams.code ?? null,
+            error: null,
+            callbackDomain: input.urlParams.domain ?? input.urlParams.site ?? null,
+          })
+          .pipe(
+            Effect.map(
+              (auth): OAuthPopupResult<TAuth> => ({
+                type: OAUTH_POPUP_MESSAGE_TYPE,
+                ok: true,
+                sessionId: input.urlParams.state,
+                ...auth,
+              }),
+            ),
+          )
+      : Effect.succeed<OAuthPopupResult<TAuth>>({
           type: OAUTH_POPUP_MESSAGE_TYPE,
           ok: false,
           sessionId: input.urlParams.state ?? null,
-          error: short,
-          ...(details && details !== short ? { errorDetails: details } : {}),
+          error: providerError.short,
+          ...(providerError.details ? { errorDetails: providerError.details } : {}),
         });
-      }),
-      Effect.tap((result) =>
-        Effect.sync(() => completionListener?.(result as OAuthPopupResult<unknown>)),
-      ),
-      Effect.map((result) => popupDocument(result, input.channelName)),
-    );
+
+  return result.pipe(
+    Effect.catchCause((cause) => {
+      const { short, details } = input.toErrorMessage(Cause.squash(cause));
+      return Effect.succeed<OAuthPopupResult<TAuth>>({
+        type: OAUTH_POPUP_MESSAGE_TYPE,
+        ok: false,
+        sessionId: input.urlParams.state ?? null,
+        error: short,
+        ...(details && details !== short ? { errorDetails: details } : {}),
+      });
+    }),
+    Effect.tap((result) =>
+      Effect.sync(() => completionListener?.(result as OAuthPopupResult<unknown>)),
+    ),
+    Effect.map((result) => popupDocument(result, input.channelName)),
+  );
+};

packages/core/api/src/oauth/api.ts

@@ -209,6 +209,7 @@ const ProbeResponse = Schema.Struct({
   scopesSupported: Schema.optional(Schema.Array(Schema.String)),
   registrationEndpoint: Schema.optional(Schema.NullOr(Schema.String)),
   tokenEndpointAuthMethodsSupported: Schema.optional(Schema.Array(Schema.String)),
+  clientIdMetadataDocumentSupported: Schema.optional(Schema.Boolean),
 });
 
 // ---------------------------------------------------------------------------

packages/core/sdk/src/core-tools.ts

@@ -293,6 +293,7 @@ const OAuthProbeOutput = Schema.Struct({
   scopesSupported: Schema.optional(Schema.Array(Schema.String)),
   registrationEndpoint: Schema.optional(Schema.NullOr(Schema.String)),
   tokenEndpointAuthMethodsSupported: Schema.optional(Schema.Array(Schema.String)),
+  clientIdMetadataDocumentSupported: Schema.optional(Schema.Boolean),
 });
 const OAuthStartInput = Schema.Struct({
   client: Schema.String,
@@ -794,6 +795,7 @@ export const coreToolsPlugin = definePlugin((options: CoreToolsPluginOptions = {
               scopesSupported: result.scopesSupported,
               registrationEndpoint: result.registrationEndpoint ?? null,
               tokenEndpointAuthMethodsSupported: result.tokenEndpointAuthMethodsSupported,
+              clientIdMetadataDocumentSupported: result.clientIdMetadataDocumentSupported,
             })),
         }),
         tool({

packages/core/sdk/src/integration.ts

@@ -52,11 +52,16 @@ export interface AuthMethodOAuthDescriptor {
   readonly discoveryUrl?: string;
   readonly authorizationUrl?: string;
   readonly tokenUrl?: string;
+  readonly resource?: string | null;
   readonly scopes?: readonly string[];
   readonly registrationEndpoint?: string;
   /** True when the integration is known to support RFC 7591 dynamic client
    *  registration (drives the transparent auto-register connect flow). */
   readonly supportsDynamicRegistration?: boolean;
+  /** True when the authorization server supports Client ID Metadata Document
+   *  clients. The UI can create a local public OAuth client using this host's
+   *  metadata-document URL as `client_id`, with no provider app registration. */
+  readonly supportsClientIdMetadataDocument?: boolean;
 }
 
 /** A single declared auth method on an integration's catalog response. */

packages/core/sdk/src/oauth-client.ts

@@ -32,7 +32,15 @@ export interface OAuthAuthentication {
   readonly kind: "oauth2";
   readonly authorizationUrl: string;
   readonly tokenUrl: string;
+  /** RFC 8707 Resource Indicator to bind the OAuth flow to this protected
+   *  resource, when discovered from protected-resource metadata. */
+  readonly resource?: string | null;
   readonly scopes: readonly string[];
+  /** True when the authorization server supports OAuth Client ID Metadata
+   *  Document (CIMD). The local OAuth client is then a public PKCE client whose
+   *  `client_id` is this host's metadata-document URL, not a provider-side
+   *  registered app id. */
+  readonly supportsClientIdMetadataDocument?: boolean;
 }
 
 /** A registered OAuth app — pure app identity: clientId/secret + its endpoints.
@@ -138,6 +146,9 @@ export interface OAuthProbeResult {
   /** RFC 8414 `token_endpoint_auth_methods_supported`. Surfaced so DCR can pick
    *  a public ("none") client when the server allows it. */
   readonly tokenEndpointAuthMethodsSupported?: readonly string[];
+  /** Draft OAuth Client ID Metadata Document support, advertised by providers
+   *  such as PostHog as `client_id_metadata_document_supported`. */
+  readonly clientIdMetadataDocumentSupported?: boolean;
 }
 
 /** Mint an OAuth client via RFC 7591 Dynamic Client Registration and persist it.

packages/core/sdk/src/oauth-discovery.ts

@@ -72,6 +72,7 @@ export const OAuthAuthorizationServerMetadataSchema = Schema.Struct({
   authorization_endpoint: Schema.String,
   token_endpoint: Schema.String,
   registration_endpoint: Schema.optional(Schema.String),
+  client_id_metadata_document_supported: Schema.optional(Schema.Boolean),
   scopes_supported: Schema.optional(StringArray),
   response_types_supported: Schema.optional(StringArray),
   grant_types_supported: Schema.optional(StringArray),

packages/core/sdk/src/oauth-scope-union.test.ts

@@ -220,6 +220,44 @@ describe("oauth.start integration-driven scopes", () => {
       ),
   );
 
+  it.effect("filters stale declared scopes against authorization-server metadata", () =>
+    Effect.scoped(
+      Effect.gen(function* () {
+        const server = yield* serveOAuthTestServer({ scopes: ["calendar", "drive"] });
+        const plugins = [
+          memoryCredentialsPlugin(),
+          makeScopePlugin({ scopes: ["calendar", "stale_scope", "drive"] }),
+        ] as const;
+        const { executor } = yield* makeTestWorkspaceHarness({ plugins });
+        yield* executor.acme.seed();
+
+        yield* executor.oauth.createClient({
+          owner: "org",
+          slug: CLIENT,
+          authorizationUrl: server.authorizationEndpoint,
+          tokenUrl: server.tokenEndpoint,
+          grant: "authorization_code",
+          clientId: "test-client",
+          clientSecret: "test-secret",
+          resource: server.resourceUrl,
+        });
+
+        const started = yield* executor.oauth.start({
+          owner: "org",
+          client: CLIENT,
+          clientOwner: "org",
+          name: ConnectionName.make("main"),
+          integration: INTEG,
+          template: TEMPLATE,
+        });
+        expect(started.status).toBe("redirect");
+        if (started.status !== "redirect") return;
+
+        expect(scopesFromAuthorizeUrl(started.authorizationUrl)).toEqual(["calendar", "drive"]);
+      }),
+    ),
+  );
+
   it.effect("(b) when the integration declares no oauth scopes, start requests none", () =>
     Effect.scoped(
       Effect.gen(function* () {

packages/core/sdk/src/oauth-service.ts

@@ -180,6 +180,15 @@ const refreshItemIdFor = (accessId: string): string => `${accessId}:refresh`;
 /** Order-preserving de-duplication of a scope list. */
 const dedupeScopes = (scopes: readonly string[]): readonly string[] => [...new Set(scopes)];
 
+const intersectScopes = (
+  requested: readonly string[],
+  supported: readonly string[] | undefined,
+): readonly string[] => {
+  if (!supported || supported.length === 0) return requested;
+  const supportedSet = new Set(supported);
+  return requested.filter((scope) => supportedSet.has(scope));
+};
+
 const recordedOAuthScope = (
   token: OAuth2TokenResponse,
   requestedScopes: readonly string[],
@@ -354,6 +363,28 @@ export const makeOAuthService = (deps: OAuthServiceDeps): OAuthService => {
   // EXPLICIT — no localhost default. `null` means this executor has no OAuth
   // callback; redirect-requiring flows fail loudly via `requireRedirectUri`.
   const redirectUri = deps.redirectUri;
+  const discoveryOptions = { endpointUrlPolicy: deps.endpointUrlPolicy };
+
+  const filterAuthorizationCodeScopes = (
+    client: LoadedOAuthClient,
+    requestedScopes: readonly string[],
+  ): Effect.Effect<readonly string[], never> =>
+    Effect.gen(function* () {
+      if (requestedScopes.length === 0) return requestedScopes;
+      const resource = client.resource
+        ? yield* discoverProtectedResourceMetadata(client.resource, discoveryOptions).pipe(
+            Effect.catch(() => Effect.succeed(null)),
+            Effect.provide(httpClientLayer),
+          )
+        : null;
+      const issuer =
+        resource?.metadata.authorization_servers?.[0] ?? new URL(client.authorizationUrl).origin;
+      const as = yield* discoverAuthorizationServerMetadata(issuer, discoveryOptions).pipe(
+        Effect.catch(() => Effect.succeed(null)),
+        Effect.provide(httpClientLayer),
+      );
+      return intersectScopes(requestedScopes, as?.metadata.scopes_supported);
+    }).pipe(Effect.catch(() => Effect.succeed(requestedScopes)));
 
   // Caps on server-controlled discovery input — a hostile or buggy server must
   // not be able to hang `oauth.start` or overflow the authorize URL.
@@ -818,6 +849,14 @@ export const makeOAuthService = (deps: OAuthServiceDeps): OAuthService => {
           message: REDIRECT_URI_REQUIRED_MESSAGE,
         });
       }
+      // Prune stale DECLARED scopes against the AS's advertised set, but leave
+      // resource-discovered scopes untouched: an RFC 9728 `scopes_supported`
+      // list is already authoritative (§7.2) and must not be re-narrowed by a
+      // divergent authorization server.
+      const authorizationRequestedScopes =
+        scopePolicy.kind === "discover"
+          ? requestedScopes
+          : yield* filterAuthorizationCodeScopes(client, requestedScopes);
 
       // authorization_code: persist a session + build the authorize URL.
       const verifier = createPkceCodeVerifier();
@@ -843,11 +882,15 @@ export const makeOAuthService = (deps: OAuthServiceDeps): OAuthService => {
           redirect_url: flowRedirectUri,
           pkce_verifier: verifier,
           identity_label: input.identityLabel ?? null,
-          // Persist the requested scope set (the integration's declared or
-          // discovered scopes) so `complete`'s recorded-scope fallback reflects
-          // exactly what was requested when the AS omits `scope`, without
-          // re-resolving it at completion.
-          payload: { owner: input.owner, clientOwner: input.clientOwner, requestedScopes },
+          // Persist the requested scope set (declared ∪ client, filtered to the
+          // authorization-code flow) so `complete`'s recorded-scope fallback
+          // reflects exactly what was requested when the AS omits `scope`,
+          // without re-resolving the integration's declared scopes at completion.
+          payload: {
+            owner: input.owner,
+            clientOwner: input.clientOwner,
+            requestedScopes: authorizationRequestedScopes,
+          },
           expires_at: expiresAt,
           created_at: now,
         }),
@@ -859,7 +902,7 @@ export const makeOAuthService = (deps: OAuthServiceDeps): OAuthService => {
             authorizationUrl: client.authorizationUrl,
             clientId: client.clientId,
             redirectUrl: flowRedirectUri,
-            scopes: requestedScopes,
+            scopes: authorizationRequestedScopes,
             state: providerState,
             codeChallenge: challenge,
             resource: client.resource ?? undefined,
@@ -1127,6 +1170,8 @@ export const makeOAuthService = (deps: OAuthServiceDeps): OAuthService => {
         scopesSupported: resource?.metadata.scopes_supported ?? as.metadata.scopes_supported,
         registrationEndpoint: as.metadata.registration_endpoint ?? null,
         tokenEndpointAuthMethodsSupported: as.metadata.token_endpoint_auth_methods_supported,
+        clientIdMetadataDocumentSupported:
+          as.metadata.client_id_metadata_document_supported === true,
       } satisfies OAuthProbeResult;
     }).pipe(Effect.provide(httpClientLayer));