@acarmisc/backstage-plugin-litellm-backend 0.26.1 → 0.27.0

package/dist/routes/teamUsage.js

@@ -72,75 +72,95 @@ function registerTeamUsageRoutes(router, ctx) {
             (0, errors_1.sendError)(res, error, logger, 'fetch team usage');
         }
     });
-    // Per-member breakdown of a team's usage. Opt-in (404 when disabled) and
+    // Shared gate of the per-member routes. Opt-in (404 when disabled) and
     // fail-closed: the caller must be a manager of the team (owning_group), or
     // a member who holds one of memberBreakdown.viewerRoles in the team or is
-    // granted litellm.team.usage.read.
-    router.get('/teams/:teamId/usage/members', requireUser, async (req, res) => {
+    // granted litellm.team.usage.read. Scoped to the one team in the path, so
+    // leading a team never reveals another. Replies and returns null on refusal.
+    async function authorizeMemberView(req, res) {
         const cfg = ctx.memberBreakdownCfg;
         if (!cfg.enabled) {
             res.status(404).json({ error: 'Not found' });
-            return;
+            return null;
+        }
+        const { teamId } = req.params;
+        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 null;
         }
+        const tokenEntityRef = res.locals.tokenEntityRef;
+        const userInfo = await (0, withUser_1.getProvisionedUser)(ctx, res);
+        const callerId = res.locals.userId;
+        const isMember = userInfo?.teams?.includes(teamId) ?? false;
+        let team;
         try {
-            const { teamId } = req.params;
-            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 userInfo = await (0, withUser_1.getProvisionedUser)(ctx, res);
-            const callerId = res.locals.userId;
-            const isMember = userInfo?.teams?.includes(teamId) ?? false;
-            let team;
-            try {
-                team = await (0, teamFetch_1.withTeamFetchRetry)(() => client.getTeamInfo(teamId));
-            }
-            catch (err) {
-                if (err instanceof client_1.LiteLLMUpstreamError && err.status === 404) {
-                    res.status(404).json({ error: 'Team not found' });
-                    return;
-                }
-                throw err;
-            }
-            const owningGroup = typeof team.metadata?.owning_group === 'string' ? team.metadata.owning_group : undefined;
-            const isManager = ctx.teamMgmtEnabled &&
-                !!owningGroup &&
-                (await (0, provisioning_1.isUserMemberOfGroup)(tokenEntityRef, owningGroup, catalogClient, auth, logger));
-            if (!isMember && !isManager) {
+            team = await (0, teamFetch_1.withTeamFetchRetry)(() => client.getTeamInfo(teamId));
+        }
+        catch (err) {
+            if (err instanceof client_1.LiteLLMUpstreamError && err.status === 404) {
                 res.status(404).json({ error: 'Team not found' });
-                return;
+                return null;
             }
-            const role = team.members_with_roles?.find(m => m.user_id === callerId)?.role;
-            const viaRole = isMember && !!role && cfg.viewerRoles.includes(role);
-            const allowed = isManager ||
-                viaRole ||
-                (isMember &&
-                    cfg.permissionEnabled &&
-                    (await ctx.assertPermission(req, backstage_plugin_litellm_common_1.litellmTeamUsageReadPermission)));
-            if (!allowed) {
-                res.status(403).json({
-                    error: 'Access denied: viewing per-member usage needs a team role or permission',
-                });
+            throw err;
+        }
+        const owningGroup = typeof team.metadata?.owning_group === 'string' ? team.metadata.owning_group : undefined;
+        const isManager = ctx.teamMgmtEnabled &&
+            !!owningGroup &&
+            (await (0, provisioning_1.isUserMemberOfGroup)(tokenEntityRef, owningGroup, catalogClient, auth, logger));
+        if (!isMember && !isManager) {
+            res.status(404).json({ error: 'Team not found' });
+            return null;
+        }
+        const role = team.members_with_roles?.find(m => m.user_id === callerId)?.role;
+        const viaRole = isMember && !!role && cfg.viewerRoles.includes(role);
+        const allowed = isManager ||
+            viaRole ||
+            (isMember &&
+                cfg.permissionEnabled &&
+                (await ctx.assertPermission(req, backstage_plugin_litellm_common_1.litellmTeamUsageReadPermission)));
+        if (!allowed) {
+            res.status(403).json({
+                error: 'Access denied: viewing per-member usage needs a team role or permission',
+            });
+            return null;
+        }
+        let via = 'permission';
+        if (isManager)
+            via = 'manager';
+        else if (viaRole)
+            via = 'teamRole';
+        return {
+            teamId,
+            team,
+            startDate: start_date,
+            endDate: end_date,
+            isManager,
+            via,
+        };
+    }
+    const hideFor = (isManager) => isManager
+        ? teamBudgetVisibility.hideTeamBudgetForManagers
+        : teamBudgetVisibility.hideTeamBudgetForMembers;
+    // Per-member breakdown of a team's usage.
+    router.get('/teams/:teamId/usage/members', requireUser, async (req, res) => {
+        try {
+            const gate = await authorizeMemberView(req, res);
+            if (!gate)
                 return;
-            }
+            const { teamId, team, startDate, endDate, isManager, via } = gate;
             const [usage, keys] = await Promise.all([
-                client.getTeamUsage(teamId, start_date, end_date),
+                client.getTeamUsage(teamId, startDate, endDate),
                 client.listTeamKeys(teamId),
             ]);
             const profiles = await lookupProfiles((0, teamMemberUsage_1.memberEmails)(team, keys));
             const breakdown = (0, teamMemberUsage_1.buildTeamMemberUsage)(teamId, usage, keys, team, profiles);
-            let via = 'permission';
-            if (isManager)
-                via = 'manager';
-            else if (viaRole)
-                via = 'teamRole';
-            logger.info('team.usage.members.read', { actor: tokenEntityRef, teamId, via });
-            const hide = isManager
-                ? teamBudgetVisibility.hideTeamBudgetForManagers
-                : teamBudgetVisibility.hideTeamBudgetForMembers;
-            res.json(hide ? (0, teamMemberUsage_1.redactTeamMemberUsage)(breakdown) : breakdown);
+            logger.info('team.usage.members.read', {
+                actor: res.locals.tokenEntityRef,
+                teamId,
+                via,
+            });
+            res.json(hideFor(isManager) ? (0, teamMemberUsage_1.redactTeamMemberUsage)(breakdown) : breakdown);
         }
         catch (error) {
             if (error instanceof provisioning_1.ProvisioningError) {
@@ -150,6 +170,36 @@ function registerTeamUsageRoutes(router, ctx) {
             (0, errors_1.sendError)(res, error, logger, 'fetch team member usage');
         }
     });
+    // The team's keys (alias, owner, status, budget) with per-key usage, so a
+    // team lead sees the members' keys and their consumption. Same gate and
+    // redaction as the per-member breakdown.
+    router.get('/teams/:teamId/usage/keys', requireUser, async (req, res) => {
+        try {
+            const gate = await authorizeMemberView(req, res);
+            if (!gate)
+                return;
+            const { teamId, team, startDate, endDate, isManager, via } = gate;
+            const [usage, keys] = await Promise.all([
+                client.getTeamUsage(teamId, startDate, endDate),
+                client.listTeamKeys(teamId),
+            ]);
+            const profiles = await lookupProfiles((0, teamMemberUsage_1.memberEmails)(team, keys));
+            const keyUsage = (0, teamMemberUsage_1.buildTeamKeyUsage)(teamId, usage, keys, team, profiles);
+            logger.info('team.usage.keys.read', {
+                actor: res.locals.tokenEntityRef,
+                teamId,
+                via,
+            });
+            res.json(hideFor(isManager) ? (0, teamMemberUsage_1.redactTeamKeyUsage)(keyUsage) : keyUsage);
+        }
+        catch (error) {
+            if (error instanceof provisioning_1.ProvisioningError) {
+                res.status(error.status).json(error.body);
+                return;
+            }
+            (0, errors_1.sendError)(res, error, logger, 'fetch team key usage');
+        }
+    });
     // Display names from catalog User entities with these emails. Best effort:
     // a catalog failure only drops the names.
     async function lookupProfiles(emails) {

package/dist/teamMemberUsage.d.ts

@@ -1,5 +1,5 @@
 import { Config } from '@backstage/config';
-import { TeamInfo, TeamMemberUsage, UsageMetrics, VirtualKey } from './types';
+import { TeamInfo, TeamKeyUsage, TeamMemberUsage, UsageMetrics, VirtualKey } from './types';
 /** `litellm.teamUsage.memberBreakdown`: who may see a team's per-member usage. */
 export interface MemberBreakdownConfig {
     /** Off by default: the route returns 404 and the UI hides the table. */
@@ -32,3 +32,11 @@ export declare function buildTeamMemberUsage(teamId: string, usage: UsageMetrics
  * way to compare members. Tokens and requests are kept.
  */
 export declare function redactTeamMemberUsage(usage: TeamMemberUsage): TeamMemberUsage;
+/**
+ * Lists a team's keys with their usage over the period, credited by key hash
+ * from the team's daily activity. Only fields safe to show a team lead are
+ * copied: no secret, hash or metadata. Keys without activity get zero rows.
+ */
+export declare function buildTeamKeyUsage(teamId: string, usage: UsageMetrics, keys: VirtualKey[], team: TeamInfo, profiles?: MemberProfiles): TeamKeyUsage;
+/** Hides dollar amounts (period spend and key budgets); tokens and requests stay. */
+export declare function redactTeamKeyUsage(usage: TeamKeyUsage): TeamKeyUsage;

package/dist/teamMemberUsage.js

@@ -4,6 +4,8 @@ exports.readMemberBreakdownConfig = readMemberBreakdownConfig;
 exports.memberEmails = memberEmails;
 exports.buildTeamMemberUsage = buildTeamMemberUsage;
 exports.redactTeamMemberUsage = redactTeamMemberUsage;
+exports.buildTeamKeyUsage = buildTeamKeyUsage;
+exports.redactTeamKeyUsage = redactTeamKeyUsage;
 function readMemberBreakdownConfig(config) {
     return {
         enabled: config.getOptionalBoolean('litellm.teamUsage.memberBreakdown.enabled') ?? false,
@@ -112,3 +114,51 @@ function redactTeamMemberUsage(usage) {
         members: usage.members.map(m => ({ ...m, spend: 0 })),
     };
 }
+/**
+ * Lists a team's keys with their usage over the period, credited by key hash
+ * from the team's daily activity. Only fields safe to show a team lead are
+ * copied: no secret, hash or metadata. Keys without activity get zero rows.
+ */
+function buildTeamKeyUsage(teamId, usage, keys, team, profiles = new Map()) {
+    const emailById = new Map();
+    for (const m of team.members_with_roles ?? []) {
+        if (m.user_id && m.user_email)
+            emailById.set(m.user_id, m.user_email);
+    }
+    const rows = keys.map(k => {
+        const u = (k.token && usage.usage_by_key?.[k.token]) || undefined;
+        const userId = k.user_id ?? null;
+        const email = (userId && emailById.get(userId)) || (userId?.includes('@') ? userId : undefined);
+        const displayName = email && profiles.get(email.toLowerCase())?.displayName;
+        return {
+            key: k.key,
+            ...(k.key_alias && { key_alias: k.key_alias }),
+            user_id: userId,
+            ...(email && { user_email: email }),
+            ...(displayName && { display_name: displayName }),
+            created_at: k.created_at,
+            ...(k.expires_at && { expires_at: k.expires_at }),
+            blocked: k.blocked === true,
+            ...(k.max_budget !== undefined && { max_budget: k.max_budget }),
+            spend: u?.total_spend ?? 0,
+            prompt_tokens: u?.prompt_tokens ?? 0,
+            completion_tokens: u?.completion_tokens ?? 0,
+            total_tokens: u?.total_tokens ?? 0,
+            api_requests: u?.api_requests ?? 0,
+            successful_requests: u?.successful_requests ?? 0,
+            failed_requests: u?.failed_requests ?? 0,
+        };
+    });
+    rows.sort((a, b) => b.spend - a.spend ||
+        b.total_tokens - a.total_tokens ||
+        a.key.localeCompare(b.key));
+    return { team_id: teamId, keys: rows };
+}
+/** Hides dollar amounts (period spend and key budgets); tokens and requests stay. */
+function redactTeamKeyUsage(usage) {
+    return {
+        ...usage,
+        budget_hidden: true,
+        keys: usage.keys.map(({ max_budget: _hidden, ...k }) => ({ ...k, spend: 0 })),
+    };
+}

package/dist/types.cjs.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/types.ts"],
-  "sourcesContent": ["// Re-export common types for backward compatibility\nexport {\n  type UserInfo,\n  type TeamMember,\n  type TeamObjectPermission,\n  type TeamInfo,\n  type CreateTeamResponse,\n  type VirtualKey,\n  type ModelInfo,\n  type UsageModelBreakdown,\n  type UsageKeyBreakdown,\n  type UsageDailyPoint,\n  type UsageDailyModelPoint,\n  type UsageMetrics,\n  type TeamMemberUsage,\n  type TeamMemberUsageRow,\n  type GenerateKeyRequest,\n  type UpdateKeyRequest,\n  type GenerateKeyResponse,\n  type AuditLogEntry,\n  type PaginatedAuditLogs,\n  type SpendLogEntry,\n  type SpendLogsParams,\n  type PaginatedSpendLogs,\n  type QualityByModel,\n  type QualityScore,\n  type QualitySummary,\n  type QualityResponse,\n} from '@acarmisc/backstage-plugin-litellm-common';\n\nexport interface CreateTeamRequest {\n  team_alias: string;\n  models?: string[];\n  max_budget?: number;\n  budget_duration?: string;\n  tpm_limit?: number;\n  rpm_limit?: number;\n  metadata?: Record<string, unknown>;\n  object_permission?: {\n    vector_stores?: string[];\n    mcp_servers?: string[];\n    mcp_access_groups?: string[];\n  };\n}\n\nexport interface UpdateTeamRequest extends Partial<CreateTeamRequest> {\n  team_id: string;\n  blocked?: boolean;\n}\n\n/**\n * Shape of a single entry inside LiteLLM's `/user/info` `keys` array.\n * Differs from VirtualKey: uses `expires` (not `expires_at`), exposes\n * both a hashed `token` and a masked `key_name`, and fields are nullable\n * rather than optional.\n */\nexport interface LiteLLMUserKey {\n  token: string;\n  key_name?: string;\n  key_alias?: string | null;\n  spend?: number;\n  expires?: string | null;\n  models?: string[];\n  tpm_limit?: number | null;\n  rpm_limit?: number | null;\n  max_budget?: number | null;\n  budget_duration?: string | null;\n  user_id?: string | null;\n  team_id?: string | null;\n  created_at: string;\n  blocked?: boolean | null;\n  /** Arbitrary metadata stored on the key record. */\n  metadata?: Record<string, unknown> | null;\n}\n\nexport interface DeleteKeyRequest {\n  keys: string[];\n}\n\nexport interface LiteLLMConfig {\n  baseUrl: string;\n  masterKey: string;\n}\n\nexport interface ProvisioningDefaults {\n  maxBudget: number;\n  budgetDuration: string;\n  models: string[];\n  teams: string[];\n  tpmLimit?: number;\n  rpmLimit?: number;\n  /**\n   * LiteLLM user role applied on /user/new. Defaults to \"internal_user\"\n   * which grants self-service Create/Delete/View on the user's own keys.\n   * Valid values: proxy_admin, proxy_admin_viewer, internal_user,\n   * internal_user_viewer, team.\n   */\n  userRole?: string;\n  metadata: Record<string, string>;\n}\n\nexport interface RoleConfig {\n  group: string;\n  maxBudget?: number;\n  budgetDuration?: string;\n  models?: string[];\n  teams?: string[];\n  tpmLimit?: number;\n  rpmLimit?: number;\n  userRole?: string;\n  metadata?: Record<string, string>;\n}\n\nexport interface CreateUserRequest {\n  user_id: string;\n  user_email?: string;\n  user_alias?: string;\n  user_role?: string;\n  max_budget?: number;\n  budget_duration?: string;\n  models?: string[];\n  teams?: string[];\n  tpm_limit?: number;\n  rpm_limit?: number;\n  metadata?: Record<string, string>;\n  auto_create_key?: boolean;\n}\n\nexport interface CreateUserResponse {\n  user_id: string;\n  user_email?: string;\n  max_budget?: number;\n  models?: string[];\n  teams?: string[];\n}\n\n\nexport interface AuditLogsParams {\n  page?: number;\n  page_size?: number;\n  start_date?: string;\n  end_date?: string;\n  action?: string;\n  table_name?: string;\n  changed_by?: string;\n  sort_by?: string;\n  sort_order?: 'asc' | 'desc';\n}\n"],
+  "sourcesContent": ["// Re-export common types for backward compatibility\nexport {\n  type UserInfo,\n  type TeamMember,\n  type TeamObjectPermission,\n  type TeamInfo,\n  type CreateTeamResponse,\n  type VirtualKey,\n  type ModelInfo,\n  type UsageModelBreakdown,\n  type UsageKeyBreakdown,\n  type UsageDailyPoint,\n  type UsageDailyModelPoint,\n  type UsageMetrics,\n  type TeamMemberUsage,\n  type TeamMemberUsageRow,\n  type TeamKeyUsage,\n  type TeamKeyUsageRow,\n  type GenerateKeyRequest,\n  type UpdateKeyRequest,\n  type GenerateKeyResponse,\n  type AuditLogEntry,\n  type PaginatedAuditLogs,\n  type SpendLogEntry,\n  type SpendLogsParams,\n  type PaginatedSpendLogs,\n  type QualityByModel,\n  type QualityScore,\n  type QualitySummary,\n  type QualityResponse,\n} from '@acarmisc/backstage-plugin-litellm-common';\n\nexport interface CreateTeamRequest {\n  team_alias: string;\n  models?: string[];\n  max_budget?: number;\n  budget_duration?: string;\n  tpm_limit?: number;\n  rpm_limit?: number;\n  metadata?: Record<string, unknown>;\n  object_permission?: {\n    vector_stores?: string[];\n    mcp_servers?: string[];\n    mcp_access_groups?: string[];\n  };\n}\n\nexport interface UpdateTeamRequest extends Partial<CreateTeamRequest> {\n  team_id: string;\n  blocked?: boolean;\n}\n\n/**\n * Shape of a single entry inside LiteLLM's `/user/info` `keys` array.\n * Differs from VirtualKey: uses `expires` (not `expires_at`), exposes\n * both a hashed `token` and a masked `key_name`, and fields are nullable\n * rather than optional.\n */\nexport interface LiteLLMUserKey {\n  token: string;\n  key_name?: string;\n  key_alias?: string | null;\n  spend?: number;\n  expires?: string | null;\n  models?: string[];\n  tpm_limit?: number | null;\n  rpm_limit?: number | null;\n  max_budget?: number | null;\n  budget_duration?: string | null;\n  user_id?: string | null;\n  team_id?: string | null;\n  created_at: string;\n  blocked?: boolean | null;\n  /** Arbitrary metadata stored on the key record. */\n  metadata?: Record<string, unknown> | null;\n}\n\nexport interface DeleteKeyRequest {\n  keys: string[];\n}\n\nexport interface LiteLLMConfig {\n  baseUrl: string;\n  masterKey: string;\n}\n\nexport interface ProvisioningDefaults {\n  maxBudget: number;\n  budgetDuration: string;\n  models: string[];\n  teams: string[];\n  tpmLimit?: number;\n  rpmLimit?: number;\n  /**\n   * LiteLLM user role applied on /user/new. Defaults to \"internal_user\"\n   * which grants self-service Create/Delete/View on the user's own keys.\n   * Valid values: proxy_admin, proxy_admin_viewer, internal_user,\n   * internal_user_viewer, team.\n   */\n  userRole?: string;\n  metadata: Record<string, string>;\n}\n\nexport interface RoleConfig {\n  group: string;\n  maxBudget?: number;\n  budgetDuration?: string;\n  models?: string[];\n  teams?: string[];\n  tpmLimit?: number;\n  rpmLimit?: number;\n  userRole?: string;\n  metadata?: Record<string, string>;\n}\n\nexport interface CreateUserRequest {\n  user_id: string;\n  user_email?: string;\n  user_alias?: string;\n  user_role?: string;\n  max_budget?: number;\n  budget_duration?: string;\n  models?: string[];\n  teams?: string[];\n  tpm_limit?: number;\n  rpm_limit?: number;\n  metadata?: Record<string, string>;\n  auto_create_key?: boolean;\n}\n\nexport interface CreateUserResponse {\n  user_id: string;\n  user_email?: string;\n  max_budget?: number;\n  models?: string[];\n  teams?: string[];\n}\n\n\nexport interface AuditLogsParams {\n  page?: number;\n  page_size?: number;\n  start_date?: string;\n  end_date?: string;\n  action?: string;\n  table_name?: string;\n  changed_by?: string;\n  sort_by?: string;\n  sort_order?: 'asc' | 'desc';\n}\n"],
   "mappings": ";;;;;;;;;;;;;;;;AAAA;AAAA;",
   "names": []
 }

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-export { type UserInfo, type TeamMember, type TeamObjectPermission, type TeamInfo, type CreateTeamResponse, type VirtualKey, type ModelInfo, type UsageModelBreakdown, type UsageKeyBreakdown, type UsageDailyPoint, type UsageDailyModelPoint, type UsageMetrics, type TeamMemberUsage, type TeamMemberUsageRow, type GenerateKeyRequest, type UpdateKeyRequest, type GenerateKeyResponse, type AuditLogEntry, type PaginatedAuditLogs, type SpendLogEntry, type SpendLogsParams, type PaginatedSpendLogs, type QualityByModel, type QualityScore, type QualitySummary, type QualityResponse, } from '@acarmisc/backstage-plugin-litellm-common';
+export { type UserInfo, type TeamMember, type TeamObjectPermission, type TeamInfo, type CreateTeamResponse, type VirtualKey, type ModelInfo, type UsageModelBreakdown, type UsageKeyBreakdown, type UsageDailyPoint, type UsageDailyModelPoint, type UsageMetrics, type TeamMemberUsage, type TeamMemberUsageRow, type TeamKeyUsage, type TeamKeyUsageRow, type GenerateKeyRequest, type UpdateKeyRequest, type GenerateKeyResponse, type AuditLogEntry, type PaginatedAuditLogs, type SpendLogEntry, type SpendLogsParams, type PaginatedSpendLogs, type QualityByModel, type QualityScore, type QualitySummary, type QualityResponse, } from '@acarmisc/backstage-plugin-litellm-common';
 export interface CreateTeamRequest {
     team_alias: string;
     models?: string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acarmisc/backstage-plugin-litellm-backend",
-  "version": "0.26.1",
+  "version": "0.27.0",
   "description": "The Backstage backend plugin for LiteLLM governance",
   "backstage": {
     "role": "backend-plugin",
@@ -35,7 +35,7 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@acarmisc/backstage-plugin-litellm-common": "0.5.0",
+    "@acarmisc/backstage-plugin-litellm-common": "0.6.0",
     "@backstage/backend-plugin-api": "^1.9.1",
     "@backstage/catalog-client": "^1.9.0",
     "@backstage/config": "^1.3.0",