@voltro/plugin-auth-workos 0.33.0 → 0.34.0

package/dist/index.d.ts

@@ -7,24 +7,58 @@ declare interface ApiCallOptions {
     readonly fetchImpl?: typeof fetch;
 }
 
-/** Exchange an authorization code for the authenticated WorkOS user. */
+/**
+ * Exchange an authorization code for the authenticated WorkOS user — AFTER
+ * checking the CSRF `state`, and carrying the PKCE `code_verifier`.
+ *
+ * **The state check lives in here rather than beside the caller's `if (!code)`
+ * deliberately.** A generated `state` that nothing verifies is worse than no
+ * state at all: it makes a code review, a screenshot of the authorize URL and a
+ * penetration test all read as "CSRF is handled". Making the check part of the
+ * only function that can redeem a code means an integration cannot arrive at a
+ * session without having performed it — the loop is closed by the type
+ * signature, not by a note in the docs.
+ *
+ * Both values are compared in constant time. `state` is not a high-value secret,
+ * but it IS a secret compared against attacker-supplied input, and a `===` on
+ * that shape is the habit this repo does not keep.
+ */
 export declare const workosAuthenticateWithCode: (o: WorkosExchangeOptions) => Promise<WorkosProfile>;
 
 /** Verify a Magic Auth one-time code → the authenticated WorkOS user. */
 export declare const workosAuthenticateWithMagicAuth: (o: WorkosMagicAuthVerifyOptions) => Promise<WorkosProfile>;
 
-/** Build the WorkOS hosted-login URL to redirect the browser to. */
-export declare const workosAuthorizationUrl: (o: WorkosAuthorizationUrlOptions) => string;
+/**
+ * Begin a WorkOS hosted-login (AuthKit) flow: mint `state` + a PKCE
+ * `code_verifier`, and build the authorize URL carrying `state` and the S256
+ * `code_challenge`.
+ *
+ * **`state` is not optional and is not caller-supplied.** It used to be both —
+ * `if (o.state) params.set('state', o.state)` — which made the CSRF defence
+ * something an integration had to know to ask for, and made "the login works"
+ * indistinguishable from "the login is forgeable". An attacker who can get a
+ * victim's browser to hit a callback with an authorization code THEY obtained
+ * logs the victim into the ATTACKER's account; `state` is the only thing that
+ * stops it, so it is minted here, always, from `randomBytes`.
+ *
+ * **PKCE (S256) rides along.** The authorization code travels through the
+ * browser's address bar and the referrer chain; without a verifier, anyone who
+ * captures it before the app redeems it can redeem it themselves. WorkOS
+ * accepts `code_challenge`/`code_challenge_method` on authorize and
+ * `code_verifier` on authenticate, so the loop closes with no extra round trip.
+ *
+ * An app that used to carry a post-login return path INSIDE `state` puts it in
+ * its own cookie next to these two instead — mixing an application payload into
+ * a CSRF nonce is what made the nonce guessable in the first place.
+ */
+export declare const workosBeginLogin: (o: WorkosBeginLoginOptions) => WorkosLoginHandoff;
 
