q-ring

Armazene segredos no chaveiro do SO (macOS/Linux/Windows) e exponha-os a agentes de codificação de IA por meio de 44 ferramentas MCP governadas por políticas.

GitHub

Experimente este MCPPatrocinado

Documentação

q-ring

Segredos do keychain do sistema operacional para agentes de codificação com IA, via MCP.

Pare de colar chaves de API em arquivos .env de texto puro ou de brigar com gerenciadores de segredos complicados. O q-ring ancora com segurança suas credenciais no cofre nativo do seu sistema operacional (Keychain do macOS, Secret Service do Linux, Credential Vault do Windows) e as turbina com mecânicas da física quântica.

📖 Veja a Documentação Oficial para uma referência completa da CLI, receitas de prompt para MCP e detalhes de arquitetura.

Por que q-ring?

Superposição: Armazene uma chave com múltiplos estados (dev/staging/prod) que colapsam com base no contexto.
Entrelaçamento: Vincule chaves entre projetos para que, ao rotacionar uma, todas sejam atualizadas automaticamente.
Tunelamento: Crie segredos efêmeros, em memória, que se autodestroem após um tempo ou contagem de leituras definidos.
Teletransporte: Empacote e compartilhe com segurança pacotes de segredos criptografados com AES-256-GCM.
Integração perfeita com IA: 46 ferramentas MCP integradas para uso nativo em Cursor, Kiro e Claude Code.

🚀 Instalação

O q-ring foi projetado para ser instalado globalmente, para que esteja disponível em qualquer lugar do seu terminal. Escolha seu gerenciador de pacotes favorito:

# pnpm (recommended)
pnpm add -g @i4ctime/q-ring

# npm
npm install -g @i4ctime/q-ring

# yarn
yarn global add @i4ctime/q-ring

# Homebrew (macOS / Linux)
brew install i4ctime/tap/qring

Docker (servidor MCP)

O repositório inclui um Dockerfile que compila o servidor MCP e o expõe via mcp-proxy — útil para implantações MCP hospedadas (ex.: Glama) ou para manter o servidor totalmente fora do host:

git clone https://github.com/I4cTime/q-ring.git
cd q-ring
docker build -t qring-mcp .
docker run --rm -p 8080:8080 qring-mcp

Observação: dentro de um contêiner não há keychain do sistema operacional (GNOME Keyring / macOS Keychain), portanto este caminho é para a superfície do protocolo MCP, uso efêmero e experimentos de CI — não para armazenamento durável de segredos local. Para uso diário, instale a CLI nativamente via um dos gerenciadores de pacotes acima.

⚡ Início Rápido

# 1️⃣ Store a secret (prompts securely if value is omitted)
qring set OPENAI_API_KEY sk-...

# 2️⃣ Retrieve it anytime
qring get OPENAI_API_KEY

# 3️⃣ List all keys (values are never shown)
qring list

# 4️⃣ Generate a cryptographic secret and save it
qring generate --format api-key --prefix "sk-" --save MY_KEY

# 5️⃣ Run a full health scan
qring health

# Something not working? Diagnose the install (keyring, audit, MCP wiring)
qring doctor

# Tab completion for your shell
qring completion zsh > ~/.zsh/completions/_qring   # also: bash, fish

Recursos Quânticos

Superposição — Uma Chave, Múltiplos Ambientes

Um único segredo pode conter valores diferentes para dev, staging e prod simultaneamente. O valor correto é resolvido com base no seu contexto atual.

# Set environment-specific values
qring set API_KEY "sk-dev-123" --env dev
qring set API_KEY "sk-stg-456" --env staging
qring set API_KEY "sk-prod-789" --env prod

# Value resolves based on context
QRING_ENV=prod qring get API_KEY   # → sk-prod-789
QRING_ENV=dev  qring get API_KEY   # → sk-dev-123

# Inspect the quantum state
qring inspect API_KEY

Promoção de Ambiente — Compare, Depois Promova

Quando um segredo carrega estados por ambiente, a promoção substitui o copiar-e-colar: compare dois ambientes chave por chave (apenas status, nunca valores) e copie um valor de um estado para outro. O diff sai com código 1 em caso de divergência, então também funciona como porta de CI; o promote se recusa a sobrescrever um destino divergente, a menos que você confirme.

# What differs between staging and prod? (same / different / missing on one side)
qring diff staging prod

# Make prod match staging for one key (asks before overwriting a different value)
qring promote DATABASE_URL --from staging --to prod

# Non-interactive, e.g. in a release script
qring promote DATABASE_URL --from staging --to prod --force --json

Agentes MCP têm as mesmas duas operações como diff_environments e promote_secret.

Colapso da Função de Onda — Detecção Inteligente de Ambiente

O q-ring detecta automaticamente seu ambiente sem flags explícitas. Ordem de resolução:

Flag --env
Variável de ambiente QRING_ENV
Variável de ambiente NODE_ENV
Heurísticas de branch Git (main/master → prod, develop → dev)
Configuração de projeto .q-ring.json
Ambiente padrão do segredo

# See what environment q-ring detects
qring env

# Project config (.q-ring.json)
echo '{"env": "staging", "branchMap": {"release/*": "staging"}}' > .q-ring.json

Decaimento Quântico — Segredos com TTL

Segredos podem ter um tempo de vida. Segredos expirados são bloqueados para leitura. Segredos obsoletos (75%+ da vida útil) disparam avisos.

# Set a secret that expires in 1 hour
qring set SESSION_TOKEN "tok-..." --ttl 3600

# Set with explicit expiry
qring set CERT_KEY "..." --expires "2026-06-01T00:00:00Z"

# Health check shows decay status
qring health

Efeito Observador — Audite Tudo

Toda leitura, escrita e exclusão de segredo é registrada com uma cadeia de hash à prova de adulteração. Padrões de acesso são rastreados para detecção de anomalias.

# View audit log
qring audit
qring audit --key OPENAI_KEY --limit 50

# Detect anomalies (burst access, unusual hours, chain tampering)
qring audit --anomalies

# Verify audit chain integrity
qring audit:verify

# Export audit log
qring audit:export --format json --since 2026-03-01
qring audit:export --format csv --output audit-report.csv

Ruído Quântico — Geração de Segredos

Gere segredos criptograficamente fortes em formatos comuns.

qring generate                          # API key (default)
qring generate --format password -l 32  # Strong password
qring generate --format uuid            # UUID v4
qring generate --format token           # Base64url token
qring generate --format hex -l 64       # 64-byte hex
qring generate --format api-key --prefix "sk-live-" --save STRIPE_KEY

Entrelaçamento — Segredos Vinculados

Vincule segredos entre projetos. Quando você rotaciona um, todas as cópias entrelaçadas são atualizadas automaticamente.

# Entangle two secrets
qring entangle API_KEY API_KEY_BACKUP

# Now updating API_KEY also updates API_KEY_BACKUP
qring set API_KEY "new-value"

# Unlink entangled secrets
qring disentangle API_KEY API_KEY_BACKUP

Tunelamento — Segredos Efêmeros

Crie segredos que existem apenas em memória. Eles nunca tocam o disco. TTL opcional e autodestruição por máximo de leituras.

# Create an ephemeral secret (returns tunnel ID)
qring tunnel create "temporary-token-xyz" --ttl 300 --max-reads 1

# Read it (self-destructs after this read)
qring tunnel read tun_abc123

