@acarmisc/backstage-plugin-litellm-backend 0.14.0 → 0.16.0

package/dist/index.d.ts

@@ -11,4 +11,4 @@ export { readTeamBudgetVisibility, redactTeamBudget, redactTeamUsage, teamBudget
 export type { TeamBudgetVisibility, TeamBudgetStatus } from './teamBudgetVisibility';
 export { KeycloakJWTVerifier, newDefaultVerifier, readBridgeConfig, resolveBridgeUserId, getOrProvisionUserFromClaims, bridgeListKeys, bridgeGenerateKey, } from './bridge';
 export type { BridgeClaims, TokenVerifier, BridgeConfig, KeycloakJWTVerifierOptions, } from './bridge';
-export { litellmPermissions, litellmKeyCreatePermission, litellmKeyRevokePermission, litellmKeyManagePermission, litellmAuditReadPermission, litellmTeamCreatePermission, litellmTeamManagePermission, litellmTeamMembersManagePermission, litellmTeamKnowledgebaseManagePermission, litellmTeamMcpManagePermission, litellmTeamDeletePermission, } from './permissions';
+export { litellmPermissions, litellmKeyCreatePermission, litellmKeyRevokePermission, litellmKeyManagePermission, litellmKeyResetSpendPermission, litellmKeyUnblockPermission, litellmAuditReadPermission, litellmTeamCreatePermission, litellmTeamManagePermission, litellmTeamMembersManagePermission, litellmTeamKnowledgebaseManagePermission, litellmTeamMcpManagePermission, litellmTeamDeletePermission, } from '@acarmisc/backstage-plugin-litellm-common';

package/dist/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.litellmTeamDeletePermission = exports.litellmTeamMcpManagePermission = exports.litellmTeamKnowledgebaseManagePermission = exports.litellmTeamMembersManagePermission = exports.litellmTeamManagePermission = exports.litellmTeamCreatePermission = exports.litellmAuditReadPermission = exports.litellmKeyManagePermission = exports.litellmKeyRevokePermission = exports.litellmKeyCreatePermission = exports.litellmPermissions = exports.bridgeGenerateKey = exports.bridgeListKeys = exports.getOrProvisionUserFromClaims = exports.resolveBridgeUserId = exports.readBridgeConfig = exports.newDefaultVerifier = exports.KeycloakJWTVerifier = exports.teamBudgetStatusFor = exports.redactTeamUsage = exports.redactTeamBudget = exports.readTeamBudgetVisibility = exports.validateTeamPatchInput = exports.validateTeamWriteInput = exports.assertTeamAdmin = exports.isTeamManagementEnabled = exports.readTeamAdminConfig = exports.ProvisioningError = exports.resolveUserRole = exports.applyRoleOverrides = exports.readRoleConfigs = exports.readProvisioningDefaults = exports.provisionUser = exports.getOrProvisionUser = exports.toLiteLLMUserId = exports.resolveUserProfile = exports.resolveUserId = exports.normalizeRequestTags = exports.LiteLLMClient = exports.createRouter = exports.default = exports.litellmPlugin = void 0;
+exports.litellmTeamDeletePermission = exports.litellmTeamMcpManagePermission = exports.litellmTeamKnowledgebaseManagePermission = exports.litellmTeamMembersManagePermission = exports.litellmTeamManagePermission = exports.litellmTeamCreatePermission = exports.litellmAuditReadPermission = exports.litellmKeyUnblockPermission = exports.litellmKeyResetSpendPermission = exports.litellmKeyManagePermission = exports.litellmKeyRevokePermission = exports.litellmKeyCreatePermission = exports.litellmPermissions = exports.bridgeGenerateKey = exports.bridgeListKeys = exports.getOrProvisionUserFromClaims = exports.resolveBridgeUserId = exports.readBridgeConfig = exports.newDefaultVerifier = exports.KeycloakJWTVerifier = exports.teamBudgetStatusFor = exports.redactTeamUsage = exports.redactTeamBudget = exports.readTeamBudgetVisibility = exports.validateTeamPatchInput = exports.validateTeamWriteInput = exports.assertTeamAdmin = exports.isTeamManagementEnabled = exports.readTeamAdminConfig = exports.ProvisioningError = exports.resolveUserRole = exports.applyRoleOverrides = exports.readRoleConfigs = exports.readProvisioningDefaults = exports.provisionUser = exports.getOrProvisionUser = exports.toLiteLLMUserId = exports.resolveUserProfile = exports.resolveUserId = exports.normalizeRequestTags = exports.LiteLLMClient = exports.createRouter = exports.default = exports.litellmPlugin = void 0;
 var plugin_1 = require("./plugin");
 Object.defineProperty(exports, "litellmPlugin", { enumerable: true, get: function () { return plugin_1.litellmPlugin; } });
 var plugin_2 = require("./plugin");
@@ -55,15 +55,17 @@ Object.defineProperty(exports, "resolveBridgeUserId", { enumerable: true, get: f
 Object.defineProperty(exports, "getOrProvisionUserFromClaims", { enumerable: true, get: function () { return bridge_1.getOrProvisionUserFromClaims; } });
 Object.defineProperty(exports, "bridgeListKeys", { enumerable: true, get: function () { return bridge_1.bridgeListKeys; } });
 Object.defineProperty(exports, "bridgeGenerateKey", { enumerable: true, get: function () { return bridge_1.bridgeGenerateKey; } });
-var permissions_1 = require("./permissions");
-Object.defineProperty(exports, "litellmPermissions", { enumerable: true, get: function () { return permissions_1.litellmPermissions; } });
-Object.defineProperty(exports, "litellmKeyCreatePermission", { enumerable: true, get: function () { return permissions_1.litellmKeyCreatePermission; } });
-Object.defineProperty(exports, "litellmKeyRevokePermission", { enumerable: true, get: function () { return permissions_1.litellmKeyRevokePermission; } });
-Object.defineProperty(exports, "litellmKeyManagePermission", { enumerable: true, get: function () { return permissions_1.litellmKeyManagePermission; } });
-Object.defineProperty(exports, "litellmAuditReadPermission", { enumerable: true, get: function () { return permissions_1.litellmAuditReadPermission; } });
-Object.defineProperty(exports, "litellmTeamCreatePermission", { enumerable: true, get: function () { return permissions_1.litellmTeamCreatePermission; } });
-Object.defineProperty(exports, "litellmTeamManagePermission", { enumerable: true, get: function () { return permissions_1.litellmTeamManagePermission; } });
-Object.defineProperty(exports, "litellmTeamMembersManagePermission", { enumerable: true, get: function () { return permissions_1.litellmTeamMembersManagePermission; } });
-Object.defineProperty(exports, "litellmTeamKnowledgebaseManagePermission", { enumerable: true, get: function () { return permissions_1.litellmTeamKnowledgebaseManagePermission; } });
-Object.defineProperty(exports, "litellmTeamMcpManagePermission", { enumerable: true, get: function () { return permissions_1.litellmTeamMcpManagePermission; } });
-Object.defineProperty(exports, "litellmTeamDeletePermission", { enumerable: true, get: function () { return permissions_1.litellmTeamDeletePermission; } });
+var backstage_plugin_litellm_common_1 = require("@acarmisc/backstage-plugin-litellm-common");
+Object.defineProperty(exports, "litellmPermissions", { enumerable: true, get: function () { return backstage_plugin_litellm_common_1.litellmPermissions; } });
+Object.defineProperty(exports, "litellmKeyCreatePermission", { enumerable: true, get: function () { return backstage_plugin_litellm_common_1.litellmKeyCreatePermission; } });
+Object.defineProperty(exports, "litellmKeyRevokePermission", { enumerable: true, get: function () { return backstage_plugin_litellm_common_1.litellmKeyRevokePermission; } });
+Object.defineProperty(exports, "litellmKeyManagePermission", { enumerable: true, get: function () { return backstage_plugin_litellm_common_1.litellmKeyManagePermission; } });
+Object.defineProperty(exports, "litellmKeyResetSpendPermission", { enumerable: true, get: function () { return backstage_plugin_litellm_common_1.litellmKeyResetSpendPermission; } });
+Object.defineProperty(exports, "litellmKeyUnblockPermission", { enumerable: true, get: function () { return backstage_plugin_litellm_common_1.litellmKeyUnblockPermission; } });
+Object.defineProperty(exports, "litellmAuditReadPermission", { enumerable: true, get: function () { return backstage_plugin_litellm_common_1.litellmAuditReadPermission; } });
+Object.defineProperty(exports, "litellmTeamCreatePermission", { enumerable: true, get: function () { return backstage_plugin_litellm_common_1.litellmTeamCreatePermission; } });
+Object.defineProperty(exports, "litellmTeamManagePermission", { enumerable: true, get: function () { return backstage_plugin_litellm_common_1.litellmTeamManagePermission; } });
+Object.defineProperty(exports, "litellmTeamMembersManagePermission", { enumerable: true, get: function () { return backstage_plugin_litellm_common_1.litellmTeamMembersManagePermission; } });
+Object.defineProperty(exports, "litellmTeamKnowledgebaseManagePermission", { enumerable: true, get: function () { return backstage_plugin_litellm_common_1.litellmTeamKnowledgebaseManagePermission; } });
+Object.defineProperty(exports, "litellmTeamMcpManagePermission", { enumerable: true, get: function () { return backstage_plugin_litellm_common_1.litellmTeamMcpManagePermission; } });
+Object.defineProperty(exports, "litellmTeamDeletePermission", { enumerable: true, get: function () { return backstage_plugin_litellm_common_1.litellmTeamDeletePermission; } });

package/dist/openapi.js

@@ -121,6 +121,23 @@ exports.openApiSpec = {
                 },
             },
         },
+        '/keys/prune-expired': {
+            post: {
+                tags: ['Keys'],
+                summary: 'Revoke all expired keys for the caller',
+                responses: {
+                    '200': { description: 'Pruning result', content: { 'application/json': { schema: { type: 'object', properties: {
+                                        pruned: { type: 'number', description: 'Count of successfully deleted keys' },
+                                        failed: { type: 'number', description: 'Count of failures' },
+                                        failures: { type: 'array', items: { type: 'object', properties: {
+                                                    keyId: { type: 'string' },
+                                                    error: { type: 'string' },
+                                                } }, description: 'Details of failed deletions (optional)' },
+                                    } } } } },
+                    '403': { description: 'Missing litellmKeyRevokePermission' },
+                },
+            },
+        },
         '/keys/{keyId}': {
             delete: {
                 tags: ['Keys'],

package/dist/plugin.js

@@ -4,7 +4,7 @@ exports.litellmPlugin = void 0;
 const backend_plugin_api_1 = require("@backstage/backend-plugin-api");
 const router_1 = require("./router");
 const bridge_1 = require("./bridge");
-const permissions_1 = require("./permissions");
+const backstage_plugin_litellm_common_1 = require("@acarmisc/backstage-plugin-litellm-common");
 exports.litellmPlugin = (0, backend_plugin_api_1.createBackendPlugin)({
     pluginId: 'litellm',
     register(reg) {
@@ -19,7 +19,7 @@ exports.litellmPlugin = (0, backend_plugin_api_1.createBackendPlugin)({
                 permissionsRegistry: backend_plugin_api_1.coreServices.permissionsRegistry,
             },
             async init({ httpRouter, config, logger, auth, discovery, permissions, permissionsRegistry, }) {
-                permissionsRegistry.addPermissions(permissions_1.litellmPermissions);
+                permissionsRegistry.addPermissions(backstage_plugin_litellm_common_1.litellmPermissions);
                 const router = await (0, router_1.createRouter)({
                     config,
                     logger,

package/dist/provisioning.d.ts

@@ -1,5 +1,5 @@
 import { Config } from '@backstage/config';
-import { AuthService, BackstageCredentials } from '@backstage/backend-plugin-api';
+import { AuthService, BackstageCredentials, LoggerService } from '@backstage/backend-plugin-api';
 import { CatalogClient } from '@backstage/catalog-client';
 import { Request } from 'express';
 import { LiteLLMClient } from './client';
@@ -16,6 +16,17 @@ import { UserInfo, ProvisioningDefaults, RoleConfig } from './types';
  * deployments where LiteLLM users were created with plain usernames.
  */
 export declare function toLiteLLMUserId(userEntityRef: string, userIdDomain?: string): string;
+/**
+ * Reads `litellm.provisioning.roles`: group-scoped overrides of the base
+ * provisioning defaults, evaluated in order (first match wins). Returns an
+ * empty list when none are configured. Fields omitted on a role fall back to
+ * the base defaults at match time (see applyRoleOverrides).
+ */
+export declare function readRoleConfigs(config: Config): RoleConfig[];
+/**
+ * Merges role config over defaults. Role fields override defaults only when explicitly set.
+ */
+export declare function applyRoleOverrides(defaults: ProvisioningDefaults, role: RoleConfig): ProvisioningDefaults;
 /**
  * Reads the provisioning block from config, applying safe defaults for every
  * field so the feature works out-of-the-box without any YAML required.
@@ -30,11 +41,6 @@ export declare function toLiteLLMUserId(userEntityRef: string, userIdDomain?: st
  *   rpmLimit:       none — same
  *   metadata:       backstage source tag only
  */
-export declare function readRoleConfigs(config: Config): RoleConfig[];
-/**
- * Merges role config over defaults. Role fields override defaults only when explicitly set.
- */
-export declare function applyRoleOverrides(defaults: ProvisioningDefaults, role: RoleConfig): ProvisioningDefaults;
 export declare function readProvisioningDefaults(config: Config): {
     enabled: boolean;
     defaults: ProvisioningDefaults;
@@ -64,12 +70,12 @@ export interface BackstageUserProfile {
  * entity (e.g. dangerouslyAllowSignInWithoutUserInCatalog was used) — the
  * caller falls back to deriving identity from userIdDomain.
  */
-export declare function resolveUserProfile(userEntityRef: string, catalogClient: CatalogClient, auth: AuthService, logger: any): Promise<BackstageUserProfile>;
+export declare function resolveUserProfile(userEntityRef: string, catalogClient: CatalogClient, auth: AuthService, logger: LoggerService): Promise<BackstageUserProfile>;
 /**
  * Creates a LiteLLM user for the given Backstage identity using the configured
  * defaults. Returns the UserInfo of the newly created account.
  */
-export declare function provisionUser(client: LiteLLMClient, userId: string, defaults: ProvisioningDefaults, profile: BackstageUserProfile, backstageEntity: string | undefined, logger: any): Promise<UserInfo | null>;
+export declare function provisionUser(client: LiteLLMClient, userId: string, defaults: ProvisioningDefaults, profile: BackstageUserProfile, backstageEntity: string | undefined, logger: LoggerService): Promise<UserInfo | null>;
 export declare class ProvisioningError extends Error {
     status: number;
     body: {
@@ -84,14 +90,14 @@ export declare class ProvisioningError extends Error {
  * When the user is missing and provisioning is enabled, attempts to create it.
  * When provisioning is disabled, throws a ProvisioningError with a clear message.
  */
-export declare function getOrProvisionUser(client: LiteLLMClient, tokenEntityRef: string | undefined, userId: string | undefined, provisioningEnabled: boolean, provisioningDefaults: ProvisioningDefaults, roleConfigs: RoleConfig[], catalogClient: CatalogClient, auth: AuthService, logger: any): Promise<UserInfo>;
+export declare function getOrProvisionUser(client: LiteLLMClient, tokenEntityRef: string | undefined, userId: string | undefined, provisioningEnabled: boolean, provisioningDefaults: ProvisioningDefaults, roleConfigs: RoleConfig[], catalogClient: CatalogClient, auth: AuthService, logger: LoggerService): Promise<UserInfo>;
 /**
  * Returns true when the user is a member of the given Backstage group entity ref.
  * Used for RBAC gates (e.g. audit log visibility) without the role-config machinery.
  */
-export declare function isUserMemberOfGroup(userEntityRef: string, group: string, catalogClient: CatalogClient, auth: AuthService, logger: any): Promise<boolean>;
+export declare function isUserMemberOfGroup(userEntityRef: string, group: string, catalogClient: CatalogClient, auth: AuthService, logger: LoggerService): Promise<boolean>;
 /**
  * Fetches the user's Backstage group memberships and returns the first matching
  * role config (priority order), or undefined when no role matches.
  */
-export declare function resolveUserRole(userEntityRef: string, roleConfigs: RoleConfig[], catalogClient: CatalogClient, auth: AuthService, logger: any): Promise<RoleConfig | undefined>;
+export declare function resolveUserRole(userEntityRef: string, roleConfigs: RoleConfig[], catalogClient: CatalogClient, auth: AuthService, logger: LoggerService): Promise<RoleConfig | undefined>;

package/dist/provisioning.js

@@ -12,6 +12,7 @@ exports.provisionUser = provisionUser;
 exports.getOrProvisionUser = getOrProvisionUser;
 exports.isUserMemberOfGroup = isUserMemberOfGroup;
 exports.resolveUserRole = resolveUserRole;
+const client_1 = require("./client");
 /**
  * Converts a Backstage user entity ref to a LiteLLM user_id.
  *
@@ -35,18 +36,10 @@ function toLiteLLMUserId(userEntityRef, userIdDomain) {
     return userIdDomain ? `${name}@${userIdDomain}` : name;
 }
 /**
- * Reads the provisioning block from config, applying safe defaults for every
- * field so the feature works out-of-the-box without any YAML required.
- *
- * Safe defaults rationale:
- *   maxBudget:      $10  — prevents runaway spend on a forgotten test account
- *   budgetDuration: 30d  — monthly reset, aligns with typical billing cycles
- *   models:         []   — empty means all proxy models are allowed;
- *                          restrict here or at team level for tighter control
- *   teams:          []   — no automatic team assignment; add IDs to enrol users
- *   tpmLimit:       none — LiteLLM global / team limits still apply
- *   rpmLimit:       none — same
- *   metadata:       backstage source tag only
+ * Reads `litellm.provisioning.roles`: group-scoped overrides of the base
+ * provisioning defaults, evaluated in order (first match wins). Returns an
+ * empty list when none are configured. Fields omitted on a role fall back to
+ * the base defaults at match time (see applyRoleOverrides).
  */
 function readRoleConfigs(config) {
     const raw = config.getOptional('litellm.provisioning.roles');
@@ -79,6 +72,20 @@ function applyRoleOverrides(defaults, role) {
         metadata: { ...defaults.metadata, ...(role.metadata ?? {}) },
     };
 }
+/**
+ * Reads the provisioning block from config, applying safe defaults for every
+ * field so the feature works out-of-the-box without any YAML required.
+ *
+ * Safe defaults rationale:
+ *   maxBudget:      $10  — prevents runaway spend on a forgotten test account
+ *   budgetDuration: 30d  — monthly reset, aligns with typical billing cycles
+ *   models:         []   — empty means all proxy models are allowed;
+ *                          restrict here or at team level for tighter control
+ *   teams:          []   — no automatic team assignment; add IDs to enrol users
+ *   tpmLimit:       none — LiteLLM global / team limits still apply
+ *   rpmLimit:       none — same
+ *   metadata:       backstage source tag only
+ */
 function readProvisioningDefaults(config) {
     const enabled = config.getOptionalBoolean('litellm.provisioning.enabled') ?? false;
     const defaults = {
@@ -152,7 +159,8 @@ async function resolveUserProfile(userEntityRef, catalogClient, auth, logger) {
         };
     }
     catch (err) {
-        logger.warn(`Could not fetch catalog profile for ${userEntityRef}: ${err.message}`);
+        const message = err instanceof Error ? err.message : String(err);
+        logger.warn(`Could not fetch catalog profile for ${userEntityRef}: ${message}`);
         return {};
     }
 }
@@ -184,7 +192,7 @@ async function provisionUser(client, userId, defaults, profile, backstageEntity,
             }),
         },
     };
-    logger.info(`Provisioning new LiteLLM user for Backstage identity: ${userId}${profile.email ? ` (email=${profile.email})` : ''}`);
+    logger.debug(`Provisioning new LiteLLM user for Backstage identity: ${userId}${profile.email ? ` (email=${profile.email})` : ''}`);
     try {
         await client.createUser(payload);
         // Defensive /user/update: LiteLLM's /user/new upsert path has been
@@ -202,14 +210,16 @@ async function provisionUser(client, userId, defaults, profile, backstageEntity,
                 });
             }
             catch (updateErr) {
-                logger.warn(`Defensive /user/update after provisioning ${userId} failed: ${updateErr.message}`);
+                const message = updateErr instanceof Error ? updateErr.message : String(updateErr);
+                logger.warn(`Defensive /user/update after provisioning ${userId} failed: ${message}`);
             }
         }
         // Fetch the freshly-created user record to return consistent UserInfo shape
         return await client.getUserInfo(userId);
     }
     catch (err) {
-        logger.error(`Failed to provision LiteLLM user ${userId}: ${err.message}`);
+        const message = err instanceof Error ? err.message : String(err);
+        logger.error(`Failed to provision LiteLLM user ${userId}: ${message}`);
         throw err;
     }
 }
@@ -299,7 +309,8 @@ async function getOrProvisionUser(client, tokenEntityRef, userId, provisioningEn
             // but keep the recovery path: if /user/new still 409s (e.g.
             // multi-replica deploys where the lock is per-process), treat
             // it as "user exists" and re-fetch.
-            if (err.status === 409 || /already exists/i.test(err.message ?? '')) {
+            if ((err instanceof client_1.LiteLLMUpstreamError && err.status === 409) ||
+                (err instanceof Error && /already exists/i.test(err.message ?? ''))) {
                 logger.info(`LiteLLM user ${userId} already exists during provisioning — re-fetching`);
                 const refetched = await client.getUserInfo(userId);
                 if (refetched) {
@@ -315,11 +326,12 @@ async function getOrProvisionUser(client, tokenEntityRef, userId, provisioningEn
             // browser, otherwise Backstage's fetch middleware treats the
             // user's Backstage session as expired and forces a re-login.
             // Only safe client-semantic codes pass through.
-            const upstreamStatus = err.status;
-            const passThrough = [400, 404, 409, 422].includes(upstreamStatus)
+            const upstreamStatus = err instanceof client_1.LiteLLMUpstreamError ? err.status : undefined;
+            const passThrough = (upstreamStatus && [400, 404, 409, 422].includes(upstreamStatus))
                 ? upstreamStatus
                 : 502;
-            throw new ProvisioningError('LiteLLM auto-provisioning failed', `LiteLLM upstream ${upstreamStatus ?? 'error'}: ${sanitizeUpstreamMessage(err.message)}`, true, passThrough);
+            const errMessage = err instanceof Error ? err.message : String(err);
+            throw new ProvisioningError('LiteLLM auto-provisioning failed', `LiteLLM upstream ${upstreamStatus ?? 'error'}: ${sanitizeUpstreamMessage(errMessage)}`, true, passThrough);
         }
     })();
     provisioningInFlight.set(userId, provisionPromise);
@@ -347,7 +359,8 @@ async function isUserMemberOfGroup(userEntityRef, group, catalogClient, auth, lo
         return groups.includes(group);
     }
     catch (err) {
-        logger.warn(`Could not check group membership for ${userEntityRef}: ${err.message}`);
+        const message = err instanceof Error ? err.message : String(err);
+        logger.warn(`Could not check group membership for ${userEntityRef}: ${message}`);
         return false;
     }
 }
@@ -370,7 +383,8 @@ async function resolveUserRole(userEntityRef, roleConfigs, catalogClient, auth,
         return roleConfigs.find(rc => groups.includes(rc.group));
     }
     catch (err) {
-        logger.warn(`Could not resolve Backstage groups for ${userEntityRef}: ${err.message}`);
+        const message = err instanceof Error ? err.message : String(err);
+        logger.warn(`Could not resolve Backstage groups for ${userEntityRef}: ${message}`);
         return undefined;
     }
 }

package/dist/router.d.ts

@@ -1,14 +1,13 @@
 import { Router } from 'express';
-import { Config } from '@backstage/config';
-import { AuthService, DiscoveryService, PermissionsService } from '@backstage/backend-plugin-api';
+import { AuthService, DiscoveryService, PermissionsService, LoggerService, RootConfigService } from '@backstage/backend-plugin-api';
 import { CatalogClient } from '@backstage/catalog-client';
 import { LiteLLMClient } from './client';
 import { ProvisioningError } from './provisioning';
 import { TokenVerifier } from './bridge';
 export { ProvisioningError };
 export interface RouterOptions {
-    config: Config;
-    logger: any;
+    config: RootConfigService;
+    logger: LoggerService;
     auth: AuthService;
     discovery: DiscoveryService;
     permissions: PermissionsService;