feat(plugins): dynamic OAuth clients, plus Notion, Slack and Gmail

.agent-marketplace.json

@@ -15,7 +15,7 @@
 			},
 			"category": "development",
 			"source": "./plugins/github",
-			"version": "1.0.0"
+			"version": "1.0.1"
 		},
 		{
 			"name": "linear",
@@ -25,7 +25,37 @@
 			},
 			"category": "productivity",
 			"source": "./plugins/linear",
-			"version": "1.4.0"
+			"version": "1.5.2"
+		},
+		{
+			"name": "notion",
+			"description": "Search, read, and write your Notion workspace: pages, databases, and comments.",
+			"author": {
+				"name": "Superset"
+			},
+			"category": "productivity",
+			"source": "./plugins/notion",
+			"version": "1.0.2"
+		},
+		{
+			"name": "slack",
+			"description": "Search, read, and post across your Slack workspace: channels, DMs, and threads.",
+			"author": {
+				"name": "Superset"
+			},
+			"category": "communication",
+			"source": "./plugins/slack",
+			"version": "1.2.3"
+		},
+		{
+			"name": "gmail",
+			"description": "Read, search, send, and organize mail in your Gmail account.",
+			"author": {
+				"name": "Superset"
+			},
+			"category": "communication",
+			"source": "./plugins/gmail",
+			"version": "1.1.5"
 		}
 	],
 	"featured": ["github", "linear"],

.env.example

@@ -148,6 +148,27 @@ POSTHOG_PROJECT_ID=
 GOOGLE_SEARCH_CONSOLE_SERVICE_ACCOUNT=
 GOOGLE_SEARCH_CONSOLE_SITE_URL=sc-domain:superset.sh
 
+# -----------------------------------------------------------------------------
+# Plugin OAuth (optional — falls back to NEXT_PUBLIC_API_URL)
+# Origin an authorization server fetches a plugin's client id metadata document
+# from. Setting this alone does not make local dev work: redirect_uris in that
+# document come from NEXT_PUBLIC_API_URL, and the document declares
+# application_type "web", so a loopback redirect is rejected. To connect a
+# dynamic-client plugin locally, point one public https tunnel at the API and
+# set NEXT_PUBLIC_API_URL to it; this variable is for the case where the two
+# origins genuinely differ.
+# -----------------------------------------------------------------------------
+PLUGIN_CLIENT_METADATA_BASE_URL=
+
+# -----------------------------------------------------------------------------
+# Connector OAuth clients
+# Only for connectors whose requires_env names a pair that no other feature
+# already sets — the rest reuse the integration clients above. Without them the
+# connector still lists, but Connect answers "not configured".
+# -----------------------------------------------------------------------------
+PLUGIN_GITHUB_CLIENT_ID=
+PLUGIN_GITHUB_CLIENT_SECRET=
+
 # -----------------------------------------------------------------------------
 # Sentry Error Tracking
 # -----------------------------------------------------------------------------

.env.local.example

@@ -135,6 +135,27 @@ POSTHOG_PROJECT_ID=00000
 GOOGLE_SEARCH_CONSOLE_SERVICE_ACCOUNT=
 GOOGLE_SEARCH_CONSOLE_SITE_URL=sc-domain:superset.sh
 
+# -----------------------------------------------------------------------------
+# Plugin OAuth (optional — falls back to NEXT_PUBLIC_API_URL)
+# Origin an authorization server fetches a plugin's client id metadata document
+# from. Setting this alone does not make local dev work: redirect_uris in that
+# document come from NEXT_PUBLIC_API_URL, and the document declares
+# application_type "web", so a loopback redirect is rejected. To connect a
+# dynamic-client plugin locally, point one public https tunnel at the API and
+# set NEXT_PUBLIC_API_URL to it; this variable is for the case where the two
+# origins genuinely differ.
+# -----------------------------------------------------------------------------
+PLUGIN_CLIENT_METADATA_BASE_URL=
+
+# -----------------------------------------------------------------------------
+# Connector OAuth clients
+# Only for connectors whose requires_env names a pair that no other feature
+# already sets — the rest reuse the integration clients above. Without them the
+# connector still lists, but Connect answers "not configured".
+# -----------------------------------------------------------------------------
+PLUGIN_GITHUB_CLIENT_ID=
+PLUGIN_GITHUB_CLIENT_SECRET=
+
 # -----------------------------------------------------------------------------
 # Sentry Error Tracking (optional — leave blank to disable)
 # -----------------------------------------------------------------------------

.github/workflows/deploy-preview.yml

