@yiaany/ghostapi 0.1.7 → 0.1.8

package/examples/README.md

@@ -0,0 +1,10 @@
+# GhostAPI Starter Examples
+
+- `stripe-node/`: Stripe checkout, subscription, refund, and local webhook starter using fake local keys.
+- `openai-streaming/`: OpenAI-shaped streaming/tool-call request against local GhostAPI.
+- `ci-smoke/`: CI policy pass/fail fixtures, including an intentional production-egress failure.
+- `record-replay/`: Sanitized HAR import plus deterministic replay with no live provider traffic.
+- `evals/`: Agent eval spec starter scored from sanitized evidence.
+- `worlds/`: Stateful synthetic world starter for a subscription recovery workflow.
+
+Run `npx @yiaany/ghostapi doctor` before using `ghostapi run`; Linux namespace enforcement is not claimed on Windows or macOS.

package/examples/agent-instructions/README.md

@@ -1,39 +1,39 @@
-# Agent Instructions
-
-Use these snippets in AI coding tools when you want agents to test external integrations safely through GhostAPI.
-
-## Universal Instruction
-
-```text
-When testing external API integrations, use GhostAPI at http://localhost:8080. Do not send real requests to Stripe, Twilio, Resend, GitHub, Gmail or other external services unless explicitly approved by the user.
-```
-
-## Cursor
-
-```text
-For integration tests and local development, route external API calls through http://localhost:8080. Treat GhostAPI as the only approved target for Stripe, Twilio, Resend, GitHub, Gmail, Slack, Notion, and other external services unless the user explicitly approves live network calls.
-```
-
-## Cline
-
-```text
-Before running code that touches third-party APIs, rewrite base URLs to http://localhost:8080 and use GhostAPI. Never use production API keys or make real external requests without explicit user approval.
-```
-
-## Aider
-
-```text
-When adding or testing API integrations, prefer GhostAPI at http://localhost:8080 for all external services. Keep credentials local and fake. Do not call real Stripe, Twilio, Resend, GitHub, Gmail, or similar APIs unless explicitly instructed.
-```
-
-## Codex
-
-```text
-Use http://localhost:8080 as the base URL for external API integration tests. GhostAPI should simulate provider responses locally. Avoid real network requests to third-party APIs unless explicitly approved by the user.
-```
-
-## OpenCode
-
-```text
-For provider integration work, point SDKs and fetch calls at GhostAPI on http://localhost:8080. Do not send real requests to Stripe, Twilio, Resend, GitHub, Gmail, Slack, Notion, or any other external service without explicit approval.
-```
+# Agent Instructions
+
+Use these snippets in AI coding tools when you want agents to test external integrations safely through GhostAPI.
+
+## Universal Instruction
+
+```text
+When testing external API integrations, use GhostAPI at http://localhost:8080. Do not send real requests to Stripe, Twilio, Resend, GitHub, Gmail or other external services unless explicitly approved by the user.
+```
+
+## Cursor
+
+```text
+For integration tests and local development, route external API calls through http://localhost:8080. Treat GhostAPI as the only approved target for Stripe, Twilio, Resend, GitHub, Gmail, Slack, Notion, and other external services unless the user explicitly approves live network calls.
+```
+
+## Cline
+
+```text
+Before running code that touches third-party APIs, rewrite base URLs to http://localhost:8080 and use GhostAPI. Never use production API keys or make real external requests without explicit user approval.
+```
+
+## Aider
+
+```text
+When adding or testing API integrations, prefer GhostAPI at http://localhost:8080 for all external services. Keep credentials local and fake. Do not call real Stripe, Twilio, Resend, GitHub, Gmail, or similar APIs unless explicitly instructed.
+```
+
+## Codex
+
+```text
+Use http://localhost:8080 as the base URL for external API integration tests. GhostAPI should simulate provider responses locally. Avoid real network requests to third-party APIs unless explicitly approved by the user.
+```
+
+## OpenCode
+
+```text
+For provider integration work, point SDKs and fetch calls at GhostAPI on http://localhost:8080. Do not send real requests to Stripe, Twilio, Resend, GitHub, Gmail, Slack, Notion, or any other external service without explicit approval.
+```

package/examples/ci-smoke/README.md

