@acarmisc/backstage-plugin-litellm-backend 0.15.0 → 0.16.1

package/config.d.ts

@@ -2,18 +2,25 @@ export interface Config {
   litellm: {
     /**
      * Base URL of the LiteLLM proxy instance.
-     * @visibility backend
      */
     baseUrl: string;
 
     /**
      * Publicly reachable LiteLLM proxy URL. Used to build ready-to-paste
      * curl / OpenAI-SDK snippets in the frontend ("Key Generated" dialog).
-     * When omitted, the internal baseUrl is used instead.
-     * @visibility backend
+     * The value is served to the frontend via GET /config. When omitted the
+     * frontend shows "Endpoint not configured" — the internal baseUrl is
+     * never exposed.
      */
     publicBaseUrl?: string;
 
+    /**
+     * Who end users should contact when their LiteLLM account isn't set up
+     * (an email address, chat channel or URL). Served to the frontend via
+     * GET /config and shown in the "account isn't set up" panel.
+     */
+    supportContact?: string;
+
     /**
      * LiteLLM master key for admin operations. Never exposed to the frontend.
      * @visibility secret
@@ -24,7 +31,6 @@ export interface Config {
      * Email domain appended to the Backstage user entity name to form the
      * LiteLLM user_id. When set, a user named "john.doe" maps to
      * "john.doe@<userIdDomain>" in LiteLLM. Omit to use the bare entity name.
-     * @visibility backend
      */
     userIdDomain?: string;
 
@@ -78,6 +84,12 @@ export interface Config {
          */
         rpmLimit?: number;
 
+        /**
+         * LiteLLM user role applied on /user/new (e.g. "internal_user").
+         * @default "internal_user"
+         */
+        userRole?: string;
+
         /**
          * Arbitrary key-value metadata stored on the LiteLLM user record.
          * Useful for tracking source, cost centre, department, etc.
@@ -102,16 +114,12 @@ export interface Config {
         teams?: string[];
         tpmLimit?: number;
         rpmLimit?: number;
+        /** LiteLLM user role for members of this group; falls back to defaults.userRole. */
+        userRole?: string;
         metadata?: Record<string, string>;
       }>;
     };
 
-    /**
-     * CLI bridge — exposes /api/litellm/bridge/* for CLI clients (Abby) that
-     * authenticate with a Keycloak access token (JWKS-verified). Lets them
-     * list/mint virtual keys without holding the master key. Disabled by
-     * default; enable explicitly when the CLI is in use.
-     */
     /**
      * Audit log access control. When set, the /audit tab in the plugin is
      * only visible to members of the specified Backstage group.
@@ -127,6 +135,103 @@ export interface Config {
       group?: string;
     };
 
+    /**
+     * Governance ceilings for individual key creation.
+     * These are strict server-side limits; config flags (allowUnlimitedBudget,
+     * teamRequired) control what users are allowed to do, but these limits
+     * cap what they can specify.
+     */
+    keys?: {
+      /**
+       * Maximum USD budget a single key can have. Requests exceeding this
+       * are rejected with a 400 error.
+       * @default 100
+       */
+      maxBudget?: number;
+
+      /**
+       * Maximum tokens-per-minute a single key can request.
+       * Requests exceeding this are rejected with a 400 error.
+       * @default 100000
+       */
+      maxTpm?: number;
+
+      /**
+       * Maximum requests-per-minute a single key can request.
+       * Requests exceeding this are rejected with a 400 error.
+       * @default 1000
+       */
+      maxRpm?: number;
+
+      /**
+       * Allowed duration presets for keys (e.g. "1d", "7d", "30d", "90d").
+       * Requests with a duration not in this list are rejected with a 400 error.
+       * An empty array allows any duration matching the format /^\d+[smhdwy]$/.
+       * @default ["1d", "7d", "30d", "90d"]
+       */
+      allowedDurations?: string[];
+
+      /**
+       * When true, key owners can reset their key's spend counter via the
+       * "Reset Spend" button in the frontend, subject to the
+       * litellm.key.resetSpend permission. When false (the default), reset
+       * is only available to administrators, even if the permission is ALLOW.
+       * Fail-closed: enforced before the permission check.
+       * @default false
+       */
+      allowOwnerResetSpend?: boolean;
+    };
+
+    /**
+     * OpenCode SSO-connect (GET/POST /opencode/connect). Lets the OpenCode
+     * portal-auth plugin obtain a personal LiteLLM key after a browser
+     * sign-in and confirmation. Disabled by default.
+     */
+    opencode?: {
+      /**
+       * When true the /opencode/connect routes are mounted.
+       * @default false
+       */
+      enabled?: boolean;
+
+      /**
+       * Duration of freshly generated keys, in LiteLLM format (e.g. "30d").
+       * @default "30d"
+       */
+      keyDuration?: string;
+
+      /**
+       * Max budget (USD) of keys created through the connect flow.
+       * @default 50
+       */
+      maxBudget?: number;
+
+      /**
+       * When true a team must be supplied and the user must belong to it.
+       * @default false
+       */
+      requireTeam?: boolean;
+
+      /**
+       * Extra metadata stamped on keys created through this flow.
+       */
+      metadata?: { [key: string]: string };
+    };
+
+    /**
+     * Caching configuration for backend data fetches.
+     */
+    cache?: {
+      /**
+       * Time-to-live for cached getUserInfo results, in seconds.
+       * When 0, caching is disabled.
+       * Cached results are never stale within this window; mutations
+       * invalidate the cache immediately to ensure consistency.
+       * @default 10
+       */
+      userInfoTtlSeconds?: number;
+    };
+
     /**
      * Controls for the "Generate New Key" form in the frontend.
      */
@@ -161,7 +266,6 @@ export interface Config {
        * e.g. "group:default/litellm-team-admins".
        * The plugin ships a group template at catalog/litellm-team-admins.yaml.
        * When omitted the feature is disabled entirely.
-       * @visibility backend
        */
       group?: string;
 
@@ -169,7 +273,6 @@ export interface Config {
        * LiteLLM model names an admin may assign to a team.
        * Empty array => none assignable (fail-closed).
        * @default []
-       * @visibility backend
        */
       allowedModels?: string[];
 
@@ -178,21 +281,18 @@ export interface Config {
        * References access_groups defined in litellm.model_info configuration.
        * Empty array => none allowed.
        * @default []
-       * @visibility backend
        */
       allowedModelAccessGroups?: string[];
 
       /**
        * Hard USD ceiling for max_budget an admin may set on a team.
        * @default 1000
-       * @visibility backend
        */
       maxBudgetCeiling?: number;
 
       /**
        * Allow an admin to create a team with no budget cap.
        * @default false
-       * @visibility backend
        */
       allowUnlimitedBudget?: boolean;
 
@@ -200,7 +300,6 @@ export interface Config {
        * Vector-store ids/names an admin may attach as team knowledge bases.
        * Empty array => none allowed.
        * @default []
-       * @visibility backend
        */
       allowedVectorStores?: string[];
 
@@ -208,7 +307,6 @@ export interface Config {
        * MCP server ids/names an admin may attach to a team.
        * Empty array => none allowed.
        * @default []
-       * @visibility backend
        */
       allowedMcpServers?: string[];
 
@@ -217,14 +315,12 @@ export interface Config {
        * References access_groups defined in litellm.mcp_info configuration.
        * Empty array => none allowed.
        * @default []
-       * @visibility backend
        */
       allowedMcpAccessGroups?: string[];
 
       /**
        * Allow an admin to delete a team (vs. only block/deactivate).
        * @default false
-       * @visibility backend
        */
       allowTeamDelete?: boolean;
 
@@ -242,7 +338,6 @@ export interface Config {
          * When true, mount the knowledge-base and MCP management routes.
          * Still gated by the permission framework and the allowlists.
          * @default false
-         * @visibility backend
          */
         enabled?: boolean;
       };
@@ -262,7 +357,6 @@ export interface Config {
        * cards, TEAM section of the budget widget). Team managers still see
        * dollars unless hideTeamBudgetForManagers is also set.
        * @default false
-       * @visibility frontend
        */
       hideTeamBudgetForMembers?: boolean;
 
@@ -271,7 +365,6 @@ export interface Config {
        * team write responses, ManageTeamDialog budget field which becomes
        * write-only). Useful when budgets are finance-sensitive.
        * @default false
-       * @visibility frontend
        */
       hideTeamBudgetForManagers?: boolean;
     };
@@ -297,6 +390,15 @@ export interface Config {
        * @default "abby-cli"
        */
       clientId?: string;
+
+      /**
+       * Email domains whose *verified* addresses may use the bridge. Defaults
+       * to `litellm.userIdDomain` when that is set. With neither configured
+       * the bridge rejects every caller. The LiteLLM user is then the same one
+       * the UI addresses (the Keycloak `preferred_username`, with
+       * `litellm.userIdDomain` applied when set) — the email is only the gate.
+       */
+      allowedEmailDomains?: string[];
     };
   };
 }

package/dist/bridge.d.ts

@@ -1,15 +1,19 @@
 import { Config } from '@backstage/config';
+import { LoggerService } from '@backstage/backend-plugin-api';
 import { LiteLLMClient } from './client';
 import { GenerateKeyRequest, GenerateKeyResponse, ProvisioningDefaults, UserInfo, VirtualKey } from './types';
 /** Claims extracted from a verified Keycloak access token. */
 export interface BridgeClaims {
     sub: string;
     email?: string;
+    email_verified?: boolean;
     preferred_username?: string;
     name?: string;
     /** Authorized party — Keycloak sets this to the client_id of the requester. */
     azp?: string;
     aud?: string | string[];
+    /** Keycloak payload `typ` claim: 'Bearer' for access tokens, 'ID' for ID tokens. */
+    typ?: string;
 }
 /** A token verifier pluggable for tests. */
 export interface TokenVerifier {
@@ -21,6 +25,12 @@ export interface BridgeConfig {
     issuer?: string;
     /** OIDC public client the CLI uses; checked against azp / aud. */
     clientId: string;
+    /**
+     * Email domains whose verified addresses may use the bridge. Defaults to
+     * `litellm.userIdDomain` when that is set; with neither, the bridge rejects
+     * every caller (fail closed).
+     */
+    allowedEmailDomains: string[];
 }
 export declare function readBridgeConfig(config: Config): BridgeConfig;
 /** Thrown when the bridge is misconfigured (e.g. enabled without an issuer). */
@@ -30,6 +40,10 @@ export declare class BridgeConfigError extends Error {
 export declare class BridgeAuthError extends Error {
     readonly status = 401;
 }
+/** Thrown when the caller's identity fails validation (e.g. email domain mismatch) → maps to HTTP 403. */
+export declare class BridgeIdentityError extends Error {
+    readonly status = 403;
+}
 export interface KeycloakJWTVerifierOptions {
     issuer: string;
     clientId: string;
@@ -49,29 +63,41 @@ export declare class KeycloakJWTVerifier implements TokenVerifier {
 /** Builds the default verifier from config, or throws BridgeConfigError. */
 export declare function newDefaultVerifier(cfg: BridgeConfig): TokenVerifier;
 /**
- * Resolves the LiteLLM user_id from the verified claims, matching exactly how
- * the UI derives it so the bridge addresses the *same* LiteLLM user (not a
- * duplicate). The UI uses toLiteLLMUserId(entityRef, userIdDomain) where the
- * Backstage entity name has been rewritten by the Keycloak user transformer:
- * because the catalog rejects '@' in entity names, usernames imported as full
- * emails are stored as their local-part. We replicate that here — strip the
- * '@domain' off the username, then apply the same userIdDomain rule.
+ * How the bridge maps a verified token to a LiteLLM user.
+ * - `userIdDomain`: the same `litellm.userIdDomain` the UI uses to build ids.
+ * - `trustedEmailDomains`: email domains allowed to use the bridge; defaults to
+ *   `[userIdDomain]` when that is set.
+ */
+export interface BridgeIdentityOptions {
+    userIdDomain?: string;
+    trustedEmailDomains?: string[];
+}
+/**
+ * Resolves the LiteLLM user_id for a verified bridge token.
+ *
+ * Two separate questions, answered separately:
+ * 1. Is this person allowed in? The token must carry a *verified* email whose
+ *    domain is in the trusted list (`litellm.bridge.allowedEmailDomains`,
+ *    defaulting to `litellm.userIdDomain`). With no trusted domain configured
+ *    everyone is rejected (fail closed). Failure → 403.
+ * 2. Which LiteLLM user are they? The same one the UI addresses: the Backstage
+ *    user entity name (the Keycloak `preferred_username`) run through the same
+ *    `litellm.userIdDomain` rule the UI applies. Using the email local part
+ *    here would address a different user whenever a Keycloak username differs
+ *    from the email (and would provision a duplicate). The realm is the same
+ *    IdP Backstage signs users in with, so its usernames are the entity names.
+ *
+ * @throws BridgeIdentityError (403) if identity validation fails
  */
-export declare function resolveBridgeUserId(claims: BridgeClaims, userIdDomain?: string): string;
+export declare function resolveBridgeUserId(claims: BridgeClaims, identity?: string | BridgeIdentityOptions): string;
 /**
  * Ensures a LiteLLM user exists for the verified identity. If the user is
  * missing and provisioning is enabled, creates it from the JWT claims (email +
  * name); if provisioning is disabled, throws a 404 telling the caller to log
  * in to Backstage first (the UI is the primary provisioning entry point).
  */
-export declare function getOrProvisionUserFromClaims(client: LiteLLMClient, claims: BridgeClaims, provisioningEnabled: boolean, provisioningDefaults: ProvisioningDefaults, logger: {
-    info: (...args: unknown[]) => void;
-}, userIdDomain?: string): Promise<UserInfo>;
+export declare function getOrProvisionUserFromClaims(client: LiteLLMClient, claims: BridgeClaims, provisioningEnabled: boolean, provisioningDefaults: ProvisioningDefaults, logger: LoggerService, userIdDomain?: string | BridgeIdentityOptions): Promise<UserInfo>;
 /** Lists the caller's virtual keys (provisioning the user first if needed). */
-export declare function bridgeListKeys(client: LiteLLMClient, claims: BridgeClaims, provisioningEnabled: boolean, provisioningDefaults: ProvisioningDefaults, logger: {
-    info: (...args: unknown[]) => void;
-}, userIdDomain?: string): Promise<VirtualKey[]>;
+export declare function bridgeListKeys(client: LiteLLMClient, claims: BridgeClaims, provisioningEnabled: boolean, provisioningDefaults: ProvisioningDefaults, logger: LoggerService, userIdDomain?: string | BridgeIdentityOptions): Promise<VirtualKey[]>;
 /** Mints a new virtual key for the caller (provisioning the user first if needed). */
-export declare function bridgeGenerateKey(client: LiteLLMClient, claims: BridgeClaims, provisioningEnabled: boolean, provisioningDefaults: ProvisioningDefaults, logger: {
-    info: (...args: unknown[]) => void;
-}, request: Partial<GenerateKeyRequest>, userIdDomain?: string): Promise<GenerateKeyResponse>;
+export declare function bridgeGenerateKey(client: LiteLLMClient, claims: BridgeClaims, provisioningEnabled: boolean, provisioningDefaults: ProvisioningDefaults, logger: LoggerService, request: Partial<GenerateKeyRequest>, userIdDomain?: string | BridgeIdentityOptions): Promise<GenerateKeyResponse>;

package/dist/bridge.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.KeycloakJWTVerifier = exports.BridgeAuthError = exports.BridgeConfigError = void 0;
+exports.KeycloakJWTVerifier = exports.BridgeIdentityError = exports.BridgeAuthError = exports.BridgeConfigError = void 0;
 exports.readBridgeConfig = readBridgeConfig;
 exports.newDefaultVerifier = newDefaultVerifier;
 exports.resolveBridgeUserId = resolveBridgeUserId;
@@ -28,7 +28,8 @@ function readBridgeConfig(config) {
     const enabled = config.getOptionalBoolean('litellm.bridge.enabled') ?? false;
     const issuer = config.getOptionalString('litellm.bridge.issuer');
     const clientId = config.getOptionalString('litellm.bridge.clientId') ?? 'abby-cli';
-    return { enabled, issuer, clientId };
+    const allowedEmailDomains = (config.getOptionalStringArray('litellm.bridge.allowedEmailDomains') ?? []).map(d => d.trim().toLowerCase()).filter(Boolean);
+    return { enabled, issuer, clientId, allowedEmailDomains };
 }
 /** Thrown when the bridge is misconfigured (e.g. enabled without an issuer). */
 class BridgeConfigError extends Error {
@@ -42,6 +43,14 @@ class BridgeAuthError extends Error {
     }
 }
 exports.BridgeAuthError = BridgeAuthError;
+/** Thrown when the caller's identity fails validation (e.g. email domain mismatch) → maps to HTTP 403. */
+class BridgeIdentityError extends Error {
+    constructor() {
+        super(...arguments);
+        this.status = 403;
+    }
+}
+exports.BridgeIdentityError = BridgeIdentityError;
 /**
  * Verifies a Keycloak access token against the realm JWKS and ensures it was
  * issued for {@link clientId} (via azp, falling back to aud). Uses jose's
@@ -73,14 +82,23 @@ class KeycloakJWTVerifier {
         if (azp !== this.clientId && !audMatches) {
             throw new BridgeAuthError(`token not issued for client "${this.clientId}" (azp=${azp ?? 'none'})`);
         }
+        // Keycloak marks the token kind in the PAYLOAD `typ` claim ('Bearer' for
+        // access tokens, 'ID' for ID tokens); the JWT header `typ` is just 'JWT'.
+        // Reject anything that isn't an access token.
+        const typ = payload.typ;
+        if (typ && typ !== 'Bearer') {
+            throw new BridgeAuthError(`token type must be Bearer or absent, got: ${typ}`);
+        }
         return {
             sub: payload.sub ?? '',
             email: payload.email,
+            email_verified: payload.email_verified,
             preferred_username: payload
                 .preferred_username,
             name: payload.name,
             azp,
             aud,
+            typ,
         };
     }
 }
@@ -93,19 +111,57 @@ function newDefaultVerifier(cfg) {
     }
     return new KeycloakJWTVerifier({ issuer: cfg.issuer, clientId: cfg.clientId });
 }
+/** A bare string is the legacy form: `userIdDomain`, also the only trusted domain. */
+function normalizeIdentityOptions(opts) {
+    const o = typeof opts === 'string' ? { userIdDomain: opts } : opts ?? {};
+    let domains = [];
+    if (o.trustedEmailDomains?.length) {
+        domains = o.trustedEmailDomains;
+    }
+    else if (o.userIdDomain) {
+        domains = [o.userIdDomain];
+    }
+    const trusted = domains.map(d => d.toLowerCase());
+    return { userIdDomain: o.userIdDomain, trusted };
+}
 /**
- * Resolves the LiteLLM user_id from the verified claims, matching exactly how
- * the UI derives it so the bridge addresses the *same* LiteLLM user (not a
- * duplicate). The UI uses toLiteLLMUserId(entityRef, userIdDomain) where the
- * Backstage entity name has been rewritten by the Keycloak user transformer:
- * because the catalog rejects '@' in entity names, usernames imported as full
- * emails are stored as their local-part. We replicate that here — strip the
- * '@domain' off the username, then apply the same userIdDomain rule.
+ * Resolves the LiteLLM user_id for a verified bridge token.
+ *
+ * Two separate questions, answered separately:
+ * 1. Is this person allowed in? The token must carry a *verified* email whose
+ *    domain is in the trusted list (`litellm.bridge.allowedEmailDomains`,
+ *    defaulting to `litellm.userIdDomain`). With no trusted domain configured
+ *    everyone is rejected (fail closed). Failure → 403.
+ * 2. Which LiteLLM user are they? The same one the UI addresses: the Backstage
+ *    user entity name (the Keycloak `preferred_username`) run through the same
+ *    `litellm.userIdDomain` rule the UI applies. Using the email local part
+ *    here would address a different user whenever a Keycloak username differs
+ *    from the email (and would provision a duplicate). The realm is the same
+ *    IdP Backstage signs users in with, so its usernames are the entity names.
+ *
+ * @throws BridgeIdentityError (403) if identity validation fails
  */
-function resolveBridgeUserId(claims, userIdDomain) {
-    const raw = claims.preferred_username ?? claims.email ?? claims.sub;
-    const entityName = raw.includes('@') ? raw.split('@')[0] : raw;
-    return (0, provisioning_1.toLiteLLMUserId)(entityName, userIdDomain);
+function resolveBridgeUserId(claims, identity) {
+    const { userIdDomain, trusted } = normalizeIdentityOptions(identity);
+    if (trusted.length === 0) {
+        throw new BridgeIdentityError('set litellm.bridge.allowedEmailDomains (or litellm.userIdDomain) to use the CLI bridge');
+    }
+    if (!claims.email) {
+        throw new BridgeIdentityError('no email found in token');
+    }
+    if (claims.email_verified !== true) {
+        throw new BridgeIdentityError('email is not verified');
+    }
+    const parts = claims.email.split('@');
+    if (parts.length !== 2 || !parts[0]) {
+        throw new BridgeIdentityError('malformed email in token');
+    }
+    const [emailLocalPart, domain] = parts;
+    if (!trusted.includes(domain.toLowerCase())) {
+        throw new BridgeIdentityError(`email domain mismatch: "${domain}" is not allowed for this deployment`);
+    }
+    const name = claims.preferred_username?.trim() || emailLocalPart;
+    return (0, provisioning_1.toLiteLLMUserId)(name, userIdDomain);
 }
 /**
  * Ensures a LiteLLM user exists for the verified identity. If the user is

package/dist/client.d.ts

@@ -10,7 +10,7 @@ export declare function normalizeRequestTags(tags: SpendLogEntry['request_tags']
  * status and the structured `param` (e.g. `key_alias`) from the upstream
  * body so the router can surface a 400 instead of collapsing everything
  * into a 500. The message is the upstream `error.message` when present,
- * otherwise the raw body text.
+ * otherwise a generic status+statusText format (never embeds raw bodies).
  */
 export declare class LiteLLMUpstreamError extends Error {
     status: number;
@@ -68,6 +68,11 @@ export declare class LiteLLMClient {
      */
     generateKey(request: GenerateKeyRequest): Promise<GenerateKeyResponse>;
     updateKey(request: UpdateKeyRequest): Promise<VirtualKey>;
+    /**
+     * Regenerates (rotates) a key by its hash, returning a new plaintext key.
+     * The LiteLLM version determines the endpoint: use POST /key/{key}/regenerate.
+     */
+    regenerateKey(keyHash: string): Promise<GenerateKeyResponse>;
     deleteKeys(request: DeleteKeyRequest): Promise<{
         success: boolean;
     }>;
@@ -180,6 +185,6 @@ export declare class LiteLLMClient {
      *   - usage_by_key    → which keys drove cost / traffic (with key_alias + team_id from metadata)
      */
     private transformDailyActivity;
-    getUsage(startDate: string, endDate: string, userId?: string): Promise<UsageMetrics>;
+    getUsage(startDate: string, endDate: string, userId: string): Promise<UsageMetrics>;
     getTeamUsage(teamId: string, startDate: string, endDate: string): Promise<UsageMetrics>;
 }

package/dist/client.js

@@ -20,11 +20,12 @@ function normalizeRequestTags(tags) {
  * status and the structured `param` (e.g. `key_alias`) from the upstream
  * body so the router can surface a 400 instead of collapsing everything
  * into a 500. The message is the upstream `error.message` when present,
- * otherwise the raw body text.
+ * otherwise a generic status+statusText format (never embeds raw bodies).
  */
 class LiteLLMUpstreamError extends Error {
     constructor(status, statusText, body) {
-        let message = `LiteLLM API error: ${status} ${statusText} - ${body}`;
+        // Default message is generic status + text; only use JSON message if present.
+        let message = `LiteLLM API error: ${status} ${statusText}`;
         let param;
         try {
             const parsed = JSON.parse(body);
@@ -36,7 +37,8 @@ class LiteLLMUpstreamError extends Error {
             }
         }
         catch {
-            // not JSON — keep the raw body in the message
+            // Not JSON — keep the generic message (no raw body embedded).
+            // Log the raw body at debug level if needed by the caller.
         }
         super(message);
         this.status = status;
@@ -112,6 +114,7 @@ class LiteLLMClient {
                 models: inner.models ?? raw?.models,
                 max_budget: inner.max_budget ?? raw?.max_budget,
                 budget_duration: inner.budget_duration ?? raw?.budget_duration,
+                budget_reset_at: inner.budget_reset_at ?? raw?.budget_reset_at,
                 spend: inner.spend ?? raw?.spend,
                 current_spend: inner.current_spend ?? raw?.current_spend,
                 soft_limit: inner.soft_limit ?? raw?.soft_limit,
@@ -119,7 +122,7 @@ class LiteLLMClient {
             };
         }
         catch (err) {
-            if (err.status === 404)
+            if (err instanceof LiteLLMUpstreamError && err.status === 404)
                 return null;
             throw err;
         }
@@ -161,7 +164,10 @@ class LiteLLMClient {
             return rawKeys.map(this.toVirtualKey);
         }
         catch (err) {
-            if (err.status === 404 || err.message.includes('not found')) {
+            if (err instanceof LiteLLMUpstreamError && err.status === 404) {
+                return [];
+            }
+            if (err instanceof Error && err.message.includes('not found')) {
                 return [];
             }
             throw err;
@@ -183,6 +189,7 @@ class LiteLLMClient {
             user_id: k.user_id ?? undefined,
             team_id: k.team_id ?? undefined,
             blocked: k.blocked ?? undefined,
+            metadata: k.metadata ?? undefined,
         };
     }
     /**
@@ -213,6 +220,16 @@ class LiteLLMClient {
             body: JSON.stringify(request),
         });
     }
+    /**
+     * Regenerates (rotates) a key by its hash, returning a new plaintext key.
+     * The LiteLLM version determines the endpoint: use POST /key/{key}/regenerate.
+     */
+    async regenerateKey(keyHash) {
+        return this.request(`/key/${encodeURIComponent(keyHash)}/regenerate`, {
+            method: 'POST',
+            body: JSON.stringify({}),
+        });
+    }
     async deleteKeys(request) {
         return this.request('/key/delete', {
             method: 'POST',
@@ -628,19 +645,25 @@ class LiteLLMClient {
         };
     }
     async getUsage(startDate, endDate, userId) {
+        if (!userId) {
+            // An empty user_id makes LiteLLM return org-wide activity.
+            throw new Error('getUsage requires a user_id');
+        }
         const params = new URLSearchParams({
             start_date: startDate,
             end_date: endDate,
             page_size: '100',
         });
-        if (userId)
-            params.append('user_id', userId);
+        params.append('user_id', userId);
         try {
             const response = await this.request(`/user/daily/activity?${params.toString()}`);
             return this.transformDailyActivity(response);
         }
         catch (err) {
-            if (err.status === 404 || err.message.includes('not found')) {
+            if (err instanceof LiteLLMUpstreamError && err.status === 404) {
+                return this.emptyUsage();
+            }
+            if (err instanceof Error && err.message.includes('not found')) {
                 return this.emptyUsage();
             }
             throw err;
@@ -658,7 +681,10 @@ class LiteLLMClient {
             return this.transformDailyActivity(response);
         }
         catch (err) {
-            if (err.status === 404 || err.message.includes('not found')) {
+            if (err instanceof LiteLLMUpstreamError && err.status === 404) {
+                return this.emptyUsage();
+            }
+            if (err instanceof Error && err.message.includes('not found')) {
                 return this.emptyUsage();
             }
             throw err;