aigetwey 1.2.0 → 1.3.0

package/src/config.ts

@@ -18,21 +18,9 @@ export { clientKeyFingerprint } from "./middleware/auth.js";
 // Shape differs from a flat OpenAI gateway: routing lives in a top-level
 // `models[]` layer (alias -> provider chain), the endpoint block carries the
 // token-saver toggles, and providers may be free passthroughs or service-account
-// backed. The handler/keypool/quota phases read these fields; defining the full
+// backed. The handler/keypool phases read these fields; defining the full
 // shape up front avoids reshaping config across later phases.
 
-/** Token quota window for a provider — drives the dashboard reset countdown. */
-const QuotaSchema = z.object({
-  window: z.enum(["5h", "daily", "weekly", "monthly"]),
-  // daily: "HH:MM" local reset; weekly: weekday name ("monday"); others: ignored.
-  reset_at: z.string().optional(),
-  timezone: z.string().default("UTC"),
-  // optional ceiling for a progress bar; quota tracking works without it.
-  limit_tokens: z.number().int().positive().optional(),
-  // soft-alert threshold (0..1); UI flags the quota when pct >= this. Default 0.8.
-  alert_at: z.number().gt(0).lte(1).optional(),
-});
-
 const ProviderModelSchema = z.object({
   id: z.string().min(1),
   price_in: z.number().nonnegative().optional(),
@@ -59,7 +47,6 @@ const ProviderSchema = z
     service_account: z.string().optional(),
     models: z.array(ProviderModelSchema).default([]),
     headers: z.record(z.string()).optional(),
-    quota: QuotaSchema.optional(),
     // when true the provider is skipped in routing (kept in config, like a key's
     // disabled state but for the whole provider).
     disabled: z.boolean().optional(),
@@ -120,14 +107,20 @@ const ServerSchema = z
     // optional friendly label per key, keyed by the key itself. Kept separate so
     // api_keys stays a plain string[] (auth/masking paths untouched).
     key_names: z.record(z.string()).optional(),
+    // per-key model allowlist (call-strings) + rate limit (req/min), keyed by the
+    // raw key like key_names. Absent → unrestricted / unlimited.
+    key_models: z.record(z.array(z.string().min(1))).optional(),
+    key_rpm: z.record(z.number().int().positive()).optional(),
+    // per-key access expiry, epoch ms, keyed by the RAW key. Absent → never expires.
+    key_expires: z.record(z.number().int().positive()).optional(),
   })
   .default({ host: "127.0.0.1", port: 18080, api_keys: [] });
 
 /**
  * A spend budget scoped to the whole gateway, one provider, or one upstream
  * model. unit picks what `limit` means — USD cost or total tokens. Soft-alert at
- * alert_at (default 0.8), hard-stop at 100%. Window math reuses the quota
- * calendar engine. Opt-in: omit / empty list to disable.
+ * alert_at (default 0.8), hard-stop at 100%. Each window is a rolling tumbling
+ * bucket on the epoch grid (window.ts). Opt-in: omit / empty list to disable.
  */
 const BudgetScopeSchema = z.discriminatedUnion("type", [
   z.object({ type: z.literal("global") }),
@@ -136,13 +129,21 @@ const BudgetScopeSchema = z.discriminatedUnion("type", [
   z.object({ type: z.literal("key"), id: z.string().min(1) }),
 ]);
 
+// rolling windows replaced the old calendar windows; coerce any legacy value so
+// existing config.yaml budgets keep loading (daily→24h, weekly→7day, monthly→30day).
+const LEGACY_WINDOW: Record<string, string> = { daily: "24h", weekly: "7day", monthly: "30day" };
+const WindowSchema = z.preprocess(
+  (v) => (typeof v === "string" && v in LEGACY_WINDOW ? LEGACY_WINDOW[v] : v),
+  z.enum(["5h", "24h", "7day", "30day"]),
+);
+
 const BudgetSchema = z.object({
   scope: BudgetScopeSchema,
   unit: z.enum(["usd", "tokens"]),
   limit: z.number().positive(),
-  window: z.enum(["5h", "daily", "weekly", "monthly"]),
-  reset_at: z.string().optional(),
-  timezone: z.string().default("UTC"),
+  window: WindowSchema,
+  // epoch ms the recurring cycle is anchored to; stamped by setBudget on create.
+  anchor: z.number().int().nonnegative().optional(),
   alert_at: z.number().gt(0).lte(1).optional(),
   // optional free-text label so an operator remembers what a budget is for.
   note: z.string().max(200).optional(),
@@ -157,7 +158,6 @@ const ConfigSchema = z.object({
   budgets: z.array(BudgetSchema).default([]),
 });
 
-export type Quota = z.infer<typeof QuotaSchema>;
 export type ProviderModel = z.infer<typeof ProviderModelSchema>;
 export type Provider = z.infer<typeof ProviderSchema>;
 export type ModelRoute = z.infer<typeof ModelRouteSchema>;
@@ -790,7 +790,7 @@ export function budgetKey(scope: BudgetScope): string {
 }
 
 /** Add a budget, or replace the existing one with the same scope key. */
-export function setBudget(config: Config, budget: Budget): Config {
+export function setBudget(config: Config, budget: Budget, now: number = Date.now()): Config {
   if (budget.scope.type === "provider") {
     const { id } = budget.scope;
     if (!config.providers.some((p) => p.id === id)) {
@@ -806,8 +806,16 @@ export function setBudget(config: Config, budget: Budget): Config {
   const next = cloneConfig(config);
   const key = budgetKey(budget.scope);
   const idx = next.budgets.findIndex((b) => budgetKey(b.scope) === key);
-  if (idx === -1) next.budgets.push(budget);
-  else next.budgets[idx] = budget;
+  if (idx === -1) {
+    next.budgets.push({ ...budget, anchor: budget.anchor ?? now });
+  } else {
+    const prev = next.budgets[idx]!;
+    // keep the running cycle on edit (preserve prev anchor as-is, including a
+    // legacy undefined = epoch grid, so editing a limit never resets spend);
+    // start a fresh cycle only when the window length actually changed.
+    const anchor = budget.anchor ?? (prev.window === budget.window ? prev.anchor : now);
+    next.budgets[idx] = { ...budget, anchor };
+  }
   return next;
 }
 
@@ -854,5 +862,63 @@ export function removeServerKey(config: Config, index: number): Config {
   if (removed && next.server.key_names && removed in next.server.key_names) {
     delete next.server.key_names[removed];
   }
+  if (removed && next.server.key_models && removed in next.server.key_models) {
+    delete next.server.key_models[removed];
+    if (Object.keys(next.server.key_models).length === 0) next.server.key_models = undefined;
+  }
+  if (removed && next.server.key_rpm && removed in next.server.key_rpm) {
+    delete next.server.key_rpm[removed];
+    if (Object.keys(next.server.key_rpm).length === 0) next.server.key_rpm = undefined;
+  }
+  if (removed && next.server.key_expires && removed in next.server.key_expires) {
+    delete next.server.key_expires[removed];
+    if (Object.keys(next.server.key_expires).length === 0) next.server.key_expires = undefined;
+  }
+  return next;
+}
+
+/**
+ * Set or clear a gateway key's scopes (by index, since keys are masked in the
+ * API). `models`/`rpm` are each applied only when present in the patch; an empty
+ * list or null/0 clears that scope. Empty maps are pruned to undefined.
+ */
+export function setServerKeyScope(
+  config: Config,
+  index: number,
+  patch: { models?: string[] | null; rpm?: number | null; expires?: number | null },
+): Config {
+  const next = cloneConfig(config);
+  const keys = next.server.api_keys;
+  if (index < 0 || index >= keys.length) throw new Error(`no gateway key at index ${index}`);
+  const key = keys[index]!;
+
+  if (patch.models !== undefined) {
+    const models = { ...(next.server.key_models ?? {}) };
+    const list = (patch.models ?? []).map((m) => m.trim()).filter(Boolean);
+    if (list.length > 0) models[key] = list;
+    else delete models[key];
+    next.server.key_models = Object.keys(models).length > 0 ? models : undefined;
+  }
+
+  if (patch.rpm !== undefined) {
+    const rpm = { ...(next.server.key_rpm ?? {}) };
+    if (patch.rpm && patch.rpm > 0) rpm[key] = Math.floor(patch.rpm);
+    else delete rpm[key];
+    next.server.key_rpm = Object.keys(rpm).length > 0 ? rpm : undefined;
+  }
+
+  if (patch.expires !== undefined) {
+    const exp = { ...(next.server.key_expires ?? {}) };
+    if (patch.expires && patch.expires > 0) exp[key] = Math.floor(patch.expires);
+    else delete exp[key];
+    next.server.key_expires = Object.keys(exp).length > 0 ? exp : undefined;
+  }
+
   return next;
 }
+
+/** True when `rawKey` has an expiry set and `now` is strictly past it. */
+export function isKeyExpired(server: Config["server"], rawKey: string, now: number): boolean {
+  const at = server.key_expires?.[rawKey];
+  return at !== undefined && now > at;
+}

package/src/core/budget.ts

@@ -8,7 +8,7 @@
  */
 import type { Budget, BudgetScope } from "../config.js";
 import { budgetKey } from "../config.js";
-import { currentWindowStart, nextResetAt } from "./quota.js";
+import { currentWindowStart, nextResetAt } from "./window.js";
 
 export interface BudgetStatus {
   scope: BudgetScope;

package/src/core/fallback.ts

@@ -32,8 +32,6 @@ export interface FallbackOpts {
   onAttempt?: (log: AttemptLog) => void;
   /** which key the pool handed out for the winning attempt (handler uses it for usage). */
   onServed?: (route: ResolvedRoute, key: string) => void;
-  /** when set, a provider this returns true for is skipped (quota exhausted). */
-  isExhausted?: (provider: ResolvedRoute["provider"]) => boolean;
   /** captured client thinking intent, applied per-attempt in the provider's format. */
   thinkingIntent?: ThinkingConfig | null;
 }
@@ -56,13 +54,6 @@ export async function executeWithFallback(
   for (const route of routes) {
     const { provider } = route;
 
-    // skip a provider whose token budget is spent for this window — like a key
-    // cooling down, but for the whole provider. Falls through to the next route.
-    if (opts.isExhausted?.(provider)) {
-      log({ provider: provider.id, model: route.model, outcome: "skip", detail: "quota exhausted" });
-      continue;
-    }
-
     const attempts = provider.max_retries + 1;
 
     for (let i = 0; i < attempts; i++) {

package/src/core/handler.ts

@@ -20,7 +20,6 @@ import { parseSSE, encodeSSE } from "../stream/sse.js";
 import { streamAdapterFor } from "../stream/index.js";
 import type { CanonicalChunk } from "../stream/chunk.js";
 import type { KeyPool } from "./keypool.js";
-import type { QuotaTracker } from "./quota.js";
 import { executeWithFallback } from "./fallback.js";
 import { type UsageDB, computeCost } from "../db.js";
 import { compressMessages } from "../rtk/index.js";
@@ -50,12 +49,12 @@ export interface HandleDeps {
   config: GatewayConfig;
   pool: KeyPool;
   db?: UsageDB;
-  quota?: QuotaTracker;
   budget?: {
     globalStatus(): { exhausted: boolean; reset_in_ms: number } | null;
     blocks(providerId: string, model: string): { exhausted: true; reset_in_ms: number } | null;
     blocksKey(fp: string): { exhausted: true; reset_in_ms: number } | null;
   };
+  clientKeyModels?: string[];
   clientKeyFp?: string;
   log?: (msg: string) => void;
   now?: () => number;
@@ -71,8 +70,6 @@ function recordUsage(
 ): void {
   const tokensIn = usage?.prompt_tokens ?? 0;
   const tokensOut = usage?.completion_tokens ?? 0;
-  // count the full request against the served provider's window budget.
-  deps.quota?.consume(route.provider, tokensIn + tokensOut);
   if (!deps.db) return;
   // Cost: a combo/route may set explicit prices; otherwise fall back to the ported
   // aigetwey pricing table so cost auto-resolves per model instead of showing $0.
@@ -118,6 +115,13 @@ export async function handle(
   // that can't reason. Matches aigetwey's capture-before-translate flow.
   const { cleanModel, override } = parseSuffix(canonical.model);
   canonical.model = cleanModel;
+
+  // per-key allowlist: a key may be restricted to specific call-strings. Empty/
+  // absent → unrestricted. Match the literal clean model the client asked for.
+  if (deps.clientKeyModels && deps.clientKeyModels.length > 0 && !deps.clientKeyModels.includes(cleanModel)) {
+    throw new GatewayError(403, { error: "model not allowed for this key" });
+  }
+
   const thinkingIntent: ThinkingConfig | null =
     override ?? captureThinking(canonical as Record<string, unknown>);
 
@@ -127,8 +131,7 @@ export async function handle(
   }
 
   // Budget hard-stop. Global overrun fails fast. Provider/model budgets bar the
-  // matching routes (like the token-quota skip); if every candidate is barred,
-  // there's nothing to serve → 402.
+  // matching routes; if every candidate is barred, there's nothing to serve → 402.
   if (deps.budget) {
     const g = deps.budget.globalStatus();
     if (g?.exhausted) throw new GatewayError(402, { error: "budget exceeded", reset_in_ms: g.reset_in_ms });
@@ -193,7 +196,6 @@ export async function handle(
       stream: wantStream,
       signal,
       thinkingIntent,
-      isExhausted: deps.quota ? (p) => deps.quota!.isExhausted(p) : undefined,
       onAttempt: (a) =>
         deps.log?.(`[fallback] ${a.provider}/${a.model} ${a.status ?? "-"} -> ${a.outcome}${a.detail ? ` (${a.detail})` : ""}`),
     });

package/src/core/keysUsage.ts

@@ -0,0 +1,49 @@
+/**
+ * Shapes one row for the Budgets page "Keys" section: a gateway key joined with
+ * its all-time spend/tokens, optional expiry, and its key-scoped budget status
+ * (null when the key is uncapped). Pure — the admin route feeds it real data.
+ */
+import type { BudgetStatus } from "./budget.js";
+
+export interface KeyBudgetView {
+  unit: "usd" | "tokens";
+  limit: number;
+  spent: number;
+  pct: number;
+  window: BudgetStatus["window"];
+  reset_in_ms: number;
+  exhausted: boolean;
+  alert: boolean;
+}
+
+export interface KeyUsageRow {
+  fingerprint: string;
+  name: string;
+  masked: string;
+  expires?: number;
+  spent: number;
+  tokens: number;
+  budget: KeyBudgetView | null;
+}
+
+export function buildKeyUsageRow(input: {
+  fingerprint: string;
+  name: string;
+  masked: string;
+  expires?: number;
+  totals: { tokens_in: number; tokens_out: number; cost: number };
+  budget: BudgetStatus | null;
+}): KeyUsageRow {
+  const b = input.budget;
+  return {
+    fingerprint: input.fingerprint,
+    name: input.name,
+    masked: input.masked,
+    expires: input.expires,
+    spent: input.totals.cost,
+    tokens: input.totals.tokens_in + input.totals.tokens_out,
+    budget: b
+      ? { unit: b.unit, limit: b.limit, spent: b.spent, pct: b.pct, window: b.window, reset_in_ms: b.reset_in_ms, exhausted: b.exhausted, alert: b.alert }
+      : null,
+  };
+}

package/src/core/ratelimit.ts

@@ -0,0 +1,25 @@
+/**
+ * Per-key request counter on a fixed calendar-minute window. In-memory only —
+ * counts reset on restart, which is fine for a 1-minute window. Used to rate-limit
+ * gateway keys that opt in via server.key_rpm.
+ */
+interface Bucket {
+  minute: number;
+  count: number;
+}
+
+export class RateLimiter {
+  private readonly buckets = new Map<string, Bucket>();
+
+  /** Record a hit for `key`; return true if it now EXCEEDS `limit` this minute. */
+  over(key: string, limit: number, now: number = Date.now()): boolean {
+    const minute = Math.floor(now / 60_000);
+    const b = this.buckets.get(key);
+    if (!b || b.minute !== minute) {
+      this.buckets.set(key, { minute, count: 1 });
+      return 1 > limit;
+    }
+    b.count += 1;
+    return b.count > limit;
+  }
+}

package/src/core/state.ts

@@ -1,15 +1,13 @@
 /**
- * Mutable holder for the live gateway config, key pool, and quota tracker.
+ * Mutable holder for the live gateway config, key pool, and budget tracker.
  *
  * Config loads once at boot, but the dashboard edits it at runtime. Routes read
- * `state.config` / `state.pool` / `state.quota` fresh per request (never close
+ * `state.config` / `state.pool` / `state.budget` fresh per request (never close
  * over them), so a successful reload swaps in the new config + pool atomically —
  * no restart.
  *
  * reload() validates and persists BEFORE swapping: an invalid edit throws and
- * the old config keeps serving. The pool is rebuilt (cooldown is transient), but
- * the quota tracker is KEPT across reloads — a budget consumed this window must
- * survive a config edit, else editing config would silently reset every quota.
+ * the old config keeps serving. The pool is rebuilt (cooldown is transient).
  */
 import {
   GatewayConfig,
@@ -21,7 +19,6 @@ import {
 } from "../config.js";
 import { clientKeyFingerprint } from "../middleware/auth.js";
 import { KeyPool } from "./keypool.js";
-import { QuotaTracker } from "./quota.js";
 import { BudgetTracker } from "./budget.js";
 
 function serverKeyLabel(server: { api_keys: string[]; key_names?: Record<string, string> }, fp: string): string {
@@ -34,18 +31,15 @@ function serverKeyLabel(server: { api_keys: string[]; key_names?: Record<string,
 export class GatewayState {
   private _config: GatewayConfig;
   private _pool: KeyPool;
-  private readonly _quota: QuotaTracker;
   private readonly _budget: BudgetTracker;
 
   constructor(
     private readonly configPath: string,
     initial: GatewayConfig,
-    quota?: QuotaTracker,
     budgetDb?: { totals(since: number, filter?: { provider?: string; model?: string; client_key?: string }): { tokens_in: number; tokens_out: number; cost: number } },
   ) {
     this._config = initial;
     this._pool = new KeyPool();
-    this._quota = quota ?? new QuotaTracker();
     this._budget = new BudgetTracker(
       () => this._config.raw.budgets,
       budgetDb ?? { totals: () => ({ tokens_in: 0, tokens_out: 0, cost: 0 }) },
@@ -63,10 +57,6 @@ export class GatewayState {
     return this._pool;
   }
 
-  get quota(): QuotaTracker {
-    return this._quota;
-  }
-
   get budget(): BudgetTracker {
     return this._budget;
   }
@@ -75,7 +65,7 @@ export class GatewayState {
    * Validate edited config text, restore masked secrets from the live config,
    * persist atomically, then swap in a fresh config + pool. Throws without
    * changing anything if validation fails or a masked key can't be resolved —
-   * the old config keeps serving. The quota tracker is intentionally preserved.
+   * the old config keeps serving.
    */
   reload(text: string): void {
     const parsed = parseConfigText(text);

package/src/core/window.ts

@@ -0,0 +1,45 @@
+/**
+ * Rolling-window engine: every budget window is a fixed-duration tumbling bucket
+ * aligned to the epoch grid (no calendar/timezone math). `5h` resets every five
+ * hours, `24h` daily, `7day` weekly, `30day` monthly — each on a rolling grid
+ * rather than a calendar boundary. Shared by the budget tracker.
+ */
+const HOUR_MS = 3600_000;
+const DAY_MS = 24 * HOUR_MS;
+
+export type WindowName = "5h" | "24h" | "7day" | "30day";
+
+export type WindowSpec = {
+  window: WindowName;
+  /** Epoch ms the recurring cycle is anchored to. Absent ⇒ epoch-grid (legacy). */
+  anchor?: number;
+};
+
+const DURATION_MS: Record<WindowName, number> = {
+  "5h": 5 * HOUR_MS,
+  "24h": 24 * HOUR_MS,
+  "7day": 7 * DAY_MS,
+  "30day": 30 * DAY_MS,
+};
+
+/** Length (ms) of one window bucket. */
+export function windowDuration(spec: WindowSpec): number {
+  return DURATION_MS[spec.window];
+}
+
+/** Epoch ms of the START of the bucket containing `now`. Anchored to `spec.anchor`
+ *  when present (cycles tumble from the anchor); otherwise floored to the epoch grid. */
+export function currentWindowStart(spec: WindowSpec, now: number): number {
+  const dur = DURATION_MS[spec.window];
+  if (spec.anchor === undefined) return Math.floor(now / dur) * dur;
+  if (now <= spec.anchor) return spec.anchor;
+  return spec.anchor + Math.floor((now - spec.anchor) / dur) * dur;
+}
+
+/** Next reset instant: the end of the current bucket (windowStart + duration). */
+export function nextResetAt(spec: WindowSpec, windowStart: number, _now: number): number {
+  return windowStart + DURATION_MS[spec.window];
+}
+
+// `DAY_MS` is exported for any future window math that needs a day constant.
+export { DAY_MS };

package/src/db.ts

@@ -67,7 +67,6 @@ export class UsageDB {
   private readonly db: DatabaseSync;
   private readonly insertUsage;
   private readonly insertLog;
-  private readonly upsertQuota;
   private readonly now: () => number;
 
   constructor(path: string, now: () => number = Date.now) {
@@ -121,13 +120,6 @@ export class UsageDB {
       INSERT INTO logs (ts, direction, provider, status, request_summary, response_summary)
       VALUES (?, ?, ?, ?, ?, ?)
     `);
-    // upsert keyed on provider_id so each provider keeps one live window row.
-    this.upsertQuota = this.db.prepare(`
-      INSERT INTO quota_state (provider_id, window_start, consumed, last_reset)
-      VALUES (?, ?, ?, ?)
-      ON CONFLICT(provider_id) DO UPDATE SET window_start = excluded.window_start,
-        consumed = excluded.consumed, last_reset = excluded.last_reset
-    `);
   }
 
   record(row: Omit<UsageRow, "ts" | "client_key"> & { ts?: number; client_key?: string }): void {
@@ -297,21 +289,6 @@ export class UsageDB {
     }));
   }
 
-  // ---- QuotaStore: one live window row per provider (survives restart) ----
-
-  loadQuota(): Array<{ provider_id: string; window_start: number; consumed: number }> {
-    const rows = this.db.prepare(`SELECT provider_id, window_start, consumed FROM quota_state`).all() as SqlRow[];
-    return rows.map((r) => ({
-      provider_id: String(r.provider_id),
-      window_start: num(r.window_start),
-      consumed: num(r.consumed),
-    }));
-  }
-
-  saveQuota(providerId: string, windowStart: number, consumed: number): void {
-    this.upsertQuota.run(providerId, windowStart, consumed, this.now());
-  }
-
   close(): void {
     this.db.close();
   }

package/src/routes/admin.ts

@@ -16,6 +16,7 @@ import type { FastifyInstance, FastifyRequest, FastifyReply } from "fastify";
 import type { GatewayState } from "../core/state.js";
 import type { UsageDB } from "../db.js";
 import { checkAdminAuth, clientKeyFingerprint, type AdminVerifier } from "../middleware/auth.js";
+import { buildKeyUsageRow } from "../core/keysUsage.js";
 import {
   maskKey,
   serializeConfig,
@@ -44,6 +45,7 @@ import {
   addServerKey,
   editServerKey,
   removeServerKey,
+  setServerKeyScope,
   setBudget,
   clearBudget,
   type Config,
@@ -87,6 +89,23 @@ function maskedConfig(config: Config): Config {
       Object.entries(clone.server.key_names).map(([k, name]) => [maskKey(k), name]),
     );
   }
+  // key_models / key_rpm are keyed by the RAW key — re-key to the masked form so
+  // real keys never leak through /admin/config.
+  if (clone.server.key_models) {
+    clone.server.key_models = Object.fromEntries(
+      Object.entries(clone.server.key_models).map(([k, v]) => [maskKey(k), v]),
+    );
+  }
+  if (clone.server.key_rpm) {
+    clone.server.key_rpm = Object.fromEntries(
+      Object.entries(clone.server.key_rpm).map(([k, v]) => [maskKey(k), v]),
+    );
+  }
+  if (clone.server.key_expires) {
+    clone.server.key_expires = Object.fromEntries(
+      Object.entries(clone.server.key_expires).map(([k, v]) => [maskKey(k), v]),
+    );
+  }
   return clone;
 }
 
@@ -143,12 +162,9 @@ export function registerAdminRoutes(app: FastifyInstance, deps: AdminDeps): void
     reply.send({ providers: deps.state.pool.snapshot(deps.state.config.listProviders()) });
   });
 
-  // per-provider quota: consumed, limit, and ms until the next scheduled reset.
-  app.get("/admin/quota", requireAdmin, (_req, reply) => {
-    reply.send({
-      quota: deps.state.quota.snapshot(deps.state.config.listProviders()),
-      budgets: deps.state.budget.statuses(),
-    });
+  // budget statuses: consumed, limit, and ms until the next scheduled reset.
+  app.get("/admin/budgets", requireAdmin, (_req, reply) => {
+    reply.send({ budgets: deps.state.budget.statuses() });
   });
 
   // add or replace a budget (keyed by scope). Body = Budget; invalid shape or an
@@ -403,7 +419,7 @@ export function registerAdminRoutes(app: FastifyInstance, deps: AdminDeps): void
   });
 
   // Test ONE model end-to-end (aigetwey's per-model science button). Routes through
-  // the real pipeline via handle(), so the ping lands in usage/quota exactly like
+  // the real pipeline via handle(), so the ping lands in usage exactly like
   // a normal call — and it catches "model not found / not entitled" a /models
   // ping can't. Model id travels as ?model= to survive slashes through the proxy.
   app.post("/admin/providers/:id/models/test", requireAdmin, async (req, reply) => {
@@ -414,7 +430,7 @@ export function registerAdminRoutes(app: FastifyInstance, deps: AdminDeps): void
     if (!provider) return reply.code(404).send({ error: `provider "${id}" not found` });
     try {
       await handle(
-        { config: deps.state.config, pool: deps.state.pool, db: deps.db, quota: deps.state.quota },
+        { config: deps.state.config, pool: deps.state.pool, db: deps.db },
         "openai",
         { model: `${id}/${modelId}`, messages: [{ role: "user", content: "ping" }], max_tokens: 1, stream: false },
       );
@@ -564,6 +580,15 @@ export function registerAdminRoutes(app: FastifyInstance, deps: AdminDeps): void
     applyMutation(reply, (c) => editServerKey(c, i, { name: b?.name }));
   });
 
+  // set/clear ONE gateway key's scopes (model allowlist + rpm), by index.
+  app.put("/admin/endpoint/keys/:index/scope", requireAdmin, (req, reply) => {
+    const { index } = req.params as { index: string };
+    const i = Number(index);
+    if (!Number.isInteger(i)) return reply.code(400).send({ error: "index must be an integer" });
+    const b = (req.body ?? {}) as { models?: string[]; rpm?: number | null; expires?: number | null };
+    applyMutation(reply, (c) => setServerKeyScope(c, i, { models: b.models, rpm: b.rpm, expires: b.expires }));
+  });
+
   app.delete("/admin/endpoint/keys/:index", requireAdmin, (req, reply) => {
     const { index } = req.params as { index: string };
     const i = Number(index);
@@ -584,6 +609,26 @@ export function registerAdminRoutes(app: FastifyInstance, deps: AdminDeps): void
     );
   });
 
+  // per-key spend for the Budgets page "Keys" section: every gateway key, its
+  // all-time usage, expiry, and key-scoped budget status (null when uncapped).
+  app.get("/admin/keys/usage", requireAdmin, (_req, reply) => {
+    if (!deps.db) return reply.code(503).send({ error: "usage tracking disabled" });
+    const cfg = deps.state.config.raw;
+    const statuses = deps.state.budget.statuses();
+    const keys = cfg.server.api_keys.map((k) => {
+      const fp = clientKeyFingerprint(k);
+      return buildKeyUsageRow({
+        fingerprint: fp,
+        name: cfg.server.key_names?.[k] ?? maskKey(k),
+        masked: maskKey(k),
+        expires: cfg.server.key_expires?.[k],
+        totals: deps.db!.totals(0, { client_key: fp }),
+        budget: statuses.find((s) => s.scope.type === "key" && s.scope.id === fp) ?? null,
+      });
+    });
+    reply.send({ keys });
+  });
+
   // reveal ONE raw gateway key (the "show key" button on the Endpoint page).
   app.get("/admin/endpoint/keys/:index/reveal", requireAdmin, (req, reply) => {
     const { index } = req.params as { index: string };
@@ -749,6 +794,13 @@ function endpointPayload(config: Config) {
     caveman: config.endpoint.caveman,
     ponytail: config.endpoint.ponytail,
     headroom: config.endpoint.headroom,
-    keys: config.server.api_keys.map((k) => ({ key: maskKey(k), name: config.server.key_names?.[k] })),
+    keys: config.server.api_keys.map((k) => ({
+      key: maskKey(k),
+      fingerprint: clientKeyFingerprint(k),
+      name: config.server.key_names?.[k],
+      models: config.server.key_models?.[k],
+      rpm: config.server.key_rpm?.[k],
+      expires: config.server.key_expires?.[k],
+    })),
   };
 }