GhostApi

Por qué GhostAPI

Los agentes de codificación pueden escribir un checkout de Stripe, un flujo de trabajo de OpenAI, una automatización de GitHub o una integración de correo electrónico en minutos. La parte peligrosa es lo que sucede cuando ejecutan ese código.

Cuando un cliente está configurado contra un proveedor en vivo, una prueba puede:

• cobrar una tarjeta real;
• enviar un correo electrónico o SMS real;
• crear o modificar recursos reales de GitHub;
• gastar créditos de API;
• filtrar credenciales en registros, indicaciones, capturas de pantalla o accesorios de prueba.

GhostAPI proporciona un endpoint local en 127.0.0.1:8080. Las solicitudes enviadas a ese endpoint se clasifican, se sanean heurísticamente, se registran en almacenes locales acotados y se responden mediante paquetes de proveedores implementados o comportamiento de respaldo genérico. Puede inspeccionar el resultado en el panel, controlar el comportamiento local a través de MCP y convertir fallas capturadas en pruebas repetibles.

Verificado Localmente, Aún No Validado por Clientes

El repositorio público contiene pruebas reproducibles para la simulación local de proveedores, la aplicación de espacios de nombres de Linux, la instalación de paquetes y la autorización del piloto alojado. GhostAPI aún no afirma tener clientes de producción, pilotos pagados o un servicio de equipo desplegado.

Inicio rápido

Inicie el servidor local y el panel:

npx @yiaany/ghostapi start --open

Envíe una solicitud con forma de Stripe:

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"}'

Abra el panel en http://127.0.0.1:8080/dashboard. La solicitud aparece en el tráfico en vivo con su proveedor, cuerpo de solicitud, respuesta generada, origen, estado y tiempo.

Inicialice GhostAPI dentro de un repositorio existente:

npx @yiaany/ghostapi init
npx @yiaany/ghostapi doctor

init crea configuración local, una política de seguridad versionada, fragmentos MCP e instrucciones para agentes sin sobrescribir archivos existentes.

En un host Linux compatible, ejecute un comando dentro del espacio de nombres de red de solo loopback:

npx @yiaany/ghostapi run -- npm test

En Windows y macOS, ghostapi run falla de forma segura porque no se implementa un backend equivalente de aislamiento de procesos. El servidor de API local y el panel siguen funcionando normalmente.

Lo que Obtiene

Característica	Qué hace
Simulación de API local	Brinda a los SDK y aplicaciones configurados explícitamente un destino local en lugar de un proveedor en vivo.
Comportamiento con forma de proveedor	Devuelve objetos y errores deterministas con la forma del subconjunto implementado de cada API de proveedor; no afirma paridad con el proveedor en vivo.
Panel en vivo	Muestra solicitudes y respuestas, filtra tráfico por proveedor, genera pruebas y activa escenarios.
Plano de control MCP	Permite que agentes de codificación compatibles inspeccionen el estado, lean tráfico, configuren respuestas y alternen el Modo Caos.
Mundos sintéticos con estado	Mantiene identidades y estado locales deterministas en proyecciones de Stripe, GitHub, correo electrónico y REST.
Escenarios y grabación/reproducción	Guarda tráfico de sandbox saneado y lo reproduce sin conexión como accesorios deterministas.
Verificaciones de desviación de contratos	Importa contratos OpenAPI/HAR acotados y clasifica cambios disruptivos, no disruptivos e inciertos.
Evaluaciones y evidencia de agentes	Produce informes acotados con un hash de autoconsistencia local, verificable mientras el tiempo de ejecución y el almacenamiento local permanezcan confiables.
Reducción de riesgo de secretos	Enmascara heurísticamente encabezados, parámetros de consulta, cuerpos, rutas, eventos, indicaciones y entradas de caché con forma de secreto reconocidos.
Pruebas de fallas	Fuerza latencia, errores de proveedor, rechazos de tarjetas, límites de velocidad y otras rutas infelices.
Controles de seguridad	Incluye aprobaciones locales, presupuestos acotados, interruptores de apagado, disyuntores, libros de contabilidad y conciliación para acciones sintéticas.
Herramientas de confiabilidad	Rastrea muestras de SLO locales, atribución de costos, salud del tiempo de ejecución, copias de seguridad, inventario y metadatos de rutas de ataque.

