From 594e1d96d63a1479355749560a8163bcdc2c19ad Mon Sep 17 00:00:00 2001 From: seniorswe Date: Fri, 26 Sep 2025 22:55:34 -0400 Subject: [PATCH] user guides --- .../platform-logs/doorman-trail.log | 2 + user-docs/OPERATIONS.md | 108 ++++++++++++++++++ user-docs/README.md | 3 +- user-docs/TOOLS.md | 34 ++++++ 4 files changed, 146 insertions(+), 1 deletion(-) create mode 100644 user-docs/OPERATIONS.md create mode 100644 user-docs/TOOLS.md diff --git a/backend-services/platform-logs/doorman-trail.log b/backend-services/platform-logs/doorman-trail.log index d06aa25..b459521 100644 --- a/backend-services/platform-logs/doorman-trail.log +++ b/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"} diff --git a/user-docs/OPERATIONS.md b/user-docs/OPERATIONS.md new file mode 100644 index 0000000..a67c338 --- /dev/null +++ b/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" +} +``` + diff --git a/user-docs/README.md b/user-docs/README.md index c487d0b..48991a9 100644 --- a/user-docs/README.md +++ b/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) diff --git a/user-docs/TOOLS.md b/user-docs/TOOLS.md new file mode 100644 index 0000000..7b72782 --- /dev/null +++ b/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. +