Fix org scope: use URL slug as single source of truth for API requests

Multi-org users viewing an org by its URL slug while their session cookie
was pinned to a different org had billing and membership checks scoped to
the session's org, not the URL's. An admin on a free-plan session org who
opened a team-plan org by slug hit the free 3-seat cap and got a 403 on
invite.

Make the URL path slug the single source of org truth for the API plane,
mirroring the MCP plane:

- Add prepareApiOrgScope worker-boundary seam: rewrites /<slug>/api/... to
  bare /api/... and pins the slug in the internal selector header; strips
  any client-supplied selector header on bare /api/... paths.
- Remove session.organizationId as a request scope in auth, account, and
  billing readers. A request with no URL slug is org-less (NoOrganization).
- Billing proxy resolves the URL selector to a WorkOS org via a live
  membership check and uses it as the Autumn customerId; non-members 403.
- Clients stop sending the x-executor-organization header and instead
  splice the active slug into the API base URL at request time.

Adds unit coverage for the boundary seam and a black-box e2e repro of the
multi-org seat bug.

Author: RhysSullivan

apps/cloud/src/account/workos-account-service.ts

@@ -87,16 +87,18 @@ export const workosAccountProvider: Layer.Layer<
         ? Effect.succeed(caller.session)
         : Effect.fail<AccountUnauthorized>(new AccountUnauthorized());
 
