Onboard users with one-time links instead of pasted keys

Issuing a key worked; getting it to the person it was issued for did not. The
operator had a secret on their terminal and no way to send it that did not
leave a bearer credential in a chat log forever.

`keys create --claim` prints a link instead. GET shows a button and consumes
nothing; POST reveals the key and burns the link. That split is not politeness
— chat clients, mail scanners and link previewers fetch URLs the moment they
are posted, so a GET that consumed the claim would mean the first thing to
unfurl the link destroys the key before anyone reads it.

A pending claim has to hold the key somewhere, which would otherwise put a
working credential in the database and undo what hashing bought. So the key is
sealed with a key derived from the link's own token, and the token is never
stored — only its hash. A database leak yields two useless hashes and a blob
nothing in the database can open. HKDF rather than the raw token, so the value
used for lookup can never become the value that decrypts.

Consuming is one UPDATE moving claimed_at off NULL, so two people opening the
same link produce one key rather than two copies. A used link, an expired one
and a token that was never real all render identically, because saying which
confirms that a token was once valid. The page is no-store, no-referrer and
noindex: the URL is itself the credential.

`GET /me` reports a key's own limits and spend, so nobody has to ask an
operator to read a dashboard they cannot reach. Outside /v1, because it is not
part of the OpenAI API.

docs/onboarding.md is written for whoever operates this, including the parts
that are deliberately absent — no self-service, no SSO, and why.

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:11:28 +02:00
1 parent cd3233ffe8
commit 3ed211b2f4
16 files changed
+1164 -23

No files matched your search

+133
View File
@@ -308,3 +308,136 @@ func TestWithoutAuthTheGatewayStillServes(t *testing.T) {
t.Errorf("an unauthenticated gateway refused a request: %d %s", code, msg)
}
}
func TestOnboardingAUserEndToEnd(t *testing.T) {
// The whole flow an operator actually performs: issue a key as a one-time
// link, hand the link over, and have the person collect it and start using
// the gateway.
path, _ := provision(t)
// The operator's side.
var link string
withStore(t, path, func(s *store.SQLite) {
secret, k, err := store.NewKey("key-new", "ayse-laptop", "proj")
if err != nil {
t.Fatal(err)
}
k.CreatedAt = time.Now()
if err := s.CreateKey(context.Background(), k); err != nil {
t.Fatal(err)
}
token, err := store.NewClaimToken()
if err != nil {
t.Fatal(err)
}
if err := s.CreateClaim(context.Background(), k.ID, token, secret, store.ClaimTTL); err != nil {
t.Fatal(err)
}
link = "/claim/" + token
})
h := start(t, 2, func(c *config.Server) {
c.Auth = config.Auth{Enabled: true, Store: path, CacheTTL: 50 * time.Millisecond}
})
page := func(method string) (int, string) {
req, err := http.NewRequestWithContext(context.Background(), method, h.router.URL+link, nil)
if err != nil {
t.Fatal(err)
}
resp, err := http.DefaultClient.Do(req)
if err != nil {
t.Fatal(err)
}
defer resp.Body.Close()
b, _ := io.ReadAll(resp.Body)
return resp.StatusCode, string(b)
}
// Something unfurls the link in a chat client. It must not burn it.
if code, body := page(http.MethodGet); code != http.StatusOK || strings.Contains(body, "sk-llmgw-") {
t.Fatalf("a preview fetch revealed or destroyed the key: %d", code)
}
// The person opens it and reveals.
code, body := page(http.MethodPost)
if code != http.StatusOK {
t.Fatalf("revealing failed: %d", code)
}
key := extractKey(t, body)
// And the key works.
if code, msg := h.call(t, key, testModel); code != http.StatusOK {
t.Fatalf("the collected key does not work: %d %s", code, msg)
}
// The link is spent.
if code, _ := page(http.MethodPost); code != http.StatusGone {
t.Errorf("the link worked a second time: %d", code)
}
}
func extractKey(t *testing.T, body string) string {
t.Helper()
i := strings.Index(body, store.KeyPrefix)
if i < 0 {
t.Fatal("no key on the page")
}
rest := body[i:]
end := strings.IndexAny(rest, "<\n ")
if end < 0 {
t.Fatal("the key is not delimited")
}
return rest[:end]
}
func TestTheSelfDescriptionEndpointAnswersWithoutAnOperator(t *testing.T) {
// So a user can see their own limits and spend rather than asking someone
// with access to the dashboard.
path, mint := provision(t)
key := mint(t, "curious")
withStore(t, path, func(s *store.SQLite) {
rpm := 42
if err := s.PutLimits(context.Background(), store.Limits{
Scope: store.ScopeKey, ScopeID: "key-curious",
RPM: &rpm, AllowedModels: []string{testModel},
}); err != nil {
t.Fatal(err)
}
})
h := start(t, 2, func(c *config.Server) {
c.Auth = config.Auth{Enabled: true, Store: path, CacheTTL: 50 * time.Millisecond}
})
req, _ := http.NewRequestWithContext(context.Background(), http.MethodGet, h.router.URL+"/me", nil)
req.Header.Set("Authorization", "Bearer "+key)
resp, err := http.DefaultClient.Do(req)
if err != nil {
t.Fatal(err)
}
defer resp.Body.Close()
var me struct {
Authenticated bool `json:"authenticated"`
KeyID string `json:"key_id"`
Key string `json:"key"`
Limits struct {
RPM int `json:"requests_per_minute"`
AllowedModels []string `json:"allowed_models"`
} `json:"limits"`
}
if err := json.NewDecoder(resp.Body).Decode(&me); err != nil {
t.Fatal(err)
}
if !me.Authenticated || me.KeyID != "key-curious" {
t.Errorf("/me returned %+v", me)
}
if me.Limits.RPM != 42 || len(me.Limits.AllowedModels) != 1 {
t.Errorf("limits came back as %+v", me.Limits)
}
// It describes the key; it must not repeat it.
if strings.Contains(me.Key, "…") == false || len(me.Key) > 24 {
t.Errorf("/me returned more of the key than a display prefix: %q", me.Key)
}
}