@acarmisc/backstage-plugin-litellm-backend 0.4.2 → 0.6.0

package/config.d.ts

@@ -6,6 +6,14 @@ export interface Config {
      */
     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
+     */
+    publicBaseUrl?: string;
+
     /**
      * LiteLLM master key for admin operations. Never exposed to the frontend.
      * @visibility secret

package/dist/client.d.ts

@@ -98,6 +98,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, _groupBy?: 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

@@ -12,6 +12,11 @@ class LiteLLMClient {
         const controller = new AbortController();
         const timeoutId = setTimeout(() => controller.abort(), this.timeout);
         try {
+            // Auth note: the LiteLLM OpenAPI spec declares the security scheme as an
+            // `x-litellm-api-key` header, but Bearer + master key is the deliberate,
+            // production-tested choice — LiteLLM's proxy accepts both, and Bearer is
+            // what every observed deployment actually uses. Do not "correct" this to
+            // match the spec literally without testing against a live gateway.
             const response = await fetch(`${this.baseUrl}${path}`, {
                 ...options,
                 signal: controller.signal,
@@ -237,6 +242,8 @@ class LiteLLMClient {
                     supports_vision: info.supports_vision ?? m.supports_vision,
                     input_cost_per_token: info.input_cost_per_token ?? params.input_cost_per_token,
                     output_cost_per_token: info.output_cost_per_token ?? params.output_cost_per_token,
+                    max_input_tokens: info.max_input_tokens ?? m.max_input_tokens,
+                    max_output_tokens: info.max_output_tokens ?? m.max_output_tokens,
                 };
             });
             const filtered = normalised.filter(m => m.model_name);
@@ -404,7 +411,7 @@ class LiteLLMClient {
             daily_by_model,
         };
     }
-    async getUsage(startDate, endDate, userId, _groupBy) {
+    async getUsage(startDate, endDate, userId) {
         const params = new URLSearchParams({
             start_date: startDate,
             end_date: endDate,

package/dist/index.cjs.js

@@ -286,7 +286,9 @@ var LiteLLMClient = class {
           supports_function_calling: info.supports_function_calling ?? m.supports_function_calling,
           supports_vision: info.supports_vision ?? m.supports_vision,
           input_cost_per_token: info.input_cost_per_token ?? params.input_cost_per_token,
-          output_cost_per_token: info.output_cost_per_token ?? params.output_cost_per_token
+          output_cost_per_token: info.output_cost_per_token ?? params.output_cost_per_token,
+          max_input_tokens: info.max_input_tokens ?? m.max_input_tokens,
+          max_output_tokens: info.max_output_tokens ?? m.max_output_tokens
         };
       });
       const filtered = normalised.filter((m) => m.model_name);
@@ -440,7 +442,7 @@ var LiteLLMClient = class {
       daily_by_model
     };
   }
-  async getUsage(startDate, endDate, userId, _groupBy) {
+  async getUsage(startDate, endDate, userId) {
     const params = new URLSearchParams({
       start_date: startDate,
       end_date: endDate,
@@ -480,6 +482,274 @@ var LiteLLMClient = class {
   }
 };
 
+// src/openapi.ts
+var openApiSpec = {
+  openapi: "3.1.0",
+  info: {
+    title: "LiteLLM Governance Plugin API",
+    version: "0.1.0",
+    description: "Backstage backend surface for the LiteLLM governance plugin. UI routes authenticate via the Backstage identity system; CLI bridge routes authenticate with a Keycloak access token."
+  },
+  servers: [
+    { url: "/api/litellm", description: "Backstage backend plugin mount point" }
+  ],
+  tags: [
+    { name: "System", description: "Health and configuration" },
+    { name: "User", description: "Current user info and provisioning" },
+    { name: "Keys", description: "Virtual key lifecycle" },
+    { name: "Models", description: "Model catalogue" },
+    { name: "Teams", description: "Team membership and usage" },
+    { name: "Usage", description: "Spend and traffic analytics" },
+    { name: "Audit", description: "Audit logs (RBAC-gated)" },
+    { name: "Provisioning", description: "Provisioning dry-run (RBAC-gated)" },
+    { name: "Bridge", description: "CLI bridge (Keycloak-token auth)" }
+  ],
+  paths: {
+    "/health": {
+      get: {
+        tags: ["System"],
+        summary: "Health check",
+        responses: {
+          "200": {
+            description: "Plugin health",
+            content: { "application/json": { schema: { type: "object", properties: {
+              status: { type: "string" },
+              provisioning: { type: "boolean" }
+            } } } }
+          }
+        }
+      }
+    },
+    "/config": {
+      get: {
+        tags: ["System"],
+        summary: "Public LiteLLM proxy base URL (for snippet generation)",
+        responses: {
+          "200": {
+            description: "Proxy URL",
+            content: { "application/json": { schema: { type: "object", properties: {
+              baseUrl: { type: "string" }
+            } } } }
+          }
+        }
+      }
+    },
+    "/openapi.json": {
+      get: {
+        tags: ["System"],
+        summary: "This OpenAPI document",
+        responses: { "200": { description: "OpenAPI 3.1 JSON" } }
+      }
+    },
+    "/user/info": {
+      get: {
+        tags: ["User"],
+        summary: "Get the current user's info and quotas",
+        responses: {
+          "200": { description: "User info" },
+          "404": { description: "User not found in LiteLLM (provisioning disabled)" }
+        }
+      }
+    },
+    "/keys": {
+      get: {
+        tags: ["Keys"],
+        summary: "List the caller's virtual keys",
+        responses: { "200": { description: "Array of keys" } }
+      }
+    },
+    "/keys/generate": {
+      post: {
+        tags: ["Keys"],
+        summary: "Generate a new virtual key",
+        requestBody: {
+          required: true,
+          content: { "application/json": { schema: { type: "object", properties: {
+            alias: { type: "string" },
+            models: { type: "array", items: { type: "string" } },
+            team_id: { type: "string" },
+            duration: { type: "string" },
+            max_budget: { type: "number", nullable: true, description: "Positive number caps spend; null = unlimited" },
+            tpm_limit: { type: "number" },
+            rpm_limit: { type: "number" },
+            auto_rotate: { type: "boolean" },
+            rotation_interval_days: { type: "number" }
+          } } } }
+        },
+        responses: {
+          "200": { description: "Generated key (includes the raw secret \u2014 shown once)" },
+          "400": { description: "Missing required fields" }
+        }
+      }
+    },
+    "/keys/{keyId}": {
+      delete: {
+        tags: ["Keys"],
+        summary: "Revoke/delete a virtual key (caller must own it)",
+        parameters: [{ name: "keyId", in: "path", required: true, schema: { type: "string" } }],
+        responses: { "200": { description: "Deleted" }, "403": { description: "Not the key owner" } }
+      }
+    },
+    "/keys/{keyId}/regenerate": {
+      post: {
+        tags: ["Keys"],
+        summary: "Rotate a key in place (caller must own it)",
+        parameters: [{ name: "keyId", in: "path", required: true, schema: { type: "string" } }],
+        responses: { "200": { description: "New secret" }, "403": { description: "Not the key owner" } }
+      }
+    },
+    "/keys/{keyId}/update": {
+      post: {
+        tags: ["Keys"],
+        summary: "Update alias / models / budget / limits (caller must own it)",
+        parameters: [{ name: "keyId", in: "path", required: true, schema: { type: "string" } }],
+        requestBody: { content: { "application/json": { schema: { type: "object" } } } },
+        responses: { "200": { description: "Updated" }, "403": { description: "Not the key owner" } }
+      }
+    },
+    "/keys/{keyId}/block": {
+      post: {
+        tags: ["Keys"],
+        summary: "Suspend a key without revoking (caller must own it)",
+        parameters: [{ name: "keyId", in: "path", required: true, schema: { type: "string" } }],
+        responses: { "200": { description: "Blocked" }, "403": { description: "Not the key owner" } }
+      }
+    },
+    "/keys/{keyId}/unblock": {
+      post: {
+        tags: ["Keys"],
+        summary: "Re-enable a blocked key (caller must own it)",
+        parameters: [{ name: "keyId", in: "path", required: true, schema: { type: "string" } }],
+        responses: { "200": { description: "Unblocked" }, "403": { description: "Not the key owner" } }
+      }
+    },
+    "/keys/{keyId}/reset_spend": {
+      post: {
+        tags: ["Keys"],
+        summary: "Zero out a key spend counter (caller must own it)",
+        parameters: [{ name: "keyId", in: "path", required: true, schema: { type: "string" } }],
+        responses: { "200": { description: "Spend reset" }, "403": { description: "Not the key owner" } }
+      }
+    },
+    "/models": {
+      get: {
+        tags: ["Models"],
+        summary: "List available LLM models",
+        responses: { "200": { description: "Model catalogue" } }
+      }
+    },
+    "/teams": {
+      get: {
+        tags: ["Teams"],
+        summary: "List teams the current user belongs to",
+        responses: { "200": { description: "Array of teams" } }
+      }
+    },
+    "/teams/{teamId}/usage": {
+      get: {
+        tags: ["Teams"],
+        summary: "Usage metrics for a team",
+        parameters: [
+          { name: "teamId", in: "path", required: true, schema: { type: "string" } },
+          { name: "start_date", in: "query", required: true, schema: { type: "string" } },
+          { name: "end_date", in: "query", required: true, schema: { type: "string" } }
+        ],
+        responses: { "200": { description: "Team usage" }, "400": { description: "Missing date range" } }
+      }
+    },
+    "/usage": {
+      get: {
+        tags: ["Usage"],
+        summary: "Usage metrics for the current user",
+        parameters: [
+          { name: "start_date", in: "query", required: true, schema: { type: "string" } },
+          { name: "end_date", in: "query", required: true, schema: { type: "string" } }
+        ],
+        responses: { "200": { description: "Usage metrics" }, "400": { description: "Missing date range" } }
+      }
+    },
+    "/audit": {
+      get: {
+        tags: ["Audit"],
+        summary: "Audit logs (gated by litellm.audit.group membership)",
+        parameters: [
+          { name: "page", in: "query", schema: { type: "integer" } },
+          { name: "page_size", in: "query", schema: { type: "integer" } },
+          { name: "start_date", in: "query", schema: { type: "string" } },
+          { name: "end_date", in: "query", schema: { type: "string" } },
+          { name: "action", in: "query", schema: { type: "string" } },
+          { name: "table_name", in: "query", schema: { type: "string" } },
+          { name: "changed_by", in: "query", schema: { type: "string" } }
+        ],
+        responses: { "200": { description: "Paginated audit logs" }, "403": { description: "Not configured or not authorized" } }
+      }
+    },
+    "/provisioning/preview": {
+      get: {
+        tags: ["Provisioning"],
+        summary: "Resolve which role a Backstage group maps to (dry-run)",
+        parameters: [
+          { name: "group", in: "query", required: true, schema: { type: "string" }, description: "e.g. group:default/ai-platform" }
+        ],
+        responses: {
+          "200": { description: "Resolved role and effective defaults" },
+          "400": { description: "Missing group parameter" },
+          "403": { description: "Not configured or not authorized" }
+        }
+      }
+    },
+    "/bridge/health": {
+      get: {
+        tags: ["Bridge"],
+        summary: "Bridge health + configured clientId (no auth)",
+        responses: { "200": { description: "Bridge health" } }
+      }
+    },
+    "/bridge/keys": {
+      get: {
+        tags: ["Bridge"],
+        summary: "List the caller virtual keys (Keycloak token auth)",
+        responses: { "200": { description: "Array of keys" }, "401": { description: "Invalid token" } }
+      },
+      post: {
+        tags: ["Bridge"],
+        summary: "Mint a virtual key for the caller (Keycloak token auth)",
+        requestBody: { content: { "application/json": { schema: { type: "object" } } } },
+        responses: { "200": { description: "Generated key" }, "401": { description: "Invalid token" } }
+      }
+    },
+    "/bridge/keys/regenerate": {
+      post: {
+        tags: ["Bridge"],
+        summary: "Rotate the caller key by alias (Keycloak token auth)",
+        requestBody: { content: { "application/json": { schema: { type: "object", properties: { alias: { type: "string" } } } } } },
+        responses: { "200": { description: "New secret" }, "401": { description: "Invalid token" }, "404": { description: "No key with that alias" } }
+      }
+    },
+    "/bridge/models": {
+      get: {
+        tags: ["Bridge"],
+        summary: "List available LLM models (Keycloak token auth)",
+        responses: { "200": { description: "Model catalogue" }, "401": { description: "Invalid token" } }
+      }
+    }
+  },
+  components: {
+    securitySchemes: {
+      backstageUserToken: {
+        type: "http",
+        scheme: "bearer",
+        description: "Backstage-issued user token (Authorization: Bearer <token>)."
+      },
+      keycloakAccessToken: {
+        type: "http",
+        scheme: "bearer",
+        description: "Raw Keycloak access token. Bridge routes only; verified against the realm JWKS."
+      }
+    }
+  }
+};
+
 // src/provisioning.ts
 function toLiteLLMUserId(userEntityRef, userIdDomain) {
   const name = userEntityRef.split("/").pop() ?? userEntityRef;
@@ -2242,6 +2512,7 @@ async function createRouter(options) {
   const baseUrl = config.getString("litellm.baseUrl");
   const masterKey = config.getString("litellm.masterKey");
   const userIdDomain = config.getOptionalString("litellm.userIdDomain");
+  const publicBaseUrl = config.getOptionalString("litellm.publicBaseUrl") ?? baseUrl;
   const client = options.client ?? new LiteLLMClient({ baseUrl, masterKey });
   const { enabled: provisioningEnabled, defaults: provisioningDefaults } = readProvisioningDefaults(config);
   const roleConfigs = readRoleConfigs(config);
@@ -2257,6 +2528,60 @@ async function createRouter(options) {
   router.get("/health", (_req, res) => {
     res.json({ status: "ok", provisioning: provisioningEnabled });
   });
+  router.get("/config", (_req, res) => {
+    res.json({ baseUrl: publicBaseUrl });
+  });
+  router.get("/openapi.json", (_req, res) => {
+    res.json(openApiSpec);
+  });
+  router.get("/provisioning/preview", async (req, res) => {
+    if (!auditGroup) {
+      res.status(403).json({ error: "Preview is not configured (litellm.audit.group not set)" });
+      return;
+    }
+    const tokenEntityRef = await resolveUserId(req, auth);
+    if (!tokenEntityRef) {
+      res.status(401).json({ error: "Authentication required" });
+      return;
+    }
+    const allowed = await isUserMemberOfGroup(
+      tokenEntityRef,
+      auditGroup,
+      catalogClient,
+      auth,
+      logger
+    );
+    if (!allowed) {
+      res.status(403).json({ error: "Access denied: not a member of the audit group" });
+      return;
+    }
+    const group = req.query.group?.trim();
+    if (!group) {
+      res.status(400).json({ error: "group query parameter is required (e.g. group=group:default/ai-platform)" });
+      return;
+    }
+    if (!roleConfigs.length) {
+      res.json({
+        group,
+        matched_role: null,
+        effective_defaults: provisioningDefaults,
+        note: "No litellm.provisioning.roles configured \u2014 every group receives the base defaults."
+      });
+      return;
+    }
+    try {
+      const matched = roleConfigs.find((rc) => rc.group === group);
+      const effective = matched ? applyRoleOverrides(provisioningDefaults, matched) : provisioningDefaults;
+      res.json({
+        group,
+        matched_role: matched?.group ?? null,
+        effective_defaults: effective
+      });
+    } catch (error) {
+      logger.error("Failed to resolve provisioning preview", error);
+      res.status(500).json({ error: error.message });
+    }
+  });
   router.get("/user/info", async (req, res) => {
     try {
       const tokenEntityRef = await resolveUserId(req, auth);
@@ -2315,6 +2640,26 @@ async function createRouter(options) {
       res.status(500).json({ error: error.message });
     }
   });
+  async function authorizeKeyAction(req, keyId) {
+    const tokenEntityRef = await resolveUserId(req, auth);
+    const userId = tokenEntityRef ? toLiteLLMUserId(tokenEntityRef, userIdDomain) : req.query.user_id;
+    if (!userId) {
+      throw { status: 403, body: { error: "Cannot verify key ownership without an authenticated user" } };
+    }
+    const ownKeys = await client.listKeys(userId);
+    const owns = ownKeys.some((k) => (k.token ?? k.key) === keyId);
+    if (!owns) {
+      throw { status: 403, body: { error: "Access denied: key does not belong to the caller" } };
+    }
+    return { tokenEntityRef, userId };
+  }
+  function sendOwnershipError(err, res) {
+    if (err && typeof err.status === "number" && err.body) {
+      res.status(err.status).json(err.body);
+      return true;
+    }
+    return false;
+  }
   router.post("/keys/:keyId/regenerate", async (req, res) => {
     try {
       const { keyId } = req.params;
@@ -2322,11 +2667,12 @@ async function createRouter(options) {
         res.status(400).json({ error: "keyId is required" });
         return;
       }
-      const tokenEntityRef = await resolveUserId(req, auth);
+      const { tokenEntityRef } = await authorizeKeyAction(req, keyId);
       const result = await client.regenerateKey(keyId);
       logger.info({ action: "key.rotate", userId: tokenEntityRef ?? "unknown", keyId });
       res.json(result);
     } catch (error) {
+      if (sendOwnershipError(error, res)) return;
       logger.error("Failed to rotate key", error);
       res.status(500).json({ error: error.message });
     }
@@ -2336,8 +2682,8 @@ async function createRouter(options) {
       const body = req.body ?? {};
       const missing = [];
       if (!body.alias?.trim()) missing.push("alias");
-      if (typeof body.max_budget !== "number" || body.max_budget <= 0) {
-        missing.push("max_budget (positive number)");
+      if (body.max_budget !== null && body.max_budget !== void 0 && (typeof body.max_budget !== "number" || body.max_budget <= 0)) {
+        missing.push("max_budget (positive number, or null for unlimited)");
       }
       if (missing.length) {
         res.status(400).json({
@@ -2396,12 +2742,13 @@ async function createRouter(options) {
         res.status(400).json({ error: "keyId is required" });
         return;
       }
-      const tokenEntityRef = await resolveUserId(req, auth);
+      const { tokenEntityRef } = await authorizeKeyAction(req, keyId);
       const request = { ...req.body, key: keyId };
       const result = await client.updateKey(request);
       logger.info({ action: "key.update", userId: tokenEntityRef ?? "unknown", keyId });
       res.json(result);
     } catch (error) {
+      if (sendOwnershipError(error, res)) return;
       logger.error("Failed to update key", error);
       res.status(500).json({ error: error.message });
     }
@@ -2413,11 +2760,12 @@ async function createRouter(options) {
         res.status(400).json({ error: "keyId is required" });
         return;
       }
-      const deleteEntityRef = await resolveUserId(req, auth);
+      const { tokenEntityRef } = await authorizeKeyAction(req, keyId);
       await client.deleteKeys({ keys: [keyId] });
-      logger.info({ action: "key.delete", userId: deleteEntityRef ?? "unknown", keyId });
+      logger.info({ action: "key.delete", userId: tokenEntityRef ?? "unknown", keyId });
       res.json({ success: true });
     } catch (error) {
+      if (sendOwnershipError(error, res)) return;
       logger.error("Failed to delete key", error);
       res.status(500).json({ error: error.message });
     }
@@ -2425,11 +2773,12 @@ async function createRouter(options) {
   router.post("/keys/:keyId/block", async (req, res) => {
     try {
       const { keyId } = req.params;
-      const tokenEntityRef = await resolveUserId(req, auth);
+      const { tokenEntityRef } = await authorizeKeyAction(req, keyId);
       await client.blockKey(keyId);
       logger.info({ action: "key.block", userId: tokenEntityRef ?? "unknown", keyId });
       res.json({ success: true });
     } catch (error) {
+      if (sendOwnershipError(error, res)) return;
       logger.error("Failed to block key", error);
       res.status(500).json({ error: error.message });
     }
@@ -2437,11 +2786,12 @@ async function createRouter(options) {
   router.post("/keys/:keyId/unblock", async (req, res) => {
     try {
       const { keyId } = req.params;
-      const tokenEntityRef = await resolveUserId(req, auth);
+      const { tokenEntityRef } = await authorizeKeyAction(req, keyId);
       await client.unblockKey(keyId);
       logger.info({ action: "key.unblock", userId: tokenEntityRef ?? "unknown", keyId });
       res.json({ success: true });
     } catch (error) {
+      if (sendOwnershipError(error, res)) return;
       logger.error("Failed to unblock key", error);
       res.status(500).json({ error: error.message });
     }
@@ -2449,11 +2799,12 @@ async function createRouter(options) {
   router.post("/keys/:keyId/reset_spend", async (req, res) => {
     try {
       const { keyId } = req.params;
-      const tokenEntityRef = await resolveUserId(req, auth);
+      const { tokenEntityRef } = await authorizeKeyAction(req, keyId);
       await client.resetKeySpend(keyId);
       logger.info({ action: "key.reset_spend", userId: tokenEntityRef ?? "unknown", keyId });
       res.json({ success: true });
     } catch (error) {
+      if (sendOwnershipError(error, res)) return;
       logger.error("Failed to reset key spend", error);
       res.status(500).json({ error: error.message });
     }
@@ -2563,7 +2914,7 @@ async function createRouter(options) {
   });
   router.get("/usage", async (req, res) => {
     try {
-      const { start_date, end_date, group_by } = req.query;
+      const { start_date, end_date } = req.query;
       if (!start_date || !end_date) {
         res.status(400).json({ error: "start_date and end_date are required" });
         return;
@@ -2586,8 +2937,7 @@ async function createRouter(options) {
       const usage = await client.getUsage(
         start_date,
         end_date,
-        userId,
-        group_by
+        userId
       );
       res.json(usage);
     } catch (error) {