@neutralauth/internal-auth 0.10.11

package/src/react/index.tsx

@@ -0,0 +1,304 @@
+import type { PropsWithChildren, ReactNode } from "react";
+import { Component, useCallback, useEffect, useMemo, useState } from "react";
+import type { AuthTokenFetcher } from "convex/browser";
+import {
+  Authenticated,
+  ConvexProviderWithAuth,
+  useConvexAuth,
+  useQuery,
+} from "convex/react";
+import type { FunctionReference } from "convex/server";
+import type { BetterAuthClientPlugin } from "better-auth";
+import type { createAuthClient } from "better-auth/react";
+import type {
+  convexClient,
+  crossDomainClient,
+} from "../client/plugins/index.js";
+import type { EmptyObject } from "convex-helpers";
+
+type CrossDomainClient = ReturnType<typeof crossDomainClient>;
+type ConvexClient = ReturnType<typeof convexClient>;
+type PluginsWithCrossDomain = (
+  | CrossDomainClient
+  | ConvexClient
+  | BetterAuthClientPlugin
+)[];
+type PluginsWithoutCrossDomain = (ConvexClient | BetterAuthClientPlugin)[];
+type AuthClientWithPlugins<
+  Plugins extends PluginsWithCrossDomain | PluginsWithoutCrossDomain,
+> = ReturnType<
+  typeof createAuthClient<
+    BetterAuthClientPlugin & {
+      plugins: Plugins;
+    }
+  >
+>;
+export type AuthClient =
+  | AuthClientWithPlugins<PluginsWithCrossDomain>
+  | AuthClientWithPlugins<PluginsWithoutCrossDomain>;
+
+// Until we can import from our own entry points (requires TypeScript 4.7),
+// just describe the interface enough to help users pass the right type.
+type IConvexReactClient = {
+  setAuth(fetchToken: AuthTokenFetcher): void;
+  clearAuth(): void;
+};
+
+/**
+ * A wrapper React component which provides a {@link react.ConvexReactClient}
+ * authenticated with Better Auth.
+ *
+ * @public
+ */
+export function ConvexBetterAuthProvider({
+  children,
+  client,
+  authClient,
+  initialToken,
+}: {
+  children: ReactNode;
+  client: IConvexReactClient;
+  authClient: AuthClient;
+  initialToken?: string | null;
+}) {
+  const useBetterAuth = useUseAuthFromBetterAuth(authClient, initialToken);
+  useEffect(() => {
+    (async () => {
+      const url = new URL(window.location?.href);
+      const token = url.searchParams.get("ott");
+      if (token) {
+        const authClientWithCrossDomain =
+          authClient as AuthClientWithPlugins<PluginsWithCrossDomain>;
+        url.searchParams.delete("ott");
+        const result =
+          await authClientWithCrossDomain.crossDomain.oneTimeToken.verify({
+            token,
+          });
+        const session = result.data?.session;
+        if (session) {
+          await authClient.getSession({
+            fetchOptions: {
+              headers: {
+                Authorization: `Bearer ${session.token}`,
+              },
+            },
+          });
+          authClientWithCrossDomain.updateSession();
+        }
+        window.history.replaceState({}, "", url);
+      }
+    })();
+  }, [authClient]);
+  return (
+    <ConvexProviderWithAuth client={client} useAuth={useBetterAuth}>
+      <>{children}</>
+    </ConvexProviderWithAuth>
+  );
+}
+
+let initialTokenUsed = false;
+
+function useUseAuthFromBetterAuth(
+  authClient: AuthClient,
+  initialToken?: string | null
+) {
+  const [cachedToken, setCachedToken] = useState<string | null>(
+    initialTokenUsed ? null : (initialToken ?? null)
+  );
+  useEffect(() => {
+    if (!initialTokenUsed) {
+      initialTokenUsed = true;
+    }
+  }, []);
+
+  return useMemo(
+    () =>
+      function useAuthFromBetterAuth() {
+        const { data: session, isPending: isSessionPending } =
+          authClient.useSession();
+        const sessionId = session?.session?.id;
+        useEffect(() => {
+          if (!session && !isSessionPending && cachedToken) {
+            setCachedToken(null);
+          }
+        }, [session, isSessionPending]);
+        const fetchAccessToken = useCallback(
+          async ({
+            forceRefreshToken = false,
+          }: { forceRefreshToken?: boolean } = {}) => {
+            if (cachedToken && !forceRefreshToken) {
+              return cachedToken;
+            }
+            try {
+              const { data } = await authClient.convex.token();
+              const token = data?.token || null;
+              setCachedToken(token);
+              return token;
+            } catch {
+              setCachedToken(null);
+              return null;
+            }
+          },
+          // Build a new fetchAccessToken to trigger setAuth() whenever the
+          // session changes.
+          // eslint-disable-next-line react-hooks/exhaustive-deps
+          [sessionId]
+        );
+        return useMemo(
+          () => ({
+            isLoading: isSessionPending && !cachedToken,
+            isAuthenticated: Boolean(session?.session) || cachedToken !== null,
+            fetchAccessToken,
+          }),
+          // eslint-disable-next-line react-hooks/exhaustive-deps
+          [isSessionPending, sessionId, fetchAccessToken, cachedToken]
+        );
+      },
+    [authClient]
+  );
+}
+
+interface ErrorBoundaryProps {
+  children: React.ReactNode;
+  onUnauth: () => void | Promise<void>;
+  renderFallback?: () => React.ReactNode;
+  isAuthError: (error: unknown) => boolean;
+}
+interface ErrorBoundaryState {
+  error?: unknown;
+}
+
+class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  constructor(props: ErrorBoundaryProps) {
+    super(props);
+    this.state = {};
+  }
+  static defaultProps: Partial<ErrorBoundaryProps> = {
+    renderFallback: () => null,
+  };
+  static getDerivedStateFromError(error: Error) {
+    return { error };
+  }
+  async componentDidCatch(error: Error) {
+    if (this.props.isAuthError(error)) {
+      await this.props.onUnauth();
+    }
+  }
+  render() {
+    if (this.state.error && this.props.isAuthError(this.state.error)) {
+      return this.props.renderFallback?.();
+    }
+    return this.props.children;
+  }
+}
+
+// Subscribe to the session validated user to keep this check reactive to
+// actual user auth state at the provider level (rather than just jwt validity state).
+const UserSubscription = ({
+  getAuthUserFn,
+}: {
+  getAuthUserFn: FunctionReference<"query">;
+}) => {
+  useQuery(getAuthUserFn);
+  return null;
+};
+
+/**
+ * _Experimental_
+ *
+ * A wrapper React component which provides error handling for auth related errors.
+ * This is typically used to redirect the user to the login page when they are
+ * unauthenticated, and does so reactively based on the getAuthUserFn query.
+ *
+ * @example
+ * ```ts
+ * // convex/auth.ts
+ * export const { getAuthUser } = authComponent.clientApi();
+ *
+ * // auth-client.tsx
+ * import { AuthBoundary } from "@convex-dev/react";
+ * import { api } from '../../convex/_generated/api'
+ * import { isAuthError } from '../lib/utils'
+ *
+ * export const ClientAuthBoundary = ({ children }: PropsWithChildren) => {
+ *   return (
+ *     <AuthBoundary
+ *       onUnauth={() => redirect("/sign-in")}
+ *       authClient={authClient}
+ *       getAuthUserFn={api.auth.getAuthUser}
+ *       isAuthError={isAuthError}
+ * >
+ *   <>{children}</>
+ * </AuthBoundary>
+ * )
+ * ```
+ * @param props.children - Children to render.
+ * @param props.onUnauth - Function to call when the user is
+ * unauthenticated. Typically a redirect to the login page.
+ * @param props.authClient - Better Auth authClient to use.
+ * @param props.renderFallback - Fallback component to render when the user is
+ * unauthenticated. Defaults to null. Generally not rendered as error handling
+ * is typically a redirect.
+ * @param props.getAuthUserFn - Reference to a Convex query that returns user.
+ * The component provides a query for this via `export const { getAuthUser } = authComponent.clientApi()`.
+ * @param props.isAuthError - Function to check if the error is auth related.
+ */
+export const AuthBoundary = ({
+  children,
+  /**
+   * The function to call when the user is unauthenticated. Typically a redirect
+   * to the login page.
+   */
+  onUnauth,
+  /**
+   * The Better Auth authClient to use.
+   */
+  authClient,
+  /**
+   * The fallback to render when the user is unauthenticated. Defaults to null.
+   * Generally not rendered as error handling is typically a redirect.
+   */
+  renderFallback,
+  /**
+   * The function to call to get the auth user.
+   */
+  getAuthUserFn,
+  /**
+   * The function to call to check if the error is auth related.
+   */
+  isAuthError,
+}: PropsWithChildren<{
+  onUnauth: () => void | Promise<void>;
+  authClient: AuthClient;
+  renderFallback?: () => React.ReactNode;
+  getAuthUserFn: FunctionReference<"query", "public", EmptyObject>;
+  isAuthError: (error: unknown) => boolean;
+}>) => {
+  const { isAuthenticated, isLoading } = useConvexAuth();
+  const handleUnauth = useCallback(async () => {
+    // Auth request that will clear cookies if session is invalid
+    await authClient.getSession();
+    await onUnauth();
+  }, [onUnauth]);
+
+  useEffect(() => {
+    void (async () => {
+      if (!isLoading && !isAuthenticated) {
+        await handleUnauth();
+      }
+    })();
+  }, [isLoading, isAuthenticated]);
+
+  return (
+    <ErrorBoundary
+      onUnauth={handleUnauth}
+      isAuthError={isAuthError}
+      renderFallback={renderFallback}
+    >
+      <Authenticated>
+        <UserSubscription getAuthUserFn={getAuthUserFn} />
+      </Authenticated>
+      {children}
+    </ErrorBoundary>
+  );
+};

