# Cloak Harbor Personal Exposure Defense — Full Machine Reference

> AI-native operating layer for Personal Exposure Defense. Authorized-local self-case cockpit with deterministic synthetic fallback. Defensive posture only.

## Mission
Cloak Harbor is the operating layer for Personal Exposure Defense (PED): an authorized operator protects a consented principal by discovering public exposure, validating it with evidence, scoring it (StealthScore), remediating via human-approved action packets, and reporting outcomes. It is explicitly NOT a people-search, doxxing, or surveillance tool.

Magic rule: One authorized client, one real exposure-defense loop, zero fake actions.

## UI scaffold state
The UI phase exposes the full cockpit flow while remaining honest about wiring. Scaffolded surfaces are labeled, sample data is synthetic unless a consented self-case is loaded, and outside-world actions require human approval plus protected server-side authorization. Report handoffs can call Docs, Sheets, Files, BrowserOps, and Sandbox through server-to-server PlatPhorm APIs using the server environment PLATPHORM_API_KEY. No UI control sends SMS, email, Jitsi invitations, Cloudflare changes, AWS uploads, takedown submissions, or partner/legal notices.

Routes: /, /case, /case/intake, /case/exposures, /case/evidence, /case/risk, /case/kanban, /case/calendar, /case/actions, /communications, /meeting, /provisioning, /portal/customer, /portal/management, /case/report, /case/trace, /integrations, /screenshots, /settings, /docs, /api/docs

## Capability support model
GET https://cloak.platphormnews.com/api/v1/capabilities returns the full Personal Exposure Defense OS capability catalog, route-to-capability bindings, loop-stage coverage, sensitive-action matrix, and runtime support state. Local development can set CLOAK_BACKEND_MODE=postgres and DATABASE_URL. Vercel production can attach Neon/Postgres with DATABASE_URL. Deployments without DATABASE_URL intentionally degrade to deterministic fixture mode and must say so.

GET https://cloak.platphormnews.com/api/v1/setup reports backend persistence status. POST https://cloak.platphormnews.com/api/v1/setup requires PLATPHORM_API_KEY and initializes Postgres-backed tables for capability support, loop checkpoints, protected intents, principal profiles, evidence records, case findings, and case tasks. On Vercel this is the production setup path after DATABASE_URL is provisioned.

POST https://cloak.platphormnews.com/api/v1/workloads/self-case requires PLATPHORM_API_KEY, selfConsent:true, displayName, and Postgres persistence. It creates a protected authorized-local principal profile, redacted public principal summary, intake evidence metadata, bounded discovery observation evidence, redacted public case findings, case tasks, and protected audit intent. It does not enrich, message, publish, upload, submit, or touch external providers. externalActionTaken remains false.

GET https://cloak.platphormnews.com/api/v1/principal, GET https://cloak.platphormnews.com/api/v1/principals/{id}, GET https://cloak.platphormnews.com/api/v1/evidence, GET https://cloak.platphormnews.com/api/v1/evidence/{id}, GET https://cloak.platphormnews.com/api/v1/findings, and GET https://cloak.platphormnews.com/api/v1/kanban read Postgres-backed authorized-local self-case records when present; otherwise they fall back to the synthetic demo dataset with dataMode/status metadata. Public principal and evidence responses redact authorized-local details. Protected detail fields require PLATPHORM_API_KEY. POST https://cloak.platphormnews.com/api/v1/kanban/tasks and POST https://cloak.platphormnews.com/api/v1/kanban/tasks/{id}/move require PLATPHORM_API_KEY and persist only local case task state.

GET https://cloak.platphormnews.com/api/v1/risk/summary, GET https://cloak.platphormnews.com/api/v1/stealthscore, GET https://cloak.platphormnews.com/api/v1/calendar, and GET https://cloak.platphormnews.com/api/v1/reports derive from the active case-state store when authorized-local self-case records exist; otherwise they return honest fixture-backed degraded/demo mode metadata. Risk and reports are explainable, deterministic, and externalActionTaken:false.

GET https://cloak.platphormnews.com/api/v1/actions lists case-derived action packets from the Postgres action-packet store when configured, with synthetic/generated packet candidates as an honest fallback. POST https://cloak.platphormnews.com/api/v1/action-packets/draft requires PLATPHORM_API_KEY, derives the finding from active case state, generates a dry-run draft, persists cloak_action_packets when Postgres is configured, and records an action_packet_draft protected intent. POST https://cloak.platphormnews.com/api/v1/actions/{id}/approve and /reject require PLATPHORM_API_KEY and update the persisted packet decision. POST https://cloak.platphormnews.com/api/v1/actions/{id}/send never sends externally; it records external_send_blocked when possible and returns an honest blocked/not-configured response. externalActionTaken remains false.

GET https://cloak.platphormnews.com/api/v1/loop returns the defense loop ledger: principal, discovery, evidence, risk, work, cadence, action, approval, report, and recurrence, each with proof, route, state, and externalActionTaken:false.

POST https://cloak.platphormnews.com/api/v1/loop requires PLATPHORM_API_KEY and records a Postgres checkpoint of the active exposure-defense ledger when DATABASE_URL is configured. Without Postgres it returns postgres_not_configured and does not fake persistence.

GET https://cloak.platphormnews.com/api/v1/intents returns the protected intent ledger: dry-run action drafts, approvals, rejections, blocked external sends, report generation, report review, and blocked report publish/export/upload attempts persisted in Postgres. Without Postgres it returns postgres_not_configured and an empty ledger instead of fake history.

