Key lifecycle: lifetime limits by scope, rotation with overlap, kinds and expiry in the listing

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Ilker ManapandClaude Opus 5.5 committed 2026-10-04 16:45:05 +02:00
1 parent 178964cf6a
commit 8866a1ea0f
14 files changed
+463 -5

No files matched your search

+3 -1
View File
@@ -391,7 +391,9 @@ portal is not done — the page shows; the console and ctl change.
balancer the callback must reach the one that started it (sticky
sessions) until the key comes from the store. **OIDC/SSO login (M), then SCIM (M).** `internal/account/service.go`,
`internal/web/account.go`; map IdP groups to org/team/admin.
3. **Service accounts and key lifecycle (S).** Per-org maximum key TTL,
3. **Done (branch `features-c`):** key lifetime limits (gateway, org, team,
project), `keys rotate --overlap`, kinds and expiry in `keys list`.
**Service accounts and key lifecycle (S).** Per-org maximum key TTL,
`keys rotate` with overlap, last-used shown, project-owned service keys
listed apart. `internal/cli/keys.go`, `internal/store/keys.go`,
`internal/auth/auth.go`.
+12
View File
@@ -49,6 +49,18 @@ APIs change between minors without a deprecation period.
Deleting a user suspends the account.
- **Groups:** joining and leaving the groups `auth.oidc` maps gives and
takes away staff roles and places in the tree.
- **Key lifecycle.**
- **Lifetime limits:** `auth.max_key_ttl` limits how long any key may
live, and `llmgw keys ttl team:Acme/ml 720h` sets shorter limits for an
organization, team or project. A key is made within the shortest that
applies, and one asked for with no expiry is given that longest — from
the CLI, the profile page and the editor connect page alike.
- **Rotation:** `llmgw keys rotate <id> --overlap 48h` issues a
replacement where the old key was, and the old one stops after the
overlap.
- **Listing:** `keys list --all` shows each key's kind — service (a
project's), member, personal — with service keys first, and when it
expires.
### Guardrails
+9
View File
@@ -35,6 +35,7 @@ rather than repeated.
| `signup_open` | `bool` | [Auth](#auth) |
| `oidc` | `OIDC` | [Auth](#auth) |
| `scim` | `SCIM` | [Auth](#auth) |
| `max_key_ttl` | `time.Duration` | [Auth](#auth) |
| `personal` | `Personal` | [Auth](#auth) |
| `pricing` | `map[string]Price` | [Auth](#auth) |
| `default_price` | `Price` | [Auth](#auth) |
@@ -443,6 +444,14 @@ SCIM is account provisioning by the identity provider.
Takes a [SCIM](#scim) block.
### `max_key_ttl`
`time.Duration`
MaxKeyTTL is how long any API key may live; a key asked for with no
expiry is given this. Organizations, teams and projects can set
shorter ones (llmgw keys ttl). Zero is no limit.
### `personal`
`Personal`
+175 -3
View File
@@ -7,6 +7,7 @@ import (
"errors"
"fmt"
"math"
"slices"
"strings"
"text/tabwriter"
"time"
@@ -37,6 +38,8 @@ func newTenancyCmd() *cobra.Command {
newKeyCreateCmd(open),
newKeyListCmd(open),
newKeyRevokeCmd(open),
newKeyRotateCmd(open),
newKeyTTLCmd(open),
newLimitsCmd(open),
newThreadsCmd(open),
newMemoryCmd(open),
@@ -220,15 +223,20 @@ func newKeyListCmd(open opener) *cobra.Command {
return err
}
w := tabwriter.NewWriter(cmd.OutOrStdout(), 0, 0, 2, ' ', 0)
fmt.Fprintln(w, "ID\tNAME\tKEY\tPROJECT\tOWNER\tSTATE\tLAST USED")
fmt.Fprintln(w, "ID\tNAME\tKIND\tKEY\tPROJECT\tOWNER\tSTATE\tEXPIRES\tLAST USED")
now := time.Now()
// Service keys — a project's, nobody's own — first: they are
// the ones nobody leaving the company takes with them.
slices.SortStableFunc(rows, func(a, b store.KeyRow) int {
return strings.Compare(keyKind(a.Key), keyKind(b.Key))
})
for _, r := range rows {
where := r.ProjectPath
if where == "" {
where = "personal"
}
fmt.Fprintf(w, "%s\t%s\t%s\t%s\t%s\t%s\t%s\n", r.ID, r.Name, r.Prefix,
where, dash(r.OwnerEmail), keyState(r.Key, now), ago(r.LastUsedAt, now))
fmt.Fprintf(w, "%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n", r.ID, r.Name, keyKind(r.Key), r.Prefix,
where, dash(r.OwnerEmail), keyState(r.Key, now), until(r.ExpiresAt, now), ago(r.LastUsedAt, now))
}
return w.Flush()
}
@@ -387,6 +395,33 @@ func newLimitsCmd(open opener) *cobra.Command {
return cmd
}
// keyKind says whose a key is: a project's (service), a person's in a
// project (member), or a person's own (personal).
func keyKind(k store.Key) string {
switch {
case k.UserID == "":
return "service"
case k.ProjectID == "":
return "personal"
}
return "member"
}
// until is how long a key has left, or "never".
func until(t, now time.Time) string {
if t.IsZero() {
return "never"
}
if !t.After(now) {
return "-"
}
d := t.Sub(now)
if d > 48*time.Hour {
return fmt.Sprintf("in %dd", int(d.Hours()/24))
}
return "in " + d.Round(time.Minute).String()
}
func keyState(k store.Key, now time.Time) string {
switch {
case !k.RevokedAt.IsZero():
@@ -427,3 +462,140 @@ func randomID(prefix string) string {
_, _ = rand.Read(buf[:])
return prefix + "-" + strings.ToLower(base32.StdEncoding.WithPadding(base32.NoPadding).EncodeToString(buf[:]))
}
func newKeyRotateCmd(open opener) *cobra.Command {
var overlap time.Duration
cmd := &cobra.Command{
Use: "rotate <key-id>",
Short: "Replace a key with a new one, the old one working on for a while",
Long: "The new key belongs where the old one did — the same project, owner, band\n" +
"and routing profile, and as long a life — and is printed once. The old\n" +
"one stops working after --overlap, so whatever uses it can be moved over\n" +
"without an outage.",
Example: " llmgw keys rotate key-7f3a --overlap 48h",
Args: cobra.ExactArgs(1),
RunE: func(cmd *cobra.Command, args []string) error {
s, err := open(cmd.Context())
if err != nil {
return err
}
defer s.Close()
old, err := s.KeyByID(cmd.Context(), args[0])
if err != nil {
return fmt.Errorf("no key %s: %w", args[0], err)
}
if !old.RevokedAt.IsZero() {
return fmt.Errorf("%s is revoked; make a new key instead", old.ID)
}
secret, k, err := store.NewKey(randomID("key"), old.Name, old.ProjectID)
if err != nil {
return err
}
k.CreatedAt = time.Now()
k.Band, k.RoutingProfile, k.UserID = old.Band, old.RoutingProfile, old.UserID
if !old.ExpiresAt.IsZero() {
k.ExpiresAt = k.CreatedAt.Add(old.ExpiresAt.Sub(old.CreatedAt))
}
if err := s.CreateKey(cmd.Context(), k); err != nil {
return err
}
retire := time.Now().Add(overlap)
if err := s.ExpireKeyBy(cmd.Context(), old.ID, retire); err != nil {
return err
}
fmt.Fprintln(cmd.OutOrStdout(), secret)
cmd.PrintErrf("\nid %s (replaces %s)\nold key stops working at %s\n", k.ID, old.ID,
retire.UTC().Format(time.RFC3339))
return nil
},
}
cmd.Flags().DurationVar(&overlap, "overlap", 24*time.Hour, "how long the old key keeps working")
return cmd
}
func newKeyTTLCmd(open opener) *cobra.Command {
return &cobra.Command{
Use: "ttl [<org|team|project>:<name> <duration|off>]",
Short: "How long a key may live at most, in a part of the tree",
Long: "A key is made within the shortest limit that applies to it — its\n" +
"project's, its team's, its organization's, and auth.max_key_ttl in\n" +
"server.yaml for every key. A key asked for with no expiry is given the\n" +
"longest allowed. Existing keys are not changed. Without arguments, lists\n" +
"the limits.",
Example: " llmgw keys ttl team:Acme/ml 720h\n llmgw keys ttl team:Acme/ml off",
Args: cobra.RangeArgs(0, 2),
RunE: func(cmd *cobra.Command, args []string) error {
s, err := open(cmd.Context())
if err != nil {
return err
}
defer s.Close()
if len(args) == 0 {
limits, err := s.KeyTTLs(cmd.Context())
if err != nil {
return err
}
if len(limits) == 0 {
fmt.Fprintln(cmd.OutOrStdout(), "No limit: keys may live for ever.")
return nil
}
names := make([]string, 0, len(limits))
for k := range limits {
names = append(names, k)
}
slices.Sort(names)
w := tabwriter.NewWriter(cmd.OutOrStdout(), 0, 0, 2, ' ', 0)
fmt.Fprintln(w, "SCOPE\tLONGEST")
for _, n := range names {
fmt.Fprintf(w, "%s\t%s\n", strings.TrimSuffix(n, ":"), limits[n])
}
return w.Flush()
}
if len(args) != 2 {
return errors.New("give a scope and a duration, or off")
}
kind, name, ok := strings.Cut(args[0], ":")
if !ok {
return fmt.Errorf("%q is not org:NAME, team:NAME or project:NAME", args[0])
}
var id string
switch store.Scope(kind) {
case store.ScopeOrg:
o, err := resolveOrg(cmd.Context(), s, name)
if err != nil {
return err
}
id = o.ID
case store.ScopeTeam:
t, err := resolveTeam(cmd.Context(), s, name)
if err != nil {
return err
}
id = t.ID
case store.ScopeProject:
p, err := resolveProject(cmd.Context(), s, name)
if err != nil {
return err
}
id = p.ID
default:
return fmt.Errorf("%q: org, team or project — the gateway's is auth.max_key_ttl in server.yaml", kind)
}
var d time.Duration
if args[1] != "off" {
if d, err = time.ParseDuration(args[1]); err != nil || d <= 0 {
return fmt.Errorf("%q is not a duration like 720h, or off", args[1])
}
}
if err := s.SetMaxKeyTTL(cmd.Context(), store.Scope(kind), id, d); err != nil {
return err
}
if d == 0 {
fmt.Fprintf(cmd.OutOrStdout(), "%s: no limit of its own\n", args[0])
} else {
fmt.Fprintf(cmd.OutOrStdout(), "%s: keys live %s at most\n", args[0], d)
}
return nil
},
}
}
+51
View File
@@ -0,0 +1,51 @@
package cli
import (
"path/filepath"
"regexp"
"strings"
"testing"
"time"
"gitea.mynodes.xyz/ilker/llmgw/internal/store"
)
func TestAKeyIsRotatedWithAnOverlapAndKeysLiveWithinTheirLimit(t *testing.T) {
db := filepath.Join(t.TempDir(), "s.db")
mustRun(t, db, "org", "add", "org", "Acme")
mustRun(t, db, "org", "add", "team", "ml", "--in", "Acme")
mustRun(t, db, "org", "add", "project", "train", "--in", "Acme/ml")
mustRun(t, db, "keys", "ttl", "team:Acme/ml", "720h")
if out := mustRun(t, db, "keys", "ttl"); !strings.Contains(out, "720h") {
t.Errorf("listing: %s", out)
}
if _, err := run(t, db, "keys", "create", "ci", "--project", "train", "--expires-in", "2000h"); err == nil {
t.Error("a key past the team's limit was made")
}
mustRun(t, db, "keys", "create", "ci", "--project", "train")
list := mustRun(t, db, "keys", "list", "--all")
if !strings.Contains(list, "service") || !strings.Contains(list, "in 29d") && !strings.Contains(list, "in 30d") {
t.Errorf("a service key, given the team's longest life:\n%s", list)
}
id := regexp.MustCompile(`key-[a-z0-9]+`).FindString(list)
out := mustRun(t, db, "keys", "rotate", id, "--overlap", "2h")
if !strings.HasPrefix(strings.TrimSpace(out), store.KeyPrefix) {
t.Errorf("the new key was not printed: %q", out)
}
s, err := store.Open(t.Context(), db)
if err != nil {
t.Fatal(err)
}
defer s.Close()
old, _ := s.KeyByID(t.Context(), id)
if d := time.Until(old.ExpiresAt); d > 2*time.Hour+time.Minute || d < time.Hour {
t.Errorf("the old key stops in %s, expected about 2h", d)
}
rows, _ := s.AllKeys(t.Context())
if len(rows) != 2 {
t.Errorf("%d keys after rotating", len(rows))
}
}
+7
View File
@@ -119,6 +119,13 @@ func newServerCmd() *cobra.Command {
if err != nil {
return err
}
// The longest any key may live, where every way of making one
// reads it: the store.
if st := rt.Store(); st != nil {
if err := st.SetMaxKeyTTL(cmd.Context(), storepkg.ScopeGateway, "", cfg.Auth.MaxKeyTTL); err != nil {
log.Warn("could not record auth.max_key_ttl", "err", err)
}
}
// Guardrails, when server.yaml defines any. Attachments to
// parts of the tenancy tree live in the store; without one, only
// guard.default applies.
+5
View File
@@ -295,6 +295,11 @@ type Auth struct {
// SCIM is account provisioning by the identity provider.
SCIM SCIM `koanf:"scim"`
// MaxKeyTTL is how long any API key may live; a key asked for with no
// expiry is given this. Organizations, teams and projects can set
// shorter ones (llmgw keys ttl). Zero is no limit.
MaxKeyTTL time.Duration `koanf:"max_key_ttl"`
// Personal is what a person may do on their own, outside any project: make
// personal keys and use the chat page personally, within these limits.
Personal Personal `koanf:"personal"`
+1
View File
@@ -29,6 +29,7 @@ var Reference = []Block{
{Key: "signup_open", Type: "bool", Doc: "SignupOpen serves the signup form. Accounts it creates are pending until\nan operator approves them, so this is not a way in — but turning it off\nmeans accounts are made with `llmgw users create` instead.", Nested: ""},
{Key: "oidc", Type: "OIDC", Doc: "OIDC is sign-in through an identity provider.", Nested: "config.OIDC"},
{Key: "scim", Type: "SCIM", Doc: "SCIM is account provisioning by the identity provider.", Nested: "config.SCIM"},
{Key: "max_key_ttl", Type: "time.Duration", Doc: "MaxKeyTTL is how long any API key may live; a key asked for with no\nexpiry is given this. Organizations, teams and projects can set\nshorter ones (llmgw keys ttl). Zero is no limit.", Nested: ""},
{Key: "personal", Type: "Personal", Doc: "Personal is what a person may do on their own, outside any project: make\npersonal keys and use the chat page personally, within these limits.", Nested: "config.Personal"},
{Key: "pricing", Type: "map[string]Price", Doc: "Pricing is what each model costs, for budgets. A model absent from the\ntable costs whatever DefaultPrice says, which is nothing unless set.", Nested: ""},
{Key: "default_price", Type: "Price", Doc: "", Nested: "config.Price"},
+1
View File
@@ -57,6 +57,7 @@ var copyOrder = []string{
"guard_attachments",
// Who changed what is not lost by moving the store.
"audit_events",
"key_ttl",
}
// notCopied are tables deliberately left behind.
+123
View File
@@ -0,0 +1,123 @@
package store
import (
"context"
"database/sql"
"errors"
"fmt"
"time"
)
// ScopeGateway is the whole gateway, for settings that apply everywhere.
const ScopeGateway Scope = "gateway"
// ErrKeyTTL is a key asked to live longer than a scope allows.
var ErrKeyTTL = errors.New("a key may not live that long here")
// SetMaxKeyTTL sets how long a key may live at most in a scope; zero takes
// the limit away.
func (s *DB) SetMaxKeyTTL(ctx context.Context, scope Scope, id string, max time.Duration) error {
if max <= 0 {
_, err := s.db.ExecContext(ctx, `DELETE FROM key_ttl WHERE scope = ? AND scope_id = ?`, string(scope), id)
return err
}
_, err := s.db.ExecContext(ctx, `INSERT INTO key_ttl (scope, scope_id, max_seconds) VALUES (?, ?, ?)
ON CONFLICT (scope, scope_id) DO UPDATE SET max_seconds = excluded.max_seconds`,
string(scope), id, int64(max/time.Second))
return err
}
// KeyTTLs lists every limit, "scope:id" to the longest a key may live.
func (s *DB) KeyTTLs(ctx context.Context) (map[string]time.Duration, error) {
type row struct {
k string
d time.Duration
}
rows, err := queryAll(ctx, s.db, `SELECT scope, scope_id, max_seconds FROM key_ttl`, nil,
func(r *sql.Rows) (row, error) {
var sc, id string
var n int64
err := r.Scan(&sc, &id, &n)
return row{sc + ":" + id, time.Duration(n) * time.Second}, err
})
out := map[string]time.Duration{}
for _, r := range rows {
out[r.k] = r.d
}
return out, err
}
// MaxKeyTTL is the longest a key in a project may live, and the scope that
// says so: the shortest of the gateway's, and the project's, its team's and
// its organization's. Zero when nothing limits it. A personal key (no
// project) has only the gateway's.
func (s *DB) MaxKeyTTL(ctx context.Context, projectID string) (time.Duration, string, error) {
limits, err := s.KeyTTLs(ctx)
if err != nil || len(limits) == 0 {
return 0, "", err
}
scopes := []string{string(ScopeGateway) + ":"}
if projectID != "" {
parents, err := s.ScopeParents(ctx)
if err != nil {
return 0, "", err
}
scopes = append(scopes, "project:"+projectID)
scopes = append(scopes, parents["project:"+projectID]...)
}
var best time.Duration
by := ""
for _, sc := range scopes {
if d, ok := limits[sc]; ok && (best == 0 || d < best) {
best, by = d, sc
}
}
return best, by, nil
}
// keyTTL gives a key that asks for no expiry the longest its scope allows,
// and refuses one that asks to outlive it.
func (s *DB) keyTTL(ctx context.Context, k Key) (Key, error) {
max, by, err := s.MaxKeyTTL(ctx, k.ProjectID)
if err != nil || max == 0 {
return k, err
}
created := k.CreatedAt
if created.IsZero() {
created = time.Now()
}
if k.ExpiresAt.IsZero() {
k.ExpiresAt = created.Add(max)
return k, nil
}
if k.ExpiresAt.Sub(created) > max+time.Minute {
return k, fmt.Errorf("%w: %s allows %s at most", ErrKeyTTL, by, max)
}
return k, nil
}
// KeyByID finds a key by its id.
func (s *DB) KeyByID(ctx context.Context, id string) (Key, error) {
row := s.db.QueryRowContext(ctx, `SELECT `+keyColumns+` FROM api_keys WHERE id = ?`, id)
k, err := scanKey(row)
if errors.Is(err, sql.ErrNoRows) {
return Key{}, ErrNotFound
}
return k, err
}
// ExpireKeyBy has a key stop working at a moment, unless it stops sooner
// already: what rotating it does to the old one.
func (s *DB) ExpireKeyBy(ctx context.Context, id string, at time.Time) error {
res, err := s.db.ExecContext(ctx, `UPDATE api_keys SET expires_at = ?
WHERE id = ? AND revoked_at IS NULL AND (expires_at IS NULL OR expires_at > ?)`, millis(at), id, millis(at))
if err != nil {
return err
}
if n, _ := res.RowsAffected(); n == 0 {
if _, err := s.KeyByID(ctx, id); err != nil {
return err
}
}
return nil
}
+52
View File
@@ -0,0 +1,52 @@
package store
import (
"errors"
"testing"
"time"
)
func TestAKeyIsMadeWithinTheShortestLifeItsScopesAllow(t *testing.T) {
db := capacityStore(t)
ctx := t.Context()
org, _ := db.CreateOrg(ctx, "acme")
team, _ := db.CreateTeam(ctx, org, "ml")
project, _ := db.CreateProject(ctx, team, "train")
key := func(id string, life time.Duration) Key {
k := Key{ID: id, Hash: []byte(id), Prefix: id, Name: id, ProjectID: project, CreatedAt: time.Now()}
if life > 0 {
k.ExpiresAt = k.CreatedAt.Add(life)
}
return k
}
if err := db.CreateKey(ctx, key("k0", 0)); err != nil {
t.Fatalf("nothing limits it: %v", err)
}
_ = db.SetMaxKeyTTL(ctx, ScopeGateway, "", 90*24*time.Hour)
_ = db.SetMaxKeyTTL(ctx, ScopeTeam, team, 30*24*time.Hour)
if max, by, _ := db.MaxKeyTTL(ctx, project); max != 30*24*time.Hour || by != "team:"+team {
t.Errorf("max %s by %s", max, by)
}
// One that asks for no expiry is given the longest allowed.
if err := db.CreateKey(ctx, key("k1", 0)); err != nil {
t.Errorf("one that asks for no expiry: %v", err)
}
if k, err := db.KeyByHash(ctx, []byte("k1")); err != nil || k.ExpiresAt.Sub(k.CreatedAt) < 29*24*time.Hour ||
k.ExpiresAt.Sub(k.CreatedAt) > 31*24*time.Hour {
t.Errorf("given %v %v", k.ExpiresAt.Sub(k.CreatedAt), err)
}
if err := db.CreateKey(ctx, key("k2", 60*24*time.Hour)); !errors.Is(err, ErrKeyTTL) {
t.Errorf("one past the team's: %v", err)
}
if err := db.CreateKey(ctx, key("k3", 7*24*time.Hour)); err != nil {
t.Errorf("one within: %v", err)
}
// A personal key has only the gateway's.
if max, _, _ := db.MaxKeyTTL(ctx, ""); max != 90*24*time.Hour {
t.Errorf("personal %s", max)
}
_ = db.SetMaxKeyTTL(ctx, ScopeTeam, team, 0)
if max, _, _ := db.MaxKeyTTL(ctx, project); max != 90*24*time.Hour {
t.Errorf("after the team's is taken away: %s", max)
}
}
@@ -0,0 +1,10 @@
-- Ported from the SQLite migration of the same number.
-- How long a key may live, at most: for the whole gateway (scope gateway,
-- written from server.yaml when the server starts) and for an organization,
-- team or project. A key is made within the shortest that applies to it.
CREATE TABLE key_ttl (
scope TEXT NOT NULL,
scope_id TEXT NOT NULL,
max_seconds BIGINT NOT NULL,
PRIMARY KEY (scope, scope_id)
);
@@ -0,0 +1,9 @@
-- How long a key may live, at most: for the whole gateway (scope gateway,
-- written from server.yaml when the server starts) and for an organization,
-- team or project. A key is made within the shortest that applies to it.
CREATE TABLE key_ttl (
scope TEXT NOT NULL,
scope_id TEXT NOT NULL,
max_seconds INTEGER NOT NULL,
PRIMARY KEY (scope, scope_id)
);
+5 -1
View File
@@ -168,7 +168,11 @@ func (s *DB) CreateKey(ctx context.Context, k Key) error {
if len(k.Hash) == 0 {
return errors.New("store: a key needs a hash")
}
_, err := s.db.ExecContext(ctx,
k, err := s.keyTTL(ctx, k)
if err != nil {
return err
}
_, err = s.db.ExecContext(ctx,
`INSERT INTO api_keys (`+keyColumns+`) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
k.ID, k.Hash, k.Prefix, k.Name, nullString(k.ProjectID),
nullString(k.Band), nullString(k.RoutingProfile),