@@ -151,6 +151,9 @@ jobs:
           NEXT_PUBLIC_POSTHOG_HOST: ${{ secrets.NEXT_PUBLIC_POSTHOG_HOST }}
           POSTHOG_API_KEY: ${{ secrets.POSTHOG_API_KEY }}
           GOOGLE_SEARCH_CONSOLE_SERVICE_ACCOUNT: ${{ secrets.GOOGLE_SEARCH_CONSOLE_SERVICE_ACCOUNT }}
+          PLUGIN_CLIENT_METADATA_BASE_URL: ${{ secrets.PLUGIN_CLIENT_METADATA_BASE_URL }}
+          PLUGIN_GITHUB_CLIENT_ID: ${{ secrets.PLUGIN_GITHUB_CLIENT_ID }}
+          PLUGIN_GITHUB_CLIENT_SECRET: ${{ secrets.PLUGIN_GITHUB_CLIENT_SECRET }}
           POSTHOG_PROJECT_ID: ${{ secrets.POSTHOG_PROJECT_ID }}
           KV_REST_API_URL: ${{ secrets.KV_REST_API_URL }}
           KV_REST_API_TOKEN: ${{ secrets.KV_REST_API_TOKEN }}
@@ -225,6 +228,9 @@ jobs:
             --env NEXT_PUBLIC_POSTHOG_HOST=$NEXT_PUBLIC_POSTHOG_HOST \
             --env POSTHOG_API_KEY=$POSTHOG_API_KEY \
             --env GOOGLE_SEARCH_CONSOLE_SERVICE_ACCOUNT="$GOOGLE_SEARCH_CONSOLE_SERVICE_ACCOUNT" \
+            --env PLUGIN_CLIENT_METADATA_BASE_URL="$PLUGIN_CLIENT_METADATA_BASE_URL" \
+            --env PLUGIN_GITHUB_CLIENT_ID="$PLUGIN_GITHUB_CLIENT_ID" \
+            --env PLUGIN_GITHUB_CLIENT_SECRET="$PLUGIN_GITHUB_CLIENT_SECRET" \
             --env POSTHOG_PROJECT_ID=$POSTHOG_PROJECT_ID \
             --env KV_REST_API_URL=$KV_REST_API_URL \
             --env KV_REST_API_TOKEN=$KV_REST_API_TOKEN \

.github/workflows/deploy-production.yml

@@ -138,6 +138,9 @@ jobs:
           STRIPE_SECRET_KEY: ${{ secrets.STRIPE_SECRET_KEY }}
           MERCURY_API_TOKEN: ${{ secrets.MERCURY_API_TOKEN }}
           GOOGLE_SEARCH_CONSOLE_SERVICE_ACCOUNT: ${{ secrets.GOOGLE_SEARCH_CONSOLE_SERVICE_ACCOUNT }}
+          PLUGIN_CLIENT_METADATA_BASE_URL: ${{ secrets.PLUGIN_CLIENT_METADATA_BASE_URL }}
+          PLUGIN_GITHUB_CLIENT_ID: ${{ secrets.PLUGIN_GITHUB_CLIENT_ID }}
+          PLUGIN_GITHUB_CLIENT_SECRET: ${{ secrets.PLUGIN_GITHUB_CLIENT_SECRET }}
           STRIPE_WEBHOOK_SECRET: ${{ secrets.STRIPE_WEBHOOK_SECRET }}
           STRIPE_PRO_MONTHLY_PRICE_ID: ${{ secrets.STRIPE_PRO_MONTHLY_PRICE_ID }}
           STRIPE_PRO_YEARLY_PRICE_ID: ${{ secrets.STRIPE_PRO_YEARLY_PRICE_ID }}
@@ -224,6 +227,9 @@ jobs:
             --env STRIPE_SECRET_KEY=$STRIPE_SECRET_KEY \
             --env MERCURY_API_TOKEN=$MERCURY_API_TOKEN \
             --env GOOGLE_SEARCH_CONSOLE_SERVICE_ACCOUNT="$GOOGLE_SEARCH_CONSOLE_SERVICE_ACCOUNT" \
+            --env PLUGIN_CLIENT_METADATA_BASE_URL="$PLUGIN_CLIENT_METADATA_BASE_URL" \
+            --env PLUGIN_GITHUB_CLIENT_ID="$PLUGIN_GITHUB_CLIENT_ID" \
+            --env PLUGIN_GITHUB_CLIENT_SECRET="$PLUGIN_GITHUB_CLIENT_SECRET" \
             --env STRIPE_WEBHOOK_SECRET=$STRIPE_WEBHOOK_SECRET \
             --env STRIPE_PRO_MONTHLY_PRICE_ID=$STRIPE_PRO_MONTHLY_PRICE_ID \
             --env STRIPE_PRO_YEARLY_PRICE_ID=$STRIPE_PRO_YEARLY_PRICE_ID \

AGENTS.md

@@ -94,8 +94,11 @@ Desktop, host-service, and cli share one version; cut releases on a dedicated br
 
 ## Plugins
 
