convex-security-check

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Convex Security Check

Convex 安全检查

A quick security audit checklist for Convex applications covering authentication, function exposure, argument validation, row-level access control, and environment variable handling.

一份针对 Convex 应用的快速安全审计清单，涵盖身份验证、函数暴露、参数验证、行级访问控制和环境变量处理。

Documentation Sources

文档来源

Before implementing, do not assume; fetch the latest documentation:

Primary: https://docs.convex.dev/auth
Production Security: https://docs.convex.dev/production
Functions Auth: https://docs.convex.dev/auth/functions-auth
For broader context: https://docs.convex.dev/llms.txt

在实施前，请勿主观假设；请获取最新文档：

主文档：https://docs.convex.dev/auth
生产环境安全：https://docs.convex.dev/production
函数身份验证：https://docs.convex.dev/auth/functions-auth
更多背景信息：https://docs.convex.dev/llms.txt

Instructions

操作说明

Security Checklist

安全审计清单

Use this checklist to quickly audit your Convex application's security:

使用此清单快速审计你的 Convex 应用安全：

1. Authentication

1. 身份验证

Authentication provider configured (Clerk, Auth0, etc.)
All sensitive queries check
```
ctx.auth.getUserIdentity()
```
Unauthenticated access explicitly allowed where intended
Session tokens properly validated

已配置身份验证提供商（Clerk、Auth0等）
所有敏感查询均检查
```
ctx.auth.getUserIdentity()
```
已明确允许预期的未认证访问场景
会话令牌已正确验证

2. Function Exposure

2. 函数暴露

Public functions (
```
query
```
,
```
mutation
```
,
```
action
```
) reviewed

Internal functions use

internalQuery

internalMutation

internalAction

No sensitive operations exposed as public functions
HTTP actions validate origin/authentication

已审核公开函数（
```
query
```
、
```
mutation
```
、
```
action
```
）

内部函数使用

internalQuery

、

internalMutation

、

internalAction

无敏感操作以公开函数形式暴露
HTTP 操作已验证来源/身份

3. Argument Validation

3. 参数验证

All functions have explicit
```
args
```
validators
All functions have explicit
```
returns
```
validators
No
```
v.any()
```
used for sensitive data
ID validators use correct table names

所有函数均有明确的
```
args
```
验证器
所有函数均有明确的
```
returns
```
验证器
敏感数据未使用
```
v.any()
```
ID 验证器使用正确的表名

4. Row-Level Access Control

4. 行级访问控制

Users can only access their own data
Admin functions check user roles
Shared resources have proper access checks
Deletion functions verify ownership

用户仅能访问自身数据
管理员函数检查用户角色
共享资源有适当的访问检查
删除函数验证资源所有权

5. Environment Variables

5. 环境变量

API keys stored in environment variables
No secrets in code or schema
Different keys for dev/prod environments
Environment variables accessed only in actions

API 密钥存储在环境变量中
代码或 schema 中无硬编码密钥
开发/生产环境使用不同密钥
仅在 action 中访问环境变量

Authentication Check

身份验证检查

typescript

// convex/auth.ts
import { query, mutation } from "./_generated/server";
import { v } from "convex/values";
import { ConvexError } from "convex/values";

// Helper to require authentication
async function requireAuth(ctx: QueryCtx | MutationCtx) {
  const identity = await ctx.auth.getUserIdentity();
  if (!identity) {
    throw new ConvexError("Authentication required");
  }
  return identity;
}

// Secure query pattern
export const getMyProfile = query({
  args: {},
  returns: v.union(v.object({
    _id: v.id("users"),
    name: v.string(),
    email: v.string(),
  }), v.null()),
  handler: async (ctx) => {
    const identity = await requireAuth(ctx);
    
    return await ctx.db
      .query("users")
      .withIndex("by_tokenIdentifier", (q) => 
        q.eq("tokenIdentifier", identity.tokenIdentifier)
      )
      .unique();
  },
});

typescript

// convex/auth.ts
import { query, mutation } from "./_generated/server";
import { v } from "convex/values";
import { ConvexError } from "convex/values";

// 身份验证辅助函数
async function requireAuth(ctx: QueryCtx | MutationCtx) {
  const identity = await ctx.auth.getUserIdentity();
  if (!identity) {
    throw new ConvexError("需要身份验证");
  }
  return identity;
}

