A wallet is a free key, so headless web3 sign-up minted one free account per key without limit. Cap counts account creations, never sign-ins, per client address and per IPv4 /24 or IPv6 /64 in a window: default 10 and 50 per 24h, set by IAM_WALLET_CAP_IP, IAM_WALLET_CAP_SUBNET and IAM_WALLET_CAP_WINDOW (0 = off). The count is the wallet-signup audit ledger, read and written in the account's own transaction, so a refusal writes no row and concurrent creations cannot share a count. Past a bound: 429, Retry-After, code wallet_signup_capped and the bound in data. The client address is httpx.Client, the identifier throttle's rule moved so both read one: CF-Connecting-IP, else the last X-Forwarded-For hop.
96 KiB
LLM.md — hanzoai/iam
Canonical Hanzo IAM service: identity & access for the Hanzo cloud —
OpenID Connect / OAuth2 with PKCE, JWKS, UserInfo, SCIM 2.0, MFA/WebAuthn,
social federation. The server behind the @hanzo/iam SDK. A clean-room
rewrite on the Hanzo stack (zip over hanzoai/orm) — no Casdoor,
Beego, or xorm. The retired Casdoor fork is hanzoai/iam-v1 (archived, do not use);
its versions are retracted here — see TestCasdoorLineageRetracted.
License — MIT OR Apache-2.0
Dual-licensed at the user's option: LICENSE-MIT + LICENSE-APACHE (canonical
texts, never edited), LICENSE declares the pair. HIP-0130 puts iam in the OSS
core tier, so the previous "confidential and proprietary / All rights reserved"
LICENSE contradicted both the HIP and the repo's own public visibility. Every Go
file carries // SPDX-License-Identifier: MIT OR Apache-2.0 instead of the old
All rights reserved header; go.mod has no license field, and this repo ships
no Cargo/npm/PyPI manifest, so the SPDX headers plus the three files are the
whole declaration.
Relicensing was Hanzo's alone to do: the tree is original work, not a fork
(fork: false, its root commit is its own, and no v1.* Casdoor tag is an
ancestor of main). Note the Casdoor-lineage tags v1.0.0–v1.31.37 are still
present on this remote even though go.mod says they "now live at
hanzoai/iam-v1" — anyone checking out one of those tags gets Apache-2.0
Casdoor code under this repo's name. The retraction covers module resolution,
not git checkout.
Role in the model
This is a hanzoai/<product> service (impl lives here, DRY — one place). It is
NOT a language SDK. Clients authenticate via the @hanzo/iam SDK, never by
hand-rolling OAuth. Full SDK model: ~/work/hanzo/SDK-ARCHITECTURE.md.
Build & run
go build ./...go run . serve --init-data init_data.json(SQLite default;--store sqlite|sql|datastore)go run . compare --legacy postgres://…/iam(needs-tags migration)- Image:
ghcr.io/hanzoai/iam. Go 1.26.
Embedding — a host GRAFTS the app, it does not adapt a handler
Two entry points, and they are different verbs for different situations:
| call | what it does | when |
|---|---|---|
server.NewApp(db) *zip.App |
the whole IAM surface as a self-contained app | a host composing IAM in process: app.Graft(iamserver.NewApp(db)) |
server.Route(app, db) |
registers IAM's routes ONTO the host's app | only when the host genuinely wants IAM's routes co-mingled with its own. It also brings IAM's root-level routes onto the host, which is what shadowed a host console once |
server.Handler(db) http.Handler is deleted (was: adaptor.FiberApp(NewApp(db).Fiber())).
It existed so a host could hang the whole surface on one wildcard —
app.All("/v1/iam/*", zip.AdaptNetHTTP(iamserver.Handler(db))) — and that
adapter is where IAM's knowledge died. AdaptNetHTTP takes an http.Handler
and returns a closure, so the App went in and a bare function came out, and
IAM's 94 typed ops went with it. hanzoai/cloud published five wildcard path
keys and 35 placeholder operations where 78 real paths and 94 typed operations
were — no schema, no MCP tool, no CLI command, no SDK method for any of them.
zip.Graft (zip v1.18.16) is the composition that keeps them: the host's router
learns IAM's route patterns AND its op registry, while IAM's own router keeps
IAM's behaviour — its Use(authz.Guard) seam, its error handler, its config.
Serving is unchanged and strictly cheaper (no net/http round trip). IAM's
Authorizer still runs on IAM's ops; the host never re-authorizes them under
its own rules. Named types are published as iam.<Type>, because a composed
document carries more than one app's Application.
Liveness is not IAM's. /healthz, /readyz and /metrics are zip's ops
surface (HIP-0119 §1) — a SECOND listener the DEPLOYMENT brings up when it names
OPS_PORT, never the public one. IAM used to register /healthz on its public
group; that was hand-rolling a path the framework owns, on the wrong listener,
and it is also what made IAM un-composable: a host registers /healthz as the
HOST's, because it must answer while every subsystem is still cold. Two
claimants on one liveness address is what once served {"binary":"iam2"} out of
a shared binary.
Endpoints (HIP-0111 — /v1 only, no /api, no vendor verbs)
/.well-known/openid-configuration · /v1/iam/.well-known/jwks ·
/v1/iam/oauth/{authorize,token,introspect,revoke,userinfo,logout,callback} ·
/v1/iam/oauth/device + /v1/iam/oauth/device/info (RFC 8628; info names the
client a pending user_code belongs to, session-gated, code in the BODY because
a request line reaches access logs) · /v1/iam/scim/v2/Users. PKCE S256 always; client_id = <org>-<app>.
Authorize bounds every parameter it reads (paramLimits: state 1 KiB, nonce 512 B,
scope, resource and redirect_uri 2 KiB) and refuses one past its bound in place.
Brands set serverUrl: hanzo→iam.hanzo.ai, lux→lux.id, zoo→zoo.id,
bootnode→id.bootno.de, pars→pars.id (white-label by domain).
Sign-in origins — where a person signs in, apart from the issuer
iss is what a relying party pins; the sign-in origin is the address a person
sees: the authorize hop, the IdP callback and /login/mfa. Google shows the
callback's domain until its brand is verified, which is why hanzo.ai's Google
button said "to continue to hanzo.id". IAM_FEDERATION_ORIGIN_MAP (internal/oidc/issuer.go)
names hosts that sign in somewhere other than their issuer:
IAM_FEDERATION_ORIGIN_MAP={"hanzo.ai":"https://hanzo.ai","www.hanzo.ai":"https://hanzo.ai"}
- A named host's authorize is answered in place (or relocated, 307, to its
origin), the binding cookie is set there, the IdP is handed
<origin>/v1/iam/oauth/callback, and tokens still sayiss=https://hanzo.id(TestFederation_SigninHostRunsTheLegAndKeepsTheIssuerredeems on hanzo.ai and fails iftokenIssuerever reads the sign-in origin). - An unnamed host follows its ISSUER host's entry, else its issuer: naming hanzo.id moves iam.hanzo.ai and auth.hanzo.ai with it. Unset is the old behaviour.
- One spelling:
https://host[:port], lowercased, no:443, no path, query, user or fragment.IAM_FEDERATION_ORIGIN(a default) is refused: it moved every brand the map did not name. - Every reachable origin must be terminal. A map that is not is refused at
route registration (
routeFederation), LOGGED, and every host signs in at its issuer; it never stops the process (cloud runsstrategy: Recreate). - Off its issuer's host, authorize never answers silently from a session: that
origin's
__Host-hanzo_sessionis not ended by the issuer's sign-out, so the page asks "continue as" andprompt=noneislogin_required. Cross-origin sign-out (ending hanzo.ai's session from hanzo.id and the reverse) is not built. - The binding, challenge and remember cookies are
__Host-(__Host-hanzo_fed,__Host-hanzo_challenge,__Host-hanzo_mfa_remember), so no sibling of a sign-in origin with siblings (*.hanzo.ai) can plant one. - Every origin in the map must be on the Google OAuth client and the GitHub App
(
hanzo-platform) BEFORE the map ships; each refuses a redirect_uri it lacks. The edge must route the host's/v1/iam/oauth/{authorize,callback,federation/mfa}to IAM (universecharts/app/values/hanzo/cloud.yamliam-signin) and serve/login/mfaand the hosted login (/login/oauth/authorize) as pages. - In cloud,
zip.Ctx.Host()honoursX-Forwarded-Host(TrustProxy, private ranges trusted; the ingress sets it before anapi-hostrewrite), so the "header-immune" wording elsewhere inissuer.go,token.goandwebauthn.gois true ofiam serveonly. A caller can still only select a configured value, for its own requests.
A principal is owner/name — org and USERNAME, on every surface
The rule. owner is the org. name is the USERNAME (<name> of
<owner>/<name>). A display name never appears in name, in a token or in
UserInfo; it has its own claim, displayName. preferred_username is the
OIDC-standard spelling of the same username and is sourced from the same field,
so the two cannot drift.
Why. hanzo auth login files its credential under the token's own
owner/name, so those claims ARE the principal downstream believes it holds.
userClaims computed name = DisplayName, else Name — OIDC's display reading of
name, inherited from the v1 Userinfo struct and present since the in-tree
server was written (73b7ef63e). Measured on iam.hanzo.ai 2026-07-30: a login as
account z minted name: "Grace Hopper" and the CLI filed hanzo/Grace Hopper,
an account that does not exist. cloud's money path had already paid for the same
reading — it addresses a wallet <org>/<username>, addressed hanzo/Grace Hopper
and 402'd every completion while the balance sat in hanzo/z. 5c0ea823f
answered that by ADDING preferred_username and deliberately leaving name
display-sourced, which gave the username a home without evicting the display name
from the claim consumers actually read; the CLI then hit the wall from the other
side. One address for a principal beats two spellings that disagree, so name is
the username and OIDC's display reading of it is the thing we diverge from.
One resolution, one claim builder. Three mint paths — the code/refresh/password
grant, the console's issue-user-token, and the RFC 8693 exchange — had each
SEPARATELY written the DisplayName, else Name fallback, so fixing one would have
left two. identityOf is now the only user→claims resolution and Signer.claims
the only place an Identity becomes a claim set. The values also stopped
travelling as six adjacent positional strings: two of them are human-readable and
were therefore swappable at the call site, they WERE swapped on all three paths,
and it type-checked (the wallet harness had lost a scope into the username slot
the same way). UserInfo answers identically — it and the token describe one
principal, and a client holding either must not get two names for it.
Usernames — one rule, at the write
schema.Username: trim, lowercase, ^[a-z0-9][a-z0-9._-]{0,62}$. Normalization
settles case and padding; everything else is REFUSED rather than rewritten,
because quietly turning what someone typed into a different principal is the
failure being avoided. One character is legal (the account this was written over
is z); a leading digit is legal (nothing resolves a principal numerically).
Ten entry points reach a user row and exactly ONE used to validate the name it
wrote. The rule now lives at users.Create — the choke point six of them share —
plus the three that write through orm directly (bootstrap's first-admin seed, the
wallet identity, the onboarding credential). CreateInput.AuthzTarget normalizes
too, so the pair AUTHORIZED is the pair STORED. Service accounts keep only what is
theirs: <org>- binding and segmentation.
Social signup derives from the ADDRESS, never the profile. schema.Handle
takes the email local part and refuses a string with no @ or a local part with
whitespace — without both, "Grace Hopper" is a local part whose space gets dropped
and the profile name silently becomes the username gracehopper. Dedupe is a
numeric suffix (z, z2, z3), replacing a random 8-hex suffix on every name
that made collisions impossible by making every username unrecognisable.
Case does not make a second person, and stored names are NOT rewritten —
renaming moves real principals. store.GetUserByName resolves exact, then folded,
then over the org for a legacy mixed-case row, and FAILS CLOSED on an ambiguous
fold (the rule GetUserById already applies to a duplicated subject), so whoever
registered "ALICE" alongside "Alice" is never resolved as the other. users.lookup
goes through it rather than repeating the query — restating it is how Create's
uniqueness check stayed case-SENSITIVE while the rule it guards is not.
A read is scoped where it is PRODUCED, never where it is rendered
Two lists answered with an ORGANIZATION's rows a question about a PERSON. Both were reached by a real request in a test before anything was changed, because the reported shape and the measured shape differed:
| list | measured before | now |
|---|---|---|
GET /v1/iam/webauthn-credentials |
plain member 403 — even for their own; org admin ?owner=hanzo → every member's passkey rows; SuperAdmin → every tenant's |
the CALLER's; ?user= needs authority over that account |
GET /v1/iam/memberships?user= |
any colleague sharing the home org learned that person's OTHER tenants | must administer the account (an app keeps its served tenant) |
The webauthn list had both faults at once: it could not serve the one caller
it is for, and it over-served the one it is not. ?owner scoped to a tenant, so
an unnamed target failed the Guard's tenant rule (403 for a member) while a named
one handed an admin the whole org (hanzo.id filtered the other people out IN THE
BROWSER — a page declining to render is not authorization). One scope fixes both
halves: the answer is a PERSON's, the caller is that person unless they say
otherwise and may. /v1/iam/webauthn-credentials is in handlerAuthorizedExact
(exact, so it cannot reach /get, /update, /delete beside it).
?user= on memberships discloses a person's other employers. The roster
question (?org=) does not have that shape — an org's own list discloses only
that org — so only the second one moved. mayReadTenancy: a person must
administer the account (authz.Can(GET, users, …), the authority that already
governs reading their record); an APP keeps its served-tenant bound, because it is
not a colleague but the tenant's own backend, and narrowing it would break an org
switcher without closing anything — the leak is between PEOPLE.
PUT /v1/iam/account — a fixed set, and the set is the gate
The one self-service write on a user row: displayName, avatar, bio,
homepage, each a POINTER so an omitted field PRESERVES and an explicit empty one
CLEARS. The subject is ALWAYS the caller (callerFrom, cookie or bearer) — the
body names no target, so no shape of it writes another account.
It exists because every other writer of a user row is admin-scoped: authz gates
the self clause to GET precisely so a regular user cannot carry isAdmin on a
full-row write, and widening that clause is the escalation it exists to prevent.
Self-service lives here instead, with the fields named one by one.
Absent on purpose: owner/name (renaming moves a real identity), isAdmin and
permissions, passwordHash/accessKey, email/phone — login identifiers
AND second-factor destinations, so changing where a code is delivered is a
credential act that is only safe once the NEW address has proved it can receive
one — and properties, because the consent record nests inside it
(PreferencesKey), so a profile write reaching it would let anyone answer the
data-sharing questions on their own behalf. avatar is schema.AvatarRef: one
rule for how a subject appears, person or organization. An address is added by
PUT /v1/iam/address, below.
PUT /v1/iam/address — a sign-in address, added once a code proved it
{clientId, address, code} → {owner, name, email, phone}. How an account that
began with no address (a wallet, an agent's headless signup at a founding app) is
later signed in to as the SAME account by email or text. Code: internal/oidc/address.go;
tests TestAddress*, wallet end to end TestWalletAccountAddsAPhoneAndSignsInByIt.
- The caller is
callerFrom(cookie or bearer, never one someone acts through); a machine is 403. The application must sign them in: they live in its org or it registered them (store.RegisteredIn), else 403. - The proof is the code
POST /v1/iam/verification-codesfiled for NOBODY under the app's org (applicationId admin/<app>), spent byotp.Prove. - It ADDS, never replaces: the same value again is ok with no code; a different one is 409. Replacing a login address is a separate owner decision.
- An address any OTHER account would be resolved by at that app
(
resolveLoginUser, ambiguity included) is refused BEFORE the code is read, with the wrong-code words, so no caller learns who holds an address. - Email lands normalized and
EmailVerified; a phonestore.NormalizePhoned.schema.ActionAddress(PlatformWritten) is written in the same transaction, object{client, field}, never the address or the code. GET /v1/iam/auth/methodssaysaddress: trueexactly when a sender is bound (otp.DeliveryConfigured), because the add is proved by a code: a screen draws the form only where it can finish, and@hanzo/iam0.21.37 reads it asmethods().address.codesays a code can be sent, by either channel; whether the org's notify holds a text credential is notify's fact (KMSorgs/<org>/notify/twilio/{account-sid,auth-token,from-number}), not IAM's.- CORS:
[bearer], and the preflight now advertises PUT for every browser path.
The phone reach. A founded account works in an org of its own, so the app's
org held its number nowhere: a texted code was filed for nobody. store.GetSignupByPhone
is GetSignupByEmail for numbers; the SMS send falls back to it after the in-org
lookup (two registrations on one number: refused, nothing minted), and
resolveLoginUser asks it for a phone-shaped identifier after the in-org and name
reaches miss, so code sign-in and a code reset find the account.
/v1/iam/auth/identifier still takes email only.
lastSigninTime had no writer, which is worse than having no column
Every row in the estate read empty, and a periodic access review reads this to
find accounts nobody uses — so a dormant-account sweep would have retired the
whole directory. store.RecordSignin is the one writer and sessions.Open the
one caller: that is where a human has just proved themselves, whatever they proved
it with (password, delivered code, passkey, wallet signature, a return from
another IdP all arrive there), so no method has to remember and none can disagree.
Stamped BEFORE the live-session check — the fact is the proof that just happened,
not whether a cookie had to be minted. Best effort: a bookkeeping field never
fails a login. A refused attempt records nothing.
Stepping into a tenant — the actor is never lost
A platform operator supports every tenant and therefore has to see what a tenant sees. Three ops, and none of them is a new way to authenticate:
| op | path | who |
|---|---|---|
listOrganizations |
GET /v1/iam/organizations?q=&limit=&cursor= |
anyone (scope is the caller's) |
assume |
POST /v1/iam/assume {"org":"acme"} |
SuperAdmin |
release |
POST /v1/iam/release |
SuperAdmin |
assume re-scopes; it does not impersonate. sub, owner and name on the
token that comes back are the operator's own, and the tenant is named beside them
in assumed, so every act downstream is attributed to the operator and metering
bills them. release is the same mint with nothing assumed. The application,
audience and signing cert are the presented token's, so the answer replaces that
token. Signing in AS a person exists too, since 2026-10 and by owner decision, as
a separate act with its own marks: see "Impersonation" below.
The tenant is reached through the switch that already exists. The assumed org
joins orgs, which is the set a resource server already reads to admit
X-Org-Id. No consumer learns a second mechanism.
It is a LABEL, not a sandbox — say so. An operator keeps the authority they
already held. Principal.Sudo is resolved from the user ROW, never from a token
claim, so a claim cannot withdraw it here; making the token claim otherwise would
be two answers to one question, and the weaker one would be a control we do not
actually enforce.
ONE predicate — schema.User.SuperAdmin (see "SuperAdmin" below). A per-org
IsAdmin is a different, org-scoped fact, and a membership of admin is not
SuperAdmin either; reading either would let the admin of one tenant step into
every other, and that is the whole escalation these endpoints would otherwise be.
Pinned: TestAssume_orgAdminRefused, TestAssume_regularUserRefused.
The collection answers one question with one shape — "which organizations may
I act in" — so a client never branches on who it is talking to: a person gets
their memberships, an operator gets every org. Own organizations first (the common case
needs no typing), then the rest newest-first, q matched server-side against name
and display name, an opaque keyset cursor for the rest. The full tenant list never
reaches a browser. A query only NARROWS what is already the caller's: it can never
widen scope. A narrowing q is a filter on the collection, not a second address:
same rows, same order, same scope, so an address per filter would be one URL per
question about one collection. /v1/iam/organizations is in
authz.handlerAuthorizedExact because it names no target — an empty target fails
the tenant rule, which would deny every non-SuperAdmin the list of their own orgs
— so the handler scopes itself, which is also what makes the answer the same one
over the MCP server. Exact, not a prefix, so it reaches the collection and never
an item under it.
Every privileged act is recorded, refusals included — a refused attempt to
step into a tenant is the row an auditor most wants. schema.AuditLog carries the
real actor (user), the org (organization), the time (createdTime) and the
address (clientIp, from X-Forwarded-For); the row is filed under the org
stepped INTO so that tenant sees who was in it. ActionAssumeOrg /
ActionReleaseOrg are schema.PlatformWritten, so the generic audit-log CRUD
refuses to create, alter or delete one. Query it at
GET /v1/iam/audit-logs?owner=<org> (indexed on organization, user, action,
createdTime).
A membership grant or revoke (POST /v1/iam/memberships, /v1/iam/delete-membership)
writes ActionMembershipGrant / ActionMembershipRevoke in the same transaction as
the row, filed under the org it changes: actor, client IP, and object
{user, org, role, added|removed}. A repeated grant is recorded with added:false;
a refused one writes nothing. Both actions are PlatformWritten.
SuperAdmin — one predicate, on the row
schema.User.SuperAdmin: a PERSON (!Machine()) whose row's owner is
admin. Nothing else answers it. The Guard sets Principal.Sudo from it when it
loads the caller's row, and every gate reads p.Sudo or asks the row directly
(assume/release, device approval across tenants, unlink, bootstrap's
credential freeze, the registry push gate). authz.Claims.Sudo is the same rule
read off a token: its home org is orgs[0], which store.MemberOrgRefs opens
with the row's owner, so the row and every token minted from it agree. The
token shape is unchanged; the owner claim is the minting app's org and decides
nothing.
- A membership of
adminconfers nothing. Not Sudo, and notMemberOf/AdminOf("admin")either (hanzoai/authz ≥ v1.10.42), so a brand org's user added to it neither reads nor edits the admin org's registry row.hanzo/zwith an admin membership is an ordinary hanzo account;admin/zis the operator. - An org name is canonical, and nothing folds onto
admin.schema.OrgName(lowercase letters, digits, inner hyphens, 2-55) is asked by every write that files a principal under an org: an organization (organizations.Create), an account (users.Create, the choke point signup, federation, SCIM and the CRUD share), a service account, and the org an application serves. A non-canonical name is refused, never lowercased — lowercasing "Admin" would make it the reserved org. Probed live 2026-10-19 (a throwaway user and org, deleted after): no person, org admin or onboarding path could found or sign in to an org spelledAdmin/ADMIN/aDmin/admiN(onboarding slugifies, the CRUD refuses the shape, sign-in resolves the org verbatim), but a SuperAdmin'sPOST /v1/iam/usersstoredAdmin/<name>andac/me/<name>— accounts in orgs that do not exist, the first of which a case-folding consumer (commerce, then) read as SuperAdmin. Census at the fix: 563 orgs, 506 account owners, all canonical; one leftover QA application serves[email protected]. - A machine in
adminis never SuperAdmin —User.Typeservice-account or application.admin/provisioneris declaredtype: servicein universe's provision document but the upsert writes it with no machine class, so it is a person here and keeps platform authority. Stamping a class on it would end its converge. - The admin org is wider than SuperAdmin on two protective gates, on
purpose:
store.SuperAdminKey(no secret key names any account inadmin, machines included, nor a name nobody holds yet) andusers.Authorize(only a SuperAdmin writes an account inadmin). Both read the owner as written; resolving a name folds its case and never its org. groupsis membership, not SuperAdmin. The claim still lists every org a person belongs to, soadminappears for a brand org's member of it. Two relying parties read it as platform authority: the forge (--admin-group admin, universehanzo-git.yaml) and Hanzo CD (hanzocd-rbac-cm.yaml). Moving them toorgs[0]needs the SuperAdmin to sign in through an app that serves the admin org — reserved-org confinement refuses the brand apps.- Provisioning is
POST /v1/iam/admin/users/upsertwithowner: admin— a named person declared IN the admin org. Nothing promotes from a brand org. - Audit. Every request the Guard admits for a SuperAdmin is one
schema.ActionSuperAdminrow (method, URI with query, status, client IP, actor), filed underadmin; so are a SuperAdmin's unlink of someone else's sign-in method and a device approval into another org. The action isPlatformWritten: the audit-log CRUD cannot create, alter or delete it. assume/release/list-organizations/impersonate keep their own rows.
Impersonation — support signs in AS the person, and every token says so
The owner overrode "nobody is impersonated" for one capability: from
admin.hanzo.ai a SuperAdmin opens hanzo.ai or platform.hanzo.ai as a customer to
reproduce their problem. The token is the person's and only the person's, it names
the operator, and nothing it touches outlives fifteen minutes. Code:
internal/oidc/impersonate.go; tests TestImpersonate_*.
Flow — authorize + token as written; no token ever reaches the operator:
POST /v1/iam/impersonate{"target":"<owner>/<name>","reason":"…","clientId":"…"},Authorization: Bearer <the operator's own sign-in token>,X-Forwarded-For: <operator ip>→{"status":"ok","data":{"loginHint":"impersonation:<id>","clientId","target","expiresIn":300,"ttl":900}}. The hint is aLoginChallengeofKindImpersonate: single-use, 5 minutes, subject = target, payload = operator + client + reason.- The site's OIDC Core §4 initiate-login endpoint gets
iss+login_hintand starts its OWN authorization request (its state, nonce, PKCE S256) carrying thatlogin_hint. authorizeanswers theimpersonation:prefix itself and never falls through to a login page. It burns the hint first — any presentation is its only one — then requires a top-level navigation, a PKCE challenge, the hint's own client, and the OPERATOR's session cookie on that browser (a leaked hint is inert). It re-asks the rule and mints the code throughMintFor, withActor/Reasonon theschema.Tokenrow. A refusal is an OAuth error on the site's registered redirect_uri.- The site redeems at
/v1/iam/oauth/tokenas always.issueTokensseesrow.Actor, re-asks the rule, setsact {sub, owner, name}andimp: trueon the access token AND the id_token, caps life atmin(app, 15m), and issues NO refresh token. A refused impersonation code is spent.
The rule, asked at every step of the rows as they stand. Operator:
schema.User.SuperAdmin on the row, not forbidden or deleted — never a claim, an
isAdmin, or an admin membership — presenting their own sign-in (no act, imp
or machine type on the bearer). Target: a person in a tenant — never a
SuperAdmin, a reserved-org identity or a machine — not disabled, and one the
application signs in. Application: named in IAM_IMPERSONATION_APPS (clientIds,
admin-owned, fail closed — unset, impersonation reaches nothing) and serving no
reserved org. Reason non-empty (recorded up to 512 bytes).
Contained.
- Authority is the TARGET's.
sub,orgsand the Guard's principal resolve from the target row, and animpprincipal is neverSudo. Nothing of the operator's rides along — the opposite ofassume, which refuses animpbearer. - It READS IAM and never WRITES it. The Guard answers any non-GET with an
impbearer 403, andcallerOf/callerFrom— every self-service write: password, passkey, linked sign-ins, unlink, onboard, profile, preferences, consent, terms — resolve nobody for one; the reads (account, whoami, linked-accounts, consent GET) usereaderOf. A key or passkey minted in the window would outlive it. - It lives only while its operator may impersonate:
oidc.Operatoris re-asked by the Guard on every request, by UserInfo, the account reads, introspection (active:falseonce it fails) and an exchange. /v1/iam/signinrefuses an impersonation code without spending it: a session at the issuer would outlive the token and carry no mark.PlatformBeareralready refuses any token withact.- An RFC 8693 exchange of an
impsubject_token carriesact/impforward and dies no later than its subject. - It does not chain: an
impbearer is refused at/v1/iam/impersonate.
Visible. act and imp ride both tokens, UserInfo and introspection;
discovery advertises imp.
Trail. schema.ActionImpersonate (PlatformWritten): a row per step — the
hint, the code, the token, an exchange — and per IAM request the token makes,
refusals included. user = the operator, always; owner/organization = the
target's org, so the tenant reads who was in it (the operator's org until the
target resolves); requestUri names the step; object = {target, reason, client, ttl}; response = why refused; clientIp is X-Forwarded-For as the
caller sent it.
Not RFC 8693 for the mint. An exchange proves a subject_token the operator does not hold, so it would need a non-standard subject parameter, and it hands the token to an API client rather than to the site's browser.
Rollout order. Cloud and the sites ship their halves below FIRST; only then
does IAM_IMPERSONATION_APPS=hanzo-platform,hanzo-ai go on the IAM deployment.
Cloud writes IAM with its own client credential (API keys, memberships), so IAM's
Guard never sees the imp bearer there: until cloud refuses it, an impersonation
could mint the person a durable key.
Contract — cloud POST /v1/admin/users/:org/:name/impersonate {site, reason}:
forward the operator's bearer unchanged and their real address as
X-Forwarded-For to POST /v1/iam/impersonate with target=<org>/<name> and the
site's clientId (platform → hanzo-platform, hanzo → hanzo-ai); relay IAM's
status and message; on 200 answer {"url":"<initiate>?iss=<issuer>&login_hint=<urlencoded loginHint>"},
<initiate> = https://platform.hanzo.ai/auth/initiate or https://hanzo.ai/auth/initiate.
IAM is the gate; cloud adds none. On every request, cloud's caller identity carries
imp and act: authorize on sub/owner/orgs exactly as for any token, never
on act; refuse every non-GET that mints or changes a credential (API, SSH and
principal keys), a membership, a payment method or a payout; bill no metered use to
the person; write act beside the subject in its own audit.
Contract — sites (hanzo.ai, platform.hanzo.ai): serve GET /auth/initiate
(OIDC Core §4) — require iss = the configured issuer, start a fresh authorize
with new state/nonce/PKCE and login_hint passed through verbatim, and replace any
local session only on a successful callback (dropping it up front makes the link a
logout CSRF); land on /. On a token or UserInfo with imp: true, show a fixed
banner "Signed in as by <act.owner>/<act.name> — support session", never
offer refresh, and at expiry (≤ 15 min) sign out locally rather than renew.
Delegation — a run acts and bills as its person, for model calls only
Cloud runs coding work FOR a person inside a sandbox that executes model output.
The sandbox needs a credential for its model calls. Cloud's own machine token
billed every tenant's run to admin and put the deployment's identity in the
box; tokens/issue would hand the box the person's whole account. Delegation is
the third thing. Code: internal/oidc/delegate.go; tests TestDelegate_*.
Grant — RFC 8693 token exchange with an actor and no subject_token:
POST /v1/iam/oauth/token
grant_type=urn:ietf:params:oauth:grant-type:token-exchange
client_id, client_secret the orchestrator (hanzo-cloud)
actor_token=<its own machine token> client_credentials or workload grant
requested_subject=<sub | owner/name> the person
org=<slug> the org the run bills
scope=ai:inference schema.Inference, the only one
resource=https://api.hanzo.ai RFC 8707, on IAM_DELEGATION_AUDIENCES
lifetime=<seconds> ≤ 4h (delegationTTL), one way
run=<id> audit only
Who may ask. IAM_DELEGATION_APPS (clientIds, admin-owned, fail closed) —
its own list, not IAM_TOKEN_EXCHANGE_APPS: a client allowed the narrower act
is not thereby allowed the wider. The actor_token must be that client's own,
live machine token (type: application, azp and sub its own, no act/imp).
For whom, where. A live person (not forbidden, deleted or a machine), never a
reserved-org identity (a SuperAdmin: IAM reads authority off the ROW). The org
must exist, must not be reserved, and must be one the person's own token names
(store.MemberOrgRefs) — a person in several orgs is minted into the one asked
for or refused.
Signed by a key no public verifier holds. The decisive narrowing. A Cert
with scope: delegation (schema.CertDelegation) is never in the JWKS
(isSigningCert), never signs for an application (signerFor), keys no session
MAC (PlatformSigningCert), and verifies here only a confined token
(parseToken). Every other verifier in the estate — admin-guard, Base, the forge,
cms — checks a signature against the public JWKS and reads none of the claims
below, so a delegated token under a published key WAS the person to all of them
(red PoC, 2026-10-09). Under this key its kid resolves nowhere they look.
Its public half is GET /v1/iam/oauth/delegation/keys (PathDelegationKeys),
answered only to a client on IAM_DELEGATION_APPS presenting its secret
(Basic); cloud reads it with the credential it delegates with. The newest mounted
delegation key signs, every one verifies (add before signing, keep until what it
signed expires). Provisioned like every signing key: a Cert row (owner: admin,
name: cert-delegation, scope: delegation, type: x509, RS256) and a PEM
of that name in the IAM_SIGNING_KEYS mount from KMS. None mounted takes down
DELEGATION and never identity: the process boots and serves, server.RequireSigning
prints one loud line (iam: ERROR delegation is down, identity serves: …, from
oidc.DelegationReady, naming the certificate and the directory its PEM goes in),
and the exchange and /v1/iam/oauth/delegation/keys answer 503
temporarily_unavailable "delegation key not mounted" — so cloud refuses the
coding run with those words, and never signs under a published key.
What comes back is the person's token narrowed, each narrowing a claim
cloud reads: orgs = that one org with role member (no admin role rides along),
owner = organization = it; scope = ai:inference; aud = the URI, azp empty (no
consumer that admits a token by its client — S3's federation — admits this one);
aud = an https origin named exactly on IAM_DELEGATION_AUDIENCES (the API that
serves model calls; unset refuses every delegation, so the client never picks the
service); act {sub: admin/hanzo-cloud, owner, name}; billing_account as the person's own
token states it at home and none elsewhere (account.Payer ignores a home claim in
another org, so the spend matches); no refresh token. Row dl-<hash>, revocable
by the client and live to introspection.
Confined means confined. schema.Confined(scope) is the one predicate.
verifyBearer refuses a confined token, so the Guard, UserInfo, account reads,
impersonation and masquerade never take one; an exchange refuses one as
subject_token. Introspection reports it as it is (active, scope, act). Cloud
serves it the inference addresses and nothing else (cloud LLM.md "Delegated
tokens"). A scope only narrows: a person who asks for ai:inference at sign-in
confines their own token.
Trail. schema.ActionDelegate (PlatformWritten), one row per attempt after
client authentication: user = the person, filed under the org asked for,
object = {actor, org, run, ttl}, refusals with their reason and status. A
client NOT on the list gets a row in its own org naming only itself
({"actor":"<clientId>"}): any tenant's app reaches the branch, and nothing it
wrote is filed as the platform's.
Rollout. IAM is embedded in cloud in production, so it ships in the cloud
image (go.mod bump) together with IAM_DELEGATION_APPS=hanzo-cloud,
IAM_DELEGATION_AUDIENCES=https://api.hanzo.ai, the cert-delegation row and its
PEM in the signing mount. Cloud fails a run rather than fall back to its machine
token.
A mark is how a SUBJECT appears, and a subject is a person OR an org
schema.Mark is the pair every subject carries — avatar, an image, and
emoji, one glyph — with schema.MarkOf the one writer. A person already had
User.Avatar (published as the OIDC picture claim and the SCIM photos
value); Organization now carries the same two fields under the same names, so
a screen draws a subject without asking which kind of subject it holds.
Two fields, one answer. They are two fields because they are two TYPES:
picture and photos are URL-typed by their specs, so an emoji in avatar is
not a smaller answer, it is an invalid one. At most one is ever stored — an image
wins at the WRITE and the emoji does not reach the row — so no reader ranks them
and nothing downstream can rank them differently. Both empty means the subject is
drawn as its initial, which is the only part that is the client's.
Both halves live on the ROW. A mark appears everywhere the org does, so it
cannot be kept per device. Logo/LogoDark are a different thing: the wordmark
a login screen draws. DefaultAvatar is a third — the avatar new MEMBERS start
with, not the org's own.
An image is a REFERENCE. https://…, or the bytes inline as
data:image/{png,jpeg,gif,webp};base64,… — which is what a crop performed in a
browser produces, and what User.Avatar already holds. IAM stores no blobs and
needs no bucket for this. schema.AvatarRef refuses everything else: http is a
downgrade on a page served over TLS, and SVG renders in an <img> while being a
document that executes. AvatarLimit (96 KiB) lives here because the row lives
here — a bound enforced only by the client that writes it binds that client alone.
POST /v1/iam/organizations/avatar (setOrganizationAvatar), body
{owner, name, avatar, emoji}, answering the masked org row. Reads need no route:
the pair rides on organizations/organizations/get like any other column, so a
picker listing orgs gets every mark in the response it already makes.
It is its own op rather than a field on update because update REPLACES the
record and every read is masked — a client that read an org, changed one field and
posted it back would persist "***" over masterPassword, passwordSalt,
passwordObfuscatorKey and kerberosKeytab. This one applies two fields to the
row as it stands, so nothing else can be carried in or out on the request.
Authorization is the one that already existed. The path's first segment is
organizations, so authorize reaches the reserved-owner clause and a write
resolves to p.adminOf(name) — an org admin manages the org they administer, by
their own IsAdmin or an owner/admin membership. Self-service, NOT SuperAdmin:
nothing here consults the reserved admin org, and a plain member and a foreign
org's admin are both refused. Pinned by TestSetAvatar_*, which drive the real
router with a real bearer.
Org scope — HONOURED or REFUSED, never silently reinterpreted
The rule. A request that NAMES an organization gets that organization's data
or an error. It never gets a different organization's data. authz.Scope is the
one place it lives; all 17 org-scoped call sites resolve their owner there.
| principal | ?owner= |
result |
|---|---|---|
SuperAdmin (org admin) |
anything | honoured; empty = every tenant |
| anyone else | absent | own org (unstated ≠ reinterpreted) |
| anyone else | its own org | honoured |
| anyone else | any other org | 403, no rows |
anyone else, p.Org == "" |
anything | 403 (no org ⇒ no scope; "" used to mean no filter = every tenant) |
Why. Scope used to return p.Org for ANY owner. Measured in production
2026-07-28 with the hanzo-console credential (home org hanzo): ?owner=lux,
?owner=zoo and ?owner=nonexistent-org-xyz each answered 200 {"status":"ok"}
with 262 hanzo accounts. Nothing in the code, the status field, the msg
or the count said the filter had been dropped, so a fabricated org was
indistinguishable from a real one and from your own. No rows escaped IAM, so it
was not a confidentiality breach here — it was misattribution, which is worse
in one specific way: you believe you hold tenant B while holding tenant A. It
nearly caused a production purge of the wrong tenant. Downstream it was a leak:
cloud's IAM edge (cloud/iam_edge.go) validates ?owner= against the calling
tenant and then forwards it under ONE confidential client, so every tenant's team
page asked for its own org and was served the edge credential's org.
Not an existence oracle — by construction, not by care. The refusal is decided
from the verified principal alone and never touches the store, so lux (real),
built-in (reserved) and nonexistent-org-xyz (invented) are the same comparison
and the same bytes; the message names the CREDENTIAL's org, never the requested
one. Same collapse cloud's per-org KMS store makes: every spelling you may not
have routes to ONE existence-independent answer. It differs only in which
answer — KMS reads the org from the token, so absence is its only observable and
it answers 404; here the org is a stated parameter, so there is a decision to
report and reporting it is the point.
Cross-tenant reach exists only where a grant says so, and a grant HONOURS the org it names (returning that org's real data, correctly attributed) — it never substitutes:
- SuperAdmin — every entity. The only unrestricted cross-tenant scope.
CapOrgAdmin— the organization REGISTRY only. Brand consoles create customer orgs during onboarding and readOrganization.Founderto resume a partial one, so registry-wide reach is load-bearing, not incidental.
So get-users and get-organization now agree on the only question carrying a
secret: for every principal without a cross-tenant grant both refuse a foreign
org existence-independently, so neither is an oracle. For a CapOrgAdmin holder
org existence is not a secret — it can create orgs and read Founder, so hiding
reads from it would be theatre. What can no longer happen anywhere: being handed
org A's rows in answer to a request that named org B.
A rewrite is not a safe answer, only an unsampled one. The old SCIM guard
(scim/read_scope_test.go) proved foreign-exists and foreign-missing were both
404 and called the oracle closed. It was: the re-pin turned /Users/orgb/bob into
a lookup of hanzo/bob, absent. Seed a hanzo/bob — a name every tenant has —
and the same request returns 200 carrying hanzo's bob under orgb's URL, and
PATCH active:false then deactivates a hanzo employee. Pinned by
TestRed_scimGet_foreignIdNeverResolvesToASameNamedLocalUser.
Divergence still open (needs a decision, do not "fix" by widening). The legacy
verb lister goes through Scope; the native noun lister (organizations.List)
filters in.Owner under the Guard's authorization. For a CapOrgAdmin app,
get-organizations?owner=admin is now a 403 while /v1/iam/organizations?owner=admin
returns every org row (masked). Before this change it was 403-vs-a-silently-EMPTY
list, so nothing regressed — but one policy still answers two ways on two
spellings. Unifying it changes a documented capability's blast radius: decide it
deliberately, in authorize(), not by opening the legacy lister.
API keys — one entity, one plural noun, and the SCOPE is what differs
internal/keys, entity keys, routes /v1/iam/keys{,/get,/update,/delete}.
Plural on every op (like users): authz.entityOf reads the FIRST path segment
as the entity, so serving the list at keys and the writes at key made two entity
strings for one entity — and any capability keyed on it was dead on whichever half
you did not name. Same defect entityNoun fixes for the legacy verb spellings.
Scope carries the ACCESS CLASS, fixed at create (an update that could flip it
would blank a secret and make its pk- half resolve at the ingest endpoint), and
the REACH beside it, which is policy: PUT may change the reach and is refused if
it names the other class. A PUT writes every editable field, so a caller sends the
row as read with its changes made.
A row records prefix (schema.PrefixOf, the first 12 characters of the credential
its holder presents, set at mint) so a listing can say which string it is. Revoking is
PUT with state: "Revoked": the row stays listed, stamps revoker/revokeTime,
resolves to key_revoked, and is final (a later PUT is 409). DELETE still removes
a row outright. keys/principal answers the row's name as key, so a resource server
can count and limit each credential on its own.
Last used is a Sighting, not a field write. The resolver (keyBySecret,
PublishableKeyByAccessKey) records when a key was presented in its own row
(sighting/<owner>/<name>), at most once a minute, and the list fills usedTime
from it. Writing it onto the key row would race a PUT and could undo an edit; the
store keys every kind by id, so the prefix keeps it off the key row too.
| scope | halves | resolves to | endpoint |
|---|---|---|---|
"" (secret) |
pk- + sk- |
the USER | get-user?accessKey= (CapKeyResolve) |
publish |
pk- only, NO secret |
just the ORG | resolve-key (CapPublishableResolve) |
The publishable key had no producer until 2026-07-28. The model, the resolver
(store.PublishableKeyByAccessKey) and the ingest endpoint all existed and nothing
minted one. It is now a FIELD on the one mint:
POST /v1/iam/users/{owner}/{name}/keys?type=publishable|secret (default secret;
unknown type → 400), and DELETE on the same address takes the key away — the
shape a service account's key already has
(POST /v1/iam/service-accounts/{name}/keys). keys.NameFor(scope) maps
scope → row name (cloud-api / publishable), so the two are separate rows and
rotating a browser key does not revoke the API key.
Every read is masked. schema.Key.Mask() blanks AccessSecret and keeps
AccessKey (a pk- is public and its holder needs it). Before it, the key list
handed every reader every secret in the org, which made read AUTHORIZATION stand in
for redaction. The secret is revealed ONCE, by create. capFor("keys") =
CapKeyMint: the authority that already mints a credential may read the set it
manages.
Who lists which keys is keys.visible; the collection authorizes itself
(handlerAuthorizedExact), because belonging opens it and the tenant rule admits
only an admin. A client holding key-mint reads the org it SERVES and no other: its
mint reaches every tenant, its read does not. A SuperAdmin or the org's admin
(AdminOf) reads every key; any other person reads the keys they hold in an org
they belong to (ScopeRead). A reserved org's keys are a SuperAdmin's alone, as the
Guard holds every row it owns. So cloud lists a customer's keys with the customer's
own token and writes with the client. A named key stays the Guard's. The allowlist
lookup is principal.Env, in the leaf so a collection can ask a capability.
Pinned by routes/member_keys_test.go.
MintUserKey writes a schema.Key ROW because that is the only thing the resolvers
read. Stamping it on schema.User.AccessKey authenticated nobody — nothing resolves
that field, and it is not a credential.
Two key shapes, estate-wide. pk- is publishable and sk- is secret; there is no
third. store.UserByAccessKey resolves a live sk- (pinned to the key row's own
tenant), refuses a pk- as key_wrong_door — a real credential at the wrong endpoint —
and answers key_unknown for everything else, which is what renders the actionable
"mint a new one at cloud.hanzo.ai/keys". A value carrying any other prefix is not a
key, so it takes that same unknown path rather than a branch of its own.
Refresh — confidential is a property of the GRANT, and a lifetime must be SAID
Two independent defects made refresh_token unusable for every client that signs
in through a browser, so a session died at the access token's expiry and the user
logged in again. Measured on hanzo-cli 2026-07-31: a live refresh answered
401 invalid_client, and the refresh token was already expired anyway.
Client auth. authorizationCodeGrant has a documented relaxation — a
registration that HOLDS a secret still serves a public PKCE surface (hanzo-cli,
and every @hanzo/iam SPA whose secret exists for a backend path), so a code
exchange that presents no secret is authenticated by PKCE instead.
refreshTokenGrant did not have it and demanded the secret unconditionally: the
client completed the exchange without one, cannot acquire one, and is refused the
moment it tries to renew. The fact is now recorded where it belongs — on the
GRANT, schema.Token.PublicGrant, set at establishment and carried across
rotation (drop it and only the FIRST refresh works). It never widens: a grant
established WITH the secret still needs it, and a presented secret is always
verified.
Lifetime. refreshTTL falls back to appTTL when RefreshExpireInHours is
unset — v1 parity, and dead on arrival: the refresh token expires at the same
instant as the token it renews. Nothing could say otherwise, because the upsert
body carried no lifetime field at all. expireInHours / refreshExpireInHours
now travel document → provision.App → upsert → model under ONE name, as
POINTERS on the wire so an omitted lifetime PRESERVES (a plain float would reset
every app on every converge). provision.checkLifetimes REFUSES a refresh
lifetime that does not outlive the access lifetime, measured against
schema.DefaultExpireInHours when the access lifetime is unstated — so the state
hanzo-cli shipped in cannot be declared again.
Which half bit whom (measured over all 286 live applications on hanzo.id).
Most first-party clients already carried expireInHours: 168 +
refreshExpireInHours: 720 from the v1 era, so for hanzo-cloud, hanzo-chat,
hanzo-platform, hanzo-world the LIFETIME was fine and only the CLIENT-AUTH
half was broken — they held a 30-day refresh token they could not spend. One fix
unblocks all of them: driven live after the change, each does code→token 200 then
refresh 200 with a new access token, presenting no secret at either step.
hanzo-cli was the rare client with BOTH lifetimes at 0, which is why it was the
one that hurt. Still at 0, and therefore still dead on arrival: hanzo-mcp (now
declared, same as the CLI), hanzo-git, hanzo-zrok, hanzo-admin, and every
auto-created per-signup app-<email> client. The fix is one line per app in that
org's provision document; it is deliberately NOT a changed global default,
because session lifetime is POLICY and this mechanism ships no policy.
Device grant — a CLI holds NO secret, and ROPC must then refuse it
hanzo auth login died on invalid_client: client authentication failed
straight out of POST /v1/iam/oauth/device, for every client, so nobody could
sign in from a terminal.
Cause. deviceHandler requires the stored secret from any registration that
HAS one (RFC 8628 §3.1 → 6749 §3.2.1), and every Hanzo client was declared
type: confidential in the provision document — deliberately, because
client_credentials and the password grant authenticate with that secret and a
public upsert DELETES it (bootstrap.resolveSecret). So all 12 held one, and a
CLI can never present one. The code exchange survived the same registration
shape only because authorizationCodeGrant skips client auth when a PKCE
challenge is present; the device grant carries no challenge to skip on, so it
had no such escape. invalid_client distinguishes the two cases — client_id is invalid means unknown, client authentication failed means known-and-holds-a-
secret — which is how the cause was read straight off the wire.
Fix. hanzo-cli is type: cli in the universe provision document: PUBLIC,
no stored secret, loopback redirects per RFC 8252 §7.3, with the device grant
declared through the additive grants: field rather than added to
grantsByType[cli] — same reason redirects is additive, a type default would
silently hand RFC 8628 to every future CLI client in every org. No image was
needed; make iam-provision converged it.
The rule this forced. Going public silently opened ROPC. passwordGrant
gates on the enablePassword FLAG, not on grantTypes, so removing password
from the document changed nothing — and the grant had a legacy-parity relaxation
that let a public client through, carried so console/chat would not 401 during
the cutover. With no stored secret and no PKCE challenge and no human approval
step, "public" there means anyone who knows the client_id can post a username and
password. passwordGrant now REFUSES a client with no stored secret. The
relaxation was dormant (every live registration is confidential and takes the
secret path), so nothing that worked broke. The rule lives on the GRANT, not in a
document, because registration shape must not be able to open a credential
surface — the same lesson as Token.PublicGrant above, in the other direction.
One client id. hanzo-cli is the id BOTH CLIs authenticate as — Rust
hanzoai/cli (src/iam/oauth.rs CLIENT_ID) and the Go control CLI
(hanzoai/cloud cli/cli.go defaultClientID). The Go one had been borrowing a
different first-party client per flow (hanzo-app for device, hanzo-console
for password and refresh); besides being unregistrable, that guaranteed renewal
could never work, because a device_code is redeemable only by the client it was
issued to and a refresh token was being presented under a different id.
Workload grant — the cluster already vouches for the pod
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer (RFC 7523,
internal/oidc/workload.go). A service in Kubernetes posts the projected
ServiceAccount token its pod already carries and gets back exactly the token
client_credentials would have given it for a stored secret — same signer, same
claims, azp = the app. No client secret travels, and none has to exist in the
cluster.
A secret in a pod is a secret in etcd, in whatever manifest names it, and in every
kubectl get secret anyone with read access on the namespace runs. The projected
token is none of those: the kubelet mints it for one pod, for one audience, with a
lifetime in hours, and rotates it in place.
POST /v1/iam/oauth/token
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
assertion=<projected ServiceAccount JWT>
[resource=… | audience=…] [scope=…]
Proved, per request: signed by a key the named cluster publishes; aud names
THIS issuer (so a token the kubelet projected for some other service cannot be
replayed here); inside its window (exp required, nbf honoured); sub is
system:serviceaccount:<namespace>:<name>.
Configured, exactly — no globs, and never a whole namespace:
IAM_CLUSTER_ISSUERS {"https://kubernetes.default.svc.cluster.local":
{"jwks_uri": "https://10.0.0.19:6443/openid/v1/jwks",
"ca_file": "/etc/iam/cluster-ca.crt",
"bearer_file":"/var/run/secrets/kubernetes.io/serviceaccount/token"}}
IAM_WORKLOADS {"hanzo:pkg":"hanzo","hanzo:chat":"hanzo"}
IAM_WORKLOADS names each ServiceAccount that speaks, as <namespace>:<name>, and
the org it speaks in. An account's name is chosen by whoever may write its
namespace, so the same name elsewhere is another account and mints nothing. A key
that is not <namespace>:<name> (a bare namespace above all) or an entry with no
org refuses the whole map with server_error.
Both absent → the grant answers unsupported_grant_type and discovery does not
advertise it. Present but unreadable is a DIFFERENT answer (server_error naming
the variable), because one bad character must not look like a deployment that
never offered the grant.
ca_file is the cluster's own CA — an apiserver serves its key set under a
certificate no public root signs. bearer_file is optional and names IAM's own
ServiceAccount token, for an apiserver that refuses an anonymous read of
/openid/v1/jwks (k3s answers 401); the account behind it is bound to nothing but
system:service-account-issuer-discovery. That file is read at every fetch and
never held, because the kubelet rotates it in place.
Key sets are cached for the lifetime the response asks for, else 10 minutes. An
unknown kid re-reads the set once — a cluster rotates on its own schedule, so the
first token under the new kid is what asks — and an UNPRODUCTIVE re-read is the
one such read a held set gets, or a made-up kid per request is a JWKS read per
request. The JWK decoder is the one federation_idp.go already verifies external
id_tokens with; a second decoder would be a second opinion about what a published
key is, and the weaker of the two is the one an attacker picks.
A GitHub Actions run speaks the same way. GitHub's issuer is one more entry
in IAM_CLUSTER_ISSUERS ({"https://token.actions.githubusercontent.com": {"jwks_uri":"https://token.actions.githubusercontent.com/.well-known/jwks"}}, no
ca_file: its key set is behind a public CA). The job asks GitHub for an ID token
whose audience is this issuer (https://hanzo.id) and posts it as the assertion.
IAM_REPOSITORIES maps the run to the CI application it speaks for:
IAM_REPOSITORIES {"hanzoai": {"org":"hanzo","app":"ci","owner_id":"…"},
"hanzo-apps/network": {"org":"hanzo","app":"sites-ci","owner_id":"…"}}
A key is an account, <owner>/<repo>, or <owner>/<repo>@<ref>, exact, and the
most specific wins. owner_id is required and must equal the token's
repository_owner_id: a GitHub account can be renamed and its old name taken, and
the id cannot. The clientId is <org>-<app>, and the same declared-application
checks apply. An assertion from GitHub is read by repository only, and one from a
cluster by service account only.
The application is DECLARED, never created here. <org>-<name> — the org
IAM_WORKLOADS gives the account, the name from the account — is the clientId
internal/provision derives, and it must already exist, declare both
client_credentials and urn:ietf:params:oauth:grant-type:jwt-bearer, and belong
to that org. The org check is load-bearing:
a clientId is a globally unique STRING, so zoo-pkg registered under some other
org would otherwise let the zoo namespace mint that org's token. Every mint writes
a workload-token audit row naming the service account that presented and the
application it was for.
A login descriptor states BOTH halves, or it is a lie
Every sign-in method on /v1/iam/auth/methods and get-app-login is the AND of
two independent facts, and publishing only the first is how a screen ends up
drawing a button that cannot finish:
the application switch the org WANTS this method
the capability this BUILD can perform it
password app.EnablePassword
code app.EnableCodeSignin && otp.DeliveryConfigured() (a bound Sender)
webauthn app.EnableWebAuthn (the ceremony is compiled in)
web3 schema.WalletChains() (what verify accepts)
oauth offerable(provider) (real credential AND a driveable dialect)
loginView masks the same switches on the legacy descriptor, so the two cannot
disagree — the browser reads whichever one still lies. The org's stored setting is
never edited; only what a screen is told.
Passkeys are the one row where the second half is now a constant true, so it is
not written: internal/oidc/webauthn.go carries the assertion ceremony in every
build, so a server that can serve this descriptor can always challenge a passkey.
The predicate that used to stand there (schema.PasskeySignin) is gone rather
than pinned to true — a switch nobody can turn off is not a switch.
The two WebAuthn ceremonies
internal/oidc/webauthn.go holds both halves of the standard, on
github.com/go-webauthn/webauthn: registration enrolls a passkey, assertion signs
in with one. Four addresses, already called by the hosted login and account pages:
GET /v1/iam/webauthn/signup/begin POST /v1/iam/webauthn/signup/finish
GET /v1/iam/webauthn/signin/begin POST /v1/iam/webauthn/signin/finish
It lives in internal/oidc because it is a LOGIN ENDPOINT, and the three rules a
login endpoint must not forget are unexported here: callerOf (cookie-or-bearer, which
is how the portal enrolls with no bearer), Gate (the org's second factor), and
loginGrant (the one mint path and the session it opens). The passkey ROWS stay in
internal/webauthn — one table, written by the ceremony, listed and revoked there,
keyed by the same schema.CredentialName.
Half-finished ceremonies ride the existing LoginChallenge primitive under two new
kinds, KindRegister and KindAssert; the go-webauthn session is the row's
Payload, the subject is the row's Subject, and TakeChallenge burns it
atomically. So a replayed assertion loses, and a finish learns whose ceremony it is
from the burned row rather than from the request.
RP ID is the issuer's host — resolveIssuer(host) parsed, nothing new to
configure. A passkey is bound to ONE relying party for life and the native endpoints
already relocate every request onto its brand's pinned issuer, so the passkey works
at exactly the origin that brand's tokens are issued from. hanzo.id and
hanzo.ai are separate registrable domains, so ONE passkey cannot serve both:
admin.hanzo.ai never runs a ceremony, it federates to hanzo.id and the passkey
is challenged there.
User verification is enforced twice, deliberately. The relying-party config asks
the browser for it (that is what makes the phone demand Face ID), and the finish
reads the UV bit off the signed authenticator data. The library's own check derives
from session.UserVerification, which makes a JSON round trip through the challenge
row; the direct read depends on the assertion alone, so a field lost in transit
cannot silently downgrade a passkey to possession. Each half has a test that fails
when only that half is reverted.
Sign-in is username-first: signin/begin takes ?owner=&name=, and the challenge
is bound to that person. Credentials are enrolled as resident keys, so they ARE
discoverable passkeys on the device — but usernameless (discoverable) sign-in is not
wired, and the login form's username field is required for this method.
A verification code has ONE receiver key
otp.Receiver (internal/otp) is the single canonical form a code's destination is
stored under, matched by, and delivered to. A phone number is
store.NormalizePhoned; anything else is verbatim, because NormalizePhone keeps only
digits and would leave an email with nothing to match on. Which one it IS is
store.LooksLikePhone, beside NormalizePhone, because "is this a number" and "what
is its canonical form" are one question and sign-in's identifier resolution asks it
too.
EVERY site routes through it, because they all live in the one package: the send that
writes the record, both readers (otp.Consume, otp.Check), and the second-factor
challenge's own send. Deciding the shape once is what makes the write and the read
unable to disagree: the record used an exact Receiver= compare while the ACCOUNT on
the same request resolves through GetUserByPhone, which normalizes first, so
"+1 415 555 0134" at send and "+14155550134" at login found the right user and then
answered "the code is incorrect or has expired".
An emailed code carries a sign-in link when the page's origin is registered
POST /v1/iam/verification-codes type=email reads the request's Origin and
landing (sendverificationcode.go) picks the first of the application's
RedirectUris whose scheme+host+port equals it exactly, fragment cut. Then
otp.IssueLink sends the designed sign-in mail (internal/otp/signin.go +
signin.html): subject "Your sign-in link", the code in the preheader, a
Sign in button to <uri>#code=<code>&email=<addr>, the code large in mono, the
expiry from TTL. Message.HTML carries the page and Message.Body the same
words as plain text, sent as its multipart alternative (cloud's notify:
client.Send.Text, hanzoai/notify Alternative). No Origin, no match, SMS,
and every other Issue caller send the plain message, unchanged and with no
HTML. Only a registered URI can be named, so a forged Origin picks among the
app's own callbacks; Host, Referer and X-Forwarded-* are never read. hanzo.ai
needs https://hanzo.ai/auth/callback registered on its app for the link to
appear (it is, on hanzo-app).
- The brand is the org row, never code: the name is
DisplayName, the siteWebsiteUrl(an https origin, path dropped; anything else gives no mark and no footer link), the mark<site>/email/mark.png(otp.MarkPath), a 132px opaque PNG an email client can show. hanzo.ai serves it (hanzo-inc/apppublic/email/mark.png,scripts/email-mark.mjs); a site that serves none shows the name as the image's alt text. hanzo-app's org ishanzo, so a code from hanzo.ai says Hanzo and never another brand. - Monochrome, light and dark. Inline light styles (any client), a
prefers-color-scheme: darkblock and Outlook's[data-ogsc]/[data-ogsb]overrides; the mark is an opaque tile, so a client that inverts the page but never an image still shows it. - Pinned whole:
internal/otp/testdata/signin.htmlis the mail as sent;go test ./internal/otp -run Snapshot -updaterewrites it, and the diff is the review of a design change. - No WebOTP line (
@hanzo.ai #123456): that format is read from an SMS only. The page's field saysautocomplete="one-time-code", which is what fills an emailed code where a browser can (Safari, from Mail).
Sign-up by code — the code proves the address, the click creates the account
A code sent to an address no account holds is filed with User == "" under the application's org. POST /v1/iam/login type=code with that code and no resolved user (codeSignup, code_signup.go):
- app code sign-in on, sign-up on,
Registers(app, org), the request names the app's org, email only — else the same opaque "incorrect or expired" every miss gets. - no
create:otp.Check(live, unowned, NOT spent; a miss counts) thendata: "SignupRequired". Only someone who proved the address learns it has no account. create: true+terms+aup(version labels): re-check no row holds the address,otp.Prove(spends), make a passwordless account (verified, normal-user, never SuperAdmin,Charterfounds the personal org likeprovisionFederatedUser), recordschema.Terms(versions, time, methodemail-code, IP), thenafterFirstFactor— the one minting tail.PUT /v1/iam/terms(caller-scoped) records the same for a federated first sign-in, methodsigned-in. The record lives in the preferences blob underterms; the preferences merge refuses the key andUpdatecarries it from the stored row.
internal/otp is the one-time code; internal/mfa/factor is the second factor
Two words that are easy to braid and must not be. otp is a secret SENT to an
address to prove somebody holds it — mint, word, file, deliver, spend — and it is a
LEAF (store + schema + cred). factor is what a second factor IS: app (TOTP, whose
secret never travels), sms, email; whether a passcode verifies; which factors an
account HOLDS (factor.Has/Held); where a delivered one goes (factor.Destination,
the address on the ACCOUNT and never one from a request); and the ONE writer of each
column (Add/Remove/Prefer/Save).
Prefer holds the invariant the login gate depends on: PreferredMfaType names a
factor the account HOLDS. factor.Enabled is that column, so a preferred type nobody
enrolled reported "MFA is on" and then left the gate nothing to ask for.
The enrolment surface (internal/mfa) and the login gate
(internal/oidc/mfa_gate.go) are the two callers, and neither owns a second copy of
any of it: one proveFactor verifies a challenge answer for both the password and the
federated resume, and the challenge row carries the factors it was minted OFFERING so
an answer is checked against that offer rather than recomputed.
Linking a provider — intent from the issuer or the platform, presence in the browser
A sign-in method outlives every token, so /v1/iam/link (internal/oidc/federation_link.go)
takes one proof per leg, and neither leg alone attaches anything:
POST /v1/iam/link{provider, clientId, returnUri}— INTENT. The caller is the person on the issuer (a session this request may spend,sessions.Writer) or a bearerPlatformBeareraccepts: an access token issued to an application init_data.json declares underadmin(schema.Application.Platform; hanzo-console, hanzo-app, hanzo-ai, lux-cloud, … are). Any other application's bearer is 403ErrNotPlatform. It answers<sign-in origin>/v1/iam/link?state=<t>and sets no cookie.GET /v1/iam/link?state=<t>— PRESENCE. A top-level navigation from a browser holding that person's session here (signedInHere). It spendst, mints the provider-leg transaction (fresh state, nonce, PKCE) and sets__Host-hanzo_fedon this navigation, as authorize does for a sign-in, then 302s to the provider. The callback refusestitself: it carries no binding.
Callers: hanzoai/id pkgs/auth createAccountClient().link() (hanzo.id
account → Security) POSTs same-origin with the session cookie plus a hanzo-console
bearer and navigates to the answer. @hanzo/iam, hanzo.ai and @hanzo/rooms do
not call it. Pinned by TestLink_*.
A wallet is a sign-in method, and the account's DID is derived from sub
A person links a wallet once, here, and every app reads it as a claim. Three
pieces, and the point is which of them depend on each other: the LINK is native
CAIP-122 in internal/wallet, the CLAIM is derived in identityOf, and the
on-chain ANCHOR is optional and depends on neither.
The link. GET /v1/iam/web3/nonce?chain=&address= mints a CAIP-122
challenge — the LoginChallenge field for field, so @luxwallet/connect's
buildSiwxMessage renders the message the wallet signs and the Go
ParseSiwxMessage reads back the same string. POST /v1/iam/web3/verify
carries the SignedProof (chain, scheme, address, publicKey?,
message, signature, extra?) plus the app routing and the authorize
passthrough, and answers a user id or a PKCE code exactly as a password login
does. verify runs luxwallet/connect/go's VerifyProof — the SAME verifier
the TypeScript client runs, so Go and TS cannot disagree about what a valid
proof is.
The ORDER in internal/wallet/verify.go is the security property: the nonce is
read from the SIGNED MESSAGE (never the body, or a forged body could desync the
two), the challenge is BURNED atomically before any cryptography (so a captured
proof cannot be replayed even when its signature is perfect), the burned row's
domain and chain are re-checked, and only then is the signature verified.
The domain is site() at both ends: the asking page's origin when the nonce
names a clientId whose redirect URIs register that origin (oidc.Landing, the
one rule the emailed link uses), else c.Host() — the true routed brand host,
never X-Forwarded-Host — because the whole anti-phishing binding rides on it.
So hanzo.ai asking IAM at api.hanzo.ai gets a challenge for hanzo.ai, and the
wallet's own domain check passes. Verify accepts the burned row's domain when it
equals either the request's site or its Host (a same-origin GET carries no
Origin), and VerifyProof always expects the burned row's. A forged Origin can
only pick among the app's own origins. Every mint sweeps expired challenges, at
most batch rows once per ttl per process (sweep); the nonce address is
bounded by maxAddress on both legs.
Identity is the address the VERIFIER recovered, canonicalized (EVM lowercased;
base58/bech32/SS58 trimmed only, because they are case-sensitive), never the one
the client claimed.
Linking to an account you already hold is the branch where the verify POST
carries a bearer AND is same-site. That is the only branch with ambient
authority, so a cross-site caller is treated as anonymous — a forged POST must
not attach an attacker's wallet to a signed-in victim. (chain, address) is
globally unique, checked in the same transaction as the bind, so one wallet is
one identity and a wallet already spoken for is refused rather than moved.
Creating an account is capped (internal/wallet/cap.go). A wallet is a free
key, so one script could mint accounts without end. Cap bounds the accounts
sign-up CREATES per client address and per network (IPv4 /24, IPv6 /64) in a
window: default 10 and 50 per 24h, set by IAM_WALLET_CAP_IP,
IAM_WALLET_CAP_SUBNET (0 = off) and IAM_WALLET_CAP_WINDOW (Go duration);
an unreadable value keeps the default. A wallet on file and a link to a held
account are never counted. The client is httpx.Client, the one rule IAM
counts by (CF-Connecting-IP, else the last X-Forwarded-For hop; the identifier
throttle reads it too). The ledger is schema.ActionWalletSignup audit rows
(ClientIp = address, Object = network), counted and written in the account's
transaction, so a refusal writes nothing and concurrent creations cannot share
one count. Refusal: 429, Retry-After, code wallet_signup_capped, data
{cap: "ip"|"subnet", limit, window, retryAfter} (seconds).
Unlinking is POST /v1/iam/unlink with
{"providerType":"wallet","chain":…,"address":…,"user":{"owner":…,"name":…}} —
the same endpoint, the same policy (holder or SuperAdmin; not an org admin), and
the same last-credential refusal every other method has. wallet is deliberately
NOT in connectorRegistry: that registry maps a type to ONE user column and an
account holds many wallets across many chains, so an entry there would have to
lie about the cardinality. detachable carries what differs — the name, which
one, and how it goes — and the policy above it is written once.
The claims.
"wallets": [{"chain":"evm","address":"0x2c75…"}, {"chain":"solana","address":"7EqQ…"}]
"did": "did:lux:6f1a3e2c-1f4a-4c0e-9a1b-2f9d4c7b8e01"
Both are resolved in identityOf, beside sub, orgs and the rest, so no mint
path can answer differently from another. wallets is ordered by (chain,
address) because it lands in a SIGNED value: an unordered read would make two
tokens for one unchanged account differ byte for byte. Both are omitempty — a
machine token has neither, and an account with no wallet omits the list rather
than carrying []. UserInfo answers with the same two, read FRESH from the store
rather than echoed from the token, which is the rule memberships are already
under: a wallet unlinked a minute ago stops counting now, not when the token
lapses.
What wallets asserts, and what it does not. It says IAM verified a CAIP-122
proof that the holder controlled that key, against a challenge IAM minted and
burned. It does NOT say they control it right now — a key can be sold, lost or
compromised between the link and the token, so the assertion is as fresh as the
token's lifetime. Anything authorizing a payment wants its own signature.
The DID derivation is schema.DID: did:lux: + the OIDC subject with /
rewritten to :. Derived, never stored — a stored DID is a second name for a
principal that can drift from the first, and it would make the identifier
something an admin write could repoint. A subject has two live shapes
(subjectOf): the opaque UUID, and the <owner>/<name> natural key a
pre-cutover row still carries. / begins a DID URL path, so did:lux:hanzo/z
would name a resource UNDER a DID rather than the DID; : is the
method-specific-id's own separator, so did:lux:hanzo:z is one identifier. The
map is injective over the subjects that exist — a UUID contains no : and no
/, and both halves of the natural key are drawn from the username alphabet —
so two people cannot derive one DID. A subject outside that alphabet yields no
DID rather than a malformed one, because an absent claim reads as "this
deployment has no DID for me" while an invalid one gets resolved, and what it
resolves to is not that person.
lux names the REGISTRY, not the brand: lux.id, hanzo.id, zoo.id and pars.id all
mint did:lux: because one registry cannot resolve four method names.
The on-chain anchor (internal/did) is off unless a deployment names all
four settings, and all four or none — a half-named registry is a mistake, not a
choice, so it is refused rather than degrading silently:
| setting | value |
|---|---|
IAM_DID_RPC |
JSON-RPC endpoint of the chain the registry is on |
IAM_DID_REGISTRY |
DIDRegistry contract address. No default — see below |
IAM_DID_CHAIN |
EIP-155 chain id, decimal; signed into every transaction |
IAM_DID_KEY_FILE |
path to KMS-mounted controller key material (hex, one line) |
The key is a FILE because the estate has one secret path: Hanzo KMS → KMSSecret →
Secret → mounted material, the same path internal/registry's signing key and
provision's credentials already read. IAM does not fetch its own secrets at run
time. A key in the environment is a plaintext secret in a pod spec, readable by
anything that can describe the workload.
On a NEW binding — only a new one, or a re-login would add a duplicate
verification method every time — IAM creates the document if the registry does
not hold one (createDIDFor), adds a CredentialIssuer service naming the
issuer and the subject at it, and adds the wallet as an
EcdsaSecp256k1RecoveryMethod2020 verification method. It runs AFTER the link
commits, outside its transaction, on its own context: a chain that is slow or
gone must not fail a sign-in.
Assumptions and limits, stated rather than discovered.
- The store is the source of truth; the registry is a projection. A failed anchor is not retried — the document catches up at the next link. Convergence, if a deployment wants it, reconciles from the store, which holds every binding.
- These documents are not self-sovereign.
createDIDForis registrar-only whileaddVerificationMethod/addServiceare controller-only, so one key does all three only by creating documents controlled BY ITSELF. IAM is that controller.changeControllerhands control to the person and ends IAM's ability to keep the document in step; no registrar override gets it back. - Only EVM wallets become verification methods. The registry's struct types
an account as an
addressplus abytes32, which fits a secp256k1 account and nothing else. Other chains link normally, appear in the claim and count as a credential; they are absent from the document, and the DID and its issuer service are still written. - No contract address ships in source. The address recorded for this contract
in
lux/standard'sregistry.json(0xB0B3Df1E27…) reports no code on any live Lux chain and names an AMM router on testnet 96368;DEPLOYMENTS.mdrecords different addresses again, and those disagree with the per-chain deployment records. Verify witheth_getCodeagainst the chain you are targeting before configuring one. - The registry is asked for its own method string once and IAM refuses to
write if it disagrees with
schema.DIDMethod. Documents registered under a name no token'sdidclaim matches are worse than no documents. - Selectors are derived from the canonical signature strings at init. A pasted four-byte constant is a value nobody can check by reading it, and a transposed digit reverts on chain as an unknown method — which looks exactly like a missing registrar role.
Key entry points
main.go— cobra root (serve/compare/version);server/server.goroute registration.internal/{oidc,routes}— OAuth2/OIDC surface;internal/{scim,mfa,webauthn,providers,sessions,tokens,cred,authz,certs,keys}.internal/{users,organizations,applications,roles,permission,memberships}— entities;pkg/model,pkg/store;MIGRATION.md(RFC surface + phases).
An identity provider's address is dialled by one rule (hanzoai/outbound)
Every IdP call (discovery, JWKS, token, userinfo) rides federationHTTPClient,
which is outbound.Client: the address is judged at the dial, after resolution,
on the IP the socket connects to, by the IANA special-purpose registries, and no
redirect is followed. The provider URLs are configuration a tenant admin writes,
so this is a request-forgery boundary. The guard it replaced (ipBlockedForFederation,
net.IP predicates) admitted Oracle's metadata (192.0.0.192), NAT64 and 6to4
spellings of 169.254.169.254, the benchmarking and documentation blocks and 240/4;
TestFederationClientRefusesNonPublicAddresses holds each. The tests' mock IdPs
bind 127.0.0.1, so allowPrivateFederationDial swaps in a plain client for the
test's duration; outbound itself has no switch that turns the rule off.
Sign in with Apple — a secret minted per exchange, and a POST back
internal/oidc/federation_apple.go, dialect apple in idpKind. Fixed endpoints
under https://appleid.apple.com (/auth/authorize, /auth/token, /auth/keys);
IssuerUrl replaces that issuer only for a test's mock. No PKCE: Apple advertises
none. The Provider row keeps the v1 mapping:
clientId Services ID the OAuth client_id; the secret's sub
clientSecret Team ID the secret's iss
clientId2 Key ID the secret's kid
clientSecret2 the .p8 PKCS#8 PEM, or its base64 body on one line
- The client secret is minted at each token exchange: ES256 JWT,
aud= the issuer as a string, five-minute life.offerableshows Apple only whenappleKeyholds: a Team ID and a Key ID of exactly ten A-Z/0-9 characters, and a P-256 key that parses (a PEM whose line breaks are the two characters\nis read with real ones). A failed exchange is logged with its cause and the RFC 6749 error code (invalid_client= Apple refused the minted secret), never key material. - The return is a cross-site POST. Asking for
name emailrequiresresponse_mode=form_post, so the callback answers POST for this dialect only and GET for every other (posts). A browser sends no SameSite=Lax cookie on a cross-site POST, so this leg's__Host-hanzo_fedis SameSite=None. That does not weaken it: the binding is the cookie's value hashed into the state row, and a page that makes a browser POST here still lacks that browser's state. A browser keeps a None cookie from an image or a frame too, so authorize sets it only on a top-level navigation (topLevelNavigation) and refuses anything else in place. - The POST hands off to a GET (
handoff).sessions.Opensets nothing on a cross-site POST (fromIssuer), so the POST proves state and binding, burns the state, writes the transaction again under a fresh id with Apple's reply inFederationState.Reply, and answers 303 tocallback?state=<id>. That GET is a top-level navigation: same binding cookie, one minute, single-use, and it reads the reply from the row, never the URL. It exchanges, mints the code and opens the session as Google's GET does, and carries the Lax cookies (MFA remember) the POST could not. The POST reads state and reply from its body only, and acode,errororuserpast 512, 256 or 1024 bytes (replyLimits) is refused, never cut. - Federation rows are swept on write. Begin, link and handoff all write through
persist, whosesweeptakes up to 100 rows that expired more thanfedStateTTLago (store.PurgeFederationStates), at most once a minute per process. The grace keeps a spent or expired link answering as such rather than as unknown. orm v0.6.44's Delete only marks a row deleted and keeps it, so each row is first rewritten to its key, expiry and Used: the verifier, nonce, binding hash, app request and Apple's reply leave the store, a tombstone per row stays. Removing the rows themselves needs a hard delete in orm.expireInis indexed over live rows, so a sweep reads no tombstone. - The identity is the id_token (RS256 under Apple's JWKS):
sub,email(possibly a private relay address),email_verifiedas bool or string. Theuserform field arrives on the first authorization only and is unsigned; it supplies the display name and nothing else. - Configuring it. The Services ID's return URLs are
<sign-in origin>/v1/iam/oauth/callbackfor hanzo.id and everyiam-signinhost. The seed creates providers new-only, so a live row's credentials are written withPUT /v1/iam/providers/admin/provider-apple. A multi-line PEM substituted into init_data.json breaks its JSON: give the seed the one-line body.
CORS — two questions, and the edge answers a third
internal/cors decides two things about an Origin, and conflating them is a
privilege escalation:
- May it read? The DERIVED allowlist — any origin some application already
registered a
redirect_urion. A tenant admin can write into this set, so it only ever grants reads of answers that carry no ambient authority. - May it send the SSO cookie and read the answer?
IAM_SESSION_ORIGINS, a comma-separated list of exact origins. Never a suffix, never derived from (1). A malformed entry panics at route registration, which is the one place bothiam serveand the cloud binary that embeds IAM pass through.
The [cookie] paths are exactly the five sites hanzoai/js-iam
src/browser.ts sends credentials: "include" to — POST /v1/iam/login,
GET /v1/iam/web3/nonce, POST /v1/iam/web3/verify, POST /v1/iam/oauth/revoke,
POST /v1/iam/oauth/logout. A browser DISCARDS a credentialed response that
lacks Access-Control-Allow-Credentials, so withholding it on one of them
withholds no privilege — it breaks the call. Only POST /v1/iam/login actually
spends the cookie (the single-sign-on branch mints an authorization code from
it); revoke, logout and both wallet legs never read or clear it, so the SDK's
credentials: "include" there is inert and the SDK is where that gets fixed.
logout not ending the portal session is a real open defect, not a CORS one.
IAM_TRUSTED_ORIGIN_SUFFIXES is a DIFFERENT list, read nowhere in this repo.
Never wire it to question 2: the fleet serves <slug>.hanzo.app as
customer-published sites, so a suffix read of it would name every customer page
a first-party console.
A proxy can override all of this. Measured 2026-08-01: hitting the cluster
ingress directly with Host: iam.hanzo.ai returns server: zip, Vary: Origin
and no ACAO; the same request through Cloudflare returns
Access-Control-Allow-Credentials: true plus the reflected origin. The
hanzo.ai zone reflects a suffix set (hanzo.ai, hanzo.app, hanzo.bot,
lux.network, zoo.ngo, zoo.network, pars.ai, bootno.de, ad.nexus) and
the hanzo.id zone reflects any origin. *.hanzo.ai is SAME-SITE with
iam.hanzo.ai, so SameSite=Lax does not withhold hanzo_session — that is the
reachable path. No Go change closes it; the edge rule has to be narrowed, and
this package must answer correctly FIRST or the narrowing breaks every login.
A brand org is no tenant of its plain members
Self-service signup files a new person under the app's organization (hanzo,
lux, zoo, pars), and store.MemberOrgRefs emits that as the HOME entry of
the orgs claim. Read as tenancy, that made every sign-up a signed member of
the brand: verified 2026-07-28, a minute-old account listed hanzo's private
repos and wrote its projects and CRM.
The rule that closes it (owner decision 2026-10-16) is one predicate, asked of the signed role and the row, never of the org name alone:
- An org the platform runs (
authz.IsPlatformOrg: the reserved orgs, the brands, the platform's own names, the directories) is a tenant only of its owners and admins, its machines, and a SuperAdmin. A plain member — a customer who landed there — acts in none of it. - A brand's directory (
authz.DirectoryOf:hanzo-id,lux-id,zoo-id,pars-id) is no one's tenant at all. It holds identities. - The funded customer orgs (
adnexus,bootnode,osage) are held names and ordinary tenants.
Where it is read: authz Claims.opens (so Default, Tenancy, EffectiveOrg
and LedgerOrg agree), authz Principal.MemberOf/AdminOf/OwnerOf, and here
store.Acts — the key resolver (key_not_tenant, before which a disabled holder
is key_holder_disabled), the user-key mint (403: a key filed there would act for
no one), the delegation (403), principal.Scope/ScopeRead, the org listing and
the registry's password path. The groups claim leaves out what opens nothing. The
orgs claim stays whole, because its first entry is who the person is.
Two takeover doors close on the same reading. In an org whose name is held
(authz.IsHeldOrg) an org admin is not its members' credential administrator:
users.Credentials lets only the person, a SuperAdmin or a platform application
holding the user-administration capability change another account's password,
address, phone or second factor, or file a passkey or token for it, and writes
an audit row (superadmin, credentials:<what> by <who>) for every such change
(users.Update, mfa, authz.AuthorizeUser). And a confidential client minting over
/v1/iam/tokens/issue proves itself, not the person: the token names it in
act, lives at most an hour, is audited, and is minted only for the people its
org signs in (living there or in its directory, or registered by its apps).
What a plain member of a brand org keeps: their account, and founding an org
(POST /v1/iam/onboard), which then is the first org their set opens and so the
one they act in. What is still open: signup files new people in the brand org
rather than its directory, so each new account acts in nothing until it founds
one. Moving signup, federation, code and wallet sign-up into DirectoryOf(brand)
with a personal org by membership is the directory build; the existing residents
move with it.
Onboarding an ORGANISATION — what works, and the three places it stops
Founding the org works and is the good part. POST /v1/iam/onboard (session) and
POST /v1/iam/admin/provision (service token) both drive one converge: org row +
the founder's owner membership + one <slug>/default metered credential the
founder holds; the founder's account is not moved (3 below). Driven live 2026-08-13 against hanzo.id: org created,
pk-live-…/sk-live-… returned once, roster correct.
Adding the SECOND person is where it stops, in three independent places, and only the first of them is fixed here.
1. The invite could not resolve anybody — fixed. cloud's sendInvite
(apps/team/invite.go) resolves the invitee with
GET /v1/iam/users/get?owner=<org>&email=<addr>. users/get took {owner, name}
with BOTH required and no email field at all, so every invite — of a member,
of a stranger, of anyone — answered 400 field "name" is required and the RPC
reported "no Hanzo account for in this org". A schema error wearing the
message of a business rule, which is why it read as working-as-intended and
survived. The read now takes Lookup{Owner, Name|Email} and both arms go through
store, so this surface and the login that authenticates the same address cannot
disagree about who it names. Ambiguity is REPORTED (409), never flattened to
not-found: two rows in one org can carry one address, and answering with an
arbitrary one of them is how a person joins a team under a colleague's identity.
Authorization is unchanged by construction — a REST read's target rides in the
query and authz.ReadTarget reads owner/name, so an address read authorizes
exactly like ?owner=<org> already did and discloses strictly less than the org
listing the same caller may already fetch. Ref (both halves required) still
addresses the WRITES: an address is a mutable attribute, and resolving one to
decide who gets written puts a rename between the authorization and the write.
2. The invitee has no account IN the org, and nothing can give them one.
Signup files everyone under the APP's org and refuses any other, so a teammate
who signs up at hanzo.id is hanzo/<name>, never acme/<name> — and an invite
scoped to ?owner=acme will not find them however it is spelled. add-membership
IS the working grant (measured: the invitee's next token carried
orgs:[{hanzo,member},{zzb2b1,member}] and /v1/projects with X-Org-Id then
answered 200), but it takes an identity that already exists. The invitations
entity — /v1/iam/invitations CRUD over schema.Invitation, carrying Email,
Code, Quota, UsedCount, State — is redeemed by nothing: no signup hook, no
accept endpoint, no reference outside its own package and the route table. So
there is no invite for a person who does not yet have an account, which is the
ordinary B2B case. The console's onboarding step says "Pick an organization you
belong to, or create a new one" above a form that only creates one
(id pkgs/onboarding OrgStep states this deliberately: "Joining an existing org
happens by invitation, handled outside this flow" — there is no outside).
3. Founding an org locked the founder out of sign-in — fixed: onboarding moves
nobody. POST /v1/iam/onboard, POST /v1/iam/admin/provision and cloud's
POST /v1/account/orgs each found an org beside the caller's account: org row
(Founder stamped), the caller's owner membership, and <org>/default held by the
caller. The account, how it signs in and its sessions do not change; the org
rides the next token's orgs claim and the org switch. The move these used to do
re-keyed the founder to <org>/<name>, and sign-in, which resolves an address in
the APP's org, found nobody: measured 2026-10-16 on hanzo.ai, a password user who
created an org was told "No account for this email yet" and offered a second
account, and hanzo.id answered "the username or password is incorrect". Pinned by
oidc.TestOnboard_TheFounderIsStillFoundByAddress (the identifier answers
account:false on the move) and TestOnboard_AnOrgFoundedAtTwoDoorsHasOneOwner
(founding at cloud and then at hanzo.id moved the person and left a ghost owner).
A signup at a founding application (orgChoiceMode: create, Charter) still moves
the account it just made into its personal org — claim.move — and the
registration reach (store.GetSignupByEmail) is what keeps it findable there.
Census 2026-10-16 (read-only, 520 accounts): no customer was in the moved-by-
onboarding state (two such rows, one staff and one service). 50 accounts outside
hanzo that hanzo.ai serves cannot sign in by address there for other reasons:
29 hold an address registered twice (14 addresses; ambiguity is refused), 17
carry no registration (legacy rows, staff and brand-org accounts), 4 are shadowed
by an account living in hanzo with the same address.
Brand rules (hard)
- Never call Hanzo an "LLM gateway"; never position vs LiteLLM. Full AI cloud, not a proxy.
/v1/only, never/api/. Zen models are our own family — never name upstream models.- White-label by domain; never the Hanzo mark on a Lux/Zoo surface.