SDKs oficiais

A partir da v2.0 cada SDK do CipherVault expõe dois clients distintos:

• Consumer (mTLS + DPoP RFC 9449) — para aplicações puxando secrets em produção.
• AdminClient (JWT bearer) — para automação, scripts ops e Infrastructure-as-Code.

Os dois convivem lado a lado dentro do mesmo pacote.

Suporte

Linguagem	Pacote	Consumer	AdminClient	Min runtime
Python	ciphervault	CipherVault	AdminClient	Python 3.9+
Node.js / TypeScript	@ciphervault/sdk	CipherVault	AdminClient	Node 18+
Java	io.ciphervault:sdk	CipherVaultClient	AdminClient (inner classes, java.net.http)	Java 11+
Go	github.com/Martinez1991/ciphervault/sdks/go	Client	NewAdmin(url, token)	Go 1.21+
C# / .NET	CipherVault.Sdk	CipherVaultClient	AdminClient (records C# 9 + System.Text.Json)	.NET 6.0+

AdminClient cobre 7 sub-resources: Dynamic Secrets, EaaS, SSH CA, PKI, Approvals, Workload Identity, Tokenization.

Python

pip install ciphervault

Consumer (mTLS + DPoP)

from ciphervault import CipherVault

# Configura mTLS via cert/key
client = CipherVault(
    base_url="https://cv.acme.com.br",
    client_id="cv_app_...",
    cert_path="./client.crt",
    key_path="./client.key",
    sig_key_path="./sig.key",   # para DPoP
)

# Fetch por path /clientId/vaultName/secretName
secret = client.fetch_by_path(vault="producao", secret="api/stripe/secret_key")
print(secret["value"])

AdminClient (JWT)

from ciphervault.admin import AdminClient

cv = AdminClient(url="https://cv.acme.com.br", token="<JWT_BEARER>")

# Dynamic Secrets — solicitar lease JIT
lease = cv.dynamic.request_lease(role_id=42, ttl_seconds=600, reason="ETL daily")
print(lease["username"], lease["password"])

# Encryption-as-a-Service
envelope = cv.eaas.encrypt(key_name="pii", plaintext=b"Rafael Martinez")
plain = cv.eaas.decrypt(envelope=envelope)

# SSH CA — assinar chave pública
cert = cv.ssh.sign(role_id=1, public_key_pem=open("id_ed25519.pub").read(), reason="deploy host bastion")

# Approvals
pendentes = cv.approvals.list(status="pending")
cv.approvals.approve(pendentes[0]["id"], reason="Validado em call SRE")

Node.js / TypeScript

npm install @ciphervault/sdk

Consumer

import { CipherVault } from '@ciphervault/sdk';

const cv = new CipherVault({
  baseUrl: 'https://cv.acme.com.br',
  clientId: 'cv_app_...',
  cert: fs.readFileSync('./client.crt'),
  key: fs.readFileSync('./client.key'),
  sigKey: fs.readFileSync('./sig.key'),
});

const secret = await cv.fetchByPath({ vault: 'producao', secret: 'api/stripe/secret_key' });

AdminClient

import { AdminClient } from '@ciphervault/sdk';

const cv = new AdminClient({ url: 'https://cv.acme.com.br', token: process.env.CV_TOKEN });

const lease = await cv.dynamic.requestLease({ roleId: 42, ttlSeconds: 600 });
const envelope = await cv.eaas.encrypt({ keyName: 'pii', plaintext: 'dados' });

Go

go get github.com/Martinez1991/ciphervault/sdks/go

Consumer

import "github.com/Martinez1991/ciphervault/sdks/go"

client, _ := ciphervault.New(ciphervault.Config{
    BaseURL:  "https://cv.acme.com.br",
    ClientID: "cv_app_...",
    CertPath: "./client.crt",
    KeyPath:  "./client.key",
    SigKey:   "./sig.key",
})

secret, _ := client.FetchByPath(ctx, "producao", "api/stripe/secret_key")

AdminClient

import "github.com/Martinez1991/ciphervault/sdks/go/admin"

adm := admin.NewAdmin("https://cv.acme.com.br", os.Getenv("CV_TOKEN"))

lease, _ := adm.Dynamic.RequestLease(ctx, admin.LeaseRequest{
    RoleID: 42,
    TTL:    600,
})

cert, _ := adm.SSH.Sign(ctx, admin.SSHSignRequest{
    RoleID:    1,
    PublicKey: pub,
    Reason:    "deploy bastion",
})

Tipos exportados: Lease, EaasEnvelope, SshCert, PkiCert, ApprovalRequest, etc.

Java

<dependency>
  <groupId>io.ciphervault</groupId>
  <artifactId>sdk</artifactId>
  <version>2.0.0</version>
</dependency>

Consumer

import io.ciphervault.CipherVaultClient;

var cv = CipherVaultClient.builder()
    .baseUrl("https://cv.acme.com.br")
    .clientId("cv_app_...")
    .cert(Path.of("./client.crt"))
    .key(Path.of("./client.key"))
    .sigKey(Path.of("./sig.key"))
    .build();

var secret = cv.fetchByPath("producao", "api/stripe/secret_key");

AdminClient

import io.ciphervault.AdminClient;

var cv = new AdminClient("https://cv.acme.com.br", System.getenv("CV_TOKEN"));

var lease = cv.dynamic().requestLease(42, 600, "ETL diário");
var envelope = cv.eaas().encrypt("pii", "dados".getBytes());

Implementação usa java.net.http (zero deps externas, Java 11+).

C# / .NET

dotnet add package CipherVault.Sdk

Consumer

using CipherVault;

var cv = new CipherVaultClient(new CipherVaultOptions
{
    BaseUrl = new Uri("https://cv.acme.com.br"),
    ClientId = "cv_app_...",
    CertPath = "./client.crt",
    KeyPath = "./client.key",
    SigKeyPath = "./sig.key",
});

var secret = await cv.FetchByPathAsync("producao", "api/stripe/secret_key");

AdminClient

using CipherVault.Admin;

var cv = new AdminClient("https://cv.acme.com.br", Environment.GetEnvironmentVariable("CV_TOKEN"));

var lease = await cv.Dynamic.RequestLeaseAsync(new LeaseRequest { RoleId = 42, TtlSeconds = 600 });
var envelope = await cv.Eaas.EncryptAsync("pii", "dados"u8.ToArray());

Records C# 9 + System.Text.Json (sem Newtonsoft).

Helper from_federated_token (OIDC CI/CD)

Disponível em todos os SDKs. Detecta automaticamente o provedor OIDC (GitHub Actions, GitLab CI, CircleCI, Jenkins, Bamboo) lendo as variáveis padrão do runner, troca o JWT por um bundle de certs efêmero do CipherVault e configura o Consumer client.

# Python
from ciphervault import from_federated_token
client = from_federated_token(client_id="cv_app_...", base_url="https://cv.acme.com.br")

// Node/TS
import { fromFederatedToken } from '@ciphervault/sdk';
const cv = await fromFederatedToken({ clientId: 'cv_app_...', baseUrl: '...' });

// Go
client, _ := ciphervault.FromFederatedToken("cv_app_...", "https://cv.acme.com.br")

Cache local e retries

Por padrão, secrets lidos são cacheados em memória por 60s (configurável). Cache respeita rotações via ETag.

Backoff exponencial com jitter em todos os SDKs:

• Tentativas: 3
• Timeout: 10s por tentativa
• Backoff inicial: 200ms
• Multiplicador: 2x
• Jitter: ±20%

Apenas erros 5xx, 429 e timeouts são retentados.