diff --git a/deploy/examples/server.yaml b/deploy/examples/server.yaml index a1a2d2f..9cea459 100644 --- a/deploy/examples/server.yaml +++ b/deploy/examples/server.yaml @@ -36,6 +36,13 @@ agent_listen: ":7443" # cert: /etc/llmgw/server.pem # key: /etc/llmgw/server-key.pem +# The public page at "/". Someone who reaches this address without a key needs a +# route to getting one, and the gateway cannot guess who to send them to. +# +# landing: +# contact: "platform@example.com" # or an https:// URL, or "#platform on Slack" +# notice: "Internal use only." + # API keys on the client-facing port (plan §7.9). Off by default, because a # gateway on a trusted network with no keys issued still has to serve — but # nothing else protects that port, so turning it on is what makes it safe to diff --git a/docs/onboarding.md b/docs/onboarding.md index 67c42ea..6119afb 100644 --- a/docs/onboarding.md +++ b/docs/onboarding.md @@ -105,7 +105,23 @@ llmgw keys limits --store … --scope project --id default \ --budget 50000000 --period month # 50 units a month ``` -## 4. What the user does +## 4. Point people at the right place + +Someone who reaches the gateway without a key sees the landing page. Tell it who +to send them to, or it can only shrug: + +```yaml +landing: + contact: "platform@example.com" # or an https:// URL, or "#platform on Slack" + notice: "Internal use only." +``` + +An address becomes a mailto link, an `http(s)` URL stays a link, anything else is +shown as text. Other schemes are never linked — configuration is not always +written by whoever runs the gateway, and a `javascript:` href on a page served to +every visitor is a short path to a stored XSS. + +## 5. What the user does They open the link, press the button, and get the key once. The page shows them the base URL and a working `curl`, and points at two endpoints: @@ -116,7 +132,7 @@ the base URL and a working `curl`, and points at two endpoints: `/me` is there so nobody has to ask you "why was I rate limited" or "how much have I used". It is outside `/v1` because it is not part of the OpenAI API. -## 5. Afterwards +## 6. Afterwards ``` llmgw keys list --store … --project default diff --git a/internal/config/config.go b/internal/config/config.go index eb0c50c..5c11067 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -35,6 +35,9 @@ type Server struct { // Auth turns on API keys on the client-facing port. Auth Auth `koanf:"auth"` + // Landing configures the page served at "/". + Landing Landing `koanf:"landing"` + // AgentTLS authenticates the fleet-facing port. It deliberately does not // cover the client-facing one: that surface is fronted by a publicly // trusted certificate, while this one is mutual and private. @@ -50,6 +53,20 @@ type Server struct { Endpoints []Endpoint `koanf:"endpoints"` } +// Landing configures the public page at "/". +// +// It exists for one thing the gateway cannot know: who to ask for a key. A page +// that explains the API and then leaves the reader with no route to using it is +// where onboarding stops. +type Landing struct { + // Contact is where someone without a key should go — an address, a URL, a + // channel name. Rendered as a link when it is one, as text otherwise. + Contact string `koanf:"contact"` + // Notice is an optional line of your own, for whatever the reader needs to + // know that this page cannot guess. + Notice string `koanf:"notice"` +} + // Auth configures client authentication (plan §7.9). // // Off by default, because a gateway on a trusted network with no keys issued diff --git a/internal/router/handlers.go b/internal/router/handlers.go index 62b2516..fc3dff8 100644 --- a/internal/router/handlers.go +++ b/internal/router/handlers.go @@ -88,7 +88,8 @@ func (r *Router) Handler() http.Handler { // The landing page says how to connect and nothing about what is here, so // it is safe to serve without a key — and it has to be, because the person // reading it is the one who does not have one yet. - mux.HandleFunc("GET /", web.Landing(version.Version, r.auth != nil)) + mux.HandleFunc("GET /", web.Landing(version.Version, r.auth != nil, + r.landing.Contact, r.landing.Notice)) mux.Handle("GET /_static/", web.Static()) mux.HandleFunc("GET /me", r.handleMe) diff --git a/internal/router/router.go b/internal/router/router.go index facd01d..e18204a 100644 --- a/internal/router/router.go +++ b/internal/router/router.go @@ -45,6 +45,10 @@ type Router struct { // onto its catalog entry. models map[string]catalog.Model + // landing configures the public page, which the router serves but does not + // otherwise care about. + landing config.Landing + // auth, store, acct and recorder are nil when authentication is disabled. auth *auth.Authenticator store *storepkg.SQLite @@ -98,6 +102,7 @@ func New(cfg config.Server, log *slog.Logger) (*Router, error) { r := &Router{ cfg: cfg.Router, + landing: cfg.Landing, log: log, reg: reg, profiles: profiles, diff --git a/internal/web/contact.go b/internal/web/contact.go new file mode 100644 index 0000000..64c2615 --- /dev/null +++ b/internal/web/contact.go @@ -0,0 +1,47 @@ +package web + +import ( + "net/url" + "strings" +) + +// contactLink decides how to render the configured contact. +// +// An address becomes a mailto:, an http(s) URL stays a link, and anything else +// — a channel name, an internal ticket queue, a person — is shown as text. +// +// The scheme allowlist is the point. This string comes from configuration, but +// configuration is not always written by the person who runs the gateway, and a +// javascript: or data: href on a page served to every visitor is a stored XSS +// with a very short path to it. Templates escape the text; they do not make a +// scheme safe. +func contactLink(contact string) (text, href string) { + c := strings.TrimSpace(contact) + if c == "" { + return "", "" + } + + if u, err := url.Parse(c); err == nil { + switch strings.ToLower(u.Scheme) { + case "http", "https", "mailto": + return c, c + case "": + // No scheme. A bare address is the common case and worth linking. + if looksLikeEmail(c) { + return c, "mailto:" + c + } + } + } + return c, "" +} + +// looksLikeEmail is deliberately crude: it decides whether to add a mailto:, +// and being wrong means a link that does not open a mail client rather than +// anything worse. +func looksLikeEmail(s string) bool { + at := strings.IndexByte(s, '@') + if at <= 0 || at == len(s)-1 || strings.ContainsAny(s, " \t/") { + return false + } + return strings.Contains(s[at+1:], ".") +} diff --git a/internal/web/landing.go b/internal/web/landing.go index 216692e..a446c23 100644 --- a/internal/web/landing.go +++ b/internal/web/landing.go @@ -12,6 +12,9 @@ import ( type LandingData struct { BaseURL string AuthEnabled bool + Contact string + ContactHref string + Notice string Version string Now string } @@ -24,7 +27,8 @@ type LandingData struct { // // It lists no models and no cluster state. Everything that says what is here // stays behind the key, including /v1/models. -func Landing(version string, authEnabled bool) http.HandlerFunc { +func Landing(version string, authEnabled bool, contact, notice string) http.HandlerFunc { + text, href := contactLink(contact) return func(w http.ResponseWriter, r *http.Request) { // Only the root: a catch-all would turn every mistyped path into this // page, hiding genuine 404s from anyone debugging a client. @@ -35,6 +39,9 @@ func Landing(version string, authEnabled bool) http.HandlerFunc { render(w, "landing", LandingData{ BaseURL: baseURL(r), AuthEnabled: authEnabled, + Contact: text, + ContactHref: href, + Notice: notice, Version: version, Now: time.Now().UTC().Format(time.RFC3339), }) diff --git a/internal/web/templates/base.css b/internal/web/templates/base.css index 8dfa13f..47fec45 100644 --- a/internal/web/templates/base.css +++ b/internal/web/templates/base.css @@ -55,3 +55,6 @@ button { border-radius: 6px; padding: .55rem 1.1rem; } button:hover { filter: brightness(1.1); } +ul { padding-left: 1.2rem; } +li { margin: .25rem 0; } +a { color: var(--accent); } diff --git a/internal/web/templates/landing.html b/internal/web/templates/landing.html index 7f316e3..d29eac5 100644 --- a/internal/web/templates/landing.html +++ b/internal/web/templates/landing.html @@ -34,9 +34,26 @@ reach the address.
reach it. That is a deployment choice and only safe on a trusted network. {{end}} -Keys are issued by an operator with llmgw keys create, and shown once.
-There is no way to recover one: only its hash is stored.
Ask {{if .ContactHref}}{{.Contact}}{{else}}{{.Contact}}{{end}} +for one.
+{{else}} +Keys are issued by whoever operates this gateway. If you do not know who that +is, the address you reached this page at is the place to start asking.
+{{end}} +You will be sent a one-time link. Opening it shows the key once and then the +link stops working, so the key never has to travel through a chat window. Put it +in a password manager straight away — nothing can produce it again, because only +its hash is kept here.
+ +{{if .Notice}}{{.Notice}}
{{end}} + +GET {{.BaseURL}}/v1/models — what your key may useGET {{.BaseURL}}/me — its limits, and what it has spent