GhostApi

Por que GhostAPI

Agentes de codificação podem escrever um checkout do Stripe, um fluxo de trabalho do OpenAI, uma automação do GitHub ou uma integração de e-mail em minutos. A parte perigosa é o que acontece quando eles executam esse código.

Quando um cliente é configurado contra um provedor ao vivo, um teste pode:

• cobrar um cartão real;
• enviar um e-mail ou SMS real;
• criar ou modificar recursos reais do GitHub;
• gastar créditos de API;
• vazar credenciais em logs, prompts, capturas de tela ou fixtures de teste.

O GhostAPI fornece um endpoint local em 127.0.0.1:8080. As solicitações enviadas a esse endpoint são classificadas, sanitizadas heuristicamente, registradas em armazenamentos locais limitados e respondidas por pacotes de provedores implementados ou comportamento de fallback genérico. Você pode inspecionar o resultado no dashboard, controlar o comportamento local por meio do MCP e transformar falhas capturadas em testes repetíveis.

Verificado Localmente, Ainda Não Validado por Clientes

O repositório público contém testes reproduzíveis para simulação local de provedores, aplicação de namespace Linux, instalação de pacotes e autorização de piloto hospedado. O GhostAPI ainda não afirma ter clientes de produção, pilotos pagos ou um serviço de equipe implantado.

Início Rápido

Inicie o servidor local e o dashboard:

npx @yiaany/ghostapi start --open

Envie uma solicitação no formato 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 o dashboard em http://127.0.0.1:8080/dashboard. A solicitação aparece no tráfego ao vivo com seu provedor, corpo da solicitação, resposta gerada, origem, status e tempo.

Inicialize o GhostAPI dentro de um repositório existente:

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

init cria configuração local, uma política de segurança versionada, trechos MCP e instruções para agentes sem sobrescrever arquivos existentes.

Em um host Linux suportado, execute um comando dentro do namespace de rede somente loopback:

npx @yiaany/ghostapi run -- npm test

No Windows e no macOS, ghostapi run falha de forma segura porque um backend equivalente de isolamento de processo não está implementado. O servidor de API local e o dashboard ainda funcionam normalmente.

O Que Você Obtém

Recurso	O que faz
Simulação de API local	Dá a SDKs e aplicativos explicitamente configurados um alvo local em vez de um provedor ao vivo.
Comportamento no formato do provedor	Retorna objetos e erros determinísticos no formato do subconjunto implementado de cada API de provedor; não afirma paridade com provedores ao vivo.
Dashboard ao vivo	Mostra solicitações e respostas, filtra tráfego por provedor, gera testes e arma cenários.
Plano de controle MCP	Permite que agentes de codificação compatíveis inspecionem estado, leiam tráfego, configurem respostas e alternem o Modo Caos.
Mundos sintéticos com estado	Mantém identidades e estado locais determinísticos em projeções de Stripe, GitHub, e-mail e REST.
Cenários e gravação/reprodução	Salva tráfego de sandbox sanitizado e o reproduz offline como fixtures determinísticas.
Verificações de desvio de contrato	Importa contratos OpenAPI/HAR limitados e classifica mudanças críticas, não críticas e incertas.
Avaliações e evidências de agente	Produz relatórios limitados com um hash local de autoconsistência, verificável enquanto o runtime e o armazenamento local permanecem confiáveis.
Redução de risco de segredos	Mascara heuristicamente cabeçalhos, parâmetros de consulta, corpos, caminhos, eventos, prompts e entradas de cache com formato de segredo reconhecido.
Teste de falhas	Força latência, erros de provedor, recusas de cartão, limites de taxa e outros caminhos infelizes.
Controles de segurança	Inclui aprovações locais, orçamentos limitados, interruptores de emergência, disjuntores, registros e reconciliação para ações sintéticas.
Ferramentas de confiabilidade	Rastreia amostras locais de SLO, atribuição de custos, saúde do runtime, backups, inventário e metadados de caminhos de ataque.

Dashboard

O dashboard é a maneira mais rápida de entender o que um agente ou aplicativo realmente fez.

• Observe o tráfego chegar em tempo real via SSE.
• Inspecione JSON de solicitação e resposta sanitizado.
• Filtre por Stripe, Twilio, Resend, GitHub, Discord, OpenAI ou REST genérico.
• Gere um teste Vitest a partir de uma solicitação capturada.
• Gere e copie arquivos de configuração para agentes de codificação suportados.
• Arme predefinições de cenário determinísticas.
• Alterne o Modo Caos e inspecione o relatório de segurança local.

As rotas do dashboard e da API são protegidas por token em todo bind não loopback. Use HTTPS ou um túnel seguro ao expor o GhostAPI além do localhost.

Suporte a Provedores

O GhostAPI tem dois níveis de suporte a provedores.

Pacotes de provedores com estado

Provedor	Comportamento incluído
Stripe	Clientes, produtos, preços, assinaturas, faturas, intenções de pagamento, métodos de pagamento, sessões de checkout, reembolsos, paginação, cenários de ciclo de vida e webhooks locais assinados.
Resend	Solicitações, respostas, validação e comportamento de falha determinísticos no formato de e-mail.

Adaptadores no formato de provedor e inferência genérica

