AGENTS.md

1# Security Rules
2 
3These rules apply to all code generated in this project. They are non-negotiable.
4 
5## Secrets
6 
7- NEVER put API keys, database credentials, or tokens in frontend code (anything under src/, app/, pages/, components/, public/)
8- NEVER put secret keys in environment variables prefixed with NEXT_PUBLIC_, VITE_, or REACT_APP_ (these are bundled into the client)
9- NEVER hardcode credentials in source files. Use environment variables loaded server-side only
10- The .env file MUST be in .gitignore before the first commit. Verify this before creating any .env file
11- Use .env.example with placeholder values only, never real credentials
12 
13## Database
14 
15- Enable Row Level Security on EVERY Supabase table before deployment. Default policy: deny all. Write explicit policies scoped to auth.uid()
16- NEVER set a Supabase RLS policy to `USING (true)` or `FOR ALL` without a WHERE condition
17- Firebase Security Rules MUST require `request.auth != null` and scope access to `request.auth.uid`
18- NEVER use `pickle.loads`, `pickle.load`, or any deserialization on user-supplied data. Use JSON for all network data exchange
19 
20## Authentication and Authorization
21 
22- EVERY API route that returns or modifies user data MUST have authentication middleware that runs BEFORE the handler, not inside it
23- Unauthenticated requests to protected endpoints MUST return 401
24- EVERY route that takes a resource ID MUST verify the authenticated user owns that resource: `current_user.id == resource.owner_id`. This is a SEPARATE check from authentication
25- Admin endpoints MUST verify admin role and return 403 for non-admin users
26- Session cookies MUST set `httpOnly: true`, `secure: true`, and `sameSite: 'lax'`
27 
28## Input and Output
29 
30- NEVER concatenate user input into SQL queries. ALWAYS use parameterized queries or ORM methods
31- NEVER use `dangerouslySetInnerHTML`, `v-html`, or `innerHTML` with user-supplied content unless it is first sanitized with DOMPurify
32- ALL user input MUST be validated server-side. Client-side validation is for UX only
33- File uploads MUST validate file type by reading magic bytes, not by checking the filename extension. Rename all uploads to UUIDs server-side. Store on a separate domain (S3, R2, GCS), never on the app origin
34 
35## URL Fetching (SSRF Prevention)
36 
37- If the application fetches URLs provided by users (link previews, image proxies, URL validators), it MUST:
38  - Block all private/internal IP ranges: 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16, ::1
39  - Allow only http and https schemes
40  - Resolve the hostname and check the IP BEFORE making the request
41 
42## Security Headers
43 
44- Set these headers on ALL responses via a single global middleware:
45  - `Content-Security-Policy: default-src 'self'` (adjust as needed for your app)
46  - `Strict-Transport-Security: max-age=31536000; includeSubDomains`
47  - `X-Frame-Options: DENY`
48  - `X-Content-Type-Options: nosniff`
49  - `Referrer-Policy: strict-origin-when-cross-origin`
50- In Express, use the `helmet` package. In Next.js, set headers in next.config.js
51 
52## CORS
53 
54- NEVER set CORS origin to `*` (wildcard). Use an explicit allowlist of your actual domains
55- NEVER combine `origin: '*'` with `credentials: true`
56 
57## Rate Limiting
58 
59- Login, registration, and password reset endpoints MUST have rate limiting (block after N failed attempts per IP within a time window)
60- Do NOT trust X-Forwarded-For for rate limiting unless behind a trusted reverse proxy
61 
62## Payments
63 
64- Stripe webhook endpoints MUST verify the signature using `stripe.Webhook.construct_event` (or equivalent) on every request. Reject any request with an invalid or missing signature
65- Webhook handlers MUST track processed event IDs and skip duplicates (idempotency)
66- Handle the full event lifecycle: payment_intent.succeeded, invoice.payment_failed, customer.subscription.deleted, customer.subscription.past_due
67 
68## Error Handling
69 
70- NEVER expose stack traces, SQL errors, file paths, or library names in API responses
71- Production error responses MUST return only generic messages: `{"error": "Something went wrong"}`
72- Full error details go to server-side logs only
73- Debug mode / development error pages MUST be disabled in production
74 
75## Password Hashing
76 
77- ALWAYS use bcrypt, Argon2, or scrypt for password hashing
78- NEVER use MD5, SHA-1, or plain SHA-256 for passwords
79 
80## Dependencies
81 
82- Before installing any package, verify it exists on the official registry with a reasonable download count and history
83- Pin exact versions in package.json / requirements.txt (no ^ or ~ in production)
84- Commit lock files (package-lock.json, poetry.lock, yarn.lock)
85