cloud

func AccountFromPrincipal ¶ added in v1.801.186

func AccountFromPrincipal() zip.Handler

func AuditTrail ¶ added in v1.786.1

func AuditTrail(rec *audit.Recorder) zip.Handler

AuditTrail returns the audit middleware bound to rec. A nil rec makes it a no-op passthrough so callers always Use() it unconditionally.

func BYOFeeBps ¶ added in v1.801.186

func BYOFeeBps() int64

BYOFeeBps resolves the BYO inference platform fee (basis points) from CLOUD_AI_BYO_FEE_BPS, else the policy default. A negative/invalid value falls through to the default so a typo cannot silently zero out the fee; 0 is honored (free BYO). This is the ONE BYO fee knob for the whole binary.

func BYOFloorMicros ¶ added in v1.801.186

func BYOFloorMicros() int64

BYOFloorMicros resolves the per-call BYO floor (micro-USD) from CLOUD_AI_BYO_FLOOR_UUSD, else the policy default. A negative/invalid value falls through to the default.

func BYOInferenceFeeMicros ¶ added in v1.801.186

func BYOInferenceFeeMicros(tokens int) int64

BYOInferenceFeeMicros is the per-CALL platform routing fee (micro-USD) for a BYO inference of `tokens` tokens: BYOFeeBps of the EQUIVALENT metered price (aiPriceUUSDPer1kTokens), FLOORED at BYOFloorMicros. A BYO model invoked with the org's own provider token (Cloudflare Workers AI) debits the SAME usage spine and the SAME per-scope caps as a Hanzo-served call, at the thin BYO fee — but never below the floor, so a call the token estimate CANNOT price (a non-text modality: 0 tokens) is still gated and billed rather than slipping through free and unchecked. This is the ONE BYO fee model — no per-provider variant.

func Billable ¶ added in v1.801.242

func Billable(method, path string) bool

Billable reports whether a request CONSUMES resource somebody has to pay a provider for, and therefore requires standing before it runs.

THIS IS THE BUG THE SPLIT EXISTS TO KILL. Authorization and pricing were one int64: DefaultPrice returned the edge charge, and BillingGate read `cents <= 0` as "do not gate". Every LLM path prices at 0 there — deliberately, because the ai and zen subsystems meter their own token costs and an edge charge would double-bill — so "we charge nothing HERE" silently meant "we authorize NOTHING here", and the same fusion made every resource kind an operator prices at 0 un-gated as well (ResourceMeter.Gate: `costCents <= 0 -> nil`). One int64 answering two questions is why the LLM leak and the non-LLM gap are a single bug. They are two questions now: Billable says WHETHER standing is required, DefaultPrice says WHAT the edge charges. Pricing something at zero can no longer un-authorize it.

READS ARE NEVER BILLABLE. GET/HEAD/OPTIONS pass unconditionally — gating reads already caused one outage, a balance view that 402s is unusable, and no read this binary serves calls a paid provider.

The path sets are MEASURED, not invented:

• inference — the exact paths zen's Claim owns (zen@v1.4.2 proxy.go) plus ai's own tree. These are the free-inference hole.
• meteredTrees — the subsystems that construct a ResourceMeter (the non-LLM auth-not-balance gap). /v1/commerce/ and /v1/o11y/ are in BillingGate's selfMeteredPrefixes but are deliberately NOT here: one is the pay path itself and the other is telemetry ingest, and neither spends a provider's money.

func BillingGate ¶ added in v1.786.1

func BillingGate(m *metering.Client, price func(c *zip.Ctx) int64) zip.Handler

BillingGate returns a zip middleware that gates every request on the caller's commerce balance and records usage for priced paths.

Order of operations:

1. price(c) == 0 AND not gated → pass straight through (free path).
2. Authorize(ctx, identity) BEFORE c.Next(): nil → allow. ErrInsufficientBalance → 402 insufficient_balance, c.Next() NOT called. other error → 503 balance_unavailable, c.Next() NOT called (fail-closed; the client returns nil here when built FailOpen, so this branch never fires in fail-open mode).
3. c.Next() runs the handler chain.
4. After a successful chain, if price(c) > 0, fire `go m.Record(...)` so the debit never blocks or corrupts the response the user already received.

When m is nil or not configured (no commerce URL) the gate is a no-op: it returns c.Next() directly so an unconfigured deployment is never blocked. price must not be nil; pass DefaultPrice.

func BrandForHost ¶ added in v1.786.165

func BrandForHost(host string) string

BrandForHost is BrandForHostOK with the Hanzo default for an unmatched Host.

func BrandForHostOK ¶ added in v1.786.165

func BrandForHostOK(host string) (string, bool)

BrandForHostOK resolves a request Host to a brand id from the same `brands` registry, mirroring the hostname→brand semantics of platform.ts's getWhiteLabelBrand: a Host at or under a brand's Domain (api.lux.network, lux.network) is that brand. The port is stripped and the compare is case-insensitive; the longest matching Domain wins so a nested brand domain is never shadowed by a shorter one. ok is false when NO brand domain matches, so the caller can choose its own fallback (the deployment brand) rather than silently emitting Hanzo branding on, say, a Zoo pod hit with an odd Host.

func BrandIssuers ¶ added in v1.786.50

func BrandIssuers() []string

