zt

Overview ¶

Package zt mounts the Hanzo Cloud NETWORKING surface: the tenant's Hanzo Zero Trust footprint — overlay networks, their routers and mesh services — served as clean, org-scoped REST off the unified cloud binary and fronting the Hanzo Zero Trust controller (hanzoai/zt, an OpenZiti-based fabric). It exists so the console's Networks, Service Mesh and Routers pages read REAL per-org ZT state from ONE place (api.hanzo.ai/v1/*) instead of rendering "not connected".

This subsystem OWNS no ZT state — the controller does. It is a thin, tenant-scoped translator: it fronts the controller's Edge MANAGEMENT API (/edge/management/v1), filters every resource to the caller's org by the "org-<org>" role attribute, and re-shapes ZT objects into the exact JSON the console modules consume (types.go). It never fabricates: a mesh row is a real ZT edge service, a router row is a real edge-router with its real online status, and a network exists only when the org actually has edge-routers on the fabric.

Surface (every route org-scoped by the validated principal; HIP-0026):

GET /v1/networks          the org's ZT overlay network(s)  -> {networks:[networkView]}
GET /v1/networks/routers  the org's ZT edge-routers        -> {routers:[routerView]}
GET /v1/networks/:id      one overlay network by id        -> networkView (404 if absent)
GET /v1/mesh/services     the org's ZT edge services       -> {services:[meshView]}

Networks maps to the fabric overview, its routers to the ZT edge-routers that ARE that overlay's nodes, and Service Mesh to ZT edge services — the three ZT concepts the three console pages need.

THE ROUTERS LIVE UNDER THE NETWORK, and this is the whole reason the route moved. They were served at /v1/edge/nodes, which read as a top-level Hanzo product named "edge" and was not one: hanzoai/edge is the on-device inference runtime, a binary a customer runs on their own machine, and it has no cloud surface at all. Three more unrelated things wore the same word — the public catalogue cache, the gateway's CORS-and-rate-ceiling policy role, and a JWT audience list — so "edge" named a POSITION, never a product, and a prefix belongs to a product a customer calls. An edge-router is a node of an overlay network, so it is addressed as one. /v1/edge now 404s at every depth, which is correct rather than a missing product.

TENANT ISOLATION. The org (principal.Org, the validated IAM owner) selects the "org-<org>" role attribute; the client lists the controller's resources and this subsystem filters to that role, so a caller can only ever read their OWN tenant's ZT footprint. The org is taken from the validated identity, never a client field.

FAIL-CLOSED. Absent the ZT service credential (ZT_CLIENT_ID / ZT_CLIENT_SECRET, KMS-injected) the subsystem mounts its full route space but every op returns an honest 503; it NEVER fabricates a network, service or node.