@yiaany/ghostapi 0.1.7 → 0.1.8

package/README.md

@@ -1,7 +1,3 @@
-<p align="center">
-  <img src="docs/assets/ghostapi-avatar.png" alt="GhostAPI" width="104" height="104">
-</p>
-
 <h1 align="center">GhostAPI</h1>
 
 <p align="center">
@@ -9,7 +5,7 @@
 </p>
 
 <p align="center">
-  A local API sandbox, dashboard, and MCP control plane for building third-party integrations without touching production.
+  Build and test third-party API integrations locally, without charging cards, sending messages, leaking production keys, or mutating real services.
 </p>
 
 <p align="center">
@@ -17,15 +13,16 @@
   <a href="https://github.com/yiaany/ghostapi/blob/main/LICENSE"><img alt="license" src="https://img.shields.io/badge/license-MIT-0f172a"></a>
   <a href="https://github.com/yiaany/ghostapi/actions/workflows/ci.yml"><img alt="ci" src="https://github.com/yiaany/ghostapi/actions/workflows/ci.yml/badge.svg"></a>
   <img alt="node" src="https://img.shields.io/badge/node-%3E%3D20-0f172a">
-  <img alt="mcp" src="https://img.shields.io/badge/MCP-enabled-0f172a">
+  <img alt="MCP" src="https://img.shields.io/badge/MCP-enabled-0f172a">
 </p>
 
 <p align="center">
   <a href="#quickstart">Quickstart</a> ·
-  <a href="#mcp-setup">MCP Setup</a> ·
-  <a href="#how-it-works">How It Works</a> ·
-  <a href="#sdk-recipes">SDK Recipes</a> ·
-  <a href="#contributing">Contributing</a>
+  <a href="#what-you-get">Features</a> ·
+  <a href="#provider-support">Providers</a> ·
+  <a href="#mcp-for-agents">MCP</a> ·
+  <a href="#safety-boundaries">Safety</a> ·
+  <a href="#hosted-and-enterprise">Enterprise</a>
 </p>
 
 ```bash
@@ -33,113 +30,144 @@ npx @yiaany/ghostapi start --open
 ```
 
 <p align="center">
-  <img src="docs/assets/dashboard.png" alt="GhostAPI dashboard showing local API traffic">
+  <img src="docs/assets/dashboard.png" alt="GhostAPI dashboard with live local Stripe, OpenAI, and REST traffic">
 </p>
 
-## The Problem
+## Why GhostAPI
 
-AI coding agents are now strong enough to write Stripe checkouts, OpenAI workflows, GitHub automations, Twilio messaging, and email integrations. The dangerous part is that they also run the code they write.
+Coding agents can write a Stripe checkout, an OpenAI workflow, a GitHub automation, or an email integration in minutes. The dangerous part is what happens when they run that code.
 
-That creates a bad default loop:
+Without a safe local target, a test can:
 
-| Agent action | Production risk |
-| --- | --- |
-| Tests a Stripe flow | Real money movement or broken payment state. |
-| Tests Twilio or Resend | Real SMS or email sent to real people. |
-| Tests GitHub automation | Real issues, branches, releases, or repo mutations. |
-| Tests OpenAI calls | Real token spend and possible prompt/data leakage. |
-| Logs request/response payloads | Secrets leak into terminals, prompts, screenshots, or cache. |
-
-GhostAPI gives agents a local universe where integrations behave like real providers, but every request stays on your machine.
-
-## What GhostAPI Does
-
-GhostAPI is a local API control layer for agent-driven development.
-
-<table>
-  <tr>
-    <td><strong>Local API Sandbox</strong><br>Run provider-shaped APIs on <code>127.0.0.1:8080</code> instead of live Stripe, OpenAI, Twilio, Resend, GitHub, Discord, or random REST services.</td>
-    <td><strong>Live Dashboard</strong><br>Watch every request, inspect request and response bodies, replay scenarios, generate setup snippets, and verify what your agent actually did.</td>
-  </tr>
-  <tr>
-    <td><strong>MCP Control Plane</strong><br>Let agents inspect state, read traffic logs, force deterministic responses, and toggle Chaos Mode through MCP tools.</td>
-    <td><strong>Safe Failure Testing</strong><br>Force card declines, rate limits, upstream errors, latency, and provider-shaped edge cases without waiting for real APIs to fail.</td>
-  </tr>
-  <tr>
-    <td><strong>Secret Masking</strong><br>Mask secret-looking headers, query params, bodies, cache keys, dashboard payloads, events, and prompt inputs.</td>
-    <td><strong>Repo Setup Generator</strong><br>Generate MCP config, agent instructions, environment snippets, and SDK patches for the current project.</td>
-  </tr>
-</table>
+- charge a real card;
+- send a real email or SMS;
+- create or modify real GitHub resources;
+- spend API credits;
+- leak credentials into logs, prompts, screenshots, or test fixtures.
+
+GhostAPI gives your application and coding agent a local API world at `127.0.0.1:8080`. Requests are detected, sanitized, recorded, and answered with deterministic provider-shaped responses. You can inspect the result in the dashboard, control behavior through MCP, and turn failures into repeatable tests.
 
 ## Quickstart
 