// 安全查询示例
export const getMyProfile = query({
  args: {},
  returns: v.union(v.object({
    _id: v.id("users"),
    name: v.string(),
    email: v.string(),
  }), v.null()),
  handler: async (ctx) => {
    const identity = await requireAuth(ctx);
    
    return await ctx.db
      .query("users")
      .withIndex("by_tokenIdentifier", (q) => 
        q.eq("tokenIdentifier", identity.tokenIdentifier)
      )
      .unique();
  },
});

Function Exposure Check

函数暴露检查

typescript

// PUBLIC - Exposed to clients (review carefully!)
export const listPublicPosts = query({
  args: {},
  returns: v.array(v.object({ /* ... */ })),
  handler: async (ctx) => {
    // Anyone can call this - intentionally public
    return await ctx.db
      .query("posts")
      .withIndex("by_public", (q) => q.eq("isPublic", true))
      .collect();
  },
});

// INTERNAL - Only callable from other Convex functions
export const _updateUserCredits = internalMutation({
  args: { userId: v.id("users"), amount: v.number() },
  returns: v.null(),
  handler: async (ctx, args) => {
    // This cannot be called directly from clients
    await ctx.db.patch(args.userId, {
      credits: args.amount,
    });
    return null;
  },
});

typescript

// 公开函数 - 对客户端暴露（需仔细审核!）
export const listPublicPosts = query({
  args: {},
  returns: v.array(v.object({ /* ... */ })),
  handler: async (ctx) => {
    // 任何人都可调用 - 为预期公开场景
    return await ctx.db
      .query("posts")
      .withIndex("by_public", (q) => q.eq("isPublic", true))
      .collect();
  },
});

// 内部函数 - 仅可被其他 Convex 函数调用
export const _updateUserCredits = internalMutation({
  args: { userId: v.id("users"), amount: v.number() },
  returns: v.null(),
  handler: async (ctx, args) => {
    // 无法被客户端直接调用
    await ctx.db.patch(args.userId, {
      credits: args.amount,
    });
    return null;
  },
});

Argument Validation Check

参数验证检查

typescript

// GOOD: Strict validation
export const createPost = mutation({
  args: {
    title: v.string(),
    content: v.string(),
    category: v.union(
      v.literal("tech"),
      v.literal("news"),
      v.literal("other")
    ),
  },
  returns: v.id("posts"),
  handler: async (ctx, args) => {
    const identity = await requireAuth(ctx);
    return await ctx.db.insert("posts", {
      ...args,
      authorId: identity.tokenIdentifier,
    });
  },
});

// BAD: Weak validation
export const createPostUnsafe = mutation({
  args: {
    data: v.any(), // DANGEROUS: Allows any data
  },
  returns: v.id("posts"),
  handler: async (ctx, args) => {
    return await ctx.db.insert("posts", args.data);
  },
});

typescript

// 良好示例：严格验证
export const createPost = mutation({
  args: {
    title: v.string(),
    content: v.string(),
    category: v.union(
      v.literal("tech"),
      v.literal("news"),
      v.literal("other")
    ),
  },
  returns: v.id("posts"),
  handler: async (ctx, args) => {
    const identity = await requireAuth(ctx);
    return await ctx.db.insert("posts", {
      ...args,
      authorId: identity.tokenIdentifier,
    });
  },
});

// 不良示例：宽松验证
export const createPostUnsafe = mutation({
  args: {
    data: v.any(), // 危险：允许任意数据
  },
  returns: v.id("posts"),
  handler: async (ctx, args) => {
    return await ctx.db.insert("posts", args.data);
  },
});

Row-Level Access Control Check

行级访问控制检查

typescript

// Verify ownership before update
export const updateTask = mutation({
  args: {
    taskId: v.id("tasks"),
    title: v.string(),
  },
  returns: v.null(),
  handler: async (ctx, args) => {
    const identity = await requireAuth(ctx);
    
    const task = await ctx.db.get(args.taskId);
    
    // Check ownership
    if (!task || task.userId !== identity.tokenIdentifier) {
      throw new ConvexError("Not authorized to update this task");
    }
    
    await ctx.db.patch(args.taskId, { title: args.title });
    return null;
  },
});

// Verify ownership before delete
export const deleteTask = mutation({
  args: { taskId: v.id("tasks") },
  returns: v.null(),
  handler: async (ctx, args) => {
    const identity = await requireAuth(ctx);
    
    const task = await ctx.db.get(args.taskId);
    
    if (!task || task.userId !== identity.tokenIdentifier) {
      throw new ConvexError("Not authorized to delete this task");
    }
    
    await ctx.db.delete(args.taskId);
    return null;
  },
});

