mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
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]>
591 lines
46 KiB
HTML
591 lines
46 KiB
HTML
<!doctype html>
|
|
<html lang="en"><head>
|
|
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
|
|
<title>hip-0027</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="/hip-0027.md">
|
|
|
|
<link rel="icon" href="/favicon.svg">
|
|
<link rel="canonical" href="https://hanzoskills.com/hip-0027">
|
|
</head>
|
|
<!-- Reading this with a machine? Every page here is also plain markdown.
|
|
This one: https://hanzoskills.com/hip-0027.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>hip-0027</h1><p class="lede">HIP-27: Secrets Management Standard. Status Draft. Hanzo architectural specification.</p><h1>HIP-0027: Secrets Management Standard</h1>
|
|
<h2>Abstract</h2>
|
|
<p>There is <strong>one</strong> KMS surface: <code>api.hanzo.ai/v1/kms</code>. It answers <code>path</code> / <code>env</code> / <code>name</code>, resolving to <code>/orgs/<org>/<path>/<NAME></code>, and it is the only store any service reads. The <code>/api/v1/</code> and <code>/api/v3/</code> surface earlier revisions of this HIP documented is gone; it carried the <code>/api/</code> prefix the estate does not use (HIP-0119) and it returns <code>404</code>.</p>
|
|
<p><strong>Where a secret sits is HIP-0136's question, not this one's.</strong> That HIP is normative for the path, and it supersedes the project-per-service layout §Secret Organization Model used to specify. This HIP covers what KMS is, how a service authenticates to it, and how the <code>KMSSecret</code> CRD gets a value into a pod.</p>
|
|
<p>This proposal defines the secrets management standard for the Hanzo ecosystem. Hanzo KMS is the centralized, auditable, Kubernetes-native secret store for all Hanzo services, built on the canonical <code>luxfi/kms</code> primitives. It replaces scattered environment variables, CI/CD secrets, and manual <code>kubectl create secret</code> operations with a single source of truth.</p>
|
|
<p>Every secret in the Hanzo ecosystem --- API keys, database credentials, OAuth client secrets, encryption keys --- flows through KMS. Services authenticate via Universal Auth (machine identity with client ID/secret), receive a short-lived bearer token, and fetch secrets at runtime. In Kubernetes, the <code>KMSSecret</code> custom resource automates syncing secrets from KMS into native <code>Secret</code> objects, eliminating human involvement in the secret lifecycle.</p>
|
|
<p><strong>Repository</strong>: <a href="https://github.com/luxfi/kms">github.com/luxfi/kms</a> — <code>hanzoai/kms</code> is archived <strong>Production</strong>: https://kms.hanzo.ai <strong>Docker</strong>: <code>ghcr.io/luxfi/kms</code></p>
|
|
<h2>Motivation</h2>
|
|
<p>Before KMS, Hanzo secrets were managed through a patchwork of mechanisms:</p>
|
|
<ol><li><strong>Hardcoded in compose files</strong>: <code>compose.yml</code> files contained plaintext</li></ol>
|
|
<p> credentials. Anyone with repository access could read database passwords.</p>
|
|
<ol><li><strong>GitHub Actions secrets</strong>: CI/CD credentials lived in GitHub's secret</li></ol>
|
|
<p> store, invisible to audit and impossible to rotate without manual updates to every workflow.</p>
|
|
<ol><li><strong>Manual kubectl</strong>: Operators ran <code>kubectl create secret</code> by hand,</li></ol>
|
|
<p> introducing drift between what was deployed and what was documented.</p>
|
|
<ol><li><strong>Duplicated across services</strong>: The same SQL password appeared in</li></ol>
|
|
<p> IAM, Cloud, Console, and Platform deployments --- each copy managed independently.</p>
|
|
<ol><li><strong>No audit trail</strong>: When a secret was accessed, changed, or leaked, there</li></ol>
|
|
<p> was no way to know who did what, when.</p>
|
|
<p>These problems compound at scale. With 15+ services on hanzo-k8s and growing, manual secrets management became the single largest operational risk.</p>
|
|
<h2>Design Philosophy</h2>
|
|
<h3>Why our own KMS over HashiCorp Vault</h3>
|
|
<p>HashiCorp Vault is the industry default for secrets management, but it carries significant operational overhead:</p>
|
|
<ul><li><strong>Unseal ceremony</strong>: Vault starts sealed. Every restart (node reboot,</li></ul>
|
|
<p> deployment, OOM kill) requires unseal keys. In a two-replica K8s deployment, this means manual intervention or complex auto-unseal configurations with cloud KMS --- defeating the purpose of self-hosting.</p>
|
|
<ul><li><strong>HA complexity</strong>: Vault HA requires Raft consensus or Consul backend.</li></ul>
|
|
<p> Both add operational surfaces. Consul alone is a distributed system that needs its own monitoring, backup, and upgrade procedures.</p>
|
|
<ul><li><strong>Configuration language</strong>: Vault policies use HCL, a domain-specific</li></ul>
|
|
<p> language that developers must learn. Access control requires writing and deploying policy files.</p>
|
|
<ul><li><strong>No native UI for developers</strong>: Vault's UI exists but is designed for</li></ul>
|
|
<p> operators. Developers adding a new API key must understand mount paths, engines, and policy bindings.</p>
|
|
<p>The design was chosen because:</p>
|
|
<ul><li><strong>Modern UI</strong>: Developers can browse projects, environments, and secrets</li></ul>
|
|
<p> in a web interface that resembles a <code>.env</code> file editor. No learning curve.</p>
|
|
<ul><li><strong>Environment-based organization</strong>: Secrets are organized as project ></li></ul>
|
|
<p> environment > folder > key-value, which maps directly to our dev/staging/ production workflow.</p>
|
|
<ul><li><strong>Built-in secret rotation</strong>: the server supports automatic rotation for</li></ul>
|
|
<p> database credentials and API keys without external tooling.</p>
|
|
<ul><li><strong>Kubernetes operator</strong>: our own operator provides the <code>KMSSecret</code> CRD in one</li></ul>
|
|
<p> API group, <code>kms.hanzo.ai/v1</code>. The second group this HIP used to name, <code>secrets.lux.network</code>, is not installed; <code>kmssecrets.kms.hanzo.ai</code> is the only one, and universe declares it.</p>
|
|
<ul><li><strong>Open source with BSL</strong>: Business Source License allows self-hosting</li></ul>
|
|
<p> and modification. We fork, rebrand, and deploy without vendor lock-in.</p>
|
|
<ul><li><strong>Single binary</strong>: the server is a single Go binary with</li></ul>
|
|
<p> SQL and KV backends --- the same infrastructure we already operate for other services.</p>
|
|
<h3>Why Not AWS Secrets Manager or GCP Secret Manager</h3>
|
|
<p>Cloud-managed secret services (AWS Secrets Manager, GCP Secret Manager, Azure Key Vault) are excellent --- for workloads that will never leave that cloud. Hanzo's infrastructure has specific constraints:</p>
|
|
<ul><li><strong>Multi-cloud portability</strong>: Our K8s clusters run on DigitalOcean today.</li></ul>
|
|
<p> We may move to bare metal, Hetzner, or a different cloud provider. Managed secret services are inherently cloud-locked: AWS Secrets Manager is only accessible from AWS networks without complex VPN/peering configurations.</p>
|
|
<ul><li><strong>Cost at scale</strong>: AWS Secrets Manager charges $0.40/secret/month plus</li></ul>
|
|
<p> $0.05 per 10,000 API calls. With 200+ secrets across environments and services polling every 60 seconds, costs become non-trivial and unpredictable.</p>
|
|
<ul><li><strong>Unified access model</strong>: A self-hosted KMS means every service ---</li></ul>
|
|
<p> whether running in K8s, in CI/CD, or on a developer's laptop --- uses the same HTTPS API. No IAM roles, service accounts, or cloud-specific SDKs required.</p>
|
|
<ul><li><strong>Data sovereignty</strong>: Some customers and compliance frameworks require</li></ul>
|
|
<p> that encryption keys and credentials never leave infrastructure we control. Self-hosted KMS satisfies this requirement.</p>
|
|
<h3>Why the KMSSecret CRD</h3>
|
|
<p>Kubernetes-native secret sync via Custom Resource Definitions eliminates the most error-prone step in the secret lifecycle: getting secrets from the source of truth into the cluster where workloads consume them.</p>
|
|
<p>Without the CRD, the workflow is:</p>
|
|
<ol><li>Operator adds secret to KMS UI</li><li>Operator runs <code>kubectl create secret</code> with the new value</li><li>Operator restarts the affected deployment</li><li>Hope that step 2 was not forgotten, typo-free, and applied to the</li></ol>
|
|
<p> correct namespace</p>
|
|
<p>With the CRD, the workflow is:</p>
|
|
<ol><li>Operator adds secret to KMS UI</li><li>The KMS Operator detects the change within <code>resyncInterval</code> seconds</li><li>The K8s <code>Secret</code> is updated automatically</li><li>Workloads consuming the secret via <code>envFrom</code> or <code>valueFrom</code> pick up</li></ol>
|
|
<p> the change on next pod restart (or immediately if using mounted volumes)</p>
|
|
<p>Steps 2-4 are automated. No human in the loop after step 1.</p>
|
|
<h2>Specification</h2>
|
|
<h3>Secret Organization Model</h3>
|
|
<p>Secrets in KMS are organized hierarchically:</p>
|
|
<pre><code>Organization
|
|
└── Project
|
|
└── Environment
|
|
└── Folder
|
|
└── Key = Value</code></pre>
|
|
<h4>Organizations</h4>
|
|
<p>Top-level organizational boundary. Maps to Hanzo business units:</p>
|
|
<p>| Organization | Purpose | |-------------|---------| | <code>hanzo</code> | Hanzo AI core services | | <code>lux</code> | Lux blockchain infrastructure | | <code>zoo</code> | Zoo Labs Foundation services | | <code>pars</code> | Pars network services |</p>
|
|
<h4>Projects and paths</h4>
|
|
<p><strong>HIP-0136 is normative here.</strong> A secret is addressed by four coordinates and nothing else — <code><org>/<app>/<NAME>@<env></code> — where <code>app</code> is the app that READS the secret and <code>NAME</code> is exactly the environment variable the value becomes.</p>
|
|
<p>Earlier revisions of this HIP specified a project per deployable service (<code>hanzo-iam</code>, <code>gateway</code>, <code>chat</code>, <code>cloud</code>, <code>console</code>, …) so that "a compromised service identity can only read its own secrets". That is not what shipped: every <code>kmsSecrets</code> declaration in the fleet takes the org's project and distinguishes the service by path alone. The one exception is <code>base</code>, which holds its own project with its own machine identity, and which HIP-0136 explicitly protects from being folded in — it carries the IAM signing keys, and moving them into the shared project would let every app in the namespace read them.</p>
|
|
<p><strong>The isolation goal is not superseded; it is unmet.</strong> One project per org means one machine identity per namespace, so <code>secretsPath</code> organizes and does not authorize. Closing that gap means one machine identity per app — a change to identity topology, and its own proposal. See §Security.</p>
|
|
<h4>Environments</h4>
|
|
<p>Standard environment slugs. Every project MUST have these:</p>
|
|
<p>| Slug | Purpose | |------|---------| | <code>prod</code> | live services; the chart default and the only environment on this plane |</p>
|
|
<p><code>default</code> is not an environment. It is a leaked upstream spelling, and it is what made a present secret read as absent for eighteen hours: a query at the right path and the wrong env returns <code>total: 0</code>, which is indistinguishable from a secret that never existed (HIP-0136 §Motivation).</p>
|
|
<h4>Folders</h4>
|
|
<p>Optional sub-grouping within environments. Used for organizing large projects. Example: <code>/database/</code>, <code>/api-keys/</code>, <code>/oauth/</code>.</p>
|
|
<h3>Authenticating, and reading a secret</h3>
|
|
<p>A service authenticates as itself with the machine identity IAM already issued it — <code>client_credentials</code>, <code>client_secret_basic</code>, and RFC 8707 <code>resource</code> naming the KMS it is calling (HIP-0111). There is no second credential type and no auth stack of KMS's own; IAM is the sole authority for identity and tokens.</p>
|
|
<h4>Step 1: get an access token</h4>
|
|
<pre><code>POST https://hanzo.id/v1/iam/oauth/token
|
|
Authorization: Basic base64(clientId:clientSecret)
|
|
grant_type=client_credentials&resource=hanzo-kms</code></pre>
|
|
<h4>Step 2: read the secret</h4>
|
|
<pre><code>GET https://api.hanzo.ai/v1/kms/secrets?path=/gateway&env=prod&name=IAM_CLIENT_SECRET
|
|
Authorization: Bearer <access token></code></pre>
|
|
<p>The three query parameters are the address: <code>path</code> names the app that reads the secret, <code>name</code> is exactly the environment variable it becomes, <code>env</code> is <code>prod</code>. They resolve to <code>/orgs/<org>/<path>/<NAME></code>, and the org comes from the validated token, never from the request — a caller that could name its own org could read another tenant's store.</p>
|
|
<p><strong>A read that returns nothing is not evidence of absence.</strong> A path-filtered list returning <code>total: 0</code> and a genuinely empty store are the same response, and treating them as the same is how a migration deletes a live credential. Absence is established only by enumerating the store the chart actually reads (HIP-0136 §Migration).</p>
|
|
<h4>Step 3: use it</h4>
|
|
<p>The value is injected into the service's runtime configuration. In Kubernetes it does not travel this path at all: the <code>KMSSecret</code> controller reads it and writes a native <code>Secret</code> the pod mounts, which is the next section.</p>
|
|
<h3>Machine Identity Lifecycle</h3>
|
|
<p>Each service is represented by a Machine Identity in KMS. The identity lifecycle follows these steps:</p>
|
|
<ol><li><strong>Create Identity</strong>: In the KMS UI, create a Machine Identity with a</li></ol>
|
|
<p> descriptive name (e.g., <code>iam-service</code>, <code>gateway-service</code>).</p>
|
|
<ol><li><strong>Enable Universal Auth</strong>: Attach Universal Auth credentials to the</li></ol>
|
|
<p> identity. KMS generates a <code>clientId</code> and <code>clientSecret</code>.</p>
|
|
<ol><li><strong>Grant Project Access</strong>: Assign the identity to the relevant project</li></ol>
|
|
<p> with the minimum required role (typically <code>Viewer</code> for read-only secret access).</p>
|
|
<ol><li><strong>Bootstrap Credentials</strong>: Store the <code>clientId</code> and <code>clientSecret</code> in</li></ol>
|
|
<p> the target environment (K8s secret, CI/CD variable, etc.).</p>
|
|
<ol><li><strong>Rotate Periodically</strong>: Regenerate the <code>clientSecret</code> and update the</li></ol>
|
|
<p> bootstrap credential. The <code>clientId</code> remains stable.</p>
|
|
<h3>KMSSecret Custom Resource Definition</h3>
|
|
<p>The <code>KMSSecret</code> CRD is the Kubernetes-native interface for syncing secrets from KMS into the cluster.</p>
|
|
<h4>API Group and Version</h4>
|
|
<pre><code>apiVersion: secrets.lux.network/v1alpha1
|
|
kind: KMSSecret</code></pre>
|
|
<h4>Full Specification</h4>
|
|
<pre><code class="lang-yaml">apiVersion: secrets.lux.network/v1alpha1
|
|
kind: KMSSecret
|
|
metadata:
|
|
name: <service>-kms-sync
|
|
namespace: hanzo
|
|
labels:
|
|
app.kubernetes.io/name: <service>
|
|
app.kubernetes.io/component: secrets
|
|
app.kubernetes.io/part-of: hanzo-universe
|
|
spec:
|
|
# KMS API endpoint
|
|
hostAPI: https://kms.hanzo.ai
|
|
|
|
# How often (in seconds) to re-sync secrets from KMS
|
|
# Lower values = faster propagation, higher API load
|
|
# Recommended: 60 for production, 30 for staging
|
|
resyncInterval: 60
|
|
|
|
# Authentication configuration
|
|
authentication:
|
|
universalAuth:
|
|
credentialsRef:
|
|
# K8s Secret containing clientId and clientSecret
|
|
secretName: <service>-kms-auth
|
|
secretNamespace: hanzo
|
|
secretsScope:
|
|
# KMS project slug
|
|
projectSlug: <project-slug>
|
|
# KMS environment slug
|
|
envSlug: production
|
|
# Path within the environment
|
|
secretsPath: /
|
|
|
|
# Target K8s Secret to create/update
|
|
managedSecretReference:
|
|
secretName: <service>-secrets
|
|
secretNamespace: hanzo
|
|
secretType: Opaque</code></pre>
|
|
<h4>Bootstrap Secret</h4>
|
|
<p>Every <code>KMSSecret</code> resource references a bootstrap secret containing the Machine Identity credentials. This is the ONE secret that must be created manually:</p>
|
|
<pre><code class="lang-bash">kubectl create secret generic <service>-kms-auth \
|
|
--from-literal=clientId=<machine-identity-client-id> \
|
|
--from-literal=clientSecret=<machine-identity-client-secret> \
|
|
--dry-run=client -o yaml | kubectl apply -f -</code></pre>
|
|
<p>This is an intentional design constraint. The bootstrap secret is a "root of trust" --- it cannot be managed by the system it bootstraps.</p>
|
|
<h3>CI/CD integration</h3>
|
|
<p>CI is Hanzo Git Actions executed by <code>act_runner</code>, and the pipeline is one reusable workflow in <code>hanzoai/ci</code> (HIP-0036). A repository does not write its own KMS fetch: the reusable workflow does it, once, using the build's machine identity, and the secret is addressed at <code>hanzo/deploy/<NAME>@prod</code>.</p>
|
|
<p>The only durable value a repository stores is that machine identity, and it is set <strong>on the forge</strong>, which is what executes the workflow.</p>
|
|
<p>Two things a build must not be given, because it does not need them: a cloud provider token or kubeconfig (it does not deploy — HIP-0036 §Deployment), and any upstream vendor credential a <em>service</em> needs at runtime (that is egress's custody — HIP-0143).</p>
|
|
<h3>Secret Rotation Policy</h3>
|
|
<p>| Secret Type | Rotation Frequency | Method | |------------|-------------------|--------| | Database passwords | 90 days | KMS auto-rotation | | API keys (third-party) | 90 days | Manual + KMS update | | OAuth client secrets | 180 days | Coordinated with IAM | | Encryption keys | 365 days | Key versioning | | Machine Identity secrets | 180 days | KMS regenerate | | JWT signing keys | 90 days | Rolling deployment |</p>
|
|
<h3>Audit Logging</h3>
|
|
<p>KMS logs every secret access with:</p>
|
|
<ul><li><strong>Who</strong>: Machine Identity ID or user email</li><li><strong>What</strong>: Secret key name (never the value)</li><li><strong>When</strong>: ISO 8601 timestamp</li><li><strong>Where</strong>: Source IP address</li><li><strong>Action</strong>: <code>read</code>, <code>create</code>, <code>update</code>, <code>delete</code></li><li><strong>Project</strong>: Project slug and environment</li></ul>
|
|
<p>Audit logs are retained for 365 days and are queryable via the KMS API:</p>
|
|
<pre><code>GET /v1/kms/audit?path=<path>&from=2026-01-01&to=2026-01-31
|
|
Authorization: Bearer <admin-token></code></pre>
|
|
<h2>Implementation</h2>
|
|
<h3>Production Architecture</h3>
|
|
<pre><code>┌─────────────────────────────────────────────────────────┐
|
|
│ Kubernetes cluster │
|
|
│ │
|
|
│ ┌───────────┐ ┌────────────────┐ │
|
|
│ │ KMS (x2) │────▶│ SQL │ │
|
|
│ │ port 8080 │ │ (kms database) │ │
|
|
│ └─────┬─────┘ └────────────────┘ │
|
|
│ │ │
|
|
│ │ ┌────────────────┐ │
|
|
│ └──────────▶│ KV │ │
|
|
│ │ (session/cache)│ │
|
|
│ └────────────────┘ │
|
|
│ │
|
|
│ ┌──────────────────┐ │
|
|
│ │ KMS Operator │ watches KMSSecret CRDs │
|
|
│ │ (kms-operator) │───▶ syncs to K8s Secrets │
|
|
│ └──────────────────┘ │
|
|
│ │
|
|
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
|
│ │ IAM │ │ Gateway │ │ Chat │ │ Cloud │ │
|
|
│ │ (reads) │ │ (reads) │ │ (reads) │ │ (reads) │ │
|
|
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
|
|
└─────────────────────────────────────────────────────────┘
|
|
▲
|
|
│ HTTPS (port 443 via Ingress)
|
|
│
|
|
┌─────┴──────┐
|
|
│ CI/CD │ GitHub Actions, developer laptops
|
|
│ (reads) │
|
|
└────────────┘</code></pre>
|
|
<h3>Deployment Specification</h3>
|
|
<p>KMS runs as a Deployment with 2 replicas for high availability:</p>
|
|
<pre><code class="lang-yaml">spec:
|
|
replicas: 2
|
|
strategy:
|
|
type: RollingUpdate
|
|
rollingUpdate:
|
|
maxSurge: 1
|
|
maxUnavailable: 0</code></pre>
|
|
<p>Pod anti-affinity ensures replicas land on different nodes:</p>
|
|
<pre><code class="lang-yaml">affinity:
|
|
podAntiAffinity:
|
|
preferredDuringSchedulingIgnoredDuringExecution:
|
|
- weight: 100
|
|
podAffinityTerm:
|
|
labelSelector:
|
|
matchExpressions:
|
|
- key: app
|
|
operator: In
|
|
values: ["kms"]
|
|
topologyKey: kubernetes.io/hostname</code></pre>
|
|
<h3>Helm Chart: kms-standalone</h3>
|
|
<p>The <code>kms-standalone</code> Helm chart supports automated bootstrap:</p>
|
|
<pre><code class="lang-yaml">kms:
|
|
autoBootstrap:
|
|
enabled: true
|
|
# Create additional organizations beyond the default
|
|
additionalOrganizations:
|
|
- hanzo
|
|
- lux
|
|
- zoo
|
|
- pars
|
|
# Grant org-admin to these emails during org creation
|
|
additionalOrganizationAdminEmails:
|
|
- [email protected]
|
|
# Secret template key for bootstrap token
|
|
additionalOrganizationsTokenSecretKey: token</code></pre>
|
|
<p>This ensures that on first deployment, all four organizations exist and the specified admin has access across all of them.</p>
|
|
<h3>Resource Requirements</h3>
|
|
<pre><code class="lang-yaml">resources:
|
|
requests:
|
|
memory: "512Mi"
|
|
cpu: "250m"
|
|
limits:
|
|
memory: "2Gi"
|
|
cpu: "1000m"</code></pre>
|
|
<h3>Health Checks</h3>
|
|
<pre><code class="lang-yaml">readinessProbe:
|
|
httpGet:
|
|
path: /healthz
|
|
port: 8080
|
|
initialDelaySeconds: 60
|
|
periodSeconds: 10
|
|
|
|
livenessProbe:
|
|
httpGet:
|
|
path: /healthz
|
|
port: 8080
|
|
initialDelaySeconds: 120
|
|
periodSeconds: 30</code></pre>
|
|
<h3>KMS's Own Secrets (Bootstrap Problem)</h3>
|
|
<p>KMS cannot fetch its own master key from the KMS it is. That circularity is irreducible — every secret store has one — and it is stated here rather than hidden.</p>
|
|
<p>What is reducible is how much sits inside it. The bootstrap set is the master key and the identity it authenticates with, held as a K8s <code>Secret</code> created once at cluster provisioning and recorded offline. It is deliberately <strong>not</strong> a database connection string and a cache URL: those were in the bootstrap set only because KMS ran on a database of its own, and a store that keeps per-org encrypted files (HIP-1134) has no such connection to bootstrap. Every value that leaves the bootstrap set is one fewer secret living outside the system that manages secrets.</p>
|
|
<p><code>stringData</code> is not an escape hatch anywhere else. Charts carry references and never values, and <code>templates/kmssecret.yaml</code> has no field that would accept one — on purpose, and this HIP does not add one.</p>
|
|
<h2>Security</h2>
|
|
<h3>Threat Model</h3>
|
|
<p>| Threat | Mitigation | |--------|-----------| | Compromised service identity | Scoped to single project; revoke identity immediately | | KMS database breach | All secrets encrypted at rest with ROOT_ENCRYPTION_KEY (AES-256-GCM) | | Network interception | All communication over HTTPS with TLS 1.3 | | Insider threat | Audit logs capture all access; role-based access control | | KMS service compromise | Two replicas on separate nodes; encrypted backups | | Leaked bearer token | Tokens expire after 7200s; IP allowlisting available | | Git secret leak | Secrets never exist in git; KMS is sole source of truth | | CI/CD secret exfiltration | Only KMS_CLIENT_ID and KMS_CLIENT_SECRET in CI; short-lived tokens |</p>
|
|
<h3>Zero-Trust Principles</h3>
|
|
<ol><li><strong>Every service authenticates independently</strong>: No shared credentials</li></ol>
|
|
<p> between services. IAM has its own Machine Identity; Gateway has its own. Compromising one does not compromise another.</p>
|
|
<ol><li><strong>Minimum privilege</strong>: Machine Identities get <code>Viewer</code> role (read-only)</li></ol>
|
|
<p> on their specific project. No service can read another service's secrets.</p>
|
|
<ol><li><strong>No implicit trust</strong>: Even services within the same K8s namespace must</li></ol>
|
|
<p> authenticate with KMS. Network proximity grants no privilege.</p>
|
|
<ol><li><strong>Short-lived credentials</strong>: Bearer tokens expire. Even if captured from</li></ol>
|
|
<p> a log or network trace, they become useless within hours.</p>
|
|
<h3>Encryption</h3>
|
|
<ul><li><strong>At rest</strong>: AES-256-GCM encryption of all secret values in SQL.</li></ul>
|
|
<p> The <code>ROOT_ENCRYPTION_KEY</code> is a 256-bit key generated during initial setup and stored as a K8s Secret.</p>
|
|
<ul><li><strong>In transit</strong>: TLS 1.3 for all API communication. The KMS Ingress</li></ul>
|
|
<p> terminates TLS with a certificate from Let's Encrypt (via cert-manager).</p>
|
|
<ul><li><strong>In memory</strong>: Secret values exist in plaintext only in the KMS</li></ul>
|
|
<p> application process memory during request handling. They are not cached in KV or written to temporary files.</p>
|
|
<h3>Compliance Mapping</h3>
|
|
<p>| Framework | Requirement | How KMS Satisfies | |-----------|------------|-------------------| | SOC 2 CC6.1 | Logical access security | Machine Identity auth, RBAC | | SOC 2 CC6.3 | Access revocation | Identity deletion, token expiry | | SOC 2 CC7.2 | System monitoring | Audit logs, access tracking | | HIPAA 164.312(a) | Access control | Per-project isolation, RBAC | | HIPAA 164.312(e) | Transmission security | TLS 1.3 | | GDPR Art. 32 | Security of processing | AES-256-GCM, audit trail | | PCI DSS 3.4 | Render PAN unreadable | Encryption at rest |</p>
|
|
<pre><code class="lang-yaml"># compose.yml - DO NOT DO THIS
|
|
environment:
|
|
DATABASE_URL: "postgresql://user:password@host:5432/db"
|
|
API_KEY: "sk-live-abc123"</code></pre>
|
|
<p>After (KMS-backed):</p>
|
|
<pre><code class="lang-yaml"># compose.yml
|
|
environment:
|
|
KMS_CLIENT_ID: "${KMS_CLIENT_ID}"
|
|
KMS_CLIENT_SECRET: "${KMS_CLIENT_SECRET}"
|
|
# Service fetches all other secrets from KMS at startup</code></pre>
|
|
<h3>From a pile of stored CI secrets</h3>
|
|
<p>Before — one stored value per credential, each rotated by hand in every repository that held it:</p>
|
|
<pre><code class="lang-yaml">env:
|
|
DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
|
|
DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
|
|
DO_ACCESS_TOKEN: ${{ secrets.DIGITALOCEAN_ACCESS_TOKEN }}
|
|
DATABASE_URL: ${{ secrets.DATABASE_URL }}
|
|
REDIS_URL: ${{ secrets.REDIS_URL }}</code></pre>
|
|
<p>Three of those five no longer exist to store, which is the more interesting half of the migration: there is no registry password (the push authorizes with an IAM identity, HIP-0033), the build holds no cloud provider token because it does not deploy (HIP-0036), and a service reaches the shared store through egress rather than through a connection string of its own (HIP-0143, HIP-0144).</p>
|
|
<p>After — one stored identity, everything else fetched:</p>
|
|
<pre><code class="lang-yaml">env:
|
|
KMS_CLIENT_ID: ${{ secrets.KMS_CLIENT_ID }}
|
|
KMS_CLIENT_SECRET: ${{ secrets.KMS_CLIENT_SECRET }}
|
|
# Fetch everything else from KMS at runtime</code></pre>
|
|
<h3>From kubectl create secret</h3>
|
|
<p>Before (manual, error-prone):</p>
|
|
<pre><code class="lang-bash">kubectl create secret generic my-service-secrets \
|
|
--from-literal=DB_URL=postgresql://... \
|
|
--from-literal=API_KEY=sk-... \
|
|
--from-literal=REDIS_URL=redis://...</code></pre>
|
|
<p>After (automated):</p>
|
|
<pre><code class="lang-yaml"># Apply once:
|
|
apiVersion: secrets.lux.network/v1alpha1
|
|
kind: KMSSecret
|
|
metadata:
|
|
name: my-service-kms-sync
|
|
namespace: hanzo
|
|
spec:
|
|
hostAPI: https://kms.hanzo.ai
|
|
resyncInterval: 60
|
|
authentication:
|
|
universalAuth:
|
|
credentialsRef:
|
|
secretName: my-service-kms-auth
|
|
secretNamespace: hanzo
|
|
secretsScope:
|
|
projectSlug: my-service
|
|
envSlug: production
|
|
secretsPath: /
|
|
managedSecretReference:
|
|
secretName: my-service-secrets
|
|
secretNamespace: hanzo
|
|
secretType: Opaque
|
|
# Secrets auto-sync every 60 seconds. No manual steps.</code></pre>
|
|
<h2>Operational Procedures</h2>
|
|
<h3>Adding a New Service to KMS</h3>
|
|
<ol><li>Create a project in KMS UI (<code>kms.hanzo.ai</code>) with slug matching the</li></ol>
|
|
<p> service name.</p>
|
|
<ol><li>Add environments: <code>dev</code>, <code>staging</code>, <code>production</code>.</li><li>Add all secret key-value pairs to each environment.</li><li>Create a Machine Identity named <code><service>-service</code>.</li><li>Enable Universal Auth on the identity.</li><li>Grant the identity <code>Viewer</code> role on the project.</li><li>Create the bootstrap K8s secret:</li></ol>
|
|
<p> ``<code>bash kubectl create secret generic <service>-kms-auth \ --from-literal=clientId=<id> \ --from-literal=clientSecret=<secret> \ --dry-run=client -o yaml | kubectl apply -f - </code>``</p>
|
|
<ol><li>Apply the <code>KMSSecret</code> resource (see specification above).</li><li>Verify sync: <code>kubectl get secret <service>-secrets -o yaml</code></li></ol>
|
|
<h3>Rotating a Machine Identity Secret</h3>
|
|
<ol><li>In KMS UI, navigate to the Machine Identity.</li><li>Regenerate the client secret (old secret remains valid for a grace</li></ol>
|
|
<p> period).</p>
|
|
<ol><li>Update the bootstrap K8s secret:</li></ol>
|
|
<p> ``<code>bash kubectl create secret generic <service>-kms-auth \ --from-literal=clientId=<id> \ --from-literal=clientSecret=<new-secret> \ --dry-run=client -o yaml | kubectl apply -f - </code>``</p>
|
|
<ol><li>The KMS Operator will use the new credentials on next resync cycle.</li><li>Verify by checking operator logs for successful sync.</li></ol>
|
|
<h3>Emergency Secret Revocation</h3>
|
|
<p>If a secret is suspected compromised:</p>
|
|
<ol><li><strong>Rotate the secret value</strong> in KMS UI immediately.</li><li><strong>Revoke the Machine Identity</strong> if the identity credentials were</li></ol>
|
|
<p> compromised (not just the secret value).</p>
|
|
<ol><li><strong>Force resync</strong> by deleting and re-creating the <code>KMSSecret</code> resource.</li><li><strong>Restart affected pods</strong> to pick up the new K8s Secret values:</li></ol>
|
|
<p> ``<code>bash kubectl rollout restart deployment/<service> </code>``</p>
|
|
<ol><li><strong>Review audit logs</strong> to determine the scope of the breach.</li></ol>
|
|
<h2>References</h2>
|
|
<ol><li><code>luxfi/kms</code> -- the primitives all server logic lives in</li><li><a href="./hip-0005-post-quantum-security-for-ai-infrastructure.md">HIP-5: Post-Quantum Security for AI Infrastructure</a></li><li><a href="./hip-0004-llm-gateway-unified-ai-provider-interface.md">HIP-4: LLM Gateway</a></li><li><a href="https://csrc.nist.gov/publications/detail/sp/800-57-part-1/rev-5/final">NIST SP 800-57: Key Management</a></li><li><a href="https://kubernetes.io/docs/concepts/configuration/secret/">Kubernetes Secrets Best Practices</a></li><li><a href="https://www.aicpa-cima.com/topic/audit-assurance/audit-and-assurance-greater-than-soc-2">SOC 2 Trust Services Criteria</a></li></ol>
|
|
<h2>Conformance status</h2>
|
|
<p>Measured on 2026-09-09.</p>
|
|
<p><strong>Ships.</strong> <code>kmssecrets.kms.hanzo.ai/v1</code> is installed and reconciled, with 174 <code>KMSSecret</code> resources live across the estate — <code>hanzo-build</code>, <code>collab</code>, <code>enso</code>, <code>extract-svc</code> and others. A representative resource carries exactly the fields §KMSSecret specifies (<code>projectSlug</code>, <code>envSlug</code>, <code>secretsPath</code>, <code>keys</code>, <code>rename</code>, <code>managedSecretName</code>, <code>creationPolicy</code>) plus <code>transport: iam</code>, so the operator reaches KMS with an IAM identity rather than a bespoke token — which is the authentication §Authenticating specifies, already in production. <code>kms.hanzo.ai/v1/health</code> returns <code>200</code> with a build revision.</p>
|
|
<p><strong>Corrected in this revision.</strong> §Authentication and §Secret Retrieval documented <code>POST /api/v1/auth/universal-auth/login</code> and <code>GET /api/v3/secrets/raw</code>, which both return <code>404</code> and carry an <code>/api/</code> prefix no Hanzo surface uses. They described the third-party product this standard was originally derived from rather than the server that answers. They are replaced by the IAM <code>client_credentials</code> flow and <code>api.hanzo.ai/v1/kms</code>.</p>
|
|
<p><strong>Still open, and the reason this HIP is not Final.</strong> Two deployments of one service hold the data between them — <code>api.hanzo.ai/v1/kms</code> and the standalone at <code>kms.hanzo.ai</code>, which every chart's <code>kmsSecrets</code> still reaches through the CRD's <code>hostAPI</code>. That is one program deployed twice with its data split, not two architectures, and it must never be written up as one. A name present in one and absent from the other returns <code>total: 0</code> from the wrong door, which is indistinguishable from a secret that never existed. HIP-0136 §Migration carries the collapse sequence; until it lands, "which KMS" is a question a reader can still be forced to ask, and that is exactly the question this standard exists to delete.</p>
|
|
<p><strong>The isolation goal remains unmet.</strong> One project per org means one machine identity per namespace, so any app in a namespace can read any path in that project. <code>secretsPath</code> organizes; it does not authorize. Closing it means one machine identity per app, which is a change of identity topology and belongs in its own proposal.</p>
|
|
<h2>Copyright</h2>
|
|
<p>Copyright and related rights waived via <a href="https://creativecommons.org/publicdomain/zero/1.0/">CC0</a>.</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="/hip-0027.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
|
|
</footer>
|
|
</div></body></html> |