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

package/dist/routes/keys.js

@@ -0,0 +1,471 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerKeysRoutes = registerKeysRoutes;
+const provisioning_1 = require("../provisioning");
+const backstage_plugin_litellm_common_1 = require("@acarmisc/backstage-plugin-litellm-common");
+const keyService_1 = require("../services/keyService");
+const errors_1 = require("../errors");
+const modelAccess_1 = require("../services/modelAccess");
+const withUser_1 = require("./middleware/withUser");
+/**
+ * Register key and user routes: /user/info, /keys*, key mutations, /audit,
+ * /models and /usage. Handlers are unchanged from router.ts; only their
+ * location and access to shared state (via ctx) differ.
+ */
+function registerKeysRoutes(router, ctx) {
+    const { client, catalogClient, auth, logger, userIdDomain, provisioningEnabled, provisioningDefaults, roleConfigs, auditGroup, allowUnlimitedBudget, teamRequired, allowOwnerResetSpend, keyValidationConfig, authorizeKeyAction, sendOwnershipError, assertPermission, sendPermissionDenied, } = ctx;
+    const generateKeyInputSchema = (0, backstage_plugin_litellm_common_1.createGenerateKeyInputSchema)(keyValidationConfig);
+    const updateKeyInputSchema = (0, backstage_plugin_litellm_common_1.createUpdateKeyInputSchema)(keyValidationConfig);
+    router.get('/user/info', async (_req, res) => {
+        try {
+            const tokenEntityRef = res.locals.tokenEntityRef;
+            const userInfo = await (0, withUser_1.getProvisionedUser)(ctx, res);
+            const canViewAudit = auditGroup && tokenEntityRef
+                ? await (0, provisioning_1.isUserMemberOfGroup)(tokenEntityRef, auditGroup, catalogClient, auth, logger)
+                : false;
+            res.json({ ...userInfo, can_view_audit: canViewAudit });
+        }
+        catch (error) {
+            if (error instanceof provisioning_1.ProvisioningError) {
+                res.status(error.status).json(error.body);
+                return;
+            }
+            (0, errors_1.sendError)(res, error, logger, 'fetch user info');
+        }
+    });
+    router.get('/keys', async (_req, res) => {
+        try {
+            const userId = res.locals.userId;
+            await (0, withUser_1.getProvisionedUser)(ctx, res);
+            const keys = await client.listKeys(userId);
+            res.json(keys);
+        }
+        catch (error) {
+            if (error instanceof provisioning_1.ProvisioningError) {
+                res.status(error.status).json(error.body);
+                return;
+            }
+            (0, errors_1.sendError)(res, error, logger, 'list keys');
+        }
+    });
+    router.post('/keys/prune-expired', async (_req, res) => {
+        try {
+            // Permission check
+            if (!(await assertPermission(_req, backstage_plugin_litellm_common_1.litellmKeyRevokePermission))) {
+                sendPermissionDenied(res, backstage_plugin_litellm_common_1.litellmKeyRevokePermission);
+                return;
+            }
+            const userId = res.locals.userId;
+            // Ensure the user is provisioned
+            await (0, withUser_1.getProvisionedUser)(ctx, res);
+            // Load the caller's keys
+            const keys = await client.listKeys(userId);
+            // Identify expired keys (expires_at in the past)
+            const now = Date.now();
+            const expiredKeys = keys.filter(k => {
+                if (!k.expires_at)
+                    return false;
+                return new Date(k.expires_at).getTime() < now;
+            });
+            if (expiredKeys.length === 0) {
+                res.json({ pruned: 0, failed: 0 });
+                return;
+            }
+            // Delete expired keys, tracking failures
+            let pruned = 0;
+            let failed = 0;
+            const failures = [];
+            for (const key of expiredKeys) {
+                try {
+                    const keyId = key.token ?? key.key;
+                    await client.deleteKeys({ keys: [keyId] });
+                    pruned++;
+                    logger.info('key.prune-expired', { userId, keyId });
+                }
+                catch (err) {
+                    failed++;
+                    const keyId = key.token ?? key.key;
+                    let errorMsg = 'Unknown error';
+                    if (err instanceof Error) {
+                        errorMsg = (0, errors_1.sanitizeUpstreamMessage)(err.message) || 'Unknown error';
+                    }
+                    failures.push({ keyId, error: errorMsg });
+                    logger.warn('key.prune-expired failed', {
+                        userId,
+                        keyId,
+                        error: errorMsg,
+                    });
+                }
+            }
+            const response = { pruned, failed };
+            if (failures.length > 0) {
+                response.failures = failures;
+            }
+            res.json(response);
+        }
+        catch (error) {
+            if (error instanceof provisioning_1.ProvisioningError) {
+                res.status(error.status).json(error.body);
+                return;
+            }
+            (0, errors_1.sendError)(res, error, logger, 'prune expired keys');
+        }
+    });
+    router.post('/keys/generate', async (req, res) => {
+        try {
+            // ── Parse & validate input with strict schema ────────────────────────
+            const parseResult = generateKeyInputSchema.safeParse(req.body);
+            if (!parseResult.success) {
+                const errorMessages = parseResult.error.errors
+                    .map(e => `${e.path.join('.')}: ${e.message}`)
+                    .join('; ');
+                res.status(400).json({
+                    error: 'Invalid request body',
+                    details: errorMessages,
+                });
+                return;
+            }
+            const input = parseResult.data;
+            // ── Permission check ────────────────────────────────────────────────
+            if (!(await assertPermission(req, backstage_plugin_litellm_common_1.litellmKeyCreatePermission))) {
+                sendPermissionDenied(res, backstage_plugin_litellm_common_1.litellmKeyCreatePermission);
+                return;
+            }
+            const tokenEntityRef = res.locals.tokenEntityRef;
+            const resolvedUserId = res.locals.userId;
+            // ── Create key via unified service ──────────────────────────────────
+            const keyCreateCtx = {
+                client,
+                config: {
+                    allowUnlimitedBudget,
+                    teamRequired,
+                },
+                catalogClient,
+                auth,
+                logger,
+                keyValidationConfig,
+                provisioningEnabled,
+                provisioningDefaults,
+                roleConfigs,
+                userIdDomain,
+            };
+            const result = await (0, keyService_1.createKeyForUser)({ tokenEntityRef, userId: resolvedUserId }, input, keyCreateCtx);
+            res.json(result);
+        }
+        catch (error) {
+            if (error instanceof keyService_1.KeyServiceError) {
+                res.status(error.status).json(error.body);
+                return;
+            }
+            if (error instanceof provisioning_1.ProvisioningError) {
+                res.status(error.status).json(error.body);
+                return;
+            }
+            // LiteLLM's enterprise team-key hook silently overrides the requested
+            // `duration` with the team's `metadata.team_member_key_duration` when a
+            // team_id is set, before parsing it. A malformed value there 500s with
+            // this exact message regardless of what we sent — surface that instead
+            // of the opaque passthrough so it's actionable from the LiteLLM side.
+            const teamId = req.body?.team_id;
+            if (error instanceof Error &&
+                error.message.includes('Invalid duration format') &&
+                teamId) {
+                res.status(502).json({
+                    error: 'LiteLLM rejected the key duration for this team. The team has a ' +
+                        '"Team Member Key Duration" set in LiteLLM that is not in a valid ' +
+                        '<number><unit> format (e.g. "30d") and overrides whatever duration ' +
+                        'is requested. Fix or clear it in LiteLLM under Teams → this team → ' +
+                        'Team Settings, then retry.',
+                    teamId,
+                });
+                return;
+            }
+            (0, errors_1.sendError)(res, error, logger, 'generate key');
+        }
+    });
+    router.post('/keys/:keyId/update', async (req, res) => {
+        try {
+            const { keyId } = req.params;
+            if (!keyId) {
+                res.status(400).json({ error: 'keyId is required' });
+                return;
+            }
+            if (!(await assertPermission(req, backstage_plugin_litellm_common_1.litellmKeyManagePermission))) {
+                sendPermissionDenied(res, backstage_plugin_litellm_common_1.litellmKeyManagePermission);
+                return;
+            }
+            const { tokenEntityRef, userId, key } = await authorizeKeyAction(req, keyId);
+            // ── Parse and validate request with strict schema ──────────────────────
+            // This will reject unknown fields including team_id, user_id, spend, blocked, key, budget_duration.
+            let input;
+            try {
+                input = updateKeyInputSchema.parse(req.body);
+            }
+            catch (error) {
+                const errorMessage = error && typeof error === 'object' && 'errors' in error
+                    ? error.errors?.[0]?.message || 'Invalid request'
+                    : 'Invalid request';
+                const details = error && typeof error === 'object' && 'errors' in error
+                    ? error.errors
+                    : undefined;
+                res.status(400).json({
+                    error: errorMessage,
+                    ...(details && { details }),
+                });
+                return;
+            }
+            // ── Enforce budget rules ──────────────────────────────────────────────
+            // allowUnlimitedBudget===false rejects max_budget:null explicitly sent
+            if (!allowUnlimitedBudget && input.max_budget === null) {
+                res.status(400).json({
+                    error: 'max_budget cannot be null when unlimited budgets are not allowed',
+                });
+                return;
+            }
+            // ── Validate models are subset of allowed using the key's team_id ─────
+            if (input.models && input.models.length > 0) {
+                let allowedModels = [];
+                if (key.team_id) {
+                    // Fetch team info to get its allowed models.
+                    // Fail closed: if the team can't be fetched, the error propagates.
+                    try {
+                        const teamInfo = await client.getTeamInfo(key.team_id);
+                        allowedModels = teamInfo?.models ?? [];
+                    }
+                    catch (err) {
+                        (0, errors_1.sendError)(res, err, logger, 'fetch team info for model validation');
+                        return;
+                    }
+                }
+                else {
+                    // Use user's models if no team
+                    const userInfo = await client.getUserInfo(userId);
+                    allowedModels = userInfo?.models ?? [];
+                }
+                const disallowed = await (0, modelAccess_1.findDisallowedModels)(client, input.models, allowedModels);
+                if (disallowed.length > 0) {
+                    res.status(400).json({
+                        error: 'One or more requested models are not allowed',
+                        disallowed_models: disallowed,
+                    });
+                    return;
+                }
+            }
+            // ── Build upstream request EXPLICITLY from parsed fields ──────────────
+            // Never spread the raw body; only include fields we've explicitly validated.
+            const upstreamRequest = {
+                key: keyId,
+            };
+            if (input.key_alias !== undefined) {
+                upstreamRequest.key_alias = input.key_alias;
+            }
+            if (input.models !== undefined) {
+                upstreamRequest.models = input.models;
+            }
+            if (input.max_budget !== undefined) {
+                // max_budget from input can be null (unlimited) or a number
+                upstreamRequest.max_budget = input.max_budget;
+            }
+            if (input.tpm_limit !== undefined) {
+                upstreamRequest.tpm_limit = input.tpm_limit;
+            }
+            if (input.rpm_limit !== undefined) {
+                upstreamRequest.rpm_limit = input.rpm_limit;
+            }
+            const result = await client.updateKey(upstreamRequest);
+            logger.info('key.update', { userId: tokenEntityRef ?? 'unknown', keyId });
+            res.json(result);
+        }
+        catch (error) {
+            if (sendOwnershipError(error, res))
+                return;
+            (0, errors_1.sendError)(res, error, logger, 'update key');
+        }
+    });
+    router.delete('/keys/:keyId', async (req, res) => {
+        try {
+            const { keyId } = req.params;
+            if (!keyId) {
+                res.status(400).json({ error: 'keyId is required' });
+                return;
+            }
+            if (!(await assertPermission(req, backstage_plugin_litellm_common_1.litellmKeyRevokePermission))) {
+                sendPermissionDenied(res, backstage_plugin_litellm_common_1.litellmKeyRevokePermission);
+                return;
+            }
+            const { tokenEntityRef } = await authorizeKeyAction(req, keyId);
+            await client.deleteKeys({ keys: [keyId] });
+            logger.info('key.delete', { userId: tokenEntityRef ?? 'unknown', keyId });
+            res.json({ success: true });
+        }
+        catch (error) {
+            if (sendOwnershipError(error, res))
+                return;
+            (0, errors_1.sendError)(res, error, logger, 'delete key');
+        }
+    });
+    router.post('/keys/:keyId/block', async (req, res) => {
+        try {
+            const { keyId } = req.params;
+            if (!(await assertPermission(req, backstage_plugin_litellm_common_1.litellmKeyManagePermission))) {
+                sendPermissionDenied(res, backstage_plugin_litellm_common_1.litellmKeyManagePermission);
+                return;
+            }
+            const { tokenEntityRef, key } = await authorizeKeyAction(req, keyId);
+            // An already-blocked key keeps its original `blocked_by`. Re-blocking would
+            // otherwise let an owner take over an admin's block and then unblock it.
+            if (key.blocked) {
+                res.status(409).json({ error: 'Key is already blocked' });
+                return;
+            }
+            // Record metadata: who blocked this key and when
+            const updatedMetadata = {
+                ...(key.metadata ?? {}),
+                blocked_by: tokenEntityRef,
+                blocked_at: new Date().toISOString(),
+            };
+            await client.blockKey(keyId);
+            // Also update the key's metadata to record blocked_by and blocked_at
+            await client.updateKey({
+                key: keyId,
+                metadata: updatedMetadata,
+            });
+            logger.info('key.block', { userId: tokenEntityRef ?? 'unknown', keyId });
+            res.json({ success: true });
+        }
+        catch (error) {
+            if (sendOwnershipError(error, res))
+                return;
+            (0, errors_1.sendError)(res, error, logger, 'block key');
+        }
+    });
+    router.post('/keys/:keyId/unblock', async (req, res) => {
+        try {
+            const { keyId } = req.params;
+            const { tokenEntityRef, key } = await authorizeKeyAction(req, keyId);
+            // Check if the key can be unblocked:
+            // - Owner can unblock a self-blocked key (metadata.blocked_by === tokenEntityRef)
+            // - Otherwise require the unblock permission
+            const isOwnerUnblockingOwnBlock = key.metadata?.blocked_by === tokenEntityRef;
+            if (!isOwnerUnblockingOwnBlock) {
+                if (!(await assertPermission(req, backstage_plugin_litellm_common_1.litellmKeyUnblockPermission))) {
+                    sendPermissionDenied(res, backstage_plugin_litellm_common_1.litellmKeyUnblockPermission);
+                    return;
+                }
+            }
+            await client.unblockKey(keyId);
+            // Clear the block record on unblock. Set the fields to null rather than
+            // deleting them: whether LiteLLM merges or replaces metadata on update, a
+            // stale `blocked_by` must not survive, or a later admin block could be
+            // lifted by the same owner.
+            const updatedMetadata = {
+                ...(key.metadata ?? {}),
+                blocked_by: null,
+                blocked_at: null,
+            };
+            await client.updateKey({
+                key: keyId,
+                metadata: updatedMetadata,
+            });
+            logger.info('key.unblock', { userId: tokenEntityRef ?? 'unknown', keyId });
+            res.json({ success: true });
+        }
+        catch (error) {
+            if (sendOwnershipError(error, res))
+                return;
+            (0, errors_1.sendError)(res, error, logger, 'unblock key');
+        }
+    });
+    router.post('/keys/:keyId/reset_spend', async (req, res) => {
+        try {
+            const { keyId } = req.params;
+            // Fail closed: check the config flag first — if false, always deny even with an allow-all permission
+            if (!allowOwnerResetSpend) {
+                res.status(403).json({
+                    error: 'Reset spend is not allowed. Contact your administrator to enable this action.',
+                });
+                return;
+            }
+            // Then check permissions
+            if (!(await assertPermission(req, backstage_plugin_litellm_common_1.litellmKeyResetSpendPermission))) {
+                sendPermissionDenied(res, backstage_plugin_litellm_common_1.litellmKeyResetSpendPermission);
+                return;
+            }
+            const { tokenEntityRef } = await authorizeKeyAction(req, keyId);
+            await client.resetKeySpend(keyId);
+            logger.info('key.reset_spend', { userId: tokenEntityRef ?? 'unknown', keyId });
+            res.json({ success: true });
+        }
+        catch (error) {
+            if (sendOwnershipError(error, res))
+                return;
+            (0, errors_1.sendError)(res, error, logger, 'reset key spend');
+        }
+    });
+    router.get('/audit', async (req, res) => {
+        if (!auditGroup) {
+            res.status(403).json({ error: 'Audit log is not configured (litellm.audit.group not set)' });
+            return;
+        }
+        const tokenEntityRef = await (0, provisioning_1.resolveUserId)(req, auth);
+        if (!tokenEntityRef) {
+            res.status(401).json({ error: 'Authentication required' });
+            return;
+        }
+        const allowed = await (0, provisioning_1.isUserMemberOfGroup)(tokenEntityRef, auditGroup, catalogClient, auth, logger);
+        if (!allowed) {
+            res.status(403).json({ error: 'Access denied: not a member of the audit group' });
+            return;
+        }
+        if (!(await assertPermission(req, backstage_plugin_litellm_common_1.litellmAuditReadPermission))) {
+            sendPermissionDenied(res, backstage_plugin_litellm_common_1.litellmAuditReadPermission);
+            return;
+        }
+        try {
+            const { page, page_size, start_date, end_date, action, table_name, changed_by } = req.query;
+            const result = await client.getAuditLogs({
+                page: page ? Number(page) : undefined,
+                page_size: page_size ? Number(page_size) : 25,
+                start_date,
+                end_date,
+                action,
+                table_name,
+                changed_by,
+            });
+            res.json(result);
+        }
+        catch (error) {
+            (0, errors_1.sendError)(res, error, logger, 'fetch audit logs');
+        }
+    });
+    router.get('/models', async (_req, res) => {
+        try {
+            const models = await client.listModels();
+            res.json(models);
+        }
+        catch (error) {
+            (0, errors_1.sendError)(res, error, logger, 'list models');
+        }
+    });
+    router.get('/usage', async (req, res) => {
+        try {
+            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;
+            }
+            const tokenEntityRef = res.locals.tokenEntityRef;
+            const userId = res.locals.userId;
+            await (0, provisioning_1.getOrProvisionUser)(client, tokenEntityRef, userId, provisioningEnabled, provisioningDefaults, roleConfigs, catalogClient, auth, logger);
+            const usage = await client.getUsage(start_date, end_date, userId);
+            res.json(usage);
+        }
+        catch (error) {
+            if (error instanceof provisioning_1.ProvisioningError) {
+                res.status(error.status).json(error.body);
+                return;
+            }
+            (0, errors_1.sendError)(res, error, logger, 'fetch usage');
+        }
+    });
+}

