---
# Security Practices

<!--
GENERATION INSTRUCTIONS:
1. Find auth middleware/guards and extract flow
2. Scan for role/permission checks and document model
3. Locate validation schemas at API boundaries
4. Check for security middleware (helmet, cors, rate-limit)
5. Find secrets loading pattern (env, vault, etc.)
6. Identify security-sensitive operations and their protections
7. Output: 150-300 lines max
-->

**Project**: [Extract from config]
**Auth Method**: [Detect: JWT | Session | OAuth2 | API Key | None]
**Auth Library**: [Detect: passport, jose, next-auth, etc.]

---

## Authentication Flow

<!-- Extract actual auth implementation -->

### How Auth Works

```
[Request] → [Auth Middleware] → [Token/Session Validation] → [User Context]
                  │
                  ▼ (on failure)
             401 Unauthorized
```

### Implementation

```[lang]
// Source: [file:lines]
[Extract auth middleware/guard usage]
```

### Token/Session Details

| Aspect | Value |
|--------|-------|
| Type | `[JWT / Session / API Key]` |
| Storage | `[Header: Bearer / Cookie / Query]` |
| Expiration | `[duration or config location]` |
| Refresh | `[mechanism if exists]` |

### Protect a Route

```[lang]
// Apply auth to new endpoints like this:
[Extract exact syntax for protecting routes]
```

---

## Authorization

<!-- Find permission/role checking patterns -->

### Permission Model

**Type**: [RBAC | ABAC | Simple roles | Custom]

| Role/Permission | Access Level | Defined In |
|-----------------|--------------|------------|
| `[role/permission]` | [What it allows] | `[file:line]` |
| `[role/permission]` | [What it allows] | `[file:line]` |

### Enforce Permissions

```[lang]
// Source: [file:lines]
[Extract authorization check pattern]
```

### Check User Permissions

```[lang]
// How to check permissions in code:
[Extract permission checking syntax]
```

---

## Input Validation

<!-- Find validation at API boundaries -->

### Validation Layer

**Library**: `[Zod / Joi / class-validator / Pydantic / etc.]`
**Applied At**: `[Middleware / Decorator / Controller]`

```[lang]
// Source: [file:lines]
[Extract validation schema example]
```

### Sanitization

```[lang]
// Source: [file:lines] - if explicit sanitization exists
[Extract sanitization pattern or note "handled by validation library"]
```

### Rules

- ✅ Validate at `[detected boundary - controller/middleware]`
- ✅ Use schemas from `[validation path]`
- ❌ Never trust: query params, body, headers, path params

---

## Secrets Management

<!-- Find how secrets are loaded and used -->

### Loading Pattern

```[lang]
// Source: [file:lines]
[Extract secrets/config loading]
```

### Secret Variables

| Variable | Purpose | Required |
|----------|---------|----------|
| `[SECRET_KEY/JWT_SECRET]` | [Token signing] | Yes |
| `[DATABASE_URL]` | [DB connection] | Yes |
| `[API_KEY_*]` | [External services] | Varies |

### Access Secrets

```[lang]
// Always access secrets via:
[Extract config/env access pattern - never hardcode]
```

### Rules

- ✅ Load from `[env / secrets manager / vault]`
- ✅ Access via `[config module pattern]`
- ❌ Hardcode in source code
- ❌ Commit `.env` files
- ❌ Log secret values

---

## Security Middleware

<!-- Find security-related middleware/headers -->

### Configured Protections

| Protection | Implementation | Source |
|------------|----------------|--------|
| Security Headers | `[helmet / manual / framework]` | `[file:line]` |
| CORS | `[cors config location]` | `[file:line]` |
| Rate Limiting | `[rate-limit implementation]` | `[file:line]` |
| CSRF | `[csrf protection or N/A]` | `[file:line]` |

### Headers Set

```[lang]
// Source: [file:lines]
[Extract security headers configuration]
```

### CORS Configuration

```[lang]
// Source: [file:lines]
[Extract CORS config - allowed origins, methods]
```

### Rate Limiting

```[lang]
// Source: [file:lines]
[Extract rate limit configuration]
```

**Limits**: `[X requests per Y time window]`

---

## SQL Injection Prevention

<!-- Verify ORM/query builder or parameterized queries -->

**Protection**: `[ORM: name | Query Builder: name | Parameterized queries]`

```[lang]
// ✅ Safe - Source: [file:lines]
[Extract parameterized query example]

// ❌ NEVER - vulnerable to injection
[Show anti-pattern if found, or generic example]
```

---

## XSS Prevention

<!-- Find output encoding/escaping -->

**Protection**: `[Framework auto-escaping | Manual escaping | CSP]`

```[lang]
// Source: [file:lines]
[Extract output escaping or template rendering pattern]
```

**Content Security Policy**: `[Configured / Not configured]`

---

## File Upload Security

<!-- If file uploads exist, document protections -->

```[lang]
// Source: [file:lines]
[Extract file upload validation - type, size, name sanitization]
```

| Protection | Implementation |
|------------|----------------|
| File type validation | `[how enforced]` |
| Size limit | `[max size]` |
| Storage location | `[path - outside webroot?]` |
| Filename sanitization | `[yes/no, how]` |

---

## Audit Logging

<!-- Find security event logging -->

**Logged Events**:

| Event | Log Level | Source |
|-------|-----------|--------|
| Login success/failure | `[level]` | `[file:line]` |
| Permission denied | `[level]` | `[file:line]` |
| Password change | `[level]` | `[file:line]` |
| Sensitive data access | `[level]` | `[file:line]` |

```[lang]
// Source: [file:lines]
[Extract audit log example]
```

---

## Dependency Security

<!-- Find vulnerability scanning setup -->

| Tool | Command | Frequency |
|------|---------|-----------|
| `[npm audit / safety / snyk / dependabot]` | `[command]` | `[CI / manual]` |

---

## Security Anti-Patterns

<!-- Extract from code review or detected issues -->

| ❌ NEVER | ✅ INSTEAD | Risk |
|----------|-----------|------|
| `[detected or common anti-pattern]` | `[correct pattern]` | [Risk type] |
| `[detected or common anti-pattern]` | `[correct pattern]` | [Risk type] |
| `[detected or common anti-pattern]` | `[correct pattern]` | [Risk type] |
| Log user passwords/tokens | Log user ID only | Data exposure |
| Return stack traces to client | Generic error messages | Info leakage |

---

## Quick Reference

| Security Need | Location | Pattern |
|---------------|----------|---------|
| Auth middleware | `[path]` | `[usage syntax]` |
| Permission check | `[path]` | `[usage syntax]` |
| Input validation | `[path]` | `[usage syntax]` |
| Secrets config | `[path]` | `[access pattern]` |
| Security headers | `[path]` | - |
| Audit logging | `[path]` | `[log function]` |

---