Panel

El panel es la forma más rápida de entender lo que un agente o aplicación realmente hizo.

• Observe el tráfico llegar en tiempo real a través de SSE.
• Inspeccione el JSON de solicitud y respuesta saneado.
• Filtre por Stripe, Twilio, Resend, GitHub, Discord, OpenAI o REST genérico.
• Genere una prueba de Vitest a partir de una solicitud capturada.
• Genere y copie archivos de configuración para agentes de codificación compatibles.
• Active ajustes preestablecidos de escenarios deterministas.
• Alterne el Modo Caos e inspeccione el informe de seguridad local.

Las rutas del panel y de la API están protegidas por token en cada enlace que no sea de loopback. Use HTTPS o un túnel seguro al exponer GhostAPI más allá de localhost.

Soporte de Proveedores

GhostAPI tiene dos niveles de soporte de proveedores.

Paquetes de proveedores con estado

Proveedor	Comportamiento incluido
Stripe	Clientes, productos, precios, suscripciones, facturas, intenciones de pago, métodos de pago, sesiones de checkout, reembolsos, paginación, escenarios de ciclo de vida y webhooks locales firmados.
Resend	Solicitudes, respuestas, validación y comportamiento de fallas deterministas con forma de correo electrónico.

Adaptadores con forma de proveedor e inferencia genérica

Las rutas de OpenAI, Twilio, GitHub, Discord y REST genérico se detectan y reciben respuestas y errores sintéticos con forma de proveedor. Estos adaptadores son útiles para el desarrollo local, pero no afirman paridad completa con los endpoints de proveedores en vivo.

Las operaciones de paquetes de Stripe y Resend no compatibles fallan de manera diagnóstica. Los adaptadores heredados y la inferencia REST genérica pueden devolver una respuesta de respaldo sintética para rutas no reconocidas; tales respuestas no indican soporte o paridad de proveedor.

Configuración del SDK

Stripe:

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",
  },
);

OpenAI:

import OpenAI from "openai";

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",
});

REST genérico:

curl -X POST http://127.0.0.1:8080/tasks \
  -H "content-type: application/json" \
  -d '{"title":"Add integration tests","status":"open"}'

MCP para Agentes

Inicie el servidor MCP:

npx @yiaany/ghostapi mcp

Configuración MCP genérica:

{
  "mcpServers": {
    "ghostapi": {
      "command": "npx",
      "args": ["-y", "@yiaany/ghostapi@0.2.1", "mcp"]
    }
  }
}

Herramientas disponibles:

Herramienta	Propósito
inspect_state	Leer objetos de API locales actuales.
get_traffic_logs	Inspeccionar tráfico reciente saneado.
set_api_behavior	Forzar una respuesta determinista para un método y una ruta.
toggle_chaos_mode	Habilitar o deshabilitar la inyección de latencia y fallas local.

Genere fragmentos de configuración para Cursor, Claude, Cline, Aider, Codex, OpenCode, Gemini CLI, Goose, OpenClaw, Hermes y clientes MCP genéricos:

npx @yiaany/ghostapi setup --write

Conecte solo clientes MCP locales confiables. Las herramientas MCP pueden leer tráfico y estado retenidos y pueden modificar el comportamiento de simulación local; MCP no es un límite de autenticación o egreso. Fije la versión del paquete en la configuración MCP persistente o use una instalación local revisada.

Escenarios, Contratos y Evaluaciones

Registre tráfico de sandbox aprobado en un paquete sin conexión saneado:

ghostapi record \
  --input capture.har \
  --allow-sandbox-host api.sandbox.example \
  --approve

Reprodúzcalo sin acceso a la red:

ghostapi replay bundle.json --requests requests.json

Importe y compare contratos de API:

ghostapi contract import-openapi --input openapi.json
ghostapi contract diff \
  --baseline base.contract.json \
  --candidate head.contract.json \
  --policy ghostapi.policy.yaml \
  --ci

Genere evidencia de CI saneada:

ghostapi evidence generate --policy ghostapi.policy.yaml --ci

