convex 1.48.0-alpha.0 → 1.48.0

package/src/cli/mcp.ts

@@ -1,4 +1,3 @@
-import path from "path";
 import { Command, Option } from "@commander-js/extra-typings";
 import { oneoffContext } from "../bundler/context.js";
 import { logError } from "../bundler/log.js";
@@ -7,7 +6,6 @@ import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { actionDescription } from "./lib/command.js";
 import { checkAuthorization } from "./lib/login.js";
 import {
-  encodeDeploymentSelector,
   McpOptions,
   RequestContext,
   RequestCrash,
@@ -117,14 +115,6 @@ function enabledTools(
 export function makeServer(options: McpOptions) {
   const enabledToolsByName = enabledTools(options);
   const mutex = new Mutex();
-  const serverDirectory = process.cwd();
-  options = {
-    ...options,
-    envFile:
-      options.envFile === undefined
-        ? undefined
-        : path.resolve(serverDirectory, options.envFile),
-  };
   const server = new Server(
     {
       name: "Convex MCP Server",
@@ -138,7 +128,17 @@ export function makeServer(options: McpOptions) {
   );
   server.setRequestHandler("tools/call", async (request: CallToolRequest) => {
     const ctx = new RequestContext(options);
+    await initializeBigBrainAuth(ctx, options);
     try {
+      const authorized = await checkAuthorization(ctx, false);
+      if (!authorized) {
+        await ctx.crash({
+          exitCode: 1,
+          errorType: "fatal",
+          printedMessage:
+            "Not Authorized: Run `npx convex dev` to login to your Convex project.",
+        });
+      }
       if (!request.params.arguments) {
         await ctx.crash({
           exitCode: 1,
@@ -158,44 +158,7 @@ export function makeServer(options: McpOptions) {
 
       // Serialize tool handlers since they're mutating the current working directory.
       const result = await mutex.runExclusive(async () => {
-        const projectDir =
-          "deploymentSelector" in input
-            ? ctx.decodeDeploymentSelectorUnchecked(input.deploymentSelector)
-                .projectDir
-            : (("projectDir" in input ? input.projectDir : undefined) ??
-              options.projectDir);
-        const previousDirectory = process.cwd();
-        try {
-          if (projectDir !== undefined)
-            process.chdir(path.resolve(serverDirectory, projectDir));
-          await initializeBigBrainAuth(ctx, options);
-          if (!(await checkAuthorization(ctx, false))) {
-            await ctx.crash({
-              exitCode: 1,
-              errorType: "fatal",
-              printedMessage:
-                "Not Authorized: Run `npx convex dev` to login to your Convex project.",
-            });
-          }
-          const absoluteDirectory = process.cwd();
-          const resolvedInput =
-            "deploymentSelector" in input
-              ? {
-                  ...input,
-                  deploymentSelector: encodeDeploymentSelector(
-                    absoluteDirectory,
-                    ctx.decodeDeploymentSelectorUnchecked(
-                      input.deploymentSelector,
-                    ).deployment,
-                  ),
-                }
-              : projectDir === undefined
-                ? input
-                : { ...input, projectDir: absoluteDirectory };
-          return await convexTool.handler(ctx, resolvedInput);
-        } finally {
-          process.chdir(previousDirectory);
-        }
+        return await convexTool.handler(ctx, input);
       });
       return {
         content: [

package/src/cli/program.ts

@@ -21,7 +21,6 @@ import { logout } from "./logout.js";
 import { logs } from "./logs.js";
 import { mcp } from "./mcp.js";
 import { networkTest } from "./network_test.js";
-import { account } from "./account.js";
 import { project } from "./project.js";
 import { reinit } from "./reinit.js";
 import { run } from "./run.js";
@@ -57,7 +56,6 @@ export function buildProgram() {
       .addCommand(codegen)
       .addCommand(update)
       .addCommand(logout)
-      .addCommand(account)
       .addCommand(networkTest, { hidden: true })
       .addCommand(integration, { hidden: true })
       .addCommand(functionSpec)

package/src/index.ts

@@ -1 +1 @@
-export const version = "1.48.0-alpha.0";
+export const version = "1.48.0";

package/src/server/authentication.ts

@@ -235,3 +235,82 @@ export interface Auth {
    */
   getUserIdentity(): Promise<UserIdentity | null>;
 }
+
+/**
+ * {@link Auth} for mutations, which can also sign JWTs with this deployment's
+ * key.
+ *
+ * @public
+ */
+export interface MutationAuth extends Auth {
+  /**
+   * Sign an ES256 JWT with this deployment's key.
+   *
+   * Pass the `claims` and `expiresInSeconds` values that match your use case.
+   *
+   * Convex populates the header and sets the `iss`, `iat` and `exp` claims.
+   *
+   * The `iss` is `process.env.CONVEX_CLOUD_URL` for the app and
+   * `${process.env.CONVEX_CLOUD_URL}/components/<name>` for a component.
+   *
+   * Anyone can verify these tokens against the public keys at
+   * `${process.env.CONVEX_CLOUD_URL}/.well-known/jwks.json`.
+   *
+   * Claims are signed but not encrypted, so anyone holding the token can read
+   * them.
+   *
+   * Prefer short token lifetimes: a token can't be revoked individually, and a
+   * mutation can always sign a fresh one to reassert the claims. This API
+   * allows a token to have a max expiration of 1 hour from issuance.
+   *
+   * Claims that start with `convex` or `cvx` (case insensitive) and the `nbf`
+   * claim are reserved and may not be set.
+   */
+  signJwt(options: SignJwtOptions): Promise<string>;
+}
+
+/**
+ * Claims that callers may not set on JWTs with {@link MutationAuth.signJwt}.
+ */
+export type ReservedJwtClaim = "iss" | "iat" | "exp" | "nbf";
+
+/**
+ * Every ASCII casing of `S`: `AnyCase<"cvx">` is `"cvx" | "cvX" | "cVx" | ...`.
+ */
+type AnyCase<S extends string> = S extends `${infer First}${infer Rest}`
+  ? `${Lowercase<First> | Uppercase<First>}${AnyCase<Rest>}`
+  : S;
+
+/**
+ * Claim names starting with `convex` or `cvx`, in any casing, are reserved
+ * for Convex. They may not be set on JWTs with {@link MutationAuth.signJwt}.
+ */
+// NOTE: only relatively short prefixes should ever be passed below. The AnyCase
+// type produces 2^length string literals which can get out of hand for anything
+// but short strings.
+export type ReservedJwtClaimPrefix = AnyCase<"convex" | "cvx">;
+
+/**
+ * Rejects claim names starting with a {@link ReservedJwtClaimPrefix}.
+ */
+// Kept as a named alias rather than inlined into SignJwtClaims: typedoc's
+// markdown renderer mangles template-literal index signatures into invalid
+// MDX, but renders a reference to a named type as plain text.
+type ReservedPrefixJwtClaims = {
+  [K: `${ReservedJwtClaimPrefix}${string}`]: never;
+};
+
+/**
+ * The claims a caller passes to {@link MutationAuth.signJwt}: any JSON value,
+ * except for the {@link ReservedJwtClaim}s and names starting with a
+ * {@link ReservedJwtClaimPrefix}.
+ */
+export type SignJwtClaims = Record<string, JSONValue> & {
+  [K in ReservedJwtClaim]?: never;
+} & ReservedPrefixJwtClaims;
+
+export type SignJwtOptions = {
+  claims?: SignJwtClaims;
+  /** How long the token stays valid, at least 1 second and at most 1 hour. */
+  expiresInSeconds: number;
+};

package/src/server/components/index.ts

@@ -49,6 +49,17 @@ export type FunctionHandle<
   ReturnType = any,
 > = string & FunctionReference<Type, "internal", Args, ReturnType>;
 
+/**
+ * A {@link FunctionHandle} with the type semantics of {@link FunctionReference_future}.
+ *
+ * @public
+ */
+export type FunctionHandle_future<
+  Type extends FunctionType,
+  Args extends DefaultFunctionArgs = any,
+  ReturnType = any,
+> = string & FunctionReference_future<Type, "internal", Args, ReturnType>;
+
 /**
  * Create a serializable reference to a Convex function.
  * Passing a this reference to another component allows that component to call this

package/src/server/impl/authentication_impl.ts

@@ -1,4 +1,5 @@
-import { Auth } from "../authentication.js";
+import { Auth, MutationAuth } from "../authentication.js";
+import { version } from "../../index.js";
 import { performAsyncSyscall } from "./syscall.js";
 
 export function setupAuth(requestId: string): Auth {
@@ -10,3 +11,16 @@ export function setupAuth(requestId: string): Auth {
     },
   };
 }
+
+export function setupMutationAuth(requestId: string): MutationAuth {
+  return {
+    ...setupAuth(requestId),
+    signJwt: async (options) => {
+      return await performAsyncSyscall("1.0/signJwt", {
+        requestId,
+        version,
+        ...options,
+      });
+    },
+  };
+}

package/src/server/impl/registration_impl.ts

@@ -24,7 +24,7 @@ import {
 } from "../registration.js";
 import { setupActionCalls } from "./actions_impl.js";
 import { setupActionVectorSearch } from "./vector_search_impl.js";
-import { setupAuth } from "./authentication_impl.js";
+import { setupAuth, setupMutationAuth } from "./authentication_impl.js";
 import { setupReader, setupWriter } from "./database_impl.js";
 import { QueryImpl, QueryInitializerImpl } from "./query_impl.js";
 import {
@@ -55,7 +55,7 @@ async function invokeMutation<
   const args = jsonToConvex(JSON.parse(argsStr));
   const mutationCtx = {
     db: setupWriter(),
-    auth: setupAuth(requestId),
+    auth: setupMutationAuth(requestId),
     storage: setupStorageWriter(requestId),
     scheduler: setupMutationScheduler(),
     meta: setupMutationMeta(visibility),

package/src/server/index.ts

@@ -55,7 +55,12 @@ export type {
   Auth,
   AuthConfig,
   AuthProvider,
+  MutationAuth,
   UserIdentity,
+  ReservedJwtClaim,
+  ReservedJwtClaimPrefix,
+  SignJwtClaims,
+  SignJwtOptions,
   UserIdentityAttributes,
 } from "./authentication.js";
 export * from "./database.js";
@@ -209,6 +214,7 @@ export type {
   ComponentDefinition,
   AnyComponents,
   FunctionHandle,
+  FunctionHandle_future,
 } from "./components/index.js";
 
 /**

package/src/server/meta.ts

@@ -26,13 +26,9 @@ export type TransactionMetrics = {
   documentsWritten: TransactionMetric;
   functionsScheduled: TransactionMetric;
   scheduledFunctionArgsBytes: TransactionMetric;
-  /** @internal */
   filesWritten: TransactionMetric;
-  /** @internal */
   fileWriteBytes: TransactionMetric;
-  /** @internal */
   filesRead: TransactionMetric;
-  /** @internal */
   fileReadBytes: TransactionMetric;
 };
 
@@ -51,13 +47,9 @@ export interface TransactionLimits {
   documentsWritten?: number;
   functionsScheduled?: number;
   scheduledFunctionArgsBytes?: number;
-  /** @internal */
   filesWritten?: number;
-  /** @internal */
   fileWriteBytes?: number;
-  /** @internal */
   filesRead?: number;
-  /** @internal */
   fileReadBytes?: number;
 }
 

package/src/server/registration.ts

@@ -1,5 +1,6 @@
 import {
   Auth,
+  MutationAuth,
   GenericDatabaseReader,
   GenericDatabaseReaderWithTable,
   GenericDatabaseWriter,
@@ -87,12 +88,14 @@ export interface GenericMutationCtx<DataModel extends GenericDataModel> {
   db: GenericDatabaseWriter<DataModel>;
 
   /**
-   * Information about the currently authenticated user.
+   * Auth functionality for mutations.
    *
    * Call `await ctx.auth.getUserIdentity()` to get the current user's identity,
    * or `null` if the user is not authenticated.
+   *
+   * `ctx.auth.signJwt` is available for creating deployment issued JWTs.
    */
-  auth: Auth;
+  auth: MutationAuth;
 
   /**
    * A utility for reading and writing files in storage.

package/src/server/schema.ts

@@ -226,8 +226,6 @@ export class TableDefinition<
    *
    * Returns indexes defined on this table.
    * Intended for the advanced use cases of dynamically deciding which index to use for a query.
-   * If you think you need this, please chime in on ths issue in the Convex JS GitHub repo.
-   * https://github.com/get-convex/convex-js/issues/49
    */
   " indexes"(): { indexDescriptor: string; fields: string[] }[] {
     return this.indexes;

package/src/server/storage.ts

@@ -133,9 +133,9 @@ export interface StorageReader {
 }
 
 /**
- * An interface to write files to storage within Convex mutation functions.
+ * An interface to read and write files to storage within Convex mutation functions.
  *
- * Available as `ctx.storage` in mutations.
+ * Available as `ctx.storage` in mutations, actions, and HTTP actions.
  *
  * @see https://docs.convex.dev/file-storage
  * @public
@@ -195,46 +195,12 @@ export interface StorageWriter extends StorageReader {
     storageId: T extends { __tableName: any } ? never : T,
   ): Promise<void>;
 
-  /**
-   * @internal
-   */
-  // TODO: move `store` from StorageActionWriter to StorageWriter when mutation
-  // file storage access is ready for release
-  store(
-    blob: Blob,
-    options?: { sha256?: string },
-  ): Promise<GenericId<"_storage">>;
-
-  /**
-   * @internal
-   */
-  // TODO: move `get` from StorageActionWriter to StorageWriter when mutation
-  // file storage access is ready for release
-  get(storageId: GenericId<"_storage">): Promise<Blob | null>;
-}
-
-/**
- * An interface to read and write files to storage within Convex actions and HTTP actions.
- *
- * In actions, `ctx.storage` has additional methods not available in mutations:
- * `get()` to download a file as a Blob, and `store()` to upload a Blob directly.
- *
- * @example
- * ```typescript
- * // In an action, download and re-upload a file:
- * const blob = await ctx.storage.get(storageId);
- * if (blob) {
- *   const newStorageId = await ctx.storage.store(blob);
- * }
- * ```
- *
- * @public
- */
-export interface StorageActionWriter extends StorageWriter {
   /**
    * Download a file from storage as a Blob.
    *
-   * Only available in actions and HTTP actions (not in mutations or queries).
+   * In mutations, files read count toward the transaction's `filesRead` and
+   * `fileReadBytes` limits. Use
+   * `ctx.meta.getTransactionMetrics()` to check the remaining headroom.
    *
    * @param storageId - The `Id<"_storage">` of the file.
    * @returns A Blob containing the file contents, or `null` if the file doesn't exist.
@@ -249,16 +215,21 @@ export interface StorageActionWriter extends StorageWriter {
   get<T extends StorageId>(
     storageId: T extends { __tableName: any } ? never : T,
   ): Promise<Blob | null>;
+
   /**
    * Upload a Blob directly to storage.
    *
-   * Only available in actions and HTTP actions. For client-side uploads from
-   * mutations, use `generateUploadUrl()` instead.
+   * To upload files from a client, use {@link StorageWriter.generateUploadUrl}
+   * instead.
+   *
+   * In mutations, files stored count toward the transaction's `filesWritten`
+   * and `fileWriteBytes` limits. Use
+   * `ctx.meta.getTransactionMetrics()` to check the remaining headroom.
    *
    * @example
    * ```typescript
    * const storageId = await ctx.storage.store(blob);
-   * // Save storageId to the database via ctx.runMutation
+   * // If in an action, save storageId to the database via ctx.runMutation
    * ```
    *
    * @param blob - The Blob to store.
@@ -270,3 +241,19 @@ export interface StorageActionWriter extends StorageWriter {
     options?: { sha256?: string },
   ): Promise<GenericId<"_storage">>;
 }
+
+/**
+ * An interface to read and write files to storage within Convex actions and HTTP actions.
+ *
+ * @example
+ * ```typescript
+ * // In an action, download and re-upload a file:
+ * const blob = await ctx.storage.get(storageId);
+ * if (blob) {
+ *   const newStorageId = await ctx.storage.store(blob);
+ * }
+ * ```
+ *
+ * @public
+ */
+export interface StorageActionWriter extends StorageWriter {}