-First-party plugins live in `plugins/<name>/`: a `plugin.json` manifest, `skills/`, and optionally
-an MCP server. A release is the git tag `<name>@<version>` on this repo — that tree is what a host
+First-party plugins live in `plugins/<name>/`: a `plugin.json` manifest and `skills/`. A plugin
+ships no code — agents reach its tools through `/mcp/plugins/<marketplace>/<plugin>` on the API,
+which proxies to the vendor's MCP server or, for the plugins named in the `SUPERSET_HOSTED_PLUGINS` constant,
+serves them from `packages/trpc/src/router/plugins/servers/`. A release is the git tag
+`<name>@<version>` on this repo — that tree is what a host
 downloads — and `packages/shared/src/plugins/manifests.generated.ts` is the bundle the API resolves
 against, which is generated and must never be hand-edited. Change the source, then
 `superset plugins publish <name> --bump patch`, which rewrites the marketplace entry in

apps/api/src/app/api/connectors/[connector]/client-metadata/route.ts

@@ -0,0 +1,31 @@
+import { getConnector } from "@superset/shared/connectors";
+import { clientMetadataUrl, redirectUriFor } from "@superset/trpc/connectors";
+
+export async function GET(
+	_request: Request,
+	{ params }: { params: Promise<{ connector: string }> },
+) {
+	const { connector: slug } = await params;
+	if (!getConnector(slug)) {
+		return Response.json({ error: "Unknown connector" }, { status: 404 });
+	}
+
+	return Response.json(
+		{
+			client_id: clientMetadataUrl(slug),
+			client_name: "Superset",
+			client_uri: "https://superset.sh",
+			redirect_uris: [redirectUriFor(slug)],
+			grant_types: ["authorization_code", "refresh_token"],
+			response_types: ["code"],
+			token_endpoint_auth_method: "none",
+			application_type: "web",
+		},
+		{
+			headers: {
+				"cache-control": "public, max-age=3600",
+				"content-type": "application/json",
+			},
+		},
+	);
+}

apps/api/src/app/api/connectors/[connector]/connect/route.ts

@@ -0,0 +1,91 @@
+import type { ConnectorMethod } from "@superset/shared/connectors";
+import {
+	authorizeUrl,
+	connectorMethod,
+	createCodeVerifier,
+	MissingConnectorEnvError,
+	redirectUriFor,
+	requireConnector,
+	resolveEndpoints,
+	UnknownConnectorError,
+} from "@superset/trpc/connectors";
+import { encryptSecret } from "@superset/trpc/integrations/plugins";
+
+import { env } from "@/env";
+import { requireOrgMember } from "@/lib/integrations/requireOrgMember";
+import { createSignedState } from "@/lib/oauth-state";
+
+export const STATE_COOKIE = "connector_oauth_state";
+
+export async function GET(
+	request: Request,
+	{ params }: { params: Promise<{ connector: string }> },
+) {
+	const { connector: slug } = await params;
+	const member = await requireOrgMember(request);
+	if (member instanceof Response) return member;
+
+	// Same reason as the callback: the generic connect page covers every
+	// connector, `/integrations/<slug>` only the seven older ones.
+	const connectUrl = `${env.NEXT_PUBLIC_WEB_URL}/connect/${slug}`;
+	const requested = new URL(request.url).searchParams.get("method");
+
+	let method: ConnectorMethod;
+	try {
+		const connector = requireConnector(slug);
+		method = connectorMethod(
+			connector,
+			(requested as ConnectorMethod["type"] | null) ?? undefined,
+		);
+	} catch (error) {
+		if (error instanceof UnknownConnectorError)
+			return Response.json({ error: "Unknown connector" }, { status: 404 });
+		throw error;
+	}
+
+	if (method.type === "api_key")
+		return Response.json(
+			{ error: "This method takes inputs, not a redirect" },
+			{ status: 400 },
+		);
+
+	let target: string;
+	let state: string;
+	try {
+		const redirect = redirectUriFor(slug);
+		const wantsPkce =
+			method.type === "oauth2" &&
+			(await resolveEndpoints(slug, method, redirect)).pkce;
+		const codeVerifier = wantsPkce ? createCodeVerifier() : null;
+		state = codeVerifier
+			? createSignedState({
+					organizationId: member.organizationId,
+					userId: member.userId,
+					codeVerifier: await encryptSecret(codeVerifier),
+				})
+			: member.state;
+
+		target = (
+			await authorizeUrl(slug, method, {
+				redirectUri: redirect,
+				state,
+				codeVerifier,
+			})
+		).url;
+	} catch (error) {
+		if (error instanceof MissingConnectorEnvError) {
+			console.error(`[connectors/${slug}] ${error.message}`);
+			return Response.redirect(`${connectUrl}?error=not_configured`);
+		}
+		throw error;
+	}
+
+	const secure = env.NEXT_PUBLIC_API_URL.startsWith("https") ? " Secure;" : "";
+	return new Response(null, {
+		status: 302,
+		headers: {
+			Location: target,
+			"Set-Cookie": `${STATE_COOKIE}=${state}; HttpOnly;${secure} SameSite=Lax; Path=/api/connectors; Max-Age=600`,
+		},
+	});
+}

