Files
iam/LLM.md
wbin90620 f2cc8e2f43 Merge branch 'main' of https://github.com/hanzoai/iam into feat/agent-auth
# Conflicts:
#	LLM.md
#	internal/oidc/oidc.go
#	pkg/schema/audit_log.go
2026-11-09 12:55:01 -05:00

115 KiB
Raw Permalink Blame History

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/oauth/agent/identity (WorkOS auth.md service_auth, "Agent registration" below) · /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 say iss=https://hanzo.id (TestFederation_SigninHostRunsTheLegAndKeepsTheIssuer redeems on hanzo.ai and fails if tokenIssuer ever 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 runs strategy: Recreate).
  • Off its issuer's host, authorize never answers silently from a session: that origin holds its own __Host-hanzo_session, so the page asks "continue as" and prompt=none is login_required. A navigating sign-out on either origin visits the other and ends the same sessions there (see "Several accounts on one browser"); a program's JSON POST to logout ends only the origin it reached.
  • 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 (universe charts/app/values/hanzo/cloud.yaml iam-signin) and serve /login/mfa and the hosted login (/login/oauth/authorize) as pages.
  • In cloud, zip.Ctx.Host() honours X-Forwarded-Host (TrustProxy, private ranges trusted; the ingress sets it before an api-host rewrite), so the "header-immune" wording elsewhere in issuer.go, token.go and webauthn.go is true of iam serve only. A caller can still only select a configured value, for its own requests.

Several accounts on one browser — chosen, switched, signed out one at a time