@@ -0,0 +1,21 @@
+# GhostAPI CI Smoke Fixture
+
+This fixture is used by the repository's GitHub Actions reference workflow and can be run on a Linux host that supports GhostAPI namespaces.
+
+```bash
+export GHOSTAPI_DATA_DIR="$(mktemp -d)"
+ghostapi run --policy ghostapi.policy.yaml -- npm run test:safe
+```
+
+The safe command sends a request only to the GhostAPI endpoint injected by `ghostapi run`. It records `ci.safe_ghostapi`, which the fixture policy requires.
+
+The unsafe command is a regression test for the namespace boundary. It must exit non-zero when run through GhostAPI:
+
+```bash
+if ghostapi run --policy ghostapi.policy.yaml -- npm run test:production-egress; then
+  echo "unexpected production egress"
+  exit 1
+fi
+```
+
+The unsafe fixture must never be run directly on a developer machine or ordinary CI executor because it intentionally targets `api.stripe.com`.

package/examples/ci-smoke/ghostapi.policy.yaml

@@ -0,0 +1,22 @@
+version: 1
+network:
+  default: deny
+  allow:
+    - host: localhost
+    - host: 127.0.0.1
+  deny:
+    - host: api.stripe.com
+  productionHosts:
+    - '*.stripe.com'
+credentials:
+  forbid:
+    - sk_live_*
+requiredScenarios:
+  - ci.safe_ghostapi
+enforcement:
+  allowedModes:
+    - linux-network-namespace
+reports:
+  maxProductionEgressAttempts: 0
+  maxForbiddenCredentialMatches: 0
+  maxBreakingContractChanges: 0

package/examples/ci-smoke/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "ghostapi-ci-smoke-fixtures",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test:safe": "node safe.mjs",
+    "test:production-egress": "node production-egress.mjs"
+  }
+}

package/examples/ci-smoke/production-egress.mjs

@@ -0,0 +1,2 @@
+// This fixture deliberately represents unsafe application behavior. Only run it through ghostapi run.
+await fetch("https://api.stripe.com/v1/customers", { signal: AbortSignal.timeout(5_000) });

package/examples/ci-smoke/safe.mjs

@@ -0,0 +1,17 @@
+const baseUrl = process.env.GHOSTAPI_BASE_URL;
+
+if (!baseUrl) throw new Error("GHOSTAPI_BASE_URL is required; run this fixture through ghostapi run.");
+
+const response = await fetch(`${baseUrl}/v1/customers`, {
+  method: "POST",
+  headers: {
+    "content-type": "application/json"
+  },
+  body: JSON.stringify({
+    email: "ci-safe@example.invalid",
+    metadata: { scenario: "ci.safe_ghostapi" }
+  })
+});
+
+if (!response.ok) throw new Error(`GhostAPI safe fixture failed with HTTP ${response.status}.`);
+console.log("GhostAPI safe fixture completed through the loopback runtime.");

package/examples/evals/README.md

@@ -0,0 +1,24 @@
+# GhostAPI Agent Eval Demo
+
+This directory shows the coding-agent workflow for deterministic evals.
+
+1. Run the agent's integration tests through the safety boundary on a supported Linux host:
+
+```bash
+ghostapi run -- npm test
+```
+
+2. Generate sanitized evidence for the run:
+
+```bash
+ghostapi evidence generate --run .ghostapi/runs/<run-id>/run.json --out .ghostapi/reports/agent.json
+```
+
+3. Score the evidence with a built-in template or the local JSON spec:
+
+```bash
+ghostapi eval --template retry-after --evidence .ghostapi/reports/agent.json --ci
+ghostapi eval --spec examples/evals/retry-after.eval.json --evidence .ghostapi/reports/agent.json --json
+```
+
+If `--evidence` is omitted, `ghostapi eval --spec ...` launches `task.command` through `ghostapi run`; it never executes the command outside that boundary. Specs that declare `injectedFailures` require pre-generated evidence until the declared synthetic-world setup can be applied automatically. Core score is deterministic and evidence-based. LLM judging is not required and does not affect the security score.

package/examples/evals/retry-after.eval.json

