AppConnections (Zero-Trust)

AppConnections são identidades não humanas no CipherVault — uma por serviço, microsserviço, batch job ou tenant interno. Cada AppConnection combina:

• client_id + client_secret (com rotação automática)
• Certificado mTLS X.509 assinado pela CA do CipherVault
• IP allowlist (CIDR)
• Policies anexadas com escopo de paths
• Path aggregators pré-configurados

A combinação implementa Zero-Trust no plano de aplicação: toda chamada ao cofre tem identidade forte, transporte criptografado mutualmente autenticado e perímetro de rede explícito.

Quando usar AppConnection vs. PAT vs. OIDC

Cenário	Recomendação
Pipeline CI/CD	OIDC Federation
Microsserviço em produção (long-running)	AppConnection
Job batch agendado	AppConnection
Script humano pontual	PAT
CLI de desenvolvedor	PAT com TTL curto
Operator Kubernetes	AppConnection

Criação

curl -X POST https://api.ciphervault.com.br/v1/app-connections \
  -H "Authorization: Bearer $CIPHERVAULT_TOKEN" \
  -d '{
    "name": "billing-api",
    "vault": "producao",
    "allowed_paths": [
      "api/stripe/*",
      "db/postgres/billing-master"
    ],
    "aggregators": [
      { "name": "billing-init", "prefix": "api/stripe/" }
    ],
    "ip_allowlist": ["10.42.0.0/16"],
    "mtls_required": true,
    "rotation": {
      "client_secret_days": 60,
      "certificate_days": 90
    }
  }'

Resposta (única exibição do secret):

{
  "id": "app_01HXYZ...",
  "client_id": "cv_app_01HXYZ...",
  "client_secret": "cs_live_...",
  "csr_signing_url": "https://api.ciphervault.com.br/v1/app-connections/app_01HXYZ.../sign-csr",
  "ca_bundle_url": "https://api.ciphervault.com.br/.well-known/ca-bundle.pem"
}

Geração e assinatura do certificado mTLS

# 1. Gerar chave privada e CSR no servidor da aplicação
openssl req -new -newkey rsa:4096 -nodes \
  -keyout app.key \
  -out app.csr \
  -subj "/CN=billing-api/O=Acme/C=BR"

# 2. Submeter CSR ao CipherVault (autenticado com client_id/secret)
curl -X POST https://api.ciphervault.com.br/v1/app-connections/app_01HXYZ.../sign-csr \
  -H "X-Client-Id: cv_app_01HXYZ..." \
  -H "X-Client-Secret: cs_live_..." \
  --data-binary @app.csr \
  -o app.crt

# 3. Baixar CA bundle
curl https://api.ciphervault.com.br/.well-known/ca-bundle.pem -o ca.pem

A chave privada nunca sai do servidor. O CipherVault só vê o CSR.

Uso no SDK

Python

from ciphervault import Client
from ciphervault.auth import AppConnectionAuth

auth = AppConnectionAuth(
    client_id="cv_app_01HXYZ...",
    client_secret_env="CV_CLIENT_SECRET",
    cert_path="/etc/cv/app.crt",
    key_path="/etc/cv/app.key",
    ca_bundle_path="/etc/cv/ca.pem",
)

client = Client(
    endpoint="https://api.ciphervault.com.br",
    auth=auth,
)

O SDK detecta proximidade da expiração do certificado e dispara renovação automática (re-CSR + sign) sem interrupção.

Path aggregators na AppConnection

AppConnections podem definir aggregators nomeados, otimizando o startup da aplicação:

secrets = client.aggregate("billing-init")
# {"api/stripe/secret_key": "...", "api/stripe/webhook_secret": "..."}

A response é um único round-trip e o resultado é cacheado de acordo com TTL configurado (default 5min).

Rotação automática

Tanto client_secret quanto o certificado mTLS rotacionam automaticamente de acordo com a política da AppConnection. O SDK obtém a nova credencial sem downtime via endpoint /v1/app-connections/{id}/rotate:

• client_secret: dois secrets ativos durante grace window de 10min.
• certificado: novo cert é instalado antes do antigo expirar; aplicação reload soft (HUP/socket reload).

Boas práticas

• Uma AppConnection por serviço. Não compartilhe entre aplicações distintas.
• Policies estritas. Apenas os paths exatos que o serviço lê. api/stripe/* em vez de *.
• IP allowlist sempre que possível. Mesmo em zero-trust, defesa em camadas.
• mTLS obrigatório em produção. mtls_required: true.
• Monitore o jti. Cada uso da AppConnection gera evento auditado com jti único.
• Revogação em incidente. O endpoint POST /app-connections/{id}/revoke inutiliza imediatamente o client_secret e o certificado, sem janela de graça.