@vellumai/cli 0.8.11-dev.202606121945.5dce801 → 0.8.11-dev.202606122025.f06346f

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.8.11-dev.202606121945.5dce801",
+  "version": "0.8.11-dev.202606122025.f06346f",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/login-loopback.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, test } from "bun:test";
+
+import { startLoopbackListener } from "../commands/login.js";
+
+/** Resolve "settled"/"pending" — proves whether `waitForCode` resolved. */
+async function settleState(p: Promise<unknown>): Promise<"settled" | "pending"> {
+  return Promise.race([
+    p.then(
+      () => "settled" as const,
+      () => "settled" as const,
+    ),
+    new Promise<"pending">((r) => setTimeout(() => r("pending"), 50)),
+  ]);
+}
+
+describe("startLoopbackListener", () => {
+  test("rejects a state-mismatched callback (CSRF) without settling", async () => {
+    const listener = await startLoopbackListener("expected-state");
+    try {
+      // Wrong state — the load-bearing CSRF check. Any local process can
+      // hit the loopback port, so a mismatched state must NOT deliver a code.
+      const res = await fetch(`${listener.redirectUri}?code=evil&state=wrong`);
+      expect(res.status).toBe(404);
+      expect(await settleState(listener.waitForCode)).toBe("pending");
+
+      // Wrong path on the right port is also ignored.
+      const noise = await fetch(
+        `${listener.redirectUri.replace("/auth/callback", "/evil")}?state=expected-state&code=c`,
+      );
+      expect(noise.status).toBe(404);
+      expect(await settleState(listener.waitForCode)).toBe("pending");
+
+      // A state-matched callback then settles it — the listener kept
+      // listening through the noise above.
+      const ok = await fetch(
+        `${listener.redirectUri}?code=good-code&state=expected-state`,
+      );
+      expect(ok.status).toBe(200);
+      expect(await listener.waitForCode).toBe("good-code");
+    } finally {
+      listener.close();
+    }
+  });
+
+  test("rejects on an error callback with the matching state", async () => {
+    const listener = await startLoopbackListener("st");
+    try {
+      const settled = listener.waitForCode.then(
+        () => null,
+        (e: Error) => e,
+      );
+      const res = await fetch(`${listener.redirectUri}?error=access_denied&state=st`);
+      expect(res.status).toBe(400);
+      const err = await settled;
+      expect(err?.message).toMatch(/access_denied/);
+    } finally {
+      listener.close();
+    }
+  });
+
+  test("close rejects a pending waiter with the given reason", async () => {
+    const listener = await startLoopbackListener("st");
+    const settled = listener.waitForCode.then(
+      () => null,
+      (e: Error) => e,
+    );
+    listener.close("Login timed out. Please try again.");
+    const err = await settled;
+    expect(err?.message).toMatch(/timed out/);
+  });
+});

package/src/__tests__/workos-pkce.test.ts

