README
¶
gateway middleware
Gateway-owned middleware for the zip web framework. Moved from
github.com/hanzoai/zip/middleware/ because these concerns belong to
the gateway subsystem (not the generic web framework) per HIP-0106.
Provided middleware
| Name | Purpose |
|---|---|
Auth(verifier AuthVerifier) |
Validate JWT, populate request context with claims, write X-Org-Id |
StripIdentityHeaders() |
Strip client-supplied X-Org-Id / X-User-Id / X-User-Email / X-User-IsAdmin / X-Roles / X-User-Permissions before validation |
Pipeline order
import (
gw "github.com/hanzoai/gateway"
"github.com/hanzoai/gateway/middleware"
)
app.Use(middleware.StripIdentityHeaders()) // first — strip client spoofing
app.Use(middleware.Auth(verifier)) // then — validate + write
// downstream handlers see gateway-written X-Org-Id
// and gw.AssertGatewayWritten(c) returns true
AuthVerifier is a one-method interface that adapts gateway's
auth-middleware to whatever JWT/JWKS implementation a deployment
provides (hanzoai/iam, gateway-sdk, a custom OIDC verifier).
Trust assertion
After this middleware runs, downstream subsystems can verify the request flowed through gateway via:
import gw "github.com/hanzoai/gateway"
if !gw.AssertGatewayWritten(c) {
return zip.Errorf(502, "expected gateway-written X-Org-Id")
}
This is defense in depth — it catches deployment misconfigurations where a subsystem is accidentally exposed to direct (non-gateway) traffic. Production cloud-mounted subsystems should reject the request when the assertion fails; the failure is a deployment bug, not a client problem.
Why not in zip/middleware?
JWT validation + identity-header writing are the gateway subsystem's
responsibility per HIP-0106. Other subsystems mounted inside the
unified cloud binary trust the gateway-written X-Org-Id header and
do NOT re-validate JWTs themselves — re-running JWT validation
per-subsystem is wasteful and risks divergent validation rules.
Generic middleware (Recover, Logger, RequestID, Timeout, MaxBody,
CORS, RateLimit, Telemetry) stays in
github.com/hanzoai/zip/middleware.
Documentation
¶
Overview ¶
Package middleware ships gateway-owned middleware for the zip web framework. JWT validation + identity-header stripping live here (and NOT in github.com/zap-proto/zip/middleware) because they are the gateway subsystem's responsibility per HIP-0106.
Other subsystems mounted inside the unified cloud binary trust the gateway-written X-Org-Id header and do not re-validate JWTs themselves — re-running JWT validation per-subsystem is wasteful and risks divergent validation rules.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Auth ¶
func Auth(verifier AuthVerifier) zip.Handler
Auth validates incoming requests via verifier. When the request already carries gateway-written X-Org-Id (i.e. behind hanzoai/gateway), the verifier is bypassed and the headers are trusted. Otherwise the Authorization: Bearer <token> is verified.
On successful gateway-trust or successful in-process verification, Auth marks the request as gateway-written via SetGatewayWritten so downstream subsystems can assert the trust boundary with gateway.AssertGatewayWritten(c).
Pass a nil verifier to only accept gateway-written headers (no in-binary JWT validation).
func StripIdentityHeaders ¶
StripIdentityHeaders strips client-supplied X-Org-Id / X-User-Id / X-User-Email / X-User-IsAdmin / X-Roles / X-User-Permissions from the request before any other middleware runs. Per HIP-0026, only the gateway-written path is trusted; everything else must be stripped to prevent client spoofing.
Use this when a service runs WITHOUT a Hanzo gateway in front (rare). When deployed behind hanzoai/gateway, the gateway strips these unconditionally and rewrites from JWT — leave this middleware OFF in that topology.
Types ¶
type AuthVerifier ¶
type AuthVerifier interface {
// Verify validates the bearer token and returns the canonical
// X-* headers to write (Org / User / Email / IsAdmin / Roles).
Verify(ctx context.Context, bearer string) (Identity, error)
}
AuthVerifier is the interface Auth() consumes. The real implementation in hanzoai/iam or hanzoai/gateway-sdk satisfies it. A nil verifier on a request that has no gateway X-* headers and no Authorization bearer is rejected with 401.
Source Files