Rotas de OpenAI, Twilio, GitHub, Discord e REST genérico são detectadas e recebem respostas e erros sintéticos no formato de provedor. Esses adaptadores são úteis para desenvolvimento local, mas não afirmam paridade completa com endpoints de provedores ao vivo.

Operações de pacote Stripe e Resend não suportadas falham de forma diagnóstica. Adaptadores legados e inferência REST genérica podem retornar uma resposta de fallback sintética para rotas não reconhecidas; tais respostas não indicam suporte ou paridade de provedor.

Configuração de 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 o servidor MCP:

npx @yiaany/ghostapi mcp

Configuração MCP genérica:

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

Ferramentas disponíveis:

Ferramenta	Propósito
inspect_state	Ler objetos de API locais atuais.
get_traffic_logs	Inspecionar tráfego recente sanitizado.
set_api_behavior	Forçar uma resposta determinística para um método e caminho.
toggle_chaos_mode	Habilitar ou desabilitar injeção local de latência e falhas.

Gere trechos de configuração para Cursor, Claude, Cline, Aider, Codex, OpenCode, Gemini CLI, Goose, OpenClaw, Hermes e clientes MCP genéricos:

npx @yiaany/ghostapi setup --write

Conecte apenas clientes MCP locais confiáveis. As ferramentas MCP podem ler tráfego e estado retidos e podem modificar o comportamento de simulação local; MCP não é um limite de autenticação ou egresso. Fixe a versão do pacote na configuração MCP persistente ou use uma instalação local revisada.

Cenários, Contratos e Avaliações

Registre tráfego de sandbox aprovado em um pacote offline sanitizado:

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

Reproduza-o sem acesso à rede:

ghostapi replay bundle.json --requests requests.json

Importe e 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

Gere evidência de CI sanitizada:

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

Execute uma avaliação de agente determinística:

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

Limites de Segurança

O GhostAPI usa padrões locais-first, opt-in explícito para LLM externo e mascaramento heurístico de segredos. Seus limites são explícitos:

• Chamadas reais a provedores são desabilitadas por padrão.
• OPENAI_API_KEY ambiente não habilita geração externa.
• Geração externa por LLM requer um sinalizador explícito mais um GHOSTAPI_LLM_API_KEY separado.
• Em binds não loopback, toda rota exceto / e /health requer um GHOSTAPI_AUTH_TOKEN forte. O token fornece controle de acesso, não criptografia.
• Redirecionamentos de resposta externa, cabeçalhos de resposta inseguros, travessia, referências de esquema remoto, symlinks, arquivos e entradas superdimensionadas são rejeitados quando aplicável.
• Armazenamentos persistentes têm limites de tamanho, entrada, retenção ou rotação.
• O backend run Linux fornece isolamento de rede de processo somente loopback quando a pré-verificação de namespace é bem-sucedida.
• run não é um sandbox de sistema de arquivos para código hostil.
• O mascaramento de segredos é heurístico e incompleto. Use credenciais e dados sintéticos mesmo em fixtures locais.
• Componentes locais de aprovação, ação, credencial, registro, confiança e segurança executam apenas operações sintéticas. Eles não são um executor de provedor de produção.
• Hashes de evidência são verificações locais de autoconsistência, não assinaturas, proveniência imutável ou prova contra um editor do mesmo usuário.
• A evidência de execução atual registra o ciclo de vida do namespace e o tráfego local do GhostAPI; não enumera tentativas de socket negadas pelo kernel.

Leia os modelos de ameaça detalhados em docs/security e a política de relatórios em SECURITY.md.

Não-Objetivos Explícitos

• Sem garantia de paridade com provedores ao vivo.
• Sem garantia completa de redação de segredos.
• Sem sandbox de sistema de arquivos para código hostil.
• Sem aplicação equivalente de egresso de processo no Windows ou macOS.
• Sem serviço hospedado implantado, SLA, certificação de conformidade ou executor de credenciais de produção.

Suporte de Plataforma

Plataforma	API local e dashboard	Aplicação ghostapi run
Linux	Suportado no Node.js 20+	Suportado quando unshare, iproute2 e a pré-verificação de namespace passam.
Windows	Suportado no Node.js 20+	Não implementado; falha de forma segura.
macOS	Suportado no Node.js 20+	Não implementado; falha de forma segura.

Verifique a máquina atual:

ghostapi doctor --json
ghostapi doctor --egress

Endpoints de Saúde

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 Hospedado

Atualmente, não há serviço hospedado ou empresarial disponível. O diretório hosted/ é uma implementação experimental não implantada, excluída do pacote npm e sem suporte para uso em produção. Seu comportamento em produção para OAuth, dependências, migração, carga, failover, backup e recuperação de desastres não foi comprovado em ambiente de staging.

Desenvolvimento

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

Verificações do piloto hospedado:

cd hosted
npm ci
npm run check

Consulte CONTRIBUTING.md, PROVENANCE.md e docs/releases/ para os limites de contribuição e lançamento.

Documentação

• Guia de uso
• Configuração do MCP
• Referência de políticas
• Integração com GitHub Actions
• Integração com CI genérico
• Pacote do provedor Stripe
• Política de segurança
• Modelos de ameaças
• Proveniência do projeto
• Evidências de lançamento
• Prontidão para lançamento
• Migração e reversão

Licença

MIT. Consulte LICENSE.