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:
1 parent
3ed211b2f4
commit
8d35faf6f8
10 files changed
+210
-14
No files matched your search
@@ -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
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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)
|
||||
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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:], ".")
|
||||
}
|
||||
@@ -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),
|
||||
})
|
||||
|
||||
@@ -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); }
|
||||
@@ -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}}
|
||||
@@ -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, "<script>") {
|
||||
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")
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user