Files
skills/public/hanzo-vault.md

5.6 KiB

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

  1. Internal network only (never expose to public internet)
  2. KMS integration for encryption key management
  3. PostgreSQL for token storage
  4. 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
  • 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