Security audit patterns for Convex applications covering authentication, authorization, input validation, and Convex-specific vulnerabilities.

The #1 Vibecoding Mistake: Unauthenticated Functions

Convex functions are public by default. Every query and mutation is callable from any client unless you add auth checks.

// ❌ CRITICAL: Anyone can read all users export const listUsers = query({ handler: async (ctx) => { return await ctx.db.query("users").collect(); }, });

// ❌ CRITICAL: Anyone can delete any document export const deleteNote = mutation({ args: { noteId: v.id("notes") }, handler: async (ctx, args) => { await ctx.db.delete(args.noteId); }, });

// ✓ SECURE: Check auth first export const listUsers = query({ handler: async (ctx) => { const userId = await getAuthUserId(ctx); if (!userId) throw new Error("Unauthenticated"); // Now safe to return data return await ctx.db.query("users").collect(); }, });

Authentication Checks

Using Convex Auth

import { getAuthUserId } from "@convex-dev/auth/server";

// ❌ No auth check export const getMyProfile = query({ handler: async (ctx) => { // Who is "my"? Anyone can call this! return await ctx.db.query("users").first(); }, });

// ✓ Get authenticated user export const getMyProfile = query({ handler: async (ctx) => { const userId = await getAuthUserId(ctx); if (!userId) throw new Error("Unauthenticated"); return await ctx.db.get(userId); }, });

Using Third-Party Auth (Clerk, Auth0)

// ❌ Just checking ctx.auth exists (wrong!) export const sensitiveData = query({ handler: async (ctx) => { const identity = await ctx.auth.getUserIdentity(); // identity could be null! return await ctx.db.query("secrets").collect(); }, });

// ✓ Properly validate identity export const sensitiveData = query({ handler: async (ctx) => { const identity = await ctx.auth.getUserIdentity(); if (!identity) throw new Error("Unauthenticated"); // Now identity.tokenIdentifier is available return await ctx.db.query("secrets") .filter(q => q.eq(q.field("userId"), identity.subject)) .collect(); }, });

Authorization: The IDOR Problem

Authentication (who you are) ≠ Authorization (what you can access).

// ❌ HIGH: IDOR - Any logged-in user can read any note export const getNote = query({ args: { noteId: v.id("notes") }, handler: async (ctx, args) => { const userId = await getAuthUserId(ctx); if (!userId) throw new Error("Unauthenticated"); // Authenticated but no ownership check! return await ctx.db.get(args.noteId); }, });

// ✓ Check ownership export const getNote = query({ args: { noteId: v.id("notes") }, handler: async (ctx, args) => { const userId = await getAuthUserId(ctx); if (!userId) throw new Error("Unauthenticated");

const note = await ctx.db.get(args.noteId);
if (!note || note.userId !== userId) {
  throw new Error("Not found"); // Don't reveal existence
}
return note;

}, });

Team/Org Membership Checks

// ❌ Trusts client-provided teamId export const getTeamData = query({ args: { teamId: v.id("teams") }, handler: async (ctx, args) => { const userId = await getAuthUserId(ctx); if (!userId) throw new Error("Unauthenticated"); // User says they're on this team - but are they? return await ctx.db.query("projects") .filter(q => q.eq(q.field("teamId"), args.teamId)) .collect(); }, });

// ✓ Verify membership export const getTeamData = query({ args: { teamId: v.id("teams") }, handler: async (ctx, args) => { const userId = await getAuthUserId(ctx); if (!userId) throw new Error("Unauthenticated");

const membership = await ctx.db.query("teamMembers")
  .withIndex("by_team_user", q => 
    q.eq("teamId", args.teamId).eq("userId", userId)
  ).first();

if (!membership) throw new Error("Not a team member");

return await ctx.db.query("projects")
  .filter(q => q.eq(q.field("teamId"), args.teamId))
  .collect();

}, });

Custom Functions Pattern (Recommended)

Use convex-helpers to enforce auth by default:

// convex/functions.ts import { customQuery, customMutation } from "convex-helpers/server/customFunctions"; import { getAuthUserId } from "@convex-dev/auth/server";

// All userQuery functions require authentication export const userQuery = customQuery(query, { args: {}, input: async (ctx) => { const userId = await getAuthUserId(ctx); if (!userId) throw new Error("Unauthenticated"); const user = await ctx.db.get(userId); if (!user) throw new Error("User not found"); return { ctx: { user }, args: {} }; }, });

// Usage - ctx.user is guaranteed to exist export const getMyNotes = userQuery({ handler: async (ctx) => { return await ctx.db.query("notes") .filter(q => q.eq(q.field("userId"), ctx.user._id)) .collect(); }, });