@@ -0,0 +1,52 @@
+{
+  "schemaVersion": 1,
+  "kind": "ghostapi.eval",
+  "id": "agent.retry_after",
+  "title": "Agent honors Retry-After",
+  "syntheticWorld": {
+    "world": {
+      "id": "subscription-recovery",
+      "version": "1.0.0",
+      "seed": "demo-seed"
+    },
+    "providers": ["stripe"],
+    "scenarios": ["stripe.rate_limited"]
+  },
+  "task": {
+    "description": "Run the coding-agent integration tests under GhostAPI and verify retry behavior.",
+    "command": ["npm", "test"]
+  },
+  "injectedFailures": [
+    {
+      "id": "stripe.rate_limited",
+      "type": "rate-limit",
+      "provider": "stripe",
+      "statusCode": 429,
+      "retryAfterMs": 2000
+    }
+  ],
+  "expectations": [
+    { "id": "retry-observed", "type": "retry-observed", "points": 40 },
+    { "id": "no-production-egress", "type": "no-production-egress", "points": 30 },
+    { "id": "run-finished", "type": "run-finished", "points": 30 }
+  ],
+  "forbidden": [
+    { "id": "production-egress", "type": "production-egress" },
+    { "id": "secret-leak", "type": "secret-leak" }
+  ],
+  "limits": {
+    "timeoutMs": 60000,
+    "maxOutputBytes": 524288
+  },
+  "rubric": {
+    "maxScore": 100,
+    "components": [
+      { "id": "retry-observed", "expectationId": "retry-observed", "points": 40, "reason": "Retry or Retry-After evidence was observed." },
+      { "id": "no-production-egress", "expectationId": "no-production-egress", "points": 30, "reason": "Evidence reports zero production egress attempts." },
+      { "id": "run-finished", "expectationId": "run-finished", "points": 30, "reason": "The GhostAPI run finished and produced lifecycle evidence." }
+    ]
+  },
+  "judge": {
+    "llmAsJudge": false
+  }
+}

package/examples/generic-rest/README.md

@@ -1,27 +1,27 @@
-# Generic REST Example
-
-Create a generic task resource through GhostAPI. This path uses the generic fallback, not a native adapter.
-
-## Run
-
-Start GhostAPI:
-
-```bash
-ghostapi start
-```
-
-Create a task:
-
-```bash
-curl -X POST http://localhost:8080/tasks \
-  -H "content-type: application/json" \
-  -d '{"title":"Write integration tests","status":"open","priority":"high"}'
-```
-
-Fetch tasks:
-
-```bash
-curl http://localhost:8080/tasks
-```
-
-The generic fallback infers the `task` resource from the path and produces local mock IDs like `task_mock_xxx`.
+# Generic REST Example
+
+Create a generic task resource through GhostAPI. This path uses the generic fallback, not a native adapter.
+
+## Run
+
+Start GhostAPI:
+
+```bash
+ghostapi start
+```
+
+Create a task:
+
+```bash
+curl -X POST http://localhost:8080/tasks \
+  -H "content-type: application/json" \
+  -d '{"title":"Write integration tests","status":"open","priority":"high"}'
+```
+
+Fetch tasks:
+
+```bash
+curl http://localhost:8080/tasks
+```
+
+The generic fallback infers the `task` resource from the path and produces local mock IDs like `task_mock_xxx`.

package/examples/github-fetch/README.md

@@ -1,35 +1,35 @@
-# GitHub Fetch Example
-
-Create a GitHub-like issue through GhostAPI using plain `fetch` or `curl`. This does not call GitHub.
-
-## Run
-
-Start GhostAPI:
-
-```bash
-ghostapi start
-```
-
-Create an issue:
-
-```bash
-curl -X POST http://localhost:8080/repos/octo/hello-world/issues \
-  -H "content-type: application/json" \
-  -H "x-github-api-version: 2022-11-28" \
-  -H "authorization: Bearer ghp_local_only" \
-  -d '{"title":"Local integration test","body":"Created through GhostAPI"}'
-```
-
-Equivalent JavaScript:
-
-```js
-await fetch("http://localhost:8080/repos/octo/hello-world/issues", {
-  method: "POST",
-  headers: {
-    "content-type": "application/json",
-    "x-github-api-version": "2022-11-28",
-    authorization: "Bearer ghp_local_only"
-  },
-  body: JSON.stringify({ title: "Local integration test", body: "Created through GhostAPI" })
-});
-```
+# GitHub Fetch Example
+
+Create a GitHub-like issue through GhostAPI using plain `fetch` or `curl`. This does not call GitHub.
+
+## Run
+
+Start GhostAPI:
+
+```bash
+ghostapi start
+```
+
+Create an issue:
+
+```bash
+curl -X POST http://localhost:8080/repos/octo/hello-world/issues \
+  -H "content-type: application/json" \
+  -H "x-github-api-version: 2022-11-28" \
+  -H "authorization: Bearer ghp_local_only" \
+  -d '{"title":"Local integration test","body":"Created through GhostAPI"}'
+```
+
+Equivalent JavaScript:
+
+```js
+await fetch("http://localhost:8080/repos/octo/hello-world/issues", {
+  method: "POST",
+  headers: {
+    "content-type": "application/json",
+    "x-github-api-version": "2022-11-28",
+    authorization: "Bearer ghp_local_only"
+  },
+  body: JSON.stringify({ title: "Local integration test", body: "Created through GhostAPI" })
+});
+```

