@acarmisc/backstage-plugin-litellm-backend 0.17.7 → 0.19.0

package/README.md

@@ -0,0 +1,58 @@
+# @acarmisc/backstage-plugin-litellm-backend
+
+Backend for the **Backstage LiteLLM Governance Plugin** (New Backend System).
+It is the only component that talks to your [LiteLLM](https://github.com/BerriAI/litellm)
+proxy: it holds the master key, resolves the caller's Backstage identity, and
+enforces budgets, key limits, team membership, model access and permissions
+before calling LiteLLM.
+
+Pair it with the frontend, [`@acarmisc/backstage-plugin-litellm`](https://www.npmjs.com/package/@acarmisc/backstage-plugin-litellm).
+
+![How the backend handles a key request](https://raw.githubusercontent.com/acarmisc/backstage-plugin-litellm-govai/main/docs/images/architecture.png)
+
+Full documentation — adoption guide, configuration reference, permissions,
+security model and architecture — starts at the
+[project README](https://github.com/acarmisc/backstage-plugin-litellm-govai#readme).
+
+## Installation
+
+```bash
+yarn --cwd packages/backend add @acarmisc/backstage-plugin-litellm-backend
+```
+
+In `packages/backend/src/index.ts`:
+
+```ts
+backend.add(import('@acarmisc/backstage-plugin-litellm-backend'));
+```
+
+## Minimal configuration
+
+```yaml
+litellm:
+  baseUrl: http://litellm-proxy:4000        # internal URL of the LiteLLM proxy
+  publicBaseUrl: https://llm.example.com    # optional: shown to users in snippets
+  masterKey: ${LITELLM_MASTER_KEY}
+  userIdDomain: example.com                 # optional: user:default/jane → jane@example.com
+  provisioning:
+    enabled: true                           # optional: create LiteLLM users on first visit
+```
+
+The configuration schema ships with the package (`config.d.ts`); see the
+[configuration reference](https://github.com/acarmisc/backstage-plugin-litellm-govai/blob/main/docs/configuration.md)
+for every key (key ceilings, team management, budget hiding, CLI bridge,
+OpenCode connect).
+
+## What it exposes
+
+Routes are mounted under `/api/litellm`. A machine-readable OpenAPI 3.1
+description is served at `/api/litellm/openapi.json`; the
+[endpoint table](https://github.com/acarmisc/backstage-plugin-litellm-govai/blob/main/docs/api.md)
+summarises them.
+
+The plugin registers the `litellm.*` permissions with the permission
+framework (see [Permissions](https://github.com/acarmisc/backstage-plugin-litellm-govai/blob/main/docs/permissions.md)).
+
+## License
+
+Apache-2.0

package/config.d.ts

@@ -324,6 +324,34 @@ export interface Config {
        */
       allowTeamDelete?: boolean;
 
+      /**
+       * When true, all team write operations return 403 even for admins:
+       * POST /teams, PATCH /teams/:id, DELETE /teams/:id,
+       * POST/DELETE /teams/:id/members, and PUT objectPermissions routes.
+       * Reads (GET /teams, GET /teams/managed) keep working.
+       * Error message: 'Team management is read-only (litellm.teamAdmin.readOnly): teams are managed outside Backstage'.
+       * @default false
+       */
+      readOnly?: boolean;
+
+      /**
+       * Backstage group refs that must include the caller for team creation.
+       * When non-empty, POST /teams additionally requires the caller to be
+       * a member of at least one of these groups, narrowing the permission.
+       * Error message: 'Access denied: team creation is limited to <comma-joined groups>'.
+       * @default []
+       */
+      createGroups?: string[];
+
+      /**
+       * LiteLLM team roles whose holders may add/remove members of their own team.
+       * When non-empty, callers with one of these roles in members_with_roles
+       * can POST/DELETE /teams/:teamId/members without owning the team's group.
+       * Allows non-admins to manage their team's membership without full admin access.
+       * @default []
+       */
+      memberManagerRoles?: string[];
+
       /**
        * Object-permission management (attaching knowledge bases / MCP servers
        * to a team). This is the highest-risk surface — attaching a vector store

package/dist/bridge.d.ts

@@ -1,7 +1,7 @@
 import { Config } from '@backstage/config';
 import { LoggerService } from '@backstage/backend-plugin-api';
 import { LiteLLMClient } from './client';
-import { GenerateKeyRequest, GenerateKeyResponse, ProvisioningDefaults, UserInfo, VirtualKey } from './types';
+import { ProvisioningDefaults, UserInfo, VirtualKey } from './types';
 /** Claims extracted from a verified Keycloak access token. */
 export interface BridgeClaims {
     sub: string;
@@ -94,7 +94,7 @@ export interface BridgeIdentityOptions {
  *
  * @throws BridgeIdentityError (403) if identity validation fails
  */
-export declare function resolveBridgeUserId(claims: BridgeClaims, identity?: string | BridgeIdentityOptions): string;
+export declare function resolveBridgeUserId(claims: BridgeClaims, identity?: BridgeIdentityOptions): string;
 /**
  * Ensures a LiteLLM user exists for the verified identity. If the user is
  * missing and provisioning is enabled, creates it from the JWT claims (email +
@@ -107,8 +107,6 @@ export declare function resolveBridgeUserId(claims: BridgeClaims, identity?: str
  * preferred_username), and helps recover from cases where the bridge's userId
  * computation and the UI's differ.
  */
-export declare function getOrProvisionUserFromClaims(client: LiteLLMClient, claims: BridgeClaims, provisioningEnabled: boolean, provisioningDefaults: ProvisioningDefaults, logger: LoggerService, userIdDomain?: string | BridgeIdentityOptions): Promise<UserInfo>;
+export declare function getOrProvisionUserFromClaims(client: LiteLLMClient, claims: BridgeClaims, provisioningEnabled: boolean, provisioningDefaults: ProvisioningDefaults, logger: LoggerService, identity?: BridgeIdentityOptions): Promise<UserInfo>;
 /** Lists the caller's virtual keys (provisioning the user first if needed). */
-export declare function bridgeListKeys(client: LiteLLMClient, claims: BridgeClaims, provisioningEnabled: boolean, provisioningDefaults: ProvisioningDefaults, logger: LoggerService, userIdDomain?: string | BridgeIdentityOptions): Promise<VirtualKey[]>;
-/** Mints a new virtual key for the caller (provisioning the user first if needed). */
-export declare function bridgeGenerateKey(client: LiteLLMClient, claims: BridgeClaims, provisioningEnabled: boolean, provisioningDefaults: ProvisioningDefaults, logger: LoggerService, request: Partial<GenerateKeyRequest>, userIdDomain?: string | BridgeIdentityOptions): Promise<GenerateKeyResponse>;
+export declare function bridgeListKeys(client: LiteLLMClient, claims: BridgeClaims, provisioningEnabled: boolean, provisioningDefaults: ProvisioningDefaults, logger: LoggerService, identity?: BridgeIdentityOptions): Promise<VirtualKey[]>;

package/dist/bridge.js

@@ -6,7 +6,6 @@ exports.newDefaultVerifier = newDefaultVerifier;
 exports.resolveBridgeUserId = resolveBridgeUserId;
 exports.getOrProvisionUserFromClaims = getOrProvisionUserFromClaims;
 exports.bridgeListKeys = bridgeListKeys;
-exports.bridgeGenerateKey = bridgeGenerateKey;
 /**
  * Bridge — lets CLI clients (Abby) list/mint LiteLLM virtual keys without ever
  * holding the LiteLLM master key.
@@ -111,18 +110,16 @@ function newDefaultVerifier(cfg) {
     }
     return new KeycloakJWTVerifier({ issuer: cfg.issuer, clientId: cfg.clientId });
 }
-/** A bare string is the legacy form: `userIdDomain`, also the only trusted domain. */
 function normalizeIdentityOptions(opts) {
-    const o = typeof opts === 'string' ? { userIdDomain: opts } : opts ?? {};
     let domains = [];
-    if (o.trustedEmailDomains?.length) {
-        domains = o.trustedEmailDomains;
+    if (opts.trustedEmailDomains?.length) {
+        domains = opts.trustedEmailDomains;
     }
-    else if (o.userIdDomain) {
-        domains = [o.userIdDomain];
+    else if (opts.userIdDomain) {
+        domains = [opts.userIdDomain];
     }
     const trusted = domains.map(d => d.toLowerCase());
-    return { userIdDomain: o.userIdDomain, trusted };
+    return { userIdDomain: opts.userIdDomain, trusted };
 }
 /**
  * Resolves the LiteLLM user_id for a verified bridge token.
@@ -147,7 +144,7 @@ function normalizeIdentityOptions(opts) {
  * @throws BridgeIdentityError (403) if identity validation fails
  */
 function resolveBridgeUserId(claims, identity) {
-    const { userIdDomain, trusted } = normalizeIdentityOptions(identity);
+    const { userIdDomain, trusted } = normalizeIdentityOptions(identity ?? {});
     if (trusted.length === 0) {
         throw new BridgeIdentityError('set litellm.bridge.allowedEmailDomains (or litellm.userIdDomain) to use the CLI bridge');
     }
@@ -193,8 +190,8 @@ function resolveBridgeUserId(claims, identity) {
  * preferred_username), and helps recover from cases where the bridge's userId
  * computation and the UI's differ.
  */
-async function getOrProvisionUserFromClaims(client, claims, provisioningEnabled, provisioningDefaults, logger, userIdDomain) {
-    const userId = resolveBridgeUserId(claims, userIdDomain);
+async function getOrProvisionUserFromClaims(client, claims, provisioningEnabled, provisioningDefaults, logger, identity) {
+    const userId = resolveBridgeUserId(claims, identity);
     const existing = await client.getUserInfo(userId);
     if (existing)
         return existing;
@@ -222,22 +219,7 @@ async function getOrProvisionUserFromClaims(client, claims, provisioningEnabled,
     return created;
 }
 /** Lists the caller's virtual keys (provisioning the user first if needed). */
-async function bridgeListKeys(client, claims, provisioningEnabled, provisioningDefaults, logger, userIdDomain) {
-    const user = await getOrProvisionUserFromClaims(client, claims, provisioningEnabled, provisioningDefaults, logger, userIdDomain);
+async function bridgeListKeys(client, claims, provisioningEnabled, provisioningDefaults, logger, identity) {
+    const user = await getOrProvisionUserFromClaims(client, claims, provisioningEnabled, provisioningDefaults, logger, identity);
     return client.listKeys(user.user_id);
 }
-/** Mints a new virtual key for the caller (provisioning the user first if needed). */
-async function bridgeGenerateKey(client, claims, provisioningEnabled, provisioningDefaults, logger, request, userIdDomain) {
-    const user = await getOrProvisionUserFromClaims(client, claims, provisioningEnabled, provisioningDefaults, logger, userIdDomain);
-    const enriched = {
-        ...request,
-        user_id: user.user_id,
-        metadata: {
-            ...(request.metadata ?? {}),
-            created_via: 'abby-cli',
-            created_by: user.user_id,
-            created_at_iso: new Date().toISOString(),
-        },
-    };
-    return client.generateKey(enriched);
-}

package/dist/client.d.ts

@@ -1,10 +1,4 @@
-import { LiteLLMConfig, UserInfo, VirtualKey, ModelInfo, UsageMetrics, TeamInfo, GenerateKeyRequest, GenerateKeyResponse, UpdateKeyRequest, DeleteKeyRequest, CreateUserRequest, CreateUserResponse, CreateTeamRequest, CreateTeamResponse, UpdateTeamRequest, AuditLogsParams, PaginatedAuditLogs, SpendLogEntry, SpendLogsParams } from './types';
-/**
- * LiteLLM versions differ on `request_tags`: an array of `k:v` strings in
- * current builds, but historically an object map. Normalise both to a flat
- * string array so callers can `includes('session:...')` uniformly.
- */
-export declare function normalizeRequestTags(tags: SpendLogEntry['request_tags']): string[];
+import { LiteLLMConfig, UserInfo, VirtualKey, ModelInfo, UsageMetrics, TeamInfo, GenerateKeyRequest, GenerateKeyResponse, UpdateKeyRequest, DeleteKeyRequest, CreateUserRequest, CreateUserResponse, CreateTeamRequest, CreateTeamResponse, UpdateTeamRequest, AuditLogsParams, PaginatedAuditLogs } from './types';
 /**
  * Typed error for failed upstream LiteLLM responses. Preserves the HTTP
  * status and the structured `param` (e.g. `key_alias`) from the upstream
@@ -23,6 +17,12 @@ export declare class LiteLLMClient {
     private timeout;
     constructor(config: LiteLLMConfig, timeout?: number);
     private request;
+    /**
+     * Normalizes a raw LiteLLM user response to the UserInfo contract.
+     * Handles both `/user/info` (with `user_info` wrapper) and `/user/list`
+     * response shapes, and converts team arrays to team_id strings.
+     */
+    private normalizeUserInfo;
     /**
      * Returns null when the user is not found in LiteLLM (404).
      * Throws on all other errors so callers know something went wrong.
@@ -126,8 +126,6 @@ export declare class LiteLLMClient {
     createTeam(payload: CreateTeamRequest): Promise<CreateTeamResponse>;
     updateTeam(payload: UpdateTeamRequest): Promise<unknown>;
     deleteTeam(teamId: string): Promise<unknown>;
-    blockTeam(teamId: string): Promise<unknown>;
-    unblockTeam(teamId: string): Promise<unknown>;
     /**
      * Adds a member to a team. LiteLLM's `/team/member_add` nests the member
      * under a `member` object; `role` is 'user' or 'admin' (we only ever send
@@ -166,17 +164,6 @@ export declare class LiteLLMClient {
         name?: string;
         url?: string;
     }>>;
-    /**
-     * Reads per-request spend logs from LiteLLM (`GET /spend/logs`), filtered
-     * by date range and optionally by key/user/team. Rows are normalised so
-     * `request_tags` is always a `string[]` (LiteLLM returns either an array
-     * or an object depending on version) — callers group by tag to attribute
-     * spend to a conversation or caller.
-     *
-     * This is the admin/DB-backed endpoint: it can return a large number of
-     * rows, so callers should keep the date window tight and cap `page_size`.
-     */
-    getSpendLogs(params: SpendLogsParams): Promise<SpendLogEntry[]>;
     private emptyUsage;
     /**
      * Transforms LiteLLM's SpendAnalyticsPaginatedResponse into the flatter

package/dist/client.js

@@ -1,20 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LiteLLMClient = exports.LiteLLMUpstreamError = void 0;
-exports.normalizeRequestTags = normalizeRequestTags;
 const DEFAULT_TIMEOUT = 30000;
-/**
- * LiteLLM versions differ on `request_tags`: an array of `k:v` strings in
- * current builds, but historically an object map. Normalise both to a flat
- * string array so callers can `includes('session:...')` uniformly.
- */
-function normalizeRequestTags(tags) {
-    if (!tags)
-        return [];
-    if (Array.isArray(tags))
-        return tags.filter((t) => typeof t === 'string');
-    return Object.entries(tags).map(([k, v]) => `${k}:${v}`);
-}
 /**
  * Typed error for failed upstream LiteLLM responses. Preserves the HTTP
  * status and the structured `param` (e.g. `key_alias`) from the upstream
@@ -87,6 +74,33 @@ class LiteLLMClient {
             clearTimeout(timeoutId);
         }
     }
+    /**
+     * Normalizes a raw LiteLLM user response to the UserInfo contract.
+     * Handles both `/user/info` (with `user_info` wrapper) and `/user/list`
+     * response shapes, and converts team arrays to team_id strings.
+     */
+    normalizeUserInfo(raw, fallbackUserId) {
+        const inner = raw?.user_info ?? {};
+        const teamIds = Array.isArray(raw?.teams)
+            ? raw.teams
+                .map((t) => (typeof t === 'string' ? t : t?.team_id))
+                .filter((t) => typeof t === 'string')
+            : [];
+        return {
+            user_id: raw?.user_id ?? inner.user_id ?? fallbackUserId ?? '',
+            user_email: inner.user_email ?? raw?.user_email,
+            email: inner.email ?? raw?.email,
+            teams: teamIds,
+            models: inner.models ?? raw?.models,
+            max_budget: inner.max_budget ?? raw?.max_budget,
+            budget_duration: inner.budget_duration ?? raw?.budget_duration,
+            budget_reset_at: inner.budget_reset_at ?? raw?.budget_reset_at,
+            spend: inner.spend ?? raw?.spend,
+            current_spend: inner.current_spend ?? raw?.current_spend,
+            soft_limit: inner.soft_limit ?? raw?.soft_limit,
+            hard_limit: inner.hard_limit ?? raw?.hard_limit,
+        };
+    }
     /**
      * Returns null when the user is not found in LiteLLM (404).
      * Throws on all other errors so callers know something went wrong.
@@ -100,26 +114,7 @@ class LiteLLMClient {
         const query = userId ? `?user_id=${encodeURIComponent(userId)}` : '';
         try {
             const raw = await this.request(`/user/info${query}`);
-            const inner = raw?.user_info ?? {};
-            const teamIds = Array.isArray(raw?.teams)
-                ? raw.teams
-                    .map((t) => (typeof t === 'string' ? t : t?.team_id))
-                    .filter((t) => typeof t === 'string')
-                : [];
-            return {
-                user_id: raw?.user_id ?? inner.user_id ?? userId ?? '',
-                user_email: inner.user_email ?? raw?.user_email,
-                email: inner.email ?? raw?.email,
-                teams: teamIds,
-                models: inner.models ?? raw?.models,
-                max_budget: inner.max_budget ?? raw?.max_budget,
-                budget_duration: inner.budget_duration ?? raw?.budget_duration,
-                budget_reset_at: inner.budget_reset_at ?? raw?.budget_reset_at,
-                spend: inner.spend ?? raw?.spend,
-                current_spend: inner.current_spend ?? raw?.current_spend,
-                soft_limit: inner.soft_limit ?? raw?.soft_limit,
-                hard_limit: inner.hard_limit ?? raw?.hard_limit,
-            };
+            return this.normalizeUserInfo(raw, userId);
         }
         catch (err) {
             if (err instanceof LiteLLMUpstreamError && err.status === 404)
@@ -149,27 +144,7 @@ class LiteLLMClient {
                 .toLowerCase() === email.toLowerCase());
             if (!found)
                 return null;
-            // Normalize to UserInfo shape (same as getUserInfo does)
-            const inner = found.user_info ?? {};
-            const teamIds = Array.isArray(found.teams)
-                ? found.teams
-                    .map((t) => (typeof t === 'string' ? t : t?.team_id))
-                    .filter((t) => typeof t === 'string')
-                : [];
-            return {
-                user_id: found.user_id ?? inner.user_id ?? '',
-                user_email: inner.user_email ?? found.user_email,
-                email: inner.email ?? found.email,
-                teams: teamIds,
-                models: inner.models ?? found.models,
-                max_budget: inner.max_budget ?? found.max_budget,
-                budget_duration: inner.budget_duration ?? found.budget_duration,
-                budget_reset_at: inner.budget_reset_at ?? found.budget_reset_at,
-                spend: inner.spend ?? found.spend,
-                current_spend: inner.current_spend ?? found.current_spend,
-                soft_limit: inner.soft_limit ?? found.soft_limit,
-                hard_limit: inner.hard_limit ?? found.hard_limit,
-            };
+            return this.normalizeUserInfo(found);
         }
         catch (err) {
             if (err instanceof LiteLLMUpstreamError && err.status === 404)
@@ -447,18 +422,6 @@ class LiteLLMClient {
             body: JSON.stringify({ team_ids: [teamId] }),
         });
     }
-    async blockTeam(teamId) {
-        return this.request('/team/block', {
-            method: 'POST',
-            body: JSON.stringify({ team_id: teamId }),
-        });
-    }
-    async unblockTeam(teamId) {
-        return this.request('/team/unblock', {
-            method: 'POST',
-            body: JSON.stringify({ team_id: teamId }),
-        });
-    }
     /**
      * Adds a member to a team. LiteLLM's `/team/member_add` nests the member
      * under a `member` object; `role` is 'user' or 'admin' (we only ever send
@@ -532,47 +495,6 @@ class LiteLLMClient {
         }))
             .filter(r => r.id);
     }
-    /**
-     * Reads per-request spend logs from LiteLLM (`GET /spend/logs`), filtered
-     * by date range and optionally by key/user/team. Rows are normalised so
-     * `request_tags` is always a `string[]` (LiteLLM returns either an array
-     * or an object depending on version) — callers group by tag to attribute
-     * spend to a conversation or caller.
-     *
-     * This is the admin/DB-backed endpoint: it can return a large number of
-     * rows, so callers should keep the date window tight and cap `page_size`.
-     */
-    async getSpendLogs(params) {
-        const query = new URLSearchParams({
-            start_date: params.start_date,
-            end_date: params.end_date,
-        });
-        if (params.api_key)
-            query.append('api_key', params.api_key);
-        if (params.user_id)
-            query.append('user_id', params.user_id);
-        if (params.team_id)
-            query.append('team_id', params.team_id);
-        if (params.page_size)
-            query.append('page_size', String(params.page_size));
-        const raw = await this.request(`/spend/logs?${query.toString()}`);
-        const rows = Array.isArray(raw) ? raw : raw?.data ?? [];
-        return rows.map(row => ({
-            request_id: row?.request_id,
-            startTime: row?.startTime ?? row?.start_time,
-            endTime: row?.endTime ?? row?.end_time,
-            spend: row?.spend ?? 0,
-            total_tokens: row?.total_tokens ?? 0,
-            prompt_tokens: row?.prompt_tokens ?? 0,
-            completion_tokens: row?.completion_tokens ?? 0,
-            model: row?.model,
-            api_key: row?.api_key,
-            user: row?.user,
-            team_id: row?.team_id,
-            request_tags: normalizeRequestTags(row?.request_tags),
-            metadata: row?.metadata,
-        }));
-    }
     emptyUsage() {
         return {
             total_spend: 0,

package/dist/errors.d.ts

@@ -25,11 +25,12 @@ export declare function isHttpishError(error: unknown): error is {
 export declare function errorMessage(error: unknown): string;
 /**
  * Sanitizes a message by:
+ * - Redacting Bearer tokens and sk- keys
  * - Stripping HTML tags
  * - Collapsing consecutive whitespace
  * - Truncating to 500 characters
  *
- * @param msg The raw message (may contain HTML, newlines, etc.)
+ * @param msg The raw message (may contain HTML, newlines, secrets, etc.)
  * @returns A safe, printable message
  */
 export declare function sanitizeUpstreamMessage(msg: string): string;

package/dist/errors.js

@@ -49,17 +49,20 @@ function errorMessage(error) {
 }
 /**
  * Sanitizes a message by:
+ * - Redacting Bearer tokens and sk- keys
  * - Stripping HTML tags
  * - Collapsing consecutive whitespace
  * - Truncating to 500 characters
  *
- * @param msg The raw message (may contain HTML, newlines, etc.)
+ * @param msg The raw message (may contain HTML, newlines, secrets, etc.)
  * @returns A safe, printable message
  */
 function sanitizeUpstreamMessage(msg) {
     if (!msg || typeof msg !== 'string')
         return '';
     return msg
+        .replace(/Bearer\s+[A-Za-z0-9._\-+/=]+/g, 'Bearer [redacted]') // Redact Bearer tokens
+        .replace(/sk-[A-Za-z0-9_\-]{8,}/g, 'sk-[redacted]') // Redact sk-* keys
         .replace(HTML_TAG_PATTERN, '') // Strip HTML tags and entities
         .replace(/\s+/g, ' ') // Collapse whitespace
         .trim()