feat: harden OAuth state secret validation, DCR file permissions, and policy defaults

- Enforce 32-char minimum on OAUTH_STATE_SECRET at startup (config.py)
- Write DCR client registry with owner-only (0o600) permissions before atomic replace
- Flip policy.yaml default write action from allow → deny
- Add CLAUDE.md with architecture, commands, and AGENTS.md contract summary
- Add .pre-commit-config.yaml mirroring `make lint` checks
- Update .gitignore: add .venv, .claude, .mypy_cache, .ruff_cache, .coverage.*
- Extend docs: audit log rotation guidance, OAUTH_STATE_SECRET and DCR_STORAGE_PATH notes
- Tests: short-secret rejection, 32-char acceptance, POSIX permission check for DCR store

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs/audit.md

@@ -31,3 +31,23 @@ Exit code `0` indicates valid chain, non-zero indicates tamper/corruption.
 - Persist audit logs to durable storage.
 - Protect write permissions (service account only).
 - Validate integrity during incident response and release checks.
+
+## Rotation
+
+The server appends to a single audit file and does not rotate it in process — rotating
+mid-stream would break the `prev_hash`/`entry_hash` chain. Manage growth externally with
+`logrotate` using `copytruncate` so the open file handle keeps appending:
+
+```
+/var/log/aegis-mcp/audit.log {
+    weekly
+    rotate 12
+    compress
+    missingok
+    notifempty
+    copytruncate
+}
+```
+
+Run `scripts/validate_audit_log.py` against each rotated segment to confirm the chain
+remains intact across rotations before archiving.

docs/configuration.md

@@ -16,7 +16,7 @@ cp .env.example .env
 | `GITEA_OAUTH_CLIENT_SECRET` | Yes when `OAUTH_MODE=true` | - | OAuth client secret |
 | `OAUTH_EXPECTED_AUDIENCE` | No | empty | Additional accepted JWT audience beyond the MCP resource and Gitea client id |
 | `OAUTH_CACHE_TTL_SECONDS` | No | `300` | OIDC discovery/JWKS cache TTL |
-| `OAUTH_STATE_SECRET` | Yes when `OAUTH_MODE=true` | - | HMAC secret for signed OAuth state wrappers |
+| `OAUTH_STATE_SECRET` | Yes when `OAUTH_MODE=true` | - | HMAC secret for signed OAuth state wrappers; must be at least 32 characters (e.g. `openssl rand -hex 32`) |
 | `OAUTH_REDIRECT_ALLOWLIST` | No | empty | Additional allowed redirect URIs for OAuth clients |
 
 ## MCP Server Settings
@@ -30,7 +30,7 @@ cp .env.example .env
 | `LOG_LEVEL` | No | `INFO` | `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` |
 | `STARTUP_VALIDATE_GITEA` | No | `true` | Validate OIDC discovery endpoint at startup |
 | `DCR_ENABLED` | No | `true` | Enable dynamic client registration at `/register` |
-| `DCR_STORAGE_PATH` | No | `/var/lib/aegis-mcp/dcr_clients.json` | Persisted OAuth client registry path |
+| `DCR_STORAGE_PATH` | No | `/var/lib/aegis-mcp/dcr_clients.json` | Persisted OAuth client registry path. Written with owner-only (`0o600`) permissions on POSIX hosts |
 
 ## Security and Limits