security-compliance

Files (8)

• SKILL.md
• auth-hardening-checklist.md · references/
• cors-configuration.md · references/
• dependency-scanning-setup.md · references/
• owasp-checklist.md · references/
• express-helmet.ts · references/security-headers/
• nextjs-headers.ts · references/security-headers/
• nginx-headers.conf · references/security-headers/

SKILL.md (first lines)

# Security & Compliance

> Phase 2: BUILD | Sprint 2

## Coverage

- OWASP Top 10 (2025) checklist with verification steps
- Auth hardening (Argon2id, rate limiting, session security, MFA, HaveIBeenPwned)
- Input validation (server-side Zod/Joi, DOMPurify, file upload security)
- Security headers (CSP, HSTS, X-Frame-Options, Referrer-Policy, Permissions-Policy)
- Dependency management (Dependabot/Renovate, Snyk/Socket, lock files, CI audit)
- Pre-commit secret scanning (gitleaks/trufflehog)

---

## Read project context first

Before responding, check `.claude/shipwise-state.json` for:
- `project.stack.auth` — determines which auth hardening items apply
- `experience_level` — beginner, intermediate, senior
- `expected_scale` — affects rate limiting thresholds

### Managed auth provider detection

If `project.stack.auth` is a managed provider (`clerk`, `auth0`, `supabase`, `firebase`), the provider handles password hashing, breach checking, and account lockout internally. **Skip these sections** from the auth hardening checklist and note why:

- **Skip Section 1 (Argon2id/bcrypt)** — managed by the provider
- **Skip Section 5 (HaveIBeenPwned)** — managed by the provider
- **Skip Section 7 (Account lockout)** — managed by the provider (verify in provider dashboard settings)

**Focus instead on** what the developer IS responsible for with managed auth:
- Rate limiting at the application layer (provider rate limits protect their endpoints, not yours)
- Session/cookie configuration via the provider's SDK
- CSRF protection for non-API routes
- MFA enablement via the provider's dashboard
- Security headers (always your responsibility regardless of auth provider)

If `project.stack.auth` is self-managed (`nextauth`, `lucia`, `custom`) or absent, present the full checklist.

---

## Checklist Items

### OWASP Top 10 Compliance

<!-- beginner -->
**Run through the OWASP Top 10 checklist** — OWASP is a nonprofit that publishes the 10 most critical web security risks. Think of it as a "building code" for web apps. Each item (like Broken Access Control, Injection, Cryptographic Failures) represents a category of attacks. Walking through this checklist catches the vast majority of real-world vulnerabilities before attackers find them.
> Time: ~2 hours for initial audit
> Reference: See `references/owasp-checklist.md`

<!-- intermediate -->
**OWASP Top 10 (2025) audit** — A01 Broken Access Control, A02 Cryptographic Failures, A03 Injection, A04 Insecure Design, A05 Security Misconfiguration, A06 Vulnerable Components, A07 Authentication Failures, A08 Software/Data Integrity, A09 Logging Failures, A10 SSRF. Verify each with automated + manual checks.
> ~2 hours | `references/owasp-checklist.md`

<!-- senior -->
**OWASP Top 10 (2025)** — Full A01-A10 audit. Automated SAST/DAST + manual verification per category.
> `references/owasp-checklist.md`

---

### Security Headers

<!-- beginner -->
**Add security headers to every response** — Security headers are instructions your server sends to the browser saying "here's how to protect this user." CSP (Content Security Policy) tells the browser which scripts/styles are allowed to run, blocking injected malicious code. HSTS forces HTTPS so no one can intercept traffic. X-Frame-Options prevents your site from being embedded in a malicious iframe (clickjacking). Without these headers, browsers allow almost anything by default.
> Time: ~15 min with templates
> Template: See `references/security-headers/`

<!-- intermediate -->
**Security headers** — CSP (nonce-based for scripts), HSTS (max-age=31536000, includeSubDomains, preload), X-Frame-Options (DENY), X-Content-Type-Options (nosniff), Referrer-Policy (strict-origin-when-cross-origin), Permissions-Policy (restrict camera, mic, geolocation). Use helmet (Express) or next.config.js headers.
> ~15 min | `references/security-headers/`

