Give the landing page somewhere to send people
CI / test (push) Successful in 56s

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) <noreply@anthropic.com>
This commit is contained in:
Ilker ManapandClaude Opus 5 committed 2026-09-16 09:22:42 +02:00
1 parent 3ed211b2f4
commit 8d35faf6f8
10 files changed
+210 -14

No files matched your search

+7
View File
@@ -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
+18 -2
View File
@@ -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
+17
View File
@@ -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
+2 -1
View File
@@ -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)
+5
View File
@@ -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,
+47
View File
@@ -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:], ".")
}
+8 -1
View File
@@ -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),
})
+3
View File
@@ -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); }
+20 -3
View File
@@ -34,9 +34,26 @@ reach the address.</p>
reach it. That is a deployment choice and only safe on a trusted network.</p>
{{end}}
<h2>Keys</h2>
<p>Keys are issued by an operator with <code>llmgw keys create</code>, and shown once.
There is no way to recover one: only its hash is stored.</p>
<h2>Getting a key</h2>
{{if .Contact}}
<p>Ask {{if .ContactHref}}<a href="{{.ContactHref}}">{{.Contact}}</a>{{else}}<strong>{{.Contact}}</strong>{{end}}
for one.</p>
{{else}}
<p>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.</p>
{{end}}
<p>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.</p>
{{if .Notice}}<p class="note">{{.Notice}}</p>{{end}}
<h2>Once you have one</h2>
<ul>
<li><code>GET {{.BaseURL}}/v1/models</code> — what your key may use</li>
<li><code>GET {{.BaseURL}}/me</code> — its limits, and what it has spent</li>
</ul>
<footer><span>llmgw {{.Version}}</span><span>{{.Now}}</span></footer>
</div></body></html>{{end}}
+83 -7
View File
@@ -24,7 +24,7 @@ func get(t *testing.T, h http.Handler, target string, headers map[string]string)
}
func TestLandingPageTellsYouHowToConnect(t *testing.T) {
code, body := get(t, Landing("v1.2.3", true), "http://llmgw.example/", nil)
code, body := get(t, Landing("v1.2.3", true, "", ""), "http://llmgw.example/", nil)
if code != http.StatusOK {
t.Fatalf("status %d", code)
}
@@ -38,7 +38,7 @@ func TestLandingPageTellsYouHowToConnect(t *testing.T) {
func TestLandingPageSaysNothingAboutWhatIsHere(t *testing.T) {
// It is served without a key, to anyone who can reach the address. Anything
// on it is public, so nothing about the cluster belongs on it.
_, body := get(t, Landing("v1", true), "http://llmgw.example/", nil)
_, body := get(t, Landing("v1", true, "", ""), "http://llmgw.example/", nil)
for _, leak := range []string{"llama", "qwen", "10.0.0.", "replica", "node01"} {
if strings.Contains(strings.ToLower(body), leak) {
t.Errorf("the landing page leaks %q", leak)
@@ -49,11 +49,11 @@ func TestLandingPageSaysNothingAboutWhatIsHere(t *testing.T) {
func TestLandingPageWarnsWhenTheGatewayIsOpen(t *testing.T) {
// Someone who reaches this page on an unauthenticated gateway should learn
// that from the page rather than by discovering they can use it.
_, open := get(t, Landing("v1", false), "http://llmgw.example/", nil)
_, open := get(t, Landing("v1", false, "", ""), "http://llmgw.example/", nil)
if !strings.Contains(open, "no API keys configured") {
t.Error("an open gateway does not say so")
}
_, closed := get(t, Landing("v1", true), "http://llmgw.example/", nil)
_, closed := get(t, Landing("v1", true, "", ""), "http://llmgw.example/", nil)
if strings.Contains(closed, "no API keys configured") {
t.Error("a closed gateway claims to be open")
}
@@ -63,7 +63,7 @@ func TestTheExampleURLSurvivesAReverseProxy(t *testing.T) {
// The process sees http and an internal host; the client used https and a
// public name. An example naming the internal address is one nobody can
// paste anywhere.
_, body := get(t, Landing("v1", true), "http://10.0.0.140:8080/", map[string]string{
_, body := get(t, Landing("v1", true, "", ""), "http://10.0.0.140:8080/", map[string]string{
"X-Forwarded-Proto": "https",
"X-Forwarded-Host": "llmgw.mynodes.xyz",
})
@@ -77,7 +77,7 @@ func TestTheExampleURLSurvivesAReverseProxy(t *testing.T) {
func TestForwardedHeaderChainsTakeTheFirstEntry(t *testing.T) {
// A chain of proxies appends rather than replaces.
_, body := get(t, Landing("v1", true), "http://internal/", map[string]string{
_, body := get(t, Landing("v1", true, "", ""), "http://internal/", map[string]string{
"X-Forwarded-Proto": "https, http",
"X-Forwarded-Host": "llmgw.example, internal",
})
@@ -89,7 +89,7 @@ func TestForwardedHeaderChainsTakeTheFirstEntry(t *testing.T) {
func TestOnlyTheRootIsTheLandingPage(t *testing.T) {
// A catch-all would turn every mistyped path into this page, hiding real
// 404s from anyone debugging a client.
code, _ := get(t, Landing("v1", true), "http://x/v1/chat/completionz", nil)
code, _ := get(t, Landing("v1", true, "", ""), "http://x/v1/chat/completionz", nil)
if code != http.StatusNotFound {
t.Errorf("a mistyped path returned %d", code)
}
@@ -231,3 +231,79 @@ func TestStaticIsNotAFileServer(t *testing.T) {
}
}
}
func TestTheLandingPageSaysWhereToGetAKey(t *testing.T) {
// A page that explains the API and leaves the reader with no route to using
// it is where onboarding stops.
_, body := get(t, Landing("v1", true, "platform@example.com", ""), "http://x/", nil)
if !strings.Contains(body, `href="mailto:platform@example.com"`) {
t.Error("an address was not turned into a mailto link")
}
if !strings.Contains(body, "one-time link") {
t.Error("the page does not say how a key will arrive")
}
}
func TestContactRenderingByKind(t *testing.T) {
cases := []struct{ in, text, href string }{
{"platform@example.com", "platform@example.com", "mailto:platform@example.com"},
{"mailto:ops@example.com", "mailto:ops@example.com", "mailto:ops@example.com"},
{"https://wiki.example/llmgw", "https://wiki.example/llmgw", "https://wiki.example/llmgw"},
{"http://wiki.example", "http://wiki.example", "http://wiki.example"},
// Not addresses and not URLs: shown, not linked.
{"#platform on Slack", "#platform on Slack", ""},
{"Ayse", "Ayse", ""},
{"", "", ""},
{" ", "", ""},
}
for _, c := range cases {
text, href := contactLink(c.in)
if text != c.text || href != c.href {
t.Errorf("contactLink(%q) = (%q, %q), want (%q, %q)", c.in, text, href, c.text, c.href)
}
}
}
func TestADangerousContactSchemeIsNeverLinked(t *testing.T) {
// This string comes from configuration, and configuration is not always
// written by whoever runs the gateway. A javascript: href on a page served
// to every visitor is a stored XSS with a very short path to it; escaping
// the text does not make the scheme safe.
for _, bad := range []string{
"javascript:alert(1)",
"JavaScript:alert(1)",
"data:text/html,<script>alert(1)</script>",
"vbscript:msgbox(1)",
"file:///etc/passwd",
} {
text, href := contactLink(bad)
if href != "" {
t.Errorf("contactLink(%q) produced href %q", bad, href)
}
if text == "" {
t.Errorf("contactLink(%q) dropped the text entirely", bad)
}
_, body := get(t, Landing("v1", true, bad, ""), "http://x/", nil)
if strings.Contains(body, "href=\"javascript") || strings.Contains(body, "href=\"data:") {
t.Errorf("%q reached the page as a link", bad)
}
}
}
func TestTheNoticeIsEscaped(t *testing.T) {
_, body := get(t, Landing("v1", true, "", "<script>alert(1)</script>"), "http://x/", nil)
if strings.Contains(body, "<script>alert(1)</script>") {
t.Error("the notice was rendered as markup")
}
if !strings.Contains(body, "&lt;script&gt;") {
t.Error("the notice was dropped rather than escaped")
}
}
func TestWithoutAContactThePageStillSaysSomethingUseful(t *testing.T) {
_, body := get(t, Landing("v1", true, "", ""), "http://x/", nil)
if !strings.Contains(body, "whoever operates this gateway") {
t.Error("an unconfigured gateway leaves the reader with nothing")
}
}