Gate signed-out document requests at the edge instead of flashing the app-shell skeleton (#975)

* Gate signed-out document requests at the edge instead of flashing the app-shell skeleton

Signed-out visitors to the cloud app were SSR'd the authenticated
app-shell skeleton (sidebar + card grid) until a client-side
/account/me round trip 401'd and swapped in the login page — a
loading preview of an app they were never going to reach.

The sealed session cookie can be verified in the worker itself
(unseal + JWT against cached JWKS; no per-request round trip), so a
new request middleware does exactly that for document navigations:

- signed-out -> 302 to /login?returnTo=<path> before any app HTML is
  served; an invalid cookie is also cleared (its presence is what
  routes the production root past the marketing site)
- signed-in -> pass through, persisting any rotated sealed session
  (refresh tokens are single-use)
- /login is a real route now; returnTo travels with the CSRF state
  cookie through the login flow and the callback resumes the original
  path (validated to same-origin relative, never /api)
- /cloud (the marketing CTA target, previously a 404) redirects into
  the app root

Signed-in loads get faster too: AuthProvider seeds optimistic state
from a new non-HttpOnly display-only auth-hint cookie it maintains on
every confirmed /account/me, so the shell paints without waiting on
the probe; the resolved answer remains the authority. Logout and the
gate clear the hint alongside the session.

Unknown paths get a real 404 page (notFoundComponent) instead of
mounting the auth gate's skeleton.

The unauthenticated-skeleton e2e (the red repro for this report) is
now green and grew scenarios for the deep-link round trip,
open-redirect rejection, signed-in passthrough, and the 404 page.

* Derive auth state idiomatically in AuthProvider

Replace the seven hand-tracked primitive fields with a memoized resolved
state: useMemo on the atom value gives the identify and hint-cookie
effects a dependency that tracks real query transitions, and the
context value is memoized so consumers don't re-render on unrelated
renders.

* Carry returnTo inside the OAuth state parameter instead of a second cookie

The state parameter already round-trips through the identity provider
and is authenticated by the wos-login-state CSRF cookie, so the
destination rides inside it — base64url(JSON { nonce, returnTo }) — and
the wos-login-return-to cookie goes away. The callback re-validates the
decoded returnTo like any other untrusted path.

* Decode the login-state envelope in the auth-session CSRF scenario

The state parameter is now base64url(JSON { nonce, returnTo }), so the
scenario decodes it and asserts the nonce inside instead of expecting
the raw hex value.

* Cover the auth-hint lifecycle and session-gate edges end to end

Five new scenarios over the real WorkOS emulator:

- auth-hint: a confirmed /account/me writes the hint and the NEXT load
  paints the real shell while the probe is held open; logout clears the
  hint with the session.
- session-gate: an invalid wos-session is cleared on the way to /login
  (not just redirected); /cloud routes into the app both signed out and
  signed in; and a session whose access token no longer verifies is
  refreshed in-flight — the rotated sealed session reaches the browser,
  the spent one is revoked server-side (real single-use refresh
  tokens), and the rotated one keeps working.

The stale-token path unseals the real session cookie with the same
iron-webcrypto sealing the WorkOS SDK uses, corrupts the JWT signature,
and reseals — exercising the gate's refresh branch without waiting out
a real expiry.

Author: RhysSullivan

apps/cloud/src/auth/api.ts

@@ -52,6 +52,13 @@ const AuthCallbackSearch = Schema.Struct({
   state: Schema.optional(Schema.String),
 });
 
+// Where to send the user after the callback completes (the /login page passes
+// the path the SSR auth gate captured). Validated server-side to same-origin
+// relative paths before use.
+const AuthLoginSearch = Schema.Struct({
+  returnTo: Schema.optional(Schema.String),
+});
+
 const PendingInvitationInviter = Schema.Struct({
   email: Schema.String,
   name: Schema.NullOr(Schema.String),
@@ -143,7 +150,7 @@ const McpApprovalErrors = [
 
 /** Public auth endpoints — no authentication required */
 export class CloudAuthPublicApi extends HttpApiGroup.make("cloudAuthPublic")
-  .add(HttpApiEndpoint.get("login", "/auth/login"))
+  .add(HttpApiEndpoint.get("login", "/auth/login", { query: AuthLoginSearch }))
   .add(
     HttpApiEndpoint.get("callback", "/auth/callback", {
       query: AuthCallbackSearch,

apps/cloud/src/auth/cookies.ts

@@ -0,0 +1,12 @@
+// The one request-header cookie parser (workos.ts, edge/marketing.ts, and the
+// SSR auth gate all need it). Pure string code — safe in any bundle.
+
+export const parseCookie = (cookieHeader: string | null, name: string): string | null => {
+  if (!cookieHeader) return null;
+  const match = cookieHeader
+    .split(";")
+    .map((c) => c.trim())
+    .find((c) => c.startsWith(`${name}=`));
+  if (!match) return null;
+  return match.slice(name.length + 1) || null;
+};

apps/cloud/src/auth/handlers.ts

@@ -10,7 +10,11 @@ import {
   McpSessionForbiddenError,
 } from "./api";
 import { NoOrganization } from "@executor-js/api/server";
+// Pure constants/codec module (no React) — safe in the backend graph.
+import { AUTH_HINT_COOKIE } from "@executor-js/react/multiplayer/auth-hint";
 import { SessionContext, SessionCookies } from "./middleware";
+import { encodeLoginState, decodeLoginState } from "./login-state";
+import { safeReturnTo } from "./return-to";
 import { UserStoreService } from "./context";
 import { env } from "cloudflare:workers";
 import { WorkOSError } from "./errors";
@@ -63,7 +67,7 @@ const DELETE_COOKIE_OPTIONS = {
   secure: true,
 };
 
-const randomState = (): string => {
+const randomNonce = (): string => {
   const bytes = new Uint8Array(32);
   crypto.getRandomValues(bytes);
   return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
@@ -143,14 +147,19 @@ export const CloudAuthPublicHandlers = HttpApiBuilder.group(
   "cloudAuthPublic",
   (handlers) =>
     handlers
-      .handleRaw("login", () =>
+      .handleRaw("login", ({ query }) =>
         Effect.gen(function* () {
           const workos = yield* WorkOSClient;
           // Use the explicit public site URL — in dev, the request's Host
           // header points at the internal proxy target, not the public URL
           // WorkOS needs to redirect back to.
           const origin = env.VITE_PUBLIC_SITE_URL ?? "";
-          const state = randomState();
+          // OAuth round-trips `state` verbatim, so the validated returnTo
+          // rides inside it next to the CSRF nonce — no extra cookie.
+          const state = encodeLoginState({
+            nonce: randomNonce(),
+            returnTo: safeReturnTo(query.returnTo) ?? undefined,
+          });
           const url = workos.getAuthorizationUrl(`${origin}${AUTH_PATHS.callback}`, state);
           return setResponseCookie(
             HttpServerResponse.redirect(url, { status: 302 }),
@@ -211,9 +220,15 @@ export const CloudAuthPublicHandlers = HttpApiBuilder.group(
             return HttpServerResponse.text("Failed to create session", { status: 500 });
           }
 
+          // Resume where the SSR gate interrupted them. The state passed the
+          // CSRF check above whenever it's present, but it's still a
+          // round-tripped value — so the returnTo inside it is re-validated
+          // like any other untrusted path.
+          const returnTo = safeReturnTo(decodeLoginState(query.state)?.returnTo) ?? "/";
+
           return deleteResponseCookie(
             setResponseCookie(
-              HttpServerResponse.redirect("/", { status: 302 }),
+              HttpServerResponse.redirect(returnTo, { status: 302 }),
               "wos-session",
               sealedSession,
               RESPONSE_COOKIE_OPTIONS,
@@ -253,7 +268,13 @@ export const CloudSessionAuthHandlers = HttpApiBuilder.group(
       )
       .handleRaw("logout", () =>
         Effect.succeed(
-          deleteResponseCookie(HttpServerResponse.redirect("/", { status: 302 }), "wos-session"),
+          // The auth-hint travels with the session: leaving it behind would
+          // make the next page load optimistically paint the app shell for a
+          // signed-out browser.
+          deleteResponseCookie(
+            deleteResponseCookie(HttpServerResponse.redirect("/", { status: 302 }), "wos-session"),
+            AUTH_HINT_COOKIE,
+          ),
         ),
       )
       .handle("organizations", () =>

apps/cloud/src/auth/login-state.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from "@effect/vitest";
+
+import { decodeLoginState, encodeLoginState } from "./login-state";
+
+// The OAuth state parameter carries { nonce, returnTo } through the WorkOS
+// round trip. It crosses a trust boundary twice (authorize URL out, callback
+// query in), so decoding must be total — junk reads as null, never a throw.
+describe("login state codec", () => {
+  it("round-trips nonce + returnTo", () => {
+    const state = { nonce: "a".repeat(64), returnTo: "/integrations/sentry?addAccount=1" };
+    expect(decodeLoginState(encodeLoginState(state))).toEqual(state);
+  });
+
+  it("round-trips a state without returnTo", () => {
+    const state = { nonce: "b".repeat(64) };
+    expect(decodeLoginState(encodeLoginState(state))).toEqual(state);
+  });
+
+  it("is URL-safe verbatim (no characters that need query escaping)", () => {
+    const encoded = encodeLoginState({ nonce: "c".repeat(64), returnTo: "/tools?q=a b&x=+/" });
+    expect(encoded).toMatch(/^[A-Za-z0-9_-]+$/);
+  });
+
+  // The callback can be reached by WorkOS-initiated redirects whose state we
+  // never minted, and by anyone typing a URL.
+  const junk = [
+    null,
+    undefined,
+    "", // absent
+    "not-base64url!!", // invalid alphabet
+    "aGVsbG8", // valid base64url, not JSON ("hello")
+    "eyJmb28iOiJiYXIifQ", // valid JSON, wrong shape ({"foo":"bar"})
+  ];
+  for (const value of junk) {
+    it(`reads ${JSON.stringify(value)} as null`, () => {
+      expect(decodeLoginState(value)).toBeNull();
+    });
+  }
+});

apps/cloud/src/auth/login-state.ts

@@ -0,0 +1,36 @@
+// ---------------------------------------------------------------------------
+// Login state — the OAuth `state` parameter for the WorkOS login round trip.
+//
+// `state` exists for CSRF (the callback checks it against the wos-login-state
+// cookie), and OAuth round-trips it verbatim — which makes it the natural
+// carrier for `returnTo` too: base64url(JSON { nonce, returnTo }). One value,
+// one cookie, and the destination is covered by the same timing-safe
+// comparison that authenticates the nonce.
+//
+// Decoding is total: anything that isn't our encoding reads as null, because
+// the callback can also be reached by WorkOS-initiated redirects whose state
+// (if any) we never minted.
+// ---------------------------------------------------------------------------
+
+import { Encoding, Option, Result, Schema } from "effect";
+
+const LoginStateSchema = Schema.Struct({
+  nonce: Schema.String,
+  returnTo: Schema.optional(Schema.String),
+});
+
+export type LoginState = typeof LoginStateSchema.Type;
+
+const LoginStateFromJson = Schema.fromJsonString(LoginStateSchema);
+const decodeLoginStateJson = Schema.decodeUnknownOption(LoginStateFromJson);
+const encodeLoginStateJson = Schema.encodeSync(LoginStateFromJson);
+
+export const encodeLoginState = (state: LoginState): string =>
+  Encoding.encodeBase64Url(encodeLoginStateJson(state));
+
+/** Decode a state value back; null for anything we didn't mint. */
+export const decodeLoginState = (value: string | null | undefined): LoginState | null => {
+  if (!value) return null;
+  const json = Result.getOrNull(Encoding.decodeBase64UrlString(value));
+  return json === null ? null : Option.getOrNull(decodeLoginStateJson(json));
+};

apps/cloud/src/auth/return-to.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "@effect/vitest";
+
+import { isSafeReturnTo, loginPath, safeReturnTo } from "./return-to";
+
+// Guards the login round-trip channel (SSR gate → /login → /api/auth/login →
+// OAuth state param → callback redirect). Everything here crosses a trust
+// boundary, so the validator is what stands between "resume where you were"
+// and an open redirect.
+describe("isSafeReturnTo", () => {
+  const safe = ["/", "/tools", "/integrations/sentry?addAccount=1", "/billing/plans"];
+  for (const path of safe) {
+    it(`allows ${path}`, () => {
+      expect(isSafeReturnTo(path)).toBe(true);
+    });
+  }
+
+  const unsafe = [
+    "https://evil.example", // absolute URL — off-origin redirect
+    "//evil.example", // protocol-relative — same thing in disguise
+    "/api/auth/logout", // API endpoints are never a landing page
+    "/api", // bare /api too
+    "javascript:alert(1)", // not a path at all
+    "tools", // relative paths resolve unpredictably
+    "", // empty
+  ];
+  for (const path of unsafe) {
+    it(`rejects ${JSON.stringify(path)}`, () => {
+      expect(isSafeReturnTo(path)).toBe(false);
+    });
+  }
+
+  // /api-keys is a React page, not an API path — the prefix check must not
+  // swallow it.
+  it("allows /api-keys (page, not API)", () => {
+    expect(isSafeReturnTo("/api-keys")).toBe(true);
+  });
+});
+
+describe("safeReturnTo", () => {
+  it("passes a safe path through", () => {
+    expect(safeReturnTo("/tools")).toBe("/tools");
+  });
+  it("nulls unsafe and absent values", () => {
+    expect(safeReturnTo("https://evil.example")).toBeNull();
+    expect(safeReturnTo(null)).toBeNull();
+    expect(safeReturnTo(undefined)).toBeNull();
+  });
+});
+
+describe("loginPath", () => {
+  it("omits returnTo for the root (the default destination)", () => {
+    expect(loginPath("/")).toBe("/login");
+  });
+  it("carries deep links URI-encoded", () => {
+    expect(loginPath("/integrations/sentry?addAccount=1")).toBe(
+      "/login?returnTo=%2Fintegrations%2Fsentry%3FaddAccount%3D1",
+    );
+  });
+});

apps/cloud/src/auth/return-to.ts

@@ -0,0 +1,23 @@
+// ---------------------------------------------------------------------------
+// returnTo — the "send me back where I was" path carried through the login
+// flow (SSR gate → /login → /api/auth/login → OAuth state param → callback).
+//
+// The value crosses trust boundaries (query params, the state round-tripped
+// through the identity provider), so every consumer validates with
+// `isSafeReturnTo` before using it: same-origin relative paths only — no
+// absolute/protocol-relative URLs (open redirect) and nothing under /api
+// (bouncing a fresh login into an API endpoint is never what the user meant).
+//
+// Pure string code — imported by server handlers and the login page alike.
+// ---------------------------------------------------------------------------
+
+export const isSafeReturnTo = (path: string): boolean =>
+  path.startsWith("/") && !path.startsWith("//") && !/^\/api(\/|$)/.test(path);
+
+/** The validated returnTo, or null when absent/unsafe. */
+export const safeReturnTo = (path: string | null | undefined): string | null =>
+  path && isSafeReturnTo(path) ? path : null;
+
+/** The /login URL that comes back to `returnTo` ("/" needs no parameter). */
+export const loginPath = (returnTo: string): string =>
+  returnTo === "/" ? "/login" : `/login?returnTo=${encodeURIComponent(returnTo)}`;