@@ -0,0 +1,312 @@
+import { afterEach, describe, expect, mock, test } from "bun:test";
+
+import {
+  buildAuthorizeUrl,
+  exchangeAccessTokenForSession,
+  exchangeCodeWithWorkos,
+  fetchWorkosClientId,
+  generatePkcePair,
+  selectWorkosClientId,
+} from "../lib/workos-pkce.js";
+
+const originalFetch = globalThis.fetch;
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
+
+/**
+ * Route fetch responses by URL substring so each WorkOS/platform call can be
+ * inspected. The module talks to remote hosts via loopbackSafeFetch, which
+ * delegates to globalThis.fetch.
+ */
+function mockFetchByUrl(responses: Record<string, () => Response>) {
+  const calls: Array<{ url: string; init?: RequestInit }> = [];
+  globalThis.fetch = mock(
+    async (input: RequestInfo | URL, init?: RequestInit) => {
+      const url = String(input);
+      calls.push({ url, init });
+      const match = Object.entries(responses).find(([prefix]) =>
+        url.includes(prefix),
+      );
+      if (!match) throw new Error(`Unexpected fetch: ${url}`);
+      return match[1]();
+    },
+  ) as unknown as typeof globalThis.fetch;
+  return calls;
+}
+
+describe("generatePkcePair", () => {
+  test("challenge is the base64url sha256 of the verifier", async () => {
+    const { verifier, challenge } = generatePkcePair();
+    const digest = await crypto.subtle.digest(
+      "SHA-256",
+      new TextEncoder().encode(verifier),
+    );
+    const expected = Buffer.from(digest).toString("base64url");
+    expect(challenge).toBe(expected);
+  });
+
+  test("verifiers are unique", () => {
+    expect(generatePkcePair().verifier).not.toBe(generatePkcePair().verifier);
+  });
+});
+
+describe("buildAuthorizeUrl", () => {
+  const base = {
+    clientId: "client_123",
+    redirectUri: "http://127.0.0.1:4242/auth/callback",
+    challenge: "chal",
+    state: "st",
+  };
+
+  test("targets user_management/authorize with PKCE and authkit defaults", () => {
+    const url = new URL(buildAuthorizeUrl(base));
+    expect(url.origin).toBe("https://api.workos.com");
+    expect(url.pathname).toBe("/user_management/authorize");
+    expect(url.searchParams.get("client_id")).toBe("client_123");
+    expect(url.searchParams.get("redirect_uri")).toBe(base.redirectUri);
+    expect(url.searchParams.get("response_type")).toBe("code");
+    expect(url.searchParams.get("scope")).toBe("openid profile email");
+    expect(url.searchParams.get("code_challenge")).toBe("chal");
+    expect(url.searchParams.get("code_challenge_method")).toBe("S256");
+    expect(url.searchParams.get("state")).toBe("st");
+    expect(url.searchParams.get("provider")).toBe("authkit");
+    // Session reuse: never force a fresh IdP login.
+    expect(url.searchParams.has("prompt")).toBe(false);
+  });
+
+  test("provider hint replaces authkit", () => {
+    const url = new URL(
+      buildAuthorizeUrl({ ...base, providerHint: "GoogleOAuth" }),
+    );
+    expect(url.searchParams.get("provider")).toBe("GoogleOAuth");
+  });
+
+  test("login hint is forwarded", () => {
+    const url = new URL(buildAuthorizeUrl({ ...base, loginHint: "a@b.co" }));
+    expect(url.searchParams.get("login_hint")).toBe("a@b.co");
+
+    const noHint = new URL(buildAuthorizeUrl(base));
+    expect(noHint.searchParams.has("login_hint")).toBe(false);
+  });
+});
+
+describe("selectWorkosClientId", () => {
+  // During coexistence the platform lists two providers that share the
+  // "workos-oidc" id; only the OAuth2 one (no discovery URL) is usable.
+  const legacy = {
+    id: "workos-oidc",
+    name: "WorkOS OIDC",
+    client_id: "client_connect",
+    flows: ["provider_redirect", "provider_token"],
+    openid_configuration_url:
+      "https://x.authkit.app/.well-known/openid-configuration",
+  };
+  const modern = {
+    id: "workos-oidc",
+    name: "WorkOS",
+    client_id: "client_um",
+    flows: ["provider_redirect", "provider_token"],
+  };
+
+  test("picks the OAuth2 entry during coexistence", () => {
+    expect(selectWorkosClientId([legacy, modern])).toBe("client_um");
+    expect(selectWorkosClientId([modern, legacy])).toBe("client_um");
+  });
+
+  test("returns null when the platform lacks token auth", () => {
+    const preTokenAuth = { ...modern, flows: ["provider_redirect"] };
+    expect(selectWorkosClientId([legacy, preTokenAuth])).toBeNull();
+    expect(selectWorkosClientId([])).toBeNull();
+  });
+
+  test("ignores an entry missing client_id", () => {
+    const noClientId = { id: "workos-oidc", flows: ["provider_token"] };
+    expect(selectWorkosClientId([noClientId])).toBeNull();
+  });
+});
+
+describe("fetchWorkosClientId", () => {
+  test("resolves the client id from the headless config", async () => {
+    const calls = mockFetchByUrl({
+      "/_allauth/app/v1/config": () =>
+        new Response(
+          JSON.stringify({
+            data: {
+              socialaccount: {
+                providers: [
+                  {
+                    id: "workos-oidc",
+                    client_id: "client_um",
+                    flows: ["provider_token"],
+                  },
+                ],
+              },
+            },
+          }),
+          { status: 200 },
+        ),
+    });
+
+    expect(await fetchWorkosClientId("https://platform.example")).toBe(
+      "client_um",
+    );
+    expect(calls[0]!.url).toBe(
+      "https://platform.example/_allauth/app/v1/config",
+    );
+  });
+
+  test("derives the config URL from the origin, ignoring any path", async () => {
+    const calls = mockFetchByUrl({
+      "/_allauth/app/v1/config": () =>
+        new Response(
+          JSON.stringify({
+            data: {
+              socialaccount: {
+                providers: [
+                  { client_id: "client_um", flows: ["provider_token"] },
+                ],
+              },
+            },
+          }),
+          { status: 200 },
+        ),
+    });
+
+    await fetchWorkosClientId("https://platform.example/some/path");
+    expect(calls[0]!.url).toBe(
+      "https://platform.example/_allauth/app/v1/config",
+    );
+  });
+
+  test("throws a clear error when no token-auth provider is advertised", async () => {
+    mockFetchByUrl({
+      "/_allauth/app/v1/config": () =>
+        new Response(
+          JSON.stringify({ data: { socialaccount: { providers: [] } } }),
+          { status: 200 },
+        ),
+    });
+
+    await expect(
+      fetchWorkosClientId("https://platform.example"),
+    ).rejects.toThrow(/does not advertise/);
+  });
+
+  test("throws on a non-OK config response", async () => {
+    mockFetchByUrl({
+      "/_allauth/app/v1/config": () => new Response("nope", { status: 500 }),
+    });
+
+    await expect(
+      fetchWorkosClientId("https://platform.example"),
+    ).rejects.toThrow(/500/);
+  });
+});
+
+describe("exchangeCodeWithWorkos", () => {
+  test("posts a public-client PKCE exchange and returns the access token", async () => {
+    const calls = mockFetchByUrl({
+      "/user_management/authenticate": () =>
+        new Response(JSON.stringify({ access_token: "at_1", user: {} }), {
+          status: 200,
+        }),
+    });
+
+    const token = await exchangeCodeWithWorkos({
+      clientId: "client_um",
+      code: "c",
+      verifier: "v",
+    });
+
+    expect(token).toBe("at_1");
+    expect(calls[0]!.url).toBe(
+      "https://api.workos.com/user_management/authenticate",
+    );
+    const body = JSON.parse(String(calls[0]!.init?.body));
+    // Public client: no secret, no API key.
+    expect(body).toEqual({
+      client_id: "client_um",
+      grant_type: "authorization_code",
+      code: "c",
+      code_verifier: "v",
+    });
+  });
+
+  test("throws with upstream detail on failure", async () => {
+    mockFetchByUrl({
+      "/user_management/authenticate": () =>
+        new Response(JSON.stringify({ error: "invalid_grant" }), {
+          status: 400,
+        }),
+    });
+
+    await expect(
+      exchangeCodeWithWorkos({ clientId: "c", code: "x", verifier: "v" }),
+    ).rejects.toThrow(/400/);
+  });
+
+  test("throws when the exchange returns no access token", async () => {
+    mockFetchByUrl({
+      "/user_management/authenticate": () =>
+        new Response(JSON.stringify({}), { status: 200 }),
+    });
+
+    await expect(
+      exchangeCodeWithWorkos({ clientId: "c", code: "x", verifier: "v" }),
+    ).rejects.toThrow(/no access token/);
+  });
+});
+
+describe("exchangeAccessTokenForSession", () => {
+  test("posts the headless token payload and returns the session token", async () => {
+    const calls = mockFetchByUrl({
+      "/_allauth/app/v1/auth/provider/token": () =>
+        new Response(JSON.stringify({ meta: { session_token: "sess_1" } }), {
+          status: 200,
+        }),
+    });
+
+    const token = await exchangeAccessTokenForSession(
+      "https://platform.example",
+      "client_um",
+      "at_1",
+    );
+
+    expect(token).toBe("sess_1");
+    expect(calls[0]!.url).toBe(
+      "https://platform.example/_allauth/app/v1/auth/provider/token",
+    );
+    const body = JSON.parse(String(calls[0]!.init?.body));
+    expect(body).toEqual({
+      provider: "workos",
+      process: "login",
+      token: { client_id: "client_um", access_token: "at_1" },
+    });
+  });
+
+  test("throws on a rejected token", async () => {
+    mockFetchByUrl({
+      "/_allauth/app/v1/auth/provider/token": () =>
+        new Response(JSON.stringify({ errors: [{ code: "invalid_token" }] }), {
+          status: 400,
+        }),
+    });
+
+    await expect(
+      exchangeAccessTokenForSession("https://platform.example", "c", "bad"),
+    ).rejects.toThrow(/400/);
+  });
+
+  test("throws when the session exchange returns no session token", async () => {
+    mockFetchByUrl({
+      "/_allauth/app/v1/auth/provider/token": () =>
+        new Response(JSON.stringify({ meta: {} }), { status: 200 }),
+    });
+
+    await expect(
+      exchangeAccessTokenForSession("https://platform.example", "c", "at"),
+    ).rejects.toThrow(/no session token/);
+  });
+});