Ejecute una evaluación de agente determinista:

ghostapi eval \
  --template retry-after \
  --evidence .ghostapi/reports/latest.json \
  --ci

Límites de Seguridad

GhostAPI usa valores predeterminados de prioridad local, aceptación explícita de LLM externo y enmascaramiento heurístico de secretos. Sus límites son explícitos:

• Las llamadas a proveedores reales están deshabilitadas de forma predeterminada.
• El OPENAI_API_KEY ambiental no habilita la generación externa.
• La generación de LLM externo requiere un indicador explícito más un GHOSTAPI_LLM_API_KEY separado.
• En enlaces que no son de loopback, cada ruta excepto / y /health requiere un GHOSTAPI_AUTH_TOKEN fuerte. El token proporciona control de acceso, no cifrado.
• Las redirecciones de respuesta externas, los encabezados de respuesta inseguros, el recorrido de rutas, las referencias de esquema remotas, los enlaces simbólicos, los archivos y las entradas de gran tamaño se rechazan cuando corresponde.
• Los almacenes persistentes tienen límites de tamaño, entrada, retención o rotación.
• El backend run de Linux proporciona aislamiento de red de procesos de solo loopback cuando la verificación previa del espacio de nombres tiene éxito.
• run no es un sandbox de sistema de archivos para código hostil.
• El enmascaramiento de secretos es heurístico e incompleto. Use credenciales y datos sintéticos incluso en accesorios locales.
• Los componentes locales de aprobación, acción, credencial, libro de contabilidad, confianza y seguridad ejecutan solo operaciones sintéticas. No son un ejecutor de proveedores de producción.
• Los hashes de evidencia son verificaciones de autoconsistencia local, no firmas, procedencia inmutable o prueba contra un editor del mismo usuario.
• La evidencia de ejecución actual registra el ciclo de vida del espacio de nombres y el tráfico local de GhostAPI; no enumera intentos de socket denegados por el kernel.

Lea los modelos de amenaza detallados en docs/security y la política de informes en SECURITY.md.

No-Objetivos Explícitos

• Sin garantía de paridad con proveedores en vivo.
• Sin garantía completa de redacción de secretos.
• Sin sandbox de sistema de archivos para código hostil.
• Sin aplicación equivalente de egreso de procesos en Windows o macOS.
• Sin servicio alojado desplegado, SLA, certificación de cumplimiento o ejecutor de credenciales de producción.

Soporte de Plataformas

Plataforma	API local y panel	Aplicación de ghostapi run
Linux	Compatible con Node.js 20+	Compatible cuando unshare, iproute2 y la verificación previa del espacio de nombres pasan.
Windows	Compatible con Node.js 20+	No implementado; falla de forma segura.
macOS	Compatible con Node.js 20+	No implementado; falla de forma segura.

Verifique la máquina actual:

ghostapi doctor --json
ghostapi doctor --egress

Endpoints de Salud

GET /health             process liveness, HTTP 200 while state can be evaluated
GET /health/readiness   structural readiness, HTTP 503 when a required store is unsafe

Experimento Alojado

No hay ningún servicio alojado o empresarial disponible actualmente. El directorio hosted/ es una implementación experimental no implementada, excluida del paquete npm y no compatible con uso en producción. Su comportamiento en vivo de OAuth, dependencias, migración, carga, conmutación por error, copias de seguridad y recuperación ante desastres no ha sido probado en un entorno de staging.

Desarrollo

npm ci
npm run lint
npm run typecheck
npm test
npm run test:coverage
npm run build
npm run smoke:package

Comprobaciones del piloto alojado:

cd hosted
npm ci
npm run check

Consulta CONTRIBUTING.md, PROVENANCE.md y docs/releases/ para conocer los límites de contribución y publicación.

Documentación

• Guía de uso
• Configuración de MCP
• Referencia de políticas
• Integración con GitHub Actions
• Integración con CI genérico
• Paquete del proveedor Stripe
• Política de seguridad
• Modelos de amenazas
• Procedencia del proyecto
• Evidencia de publicación
• Preparación para la publicación
• Migración y reversión

Licencia

MIT. Consulta LICENSE.