user guides

backend-services/platform-logs/doorman-trail.log

@@ -638,3 +638,5 @@
 2025-09-26 22:44:15,591 - doorman.audit - INFO - {"actor":"admin","action":"api.create","target":"subapi/v1","status":201,"details":{"message":"API created successfully"},"ip":"127.0.0.1","path":"/platform/api","request_id":"60450202-7495-4ee3-b134-f92ab3652cdf"}
 2025-09-26 22:44:15,592 - doorman.audit - INFO - {"actor":"admin","action":"subscription.subscribe","target":"admin:subapi/v1","status":200,"details":null,"ip":"127.0.0.1","path":"/platform/subscription/subscribe","request_id":"5162fa36-d731-4718-972a-33ffec36cec2"}
 2025-09-26 22:44:15,594 - doorman.audit - INFO - {"actor":"admin","action":"subscription.unsubscribe","target":"admin:subapi/v1","status":200,"details":null,"ip":"127.0.0.1","path":"/platform/subscription/unsubscribe","request_id":"06cd1e36-f29a-4572-b249-6f453ae38993"}
+2025-09-26 22:53:14,108 - doorman.audit - INFO - {"actor":"admin","action":"security.update_settings","target":"security_settings","status":"success","details":{"enable_auto_save":false,"auto_save_frequency_seconds":60,"dump_path":"generated/memory_dump.bin"},"ip":"127.0.0.1","path":"/platform/security/settings","request_id":"e2c9b14f-d027-4aaa-80f2-ee458d1068f2"}
+2025-09-26 22:53:15,799 - doorman.audit - INFO - {"actor":"admin","action":"security.update_settings","target":"security_settings","status":"success","details":{"enable_auto_save":false,"auto_save_frequency_seconds":60,"dump_path":"generated/memory_dump.bin"},"ip":"127.0.0.1","path":"/platform/security/settings","request_id":"8b6192da-e189-4a66-ac3e-9206aecf7b34"}

user-docs/OPERATIONS.md

