Framework integration guides

A partir da v4.5, o repo do produto inclui 8 guides específicos por framework para integrar CipherVault em apps reais. Esta página é um índice rápido; os guides completos estão no monorepo do produto em docs/integrations/.

Frameworks cobertos

Framework	Stack	Padrão recomendado
Vite	Frontend JS/TS, SPA	Build-time injection via env vars
Next.js	React + SSR/SSG	OIDC pull no getServerSideProps ou app/router
Laravel	PHP	SDK PHP (community) + .env populated via SDK boot
Django	Python	ciphervault-sdk em settings.py, lazy load
FastAPI	Python async	Dependency injection + SDK async
Rails	Ruby	ciphervault-sdk (community) + Rails.application.credentials shim
Spring Boot	Java	ciphervault-spring-boot-starter (auto-config)
Express	Node.js	Middleware + SDK Node Consumer

Padrões transversais

1. Build-time vs runtime

• Build-time: secrets resolvidos durante build (Vite, Next.js SSG). Resultado fica empacotado — NUNCA use isso para secrets sensíveis (vão para o bundle do client).
• Runtime: secrets buscados no boot do server ou na primeira request. Apropriado para back-end.

2. OIDC sempre que possível

Em CI/CD que faz build/deploy, use OIDC Federation para autenticar o pipeline no CV. Sem secret estático.

Em runtime no servidor, prefira Workload Identity (K8s SA, AWS IAM, GCP IAM, Azure MSI, SPIFFE) quando disponível.

3. AppConnection com escopo mínimo

Cada app/microsserviço tem AppConnection própria, com vault_ids escopados e allowed_paths específicos. Não compartilhe credentials entre apps.

4. Cache local + refresh

SDKs cacheiam secrets em memória (default 60s). Configure cache_ttl_seconds conforme criticidade — rotação refresh dentro do TTL.

5. Health probes incluem CipherVault

Health endpoint do app valida que SDK consegue ler secret de teste:

@app.get("/health/deep")
def health_deep():
    try:
        cv.secrets.get(vault=os.environ["VAULT"], path="health/probe")
        return {"ciphervault": "ok"}
    except Exception as e:
        return JSONResponse(status_code=503, content={"ciphervault": str(e)})

Exemplos rápidos

Spring Boot

<dependency>
  <groupId>io.ciphervault</groupId>
  <artifactId>ciphervault-spring-boot-starter</artifactId>
  <version>4.5.0</version>
</dependency>

# application.yml
ciphervault:
  base-url: https://cv.acme.com.br
  client-id: ${CV_CLIENT_ID}
  cert-path: /run/cv/client.crt
  key-path: /run/cv/client.key
  vault: producao

@Service
public class StripeService {
    @CVSecret("api/stripe/secret_key")
    private String stripeKey;
    // ...
}

Next.js (App Router)

// app/billing/page.tsx
import { CipherVault } from '@ciphervault/sdk';

const cv = new CipherVault({ /* ... */ });

export default async function BillingPage() {
  const apiKey = await cv.fetchByPath({
    vault: 'producao',
    secret: 'api/stripe/secret_key',
  });
  // apiKey nunca chega ao client component
  return <BillingDashboard apiKeyMasked={apiKey.slice(-4)} />;
}

FastAPI

from fastapi import FastAPI, Depends
from ciphervault import Client

app = FastAPI()

async def get_cv():
    # Singleton via lifespan
    return app.state.cv

@app.get("/process")
async def process(cv: Client = Depends(get_cv)):
    secret = await cv.secrets.get(vault="producao", path="api/openai/key")
    return {"masked": secret.value[-4:]}

Express

const { CipherVault } = require('@ciphervault/sdk');
const app = express();

const cv = new CipherVault({ /* config */ });

app.use(async (req, res, next) => {
  req.cv = cv;
  next();
});

app.get('/api/data', async (req, res) => {
  const secret = await req.cv.secrets.get({ vault: 'producao', path: 'api/foo' });
  // ...
});

Onde encontrar os guides completos

Guides com exemplos completos, error handling, testes e best practices específicas vivem no repo do produto:

📁 docs/integrations/ no monorepo do CipherVault

Arquivos disponíveis:

• vite.md
• nextjs.md
• laravel.md
• django.md
• fastapi.md
• rails.md
• spring-boot.md
• express.md

Não vê seu framework?

• Use SDK direto — Python, Node, Java, Go, C# cobrem 95% dos cenários
• CLI Go cv — pipe-friendly, funciona em qualquer linguagem
• Secretless Proxy — Postgres/MySQL/Redis/MongoDB sem mudar app
• REST API — última opção (cuidado com mTLS handshake manual)