security-critical

CRITICAL SECURITY PATTERNS

These are the three most critical security patterns that MUST be followed in every Payload CMS project.

1. Local API Access Control (MOST IMPORTANT)

By default, Local API operations bypass ALL access control, even when passing a user.

// ❌ SECURITY BUG: Passes user but ignores their permissions
await payload.find({
  collection: 'posts',
  user: someUser, // Access control is BYPASSED!
})

// ✅ SECURE: Actually enforces the user's permissions
await payload.find({
  collection: 'posts',
  user: someUser,
  overrideAccess: false, // REQUIRED for access control
})

// ✅ Administrative operation (intentional bypass)
await payload.find({
  collection: 'posts',
  // No user, overrideAccess defaults to true
})

When to use each:

• overrideAccess: true (default) - Server-side operations you trust (cron jobs, system tasks)
• overrideAccess: false - When operating on behalf of a user (API routes, webhooks)

Rule: When passing user to Local API, ALWAYS set overrideAccess: false

2. Transaction Safety in Hooks

Nested operations in hooks without req break transaction atomicity.

// ❌ DATA CORRUPTION RISK: Separate transaction
hooks: {
  afterChange: [
    async ({ doc, req }) => {
      await req.payload.create({
        collection: 'audit-log',
        data: { docId: doc.id },
        // Missing req - runs in separate transaction!
      })
    },
  ]
}

// ✅ ATOMIC: Same transaction
hooks: {
  afterChange: [
    async ({ doc, req }) => {
      await req.payload.create({
        collection: 'audit-log',
        data: { docId: doc.id },
        req, // Maintains atomicity
      })
    },
  ]
}

Why This Matters:

• MongoDB (with replica sets): Creates atomic session across operations
• PostgreSQL: All operations use same Drizzle transaction
• SQLite (with transactions enabled): Ensures rollback on errors
• Without req: Each operation runs independently, breaking atomicity