package/examples/openai-streaming/README.md

@@ -0,0 +1,16 @@
+# OpenAI Streaming And Tool Call Starter
+
+This starter exercises OpenAI-shaped chat completions against local GhostAPI. It uses a fake key and never requires a live OpenAI account.
+
+```bash
+npx @yiaany/ghostapi start
+node examples/openai-streaming/streaming-tool-call.mjs
+```
+
+When running on a supported Linux host, execute the app through the egress boundary:
+
+```bash
+npx @yiaany/ghostapi run -- node examples/openai-streaming/streaming-tool-call.mjs
+```
+
+Windows and macOS process isolation is unsupported/experimental; use `ghostapi start` and local SDK base URLs there.

package/examples/openai-streaming/streaming-tool-call.mjs

@@ -0,0 +1,31 @@
+const baseUrl = process.env.GHOSTAPI_OPENAI_BASE_URL ?? "http://127.0.0.1:8080/v1";
+
+const response = await fetch(`${baseUrl}/chat/completions`, {
+  method: "POST",
+  headers: {
+    "content-type": "application/json",
+    authorization: `Bearer ${process.env.OPENAI_API_KEY ?? "sk-ghostapi"}`
+  },
+  body: JSON.stringify({
+    model: "gpt-4o-mini",
+    stream: true,
+    messages: [{ role: "user", content: "Return a local weather tool call for Berlin." }],
+    tools: [
+      {
+        type: "function",
+        function: {
+          name: "get_weather",
+          description: "Return local test weather.",
+          parameters: { type: "object", properties: { city: { type: "string" } }, required: ["city"] }
+        }
+      }
+    ]
+  })
+});
+
+if (!response.ok) throw new Error(`GhostAPI OpenAI request failed: ${response.status} ${await response.text()}`);
+
+const text = await response.text();
+if (!text.includes("[DONE]")) throw new Error("Expected a local streaming completion terminator.");
+
+console.log("OpenAI streaming/tool-call starter completed against local GhostAPI.");

package/examples/policy/ghostapi.policy.yaml

@@ -0,0 +1,27 @@
+version: 1
+network:
+  default: deny
+  allow:
+    - host: localhost
+    - host: 127.0.0.1
+  deny:
+    - host: api.stripe.com
+    - host: api.openai.com
+  productionHosts:
+    - '*.stripe.com'
+    - '*.openai.com'
+credentials:
+  forbid:
+    - sk_live_*
+    - rk_live_*
+    - ghp_*
+requiredScenarios:
+  - stripe-payment-intent-card-declined
+  - stripe-subscription-payment-failed
+enforcement:
+  allowedModes:
+    - linux-network-namespace
+reports:
+  maxProductionEgressAttempts: 0
+  maxForbiddenCredentialMatches: 0
+  maxBreakingContractChanges: 0

package/examples/record-replay/README.md

@@ -0,0 +1,19 @@
+# Record/Replay Starter
+
+This starter uses a tiny sanitized HAR fixture and a matching request file. It demonstrates the workflow without a live provider key.
+
+```bash
+npx @yiaany/ghostapi record \
+  --input examples/record-replay/stripe-checkout.har.json \
+  --allow-sandbox-host api.stripe.com \
+  --out .ghostapi/scenarios/stripe-checkout.bundle.json \
+  --title "Starter checkout" \
+  --approve
+
+npx @yiaany/ghostapi replay \
+  .ghostapi/scenarios/stripe-checkout.bundle.json \
+  --requests examples/record-replay/replay-requests.json \
+  --json
+```
+
+The fixture uses a fake `sk_test_...` key marker; do not record production traffic.

package/examples/record-replay/replay-requests.json

@@ -0,0 +1,22 @@
+[
+  {
+    "method": "POST",
+    "path": "/v1/checkout/sessions",
+    "headers": { "content-type": "application/json" },
+    "body": {
+      "mode": "payment",
+      "success_url": "https://sandbox.example/success",
+      "cancel_url": "https://sandbox.example/cancel",
+      "line_items": [
+        {
+          "quantity": 1,
+          "price_data": {
+            "currency": "usd",
+            "unit_amount": 2400,
+            "product_data": { "name": "Starter" }
+          }
+        }
+      ]
+    }
+  }
+]

package/examples/record-replay/stripe-checkout.har.json