typescript

// 更新前验证所有权
export const updateTask = mutation({
  args: {
    taskId: v.id("tasks"),
    title: v.string(),
  },
  returns: v.null(),
  handler: async (ctx, args) => {
    const identity = await requireAuth(ctx);
    
    const task = await ctx.db.get(args.taskId);
    
    // 检查所有权
    if (!task || task.userId !== identity.tokenIdentifier) {
      throw new ConvexError("无权限更新此任务");
    }
    
    await ctx.db.patch(args.taskId, { title: args.title });
    return null;
  },
});

// 删除前验证所有权
export const deleteTask = mutation({
  args: { taskId: v.id("tasks") },
  returns: v.null(),
  handler: async (ctx, args) => {
    const identity = await requireAuth(ctx);
    
    const task = await ctx.db.get(args.taskId);
    
    if (!task || task.userId !== identity.tokenIdentifier) {
      throw new ConvexError("无权限删除此任务");
    }
    
    await ctx.db.delete(args.taskId);
    return null;
  },
});

Environment Variables Check

环境变量检查

typescript

// convex/actions.ts
"use node";

import { action } from "./_generated/server";
import { v } from "convex/values";

export const sendEmail = action({
  args: {
    to: v.string(),
    subject: v.string(),
    body: v.string(),
  },
  returns: v.object({ success: v.boolean() }),
  handler: async (ctx, args) => {
    // Access API key from environment
    const apiKey = process.env.RESEND_API_KEY;
    
    if (!apiKey) {
      throw new Error("RESEND_API_KEY not configured");
    }
    
    const response = await fetch("https://api.resend.com/emails", {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${apiKey}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        from: "noreply@example.com",
        to: args.to,
        subject: args.subject,
        html: args.body,
      }),
    });
    
    return { success: response.ok };
  },
});

typescript

// convex/actions.ts
"use node";

import { action } from "./_generated/server";
import { v } from "convex/values";

export const sendEmail = action({
  args: {
    to: v.string(),
    subject: v.string(),
    body: v.string(),
  },
  returns: v.object({ success: v.boolean() }),
  handler: async (ctx, args) => {
    // 从环境变量获取 API 密钥
    const apiKey = process.env.RESEND_API_KEY;
    
    if (!apiKey) {
      throw new Error("未配置 RESEND_API_KEY");
    }
    
    const response = await fetch("https://api.resend.com/emails", {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${apiKey}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        from: "noreply@example.com",
        to: args.to,
        subject: args.subject,
        html: args.body,
      }),
    });
    
    return { success: response.ok };
  },
});

Examples

示例

Complete Security Pattern

完整安全模式

typescript

// convex/secure.ts
import { query, mutation, internalMutation } from "./_generated/server";
import { v } from "convex/values";
import { ConvexError } from "convex/values";

// Authentication helper
async function getAuthenticatedUser(ctx: QueryCtx | MutationCtx) {
  const identity = await ctx.auth.getUserIdentity();
  if (!identity) {
    throw new ConvexError({
      code: "UNAUTHENTICATED",
      message: "You must be logged in",
    });
  }
  
  const user = await ctx.db
    .query("users")
    .withIndex("by_tokenIdentifier", (q) => 
      q.eq("tokenIdentifier", identity.tokenIdentifier)
    )
    .unique();
    
  if (!user) {
    throw new ConvexError({
      code: "USER_NOT_FOUND",
      message: "User profile not found",
    });
  }
  
  return user;
}

// Check admin role
async function requireAdmin(ctx: QueryCtx | MutationCtx) {
  const user = await getAuthenticatedUser(ctx);
  
  if (user.role !== "admin") {
    throw new ConvexError({
      code: "FORBIDDEN",
      message: "Admin access required",
    });
  }
  
  return user;
}

// Public: List own tasks
export const listMyTasks = query({
  args: {},
  returns: v.array(v.object({
    _id: v.id("tasks"),
    title: v.string(),
    completed: v.boolean(),
  })),
  handler: async (ctx) => {
    const user = await getAuthenticatedUser(ctx);
    
    return await ctx.db
      .query("tasks")
      .withIndex("by_user", (q) => q.eq("userId", user._id))
      .collect();
  },
});

// Admin only: List all users
export const listAllUsers = query({
  args: {},
  returns: v.array(v.object({
    _id: v.id("users"),
    name: v.string(),
    role: v.string(),
  })),
  handler: async (ctx) => {
    await requireAdmin(ctx);
    
    return await ctx.db.query("users").collect();
  },
});