@@ -0,0 +1,108 @@
+# Operations Guide (Doorman Gateway)
+
+This document summarizes production configuration, deployment runbooks, and key operational endpoints for Doorman.
+
+## Environment Configuration
+
+Recommended production defaults (see `.env`):
+
+- HTTPS_ONLY=true — set `Secure` flag on cookies
+- HTTPS_ENABLED=true — enforce CSRF double-submit for cookie auth
+- CORS_STRICT=true — disallow wildcard origins; whitelist your domains via `ALLOWED_ORIGINS`
+- LOG_FORMAT=json — optional JSON log output for production log pipelines
+- MAX_BODY_SIZE_BYTES=1048576 — reject requests with Content-Length above 1 MB
+- STRICT_RESPONSE_ENVELOPE=true — platform APIs return consistent envelopes
+
+Unified cache/DB flags:
+
+- MEM_OR_EXTERNAL=MEM|REDIS — unified flag for cache/DB mode
+- MEM_OR_REDIS — deprecated alias still accepted for backward compatibility
+
+JWT/Token encryption:
+
+- JWT_SECRET_KEY — REQUIRED; gateway fails fast if missing at startup
+- TOKEN_ENCRYPTION_KEY — recommended; encrypts stored API keys and user API keys at rest
+
+Core variables:
+
+- ALLOWED_ORIGINS — comma-separated list of allowed origins
+- ALLOW_CREDENTIALS — set to true only with explicit origins
+- ALLOW_METHODS, ALLOW_HEADERS — scope to what you need
+- JWT_SECRET_KEY — rotate periodically; store in a secret manager
+- MEM_OR_REDIS — MEM or REDIS depending on cache backing
+- MONGO_DB_HOSTS, MONGO_REPLICA_SET_NAME — enable DB in non-memory mode
+
+## Security
+
+- Cookies: access_token_cookie is HttpOnly; set Secure via HTTPS_ONLY. CSRF cookie (`csrf_token`) issued on login/refresh.
+- CSRF: when HTTPS_ENABLED=true, clients must include `X-CSRF-Token` header matching `csrf_token` cookie on protected endpoints.
+- CORS: avoid wildcard with credentials; use explicit allowlists.
+- Logging: includes redaction filter to reduce token/password leakage. Avoid logging PII.
+- Rate limiting: Redis-based limiter; if Redis is unavailable the gateway falls back to a process-local in-memory limiter (non-distributed). Configure user limits in DB/role as needed.
+- Request limits: global Content-Length check; per-route multipart (proto upload) size limits via MAX_MULTIPART_SIZE_BYTES.
+- Response envelopes: `STRICT_RESPONSE_ENVELOPE=true` makes platform API responses consistent for client parsing.
+
+## Health and Monitoring
+
+- Liveness: `GET /platform/monitor/liveness` → `{ status: "alive" }`
+- Readiness: `GET /platform/monitor/readiness` → `{ status, mongodb, redis }`
+- Metrics: `GET /platform/monitor/metrics?range=24h` (auth required; manage_gateway)
+- Logging: `/platform/logging/*` endpoints; requires `view_logs`/`export_logs`
+
+## Deployment
+
+1. Configure `.env` with production values (see above) or environment variables.
+2. Run behind an HTTPS-capable reverse proxy (or enable HTTPS in-process with `HTTPS_ONLY=true` and valid certs).
+3. Set ALLOWED_ORIGINS to your web client domains; set ALLOW_CREDENTIALS=true only when needed.
+4. Provision Redis (recommended) and MongoDB (optional in memory-only mode). In memory mode, enable encryption key for dumps and consider TOKEN_ENCRYPTION_KEY for API keys.
+5. Rotate JWT_SECRET_KEY periodically; plan for key rotation and token invalidation.
+6. Memory-only mode requires a single worker (THREADS=1); multiple workers will have divergent in-memory state.
+
+## Runbooks
+
+- Restarting gateway:
+  - Graceful stop writes a final encrypted memory dump in memory-only mode.
+- Token leakage suspect:
+  - Invalidate tokens (`/platform/authorization/invalidate`), rotate JWT secret if necessary, audit logs (redaction is best-effort).
+- Elevated error rates:
+  - Check readiness endpoint; verify Redis/Mongo health; inspect logs via `/platform/logging/logs`.
+- CORS failures:
+  - Verify ALLOWED_ORIGINS and CORS_STRICT settings; avoid `*` with credentials.
+  - Use Tools → CORS Checker (or POST `/platform/tools/cors/check`) to simulate preflight/actual decisions and view effective headers.
+- CSRF errors:
+  - Ensure clients set `X-CSRF-Token` header to value of `csrf_token` cookie when HTTPS_ENABLED=true.
+
+## Notes
+
+- Gateway (proxy) responses can be optionally wrapped by STRICT_RESPONSE_ENVELOPE; confirm client contracts before enabling globally in front of external consumers.
+- Prefer Authorization: Bearer header for external API consumers to reduce CSRF surface.
+
+## Strict Envelope Examples
+
+When `STRICT_RESPONSE_ENVELOPE=true`, platform endpoints return a consistent structure.
+
+- Success (200):
+```
+{
+  "status_code": 200,
+  "response": { "key": "value" }
+}
+```
+
+- Created (201):
+```
+{
+  "status_code": 201,
+  "message": "Resource created successfully"
+}
+```
+
+- Error (400/403/404):
+```
+{
+  "status_code": 403,
+  "error_code": "ROLE009",
+  "error_message": "You do not have permission to create roles"
+}
+```
+

user-docs/README.md

@@ -2,4 +2,5 @@
 
 - `GET-STARTED-SECURE.md`: Secure setup guide from local to production
 - `END-TO-END-FLOWS.md`: Real-world workflows to publish and operate APIs
-
+- `OPERATIONS.md`: Operations guide for configuration, deployment, runbooks
+- `TOOLS.md`: Tools and diagnostics (CORS checker)

user-docs/TOOLS.md

@@ -0,0 +1,34 @@
+# Tools and Diagnostics
+
+This page describes built-in tools available to help operate and troubleshoot your Doorman gateway.
+
+## CORS Checker
+
+Validate your CORS configuration without trial-and-error in a browser.
+
+- UI: Navigate to `/tools` in the web client (requires `manage_security` permission).
+- API: `POST /platform/tools/cors/check` (requires `manage_security`).
+
+Request body:
+```
+{
+  "origin": "https://app.example.com",
+  "method": "GET",
+  "request_headers": ["Content-Type", "Authorization"],
+  "with_credentials": true
+}
+```
+
+Response highlights:
+- `config`: Effective CORS configuration derived from environment variables.
+- `preflight`: Whether the preflight would be allowed and the headers that would be returned.
+- `actual`: Whether an actual request would be allowed and expected response headers.
+- `notes`: Guidance for common misconfigurations (e.g., wildcard with credentials).
+
+Environment variables considered:
+- `ALLOWED_ORIGINS`, `ALLOW_METHODS`, `ALLOW_HEADERS`, `ALLOW_CREDENTIALS`, `CORS_STRICT`.
+
+Tips:
+- Avoid `*` origins when `ALLOW_CREDENTIALS=true`; explicitly list origins or enable `CORS_STRICT=true`.
+- If `ALLOW_HEADERS='*'` is set with credentials, the gateway applies a conservative default set.
+