From 8d35faf6f878b3b5058d866499a3be7a1f4c62e5 Mon Sep 17 00:00:00 2001
From: Ilker Manap
Date: Wed, 16 Sep 2026 09:22:42 +0200
Subject: [PATCH] Give the landing page somewhere to send people
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
The page explained the API, said keys come from an operator, and left the
reader there. Someone who reaches the address without a key had no route to
getting one, which is where onboarding stopped.
`landing.contact` is that route, because the gateway cannot guess who to ask.
An address becomes a mailto link, an http(s) URL stays a link, and anything
else — a channel, a queue, a person — is shown as text. Other schemes are
never linked: this string comes from configuration, 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. Escaping the text
does not make a scheme safe.
Unconfigured, it now says something rather than nothing, and the page explains
that a key arrives as a one-time link so the reader knows what to expect
before it lands.
Co-Authored-By: Claude Opus 5 (1M context)
---
deploy/examples/server.yaml | 7 +++
docs/onboarding.md | 20 ++++++-
internal/config/config.go | 17 ++++++
internal/router/handlers.go | 3 +-
internal/router/router.go | 5 ++
internal/web/contact.go | 47 +++++++++++++++
internal/web/landing.go | 9 ++-
internal/web/templates/base.css | 3 +
internal/web/templates/landing.html | 23 +++++++-
internal/web/web_test.go | 90 ++++++++++++++++++++++++++---
10 files changed, 210 insertions(+), 14 deletions(-)
create mode 100644 internal/web/contact.go
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
-
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.
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}}
+
+
Once you have one
+
+
GET {{.BaseURL}}/v1/models — what your key may use
+
GET {{.BaseURL}}/me — its limits, and what it has spent