The session cookie holds one signed session per person (internal/sessions, joined by ~, current first). Five rules sit on top of it:

  • Nobody is guessed. signedIn (prompt.go) answers the one account the request names (login_hint, id_token_hint), or the ONE account the app can serve. Several and none named is many: authorize forwards the hosted page prompt=select_account, and prompt=none gets account_selection_required (OIDC Core §3.1.2.6). The most-recent-sign-in fallback is gone: it is how a CLI sign-in on a shared browser completed as the wrong account.
  • The session branch of POST /v1/iam/login keeps the authorize request's word. A page's credential-less resume carries prompt and loginHint (body or query). prompt=login is refused login_required; select_account without a chosen loginHint, or several accounts and no hint, is refused account_selection_required (CodeAccountSelectionRequired); a loginHint answers only that account. type=device approves as the account its loginHint names (the one the approval page showed), else the current one.
  • What authorize demanded is kept by the server (demand.go). Handing a request to the hosted page records a LoginChallenge of kind prompt, named by sha256(client, redirect, state, PKCE challenge), holding prompt=login, select_account (or several-accounts-none-named) and max_age, for 30 minutes. The session branch and a silent re-entry of the same request both read it, so a page that forwards nothing (hanzo.ai's resume did, for the CLI) is held to it: login is met only by a sign-in made after the request's second, choose only by a named account, max_age by freshEnough. A store fault refuses. A page that alters any of the four values gets a code no client asked for.
  • auth_time moves only on a proof. sessions.Open(..., proved): a credential shown again for a held person restamps their session's auth_time (same sid); a resume (resumeGrant) does not, so a resume cannot launder an old sign-in past max_age or prompt=login.
  • Switch: PUT /v1/iam/accounts {"current":"<sub>"} moves an account already signed in here to the front (sessions.Switch, same sid and auth_time) and answers the list. Same-origin JSON only (Forgeable, checked before the lookup, so another page learns nothing). Each session still resolves to its own row, so no org, role or SuperAdmin standing crosses accounts (TestAccounts_SwitchCarriesNoStandingAcross). A page holding a bearer for the old account must drop it on switch.
  • Sign out one: end-session with logout_hint (RP-Initiated Logout §2: sub, address or username) ends every account it names and no other (sessions.End): an address two orgs share names both, so a SuperAdmin admin/alice is never the one left behind. A hint naming nobody here ends nothing. No hint ends every account (sessions.Clear).
  • Sign out on every sign-in origin: a navigating end-session walks the issuer and every origin IAM_FEDERATION_ORIGIN_MAP names for it, sorted, once each (nextSignout, chain=<origin it started at>~<MAC over the session key>; an unsealed chain is no chain, so a crafted link cannot skip an origin; the issuer is compared in sign-in-origin spelling, so :443 is not a second stop), carrying id_token_hint, client_id, post_logout_redirect_uri, state, logout_hint, everywhere. The last hop validates and returns the browser. Each origin must route /v1/iam/oauth/logout to IAM (hanzo.ai does, infra/sites).

Where the chooser renders is the hosted page's job: the id SPA's Login phase choose. hanzo.id's edge sends /login/oauth/authorize with a state to hanzo.ai/login (universe infra/sites/sites.yaml, route hanzo-id), and hanzo.ai's panel resumes for a loopback platform client without reading prompt; that is why a prompt=select_account CLI sign-in completed silently in production. The session-branch rules above refuse that resume when several accounts are signed in or when the page forwards prompt.

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-codes filed for NOBODY under the app's org (applicationId admin/<app>), spent by otp.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 phone store.NormalizePhoned. schema.ActionAddress (PlatformWritten) is written in the same transaction, object {client, field}, never the address or the code.
  • GET /v1/iam/auth/methods says address: true exactly 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/iam 0.21.37 reads it as methods().address. code says a code can be sent, by either channel; whether the org's notify holds a text credential is notify's fact (KMS orgs/<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 admin confers nothing. Not Sudo, and not MemberOf/ 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/z with an admin membership is an ordinary hanzo account; admin/z is 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 spelled Admin/ADMIN/aDmin/admiN (onboarding slugifies, the CRUD refuses the shape, sign-in resolves the org verbatim), but a SuperAdmin's POST /v1/iam/users stored Admin/<name> and ac/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 admin is never SuperAdmin — User.Type service-account or application. admin/provisioner is declared type: service in 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 in admin, machines included, nor a name nobody holds yet) and users.Authorize (only a SuperAdmin writes an account in admin). Both read the owner as written; resolving a name folds its case and never its org.
  • groups is membership, not SuperAdmin. The claim still lists every org a person belongs to, so admin appears for a brand org's member of it. Two relying parties read it as platform authority: the forge (--admin-group admin, universe hanzo-git.yaml) and Hanzo CD (hanzocd-rbac-cm.yaml). Moving them to orgs[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/upsert with owner: 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.ActionSuperAdmin row (method, URI with query, status, client IP, actor), filed under admin; so are a SuperAdmin's unlink of someone else's sign-in method and a device approval into another org. The action is PlatformWritten: 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:

  1. 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 a LoginChallenge of KindImpersonate: single-use, 5 minutes, subject = target, payload = operator + client + reason.
  2. The site's OIDC Core §4 initiate-login endpoint gets iss + login_hint and starts its OWN authorization request (its state, nonce, PKCE S256) carrying that login_hint.
  3. authorize answers the impersonation: 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 through MintFor, with Actor/Reason on the schema.Token row. A refusal is an OAuth error on the site's registered redirect_uri.
  4. The site redeems at /v1/iam/oauth/token as always. issueTokens sees row.Actor, re-asks the rule, sets act {sub, owner, name} and imp: true on the access token AND the id_token, caps life at min(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, orgs and the Guard's principal resolve from the target row, and an imp principal is never Sudo. Nothing of the operator's rides along — the opposite of assume, which refuses an imp bearer.
  • It READS IAM and never WRITES it. The Guard answers any non-GET with an imp bearer 403, and callerOf/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) use readerOf. A key or passkey minted in the window would outlive it.
  • It lives only while its operator may impersonate: oidc.Operator is re-asked by the Guard on every request, by UserInfo, the account reads, introspection (active:false once it fails) and an exchange.
  • /v1/iam/signin refuses an impersonation code without spending it: a session at the issuer would outlive the token and carry no mark. PlatformBearer already refuses any token with act.
  • An RFC 8693 exchange of an imp subject_token carries act/imp forward and dies no later than its subject.
  • It does not chain: an imp bearer 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 read Organization.Founder to 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.

Where the person opens the link (verificationOrigin, device.go). The device response's verification_uri and verification_uri_complete are on the origin of the application's signinUrl when that origin is a sign-in origin the operator configured for the request's issuer (IAM_FEDERATION_ORIGIN_MAP values whose host resolves to the same issuer), else on the issuer. The application says, the operator decides: signinUrl is a field an organization writes for its own applications, so it can only select among configured origins, and an origin of another brand (a host the issuer map folds elsewhere) is refused exactly as the boot check refuses a map that would send one there. Only an application the platform declares (Application.Platform, SuperAdmin-written) is sent there: the approval page shows the application's name, which its registrant chose, so a tenant's application keeps the issuer's page rather than borrow the brand's standing for a name of its own choosing (device/info also says platform and organization, so the page can say whose it is). Only the origin is taken; the page is /login/oauth/device[/<userCode>] on it. Discovery, the issuer and the token and JSON endpoints do not move. Declared per app in the provision document (signin: -> upsert signinUrl, a pointer: omitted preserves, "" clears), so it moves the app's hosted-login page too (hostedLoginTarget reads the same field). Deny is POST /v1/iam/login {type:"device_deny", userCode}, a verb of its own on the approval's own seam (session, same-origin JSON via sessions.Writer, loginHint, tenant boundary). The flag deny is READ too, on any device body: a body that says deny is a refusal and never an approval (the page's first spelling, {type:"device", deny:true}, is still sent by stale tabs; ambiguity fails to the side that signs nobody in). Approve, refuse and the poll's burn decide on the row as the lock holder reads it (store.WithToken: GetForUpdate), so one outcome stands and a request is minted once; pending is the one live-code predicate. The device's next poll is access_denied once, then expired_token. What a stranger may ask (device_guard.go): the start needs no credential, so the scope is pinned (grantedScope: the application's declared scopes, else the standard OIDC set; openid admin kms:write * is openid; past 2048 bytes is invalid_scope), the start is budgeted per client and per address (429 slow_down; in-process, a brake not a meter), unapproved expired rows are swept (PurgeDeviceCodes, a batch a minute), and a pending poll sooner than 4 s after the last is slow_down. The row records where it was started (RequestIp from CF-Connecting-IP via httpx.Client, never a client-written XFF hop; RequestCountry from CF-IPCountry; Requested), and device/info shows that and the pinned scope beside the application's name, so a person approving a stranger's request can see it is a stranger's. Wrong codes are counted per account (deviceMisses, 10 per 15 min, logged once): past it every answer is the one opaque refusal. That refusal also covers a code that is live but not the caller's tenant. mayApprove: a SuperAdmin crosses tenants only for Platform applications. TTL is 10 min. On the brand's own site the code rides the URL FRAGMENT (verification_uri_complete = <origin>/login/oauth/device#<code>), which reaches no server, log, Referer or CDN analytics; the issuer's own SPA keeps the path form. signinUrl is validated on create and update (schema.CheckSigninUrl) and authorize follows it only to an origin IAM signs people in at (hostedLoginTarget), else the default hosted login.

Agent registration — an agent names its person, and becomes a service account in their org

WorkOS's auth.md profile (github.com/workos/auth.md), service_auth ONLY (internal/oidc/agent.go). Cloudflare's Agent Readiness scan reads the AS metadata for an agent_auth block; this is what puts one there, for an issuer configured to offer it.

POST /v1/iam/oauth/agent/identity   {"type":"service_auth","login_hint":"[email protected]"}
  → registration_id reg_…, claim_token clm_… (once; the row holds its SHA-256),
    claim {user_code, verification_uri(_complete), expires_in 600, interval 5}
person: /login/oauth/device, signed in, types the code   (POST /v1/iam/login type=device)
POST /v1/iam/oauth/token  grant_type=urn:workos:agent-auth:grant-type:claim  claim_token=…
  → authorization_pending | slow_down | access_denied | expired_token, then once:
    access_token (1h), identity_assertion (typ oauth-id-jag+jwt, 7 days), no refresh
POST /v1/iam/oauth/token  grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer  assertion=…
  → a fresh access token, for as long as the assertion lives and the account exists

A registration is a device row with another key. The same schema.Token row (Code, UserCode, store.WithToken for every decision, the same sweep and the same approval page), marked by its NAME (ag-<registration id>): isDevice is false for it, so the device poll never redeems a claim token's row and the claim poll never redeems a device row (isAgent), and asksPerson keeps both out of the authorization-code grant. The row adds LoginHint. Device info answers agent: {registration, organization} so the page can say what approving does.

Who approves (mayClaim, asked at the page AND again at the claim): the account whose VERIFIED email is the login_hint (case-insensitive), not a machine, home org not reserved, and allowed to create a service account there — serviceaccounts.MayAdminister, the gate POST /v1/iam/service-accounts applies, so approving makes nothing the person could not make there. Anyone else gets the device page's one opaque refusal, counted against their miss budget like any wrong code.

What the claim makes, once (the burn is under the row lock): a service account in the APPROVER's home org (serviceaccounts.Enroll: the row create writes, no sk- key), named <org>-agent-<first 8 of the registration>, Tag = the registration id; the row's User becomes that account; an agent-claim audit row (PlatformWritten) names the approver. The access token is the account's user token (identityOf + SignUserToken, owner and organization = the account's org), so a resource server reads a principal of that org whose billing_account is the org pool — cloud bills it to the org. azp/aud = the agent application. The assertion's sub is the registration and it carries no tokenType, so no IAM verifier takes it as a bearer.

Revoking is deleting the account (DELETE /v1/iam/service-accounts/:name): every exchange re-reads the registration and the account (exists, service-account type, Tag = registration), so the assertion is dead at once. Access tokens already minted live out their hour, as any token does.

jwt-bearer is shared with the workload grant. agentAssertion reads the assertion unverified: typ oauth-id-jag+jwt AND iss = this request's issuer goes to the agent path; anything else goes to workloadGrant untouched. Discovery lists jwt-bearer wherever either can be exchanged.

Configured per issuer, both or neither (judged at boot, server.RequireIssuer → CheckAgentAuth):

IAM_AGENT_SKILL_MAP  {"hanzo.id":"https://hanzo.ai/auth.md"}   issuer HOST → its auth.md
IAM_AGENT_CLIENT     hanzo-agents                              the app agents register through

An issuer with no entry advertises no agent_auth, no claim grant, and answers service_auth_not_enabled. The application must be admin-owned, declare urn:workos:agent-auth:grant-type:claim, serve a tenant, and NOT be Platform: a Platform application's bearer passes PlatformBearer (accept an invitation, start a provider link), and an agent's token is issued to this application. Withdrawing the grant ends every claim and exchange through it.

Budgets (in-process, as the device's): 20 registrations an hour per address, 6 per login_hint; past either, 429 rate_limited with Retry-After.

Deliberately not implemented, and not advertised: anonymous (anonymous_not_enabled: a principal nobody vouches for, spending nobody's money), identity_assertion (issuer_not_enabled: there is no trust list of agent providers), events_endpoint (only identity_assertion has an upstream to hear from), claim_endpoint (anonymous only; the re-ceremony it would give service_auth after an expired code is a fresh registration here). The user_code is the device grant's 8-symbol code, stored as the device's is, not the profile's 6 digits: the page normalizes to that alphabet, and 0/1 do not survive it.

Dynamic client registration — how an MCP client gets a client_id (RFC 7591)

POST /v1/iam/oauth/register (internal/oidc/register.go). Claude.ai, ChatGPT, Codex, Cursor, VS Code and the rest add https://api.hanzo.ai/v1/mcp, read its protected-resource metadata, find this issuer, and register here before running the ordinary authorization-code flow with PKCE. Advertised as registration_endpoint in both discovery documents, and only where it is served.

Off unless the deployment says so: IAM_REGISTRATION={"organization":"hanzo","signinUrl":"https://hanzo.ai/login","providers":"hanzo-app"}. Unset or unreadable, the route does not exist and discovery does not mention it. organization owns every registered client and signs its tokens (cert-<org>); signinUrl is where authorize hands the request, and it is followed only on an origin in IAM_FEDERATION_ORIGIN_MAP for the issuer. A registration is refused (503) where that is not so, because the client would land on the issuer's page instead of the brand's. providers names the application whose social sign-in methods (Google, GitHub, ...) a new client is given, copied as sign-in only (no sign-up, no unlink) so a person who signs in that way on the brand's page can do so for a client.

  • What it registers: a PUBLIC client (token_endpoint_auth_method answers none whatever was asked; the response says so), authorization_code + refresh_token, the scopes openid profile email offline_access narrowed to those asked, redirect URIs that are https on a named public host or http on 127.0.0.1/[::1]/localhost (max 5; no custom scheme, wildcard, fragment, userinfo or IP-literal https host). Owned by the configured org, IsShared (it serves any of the issuer's people), Platform false, tagged schema.TagDynamic; ExpireInHours 1, RefreshExpireInHours 720.
  • Idempotent: client_id is mcp- + a digest of the registered metadata, so a hosted client whose every user registers the same name and callback is one row, and a repeat creates nothing and counts against nothing. A loopback client with a fresh port each run is a new row.
  • Bounded: new clients per address (20/h) and per network (a /24 or /64, 100/h), counted from the audit ledger in the transaction that writes the row; 429 with Retry-After. Every created client is an audit row (register-client, schema.PlatformWritten) naming the client, the address, and where it sends a code.
  • Untrusted until a person says otherwise. Nobody vetted it and the address it chose is where the code goes. So it is never answered from a session: authorize forces prompt=login (prompt=none is interaction_required) and the login resume refuses it, whichever door the request came through (a link straight to the sign-in page never runs authorize). MintCode (the one constructor of a code row, so the federation mint too) clamps the grant's scope to what it registered. DisplayName is <client_name> (<host>), the host its code returns to. SuperAdmin cannot authorize one (reserved-org confinement).
  • Not built: RFC 7592 client management (no registration access token, no delete over the wire; delete a row with the applications API), a consent screen (the sign-in is the consent, and the page shows the name with its host), a janitor for clients that never completed a sign-in (growth is bounded by the cap), CIMD (clients identified by a URL the server fetches).
  • The aud of a code-grant access token is the client's id, as for every application; the resource an authorize request carries rides the code and the refresh but is not applied to aud. Resource servers here trust issuer + signature (cloud does not gate on aud).

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".

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 site WebsiteUrl (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/app public/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 is hanzo, 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: dark block 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.html is the mail as sent; go test ./internal/otp -run Snapshot -update rewrites 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 says autocomplete="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) then data: "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, Charter founds the personal org like provisionFederatedUser), record schema.Terms (versions, time, method email-code, IP), then afterFirstFactor — the one minting tail.
  • PUT /v1/iam/terms (caller-scoped) records the same for a federated first sign-in, method signed-in. The record lives in the preferences blob under terms; the preferences merge refuses the key and Update carries 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:

  1. 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 bearer PlatformBearer accepts: an access token issued to an application init_data.json declares under admin (schema.Application.Platform; hanzo-console, hanzo-app, hanzo-ai, lux-cloud, … are). Any other application's bearer is 403 ErrNotPlatform. It answers <sign-in origin>/v1/iam/link?state=<t> and sets no cookie.
  2. GET /v1/iam/link?state=<t> — PRESENCE. A top-level navigation from a browser holding that person's session here (signedInHere). It spends t, mints the provider-leg transaction (fresh state, nonce, PKCE) and sets __Host-hanzo_fed on this navigation, as authorize does for a sign-in, then 302s to the provider. The callback refuses t itself: 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 social SIGN-IN resolves its account in linkOrProvision (internal/oidc/federation.go): the provider subject, else the one account holding the address, else a new account. An existing account is opened only when the provider vouches for it (vouches): a provider filed under a reserved org (every production provider is admin/provider-*) may open any account outside a reserved org; a tenant's provider only accounts of its own org, never a held org's. The address links when the provider verified it, however the account was made and whatever its own EmailVerified; the link sets the subject and EmailVerified and nothing else (password, sessions, other methods, org, roles stay). It is resolved, not written: federationMint writes it after the account state and second-factor gates, re-checking the row under its lock, with the schema.ActionFederationLink audit row appended first. Refused (errAddressHeld): an address the provider did not verify, an account the provider does not vouch for, an account holding another subject of that provider. Two accounts on one address, in either reach or across both, is store.ErrEmailAmbiguous. The lookups never read a reserved org, so an admin account is never linked this way. Pinned by TestFederation_Links*, federation_trust_test.go.

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. createDIDFor is registrar-only while addVerificationMethod/addService are controller-only, so one key does all three only by creating documents controlled BY ITSELF. IAM is that controller. changeController hands 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 address plus a bytes32, 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's registry.json (0xB0B3Df1E27…) reports no code on any live Lux chain and names an AMM router on testnet 96368; DEPLOYMENTS.md records different addresses again, and those disagree with the per-chain deployment records. Verify with eth_getCode against 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's did claim 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.go route 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. offerable shows Apple only when appleKey holds: 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 \n is 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 email requires response_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_fed is 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.Open sets 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 in FederationState.Reply, and answers 303 to callback?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 a code, error or user past 512, 256 or 1024 bytes (replyLimits) is refused, never cut.
  • Federation rows are swept on write. Begin, link and handoff all write through persist, whose sweep takes up to 100 rows that expired more than fedStateTTL ago (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. expireIn is 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_verified as bool or string. The user form 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/callback for hanzo.id and every iam-signin host. The seed creates providers new-only, so a live row's credentials are written with PUT /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:

  1. May it read? The DERIVED allowlist — any origin some application already registered a redirect_uri on. A tenant admin can write into this set, so it only ever grants reads of answers that carry no ambient authority.
  2. 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 both iam serve and 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.

Web3 verify-signature (cloud#464)

  • This checkout (hanzoai/iam) has no idp/web3onboard.go; native wallet flow is internal/wallet (GET /v1/iam/web3/nonce, POST /v1/iam/web3/verify).
  • verify.go parses CAIP-122 signed message, burns single-use server nonce (10m TTL, burn() via GetForUpdate), checks domain/chain, calls VerifyProof (EIP-191 VerifyEVM recovers signer and compares case-insensitively to claimed address), identity is recovered res.Address, never body.
  • Fixed store.go:burn/first to use orm.IsNotFound (backend returns db.ErrNoSuchEntity/sql.ErrNoRows, not orm.ErrNotFound) so unknown nonce correctly yields opaque web3: nonce invalid, already used, or expired instead of leaking db: no such entity.
  • Added internal/wallet/attack_test.go: empty payload, forged address/no signature, valid signature by different key, replayed nonce, expired nonce, unknown nonce, happy path with real secp256k1 key.
  • Test output: ok github.com/hanzoai/iam/internal/wallet 3.291s (full ./internal/wallet/...), vet clean.