package/src/commands/login.ts

@@ -1,19 +1,16 @@
-import { createServer } from "http";
 import { spawn } from "child_process";
 import { randomBytes } from "crypto";
+import { createServer } from "http";
+import type { AddressInfo } from "net";
 
 import {
   getActiveAssistant,
-  resolveAssistant,
   loadAllAssistants,
   removeAssistantEntry,
+  resolveAssistant,
   setActiveAssistant,
 } from "../lib/assistant-config";
 import { computeDeviceId } from "../lib/guardian-token";
-import {
-  fetchAssistantIngressUrl,
-  fetchCurrentVersion,
-} from "../lib/upgrade-lifecycle.js";
 import {
   clearPlatformToken,
   ensureSelfHostedLocalRegistration,
@@ -21,7 +18,6 @@ import {
   fetchOrganizationId,
   fetchPlatformAssistants,
   getPlatformUrl,
-  getWebUrl,
   injectCredentialsIntoAssistant,
   readGatewayCredential,
   readPlatformToken,
@@ -29,6 +25,18 @@ import {
   savePlatformToken,
 } from "../lib/platform-client";
 import { syncCloudAssistants } from "../lib/sync-cloud-assistants";
+import {
+  fetchAssistantIngressUrl,
+  fetchCurrentVersion,
+} from "../lib/upgrade-lifecycle.js";
+import {
+  CALLBACK_PATH,
+  buildAuthorizeUrl,
+  exchangeAccessTokenForSession,
+  exchangeCodeWithWorkos,
+  fetchWorkosClientId,
+  generatePkcePair,
+} from "../lib/workos-pkce";
 
 const LOGIN_TIMEOUT_MS = 120_000; // 2 minutes
 
@@ -41,7 +49,11 @@ function escapeHtml(s: string): string {
     .replace(/'/g, "'");
 }
 
-function renderLoginPage(title: string, subtitle: string, success: boolean): string {
+function renderLoginPage(
+  title: string,
+  subtitle: string,
+  success: boolean,
+): string {
   const checkmarkSvg = `<svg class="icon" viewBox="0 0 56 56" fill="none" xmlns="http://www.w3.org/2000/svg">
       <circle cx="28" cy="28" r="28" fill="var(--positive-bg)"/>
       <path class="check" d="M17 28.5L24.5 36L39 21" stroke="var(--positive-fg)" stroke-width="3.5" stroke-linecap="round" stroke-linejoin="round" fill="none"/>
@@ -175,78 +187,131 @@ function openBrowser(url: string): void {
   child.unref();
 }
 
+export interface LoopbackListener {
+  /** The full `http://127.0.0.1:<port>/auth/callback` redirect URI. */
+  redirectUri: string;
+  /** Resolves with the authorization code once the state-matched callback arrives. */
+  waitForCode: Promise<string>;
+  /** Tear down the server, rejecting any pending waiter with `reason`. */
+  close: (reason?: string) => void;
+}
+
 /**
- * Start a local HTTP server, open the browser to the platform login page,
- * and wait for the platform to redirect back with the session token.
+ * Bind an ephemeral 127.0.0.1 listener and wait for the OAuth redirect.
+ * Exported for tests; production callers go through `workosPkceLogin`.
  */
-function browserLogin(webUrl: string): Promise<string> {
-  return new Promise((resolve, reject) => {
-    const state = randomBytes(32).toString("hex");
+export function startLoopbackListener(
+  expectedState: string,
+): Promise<LoopbackListener> {
+  return new Promise((resolveListener, rejectListener) => {
+    let settle: {
+      resolve: (code: string) => void;
+      reject: (err: Error) => void;
+    };
+    const waitForCode = new Promise<string>((resolve, reject) => {
+      settle = { resolve, reject };
+    });
 
     const server = createServer((req, res) => {
-      const url = new URL(req.url ?? "/", `http://localhost`);
-
-      if (url.pathname !== "/callback") {
+      const url = new URL(req.url ?? "/", "http://127.0.0.1");
+      if (
+        url.pathname !== CALLBACK_PATH ||
+        url.searchParams.get("state") !== expectedState
+      ) {
         res.writeHead(404, { "Content-Type": "text/plain" });
         res.end("Not found");
         return;
       }
 
-      const receivedState = url.searchParams.get("state");
-      const sessionToken = url.searchParams.get("session_token");
-
-      if (receivedState !== state) {
+      const error = url.searchParams.get("error");
+      const code = url.searchParams.get("code");
+      if (error || !code) {
         res.writeHead(400, { "Content-Type": "text/html" });
-        res.end(renderLoginPage("Login Failed", "State mismatch. Please try again.", false));
-        cleanup("State mismatch — possible CSRF attack.");
-        return;
-      }
-
-      if (!sessionToken) {
-        res.writeHead(400, { "Content-Type": "text/html" });
-        res.end(renderLoginPage("Login Failed", "No session token received. Please try again.", false));
-        cleanup("No session token received from platform.");
+        res.end(
+          renderLoginPage(
+            "Login Failed",
+            "Please try again from your terminal.",
+            false,
+          ),
+        );
+        server.close();
+        settle.reject(
+          new Error(
+            `Authentication failed: ${error ?? "no authorization code received"}`,
+          ),
+        );
         return;
       }
 
       res.writeHead(200, { "Content-Type": "text/html" });
-      res.end(renderLoginPage("Login Successful", "You can close this window and return to your terminal.", true));
-      cleanup(null, sessionToken);
-    });
-
-    const timeout = setTimeout(() => {
-      cleanup("Login timed out. Please try again.");
-    }, LOGIN_TIMEOUT_MS);
-
-    function cleanup(error: string | null, token?: string): void {
-      clearTimeout(timeout);
+      res.end(
+        renderLoginPage(
+          "Login Successful",
+          "You can close this window and return to your terminal.",
+          true,
+        ),
+      );
       server.close();
-      if (error) {
-        reject(new Error(error));
-      } else if (token) {
-        resolve(token);
-      } else {
-        reject(new Error("Unknown error during login."));
-      }
-    }
+      settle.resolve(code);
+    });
 
-    server.on("error", (err) => cleanup(err.message));
+    server.on("error", rejectListener);
     server.listen(0, "127.0.0.1", () => {
       const addr = server.address();
       if (!addr || typeof addr === "string") {
-        cleanup("Failed to start local server.");
+        rejectListener(new Error("Failed to start local server."));
         return;
       }
+      const { port } = addr as AddressInfo;
+      resolveListener({
+        redirectUri: `http://127.0.0.1:${port}${CALLBACK_PATH}`,
+        waitForCode,
+        close: (reason?: string) => {
+          server.close();
+          settle.reject(new Error(reason ?? "Login cancelled."));
+        },
+      });
+    });
+  });
+}
+
+/** App-held WorkOS PKCE login */
+async function workosPkceLogin(platformUrl: string): Promise<string> {
+  const clientId = await fetchWorkosClientId(platformUrl);
+  const { verifier, challenge } = generatePkcePair();
+  const state = randomBytes(32).toString("hex");
 
-      const port = addr.port;
-      const returnTo = `/accounts/cli/callback?port=${port}&state=${state}`;
-      const loginUrl = `${webUrl}/account/login?returnTo=${encodeURIComponent(returnTo)}`;
+  const listener = await startLoopbackListener(state);
+  const timeout = setTimeout(() => {
+    listener.close("Login timed out. Please try again.");
+  }, LOGIN_TIMEOUT_MS);
 
-      console.log("Opening browser for login...");
-      console.log(`If the browser doesn't open, visit: ${loginUrl}`);
-      openBrowser(loginUrl);
+  try {
+    const authorizeUrl = buildAuthorizeUrl({
+      clientId,
+      redirectUri: listener.redirectUri,
+      challenge,
+      state,
     });
-  });
+
+    console.log("Opening browser for login...");
+    console.log(`If the browser doesn't open, visit: ${authorizeUrl}`);
+    openBrowser(authorizeUrl);
+
+    const code = await listener.waitForCode;
+    const accessToken = await exchangeCodeWithWorkos({
+      clientId,
+      code,
+      verifier,
+    });
+    return await exchangeAccessTokenForSession(
+      platformUrl,
+      clientId,
+      accessToken,
+    );
+  } finally {
+    clearTimeout(timeout);
+  }
 }
 
 export async function login(): Promise<void> {
@@ -306,11 +371,10 @@ export async function login(): Promise<void> {
     }
   }
 
-  // If no --token flag, use browser-based login
+  // If no --token flag, use app-held WorkOS PKCE login.
   if (!token) {
-    const webUrl = getWebUrl();
     try {
-      token = await browserLogin(webUrl);
+      token = await workosPkceLogin(getPlatformUrl());
     } catch (error) {
       console.error(`❌ ${error instanceof Error ? error.message : error}`);
       process.exit(1);

package/src/lib/workos-pkce.ts

@@ -0,0 +1,160 @@
+/**
+ * App-held PKCE login against WorkOS User Management (RFC 8252 loopback).
+ */
+
+import crypto from "node:crypto";
+
+import { loopbackSafeFetch } from "./loopback-fetch.js";
+
+const WORKOS_API_BASE_URL = "https://api.workos.com";
+const PROVIDER_ID = "workos";
+const SCOPE = "openid profile email";
+
+// Use a loopback callback: `http://127.0.0.1:*/auth/callback`
+export const CALLBACK_PATH = "/auth/callback";
+
+export interface PkcePair {
+  verifier: string;
+  challenge: string;
+}
+
+export function generatePkcePair(): PkcePair {
+  const verifier = crypto.randomBytes(32).toString("base64url");
+  const challenge = crypto
+    .createHash("sha256")
+    .update(verifier)
+    .digest("base64url");
+  return { verifier, challenge };
+}
+
+export interface AuthorizeUrlOptions {
+  clientId: string;
+  redirectUri: string;
+  challenge: string;
+  state: string;
+  loginHint?: string;
+  providerHint?: string;
+}
+
+export function buildAuthorizeUrl(options: AuthorizeUrlOptions): string {
+  const url = new URL("/user_management/authorize", WORKOS_API_BASE_URL);
+  url.searchParams.set("client_id", options.clientId);
+  url.searchParams.set("redirect_uri", options.redirectUri);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("scope", SCOPE);
+  url.searchParams.set("code_challenge", options.challenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  url.searchParams.set("state", options.state);
+  // No `prompt`: lets the browser's existing IdP session be reused.
+  url.searchParams.set("provider", options.providerHint || "authkit");
+  if (options.loginHint) url.searchParams.set("login_hint", options.loginHint);
+  return url.toString();
+}
+
+interface HeadlessProviderEntry {
+  id: string;
+  name?: string;
+  client_id?: string;
+  flows?: string[];
+  openid_configuration_url?: string;
+}
+
+/**
+ * Pick the OAuth2 WorkOS provider from the headless config. During the
+ * coexistence window two entries share the "workos-oidc" id; the usable one
+ * has token auth and no OIDC discovery URL. Null if none.
+ */
+export function selectWorkosClientId(
+  providers: HeadlessProviderEntry[],
+): string | null {
+  const entry = providers.find(
+    (p) =>
+      !p.openid_configuration_url &&
+      (p.flows ?? []).includes("provider_token") &&
+      typeof p.client_id === "string",
+  );
+  return entry?.client_id ?? null;
+}
+
+export async function fetchWorkosClientId(
+  platformUrl: string,
+): Promise<string> {
+  const url = `${new URL(platformUrl).origin}/_allauth/app/v1/config`;
+  const response = await loopbackSafeFetch(url);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch auth config (${response.status})`);
+  }
+  const body = (await response.json()) as {
+    data?: { socialaccount?: { providers?: HeadlessProviderEntry[] } };
+  };
+  const clientId = selectWorkosClientId(
+    body.data?.socialaccount?.providers ?? [],
+  );
+  if (!clientId) {
+    throw new Error(
+      "Platform does not advertise a token-auth WorkOS provider; cannot start PKCE login.",
+    );
+  }
+  return clientId;
+}
+
+/** Exchange the authorization code at WorkOS as a public client. */
+export async function exchangeCodeWithWorkos(options: {
+  clientId: string;
+  code: string;
+  verifier: string;
+}): Promise<string> {
+  const response = await loopbackSafeFetch(
+    `${WORKOS_API_BASE_URL}/user_management/authenticate`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        client_id: options.clientId,
+        grant_type: "authorization_code",
+        code: options.code,
+        code_verifier: options.verifier,
+      }),
+    },
+  );
+  if (!response.ok) {
+    const body = await response.text();
+    throw new Error(
+      `WorkOS code exchange failed (${response.status}): ${body}`,
+    );
+  }
+  const data = (await response.json()) as { access_token?: string };
+  if (!data.access_token) {
+    throw new Error("WorkOS code exchange returned no access token.");
+  }
+  return data.access_token;
+}
+
+/** Exchange the WorkOS access token for a platform session token. */
+export async function exchangeAccessTokenForSession(
+  platformUrl: string,
+  clientId: string,
+  accessToken: string,
+): Promise<string> {
+  const url = `${new URL(platformUrl).origin}/_allauth/app/v1/auth/provider/token`;
+  const response = await loopbackSafeFetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      provider: PROVIDER_ID,
+      process: "login",
+      token: { client_id: clientId, access_token: accessToken },
+    }),
+  });
+  if (!response.ok) {
+    const body = await response.text();
+    throw new Error(`Session exchange failed (${response.status}): ${body}`);
+  }
+  const data = (await response.json()) as {
+    meta?: { session_token?: string };
+  };
+  if (!data.meta?.session_token) {
+    throw new Error("Session exchange returned no session token.");
+  }
+  return data.meta.session_token;
+}