​

Rate Limiting & Security Headers

• internal/api/middleware.go — SecurityHeaders.
• internal/api/ratelimit.go — RateLimiter, extractIP.
• internal/api/router.go — middleware composition and route buckets.
• internal/api/auth_google.go + internal/api/oauth.go — OAuth state lifecycle.

​

Security response headers

​

Path-aware CSP

​

Per-IP rate limiting

​

Runtime tuning (admin “Rate Limiters”)

• UI: Admin Console → Infrastructure → Rate Limiters — a table of every limiter with its current value, default, and an inline editor + reset-to-default.
• CLI: crewship admin ratelimits list | set <key> <value> | reset <key> (see the admin CLI reference).
• API: GET /api/v1/admin/rate-limits, PUT /api/v1/admin/rate-limits/{key} ({"value": N}), DELETE /api/v1/admin/rate-limits/{key}.

// Skip rate limiting for internal routes (sidecar IPC, X-Internal-Token auth)
if strings.HasPrefix(path, "/api/v1/internal/") { r.mux.ServeHTTP(w, req); return }
// Read-only NextAuth GETs (session/csrf/…) are polled on every page load —
// route them through the general 120/min bucket, not the strict auth one.
if req.Method == http.MethodGet && strings.HasPrefix(path, "/api/auth/") { r.apiRateLimitedMux.ServeHTTP(…); return }
if strings.HasPrefix(path, "/api/auth/") || … { r.authRateLimitedMux.ServeHTTP(…); return }
if path == "/api/v1/credentials/test" || … { r.credTestRateLimitedMux.ServeHTTP(…); return }
if strings.HasPrefix(path, "/api/") {
  if token := extractToken(req); token != "" && IsCLIToken(token) {
    // negative cache of failed lookups keeps spoofed CLI-prefix bearers
    // from forcing an unthrottled DB lookup per request
    if !r.cliExemptNeg.has(key, now) {
      if IsValidCLIToken(req.Context(), r.db, token) {
        r.cappedMux.ServeHTTP(w, req); return // authenticated CLI — exempt (#1333)
      }
      r.cliExemptNeg.put(key, now)
    }
  }
  r.apiRateLimitedMux.ServeHTTP(w, req); return
}
r.mux.ServeHTTP(w, req)

​

Authenticated-CLI exemption (#1333)

​

Read-only auth GETs stay out of the login bucket

1. Router split — GET /api/auth/* requests carry no credentials, so they route through the general 120 req/min bucket. Only credential-submitting auth requests (the login callback, token refresh, sign-out — all non-GET) stay on the strict 10/min bucket, so brute-force protection is untouched. See Router.routeWithRateLimiting (internal/api/router.go).
2. Frontend resilience — the session probe (hooks/use-auth.tsx) treats a 429, a 5xx/408, or a network error as a transient failure: it backs off and retries (honouring Retry-After) instead of dropping the session. An existing authenticated session is never downgraded to logged-out by a transient response — only a definitive 200 {} (empty), 401, or 403 unauthenticates.

​

Burst, cleanup, 429 response

• Bucket burst equals the per-minute limit (full bucket on first visit).
• Stale per-IP entries are swept every 3 minutes; anything not seen in the last 5 minutes is evicted.
• Exceeding the bucket returns:
  HTTP/1.1 429 Too Many Requests
  Retry-After: 60
  X-RateLimit-Limit: 120
  X-RateLimit-Remaining: 0
  X-RateLimit-Reset: 1717000000
  Content-Type: application/json
  
  {"error": "Too many requests"}
  
  X-RateLimit-Limit is the bucket burst (the per-minute limit); X-RateLimit-Reset is a Unix timestamp 60 s out. The values come from the limiter’s own state, not hard-coded, so well-behaved clients can back off intelligently.

​

IP extraction

1. If the immediate hop is not in the trusted-proxy set, forwarding headers are ignored and the client IP is r.RemoteAddr (host portion).
2. If the immediate hop is a trusted proxy, X-Forwarded-For is parsed right to left, skipping trusted-proxy hops, and the first untrusted entry is returned. X-Real-IP is consulted only if that yields nothing.
3. r.RemoteAddr (host portion) is the final fallback.

​

OAuth CSRF state

• Single-use — the callback uses DELETE … RETURNING to read and remove the row in one statement. A replayed ?state=… returns 400 Invalid or expired state.
• 15-minute expiry — the callback rejects any state whose created_at is older than 15 minutes with 400 OAuth state expired. The OAuth connector flow also sweeps expired rows on each new request (DELETE FROM oauth_states WHERE created_at < datetime('now', '-15 minutes')).
• Fail closed on parse error — unreadable timestamps are treated as invalid rather than allowed through.
• PKCE — the credential-connector flow additionally stores a PKCE code_verifier alongside the state for the token-exchange step.
• Safe redirect allowlist — Google sign-in passes the caller’s ?redirect= through isSafeRedirect before storing, so a bad actor cannot smuggle in an open-redirect target via the state row.

​

State lifecycle

POST /api/auth/google/start
  → generate 32 random bytes (256-bit), base64url-encode
  → INSERT INTO oauth_states (state, redirect_uri, [code_verifier])
  → 307 redirect to provider with ?state=<token>

GET /api/auth/google/callback?state=<token>&code=<code>
  → DELETE FROM oauth_states WHERE state = ? RETURNING redirect_uri, created_at
  → if row missing              → 400 Invalid or expired state
  → if created_at > 15 min ago  → 400 OAuth state expired
  → otherwise exchange code and sign the user in

​

Reviewing behaviour in practice

​

See also

• RBAC — role-gated authorisation layered on top of these controls.
• Encryption — credential + memory at-rest protection.