apps/api/src/app/api/connectors/callback/[connector]/route.ts

@@ -0,0 +1,117 @@
+import type { ConnectorMethod } from "@superset/shared/connectors";
+import {
+	connectorMethod,
+	exchangeCode,
+	probeIdentity,
+	redirectUriFor,
+	requireConnector,
+	UnknownConnectorError,
+	upsertConnection,
+} from "@superset/trpc/connectors";
+import { decryptSecret } from "@superset/trpc/integrations/plugins";
+import { STATE_COOKIE } from "@/app/api/connectors/[connector]/connect/route";
+import { env } from "@/env";
+import { resolveCallback } from "@/lib/integrations/resolveCallback";
+import { connectorStateSchema, verifySignedState } from "@/lib/oauth-state";
+
+function callbackParams(method: ConnectorMethod): string[] {
+	if (method.type === "oauth2") return ["code"];
+	if (method.type === "app_install" || method.type === "admin_consent")
+		return [...method.callback_params];
+	return [];
+}
+
+function stateCookie(request: Request): string | null {
+	const cookie = request.headers.get("cookie") ?? "";
+	const match = cookie.match(new RegExp(`(?:^|;\\s*)${STATE_COOKIE}=([^;]+)`));
+	return match?.[1] ?? null;
+}
+
+export async function GET(
+	request: Request,
+	{ params }: { params: Promise<{ connector: string }> },
+) {
+	const { connector: slug } = await params;
+	// The generic connect page exists for every connector; `/integrations/<slug>`
+	// only exists for the seven that predate the registry, so a new connector
+	// would 404 the moment someone finished authorizing it.
+	const connectUrl = `${env.NEXT_PUBLIC_WEB_URL}/connect/${slug}`;
+	const web = (query: string) => Response.redirect(`${connectUrl}${query}`);
+
+	let connector: ReturnType<typeof requireConnector>;
+	let method: ConnectorMethod;
+	try {
+		connector = requireConnector(slug);
+		method = connectorMethod(connector);
+	} catch (error) {
+		if (error instanceof UnknownConnectorError)
+			return Response.json({ error: "Unknown connector" }, { status: 404 });
+		throw error;
+	}
+
+	const callback = await resolveCallback(request, {
+		params: callbackParams(method),
+		redirect: (error) => web(`?error=${error}`),
+		stateFrom: method.type === "app_install" ? stateCookie : undefined,
+	});
+	if (callback instanceof Response) return callback;
+
+	// The signed state proves who asked, not who is answering. Without this the
+	// authorization code a victim approves can be paired with a state minted by
+	// an attacker, binding the victim's account to the attacker's connection.
+	if (method.type !== "app_install") {
+		const query = new URL(request.url).searchParams.get("state");
+		if (!query || query !== stateCookie(request))
+			return web("?error=invalid_state");
+	}
+
+	try {
+		const rawState =
+			method.type === "app_install"
+				? stateCookie(request)
+				: new URL(request.url).searchParams.get("state");
+		const carried = rawState
+			? verifySignedState(rawState, connectorStateSchema)
+			: null;
+		const codeVerifier = carried?.codeVerifier
+			? await decryptSecret(carried.codeVerifier)
+			: null;
+
+		const tokens = await exchangeCode(slug, method, {
+			code: callback.params.code ?? "",
+			redirectUri: redirectUriFor(slug),
+			codeVerifier,
+			params: callback.params,
+			issuer: new URL(request.url).searchParams.get("iss"),
+		});
+
+		const identity = await probeIdentity(
+			slug,
+			method,
+			tokens.accessToken,
+			callback.params,
+		);
+
+		const result = await upsertConnection({
+			connector,
+			slug,
+			authMethod: method.type,
+			organizationId: callback.organizationId,
+			userId: callback.userId,
+			tokens,
+			identity,
+		});
+
+		if (result.conflict) {
+			const owner = result.conflict.ownerEmail
+				? `&owner=${encodeURIComponent(result.conflict.ownerEmail)}`
+				: "";
+			return web(`?error=account_already_linked${owner}`);
+		}
+	} catch (error) {
+		console.error(`[connectors/${slug}] callback failed:`, error);
+		return web("?error=token_exchange_failed");
+	}
+
+	return web("?connected=1");
+}