-Run GhostAPI instantly:
+Start the local server and dashboard:
 
 ```bash
 npx @yiaany/ghostapi start --open
 ```
 
-Install globally:
+Send a Stripe-shaped request:
 
 ```bash
-npm i -g @yiaany/ghostapi
-ghostapi start --open
+curl -X POST http://127.0.0.1:8080/v1/customers \
+  -H "content-type: application/json" \
+  -H "authorization: Bearer stripe_test_ghostapi" \
+  -d '{"email":"ada@example.com","name":"Ada Lovelace"}'
 ```
 
-Open the dashboard:
+Open the dashboard at `http://127.0.0.1:8080/dashboard`. The request appears in live traffic with its provider, request body, generated response, source, status, and timing.
 
-```text
-http://127.0.0.1:8080/dashboard
-```
-
-Health check:
+Initialize GhostAPI inside an existing repository:
 
 ```bash
-curl http://127.0.0.1:8080/health
+npx @yiaany/ghostapi init
+npx @yiaany/ghostapi doctor
 ```
 
-## 30 Second Demo
+`init` creates local configuration, a versioned safety policy, MCP snippets, and agent instructions without overwriting existing files.
 
-Start the local API world:
+On a supported Linux host, run a command inside the loopback-only network namespace:
 
 ```bash
-npx @yiaany/ghostapi start --open
+npx @yiaany/ghostapi run -- npm test
 ```
 
-Send a Stripe-shaped request locally:
+On Windows and macOS, `ghostapi run` fails closed because an equivalent process-isolation backend is not implemented. The local API server and dashboard still work normally.
 
-```bash
-curl -X POST http://127.0.0.1:8080/v1/customers \
-  -H "content-type: application/json" \
-  -H "authorization: Bearer stripe_test_ghostapi" \
-  -d '{"email":"ada@example.com","name":"Ada Lovelace"}'
-```
+## What You Get
 
-Inspect the captured request in the dashboard:
+| Feature | What it does |
+| --- | --- |
+| Local API sandbox | Gives SDKs and applications a local target instead of a live provider. |
+| Provider-shaped behavior | Returns realistic objects, validation errors, rate limits, declines, and failure payloads. |
+| Live dashboard | Shows requests and responses, filters traffic by provider, generates tests, and arms scenarios. |
+| MCP control plane | Lets compatible coding agents inspect state, read traffic, configure responses, and toggle Chaos Mode. |
+| Stateful synthetic worlds | Maintains deterministic local identities and state across Stripe, GitHub, email, and REST projections. |
+| Scenarios and record/replay | Saves sanitized sandbox traffic and replays it offline as deterministic fixtures. |
+| Contract drift checks | Imports bounded OpenAPI/HAR contracts and classifies breaking, non-breaking, and uncertain changes. |
+| Agent evals and evidence | Produces redacted, tamper-evident reports for local review and CI policy gates. |
+| Secret protection | Masks secret-shaped headers, query parameters, bodies, paths, events, prompts, and cache inputs. |
+| Fault testing | Forces latency, provider errors, card declines, rate limits, and other unhappy paths. |
+| Safety controls | Includes local approvals, scoped budgets, kill switches, circuit breakers, ledgers, and reconciliation for synthetic actions. |
+| Reliability tooling | Tracks local SLO samples, cost attribution, runtime health, backups, inventory, and attack-path metadata. |
 
