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

268 lines
22 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>hip-1048</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-1048.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/hip-1048">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/hip-1048.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-1048</h1><p class="lede">HIP-1048: Team. Status Final. Hanzo architectural specification.</p><h1>HIP-1048: Team</h1>
<h2>Abstract</h2>
<p><code>/v1/team</code> is the shared workspace: the login and membership control plane, the live document plane clients connect to, the workspace file store, and the roster that includes an organization&#x27;s agents. It is served by <code>apps/team</code> in <code>hanzoai/cloud</code>.</p>
<p>Its identity domain membership is not a filing accident. The thing this capability actually owns is WHO IS IN A WORKSPACE — the rows that authorize every other plane under this address — and the org each workspace belongs to.</p>
<h2>Motivation</h2>
<p>A workspace surface accretes credentials: it has its own sessions, its own tokens, its own idea of who a member is. Every one of those is a second identity system, and a second identity system is a second place a member can be admitted after the first one revoked them.</p>
<p>So there is ONE identity seam here, one answer to &quot;who is calling and what may they touch&quot;, shared by every surface under the address (<code>apps/team/account.go:943</code>). No surface reads a claim off a credential for itself, and therefore no surface can disagree with another about who is calling.</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. Tenancy is a column, enforced on every query</h3>
<p>A workspace belongs to exactly one org, and that org is a column on the row. Every read and every write MUST be scoped to the caller&#x27;s VERIFIED org (<code>apps/team/account_store.go:32</code>, <code>:65</code>). Composite uniqueness is on <code>(org, slug)</code> and <code>(workspace, user)</code>, so two orgs may hold the same workspace name and neither can address the other&#x27;s.</p>
<p>The membership rows ARE the authorization. On the identity lane nothing about a workspace is signed, so what a caller may touch is decided per request against those rows and never by a claim the caller carries (<code>apps/team/account.go:971-975</code>).</p>
<h3>2. Two lanes, and one of them carries no credential out</h3>
<p>A caller resolves either from a verified identity token — narrowed to this deployment&#x27;s own audience — or from a token this service minted itself.</p>
<p>On the identity lane the credential MUST NOT leave the resolution: the session RPC echoes a token back to page script, and an identity access token is an estate-wide bearer that reaches every other service. The login flow puts it in an HttpOnly cookie precisely so script cannot read it; echoing it would hand it back to the script the flag exists to keep it from. The lane therefore carries no credential out at all, structurally, so a future echo site cannot reintroduce the leak by forgetting (<code>apps/team/account.go:976-992</code>).</p>
<p>The minted arm exists because one read still answers for &quot;the workspace the credential pins&quot;, and the identity lane pins none. Removing it is a client change: the client names the workspace and the server authorizes it against the rows, the way the document and file planes already do.</p>
<h3>3. No signing secret means health only</h3>
<p>When the signing secret is unset or is the public default, the subsystem serves HEALTH ONLY: every route under the address answers 503 and NO token is ever decoded or accepted (<code>apps/team/team.go:293</code>). A forged token cannot be used because nothing verifies one.</p>
<p>Mount MUST still SUCCEED. Erroring at mount fails the whole composition and takes every other subsystem in the binary down with it; refusing at the route is the same safety with none of the blast radius.</p>
<p>The refusal MUST be applied per route and MUST NOT wrap the liveness probe. A prefix-wide middleware risks catching it, and a degraded subsystem that also reports itself dead cannot be diagnosed.</p>
<h3>4. The file plane repeats the boundary physically</h3>
<p>A workspace blob&#x27;s key embeds org, workspace and blob id (<code>apps/team/files.go:289</code>), so an identifier from another org or another workspace does not resolve. The caller MUST additionally be asserted a MEMBER of the named workspace — not merely same-org — before anything is stored or served, and every denial is a 404, so the plane is neither a membership oracle nor an existence oracle.</p>
<p>Three independent layers for one property is deliberate: the verified org, the membership assertion, and the key shape.</p>
<h3>5. Login&#x27;s billing check fails open, and says so</h3>
<p>The single chokepoint every client passes on its way into a workspace asks whether the org&#x27;s plan licenses this product. Two kinds of &quot;no&quot; are distinguished (<code>apps/team/entitle.go</code>):</p>
<ul><li>Cannot verify — an infrastructure absence — ADMITS. A login gate that fails</li></ul>
<p> closed during an outage bricks every session mid-rollout.</p>
<ul><li>A definitive &quot;no entitlement&quot; currently OBSERVES: it logs the denial and</li></ul>
<p> admits, because self-serve checkout does not exist yet and refusing sends a person to a dead end. Enforcement returns when the self-serve path ships.</p>
<p>This is stated in the specification rather than left in a comment because it is a live posture with a date-stamped reason, and a reader MUST NOT assume the presence of a gate implies enforcement.</p>
<h3>6. Agent replies are off unless an operator opts in</h3>
<p>The workspace&#x27;s automated responder is DISABLED by default, and the model seam is wired only when explicitly enabled (<code>apps/team/team.go:113-119</code>). An unconfigured or misconfigured binary is provably inert: with no responder wired, no outbound model call can fire.</p>
<h3>7. The document plane&#x27;s wire is fixed</h3>
<p>The live document transport carries one message per frame in the platform&#x27;s own envelope, negotiates a text encoding, and pins the model version it reports. It is a data plane over an already-resolved caller, and it MUST NOT re-derive identity of its own.</p>
<h3>8. Addresses, and which operations cannot be values</h3>
<p>The capability answers at two prefixes, and the second is deliberate: <code>/v1/team</code> — the control plane, bots, files, billing reads and the transactor endpoint — and <code>/collaborator</code>, the live document lane, app-level because the front derives its WebSocket address from an origin, not from the <code>/v1/team</code> base (<code>manifest/apps.go:339-346</code>). Operations are typed by default; the closed exception list names each one that cannot be a value, with its wire fact — the two WebSocket upgrades, the account plane&#x27;s JSON-RPC envelope, the cookie write whose unparseable body is ignored rather than 400&#x27;d, the two browser redirects, the embedded billing page&#x27;s bytes, and the file plane&#x27;s multipart-in and raw-bytes-out (<code>apps/team/typed_wire_test.go:152-178</code>).</p>
<h3>9. Store, money, events, stage, upstreams</h3>
<p>The store this capability owns is the workspace store §1 describes: one encrypted SQLite file for the deployment (<code>cek.Open(namespace.System(), &quot;account&quot;, dir)</code>, <code>apps/team/account_store.go:83</code>), org isolation the column §1 states, holding workspaces, memberships and the roster — plus the workspace blob store §4 bounds. It is FREE: no meter, no debit through any plane (<code>plugin/team/main.go</code>, <code>Price: cloud.Free</code>); §5&#x27;s login check is a licence read, not a meter. It publishes no event, so a customer&#x27;s webhooks receive nothing from it, and it emits nothing to observability beyond the request span every route already gets. Its stage is <code>ga</code>.</p>
<p>It derives from no forked upstream. The live lane SPEAKS the Y.js sync protocol — the server is a relay and update log, not an embedded CRDT engine (<code>apps/team/collabws.go:13</code>) — and the document contract is the one the Team front&#x27;s own collaborator client states (<code>apps/team/collab.go:3-7</code>).</p>
<h2>Rationale</h2>
<p>Membership could be read from a signed claim in the workspace token, which is faster and needs no store lookup. It is also stale by construction: a member removed from a workspace keeps their claim until it expires. Rows read per request cost a query and revoke immediately.</p>
<p>Holding one file for the deployment rather than one per workspace keeps a single writer and lets the org column carry isolation. The store is encrypted at rest by a handle the caller opens, rather than by the object mapper opening its own — the mapper&#x27;s own configuration carries no master key, so letting it open the file would write every workspace, membership and display name as plaintext (<code>apps/team/account_store.go:43-49</code>).</p>
<h2>Security Considerations</h2>
<p>The identity lane&#x27;s no-echo rule is the sharpest edge here: one unauthenticated- looking RPC that returned the caller&#x27;s identity token would put an estate-wide bearer into page script. The property is structural — the lane&#x27;s credential field is empty by construction — and MUST stay structural rather than becoming a rule each new surface remembers.</p>
<p>The degraded posture is a security feature, not an outage behaviour: without a real secret, accepting a token is accepting a forgery, so the subsystem refuses to decode one at all.</p>
<p>Tenant isolation rests on the verified org, never on a client-supplied header, and is repeated in the key shape of the file plane so a single missed predicate is not a cross-tenant read. Every denial across these planes is the same 404 for the same reason: a distinguishable refusal is an oracle for what exists and who belongs.</p>
<h2>References</h2>
<ul><li>HIP-0026 — Identity &amp; Access Management Standard</li><li>HIP-0106 — The Hanzo Plugin Contract</li><li>HIP-0519 — One Identity Boundary</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-1048.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>