@acarmisc/backstage-plugin-litellm-backend 0.8.2 → 0.9.0

package/dist/index.d.ts

@@ -7,3 +7,4 @@ export { resolveUserId, resolveUserProfile, toLiteLLMUserId, getOrProvisionUser,
 export type { BackstageUserProfile } from './provisioning';
 export { KeycloakJWTVerifier, newDefaultVerifier, readBridgeConfig, resolveBridgeUserId, getOrProvisionUserFromClaims, bridgeListKeys, bridgeGenerateKey, } from './bridge';
 export type { BridgeClaims, TokenVerifier, BridgeConfig, KeycloakJWTVerifierOptions, } from './bridge';
+export { litellmPermissions, litellmKeyCreatePermission, litellmKeyRevokePermission, litellmKeyManagePermission, litellmAuditReadPermission, } from './permissions';

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.bridgeGenerateKey = exports.bridgeListKeys = exports.getOrProvisionUserFromClaims = exports.resolveBridgeUserId = exports.readBridgeConfig = exports.newDefaultVerifier = exports.KeycloakJWTVerifier = exports.ProvisioningError = exports.resolveUserRole = exports.applyRoleOverrides = exports.readRoleConfigs = exports.readProvisioningDefaults = exports.provisionUser = exports.getOrProvisionUser = exports.toLiteLLMUserId = exports.resolveUserProfile = exports.resolveUserId = exports.LiteLLMClient = exports.createRouter = exports.default = exports.litellmPlugin = void 0;
+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.ProvisioningError = exports.resolveUserRole = exports.applyRoleOverrides = exports.readRoleConfigs = exports.readProvisioningDefaults = exports.provisionUser = exports.getOrProvisionUser = exports.toLiteLLMUserId = exports.resolveUserProfile = exports.resolveUserId = 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");
@@ -43,3 +43,9 @@ 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; } });

package/dist/permissions.d.ts

@@ -0,0 +1,5 @@
+export declare const litellmKeyCreatePermission: import("@backstage/plugin-permission-common").BasicPermission;
+export declare const litellmKeyRevokePermission: import("@backstage/plugin-permission-common").BasicPermission;
+export declare const litellmKeyManagePermission: import("@backstage/plugin-permission-common").BasicPermission;
+export declare const litellmAuditReadPermission: import("@backstage/plugin-permission-common").BasicPermission;
+export declare const litellmPermissions: import("@backstage/plugin-permission-common").BasicPermission[];

package/dist/permissions.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.litellmPermissions = exports.litellmAuditReadPermission = exports.litellmKeyManagePermission = exports.litellmKeyRevokePermission = exports.litellmKeyCreatePermission = void 0;
+const plugin_permission_common_1 = require("@backstage/plugin-permission-common");
+exports.litellmKeyCreatePermission = (0, plugin_permission_common_1.createPermission)({
+    name: 'litellm.key.create',
+    attributes: { action: 'create' },
+});
+exports.litellmKeyRevokePermission = (0, plugin_permission_common_1.createPermission)({
+    name: 'litellm.key.revoke',
+    attributes: { action: 'delete' },
+});
+exports.litellmKeyManagePermission = (0, plugin_permission_common_1.createPermission)({
+    name: 'litellm.key.manage',
+    attributes: { action: 'update' },
+});
+exports.litellmAuditReadPermission = (0, plugin_permission_common_1.createPermission)({
+    name: 'litellm.audit.read',
+    attributes: { action: 'read' },
+});
+exports.litellmPermissions = [
+    exports.litellmKeyCreatePermission,
+    exports.litellmKeyRevokePermission,
+    exports.litellmKeyManagePermission,
+    exports.litellmAuditReadPermission,
+];

package/dist/plugin.js