-```text
-http://127.0.0.1:8080/dashboard
+## Dashboard
+
+The dashboard is the fastest way to understand what an agent or application actually did.
+
+- Watch traffic arrive in real time over SSE.
+- Inspect sanitized request and response JSON.
+- Filter by Stripe, Twilio, Resend, GitHub, Discord, OpenAI, or generic REST.
+- Generate a Vitest test from a captured request.
+- Generate and copy setup files for supported coding agents.
+- Arm deterministic scenario presets.
+- Toggle Chaos Mode and inspect the local safety report.
+
+Dashboard and API routes are token-protected on every non-loopback bind. Use HTTPS or a secure tunnel when exposing GhostAPI beyond localhost.
+
+## Provider Support
+
+GhostAPI has two levels of provider support.
+
+### Stateful provider packs
+
+| Provider | Included behavior |
+| --- | --- |
+| Stripe | Customers, products, prices, subscriptions, invoices, payment intents, payment methods, checkout sessions, refunds, pagination, lifecycle scenarios, and signed local webhooks. |
+| Resend | Deterministic email-shaped requests, responses, validation, and failure behavior. |
+
+### Provider-shaped adapters and generic inference
+
+OpenAI, Twilio, GitHub, Discord, and generic REST routes are detected and receive provider-shaped mock responses and errors. These adapters are useful for local development, but they do not claim complete parity with every live-provider endpoint.
+
+Unsupported endpoints fail diagnostically instead of silently pretending that an operation succeeded.
+
+## SDK Setup
+
+Stripe:
+
+```ts
+import Stripe from "stripe";
+
+export const stripe = new Stripe(
+  process.env.STRIPE_SECRET_KEY ?? "stripe_test_ghostapi",
+  {
+    host: process.env.GHOSTAPI_HOST ?? "127.0.0.1",
+    port: Number(process.env.GHOSTAPI_PORT ?? "8080"),
+    protocol: process.env.GHOSTAPI_PROTOCOL ?? "http"
+  }
+);
 ```
 
-## One-Command Repo Setup
+OpenAI:
 
-Run setup inside any project:
+```ts
+import OpenAI from "openai";
 
-```bash
-npx @yiaany/ghostapi setup --write
+export const openai = new OpenAI({
+  apiKey: process.env.OPENAI_API_KEY ?? "sk-ghostapi",
+  baseURL: process.env.GHOSTAPI_OPENAI_BASE_URL ?? "http://127.0.0.1:8080/v1"
+});
 ```
 
-This generates local setup assets for agent workflows:
+Generic REST:
 
-| Output | Why it matters |
-| --- | --- |
-| Agent instructions | Tell coding agents to keep provider calls local. |
-| MCP snippets | Configure Cursor, Claude, Cline, Aider, Codex, OpenCode, Gemini CLI, Goose, OpenClaw, Hermes, and generic MCP clients. |
-| Environment snippets | Point SDKs at `http://127.0.0.1:8080`. |
-| SDK patches | Show how to route Stripe and OpenAI SDKs into GhostAPI. |
-| Safety guidance | Warn before live providers or live-looking keys enter the loop. |
+```bash
+curl -X POST http://127.0.0.1:8080/tasks \
+  -H "content-type: application/json" \
+  -d '{"title":"Add integration tests","status":"open"}'
+```
 
-## MCP Setup
+## MCP For Agents
 
 Start the MCP server:
 
