category: spec
tags: [security, caddy, rate-limiting, headers, plan]
last_updated: 2026-03-17
confidence: high

Rate Limiting and Security Headers Plan

Both handled in Caddy on proxy-1. Two phases: security headers (immediate, zero risk) and rate limiting (requires xcaddy rebuild for the rate_limit module).

Phase 1: Security Headers (no module change)

Caddyfile snippet

Define a named snippet at the top of the Caddyfile (before any site blocks) and import it into the wiki site blocks. Do not apply to the MCP site block — MCP endpoints return JSON and the browser security headers are irrelevant there, and CSP in particular can cause unexpected behavior with SSE clients.

caddyfile
(security_headers) {
    header {
        # Remove server fingerprinting
        -Server

        # HSTS — 1 year. No preload (irreversible without HSTS preload list submission).
        # 1 month — conservative while project is pre-launch. Bump to 31536000 (1 year) post-launch.
        Strict-Transport-Security "max-age=2592000; includeSubDomains"

        # Prevent MIME sniffing
        X-Content-Type-Options "nosniff"

        # Block clickjacking. Use SAMEORIGIN if iframing within the same site is needed.
        X-Frame-Options "DENY"

        # Disable legacy XSS filter (modern browsers; CSP is the real mitigation)
        X-XSS-Protection "0"

        # Referrer: send origin on same-site, origin-only on cross-site HTTPS
        Referrer-Policy "strict-origin-when-cross-origin"

        # Permissions policy: disable sensors/hardware not used by the wiki
        Permissions-Policy "camera=(), microphone=(), geolocation=(), payment=(), usb=(), magnetometer=(), gyroscope=(), accelerometer=()"

        # CSP — see notes below for rationale
        Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob: https:; font-src 'self' data:; frame-ancestors 'none'; base-uri 'self'; form-action 'self'"
    }
}

Apply it to the wiki site blocks:

caddyfile
# Otterwiki web UI
wiki.robot.wtf {
    import security_headers
    import wiki_auth
    reverse_proxy 3gw.lan:8080
}

# Auth, management UI (if served separately)
*.robot.wtf {
    import security_headers
    # ... other directives
}

Do not import security_headers in the mcp.robot.wtf site block.

CSP rationale

Otterwiki's frontend (audited from templates): all JS and CSS are self-hosted (/static/). No external CDNs. MathJax, Mermaid, Font Awesome, and Roboto fonts are all bundled. However:

• layout.html has inline <script> blocks (flash message rendering) — requires 'unsafe-inline' for scripts.
• editor.html has an inline <style> block — requires 'unsafe-inline' for styles.
• editor.js uses preview_block.innerHTML = data.preview_content to render server-fetched HTML into the DOM — this is XSS-safe as long as the server sanitizes, but means wiki content may include <img> tags with arbitrary https: src URLs (user-uploaded or markdown-linked images). Hence img-src 'self' data: blob: https:.
• Font CSS uses local data: URIs for IE compat woff, so font-src 'self' data: is needed.
• frame-ancestors 'none' enforces no-iframe (equivalent to X-Frame-Options: DENY for modern browsers; keep both for compatibility).

Dropping 'unsafe-inline' from script-src would require nonce injection in the app — that's an application change, out of scope for Phase 1.

Verification

After reload, verify with:

curl -sI https://wiki.robot.wtf/ | grep -E '(strict-transport|x-content|x-frame|referrer|permissions|content-security|x-xss)'

Expected: all six response headers present. Confirm Server: header is absent.

Also open browser DevTools → Console on the wiki to confirm no CSP violations are logged.

Phase 2: Rate Limiting

The problem

Standard Caddy Debian package has no rate limiting module. caddy add-package is not viable (doesn't survive apt upgrade, slated for removal from Caddy core). Instead, rate limiting is split across layers:

• Flask-Limiter in the app for per-route, per-IP limits (login, OAuth, API)
• fail2ban on proxy-1 for reactive IP banning after auth failures (already running)
• nftables as a volumetric DoS backstop (optional, future)

Rate limits by endpoint

All per-IP using {remote_host}. User-level limits deferred to application layer.

MCP considerations

• SSE connections are long-lived — don't rate limit /mcp itself (the stream endpoint)
• Rate limit /mcp/* (tool call messages) at 60/min — one AI conversation can make 30-60 calls
• MCP OAuth flow gets auth-level limits (5/min)

Implementation sequence

1. Phase 1 (immediate): Add header blocks to Caddyfile, reload. Verify with curl -I.
2. Phase 2a: Build xcaddy binary with rate_limit module, add to proxy Ansible repo.
3. Phase 2b: Add rate_limit directives to Caddyfile template, deploy to proxy-1.
4. Validate: caddy list-modules confirms module; curl loops verify 429s after threshold.

Rollback

• Headers: remove block, reload. Strictly additive, minimal risk.
• Rate limits: remove directives or raise events values, reload. No restart needed.
• Monitor with journalctl -u caddy -f | grep '" 429 ' after deployment.

Important notes

• Caddy config is on proxy-1, managed by a separate Ansible repo (not robot.wtf)
• proxy-1 is the outermost proxy — {remote_host} is the real client IP
• rate_limit zone names must be globally unique across the Caddyfile