Convex Security Check

Convex アプリケーションのセキュリティを監査するためのクイックチェックリストです。認証、関数公開、引数検証、行レベルアクセス制御、環境変数処理を網羅しています。

ドキュメントソース

実装前に、推測ではなく最新ドキュメントを確認してください:

• Primary: https://docs.convex.dev/auth
• Production Security: https://docs.convex.dev/production
• Functions Auth: https://docs.convex.dev/auth/functions-auth
• より広い文脈: https://docs.convex.dev/llms.txt

使用方法

セキュリティチェックリスト

このチェックリストを使用して、Convex アプリケーションのセキュリティを素早く監査してください:

1. 認証

• 認証プロバイダが設定されている (Clerk、Auth0 など)
• すべての機密クエリが ctx.auth.getUserIdentity() を確認している
• 認証なしのアクセスが意図的に許可されている場所が明記されている
• セッショントークンが適切に検証されている

2. 関数公開

• パブリック関数 (query、mutation、action) をレビューした
• 内部関数は internalQuery、internalMutation、internalAction を使用している
• 機密操作がパブリック関数として公開されていない
• HTTP アクションがオリジン/認証を検証している

3. 引数検証

• すべての関数に明示的な args バリデータがある
• すべての関数に明示的な returns バリデータがある
• 機密データに v.any() が使用されていない
• ID バリデータが正しいテーブル名を使用している

4. 行レベルアクセス制御

• ユーザーは自身のデータのみアクセスできる
• 管理者関数がユーザーロールを確認している
• 共有リソースに適切なアクセスチェックがある
• 削除関数が所有権を検証している

5. 環境変数

• API キーが環境変数に保存されている
• コードやスキーマにシークレットがない
• 開発環境/本番環境で異なるキーを使用している
• 環境変数は action でのみアクセスされている

認証チェック

// 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();
  },
});

関数公開チェック

// 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;
  },
});

引数検証チェック

// 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);
  },
});

行レベルアクセス制御チェック

// 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;
  },
});

環境変数チェック

// 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 };
  },
});

例

完全なセキュリティパターン

// 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;
  },
});

ベストプラクティス

• 明示的に指示されない限り、npx convex deploy を実行しないこと
• 明示的に指示されない限り、git コマンドを実行しないこと
• 機密データを返す前に常にユーザーアイデンティティを検証すること
• 機密操作には内部関数を使用すること
• すべての引数を厳密なバリデータで検証すること
• 更新/削除操作の前に所有権を確認すること
• API キーを環境変数に保存すること
• すべてのパブリック関数をセキュリティの観点からレビューすること

よくある落とし穴

1. 認証チェックの欠落 - 常にアイデンティティを検証する
2. 内部操作の公開 - internalMutation/Query を使用する
3. クライアント提供の ID を信頼する - 所有権を検証する
4. 引数に v.any() を使用する - 具体的なバリデータを使用する
5. シークレットをハードコードする - 環境変数を使用する

リファレンス

• 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