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

package/src/server/index.ts

@@ -1,4 +1,10 @@
+import { ConvexHttpClient } from "convex/browser";
+import { jwtDecode } from "jwt-decode";
 import { parse, serialize } from "cookie";
+import type {
+  SignInAction,
+  SignOutAction,
+} from "./implementation/index.js";
 import { isLocalHost } from "./utils.js";
 
 export type AuthCookieConfig = {
@@ -11,6 +17,20 @@ export type AuthCookies = {
   verifier: string | null;
 };
 
+export type ServerOptions = {
+  /** Convex deployment URL. */
+  url: string;
+  apiRoute?: string;
+  cookieMaxAge?: number | null;
+  verbose?: boolean;
+  shouldHandleCode?: ((request: Request) => boolean | Promise<boolean>) | boolean;
+};
+
+export type RefreshResult = {
+  response?: Response;
+  cookies?: string[];
+};
+
 export function authCookieNames(host?: string) {
   const prefix = isLocalHost(host) ? "" : "__Host-";
   return {
@@ -72,3 +92,356 @@ export function shouldProxyAuthAction(pathname: string, apiRoute: string) {
   }
   return pathname === apiRoute || pathname === `${apiRoute}/`;
 }
+
+const REQUIRED_TOKEN_LIFETIME_MS = 60_000;
+const MINIMUM_REQUIRED_TOKEN_LIFETIME_MS = 10_000;
+
+type DecodedToken = { exp?: number; iat?: number };
+
+export function server(options: ServerOptions) {
+  const convexUrl = options.url;
+  const apiRoute = options.apiRoute ?? "/api/auth";
+  const cookieConfig = { maxAge: options.cookieMaxAge ?? null };
+  const verbose = options.verbose ?? false;
+
+  const logVerbose = (message: string) => {
+    if (!verbose) {
+      return;
+    }
+    console.debug(
+      `${new Date().toISOString()} [convex-auth/server] ${message}`,
+    );
+  };
+
+  const cookieHost = (request: Request) => {
+    return request.headers.get("host") ?? new URL(request.url).host;
+  };
+
+  const parseRequestCookies = (request: Request) => {
+    return parseAuthCookies(request.headers.get("cookie"), cookieHost(request));
+  };
+
+  const attachCookies = (response: Response, cookies: string[]) => {
+    for (const value of cookies) {
+      response.headers.append("Set-Cookie", value);
+    }
+    return response;
+  };
+
+  const jsonResponse = (body: unknown, status = 200) => {
+    return new Response(JSON.stringify(body), {
+      status,
+      headers: {
+        "Content-Type": "application/json",
+      },
+    });
+  };
+
+  const isCorsRequest = (request: Request) => {
+    const originHeader = request.headers.get("origin");
+    if (originHeader === null) {
+      return false;
+    }
+    const requestUrl = new URL(request.url);
+    const originUrl = new URL(originHeader);
+    return (
+      originUrl.host !== requestUrl.host ||
+      originUrl.protocol !== requestUrl.protocol
+    );
+  };
+
+  const decodeToken = (token: string): DecodedToken | null => {
+    try {
+      return jwtDecode<DecodedToken>(token);
+    } catch {
+      return null;
+    }
+  };
+
+  const convexClient = (token?: string | null) => {
+    const client = new ConvexHttpClient(convexUrl);
+    if (token !== undefined && token !== null) {
+      client.setAuth(token);
+    }
+    return client;
+  };
+
+  const refreshTokens = async (
+    request: Request,
+  ): Promise<{ token: string; refreshToken: string } | null | undefined> => {
+    const cookies = parseRequestCookies(request);
+    const { token, refreshToken } = cookies;
+    if (refreshToken === null && token === null) {
+      logVerbose("No auth cookies found, skipping refresh");
+      return undefined;
+    }
+    if (refreshToken === null || token === null) {
+      logVerbose("Only one auth cookie present, clearing auth cookies");
+      return null;
+    }
+    const decodedToken = decodeToken(token);
+    if (decodedToken?.exp === undefined || decodedToken.iat === undefined) {
+      logVerbose("Failed to decode token, clearing auth cookies");
+      return null;
+    }
+    const totalTokenLifetimeMs = decodedToken.exp * 1000 - decodedToken.iat * 1000;
+    const minimumExpiration =
+      Date.now() +
+      Math.min(
+        REQUIRED_TOKEN_LIFETIME_MS,
+        Math.max(MINIMUM_REQUIRED_TOKEN_LIFETIME_MS, totalTokenLifetimeMs / 10),
+      );
+    if (decodedToken.exp * 1000 > minimumExpiration) {
+      logVerbose("Token valid long enough, skipping refresh");
+      return undefined;
+    }
+
+    try {
+      const result = await convexClient().action(
+        "auth:signIn" as unknown as SignInAction,
+        {
+          refreshToken,
+        },
+      );
+      if (result.tokens === undefined) {
+        throw new Error("Invalid `auth:signIn` result for token refresh");
+      }
+      logVerbose(`Refreshed tokens, null=${result.tokens === null}`);
+      return result.tokens;
+    } catch (error) {
+      console.error(error);
+      logVerbose("Token refresh failed, clearing auth cookies");
+      return null;
+    }
+  };
+
+  return {
+    token(request: Request): string | null {
+      return parseRequestCookies(request).token;
+    },
+
+    async verify(request: Request): Promise<boolean> {
+      const token = parseRequestCookies(request).token;
+      if (token === null) {
+        return false;
+      }
+      const decodedToken = decodeToken(token);
+      if (decodedToken?.exp === undefined) {
+        return false;
+      }
+      return decodedToken.exp * 1000 > Date.now();
+    },
+
+    async proxy(request: Request): Promise<Response> {
+      const requestUrl = new URL(request.url);
+      if (!shouldProxyAuthAction(requestUrl.pathname, apiRoute)) {
+        return new Response("Invalid route", { status: 404 });
+      }
+      if (request.method !== "POST") {
+        return new Response("Invalid method", { status: 405 });
+      }
+      if (isCorsRequest(request)) {
+        return new Response("Invalid origin", { status: 403 });
+      }
+
+      const body = await request.json();
+      const action = body.action as string;
+      const args = (body.args ?? {}) as Record<string, any>;
+
+      if (action !== "auth:signIn" && action !== "auth:signOut") {
+        return new Response("Invalid action", { status: 400 });
+      }
+
+      const currentCookies = parseRequestCookies(request);
+      const host = cookieHost(request);
+
+      if (action === "auth:signIn") {
+        if (args.refreshToken !== undefined) {
+          if (currentCookies.refreshToken === null) {
+            return jsonResponse({ tokens: null });
+          }
+          args.refreshToken = currentCookies.refreshToken;
+        }
+        const client = convexClient(
+          args.refreshToken !== undefined || args.params?.code !== undefined
+            ? null
+            : currentCookies.token,
+        );
+
+        try {
+          const result = await client.action(
+            "auth:signIn" as unknown as SignInAction,
+            args,
+          );
+          if (result.redirect !== undefined) {
+            const response = jsonResponse({ redirect: result.redirect });
+            return attachCookies(
+              response,
+              serializeAuthCookies(
+                {
+                  ...currentCookies,
+                  verifier: result.verifier ?? null,
+                },
+                host,
+                cookieConfig,
+              ),
+            );
+          }
+          if (result.tokens !== undefined) {
+            const response = jsonResponse({
+              tokens:
+                result.tokens === null
+                  ? null
+                  : { token: result.tokens.token, refreshToken: "dummy" },
+            });
+            return attachCookies(
+              response,
+              serializeAuthCookies(
+                {
+                  token: result.tokens?.token ?? null,
+                  refreshToken: result.tokens?.refreshToken ?? null,
+                  verifier: null,
+                },
+                host,
+                cookieConfig,
+              ),
+            );
+          }
+          return jsonResponse(result);
+        } catch (error) {
+          const response = jsonResponse({ error: (error as Error).message }, 400);
+          return attachCookies(
+            response,
+            serializeAuthCookies(
+              {
+                token: null,
+                refreshToken: null,
+                verifier: null,
+              },
+              host,
+              cookieConfig,
+            ),
+          );
+        }
+      }
+
+      try {
+        await convexClient(currentCookies.token).action(
+          "auth:signOut" as unknown as SignOutAction,
+        );
+      } catch (error) {
+        console.error(error);
+      }
+      return attachCookies(
+        jsonResponse(null),
+        serializeAuthCookies(
+          {
+            token: null,
+            refreshToken: null,
+            verifier: null,
+          },
+          host,
+          cookieConfig,
+        ),
+      );
+    },
+
+    async refresh(request: Request): Promise<RefreshResult> {
+      const host = cookieHost(request);
+
+      if (isCorsRequest(request)) {
+        return {
+          cookies: serializeAuthCookies(
+            {
+              token: null,
+              refreshToken: null,
+              verifier: null,
+            },
+            host,
+            cookieConfig,
+          ),
+        };
+      }
+
+      const requestUrl = new URL(request.url);
+      const code = requestUrl.searchParams.get("code");
+      const shouldHandleCode =
+        options.shouldHandleCode === undefined
+          ? true
+          : typeof options.shouldHandleCode === "function"
+            ? await options.shouldHandleCode(request)
+            : options.shouldHandleCode;
+
+      if (
+        code !== null &&
+        request.method === "GET" &&
+        request.headers.get("accept")?.includes("text/html") &&
+        shouldHandleCode
+      ) {
+        const requestCookies = parseRequestCookies(request);
+        const redirectUrl = new URL(requestUrl);
+        redirectUrl.searchParams.delete("code");
+        try {
+          const result = await convexClient().action(
+            "auth:signIn" as unknown as SignInAction,
+            {
+              params: { code },
+              verifier: requestCookies.verifier ?? undefined,
+            },
+          );
+          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,
+              ),
+            ),
+          };
+        } 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,
+              ),
+            ),
+          };
+        }
+      }
+
+      const tokens = await refreshTokens(request);
+      if (tokens === undefined) {
+        return {};
+      }
+      return {
+        cookies: serializeAuthCookies(
+          {
+            token: tokens?.token ?? null,
+            refreshToken: tokens?.refreshToken ?? null,
+            verifier: null,
+          },
+          host,
+          cookieConfig,
+        ),
+      };
+    },
+  };
+}

