1df516d316 oidc: an application that cannot sign names the cert it names and why (#42)
An application whose row names a cert that is not a platform signing cert
answered the token exchange with "this application has no signing cert, so
no token can be issued for it". That is wrong on its face for the case in
hanzo-inc/cloud#757: an organization adds a certificate, points its
application at it, and is told it has none. The reason is the trust
boundary in store.GetSigningCert: only certs under the reserved platform
owners sign, because only the platform holds signing keys.

signerFor now returns unsignableError. It wraps ErrNoSigningCert and names
the registration, the cert it names, and why that cert cannot sign. The
three cases are no cert, the delegation key, and a cert that is not one of
the platform's. mintError answers with that text, plus the remedy: a
platform administrator points the application at a platform signing cert.
Names are quoted within RFC 6749 section 5.2's character set and capped.
Nothing about signing or trust changes.

Testing: internal/oidc/unsignable_test.go fails on the previous token.go.
The full internal/oidc package passes, and internal/oidc and server pass
under -race. CI test-amd64 is green.
Risk: low. Only the error_description of an already-failing 500 changes.
How to revert: git revert this commit.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-11-19 13:26:00 -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 legacy surface, no Beego, no xorm. The identity binary owns its source outright and collapses to one way of doing each thing. The retired legacy 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).

Quickstart (Run Locally)

Requires Go 1.27+ and openssl. Signing key material is deliberately never stored in SQLite (schema.Cert.PrivateKey is json:"-"), so local dev mounts one RSA PEM in IAM_SIGNING_KEYS matching the seeded cert name:

git clone https://github.com/hanzoai/iam && cd iam

# 1. Generate a local dev signing key and minimal seed config (gitignored under .dev/)
mkdir -p .dev/keys
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out .dev/keys/cert-dev
cat > .dev/init_data.json <<'EOF'
{
  "organizations": [{"owner":"admin","name":"hanzo"}],
  "certs": [{"owner":"admin","name":"cert-dev","cryptoAlgorithm":"RS256"}],
  "applications": [{"owner":"admin","name":"hanzo-dev","clientId":"hanzo-dev","organization":"hanzo","enablePassword":true}]
}
EOF

# 2. Boot local OIDC + JWKS on 127.0.0.1:8000 (SQLite in data/iam.db)
IAM_DEV_HOST_RELATIVE=1 IAM_SIGNING_KEYS=.dev/keys \
  go run . serve \
  --http http://127.0.0.1:8000 \
  --zap 127.0.0.1:19653 \
  --init-data .dev/init_data.json

Verify from a second terminal:

curl -sS http://127.0.0.1:8000/.well-known/openid-configuration
curl -sS http://127.0.0.1:8000/v1/iam/.well-known/jwks

hanzoai/cloud defaults CLOUD_IAM_ISSUER=http://127.0.0.1:8000 (with ZAP on :9653, which is why the snippet above binds IAM's ZAP port to 19653 when running both on one machine). See the full Self-Hosting & Air-Gapped Deployment Guide.

Stack

Concern Component Notes
HTTP hanzoai/zip Typed zip.Get[In,Out] handlers on the 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 hanzoai/zap 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 config + serve OIDC / login (SQLite by default; requires $IAM_SIGNING_KEYS and either $IAM_ISSUER or IAM_DEV_HOST_RELATIVE=1)
IAM_ISSUER=https://iam.example.com IAM_SIGNING_KEYS=/etc/iam/keys go run . serve --init-data /etc/iam/init_data.json

# ZAP-native persistence instead of embedded SQLite
IAM_ISSUER=https://iam.example.com IAM_SIGNING_KEYS=/etc/iam/keys go run . serve --store datastore --init-data /etc/iam/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 LLM.md for architecture details and the full RFC surface.

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 · Self-Hosting Guide

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%