@robelest/convex-auth 0.0.3-preview → 0.0.3-preview.3

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,13 +8,19 @@ 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;
 };
 
@@ -31,12 +38,28 @@ export type AuthCookie = {
   };
 };
 
+/**
+ * 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;
 };
 
@@ -49,6 +72,15 @@ export type RefreshResult = {
   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 {
@@ -58,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,
@@ -71,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,
@@ -155,6 +204,16 @@ export function structuredAuthCookies(
   ];
 }
 
+/**
+ * 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);
@@ -167,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";
@@ -285,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) {
@@ -301,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)) {
@@ -377,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(
@@ -415,6 +541,19 @@ 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;

package/src/server/oauth/{authorizationUrl.ts → authorization.ts}

@@ -4,9 +4,10 @@ import { InternalOptions } from "./types.js";
 import {
   callbackUrl,
   getAuthorizationSignature,
-} from "./convexAuth.js";
+} from "./helpers.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

@@ -3,7 +3,7 @@
 import * as checks from "./checks.js";
 import * as o from "oauth4webapi";
 import { InternalOptions } from "./types.js";
-import { fetchOpt } from "./lib/utils/customFetch.js";
+import { fetchOpt } from "./lib/utils/fetch.js";
 import { Cookie } from "@auth/core/lib/utils/cookie.js";
 import { logWithLevel } from "../implementation/utils.js";
 import { Account, Profile, TokenSet } from "@auth/core/types.js";
@@ -11,7 +11,8 @@ import { isOIDCProvider } from "./lib/utils/providers.js";
 import {
   callbackUrl,
   getAuthorizationSignature,
-} from "./convexAuth.js";
+} from "./helpers.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 → helpers.ts}

@@ -2,11 +2,12 @@ import { CookieOption, CookiesOptions } from "@auth/core/types.js";
 import { requireEnv } from "../utils.js";
 import { InternalProvider } from "./types.js";
 import { SHARED_COOKIE_OPTIONS } from "../cookies.js";
-import { fetchOpt } from "./lib/utils/customFetch.js";
+import { fetchOpt } from "./lib/utils/fetch.js";
 import * as o from "oauth4webapi";
-import { normalizeEndpoint } from "../provider_utils.js";
+import { normalizeEndpoint } from "../providers.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;

package/src/server/{portal-email.ts → templates.ts}

@@ -1,3 +1,81 @@
+/**
+ * Default email templates generated by the Auth library.
+ *
+ * These are used when the library sends emails on behalf of the developer
+ * (magic links, portal admin sign-in). The developer provides the transport
+ * via `email.send`; the library provides the content.
+ *
+ * @module
+ */
+
+/**
+ * Default magic link email template.
+ *
+ * Clean, minimal design that works across email clients.
+ * Used by the auto-registered `email` provider when `email` is
+ * configured in the Auth constructor.
+ */
+export function defaultMagicLinkEmail(url: string, host: string): string {
+  const escapedHost = host.replace(/[&<>"']/g, (c) =>
+    ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]!,
+  );
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Sign in to ${escapedHost}</title>
+</head>
+<body style="margin:0;padding:0;background-color:#f9fafb;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,'Helvetica Neue',Arial,sans-serif;">
+  <table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="background-color:#f9fafb;padding:40px 16px;">
+    <tr>
+      <td align="center">
+        <table role="presentation" width="480" cellpadding="0" cellspacing="0" style="background-color:#ffffff;border:1px solid #e5e7eb;border-radius:8px;overflow:hidden;">
+          <tr>
+            <td style="padding:32px 32px 0 32px;text-align:center;">
+              <h1 style="margin:0 0 8px 0;font-size:20px;font-weight:600;color:#111827;line-height:1.3;">
+                Sign in to ${escapedHost}
+              </h1>
+            </td>
+          </tr>
+          <tr>
+            <td style="padding:24px 32px;">
+              <p style="margin:0 0 24px 0;font-size:15px;line-height:1.6;color:#4b5563;text-align:center;">
+                Click the button below to sign in. This link will expire shortly.
+              </p>
+              <table role="presentation" width="100%" cellpadding="0" cellspacing="0">
+                <tr>
+                  <td align="center" style="padding:0 0 24px 0;">
+                    <a href="${url}" target="_blank" style="display:inline-block;background-color:#111827;color:#ffffff;font-size:15px;font-weight:600;text-decoration:none;padding:12px 32px;border-radius:6px;line-height:1;">
+                      Sign in
+                    </a>
+                  </td>
+                </tr>
+              </table>
+              <p style="margin:0 0 12px 0;font-size:13px;line-height:1.6;color:#9ca3af;">
+                If the button doesn't work, copy and paste this URL into your browser:
+              </p>
+              <p style="margin:0;font-size:13px;line-height:1.5;color:#6b7280;word-break:break-all;">
+                ${url}
+              </p>
+            </td>
+          </tr>
+          <tr>
+            <td style="padding:20px 32px;border-top:1px solid #e5e7eb;">
+              <p style="margin:0;font-size:12px;line-height:1.5;color:#9ca3af;text-align:center;">
+                If you didn't request this email, you can safely ignore it.
+              </p>
+            </td>
+          </tr>
+        </table>
+      </td>
+    </tr>
+  </table>
+</body>
+</html>`;
+}
+
 /**
  * Styled dark-theme magic link email template for the Convex Auth Portal.
  *
@@ -6,8 +84,6 @@
  * - Accent: #63a8f8 (Convex blue)
  * - Text: #ffffff (headings), #b9b1aa (secondary), #8f8780 (muted)
  * - Border: #4a4743
- *
- * @module
  */
 
 const SHIELD_SVG = `<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" fill="none" stroke="#63a8f8" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M20 13c0 5-3.5 7.5-7.66 8.95a1 1 0 0 1-.67-.01C7.5 20.5 4 18 4 13V6a1 1 0 0 1 1-1c2 0 4.5-1.2 6.24-2.72a1.17 1.17 0 0 1 1.52 0C14.51 3.81 17 5 19 5a1 1 0 0 1 1 1z"/></svg>`;