BrandIssuers returns the OIDC issuer of every configured white-label brand. The in-binary identity validator (auth_identity.go) trusts a token whose `iss` is any of these, so ONE cloud binary validates hanzo AND lux/zoo/pars tokens. One source of truth: derived from the same `brands` registry above.

func CallerBearer ¶ added in v1.801.89

func CallerBearer(c *zip.Ctx) string

CallerBearer returns the caller's validated JWT bearer for RELAY to a downstream org-scoped service (e.g. the DNS control plane) that authorizes on the caller's OWN identity and derives the org from the token's `owner` claim. It returns the SAME token SanitizeIdentity validated the principal with (callerToken), UNCHANGED -- cloud substitutes NO service credential of its own, so tenant isolation carries across the hop: a caller in org A relays an org-A token and can reach only org A.

An opaque API key (hk-/sk-/...) is NOT a relayable bearer -- an OIDC target cannot validate it and forwarding it would leak the key -- so it returns "". Empty when the request carries no validatable bearer; the relay then sends no Authorization and the downstream fails closed on its own gate.

func ClientIP ¶ added in v1.786.1

func ClientIP(c *zip.Ctx) string

ClientIP extracts the originating client IP from X-Forwarded-For (the gateway sets it); the left-most entry is the real client. Shared by the edge gate and the resource meter so usage records carry a consistent client_ip.

func DefaultPrice ¶ added in v1.786.1

func DefaultPrice(c *zip.Ctx) int64

DefaultPrice is cloud's per-request price (in cents) for the edge gate.

It returns 0 — meaning "do not gate, do not charge" — for:

• health/liveness probes (every /v1/<svc>/health and bare /health),

