---
name: app-security
description: >
  Full-stack application and API security hardening: Four-Pillar upload defense,
  SSRF prevention, input boundary clamping, IDOR elimination, and secret masking.
  Use when creating or auditing API routes, handling uploads, making outbound requests,
  or preparing pre-release security verification.
concerns: [security]
---

# Application Security Hardening

Enforces defensive boundaries across the API membrane, eliminating exploit vectors, path traversals, SSRF risks, IDOR vulnerabilities, and payload exhaustion.

```mermaid
flowchart LR
    A["Inbound Request"] --> B["1. Membrane Clamping<br/>(Schema & Bound Validation)"]
    B --> C["2. Four-Pillar Uploads<br/>(Size, Ext, Magic, Path)"]
    C --> D["3. Outbound SSRF Guard<br/>(Loopback/Metadata Block)"]
    D --> E["4. Secret Masking<br/>(Zero Token Sediment)"]
```

---

## Phase 0: Setup and Protocols

1. Review reference playbooks:
   - [references/app-hardening-playbook.md](references/app-hardening-playbook.md) for concrete TypeScript/Python code patterns and boundary clamps.
   - [references/review-checklist.md](references/review-checklist.md) for pre-release OWASP verification checks.
2. Invariants:
   - Every input payload must be typed and bounded.
   - Every state mutation must verify session identity and tenant ownership.
   - Outbound HTTP fetches must never touch private/loopback networks.

---

## Phase 1: Ingest and Check

1. **Surface Identification**:
   - Inbound API routes (REST, GraphQL, RPC handlers).
   - File/document ingestion and attachment endpoints.
   - Outbound network calls (webhooks, URL unfurlers, external data scrapers).
   - Data persistence operations and logging sinks.
2. **Access Control Check**:
   - Confirm identity is derived from verified server sessions/tokens, never trusted client parameters (`userId`, `orgId`).
   - Confirm entity queries enforce ownership: verify record exists AND belongs to the authenticated caller before mutating.

---

## Phase 2: Processing (Core Logic)

### Step 1: Input Boundaries & Membrane Clamping
- Never accept arbitrary, unvalidated request dictionaries. Model all payloads using strict schemas (e.g. Pydantic, Zod).
- Enforce hard string limits:
  - Text prompts / message content: Max 50,000 characters.
  - Titles / Names: Max 100–200 characters.
  - Pagination limits: Clamped to `1 <= limit <= 50`.
  - Batch arrays: Clamped to max 100–200 items.
- Sanitize entity and path identifiers against path traversal tokens (`../`, `..\\`).

### Step 2: Four-Pillar Upload Defense
When handling file or media uploads:
1. **Size Bounds**: Reject payloads exceeding size thresholds (e.g., 100MB for docs; 5MB for images).
2. **Blocked Extensions**: Reject executable and script formats (`.exe`, `.bat`, `.sh`, `.svg`, `.html`, `.php`).
3. **Magic Byte Inspection**: Inspect file headers to detect disguised binaries (PE `MZ`, ELF, Mach-O).
4. **Path Traversal Defense**:
   - Sanitize original filenames (strip path separators and non-printable characters).
   - Write files strictly to designated, isolated upload roots with unique IDs (e.g. UUID filenames).

### Step 3: Outbound SSRF Guard
Before executing outbound HTTP requests (scraping, webhooks):
- Validate target URLs against an allowlist or safety filter.
- Block loopback addresses (`127.0.0.1`, `localhost`, `::1`), RFC 1918 private subnets (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`), and cloud metadata services (`169.254.169.254`).
- Restrict allowed protocols strictly to `http` and `https`.

### Step 4: Secret Masking & Error Shielding
- Scrub Authorization tokens (`Bearer ***`), provider API keys, and sensitive credentials from logs, database traces, and telemetry.
- In public HTTP error responses, return clean structured error objects with opaque error codes; never leak internal filesystem paths, environment variables, or stack traces.

---

## Phase 3: The System One Balance Pass

- **Augment, Don't Handcuff**:
  - Do NOT break local development workflows: allow local mock endpoints and fixture testing in non-production test environments.
  - Keep security checks non-intrusive during prototyping; enforce strictly at boundaries and pre-release gates.
  - Avoid noisy confirmation warnings for routine safe operations.

---

## Phase 4: Output Execution & Verification

1. Run verification checks from [references/review-checklist.md](references/review-checklist.md).
2. Provide a security verification summary detailing:
   - Bound clamps applied to route schemas.
   - Upload filters active (size, extension, magic bytes, safe path).
   - SSRF protection status on outbound calls.
   - Secret scrubbing confirmation.