@@ -147,7 +175,7 @@ Start the MCP server:
 npx @yiaany/ghostapi mcp
 ```
 
-Universal MCP config:
+Generic MCP configuration:
 
 ```json
 {
@@ -160,158 +188,153 @@ Universal MCP config:
 }
 ```
 
-Agent prompt:
-
-```text
-Use the GhostAPI MCP server.
-
-Keep all third-party API calls local on http://127.0.0.1:8080.
-Do not call real providers.
-
-Use GhostAPI MCP tools to inspect state, read traffic logs, configure deterministic responses, and test failure scenarios.
-```
-
-MCP tools:
+Available tools:
 
 | Tool | Purpose |
 | --- | --- |
-| `inspect_state` | Read local API objects from `.ghostapi/state.json`. |
-| `get_traffic_logs` | Inspect recent local traffic. |
-| `set_api_behavior` | Force deterministic responses for `method + path`. |
-| `toggle_chaos_mode` | Enable local latency and provider-shaped errors. |
+| `inspect_state` | Read current local API objects. |
+| `get_traffic_logs` | Inspect sanitized recent traffic. |
+| `set_api_behavior` | Force a deterministic response for a method and path. |
+| `toggle_chaos_mode` | Enable or disable local latency and failure injection. |
 
-## How It Works
+Generate setup snippets for Cursor, Claude, Cline, Aider, Codex, OpenCode, Gemini CLI, Goose, OpenClaw, Hermes, and generic MCP clients:
 
-```text
-Your app or agent
-  -> http://127.0.0.1:8080
-  -> GhostAPI proxy
-  -> provider detection
-  -> local state / scenarios / deterministic behavior
-  -> dashboard + MCP inspection
+```bash
+npx @yiaany/ghostapi setup --write
 ```
 
-GhostAPI does five things in the loop:
+## Scenarios, Contracts, And Evals
 
-| Step | What happens |
-| --- | --- |
-| Detect | It infers the provider from routes, headers, SDK shapes, and request bodies. |
-| Normalize | It converts requests into safe, inspectable local events. |
-| Mask | It strips secret-looking values before logs, cache, dashboard, and prompts. |
-| Respond | It returns provider-shaped mock responses, errors, or saved state. |
-| Control | MCP and dashboard tools let agents force behavior and replay flows. |
+Record approved sandbox traffic into a sanitized offline bundle:
 
-## SDK Recipes
-
-Stripe:
+```bash
+ghostapi record \
+  --input capture.har \
+  --allow-sandbox-host api.sandbox.example \
+  --approve
+```
 
-```ts
-import Stripe from "stripe";
+Replay it without network access:
 
-export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY ?? "stripe_test_ghostapi", {
-  host: process.env.GHOSTAPI_HOST ?? "127.0.0.1",
-  port: Number(process.env.GHOSTAPI_PORT ?? "8080"),
-  protocol: process.env.GHOSTAPI_PROTOCOL ?? "http"
-});
+```bash
+ghostapi replay bundle.json --requests requests.json
 ```
 
-OpenAI:
+Import and compare API contracts:
 
-```ts
-import OpenAI from "openai";
+```bash
+ghostapi contract import-openapi --input openapi.json
+ghostapi contract diff \
+  --baseline base.contract.json \
+  --candidate head.contract.json \
+  --policy ghostapi.policy.yaml \
+  --ci
+```
 
-export const openai = new OpenAI({
-  apiKey: process.env.OPENAI_API_KEY ?? "sk-ghostapi",
-  baseURL: process.env.GHOSTAPI_OPENAI_BASE_URL ?? "http://127.0.0.1:8080/v1"
-});
+Generate sanitized CI evidence:
+
+```bash
+ghostapi evidence generate --policy ghostapi.policy.yaml --ci
 ```
 
-Generic REST:
+Run a deterministic agent eval:
 
 ```bash
-curl -X POST http://127.0.0.1:8080/tasks \
-  -H "content-type: application/json" \
-  -d '{"title":"Write integration tests","status":"open"}'
+ghostapi eval \
+  --template retry-after \
+  --evidence .ghostapi/reports/latest.json \
+  --ci
 ```
 
-## Built For
+## Safety Boundaries
 