<!-- senior -->
**Security headers** — CSP w/ nonce, HSTS w/ preload, XFO, XCTO, Referrer-Policy, Permissions-Policy. Templates in `references/security-headers/`.

---

### Auth Hardening

> **Note:** If using a managed auth provider (Clerk, Auth0, Supabase Auth, Firebase Auth), see the "Managed auth provider detection" section above. Skip password hashing, HIBP, and account lockout — your provider handles those. Focus on rate limiting, session config, CSRF, and MFA enablement.

<!-- beginner -->
**Harden your authentication system** — Authentication is how your app knows who someone is. If it's weak, attackers can steal accounts.

**If using Clerk, Auth0, or similar managed auth:**
- Your provider handles password hashing and breach checking — you don't need to implement those
- **Rate limiting**: Still your responsibility. Limit login attempts to 5 per minute per IP on YOUR API routes. The provider protects their endpoints, but you need to protect yours.
- **Secure cookies**: Configure via your provider's SDK. Clerk: set `sameSite: 'strict'` in middleware. Auth0: configure in tenant settings.
- **CSRF protection**: Add CSRF tokens to all state-changing forms so requests can only come from your own site.
- **MFA**: Enable in your provider's dashboard. Clerk: Dashboard → User & Authentication → Multi-factor. Auth0: Dashboard → Security → MFA.

**If using custom/self-hosted auth (NextAuth, Lucia, custom):**
- **Password hashing**: Use Argon2id (or bcrypt with cost factor >= 12 as fallback). Never store plain text or use MD5/SHA.
- **Rate limiting**: Limit login attempts to 5 per minute per IP.
- **Secure cookies**: Set `httpOnly`, `secure`, and `sameSite=strict`.
- **CSRF protection**: Add CSRF tokens to all state-changing forms.
- **Password breach checking**: Check new passwords against the HaveIBeenPwned database.
- **Account lockout**: Lock accounts after 5 failed attempts for 15 minutes.
> Time: ~30 min (managed) / ~1 hour (self-hosted)
> Reference: See `references/auth-hardening-checklist.md`

<!-- intermediate -->
**Auth hardening** — Check `project.stack.auth` first.
- **Managed (Clerk/Auth0/Supabase/Firebase):** Skip Argon2id/HIBP/lockout (provider-managed). Focus on: application-layer rate limiting (5/min login, 100/min API), session config via provider SDK, CSRF double-submit pattern, MFA enablement in provider dashboard.
- **Self-hosted (NextAuth/Lucia/custom):** Full checklist — Argon2id (memoryCost: 65536, timeCost: 3, parallelism: 4), rate limiting, httpOnly+secure+sameSite=strict cookies, CSRF double-submit, HIBP k-anonymity, account lockout (5 attempts/15 min), MFA via TOTP.
> ~30 min (managed) / ~1 hour (self-hosted) | `references/auth-hardening-checklist.md`

<!-- senior -->
**Auth hardening** — Managed auth: rate limit (app layer), session SDK config, CSRF, MFA dashboard toggle. Self-hosted: Argon2id, sliding-window rate limit, session config, CSRF double-submit, HIBP k-anonymity, account lockout, MFA (TOTP/WebAuthn).
> `references/auth-hardening-checklist.md`

---

### Input Validation

<!-- beginner -->
**Validate all user input on the server** — Never trust data from the browser. Even if you have client-side validation, attackers can bypass it entirely (using tools like Postman or curl). Always validate on the server using a schema library like Zod or Joi. For HTML content users submit, sanitize it with DOMPurify to strip malicious scripts. For file uploads: check MIME types, limit file sizes, and store files outside your web root.
> Time: ~45 min
> Key rule: Client-side validation is UX. Server-side validation is security.

From harmansidhudev/shipwise, MIT.

More from harmansidhudev/shipwise