# List active tunnels
qring tunnel list

Teletransporte — Compartilhamento Criptografado

Empacote segredos em pacotes criptografados com AES-256-GCM para transferência segura entre máquinas. Duas formas de proteger um pacote:

Frase secreta (v1): chaves derivadas com PBKDF2-HMAC-SHA512 (210.000 iterações); cada pacote registra sua contagem de iterações, então pacotes antigos ainda podem ser desempacotados.
Destinatários (v2, 0.18): cada membro da equipe executa qring teleport keygen uma vez e compartilha sua string de destinatário (qring1…, uma chave pública X25519; a metade privada vive no keychain do sistema operacional). O pack --to criptografa uma nova chave de conteúdo para cada destinatário — HKDF-SHA256 sobre um acordo X25519 efêmero, AES-256-GCM em todo o processo, apenas node:crypto — para que nada secreto viaje junto ao pacote e ninguém precise sussurrar uma frase secreta.

# Passphrase bundle (prompts)
qring teleport pack --keys "API_KEY,DB_PASS" > bundle.txt
cat bundle.txt | qring teleport unpack

# Recipient bundle: teammates publish their recipient once…
qring teleport keygen            # → qring1a3F…  (share this; keep the keyring)
qring teleport identity          # print it again later

# …then you address the pack to them (repeatable or comma-separated)
qring teleport pack --keys "API_KEY,DB_PASS" --to qring1a3F… --to qring1Zz9… > bundle.txt

# They unpack with the identity in their keyring — no passphrase
cat bundle.txt | qring teleport unpack

# Preview: who it's addressed to, whether that's you, and what's inside
qring teleport unpack <bundle> --dry-run

Importação — Ingestão em Massa de Segredos

Importe segredos de arquivos .env diretamente para o q-ring. Suporta sintaxe padrão de dotenv, incluindo comentários, valores entre aspas e sequências de escape. A CLI aceita um caminho de arquivo ou conteúdo bruto; a ferramenta MCP import_dotenv aceita apenas conteúdo bruto (ela nunca lê arquivos do disco), para que um agente não possa forçá-la a ler arquivos locais arbitrários.

# Import all secrets from a .env file
qring import .env

# Import to project scope, skipping existing keys
qring import .env --project --skip-existing

# Preview what would be imported
qring import .env --dry-run

Exportação Seletiva

Exporte apenas os segredos necessários usando nomes de chave ou filtros de tag.

# Export specific keys
qring export --keys "API_KEY,DB_PASS,REDIS_URL"

# Export by tag
qring export --tags "backend"

# Combine with format
qring export --keys "API_KEY,DB_PASS" --format json

Pesquisa e Filtragem de Segredos

Filtre a saída de qring list por tag, estado de expiração ou padrão de chave.

# Filter by tag
qring list --tag backend

# Show only expired secrets
qring list --expired

# Show only stale secrets (75%+ decay)
qring list --stale

# Glob pattern on key name
qring list --filter "API_*"

# Script-friendly existence check (exit 0 if present, 1 if not; decay-aware)
qring has OPENAI_API_KEY --quiet && echo "configured"

Manifesto de Segredos do Projeto

Declare segredos necessários em .q-ring.json e valide a prontidão do projeto com um único comando.

# Validate project secrets against the manifest
qring check

# See which secrets are present, missing, expired, or stale
qring check --project-path /path/to/project

Sincronização de Arquivo Env

Gere um arquivo .env a partir do manifesto do projeto, resolvendo cada chave do q-ring com colapso de superposição ciente do ambiente.

# Generate to stdout
qring env:generate

# Write to a file
qring env:generate --output .env

# Force a specific environment
qring env:generate --env staging --output .env.staging

Referências de Segredos e Execução com Menor Privilégio

Uma referência qring:// é um ponteiro versionável para um segredo — ela vai no seu arquivo .env em vez do valor. O qring run resolve referências e chaves do manifesto no momento da execução, injetando apenas o que o projeto declara (diferente do exec, que injeta todo o escopo). A saída é automaticamente redigida.

# .env — safe to commit: these are references, not values
DATABASE_URL=qring://project/DATABASE_URL
OPENAI_API_KEY=qring://global/OPENAI_API_KEY
STRIPE_KEY=qring:///STRIPE_KEY            # auto scope: project, then global
SESSION_TTL=3600                          # plain values pass through

# Run with declared secrets injected (manifest + .env refs)
qring run -- pnpm dev

# Preview what would be injected, without running
qring run --dry-run -- pnpm dev

# Pin an environment, use a specific env file, or skip the manifest
qring run --env prod --env-file .env.prod --no-manifest -- ./deploy.sh

