Files
skills/public/hip-0136.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

308 lines
30 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>hip-0136</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-0136.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/hip-0136">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/hip-0136.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-0136</h1><p class="lede">HIP-136: One Secret, One Path. Status Final. Hanzo architectural specification.</p><h1>HIP-0136: One Secret, One Path</h1>
<h2>Abstract</h2>
<p>A secret&#x27;s location is <strong>derivable</strong>, never remembered. Given the app that reads it and the environment variable it becomes, there is exactly one path it can be at, one Kubernetes Secret it lands in, and one key inside that Secret. Nobody looks it up, because there is nothing to look up.</p>
<p> hanzo/gateway/IAM_CLIENT_SECRET@prod</p>
<p>Read that as: the <code>hanzo</code> org&#x27;s <code>gateway</code> app reads <code>IAM_CLIENT_SECRET</code>, in <code>prod</code>. Every part is a fact you already had before you went looking.</p>
<h2>Motivation</h2>
<p>This is written from an outage. <code>index-chat</code> sat in CrashLoopBackOff for 18 hours — 221 restarts — exiting with <em>&quot;You must provide a master key&quot;</em> and printing a freshly generated key into its own log each time. The key was never missing. It was in KMS the whole time. Nobody could find it, because one concept had four names across two namespaces:</p>
<p> env var INDEX_MASTER_KEY k8s secrets search-secrets/SEARCH_MASTER_KEY chat-index-key/INDEX_MASTER_KEY index-chat-env/INDEX_MASTER_KEY index-chat-env-mnemonic KMS /platform/index-chat, read at envSlug <code>default</code> every other service reads <code>prod</code></p>
<p>During the repair an engineer queried the right path at the wrong env, got <code>total: 0</code>, and concluded the secret did not exist. It did. That is the cost of a path you have to know rather than derive.</p>
<p>Across the fleet the <code>secretsPath</code> field had grown five incompatible shapes. It sometimes named the app, sometimes the secret, sometimes a category, sometimes nothing:</p>
<p> / the root, flat /aml /studio /pkg the app /iam-service-token the SECRET, not the app /cloud-sign a purpose /platform/index-chat a category, then the app</p>
<p>Five shapes is not a convention with exceptions. It is the absence of one.</p>
<h2>There is ONE KMS: <code>api.hanzo.ai/v1/kms</code></h2>
<p>It answers <code>path</code> / <code>env</code> / <code>name</code>, resolving to <code>/orgs/&lt;org&gt;/&lt;path&gt;/&lt;NAME&gt;</code>, and it is the only store any service reads.</p>
<p>There is currently a SECOND DEPLOYMENT of it — <code>localhost:8200</code> / <code>kms.hanzo.ai</code>, which every chart&#x27;s <code>kmsSecrets</code> still points at through the KMSSecret CRD&#x27;s <code>hostAPI</code>. That is not a second architecture and must never be written up as one. It is the same <code>luxfi/kms</code> binary serving the same <code>/v1/kms/secrets</code> routes under the same JWT boundary — its own source says of the two endpoints, <em>&quot;gates on the same thing requireOrgJWT ultimately does: whether the caller&#x27;s own org authorizes this deployment&#x27;s home org. Two doors, one boundary.&quot;</em> One program, deployed twice, with its data split across the two.</p>
<p>The split is what makes secrets unfindable, and it is a migration item, not a design. A name present in one deployment is absent from the other, so a query against the wrong one returns <code>total: 0</code> — indistinguishable from a secret that never existed, and exactly how a migration deletes a live credential. See the Migration section: the standalone&#x27;s contents move into <code>api.hanzo.ai/v1/kms</code>, every <code>hostAPI</code> repoints there, and the standalone is scaled to zero.</p>
<p><strong>White-labelling is a frontend concern, not a second store.</strong> <code>kms.lux.cloud</code> resolves to this same API with Lux branding, as <code>kms.hanzo.ai</code> does with Hanzo&#x27;s; the org boundary already separates the data. A brand does not earn a deployment. An operator that needs its own MPC root — a Lux committee signing in <code>lux-k8s</code> rather than <code>hanzo-k8s</code> — configures that under one API too; the REK&#x27;s location is deployment configuration, not a fork of the service.</p>
<h2>Specification</h2>
<h3>1. The path</h3>
<p>A secret is addressed by four coordinates and nothing else:</p>
<p> &lt;org&gt;/&lt;app&gt;/&lt;NAME&gt;@&lt;env&gt;</p>
<p><strong><code>org</code></strong> — the KMS project the secret lives in, which for a shared platform service is the tenant that owns it: <code>hanzo</code>. This is the store boundary already — KMS resolves <code>/orgs/&lt;org&gt;/…</code> — so stating it makes explicit what was implicit.</p>
<p>A service with its OWN project (its own machine identity, e.g. <code>base</code> at <code>hanzo-base</code>) is addressed by that project instead, and keeps it. The project is the real authorization boundary; the path below it is organization. Anything holding material the rest of the namespace must not read belongs in its own project, and moving it into the shared one to satisfy a naming rule would be a downgrade.</p>
<p><strong><code>app</code></strong> — the app that <strong>READS</strong> the secret. Never the app that produced it, never a category, never a purpose. One question with one answer: <em>which process will hold this in memory?</em> It is the same string as the app&#x27;s name in <code>charts/app/values/&lt;namespace&gt;/&lt;app&gt;.yaml</code> and its Kubernetes workload.</p>
<p>A secret read by two apps is <strong>one entry</strong>, and both name their own path only if they genuinely hold different material. Two apps sharing one credential share one path; copying it to a second path so each can &quot;own&quot; one is what produced <code>chat-index-key</code> and <code>index-chat-env</code> — two names, one key, guaranteed to drift.</p>
<p><strong><code>NAME</code></strong> — exactly the environment variable the value becomes. Not a description of it, not a slug, not a renaming. <code>INDEX_MASTER_KEY</code> in the container is <code>INDEX_MASTER_KEY</code> in KMS. When the variable and the key disagree, every reader must carry a translation, and a translation is a thing that can be wrong.</p>
<p><strong><code>env</code></strong> — <code>prod</code>. There is one environment on this plane and it is the chart default. <code>default</code> is not an environment; it was a Infisical-ism that leaked, and it is what made a present secret read as absent.</p>
<h3>2. The Kubernetes side is derived, not chosen</h3>
<p>Declaring the path fixes everything downstream. There are no further decisions:</p>
<pre><code class="lang-yaml">kmsSecrets:
- name: &lt;app&gt;-env-kms-sync # the KMSSecret CR
secretsPath: /&lt;app&gt; # the org is the store; the app is the path
keys: [&lt;NAME&gt;, ...] # the variable names, verbatim
secretName: &lt;app&gt;-env # the Secret the pod mounts</code></pre>
<p>and the container reads it the only way it can:</p>
<pre><code class="lang-yaml">- name: &lt;NAME&gt;
valueFrom:
secretKeyRef:
name: &lt;app&gt;-env
key: &lt;NAME&gt;</code></pre>
<p><code>hostAPI</code>, <code>projectSlug</code>, <code>envSlug</code>, <code>credentialsSecret</code> and <code>resyncInterval</code> come from the chart&#x27;s <code>kms:</code> defaults. Set them only when the app runs outside the platform namespace, where the credential it authenticates with is its own namespace&#x27;s.</p>
<p><strong>The Secret lives in the app&#x27;s own namespace.</strong> The controller reads its credential from, and writes its managed Secret to, the release namespace. A secret synced beside a <em>different</em> app is not available to this one — that is precisely how a key sat in <code>hanzo</code> while the service that needed it ran in <code>tenant-hanzo</code> and died for 18 hours.</p>
<h3>3. <code>optional: true</code> is banned on a value the service requires</h3>
<pre><code class="lang-yaml"> secretKeyRef:
name: index-chat-env
key: INDEX_MASTER_KEY
optional: true # ← this</code></pre>
<p><code>optional</code> converts a missing Secret — which Kubernetes reports precisely, as <code>CreateContainerConfigError</code>, naming the Secret — into a container that starts and then kills itself for reasons only its logs know. It buys nothing and it costs the diagnosis. If the service cannot run without the value, let the kubelet say so.</p>
<h3>4. Deriving a path you have never seen</h3>
<p>Two questions, no lookup:</p>
<ol><li><em>Which app reads it?</em> → <code>&lt;app&gt;</code></li><li><em>What is the variable called?</em> → <code>&lt;NAME&gt;</code></li></ol>
<pre><code>gateway needs STRIPE_SECRET_KEY → hanzo/gateway/STRIPE_SECRET_KEY@prod
→ secretsPath: /gateway
→ Secret gateway-env, key STRIPE_SECRET_KEY</code></pre>
<p>If answering (1) is hard, the secret is shared and the sharing is the thing to fix — not the path.</p>
<h2>Relationship to HIP-0027</h2>
<p>HIP-0027 §&quot;Secret Organization Model&quot; specifies <code>Organization → Project → Environment → Folder → Key</code>, with <strong>a project per deployable service</strong> — <code>hanzo-iam</code>, <code>gateway</code>, <code>chat</code>, <code>cloud</code>, <code>console</code> — so that &quot;a compromised service identity can only read its own secrets.&quot;</p>
<p><strong>That is not what shipped.</strong> Every <code>kmsSecrets</code> declaration in the fleet takes the chart default <code>projectSlug: hanzo</code>, one project for the whole org, with the service distinguished only by <code>secretsPath</code>. The sole exception is <code>base</code> (<code>hanzo-base</code>). The per-service projects that HIP-0027 tabulates as &quot;current projects in production&quot; are not what the charts address.</p>
<p>This HIP states the rule for the tree that exists: one project per <strong>org</strong>, and the app in the <strong>path</strong>. Where the two disagree about where a service&#x27;s secrets live, this one is normative and HIP-0027&#x27;s project-per-service layout is superseded.</p>
<p>What is <strong>not</strong> superseded is HIP-0027&#x27;s <em>reason</em> for wanting it. That isolation goal remains unmet — see Security Considerations. Closing it is a change of identity topology, not of naming, and belongs in its own proposal.</p>
<h2>Migration</h2>
<p>Four of eleven declarations already conform. Seven move:</p>
<p>| app | today | becomes | |---|---|---| | <code>admin-guard</code> | <code>/admin-guard-secrets</code> | <code>/admin-guard</code> | | <code>chat</code> | <code>/chat-guest-key</code> | <code>/chat</code> | | <code>cloud</code> | <code>/cloud-sign</code> | <code>/cloud</code> | | <code>cloud</code> | <code>/integrations/cloudflare</code> (env <code>default</code>) | <code>/cloud</code> (env <code>prod</code>) | | <code>iam</code> | <code>/iam-service-token</code> | <code>/iam</code> |</p>
<p>The <code>iam</code> row is the one worth reading twice. Its old path named a <strong>service token</strong> — a bearer minted outside IAM and shared between callers, which is the pattern IAM exists to replace. Those tokens have since been deleted across cloud and commerce; a caller presents an IAM identity now (<code>client_credentials</code>, RFC 8707 <code>resource</code>-scoped, JWKS-verified — HIP-0111). So the move is not only a rename: the entry that moves is a client secret, and the shared token it replaced should not come back under a conforming path. | <code>team</code> | <code>/team-go-secret</code> | <code>/team</code> |</p>
<p>Already conforming: <code>aml</code>, <code>bot-browser</code>, <code>pkg</code>, <code>studio</code>.</p>
<p><strong><code>base</code> is deliberately NOT in that table, and must not be added to it.</strong> It sets <code>projectSlug: hanzo-base</code> with its own <code>credentialsSecret</code>, so its <code>/</code> is the root of its OWN project, reached by its OWN machine identity — not a shared path carelessly left at the root of everyone else&#x27;s. It holds <code>EMBEDDED_IAM_ROOT_PASSWORD</code> and the IAM signing keys, and no other app in the fleet can read them.</p>
<p>That is HIP-0027&#x27;s project-per-service isolation, actually implemented, and it is STRONGER than what this HIP describes. Folding it into <code>hanzo/base/*</code> would move the most sensitive material in the estate into the shared project where every app in the namespace could read it. An app with its own project keeps it. The rule below is how a service in the SHARED project is addressed; <code>&lt;org&gt;</code> names the project a secret lives in, and a service that has earned its own is the direction of travel, not a deviation from it.</p>
<h3>Collapsing the second deployment</h3>
<p>The path moves above are the small half. The larger one is that a second deployment of this same service holds most of the data, and it goes away:</p>
<ol><li>Copy every secret from the standalone (<code>kms.hanzo.ai</code>, ~1832 entries at root)</li></ol>
<p> into <code>api.hanzo.ai/v1/kms</code>, preserving <code>path</code>/<code>env</code>/<code>name</code>, verifying each value byte-identical after the write. Both speak the same API under the same JWT boundary, so this is a read here / write there with one token — not an envelope conversion.</p>
<ol><li>Repoint every chart&#x27;s <code>kmsSecrets</code> <code>hostAPI</code> at cloud, and drop the</li></ol>
<p> <code>localhost:8200</code> default from <code>charts/app/values.yaml</code>.</p>
<ol><li>Confirm each app&#x27;s Secret still carries byte-identical values, from a RUNNING</li></ol>
<p> pod, before anything is deleted.</p>
<ol><li>Scale the standalone to zero, then remove it.</li></ol>
<p>Order matters and step 3 is not optional: a Secret that syncs empty does not fail the pod, it starts one that cannot work.</p>
<p>Each path move is <strong>copy, repoint, verify, delete</strong> — in that order, one app at a time. The old entry is removed only after the new path has been read by a running pod, because a secret that exists at neither path is an outage and a secret that exists at both is merely untidy.</p>
<p>Two rules learned from the first attempt, which read cloud&#x27;s embedded store by mistake and would have destroyed live credentials:</p>
<p><strong>A read that returns nothing STOPS the move.</strong> Never write what a read did not return. An empty read followed by a write of that empty value, then a read-back comparing empty to empty, reports success for a migration that moved nothing — and the delete that follows then removes the only real copy. <code>admin-guard</code> gates SuperAdmin admission to every raw admin surface; that sequence would have left it booting with no <code>GUARD_HMAC_KEY</code>.</p>
<p><strong>Absence must be proven against the deployment the chart reads, by an unfiltered listing.</strong> A path-filtered list returning <code>total: 0</code> is not evidence: the same token that reported zero for <code>/orgs/hanzo</code> returned five secrets when listed unfiltered. Absence is only established by enumerating the store the chart actually reads.</p>
<p>An omitted <code>keys</code> list pulls the whole path, which is a different request from an empty list rather than a shorthand for one, and stays that way. <code>base</code> is the one service that makes it — reading the root of its own project — and neither the list nor the project moves.</p>
<p>The one KMS reference in Go — <code>apps/platform/pin.go</code>&#x27;s <code>orgs/hanzo/deploy/UNIVERSE_PIN_TOKEN@prod</code> — already has this shape. <code>deploy</code> is a purpose rather than an app, which is the one standing exception: nothing reads it but the release pipeline, which is not a deployed app. It stays until the pipeline is one.</p>
<h2>Security Considerations</h2>
<p>Nothing here changes what a secret is protected by; it changes where it is found. Three properties are worth stating.</p>
<p><strong>The isolation HIP-0027 wanted is still missing, and this HIP does not add it.</strong> One project per org means one machine identity per namespace — <code>hanzo-platform-iam-creds</code> in <code>hanzo</code> — so every app in that namespace can read every path in that project. <code>secretsPath</code> organizes; it does not authorize. A compromised app reads its neighbours&#x27; credentials, which is exactly what project-per-service was meant to prevent.</p>
<p>Making the path derivable does not widen that: any app could already read any path, whether or not it could guess the name, and a convention nobody follows is not a control. But it should be recorded plainly that the boundary is the <strong>namespace&#x27;s credential</strong>, not the path, and that closing the gap means one machine identity per app — a change to identity topology, deliberately out of scope here.</p>
<p><strong>A path reveals its consumer.</strong> <code>hanzo/gateway/STRIPE_SECRET_KEY@prod</code> says gateway holds a Stripe key. That is already true of the running deployment and of its values file, so the path adds no exposure — and it makes an over-broad grant visible instead of buried.</p>
<p><strong>One entry, one rotation.</strong> A credential copied to two paths rotates at one and not the other, and the failure appears at whichever consumer was not rotated, which is not the one that was changed. Sharing an entry makes rotation atomic.</p>
<p>Charts continue to carry references and never values. <code>templates/kmssecret.yaml</code> has no <code>stringData</code> escape hatch, on purpose; this HIP does not add one.</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-0136.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>