@usehercules/auth-tanstack 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Grant Gurvis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.mts

@@ -0,0 +1,48 @@
+import { IDToken } from "openid-client";
+
+//#region src/types.d.ts
+type User = {};
+type Impersonator = {};
+type Session = {};
+type AuthResult = {};
+type BaseTokenClaims = {};
+type CustomClaims = {};
+//#endregion
+//#region src/server/types.d.ts
+interface HandleSignInOptions {
+  redirectUri?: string;
+  scope?: string;
+}
+interface HandleCallbackOptions {
+  returnPathname?: string;
+  onSuccess?: (data: HandleAuthSuccessData) => void | Promise<void>;
+  onError?: (params: {
+    error?: unknown;
+    request: Request;
+  }) => Response | Promise<Response>;
+  errorRedirectUrl?: string;
+}
+interface HandleAuthSuccessData {
+  accessToken: string;
+  idToken?: string;
+  refreshToken?: string;
+  expiresIn?: number;
+  scope?: string;
+  claims?: IDToken;
+  state?: string;
+}
+//#endregion
+//#region src/server/server.d.ts
+declare function handleSignInRoute(options?: HandleSignInOptions): ({
+  request
+}: {
+  request: Request;
+}) => Promise<Response>;
+declare function handleCallbackRoute(options?: HandleCallbackOptions): ({
+  request
+}: {
+  request: Request;
+}) => Promise<Response>;
+//#endregion
+export { type AuthResult, type BaseTokenClaims, type CustomClaims, type HandleAuthSuccessData, type HandleCallbackOptions, type HandleSignInOptions, type Impersonator, type Session, type User, handleCallbackRoute, handleSignInRoute };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/types.ts","../src/server/types.ts","../src/server/server.ts"],"mappings":";;;KAAY,IAAA;AAAA,KACA,YAAA;AAAA,KACA,OAAA;AAAA,KACA,UAAA;AAAA,KACA,eAAA;AAAA,KACA,YAAA;;;UCHK,mBAAA;EAUf,WAAA;EAKA,KAAK;AAAA;AAAA,UAGU,qBAAA;EACf,cAAA;EACA,SAAA,IAAa,IAAA,EAAM,qBAAA,YAAiC,OAAA;EAUpD,OAAA,IAAW,MAAA;IAAU,KAAA;IAAiB,OAAA,EAAS,OAAA;EAAA,MAAc,QAAA,GAAW,OAAA,CAAQ,QAAA;EAqBhF,gBAAA;AAAA;AAAA,UAUe,qBAAA;EAEf,WAAA;EAEA,OAAA;EAEA,YAAA;EAEA,SAAA;EAEA,KAAA;EAKA,MAAA,GAAS,OAAO;EAEhB,KAAA;AAAA;;;iBCuDc,iBAAA,CAAkB,OAAA,GAAU,mBAAA;EAC5B;AAAA;EAAe,OAAA,EAAS,OAAA;AAAA,MAAY,OAAA,CAAQ,QAAA;AAAA,iBA4E5C,mBAAA,CAAoB,OAAA,GAAU,qBAAA;EAC9B;AAAA;EAAe,OAAA,EAAS,OAAA;AAAA,MAAY,OAAA,CAAQ,QAAA"}

package/dist/index.mjs

