Everything you need to ship post-quantum encryption — from your first encrypted string to the wire format underneath it.
The VellumGuard SDK is available for TypeScript/Node. Python and Go are on the roadmap. Install from npm:
npm install @vellumguard/sdkInitialize 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.
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",
});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.
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.
The classical and post-quantum shared secrets are concatenated before key derivation, so compromising either one alone reveals nothing about the payload.
Ciphertexts are binary by default. For JSON-friendly transport they are encoded as
Base64URL with a v1. prefix for easy identification in logs.
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 */ }
}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.
Learn how VellumGuard integrates with applications, existing secure transport, legacy systems, and customer-controlled infrastructure. A secure transport layer protects the route. VellumGuard helps protect and verify the participants and the payload.
No. Payload encryption and decryption occur inside the application process. Customer plaintext does not need to be sent to a VellumGuard-hosted server.
The current beta does use the VellumGuard service for two private-key
operations. During encryption, the SDK makes a hosted signing request.
During decryption, the SDK makes a hosted key-decapsulation request. These
calls are made on every encrypt() and
decrypt().
Public identity keys are cached in memory for up to one hour per SDK instance, which can avoid repeated public-key lookups. The cache does not remove the live-service requirement for signing or decapsulation.
VellumGuard is therefore not the routine processing location for customer plaintext, but the current hosted service is still part of the cryptographic execution path.
For the strongest application-level protection, the SDK can be embedded in each service. This allows each participant to establish its own cryptographic identity, encrypt and decrypt payloads locally, make hosted signing calls, verify signatures, and decrypt at the approved endpoint.
Legacy systems that cannot be directly modified do not necessarily require the SDK. VellumGuard can instead be integrated through a local gateway, adapter, sidecar, proxy, or integration service placed at the system boundary.
Direct SDK integration provides the greatest application-level visibility. Boundary integration protects communication at the gateway but cannot provide complete visibility into activity occurring inside an unmodified legacy application.
No. TLS and secure tunnels protect the transport connection between systems. VellumGuard adds protection and verification at the application and data level.
VellumGuard can help an application:
The technologies are complementary. A secure transport layer protects the route. VellumGuard helps protect and verify the participants and the payload.
An encrypted tunnel protects information while it travels across that specific connection. A digital signature remains useful before, during, and after transport.
A signature can help the recipient verify:
The tunnel proves that a protected connection existed. The signature provides evidence tied to the specific data, even after it leaves that connection.
Public identity keys may be cached in memory inside the SDK for up to one hour per identity. This cache is scoped to an individual SDK instance and is not persisted to disk.
The current beta does not perform private signing or decapsulation using keys stored inside the application. Those operations are requested from the VellumGuard service on every call. Private-key blobs are currently held by the VellumGuard service and protected using GCP KMS data-encryption keys.
Planned enterprise architecture — not currently available in beta: Customer-managed keys (BYOK), hardware security module (HSM) integration, TPM or secure element storage, and alternative key-management backends. Contact beta@vellumguard.com to discuss requirements before sending regulated data.
In the current beta, every new encryption and decryption operation depends on the availability of the VellumGuard service.
Encryption requires a live signing request. Decryption requires a live key-decapsulation request. Cached public keys can reduce public-key lookup traffic, but they do not allow those private-key operations to continue when the service is unavailable.
Audit events are submitted asynchronously and do not block the operation if audit delivery fails.
Applications should currently treat VellumGuard service availability as a runtime dependency. Because the public-key cache is in memory and scoped to a single SDK instance, serverless and short-lived workloads may also experience more cold-cache public-key lookups.
Customer-hosted, customer-controlled, and offline key-operation models are planned enterprise architecture. They are not part of the current beta.
VellumGuard adds local cryptographic processing plus network latency for required service operations.
With a warm public-key cache:
encrypt() requires one synchronous hosted signing requestdecrypt() requires one synchronous hosted decapsulation requestWith a cold cache:
encrypt() may also require up to two public-key lookup requestsdecrypt() may also require one public-key lookup requestAudit events are submitted asynchronously and are not part of the blocking request path.
Actual latency depends on network distance, service response time, payload size, algorithm choice, hardware, concurrency, and whether the SDK instance has a warm public-key cache. VellumGuard does not claim zero overhead. Benchmark results should only be published with a documented environment and test methodology.
No. VellumGuard provides application-level data protection — cryptographic identity, local payload encryption and decryption, hosted signing and decapsulation, and signature verification. It is not a replacement for transport-layer security.
Applications should continue to use TLS, private networking, secure tunnels, or other appropriate transport protections alongside VellumGuard. A secure transport layer protects the connection. VellumGuard adds identity, data protection, and verification that remain meaningful beyond a single network session.
Yes. Where an existing system cannot directly embed the SDK, VellumGuard can be integrated through a gateway, sidecar, adapter, proxy, or adjacent service placed at the system boundary.
This approach can protect data entering or leaving the legacy system and establish a verifiable boundary identity. It cannot, however, provide complete evidence of internal actions performed by software that has not been instrumented.
Both endpoints must participate in the trust relationship, but that does not always mean the SDK must be embedded in both.
Supported deployment approaches include:
Direct SDK integration on both sides provides the greatest visibility into each application's activity. Gateway integration protects data at the boundary but cannot provide complete insight into actions performed inside an unmodified legacy application. See also "Does every application need the VellumGuard SDK?" and "Can VellumGuard be used with legacy systems?"
Yes. Private connectivity and VellumGuard address different layers of the stack and can be used together.
A private connectivity layer — such as a VPN, private network, or dedicated link — protects the network path. It controls which systems can communicate and restricts unauthorized routing.
VellumGuard operates at the application and data level. It provides cryptographic identity, local payload encryption and decryption, hosted signing and decapsulation, and signature verification for the applications exchanging data and the data moving across that path.
A secure transport layer protects the route. VellumGuard helps protect and verify the participants and the payload. Private connectivity controls who can reach a service; VellumGuard adds identity verification and data protection within that network.
A capable engineering team can implement encryption, signatures, identity, and auditing within a single application. That approach works well for a contained system with a stable team and a well-defined scope.
VellumGuard is designed to provide these capabilities as a reusable layer that can be applied consistently across independently built applications, services, devices, and systems — without requiring each team to design, maintain, and audit its own implementation.
Benefits include consistent cryptographic APIs, reusable identity patterns, simplified integration across system boundaries, algorithm agility as standards evolve, and a shared developer experience across teams.
VellumGuard does not make cryptography possible. It makes trust capabilities reusable and consistent across independently built systems.
Individual technologies solve parts of the problem. TLS protects network connections. A KMS manages cryptographic keys. Hashing detects changes. Identity providers authenticate users or workloads. Policy engines evaluate authorization. Logging platforms record events.
VellumGuard is designed to provide a unified developer interface for identity, local payload encryption and decryption, hosted signing and decapsulation, signature verification, and audit — while integrating with existing infrastructure rather than replacing it.
The current TypeScript SDK composes these capabilities in a single API: create and resolve identities, encrypt and decrypt payloads locally, make hosted signing and decapsulation calls, verify signatures locally, and record audit events — all with one consistent interface and a post-quantum cryptographic suite.
Broader integrations with external policy systems, IdPs, and enterprise audit platforms are on the roadmap but are not part of the current beta SDK.
Currently available — TypeScript SDK, controlled beta:
Roadmap — not currently available in beta:
Any security component becomes part of the trusted computing base. VellumGuard is no exception.
The architecture is designed to reduce attack surface:
Currently, private key blobs reside in the VellumGuard service encrypted under DEKs wrapped by Google Cloud KMS. Both VellumGuard and GCP KMS are in the trust chain. Customer-managed keys (BYOK) — which would allow customers to hold the root key — are planned but not yet available.
VellumGuard does not claim to be immune to compromise. The intent is to minimize risk, minimize centralized plaintext handling, and keep the trusted core as small as possible. Production deployments should evaluate the trust model carefully.
VellumGuard does not receive customer plaintext during normal SDK encryption or decryption. Payload cryptography occurs in the application process.
However, the current beta relies on the VellumGuard service for key decapsulation during decryption, and the service stores protected private-key blobs. Customers therefore place trust in the hosted VellumGuard key service and its access controls.
The current architecture limits scope through per-identity key pairs, workspace-scoped API keys, and identity-scoped authorization. Private key blobs are encrypted under DEKs wrapped by Google Cloud KMS — neither VellumGuard nor GCP stores an unencrypted DEK on disk or in logs.
Planned enterprise architecture — not currently available in beta: Customer-controlled KMS or HSM, tenant-isolated key authority, non-exportable key operations, BYOK, and offline or air-gapped modes. Contact beta@vellumguard.com to discuss trust model requirements before sending regulated data.
No. Container isolation, operating-system protections, virtualization, network controls, and hardware security mechanisms are responsible for preventing an AI system from escaping its execution environment. VellumGuard does not provide or replace those controls.
VellumGuard complements sandbox controls by providing identity, authentication, authorization, and cryptographic verification for external resources. If an AI system attempts to reach a protected resource outside its environment, that resource can independently verify the identity and authorization of the request before accepting it.
VellumGuard helps control what external systems are willing to trust. It is not a replacement for operating-system or container isolation.
The SDK is endpoint-configurable. The baseUrl parameter in
HttpKmsClient defaults to the hosted service at
https://api.vellumguard.com but can be overridden:
const kms = new HttpKmsClient({
baseUrl: "https://trust.company.gov",
apiKey: process.env.VELLUMGUARD_API_KEY!,
});The target endpoint must implement the VellumGuard API — including identity management, signing, key decapsulation, authentication, and audit services. An existing customer KMS (AWS KMS, Azure Key Vault, GCP KMS, HashiCorp Vault, HSM) does not expose these APIs by itself. It would require a VellumGuard-compatible service deployed in front of it.
Current beta: The hosted service at
api.vellumguard.com and local development
(http://localhost) are the supported deployment targets.
The baseUrl option is available and validated at SDK
construction time.
Planned enterprise architecture — not currently available in beta: A fully packaged customer-hosted VellumGuard service for production deployment, customer-controlled KMS, HSM-backed deployments, BYOK, and air-gapped operation. Contact beta@vellumguard.com to discuss deployment requirements.
The SDK is designed to be endpoint-configurable rather than permanently coupled to a single hosted service.
Request a design-partner API key and put these examples into production.