waitlist-guard

Overview ¶

admin-guard is the single forward-auth gate that restricts Hanzo's RAW global-admin surfaces (platform.hanzo.ai, studio, commerce-admin, the raw KMS admin UI, the IAM management UI) to GLOBAL ADMINS ONLY — an IAM user whose org (`owner`) is the admin org (IAM `IsGlobalAdmin`: owner == AdminOrg).

It is consumed by hanzoai/ingress (the edge router) as a ForwardAuth middleware: the ingress forwards each request's headers to GET /__guard/verify and enforces the verdict.

verdict 2xx  → allow (caller is a global admin)
verdict 302  → redirect (caller is a non-admin → console.hanzo.ai;
               or anonymous → IAM PKCE login)

One gate, one mechanism, every admin surface. Clients never reach a raw admin or a 403 dead-end: a non-admin is always sent to the unified client surface, console.hanzo.ai.

Identity resolution is decomplected into three orthogonal sources, tried in order, all collapsing to one predicate (owner == AdminOrg):

1. the guard's own signed session cookie (set after a prior PKCE login) — the browser fast path, shared across *.hanzo.ai via a parent-domain cookie;
2. a Bearer / Basic JWT validated through the edge (the API path) — the JWT already carries `owner`, so no IAM round-trip is needed;
3. an IAM session cookie, resolved by calling IAM get-account server-side (the path for a browser that has an IAM session but no guard cookie yet).

The login flow is standard OAuth2 Authorization-Code + PKCE against IAM (client_id default `hanzo-admin-guard`), mirroring oauth2-proxy.