@@ -0,0 +1,30 @@
+{
+  "log": {
+    "version": "1.2",
+    "creator": { "name": "ghostapi-starter", "version": "1.0" },
+    "entries": [
+      {
+        "request": {
+          "method": "POST",
+          "url": "https://api.stripe.com/v1/checkout/sessions",
+          "headers": [
+            { "name": "authorization", "value": "Bearer sk_test_ghostapi" },
+            { "name": "content-type", "value": "application/json" }
+          ],
+          "postData": {
+            "mimeType": "application/json",
+            "text": "{\"mode\":\"payment\",\"success_url\":\"https://sandbox.example/success\",\"cancel_url\":\"https://sandbox.example/cancel\",\"line_items\":[{\"quantity\":1,\"price_data\":{\"currency\":\"usd\",\"unit_amount\":2400,\"product_data\":{\"name\":\"Starter\"}}}]}"
+          }
+        },
+        "response": {
+          "status": 200,
+          "headers": [{ "name": "content-type", "value": "application/json" }],
+          "content": {
+            "mimeType": "application/json",
+            "text": "{\"id\":\"cs_test_starter\",\"object\":\"checkout.session\",\"mode\":\"payment\",\"livemode\":false,\"url\":\"http://127.0.0.1:8080/checkout/cs_test_starter\"}"
+          }
+        }
+      }
+    ]
+  }
+}

package/examples/resend-node/README.md

@@ -1,22 +1,22 @@
-# Resend Node Example
-
-Send a Resend-like email through GhostAPI. This does not send a real email.
-
-## Run
-
-Start GhostAPI:
-
-```bash
-ghostapi start
-```
-
-Send an email:
-
-```bash
-curl -X POST http://localhost:8080/emails \
-  -H "content-type: application/json" \
-  -H "authorization: Bearer re_local_only" \
-  -d '{"from":"onboarding@example.com","to":"ada@example.com","subject":"Welcome","html":"<p>Hello from GhostAPI</p>"}'
-```
-
-GhostAPI detects Resend from `/emails` and returns a local mock email response.
+# Resend Node Example
+
+Send a Resend-like email through GhostAPI. This does not send a real email.
+
+## Run
+
+Start GhostAPI:
+
+```bash
+ghostapi start
+```
+
+Send an email:
+
+```bash
+curl -X POST http://localhost:8080/emails \
+  -H "content-type: application/json" \
+  -H "authorization: Bearer re_local_only" \
+  -d '{"from":"onboarding@example.com","to":"ada@example.com","subject":"Welcome","html":"<p>Hello from GhostAPI</p>"}'
+```
+
+GhostAPI detects Resend from `/emails` and returns a local mock email response.

package/examples/stripe-node/README.md

@@ -1,29 +1,35 @@
-# Stripe Node Example
-
-Create and fetch a Stripe-like customer through GhostAPI. This does not call Stripe.
-
-## Run
-
-Start GhostAPI:
-
-```bash
-ghostapi start
-```
-
-Create a customer:
-
-```bash
-curl -X POST http://localhost:8080/v1/customers \
-  -H "content-type: application/json" \
-  -H "authorization: Bearer stripe_test_local_only" \
-  -d '{"email":"ada@example.com","name":"Ada Lovelace","metadata":{"source":"ghostapi-example"}}'
-```
-
-Copy the returned `id`, then fetch it:
-
-```bash
-curl http://localhost:8080/v1/customers/cus_mock_example \
-  -H "authorization: Bearer stripe_test_local_only"
-```
-
-GhostAPI detects Stripe from the `/v1/customers` path and keeps the created object in `.ghostapi/state.json`.
+# Stripe Node Subscription Flow
+
+Run the official Stripe Node SDK against GhostAPI without patching SDK source. This example only talks to `127.0.0.1`; it does not call Stripe.
+
+## Run
+
+Start GhostAPI:
+
+```bash
+ghostapi start
+```
+
+Install the SDK once in this example directory:
+
+```bash
+npm install stripe
+```
+
+Run the subscription flow:
+
+```bash
+node checkout-flow.mjs
+```
+
+The script creates a customer, product, recurring price, and trial subscription; activates the local renewal control; then verifies the signed `invoice.payment_succeeded` payload with the official Stripe SDK. `delivery_mode=duplicate` deliberately returns the same event again so application-level de-duplication can be tested.
+
+The pack accepts SDK-style `application/x-www-form-urlencoded` requests and JSON requests used by direct HTTP clients. It uses Stripe API version `2026-02-25.clover`. Webhook deliveries are pull-based local test endpoints, so this example never asks GhostAPI to send an outbound request.
+
+To inspect the generated state:
+
+```bash
+curl http://127.0.0.1:8080/v1/payment_intents?limit=10
+```
+
+See [`docs/providers/stripe-core-pack.md`](../../docs/providers/stripe-core-pack.md) for supported operations and deliberate limits.