-    // The org scope for an org-scoped request: the console URL's org (sent in
-    // the selector header) when present, else the session's own org. Membership
-    // is re-checked live, so the header is a selector, not a trust boundary —
-    // and two browser tabs on different orgs each send their own header, so
-    // they stay independent (see organization.ts). Yields the session +
-    // resolved org, or AccountNoOrganization.
+    // The org scope for an org-scoped request comes ONLY from the console URL,
+    // which the worker boundary pins in the selector header (`/<slug>/api/...`
+    // → ORG_SELECTOR_HEADER). The session identifies the USER, never the org —
+    // there is no session fallback, so two browser tabs on different orgs each
+    // resolve their own org from their own URL and stay independent (see
+    // organization.ts). Membership is re-checked live, so the header is a
+    // URL-derived selector, not a trust boundary. Yields the session + resolved
+    // org, or AccountNoOrganization when the request is org-less.
     const requireOrganization = (headers: AccountHeaders) =>
       Effect.gen(function* () {
         const session = yield* requireSession();
-        const selector = headers[ORG_SELECTOR_HEADER] ?? session.organizationId;
+        const selector = headers[ORG_SELECTOR_HEADER];
         if (!selector) {
           return yield* new AccountNoOrganization();
         }
@@ -165,10 +167,12 @@ export const workosAccountProvider: Layer.Layer<
       me: (headers) =>
         Effect.gen(function* () {
           const session = yield* requireSession();
-          // Same selector precedence as requireOrganization: the URL's org
-          // (header) drives /account/me so the shell reflects the org the tab
-          // is viewing, not a session-global active org.
-          const selector = headers[ORG_SELECTOR_HEADER] ?? session.organizationId;
+          // Same org source as requireOrganization: the URL's org (pinned in
+          // the selector header by the worker boundary) drives /account/me so
+          // the shell reflects the org the tab is viewing. `me` stays
+          // null-tolerant — an org-less request (no URL slug, e.g. onboarding)
+          // resolves organization: null rather than erroring.
+          const selector = headers[ORG_SELECTOR_HEADER];
           const org = selector
             ? yield* authorizeOrganizationSelector(session.accountId, selector).pipe(
                 Effect.provideContext(ctx),

apps/cloud/src/api/org-scope.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, it } from "@effect/vitest";
+
+import { ORG_SELECTOR_HEADER } from "../auth/organization";
+import { classifyApiOrgScope, isApiPath, prepareApiOrgScope } from "./org-scope";
+
+// The worker-boundary seam that turns the URL's first path segment into the org
+// scope for the `/api/*` plane. The wire form is `/<slug>/api/...` (or the
+// legacy `/<org_id>/api/...`); the boundary strips the prefix to the bare
+// `/api/...` the app handler routes and pins the selector in an internal header.
+// Org rides ONLY in the URL — a client-supplied selector header is never trusted.
+
+describe("isApiPath", () => {
+  it("matches the bare API plane", () => {
+    expect(isApiPath("/api")).toBe(true);
+    expect(isApiPath("/api/executions")).toBe(true);
+    expect(isApiPath("/api/billing/customer")).toBe(true);
+  });
+
+  it("does not match org-scoped, MCP, or console paths", () => {
+    expect(isApiPath("/acme-corp/api/executions")).toBe(false);
+    expect(isApiPath("/mcp")).toBe(false);
+    expect(isApiPath("/settings")).toBe(false);
+    expect(isApiPath("/apiary")).toBe(false); // not `/api` nor `/api/`
+  });
+});
+
+describe("classifyApiOrgScope", () => {
+  it("classifies a slug-scoped API path", () => {
+    expect(classifyApiOrgScope("/acme-corp/api/billing/customer")).toEqual({
+      selector: "acme-corp",
+      barePath: "/api/billing/customer",
+    });
+  });
+
+  it("classifies the legacy org-id-scoped form", () => {
+    expect(classifyApiOrgScope("/org_01ABCDEF/api/executions")).toEqual({
+      selector: "org_01ABCDEF",
+      barePath: "/api/executions",
+    });
+  });
+
+  it("returns null for a bare API path (no selector segment)", () => {
+    expect(classifyApiOrgScope("/api/billing/customer")).toBeNull();
+    expect(classifyApiOrgScope("/api")).toBeNull();
+  });
+
+  it("returns null when the second segment is not `api`", () => {
+    expect(classifyApiOrgScope("/acme-corp/mcp")).toBeNull();
+    expect(classifyApiOrgScope("/settings/mcp")).toBeNull();
+    expect(classifyApiOrgScope("/acme-corp")).toBeNull();
+  });
+});
+
+describe("prepareApiOrgScope", () => {
+  it("rewrites a slug-scoped request to the bare path and pins the selector", () => {
+    const out = prepareApiOrgScope(
+      new Request("https://executor.test/acme-corp/api/billing/customer", { method: "POST" }),
+    );
+    expect(new URL(out.url).pathname).toBe("/api/billing/customer");
+    expect(out.headers.get(ORG_SELECTOR_HEADER)).toBe("acme-corp");
+    expect(out.method).toBe("POST");
+  });
+
+  it("pins the legacy org-id selector", () => {
+    const out = prepareApiOrgScope(
+      new Request("https://executor.test/org_01ABCDEF/api/executions"),
+    );
+    expect(new URL(out.url).pathname).toBe("/api/executions");
+    expect(out.headers.get(ORG_SELECTOR_HEADER)).toBe("org_01ABCDEF");
+  });
+
+  it("strips a client-supplied selector header on a bare API path", () => {
+    // Org may come ONLY from the URL — a client cannot smuggle a different org
+    // by setting the internal selector header on a bare `/api/...` request.
+    const out = prepareApiOrgScope(
+      new Request("https://executor.test/api/billing/customer", {
+        headers: { [ORG_SELECTOR_HEADER]: "org_attacker" },
+      }),
+    );
+    expect(new URL(out.url).pathname).toBe("/api/billing/customer");
+    expect(out.headers.has(ORG_SELECTOR_HEADER)).toBe(false);
+  });
+
+  it("leaves a bare API path without a selector header untouched", () => {
+    const req = new Request("https://executor.test/api/executions");
+    expect(prepareApiOrgScope(req)).toBe(req);
+  });
+
+  it("leaves a non-API path untouched", () => {
+    const req = new Request("https://executor.test/settings");
+    expect(prepareApiOrgScope(req)).toBe(req);
+  });
+});

apps/cloud/src/api/org-scope.ts

@@ -0,0 +1,81 @@
+// ---------------------------------------------------------------------------
+// API org scope — the worker-boundary seam that carries the URL's org into the
+// `/api/*` plane, mirroring `prepareMcpOrgScope` for `/mcp`.
+//
+// On the wire the org is the FIRST PATH SEGMENT of every org-scoped API request
+// (`/<slug>/api/...`, or the legacy `/<org_id>/api/...`), exactly like the
+// console URL it rides alongside — the URL is the single source of org truth,
+// and no client header carries org anymore. This boundary classifies that path,
+// rewrites it to the bare `/api/...` the app handler actually routes, and pins
+// the URL's org in the internal `ORG_SELECTOR_HEADER` the auth/account/billing
+// planes read via `orgSelectorFromRequest`. Membership is STILL re-checked per
+// request downstream (`authorizeOrganizationSelector`), so the header is a
+// selector the worker sets from the URL, never a trust boundary or a value a
+// client may supply.
+// ---------------------------------------------------------------------------
+
+import { isValidOrgSlug } from "@executor-js/api";
+
+import { ORG_SELECTOR_HEADER } from "../auth/organization";
+
+// Bare API path — what the app handler routes once the boundary has stripped any
+// `/<slug>` prefix. `api` is itself a RESERVED slug, so a bare `/api/...` first
+// segment can never be mistaken for an org selector.
+export const isApiPath = (pathname: string): boolean =>
+  pathname === "/api" || pathname.startsWith("/api/");
+
+// A leading path segment counts as an org selector when it's the org's URL slug
+// (the canonical console form) or has the WorkOS org-id shape (`org_…`, the
+// legacy form). The slug grammar reserves `api`, so the bare API plane never
+// matches. Same rule as the MCP front's `orgSelectorSegment`.
+const orgSelectorSegment = (segment: string | undefined): string | null =>
+  segment && (segment.startsWith("org_") || isValidOrgSlug(segment)) ? segment : null;
+
+export type ApiOrgScope = {
+  /** Org selector pinned in the URL (`/<slug>/api/...` slug or the legacy
+   *  `/<org_id>/api/...` id). Resolved to an org id — and re-checked against
+   *  live membership — by `authorizeOrganizationSelector` downstream. */
+  readonly selector: string;
+  /** The bare `/api/...` path the app handler routes, with the `/<selector>`
+   *  prefix removed. */
+  readonly barePath: string;
+};
+
+/**
+ * Classify an org-scoped API path (`/<selector>/api/...`), returning the URL's
+ * org selector + the bare path the app handler routes, or `null` when the path
+ * isn't one (a bare `/api/...`, an MCP path, or a console route). Shared by
+ * `app-paths.ts`'s app-owned gate and `prepareApiOrgScope`.
+ */
+export const classifyApiOrgScope = (pathname: string): ApiOrgScope | null => {
+  const segments = pathname.split("/").filter((segment) => segment.length > 0);
+  if (segments.length < 2) return null;
+  const selector = orgSelectorSegment(segments[0]);
+  if (selector === null || segments[1] !== "api") return null;
+  return { selector, barePath: `/${segments.slice(1).join("/")}` };
+};
+
+/**
+ * Normalize an API request for the app handler, which routes ONLY bare `/api/*`.
+ * Rewrites `/<selector>/api/...` to its bare path and pins the URL's org in the
+ * internal `ORG_SELECTOR_HEADER`. A bare `/api/*` is left untouched, except any
+ * client-supplied selector header is stripped — org may come ONLY from the URL,
+ * so a header can never smuggle a different org past it (a no-op for non-API
+ * paths). Called by start.ts's app dispatch alongside `prepareMcpOrgScope`.
+ */
+export const prepareApiOrgScope = (request: Request): Request => {
+  const url = new URL(request.url);
+  const scope = classifyApiOrgScope(url.pathname);
+  if (scope === null) {
+    if (isApiPath(url.pathname) && request.headers.has(ORG_SELECTOR_HEADER)) {
+      const stripped = new Request(url, request);
+      stripped.headers.delete(ORG_SELECTOR_HEADER);
+      return stripped;
+    }
+    return request;
+  }
+  url.pathname = scope.barePath;
+  const rewritten = new Request(url, request);
+  rewritten.headers.set(ORG_SELECTOR_HEADER, scope.selector);
+  return rewritten;
+};

apps/cloud/src/api/router.ts

@@ -1,7 +1,7 @@
 import { Layer } from "effect";
 import { HttpRouter } from "effect/unstable/http";
 
-import { RouterConfigLive } from "@executor-js/api/server";
+import { RouterConfigLive, requestScopedMiddleware } from "@executor-js/api/server";
 
 import { UserStoreService } from "../auth/context";
 import { DbService } from "../db/db";
@@ -36,7 +36,11 @@ export const makeApiLive = (requestScopedLive: Layer.Layer<DbService | UserStore
     makeAccountApiLive(requestScopedLive),
     CloudDocsLive,
     makeProtectedApiLive(requestScopedLive),
-    AutumnRoutesLive,
+    // The Autumn billing proxy resolves the URL's org selector to its WorkOS id
+    // via `authorizeOrganizationSelector`, which yields `UserStoreService` — so
+    // it needs the SAME per-request DB scoping the other sub-APIs thread in
+    // (matching `makeCloudExtensionRoutes`, the production composition).
+    AutumnRoutesLive.pipe(Layer.provide(requestScopedMiddleware(requestScopedLive).layer)),
     ApiErrorLoggingLive,
   ).pipe(Layer.provideMerge(RouterConfigLive), Layer.provideMerge(BootSharedServices));
 

apps/cloud/src/app-paths.test.ts

@@ -25,6 +25,13 @@ describe("isAppOwnedPath", () => {
     "/org_01ABCDEF/mcp",
     "/.well-known/oauth-protected-resource/acme-corp/mcp",
     "/.well-known/oauth-protected-resource/org_01ABCDEF/mcp",
+    // Org-scoped API: org rides as the first path segment (`/<slug>/api/...`),
+    // mirroring the MCP plane. The React app posts billing to
+    // `/<slug>/api/billing/*` via <AutumnProvider pathPrefix> — that slug-scoped
+    // form must reach the app handler, not the SPA. Legacy org-id form too.
+    "/acme-corp/api/billing/customer",
+    "/acme-corp/api/executions",
+    "/org_01ABCDEF/api/billing/attach",
   ];
   for (const pathname of appOwned) {
     it(`forwards ${pathname} to the app handler`, () => {

apps/cloud/src/app-paths.ts

@@ -1,3 +1,4 @@
+import { classifyApiOrgScope, isApiPath } from "./api/org-scope";
 import { classifyMcpPath } from "./mcp/mount";
 
 // ---------------------------------------------------------------------------
@@ -8,12 +9,13 @@ import { classifyMcpPath } from "./mcp/mount";
 // `/api/*` — the typed API plus the cloud `extensions.routes` (the Autumn billing
 // proxy at `/api/billing/*` and Swagger at `/api/docs` both live under `/api`) —
 // plus the `/mcp` serving envelope and its `/.well-known/*` OAuth discovery docs.
-// The dispatcher forwards those UNMODIFIED; anything else falls through to the
-// Start router. Keeping every served route under `/api` (no separate top-level
-// namespace) is what keeps this gate a simple two-prefix check.
+// Org-scoped API requests arrive slug-first (`/<slug>/api/...`); the dispatcher
+// forwards every app-owned path, rewriting the slug-scoped MCP/API forms to the
+// bare path the handler routes (see `prepareMcpOrgScope` / `prepareApiOrgScope`).
+// Anything else falls through to the Start router.
 // ---------------------------------------------------------------------------
 
-export const isApiPath = (pathname: string) => pathname === "/api" || pathname.startsWith("/api/");
-
 export const isAppOwnedPath = (pathname: string) =>
-  isApiPath(pathname) || classifyMcpPath(pathname) !== null;
+  isApiPath(pathname) ||
+  classifyApiOrgScope(pathname) !== null ||
+  classifyMcpPath(pathname) !== null;

apps/cloud/src/auth/org-selector-auth.node.test.ts

@@ -6,11 +6,12 @@ import { UserStoreService } from "./context";
 import { resolveSessionPrincipal } from "./workos-auth-provider";
 import { WorkOSClient, type WorkOSClientService } from "./workos";
 
-// The org a console request resolves to is the URL's org (sent in the
-// `x-executor-organization` selector header), not the session's stored org —
-// with the session org as the fallback for non-console callers, and live
-// membership re-checked either way. This is what makes two browser tabs on
-// different orgs independent.
+// The org a request resolves to comes ONLY from the URL, carried in the
+// `x-executor-organization` selector header that the worker boundary derives
+// from the `/<slug>/api/...` path. There is no session-org fallback: a request
+// with no selector is org-less and fails `NoOrganization`. Live membership is
+// re-checked either way. This is what makes two browser tabs on different orgs
+// independent — the session's stored org never silently scopes a request.
 
 const createdAt = new Date("2026-01-01T00:00:00.000Z");
 
@@ -85,10 +86,13 @@ const run = (headers: Record<string, string>) =>
   );
 
 describe("resolveSessionPrincipal · URL org selector", () => {
-  it.effect("falls back to the session org when no selector header is sent", () =>
+  it.effect("rejects an org-less request when no selector header is sent", () =>
     Effect.gen(function* () {
-      const principal = yield* run({ cookie: "wos-session=x" });
-      expect(principal.organizationId, "scopes to the session org").toBe(SESSION_ORG);
+      // No `/<slug>/` in the URL → no selector header → no org. The session's
+      // stored org does NOT silently scope the request anymore; org comes only
+      // from the URL.
+      const error = yield* Effect.flip(run({ cookie: "wos-session=x" }));
+      expect(error).toMatchObject({ _tag: "NoOrganization" });
     }),
   );
 

apps/cloud/src/auth/organization.ts

@@ -82,23 +82,27 @@ export const authorizeOrganization = (userId: string, organizationId: string) =>
 // Org SELECTOR — the URL is the scope authority, not the session.
 // ---------------------------------------------------------------------------
 //
-// Org-scoped requests carry the active org in this header, set by the web
-// client from the console URL's slug (the MCP plane carries the same idea in
-// its own `x-executor-mcp-organization`). The selector is a slug (`acme`, the
-// readable URL form) or a WorkOS id (`org_…`, the legacy/token form). It is a
-// SELECTOR, not a trust boundary: `authorizeOrganizationSelector` re-checks
-// live membership, so the worst a forged header does is name an org the caller
-// already belongs to.
+// Org-scoped API requests carry the active org as the FIRST PATH SEGMENT of the
+// URL (`/<slug>/api/...`). The worker boundary (`api/org-scope.ts`'s
+// `prepareApiOrgScope`) strips that segment and re-pins it in this INTERNAL
+// header before the request reaches the app handler — the same shape the MCP
+// plane uses with its own `x-executor-mcp-organization`. The selector is a slug
+// (`acme`, the readable URL form) or a WorkOS id (`org_…`, the legacy/token
+// form). It is a SELECTOR, not a trust boundary: clients never set it (the
+// boundary strips any client-sent value on a bare `/api/*`), and
+// `authorizeOrganizationSelector` re-checks live membership, so the worst a
+// value does is name an org the caller already belongs to.
 //
-// Why a header and not the session's `org_id`: a browser shares ONE cookie jar
+// Why the URL and not the session's `org_id`: a browser shares ONE cookie jar
 // across tabs, so a single session-pinned org makes "active org" a
 // browser-global — two tabs can't be in two orgs at once, and switching in one
-// silently re-scopes the other. Scoping per-request from the URL makes each
-// tab independent.
+// silently re-scopes the other. Scoping per-request from the URL makes each tab
+// independent.
 
 export const ORG_SELECTOR_HEADER = "x-executor-organization";
 
-/** The URL-pinned org selector for a request, or `null` to fall back to the session. */
+/** The URL-pinned org selector for a request (set by the worker boundary from
+ *  the URL), or `null` when the request is org-less. */
 export const orgSelectorFromRequest = (request: Request): string | null =>
   request.headers.get(ORG_SELECTOR_HEADER);
 

apps/cloud/src/auth/workos-auth-provider.ts

@@ -115,11 +115,13 @@ export const resolveSessionPrincipal = (request: Request) =>
     if (!session) {
       return yield* new NoOrganization(NO_ORGANIZATION_IN_SESSION);
     }
-    // The console URL's org is the scope authority (sent as a header); the
-    // session's own org is the fallback for non-console callers. Membership is
-    // re-checked live either way — the header is a selector, not a trust
-    // boundary (see organization.ts).
-    const selector = orgSelectorFromRequest(request) ?? session.organizationId;
+    // The console URL is the ONLY scope authority: the worker boundary pins the
+    // URL's org in the selector header from `/<slug>/api/...`. The session
+    // identifies the USER, never the org — a request with no URL-scoped org is
+    // org-less here (an org-less page must not reach a protected route).
+    // Membership is still re-checked live — the selector is not a trust boundary
+    // (see organization.ts).
+    const selector = orgSelectorFromRequest(request);
     if (!selector) {
       return yield* new NoOrganization(NO_ORGANIZATION_IN_SESSION);
     }