Audit: Check if custom functions are used consistently. Search for raw query( and mutation( usage.

Input Validation

Missing Validators

// ❌ No validation - args is 'any' export const createNote = mutation({ handler: async (ctx, args) => { await ctx.db.insert("notes", args); // Could insert anything! }, });

// ✓ Strict validators export const createNote = mutation({ args: { title: v.string(), content: v.string(), isPublic: v.optional(v.boolean()), }, handler: async (ctx, args) => { const userId = await getAuthUserId(ctx); if (!userId) throw new Error("Unauthenticated"); await ctx.db.insert("notes", { ...args, userId, // Server sets this, not client }); }, });

Trusting Client-Provided IDs for Ownership

// ❌ Client provides userId - can impersonate anyone export const createNote = mutation({ args: { title: v.string(), userId: v.id("users"), // Client-controlled! }, handler: async (ctx, args) => { await ctx.db.insert("notes", args); }, });

// ✓ Server determines userId export const createNote = mutation({ args: { title: v.string() }, handler: async (ctx, args) => { const userId = await getAuthUserId(ctx); if (!userId) throw new Error("Unauthenticated"); await ctx.db.insert("notes", { title: args.title, userId, // From auth, not args }); }, });

Internal Functions

// ❌ Sensitive logic in public mutation export const processPayment = mutation({ args: { amount: v.number() }, handler: async (ctx, args) => { // Anyone can call this! await chargeCard(args.amount); }, });

// ✓ Use internalMutation for sensitive operations export const processPayment = internalMutation({ args: { userId: v.id("users"), amount: v.number() }, handler: async (ctx, args) => { // Only callable from other server functions await chargeCard(args.amount); }, });

// Public function validates then calls internal export const purchaseItem = mutation({ args: { itemId: v.id("items") }, handler: async (ctx, args) => { const userId = await getAuthUserId(ctx); if (!userId) throw new Error("Unauthenticated");

const item = await ctx.db.get(args.itemId);
// Validate, then call internal
await ctx.runMutation(internal.payments.processPayment, {
  userId,
  amount: item.price,
});

}, });

HTTP Actions

// ❌ No auth on HTTP endpoint export const webhook = httpAction(async (ctx, request) => { const body = await request.json(); await ctx.runMutation(api.data.processWebhook, body); return new Response("OK"); });

// ✓ Verify webhook signature export const webhook = httpAction(async (ctx, request) => { const signature = request.headers.get("x-webhook-signature"); const body = await request.text();

if (!verifySignature(body, signature, process.env.WEBHOOK_SECRET)) { return new Response("Unauthorized", { status: 401 }); }

await ctx.runMutation(api.data.processWebhook, JSON.parse(body)); return new Response("OK"); });

Real-Time Subscription Leakage

// ❌ Subscription returns all messages (data leak) export const allMessages = query({ handler: async (ctx) => { return await ctx.db.query("messages").collect(); }, });

// ✓ Filter by user's access export const myMessages = query({ handler: async (ctx) => { const userId = await getAuthUserId(ctx); if (!userId) return []; // Or throw

// Only messages user has access to
const myChannels = await ctx.db.query("channelMembers")
  .filter(q => q.eq(q.field("userId"), userId))
  .collect();

const channelIds = myChannels.map(m => m.channelId);
return await ctx.db.query("messages")
  .filter(q => q.or(...channelIds.map(id => 
    q.eq(q.field("channelId"), id)
  )))
  .collect();

}, });

Environment Variables

// ❌ Accessing env vars that don't exist (undefined behavior) const apiKey = process.env.STRIPE_SECRET_KEY;

// ✓ Use Convex environment variables properly // Set via: npx convex env set STRIPE_SECRET_KEY sk_live_... // Access in actions only (not queries/mutations for determinism) export const callStripe = action({ handler: async (ctx) => { const apiKey = process.env.STRIPE_SECRET_KEY; if (!apiKey) throw new Error("STRIPE_SECRET_KEY not configured"); // ... }, });

Note: Environment variables are only available in actions, not queries/mutations.

<severity_table>

Common Vulnerabilities Summary

Issue Where to Look Severity

No auth check in query/mutation All query({ and mutation({

CRITICAL

IDOR (no ownership check) Functions with document IDs in args HIGH

Client-provided userId Args with v.id("users")

HIGH

Missing validators Functions without args: {}

HIGH

Public function for internal logic Sensitive business logic HIGH

HTTP action without auth httpAction(

HIGH

Subscription data leak Queries returning collections MEDIUM

Raw query/mutation (no custom fn) Not using userQuery/userMutation MEDIUM

</severity_table>

Quick Audit Commands

Find all public queries and mutations

rg "export const .* = query(" convex/ rg "export const .* = mutation(" convex/

Find functions without auth checks

rg -l "export const .* = (query|mutation)(" convex/ |
xargs rg -L "(getAuthUserId|getUserIdentity)"

Find client-provided userId (potential IDOR)

rg 'userId: v.id("users")' convex/

Find functions without validators

rg "handler: async (ctx)" convex/ -g "*.ts"

Find HTTP actions

rg "httpAction" convex/

Find internal vs public function usage

rg "internalMutation|internalQuery|internalAction" convex/

Hardening Checklist

• All queries/mutations have auth checks (or use custom functions)

• Document access includes ownership/membership verification

• userId comes from auth context, not client args

• All functions have proper validators

• Sensitive operations use internalMutation/internalAction

• HTTP actions verify signatures/tokens

• Real-time subscriptions filter by user access

• Custom functions (userQuery/userMutation) used consistently

• ESLint rules prevent importing raw query/mutation