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

274 lines
27 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>hip-1180</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-1180.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/hip-1180">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/hip-1180.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-1180</h1><p class="lede">HIP-1180: Link — A Record of Provider Accounts. Status Final. Hanzo architectural specification.</p><h1>HIP-1180: Link — A Record of Provider Accounts</h1>
<h2>Abstract</h2>
<p><code>link</code> is the unified AI login manager&#x27;s registry: the org+user-scoped record of WHICH provider accounts — Claude Max, ChatGPT Plus, a Hanzo API key, a raw provider key — a developer has signed into, ON WHICH MACHINES, with each account&#x27;s latest usage snapshot. It answers at <code>/v1/link</code>. It holds no credential: the secret stays sealed where the connections plane put it, and this capability holds the binding and the numbers. It is implemented in <code>hanzoai/cloud</code> at <code>apps/link</code> (HIP-0106).</p>
<h2>Motivation</h2>
<p>A developer signs into Claude on a laptop, into ChatGPT on a desktop, and points a Hanzo key at both. No machine can answer &quot;which accounts do I have, where, and how much of each plan is left&quot; — each login knows only itself, and a plan&#x27;s remaining percentage is a number no Hanzo request produced, so no gateway ledger holds it either. One registry makes that a read, and makes failover across those accounts an ordered list a customer can inspect before a request is dialled.</p>
<h2>Specification</h2>
<p>The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are to be interpreted as in RFC 2119.</p>
<h3>§1 The atom, and the stores it owns</h3>
<p>The atom is a Link: one <code>(user, device, provider, account)</code> binding plus its kind, status, last-seen and latest usage snapshot. A device is the <code>(machine, host, os)</code> projection shared by a machine&#x27;s Links, not a stored entity of its own — so there is no device-to-link join and no orphan device to collect (<code>apps/link/link.go:1-12</code>).</p>
<p>The durable store is ONE encrypted SQLite file, the deployment&#x27;s own <code>link</code>, opened through the one opener so it is born encrypted and comes back with the single-connection cap already applied (<code>apps/link/store.go:39-42</code>). It carries two tables whose meanings never mix. <code>link</code> holds one row per binding under the natural key <code>(org, subject, machine, provider, account)</code>, so a re-registration UPSERTs the row that already exists and reads back the id it was first given (<code>apps/link/store.go:113-135</code>). <code>routed_usage</code> is an additive counter keyed on <code>(org, subject, provider, account)</code> — what this gateway routed through an account, in exact per-request deltas, transactionally added (<code>apps/link/routed.go:1-30</code>).</p>
<p>Beside them this capability owns one warehouse series: <code>hanzo.account_usage</code> and its daily rollup in the datastore, a <code>ReplacingMergeTree(ts)</code> whose order-by IS the dedup key, because a device collector re-reports the SAME window as it fills and those reports are one fact observed twice rather than two facts (<code>apps/link/datastore.go:38-52</code>). The series is history; the Link row is the durable truth. Every read and write against the series MUST degrade — a write to a no-op, a read to an honest &quot;unavailable&quot; — when the datastore is absent, and MUST NOT answer a fabricated zero, which reads as truth and is worse than an outage.</p>
<p>NO SECRET LIVES HERE, and the store&#x27;s shape is what makes that structural: there is no column for one. A provider&#x27;s OAuth token or API key stays where the connections plane sealed it, and the device collector registers a Link and pushes its usage with the SAME IAM bearer it already carries — never a provider secret.</p>
<h3>§2 The addresses</h3>
<p>Eleven operations under <code>/v1/link</code>, every one typed: each is a <code>zip</code> typed op with a named In and Out, so the REST route, the served document, the MCP tool, the CLI command and every generated client project from one registration (<code>apps/link/http.go:125-142</code>). None is declared-and-untyped — this capability holds no route whose shape it cannot name.</p>
<p>| operation | what it answers | |---|---| | <code>POST /v1/link</code> | registers a signed-in provider account on a machine → the Link (201) | | <code>GET /v1/link</code> | the caller&#x27;s linked accounts and the devices they sit on | | <code>GET /v1/link/{id}</code> | one linked account | | <code>DELETE /v1/link/{id}</code> | logs out one account and stops the sessions it was running | | <code>GET /v1/link/devices/{machine}</code> | one machine: its accounts, usage and live sessions | | <code>POST /v1/link/devices/{machine}/revoke</code> | logs out every account on one machine and stops its sessions | | <code>GET /v1/link/route</code> | the failover order across the caller&#x27;s accounts (§4) | | <code>POST /v1/link/usage</code> | usage samples from the device collector (202) | | <code>GET /v1/link/usage</code> | one provider account&#x27;s own usage dashboard | | <code>GET /v1/link/usage/accounts</code> | what the gateway routed through each account | | <code>GET /v1/link/usage/summary</code> | plan consumption and Hanzo spend, side by side |</p>
<p>The summary is the point of the usage plane, and it carries a labelling rule. &quot;My Claude Max plan&quot; and &quot;what I spend through Hanzo&quot; come from different meters with different meanings, so every row MUST be labelled by source, by scope and by confidence, and the two MUST NOT be summed: a plan&#x27;s percentage is not money, and a provider&#x27;s own spend is not a Hanzo charge (<code>apps/link/usage.go:15-27</code>). Both halves of that board resolve their window through ONE resolver over a closed set of range labels, so the account rows and the Hanzo rows always cover the same period; an unknown label is an error, never a silent substitution.</p>
<p>Registration order is load-bearing and fixed: the literals <code>route</code>, <code>usage</code> and <code>devices</code> are declared before <code>:id</code>, because the router matches in registration order and the parameter would otherwise swallow them.</p>
<h3>§3 Tenancy</h3>
<p>The tenant is the PAIR <code>(org, subject)</code>. The org is the validated IAM owner claim the identity boundary parked (HIP-0026); the subject is the validated user on the same request. One gate resolves both, and a caller with no validated principal, an empty org, or a call arriving off the HTTP path with no attested caller is refused with 403 — the same answer an anonymous REST call gets, fail-closed, one gate rather than two (<code>apps/link/http.go:44-60</code>).</p>
<p>Every statement in the store leads with <code>org = ? AND subject = ?</code> as bound parameters. Neither half is ever a request field. Within one org a colleague&#x27;s accounts are invisible, because the subject is part of the key and not a filter somebody could widen.</p>
<h3>§4 Route is a policy, not a dial</h3>
<p><code>GET /v1/link/route</code> returns the ordered candidate list a caller fails over along — two subscriptions for redundancy, then the metered API as the always-available backstop. Each candidate carries provider, account, plan, kind, billing mode, availability and remaining rate-limit headroom, so a caller knows how a candidate BILLS before it dials it (<code>apps/link/route.go:20-45</code>). The policy is a total function of the caller&#x27;s Links and the snapshots already on them, never a live provider probe, so the plan is reproducible and provable in a unit test.</p>
<p>Execution — dialling a provider, seeing a 429, advancing to the next candidate — belongs to the gateway. The resolved credential rides the request context as a PROCESS-LOCAL value and MUST NOT be serialized: not a header, not a body, not argv, not an error, not a log line. The provider egress reads it at the instant it dials and discards it (<code>apps/link/carrier.go:1-9</code>). Crossing a process boundary with it is out of scope by construction, which is what makes &quot;a credential lives only in memory&quot; mechanical rather than a promise.</p>
<p>Per-request selection carries only <code>(provider, profile)</code>. A Selection has no org field and no subject field, by construction — those come solely from the validated principal at the router boundary — so the worst a hostile selector achieves is naming an account the caller does not have, which resolves to unavailable (<code>apps/link/select.go:5-11</code>).</p>
<h3>§5 Money</h3>
<p>The surface is free. The plugin declares <code>cloud.Free</code> (<code>plugin/link/main.go</code>), and the registry holds no metering client at all, which makes it structurally incapable of creating a charge (<code>apps/link/store.go:21-30</code>).</p>
<p>What bills is the routed call, and the Link&#x27;s own billing mode decides. A subscription account&#x27;s inference is paid by the developer&#x27;s plan with the provider directly: it is metered here for VISIBILITY and MUST NOT be charged. An api-key account&#x27;s routed call debits the metering spine under the provider label <code>ai</code> — the same label every other inference debit carries, so routed spend sums into the org&#x27;s <code>ai</code> scope like any other. The retail price is injected rather than computed here, and the default charges nothing: the customer already paid the provider on their own key, so absent an operator-set fee the usage is recorded and no charge is invented (<code>apps/link/meter.go:29-45</code>). A routed call is therefore metered exactly once per meaning and never charged twice. The meter is handed the account IDENTITY, the kind and the served token counts — never the credential, so no metering path can observe a secret.</p>
<h3>§6 Events and observability</h3>
<p>It publishes nothing on the bus. A customer&#x27;s webhooks at <code>/v1/webhook</code> receive no <code>link.*</code> event.</p>
<p>Beyond the request span every route gets, it emits structured log lines only: one per served routed call, one warning per failover attempt naming the org, the account and the reason, and one warning when a revoke&#x27;s session stop fails. The last carries a rule: a stop failure MUST NOT fail the revoke, because the row is already revoked and the row is the durable truth (<code>apps/link/http.go:590-602</code>). It writes no audit record; the evidence a revoke leaves is the row itself, which is retained with status <code>revoked</code> rather than deleted, so the account&#x27;s usage history survives a log-out.</p>
<h3>§7 Stage</h3>
<p><code>beta</code>. The manifest row declares <code>Stage: Beta</code> (<code>manifest/apps.go:172</code>), so the capability is reached by flag (HIP-0139 §8). It is the self-service cloud&#x27;s answer to &quot;which AI accounts do I have&quot;, which the console renders on first load, so <code>ga</code> is where it is headed; the promotion is the one manifest edit HIP-0139 §8.4 names.</p>
<h3>§8 Upstream</h3>
<p>It derives from no upstream project: nothing here is forked, embedded or mirrored. Persistence links <code>github.com/hanzoai/sqlite</code> (MIT / Apache-2.0 dual), the one SQLite driver cloud links. Provider identifiers match the ids the Hanzo usage collector registers, by value — a shared vocabulary, not shared code.</p>
<h3>§9 Boundary</h3>
<p>The neighbour to confuse this with is <code>billing</code>, and the split is usage versus money.</p>
<ul><li><strong>billing</strong> is the ORG&#x27;s money endpoint — balance, spend, cards. <code>link</code> is the</li></ul>
<p> PERSON&#x27;s account endpoint — which providers they signed into and what those accounts consumed. <code>GET /v1/billing/usage/accounts</code> is billing&#x27;s address and reads this capability&#x27;s per-account breakdown at the same <code>(org, subject)</code> pair: the shape is link&#x27;s, the address is billing&#x27;s, and the charge of record is commerce&#x27;s ledger and never a counter here. A number under <code>/v1/link</code> is USAGE; a number under <code>/v1/billing</code> is MONEY; they MUST NOT be added.</p>
<ul><li><strong>iam</strong> (HIP-0026) is who the caller is at Hanzo, and the only thing that</li></ul>
<p> authenticates anyone. <code>link</code> is who the caller is at somebody ELSE, and it authenticates nobody. A row here grants access to nothing, here or upstream.</p>
<ul><li><strong>The connections plane</strong> (<code>/v1/ai/connections/{provider}</code>) owns a linked</li></ul>
<p> account&#x27;s LIFECYCLE: the authorization dance, sealing the secret per org, and refreshing a token before it expires. This capability only READS — given an account, resolve the current sealed credential for one dial. Storage, sealing and refresh belong there; selection, ordering and metering belong here, which is why a secret has no home in this store (<code>apps/link/resolver.go:5-11</code>).</p>
<ul><li><strong>The gateway.</strong> <code>/v1/link/route</code> publishes the ORDER; <code>/v1/chat/completions</code></li></ul>
<p> dials. A capability that both chose and dialled would make the choice unobservable, and the choice is the half a customer needs to audit before it costs them anything.</p>
<h2>Rationale</h2>
<p>The alternative to a registry is asking each machine. That answers only for the machine that is awake, cannot order a failover across two of them, and turns &quot;what did I spend where&quot; into a question with as many answers as devices. The alternative to keeping the credential out is one store holding both the map and the keys, which upgrades a metadata leak into a provider-account takeover. The alternative to a policy address is failover buried in the gateway with no address at all: the order becomes an implementation detail nobody can read back, on a decision that moves money.</p>
<p>Three ledgers sit in this design and none is allowed to absorb another: the collector&#x27;s plan snapshots, the gateway&#x27;s routed deltas, and commerce&#x27;s charge of record. Their engines differ because their shapes differ — a snapshot is a re-observation to replace, a delta is a quantity to add — and forcing one into the other&#x27;s storage loses counts silently.</p>
<h2>Security Considerations</h2>
<p>The wrong implementation gives an attacker one of three things.</p>
<p>A cross-tenant read is the largest. The registry names every provider account a person holds and how much of each plan is left — a map of a developer&#x27;s whole AI footprint, and a list of exactly which subscriptions to attack elsewhere. The <code>(org, subject)</code> predicate is bound, in the store, on every statement, and both halves come only from the validated principal, so a handler cannot widen it and a request field cannot assert it.</p>
<p>A credential is the one an attacker wants and the one that is not here. No column stores one, no response carries one, and the resolved value exists only as a process-local context value that is read at egress and dropped. The blast radius of a compromised registry is metadata.</p>
<p>A misrouted dial is the subtle one: if a per-request selector could carry a tenant, a caller could route on somebody else&#x27;s account and consume somebody else&#x27;s plan. A Selection carries <code>(provider, profile)</code> and nothing else — closed by construction rather than by validation, so there is no check to forget.</p>
<h2>References</h2>
<ul><li>HIP-0026 — Identity and Access Management</li><li>HIP-0106 — Hanzo Plugin Contract</li><li>HIP-0139 — Capability</li></ul>
<h2>Copyright</h2>
<p>Released under CC0 1.0 Universal Public Domain Dedication.</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-1180.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>