@@ -0,0 +1,252 @@
+import * as client from "openid-client";
+//#region src/server/cookie-utils.ts
+function parseCookies(cookieHeader) {
+	if (!cookieHeader.trim()) return {};
+	return Object.fromEntries(cookieHeader.split(";").map((cookie) => {
+		const [key, ...valueParts] = cookie.trim().split("=");
+		return [key, valueParts.join("=")];
+	}));
+}
+/**
+* Parse only the cookie names from a `Cookie` header, skipping the values.
+*
+* Use this when you need the set of cookie names but not their contents — it
+* avoids allocating the (potentially large) value strings that `parseCookies`
+* materializes. Relevant on the PKCE-verifier eviction path, where the header
+* can carry many large encrypted verifier blobs whose values are irrelevant.
+*/
+function parseCookieNames(cookieHeader) {
+	if (!cookieHeader.trim()) return [];
+	return cookieHeader.split(";").map((cookie) => {
+		const eq = cookie.indexOf("=");
+		return (eq === -1 ? cookie : cookie.slice(0, eq)).trim();
+	}).filter(Boolean);
+}
+/**
+* Serialize a cookie name/value pair into a `Set-Cookie` header string.
+*
+* Only the attributes needed by this package are supported. `maxAge` is floored
+* to a whole number of seconds; pass `0` to expire a cookie immediately.
+*/
+function serializeCookie(name, value, options = {}) {
+	const parts = [`${name}=${value}`];
+	if (options.path) parts.push(`Path=${options.path}`);
+	if (options.maxAge !== void 0) parts.push(`Max-Age=${Math.floor(options.maxAge)}`);
+	if (options.httpOnly) parts.push("HttpOnly");
+	if (options.secure) parts.push("Secure");
+	if (options.sameSite) parts.push(`SameSite=${options.sameSite}`);
+	return parts.join("; ");
+}
+//#endregion
+//#region src/server/server.ts
+/**
+* OIDC issuer URL used for discovery (`{issuer}/.well-known/openid-configuration`).
+* For Amazon Cognito this is the user-pool issuer
+* (`https://cognito-idp.<region>.amazonaws.com/<userPoolId>`), NOT the hosted-UI
+* domain — the hosted domain does not serve the discovery document.
+*/
+const ISSUER_URL_ENV = "HERCULES_AUTH_ISSUER_URL";
+/** OAuth client (app client) identifier. */
+const CLIENT_ID_ENV = "HERCULES_AUTH_CLIENT_ID";
+/** OAuth client secret. Optional — omit for a public (PKCE-only) client. */
+const CLIENT_SECRET_ENV = "HERCULES_AUTH_CLIENT_SECRET";
+/**
+* Prefix for per-flow PKCE cookies. Each pending sign-in stores its
+* `code_verifier` under `${PKCE_COOKIE_PREFIX}${state}`, so concurrent flows
+* (a double-click, a retry, a second tab) keep independent cookies instead of
+* overwriting one shared name and invalidating each other.
+*/
+const PKCE_COOKIE_PREFIX = "hercules_pkce_";
+/** Cookie holding the authenticated session token. */
+const AUTH_COOKIE = "hercules_session";
+/** Where to send the user once the callback completes. */
+const DEFAULT_REDIRECT = "/";
+/** Callback route the provider returns to, unless overridden. */
+const DEFAULT_CALLBACK_PATH = "/api/auth/callback";
+/** OAuth scopes requested when none are configured. */
+const DEFAULT_SCOPE = "openid profile email";
+/** Lifetime (seconds) of a pending sign-in's PKCE cookie. */
+const SIGN_IN_COOKIE_MAX_AGE = 600;
+/**
+* Cap on simultaneously pending sign-in flows. Beyond this we expire surplus
+* verifier cookies on the next sign-in so the request `Cookie` header cannot
+* grow without bound from abandoned attempts.
+*/
+const MAX_PENDING_SIGN_INS = 10;
+/** Cookie name holding the PKCE verifier for the flow identified by `state`. */
+function pkceCookieName(state) {
+	return PKCE_COOKIE_PREFIX + state;
+}
+function requireEnv(name) {
+	const value = process.env[name];
+	if (!value) throw new Error(`[auth-tanstack] Missing required environment variable: ${name}`);
+	return value;
+}
+let configPromise;
+function getConfig() {
+	if (!configPromise) {
+		const issuerUrl = new URL(requireEnv(ISSUER_URL_ENV));
+		const clientId = requireEnv(CLIENT_ID_ENV);
+		const clientSecret = process.env[CLIENT_SECRET_ENV];
+		configPromise = (clientSecret ? client.discovery(issuerUrl, clientId, clientSecret) : client.discovery(issuerUrl, clientId, void 0, client.None())).catch((error) => {
+			configPromise = void 0;
+			throw error;
+		});
+	}
+	return configPromise;
+}
+/** Append a `Set-Cookie` that immediately expires the named cookie. */
+function deleteCookie(headers, name) {
+	headers.append("Set-Cookie", serializeCookie(name, "", {
+		path: "/",
+		maxAge: 0
+	}));
+}
+/**
+* Resolve a callback failure into a Response, honoring the caller's error
+* handling preferences (see {@link HandleCallbackOptions}). `onError` wins over
+* `errorRedirectUrl`, which in turn wins over the default JSON error response.
+*
+* When `clearCookieName` is given (the failed flow's verifier cookie) it is
+* expired; other pending sign-in flows are left untouched.
+*/
+async function handleError(request, status, message, error, options, clearCookieName) {
+	if (options?.onError) return options.onError({
+		error,
+		request
+	});
+	if (options?.errorRedirectUrl) try {
+		const location = new URL(options.errorRedirectUrl, new URL(request.url).origin).toString();
+		const headers = new Headers({ Location: location });
+		if (clearCookieName) deleteCookie(headers, clearCookieName);
+		return new Response(null, {
+			status: 302,
+			headers
+		});
+	} catch {
+		console.warn(`[auth-tanstack] Ignoring malformed errorRedirectUrl: ${options.errorRedirectUrl}`);
+	}
+	const headers = new Headers({ "Content-Type": "application/json" });
+	if (clearCookieName) deleteCookie(headers, clearCookieName);
+	return new Response(JSON.stringify({ error: message }), {
+		status,
+		headers
+	});
+}
+/**
+* Build a TanStack route handler that initiates the OIDC login.
+*
+* Navigating to (redirecting to) the route this is mounted on starts the
+* Authorization Code + PKCE flow: it generates a fresh `code_verifier` and
+* `state`, stashes them in short-lived cookies for {@link handleCallbackRoute}
+* to consume, and redirects the user-agent to the provider's authorization
+* endpoint.
+*
+* @public
+*/
+function handleSignInRoute(options) {
+	return async ({ request }) => {
+		return handleSignInInternal(request, options);
+	};
+}
+async function handleSignInInternal(request, options) {
+	const url = new URL(request.url);
+	const codeVerifier = client.randomPKCECodeVerifier();
+	const codeChallenge = await client.calculatePKCECodeChallenge(codeVerifier);
+	const state = client.randomState();
+	const redirectUri = new URL(options?.redirectUri ?? DEFAULT_CALLBACK_PATH, url.origin).toString();
+	let authorizationUrl;
+	try {
+		const config = await getConfig();
+		authorizationUrl = client.buildAuthorizationUrl(config, {
+			redirect_uri: redirectUri,
+			scope: options?.scope ?? DEFAULT_SCOPE,
+			state,
+			code_challenge: codeChallenge,
+			code_challenge_method: "S256"
+		});
+	} catch {
+		return new Response(JSON.stringify({ error: "Failed to start sign-in" }), {
+			status: 500,
+			headers: { "Content-Type": "application/json" }
+		});
+	}
+	const headers = new Headers({ Location: authorizationUrl.toString() });
+	headers.append("Set-Cookie", serializeCookie(pkceCookieName(state), codeVerifier, {
+		httpOnly: true,
+		secure: url.protocol === "https:",
+		sameSite: "Lax",
+		path: "/",
+		maxAge: SIGN_IN_COOKIE_MAX_AGE
+	}));
+	const pending = parseCookieNames(request.headers.get("cookie") ?? "").filter((name) => name.startsWith(PKCE_COOKIE_PREFIX));
+	for (const name of pending.slice(MAX_PENDING_SIGN_INS - 1)) deleteCookie(headers, name);
+	return new Response(null, {
+		status: 302,
+		headers
+	});
+}
+/**
+* Build a TanStack route handler for the OAuth/OIDC callback.
+*
+* The handler completes the authorization-code grant using the PKCE
+* `code_verifier` and `state` stashed in cookies during sign-in, invokes
+* {@link HandleCallbackOptions.onSuccess} with the token response, stores the
+* resulting session token in an HttpOnly cookie, clears the one-time sign-in
+* cookies, and redirects the user to {@link HandleCallbackOptions.returnPathname}.
+*
+* @public
+*/
+function handleCallbackRoute(options) {
+	return async ({ request }) => {
+		return handleCallbackInternal(request, options);
+	};
+}
+async function handleCallbackInternal(request, options) {
+	const url = new URL(request.url);
+	if (!url.searchParams.get("code")) return handleError(request, 400, "Missing code parameter", void 0, options);
+	const state = url.searchParams.get("state");
+	if (!state) return handleError(request, 400, "Missing state parameter", void 0, options);
+	const verifierCookieName = pkceCookieName(state);
+	const pkceCodeVerifier = parseCookies(request.headers.get("cookie") ?? "")[verifierCookieName];
+	if (!pkceCodeVerifier) return handleError(request, 400, "Unknown or expired sign-in state", void 0, options);
+	const checks = {
+		pkceCodeVerifier,
+		expectedState: state
+	};
+	let tokens;
+	try {
+		const config = await getConfig();
+		tokens = await client.authorizationCodeGrant(config, url, checks);
+	} catch (error) {
+		return handleError(request, 500, "Token exchange failed", error, options, verifierCookieName);
+	}
+	const data = {
+		accessToken: tokens.access_token,
+		idToken: tokens.id_token,
+		refreshToken: tokens.refresh_token,
+		expiresIn: tokens.expires_in,
+		scope: tokens.scope,
+		claims: tokens.claims(),
+		state
+	};
+	await options?.onSuccess?.(data);
+	const secure = url.protocol === "https:";
+	const headers = new Headers({ Location: options?.returnPathname ?? DEFAULT_REDIRECT });
+	headers.append("Set-Cookie", serializeCookie(AUTH_COOKIE, data.idToken ?? data.accessToken, {
+		httpOnly: true,
+		secure,
+		sameSite: "Lax",
+		path: "/",
+		maxAge: data.expiresIn
+	}));
+	deleteCookie(headers, verifierCookieName);
+	return new Response(null, {
+		status: 302,
+		headers
+	});
+}
+//#endregion
+export { handleCallbackRoute, handleSignInRoute };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/server/cookie-utils.ts","../src/server/server.ts"],"sourcesContent":["export function parseCookies(cookieHeader: string): Record<string, string> {\n  if (!cookieHeader.trim()) return {};\n  return Object.fromEntries(\n    cookieHeader.split(\";\").map((cookie) => {\n      const [key, ...valueParts] = cookie.trim().split(\"=\");\n      return [key, valueParts.join(\"=\")];\n    }),\n  );\n}\n\n/**\n * Parse only the cookie names from a `Cookie` header, skipping the values.\n *\n * Use this when you need the set of cookie names but not their contents — it\n * avoids allocating the (potentially large) value strings that `parseCookies`\n * materializes. Relevant on the PKCE-verifier eviction path, where the header\n * can carry many large encrypted verifier blobs whose values are irrelevant.\n */\nexport function parseCookieNames(cookieHeader: string): string[] {\n  if (!cookieHeader.trim()) return [];\n  return cookieHeader\n    .split(\";\")\n    .map((cookie) => {\n      const eq = cookie.indexOf(\"=\");\n      return (eq === -1 ? cookie : cookie.slice(0, eq)).trim();\n    })\n    .filter(Boolean);\n}\n\nexport interface CookieOptions {\n  httpOnly?: boolean;\n  secure?: boolean;\n  sameSite?: \"Strict\" | \"Lax\" | \"None\";\n  path?: string;\n  maxAge?: number;\n}\n\n/**\n * Serialize a cookie name/value pair into a `Set-Cookie` header string.\n *\n * Only the attributes needed by this package are supported. `maxAge` is floored\n * to a whole number of seconds; pass `0` to expire a cookie immediately.\n */\nexport function serializeCookie(\n  name: string,\n  value: string,\n  options: CookieOptions = {},\n): string {\n  const parts = [`${name}=${value}`];\n  if (options.path) parts.push(`Path=${options.path}`);\n  if (options.maxAge !== undefined) parts.push(`Max-Age=${Math.floor(options.maxAge)}`);\n  if (options.httpOnly) parts.push(\"HttpOnly\");\n  if (options.secure) parts.push(\"Secure\");\n  if (options.sameSite) parts.push(`SameSite=${options.sameSite}`);\n  return parts.join(\"; \");\n}\n","import * as client from \"openid-client\";\nimport { parseCookieNames, parseCookies, serializeCookie } from \"./cookie-utils\";\nimport type { HandleAuthSuccessData, HandleCallbackOptions, HandleSignInOptions } from \"./types\";\n\nexport type { HandleAuthSuccessData, HandleCallbackOptions, HandleSignInOptions } from \"./types\";\n\n/**\n * OIDC issuer URL used for discovery (`{issuer}/.well-known/openid-configuration`).\n * For Amazon Cognito this is the user-pool issuer\n * (`https://cognito-idp.<region>.amazonaws.com/<userPoolId>`), NOT the hosted-UI\n * domain — the hosted domain does not serve the discovery document.\n */\nconst ISSUER_URL_ENV = \"HERCULES_AUTH_ISSUER_URL\";\n/** OAuth client (app client) identifier. */\nconst CLIENT_ID_ENV = \"HERCULES_AUTH_CLIENT_ID\";\n/** OAuth client secret. Optional — omit for a public (PKCE-only) client. */\nconst CLIENT_SECRET_ENV = \"HERCULES_AUTH_CLIENT_SECRET\";\n\n/**\n * Prefix for per-flow PKCE cookies. Each pending sign-in stores its\n * `code_verifier` under `${PKCE_COOKIE_PREFIX}${state}`, so concurrent flows\n * (a double-click, a retry, a second tab) keep independent cookies instead of\n * overwriting one shared name and invalidating each other.\n */\nconst PKCE_COOKIE_PREFIX = \"hercules_pkce_\";\n/** Cookie holding the authenticated session token. */\nconst AUTH_COOKIE = \"hercules_session\";\n\n/** Where to send the user once the callback completes. */\nconst DEFAULT_REDIRECT = \"/\";\n/** Callback route the provider returns to, unless overridden. */\nconst DEFAULT_CALLBACK_PATH = \"/api/auth/callback\";\n/** OAuth scopes requested when none are configured. */\nconst DEFAULT_SCOPE = \"openid profile email\";\n/** Lifetime (seconds) of a pending sign-in's PKCE cookie. */\nconst SIGN_IN_COOKIE_MAX_AGE = 600;\n/**\n * Cap on simultaneously pending sign-in flows. Beyond this we expire surplus\n * verifier cookies on the next sign-in so the request `Cookie` header cannot\n * grow without bound from abandoned attempts.\n */\nconst MAX_PENDING_SIGN_INS = 10;\n\n/** Cookie name holding the PKCE verifier for the flow identified by `state`. */\nfunction pkceCookieName(state: string): string {\n  return PKCE_COOKIE_PREFIX + state;\n}\n\nfunction requireEnv(name: string): string {\n  const value = process.env[name];\n  if (!value) {\n    throw new Error(`[auth-tanstack] Missing required environment variable: ${name}`);\n  }\n  return value;\n}\n\n// Discovery is a network round-trip and the resolved metadata is static for the\n// lifetime of the process, so resolve the Configuration once and reuse it.\nlet configPromise: Promise<client.Configuration> | undefined;\nfunction getConfig(): Promise<client.Configuration> {\n  if (!configPromise) {\n    const issuerUrl = new URL(requireEnv(ISSUER_URL_ENV));\n    const clientId = requireEnv(CLIENT_ID_ENV);\n    const clientSecret = process.env[CLIENT_SECRET_ENV];\n\n    // A public client authenticates with PKCE alone (no secret); a confidential\n    // client authenticates the token request with its secret.\n    const discovered = clientSecret\n      ? client.discovery(issuerUrl, clientId, clientSecret)\n      : client.discovery(issuerUrl, clientId, undefined, client.None());\n\n    configPromise = discovered.catch((error) => {\n      // Don't cache a failed discovery — let the next request retry instead of\n      // permanently poisoning every sign-in and callback.\n      configPromise = undefined;\n      throw error;\n    });\n  }\n  return configPromise;\n}\n\n/** Append a `Set-Cookie` that immediately expires the named cookie. */\nfunction deleteCookie(headers: Headers, name: string): void {\n  headers.append(\"Set-Cookie\", serializeCookie(name, \"\", { path: \"/\", maxAge: 0 }));\n}\n\n/**\n * Resolve a callback failure into a Response, honoring the caller's error\n * handling preferences (see {@link HandleCallbackOptions}). `onError` wins over\n * `errorRedirectUrl`, which in turn wins over the default JSON error response.\n *\n * When `clearCookieName` is given (the failed flow's verifier cookie) it is\n * expired; other pending sign-in flows are left untouched.\n */\nasync function handleError(\n  request: Request,\n  status: 400 | 500,\n  message: string,\n  error: unknown,\n  options?: HandleCallbackOptions,\n  clearCookieName?: string,\n): Promise<Response> {\n  // `onError` is intentionally not wrapped — errors it throws propagate.\n  if (options?.onError) {\n    return options.onError({ error, request });\n  }\n\n  if (options?.errorRedirectUrl) {\n    try {\n      const location = new URL(options.errorRedirectUrl, new URL(request.url).origin).toString();\n      const headers = new Headers({ Location: location });\n      if (clearCookieName) deleteCookie(headers, clearCookieName);\n      return new Response(null, { status: 302, headers });\n    } catch {\n      // Malformed config value — warn and fall back to the JSON error response.\n      console.warn(`[auth-tanstack] Ignoring malformed errorRedirectUrl: ${options.errorRedirectUrl}`);\n    }\n  }\n\n  const headers = new Headers({ \"Content-Type\": \"application/json\" });\n  if (clearCookieName) deleteCookie(headers, clearCookieName);\n  return new Response(JSON.stringify({ error: message }), { status, headers });\n}\n\n/**\n * Build a TanStack route handler that initiates the OIDC login.\n *\n * Navigating to (redirecting to) the route this is mounted on starts the\n * Authorization Code + PKCE flow: it generates a fresh `code_verifier` and\n * `state`, stashes them in short-lived cookies for {@link handleCallbackRoute}\n * to consume, and redirects the user-agent to the provider's authorization\n * endpoint.\n *\n * @public\n */\nexport function handleSignInRoute(options?: HandleSignInOptions) {\n  return async ({ request }: { request: Request }): Promise<Response> => {\n    return handleSignInInternal(request, options);\n  };\n}\n\nasync function handleSignInInternal(\n  request: Request,\n  options?: HandleSignInOptions,\n): Promise<Response> {\n  const url = new URL(request.url);\n\n  // These must be unique per authorization request and tied to the user-agent.\n  const codeVerifier = client.randomPKCECodeVerifier();\n  const codeChallenge = await client.calculatePKCECodeChallenge(codeVerifier);\n  const state = client.randomState();\n\n  const redirectUri = new URL(options?.redirectUri ?? DEFAULT_CALLBACK_PATH, url.origin).toString();\n\n  let authorizationUrl: URL;\n  try {\n    const config = await getConfig();\n    authorizationUrl = client.buildAuthorizationUrl(config, {\n      redirect_uri: redirectUri,\n      scope: options?.scope ?? DEFAULT_SCOPE,\n      state,\n      code_challenge: codeChallenge,\n      code_challenge_method: \"S256\",\n    });\n  } catch {\n    return new Response(JSON.stringify({ error: \"Failed to start sign-in\" }), {\n      status: 500,\n      headers: { \"Content-Type\": \"application/json\" },\n    });\n  }\n\n  const headers = new Headers({ Location: authorizationUrl.toString() });\n\n  // Stash this flow's PKCE verifier under a state-keyed cookie so concurrent\n  // sign-ins keep separate verifiers instead of clobbering a shared name.\n  // SameSite=Lax so it survives the top-level redirect back from the provider.\n  headers.append(\n    \"Set-Cookie\",\n    serializeCookie(pkceCookieName(state), codeVerifier, {\n      httpOnly: true,\n      secure: url.protocol === \"https:\",\n      sameSite: \"Lax\",\n      path: \"/\",\n      maxAge: SIGN_IN_COOKIE_MAX_AGE,\n    }),\n  );\n\n  // Bound the number of pending verifier cookies. Abandoned flows would\n  // otherwise linger until they expire and could overflow the cookie header; we\n  // can't tell their age, so once over the cap we expire the surplus and keep\n  // this fresh flow plus a handful of genuinely concurrent ones.\n  const pending = parseCookieNames(request.headers.get(\"cookie\") ?? \"\").filter((name) =>\n    name.startsWith(PKCE_COOKIE_PREFIX),\n  );\n  for (const name of pending.slice(MAX_PENDING_SIGN_INS - 1)) {\n    deleteCookie(headers, name);\n  }\n\n  return new Response(null, { status: 302, headers });\n}\n\n/**\n * Build a TanStack route handler for the OAuth/OIDC callback.\n *\n * The handler completes the authorization-code grant using the PKCE\n * `code_verifier` and `state` stashed in cookies during sign-in, invokes\n * {@link HandleCallbackOptions.onSuccess} with the token response, stores the\n * resulting session token in an HttpOnly cookie, clears the one-time sign-in\n * cookies, and redirects the user to {@link HandleCallbackOptions.returnPathname}.\n *\n * @public\n */\nexport function handleCallbackRoute(options?: HandleCallbackOptions) {\n  return async ({ request }: { request: Request }): Promise<Response> => {\n    return handleCallbackInternal(request, options);\n  };\n}\n\nasync function handleCallbackInternal(\n  request: Request,\n  options?: HandleCallbackOptions,\n): Promise<Response> {\n  const url = new URL(request.url);\n  const code = url.searchParams.get(\"code\");\n\n  if (!code) {\n    return handleError(request, 400, \"Missing code parameter\", undefined, options);\n  }\n\n  // The provider echoes back the `state` from the authorization request; use it\n  // to locate the matching pending flow's PKCE verifier. Only a sign-in we\n  // started in this browser could have set that state-keyed cookie, so its\n  // presence both proves the callback belongs to that request (CSRF defense)\n  // and tells concurrent flows apart. Pass `state` as `expectedState` so the\n  // grant also rejects a response whose `state` is missing or mismatched.\n  const state = url.searchParams.get(\"state\");\n  if (!state) {\n    return handleError(request, 400, \"Missing state parameter\", undefined, options);\n  }\n\n  const verifierCookieName = pkceCookieName(state);\n  const pkceCodeVerifier = parseCookies(request.headers.get(\"cookie\") ?? \"\")[verifierCookieName];\n  if (!pkceCodeVerifier) {\n    return handleError(request, 400, \"Unknown or expired sign-in state\", undefined, options);\n  }\n\n  const checks: client.AuthorizationCodeGrantChecks = { pkceCodeVerifier, expectedState: state };\n\n  let tokens: Awaited<ReturnType<typeof client.authorizationCodeGrant>>;\n  try {\n    const config = await getConfig();\n    tokens = await client.authorizationCodeGrant(config, url, checks);\n  } catch (error) {\n    return handleError(request, 500, \"Token exchange failed\", error, options, verifierCookieName);\n  }\n\n  // `access_token` is always present in a successful token response, so the\n  // session token below is guaranteed to be a string.\n  const data: HandleAuthSuccessData = {\n    accessToken: tokens.access_token,\n    idToken: tokens.id_token,\n    refreshToken: tokens.refresh_token,\n    expiresIn: tokens.expires_in,\n    scope: tokens.scope,\n    claims: tokens.claims(),\n    state,\n  };\n\n  await options?.onSuccess?.(data);\n\n  const secure = url.protocol === \"https:\";\n  const headers = new Headers({ Location: options?.returnPathname ?? DEFAULT_REDIRECT });\n\n  // Persist the session token (prefer the ID token) for subsequent requests.\n  headers.append(\n    \"Set-Cookie\",\n    serializeCookie(AUTH_COOKIE, data.idToken ?? data.accessToken, {\n      httpOnly: true,\n      secure,\n      sameSite: \"Lax\",\n      path: \"/\",\n      maxAge: data.expiresIn,\n    }),\n  );\n\n  // Clear only this flow's verifier; other concurrent sign-ins keep theirs.\n  deleteCookie(headers, verifierCookieName);\n\n  return new Response(null, { status: 302, headers });\n}\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@usehercules/auth-tanstack",
+  "version": "0.0.1",
+  "description": "TanStack authentication utilities for Hercules applications",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "author": "Hercules Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/withzeusai/hercules-js.git",
+    "directory": "packages/auth-tanstack"
+  },
+  "files": [
+    "dist",
+    "src",
+    "tsconfig.json",
+    "tsdown.config.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.2",
+    "tsdown": "^0.22.3",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  },
+  "dependencies": {
+    "@tanstack/react-router": "^1.170.16",
+    "@tanstack/react-start": "^1.168.26",
+    "oauth4webapi": "^3.8.6",
+    "openid-client": "^6.8.4"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest --run"
+  }
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+export type {
+  User,
+  Impersonator,
+  Session,
+  AuthResult,
+  BaseTokenClaims,
+  CustomClaims,
+} from "./types";
+export {
+  type HandleAuthSuccessData,
+  type HandleCallbackOptions,
+  type HandleSignInOptions,
+  handleCallbackRoute,
+  handleSignInRoute,
+} from "./server/server";

package/src/server/cookie-utils.test.ts

@@ -0,0 +1,83 @@
+import { describe, it, expect } from "vitest";
+import { parseCookies, parseCookieNames, serializeCookie } from "./cookie-utils";
+
+describe("parseCookies", () => {
+  it("parses a single cookie", () => {
+    expect(parseCookies("a=1")).toEqual({ a: "1" });
+  });
+
+  it("parses multiple cookies", () => {
+    expect(parseCookies("a=1; b=2; c=3")).toEqual({ a: "1", b: "2", c: "3" });
+  });
+
+  it("preserves = characters within cookie values", () => {
+    expect(parseCookies("token=base64==padding==")).toEqual({ token: "base64==padding==" });
+  });
+
+  it("returns an empty object for an empty header", () => {
+    expect(parseCookies("")).toEqual({});
+    expect(parseCookies("   ")).toEqual({});
+  });
+
+  it("trims whitespace around each pair", () => {
+    expect(parseCookies("a=1 ;   b=2")).toEqual({ a: "1", b: "2" });
+  });
+});
+
+describe("parseCookieNames", () => {
+  it("returns names only, ignoring values", () => {
+    expect(parseCookieNames("a=1; b=2; c=3")).toEqual(["a", "b", "c"]);
+  });
+
+  it("handles values containing = signs", () => {
+    expect(parseCookieNames("token=base64==padding==")).toEqual(["token"]);
+  });
+
+  it("trims whitespace around each name", () => {
+    expect(parseCookieNames("a=1 ;   b=2")).toEqual(["a", "b"]);
+  });
+
+  it("returns an empty array for an empty header", () => {
+    expect(parseCookieNames("")).toEqual([]);
+    expect(parseCookieNames("   ")).toEqual([]);
+  });
+
+  it("tolerates a valueless cookie segment", () => {
+    expect(parseCookieNames("a=1; flag; b=2")).toEqual(["a", "flag", "b"]);
+  });
+});
+
+describe("serializeCookie", () => {
+  it("serializes a bare name/value pair", () => {
+    expect(serializeCookie("a", "1")).toBe("a=1");
+  });
+
+  it("includes Path and Max-Age when provided", () => {
+    expect(serializeCookie("a", "1", { path: "/", maxAge: 3600 })).toBe(
+      "a=1; Path=/; Max-Age=3600",
+    );
+  });
+
+  it("appends HttpOnly, Secure, and SameSite flags", () => {
+    expect(
+      serializeCookie("session", "tok", {
+        httpOnly: true,
+        secure: true,
+        sameSite: "Lax",
+        path: "/",
+      }),
+    ).toBe("session=tok; Path=/; HttpOnly; Secure; SameSite=Lax");
+  });
+
+  it("floors a fractional Max-Age to whole seconds", () => {
+    expect(serializeCookie("a", "1", { maxAge: 59.9 })).toBe("a=1; Max-Age=59");
+  });
+
+  it("emits Max-Age=0 to expire a cookie", () => {
+    expect(serializeCookie("a", "", { path: "/", maxAge: 0 })).toBe("a=; Path=/; Max-Age=0");
+  });
+
+  it("omits falsy flags", () => {
+    expect(serializeCookie("a", "1", { httpOnly: false, secure: false })).toBe("a=1");
+  });
+});

package/src/server/cookie-utils.ts

@@ -0,0 +1,56 @@
+export function parseCookies(cookieHeader: string): Record<string, string> {
+  if (!cookieHeader.trim()) return {};
+  return Object.fromEntries(
+    cookieHeader.split(";").map((cookie) => {
+      const [key, ...valueParts] = cookie.trim().split("=");
+      return [key, valueParts.join("=")];
+    }),
+  );
+}
+
+/**
+ * Parse only the cookie names from a `Cookie` header, skipping the values.
+ *
+ * Use this when you need the set of cookie names but not their contents — it
+ * avoids allocating the (potentially large) value strings that `parseCookies`
+ * materializes. Relevant on the PKCE-verifier eviction path, where the header
+ * can carry many large encrypted verifier blobs whose values are irrelevant.
+ */
+export function parseCookieNames(cookieHeader: string): string[] {
+  if (!cookieHeader.trim()) return [];
+  return cookieHeader
+    .split(";")
+    .map((cookie) => {
+      const eq = cookie.indexOf("=");
+      return (eq === -1 ? cookie : cookie.slice(0, eq)).trim();
+    })
+    .filter(Boolean);
+}
+
+export interface CookieOptions {
+  httpOnly?: boolean;
+  secure?: boolean;
+  sameSite?: "Strict" | "Lax" | "None";
+  path?: string;
+  maxAge?: number;
+}
+
+/**
+ * Serialize a cookie name/value pair into a `Set-Cookie` header string.
+ *
+ * Only the attributes needed by this package are supported. `maxAge` is floored
+ * to a whole number of seconds; pass `0` to expire a cookie immediately.
+ */
+export function serializeCookie(
+  name: string,
+  value: string,
+  options: CookieOptions = {},
+): string {
+  const parts = [`${name}=${value}`];
+  if (options.path) parts.push(`Path=${options.path}`);
+  if (options.maxAge !== undefined) parts.push(`Max-Age=${Math.floor(options.maxAge)}`);
+  if (options.httpOnly) parts.push("HttpOnly");
+  if (options.secure) parts.push("Secure");
+  if (options.sameSite) parts.push(`SameSite=${options.sameSite}`);
+  return parts.join("; ");
+}

package/src/server/server.ts

@@ -0,0 +1,262 @@
+import * as client from "openid-client";
+import { parseCookies, serializeCookie } from "./cookie-utils";
+import type { HandleAuthSuccessData, HandleCallbackOptions, HandleSignInOptions } from "./types";
+
+export type { HandleAuthSuccessData, HandleCallbackOptions, HandleSignInOptions } from "./types";
+
+/**
+ * OIDC issuer URL used for discovery (`{issuer}/.well-known/openid-configuration`).
+ * For Amazon Cognito this is the user-pool issuer
+ * (`https://cognito-idp.<region>.amazonaws.com/<userPoolId>`), NOT the hosted-UI
+ * domain — the hosted domain does not serve the discovery document.
+ */
+const ISSUER_URL_ENV = "HERCULES_AUTH_ISSUER_URL";
+/** OAuth client (app client) identifier. */
+const CLIENT_ID_ENV = "HERCULES_AUTH_CLIENT_ID";
+/** OAuth client secret. Optional — omit for a public (PKCE-only) client. */
+const CLIENT_SECRET_ENV = "HERCULES_AUTH_CLIENT_SECRET";
+
+/** Cookie carrying the PKCE `code_verifier`, written when the sign-in flow began. */
+const PKCE_VERIFIER_COOKIE = "hercules_pkce_verifier";
+/** Cookie carrying the OAuth `state`, written when the sign-in flow began. */
+const STATE_COOKIE = "hercules_oauth_state";
+/** Cookie holding the authenticated session token. */
+const AUTH_COOKIE = "hercules_session";
+
+/** Where to send the user once the callback completes. */
+const DEFAULT_REDIRECT = "/";
+/** Callback route the provider returns to, unless overridden. */
+const DEFAULT_CALLBACK_PATH = "/api/auth/callback";
+/** OAuth scopes requested when none are configured. */
+const DEFAULT_SCOPE = "openid profile email";
+/** Lifetime (seconds) of the one-time sign-in cookies. */
+const SIGN_IN_COOKIE_MAX_AGE = 600;
+
+/** One-time sign-in cookies, cleared once the callback resolves either way. */
+const SIGN_IN_COOKIES = [PKCE_VERIFIER_COOKIE, STATE_COOKIE];
+
+function requireEnv(name: string): string {
+  const value = process.env[name];
+  if (!value) {
+    throw new Error(`[auth-tanstack] Missing required environment variable: ${name}`);
+  }
+  return value;
+}
+
+// Discovery is a network round-trip and the resolved metadata is static for the
+// lifetime of the process, so resolve the Configuration once and reuse it.
+let configPromise: Promise<client.Configuration> | undefined;
+function getConfig(): Promise<client.Configuration> {
+  if (!configPromise) {
+    const issuerUrl = new URL(requireEnv(ISSUER_URL_ENV));
+    const clientId = requireEnv(CLIENT_ID_ENV);
+    const clientSecret = process.env[CLIENT_SECRET_ENV];
+
+    // A public client authenticates with PKCE alone (no secret); a confidential
+    // client authenticates the token request with its secret.
+    const discovered = clientSecret
+      ? client.discovery(issuerUrl, clientId, clientSecret)
+      : client.discovery(issuerUrl, clientId, undefined, client.None());
+
+    configPromise = discovered.catch((error) => {
+      // Don't cache a failed discovery — let the next request retry instead of
+      // permanently poisoning every sign-in and callback.
+      configPromise = undefined;
+      throw error;
+    });
+  }
+  return configPromise;
+}
+
+function deleteSignInCookies(headers: Headers): void {
+  for (const name of SIGN_IN_COOKIES) {
+    headers.append("Set-Cookie", serializeCookie(name, "", { path: "/", maxAge: 0 }));
+  }
+}
+
+/**
+ * Resolve a callback failure into a Response, honoring the caller's error
+ * handling preferences (see {@link HandleCallbackOptions}). `onError` wins over
+ * `errorRedirectUrl`, which in turn wins over the default JSON error response.
+ * All paths clear the one-time sign-in cookies.
+ */
+async function handleError(
+  request: Request,
+  status: 400 | 500,
+  message: string,
+  error: unknown,
+  options?: HandleCallbackOptions,
+): Promise<Response> {
+  // `onError` is intentionally not wrapped — errors it throws propagate.
+  if (options?.onError) {
+    return options.onError({ error, request });
+  }
+
+  if (options?.errorRedirectUrl) {
+    try {
+      const location = new URL(options.errorRedirectUrl, new URL(request.url).origin).toString();
+      const headers = new Headers({ Location: location });
+      deleteSignInCookies(headers);
+      return new Response(null, { status: 302, headers });
+    } catch {
+      // Malformed config value — warn and fall back to the JSON error response.
+      console.warn(`[auth-tanstack] Ignoring malformed errorRedirectUrl: ${options.errorRedirectUrl}`);
+    }
+  }
+
+  const headers = new Headers({ "Content-Type": "application/json" });
+  deleteSignInCookies(headers);
+  return new Response(JSON.stringify({ error: message }), { status, headers });
+}
+
+/**
+ * Build a TanStack route handler that initiates the OIDC login.
+ *
+ * Navigating to (redirecting to) the route this is mounted on starts the
+ * Authorization Code + PKCE flow: it generates a fresh `code_verifier` and
+ * `state`, stashes them in short-lived cookies for {@link handleCallbackRoute}
+ * to consume, and redirects the user-agent to the provider's authorization
+ * endpoint.
+ *
+ * @public
+ */
+export function handleSignInRoute(options?: HandleSignInOptions) {
+  return async ({ request }: { request: Request }): Promise<Response> => {
+    return handleSignInInternal(request, options);
+  };
+}
+
+async function handleSignInInternal(
+  request: Request,
+  options?: HandleSignInOptions,
+): Promise<Response> {
+  const url = new URL(request.url);
+
+  // These must be unique per authorization request and tied to the user-agent.
+  const codeVerifier = client.randomPKCECodeVerifier();
+  const codeChallenge = await client.calculatePKCECodeChallenge(codeVerifier);
+  const state = client.randomState();
+
+  const redirectUri = new URL(options?.redirectUri ?? DEFAULT_CALLBACK_PATH, url.origin).toString();
+
+  let authorizationUrl: URL;
+  try {
+    const config = await getConfig();
+    authorizationUrl = client.buildAuthorizationUrl(config, {
+      redirect_uri: redirectUri,
+      scope: options?.scope ?? DEFAULT_SCOPE,
+      state,
+      code_challenge: codeChallenge,
+      code_challenge_method: "S256",
+    });
+  } catch {
+    return new Response(JSON.stringify({ error: "Failed to start sign-in" }), {
+      status: 500,
+      headers: { "Content-Type": "application/json" },
+    });
+  }
+
+  const headers = new Headers({ Location: authorizationUrl.toString() });
+
+  // Stash the PKCE verifier and state for the callback. SameSite=Lax so they
+  // survive the top-level redirect back from the provider.
+  const cookieOptions = {
+    httpOnly: true,
+    secure: url.protocol === "https:",
+    sameSite: "Lax" as const,
+    path: "/",
+    maxAge: SIGN_IN_COOKIE_MAX_AGE,
+  };
+  headers.append("Set-Cookie", serializeCookie(PKCE_VERIFIER_COOKIE, codeVerifier, cookieOptions));
+  headers.append("Set-Cookie", serializeCookie(STATE_COOKIE, state, cookieOptions));
+
+  return new Response(null, { status: 302, headers });
+}
+
+/**
+ * Build a TanStack route handler for the OAuth/OIDC callback.
+ *
+ * The handler completes the authorization-code grant using the PKCE
+ * `code_verifier` and `state` stashed in cookies during sign-in, invokes
+ * {@link HandleCallbackOptions.onSuccess} with the token response, stores the
+ * resulting session token in an HttpOnly cookie, clears the one-time sign-in
+ * cookies, and redirects the user to {@link HandleCallbackOptions.returnPathname}.
+ *
+ * @public
+ */
+export function handleCallbackRoute(options?: HandleCallbackOptions) {
+  return async ({ request }: { request: Request }): Promise<Response> => {
+    return handleCallbackInternal(request, options);
+  };
+}
+
+async function handleCallbackInternal(
+  request: Request,
+  options?: HandleCallbackOptions,
+): Promise<Response> {
+  const url = new URL(request.url);
+  const code = url.searchParams.get("code");
+
+  if (!code) {
+    return handleError(request, 400, "Missing code parameter", undefined, options);
+  }
+
+  const cookies = parseCookies(request.headers.get("cookie") ?? "");
+
+  const pkceCodeVerifier = cookies[PKCE_VERIFIER_COOKIE];
+  if (!pkceCodeVerifier) {
+    return handleError(request, 400, "Missing PKCE verifier", undefined, options);
+  }
+
+  // Sign-in always sends `state` and stores the matching cookie, so the callback
+  // must always prove it belongs to that request. Require the stored value and
+  // pass it as `expectedState` unconditionally — `authorizationCodeGrant` then
+  // rejects a response whose `state` is missing or mismatched (CSRF defense).
+  const expectedState = cookies[STATE_COOKIE];
+  if (!expectedState) {
+    return handleError(request, 400, "Missing state cookie", undefined, options);
+  }
+  const checks: client.AuthorizationCodeGrantChecks = { pkceCodeVerifier, expectedState };
+
+  let tokens: Awaited<ReturnType<typeof client.authorizationCodeGrant>>;
+  try {
+    const config = await getConfig();
+    tokens = await client.authorizationCodeGrant(config, url, checks);
+  } catch (error) {
+    return handleError(request, 500, "Token exchange failed", error, options);
+  }
+
+  // `access_token` is always present in a successful token response, so the
+  // session token below is guaranteed to be a string.
+  const data: HandleAuthSuccessData = {
+    accessToken: tokens.access_token,
+    idToken: tokens.id_token,
+    refreshToken: tokens.refresh_token,
+    expiresIn: tokens.expires_in,
+    scope: tokens.scope,
+    claims: tokens.claims(),
+    state: url.searchParams.get("state") ?? undefined,
+  };
+
+  await options?.onSuccess?.(data);
+
+  const secure = url.protocol === "https:";
+  const headers = new Headers({ Location: options?.returnPathname ?? DEFAULT_REDIRECT });
+
+  // Persist the session token (prefer the ID token) for subsequent requests.
+  headers.append(
+    "Set-Cookie",
+    serializeCookie(AUTH_COOKIE, data.idToken ?? data.accessToken, {
+      httpOnly: true,
+      secure,
+      sameSite: "Lax",
+      path: "/",
+      maxAge: data.expiresIn,
+    }),
+  );
+
+  // Clear the one-time sign-in cookies now that the flow is complete.
+  deleteSignInCookies(headers);
+
+  return new Response(null, { status: 302, headers });
+}

package/src/server/types.ts

@@ -0,0 +1,82 @@
+import type { IDToken } from "openid-client";
+
+export interface HandleSignInOptions {
+  /**
+   * Callback URL the provider redirects back to after authentication. Accepts
+   * an absolute URL (`https://app.example.com/api/auth/callback`) or a path
+   * (`/api/auth/callback`); a path resolves against the request origin.
+   *
+   * This must match both the `redirect_uri` registered with the provider and
+   * the route where {@link HandleCallbackOptions} is mounted. Defaults to
+   * `/api/auth/callback`.
+   */
+  redirectUri?: string;
+  /**
+   * Space-delimited OAuth scopes to request. `openid` is required for an ID
+   * token to be returned. Defaults to `openid profile email`.
+   */
+  scope?: string;
+}
+
+export interface HandleCallbackOptions {
+  returnPathname?: string;
+  onSuccess?: (data: HandleAuthSuccessData) => void | Promise<void>;
+  /**
+   * Custom error handler. Receives the underlying error and the original
+   * request, returns a Response. Errors thrown from inside `onError` are
+   * NOT caught by the SDK — they propagate up to the runtime. Wrap your
+   * `onError` body in a try/catch if you want different behavior.
+   *
+   * If both `onError` and `errorRedirectUrl` are provided, `onError` wins
+   * and `errorRedirectUrl` is ignored.
+   */
+  onError?: (params: { error?: unknown; request: Request }) => Response | Promise<Response>;
+  /**
+   * Optional URL to redirect the user to when the callback fails. Accepts
+   * absolute URLs (`https://example.com/sign-in`) or relative paths
+   * (`/sign-in?error=auth_failed`); relative values resolve against the
+   * request origin.
+   *
+   * When set and `onError` is not, the SDK responds with a 302 Location
+   * redirect plus the verifier-delete cookies. When `onError` is also
+   * set, this option is ignored.
+   *
+   * The redirect URL is set at route-construction time by application
+   * code, not derived from request input. Do not pass user-controlled
+   * values here. The SDK does not validate the URL scheme; any value the
+   * URL constructor accepts is accepted (including `javascript:` and
+   * `data:`).
+   *
+   * If the value is malformed and the URL constructor throws, the SDK
+   * logs a config warning and falls back to the path-dependent JSON
+   * error response (400 or 500) with delete-cookies.
+   */
+  errorRedirectUrl?: string;
+}
+
+/**
+ * Data passed to {@link HandleCallbackOptions.onSuccess} after a successful
+ * authorization-code exchange. The shape mirrors what the token endpoint
+ * actually returns (an OAuth 2.0 / OIDC token response) — only `accessToken`
+ * is guaranteed; everything else depends on the provider, the requested
+ * scopes, and the client configuration.
+ */
+export interface HandleAuthSuccessData {
+  /** OAuth 2.0 access token. Always present. */
+  accessToken: string;
+  /** OIDC ID token (a JWT), when the provider returns one. */
+  idToken?: string;
+  /** Refresh token, when the provider issues one (e.g. with `offline_access`). */
+  refreshToken?: string;
+  /** Seconds until {@link accessToken} expires, when the provider reports it. */
+  expiresIn?: number;
+  /** Space-delimited scopes granted, when the provider echoes them back. */
+  scope?: string;
+  /**
+   * Parsed claims of the ID token — the authenticated user's identity (`sub`,
+   * `email`, any custom claims). Present only when an ID token was returned.
+   */
+  claims?: IDToken;
+  /** The `state` value echoed back by the provider, when present. */
+  state?: string;
+}

package/src/types.ts

@@ -0,0 +1,6 @@
+export type User = {};
+export type Impersonator = {};
+export type Session = {};
+export type AuthResult = {};
+export type BaseTokenClaims = {};
+export type CustomClaims = {};

package/tsconfig.json

@@ -0,0 +1,42 @@
+{
+  "compilerOptions": {
+    // Language and environment
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "types": ["node"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+
+    // Emit
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "dist",
+    "removeComments": true,
+    "importHelpers": true,
+
+    // Interop constraints
+    "isolatedModules": true,
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "verbatimModuleSyntax": true,
+
+    // Type checking
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+
+    // JSX (for React peer dependency)
+    "jsx": "react-jsx",
+
+    // Skip type checking of declaration files
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.*", "**/*.spec.*"]
+}

package/tsdown.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from "tsdown";
+
+export default defineConfig((options) => [
+  {
+    ...options,
+    entry: ["src/index.ts"],
+    dts: true,
+    sourcemap: true,
+    exports: true,
+    ignoreWatch: [".turbo"],
+  },
+]);