build prospect intelligence platform MVP

docs/OPERATIONS.md

@@ -0,0 +1,67 @@
+# Operations Runbook
+
+## Start, inspect, stop
+
+From the repository root:
+
+```sh
+docker compose up --build -d
+docker compose ps
+docker compose logs --follow api web
+docker compose down
+```
+
+The expected health endpoints are:
+
+- API: `GET http://localhost:8000/healthz`
+- Web: `GET http://localhost:8080/healthz`
+
+A service is ready only when Compose reports `healthy`; container running status alone is insufficient. The API health response includes `"outreach_enabled": false` as an operational safety check.
+
+## Configuration and deployment
+
+Copy `.env.example` for local development. Production values must be supplied by the deployment environment, never committed. Keep `AUTOMATED_OUTREACH_ENABLED=false`; automated outreach is explicitly disabled in this MVP and there is no supported production enablement path in this repository.
+
+Before deployment:
+
+1. Run `docker compose config` and review the rendered configuration.
+2. Build from a reviewed commit and scan the resulting images.
+3. Restrict host/network exposure at the ingress/firewall.
+4. Verify both health checks and review logs for unexpected errors or sensitive data.
+5. Record the image digest and configuration revision for rollback.
+
+## Data, backups, and retention
+
+The canonical API runtime under `apps/api` uses the named Docker volume `prospect-platform-api-data`. Inspect it with `docker volume inspect prospect-platform-api-data`; do not treat a local Docker volume as a backup.
+
+For the current MVP there is no database migration or backup command. If runtime data is material, stop writes first and snapshot/copy the volume using an approved host backup process. Protect backup files with encryption and access controls, test a restore into an isolated environment, and document the result.
+
+Recommended starting policy for a future production data store:
+
+- daily encrypted backups, with at least 30 days of retention;
+- point-in-time recovery where supported;
+- one offline or separately isolated copy;
+- quarterly restore drills, plus a restore test after storage/provider changes;
+- retention and deletion schedules aligned with the source/contact policy and applicable law.
+
+Do not run `docker compose down -v` on a data-bearing environment: it removes the named volume.
+
+## Failure handling
+
+- **Unhealthy API:** inspect `docker compose logs api`, verify port binding and resource availability, then restart with `docker compose restart api` if appropriate.
+- **Unhealthy web:** inspect `docker compose logs web`; confirm port `8080` is available and the image contains `/healthz`.
+- **Build failure:** run `docker compose build --no-cache` from a reviewed checkout and check Docker daemon/network status.
+- **Unexpected outbound traffic:** stop the stack, preserve logs/metadata, and investigate. The MVP has no outreach worker and must not send automated messages.
+
+## Scaling path
+
+Adding Postgres, Redis, workers, or schedulers requires explicit readiness checks, migrations, queue durability/idempotency, secret injection, network segmentation, metrics/alerts, backup/restore procedures, and an operational owner. Do not add them as an implicit Compose dependency: this MVP is intentionally runnable without external Postgres or Redis.
+
+## Incident checklist
+
+1. Record time, affected service, image/config revision, and observed health state.
+2. Preserve relevant logs without exporting secrets or unnecessary contact data.
+3. Stop or isolate the affected service if data loss, unauthorized access, SSRF, or unexpected outreach is suspected.
+4. Rotate exposed credentials through the secret manager.
+5. Validate recovery with health checks and a targeted smoke test.
+6. Document root cause, corrective action, and any retention/suppression impact.

docs/SECURITY.md

@@ -0,0 +1,28 @@
+# Security Notes
+
+## Current safety boundary
+
+- **Automated outreach is disabled.** The compose file sets `AUTOMATED_OUTREACH_ENABLED=false` for both services. The MVP sends no email, SMS, or other outbound communication.
+- No credentials are committed. `.env.example` contains non-secret names and local defaults only.
+- Containers run as an unprivileged user, drop Linux capabilities, use `no-new-privileges`, and use read-only root filesystems. The API data volume is the only intended writable persistent location.
+- The stdlib API is a health/smoke service, not a production security boundary. It has no user authentication, authorization, CSRF protection, rate limiting, or audit log implementation.
+
+## Known limitations before production
+
+1. **Authentication and authorization:** add an identity provider/session or signed-token design, enforce authorization server-side on every protected route, rotate sessions/tokens, and test tenant isolation.
+2. **CSRF:** browser state-changing endpoints must use same-site cookies plus CSRF tokens (or a rigorously reviewed equivalent). Do not rely on CORS as CSRF protection.
+3. **SSRF:** any future URL fetcher must allow only `http`/`https`, validate DNS/IP targets, block loopback/private/link-local/cloud-metadata ranges after resolution, limit redirects, enforce size/time limits, and re-check each redirect. Never fetch arbitrary user-provided URLs from the server without these controls.
+4. **Input/output safety:** validate schema and content types, bound request sizes, parameterize database queries, escape output, and avoid logging contact data or secrets.
+5. **Secrets:** inject production secrets from a secret manager or orchestrator secret store. Do not place them in images, Compose files, source, CI logs, or committed `.env` files.
+6. **Transport and perimeter:** terminate TLS at a trusted ingress, restrict exposed ports, add network policy, and place admin surfaces behind appropriate access controls.
+7. **Data protection:** define retention and deletion rules for prospect/contact data, restrict volume access, encrypt backups, and maintain an access/audit trail.
+
+## Source and contact policy
+
+Treat discovered business information as potentially personal or copyrighted data. Collect only what is needed for the documented product purpose, preserve source attribution where required, respect site terms and robots/access policies, and provide suppression/deletion handling. Do not infer consent to contact from public availability. Any future outreach feature requires an explicit product/legal review and must remain off by default.
+
+## CI/dependency hygiene
+
+Pin or review base-image and dependency updates, scan images before release, use least-privilege GitHub tokens, and avoid printing environment values. CI in this MVP performs build and health checks; it is not a substitute for a security assessment.
+
+Report vulnerabilities privately to the repository maintainers; do not include live credentials or personal data in an issue.