hanzo-vault

Hanzo Vault is a card tokenization service that runs as an isolated cardholder data environment (CDE).

Hanzo Vault - Card Tokenization and Cardholder Data Environment

Category: Hanzo Ecosystem Related Skills: hanzo/hanzo-kms.md, hanzo/hanzo-commerce-api.md

Overview

Hanzo Vault is a card tokenization service that runs as an isolated cardholder data environment (CDE). Securely tokenize, store, and detokenize payment card data without handling raw card numbers in your application. Written in Go with hardware-backed encryption.

Why Hanzo Vault?

PCI DSS controls: Full cardholder data environment isolation
Zero plaintext: Card numbers never exist in plaintext outside Vault
Hardware-backed: Encryption keys in HSM/KMS, never in memory
Go performance: Sub-millisecond tokenization
Format-preserving: Tokens maintain card number format (Luhn-valid)
Audit trail: Every access logged for compliance

Architecture

Vault is an internal service — never exposed publicly. Applications call Vault's internal API to tokenize/detokenize. Only Vault touches raw card data, keeping PCI scope minimal.

When to use

Processing credit/debit card payments
Reducing PCI DSS scope
Tokenizing sensitive payment data
Building e-commerce payment flows
Storing card-on-file for subscriptions

Hard requirements

Internal network only (never expose to public internet)
KMS integration for encryption key management
PostgreSQL for token storage
TLS for all connections (even internal)

Quick reference

| Item | Value | |------|-------| | Language | Go | | API | Internal gRPC + HTTP | | Port | 8080 (HTTP), 8443 (gRPC) | | Tokenize | POST /v1/tokens | | Detokenize | POST /v1/detokenize | | Repo | github.com/hanzoai/vault | | License | Proprietary |

API Reference

Tokenize Card

POST /v1/tokens
Content-Type: application/json
Authorization: Bearer <service-token>

{
 "card": {
 "number": "4111111111111111",
 "exp_month": 12,
 "exp_year": 2027,
 "cvc": "123",
 "name": "Card Holder"
 }
}

Response:

{
 "id": "tok_abc123def456",
 "last4": "1111",
 "brand": "visa",
 "exp_month": 12,
 "exp_year": 2027,
 "fingerprint": "fp_a1b2c3d4e5"
}

Detokenize (Restricted)

POST /v1/detokenize
Content-Type: application/json
Authorization: Bearer <restricted-service-token>

{
 "token_id": "tok_abc123def456",
 "fields": ["number", "cvc"]
}

Response:

{
 "number": "4111111111111111",
 "cvc": "123"
}

List Tokens

GET /v1/tokens?customer_id=cus_123
Authorization: Bearer <service-token>

Delete Token

DELETE /v1/tokens/tok_abc123def456
Authorization: Bearer <service-token>

Go Client SDK

import "github.com/hanzoai/vault/client"

vc := client.New(client.Config{
 Endpoint: "http://vault.hanzo.svc:8080",
 Token: os.Getenv("VAULT_SERVICE_TOKEN"),
})

// Tokenize a card
token, err := vc.Tokenize(ctx, client.Card{
 Number: "4111111111111111",
 ExpMonth: 12,
 ExpYear: 2027,
 CVC: "123",
})
// token.ID = "tok_abc123" (safe to store anywhere)
// token.Last4 = "1111"
// token.Brand = "visa"

// Detokenize (restricted — requires elevated permissions)
card, err := vc.Detokenize(ctx, "tok_abc123", client.DetokenizeOpts{
 Fields: []string{"number", "cvc"},
 Reason: "payment_processing", // Audit trail
})

// List customer's tokens
tokens, err := vc.ListTokens(ctx, client.ListOpts{
 CustomerID: "cus_123",
})

// Delete token
err = vc.DeleteToken(ctx, "tok_abc123")

Token Properties

| Property | Description | |----------|-------------| | id | Unique token ID (tok_*) | | last4 | Last 4 digits of card | | brand | Card brand (visa, mastercard, amex) | | exp_month | Expiration month | | exp_year | Expiration year | | fingerprint | Unique card fingerprint for dedup | | created_at | Token creation timestamp | | customer_id | Associated customer (optional) |

Security

CRITICAL: Never store raw card numbers. Always use Vault tokens.
CRITICAL: Always hash passwords — NEVER store in plaintext.
CVC: Stored temporarily (max 2 hours) then auto-deleted per PCI rules
Encryption: AES-256-GCM with KMS-managed keys
Access control: Service tokens scoped to tokenize-only or detokenize
Audit log: Every tokenize/detokenize call logged with timestamp, caller, reason

Deployment

# K8s deployment (internal only)
apiVersion: apps/v1
kind: Deployment
metadata:
 name: vault
 namespace: hanzo
spec:
 replicas: 2
 template:
 spec:
 containers:
 - name: vault
 image: ghcr.io/hanzoai/vault:latest
 ports:
 - containerPort: 8080
 - containerPort: 8443
 env:
 - name: DATABASE_URL
 valueFrom:
 secretKeyRef:
 name: vault-secrets
 key: database-url
 - name: KMS_ENDPOINT
 value: "http://kms.hanzo.svc:8080"
---
# No Ingress — internal only
apiVersion: v1
kind: Service
metadata:
 name: vault
 namespace: hanzo
spec:
 type: ClusterIP # Internal only
 ports:
 - port: 8080
 name: http
 - port: 8443
 name: grpc

Troubleshooting

| Issue | Cause | Solution | |-------|-------|----------| | Tokenize fails | KMS unreachable | Check KMS connection | | Detokenize denied | Insufficient permissions | Use restricted token | | Token not found | Wrong ID or deleted | Check token ID format | | Slow tokenize | HSM latency | Check KMS health |

Related Skills

hanzo/hanzo-kms.md - Key management (Vault uses KMS for encryption keys)
hanzo/hanzo-commerce-api.md - Payment processing (uses Vault for card tokenization)
hanzo/hanzo-contracts.md - Smart contracts (crypto payments, not card)

Last Updated: 2026-03-13 Category: Hanzo Ecosystem Related: pci, tokenization, payments, security, go Prerequisites: PCI DSS concepts, Go, internal networking