-| Audience | Use GhostAPI to |
-| --- | --- |
-| AI coding agents | Build integrations without accidentally touching production. |
-| SaaS developers | Test provider happy paths and failure paths locally. |
-| API-heavy teams | Turn captured traffic into repeatable scenarios and tests. |
-| Open-source maintainers | Give contributors safe examples that do not require live provider accounts. |
+GhostAPI is designed to fail closed, but its boundaries are explicit:
 
-## Safety Model
+- Real provider calls are disabled by default.
+- Ambient `OPENAI_API_KEY` does not enable external generation.
+- External LLM generation requires an explicit flag plus a separate `GHOSTAPI_LLM_API_KEY`.
+- Non-loopback access requires a strong dashboard token.
+- External response redirects, unsafe response headers, traversal, remote schema references, symlinks, archives, and oversized inputs are rejected where applicable.
+- Persistent stores have size, entry, retention, or rotation limits.
+- The Linux `run` backend provides loopback-only process network isolation when namespace preflight succeeds.
+- `run` is not a hostile-code filesystem sandbox.
+- Secret masking is heuristic. Use synthetic credentials and data even in local fixtures.
+- Local approval, action, credential, ledger, trust, and safety components execute synthetic operations only. They are not a production-provider executor.
 
-- No real provider calls by default.
-- Keep SDKs pointed at `http://127.0.0.1:8080`.
-- Use fake local keys like `stripe_test_ghostapi` and `sk-ghostapi`.
-- Secrets are masked before logs, cache, dashboard, events, and prompts.
-- Chaos Mode is opt-in.
-- Local state lives under `.ghostapi/` and is gitignored.
+Read the detailed threat models in [`docs/security`](docs/security) and the reporting policy in [`SECURITY.md`](SECURITY.md).
 
-## Local Files
+## Platform Support
 
-| Path | Purpose |
-| --- | --- |
-| `.ghostapi/config.json` | Local GhostAPI config. |
-| `.ghostapi/state.json` | Simulated API object state. |
-| `.ghostapi/events.jsonl` | Captured local request events. |
-| `.ghostapi/behaviors.json` | Deterministic behavior overrides. |
-| `.ghostapi/cache/` | Local response cache. |
+| Platform | Local API and dashboard | `ghostapi run` enforcement |
+| --- | --- | --- |
+| Linux | Supported on Node.js 20+ | Supported when `unshare`, `iproute2`, and namespace preflight pass. |
+| Windows | Supported on Node.js 20+ | Not implemented; fails closed. |
+| macOS | Supported on Node.js 20+ | Not implemented; fails closed. |
 
-## CLI Reference
+Check the current machine:
 
 ```bash
-npx @yiaany/ghostapi start --open
-npx @yiaany/ghostapi open
-npx @yiaany/ghostapi setup --write
-npx @yiaany/ghostapi mcp
-npx @yiaany/ghostapi report
-npx @yiaany/ghostapi doctor --port 8080
-npx @yiaany/ghostapi clear cache|state|events|all
-npx @yiaany/ghostapi providers list
-npx @yiaany/ghostapi providers inspect stripe
+ghostapi doctor --json
+ghostapi doctor --egress
 ```
 
-## Repository About
-
-Use this for the GitHub repository description:
+## Health Endpoints
 
 ```text
-The local internet for AI coding agents. Simulate Stripe, OpenAI, Twilio, Resend, GitHub, Discord, and REST APIs locally with a dashboard, MCP tools, scenarios, and secret masking.
+GET /health             process liveness, HTTP 200 while state can be evaluated
+GET /health/readiness   structural readiness, HTTP 503 when a required store is unsafe
 ```
 
-Recommended topics:
+## Hosted And Enterprise
 
-```text
-mcp, ai-agents, stripe, openai, mock-server, api-testing, sandbox, proxy, local-development, typescript, cursor
-```
+The `hosted/` directory contains an implemented but not yet deployed team pilot. It includes:
 
