Documentation — VellumGuard

Installation

The VellumGuard SDK is available for TypeScript/Node. Python and Go are on the roadmap. Install from npm:

npm install @vellumguard/sdk

Quickstart

Initialize the client with the hosted API endpoint and your workspace API key, then encrypt and decrypt against your own user identities. Hybrid post-quantum protection is on by default.

import { VellumGuard, HttpKmsClient } from "@vellumguard/sdk";

const kms = new HttpKmsClient({
  baseUrl: "https://api.vellumguard.com",
  apiKey: process.env.VELLUMGUARD_API_KEY!,
});

const vg = new VellumGuard({ kms });

// Encrypt — addressed to one of your user IDs; signed by the same identity
const ciphertext = await vg.encrypt({
  data: "patient note: BP 120/80",
  recipient: "user_abc123",
  signAs: "user_abc123",
});

// Decrypt — on the recipient's side
const { data } = await vg.decrypt(ciphertext, "user_abc123");

console.log(data); // "patient note: BP 120/80"

That is the whole surface for the common case. No key handling, no algorithm selection, no mode flags to forget.

Encrypting a file

Read the file into a Buffer and use the standard encrypt call:

import { readFile } from "node:fs/promises";

const pdf = await readFile("/tmp/labs.pdf");
const ciphertext = await vg.encrypt({
  data: pdf,
  recipient: "patient_001",
  signAs: "service_key",
});

Managing identities

Identities represent participants (users, devices, services). Create them via the REST API:

curl -s -X POST https://api.vellumguard.com/v1/identities \
  -H "Authorization: Bearer $VELLUMGUARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "user_abc123"}'

The SDK resolves identities by their external ID at encrypt and decrypt time. Your API key is supplied during design-partner onboarding. Contact beta@vellumguard.com to request access.

Ciphertext format

The VellumGuard ciphertext format is public and versioned. A published specification with reference test vectors means your data stays decryptable with any conforming implementation — there is no proprietary lock-in.

Every ciphertext carries a version byte, a suite identifier, recipient and sender key IDs, a hybrid KEM payload, the AEAD-encrypted body, and a hybrid signature. Old versions remain decryptable permanently.

v1 cryptographic suite

Key encapsulation — X25519 + ML-KEM-768 (FIPS 203)
Signatures — Ed25519 + ML-DSA-65 (FIPS 204)
Symmetric cipher — AES-256-GCM
Key derivation — HKDF-SHA-256, binding both shared secrets

The classical and post-quantum shared secrets are concatenated before key derivation, so compromising either one alone reveals nothing about the payload.

Transport encoding

Ciphertexts are binary by default. For JSON-friendly transport they are encoded as Base64URL with a v1. prefix for easy identification in logs.

Error handling

Every error carries a stable code, a retryable flag, and a requestId for support. Match on the code — never parse messages.

try {
  await vg.decrypt(ciphertext, "user_abc123");
} catch (err) {
  if (err.code === "recipient_revoked") { /* handle */ }
}

Next steps

Review the security model to understand the trust boundary. To request a design-partner API key, apply here. Extended SDK reference and language-specific guides are available to active partners.

Quickstart & reference.