package/src/server/portal-email.ts

@@ -0,0 +1,95 @@
+/**
+ * Styled dark-theme magic link email template for the Convex Auth Portal.
+ *
+ * Matches the portal's design system:
+ * - Background: #1e1c1a (body), #2a2825 (card)
+ * - 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>`;
+
+/**
+ * Generate the styled magic link email HTML.
+ *
+ * @param url - The magic link URL the user clicks to sign in.
+ * @param expiresInHours - How long the link is valid (shown in the email).
+ */
+export function portalMagicLinkEmail(
+  url: string,
+  expiresInHours: number = 24,
+): string {
+  const expiryText =
+    expiresInHours >= 24
+      ? `${Math.floor(expiresInHours / 24)} day${Math.floor(expiresInHours / 24) > 1 ? "s" : ""}`
+      : `${expiresInHours} hour${expiresInHours > 1 ? "s" : ""}`;
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <meta name="color-scheme" content="dark" />
+  <meta name="supported-color-schemes" content="dark" />
+  <title>Sign in to Convex Auth Portal</title>
+</head>
+<body style="margin:0;padding:0;background-color:#1e1c1a;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:#1e1c1a;padding:40px 16px;">
+    <tr>
+      <td align="center">
+        <table role="presentation" width="480" cellpadding="0" cellspacing="0" style="background-color:#2a2825;border:1px solid #4a4743;border-radius:8px;overflow:hidden;">
+          <!-- Header -->
+          <tr>
+            <td style="padding:32px 32px 0 32px;text-align:center;">
+              ${SHIELD_SVG}
+              <h1 style="margin:16px 0 0 0;font-size:20px;font-weight:600;color:#ffffff;line-height:1.3;">
+                Convex Auth Portal
+              </h1>
+            </td>
+          </tr>
+
+          <!-- Body -->
+          <tr>
+            <td style="padding:24px 32px;">
+              <p style="margin:0 0 20px 0;font-size:15px;line-height:1.6;color:#b9b1aa;">
+                Click the button below to sign in to the admin portal. This link will expire in ${expiryText}.
+              </p>
+
+              <!-- CTA Button -->
+              <table role="presentation" width="100%" cellpadding="0" cellspacing="0">
+                <tr>
+                  <td align="center" style="padding:8px 0 24px 0;">
+                    <a href="${url}" target="_blank" style="display:inline-block;background-color:#63a8f8;color:#0a0a0b;font-size:15px;font-weight:600;text-decoration:none;padding:12px 32px;border-radius:6px;line-height:1;">
+                      Sign in to Portal
+                    </a>
+                  </td>
+                </tr>
+              </table>
+
+              <p style="margin:0 0 16px 0;font-size:13px;line-height:1.6;color:#8f8780;">
+                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:#63a8f8;word-break:break-all;">
+                ${url}
+              </p>
+            </td>
+          </tr>
+
+          <!-- Footer -->
+          <tr>
+            <td style="padding:20px 32px;border-top:1px solid #4a4743;">
+              <p style="margin:0;font-size:12px;line-height:1.5;color:#8f8780;text-align:center;">
+                If you didn't request this email, you can safely ignore it.
+              </p>
+            </td>
+          </tr>
+        </table>
+      </td>
+    </tr>
+  </table>
+</body>
+</html>`;
+}