iam

Documentation

Overview

Package iam folds Hanzo IAM into the unified hanzoai/cloud binary as an in-process subsystem (HIP-0106) — the LAST binary-consolidation piece: "one Go binary (hanzoai/cloud) embeds IAM + KMS + o11y".

CLEAN IAM (v2), NOT CASDOOR. This subsystem embeds github.com/hanzoai/iam — the clean-room identity rewrite on the native Hanzo stack (zip + hanzoai/orm + hanzoai/sqlite). The retired Casdoor/Beego fork (github.com/hanzoai/iam-v1) is GONE from cloud's graph: there is no beego process-global to corrupt, no InitEmbed, no session-manager hook, no shared-AppConfig co-residence hazard with the sibling `ai` casdoor fork. iamserver.Mount registers the whole IAM v2 surface (OIDC discovery/JWKS, oauth authorize/token/userinfo/introspect/revoke, get-app-login, signin, the v2 entity CRUD, and the Casdoor verb-alias compat layer) ZIP-NATIVELY onto cloud's shared app — no net/http adaptor round-trip. The specific self-service routes layered in front (account, agentskills) still win by Fiber's in-order match, so the fold is collision-free.

The store is embedded SQLite under {DataDir}/iam (server.OpenSQLite, WAL) — this embed owns its OWN orm.DB outright, so the old Casdoor-fork "ai bootstrap unable to open database file (14)" crash is gone. Config (orgs/apps/providers/signing certs) is seeded from the same init_data.json the deployment already provides (server.Seed, new-only + idempotent), so hanzo.id's OAuth/OIDC semantics are preserved.

IN-PROCESS STORE ACCESS. DB() exposes the opened orm.DB to sibling subsystems that REFLECT the IAM-owned Project resource in-process (clients/platform, clients/deploy) via github.com/hanzoai/iam/pkg/store — no HTTP hop to /v1/iam. It is nil until Mount runs (the same lifecycle the retired iam-v1 object-store global ormer had), so those callers guard a nil DB and degrade to a clean 503 until IAM is mounted.

FAIL-CLOSED, NOT FAIL-LOUD. A broken/misconfigured IAM does NOT crash the consolidated binary: an open/seed/mount failure degrades THIS subsystem to a 503 fail-closed on every IAM prefix (mountFailClosed) while every co-resident subsystem (KMS, o11y, …) stays up — the blast-radius isolation the whole consolidation exists for, mirroring the KMS "no master key → health-only" pattern.

Mounted in-process (the whole IAM v2 surface, registered at its canonical paths):

/v1/iam/*      OIDC/OAuth2 (/v1/iam/oauth/{authorize,token,userinfo,introspect,
               revoke,...}) + OIDC discovery (/v1/iam/.well-known/*) + signin +
               get-app-login + the v2 entity CRUD + the Casdoor verb-alias compat
/login/oauth/* browser authorize surface (the /v1/iam/oauth/authorize 302 target)

STAGING (security-critical): activation is the standard enable-list gate — the operator adds "iam" to the cloud deployment's --enable only AFTER the v2 config (init_data + KMS signing keys) is present and the fold is verified (login/authorize/token/jwks + the operator SSO chain). Until then hanzo.id is served by the standalone iam pod via ingress. If a broken config slips through, the subsystem serves 503 fail-closed rather than crashing cloud.

Index

• func DB() orm.DB
• func Mount(app *zip.App, deps cloud.Deps) error

Functions

func DB

func DB() orm.DB

DB returns the embedded IAM store's orm.DB for in-process readers (clients/platform, clients/deploy) that reflect the IAM-owned Project resource via github.com/hanzoai/iam/pkg/store. It is nil until Mount has run (IAM not enabled, or a boot failure that fail-closed the subsystem); callers MUST nil-guard and degrade to 503 rather than dereference it.

func Mount

func Mount(app *zip.App, deps cloud.Deps) error

Mount opens IAM's embedded store, seeds config from the same init_data.json the deployment provides (non-fatal), and registers the whole IAM v2 surface onto cloud's shared zip.App. Called once by cloud.MountAll when "iam" is enabled.