// Internal: Update user role (never exposed)
export const _setUserRole = internalMutation({
  args: {
    userId: v.id("users"),
    role: v.union(v.literal("user"), v.literal("admin")),
  },
  returns: v.null(),
  handler: async (ctx, args) => {
    await ctx.db.patch(args.userId, { role: args.role });
    return null;
  },
});

typescript

// convex/secure.ts
import { query, mutation, internalMutation } from "./_generated/server";
import { v } from "convex/values";
import { ConvexError } from "convex/values";

// 身份验证辅助函数
async function getAuthenticatedUser(ctx: QueryCtx | MutationCtx) {
  const identity = await ctx.auth.getUserIdentity();
  if (!identity) {
    throw new ConvexError({
      code: "UNAUTHENTICATED",
      message: "你必须登录",
    });
  }
  
  const user = await ctx.db
    .query("users")
    .withIndex("by_tokenIdentifier", (q) => 
      q.eq("tokenIdentifier", identity.tokenIdentifier)
    )
    .unique();
    
  if (!user) {
    throw new ConvexError({
      code: "USER_NOT_FOUND",
      message: "未找到用户资料",
    });
  }
  
  return user;
}

// 检查管理员角色
async function requireAdmin(ctx: QueryCtx | MutationCtx) {
  const user = await getAuthenticatedUser(ctx);
  
  if (user.role !== "admin") {
    throw new ConvexError({
      code: "FORBIDDEN",
      message: "需要管理员权限",
    });
  }
  
  return user;
}

// 公开函数：列出自身任务
export const listMyTasks = query({
  args: {},
  returns: v.array(v.object({
    _id: v.id("tasks"),
    title: v.string(),
    completed: v.boolean(),
  })),
  handler: async (ctx) => {
    const user = await getAuthenticatedUser(ctx);
    
    return await ctx.db
      .query("tasks")
      .withIndex("by_user", (q) => q.eq("userId", user._id))
      .collect();
  },
});

// 仅管理员可用：列出所有用户
export const listAllUsers = query({
  args: {},
  returns: v.array(v.object({
    _id: v.id("users"),
    name: v.string(),
    role: v.string(),
  })),
  handler: async (ctx) => {
    await requireAdmin(ctx);
    
    return await ctx.db.query("users").collect();
  },
});

// 内部函数：更新用户角色（绝不对外暴露）
export const _setUserRole = internalMutation({
  args: {
    userId: v.id("users"),
    role: v.union(v.literal("user"), v.literal("admin")),
  },
  returns: v.null(),
  handler: async (ctx, args) => {
    await ctx.db.patch(args.userId, { role: args.role });
    return null;
  },
});

Best Practices

最佳实践

Never run
```
npx convex deploy
```
unless explicitly instructed
Never run any git commands unless explicitly instructed
Always verify user identity before returning sensitive data
Use internal functions for sensitive operations
Validate all arguments with strict validators
Check ownership before update/delete operations
Store API keys in environment variables
Review all public functions for security implications

除非明确指示，否则请勿运行
```
npx convex deploy
```
除非明确指示，否则请勿运行任何 git 命令
返回敏感数据前始终验证用户身份
敏感操作使用内部函数
使用严格验证器验证所有参数
更新/删除操作前检查资源所有权
API 密钥存储在环境变量中
审核所有公开函数的安全影响

Common Pitfalls

常见陷阱

Missing authentication checks - Always verify identity
Exposing internal operations - Use internalMutation/Query
Trusting client-provided IDs - Verify ownership
Using v.any() for arguments - Use specific validators
Hardcoding secrets - Use environment variables

缺失身份验证检查 - 始终验证用户身份
暴露内部操作 - 使用 internalMutation/Query
信任客户端提供的ID - 验证资源所有权
参数使用 v.any() - 使用特定验证器
硬编码密钥 - 使用环境变量

References

参考资料

Convex Documentation: https://docs.convex.dev/
Convex LLMs.txt: https://docs.convex.dev/llms.txt
Authentication: https://docs.convex.dev/auth
Production Security: https://docs.convex.dev/production
Functions Auth: https://docs.convex.dev/auth/functions-auth

Convex 官方文档：https://docs.convex.dev/
Convex LLMs.txt：https://docs.convex.dev/llms.txt
身份验证：https://docs.convex.dev/auth
生产环境安全：https://docs.convex.dev/production
函数身份验证：https://docs.convex.dev/auth/functions-auth