backend-mongodb ยท v6.0.0 ยท 2026-10-24 ยท sha256 2978e737200b41c5
backend-mongodb v6.0.0A
Immutable. This exact content never changes and is served at /api/v1/blob/2978e737200b41c5.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_2apwzz5epachvwyo/2978e737200b41c538dc177b8dacab9125d7d35aaea2201b5da2b6c9e375bb57.json
Then /plugin install backend-mongodb@markdownregistry-2apwzz5epachvwyo in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
---
name: backend-mongodb
description: "Use when analyzing, querying, designing, and hardening MongoDB schemas, indexes, and aggregation pipelines. Covers compound indexes, NoSQL injection prevention, schema validation, transaction boundaries, and projection safety."
version: 6.0.0
last-updated: 2026-09-29
skills:
- database-design
- backend-security-expert
- data-validation-schemas
tools: Read, Grep, Glob, Bash, Edit, Write
scripts-binding:
- .agent/scripts/lint_runner.js
- .agent/scripts/verify_all.js
inputs:
task: "string"
target_file: "string"
outputs:
result: "string"
verification_status: "boolean"
trigger:
- "backend"
- "mongodb"
- "analyzing"
---
# MongoDB Architecture & Security Mastery
## ๐ Multi-Pass Execution Protocol
| Pass | Phase | Core Action | Adaptive Depth |
|:---|:---|:---|:---|
| **Pass 1** | **Understand** | Deconstruct the user's explicit objective, implicit requirements, and platform constraints. | Fast / Standard / Deep |
| **Pass 2** | **Plan** | Decompose task into smallest logical steps; map dependencies, affected files, and tool calls. | Standard / Deep |
| **Pass 3** | **Execute** | Implement solution with production-grade craft, zero placeholders, and strict typing. | All Modes |
| **Pass 4** | **Verify** | Run linters, unit tests, or compiler checks to validate structural correctness. | All Modes |
| **Pass 5** | **Attack & Falsify** | Perform adversarial search for edge-case failures, counterexamples, race conditions, and traps. | Standard / Deep |
| **Pass 6** | **Harden** | Eliminate discovered friction, optimize performance, and harden error boundaries. | Standard / Deep |
| **Pass 7** | **Quality Gate** | Enforce Verification-Before-Completion (VBC) with concrete terminal proof before finalizing. | All Modes |
## Mandatory Pre-Flight Context Inspection
1. **Driver & Server Version**: Verify Mongoose or native MongoDB driver version (v5 vs v6+) and connection URI options.
2. **Schema Models**: Inspect Mongoose schema definitions or collection validation rules (`validator: { $jsonSchema: ... }`).
3. **Compound Index Prefixing**: Verify that queries match the equality, sort, range (ESR) rule on compound indexes.
4. **Input Sanitization**: Inspect how incoming request parameters reach collection queries; block operator injection.
5. **Memory Limits in Aggregations**: Ensure pipelines contain `$limit` before sorting or heavy projection stages.
## Activation Boundaries
- **Activate when:** Writing MongoDB queries, building aggregation pipelines, defining Mongoose schemas, or hardening against NoSQL injection.
- **DO NOT activate when:** The project uses relational databases (PostgreSQL, MySQL) or client-side caching.
## ๐ ๏ธ Technical Architecture & Reference Recipes
### 1. NoSQL Injection Prevention
```typescript
// โ VULNERABLE: Direct object pass allows { "$gt": "" } bypassing auth
app.post('/api/login', async (req, res) => {
const { username, password } = req.body;
const user = await db.collection('users').findOne({ username, password });
if (user) generateSession(res, user);
});
// โ
SECURE: Strict schema parsing (Zod) + casting to string primitive
import { z } from 'zod';
const LoginSchema = z.object({
username: z.string().min(3).max(50),
password: z.string().min(8)
});
app.post('/api/login', async (req, res) => {
const parsed = LoginSchema.safeParse(req.body);
if (!parsed.success) return res.status(400).json({ error: 'Invalid payload' });
const { username, password } = parsed.data;
const user = await db.collection('users').findOne({
username: String(username),
passwordHash: await hashPassword(String(password))
});
if (!user) return res.status(401).json({ error: 'Unauthorized' });
generateSession(res, user);
});
```
### 2. ESR Index Optimization (Equality, Sort, Range)
```javascript
// Query pattern: Find active orders for user, sorted by date, with amount > 100
// db.orders.find({ userId: uid, status: 'ACTIVE', total: { $gt: 100 } }).sort({ createdAt: -1 })
// โ
ESR Index order:
// 1. Equality: userId, status
// 2. Sort: createdAt
// 3. Range: total
db.orders.createIndex(
{ userId: 1, status: 1, createdAt: -1, total: 1 },
{ name: 'idx_orders_esr', background: true }
);
```
### 3. Safe Multi-Document Transactions
```typescript
const session = client.startSession();
try {
await session.withTransaction(async () => {
await orders.updateOne(
{ _id: orderId, status: 'PENDING' },
{ $set: { status: 'PAID', paidAt: new Date() } },
{ session }
);
await inventory.updateOne(
{ sku: itemSku, stock: { $gte: quantity } },
{ $inc: { stock: -quantity } },
{ session }
);
}, {
readPreference: 'primary',
readConcern: { level: 'local' },
writeConcern: { w: 'majority' }
});
} finally {
await session.endSession();
}
```
## ๐จ Edge-Case & Failure Mode Matrix
| Scenario | Risk | Production Mitigation |
|:---|:---|:---|
| **Unbounded Projection** | Documents with massive arrays or base64 files exhaust Node.js heap memory | Always pass explicit projection `{ projection: { bio: 1, avatarUrl: 1, _id: 1 } }` |
| **Pipeline Memory Exceeded** | Sorting >100MB in memory without index crashes with `13848 ExceededMemoryLimit` | Place `$match` and `$limit` early; index the sort field; enable `allowDiskUse: true` only when necessary |
| **Unchecked Write Concern** | Primary writes return before replica acknowledgment, risking data loss on failover | Always use `writeConcern: { w: 'majority', j: true }` for critical state changes |
## ๐ค LLM-Specific Traps Table
| Anti-Pattern | What AI Commonly Does Wrong | What Is Actually Correct |
|:---|:---|:---|
| **Blind `$where` Evaluation** | Using `$where: "this.a == this.b"` | Avoid `$where` completely; it executes arbitrary JS, introduces injection, and bypasses indexes |
| **Missing `$limit` on Collections** | Calling `.find({}).toArray()` | Always attach bounded `.limit(PAGE_SIZE)` to prevent OOM on production scale |
| **Nested Array Unchecked Growth** | Appending logs into a single document without boundary | Cap arrays using `$slice` or create a separate time-series / event collection |
## ๐๏ธ Tribunal Verification & Guardrails
- **Active Reviewers:** `database-architect`, `security-auditor`, `schema-reviewer`
- **Evidence Standard:** Categorize each finding as `[OBSERVED]` (concrete query/schema in repo), `[INFERRED]` (index utilization hypothesis), or `[UNVERIFIED]`.