package/dist/routes/middleware/withUser.d.ts

@@ -0,0 +1,18 @@
+import { Request, Response, NextFunction } from 'express';
+import type { RouterContext } from '../context';
+/**
+ * Express middleware that resolves a Backstage user principal to a LiteLLM user ID.
+ * Stores both `tokenEntityRef` and `userId` in res.locals for downstream handlers.
+ *
+ * Returns 401 if the request lacks a valid Backstage user credential.
+ */
+export declare function createRequireUser(ctx: RouterContext): (req: Request, res: Response, next: NextFunction) => Promise<void>;
+/**
+ * Helper to fetch and provision a user from res.locals (populated by requireUser middleware).
+ * Returns the user info or throws ProvisioningError (which the caller must handle and respond to).
+ *
+ * This deduplicates the repeated pattern:
+ *   const userInfo = await getOrProvisionUser(...);
+ *   if (error instanceof ProvisioningError) { res.status(...).json(...); return; }
+ */
+export declare function getProvisionedUser(ctx: RouterContext, res: Response): Promise<any>;

package/dist/routes/middleware/withUser.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRequireUser = createRequireUser;
+exports.getProvisionedUser = getProvisionedUser;
+const provisioning_1 = require("../../provisioning");
+/**
+ * Express middleware that resolves a Backstage user principal to a LiteLLM user ID.
+ * Stores both `tokenEntityRef` and `userId` in res.locals for downstream handlers.
+ *
+ * Returns 401 if the request lacks a valid Backstage user credential.
+ */
+function createRequireUser(ctx) {
+    return async (req, res, next) => {
+        try {
+            const tokenEntityRef = await (0, provisioning_1.resolveUserId)(req, ctx.auth);
+            if (!tokenEntityRef) {
+                res.status(401).json({ error: 'A Backstage user credential is required' });
+                return;
+            }
+            res.locals.tokenEntityRef = tokenEntityRef;
+            res.locals.userId = (0, provisioning_1.toLiteLLMUserId)(tokenEntityRef, ctx.userIdDomain);
+            next();
+        }
+        catch (error) {
+            res.status(401).json({ error: 'A Backstage user credential is required' });
+        }
+    };
+}
+/**
+ * Helper to fetch and provision a user from res.locals (populated by requireUser middleware).
+ * Returns the user info or throws ProvisioningError (which the caller must handle and respond to).
+ *
+ * This deduplicates the repeated pattern:
+ *   const userInfo = await getOrProvisionUser(...);
+ *   if (error instanceof ProvisioningError) { res.status(...).json(...); return; }
+ */
+async function getProvisionedUser(ctx, res) {
+    const tokenEntityRef = res.locals.tokenEntityRef;
+    const userId = res.locals.userId;
+    return (0, provisioning_1.getOrProvisionUser)(ctx.client, tokenEntityRef, userId, ctx.provisioningEnabled, ctx.provisioningDefaults, ctx.roleConfigs, ctx.catalogClient, ctx.auth, ctx.logger);
+}

package/dist/routes/objectPermissions.d.ts

@@ -0,0 +1,3 @@
+import { Router } from 'express';
+import type { RouterContext } from './context';
+export declare function registerObjectPermissionsRoutes(router: Router, ctx: RouterContext): void;