-export declare interface WorkosAuthorizationUrlOptions {
+export declare interface WorkosBeginLoginOptions {
     /** WorkOS Client ID (`client_01…`). */
     readonly clientId: string;
     /** The callback URL WorkOS redirects to with `?code=…&state=…`. Must be
      *  registered in the WorkOS dashboard. */
     readonly redirectUri: string;
-    /** Opaque state echoed back to the callback — use it for CSRF defence
-     *  and to carry a post-login return path. */
-    readonly state?: string;
     /** `'authkit'` (default) = WorkOS' hosted AuthKit UI; or a specific
      *  connection/provider id for direct SSO. */
     readonly provider?: string;
@@ -32,6 +66,15 @@ export declare interface WorkosAuthorizationUrlOptions {
     readonly loginHint?: string;
     /** Override the API origin (tests). Default `https://api.workos.com`. */
     readonly apiBase?: string;
+    /**
+     * Inject the two random values instead of minting them. TESTS ONLY — a
+     * deterministic `state` is a CSRF token an attacker can also predict, and a
+     * deterministic `codeVerifier` is no PKCE at all.
+     */
+    readonly randomness?: {
+        readonly state: string;
+        readonly codeVerifier: string;
+    };
 }
 
 /** Claims we expect from a WorkOS-issued AuthKit access token. The
@@ -86,6 +129,14 @@ export declare interface WorkosExchangeOptions {
     readonly apiKey: string;
     /** The `code` from the callback query string. */
     readonly code: string;
+    /** The `state` from the callback query string — what the browser presented. */
+    readonly state: string;
+    /** The `state` {@link workosBeginLogin} minted for this browser, read back
+     *  out of wherever the app stashed it. */
+    readonly expectedState: string;
+    /** The PKCE `codeVerifier` {@link workosBeginLogin} minted, read back out of
+     *  wherever the app stashed it. */
+    readonly codeVerifier: string;
     readonly apiBase?: string;
     /** Injectable fetch for tests. */
     readonly fetchImpl?: typeof fetch;
@@ -109,6 +160,25 @@ export declare const workosListUserMemberships: (o: ApiCallOptions & {
     readonly userId: string;
 }) => Promise<ReadonlyArray<WorkosMembership>>;
 
+/**
+ * What a login handoff produces: the URL to send the browser to, plus the two
+ * secrets the CALLBACK has to be able to check.
+ *
+ * Both `state` and `codeVerifier` must be stashed somewhere the same browser
+ * will present back — a short-lived `HttpOnly` cookie is the usual answer — and
+ * handed to {@link workosAuthenticateWithCode}. There is no server-side store
+ * here on purpose: this package is transport-thin, and where the app keeps a
+ * 10-minute nonce is the app's decision.
+ */
+export declare interface WorkosLoginHandoff {
+    /** The WorkOS hosted-login URL to redirect the browser to. */
+    readonly url: string;
+    /** The CSRF nonce. Compare against the callback's `?state=` before exchanging. */
+    readonly state: string;
+    /** The PKCE verifier. Send it with the code exchange. */
+    readonly codeVerifier: string;
+}
+
 export declare interface WorkosMagicAuthSendOptions {
     /** WorkOS API key (`sk_…`) — sent as a Bearer token. Server-only. */
     readonly apiKey: string;
@@ -162,6 +232,17 @@ export declare interface WorkosProfile {
  */
 export declare const workosSendMagicAuthCode: (o: WorkosMagicAuthSendOptions) => Promise<void>;
 
+/**
+ * The callback's `state` did not match the one minted for this browser.
+ *
+ * A distinct class because it is a distinct event: every other
+ * `WorkosExchangeError` means WorkOS said no, this one means the request did
+ * not come from a login THIS server started. Worth alerting on separately.
+ */
+export declare class WorkosStateMismatchError extends WorkosExchangeError {
+    constructor(message: string);
+}
+
 export declare const workosStrategy: (options: WorkosStrategyOptions) => AuthStrategy;
 
 export declare interface WorkosStrategyOptions {

package/dist/index.js

@@ -1,40 +1,53 @@
 import { jwtBearerStrategy as e } from "@voltro/protocol/jwt";
+import { createHash as t, randomBytes as n } from "node:crypto";
+import { timingSafeStringEqual as r } from "@voltro/protocol/session";
 //#region src/strategy.ts
-var t = "https://api.workos.com", n = "wos-session", r = (r) => {
-	if (!r.clientId) throw Error("workosStrategy: `clientId` is required");
-	let i = r.scopesFromClaims;
+var i = "https://api.workos.com", a = "wos-session", o = (t) => {
+	if (!t.clientId) throw Error("workosStrategy: `clientId` is required");
+	let n = t.scopesFromClaims;
 	return e({
 		id: "workos",
-		jwksUrl: r.jwksUrl ?? `${t}/sso/jwks/${r.clientId}`,
-		issuer: r.issuer ?? t,
-		audience: r.clientId,
+		jwksUrl: t.jwksUrl ?? `${i}/sso/jwks/${t.clientId}`,
+		issuer: t.issuer ?? i,
+		audience: t.clientId,
 		algorithms: ["RS256", "ES256"],
-		cookieName: r.cookieName === void 0 ? n : r.cookieName,
-		tenantIdFromClaims: (e) => r.tenantIdFromClaims?.(e) ?? (typeof e.org_id == "string" ? e.org_id : void 0) ?? r.defaultTenantId ?? null,
-		...i === void 0 ? {} : { scopesFromClaims: (e) => i(e) }
+		cookieName: t.cookieName === void 0 ? a : t.cookieName,
+		tenantIdFromClaims: (e) => t.tenantIdFromClaims?.(e) ?? (typeof e.org_id == "string" ? e.org_id : void 0) ?? t.defaultTenantId ?? null,
+		...n === void 0 ? {} : { scopesFromClaims: (e) => n(e) }
 	});
-}, i = "https://api.workos.com", a = (e) => {
-	if (!e.clientId) throw Error("workosAuthorizationUrl: `clientId` is required");
-	if (!e.redirectUri) throw Error("workosAuthorizationUrl: `redirectUri` is required");
-	let t = new URLSearchParams({
+}, s = "https://api.workos.com", c = (e) => e.toString("base64url"), l = () => c(n(32)), u = (e) => c(t("sha256").update(e, "ascii").digest()), d = (e) => {
+	if (!e.clientId) throw Error("workosBeginLogin: `clientId` is required");
+	if (!e.redirectUri) throw Error("workosBeginLogin: `redirectUri` is required");
+	let t = e.randomness?.state ?? l(), n = e.randomness?.codeVerifier ?? l(), r = new URLSearchParams({
 		client_id: e.clientId,
 		redirect_uri: e.redirectUri,
 		response_type: "code",
-		provider: e.provider ?? "authkit"
+		provider: e.provider ?? "authkit",
+		state: t,
+		code_challenge: u(n),
+		code_challenge_method: "S256"
 	});
-	return e.state && t.set("state", e.state), e.loginHint && t.set("login_hint", e.loginHint), `${e.apiBase ?? i}/user_management/authorize?${t.toString()}`;
-}, o = class extends Error {
+	return e.loginHint && r.set("login_hint", e.loginHint), {
+		url: `${e.apiBase ?? s}/user_management/authorize?${r.toString()}`,
+		state: t,
+		codeVerifier: n
+	};
+}, f = class extends Error {
 	status;
 	constructor(e, t) {
 		super(t), this.status = e, this.name = "WorkosExchangeError";
 	}
-}, s = async (e) => {
+}, p = class extends f {
+	constructor(e) {
+		super(400, e), this.name = "WorkosStateMismatchError";
+	}
+}, m = async (e) => {
 	if (!e.ok) {
 		let t = await e.text().catch(() => "");
-		throw new o(e.status, `WorkOS authenticate failed (${e.status}): ${t.slice(0, 200)}`);
+		throw new f(e.status, `WorkOS authenticate failed (${e.status}): ${t.slice(0, 200)}`);
 	}
 	let t = await e.json(), n = t.user;
-	if (!n?.id || !n.email) throw new o(e.status, "WorkOS authenticate response missing user id/email");
+	if (!n?.id || !n.email) throw new f(e.status, "WorkOS authenticate response missing user id/email");
 	return {
 		workosUserId: n.id,
 		email: n.email,
@@ -42,21 +55,25 @@ var t = "https://api.workos.com", n = "wos-session", r = (r) => {
 		lastName: n.last_name ?? null,
 		organizationId: t.organization_id ?? null
 	};
-}, c = async (e) => {
-	if (!e.code) throw new o(400, "workosAuthenticateWithCode: missing `code`");
-	return s(await (e.fetchImpl ?? fetch)(`${e.apiBase ?? i}/user_management/authenticate`, {
+}, h = async (e) => {
+	if (!e.code) throw new f(400, "workosAuthenticateWithCode: missing `code`");
+	if (!e.expectedState) throw new p("workosAuthenticateWithCode: no `expectedState` — the login was never started by this server, or the state cookie expired. Refusing to exchange the code.");
+	if (!e.state || !r(e.state, e.expectedState)) throw new p("workosAuthenticateWithCode: `state` does not match the value minted for this browser (possible CSRF).");
+	if (!e.codeVerifier) throw new f(400, "workosAuthenticateWithCode: missing `codeVerifier` (PKCE)");
+	return m(await (e.fetchImpl ?? fetch)(`${e.apiBase ?? s}/user_management/authenticate`, {
 		method: "POST",
 		headers: { "content-type": "application/json" },
 		body: JSON.stringify({
 			client_id: e.clientId,
 			client_secret: e.apiKey,
 			grant_type: "authorization_code",
-			code: e.code
+			code: e.code,
+			code_verifier: e.codeVerifier
 		})
 	}));
-}, l = async (e) => {
-	if (!e.email) throw new o(400, "workosSendMagicAuthCode: missing `email`");
-	let t = await (e.fetchImpl ?? fetch)(`${e.apiBase ?? i}/user_management/magic_auth`, {
+}, g = async (e) => {
+	if (!e.email) throw new f(400, "workosSendMagicAuthCode: missing `email`");
+	let t = await (e.fetchImpl ?? fetch)(`${e.apiBase ?? s}/user_management/magic_auth`, {
 		method: "POST",
 		headers: {
 			"content-type": "application/json",
@@ -66,12 +83,12 @@ var t = "https://api.workos.com", n = "wos-session", r = (r) => {
 	});
 	if (!t.ok) {
 		let e = await t.text().catch(() => "");
-		throw new o(t.status, `WorkOS magic-auth send failed (${t.status}): ${e.slice(0, 200)}`);
+		throw new f(t.status, `WorkOS magic-auth send failed (${t.status}): ${e.slice(0, 200)}`);
 	}
-}, u = async (e) => {
-	if (!e.code) throw new o(400, "workosAuthenticateWithMagicAuth: missing `code`");
-	if (!e.email) throw new o(400, "workosAuthenticateWithMagicAuth: missing `email`");
-	return s(await (e.fetchImpl ?? fetch)(`${e.apiBase ?? i}/user_management/authenticate`, {
+}, _ = async (e) => {
+	if (!e.code) throw new f(400, "workosAuthenticateWithMagicAuth: missing `code`");
+	if (!e.email) throw new f(400, "workosAuthenticateWithMagicAuth: missing `email`");
+	return m(await (e.fetchImpl ?? fetch)(`${e.apiBase ?? s}/user_management/authenticate`, {
 		method: "POST",
 		headers: { "content-type": "application/json" },
 		body: JSON.stringify({
@@ -82,8 +99,8 @@ var t = "https://api.workos.com", n = "wos-session", r = (r) => {
 			email: e.email
 		})
 	}));
-}, d = "https://api.workos.com", f = async (e, t, n, r) => {
-	let i = await (e.fetchImpl ?? fetch)(`${e.apiBase ?? d}${n}`, {
+}, v = "https://api.workos.com", y = async (e, t, n, r) => {
+	let i = await (e.fetchImpl ?? fetch)(`${e.apiBase ?? v}${n}`, {
 		method: t,
 		headers: {
 			authorization: `Bearer ${e.apiKey}`,
@@ -93,18 +110,18 @@ var t = "https://api.workos.com", n = "wos-session", r = (r) => {
 	});
 	if (!i.ok) {
 		let e = await i.text().catch(() => "");
-		throw new o(i.status, `WorkOS ${t} ${n} failed (${i.status}): ${e.slice(0, 200)}`);
+		throw new f(i.status, `WorkOS ${t} ${n} failed (${i.status}): ${e.slice(0, 200)}`);
 	}
 	if (i.status !== 204) return await i.json();
-}, p = (e) => {
-	if (!e.id) throw new o(502, "WorkOS organization response missing id");
+}, b = (e) => {
+	if (!e.id) throw new f(502, "WorkOS organization response missing id");
 	return {
 		id: e.id,
 		name: e.name ?? ""
 	};
-}, m = async (e) => {
-	if (!e.name) throw new o(400, "workosCreateOrganization: missing `name`");
-	let t = await (e.fetchImpl ?? fetch)(`${e.apiBase ?? d}/organizations`, {
+}, x = async (e) => {
+	if (!e.name) throw new f(400, "workosCreateOrganization: missing `name`");
+	let t = await (e.fetchImpl ?? fetch)(`${e.apiBase ?? v}/organizations`, {
 		method: "POST",
 		headers: {
 			authorization: `Bearer ${e.apiKey}`,
@@ -115,11 +132,11 @@ var t = "https://api.workos.com", n = "wos-session", r = (r) => {
 	});
 	if (!t.ok) {
 		let e = await t.text().catch(() => "");
-		throw new o(t.status, `WorkOS create organization failed (${t.status}): ${e.slice(0, 200)}`);
+		throw new f(t.status, `WorkOS create organization failed (${t.status}): ${e.slice(0, 200)}`);
 	}
-	return p(await t.json());
-}, h = async (e) => p(await f(e, "GET", `/organizations/${encodeURIComponent(e.organizationId)}`)), g = async (e) => p(await f(e, "PUT", `/organizations/${encodeURIComponent(e.organizationId)}`, { name: e.name })), _ = (e) => {
-	if (!e.id || !e.user_id || !e.organization_id) throw new o(502, "WorkOS membership response missing id/user_id/organization_id");
+	return b(await t.json());
+}, S = async (e) => b(await y(e, "GET", `/organizations/${encodeURIComponent(e.organizationId)}`)), C = async (e) => b(await y(e, "PUT", `/organizations/${encodeURIComponent(e.organizationId)}`, { name: e.name })), w = (e) => {
+	if (!e.id || !e.user_id || !e.organization_id) throw new f(502, "WorkOS membership response missing id/user_id/organization_id");
 	return {
 		id: e.id,
 		userId: e.user_id,
@@ -127,11 +144,11 @@ var t = "https://api.workos.com", n = "wos-session", r = (r) => {
 		roleSlug: e.role?.slug ?? null,
 		status: e.status ?? "active"
 	};
-}, v = async (e) => _(await f(e, "POST", "/user_management/organization_memberships", {
+}, T = async (e) => w(await y(e, "POST", "/user_management/organization_memberships", {
 	user_id: e.userId,
 	organization_id: e.organizationId,
 	...e.roleSlug ? { role_slug: e.roleSlug } : {}
-})), y = async (e) => {
+})), E = async (e) => {
 	let t = [], n;
 	for (let r = 0; r < 100; r++) {
 		let r = new URLSearchParams({
@@ -139,24 +156,24 @@ var t = "https://api.workos.com", n = "wos-session", r = (r) => {
 			limit: "100"
 		});
 		n && r.set("after", n);
-		let i = await f(e, "GET", `/user_management/organization_memberships?${r.toString()}`);
-		for (let e of i.data ?? []) t.push(_(e));
+		let i = await y(e, "GET", `/user_management/organization_memberships?${r.toString()}`);
+		for (let e of i.data ?? []) t.push(w(e));
 		let a = i.list_metadata?.after;
 		if (!a) break;
 		n = a;
 	}
 	return t;
-}, b = async (e) => {
-	await f(e, "DELETE", `/user_management/organization_memberships/${encodeURIComponent(e.membershipId)}`);
-}, x = async (e) => {
-	if (!e.email) throw new o(400, "workosCreateInvitation: missing `email`");
-	let t = await f(e, "POST", "/user_management/invitations", {
+}, D = async (e) => {
+	await y(e, "DELETE", `/user_management/organization_memberships/${encodeURIComponent(e.membershipId)}`);
+}, O = async (e) => {
+	if (!e.email) throw new f(400, "workosCreateInvitation: missing `email`");
+	let t = await y(e, "POST", "/user_management/invitations", {
 		email: e.email,
 		organization_id: e.organizationId,
 		...e.roleSlug ? { role_slug: e.roleSlug } : {},
 		...e.inviterUserId ? { inviter_user_id: e.inviterUserId } : {}
 	});
-	if (!t.id || !t.email) throw new o(502, "WorkOS invitation response missing id/email");
+	if (!t.id || !t.email) throw new f(502, "WorkOS invitation response missing id/email");
 	return {
 		id: t.id,
 		email: t.email,
@@ -165,4 +182,4 @@ var t = "https://api.workos.com", n = "wos-session", r = (r) => {
 	};
 };
 //#endregion
-export { o as WorkosExchangeError, c as workosAuthenticateWithCode, u as workosAuthenticateWithMagicAuth, a as workosAuthorizationUrl, x as workosCreateInvitation, v as workosCreateMembership, m as workosCreateOrganization, b as workosDeleteMembership, h as workosGetOrganization, y as workosListUserMemberships, l as workosSendMagicAuthCode, r as workosStrategy, g as workosUpdateOrganization };
+export { f as WorkosExchangeError, p as WorkosStateMismatchError, h as workosAuthenticateWithCode, _ as workosAuthenticateWithMagicAuth, d as workosBeginLogin, O as workosCreateInvitation, T as workosCreateMembership, x as workosCreateOrganization, D as workosDeleteMembership, S as workosGetOrganization, E as workosListUserMemberships, g as workosSendMagicAuthCode, o as workosStrategy, C as workosUpdateOrganization };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/plugin-auth-workos",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "description": "WorkOS-backed AuthStrategy for the Voltro framework. Verifies WorkOS AuthKit/SSO JWTs via JWKS and maps `org_id`→tenant. Composes via @voltro/protocol AuthStrategy alongside other IdP plugins.",
   "keywords": [
     "voltro",
@@ -33,7 +33,7 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@voltro/protocol": "0.33.0"
+    "@voltro/protocol": "0.34.0"
   },
   "peerDependencies": {
     "effect": "^3.22.0"