package/src/react-start/index.ts

@@ -0,0 +1,153 @@
+import { stripIndent } from "common-tags";
+import type {
+  FunctionReference,
+  FunctionReturnType,
+  OptionalRestArgs,
+} from "convex/server";
+import { ConvexHttpClient } from "convex/browser";
+import { getToken } from "../utils/index.js";
+import type { GetTokenOptions } from "../utils/index.js";
+import React from "react";
+
+// Caching supported for React 19+ only
+const cache =
+  (React as typeof React & {
+    cache?: <Fn extends (...args: any[]) => any>(fn: Fn) => Fn;
+  }).cache ||
+  ((fn: (...args: any[]) => any) => {
+    return (...args: any[]) => fn(...args);
+  });
+
+type ClientOptions = {
+  /**
+   * The URL of the Convex deployment to use for the function call.
+   */
+  convexUrl: string;
+  /**
+   * The HTTP Actions URL of the Convex deployment to use for the function call.
+   */
+  convexSiteUrl: string;
+  /**
+   * The JWT-encoded OpenID Connect authentication token to use for the function call.
+   * Just an optional override for edge cases, you probably don't need this.
+   */
+  token?: string;
+};
+
+function setupClient(options: ClientOptions) {
+  const client = new ConvexHttpClient(options.convexUrl);
+  if (options.token !== undefined) {
+    client.setAuth(options.token);
+  }
+  // @ts-expect-error - setFetchOptions is internal
+  client.setFetchOptions({ cache: "no-store" });
+  return client;
+}
+
+const parseConvexSiteUrl = (url: string) => {
+  if (!url) {
+    throw new Error(stripIndent`
+      CONVEX_SITE_URL is not set.
+      This is automatically set in the Convex backend, but must be set in the TanStack Start environment.
+      For local development, this can be set in the .env.local file.
+    `);
+  }
+  if (url.endsWith(".convex.cloud")) {
+    throw new Error(stripIndent`
+      CONVEX_SITE_URL should be set to your Convex Site URL, which ends in .convex.site.
+      Currently set to ${url}.
+    `);
+  }
+  return url;
+};
+
+const handler = (request: Request, opts: { convexSiteUrl: string }) => {
+  const requestUrl = new URL(request.url);
+  const nextUrl = `${opts.convexSiteUrl}${requestUrl.pathname}${requestUrl.search}`;
+  const headers = new Headers(request.headers);
+  headers.set("accept-encoding", "application/json");
+  headers.set("host", new URL(opts.convexSiteUrl).host);
+  return fetch(nextUrl, {
+    method: request.method,
+    headers,
+    redirect: "manual",
+    body: request.body,
+    // @ts-expect-error - duplex is required for streaming request bodies in modern fetch
+    duplex: "half",
+  });
+};
+
+export const convexBetterAuthReactStart = (
+  opts: Omit<GetTokenOptions, "forceRefresh"> & {
+    convexUrl: string;
+    convexSiteUrl: string;
+  }
+) => {
+  const siteUrl = parseConvexSiteUrl(opts.convexSiteUrl);
+
+  const cachedGetToken = cache(async (opts: GetTokenOptions) => {
+    const { getRequestHeaders } = await import("@tanstack/react-start/server");
+    const headers = getRequestHeaders();
+    return getToken(siteUrl, headers, opts);
+  });
+
+  const callWithToken = async <
+    FnType extends "query" | "mutation" | "action",
+    Fn extends FunctionReference<FnType>,
+  >(
+    fn: (token?: string) => Promise<FunctionReturnType<Fn>>
+  ): Promise<FunctionReturnType<Fn>> => {
+    const token = (await cachedGetToken(opts)) ?? {};
+    try {
+      return await fn(token?.token);
+    } catch (error) {
+      if (
+        !opts?.jwtCache?.enabled ||
+        token.isFresh ||
+        opts.jwtCache?.isAuthError(error)
+      ) {
+        throw error;
+      }
+      const newToken = await cachedGetToken({
+        ...opts,
+        forceRefresh: true,
+      });
+      return await fn(newToken.token);
+    }
+  };
+
+  return {
+    getToken: async () => {
+      const token = await cachedGetToken(opts);
+      return token.token;
+    },
+    handler: (request: Request) => handler(request, opts),
+    fetchAuthQuery: async <Query extends FunctionReference<"query">>(
+      query: Query,
+      ...args: OptionalRestArgs<Query>
+    ): Promise<FunctionReturnType<Query>> => {
+      return callWithToken((token?: string) => {
+        const client = setupClient({ ...opts, token });
+        return client.query(query, ...args);
+      });
+    },
+    fetchAuthMutation: async <Mutation extends FunctionReference<"mutation">>(
+      mutation: Mutation,
+      ...args: OptionalRestArgs<Mutation>
+    ): Promise<FunctionReturnType<Mutation>> => {
+      return callWithToken((token?: string) => {
+        const client = setupClient({ ...opts, token });
+        return client.mutation(mutation, ...args);
+      });
+    },
+    fetchAuthAction: async <Action extends FunctionReference<"action">>(
+      action: Action,
+      ...args: OptionalRestArgs<Action>
+    ): Promise<FunctionReturnType<Action>> => {
+      return callWithToken((token?: string) => {
+        const client = setupClient({ ...opts, token });
+        return client.action(action, ...args);
+      });
+    },
+  };
+};

