Documentation
¶
Overview ¶
Package iammiddleware is the gateway-trust shim for legacy call sites. It used to do JWKS fetch + JWT validation in-binary (293 LOC). That trust boundary is now hanzoai/gateway: gateway validates the JWT, populates X-Org-Id / X-User-Id / X-User-Email, and only gateway-routed traffic reaches commerced.
This file preserves the public API the rest of commerce depends on (Init, InitKV, Client, IAMTokenRequired, IsIAMAuthenticated, GetIAMClaims, GetIAMTier) so the 13 call sites compile, but every function reads identity from the gateway-supplied headers via pkg/auth.
Deletion target: once all call sites migrate to pkg/auth + pkg/org, this file can be removed wholesale.
Index ¶
Constants ¶
const HeaderRoles = "X-Roles"
HeaderRoles is the canonical comma-joined role-name header set by the gateway from the JWT roles claim. Empty value -> no roles.
const HeaderUserIsAdmin = "X-User-IsAdmin"
HeaderUserIsAdmin is the gateway-minted "true"/"" superadmin flag. Only "true" (case-insensitive) is treated as admin; any other value (including absent) fails closed to false.
const HeaderUserPermissions = "X-User-Permissions"
HeaderUserPermissions is the canonical gateway-minted permission header. It carries the bit.Field value as a base-10 int64 string (e.g. "3" for Live|Test). The gateway MUST set it from the validated JWT roles/claims; commerced reads it as-is. Missing or malformed values fail closed (zero permissions). Documented in HEADERS.md.
Variables ¶
This section is empty.
Functions ¶
func Client ¶ added in v1.39.1
Client returns the initialized IAM client, or nil if IAM is disabled or Init() has not been called. Consumers outside the middleware chain (e.g. SPA handlers with their own auth gate) use this to validate bearer tokens against the same JWKS the /v1 middleware uses. Fail-closed: a nil return means "treat every request as unauthenticated".
NOTE: returns nil unconditionally on this build — the legacy IAM JWKS client has been retired in favor of gateway-trusted headers. SPA call sites that still call Client() get a nil and fall through to their own header-based identity path. Wire a real client back in here if a non-gateway entry point ever needs JWKS validation again.
func GetIAMClaims ¶
GetIAMClaims returns a non-nil *auth.IAMClaims populated from the gateway-minted identity headers. The gateway validated the JWT and stamped X-Org-Id, X-User-Id, X-User-Email, X-User-IsAdmin, X-Roles (see hanzoai/gateway/auth_middleware.go). commerced trusts those bits and reflects them into a claims struct so call sites can read IsAdmin / Owner / Subject / Roles uniformly.
Fail-closed contract: missing headers map to zero-valued fields. In particular, missing X-User-IsAdmin yields IsAdmin=false (not "unknown"). Call sites MUST NOT nil-guard the return — it is always non-nil.
The legacy in-test path stores a *auth.IAMClaims under the "iam_claims" gin key; that wins when present so tests can inject arbitrary claim shapes without going through HTTP.
func GetIAMTier ¶ added in v1.36.4
GetIAMTier returns "" — tier is no longer derived in-binary. The gateway can attach an X-Tier header in a future iteration if needed.
func IAMTokenRequired ¶
func IAMTokenRequired() gin.HandlerFunc
IAMTokenRequired returns a Gin middleware that:
- Reads the gateway-supplied X-Org-Id / X-User-Id / X-User-Email headers (already JWT-validated upstream).
- Resolves the Organization via pkg/org.Resolve (KV-cached).
- Sets the legacy gin context keys downstream handlers expect: iam_authenticated, iam_org, iam_user_id, iam_email, organization, active-organization, permissions.
Missing headers: falls through (handler chain may use a legacy org-token instead). The gateway is the trust boundary; commerced is only reachable via the gateway in production, where COMMERCED_REQUIRE_IDENTITY rejects header-less requests at the edge of the binary.
func Init ¶
Init is a no-op kept for source-compat with the legacy bootstrap call (commerce.go calls it with auth.IAMConfig). The trust boundary is now the gateway, not this binary.
func InitKV ¶ added in v1.36.4
func InitKV(kv KVCache)
InitKV wires the KV cache used by org-id resolution.
func IsIAMAuthenticated ¶
IsIAMAuthenticated reports whether the request was identity-attached by either pkg/auth.Gin (preferred) or legacy IAMTokenRequired.
Source Files