fix(core-tools): include org slug in connection handoff URLs

RhysSullivan · RhysSullivan · commit 694a6469cb02 · 2026-06-22T18:16:07.000-07:00
The agentic connection handoff (connections.createHandoff) emitted a bare
/integrations/&lt;id&gt; path with no org slug, so a user in multiple orgs could
land in whatever org the browser last canonicalized to rather than the one
the executor is bound to. Thread the resolved org's slug from the identity
through a request-scoped service (RequestOrgSlug) into the URL builder,
emitting /&lt;org-slug&gt;/integrations/&lt;id&gt;. Falls back to the bare path when no
slug is known (CLI, local, non-request callers).
diff --git a/apps/cloud/src/auth/workos-auth-provider.ts b/apps/cloud/src/auth/workos-auth-provider.ts
@@ -137,6 +137,7 @@ const resolveJwtPrincipal = (token: string, jwt: JwtBearerConfig) =>
       accountId: verified.accountId,
       organizationId: org.id,
       organizationName: org.name,
+      organizationSlug: org.slug,
       email: "",
       name: null,
       avatarUrl: null,
@@ -183,6 +184,7 @@ export const resolveApiKeyPrincipal = (request: Request, jwt: JwtBearerConfig |
       accountId: principal.accountId,
       organizationId: org.id,
       organizationName: org.name,
+      organizationSlug: org.slug,
       email: "",
       name: null,
       avatarUrl: null,
@@ -211,6 +213,7 @@ export const resolveSessionPrincipal = (request: Request) =>
       accountId: session.userId,
       organizationId: org.id,
       organizationName: org.name,
+      organizationSlug: org.slug,
       email: session.email,
       name: sealedSessionDisplayName(session),
       avatarUrl: session.avatarUrl ?? null,
diff --git a/apps/cloud/src/mcp/session-durable-object.ts b/apps/cloud/src/mcp/session-durable-object.ts
@@ -170,6 +170,7 @@ export class McpSessionDO extends McpSessionDOBase<CloudSessionDbHandle> {
       return {
         organizationId: org.id,
         organizationName: org.name,
+        organizationSlug: org.slug,
         userId: token.userId,
         elicitationMode: token.elicitationMode,
       } satisfies SessionMeta;
diff --git a/apps/host-cloudflare/src/auth/cloudflare-access.ts b/apps/host-cloudflare/src/auth/cloudflare-access.ts
@@ -41,6 +41,7 @@ export const principalFromAccessClaims = (
     accountId: sub || email || commonName,
     organizationId: config.organizationId,
     organizationName: config.organizationName,
+    organizationSlug: config.organizationSlug,
     email,
     name: typeof nameClaim === "string" ? nameClaim : commonName || null,
     avatarUrl: null,
@@ -68,6 +69,7 @@ export const makeAccessVerifier = (config: CloudflareConfig) => {
     accountId: "dev",
     organizationId: config.organizationId,
     organizationName: config.organizationName,
+    organizationSlug: config.organizationSlug,
     email: config.adminEmails[0] ?? "dev@local",
     name: "Dev",
     avatarUrl: null,
diff --git a/apps/host-cloudflare/src/mcp/session-durable-object.ts b/apps/host-cloudflare/src/mcp/session-durable-object.ts
@@ -59,6 +59,7 @@ export class McpSessionDO extends McpSessionDOBase<CfSessionDbHandle> {
     return Effect.succeed({
       organizationId: token.organizationId,
       organizationName: this.cfConfig.organizationName,
+      organizationSlug: this.cfConfig.organizationSlug,
       userId: token.userId,
       elicitationMode: token.elicitationMode,
     } satisfies SessionMeta);
diff --git a/apps/host-selfhost/src/auth/identity.ts b/apps/host-selfhost/src/auth/identity.ts
@@ -42,7 +42,7 @@ const bearerToken = (headers: Headers): string | undefined => {
 export const betterAuthIdentityLayer: Layer.Layer<IdentityProvider, never, BetterAuth> =
   Layer.effect(IdentityProvider)(
     Effect.gen(function* () {
-      const { auth, organizationId, organizationName } = yield* BetterAuth;
+      const { auth, organizationId, organizationName, organizationSlug } = yield* BetterAuth;
       return IdentityProvider.of({
         authenticate: (request) =>
           Effect.gen(function* () {
@@ -70,6 +70,7 @@ export const betterAuthIdentityLayer: Layer.Layer<IdentityProvider, never, Bette
               accountId: resolved.user.id,
               organizationId: resolvedOrganizationId,
               organizationName,
+              organizationSlug,
               email: resolved.user.email,
               name: resolved.user.name ?? null,
               avatarUrl: resolved.user.image ?? null,
diff --git a/apps/host-selfhost/src/mcp/auth.ts b/apps/host-selfhost/src/mcp/auth.ts
@@ -80,7 +80,7 @@ export const selfHostMcpAuth: Layer.Layer<McpAuthProvider, never, BetterAuth | I
   Layer.effect(
     McpAuthProvider,
     Effect.gen(function* () {
-      const { auth, organizationId, organizationName } = yield* BetterAuth;
+      const { auth, organizationId, organizationName, organizationSlug } = yield* BetterAuth;
       const fallback = yield* IdentityProvider;
 
       const asMetadata = oAuthDiscoveryMetadata(auth);
@@ -121,6 +121,7 @@ export const selfHostMcpAuth: Layer.Layer<McpAuthProvider, never, BetterAuth | I
             // the seeded org (same default as the cookie/api-key path).
             organizationId,
             organizationName,
+            organizationSlug,
             email: user.email ?? "",
             name: user.name ?? null,
             avatarUrl: user.image ?? null,
diff --git a/e2e/scenarios/connect-handoff.test.ts b/e2e/scenarios/connect-handoff.test.ts
@@ -7,7 +7,10 @@
 //
 //   1. MCP `execute` → `openapi.addSpec` registers the emulated Resend API
 //   2. MCP `execute` → `connections.createHandoff` returns the browser URL
-//   3. The URL's origin must be THIS deployment (not a hardcoded host)
+//   3. The URL's origin must be THIS deployment (not a hardcoded host) AND it
+//      must carry the bound org's slug (`/<slug>/integrations/…`), so a user in
+//      several orgs lands in the exact org the agent is scoped to, not whatever
+//      org the browser happened to last canonicalize onto
 //   4. Playwright opens it: the Add connection modal must be open with a
 //      credential field, the emulator-minted API key is pasted and submitted
 //   5. The saved connection is proven live: `execute` sends an email through
@@ -17,6 +20,7 @@ import { randomBytes } from "node:crypto";
 
 import { expect } from "@effect/vitest";
 import { Effect } from "effect";
+import { AccountHttpApi } from "@executor-js/api";
 import { composePluginApi } from "@executor-js/api/server";
 import { connectEmulator } from "@executor-js/emulate";
 import { openApiHttpPlugin } from "@executor-js/plugin-openapi/api";
@@ -126,6 +130,13 @@ scenario(
     const session = mcp.session(identity);
     const client = yield* makeApiClient(api, identity);
 
+    // The bound org's slug, read from the same account surface the console
+    // shell reads — the handoff URL must canonicalize onto exactly this.
+    const accountClient = yield* makeApiClient(AccountHttpApi, identity);
+    const me = yield* accountClient.account.me();
+    const orgSlug = me.organization?.slug;
+    expect(orgSlug, "the bound organization advertises a URL slug").toBeTruthy();
+
     yield* runScenario({
       target,
       browser,
@@ -134,6 +145,7 @@ scenario(
       integration,
       emailSubject,
       apiKey,
+      orgSlug: orgSlug!,
     }).pipe(
       // Best-effort cleanup even on failure: drop the created connection(s)
       // over MCP, then the integration over the API.
@@ -155,9 +167,11 @@ const runScenario = (input: {
   readonly integration: string;
   readonly emailSubject: string;
   readonly apiKey: string;
+  readonly orgSlug: string;
 }) =>
   Effect.gen(function* () {
-    const { target, browser, session, identity, integration, emailSubject, apiKey } = input;
+    const { target, browser, session, identity, integration, emailSubject, apiKey, orgSlug } =
+      input;
 
     // 1. Agent registers the emulated provider over MCP.
     const added = yield* executeJson(session, addSpecCode(integration));
@@ -168,13 +182,16 @@ const runScenario = (input: {
     expect(handoff.ok, `createHandoff succeeded: ${JSON.stringify(handoff)}`).toBe(true);
     const handoffUrl = String(handoff.url);
 
-    // 3. The URL must target THIS deployment. (Production returned a URL the
-    //    user called "wrong/bad" — pin the contract here.)
+    // 3. The URL must target THIS deployment AND carry the bound org's slug.
+    //    (Production returned a URL the user called "wrong/bad" — it had no slug,
+    //    so a multi-org user could land in the wrong workspace. Pin both here.)
     const parsed = new URL(handoffUrl);
     expect(parsed.origin, `handoff URL (${handoffUrl}) targets this deployment`).toBe(
       new URL(target.baseUrl).origin,
     );
-    expect(parsed.pathname).toBe(`/integrations/${integration}`);
+    expect(parsed.pathname, `handoff URL (${handoffUrl}) carries the bound org slug`).toBe(
+      `/${orgSlug}/integrations/${integration}`,
+    );
     expect(parsed.searchParams.get("addAccount")).toBe("1");
 
     // 4. The user opens the handoff URL and pastes the credential.
diff --git a/packages/core/api/src/server.ts b/packages/core/api/src/server.ts
@@ -56,9 +56,11 @@ export {
   HostConfig,
   PluginsProvider,
   RequestWebOrigin,
+  RequestOrgSlug,
   type HostConfigShape,
   type PluginsProviderShape,
   type RequestWebOriginShape,
+  type RequestOrgSlugShape,
 } from "./server/scoped-executor";
 export { collectTables } from "@executor-js/sdk";
 export {
diff --git a/packages/core/api/src/server/execution-stack-middleware.ts b/packages/core/api/src/server/execution-stack-middleware.ts
@@ -40,7 +40,12 @@ import { Context, Effect, Layer } from "effect";
 import type { AnyPlugin } from "@executor-js/sdk";
 
 import type { DbProvider } from "./executor-fuma-db";
-import { RequestWebOrigin, type HostConfig, type PluginsProvider } from "./scoped-executor";
+import {
+  RequestOrgSlug,
+  RequestWebOrigin,
+  type HostConfig,
+  type PluginsProvider,
+} from "./scoped-executor";
 import { ExecutionEngineService, ExecutorService } from "../services";
 import { providePluginExtensions, type PluginExtensionServices } from "../plugin-routes";
 import {
@@ -169,7 +174,7 @@ export const makeExecutionStackMiddleware = <
           // web base URL (a Worker) derives one zero-config. An explicit
           // `HostConfig.webBaseUrl` still wins; we deliberately read `request.url`
           // (not a spoofable `X-Forwarded-Host`).
-          const { executor, engine } = yield* makeExecutionStack<TPlugins>(
+          const stack = makeExecutionStack<TPlugins>(
             resolved.accountId,
             resolved.organizationId,
             resolved.organizationName,
@@ -179,6 +184,12 @@ export const makeExecutionStackMiddleware = <
               origin: requestWebOriginFromRequest(webRequest),
             }),
           );
+          // Pin browser-handoff URLs to the resolved org's slug when the identity
+          // provider carried one. Absent slug -> the service stays unprovided and
+          // the URL falls back to its bare, client-canonicalized form.
+          const { executor, engine } = yield* resolved.organizationSlug !== undefined
+            ? stack.pipe(Effect.provideService(RequestOrgSlug, { slug: resolved.organizationSlug }))
+            : stack;
           return yield* httpEffect.pipe(
             Effect.provideService(AuthContext, auth),
             Effect.provideService(ExecutorService, executor),
diff --git a/packages/core/api/src/server/identity.ts b/packages/core/api/src/server/identity.ts
@@ -32,6 +32,13 @@ export interface Principal {
   readonly accountId: string;
   readonly organizationId: string;
   readonly organizationName: string;
+  /**
+   * The org's URL slug (`acme`), when the resolver has it. Optional because not
+   * every principal source carries it (api-key paths that never load the org
+   * row). Threaded into browser-handoff URLs so they open the right org's
+   * console; a missing slug just falls back to a bare, client-canonicalized URL.
+   */
+  readonly organizationSlug?: string;
   readonly email: string;
   readonly name: string | null;
   readonly avatarUrl: string | null;
diff --git a/packages/core/api/src/server/mcp-build.ts b/packages/core/api/src/server/mcp-build.ts
@@ -11,7 +11,7 @@ import { createExecutorMcpServer } from "@executor-js/host-mcp/tool-server";
 import { ErrorCapture } from "../observability";
 import { CodeExecutorProvider, EngineDecorator, makeExecutionStack } from "./execution-stack";
 import { DbProvider } from "./executor-fuma-db";
-import { HostConfig, PluginsProvider } from "./scoped-executor";
+import { HostConfig, PluginsProvider, RequestOrgSlug } from "./scoped-executor";
 
 // ---------------------------------------------------------------------------
 // Shared in-process MCP host helpers.
@@ -45,6 +45,11 @@ export const makeMcpBuildServer =
       principal.organizationName,
     ).pipe(
       Effect.map(({ engine }) => engine),
+      // Pin browser-handoff URLs to the principal's org slug when present;
+      // absent slug leaves the service unprovided and the URL stays bare.
+      principal.organizationSlug !== undefined
+        ? Effect.provideService(RequestOrgSlug, { slug: principal.organizationSlug })
+        : (effect) => effect,
       Effect.provide(executionStack),
       Effect.mapError((cause) => new McpEngineBuildError({ cause })),
       Effect.flatMap((engine) =>
diff --git a/packages/core/api/src/server/scoped-executor.ts b/packages/core/api/src/server/scoped-executor.ts
@@ -109,6 +109,25 @@ export class RequestWebOrigin extends Context.Service<RequestWebOrigin, RequestW
   "@executor-js/api/RequestWebOrigin",
 ) {}
 
+// ---------------------------------------------------------------------------
+// RequestOrgSlug seam — the URL slug of the org the executor is bound to for
+// this request. Threaded into `coreTools.orgSlug` so browser-handoff URLs open
+// the right org's console (`${webBaseUrl}/<slug>/integrations/...`) instead of
+// a bare path the browser would canonicalize to its last-active org. Like
+// `RequestWebOrigin` it is provided per request by the host's pipeline (the
+// HTTP middleware from the resolved principal; the MCP session DO from the
+// stored session meta) and read OPTIONALLY, so non-request callers (CLI, tests,
+// local) simply emit a slug-less URL.
+// ---------------------------------------------------------------------------
+
+export interface RequestOrgSlugShape {
+  readonly slug: string;
+}
+
+export class RequestOrgSlug extends Context.Service<RequestOrgSlug, RequestOrgSlugShape>()(
+  "@executor-js/api/RequestOrgSlug",
+) {}
+
 const LOOPBACK_HOSTNAMES = new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
 
 const isLoopbackOrigin = (origin: string): boolean => {
@@ -198,6 +217,13 @@ export const makeScopedExecutor = <
         onSome: (o) => o.origin,
       }),
     });
+    // The bound org's URL slug, when the host's request pipeline provided one.
+    // Stays `undefined` for non-request callers — `coreTools` then emits bare
+    // (org-less) handoff URLs, which org-scoped hosts canonicalize client-side.
+    const orgSlug = Option.match(yield* Effect.serviceOption(RequestOrgSlug), {
+      onNone: () => undefined,
+      onSome: (o) => o.slug,
+    });
 
     // EXPLICIT OAuth wiring: the redirect callback the host serves and sends to
     // providers is `${webBaseUrl}${oauthCallbackPath}` — the host's API mount
@@ -233,6 +259,7 @@ export const makeScopedExecutor = <
       redirectUri,
       coreTools: {
         webBaseUrl,
+        orgSlug,
         includeProviders: config.exposeCredentialProviders ?? true,
       },
     });
diff --git a/packages/core/sdk/src/core-tools.ts b/packages/core/sdk/src/core-tools.ts
@@ -427,19 +427,29 @@ const createConnectionInputFromTool = (
 
 const connectionCreateHandoffUrl = (
   webBaseUrl: string | undefined,
+  orgSlug: string | undefined,
   input: typeof ConnectionCreateHandoffInput.Type,
 ): string => {
   const search = new URLSearchParams({ addAccount: "1" });
   if (input.owner !== undefined) search.set("owner", input.owner);
   if (input.template !== undefined) search.set("template", input.template);
   if (input.label !== undefined) search.set("label", input.label);
-  const path = `/integrations/${encodeURIComponent(input.integration)}?${search.toString()}`;
+  // Org-scoped hosts (cloud, self-host, cloudflare) serve the console under an
+  // optional `/<org-slug>` segment. Pin the URL to the executor's bound org so
+  // it opens that org directly instead of relying on the browser's last-active
+  // org (which `OrgSlugGate` would otherwise canonicalize a bare URL to). When
+  // no slug is known (CLI, local, non-request callers) we emit the bare path.
+  const orgPrefix = orgSlug !== undefined && orgSlug.length > 0 ? `/${orgSlug}` : "";
+  const path = `${orgPrefix}/integrations/${encodeURIComponent(input.integration)}?${search.toString()}`;
   if (webBaseUrl === undefined || webBaseUrl.length === 0) return path;
   return new URL(path, webBaseUrl.endsWith("/") ? webBaseUrl : `${webBaseUrl}/`).toString();
 };
 
 export interface CoreToolsPluginOptions {
   readonly webBaseUrl?: string;
+  /** The bound org's URL slug, prefixed onto browser-handoff URLs so they open
+   *  the right org's console (`${webBaseUrl}/<orgSlug>/integrations/...`). */
+  readonly orgSlug?: string;
   readonly includeProviders?: boolean;
 }
 
@@ -529,7 +539,7 @@ export const coreToolsPlugin = definePlugin((options: CoreToolsPluginOptions = {
           inputSchema: ConnectionCreateHandoffInputStd,
           outputSchema: ConnectionCreateHandoffOutputStd,
           execute: (input: typeof ConnectionCreateHandoffInput.Type) => {
-            const url = connectionCreateHandoffUrl(options.webBaseUrl, input);
+            const url = connectionCreateHandoffUrl(options.webBaseUrl, options.orgSlug, input);
             return Effect.succeed({
               url,
               instructions:
diff --git a/packages/core/sdk/src/executor.ts b/packages/core/sdk/src/executor.ts
@@ -372,6 +372,7 @@ export interface ExecutorConfig<TPlugins extends readonly AnyPlugin[] = readonly
    */
   readonly coreTools?: {
     readonly webBaseUrl?: string;
+    readonly orgSlug?: string;
     readonly includeProviders?: boolean;
   };
 }
@@ -1239,6 +1240,7 @@ export const createExecutor = <const TPlugins extends readonly AnyPlugin[] = rea
       ? ([
           coreToolsPlugin({
             webBaseUrl: config.coreTools.webBaseUrl,
+            orgSlug: config.coreTools.orgSlug,
             includeProviders: config.coreTools.includeProviders,
           }),
           ...userPlugins,
diff --git a/packages/hosts/cloudflare/src/mcp/session-durable-object.ts b/packages/hosts/cloudflare/src/mcp/session-durable-object.ts
@@ -18,7 +18,7 @@ import type { TransportState } from "agents/mcp";
 
 import { jsonRpcErrorBody } from "@executor-js/host-mcp";
 import { formatResumeAcknowledgement } from "@executor-js/host-mcp/browser-approval";
-import { RequestWebOrigin } from "@executor-js/api/server";
+import { RequestOrgSlug, RequestWebOrigin } from "@executor-js/api/server";
 import {
   formatPausedExecution,
   type ExecutionEngine,
@@ -122,6 +122,9 @@ export interface SessionDbHandle {
 export interface SessionMeta {
   readonly organizationId: string;
   readonly organizationName: string;
+  /** The org's URL slug, when the host's `resolveSessionMeta` carried one.
+   *  Pins browser-handoff URLs to the right org's console. */
+  readonly organizationSlug?: string;
   readonly userId: string;
   readonly elicitationMode?: "browser" | "model" | "native";
   /** Public origin captured at session create — used to derive the runtime's
@@ -354,9 +357,16 @@ export abstract class McpSessionDOBase<
       // The session's captured origin is provided here so the host's execution
       // stack derives a web base URL zero-config (a no-op when it configures one).
       const built = self.buildMcpServer(sessionMeta, options.dbHandle);
-      const { mcpServer, engine } = yield* sessionMeta.webOrigin
+      const withOrigin = sessionMeta.webOrigin
         ? built.pipe(Effect.provideService(RequestWebOrigin, { origin: sessionMeta.webOrigin }))
         : built;
+      // Pin browser-handoff URLs to the session's org slug when captured at
+      // create; absent slug leaves the URL bare for client canonicalization.
+      const { mcpServer, engine } = yield* sessionMeta.organizationSlug
+        ? withOrigin.pipe(
+            Effect.provideService(RequestOrgSlug, { slug: sessionMeta.organizationSlug }),
+          )
+        : withOrigin;
       const transport = yield* makeMcpWorkerTransport({
         sessionIdGenerator: () => self.sessionId,
         storage: self.makeStorage(),
diff --git a/packages/hosts/mcp/src/seams.ts b/packages/hosts/mcp/src/seams.ts
@@ -40,6 +40,10 @@ export const Principal = Schema.Struct({
   accountId: Schema.String,
   organizationId: Schema.String,
   organizationName: Schema.String,
+  /** The org's URL slug, when the auth provider resolved it. Threaded into
+   *  browser-handoff URLs so they open the right org's console. Optional so a
+   *  provider without it (no org row loaded) still maps onto this shape. */
+  organizationSlug: Schema.optional(Schema.String),
   email: Schema.String,
   name: Schema.NullOr(Schema.String),
   avatarUrl: Schema.NullOr(Schema.String),