@@ -4,6 +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");
 exports.litellmPlugin = (0, backend_plugin_api_1.createBackendPlugin)({
     pluginId: 'litellm',
     register(reg) {
@@ -14,9 +15,18 @@ exports.litellmPlugin = (0, backend_plugin_api_1.createBackendPlugin)({
                 logger: backend_plugin_api_1.coreServices.logger,
                 auth: backend_plugin_api_1.coreServices.auth,
                 discovery: backend_plugin_api_1.coreServices.discovery,
+                permissions: backend_plugin_api_1.coreServices.permissions,
+                permissionsRegistry: backend_plugin_api_1.coreServices.permissionsRegistry,
             },
-            async init({ httpRouter, config, logger, auth, discovery }) {
-                const router = await (0, router_1.createRouter)({ config, logger, auth, discovery });
+            async init({ httpRouter, config, logger, auth, discovery, permissions, permissionsRegistry, }) {
+                permissionsRegistry.addPermissions(permissions_1.litellmPermissions);
+                const router = await (0, router_1.createRouter)({
+                    config,
+                    logger,
+                    auth,
+                    discovery,
+                    permissions,
+                });
                 httpRouter.use(router);
                 // The CLI bridge verifies raw Keycloak JWTs itself (it does NOT use a
                 // Backstage-issued token). Exempt its routes from the default auth

package/dist/provisioning.d.ts

@@ -1,5 +1,5 @@
 import { Config } from '@backstage/config';
-import { AuthService } from '@backstage/backend-plugin-api';
+import { AuthService, BackstageCredentials } from '@backstage/backend-plugin-api';
 import { CatalogClient } from '@backstage/catalog-client';
 import { Request } from 'express';
 import { LiteLLMClient } from './client';
@@ -45,6 +45,11 @@ export declare function readProvisioningDefaults(config: Config): {
  * the request carries no user credential (service-to-service calls).
  */
 export declare function resolveUserId(req: Request, auth: AuthService): Promise<string | undefined>;
+/**
+ * Like resolveUserId, but returns the raw BackstageCredentials object
+ * (rather than just the entity ref) for passing into PermissionsService.authorize().
+ */
+export declare function resolveCredentials(req: Request, auth: AuthService): Promise<BackstageCredentials | undefined>;
 /**
  * Profile data extracted from a Backstage Catalog User entity, used to
  * populate user_email / user_alias on the LiteLLM record.

package/dist/provisioning.js

@@ -6,6 +6,7 @@ exports.readRoleConfigs = readRoleConfigs;
 exports.applyRoleOverrides = applyRoleOverrides;
 exports.readProvisioningDefaults = readProvisioningDefaults;
 exports.resolveUserId = resolveUserId;
+exports.resolveCredentials = resolveCredentials;
 exports.resolveUserProfile = resolveUserProfile;
 exports.provisionUser = provisionUser;
 exports.getOrProvisionUser = getOrProvisionUser;
@@ -116,6 +117,21 @@ async function resolveUserId(req, auth) {
     }
     return undefined;
 }
+/**
+ * Like resolveUserId, but returns the raw BackstageCredentials object
+ * (rather than just the entity ref) for passing into PermissionsService.authorize().
+ */
+async function resolveCredentials(req, auth) {
+    const rawToken = req.headers.authorization?.slice(7);
+    if (!rawToken)
+        return undefined;
+    try {
+        return await auth.authenticate(rawToken);
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Looks up the catalog User entity for the authenticated user and returns
  * the profile block. Returns an empty object when the user has no catalog

package/dist/router.d.ts

@@ -1,6 +1,6 @@
 import { Router } from 'express';
 import { Config } from '@backstage/config';
-import { AuthService, DiscoveryService } from '@backstage/backend-plugin-api';
+import { AuthService, DiscoveryService, PermissionsService } from '@backstage/backend-plugin-api';
 import { LiteLLMClient } from './client';
 import { ProvisioningError } from './provisioning';
 import { TokenVerifier } from './bridge';
@@ -10,6 +10,7 @@ export interface RouterOptions {
     logger: any;
     auth: AuthService;
     discovery: DiscoveryService;
+    permissions: PermissionsService;
     /** Override the LiteLLM client (tests). Defaults to one built from config. */
     client?: LiteLLMClient;
     /** Override the bridge token verifier (tests). Defaults to a Keycloak JWKS verifier. */

package/dist/router.js

@@ -36,14 +36,16 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ProvisioningError = void 0;
 exports.createRouter = createRouter;
 const express_1 = __importStar(require("express"));
+const plugin_permission_common_1 = require("@backstage/plugin-permission-common");
 const catalog_client_1 = require("@backstage/catalog-client");
 const client_1 = require("./client");
 const openapi_1 = require("./openapi");
 const provisioning_1 = require("./provisioning");
 Object.defineProperty(exports, "ProvisioningError", { enumerable: true, get: function () { return provisioning_1.ProvisioningError; } });
 const bridge_1 = require("./bridge");
+const permissions_1 = require("./permissions");
 async function createRouter(options) {
-    const { config, logger, auth, discovery } = options;
+    const { config, logger, auth, discovery, permissions } = options;
     const baseUrl = config.getString('litellm.baseUrl');
     const masterKey = config.getString('litellm.masterKey');
     const userIdDomain = config.getOptionalString('litellm.userIdDomain');
@@ -212,6 +214,27 @@ async function createRouter(options) {
         }
         return false;
     }
+    // ── Permission-framework guard ───────────────────────────────────────────
+    //
+    // Coarse-grained "is this identity allowed to do this at all" check, layered
+    // on top of (not replacing) the ownership guard above. With no permission
+    // policy installed (the default for a fresh Backstage instance) this always
+    // resolves ALLOW, so behavior is unchanged until an operator wires up
+    // @backstage-community/plugin-rbac or a custom PermissionPolicy.
+    async function assertPermission(req, permission) {
+        const credentials = await (0, provisioning_1.resolveCredentials)(req, auth);
+        if (!credentials)
+            return false;
+        const [decision] = await permissions.authorize([{ permission }], {
+            credentials,
+        });
+        return decision.result === plugin_permission_common_1.AuthorizeResult.ALLOW;
+    }
+    function sendPermissionDenied(res, permission) {
+        res.status(403).json({
+            error: `Access denied: missing permission "${permission.name}"`,
+        });
+    }
     router.post('/keys/generate', async (req, res) => {
         try {
             // Only alias is hard-required. max_budget is optional: a positive
@@ -236,6 +259,10 @@ async function createRouter(options) {
                 });
                 return;
             }
+            if (!(await assertPermission(req, permissions_1.litellmKeyCreatePermission))) {
+                sendPermissionDenied(res, permissions_1.litellmKeyCreatePermission);
+                return;
+            }
             const tokenEntityRef = await (0, provisioning_1.resolveUserId)(req, auth);
             const resolvedUserId = tokenEntityRef
                 ? (0, provisioning_1.toLiteLLMUserId)(tokenEntityRef, userIdDomain)
@@ -314,6 +341,10 @@ async function createRouter(options) {
                 res.status(400).json({ error: 'keyId is required' });
                 return;
             }
+            if (!(await assertPermission(req, permissions_1.litellmKeyManagePermission))) {
+                sendPermissionDenied(res, permissions_1.litellmKeyManagePermission);
+                return;
+            }
             const { tokenEntityRef } = await authorizeKeyAction(req, keyId);
             const request = { ...req.body, key: keyId };
             const result = await client.updateKey(request);
@@ -334,6 +365,10 @@ async function createRouter(options) {
                 res.status(400).json({ error: 'keyId is required' });
                 return;
             }
+            if (!(await assertPermission(req, permissions_1.litellmKeyRevokePermission))) {
+                sendPermissionDenied(res, permissions_1.litellmKeyRevokePermission);
+                return;
+            }
             const { tokenEntityRef } = await authorizeKeyAction(req, keyId);
             await client.deleteKeys({ keys: [keyId] });
             logger.info({ action: 'key.delete', userId: tokenEntityRef ?? 'unknown', keyId });
@@ -349,6 +384,10 @@ async function createRouter(options) {
     router.post('/keys/:keyId/block', async (req, res) => {
         try {
             const { keyId } = req.params;
+            if (!(await assertPermission(req, permissions_1.litellmKeyManagePermission))) {
+                sendPermissionDenied(res, permissions_1.litellmKeyManagePermission);
+                return;
+            }
             const { tokenEntityRef } = await authorizeKeyAction(req, keyId);
             await client.blockKey(keyId);
             logger.info({ action: 'key.block', userId: tokenEntityRef ?? 'unknown', keyId });
@@ -364,6 +403,10 @@ async function createRouter(options) {
     router.post('/keys/:keyId/unblock', async (req, res) => {
         try {
             const { keyId } = req.params;
+            if (!(await assertPermission(req, permissions_1.litellmKeyManagePermission))) {
+                sendPermissionDenied(res, permissions_1.litellmKeyManagePermission);
+                return;
+            }
             const { tokenEntityRef } = await authorizeKeyAction(req, keyId);
             await client.unblockKey(keyId);
             logger.info({ action: 'key.unblock', userId: tokenEntityRef ?? 'unknown', keyId });
@@ -379,6 +422,10 @@ async function createRouter(options) {
     router.post('/keys/:keyId/reset_spend', async (req, res) => {
         try {
             const { keyId } = req.params;
+            if (!(await assertPermission(req, permissions_1.litellmKeyManagePermission))) {
+                sendPermissionDenied(res, permissions_1.litellmKeyManagePermission);
+                return;
+            }
             const { tokenEntityRef } = await authorizeKeyAction(req, keyId);
             await client.resetKeySpend(keyId);
             logger.info({ action: 'key.reset_spend', userId: tokenEntityRef ?? 'unknown', keyId });
@@ -406,6 +453,10 @@ async function createRouter(options) {
             res.status(403).json({ error: 'Access denied: not a member of the audit group' });
             return;
         }
+        if (!(await assertPermission(req, permissions_1.litellmAuditReadPermission))) {
+            sendPermissionDenied(res, permissions_1.litellmAuditReadPermission);
+            return;
+        }
         try {
             const { page, page_size, start_date, end_date, action, table_name, changed_by } = req.query;
             const result = await client.getAuditLogs({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acarmisc/backstage-plugin-litellm-backend",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "The Backstage backend plugin for LiteLLM governance",
   "backstage": {
     "role": "backend-plugin",
@@ -31,6 +31,7 @@
     "build": "node build.js && tsc -p tsconfig.json",
     "lint": "eslint src --ext .ts",
     "test": "tsc -p tsconfig.test.json && node --test dist-test/**/*.test.js dist-test/*.test.js",
+    "api-report": "npm run build && api-extractor run --local --verbose",
     "prepack": "npm run build",
     "postpack": ""
   },
@@ -39,16 +40,18 @@
     "@backstage/catalog-client": "^1.9.0",
     "@backstage/catalog-model": "^1.7.0",
     "@backstage/config": "^1.3.0",
+    "@backstage/plugin-permission-common": "^0.9.10",
     "@backstage/types": "^1.2.0",
     "express": "^4.18.2",
     "jose": "^5.9.6"
   },
   "devDependencies": {
     "@backstage/cli": "^0.36.2",
+    "@microsoft/api-extractor": "^7.59.0",
     "@types/express": "^4.17.25",
+    "@types/node": "^20.0.0",
     "esbuild": "^0.28.0",
-    "typescript": "^5.9.3",
-    "@types/node": "^20.0.0"
+    "typescript": "^5.9.3"
   },
   "configSchema": "config.d.ts"
 }