convex 1.43.0 → 1.44.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "convex",
   "description": "Client for the Convex Cloud",
-  "version": "1.43.0",
+  "version": "1.44.0",
   "author": "Convex, Inc. <no-reply@convex.dev>",
   "homepage": "https://convex.dev",
   "repository": {
@@ -258,19 +258,18 @@
     "openapi-typescript-helpers": "~0.1.0",
     "openid-client": "^5.3.1",
     "ora": "^9.0.0",
-    "prettier": "3.8.1",
     "react": "^18.0.0",
     "react-dom": "^18.0.0",
     "semver": "^7.6.0",
     "serve-handler": "~6.1.6",
     "shx": "~0.4.0",
     "skott": "~0.35.4",
-    "tar": "^7.5.16",
+    "tar": "^7.5.21",
     "tsx": "^4.19.4",
     "typedoc": "^0.24.6",
     "typescript": "~5.0.3",
     "typescript-eslint": "~8.57.0",
-    "undici": "7.28.0",
+    "undici": "7.29.0",
     "vitest": "^4.1.0",
     "wait-for-expect": "~4.0.0",
     "zod": "^3.24.0",

package/src/cli/codegen_templates/component_server.ts

@@ -1,15 +1,21 @@
 import { header } from "./common.js";
-import { EnvVarMeta, generateEnvInterface } from "./server.js";
+import {
+  EnvVarMeta,
+  generateEnvInterface,
+  withPlatformEnvVars,
+} from "./server.js";
 
 export function componentServerTS(
   isRoot: boolean,
   // - undefined: not yet known (initial codegen). Emits an untyped `env` stub.
-  // - non-empty array: emit typed `Env` interface and typed `env` export.
-  // - empty array: no env vars declared. Omit `env` from generated code.
+  // - array (empty or not): emit a typed `Env` interface and typed `env`
+  //   export. The interface always includes the platform-provided env vars.
   envVars: EnvVarMeta[] | undefined,
 ): string {
-  const hasEnv = !!envVars && envVars.length > 0;
-  const envInterface = hasEnv ? generateEnvInterface(envVars!) : "";
+  const emittedEnvVars =
+    envVars === undefined ? undefined : withPlatformEnvVars(envVars);
+  const hasEnv = emittedEnvVars !== undefined;
+  const envInterface = hasEnv ? generateEnvInterface(emittedEnvVars!) : "";
 
   const result = `
   ${header(
@@ -113,7 +119,7 @@ export function componentServerTS(
    * @returns The wrapped function. Import this function from \`convex/http.js\` and route it to hook it up.
    */
   export const httpAction: HttpActionBuilder = httpActionGeneric;
-  ${hasEnv ? "export const env: Env = process.env as unknown as Env;" : envVars === undefined ? "export const env: Record<string, string | undefined> = process.env as unknown as Record<string, string | undefined>;" : ""}
+  ${hasEnv ? "export const env: Env = (globalThis as unknown as { process: { env: Env } }).process.env;" : "export const env: Record<string, string | undefined> = (globalThis as unknown as { process: { env: Record<string, string | undefined> } }).process.env;"}
 
   /**
    * A set of services for use within Convex query functions.

package/src/cli/codegen_templates/server.ts

@@ -6,8 +6,26 @@ export type EnvVarMeta = [
   { type: "value"; value: string; optional?: boolean | undefined },
 ];
 
+// Environment variables the platform always injects into every deployment,
+// independent of the user's `convex.config.ts` declarations. Both are always
+// present, so they're typed as required `string`.
+const PLATFORM_ENV_VARS: EnvVarMeta[] = [
+  ["CONVEX_CLOUD_URL", { type: "value", value: '{"type":"string"}' }],
+  ["CONVEX_SITE_URL", { type: "value", value: '{"type":"string"}' }],
+];
+
+// Prepend the always-present platform env vars. Users can't declare env vars
+// with these names — the backend rejects overriding built-in system env vars —
+// so there's no collision to worry about.
+export function withPlatformEnvVars(envVars: EnvVarMeta[]): EnvVarMeta[] {
+  return [...PLATFORM_ENV_VARS, ...envVars];
+}
+
 const ENV_DOCSTRING = `/**
- * Typesafe environment variables declared in \`convex.config.ts\`.
+ * Typesafe environment variables.
+ *
+ * This includes platform-provided env vars and any variables declared in
+ * \`convex.config.ts\`.
  */`;
 
 export function serverCodegen({
@@ -17,42 +35,41 @@ export function serverCodegen({
   useTypeScript: boolean;
   // - undefined: env var declarations not yet known (initial codegen before
   //   server analysis). Emits an untyped `env` stub so imports don't break.
-  // - non-empty array: emit a typed `Env` interface and typed `env` export.
-  // - empty array: no env vars declared. Omit `env` from generated code.
+  // - array (empty or not): emit a typed `Env` interface and typed `env`
+  //   export. The interface always includes the platform-provided env vars, so
+  //   an empty array still yields a typed `env` with just those.
   envVars: EnvVarMeta[] | undefined;
 }) {
-  const hasEnv = !!envVars && envVars.length > 0;
-  const envInterface = hasEnv ? generateEnvInterface(envVars!) : "";
+  const emittedEnvVars =
+    envVars === undefined ? undefined : withPlatformEnvVars(envVars);
+  const hasEnv = emittedEnvVars !== undefined;
+  const envInterface = hasEnv ? generateEnvInterface(emittedEnvVars!) : "";
   const envDeclDTS = hasEnv
     ? `
 ${ENV_DOCSTRING}
 export declare const env: Env;
 `
-    : envVars === undefined
-      ? `
+    : `
 export declare const env: Record<string, string | undefined>;
-`
-      : "";
+`;
+  // Route through `globalThis` rather than the bare `process` global so the
+  // generated file typechecks even in projects without `@types/node`.
   const envDeclTS = hasEnv
     ? `
 ${ENV_DOCSTRING}
-export const env: Env = process.env as unknown as Env;
+export const env: Env = (globalThis as unknown as { process: { env: Env } }).process.env;
 `
-    : envVars === undefined
-      ? `
-export const env: Record<string, string | undefined> = process.env as unknown as Record<string, string | undefined>;
-`
-      : "";
+    : `
+export const env: Record<string, string | undefined> = (globalThis as unknown as { process: { env: Record<string, string | undefined> } }).process.env;
+`;
   const envDeclJS = hasEnv
     ? `
 ${ENV_DOCSTRING}
 export const env = process.env;
 `
-    : envVars === undefined
-      ? `
+    : `
 export const env = process.env;
-`
-      : "";
+`;
 
   if (!useTypeScript) {
     // Generate separate .js and .d.ts files

package/src/cli/lib/login.ts

@@ -38,14 +38,14 @@ custom.setHttpOptionsDefaults({
   timeout: parseInt(process.env.OPENID_CLIENT_TIMEOUT || "10000"),
 });
 
-export async function checkAuthorization(
+/**
+ * Whether Big Brain accepts this credential. Takes the header explicitly so
+ * callers can check a credential other than the one `ctx` resolved to.
+ */
+export async function isAuthorizedHeader(
   ctx: Context,
-  acceptOptIns: boolean,
+  header: string,
 ): Promise<boolean> {
-  const header = ctx.bigBrainAuth()?.header ?? null;
-  if (header === null) {
-    return false;
-  }
   try {
     const resp = await fetch(`${provisionHost}/api/authorize`, {
       method: "HEAD",
@@ -57,9 +57,7 @@ export async function checkAuthorization(
     // Don't throw an error if this request returns a non-200 status.
     // Big Brain responds with a variety of error codes -- 401 if the token is correctly-formed but not valid, and either 400 or 500 if the token is ill-formed.
     // We only care if this check returns a 200 code (so we can skip logging in again) -- any other errors should be silently skipped and we'll run the whole login flow again.
-    if (resp.status !== 200) {
-      return false;
-    }
+    return resp.status === 200;
   } catch (e: any) {
     // This `catch` block should only be hit if a network error was encountered
     logError(
@@ -67,6 +65,19 @@ export async function checkAuthorization(
     );
     return await logAndHandleFetchError(ctx, e);
   }
+}
+
+export async function checkAuthorization(
+  ctx: Context,
+  acceptOptIns: boolean,
+): Promise<boolean> {
+  const header = ctx.bigBrainAuth()?.header ?? null;
+  if (header === null) {
+    return false;
+  }
+  if (!(await isAuthorizedHeader(ctx, header))) {
+    return false;
+  }
 
   // Check that we have optin as well
   const shouldContinue = await optins(ctx, acceptOptIns);

package/src/cli/login.test.ts

@@ -0,0 +1,261 @@
+import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
+import { nodeFs } from "../bundler/fs.js";
+import { login } from "./login.js";
+import { bigBrainAPI } from "./lib/utils/utils.js";
+import { readGlobalConfig } from "./lib/utils/globalConfig.js";
+
+vi.mock("@sentry/node", () => ({
+  captureException: vi.fn(),
+  close: vi.fn(),
+}));
+
+vi.mock("../bundler/fs.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../bundler/fs.js")>();
+  return {
+    ...actual,
+    nodeFs: {
+      ...actual.nodeFs,
+      exists: vi.fn(),
+      readUtf8File: vi.fn(),
+    },
+  };
+});
+
+vi.mock("./lib/utils/utils.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("./lib/utils/utils.js")>();
+  return { ...actual, bigBrainAPI: vi.fn() };
+});
+
+vi.mock("./lib/utils/globalConfig.js", async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import("./lib/utils/globalConfig.js")>();
+  return { ...actual, readGlobalConfig: vi.fn() };
+});
+
+// `initializeBigBrainAuth` loads `.env.local` and `.env` into `process.env`.
+// Tests set those variables directly, and `dotenv.parse` stays real for the
+// file-attribution lookup.
+vi.mock("dotenv", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("dotenv")>();
+  return { ...actual, config: vi.fn() };
+});
+
+const ACCOUNT_TOKEN = "account-token";
+const TEAMS = [{ id: 1, name: "Team One", slug: "team-one" }];
+const DEPLOYMENT_KEY = "dev:tall-goat-123|deployment-secret";
+const PROJECT_KEY = "project:my-team:my-project|project-secret";
+
+/** Authorization headers Big Brain accepts. Anything else gets a 401. */
+let authorized: Set<string>;
+let mockFetch: ReturnType<typeof vi.fn>;
+
+async function runStatus() {
+  await login.parseAsync(["status"], { from: "user" });
+}
+
+function output(): string {
+  return vi
+    .mocked(process.stderr.write)
+    .mock.calls.map((call) => String(call[0]))
+    .join("");
+}
+
+/** The credentials `/api/authorize` was called with, in order. */
+function authorizeHeaders(): string[] {
+  return mockFetch.mock.calls.map(
+    (call) => (call[1] as any).headers.Authorization,
+  );
+}
+
+function setEnvFile(path: string, contents: string) {
+  vi.mocked(nodeFs.exists).mockImplementation((p) => p === path);
+  vi.mocked(nodeFs.readUtf8File).mockImplementation((p) => {
+    if (p !== path) {
+      throw new Error(`Unexpected read of ${p}`);
+    }
+    return contents;
+  });
+}
+
+describe("npx convex login status", () => {
+  let savedEnv: NodeJS.ProcessEnv;
+
+  beforeEach(() => {
+    savedEnv = { ...process.env };
+    process.env = {};
+
+    vi.resetAllMocks();
+    authorized = new Set([`Bearer ${ACCOUNT_TOKEN}`]);
+    mockFetch = vi.fn(async (url: string, options: any) => {
+      if (!String(url).endsWith("/api/authorize")) {
+        throw new Error(`Unexpected fetch of ${url}`);
+      }
+      return {
+        status: authorized.has(options.headers.Authorization) ? 200 : 401,
+      };
+    });
+    vi.stubGlobal("fetch", mockFetch);
+
+    vi.mocked(readGlobalConfig).mockReturnValue({ accessToken: ACCOUNT_TOKEN });
+    vi.mocked(bigBrainAPI).mockResolvedValue(TEAMS);
+    vi.mocked(nodeFs.exists).mockReturnValue(false);
+
+    vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+    vi.spyOn(process, "exit").mockImplementation((() => {
+      throw new Error("process.exit called");
+    }) as any);
+  });
+
+  afterEach(() => {
+    process.env = savedEnv;
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  describe("account status", () => {
+    test("reports the account and its teams", async () => {
+      await runStatus();
+
+      expect(output()).toContain("Convex account token found in:");
+      expect(output()).toContain("config.json");
+      expect(output()).toContain("Status: Logged in");
+      expect(output()).toContain("Teams: 1 team accessible");
+      expect(output()).toContain("- Team One (team-one)");
+      expect(output()).not.toContain("Working Directory:");
+    });
+
+    test("reports no token when the global config is missing", async () => {
+      vi.mocked(readGlobalConfig).mockReturnValue(null);
+
+      await runStatus();
+
+      expect(output()).toContain("No Convex account token found in:");
+      expect(output()).toContain("Status: Not logged in");
+      expect(bigBrainAPI).not.toHaveBeenCalled();
+    });
+
+    test("reports not logged in when Big Brain rejects the account token", async () => {
+      authorized.clear();
+
+      await runStatus();
+
+      expect(output()).toContain("Convex account token found in:");
+      expect(output()).toContain("Status: Not logged in");
+      expect(bigBrainAPI).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("deploy key in the working directory", () => {
+    test("reports a valid deployment key, checked without its prefix", async () => {
+      process.env.CONVEX_DEPLOY_KEY = DEPLOYMENT_KEY;
+      setEnvFile(".env.local", `CONVEX_DEPLOY_KEY=${DEPLOYMENT_KEY}\n`);
+      // Big Brain only accepts a deployment key with the `dev:` prefix removed.
+      authorized.add("Bearer deployment-secret");
+
+      await runStatus();
+
+      expect(output()).toContain(
+        "Working Directory: Valid CONVEX_DEPLOY_KEY in .env.local",
+      );
+      expect(authorizeHeaders()).toContain("Bearer deployment-secret");
+      expect(authorizeHeaders()).not.toContain(`Bearer ${DEPLOYMENT_KEY}`);
+    });
+
+    test("reports a deployment key Big Brain rejects", async () => {
+      process.env.CONVEX_DEPLOY_KEY = DEPLOYMENT_KEY;
+      setEnvFile(".env.local", `CONVEX_DEPLOY_KEY=${DEPLOYMENT_KEY}\n`);
+
+      await runStatus();
+
+      expect(output()).toContain(
+        "Working Directory: Invalid CONVEX_DEPLOY_KEY in .env.local",
+      );
+    });
+
+    test("attributes a key that isn't in an env file to the shell", async () => {
+      process.env.CONVEX_DEPLOY_KEY = DEPLOYMENT_KEY;
+
+      await runStatus();
+
+      expect(output()).toContain(
+        "Working Directory: Invalid CONVEX_DEPLOY_KEY in shell environment",
+      );
+    });
+
+    test("attributes a key found in .env", async () => {
+      process.env.CONVEX_DEPLOY_KEY = DEPLOYMENT_KEY;
+      setEnvFile(".env", `CONVEX_DEPLOY_KEY=${DEPLOYMENT_KEY}\n`);
+
+      await runStatus();
+
+      expect(output()).toContain(
+        "Working Directory: Invalid CONVEX_DEPLOY_KEY in .env",
+      );
+    });
+
+    test("names CONVEX_DEPLOYMENT_TOKEN when that's the variable set", async () => {
+      process.env.CONVEX_DEPLOYMENT_TOKEN = DEPLOYMENT_KEY;
+      setEnvFile(".env.local", `CONVEX_DEPLOYMENT_TOKEN=${DEPLOYMENT_KEY}\n`);
+      authorized.add("Bearer deployment-secret");
+
+      await runStatus();
+
+      expect(output()).toContain(
+        "Working Directory: Valid CONVEX_DEPLOYMENT_TOKEN in .env.local",
+      );
+    });
+
+    test("reports a project key", async () => {
+      process.env.CONVEX_DEPLOY_KEY = PROJECT_KEY;
+      setEnvFile(".env.local", `CONVEX_DEPLOY_KEY=${PROJECT_KEY}\n`);
+      authorized.add("Bearer project-secret");
+
+      await runStatus();
+
+      expect(output()).toContain(
+        "Working Directory: Valid CONVEX_DEPLOY_KEY in .env.local",
+      );
+      expect(authorizeHeaders()).toContain("Bearer project-secret");
+    });
+
+    test("stays quiet about a preview key, which never outranks the account", async () => {
+      vi.mocked(readGlobalConfig).mockReturnValue(null);
+      process.env.CONVEX_DEPLOY_KEY =
+        "preview:my-team:my-project|preview-secret";
+
+      await runStatus();
+
+      expect(output()).toContain("Status: Not logged in");
+      expect(output()).not.toContain("Working Directory:");
+    });
+  });
+
+  describe("account and deploy key together", () => {
+    test("reports both, listing teams for the account", async () => {
+      process.env.CONVEX_DEPLOY_KEY = DEPLOYMENT_KEY;
+      setEnvFile(".env.local", `CONVEX_DEPLOY_KEY=${DEPLOYMENT_KEY}\n`);
+
+      await runStatus();
+
+      expect(output()).toContain("Status: Logged in");
+      expect(output()).toContain("Teams: 1 team accessible");
+      expect(output()).toContain(
+        "Working Directory: Invalid CONVEX_DEPLOY_KEY in .env.local",
+      );
+    });
+
+    test("reports the key while logged out", async () => {
+      vi.mocked(readGlobalConfig).mockReturnValue(null);
+      process.env.CONVEX_DEPLOY_KEY = DEPLOYMENT_KEY;
+      setEnvFile(".env.local", `CONVEX_DEPLOY_KEY=${DEPLOYMENT_KEY}\n`);
+
+      await runStatus();
+
+      expect(output()).toContain("No Convex account token found in:");
+      expect(output()).toContain("Status: Not logged in");
+      expect(output()).toContain(
+        "Working Directory: Invalid CONVEX_DEPLOY_KEY in .env.local",
+      );
+    });
+  });
+});

package/src/cli/login.ts

@@ -1,7 +1,12 @@
 import { Command, Option } from "@commander-js/extra-typings";
-import { Context, oneoffContext } from "../bundler/context.js";
-import { logFinishedStep, logMessage } from "../bundler/log.js";
-import { checkAuthorization, performLogin } from "./lib/login.js";
+import * as dotenv from "dotenv";
+import { BigBrainAuth, Context, oneoffContext } from "../bundler/context.js";
+import { logFinishedStep, logMessage, logWarning } from "../bundler/log.js";
+import {
+  checkAuthorization,
+  isAuthorizedHeader,
+  performLogin,
+} from "./lib/login.js";
 import {
   loadProjectLocalConfig,
   loadUuidForAnonymousUser,
@@ -16,7 +21,12 @@ import {
   teamDashboardUrl,
 } from "./lib/dashboard.js";
 import { promptSearch, promptYesNo } from "./lib/utils/prompts.js";
-import { validateOrSelectTeam } from "./lib/utils/utils.js";
+import {
+  CONVEX_DEPLOY_KEY_ENV_VAR_NAME,
+  CONVEX_DEPLOYMENT_TOKEN_ENV_VAR_NAME,
+  ENV_VAR_FILE_PATH,
+  validateOrSelectTeam,
+} from "./lib/utils/utils.js";
 import {
   selectProject,
   updateEnvAndConfigForDeploymentSelection,
@@ -35,6 +45,61 @@ import {
 } from "./lib/utils/globalConfig.js";
 import { getTeamsForUser } from "./lib/api.js";
 
+/**
+ * The env file a deploy key came from, or null if it came from the shell.
+ * `dotenv` doesn't overwrite variables that are already set, so a value from
+ * the shell outranks these files -- match on the value to tell them apart.
+ */
+function deployKeyEnvFile(
+  ctx: Context,
+  envVarName: string,
+  value: string,
+): string | null {
+  for (const file of [ENV_VAR_FILE_PATH, ".env"]) {
+    if (!ctx.fs.exists(file)) {
+      continue;
+    }
+    if (dotenv.parse(ctx.fs.readUtf8File(file))[envVarName] === value) {
+      return file;
+    }
+  }
+  return null;
+}
+
+/**
+ * A project or deployment key in the environment outranks the account token for
+ * commands run from this directory, and an expired one makes the CLI look
+ * logged out, so report it separately from the account.
+ */
+async function reportDeployKeyInWorkingDirectory(
+  ctx: Context,
+  auth: BigBrainAuth | null,
+) {
+  // A preview deploy key is only used when there's no account token at all.
+  if (
+    auth === null ||
+    auth.kind === "accessToken" ||
+    auth.kind === "previewDeployKey"
+  ) {
+    return;
+  }
+  const key = auth.kind === "projectKey" ? auth.projectKey : auth.deploymentKey;
+  const envVarName = process.env[CONVEX_DEPLOY_KEY_ENV_VAR_NAME]
+    ? CONVEX_DEPLOY_KEY_ENV_VAR_NAME
+    : CONVEX_DEPLOYMENT_TOKEN_ENV_VAR_NAME;
+  const envFile = deployKeyEnvFile(ctx, envVarName, key);
+  const source = envFile ?? "shell environment";
+  // Big Brain only strips a `project:`/`team:` prefix itself, so a deployment
+  // key authorizes only without its `dev:`/`prod:` prefix. Split on the first
+  // `|` like the server does, so a secret containing one survives.
+  const secret = key.slice(key.indexOf("|") + 1);
+  if (await isAuthorizedHeader(ctx, `Bearer ${secret}`)) {
+    logMessage(`Working Directory: Valid ${envVarName} in ${source}`);
+    return;
+  }
+  logWarning(`Working Directory: Invalid ${envVarName} in ${source}`);
+}
+
 const loginStatus = new Command("status")
   .description("Check login status and list accessible teams")
   .allowExcessArguments(false)
@@ -45,24 +110,33 @@ const loginStatus = new Command("status")
       envFile: undefined,
     });
 
-    const globalConfig = readGlobalConfig(ctx);
-    const hasToken = globalConfig?.accessToken !== null;
+    // `_updateBigBrainAuth` below replaces any deploy key in `ctx` with the
+    // account token, so read the deploy key first.
+    const auth = ctx.bigBrainAuth();
 
-    if (hasToken) {
-      logMessage(`Convex account token found in: ${globalConfigPath()}`);
-    } else {
-      logMessage("No token found locally");
+    const globalConfig = readGlobalConfig(ctx);
+    if (globalConfig === null) {
+      logMessage(`No Convex account token found in: ${globalConfigPath()}`);
+      logMessage("Status: Not logged in");
+      await reportDeployKeyInWorkingDirectory(ctx, auth);
       return;
     }
+    logMessage(`Convex account token found in: ${globalConfigPath()}`);
 
-    const isLoggedIn = await checkAuthorization(ctx, false);
-
-    if (!isLoggedIn) {
+    const accessToken = globalConfig.accessToken;
+    if (!(await isAuthorizedHeader(ctx, `Bearer ${accessToken}`))) {
       logMessage("Status: Not logged in");
+      await reportDeployKeyInWorkingDirectory(ctx, auth);
       return;
     }
 
     logMessage("Status: Logged in");
+    // Describe the account, even if a deploy key outranks it for other commands.
+    ctx._updateBigBrainAuth({
+      kind: "accessToken",
+      header: `Bearer ${accessToken}`,
+      accessToken,
+    });
     const teams = await getTeamsForUser(ctx);
     logMessage(
       `Teams: ${teams.length} team${teams.length === 1 ? "" : "s"} accessible`,
@@ -70,6 +144,7 @@ const loginStatus = new Command("status")
     for (const team of teams) {
       logMessage(`  - ${team.name} (${team.slug})`);
     }
+    await reportDeployKeyInWorkingDirectory(ctx, auth);
   });
 
 export const login = new Command("login")

package/src/index.ts

@@ -1 +1 @@
-export const version = "1.43.0";
+export const version = "1.44.0";

package/src/react/ConvexAuthState.tsx

@@ -3,6 +3,7 @@ import React, {
   ReactNode,
   useContext,
   useEffect,
+  useMemo,
   useState,
 } from "react";
 import { AuthTokenFetcher } from "../browser/sync/client.js";
@@ -129,15 +130,22 @@ export function ConvexProviderWithAuth({
 
   const isAuthenticated =
     authProviderAuthenticated && (isConvexAuthenticated ?? false);
+  const isLoading = isConvexAuthenticated === null;
+  const isRefreshingWhileAuthenticated = isRefreshing && isAuthenticated;
+
+  // Stabilize the context value's identity so `useConvexAuth()` consumers
+  // only re-render when the derived auth state actually changes.
+  const authState = useMemo<ConvexAuthState>(
+    () => ({
+      isLoading,
+      isAuthenticated,
+      isRefreshing: isRefreshingWhileAuthenticated,
+    }),
+    [isLoading, isAuthenticated, isRefreshingWhileAuthenticated],
+  );
 
   return (
-    <ConvexAuthContext.Provider
-      value={{
-        isLoading: isConvexAuthenticated === null,
-        isAuthenticated,
-        isRefreshing: isRefreshing && isAuthenticated,
-      }}
-    >
+    <ConvexAuthContext.Provider value={authState}>
       <ConvexAuthStateFirstEffect
         authProviderAuthenticated={authProviderAuthenticated}
         fetchAccessToken={fetchAccessToken}