GET https://cloak.platphormnews.com/api/v1/operator/workflows/self-case reports Vercel Workflow readiness for the durable authorized self-case pipeline. POST https://cloak.platphormnews.com/api/v1/operator/workflows/self-case uses the server environment PLATPHORM_API_KEY, requires Postgres, queues the durable self-case workflow only on Vercel Workflow runtime, and records workflow_start_queued or workflow_start_blocked in the protected intent ledger. Local Docker/dev returns workflow_runtime_not_available instead of pretending a durable workflow was queued.

POST https://cloak.platphormnews.com/api/v1/reports/RPT-EXEC-001/review requires PLATPHORM_API_KEY and records a human report-review intent for the active case-derived executive report. POST https://cloak.platphormnews.com/api/v1/reports/RPT-EXEC-001/publish-docs, /export-sheets, /upload-files, /run-browserops, and /run-sandbox require PLATPHORM_API_KEY on the incoming Cloak request, generate redacted AI/template guidance, and call the matching PlatPhorm service server-to-server with the server environment PLATPHORM_API_KEY. The response reports handoff status, downstreamActionTaken, externalActionTaken, AI guidance source, and persisted audit intent.

GET https://cloak.platphormnews.com/api/v1/integrations and GET https://cloak.platphormnews.com/api/v1/integrations/status return the runtime integration registry, not static fixtures. The registry reports local Postgres-backed case features, platform handoff readiness, missing env names, supported actions, target endpoints, dataMode, and externalActionTaken:false. Protected platform handoffs require the server environment PLATPHORM_API_KEY; CLOAK_ENABLE_PLATFORM_HANDOFFS is an optional kill switch when explicitly set to 0, false, FALSE, or off.

POST https://cloak.platphormnews.com/api/v1/integrations/{service}/{action} requires PLATPHORM_API_KEY and records a protected integration intent. Docs publish, Sheets export, Files upload, BrowserOps run/capture, and Sandbox run/replay delegate to the real report handoff executor. Unsupported actions return integration_action_not_found. Missing configuration returns integration_not_configured with the missing env list. Configured service/action pairs without an executor return integration_executor_not_implemented instead of pretending work happened.

## Domain objects
### ExposureFinding
findingId, principalId, title, sourceClass (broker | breach | social | public-record | search | paste | image), severity (critical | high | medium | low), status (new | triaged | action-ready | in-progress | mitigated | recurring | wont-fix), confidence (0-1), discoveredAt, summary, evidence[], riskFactors{}, recommendedAction.

### Evidence
evidenceId, type (url | screenshot | api-response | document | hash), capturedAt, integrityHash, validatedBy, note. All demo evidence references reserved/fictional identifiers.

### Principal (consented subject)
principalId, displayName (synthetic), roleContext, aliases[], entities[], consentScope, approvalRules. Demo principal: Jordan Hale (synthetic-principal-001).

### CaseTask (remediation)
taskId, findingId, lane (triage | drafting | awaiting-approval | submitted | verifying | closed), owner, dueAt.

### ActionPacket
packetId, findingId, channel (broker-optout | suppression | legal-notice | platform-report), draftText, draftSource (ai-gateway | template-fallback), aiDraft (bool), approvalState (draft | pending-approval | approved | rejected | submitted-dry-run). External submission is always DRY-RUN pending human approval.

## StealthScore rubric (sigreduce-rubric-0.3-demo, 0-100, lower = safer)
- severity (weight 0.22): Severity
- confidence (weight 0.12): Confidence
- physicalRisk (weight 0.18): Physical proximity
- fraudUtility (weight 0.14): Fraud utility
- familyExposure (weight 0.12): Family exposure
- socialEngineeringValue (weight 0.12): Social-engineering leverage
- recurrenceLikelihood (weight 0.1): Recurrence likelihood

Projected post-remediation scores are deterministic planning estimates labeled by calibration mode: demo or case-derived.

## Events (outbox model)
Event types: finding.discovered, finding.validated, finding.triaged, packet.drafted, packet.approved, packet.submitted_dryrun, score.recalculated. Each event: id, type, occurredAt, principalId, payload. Consume at GET https://cloak.platphormnews.com/api/events.

## Webhooks
POST https://cloak.platphormnews.com/api/webhooks — signed (HMAC x-cloak-signature), idempotent (x-idempotency-key), retryable. n8n-compatible JSON payloads.

## Auth & limits
- Read endpoints: public-safe synthetic data or redacted authorized-local case data.
- State-changing endpoints: Authorization: Bearer $PLATPHORM_API_KEY or X-PlatPhorm-API-Key must equal PLATPHORM_API_KEY (server-side only; never exposed client-side).
- Rate limiting and request fingerprinting (request_id, tenant_id, route, latency) applied at the edge in production.

## Guardrails
- AI drafts notices only, in dry-run, always labeled "AI-drafted".
- Every external action requires explicit human approval.
- If the AI Gateway is unavailable, drafting degrades to deterministic templates labeled "template fallback". Output is never fabricated.

## Links
- OpenAPI: https://cloak.platphormnews.com/openapi.yaml
- OpenAPI JSON: https://cloak.platphormnews.com/openapi.json
- Docs: https://cloak.platphormnews.com/docs
- Responsible use: https://cloak.platphormnews.com/docs/responsible-use
- Index: https://cloak.platphormnews.com/llms-index.json