POST /v1/iam/impersonate answers a single-use login_hint, never a token.
The site starts its own OIDC sign-in with it (third-party-initiated login),
so the code is bound to the site's client, redirect_uri and PKCE, and is
redeemed at the ordinary token endpoint. Authorize honours the hint only in
a browser holding the operator's own session, and only for a client named
in IAM_IMPERSONATION_APPS (unset: none).
The token is the target's (sub, owner, name, orgs) with act {sub, owner,
name} and imp: true, at most fifteen minutes, with no refresh token. The
rule (operator is a SuperAdmin on the row; target a person in a tenant) is
asked again at the hint, the code, the token and every Guard request.
An imp token reads IAM and writes nothing: the Guard refuses its non-GETs,
self-service writes resolve nobody for it, /signin refuses its code, and an
exchange keeps the mark and the clock. act and imp ride UserInfo and
introspection. Every step and refusal is an ActionImpersonate row naming
the operator, filed under the target's org.
LLM.md records the change of stance and the contract cloud and the sites
must ship before the allow-list names them.
Claude-Session: https://claude.ai/code/session_01HvACxex9ZZTzJCCHgirsGy
7.4 KiB
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