@robelest/convex-auth 0.0.2 → 0.0.3-preview.1

package/src/server/index.ts

@@ -1,4 +1,5 @@
 import { ConvexHttpClient } from "convex/browser";
+import { ConvexError } from "convex/values";
 import { jwtDecode } from "jwt-decode";
 import { parse, serialize } from "cookie";
 import type {
@@ -7,30 +8,79 @@ import type {
 } from "./implementation/index.js";
 import { isLocalHost } from "./utils.js";
 
+/** Cookie lifetime configuration for auth tokens. */
 export type AuthCookieConfig = {
+  /** Maximum age in seconds, or `null` for session cookies. */
   maxAge: number | null;
 };
 
+/** Raw cookie values extracted from a request. */
 export type AuthCookies = {
+  /** The JWT access token, or `null` when absent. */
   token: string | null;
+  /** The refresh token, or `null` when absent. */
   refreshToken: string | null;
+  /** The OAuth PKCE verifier, or `null` when absent. */
   verifier: string | null;
 };
 
+/** A structured cookie ready to be set via any framework's cookie API. */
+export type AuthCookie = {
+  name: string;
+  value: string;
+  options: {
+    path: string;
+    httpOnly: boolean;
+    secure: boolean;
+    sameSite: "lax" | "strict" | "none";
+    maxAge?: number;
+    expires?: Date;
+  };
+};
+
+/**
+ * Options for the SSR auth helper returned by {@link server}.
+ */
 export type ServerOptions = {
-  /** Convex deployment URL. */
+  /** Convex deployment URL (e.g. `https://your-app.convex.cloud`). */
   url: string;
+  /**
+   * Path the client POSTs auth actions to. Defaults to `"/api/auth"`.
+   * Must match the `proxy` option on the client.
+   */
   apiRoute?: string;
+  /** Cookie `maxAge` in seconds, or `null` for session cookies. */
   cookieMaxAge?: number | null;
+  /** Enable verbose debug logging for token refresh and cookie operations. */
   verbose?: boolean;
+  /**
+   * Control whether `refresh()` handles OAuth `?code=` query parameters.
+   *
+   * - `true` (default): always exchange the code on GET requests with `text/html` accept.
+   * - `false`: never exchange — useful when only the client handles codes.
+   * - A function: called with the `Request` for per-request decisions.
+   */
   shouldHandleCode?: ((request: Request) => boolean | Promise<boolean>) | boolean;
 };
 
 export type RefreshResult = {
-  response?: Response;
-  cookies?: string[];
+  /** Structured cookies to set on the response. */
+  cookies: AuthCookie[];
+  /** URL to redirect to (set after OAuth code exchange). */
+  redirect?: string;
+  /** JWT for SSR hydration, or `null` if not authenticated. */
+  token: string | null;
 };
 
+/**
+ * Derive the cookie names used for auth tokens.
+ *
+ * On localhost the names are unprefixed; on production hosts they
+ * use the `__Host-` prefix for tighter security.
+ *
+ * @param host - The `Host` header value. Omit to use unprefixed names.
+ * @returns An object with `token`, `refreshToken`, and `verifier` cookie names.
+ */
 export function authCookieNames(host?: string) {
   const prefix = isLocalHost(host) ? "" : "__Host-";
   return {
@@ -40,6 +90,13 @@ export function authCookieNames(host?: string) {
   };
 }
 
+/**
+ * Parse auth cookie values from a raw `Cookie` header string.
+ *
+ * @param cookieHeader - The raw `Cookie` header, or `null`/`undefined`.
+ * @param host - The `Host` header, used to determine cookie name prefixes.
+ * @returns Parsed {@link AuthCookies} with `token`, `refreshToken`, and `verifier`.
+ */
 export function parseAuthCookies(
   cookieHeader: string | null | undefined,
   host?: string,
@@ -53,6 +110,16 @@ export function parseAuthCookies(
   };
 }
 
+/**
+ * Serialize auth cookies into `Set-Cookie` header strings.
+ *
+ * Nulled-out values produce deletion cookies (maxAge 0, expired date).
+ *
+ * @param cookies - The auth cookie values to serialize.
+ * @param host - The `Host` header, used for cookie name prefixes and `Secure` flag.
+ * @param config - Cookie lifetime config. Defaults to session cookies.
+ * @returns An array of three `Set-Cookie` header strings.
+ */
 export function serializeAuthCookies(
   cookies: AuthCookies,
   host?: string,
@@ -86,6 +153,67 @@ export function serializeAuthCookies(
   ];
 }
 
+/**
+ * Build structured cookie objects for any SSR framework.
+ *
+ * Use with SvelteKit's `event.cookies.set()`, TanStack Start's `setCookie()`,
+ * Next.js's `cookies().set()`, or any other framework cookie API.
+ */
+export function structuredAuthCookies(
+  cookies: AuthCookies,
+  host?: string,
+  config: AuthCookieConfig = { maxAge: null },
+): AuthCookie[] {
+  const names = authCookieNames(host);
+  const secure = !isLocalHost(host);
+  const base = {
+    path: "/" as const,
+    httpOnly: true as const,
+    secure,
+    sameSite: "lax" as const,
+  };
+  const maxAge = config.maxAge ?? undefined;
+  return [
+    {
+      name: names.token,
+      value: cookies.token ?? "",
+      options: {
+        ...base,
+        maxAge: cookies.token === null ? 0 : maxAge,
+        expires: cookies.token === null ? new Date(0) : undefined,
+      },
+    },
+    {
+      name: names.refreshToken,
+      value: cookies.refreshToken ?? "",
+      options: {
+        ...base,
+        maxAge: cookies.refreshToken === null ? 0 : maxAge,
+        expires: cookies.refreshToken === null ? new Date(0) : undefined,
+      },
+    },
+    {
+      name: names.verifier,
+      value: cookies.verifier ?? "",
+      options: {
+        ...base,
+        maxAge: cookies.verifier === null ? 0 : maxAge,
+        expires: cookies.verifier === null ? new Date(0) : undefined,
+      },
+    },
+  ];
+}
+
+/**
+ * Check whether a request pathname matches the auth proxy route.
+ *
+ * Handles trailing-slash ambiguity: both `/api/auth` and `/api/auth/`
+ * match regardless of how `apiRoute` is configured.
+ *
+ * @param pathname - The request URL pathname.
+ * @param apiRoute - The configured proxy route (e.g. `"/api/auth"`).
+ * @returns `true` when the pathname matches the proxy route.
+ */
 export function shouldProxyAuthAction(pathname: string, apiRoute: string) {
   if (apiRoute.endsWith("/")) {
     return pathname === apiRoute || pathname === apiRoute.slice(0, -1);
@@ -98,6 +226,39 @@ const MINIMUM_REQUIRED_TOKEN_LIFETIME_MS = 10_000;
 
 type DecodedToken = { exp?: number; iat?: number };
 
+/**
+ * Create an SSR auth helper for server-side frameworks.
+ *
+ * Handles cookie-based token management, OAuth code exchange,
+ * and automatic JWT refresh on page loads. Works with any
+ * framework that gives you a `Request` object — SvelteKit,
+ * TanStack Start, Remix, Next.js, etc.
+ *
+ * @param options - SSR configuration (Convex URL, proxy route, cookie lifetime).
+ * @returns An object with `token`, `verify`, `proxy`, and `refresh` methods.
+ *
+ * @example SvelteKit hooks
+ * ```ts
+ * // src/hooks.server.ts
+ * import { server } from '@robelest/convex-auth/server';
+ *
+ * const auth = server({ url: CONVEX_URL });
+ *
+ * export const handle = async ({ event, resolve }) => {
+ *   const { cookies, token } = await auth.refresh(event.request);
+ *   for (const c of cookies) event.cookies.set(c.name, c.value, c.options);
+ *   event.locals.token = token;
+ *   return resolve(event);
+ * };
+ * ```
+ *
+ * @example Generic proxy endpoint
+ * ```ts
+ * if (shouldProxyAuthAction(url.pathname, '/api/auth')) {
+ *   return auth.proxy(request);
+ * }
+ * ```
+ */
 export function server(options: ServerOptions) {
   const convexUrl = options.url;
   const apiRoute = options.apiRoute ?? "/api/auth";
@@ -216,10 +377,25 @@ export function server(options: ServerOptions) {
   };
 
   return {
+    /**
+     * Read the JWT from the request cookies without any validation.
+     *
+     * @param request - The incoming HTTP request.
+     * @returns The raw JWT string, or `null` when no token cookie exists.
+     */
     token(request: Request): string | null {
       return parseRequestCookies(request).token;
     },
 
+    /**
+     * Check whether the request carries a non-expired JWT.
+     *
+     * Performs local expiration checking only (no network call).
+     * Use for lightweight auth guards in middleware.
+     *
+     * @param request - The incoming HTTP request.
+     * @returns `true` when a valid, non-expired JWT exists in the cookies.
+     */
     async verify(request: Request): Promise<boolean> {
       const token = parseRequestCookies(request).token;
       if (token === null) {
@@ -232,6 +408,17 @@ export function server(options: ServerOptions) {
       return decodedToken.exp * 1000 > Date.now();
     },
 
+    /**
+     * Handle a proxied `signIn` or `signOut` POST from the client.
+     *
+     * Validates the route, method, and origin, then forwards the
+     * action to Convex and returns a `Response` with updated
+     * `Set-Cookie` headers. The client never sees the real
+     * refresh token — it stays in httpOnly cookies.
+     *
+     * @param request - The incoming POST request from the client.
+     * @returns A JSON `Response` with auth result and cookie headers.
+     */
     async proxy(request: Request): Promise<Response> {
       const requestUrl = new URL(request.url);
       if (!shouldProxyAuthAction(requestUrl.pathname, apiRoute)) {
@@ -308,8 +495,16 @@ export function server(options: ServerOptions) {
             );
           }
           return jsonResponse(result);
-        } catch (error) {
-          const response = jsonResponse({ error: (error as Error).message }, 400);
+        } catch (error: unknown) {
+          // Forward structured error data when available (ConvexError with { code, message }).
+          const errorBody =
+            error instanceof ConvexError &&
+            typeof error.data === "object" &&
+            error.data !== null &&
+            "code" in error.data
+              ? { error: (error.data as { message?: string }).message ?? String(error), authError: error.data }
+              : { error: error instanceof Error ? error.message : String(error) };
+          const response = jsonResponse(errorBody, 400);
           return attachCookies(
             response,
             serializeAuthCookies(
@@ -346,23 +541,36 @@ export function server(options: ServerOptions) {
       );
     },
 
+    /**
+     * Refresh auth tokens on page load.
+     *
+     * Call this in your server hooks/middleware on every request.
+     * It handles three scenarios:
+     *
+     * 1. **OAuth code exchange** — exchanges a `?code=` query param for tokens and returns a redirect URL.
+     * 2. **Token refresh** — refreshes the JWT if it's close to expiry.
+     * 3. **No-op** — returns the existing token when no refresh is needed.
+     *
+     * @param request - The incoming HTTP request.
+     * @returns Structured cookies to set on the response, an optional redirect URL, and the current JWT.
+     */
     async refresh(request: Request): Promise<RefreshResult> {
       const host = cookieHost(request);
+      const currentToken = parseRequestCookies(request).token;
 
+      // CORS request — clear all auth cookies.
       if (isCorsRequest(request)) {
         return {
-          cookies: serializeAuthCookies(
-            {
-              token: null,
-              refreshToken: null,
-              verifier: null,
-            },
+          cookies: structuredAuthCookies(
+            { token: null, refreshToken: null, verifier: null },
             host,
             cookieConfig,
           ),
+          token: null,
         };
       }
 
+      // OAuth code exchange — exchange code for tokens and redirect.
       const requestUrl = new URL(request.url);
       const code = requestUrl.searchParams.get("code");
       const shouldHandleCode =
@@ -392,47 +600,41 @@ export function server(options: ServerOptions) {
           if (result.tokens === undefined) {
             throw new Error("Invalid `auth:signIn` result for code exchange");
           }
-          const response = Response.redirect(redirectUrl.toString(), 302);
           return {
-            response: attachCookies(
-              response,
-              serializeAuthCookies(
-                {
-                  token: result.tokens?.token ?? null,
-                  refreshToken: result.tokens?.refreshToken ?? null,
-                  verifier: null,
-                },
-                host,
-                cookieConfig,
-              ),
+            cookies: structuredAuthCookies(
+              {
+                token: result.tokens?.token ?? null,
+                refreshToken: result.tokens?.refreshToken ?? null,
+                verifier: null,
+              },
+              host,
+              cookieConfig,
             ),
+            redirect: redirectUrl.toString(),
+            token: result.tokens?.token ?? null,
           };
         } catch (error) {
           console.error(error);
-          const response = Response.redirect(redirectUrl.toString(), 302);
           return {
-            response: attachCookies(
-              response,
-              serializeAuthCookies(
-                {
-                  token: null,
-                  refreshToken: null,
-                  verifier: null,
-                },
-                host,
-                cookieConfig,
-              ),
+            cookies: structuredAuthCookies(
+              { token: null, refreshToken: null, verifier: null },
+              host,
+              cookieConfig,
             ),
+            redirect: redirectUrl.toString(),
+            token: null,
           };
         }
       }
 
+      // Normal page load — refresh tokens if needed.
       const tokens = await refreshTokens(request);
       if (tokens === undefined) {
-        return {};
+        // No refresh needed — return current token for hydration.
+        return { cookies: [], token: currentToken };
       }
       return {
-        cookies: serializeAuthCookies(
+        cookies: structuredAuthCookies(
           {
             token: tokens?.token ?? null,
             refreshToken: tokens?.refreshToken ?? null,
@@ -441,6 +643,7 @@ export function server(options: ServerOptions) {
           host,
           cookieConfig,
         ),
+        token: tokens?.token ?? null,
       };
     },
   };

package/src/server/oauth/authorizationUrl.ts

@@ -7,6 +7,7 @@ import {
 } from "./convexAuth.js";
 import { Cookie } from "@auth/core/lib/utils/cookie.js";
 import { logWithLevel } from "../implementation/utils.js";
+import { throwAuthError } from "../errors.js";
 
 /**
  * Generates an authorization/request token URL.
@@ -25,7 +26,7 @@ export async function getAuthorizationUrl(
   const { as, authorization: authorizationEndpoint, configSource } = provider;
 
   if (!authorizationEndpoint) {
-    throw new TypeError("Could not determine the authorization endpoint.");
+    throwAuthError("PROVIDER_NOT_CONFIGURED", "Could not determine the authorization endpoint.");
   }
   if (!url) {
     url = new URL(authorizationEndpoint.url);

package/src/server/oauth/callback.ts

@@ -12,6 +12,7 @@ import {
   callbackUrl,
   getAuthorizationSignature,
 } from "./convexAuth.js";
+import { throwAuthError } from "../errors.js";
 
 function formUrlEncode(token: string) {
   return encodeURIComponent(token).replace(/%20/g, "+");
@@ -88,7 +89,7 @@ export async function handleOAuth(
       });
       break;
     default:
-      throw new Error("unsupported client authentication method");
+      throwAuthError("OAUTH_UNSUPPORTED_AUTH_METHOD");
   }
 
   const resCookies: Cookie[] = [];
@@ -110,7 +111,7 @@ export async function handleOAuth(
         ...Object.fromEntries(err.cause.entries()),
       };
       logWithLevel("DEBUG", "OAuthCallbackError", cause);
-      throw new Error("OAuth Provider returned an error", { cause });
+      throwAuthError("OAUTH_PROVIDER_ERROR", "OAuth provider returned an error", { cause: JSON.stringify(cause) });
     }
     throw err;
   }
@@ -174,7 +175,7 @@ export async function handleOAuth(
       processedCodeResponse,
     );
     if (idTokenClaimsOrUndefined === undefined) {
-      throw new Error("ID Token claims are missing");
+      throwAuthError("OAUTH_MISSING_ID_TOKEN");
     }
     const idTokenClaims = idTokenClaimsOrUndefined;
     profile = idTokenClaims;
@@ -221,7 +222,7 @@ export async function handleOAuth(
       );
       profile = await userinfoResponse.json();
     } else {
-      throw new TypeError("No userinfo endpoint configured");
+      throwAuthError("OAUTH_NO_USERINFO");
     }
   }
 

package/src/server/oauth/checks.ts

@@ -6,6 +6,7 @@ import type { InternalOptions } from "./types.js";
 import { Cookie } from "@auth/core/lib/utils/cookie.js";
 import { CookiesOptions } from "@auth/core/types.js";
 import { logWithLevel } from "../implementation/utils.js";
+import { throwAuthError } from "../errors.js";
 
 const COOKIE_TTL = 60 * 15; // 15 minutes
 
@@ -97,7 +98,8 @@ export const state = {
     const { provider } = options;
     if (!provider.checks.includes("state")) {
       if (origin) {
-        throw new Error(
+        throwAuthError(
+          "OAUTH_INVALID_STATE",
           "State data was provided but the provider is not configured to use state",
         );
       }

package/src/server/oauth/convexAuth.ts

@@ -7,6 +7,7 @@ import * as o from "oauth4webapi";
 import { normalizeEndpoint } from "../provider_utils.js";
 import { isLocalHost } from "../utils.js";
 import { OAuthConfig } from "@auth/core/providers/oauth.js";
+import { throwAuthError } from "../errors.js";
 
 // ConvexAuth: The logic for the callback URL is different from Auth.js
 export function callbackUrl(providerId: string) {
@@ -92,7 +93,8 @@ export async function oAuthConfigToInternalProvider(config: OAuthConfig<any>): P
   if (!config.authorization || !config.token || !config.userinfo) {
     // Taken from https://github.com/nextauthjs/next-auth/blob/a7491dcb9355ff2d01fb8e9236636605e2090145/packages/core/src/lib/actions/callback/oauth/callback.ts#L63
     if (!config.issuer) {
-      throw new Error(
+      throwAuthError(
+        "PROVIDER_NOT_CONFIGURED",
         `Provider \`${config.id}\` is missing an \`issuer\` URL configuration. Consult the provider docs.`,
       );
     }
@@ -109,8 +111,9 @@ export async function oAuthConfigToInternalProvider(config: OAuthConfig<any>): P
     );
 
     if (!discoveredAs.token_endpoint)
-      throw new TypeError(
-        "TODO: Authorization server did not provide a token endpoint.",
+      throwAuthError(
+        "PROVIDER_NOT_CONFIGURED",
+        "Authorization server did not provide a token endpoint.",
       );
 
     const as: o.AuthorizationServer = discoveredAs;