wbin90620 c1085abe4f teams: reachable by the people who run them
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
2026-11-09 03:56:12 -05:00
2026-11-08 21:53:21 -08:00

Hanzo IAM

Identity & access for the Hanzo cloud — OpenID Connect / OAuth2 with PKCE, standards only.

Go 1.26 Standards License

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/sql over ZAP.
  • datastore — hanzoai/datastore over 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

S
Description
Hanzo IAM v2 — proprietary identity service on zap-proto/zip + hanzoai/orm + hanzoai/base. Clean-room, original work.
Readme
122 MiB
Languages
Go 99.4%
Python 0.4%
HTML 0.1%
Dockerfile 0.1%