-## Docs
+- organizations, projects, invitations, memberships, and role-based access;
+- tenant-safe report and scenario APIs;
+- hashed and rotatable CI ingest keys;
+- bounded request handling, CSRF checks, security headers, quotas, and abuse limits;
+- PostgreSQL migrations, idempotency, outbox dispatch, worker leases, retries, dead letters, and retention cleanup;
+- Redis-backed rate limiting, QStash verification, readiness checks, and a non-root Docker image.
 
-- [MCP setup](docs/mcp.md)
-- [Usage guide](docs/usage.md)
-- [Release checklist](docs/release-checklist.md)
-- [Contributing](CONTRIBUTING.md)
-- [Security policy](SECURITY.md)
-
-## Contributing
+It is not advertised as a production SaaS yet. Live OAuth, Redis, QStash, load, failover, backup/restore, and disaster-recovery behavior must still be proven in staging before a paid pilot.
 
-Contributions are welcome. GhostAPI should stay local-first, safe by default, and useful for real agent workflows.
+The detailed product plan for a complete enterprise edition is available in [`docs/enterprise-product-roadmap-ru.md`](docs/enterprise-product-roadmap-ru.md).
 
-Before opening a pull request:
+## Development
 
 ```bash
+npm ci
+npm run lint
 npm run typecheck
 npm test
 npm run build
+npm run smoke:package
 ```
 
-Do not add tests or examples that call live providers by default. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.
+Hosted pilot checks:
+
+```bash
+cd hosted
+npm ci
+npm run check
+```
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md), [`docs/release-readiness.md`](docs/release-readiness.md), and [`docs/development/verification-0.1.8.md`](docs/development/verification-0.1.8.md) for the complete verification boundary.
+
+## Documentation
+
+- [Usage guide](docs/usage.md)
+- [MCP setup](docs/mcp.md)
+- [Policy reference](docs/policy.md)
+- [GitHub Actions integration](docs/github-actions.md)
+- [Generic CI integration](docs/ci.md)
+- [Stripe provider pack](docs/providers/stripe-core-pack.md)
+- [Security policy](SECURITY.md)
+- [Threat models](docs/security)
+- [Release readiness](docs/release-readiness.md)
+- [Migration and rollback](docs/release-migration-and-rollback.md)
+- [Enterprise roadmap in Russian](docs/enterprise-product-roadmap-ru.md)
 
 ## License
 
-MIT. See [LICENSE](LICENSE).
+MIT. See [`LICENSE`](LICENSE).

package/SECURITY.md

