Documentation
¶
Overview ¶
Package brand is the white-label registry (HIP-0111): the map from a brand id (and from a request Host) to that brand's PUBLIC identity — its canonical OIDC issuer and its serving domains.
It is a LEAF (imports only strings), on purpose. Three unrelated callers need it and none should drag the others in: package cloud derives Config.IAMIssuer and validates token `iss` from it; the light webui console reads it to write the per-Host <title>; and cmd/cloud — the light host, which cannot import package cloud — reaches it through webui to brand the "/" it serves. A brand map that lived in package cloud would be unreachable from the host without linking every subsystem, so the white-label fact lives here, once.
The cloud binary is one artifact serving every brand's API host (api.hanzo.ai, api.lux.cloud, api.zoo.cloud, api.cloud.pars.network, ...). Brand is a per-deployment value (CLOUD_BRAND / --brand). These facts are public (issuer host + brand domain), so they live in code, not in KMS.
Index ¶
- Constants
- func APIHost(id string) string
- func Apex(host string) string
- func Display(id string) string
- func ForHost(host string) string
- func ForHostOK(host string) (string, bool)
- func ForIssuer(iss string) (string, bool)
- func IssuerFor(id string) string
- func Issuers() []string
- func Registered(id string) bool
- func Sibling(host, label string) string
- type Info
Constants ¶
const Default = "hanzo"
Default is the fallback brand when CLOUD_BRAND is unknown.
Variables ¶
This section is empty.
Functions ¶
func APIHost ¶ added in v1.801.490
APIHost is the public API host a deployment of brand `id` answers on: api.<that brand's apex> — api.hanzo.ai, api.lux.network, api.zoo.ngo.
It is here, beside the apex it derives from, because two packages need the SAME answer and neither can hold it for the other: package cloud resolves Config.Domain from it, and apps/sites (a leaf that must never import the root package) resolves the self-domain floor from it. Each used to spell the literal "api.hanzo.ai" for itself, so the deployment's own host was stated twice, brand-blind in both places, and nothing made the two agree.
func Apex ¶ added in v1.801.490
Apex returns the registrable apex of a host: the domain one label below the public suffix ("api.hanzo.ai" -> "hanzo.ai", "hanzo.ai" -> "hanzo.ai"). It is THE ONE derivation of that value in this binary.
It exists because a deployment's SIBLING hosts are its own: the forge (git.<apex>), CI (ci.<apex>), CD (cd.<apex>) and the status page (status.<apex>) are neither the API host nor children of it, and any code that must decide "is this host mine?" has to reduce to the apex first. Three packages needed that reduction and each wrote its own, by three different rules that agreed only on the three brand domains we happen to run today:
platform publicsuffix api.acme.co.uk -> acme.co.uk sites last two labels api.acme.co.uk -> co.uk (WRONG) git TrimPrefix "api." + "git." cloud.hanzo.ai -> git.cloud.hanzo.ai (WRONG)
The sites rule hands a bare public suffix to the self-domain floor, which is the set that decides a host is OURS and not a tenant's to claim — so a white-label on any multi-label suffix claimed every domain under it. The git rule advertised a forge host that platform's own allowlist would then refuse, which is verbatim the defect dc84b46d fixed in platform alone: the fix was correct and incomplete, because the derivation was duplicated rather than shared. One copy cannot disagree with itself.
publicsuffix rather than "last two labels" so a multi-label suffix (co.uk, com.au, github.io) yields the registrable domain and not the suffix itself, which would trust — or claim — every domain under it. A name with no registrable form (localhost, a bare IP) is returned verbatim: it is not delegable, so it is its own apex.
func Display ¶
Display is a brand id's human display name: the id with an upper-cased first letter (lux → "Lux", hanzo → "Hanzo"). Derived from the id — one source of truth with the brands registry, no hand-maintained display list. Used to build the white-label console <title>.
func ForHostOK ¶
ForHostOK 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 ForIssuer ¶ added in v1.801.390
ForIssuer resolves the brand whose IAM minted a token, from the token's own verified `iss`. It is the reverse of IssuerFor over the SAME registry, so the two cannot name different brands for one issuer.
It exists because the deployment's brand and the token's brand are two facts, not one: cloud accepts every white-label brand's issuer (trustedIssuers), so a process configured CLOUD_BRAND=hanzo can hold a validly-signed token minted by lux.id. Anything keyed by brand — a tenant key, a derived-key salt — has to be able to tell those apart, and it can only do that from a value the ISSUER signed rather than one the process assumed.
ok is false for an issuer no brand claims, so a caller fails closed instead of silently folding an unknown issuer onto the default brand.
func Issuers ¶
func Issuers() []string
Issuers 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 Registered ¶ added in v1.801.390
Registered reports whether id names a brand in the registry. It is the FALLIBLE half of For, which cannot say so because it answers Hanzo for everything it does not know — the right default for rendering a title, and the wrong one for any decision that turns on which brand a caller belongs to. Lookup is case-insensitive, exactly like For.
func Sibling ¶ added in v1.801.490
Sibling is the host named `label` under host's registrable apex: Sibling("api.hanzo.ai", "git") == "git.hanzo.ai". It is how a deployment names the surfaces it owns beside its API — the forge, CI, CD, status — from the one domain it is configured with, so those names cannot drift apart per package.
Types ¶
type Info ¶
type Info struct {
// ID is the canonical brand key.
ID string
// IAMIssuer is the OIDC issuer (JWKS source) for this brand — the value the
// JWT `iss` claim must equal and whose /v1/iam/.well-known/jwks signs tokens.
IAMIssuer string
// Domain is the brand's primary marketing/site domain (for response scoping
// and base-URL derivation, e.g. api.<Domain>).
Domain string
// AltDomains are additional registrable domains that ALSO belong to this
// brand, used ONLY for hostname→brand white-label detection (ForHostOK).
// A brand's real serving surfaces span more than its marketing domain — the
// cloud console runs on <brand>.cloud hosts (console.lux.cloud,
// console.zoo.cloud), and a request Host there must brand as Lux/Zoo, never
// fall through to Hanzo. Base-URL/issuer scoping still uses the primary Domain.
AltDomains []string
}
Info is the PUBLIC per-brand identity used for token validation + URL scoping. No secrets.
Source Files