session-orchestrator 3.16.0

package/rules/opt-in-stack/security-web.md

@@ -0,0 +1,194 @@
+<!-- source: session-orchestrator plugin (canonical: rules/opt-in-stack/security-web.md) -->
+---
+globs:
+  - src/middleware*.ts
+  - src/app/**
+  - next.config.*
+  - src/lib/csp*
+  - src/lib/cors*
+tier: wave-only
+---
+
+# Security — Web & API (Path-scoped)
+
+CSRF, rate limiting, CSP, and transport security. Core security rules are in `security.md` (always-on).
+
+## CSRF Protection (SEC-005)
+- **Next.js 15+ Server Actions**: Built-in CSRF protection via Origin header validation against Host header. No manual CSRF token needed.
+- **Manual CSRF tokens required for**: custom API routes (`/api/*`), form submissions to external endpoints, any non-Server-Action mutation endpoint.
+- For manual CSRF token validation, use `crypto.timingSafeEqual()` for timing-safe comparison.
+- Note: Next.js 15+ Server Actions automatically validate the Origin header against the Host header, providing CSRF protection out of the box.
+
+## Headers & Transport
+- HTTPS everywhere. No HTTP in production.
+- Security headers via Helmet (Express) or Next.js config.
+- CORS: explicit allow-list, never `*` in production.
+- CORS origin comparison is case-sensitive in most implementations — `https://Example.com` !== `https://example.com`. Always use lowercase origins in Express/Helmet CORS allowlists. In Next.js middleware, normalize with `request.headers.get('origin')?.toLowerCase()` before comparing.
+
+### CORS Origin Validation
+- Always normalize origins with `.toLowerCase()` before comparison — some browsers send mixed-case Origin headers.
+- Example:
+  ```ts
+  const allowedOrigins = ['https://example.com', 'https://app.example.com'];
+  const origin = req.headers.origin?.toLowerCase();
+  if (origin && allowedOrigins.includes(origin)) {
+    res.setHeader('Access-Control-Allow-Origin', origin);
+  }
+  ```
+- Never use `Access-Control-Allow-Origin: *` with `credentials: true` — browsers will reject this.
+- For multi-tenant: derive allowed origins from database at startup, cache with TTL.
+
+## Content Security Policy & Headers (SEC-011)
+
+- Every Next.js app MUST define security headers in `next.config.ts` via `headers()` on `source: '/(.*)'`.
+- Every Express service MUST use `helmet()` with explicit CSP directives — never rely on defaults alone.
+- CSP `default-src` MUST be `'self'`. Never use `'unsafe-eval'` in production.
+- CSP `script-src`: use nonces (`'nonce-${nonce}'` + `'strict-dynamic'`) in production Next.js. `'unsafe-inline'` only in development.
+- CSP `style-src`: use `'nonce-${nonce}'` in production where possible. `'unsafe-inline'` acceptable only during development or when Tailwind CSS runtime styles require it. Document retention.
+- CSP `object-src: 'none'`, `base-uri: 'self'`, `form-action: 'self'`, `frame-ancestors: 'none'`.
+- `Strict-Transport-Security: max-age=63072000; includeSubDomains; preload` (2 years).
+- `X-Content-Type-Options: nosniff`, `Referrer-Policy: strict-origin-when-cross-origin` — mandatory on all routes.
+- `Permissions-Policy`: deny `camera`, `microphone`, `geolocation`, `payment` unless actually used.
+- Add Sentry CDN, Supabase URL, and Vercel Analytics to CSP `connect-src` as needed.
+- Cookies MUST use `HttpOnly; Secure; SameSite=Lax` minimum. Use `__Host-` prefix for session cookies.
+- CSP violations should be reported via `report-uri` to Sentry's CSP endpoint in production.
+- CSP `report-to` directive + `Reporting-Endpoints` header is the modern replacement for `report-uri`. Both should be configured:
+  - `Reporting-Endpoints: csp-endpoint="https://sentry.io/api/PROJECT_ID/security/?sentry_key=KEY"` response header
+  - `report-to csp-endpoint` CSP directive (references the named endpoint)
+  - Keep `report-uri` as legacy fallback for older browsers
+  - Both are commented out in templates — uncomment with project-specific Sentry CSP endpoint
+- Test headers with securityheaders.com before launch. Target grade A+.
+
+### Next.js 16 CSP via proxy.ts
+- Next.js 16 introduces `proxy.ts` as the recommended file for per-request header injection (CSP nonces, CORS). The baseline provides `templates/nextjs-saas/proxy.ts.template` — copy it as `proxy.ts` in the project root at setup time.
+- `proxy.ts`: runs before routing, ideal for CSP nonce injection. Use for Next.js 16+ projects.
+- `middleware.ts`: still works for CSP but is primarily for routing logic (auth redirects, rewrites).
+- **Never set CSP in both proxy.ts AND middleware.ts.** proxy.ts is the single source for CSP. middleware.ts handles rate limiting and routing only.
+
+#### SEC-011: CSP single-source enforcement
+- Advisory rules are silent when they regress. Wire the single-source rule into a mechanical check so duplicates fail fast.
+- Canonical hook: `templates/shared/hooks/check-csp-single-source.sh`. Greps all TS/JS under the given paths for `Content-Security-Policy`, filters to `proxy.ts` / `middleware.ts` / `next.config.*`, fails if more than one file matches.
+- **Wire into pre-push (Husky):**
+  ```json
+  // package.json
+  { "scripts": { "hook:check-csp": "bash templates/shared/hooks/check-csp-single-source.sh src" } }
+  ```
+  ```bash
+  # .husky/pre-push
+  pnpm run hook:check-csp
+  ```
+- **Wire into CI security stage:** copy the `check-csp-single-source` job from `templates/shared/hooks/README.md` into `.gitlab-ci.yml`. Runs on every merge request.
+- Exit codes: `0` pass, `1` duplicate CSP source (SEC-011 violation), `2` tool error.
+- Why: browsers receiving two `Content-Security-Policy` headers take the intersection — nonces and `strict-dynamic` break silently. Humans miss this in review; a grep doesn't.
+
+#### Nonce Generation Pattern
+- Generate a unique nonce per request: `const nonce = Buffer.from(crypto.randomUUID()).toString('base64');`
+- Pass the nonce to Server Components via the `x-nonce` request header: `requestHeaders.set('x-nonce', nonce);`
+- In Server Components, read it with `headers().get('x-nonce')` and pass to `<Script nonce={nonce}>` or inline `<script nonce={nonce}>` tags.
+- Next.js automatically applies the nonce to framework scripts, bundles, and `<Script>` components when set via proxy.ts.
+- The CSP header uses `'nonce-${nonce}' 'strict-dynamic'` for `script-src`, which allows nonce-tagged scripts to load their dependencies without explicit allowlisting.
+
+#### Proxy Matcher Pattern
+- The proxy matcher excludes API routes, static assets (`_next/static`, `_next/image`, `favicon.ico`), and prefetch requests (`next-router-prefetch` header, `purpose: prefetch` header).
+- This avoids unnecessary nonce generation for requests that do not render HTML pages.
+- Pattern: `/((?!api|_next/static|_next/image|favicon.ico).*)` with `missing` conditions for prefetch headers.
+
+#### SRI (Subresource Integrity) as Alternative
+- For fully static pages (no per-request nonce needed), enable SRI in `next.config.ts`:
+  ```ts
+  experimental: { sri: { algorithm: 'sha256' } }
+  ```
+- SRI adds `integrity="sha256-..."` attributes to `<script>` and `<link>` tags at build time, allowing `script-src 'self'` without nonces.
+- **Do not combine SRI and nonces on the same page.** SRI hashes are computed at build time; nonces change per request. Mixing both creates conflicting CSP expectations and may cause script blocking.
+- Use SRI for marketing/landing pages and other static content. Use nonces (via proxy.ts) for dynamic, authenticated pages.
+
+### CSP Report-Only Mode
+- Use `Content-Security-Policy-Report-Only` header to test CSP changes without blocking resources in production.
+- Pattern: deploy new directives as report-only first, monitor violation reports for 1-2 weeks, then promote to enforcing `Content-Security-Policy`.
+- Report endpoint: `report-uri /api/csp-report` (receives JSON violation reports). Forward to Sentry or structured logs for analysis.
+- Never skip report-only. A single misconfigured directive in enforcing mode can break the entire page.
+- In Next.js, set report-only header in `proxy.ts` alongside (not replacing) the enforcing CSP header.
+
+### CSP Source of Truth (Critical)
+- **Next.js projects**: `proxy.ts` is the SSOT for CSP headers. middleware.ts handles rate limiting and routing only.
+- **Express/Docker projects**: `securityMiddleware()` in security.ts sets CSP via Helmet.
+- **Never set CSP in both proxy.ts AND middleware.ts** — if both set Content-Security-Policy, the last writer wins (middleware.ts response overwrites proxy.ts header), creating security gaps where expected CSP directives are silently dropped.
+- **Detection**: Search for `Content-Security-Policy` across all middleware files. If found in >1 file, consolidate into the SSOT.
+- **Testing**: Use `CSP-Report-Only` header during development to catch violations before enforcing.
+
+## Session Cookie Hardening (SEC-017)
+- Cookie flags: `HttpOnly; Secure; SameSite=Lax` minimum on all session cookies. Use `SameSite=Strict` for admin/sensitive operations.
+- Use `__Host-` prefix for session cookies: enforces `Secure`, no `Domain`, `Path=/`. Prevents cookie injection from sibling subdomains.
+- Token rotation: rotate session token after login, privilege escalation, role change, or password change. Invalidate old token immediately.
+- Idle timeout: 30 minutes for sensitive operations (payments, admin). Max-Age 7 days for persistent "remember me" sessions.
+- Supabase Auth: `@supabase/ssr` handles cookie management. Verify that `cookieOptions` in `createServerClient()` sets `httpOnly: true`, `secure: true`, `sameSite: 'lax'`.
+- Never store session tokens in `localStorage` or `sessionStorage`. Cookies with `HttpOnly` are not accessible to JavaScript (XSS-resistant).
+- Logout: invalidate server-side session AND clear client cookie. Call `supabase.auth.signOut()` which handles both.
+
+## Rate Limiting Details (SEC-003)
+
+- All public API endpoints must enforce rate limiting. No exceptions.
+- Use Upstash Redis for distributed rate limiting. Required env vars: `UPSTASH_REDIS_REST_URL`, `UPSTASH_REDIS_REST_TOKEN` (add to `.env.example`).
+- **Public endpoints**: `express-rate-limit` fixed window (all project types). Acceptable for general API traffic.
+- **Auth endpoints** (login, register, password reset): `@upstash/ratelimit` sliding window with `@upstash/redis` (all project types — Next.js, Express, Docker). Prevents burst attacks at fixed-window boundaries.
+- Next.js: `@upstash/ratelimit` + `@upstash/redis` in middleware. Express/Docker: `@upstash/ratelimit` + `@upstash/redis` in `authRateLimiter()` from shared security middleware.
+- Rate limit thresholds SHOULD be configurable via environment variables (`RATE_LIMIT_REQUESTS`, `RATE_LIMIT_WINDOW_MS`, `RATE_LIMIT_AUTH_REQUESTS`, `RATE_LIMIT_AUTH_WINDOW_MS`) with sensible defaults. Templates read these from `process.env` at startup.
+- Rate limit keys: IP for unauthenticated, `userId` for authenticated, `IP + email hash` for auth endpoints.
+- Use sliding window for auth endpoints (login, register, password reset) — prevents burst attacks at window boundaries.
+- Apply rate limiting as early as possible in middleware — before auth and body parsing where applicable.
+- Always return 429 with `Retry-After` header and `RateLimit-Limit` / `RateLimit-Remaining` / `RateLimit-Reset`.
+- Rate limit config: `standardHeaders: true, legacyHeaders: false` — uses IETF `RateLimit-*` headers. Response body must only contain a user-friendly error message, never internal limit configuration.
+- Response body on 429: generic user-friendly message. Never expose internal limit config.
+- Log every 429 with endpoint, key, window, limit. Alert when a key hits limit > 5 times in 10 minutes.
+- If Redis store is unavailable, fail open with warning log — but alert immediately.
+
+### Bounded Exception — localhost-only single-process MVP endpoints
+The "Upstash Redis, no exceptions" mandate above scopes to **public / production** API surfaces. It is NOT a contradiction to use a lighter limiter for a localhost-only daemon or MVP endpoint running in a **single process**: a ~10-line inline `Map<ip, { count, resetAt }>` fixed-window limiter is sufficient and preferable to pulling in `@upstash/ratelimit` + a Redis dependency. Reset-on-restart is acceptable at MVP scope (the daemon is a long-running, user-scoped service). Keep `@upstash/ratelimit` available for the eventual distributed upgrade, but do not wire it until the endpoint is genuinely multi-process or public-facing. Still return 429 + `Retry-After` on window exhaustion, and add a regression test that exercises the exhaustion path. Promote to Upstash the moment the endpoint leaves localhost or spans processes.
+
+### Rate Limiting Matrix
+
+| Endpoint Type | Window | Strategy | Anon | Auth | Premium |
+|---------------|--------|----------|------|------|---------|
+| Auth (login/register/reset) | Sliding, 15 min | Upstash | 5 | 10 | 10 |
+| Auth (verify/token) | Sliding, 5 min | Upstash | 3 | 5 | 5 |
+| Public API | Fixed, 1 min | express-rate-limit | 60 | 300 | 1000 |
+| Authenticated API | Fixed, 1 min | express-rate-limit | — | 300 | 1000 |
+| File Upload | Fixed, 1 min | express-rate-limit | — | 10 | 50 |
+| Webhook Receiver | Fixed, 1 min | express-rate-limit | 100 | 100 | 100 |
+| WebSocket Upgrade | Fixed, 1 min | Custom | 5 | 20 | 50 |
+
+Tier detection: check `req.user.tier` after auth middleware. Anonymous = no auth token.
+- Store tier definitions in config, not inline. Example: `RATE_TIERS = { anon: 60, auth: 300, premium: 1000 }`.
+- If tier lookup fails (e.g., Redis unavailable), fall back to the anonymous tier — never fail open to the highest tier.
+- IP-based limits still apply as a baseline layer to prevent abuse from a single source, even for premium users.
+
+### Health/Readiness Route Bypass
+Mount health routes BEFORE applying rate limiting middleware, so they remain unlimited:
+```ts
+// Health routes — excluded from rate limiting (SEC-003)
+app.use('/health', healthRouter);
+app.use('/ready', readinessRouter);
+
+// Rate limiting applied AFTER health routes
+securityMiddleware(app);
+```
+
+### Additional Rate Limit Guidance
+- **Export row limits**: max 100,000 rows per export. Enforce server-side regardless of client request.
+- **File upload size quotas**: 10MB per file, 50MB per request total. Enforce via middleware before body parsing.
+- **WebSocket reconnection**: mandate exponential backoff on client disconnect (base 1s, max 30s, jitter).
+- **Upstash sliding window**: standard for auth endpoints across all project types. `express-rate-limit` fixed window is acceptable for general public API rate limiting.
+- **Search endpoints**: expensive queries (full-text search, complex joins) should have stricter limits than simple CRUD.
+
+## Output Encoding & Escaping (SEC-016)
+
+- **HTML**: React auto-escapes JSX output. For `dangerouslySetInnerHTML`, sanitize with DOMPurify first. Never render raw user HTML.
+- **URL**: Use `encodeURIComponent()` for user data in URL parameters. Never interpolate raw user input into URLs.
+- **CSV Injection**: Prefix cell values starting with `=`, `+`, `-`, `@`, `\t`, `\r` with a single quote (`'`) before export. Applies to all CSV/XLSX generation.
+- **Base64**: Validate format before decoding (`/^[A-Za-z0-9+/]*={0,2}$/`). Enforce size limits (max 10MB decoded) to prevent memory exhaustion.
+- **JSON**: Never use `eval()` or `new Function()` to parse JSON. Always `JSON.parse()` + Zod validation at system boundaries.
+- **Log Injection**: Strip newlines (`\n`, `\r`) and ANSI escape codes (`\x1b[`) from user input before logging. Use structured logging (JSON format) to prevent log forging.
+- **Template Literals**: Never use tagged template literals with user input for SQL, HTML, or shell commands. Use parameterized queries, DOMPurify, or `child_process.execFile()` respectively.
+
+## See Also
+development.md · security.md · testing.md · frontend.md · backend.md · backend-data.md · swift.md · mvp-scope.md · cli-design.md · parallel-sessions.md

package/rules/opt-in-stack/swift.md

@@ -0,0 +1,65 @@
+<!-- source: session-orchestrator plugin (canonical: rules/opt-in-stack/swift.md) -->
+---
+globs:
+  - "**/*.swift"
+  - "**/Package.swift"
+  - "**/*.xcodeproj/**"
+tier: wave-only
+---
+# Swift Rules (Path-scoped)
+
+## Language & Style
+
+- Swift 5.9+ (Swift 6 concurrency model where the target supports it).
+- Enable strict concurrency checking (`-strict-concurrency=complete`) in `Package.swift` for new targets.
+- Use `async`/`await` for all asynchronous code. Never use completion-handler callbacks in new code.
+- Prefer value types (`struct`, `enum`) over reference types (`class`) unless shared mutable state is required.
+- Mark reference types `final` unless inheritance is intentional and documented.
+- Use `@MainActor` for UI-updating code. Isolate background work with structured concurrency (`TaskGroup`, `async let`).
+
+## Testing
+
+- Use Swift Testing framework (`import Testing`) for all new tests. Do NOT use XCTest for new code.
+- Test file naming: `<FeatureName>Tests.swift` co-located with source in the same target.
+- Parameterised tests: use `@Test(arguments:)` instead of duplicating test functions.
+- Use `#expect` and `#require` (not `XCTAssert*`) for assertions.
+- Mock protocols, not classes. Define `protocol`-based dependencies for all external calls.
+
+## SwiftUI
+
+- Extract view logic into `ViewModels` or use `@Observable` (iOS 17+) / `ObservableObject` (< iOS 17).
+- Prefer composable, single-responsibility views. Split views that exceed ~100 lines of `body`.
+- Avoid `AnyView` — it disables diffing optimisations. Use `@ViewBuilder` or generics instead.
+- Use `task(id:)` for async view setup tied to identity. Avoid `onAppear` for network calls.
+- Animations: use `.animation(.default, value:)` tied to state changes. Never animate on `onAppear` without a state guard.
+
+## Networking
+
+- Use `URLSession` with `async`/`await`. Wrap calls in `Actor`-isolated service types.
+- Decode responses with `Codable` + `JSONDecoder`. Set `keyDecodingStrategy = .convertFromSnakeCase` for snake_case APIs.
+- Always cancel network tasks when the owning view disappears (use `Task` stored in `@State` and `.cancel()` in `onDisappear`).
+- Never call APIs directly from SwiftUI `View` body — always go through a `ViewModel` or service layer.
+
+## Error Handling
+
+- Define domain-specific `Error` enums conforming to `LocalizedError`. Provide `errorDescription` for user-facing messages.
+- Use `Result<Success, Failure>` for APIs that callers must handle failures of.
+- In async contexts, use `throws` + `try`/`catch`. Never silence errors with `try?` unless the failure is genuinely unimportant.
+- Log errors with `Logger` from `os.log` (not `print`). Use subsystems and categories for structured filtering.
+
+## Package Management (SPM)
+
+- Use Swift Package Manager exclusively. No CocoaPods or Carthage for new projects.
+- Pin exact versions in `Package.resolved`. Review and update dependencies with each minor release cycle.
+- Keep `Package.swift` platforms list up to date with the minimum deployment target.
+- Separate library targets from executable/app targets to maximise testability.
+
+## Security
+
+- Never hard-code secrets, API keys, or tokens in source. Use the Keychain or environment variables injected at build time.
+- Use `SecureField` for password inputs. Never log or persist raw password strings.
+- Certificate pinning for high-sensitivity apps (healthcare, financial). Use `URLSessionDelegate` + `SecTrustEvaluate`.
+- Validate all server-sent data with Codable schemas. Never `force-unwrap` optional JSON fields.
+
+## See Also
+development.md · security.md · testing.md · frontend.md · backend.md · mvp-scope.md · parallel-sessions.md