• /v1/ai/* : the ai subsystem self-meters its own LLM token costs to commerce; charging again here would DOUBLE-BILL,

• /v1/agents/* : the canonical agents subsystem now gates + meters its OWN per-run fee to commerce (clients/agents runAgent); the edge must stay 0 or every agent run is billed twice,

• other subsystems that already self-meter their units (commerce billing itself, o11y telemetry, mcp tool dispatch),

• /v1/agent* : the agent orchestrator self-meters, billing through the completion it runs in-process, so an edge charge would double-bill.

Every billable surface meters its own units downstream, so the edge charges nothing on its own; it stays wired as a uniform passthrough. Keep self-metering subsystems at 0 to preserve single-charge accounting.

func DenyResource ¶ added in v1.786.1

func DenyResource(c *zip.Ctx, err error) error

DenyResource renders the Gate denial outcomes as the SAME JSON the edge gate returns (denyBilling), so every Hanzo surface emits one error contract: 402 insufficient_balance / 503 balance_unavailable.

func Draining ¶ added in v1.801.231

func Draining() bool

Draining reports whether a graceful shutdown is in progress.

func EdgeCORS ¶ added in v1.786.165

func EdgeCORS(pol *edge.Store) zip.Handler

EdgeCORS returns the browser-CORS middleware for the public /v1 edge. The origin allowlist is the PLATFORM policy's CORSOrigins, read live (recompiled only when it changes) so a SuperAdmin can add/remove origins via PUT /v1/gateway/config.

DEFAULT OFF (empty allowlist ⇒ no-op passthrough). On the RECOMMENDED rollout — the shared Traefik ingress keeps fronting api.hanzo.ai and its `cors-allow-all` middleware already answers CORS there — enabling cloud CORS too would emit a SECOND Access-Control-Allow-Origin header and break every browser preflight. So CORS stays owned by exactly ONE layer: the ingress until/unless the edge moves to a direct DO-LB→cloud path (cloud terminates TLS for api.hanzo.ai), at which point the operator sets CLOUD_CORS_ORIGINS (or PUTs it) and cloud becomes the sole CORS authority. One policy, one place — never both.

When enabled it handles the OPTIONS preflight itself (204, short-circuit) and reflects the allowlisted Origin on the actual response, then continues the chain.

func EdgeRateLimit ¶ added in v1.786.165

func EdgeRateLimit(pol *edge.Store) zip.Handler

EdgeRateLimit returns the per-client-IP flood cap that runs BEFORE identity — the gateway's `qos/ratelimit/router` (strategy:"ip") role. The limit + window are read LIVE from the PLATFORM policy (per_ip_rpm / window_sec), so a SuperAdmin can retune the cap via PUT /v1/gateway/config with no redeploy. It is a fixed-window counter keyed on the client IP (leftmost X-Forwarded-For, via ClientIP) with opportunistic eviction of expired windows so the map stays bounded even at the edge's high IP cardinality (why this is not the zip token-bucket primitive that ScopeRateLimit reuses: that primitive never evicts, which is fine for a bounded per-org keyspace but would grow without bound keyed on raw IPs).

SCOPE = public edge only. A request with NO X-Forwarded-For is an IN-CLUSTER direct caller (console BFF, sibling service hitting cloud.svc:8000) — it never transited the ingress/LB, exactly the traffic the standalone gateway never saw, so it is not IP-limited here (parity: the gateway only ever rate-limited public traffic). Only proxied edge traffic, which carries the real client IP in XFF, is throttled. A per_ip_rpm of 0 (env CLOUD_EDGE_RATELIMIT=false at boot) is a live no-op.

func EmbeddedTasks ¶ added in v1.786.72

func EmbeddedTasks() *tasksengine.Embedded

EmbeddedTasks returns the ONE in-process tasks engine, or nil until wireDurableIngest has run (or if it failed to start). The Tasks HTTP/UI surface (clients/tasks, mounted at /v1/tasks/*) serves on THIS shared engine — there is exactly one engine per process, shared by ai's durable ingest AND the Tasks product surface, never a second Embed. The surface resolves it lazily (per request) because subsystem Mount runs during MountAll, before wireDurableIngest.

func EmitLifecycle ¶ added in v1.800.1

func EmitLifecycle(ctx context.Context, ev LifecycleEvent)

EmitLifecycle fans one event out to every registered subscriber, best-effort and NON-BLOCKING: each subscriber runs in its own goroutine on a cancel-immune context (the fact already happened — a request cancel must not abort the notify/mirror), so a slow reactor (a mirror push) can never delay the git/deploy path or another reactor. A panicking subscriber is contained so one bad reactor can neither crash the shared multi-tenant process nor starve the others; each subscriber logs its own errors.

func EnsureGitMirror ¶ added in v1.801.59

func EnsureGitMirror(ctx context.Context, org, project, repo, url string, enabled bool) error

EnsureGitMirror registers (enabled) or removes (disabled) the outbound mirror target url on the native repo. Idempotent.

func EnsureStarterCredit ¶ added in v1.801.242

func EnsureStarterCredit(ctx context.Context, w principal.Wallet) (int64, error)

EnsureStarterCredit grants the one-time starter credit to wallet and reports the balance it left behind, or (0,nil) when the wallet was not eligible.

THE ADDRESS IS THE CALLER'S, NOT A GUESS. It credits (Ledger, Account) exactly as principal.WalletOf resolved it, passing Account through as CreditInput.Subject. For a real org Payer yields the org pool and Subject is the bare slug; the day IAM mints per-member `billing_account` claims it yields a person account and the same field carries it. Either way the credit lands where the gate looks, because both come from one call to account.Payer.

ELIGIBILITY IS "NEW", NOT "UNSEEN". A first-contact trigger sees every EXISTING account too — on the first request after a deploy, every org in the fleet is unseen. Granting on unseen alone would hand a retroactive $5 to the entire customer base. So a wallet qualifies only if it has no money and no history: a zero balance AND zero lifetime usage. A funded org is skipped, an org that has ever spent is skipped, and a genuinely new account passes. (Known edge, stated: an old account that was refunded to exactly zero and never metered reads as new and is granted once. It cannot recur — the Ref below is permanent.)

AMOUNT IS SERVER-AUTHORITATIVE. credit.StarterCreditCents, the shared constant, read from the server's own dependency. This function takes no amount and no request body, so there is no client field that could reach it.

func EstTokens ¶ added in v1.801.186

func EstTokens(texts ...string) int

EstTokens is a deterministic, provider-agnostic token estimate (~4 chars/token) used to price embeddings (no usage returned) and to pre-gate chat before the completion tokens are known.

func Fail ¶ added in v1.801.231

func Fail(c *zip.Ctx, msg string) error

Fail writes a { status:"error", msg } envelope. The operator's transport maps a non-ok envelope to a surfaced error (never a fabricated value).

func GitRepoStatuses ¶ added in v1.801.23

func GitRepoStatuses(ctx context.Context, org, project string, names []string) (map[string]GitRepoStatus, error)

GitRepoStatuses returns the per-repo import + sync status for names (org-scoped).

func Handle ¶ added in v1.786.216

func Handle[S any](s *Service[S], h func(*Service[S], *zip.Ctx) error) func(*zip.Ctx) error

Handle binds a Service-scoped handler to a route: it adapts a `func(*Service[S], *zip.Ctx) error` to the plain `func(*zip.Ctx) error` the router takes, capturing s. One adapter, so packages write free-function handlers and register them with `app.Get("/path", cloud.Handle(s, myHandler))`.

func IdentityMiddleware ¶ added in v1.786.72

func IdentityMiddleware(cfg *Config) zip.Handler

IdentityMiddleware builds the identity trust-boundary middleware from cfg: it constructs the IAM JWT validator (trusted-issuer set, JWKS, audience allowlist) and returns SanitizeIdentity bound to the admin org. This is the ONE constructor for the boundary, so Serve and integration tests wire it identically — no second copy of the validator-construction glue to drift.

func ImportGitRepo ¶ added in v1.801.23

func ImportGitRepo(ctx context.Context, req GitImportReq) error

ImportGitRepo creates + mirrors an external repo into the native git server.

func IsPublishableKey ¶ added in v1.801.231

func IsPublishableKey(tok string) bool

IsPublishableKey reports whether tok is a publishable key.

A publishable key is NOT a credential: it identifies a tenant so a public surface can WRITE (ingest events), and it must never mint a principal that can READ. Cloud resolved any isAPIKey token — pk- included — into "the same principal a JWT yields", which made a key documented as "safe to show" into a full bearer for the org that owns it. IdentityFromRequest now refuses it, so publishable means publishable.

It stays in APIKeyPrefixes on purpose: OrgForKey must still resolve a pk- to its owning org, because that is exactly how the ingest door learns which tenant a browser beacon belongs to. Resolvable, not authenticating.

func IssuerForBrand ¶ added in v1.786.1

func IssuerForBrand(id string) string

IssuerForBrand returns the canonical OIDC issuer for a brand id.

func MarkdownNegotiation ¶ added in v1.786.165

func MarkdownNegotiation(defaultPrefixes []string) zip.Handler

MarkdownNegotiation returns the response-path middleware. Register it ONCE at the compose root and every /v1 endpoint negotiates markdown uniformly.

func MetricsHandler ¶ added in v1.786.131

func MetricsHandler() http.Handler

MetricsHandler serves the private registry in Prometheus exposition format for the ops /metrics listener (healthMux). Self-contained: it reads only this registry, never the API stack.

func MicrosToGateCents ¶ added in v1.801.186

func MicrosToGateCents(micros int64) int64

MicrosToGateCents converts a micro-USD amount to the whole cents a pre-call balance gate must RESERVE: round UP (a gate must never under-reserve), with a 1-cent floor for any positive amount. 1 cent = 10_000 micro-USD. Shared by the LLM meter and every other inference path (Workers AI) so one rule prices the gate everywhere.

func Mount ¶ added in v1.786.216

func Mount[S any](app Router, deps Deps, name string, build func(Base) (S, error), routes func(Router, *Service[S])) error

Mount is the one generic subsystem entrypoint. `build` constructs the typed State from Base (open stores, dial clients — returns an error to fail the mount closed); `routes` registers the handlers. A package's exported Mount is then one line: `return cloud.Mount(app, deps, "name", build, routes)`.

func MountAll ¶

func MountAll(app *zip.App, specs []MountSpec, cfg *Config, deps Deps) error

MountAll mounts every ENABLED subsystem in specs, in slice order — the order is the composition root's (apps.Wire()); MountAll does NOT sort.

app is the concrete *zip.App from Serve. A Global spec receives it. Everyone else receives a scope bound to their declared Prefixes, so a subsystem's middleware reaches its own subtrees and nothing else, whatever its slice position. A subsystem that installs middleware outside them fails the mount — the binary refuses to boot half-gated rather than serving with a stranger's gate on.

Teardown is wired HERE, at mount time: right after a subsystem mounts, its ShutdownFunc (if any) is registered via app.OnShutdown. zip drains those hooks LIFO — AFTER the listeners stop accepting and in-flight requests drain — so registration-at-mount yields reverse-mount teardown (a dependency mounted before its dependents is torn down after them) with no subsystem torn down while a request still uses it. Only ENABLED specs mount, so only they register a hook; teardown needs no separate enablement gate.

func OK ¶ added in v1.801.231

func OK(c *zip.Ctx, data any) error

OK writes a { status:"ok", data } envelope (the get<T> shape).

func OKList ¶ added in v1.801.231

func OKList(c *zip.Ctx, rows any, total int) error

OKList writes a { status:"ok", data:[...], data2:total } envelope (getList<T>).

func OKRaw ¶ added in v1.801.231

func OKRaw(c *zip.Ctx, rows json.RawMessage, total int) error

OKRaw writes a { status:"ok", data:<raw>, data2:total } envelope, forwarding a pre-encoded payload verbatim so its exact wire shape reaches the operator field-for-field. An empty payload is normalized to an empty array.

func OnGitPush ¶ added in v1.786.216

func OnGitPush(ctx context.Context, ev GitPushEvent) error

OnGitPush fires the registered push-to-deploy trigger for a landed push. It is a no-op when no builder is registered (git server running without the platform subsystem co-resident). Best-effort by contract: the caller must never fail the push the client already committed just because a build could not be triggered.

func OnServiceRelease ¶ added in v1.801.7

func OnServiceRelease(ctx context.Context, ev ServiceReleaseEvent) error

OnServiceRelease rolls a proven image live by patching the matching hanzo.ai/v1 Service CR's spec.image (the operator then reconciles the Deployment). It is a no-op when no releaser is registered (a binary without the paas control plane co-resident). The releaser enforces the clean-semver gate and CR-name resolution; this is only the dispatch seam.

func OrgDB ¶ added in v1.786.216

func OrgDB(dataDir, org, project, subsystem string) (*sql.DB, error)

OrgDB is the ONE way any cloud subsystem opens a per-org SQLite file (HIP-0302 physical org isolation). It resolves the path, creates the parent directory 0700, opens via the sole "sqlite" driver, and applies the single-writer + WAL pragmas every org store shares. The caller owns migration (its schema is its own) and Close.

Path convention — scope is chosen by project:

project != ""  →  {DataDir}/orgs/{orgSlug}/projects/{projectSlug}/{subsystem}.db
project == ""  →  {DataDir}/orgs/{orgSlug}/{subsystem}.db

org and project MUST be the VALIDATED principal values (principal.Org and, when project-scoped, principal.Project) — never a raw request body/header. OrgDB folds each through SanitizeOrg, the ONE injective org slugger, so two distinct orgs can never share a file (case-fold on a case-insensitive filesystem, or a "-"/"." fold, would otherwise collapse them) and no segment can traverse out of DataDir. An org (or, when project-scoped, a project) that SanitizeOrg refuses is an error — never a silent fall-through to another org's file.

func OrgForKey ¶ added in v1.801.91

func OrgForKey(ctx context.Context, key string) (string, bool)

OrgForKey resolves an opaque Hanzo API key (hk-/sk-/pk-/fw_/hz_) to the org it belongs to — the SAME owner org SanitizeIdentity mints when that key arrives as a bearer — through the ONE IAM key seam (get-user?accessKey). It is the exported door a keyed, bearer-less SDK path uses to attribute a project key to a tenant.

FAILS CLOSED: ("", false) for a non-key-shaped string, an unknown/unresolvable key, an unconfigured resolver, or an out-of-bounds org — never a fabricated or default tenant, so a bad key can never be written into another org's partition. The isAPIKey prefix gate keeps garbage strings off the IAM network path.

func OrgHasUnsafeRune ¶ added in v1.786.32

func OrgHasUnsafeRune(s string) bool

OrgHasUnsafeRune reports whether s carries any whitespace, control, or zero-width/format rune — the class that defeats the injectivity of the org→org map. strings.TrimSpace (and fasthttp's own header-value OWS trimming) silently drop such runes at the edges, so two DISTINCT IAM org names ("acme" vs "acme ", or an NBSP/ZWSP variant) would collapse onto ONE org-<slug> namespace / image ref — a cross-org fold. The identity trust boundary REFUSES to grant org-scoping from an org bearing one of these (fail secure) instead of folding it, so distinct raw names never collide and no namespace is ever derived from an invisible-character identifier.

Case / '-' / '.' / other visible punctuation are deliberately NOT unsafe: those fold INJECTIVELY through the org-slug hash (provisioning.SanitizeOrg). Only the invisible / edge-trimmable class — which no injective fold can survive once transport strips it — is rejected here. A legitimate IAM org slug never contains such a rune, so no real caller is affected.

func PlatformDB ¶ added in v1.801.59

func PlatformDB(dataDir, subsystem string) (*sql.DB, error)

PlatformDB opens the deployment's reserved, NON-tenant partition of an otherwise per-org subsystem at {DataDir}/orgs/_platform/{subsystem}.db, through the SAME cek + single-writer + WAL path as OrgDB. It is the home for records a per-org subsystem holds that belong to no single tenant (e.g. a platform-wide HMAC key): everything tenant-scoped stays in its own {DataDir}/orgs/{slug}/… file. Because the slug carries a '_' that SanitizeOrg never produces, this file is guaranteed disjoint from every tenant's. The caller owns migration + Close.

func Reachable ¶ added in v1.801.242

func Reachable(path string) bool

Reachable reports whether a path must be served REGARDLESS of standing.

This is not a scope selector — which routes a gate guards is decided by where it is applied. It is a SAFETY PROPERTY: a customer who has not yet paid must still be able to reach the paths that let them pay, and a lapsed one must be able to cure their own lapse. Gate those and you deadlock every prospect and every lapsed customer at once — a self-inflicted total revenue stop that looks like success in a naive test, because everything returns 402. So the list lives INSIDE the predicate: no future wiring mistake can gate the pay path, whatever it wraps.

Gating too little is a revenue leak we fix next week. Gating too much is an outage. The list is therefore deliberately generous, and anything ambiguous belongs on it.

Traced from the console subscribe flow (console src/components/products/ PlansModule.tsx -> src/lib/api/plans.ts): PlansApi.plans() reads /v1/billing/plans through the per-tenant billing proxy, and checkout drives the /v1/billing/* money surface — which also carries the INBOUND PROVIDER WEBHOOKS at /v1/billing/webhooks/:provider. Gating an inbound payment webhook loses payments outright, so that prefix is load-bearing twice over.

func Refuse ¶ added in v1.801.242

func Refuse(c *zip.Ctx, product, reason string) error

Refuse renders the ONE 402 shape every spend gate uses. product is empty for the edge gate (which gates spend itself, not a product) and set by a product-scoped gate; `for <product>` is the only difference it makes to the sentence.

func RegisterCommerceClientFactory ¶ added in v1.786.216

func RegisterCommerceClientFactory(f func(cfg *Config, log luxlog.Logger) CommerceClient)

RegisterCommerceClientFactory installs the embedded-Commerce client constructor. apps/commerce.go calls this from its init(); exactly one registration.

func RegisterGitImporter ¶ added in v1.801.23

func RegisterGitImporter(g GitImporter)

RegisterGitImporter installs the git object-plane importer. nil-safe.

func RegisterGitMirrorController ¶ added in v1.801.59

func RegisterGitMirrorController(c GitMirrorController)

RegisterGitMirrorController installs the git-plane mirror controller. nil-safe.

func RegisterIssueSink ¶ added in v1.801.218

func RegisterIssueSink(fn IssueSink)

RegisterIssueSink installs the tracker upsert sink. nil-safe.

func RegisterKMSClientFactory ¶ added in v1.786.165

func RegisterKMSClientFactory(f func(cfg *Config, log luxlog.Logger) (KMSClient, error))

RegisterKMSClientFactory installs the embedded-KMS constructor. clients/kms calls this from its init(); it is the ONE inversion point that lets the KMS library and its /v1/kms subsystem share one package with no cloud⇄kms cycle.

func RegisterLifecycleSubscriber ¶ added in v1.800.1

func RegisterLifecycleSubscriber(fn func(ctx context.Context, ev LifecycleEvent))

RegisterLifecycleSubscriber adds a git-lifecycle reactor. Every subsystem that reacts to a push/deploy (mirror-out, Slack-notify) registers ONE here at Mount; git/platform EMIT via EmitLifecycle. The inversion keeps the emitters from importing the subscribers — the same pattern as RegisterPushBuilder, but many-registrant.

func RegisterOrgScopeResolver ¶ added in v1.786.216

func RegisterOrgScopeResolver(r OrgScopeResolver)

RegisterOrgScopeResolver adds a project-ownership registry consulted by the identity trust boundary. Called once per registry at its Mount (mirrors sites.SetResolver). Registries COMPOSE: a project is "mine" if ANY registry owns it for the org, and "foreign" only if some registry owns it for another org while NONE owns it for this org. A nil resolver is ignored.

func RegisterPushBuilder ¶ added in v1.786.216

func RegisterPushBuilder(f func(ctx context.Context, ev GitPushEvent) error)

RegisterPushBuilder installs the git-push-to-deploy trigger. clients/platform calls this from its Mount when co-resident; it is the ONE inversion point that lets the embedded git server launch a platform build with no git⇄platform cycle.

func RegisterServiceReleaser ¶ added in v1.801.7

func RegisterServiceReleaser(f func(ctx context.Context, ev ServiceReleaseEvent) error)

RegisterServiceReleaser installs the first-party CR-rollout hook. clients/paas calls this from its Mount when co-resident; it is the ONE inversion point that lets a build-completion path roll a proven image onto its operator Service CR with no cloud⇄paas import cycle.

func RegisterSync ¶ added in v1.801.59

func RegisterSync(fn SyncFunc)

RegisterSync installs the sync reconcile func. nil-safe.

func RegisterTelemetryInstaller ¶ added in v1.786.216

func RegisterTelemetryInstaller(f func(ctx context.Context, serviceName string) func(context.Context))

RegisterTelemetryInstaller installs the tracer-provider bootstrap that wires this process's OTel global provider to the o11y in-process trace sink AND adopts it into the embedded ai module (so ai emits gen_ai spans). clients/o11y calls this from its init(); it is the ONE inversion point that lets cloud.Serve bootstrap telemetry with no cloud⇄clients/o11y import cycle. Exactly one registration.

func RepoFromCloneURL ¶ added in v1.800.1

func RepoFromCloneURL(u string) string

RepoFromCloneURL extracts the repo name from a git clone URL (last path segment, ".git" stripped) — the repo component of the (org,project,repo) routing key that a deploy emitter derives from an app/project's linked RepoURL. The ONE place this derivation lives, shared by the platform + projects deploy paths (no per-package copy).

func ResetLifecycleSubscribers ¶ added in v1.800.1

func ResetLifecycleSubscribers()

ResetLifecycleSubscribers clears the registry. TEST-ONLY seam (a test mounts and unmounts repeatedly); production registers once at Mount and never resets.

func ResourceFeeCents ¶ added in v1.786.1

func ResourceFeeCents(envPrefix, kind string) int64

ResourceFeeCents resolves the flat create fee (in cents) for kind from operator config, most specific first:

<envPrefix>_<KIND>   e.g. CLOUD_PROVISION_FEE_CENTS_SQL=500
<envPrefix>          e.g. CLOUD_PROVISION_FEE_CENTS=100  (all kinds)
DefaultResourceFeeCents                                   ($1.00)

A clearly-named, configurable policy knob — never a fabricated price. A value of 0 makes the kind free (and un-gated). Negative/invalid values are ignored (fall through), so a typo can never make a paid resource free by accident.

func SanitizeIdentity ¶ added in v1.786.1

func SanitizeIdentity(v *identityValidator, adminOrg string) zip.Handler

SanitizeIdentity returns the identity-trust-boundary middleware.

Per request:

• ALWAYS delete every header in authorityHeaders (a client copy never survives — this alone kills X-User-IsAdmin forgery).
• Validate a Bearer / Basic / session-cookie JWT, if present: SuperAdmin (homeOrg == adminOrg, human) — membership of the reserved admin org IS the predicate; the isAdmin bit is deliberately not a second term. This line previously read "claims.isAdmin && owner == adminOrg", which was wrong twice over: the code has never consulted isAdmin here (see TestSuperAdminGate_IsAdminOrgMembership), and `owner` named the APP's org, not the user's. → X-User-IsAdmin=true; X-Org-Id = the requested org when present (admin org-switch), else the home org. any other principal (incl. org admins, normal users) → X-Org-Id pinned to owner; NO admin. A client org cannot widen scope.
• No / invalid / opaque-API-key credential: → NO admin (forgery dead), and the client's X-Org-Id is restored for the Phase-1 data path (residual below).

PHASE-1 RESIDUAL (documented; not a regression vs. today): with no validatable bearer, the client X-Org-Id is passed through for DATA scoping. cloud's data plane has no session of its own yet ("Auth stays gateway-owned in Phase 1") and the console browser data path depends on this header. So a direct-to-pod caller can still SELECT an org for DATA reads. Closing that needs the data path to carry a bearer universally OR the NetworkPolicy locked to gateway-only (which would break console's legitimate direct in-cluster BFF) — Phase-2. The ADMIN boundary (this fix's P0) is closed on every path regardless, because X-User-IsAdmin is NEVER restored from client input.

FAIL MODE. If the validator can't verify a token (JWKS unreachable on a cold cache, issuer/audience misconfigured), the request resolves anonymous and BOTH planes fail SECURE. Admin fails closed (X-User-IsAdmin is never restored from client input), and — since F1 — the DATA plane fails closed too: it gates on a validated principal (clients/principal.Validated) and the anonymous request carries no X-User-Id, so the restored X-Org-Id is refused, not served. Never fails OPEN. The availability cost is bounded to COLD caches: the jwksCache is stale-on-error (a warm cache keeps validating through a transient JWKS outage), so only a from-cold JWKS failure degrades to anonymous-403.

func SanitizeOrg ¶ added in v1.786.173

func SanitizeOrg(s string) string

SanitizeOrg reduces a gateway org id to a lowercase [a-z0-9-] slug that is INJECTIVE in the raw owner: an org bearing any whitespace/control/format rune is REFUSED (→ "") at the boundary — folding it would not survive TrimSpace / transport OWS-trim and would collapse "acme " onto "acme" — and every accepted owner then maps to the identity on a DNS-1123 label, else a folded slug disambiguated with "-" + the first 16 hex of SHA-256(raw owner). Without the suffix the fold was lossy — ToLower + every non-[a-z0-9-]→"-" + a 32-char truncation collapse distinct owners (`Acme`/`acme`, `team.a`/`team-a`) onto one slug, and since the whole org→bucket/DB/namespace hashes THIS slug, that was a cross-org collision.

This is the ONE org-slug normalizer for the cloud org layer; it lives in the root package beside OrgHasUnsafeRune (the identity-middleware twin) and OrgDB (which folds every org DB path through it). provisioning.SanitizeOrg (shared with S3/KMS/knowledge) delegates here, so the slug is byte-identical across every physical namespace an org touches.

The identity fast-path is withheld from a clean slug that ITSELF looks like a suffixed output (`<label>-<16 lowercase hex>`): such a slug is ambiguous with a folded owner's disambiguation, so it too is re-suffixed — otherwise a squatted org literally named "foo-<sha256(Foo)[:8]>" would alias non-slug owner "Foo".

func ScopeRateLimit ¶ added in v1.786.112

func ScopeRateLimit(m *metering.Client, gp *edge.Store) zip.Handler

ScopeRateLimit returns the per-scope rate-limit middleware. It caps an authenticated org from TWO config sources, most-restrictive-wins:

• commerce spend-alert RateLimitRpm (the plan-configured ceiling), and
• the /v1/gateway per-org OrgRPM (gp), the runtime-mutable operator override.

It is a no-op passthrough only when BOTH are absent (no commerce AND no policy store), so an unwired deployment is never blocked — mirroring BillingGate.

func Serve ¶

func Serve(specs []MountSpec, enable []string) error

Serve boots the canonical compose root and mounts the selected subsystems.

This is the ONE place the cloud-server body lives. cmd/cloud (the full fused surface) and every `hanzo <svc>` subcommand share it; no boot logic is duplicated per entrypoint.

specs is the composition root's subsystem list (apps.Wire()), threaded in by the caller so cloud never imports subsystems (which would cycle). Serve mounts it in slice order and tears it down in reverse.

enable==nil ⇒ honor cfg.Enable from flags/env (cloud mode; empty = all). enable!=nil ⇒ force exactly that set (single-service mode), overriding --enable so `hanzo kms` is unambiguous.

Serve registers the HIP-0106 liveness contract (GET /v1/<name>/health for every enabled subsystem) before MountAll, runs the canonical middleware pipeline (Recover → RequestID → Logger), and shuts down gracefully on SIGINT/SIGTERM.

func ServiceReleaserRegistered ¶ added in v1.801.7

func ServiceReleaserRegistered() bool

ServiceReleaserRegistered reports whether a first-party CR-rollout hook is installed (the paas control plane is co-resident). A caller uses it to know whether OnServiceRelease actually patches a CR or is a no-op, so it can be honest about which rollout path took effect.

func SetDraining ¶ added in v1.801.231

func SetDraining()

SetDraining marks the process draining (readiness → NotReady). Idempotent.

func SetSwitchReader ¶ added in v1.801.218

func SetSwitchReader(f func(string) bool)

SetSwitchReader installs the platform-switch evaluator. clients/flags calls it once on mount; passing nil detaches it (used by tests).

func SpendGate ¶ added in v1.801.242

func SpendGate(commerce CommerceClient) zip.Handler

SpendGate returns the balance-and-subscription gate serve.go mounts app-wide.

DEFAULT OFF, AND THAT IS A SEQUENCING DECISION, NOT TIMIDITY. There is no reachable starter-credit path in this binary today: the grant-starter route was deleted from commerce (last present in commerce v1.48.2), its replacement POST /v1/billing/credit is not registered in the co-resident build, and no ensureStarterCredit runs anywhere. So a brand-new signup's wallet is $0 with no self-service way to fund it. Enforcing on that state 402s every new signup on day one — trading a revenue leak for a total signup outage. The gate therefore ships behind the kill switch, proven by tests, and is flipped only after a funding path exists. Turning it on before then is the one way to make this worse.

Enforcement is read PER REQUEST from the platform switch an owner flips at admin.hanzo.ai, so it turns on and off within one flag-cache TTL — no redeploy, no CR edit. Switch reports false before the flag engine mounts, so an unmounted switch never enforces.

DECISION ORDER — a request is ADMITTED unless the one proven refusal fires:

1. enforcement OFF ........................ admit. Read FIRST, so a dark gate costs one atomic load and touches no authority.
2. not Billable ........................... admit. Reads, the pay path, and every non-metered route are never gated (see Billable / Reachable).
3. unvalidated principal .................. admit. An anonymous caller is the route's own 401 to make; a 402 is meaningless to someone not signed in, and the org on such a request is a forge anyway.
4. platform super-admin ................... admit. Platform sudo, including masquerade, is strictly tighter than any purchasable tier and never 402s.
5. subscribed OR funded ................... admit.
6. UNRESOLVABLE standing .................. posture (paywall_strict), logged WARN.
7. proven unpaid .......................... 402 with the actionable refusal.

FAIL POSTURE — argued, not inherited. The refusal in (7) requires PROOF: both authorities answered and both said no. An authority we could not reach yields Unknown, and by default an Unknown ADMITS. That is not "unpaid users get everything free whenever commerce hiccups" — it is "we never call a customer delinquent on evidence we do not have". The asymmetry decides it: refusing on an outage 402s every PAYING customer at once (a total product outage, irreversible), while admitting on an outage leaks access for the duration (bounded, recoverable, and separately capped — the subsystem meters still run their own fail-closed debit). Every fail-open admit logs at WARN with the reason, so a sustained leak pages rather than hides. When an owner wants the other trade, paywall_strict flips it live.

An unresolvable WALLET is an Unknown, not an admit: principal.WalletOf refuses an unresolvable org, and "we could not work out who pays" must refuse AS UNKNOWN and take the strict posture, never be silently waved through as if it were free.

func StarterGrant ¶ added in v1.801.242

func StarterGrant() zip.Handler

StarterGrant returns the middleware serve.go mounts ahead of the billing gates, so a brand-new account is funded BEFORE the gate on that same request evaluates it — otherwise the very first request of every new signup would 402 the moment enforcement is switched on, which is the failure this whole path exists to prevent.

It never blocks, never fails a request, and never rejects: funding is not an authorization decision. Every outcome falls through to c.Next(). If the grant fails the account simply holds no credit, and the gate — which reads the ledger, not a grant flag — refuses it. There is no path where a failed grant is mistaken for funding.

func Switch ¶ added in v1.801.218

func Switch(key string) bool

Switch reports a platform switch's live value. It returns false before the flag engine mounts and when no engine is present (!cgo), which is the same dark default the engine itself falls back to — so an unmounted switch never enforces.

func Terminal ¶ added in v1.801.59

func Terminal(h func(*zip.Ctx) error) func(*zip.Ctx) error

Terminal wraps a handler so a returned *zip.HTTPError is written in-band (its status + the {status,code,error} JSON zip's default errorHandler would emit) and nil is returned, instead of propagating the error up the middleware chain.

It exists for routes mounted UNDER an outer error-flattening filter. The commerce embed installs one: mountCommerce (apps) registers ErrorHandlerJSON on an app.Group("/v1") whose middleware rewrites ANY error a downstream /v1 handler PROPAGATES into a hardcoded HTTP 500 — so a reject that returns zip.ErrUnauthorized (401) or zip.ErrBadRequest (400) up the chain surfaces to the client as 500. A subsystem mounted after commerce (git, sync, integrations, …) whose reject path must keep its real 4xx wraps its handler here: the status is written before the filter runs, so the filter's c.Next() sees nil and has nothing to flatten. A non-HTTPError (a genuine unexpected failure) passes through unchanged — those are 500s regardless. Compose with Handle: cloud.Terminal(cloud.Handle(s, fn)).

func TracingMiddleware ¶ added in v1.786.82

func TracingMiddleware() zip.Handler

TracingMiddleware emits ONE OpenTelemetry SERVER span per /v1/* request through the global (ZAP) tracer provider, so every api.hanzo.ai request lands in hanzoai/datastore over the ZAP wire alongside the log pipeline. It records the OTel HTTP semantic-convention attributes (method, route, status), sets the span status on error/5xx, and — critically — PROPAGATES the span context onto the request via SetContext so nested spans (agent.run, agent.step, the LLM chat client span in clients/aihttp.go) parent correctly under the request span. That makes a full agent trace a single tree: request → run → step → chat.

It is a plain zip.Handler wrapping c.Continue(), the framework's idiomatic middleware form (the same shape as middleware.Logger); no otelfiber shim is needed because zip already exposes method/path/status/context.

func UpstreamModel ¶ added in v1.801.231

func UpstreamModel(name string) bool

UpstreamModel reports whether name carries an upstream family name.

It matches the family as a WORD, not as a substring: a model id is split on its separators (vendor prefixes, tiers, sizes) and each word has its trailing version digits stripped, so "qwen3.5-397b", "fireworks/deepseek-v3" and "kimi-k2.6" all match while "zen5-coder" and "enso-flash" do not.

func ZenModel ¶ added in v1.801.231

func ZenModel(name string) string

ZenModel returns the Hanzo name for a model: an upstream family name becomes DefaultModel, and a name that is already ours is returned unchanged (trimmed).

Mapping to the default rather than to a guessed tier is the honest answer. We are not claiming which enso tier a given upstream base corresponds to; we are saying the work runs on whatever this deployment runs unnamed work on, which is the same thing we would have told the caller had they named no model.