tribunal-kit 9.0.0 → 9.0.1

package/.agents/skills/api-security-auditor/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: api-security-auditor
+description: Use when API Security auditing mastery. Rate limiting architecture, API key management, payload validation, IDOR (Insecure Direct Object Reference) prevention, mass assignment flaws, GraphQL security, and server-side mitigations. Use when building external APIs, B2B services, or reviewing endpoint security.
+version: 5.0.0
+last-updated: 2026-09-13
+skills:
+  - backend-security-expert
+  - vulnerability-scanner
+  - schema-reviewer
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/lint_runner.js
+  - .agent/scripts/verify_all.js
+---
+
+# API Security Auditor — Endpoint Hardening Mastery
+
+## Mandatory Pre-Flight Context Inspection
+
+Before generating, refactoring, or reviewing code in the `api-security-auditor` domain, inspect these 5 critical parameters:
+
+1. **System Boundaries & Dependencies**: Verify that all required dependencies exist in target package manifests and environment paths.
+2. **Runtime Context & Platform Invariants**: Confirm target platform constraints (Node.js, Browser, Mobile OS, Edge runtime) before applying APIs.
+3. **Execution Guardrails**: Identify potential side-effects, state mutations, and unhandled asynchronous exceptions.
+4. **Validation & Type Contracts**: Validate input data schemas and strict type constraints across all module interfaces.
+5. **Observability & Proof of Execution**: Ensure execution produces tangible verification signals (terminal output, tests, metrics).
+
+## Activation Boundaries
+
+- **Activate when:** Use when API Security auditing mastery. Rate limiting architecture, API key management, payload validation, IDOR (Insecure Direct Object Reference) prevention, mass assignment flaws, GraphQL security, and server-side mitigations. Use when building external APIs, B2B services, or reviewing endpoint security.
+- **DO NOT activate when:** The task falls outside the `api-security-auditor` domain or is managed by a different dedicated specialist.
+
+## 🔁 Multi-Pass Execution Protocol
+
+Execute all non-trivial tasks through this 7-pass cognitive loop:
+
+| Pass | Phase | Core Action |
+|:---|:---|:---|
+| **Pass 1** | **Understand** | Deconstruct the user's explicit objective, implicit requirements, and platform constraints. |
+| **Pass 2** | **Plan** | Decompose the task into smallest logical steps; map dependencies and required tool calls. |
+| **Pass 3** | **Execute** | Implement the solution with production-grade craft, zero placeholders, and strict typing. |
+| **Pass 4** | **Verify** | Run linters, unit tests, or compiler checks to validate structural correctness. |
+| **Pass 5** | **Attack** | Perform an adversarial review searching for edge-case failures, race conditions, and traps. |
+| **Pass 6** | **Improve** | Eliminate discovered friction, optimize performance, and harden error boundaries. |
+| **Pass 7** | **Quality Gate** | Enforce Verification-Before-Completion (VBC) with concrete terminal proof before finalizing. |
+
+---
+
+## 🛠️ Technical Architecture & Reference Recipes
+
+---
+
+
+---
+
+## Insecure Direct Object Reference (IDOR)
+
+IDOR occurs when an application provides direct access to objects based on user-supplied input without authorization checks.
+
+```typescript
+// ❌ VULNERABLE: Trusting the requested ID blindly
+app.get('/api/receipts/:id', async (req, res) => {
+  const receipt = await db.receipts.findById(req.params.id);
+  res.json(receipt); // Attack: Increment ID to view others' receipts
+});
+
+// ✅ SAFE: Verifying ownership
+app.get('/api/receipts/:id', async (req, res) => {
+  const receipt = await db.receipts.findById(req.params.id);
+  if (!receipt) return res.status(404).send();
+
+  // Explicit tenancy check
+  if (receipt.userId !== req.user.id && req.user.role !== 'admin') {
+    return res.status(403).json({ error: 'Access denied' });
+  }
+
+  res.json(receipt);
+});
+
+// ✅ BEST: Using UUIDv4/CUID/NanoID instead of sequential integers
+// Attackers cannot guess standard UUIDs, heavily mitigating IDOR risks.
+```
+
+---
+
+## Mass Assignment (Overposting)
+
+Occurs when web frameworks automatically bind HTTP request parameters to application models without filtering.
+
+```typescript
+// ❌ VULNERABLE: Direct object binding
+app.put('/api/users/:id', async (req, res) => {
+  // Attack: req.body = { name: "Bob", role: "admin", isPaid: true }
+  await db.users.update({ id: req.params.id }, req.body);
+  res.send('Updated');
+});
+
+// ✅ SAFE: Explicit property selection (DTOs)
+app.put('/api/users/:id', async (req, res) => {
+  // Only extract explicitly allowed fields
+  const { name, email, bio } = req.body;
+  const safeData = { name, email, bio };
+
+  await db.users.update({ id: req.params.id }, safeData);
+  res.send('Updated');
+});
+
+// ✅ BEST: Validation libraries (Zod, Joi) handling stripping
+const UpdateUserSchema = z
+  .object({
+    name: z.string().min(2),
+    email: z.string().email(),
+  })
+  .strict(); // `.strict()` throws if "role" or "isPaid" is passed
+```
+
+---
+
+## Rate Limiting Architecture
+
+```typescript
+// Basic Rate Limiting (Express)
+import rateLimit from 'express-rate-limit';
+import RedisStore from 'rate-limit-redis';
+
+// Global baseline limit
+export const globalLimiter = rateLimit({
+  store: new RedisStore({ client: redisClient }),
+  windowMs: 15 * 60 * 1000, // 15 min
+  max: 100, // Limit each IP to 100 reqs per window
+  standardHeaders: true, // Return rate limit info in the `RateLimit-*` headers
+});
+
+// Aggressive endpoint-specific limit (Login, Password Reset)
+export const authLimiter = rateLimit({
+  store: new RedisStore({ client: redisClient }),
+  windowMs: 60 * 60 * 1000, // 1 Hour
+  max: 5, // 5 login attempts per IP per hour
+  message: 'Too many login attempts, please try again later',
+});
+
+// ❌ HALLUCINATION TRAP: In-memory rate limiting across multiple server pods
+// If you use basic memory stores in a load-balanced environment (K8s, ECS),
+// an attacker has `limit * num_pods` attempts. Always use a centralized store (Redis).
+```
+
+---
+
+## API Key Management
+
+```
+Best Practices for issuance and storage:
+1. Format: Prefix keys to identify them and allow secret scanners to find them easily.
+   - Example: `pk_live_8a9b...` (Stripe pattern).
+2. Storage: NEVER store plaintext API keys in the DB.
+   - Hash them using SHA-256 (not bcrypt, because API keys are high entropy/long).
+   - Only show the user the plaintext key ONCE upon creation.
+3. Transport: API keys must only be accepted via Headers, never in Query Params.
+   - `Authorization: Bearer pk_live_123`
+   - Query params are logged in server access logs and browser histories.
+```
+
+---
+
+## GraphQL Security Vectors
+
+```typescript
+// GraphQL introduces unique DoS vectors not found in REST
+
+// 1. Query Depth Limiting (Prevent nested joins crushing the DB)
+// User -> Posts -> Comments -> Author -> Posts -> Comments...
+import depthLimit from 'graphql-depth-limit';
+app.use('/graphql', graphqlHTTP({ validationRules: [depthLimit(5)] }));
+
+// 2. Query Cost Analysis
+// Prevent attackers from requesting 100,000 items in a single query
+// Implement cursor pagination and enforce `first: 100` limits.
+
+// 3. Introspection Disabled in Production
+// Introspection allows attackers to download your entire schema.
+const server = new ApolloServer({
+  schema,
+  introspection: process.env.NODE_ENV !== 'production',
+});
+```
+
+---
+
+## 🚨 Edge-Case & Failure Mode Matrix
+
+| Scenario | Risk | Mitigation Strategy |
+|:---|:---|:---|
+| **Empty or Null Inputs** | Unhandled exception or unexpected rendering collapse | Enforce fallback guards, optional chaining, and explicit empty state handlers |
+| **Network Timeout / Latency** | Hanging operations or duplicate side-effects | Implement bounded abort controllers, exponential backoff, and idempotency keys |
+| **Concurrency / Race Conditions** | Stale state overwrite or inconsistent data mutations | Use atomic transactions, mutex locking, or cancel-on-resubmit controls |
+| **Invalid Schema / Malformed Payload** | Downstream runtime errors or security injection | Validate boundary payloads with Zod/Pydantic schemas prior to execution |
+| **Resource / Memory Saturation** | OOM errors, frame drops, or memory leaks | Clean up listeners, cancel active timers, and enforce pagination/virtualization |
+
+---
+
+## 🤖 LLM-Specific Traps Table
+
+| Anti-Pattern | What AI Commonly Does Wrong | What Is Actually Correct |
+|:---|:---|:---|
+| **Unchecked Payload Cast** | Casting request bodies to TypeScript types without runtime schema validation | Parse request payloads through Zod/Pydantic schemas before business logic |
+| **Silent Error Swallowing** | Catching errors with empty catch blocks or logging without rethrowing | Propagate structured errors with status codes and contextual stack traces |
+| **Unparameterized Query** | Concatenating user inputs into SQL/Prisma query strings | Always use parameterized bindings or type-safe ORM query builders |
+
+---
+
+## 🏛️ Tribunal Verification & Guardrails
+
+**Active Reviewers:** `logic-reviewer` · `security-auditor` · `api-architect` · `resilience-reviewer`
+**Slash Command:** `/review` or `/tribunal-full`
+
+### ✅ Pre-Flight Self-Audit Checklist
+
+```
+✅ Are all inputs and boundary payloads validated against schemas (Zod/Pydantic)?
+✅ Are SQL and database queries parameterized with zero string concatenation?
+✅ Are error boundaries and timeout/retry policies explicitly declared?
+✅ Are authentication checks performed before business logic execution?
+✅ Did I verify that imported dependencies exist in package.json/requirements.txt?
+```
+
+### 🛑 Verification-Before-Completion (VBC) Protocol
+
+**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
+- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
+- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing test suites, compiler success, or equivalent operational proof) that your output works as intended.