The teams surface answered no one. Its inputs name no organization (it
comes from the credential), and both authorization layers decide on the
organization a request names: the Guard read an empty target for every
team read and refused it, and the op seam refused every team write on its
empty decoded owner. A SuperAdmin passed both, then reached a handler that
asked principal.Scope for an org and got "", so it 400'd.
Reads: /v1/iam/teams and /v1/iam/teams/{name} are handler-authorized, and
the handler asks principal.ScopeRead, as the workspace list does. A member
reads their org's teams; a stranger is refused.
Writes: a typed input may now declare AuthzScope, which resolves its
target through principal.Scope (the org it names, or the caller's own).
The seam decides that org, and the handler calls the same method, so the
org authorized is the org written. An org admin, or an admin by
membership naming the org, may create, update and delete; a member or a
stranger is refused. A SuperAdmin names the org, or gets a 400.
Ref, Input and ListInput gain an optional owner. Paths are unchanged.
Refs hanzoai/iam#23
Hanzo IAM
Identity & access for the Hanzo cloud — OpenID Connect / OAuth2 with PKCE, standards only.
Hanzo IAM is the identity service behind every Hanzo sign-in: OpenID Connect
discovery, the authorize + token endpoints (authorization code + PKCE, refresh,
client_credentials, RFC 8693 token exchange), UserInfo, JWKS, SCIM 2.0
provisioning, MFA / WebAuthn, service accounts, and social federation
(Google, GitHub).
It is a clean-room, native rewrite on the Hanzo stack — zip over
hanzoai/orm, no the legacy surface, no Beego, no xorm. The identity binary owns its
source outright and collapses to one way of doing each thing. The retired
the legacy surface/Beego fork lives at
hanzoai/iam-v1, private and archived, and is out of every graph.
Clients never hand-roll OAuth. They authenticate through the @hanzo/iam
SDK against the endpoints below — one way, no legacy paths (HIP-0111).
Stack
| Concern | Component | Notes |
|---|---|---|
| HTTP | zap-proto/zip |
Typed zip.Get[In,Out] handlers on the zap-proto/fiber/v3 engine; specificity routing; OpenAPI 3.1 at the edge |
| Storage | hanzoai/orm |
Typed Go records + KV cache over one orm.DB abstraction. Embedded SQLite by default (hanzoai/sqlite, pure-Go, WAL) — never Postgres |
| OIDC / OAuth2 | in-tree | RS256 today; ML-DSA-65 hybrid JWT + real JWKS from the Cert entity. No external OIDC library |
| Password verify | internal/cred |
Algorithm resolved from the stored row — argon2id + bcrypt, verify-only, fail-closed |
| Authorization | hanzoai/authz |
One canonical policy engine, called over ZAP RPC |
| Inter-service | zap-proto |
Binary RPC service↔service. HTTPS is the external edge only |
Endpoints — RFC / OIDC standard (no /api/, no vendor verbs)
The HTTP contract is RFC/OpenID-standard only. There are no legacy verb aliases
(get-users, add-user, issue-user-token, …) and no /api/ prefix — /v1/
throughout. Paths are relative to the brand serverUrl.
| Capability | Standard | Endpoint |
|---|---|---|
| Discovery / AS metadata | RFC 8414 · OIDC Discovery | /.well-known/openid-configuration |
| JWKS | RFC 7517 | /v1/iam/.well-known/jwks |
| Authorize | RFC 6749 (code + PKCE S256) |
/v1/iam/oauth/authorize |
| Token | RFC 6749 (code, refresh, client_credentials, password) |
/v1/iam/oauth/token |
| Token exchange / on-behalf-of | RFC 8693 | /v1/iam/oauth/token (grant_type=…token-exchange) |
| Introspection / revocation | RFC 7662 / RFC 7009 | /v1/iam/oauth/{introspect,revoke} |
| UserInfo (account claims) | OIDC UserInfo | /v1/iam/oauth/userinfo |
| Logout | OIDC RP-initiated logout | /v1/iam/oauth/logout |
| Identity provisioning | SCIM 2.0 (RFC 7644 / 7643) | /v1/iam/scim/v2/Users |
| Social sign-in / federation | OIDC/OAuth2 Relying Party | /v1/iam/oauth/authorize?provider=<name> → /v1/iam/oauth/callback |
| Wallet sign-in / linking | CAIP-122 · EIP-4361 | /v1/iam/web3/nonce → /v1/iam/web3/verify |
| Disconnect a sign-in method | — | /v1/iam/unlink |
A wallet linked here rides on every token as wallets —
[{"chain":"evm","address":"0x…"}], the addresses whose CAIP-122 proof IAM
verified — beside did, the account's did:lux:<subject> identifier derived
from sub. UserInfo answers with both, read fresh. Neither is proof of PRESENT
control: the assertion is as fresh as the token, so anything authorizing a
payment takes its own signature. LLM.md has the derivation, the unlink rules,
and the optional on-chain anchor.
PKCE S256 always; client_secret_basic; scopes openid profile email.
client_id is <org>-<app> (globally unique); redirectUris must be the
framework's exact callback.
Brands (set serverUrl): hanzo → iam.hanzo.ai · lux → lux.id ·
zoo → zoo.id · bootnode → id.bootno.de · pars → pars.id. Shared infra
white-labels by domain — never the Hanzo mark on a Lux or Zoo surface.
Storage — one orm.DB, backend-pluggable
Every handler and the drift tool are written once against orm.DB, never a
driver. Pick the backend at boot with --store:
sqlite(default) — embedded, pure-Go, WAL. No Postgres.sql—hanzoai/sqlover ZAP.datastore—hanzoai/datastoreover ZAP (ZAP-native persistence + snapshots, zero code change).
Build & run
go build ./...
# Seed real config + serve OIDC / login (SQLite by default)
go run . serve --init-data init_data.json
# ZAP-native persistence instead of embedded SQLite
go run . serve --store datastore --init-data init_data.json
# Read-only v1 → v2 drift report (needs a `-tags migration` build)
go run . compare --legacy postgres://…/iam
go run . version
serve flags: --store (sqlite|sql|datastore), --db (SQLite path),
--zap (ZAP listen), --http (HTTP edge), --init-data (new-only seed;
${VAR} expands from env). Deploy env: IAM_ISSUER=https://<brand-id>;
the on-behalf-of (token-exchange) allow-lists IAM_TOKEN_EXCHANGE_APPS and
IAM_ADMIN_TOKEN_EXCHANGE_APPS, matched by the globally-unique client_id;
IAM_IMPERSONATION_APPS, the sites a SuperAdmin may open signed in as a person
(POST /v1/iam/impersonate; LLM.md "Impersonation"), by client_id, unset = none;
and the credential-administration capability IAM_KEY_MINT_ALLOWED_APPS,
matched by application name (distinct from token exchange, so exchanging tokens
does not grant the capability).
The service is embeddable via server.Route and builds on Hanzo CI
(ghcr.io/hanzoai/iam).
Client auth (HIP-0111)
Authenticate only through @hanzo/iam against the canonical OIDC endpoints —
no hand-rolled OAuth, no genericOAuth({discoveryUrl}), no per-app path strings,
no legacy paths. SDK subpaths cover every runtime: @hanzo/iam/server
(validateToken / getServerSession), @hanzo/iam/betterauth,
@hanzo/iam/nextauth, @hanzo/iam/react + @hanzo/iam/browser (SPA PKCE),
@hanzo/iam/passport. Keep originFrontend empty in prod so discovery is
host-relative.
Status
OIDC/OAuth2 core is live and tested end to end (login → PKCE code → token → JWT):
discovery + JWKS, credential login (argon2id / bcrypt), the token endpoint,
introspection / revocation, UserInfo, RFC 8693 token exchange, SCIM 2.0
provisioning, and Google / GitHub federation. Current release line: v1.33.x.
See MIGRATION.md for the phased plan and the full RFC surface
table.
License
Dual-licensed under MIT or Apache-2.0 at your option, as the OSS core tier of HIP-0130.
Hanzo — the Open AI Cloud
Open source · every language · on-chain settlement. hanzo.ai · docs.hanzo.ai
SDKs in every language — Python (flagship) · TypeScript · Go · Rust · C++ · Swift · Kotlin · umbrella