@@ -1,37 +1,53 @@
-# Security Policy
-
-GhostAPI exists to make local integration development safer. Security-sensitive behavior should be treated as core product behavior, not an afterthought.
-
-## Supported Versions
-
-GhostAPI is pre-1.0. Security fixes target the current `main` branch and the latest published package once releases begin.
-
-## Safety Model
-
-- GhostAPI does not make real external provider API calls by default.
-- Incoming requests are normalized and sanitized before use in prompts, cache keys, logs, or dashboard events.
-- Secret-looking fields are masked, including `authorization`, `api_key`, `apikey`, `x-api-key`, `access_token`, `refresh_token`, `client_secret`, `password`, `secret`, `token`, and `key`.
-- Known token patterns are masked, including Stripe keys, GitHub tokens, Slack bot tokens, SendGrid keys, and bearer tokens.
-- Local cache entries are stored under `.ghostapi/cache/{provider}/{hash}.json`.
-- Local state is stored under `.ghostapi/state.json`.
-- `ghostapi doctor` warns when `NODE_TLS_REJECT_UNAUTHORIZED=0` is set.
-
-## Reporting A Vulnerability
-
-Please do not open a public issue for a vulnerability.
-
-Until a dedicated security email is published, report privately to the project maintainer or repository owner and include:
-
-- A clear description of the issue.
-- Steps to reproduce.
-- Expected impact.
-- Whether secrets, prompts, cache, state, dashboard events, or network behavior are involved.
-- Suggested fix, if you have one.
-
-We will acknowledge valid reports as quickly as possible and prioritize fixes that could leak secrets, trigger real external calls unexpectedly, or expose local data.
-
-## Out Of Scope
-
-- Issues requiring malicious local filesystem access outside GhostAPI's process permissions.
-- Vulnerabilities in unsupported Node.js versions.
-- Reports without reproduction details.
+# Security Policy
+
+GhostAPI exists to make local integration development safer. Security-sensitive behavior should be treated as core product behavior, not an afterthought.
+
+## Supported Versions
+
+GhostAPI is pre-1.0. Security fixes target the current `main` branch and the latest published package once releases begin.
+
+## Safety Model
+
+- GhostAPI does not make real external provider API calls by default.
+- External LLM generation requires explicit `--allow-external-llm` or `GHOSTAPI_ALLOW_EXTERNAL_LLM=true` plus `GHOSTAPI_LLM_API_KEY`. Ambient `OPENAI_API_KEY` is ignored by the GhostAPI runtime.
+- Incoming requests are normalized and sanitized before use in prompts, cache keys, logs, or dashboard events.
+- Secret-looking fields are masked, including `authorization`, `api_key`, `apikey`, `x-api-key`, `access_token`, `refresh_token`, `client_secret`, `password`, `secret`, `token`, and `key`.
+- Known token patterns are masked, including Stripe keys, GitHub tokens, Slack bot tokens, SendGrid keys, and bearer tokens.
+- State, behaviors, scenarios, and events are sanitized again at persistence boundaries. Cache keys are derived from sanitized requests; cached generated responses preserve provider response fidelity.
+- Runtime data defaults to `.ghostapi/` and can be isolated with `GHOSTAPI_DATA_DIR`.
+- JSON stores use adjacent inter-process lock files and same-directory temporary-file replacement to avoid covered local lost-update and partial-write scenarios.
+- The persisted event log rotates at 5 MiB, retaining two archives. Individual persisted event details are limited to 256 KiB.
+- Non-loopback binds fail closed unless `GHOSTAPI_AUTH_TOKEN` contains at least 24 characters. The token protects `/dashboard`, dashboard assets, `/api/*`, and `/events`.
+- Loopback remains token-free for local convenience, but hostile browser origins are rejected for dashboard routes.
+- `ghostapi doctor` warns when `NODE_TLS_REJECT_UNAUTHORIZED=0` is set.
+
+## Threat Assumptions
+
+- GhostAPI is a local development tool, not a network-isolation boundary. Provider simulation routes remain reachable on the configured bind address, except that remote proxy requests require the dashboard token while external LLM generation is enabled.
+- Dashboard authentication provides access control, not transport confidentiality. Use HTTPS or a secure tunnel for any non-loopback bind; never send the token over untrusted plain HTTP.
+- Filesystem locks coordinate cooperating GhostAPI processes on one local filesystem. They are not distributed locks and are not guaranteed on network shares or independently synchronized copies.
+- On POSIX systems GhostAPI requests owner-only directory/file modes. On Windows, effective access is inherited from the configured directory ACL.
+- Secret masking is heuristic. Do not place production credentials or sensitive personal data in scenarios, behaviors, manually edited state, or other local fixtures.
+- A process that can read the GhostAPI data directory or inspect the running process environment is inside the trust boundary.
+- Query-token bootstrap is accepted only for `GET /dashboard`, then redirected to a URL without the token and stored in an HttpOnly `SameSite=Strict` cookie. API and SSE query tokens are rejected.
+- GhostAPI does not claim DNS, process, container, or host-level egress isolation.
+
+## Reporting A Vulnerability
+
+Please do not open a public issue for a vulnerability.
+
+Until a dedicated security email is published, report privately to the project maintainer or repository owner and include:
+
+- A clear description of the issue.
+- Steps to reproduce.
+- Expected impact.
+- Whether secrets, prompts, cache, state, dashboard events, or network behavior are involved.
+- Suggested fix, if you have one.
+
+We will acknowledge valid reports as quickly as possible and prioritize fixes that could leak secrets, trigger real external calls unexpectedly, or expose local data.
+
+## Out Of Scope
+
+- Issues requiring malicious local filesystem access already authorized to the GhostAPI data directory.
+- Vulnerabilities in unsupported Node.js versions.
+- Reports without reproduction details.