Files
skills/public/hanzo-vault.html
zeekayandHanzo Dev 9e10c1c10e Each llms index points at the other two
hanzoskills.com/llms.txt now opens with the install line, the API
reference index and the company index, so an agent that lands on any
one of the three can find the rest.

robots.txt claimed 537 documents while llms.txt counts 920. The number
is gone from robots.txt; llms.txt derives it.

public/ is regenerated from scripts/site.py, which it had fallen
behind: the copy-prompt menu and agent bar were in the generator and
not in the committed pages. tests/site.mjs passes against the result.

Co-authored-by: Hanzo Dev <[email protected]>
2026-09-11 00:27:59 -07:00

357 lines
19 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>hanzo-vault</title>
<meta name="color-scheme" content="dark">
<style>
/* Committed to one visual world: a dark instrument panel. No light variant —
the dot field and the hairline rules only read on black, and a naive
inversion would wash both out. Every colour is painted explicitly so the page
never borrows a host background. */
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
:root{
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
--font-zen-pixel-square:'Zen Pixel Square',monospace;
--mono:var(--font-zen-mono);
--sans:var(--font-zen-sans);
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
--r:999px; --r-soft:14px;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
/* The dot field. A halftone made of one repeating radial-gradient, faded out
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
/* No overflow clip here: the dot field is inset to the box already, and a clip
would cut off the copy-prompt menu. */
.hero{position:relative;border-bottom:1px solid var(--line)}
.hero::before{content:"";position:absolute;inset:0;
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
background-size:7px 7px;
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
pointer-events:none}
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
nav{border-bottom:1px solid var(--line)}
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
justify-content:space-between;align-items:center;gap:1rem}
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--ink);text-decoration:none;
display:inline-flex;align-items:center;gap:.6rem}
.brand i{font-style:normal;color:var(--faint)}
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--soft);text-decoration:none}
nav a.up:hover{color:var(--ink)}
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
h1 em{font-style:normal;color:var(--faint)}
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
line-height:1.2;font-weight:400}
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
.btn.solid:hover{background:#d8d8d4}
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
/* Copy-prompt selector. Each row copies the prompt for its own target. */
.copy{position:relative;display:inline-flex}
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
padding:.4rem;display:flex;flex-direction:column;
box-shadow:0 12px 32px rgba(0,0,0,.75)}
.menu[hidden]{display:none}
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
white-space:nowrap}
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
.mi:hover .mark{color:var(--ink)}
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
letter-spacing:.1em;text-transform:uppercase}
/* Works-with bar: one scrolling row, name and mark per agent. */
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
display:flex;align-items:center}
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
-webkit-overflow-scrolling:touch;
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
.bar::-webkit-scrollbar{display:none}
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
text-decoration:none;background:var(--ground)}
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
.agent .mark{width:.95rem;height:.95rem}
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
p{margin:0 0 1rem;max-width:70ch}
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
li{margin:.22rem 0}
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
text-decoration-color:var(--line-hi)}
a:hover{text-decoration-color:var(--ink)}
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
display:block;overflow-x:auto}
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
.curl{display:block;background:var(--panel);border:1px solid var(--line);
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
white-space:pre;line-height:1.9}
.curl b{color:var(--ink);font-weight:400}
.curl i{font-style:normal;color:var(--faint)}
/* index */
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
#q:focus{outline:none;border-color:var(--soft)}
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
text-transform:uppercase;margin:0 0 2rem}
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
padding-bottom:.45rem}
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
border-radius:var(--r-soft);text-decoration:none}
.row:hover{background:#0a0a0a}
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
color:var(--faint);font-size:.85rem}
footer a{color:var(--soft)}
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
margin:0 0 2rem;font-size:.85rem}
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
border-bottom:1px solid var(--line);padding-bottom:.4rem}
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
.fmap a:hover{text-decoration:underline}
.fmap div{color:var(--faint);line-height:1.5}
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
@media (max-width:640px){
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
.btns{gap:.5rem}
.btn{padding:.75rem 1.15rem;font-size:.68rem}
.copy,.copy .btn{width:100%;justify-content:center}
.menu{left:0;right:0;min-width:0}
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
.strip b{border-right:0;padding-right:0}
.bar{width:100%}
}
</style>
<link rel="alternate" type="text/markdown" href="/hanzo-vault.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/hanzo-vault">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/hanzo-vault.md
Index: https://hanzoskills.com/llms.txt
Corpus: https://hanzoskills.com/all.md
Append .md to any path for the markdown twin. -->
<body>
<nav><div class="in">
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
<a class="up" href="/">All skills</a>
</div></nav>
<div class="wrap">
<h1>hanzo-vault</h1><p class="lede">Hanzo Vault is a card tokenization service that runs as an isolated cardholder data environment (CDE).</p><h1>Hanzo Vault - Card Tokenization and Cardholder Data Environment</h1>
<p><strong>Category</strong>: Hanzo Ecosystem <strong>Related Skills</strong>: <code>hanzo/hanzo-kms.md</code>, <code>hanzo/hanzo-commerce-api.md</code></p>
<h2>Overview</h2>
<p>Hanzo Vault is a <strong>card tokenization service</strong> 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.</p>
<h3>Why Hanzo Vault?</h3>
<ul><li><strong>PCI DSS controls</strong>: Full cardholder data environment isolation</li><li><strong>Zero plaintext</strong>: Card numbers never exist in plaintext outside Vault</li><li><strong>Hardware-backed</strong>: Encryption keys in HSM/KMS, never in memory</li><li><strong>Go performance</strong>: Sub-millisecond tokenization</li><li><strong>Format-preserving</strong>: Tokens maintain card number format (Luhn-valid)</li><li><strong>Audit trail</strong>: Every access logged for compliance</li></ul>
<h3>Architecture</h3>
<p>Vault is an <strong>internal service</strong> — never exposed publicly. Applications call Vault&#x27;s internal API to tokenize/detokenize. Only Vault touches raw card data, keeping PCI scope minimal.</p>
<h2>When to use</h2>
<ul><li>Processing credit/debit card payments</li><li>Reducing PCI DSS scope</li><li>Tokenizing sensitive payment data</li><li>Building e-commerce payment flows</li><li>Storing card-on-file for subscriptions</li></ul>
<h2>Hard requirements</h2>
<ol><li><strong>Internal network only</strong> (never expose to public internet)</li><li><strong>KMS integration</strong> for encryption key management</li><li><strong>PostgreSQL</strong> for token storage</li><li><strong>TLS</strong> for all connections (even internal)</li></ol>
<h2>Quick reference</h2>
<p>| Item | Value | |------|-------| | Language | Go | | API | Internal gRPC + HTTP | | Port | 8080 (HTTP), 8443 (gRPC) | | Tokenize | <code>POST /v1/tokens</code> | | Detokenize | <code>POST /v1/detokenize</code> | | Repo | <code>github.com/hanzoai/vault</code> | | License | Proprietary |</p>
<h2>API Reference</h2>
<h3>Tokenize Card</h3>
<pre><code class="lang-http">POST /v1/tokens
Content-Type: application/json
Authorization: Bearer &lt;service-token&gt;
{
&quot;card&quot;: {
&quot;number&quot;: &quot;4111111111111111&quot;,
&quot;exp_month&quot;: 12,
&quot;exp_year&quot;: 2027,
&quot;cvc&quot;: &quot;123&quot;,
&quot;name&quot;: &quot;Card Holder&quot;
}
}</code></pre>
<p>Response:</p>
<pre><code class="lang-json">{
&quot;id&quot;: &quot;tok_abc123def456&quot;,
&quot;last4&quot;: &quot;1111&quot;,
&quot;brand&quot;: &quot;visa&quot;,
&quot;exp_month&quot;: 12,
&quot;exp_year&quot;: 2027,
&quot;fingerprint&quot;: &quot;fp_a1b2c3d4e5&quot;
}</code></pre>
<h3>Detokenize (Restricted)</h3>
<pre><code class="lang-http">POST /v1/detokenize
Content-Type: application/json
Authorization: Bearer &lt;restricted-service-token&gt;
{
&quot;token_id&quot;: &quot;tok_abc123def456&quot;,
&quot;fields&quot;: [&quot;number&quot;, &quot;cvc&quot;]
}</code></pre>
<p>Response:</p>
<pre><code class="lang-json">{
&quot;number&quot;: &quot;4111111111111111&quot;,
&quot;cvc&quot;: &quot;123&quot;
}</code></pre>
<h3>List Tokens</h3>
<pre><code class="lang-http">GET /v1/tokens?customer_id=cus_123
Authorization: Bearer &lt;service-token&gt;</code></pre>
<h3>Delete Token</h3>
<pre><code class="lang-http">DELETE /v1/tokens/tok_abc123def456
Authorization: Bearer &lt;service-token&gt;</code></pre>
<h2>Go Client SDK</h2>
<pre><code class="lang-go">import &quot;github.com/hanzoai/vault/client&quot;
vc := client.New(client.Config{
Endpoint: &quot;http://vault.hanzo.svc:8080&quot;,
Token: os.Getenv(&quot;VAULT_SERVICE_TOKEN&quot;),
})
// Tokenize a card
token, err := vc.Tokenize(ctx, client.Card{
Number: &quot;4111111111111111&quot;,
ExpMonth: 12,
ExpYear: 2027,
CVC: &quot;123&quot;,
})
// token.ID = &quot;tok_abc123&quot; (safe to store anywhere)
// token.Last4 = &quot;1111&quot;
// token.Brand = &quot;visa&quot;
// Detokenize (restricted — requires elevated permissions)
card, err := vc.Detokenize(ctx, &quot;tok_abc123&quot;, client.DetokenizeOpts{
Fields: []string{&quot;number&quot;, &quot;cvc&quot;},
Reason: &quot;payment_processing&quot;, // Audit trail
})
// List customer&#x27;s tokens
tokens, err := vc.ListTokens(ctx, client.ListOpts{
CustomerID: &quot;cus_123&quot;,
})
// Delete token
err = vc.DeleteToken(ctx, &quot;tok_abc123&quot;)</code></pre>
<h2>Token Properties</h2>
<p>| Property | Description | |----------|-------------| | <code>id</code> | Unique token ID (<code>tok_*</code>) | | <code>last4</code> | Last 4 digits of card | | <code>brand</code> | Card brand (visa, mastercard, amex) | | <code>exp_month</code> | Expiration month | | <code>exp_year</code> | Expiration year | | <code>fingerprint</code> | Unique card fingerprint for dedup | | <code>created_at</code> | Token creation timestamp | | <code>customer_id</code> | Associated customer (optional) |</p>
<h2>Security</h2>
<ul><li><strong>CRITICAL</strong>: Never store raw card numbers. Always use Vault tokens.</li><li><strong>CRITICAL</strong>: Always hash passwords — NEVER store in plaintext.</li><li><strong>CVC</strong>: Stored temporarily (max 2 hours) then auto-deleted per PCI rules</li><li><strong>Encryption</strong>: AES-256-GCM with KMS-managed keys</li><li><strong>Access control</strong>: Service tokens scoped to tokenize-only or detokenize</li><li><strong>Audit log</strong>: Every tokenize/detokenize call logged with timestamp, caller, reason</li></ul>
<h2>Deployment</h2>
<pre><code class="lang-yaml"># 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: &quot;http://kms.hanzo.svc:8080&quot;
---
# 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</code></pre>
<h2>Troubleshooting</h2>
<p>| 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 |</p>
<h2>Related Skills</h2>
<ul><li><code>hanzo/hanzo-kms.md</code> - Key management (Vault uses KMS for encryption keys)</li><li><code>hanzo/hanzo-commerce-api.md</code> - Payment processing (uses Vault for card tokenization)</li><li><code>hanzo/hanzo-contracts.md</code> - Smart contracts (crypto payments, not card)</li></ul>
<hr>
<p><strong>Last Updated</strong>: 2026-03-13 <strong>Category</strong>: Hanzo Ecosystem <strong>Related</strong>: pci, tokenization, payments, security, go <strong>Prerequisites</strong>: PCI DSS concepts, Go, internal networking</p>
<footer>
<div class="fmap">
<div><b>Build</b>
<a href="https://hanzo.app">hanzo.app</a> app builder
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
<div><b>Run</b>
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
<div><b>Account</b>
<a href="https://hanzo.id">hanzo.id</a> sign in
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
<div><b>Company</b>
<a href="https://hanzo.ai">hanzo.ai</a> canonical
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
</div>
<div class="fend"><a href="/hanzo-vault.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>