package/src/react-start/vite-env.d.ts

@@ -0,0 +1,2 @@
+/// <reference types="vite/client" />
+/// <reference types="vite/types/importMeta.d.ts" />

package/src/test.ts

@@ -0,0 +1,18 @@
+/// <reference types="vite/client" />
+import type { TestConvex } from "convex-test";
+import type { GenericSchema, SchemaDefinition } from "convex/server";
+import schema from "./component/schema.js";
+const modules = import.meta.glob("./component/**/*.ts");
+
+/**
+ * Register the component with the test convex instance.
+ * @param t - The test convex instance, e.g. from calling `convexTest`.
+ * @param name - The name of the component, as registered in convex.config.ts.
+ */
+export function register(
+  t: TestConvex<SchemaDefinition<GenericSchema, boolean>>,
+  name: string = "betterAuth"
+) {
+  t.registerComponent(name, schema, modules);
+}
+export default { register, schema, modules };

package/src/utils/index.ts

@@ -0,0 +1,171 @@
+import { betterFetch } from "@better-fetch/fetch";
+import type { Auth } from "better-auth";
+import type { betterAuth } from "better-auth/minimal";
+import { getSessionCookie } from "better-auth/cookies";
+import type {
+  AuthProvider,
+  DefaultFunctionArgs,
+  FunctionReference,
+  GenericActionCtx,
+  GenericDataModel,
+  GenericMutationCtx,
+  GenericQueryCtx,
+} from "convex/server";
+import { JWT_COOKIE_NAME } from "../plugins/convex/index.js";
+import * as jose from "jose";
+import type { Jwk } from "better-auth/plugins/jwt";
+
+export type CreateAuth<
+  DataModel extends GenericDataModel,
+  A extends ReturnType<typeof betterAuth> = Auth,
+> = (ctx: GenericCtx<DataModel>) => A;
+
+export type EventFunction<T extends DefaultFunctionArgs> = FunctionReference<
+  "mutation",
+  "internal" | "public",
+  T
+>;
+
+export type GenericCtx<DataModel extends GenericDataModel = GenericDataModel> =
+  | GenericQueryCtx<DataModel>
+  | GenericMutationCtx<DataModel>
+  | GenericActionCtx<DataModel>;
+
+export type RunMutationCtx<DataModel extends GenericDataModel> = (
+  | GenericMutationCtx<DataModel>
+  | GenericActionCtx<DataModel>
+) & {
+  runMutation: GenericMutationCtx<DataModel>["runMutation"];
+};
+
+export const isQueryCtx = <DataModel extends GenericDataModel>(
+  ctx: GenericCtx<DataModel>
+): ctx is GenericQueryCtx<DataModel> => {
+  return "db" in ctx;
+};
+
+export const isMutationCtx = <DataModel extends GenericDataModel>(
+  ctx: GenericCtx<DataModel>
+): ctx is GenericMutationCtx<DataModel> => {
+  return "db" in ctx && "scheduler" in ctx;
+};
+
+export const isActionCtx = <DataModel extends GenericDataModel>(
+  ctx: GenericCtx<DataModel>
+): ctx is GenericActionCtx<DataModel> => {
+  return "runAction" in ctx;
+};
+
+export const isRunMutationCtx = <DataModel extends GenericDataModel>(
+  ctx: GenericCtx<DataModel>
+): ctx is RunMutationCtx<DataModel> => {
+  return "runMutation" in ctx;
+};
+
+export const requireQueryCtx = <DataModel extends GenericDataModel>(
+  ctx: GenericCtx<DataModel>
+): GenericQueryCtx<DataModel> => {
+  if (!isQueryCtx(ctx)) {
+    throw new Error("Query context required");
+  }
+  return ctx;
+};
+
+export const requireMutationCtx = <DataModel extends GenericDataModel>(
+  ctx: GenericCtx<DataModel>
+): GenericMutationCtx<DataModel> => {
+  if (!isMutationCtx(ctx)) {
+    throw new Error("Mutation context required");
+  }
+  return ctx;
+};
+
+export const requireActionCtx = <DataModel extends GenericDataModel>(
+  ctx: GenericCtx<DataModel>
+): GenericActionCtx<DataModel> => {
+  if (!isActionCtx(ctx)) {
+    throw new Error("Action context required");
+  }
+  return ctx;
+};
+
+export const requireRunMutationCtx = <DataModel extends GenericDataModel>(
+  ctx: GenericCtx<DataModel>
+): RunMutationCtx<DataModel> => {
+  if (!isRunMutationCtx(ctx)) {
+    throw new Error("Mutation or action context required");
+  }
+  return ctx;
+};
+
+export type GetTokenOptions = {
+  forceRefresh?: boolean;
+  cookiePrefix?: string;
+  jwtCache?: {
+    enabled: boolean;
+    expirationToleranceSeconds?: number;
+    isAuthError: (error: unknown) => boolean;
+  };
+};
+
+export const getToken = async (
+  siteUrl: string,
+  headers: Headers,
+  opts?: GetTokenOptions
+) => {
+  const fetchToken = async () => {
+    const { data } = await betterFetch<{ token: string }>(
+      "/api/auth/convex/token",
+      {
+        baseURL: siteUrl,
+        headers,
+      }
+    );
+    return { isFresh: true, token: data?.token };
+  };
+  if (!opts?.jwtCache?.enabled || opts.forceRefresh) {
+    return await fetchToken();
+  }
+  const token = getSessionCookie(new Headers(headers), {
+    cookieName: JWT_COOKIE_NAME,
+    cookiePrefix: opts?.cookiePrefix,
+  });
+  if (!token) {
+    return await fetchToken();
+  }
+  try {
+    const claims = jose.decodeJwt(token);
+    const exp = claims?.exp;
+    const now = Math.floor(new Date().getTime() / 1000);
+    const isExpired = exp
+      ? now > exp + (opts?.jwtCache?.expirationToleranceSeconds ?? 60)
+      : true;
+    if (!isExpired) {
+      return { isFresh: false, token };
+    }
+  } catch (error) {
+    // eslint-disable-next-line no-console
+    console.error("Error decoding JWT", error);
+  }
+  return await fetchToken();
+};
+
+export const parseJwks = (providerConfig: AuthProvider) => {
+  const staticJwksString =
+    "jwks" in providerConfig && providerConfig.jwks?.startsWith("data:text/")
+      ? atob(providerConfig.jwks.split("base64,")[1])
+      : undefined;
+
+  if (!staticJwksString) {
+    return;
+  }
+  const parsed = JSON.parse(
+    staticJwksString?.slice(1, -1).replaceAll(/[\s\\]/g, "") || "{}"
+  );
+  const staticJwks = {
+    ...parsed,
+    privateKey: `"${parsed.privateKey}"`,
+    publicKey: `"${parsed.publicKey}"`,
+  } as Jwk;
+  return staticJwks;
+};