A chave vive no caminho, nunca no host (qring://project/KEY, não qring://KEY) — hosts de URL não diferenciam maiúsculas de minúsculas, e chaves de variáveis de ambiente diferenciam. Referências malformadas falham ruidosamente em vez de vazar uma string literal qring://… para o processo filho. Uma referência fixada a um ambiente: qring://project/DATABASE_URL?env=prod.

Configuração do Editor

Conecte o servidor MCP do q-ring à configuração MCP de um editor com um único comando. Faz merge de forma não destrutiva — outros servidores são preservados, e uma entrada existente do q-ring só é substituída com --force.

qring setup cursor          # .cursor/mcp.json (project) or --global for ~/.cursor
qring setup kiro            # .kiro/settings/mcp.json, with read-only autoApprove list
qring setup claude          # .mcp.json (project scope)

# Preview without writing
qring setup cursor --dry-run

Envio para Plataformas de Implantação

Envie segredos do manifesto para GitHub Actions, Vercel, Cloudflare Workers, fly.io, Railway ou Netlify através da própria CLI autenticada de cada plataforma (gh / vercel / wrangler / flyctl / railway / netlify) — o q-ring nunca guarda tokens de plataforma, e os valores trafegam via stdin (ou, para a CLI de importação do Netlify, um arquivo temporário 0600 que é removido imediatamente), nunca via argv. Cada envio é registrado na cadeia de auditoria.

# Push the .q-ring.json manifest keys to GitHub Actions secrets
qring push github --repo you/your-app

# Push to Vercel environments
qring push vercel --vercel-env production,preview

# Push to Cloudflare Workers secrets
qring push cloudflare

# fly.io (flyctl secrets import over stdin — note flyctl deploys per import), Railway, Netlify
qring push fly --app my-app
qring push railway --service api --railway-env production
qring push netlify --site 1234-abcd

# Explicit keys, preview first
qring push github --keys DATABASE_URL,API_KEY --dry-run

Canários podem acompanhar: o qring canary plant KEY --format aws --push github planta um honeytoken localmente e o semeia na plataforma sem lê-lo de volta (veja Canary Honeytokens).

Validação de Vitalidade de Segredos

Teste se um segredo é realmente válido com o serviço de destino. O q-ring detecta automaticamente o provedor a partir de prefixos de chave (sk- → OpenAI, ghp_ → GitHub, etc.) ou aceita um nome de provedor explícito.

# Validate a single secret
qring validate OPENAI_API_KEY

# Force a specific provider
qring validate SOME_KEY --provider stripe

# Validate all secrets with detectable providers
qring validate --all

# Only validate manifest-declared secrets
qring validate --all --manifest

# List available providers
qring validate --list-providers

Provedores integrados: OpenAI, Anthropic, OpenRouter, Google AI (Gemini), Groq, Hugging Face, ElevenLabs*, Vercel*, Stripe, GitHub, AWS (verificação de formato), HTTP genérico. Chaves são enviadas apenas em cabeçalhos, nunca em URLs. (*sem prefixo público seguro — selecione explicitamente com --provider ou o campo provider do manifesto.)

Saída:

  ✓ OPENAI_API_KEY   valid    (openai, 342ms)
  ✗ STRIPE_KEY       invalid  (stripe, 128ms) — API key has been revoked
  ⚠ AWS_ACCESS_KEY   error    (aws, 10002ms) — network timeout
  ○ DATABASE_URL     unknown  — no provider detected

Hooks — Callbacks em Mudança de Segredo

Registre webhooks, comandos de shell ou sinais de processo que disparam quando segredos são criados, atualizados ou excluídos. Suporta correspondência de chaves, padrões glob, filtragem por tag e restrições de escopo.

# Run a shell command when a secret changes
qring hook add --key DB_PASS --exec "docker restart app"

# POST to a webhook on any write/delete
qring hook add --key API_KEY --url "https://hooks.example.com/rotate"

# Trigger on all secrets tagged "backend"
qring hook add --tag backend --exec "pm2 restart all"

# Signal a process when DB secrets change
qring hook add --key-pattern "DB_*" --signal-target "node"

# List all hooks
qring hook list

# Remove a hook
qring hook remove <id>

# Enable/disable
qring hook enable <id>
qring hook disable <id>

# Dry-run test a hook
qring hook test <id>

Hooks são fire-and-forget: um hook com falha nunca bloqueia operações de segredo. O registro de hooks é armazenado em ~/.config/q-ring/hooks.json.

Proteção SSRF: URLs de hooks HTTP que apontam para faixas de IP privadas/loopback (127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16, ::1, fc00::/7) são bloqueadas por padrão. O DNS é verificado antecipadamente e revalidado no momento da conexão, para que um hostname não possa passar na verificação e depois fazer rebind para um endereço privado antes de o socket abrir. Para permitir hooks direcionados a serviços locais (ex.: durante o desenvolvimento), defina a variável de ambiente Q_RING_ALLOW_PRIVATE_HOOKS=1.

Rotação Configurável

Defina um formato de rotação por segredo para que o agente rotacione automaticamente com o formato de valor correto, e um intervalo de rotação para que o q-ring lembre você antes de uma credencial ficar obsoleta. Cada segredo lembra quando seu valor mudou pela última vez (rotatedAt); com --rotate-every, ele fica próximo do vencimento nos últimos 20% do intervalo (ou nos últimos 7 dias, o que for menor) e vencido após isso — em qring inspect, qring rotate:due, no cartão "Rotacionar em breve" do painel e na ferramenta inspect_secret.

# Store a secret with rotation format metadata
qring set STRIPE_KEY "sk-..." --rotation-format api-key --rotation-prefix "sk-"

# Store a password with password rotation format
qring set DB_PASS "..." --rotation-format password

# Remind me every 90 days
qring set STRIPE_KEY "sk-..." --rotate-every 90

# What needs rotating? (most overdue first; --all lists every scheduled secret)
qring rotate:due
qring rotate:due --json

Execução Segura e Redação Automática

Execute comandos com segredos injetados com segurança no ambiente. Todos os valores de segredo conhecidos são automaticamente redigidos de stdout e stderr para evitar vazamento em logs de terminal ou transcrições de agentes. Perfis de execução restringem quais comandos podem ser executados.

# Execute a deployment script with secrets injected
qring exec -- npm run deploy

# Inject only specific tags
qring exec --tags backend -- node server.js

# Run with a restricted profile (blocks network tools and interpreters/shells, 30s timeout)
qring exec --profile restricted -- npm test

Scanner de Segredos em Base de Código

Migrando uma base de código legada? Digitalize rapidamente diretórios em busca de credenciais hardcoded usando heurísticas de regex e análise de entropia de Shannon.

# Scan current directory
qring scan .

Saída:

  ✗ src/db/connection.js:12
    Key:     DB_PASSWORD
    Entropy: 4.23
    Context: const DB_PASSWORD = "..."

Segredos Compostos / Modelados

Armazene strings de conexão complexas que resolvem dinamicamente outros segredos. Se DB_PASS rotacionar, DB_URL fica automaticamente correto sem atualizações manuais.

qring set DB_USER "admin"
qring set DB_PASS "supersecret"
qring set DB_URL "postgres://{{DB_USER}}:{{DB_PASS}}@localhost/mydb"

# Resolves embedded templates automatically
qring get DB_URL 
# Output: postgres://admin:supersecret@localhost/mydb

Aprovações de Usuário (Agente Zero-Confiança)

Proteja segredos de produção sensíveis de serem lidos autonomamente pelo servidor MCP sem aprovação explícita do usuário. Cada token de aprovação é verificado por HMAC, com escopo, justificativa e limite de tempo. A proteção se aplica também a leituras em massa — export_secrets e teleport_pack via MCP pulam chaves protegidas por aprovação que não tenham uma concessão válida.

# Mark a secret as requiring approval
qring set PROD_DB_URL "..." --requires-approval

# Temporarily grant MCP access for 1 hour with a reason
qring approve PROD_DB_URL --for 3600 --reason "deploying v2.0"

# List all approvals with verification status
qring approvals

# Revoke an approval
qring approve PROD_DB_URL --revoke

Quando um agente é bloqueado em uma chave protegida por aprovação, o q-ring exibe uma notificação de desktop (Linux notify-send, macOS osascript) nomeando a chave e o comando exato qring approve — limitada por chave, desativada com QRING_NOTIFY=off.

Canary Honeytokens

Plante credenciais falsas que parecem e são lidas exatamente como as reais. Qualquer coisa que toque uma delas — um servidor MCP comprometido, um agente curioso demais, ferramentas exfiltradas varrendo o anel — recebe o valor falso de volta sem nenhum indício, enquanto o q-ring dispara um alerta de desktop e grava um evento canary na cadeia de auditoria à prova de adulteração.

# Plant a canary shaped like a real AWS access key
qring canary plant AWS_SECRET_ACCESS_KEY --format aws

# Other shapes: aws-secret, github, github-pat, openai, openai-project,
# anthropic, stripe, gitlab, slack, google, npm, generic
qring canary plant GHP_BACKUP_TOKEN --format github-pat

# See what's been tripped
qring canary list
qring audit --action canary

Os valores são ruído CSPRNG no formato real de token do provedor (um canário aws corresponde a AKIA[A-Z0-9]{16}, um anthropic ao layout real de sk-ant-api03-…AA) — plausíveis o suficiente para serem capturados, nunca válidos. Alertas são limitados a um por chave a cada 30 segundos; a trilha de auditoria registra cada leitura.

Seja acionado. Notificações de desktop só ajudam quando você está na máquina. Registre canais de webhook e cada disparo também chega até eles:

qring canary alert add --discord https://discord.com/api/webhooks/…
qring canary alert add --slack   https://hooks.slack.com/services/…
qring canary alert add --ntfy    https://ntfy.sh/my-canaries
qring canary alert add --url     https://example.com/canary   # generic JSON POST
qring canary alert list
qring canary alert test          # send a clearly-labelled drill

Channels vivem em ~/.config/q-ring/canary-alerts.json (modo 0600). Envios são fire-and-forget, protegidos contra SSRF como hooks, limitados junto com o alerta da área de trabalho, e nunca incluem o valor falso — apenas a chave, o escopo, a origem e o rótulo do agente que o acessou.

Plante um tripwire no CI. Plante um canário e envie-o para uma plataforma de deploy em um único passo, para que um ambiente vazado do GitHub Actions / Vercel / Cloudflare carregue um chamariz:

qring canary plant AWS_SECRET_ACCESS_KEY --format aws-secret --push github --repo you/your-app

Advertência honesta: o q-ring só enxerga leituras que passam pelo q-ring. Um valor vazado usado diretamente no lado da plataforma não é observável aqui — combine com o alerta do próprio provedor se precisar disso.

Canários são feitos para permanecerem ocultos: eles não carregam descrição identificadora (adicione uma história de capa inofensiva com --description se quiser), sua flag nunca aparece nas respostas das ferramentas MCP, e os registros de disparo são visíveis apenas no terminal do operador — nunca para agentes via ferramentas de auditoria MCP. export e delete em massa os disparam assim como leituras, então varrer o anel ou remover o tripwire ambos tocam o alarme. Terminou com um? qring canary disarm <key> o transforma de volta em um segredo comum (qring set sobre um canário avisa você primeiro — a flag sobrevive deliberadamente a sobrescritas para que um agente não possa lavá-la).

Airlock MCP

Execute um servidor MCP de terceiros atrás do q-ring. O airlock fica entre o host do seu agente e o servidor encapsulado, inicia-o com um ambiente limpo (sem chaves de API herdadas — opte por reativá-las com --inherit-env), registra cada chamada de ferramenta, leitura de recurso e busca de prompt que o atravessa como um evento wrap na cadeia de auditoria (agrupado por sessão e rotulado com a identidade do cliente chamador), remove valores de segredos conhecidos de cada resultado antes de chegar à transcrição, e aplica as regras de policy.wrap do projeto. Argumentos de ferramentas e prompts nunca são registrados — eles podem conter segredos.

{
  "mcpServers": {
    "some-server": {
      "command": "qring",
      "args": ["mcp", "wrap", "--", "npx", "-y", "some-mcp-server"]
    }
  }
}

Ferramentas, recursos e prompts passam todos intactos (paginação, notificações de progresso, cancelamento, assinaturas e as notificações list_changed / updated incluídas); o airlock anuncia exatamente as capacidades que o servidor encapsulado possui. Ferramentas de longa duração são governadas pelo timeout do próprio host, com um teto generoso do airlock configurável via QRING_WRAP_TIMEOUT_MS.

# Wrap a remote Streamable HTTP server; the Bearer token comes from q-ring (audited read)
qring mcp wrap --url https://mcp.example.com/mcp --auth-secret EXAMPLE_MCP_TOKEN

# Keep results verbatim (default: known secret values are replaced with [QRING:REDACTED])
qring mcp wrap --no-redact -- npx -y some-mcp-server

Política de encapsulamento. Governa o servidor encapsulado a partir de .q-ring.json — o mesmo arquivo, o mesmo motor fail-closed:

{
  "policy": {
    "wrap": {
      "allowTools": ["github_*", "search"],
      "denyTools": ["github_delete_*"],
      "approveTools": ["github_merge_pr"],
      "rateLimit": { "maxCalls": 60, "perSeconds": 60 },
      "toolRateLimits": { "search": { "maxCalls": 5, "perSeconds": 10 } },
      "redactResults": true
    }
  }
}

Ferramentas negadas ficam ocultas de tools/list e são recusadas na chamada com um evento de auditoria policy_deny; approveTools são recusadas até que você as conceda:

qring mcp approve github_merge_pr --for 900 --reason "release 1.4"
qring mcp approvals
qring mcp approve github_merge_pr --revoke

Seja claro sobre o que o airlock é: limpeza de ambiente, um registro à prova de adulteração de cada travessia, política na fronteira das ferramentas e remoção de valores de segredos que o anel conhece com melhor esforço. Ele não é um sandbox — o processo encapsulado ainda roda como seu usuário com acesso normal a sistema de arquivos, rede e chaveiro do SO, e descrições de ferramentas passam sem inspeção. Veja docs/threat-model.md para o quadro honesto de fronteiras.

Provisionamento Just-In-Time (JIT)

Em vez de armazenar credenciais estáticas, configure q-ring para gerar dinamicamente tokens de curta duração sob demanda quando solicitado (ex.: AWS STS, endpoints HTTP genéricos).

# Store the STS role configuration
qring set AWS_TEMP_KEYS '{"roleArn":"arn:aws:iam::123:role/AgentRole", "durationSeconds":3600}' --jit-provider aws-sts

# Resolving the secret automatically assumes the role and caches the temporary token
qring get AWS_TEMP_KEYS

Contexto de Projeto para Agentes de IA

Uma visão geral segura e editada dos segredos, configuração e estado do projeto. Projetada para ser alimentada no prompt de sistema de um agente de IA sem nunca expor valores de segredos.

# Human-readable summary
qring context

# JSON output (for MCP / programmatic use)
qring context --json

Linter Ciente de Segredos

Escaneie arquivos específicos em busca de segredos codificados com correção automática opcional. Quando --fix é usado, segredos detectados são substituídos por referências process.env.KEY e armazenados no q-ring.

# Lint files for hardcoded secrets
qring lint src/config.ts src/db.ts

# Auto-fix: replace hardcoded values and store in q-ring
qring lint src/config.ts --fix

# Scan entire directory with auto-fix
qring scan . --fix

Memória do Agente

Armazenamento de chave-valor criptografado e persistente que sobrevive entre sessões de agentes de IA. Útil para lembrar histórico de rotação, decisões de projeto ou contexto.

# Store a memory
qring remember last_rotation "Rotated STRIPE_KEY on 2026-03-21"

# Retrieve it
qring recall last_rotation

# List all memories
qring recall

# Forget
qring forget last_rotation

Varredura de Segredos Pré-Commit

Instale um hook de pre-commit do git que bloqueia automaticamente commits contendo segredos codificados.

# Install the hook
qring hook:install

# Uninstall
qring hook:uninstall

Análise de Segredos

Analise padrões de uso e obtenha sugestões de otimização para seus segredos.

qring analyze

A saída inclui segredos mais acessados, segredos não utilizados/obsoletos, sugestões de otimização de escopo e recomendações de rotação.

Assistente de Configuração de Serviço

Configure rapidamente uma nova integração de serviço com segredos, entradas de manifesto e hooks em um único comando.

# Create secrets for a new Stripe integration
qring wizard stripe --keys STRIPE_KEY,STRIPE_SECRET --provider stripe --tags payment

# With a hook to restart the app on change
qring wizard myservice --hook-exec "pm2 restart app"

Política de Governança

Defina regras de governança no nível do projeto em .q-ring.json para controlar quais ferramentas MCP podem ser usadas, quais chaves são acessíveis, quais comandos podem ser executados e o que um servidor MCP encapsulado pode fazer atrás do airlock. A política é aplicada no nível do servidor MCP, do chaveiro e do airlock.

Via MCP, a política é resolvida a partir do diretório em que o servidor foi iniciado — não do projectPath que um chamador passa — então um agente não pode contornar restrições apontando para um diretório sem política. Inicie o servidor MCP a partir da raiz do seu projeto (onde .q-ring.json reside). Edições em .q-ring.json são detectadas automaticamente (o cache de política é invalidado na mudança de arquivo), então você não precisa reiniciar o servidor.

Arquivos de política são validados por esquema e falham fechados: um objeto policy inválido (digamos, um erro de digitação como denytools) levanta um PolicyConfigError em vez de ser silenciosamente ignorado, então uma regra malformada nunca pode ampliar o acesso.

# View the active policy
qring policy

# JSON output
qring policy --json

Exemplo de política em .q-ring.json:

{
  "policy": {
    "mcp": {
      "denyTools": ["delete_secret"],
      "deniedKeys": ["PROD_DB_PASSWORD"],
      "deniedTags": ["production"]
    },
    "exec": {
      "denyCommands": ["curl", "wget", "ssh"],
      "maxRuntimeSeconds": 30
    },
    "secrets": {
      "requireApprovalForTags": ["production"],
      "maxTtlSeconds": 86400
    },
    "wrap": {
      "denyTools": ["*_delete_*"],
      "approveTools": ["deploy_*"],
      "rateLimit": { "maxCalls": 60, "perSeconds": 60 }
    }
  }
}

Perfis de Execução

Restrinja a execução de comandos com perfis nomeados que controlam comandos permitidos, acesso à rede, timeouts e sanitização de ambiente.

# Run with the "restricted" profile (blocks network tools and interpreters/shells; 30s timeout)
qring exec --profile restricted -- npm test

# Run with the "ci" profile (5min timeout, allows network)
qring exec --profile ci -- npm run deploy

# Default: unrestricted
qring exec -- echo "hello"

Perfis integrados: unrestricted, restricted (nega ferramentas de rede e interpretadores/shells — python -c, node -e, bash e amigos não podem exfiltrar segredos injetados; limite de 30s), ci (limite de 5min, bloqueia comandos destrutivos).

Auditoria à Prova de Adulteração

Cada evento de auditoria inclui um hash SHA-256 do evento anterior, criando uma cadeia à prova de adulteração. Desde a v0.14, a cadeia também é ancorada com um HMAC chaveado armazenado no chaveiro do SO, então qring audit:verify detecta truncamento e reescritas de arquivo inteiro — não apenas edições no lugar. Verifique a integridade e exporte logs em múltiplos formatos. Eventos de sessões MCP são adicionalmente carimbados com a identidade auto-relatada do cliente conectado (clientInfo nome@versão) — mostrada na saída de qring audit e filtrável com qring audit --agent <label>. É um rótulo de auditoria para "qual agente fez isso", nunca uma fronteira de autorização, já que os clientes escolhem o que relatar.

# Verify the entire audit chain
qring audit:verify

# Export as JSON
qring audit:export --format json --since 2026-03-01

# Export as CSV
qring audit:export --format csv --output audit-report.csv

Linha do Tempo de Sessão do Agente

Cada sessão MCP é carimbada com a identidade do cliente (clientInfo nome@versão) e cada sessão de airlock com um id de correlação. audit:sessions dobra o feed de auditoria plano de volta em uma linha do tempo por processo de agente, então "o que o Cursor fez naquela sessão?" é um comando em vez de um grep.

# One block per session: agent, source, window, event + denial counts, keys touched
qring audit:sessions

# Narrow to one client, widen the window, print every event line
qring audit:sessions --agent "Cursor@1.2.3" --since 7d --verbose

# Machine-readable
qring audit:sessions --json

Sessões de airlock (qring mcp wrap) aparecem como airlock: <wrapped command> com cada chamada proxy em ordem. O painel de status (qring status) renderiza os mesmos dados como um cartão expansível Sessões de Agente (24h).

Agentes também podem olhar seu próprio histórico — como recursos MCP, não ferramentas: qring://sessions lista resumos de sessão e qring://sessions/{id} retorna uma linha do tempo (apenas nomes de chaves e ações, nunca valores). Duas garantias valem no lado do agente: disparos de canário são removidos antes de qualquer resumo, então um honeytoken nunca pode ser descoberto a partir de uma visão de sessão, e negar a ferramenta audit_log na política .q-ring.json também oculta os recursos — um único interruptor controla a visibilidade de auditoria para agentes.

Backend de Arquivo Criptografado (Headless / CI)

Hosts sem nenhum chaveiro do SO (Linux headless, contêineres, CI) podem optar por um armazenamento de arquivo criptografado. Tudo — segredos, a âncora de auditoria, a chave de memória do agente — passa por ele.

export QRING_BACKEND=file
export QRING_FILE_PASSPHRASE="a strong passphrase"   # required — no passphrase, no access
qring set CI_TOKEN

O armazenamento é AES-256-GCM em ~/.config/q-ring/file-backend.enc (modo 0600, substituição de caminho via QRING_FILE_BACKEND_PATH), chaveado por PBKDF2 a partir da frase secreta. É somente explícito: um chaveiro do SO ausente nunca cai nele silenciosamente, e sem a frase secreta toda operação falha fechada — o q-ring nunca criptografa sob uma chave derivável por máquina.

Escopos de Equipe e Organização

Estenda além dos escopos global e project com escopos team e org para segredos compartilhados entre grupos. Ordem de resolução: projeto → equipe → organização → global (o mais específico vence).

# Store a secret in team scope
qring set SHARED_API_KEY "sk-..." --team my-team

# Store in org scope
qring set ORG_LICENSE "lic-..." --org acme-corp

# Resolution cascades: project > team > org > global
qring get API_KEY --team my-team --org acme-corp

Rotação Nativa do Emissor

Tente rotação de segredos nativa do provedor (para provedores que a suportam) ou recorra à geração local.

# Rotate via the detected provider
qring rotate STRIPE_KEY

# Force a specific provider
qring rotate API_KEY --provider openai

Validação de Segredos em CI

Valide em lote todos os segredos contra seus provedores em um modo amigável para CI. Retorna um relatório estruturado de aprovado/reprovado com código de saída 1 em falha.

# Validate all secrets (CI mode)
qring ci:validate

# JSON output for pipeline parsing
qring ci:validate --json

Modo Agente — Monitoramento Autônomo

Um daemon em segundo plano que monitora continuamente a saúde dos segredos, detecta anomalias e, opcionalmente, auto-rotaciona segredos expirados.

# Start the agent
qring agent --interval 60 --verbose

# With auto-rotation of expired secrets
qring agent --auto-rotate

# Single scan (for CI/cron)
qring agent --once

Painel de Status Quântico — Monitoramento ao Vivo

Inicie um painel em tempo real no seu navegador que transforma todo o subsistema quântico em uma única página visível de relance. É uma única página HTML autocontida servida localmente — sem nuvem, sem configuração, totalmente offline — construída como um aplicativo Preact + htm (runtime empacotado e embutido). Ela transmite atualizações a cada 5 segundos via Server-Sent Events e faz diff do DOM no lugar, então os dados são atualizados sem reexecutar animações de entrada e sua entrada de pesquisa, cursor e posição de rolagem são preservados entre ticks.

O que você obtém:

Faixa de KPIs — total de segredos, ambiente detectado, contagem protegida, aprovações ativas, hooks, leituras de 24 horas e contagem de anomalias ao vivo.
Resumo de saúde — gráfico de rosca de segredos saudáveis / obsoletos / expirados / sem decaimento, além de contagens por escopo (global / projeto / equipe / organização).
Ambiente — detalhes do colapso da função de onda: ambiente detectado, origem, branch e qualquer contexto de projeto.
Manifesto — resumo de .q-ring.json com chaves declaradas / exigidas / ausentes / expiradas / obsoletas.
Política — visão rápida das políticas MCP, exec e de segredos (permitir/negar ferramentas, negar chaves/tags, permitir/negar comandos, requisitos de aprovação e rotação).
Tabela de segredos — visão pesquisável e ordenável de cada segredo (chave, escopo, ambiente, tipo, decaimento, tags, última leitura), com chips rápidos para filtros expired, stale e protected. Pressione / para focar a caixa de pesquisa.
Cartões quânticos — temporizadores de decaimento, estados de superposição, pares de entrelaçamento e túneis quânticos ativos.
Aprovações e hooks — lista ao vivo de concessões de aprovação válidas (e adulteradas) e cada hook registrado com seu resumo de correspondência.
Sessões de agente (24h) — uma linha expansível por cliente MCP ou sessão de airlock: rótulo do agente, origem, janela, contagens de eventos e negações, eventos recentes.
Memória do agente — contagem de chaves de memória criptografadas persistidas em ~/.config/q-ring/agent-memory.enc.
Alertas de anomalia — leituras em rajada, acesso fora do horário, cadeia de auditoria adulterada e outros padrões suspeitos.
Log de auditoria (24h) — feed filtrável com chips de ação (read/write/delete/export), chips de origem (cli/mcp/hook/agent) e um filtro de texto livre.

Controles da barra superior permitem pausar atualizações SSE (útil ao ler o feed de auditoria), atualizar sob demanda ou pular para o instantâneo JSON bruto em /api/status. Atalhos de teclado: / foca a pesquisa de segredos · P pausa · R atualiza. O painel vincula-se apenas a 127.0.0.1 e nunca expõe valores secretos, mas ele exibe nomes de chaves, o log de auditoria e concessões de aprovação — portanto, cada rota é protegida por um token aleatório gerado por inicialização. qring status imprime (e abre) a URL completa incluindo ?token=…; requisições sem o token recebem um 403. Pare o servidor para invalidar o token.

# Open the dashboard (auto-launches your browser at http://127.0.0.1:9876/?token=…)
qring status

# Specify a custom port
qring status --port 4200

# Don't auto-open the browser (copy the printed tokenized URL yourself)
qring status --no-open

Servidor MCP

O q-ring inclui um servidor MCP completo com 46 ferramentas para integração com agentes de IA.

Ferramentas Principais

Ferramenta	Descrição
`get_secret`	Lê um valor secreto (colapsa a superposição, audita a leitura)
`list_secrets`	Lista chaves + metadados no escopo (valores nunca expostos); filtra por tag, expiração, glob
`set_secret`	Cria ou sobrescreve um único segredo com TTL opcional, estado por ambiente, tags, formato de rotação
`promote_secret`	Copia o valor de um segredo de um estado de ambiente para outro (no-op quando iguais; `force` para sobrescrever um destino diferente)
`diff_environments`	Compara dois ambientes chave por chave — iguais / diferentes / apenas-a / apenas-b / colapsados; apenas status, nunca valores
`delete_secret`	Remove permanentemente um valor secreto (não é desfazível pelo q-ring)
`has_secret`	Verificação booleana de existência que respeita decaimento (sem leitura auditada)
`export_secrets`	Renderiza múltiplos segredos como `.env` ou JSON para exportação pontual (ignora chaves protegidas por aprovação sem concessão)
`import_dotenv`	Analisa texto `.env` e armazena em massa cada par chave/valor (aceita apenas conteúdo bruto — nunca lê arquivos)
`check_project`	Compara o manifesto `.q-ring.json` com o chaveiro para chaves ausentes/expiradas/desatualizadas
`env_generate`	Renderiza um corpo `.env` completo a partir do manifesto do projeto, com avisos para lacunas

Ferramentas Quânticas

Ferramenta	Descrição
`inspect_secret`	Mostra metadados de uma chave (estados, decaimento, emaranhamento, contagem de acessos) sem revelar o valor
`detect_environment`	Resolve qual slug de ambiente deve conduzir o colapso da superposição para o contexto atual
`generate_secret`	Gera um valor com suporte CSPRNG em um formato escolhido e opcionalmente o armazena
`entangle_secrets`	Vincula duas chaves para que gravações/rotações futuras propaguem o mesmo valor
`disentangle_secrets`	Quebra o vínculo de sincronização entre duas chaves (não exclui valores)

Ferramentas de Tunelamento

Ferramenta	Descrição
`tunnel_create`	Guarda um valor na memória do processo e retorna um ID opaco (nunca toca o disco)
`tunnel_read`	Busca um valor tunelado por ID — pode se autodestruir na leitura
`tunnel_list`	Enumera túneis ativos com orçamento de leitura restante e TTL (apenas IDs)
`tunnel_destroy`	Remove imediatamente um túnel da memória antes que seu TTL/leituras se esgotem

Ferramentas de Teletransporte

Ferramenta	Descrição
`teleport_pack`	Criptografa segredos selecionados em um pacote AES-256-GCM protegido por senha
`teleport_unpack`	Descriptografa um pacote de teletransporte e importa cada segredo (com dry-run opcional)

Ferramentas de Validação

Ferramenta	Descrição
`validate_secret`	Acessa o serviço upstream (OpenAI/Stripe/GitHub/AWS/HTTP) para confirmar se uma única chave ainda está ativa
`list_providers`	Enumera provedores de validação integrados e seus prefixos de autodetecção

Ferramentas de Hook

Ferramenta	Descrição
`register_hook`	Registra um efeito colateral shell/HTTP/sinal que dispara em gravação/exclusão/rotação
`list_hooks`	Mostra cada hook registrado com critérios de correspondência, tipo e flag de ativação
`remove_hook`	Remove um único hook por ID sem tocar em nenhum segredo

Ferramentas de Execução e Varredura

Ferramenta	Descrição
`exec_with_secrets`	Executa um comando filho com segredos injetados como variáveis de ambiente e valores vazados redigidos na saída
`scan_codebase_for_secrets`	Percorre uma árvore de diretórios e sinaliza segredos hardcoded via regex + heurísticas de entropia
`lint_files`	Inspeciona uma lista específica de arquivos em busca de segredos hardcoded com correção automática opcional para `process.env.KEY`

Ferramentas para Agentes de IA

Ferramenta	Descrição
`get_project_context`	Snapshot único redigido de segredos, ambiente, manifesto, hooks e atividade de auditoria recente
`agent_remember`	Persiste uma nota não secreta na memória criptografada do agente entre sessões
`agent_recall`	Lê um valor de memória, ou lista cada chave armazenada quando nenhuma chave é fornecida
`agent_forget`	Exclui permanentemente uma chave da memória do agente
`analyze_secrets`	Perfil de uso: mais acessados, desatualizados, nunca acessados, candidatos sem rotação

Ferramentas de Observação e Saúde

Ferramenta	Descrição
`audit_log`	Consulta o log de auditoria à prova de adulteração filtrado por chave, ação e limite
`detect_anomalies`	Superfície de leituras em rajada e descobertas fora do horário comercial a partir do histórico de auditoria
`verify_audit_chain`	Recalcula a cadeia de hash de auditoria e relata o primeiro ponto de quebra se adulterado
`export_audit`	Exporta eventos de auditoria como jsonl, json ou csv para arquivamento/SIEM
`health_check`	Varredura de escopo somente leitura: contagens de decaimento/desatualizados/expirados mais anomalias atuais
`status_dashboard`	Inicia um painel SSE local com KPIs ao vivo, segredos, hooks e feed de auditoria (retorna uma URL `127.0.0.1` protegida por token)
`agent_scan`	Verificação de saúde multiprojeto com `autoRotate` opcional para segredos expirados

Ferramentas de Governança e Política

Ferramenta	Descrição
`check_policy`	Dry-run de uma ação de ferramenta/chave/exec contra a política `.q-ring.json` sem executá-la
`get_policy_summary`	Visão geral de alto nível das contagens de regras de política e requisitos de aprovação/rotação
`rotate_secret`	Solicita ao provedor upstream a emissão de uma nova credencial e a armazena de volta no chaveiro
`ci_validate_secrets`	Valida em lote cada segredo acessível no escopo e retorna um relatório estruturado de aprovado/reprovado

Configuração Cursor / Kiro

Adicione a .cursor/mcp.json ou .kiro/settings/mcp.json (ou deixe qring setup cursor / qring setup kiro escrever):

Se o q-ring estiver instalado globalmente (ex.: pnpm add -g @i4ctime/q-ring):

{
  "mcpServers": {
    "q-ring": {
      "command": "qring-mcp"
    }
  }
}

Se estiver usando um clone local:

{
  "mcpServers": {
    "q-ring": {
      "command": "node",
      "args": ["/path/to/q-ring/dist/mcp.js"]
    }
  }
}

Configuração Claude Code

Adicione a .mcp.json na raiz do projeto — ou execute qring setup claude, ou claude mcp add q-ring -- qring-mcp (Claude Desktop é o aplicativo que usa claude_desktop_config.json, não Claude Code):

Instalação global:

{
  "mcpServers": {
    "q-ring": {
      "command": "qring-mcp"
    }
  }
}

Clone local:

{
  "mcpServers": {
    "q-ring": {
      "command": "node",
      "args": ["/path/to/q-ring/dist/mcp.js"]
    }
  }
}

Configuração VS Code

O VS Code fala MCP nativamente — adicione a .vscode/mcp.json (observe a chave servers, não mcpServers):

{
  "servers": {
    "q-ring": {
      "command": "qring-mcp"
    }
  }
}

qring setup ainda não escreve este arquivo — VS Code é somente configuração (sem pacote de plugin de primeira parte).

Plugins de Editor

O repositório q-ring inclui três pacotes de editor de primeira parte — cada um adiciona regras/orientação, agentes, comandos, habilidades, hooks e o conector MCP ao seu editor host.

Plugin	Editor	Destaques
`cursor-plugin/`	Cursor	3 regras, 5 habilidades, 2 agentes, 8 comandos de barra, 3 hooks, autoconexão MCP
`kiro-plugin/`	Kiro	Layout oficial Power: `POWER.md`, raiz `mcp.json`, `steering/`, `hooks/`; ou achate com `plugin:sync:kiro`
`claude-code-plugin/`	Claude Code	Memória `CLAUDE.md`, `.mcp.json` do projeto, 2 subagentes, 8 comandos de barra, 6 habilidades, 3 scripts de hook

Plugin Cursor

O Plugin q-ring para Cursor traz o gerenciamento quântico de segredos diretamente para sua IDE com regras, habilidades, agentes, comandos, hooks e um conector MCP integrado.

Componente	O que faz
3 Regras	Orientação sempre ativa: nunca codifique segredos, use q-ring para todas as operações, avise sobre arquivos `.env`
5 Habilidades	Acionadas automaticamente por contexto: gerenciamento de segredos, varredura, rotação, onboarding de projeto, execução com segredos
2 Agentes	`security-auditor` (monitoramento proativo) e `secret-ops` (assistente do dia a dia)
8 Comandos	`/qring:scan-secrets`, `/qring:health-check`, `/qring:rotate-expired`, `/qring:setup-project`, `/qring:teleport-secrets`, `/qring:dashboard`, `/qring:exec-safe`, `/qring:analyze`
3 Hooks	`afterFileEdit` (varredura de lint), `sessionStart` (contexto do projeto), `beforeShellExecution` (proteção `.env`)
Conector MCP	Conecta automaticamente a `qring-mcp` via stdio — todas as 46 ferramentas disponíveis

Instale pelo marketplace do Cursor ou veja cursor-plugin/README.md para configuração manual.

Plugin Kiro (Power)

O diretório kiro-plugin/ é um Power do Kiro conforme Criar powers: POWER.md (metadados, onboarding, mapa de orientação), raiz mcp.json (o servidor MCP deve corresponder ao nome do servidor referenciado no power) e steering/ para fluxos de trabalho. Instale pelo Kiro → Powers → Adicionar power do caminho local e selecione kiro-plugin, ou publique a pasta no GitHub e use Adicionar power do GitHub.

A orientação sempre ativa bloqueia segredos hardcoded e roteia tudo pelo q-ring; os arquivos de orientação manual atuam como personas de agente (#qring-secret-ops, #qring-security-auditor), pacotes de habilidades e comandos estilo barra (#qring-cmd-scan-secrets, etc.). Hooks opcionais ficam em hooks/ para cópia em .kiro/hooks/.

# Alternative: flatten into ~/.kiro (settings + steering + hooks)
pnpm run plugin:sync:kiro

# Or scope to a single project
pnpm run plugin:sync:kiro -- /path/to/your/project/.kiro

Veja kiro-plugin/README.md para o detalhamento completo.

Plugin Claude Code

Para Claude Code, o q-ring inclui um arquivo de memória CLAUDE.md, um .mcp.json com escopo de projeto, dois subagentes (secret-ops, security-auditor), oito comandos de barra (/qring-scan-secrets, /qring-health-check, …), seis habilidades e três hooks (lembrete de lint pós-edição, proteção .env pré-Bash, primer de contexto no início da sessão).

# Install into the current project ($PWD)
pnpm run plugin:sync:claude

# Install agents/commands/skills/hooks at user scope (~/.claude)
pnpm run plugin:sync:claude -- --user

# Or target a specific project
pnpm run plugin:sync:claude -- /path/to/your/project

Arquivos CLAUDE.md, .mcp.json ou .claude/settings.json existentes nunca são sobrescritos silenciosamente — o script grava um <filename>.qring-template ao lado deles para que você possa mesclar manualmente. Passe --force para sobrescrever.

Veja claude-code-plugin/README.md para o detalhamento completo.

Arquitetura

qring CLI ─────┐
               ├──▶ Core Engine ──▶ @napi-rs/keyring ──▶ OS Keyring
MCP Server ────┘       │
                       ├── Envelope (quantum metadata)
                       ├── Scope Resolver (global / project / team / org)
                       ├── Collapse (env detection + branchMap globs)
                       ├── Observer (tamper-evident audit chain)
                       ├── Policy (governance-as-code engine)
                       ├── Noise (secret generation)
                       ├── Entanglement (cross-secret linking)
                       ├── Validate (provider-based liveness + rotation)
                       ├── Hooks (shell/HTTP/signal callbacks)
                       ├── Import (.env file ingestion)
                       ├── Exec (profile-restricted injection + redaction)
                       ├── Scan (codebase entropy heuristics)
                       ├── Provision (JIT ephemeral credentials)
                       ├── Approval (HMAC-verified zero-trust tokens)
                       ├── Context (safe redacted project view)
                       ├── Linter (secret-aware code scanning)
                       ├── Memory (encrypted agent persistence)
                       ├── Tunnel (ephemeral in-memory)
                       ├── Teleport (encrypted sharing)
                       ├── Agent (autonomous monitor + rotation)
                       └── Dashboard (live status via SSE)

Configuração do Projeto (`.q-ring.json`)

Configuração opcional por projeto:

{
  "env": "dev",
  "defaultEnv": "dev",
  "branchMap": {
    "main": "prod",
    "develop": "dev",
    "staging": "staging",
    "release/*": "staging",
    "feature/*": "dev"
  },
  "secrets": {
    "OPENAI_API_KEY": { "required": true, "description": "OpenAI API key", "format": "api-key", "prefix": "sk-", "provider": "openai" },
    "DATABASE_URL": { "required": true, "description": "Postgres connection string", "validationUrl": "https://api.example.com/health" },
    "SENTRY_DSN": { "required": false, "description": "Sentry error tracking" }
  },
  "policy": {
    "mcp": {
      "denyTools": ["delete_secret"],
      "deniedKeys": ["PROD_DB_PASSWORD"],
      "deniedTags": ["production"]
    },
    "exec": {
      "denyCommands": ["curl", "wget"],
      "maxRuntimeSeconds": 60
    }
  }
}

branchMap suporta padrões glob com curingas * (ex.: release/* corresponde a release/v1.0)
secrets declara os segredos obrigatórios do projeto — use qring check para validar, qring env:generate para produzir um arquivo .env
provider associa um provedor de validação de vivacidade a um segredo (ex.: "openai", "stripe", "github") — use qring validate para testar
validationUrl configura o endpoint do provedor HTTP genérico para validação personalizada
policy define regras de governança para controle de ferramentas MCP, restrições de acesso a chaves, allowlists de execução e requisitos de ciclo de vida de segredos

📚 Documentação

Início rápido: Claude Code · Cursor · Kiro
Solução de problemas — backends de chaveiro, conexão MCP, portão de aprovação, fixação de política
Paridade CLI ↔ MCP — cada comando mapeado para sua ferramenta MCP
Lançamentos — fluxo de lançamento orientado por tags

Contribuindo

Veja CONTRIBUTING.md para o guia completo (ambiente de desenvolvimento, convenções, arquivos para manter em sincronia). A versão resumida:

Execute pnpm run lint, pnpm run typecheck, e pnpm run test:ci antes de abrir um PR.
Testes ou sandboxes podem direcionar o log de auditoria para outro local com QRING_AUDIT_DIR (o diretório é criado se não existir); o padrão é ~/.config/q-ring/audit.jsonl.
Pré-commit local opcional: qring hook:install (usa o hook precommit deste pacote quando qring está no seu PATH).
Após alterar um dos plugins de editor:
- Cursor: pnpm run plugin:sync copia cursor-plugin/ para ~/.cursor/plugins/local/my-plugin (ou passe um caminho personalizado).
- Kiro: pnpm run plugin:sync:kiro copia kiro-plugin/mcp.json → ~/.kiro/settings/mcp.json, além de steering/ e hooks/ (ou passe um caminho de projeto .kiro). Prefira adicionar kiro-plugin/ como um Power no painel de Powers.
- Claude Code: pnpm run plugin:sync:claude copia claude-code-plugin/ para o diretório atual (ou passe um caminho de projeto; adicione --user para instalar em ~/.claude/).
Veja também docs/cli-mcp-parity.md.

🔒 Segurança

Local-first. O armazenamento principal é o chaveiro do seu sistema operacional — não há nuvem q-ring nem conta. A superfície MCP, o log de auditoria e a memória do agente ficam na sua máquina (arquivos de auditoria e memória são gravados somente para o proprietário, 0600).
Modelo de ameaça documentado. O que o q-ring protege, o que não protege e onde reside o risco residual — incluindo uma resposta honesta à questão de exfiltração por agente — em docs/threat-model.md.
Endurecido por revisão adversarial. A v0.14.0 trouxe os resultados de uma auditoria adversarial interna — descobertas de bypass de política, escopo de aprovação e perfis de execução foram corrigidas, cada uma com testes de regressão. Detalhes estão nas seções Security do CHANGELOG (estilo da casa desde 0.12.0: corrija primeiro, depois divulgue lá).
Reportando uma vulnerabilidade. Use o relatório privado de vulnerabilidades do GitHub — veja SECURITY.md para a tabela de versões suportadas e compromissos de resposta (confirmação em 48 horas, avaliação em 7 dias).

📜 Licença

AGPL-3.0 — Livre para usar, modificar e compartilhar. Qualquer trabalho derivado ou serviço hospedado deve liberar seu código-fonte sob a mesma licença.

q-ring

Documentação

q-ring

Por que q-ring?

🚀 Instalação

Docker (servidor MCP)

⚡ Início Rápido

Recursos Quânticos

Superposição — Uma Chave, Múltiplos Ambientes

Promoção de Ambiente — Compare, Depois Promova

Colapso da Função de Onda — Detecção Inteligente de Ambiente

Decaimento Quântico — Segredos com TTL

Efeito Observador — Audite Tudo

Ruído Quântico — Geração de Segredos

Entrelaçamento — Segredos Vinculados

Tunelamento — Segredos Efêmeros

Teletransporte — Compartilhamento Criptografado

Importação — Ingestão em Massa de Segredos

Exportação Seletiva

Pesquisa e Filtragem de Segredos

Manifesto de Segredos do Projeto

Sincronização de Arquivo Env

Referências de Segredos e Execução com Menor Privilégio

Configuração do Editor

Envio para Plataformas de Implantação

Validação de Vitalidade de Segredos

Hooks — Callbacks em Mudança de Segredo

Rotação Configurável

Execução Segura e Redação Automática

Scanner de Segredos em Base de Código

Segredos Compostos / Modelados

Aprovações de Usuário (Agente Zero-Confiança)

Canary Honeytokens

Airlock MCP

Provisionamento Just-In-Time (JIT)

Contexto de Projeto para Agentes de IA

Linter Ciente de Segredos

Memória do Agente

Varredura de Segredos Pré-Commit

Análise de Segredos

Assistente de Configuração de Serviço

Política de Governança

Perfis de Execução

Auditoria à Prova de Adulteração

Linha do Tempo de Sessão do Agente

Backend de Arquivo Criptografado (Headless / CI)

Escopos de Equipe e Organização

Rotação Nativa do Emissor

Validação de Segredos em CI

Modo Agente — Monitoramento Autônomo

Painel de Status Quântico — Monitoramento ao Vivo

Servidor MCP

Ferramentas Principais

Ferramentas Quânticas

Ferramentas de Tunelamento

Ferramentas de Teletransporte

Ferramentas de Validação

Ferramentas de Hook

Ferramentas de Execução e Varredura

Ferramentas para Agentes de IA

Ferramentas de Observação e Saúde

Ferramentas de Governança e Política

Configuração Cursor / Kiro

Configuração Claude Code

Configuração VS Code

Plugins de Editor

Plugin Cursor

Plugin Kiro (Power)

Plugin Claude Code

Arquitetura

Configuração do Projeto (.q-ring.json)

📚 Documentação

Contribuindo

🔒 Segurança

📜 Licença

Configuração do Projeto (`.q-ring.json`)