@acarmisc/backstage-plugin-litellm-backend 0.18.0 → 0.20.0

package/dist/index.d.ts

@@ -2,13 +2,13 @@ export { litellmPlugin } from './plugin';
 export { litellmPlugin as default } from './plugin';
 export { createRouter } from './router';
 export * from './types';
-export { LiteLLMClient, normalizeRequestTags } from './client';
+export { LiteLLMClient } from './client';
 export { resolveUserId, resolveUserProfile, toLiteLLMUserId, getOrProvisionUser, provisionUser, readProvisioningDefaults, readRoleConfigs, applyRoleOverrides, resolveUserRole, ProvisioningError, } from './provisioning';
 export type { BackstageUserProfile } from './provisioning';
 export { readTeamAdminConfig, isTeamManagementEnabled, assertTeamAdmin, validateTeamWriteInput, validateTeamPatchInput, } from './teamAdmin';
 export type { TeamAdminConfig, TeamAdminCheck, TeamWriteInput, TeamWriteValidation, TeamPatchValidation } from './teamAdmin';
 export { readTeamBudgetVisibility, redactTeamBudget, redactTeamUsage, teamBudgetStatusFor, } from './teamBudgetVisibility';
 export type { TeamBudgetVisibility, TeamBudgetStatus } from './teamBudgetVisibility';
-export { KeycloakJWTVerifier, newDefaultVerifier, readBridgeConfig, resolveBridgeUserId, getOrProvisionUserFromClaims, bridgeListKeys, bridgeGenerateKey, } from './bridge';
+export { KeycloakJWTVerifier, newDefaultVerifier, readBridgeConfig, resolveBridgeUserId, getOrProvisionUserFromClaims, bridgeListKeys, } from './bridge';
 export type { BridgeClaims, TokenVerifier, BridgeConfig, KeycloakJWTVerifierOptions, } from './bridge';
 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.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;
+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.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.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");
@@ -24,7 +24,6 @@ Object.defineProperty(exports, "createRouter", { enumerable: true, get: function
 __exportStar(require("./types"), exports);
 var client_1 = require("./client");
 Object.defineProperty(exports, "LiteLLMClient", { enumerable: true, get: function () { return client_1.LiteLLMClient; } });
-Object.defineProperty(exports, "normalizeRequestTags", { enumerable: true, get: function () { return client_1.normalizeRequestTags; } });
 var provisioning_1 = require("./provisioning");
 Object.defineProperty(exports, "resolveUserId", { enumerable: true, get: function () { return provisioning_1.resolveUserId; } });
 Object.defineProperty(exports, "resolveUserProfile", { enumerable: true, get: function () { return provisioning_1.resolveUserProfile; } });
@@ -54,7 +53,6 @@ Object.defineProperty(exports, "readBridgeConfig", { enumerable: true, get: func
 Object.defineProperty(exports, "resolveBridgeUserId", { enumerable: true, get: function () { return bridge_1.resolveBridgeUserId; } });
 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 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; } });

package/dist/openapi.js

@@ -111,6 +111,7 @@ exports.openApiSpec = {
                                     team_id: { type: 'string' },
                                     duration: { type: 'string' },
                                     max_budget: { type: 'number', nullable: true, description: 'Positive number caps spend; null = unlimited' },
+                                    budget_duration: { type: 'string', description: 'How often max_budget resets (e.g. "30d", "1mo"); one of litellm.keys.allowedBudgetDurations' },
                                     tpm_limit: { type: 'number' },
                                     rpm_limit: { type: 'number' },
                                 } } } },
@@ -210,6 +211,27 @@ exports.openApiSpec = {
                 responses: { '200': { description: 'Team usage' }, '400': { description: 'Missing date range' } },
             },
         },
+        '/teams/{teamId}/usage/members': {
+            get: {
+                tags: ['Teams'],
+                summary: 'Per-member usage breakdown for a team',
+                description: 'Needs litellm.teamUsage.memberBreakdown.enabled. Allowed for team ' +
+                    'managers, members holding one of memberBreakdown.viewerRoles, and ' +
+                    'members granted litellm.team.usage.read. Spend is zeroed (with ' +
+                    'budget_hidden: true) under team budget hiding; spend_share_pct remains.',
+                parameters: [
+                    { name: 'teamId', in: 'path', required: true, schema: { type: 'string' } },
+                    { name: 'start_date', in: 'query', required: true, schema: { type: 'string' } },
+                    { name: 'end_date', in: 'query', required: true, schema: { type: 'string' } },
+                ],
+                responses: {
+                    '200': { description: 'One row per member, sorted by spend' },
+                    '400': { description: 'Missing date range' },
+                    '403': { description: 'Caller may see the team but not its member breakdown' },
+                    '404': { description: 'Feature disabled, or team not found / not visible to the caller' },
+                },
+            },
+        },
         '/usage': {
             get: {
                 tags: ['Usage'],

package/dist/provisioning.d.ts

@@ -49,11 +49,13 @@ export declare function readProvisioningDefaults(config: Config): {
  * Extracts the authenticated Backstage user identity from the request token.
  * Returns the userEntityRef (e.g. "user:default/john.doe") or undefined when
  * the request carries no user credential (service-to-service calls).
+ * Only accepts headers starting with 'Bearer ' (case-sensitive as Backstage sends it).
  */
 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().
+ * Only accepts headers starting with 'Bearer ' (case-sensitive as Backstage sends it).
  */
 export declare function resolveCredentials(req: Request, auth: AuthService): Promise<BackstageCredentials | undefined>;
 /**
@@ -86,7 +88,20 @@ export declare class ProvisioningError extends Error {
     constructor(message: string, hint: string, provisioning: boolean, status?: number);
 }
 /**
- * Ensures the LiteLLM user exists, returning its UserInfo.
+ * The LiteLLM user id to act on for a computed id: the id of the user adopted
+ * by email for it, if any, else the computed id itself. Accurate once
+ * getOrProvisionUser or findLiteLLMUser has run for that id.
+ */
+export declare function effectiveUserId(userId: string): string;
+/**
+ * Finds the LiteLLM user for a Backstage identity without creating it: by
+ * the computed id first, then by the catalog email (see adoptUserByEmail).
+ * Returns null when neither matches.
+ */
+export declare function findLiteLLMUser(client: LiteLLMClient, tokenEntityRef: string | undefined, userId: string, catalogClient: CatalogClient, auth: AuthService, logger: LoggerService): Promise<UserInfo | null>;
+/**
+ * Ensures the LiteLLM user exists, returning its UserInfo. The user may have
+ * been found by email under a different id: see effectiveUserId.
  * When the user is missing and provisioning is enabled, attempts to create it.
  * When provisioning is disabled, throws a ProvisioningError with a clear message.
  */

package/dist/provisioning.js

@@ -9,10 +9,13 @@ exports.resolveUserId = resolveUserId;
 exports.resolveCredentials = resolveCredentials;
 exports.resolveUserProfile = resolveUserProfile;
 exports.provisionUser = provisionUser;
+exports.effectiveUserId = effectiveUserId;
+exports.findLiteLLMUser = findLiteLLMUser;
 exports.getOrProvisionUser = getOrProvisionUser;
 exports.isUserMemberOfGroup = isUserMemberOfGroup;
 exports.resolveUserRole = resolveUserRole;
 const client_1 = require("./client");
+const errors_1 = require("./errors");
 /**
  * Converts a Backstage user entity ref to a LiteLLM user_id.
  *
@@ -107,11 +110,13 @@ function readProvisioningDefaults(config) {
  * Extracts the authenticated Backstage user identity from the request token.
  * Returns the userEntityRef (e.g. "user:default/john.doe") or undefined when
  * the request carries no user credential (service-to-service calls).
+ * Only accepts headers starting with 'Bearer ' (case-sensitive as Backstage sends it).
  */
 async function resolveUserId(req, auth) {
-    const rawToken = req.headers.authorization?.slice(7);
-    if (!rawToken)
+    const authHeader = req.headers.authorization ?? '';
+    if (!authHeader.startsWith('Bearer '))
         return undefined;
+    const rawToken = authHeader.slice(7);
     try {
         const credentials = await auth.authenticate(rawToken);
         const principal = credentials.principal;
@@ -120,18 +125,20 @@ async function resolveUserId(req, auth) {
         }
     }
     catch {
-        // invalid or service token — caller gets query-param fallback
+        // invalid or service token
     }
     return undefined;
 }
 /**
  * Like resolveUserId, but returns the raw BackstageCredentials object
  * (rather than just the entity ref) for passing into PermissionsService.authorize().
+ * Only accepts headers starting with 'Bearer ' (case-sensitive as Backstage sends it).
  */
 async function resolveCredentials(req, auth) {
-    const rawToken = req.headers.authorization?.slice(7);
-    if (!rawToken)
+    const authHeader = req.headers.authorization ?? '';
+    if (!authHeader.startsWith('Bearer '))
         return undefined;
+    const rawToken = authHeader.slice(7);
     try {
         return await auth.authenticate(rawToken);
     }
@@ -236,20 +243,6 @@ async function provisionUser(client, userId, defaults, profile, backstageEntity,
  * requests for a re-deleted user can still trigger fresh provisioning.
  */
 const provisioningInFlight = new Map();
-/**
- * Strips any echoed Authorization bearer token from upstream LiteLLM error
- * messages before they're shipped back to the browser. LiteLLM normally does
- * not echo the master key, but defense in depth: never let a `Bearer …`
- * substring travel out in a response body.
- */
-function sanitizeUpstreamMessage(message) {
-    if (!message)
-        return 'unknown error';
-    return message
-        .replace(/Bearer\s+[A-Za-z0-9._\-+/=]+/g, 'Bearer [redacted]')
-        .replace(/sk-[A-Za-z0-9_\-]{8,}/g, 'sk-[redacted]')
-        .slice(0, 500);
-}
 class ProvisioningError extends Error {
     constructor(message, hint, provisioning, status = 404) {
         super(message);
@@ -259,7 +252,68 @@ class ProvisioningError extends Error {
 }
 exports.ProvisioningError = ProvisioningError;
 /**
- * Ensures the LiteLLM user exists, returning its UserInfo.
+ * Computed user id → id of an existing LiteLLM user adopted by email. Saves
+ * the catalog and `/user/list` round-trips on later requests; an entry is
+ * dropped when the adopted user disappears.
+ */
+const adoptedUserIds = new Map();
+/**
+ * The LiteLLM user id to act on for a computed id: the id of the user adopted
+ * by email for it, if any, else the computed id itself. Accurate once
+ * getOrProvisionUser or findLiteLLMUser has run for that id.
+ */
+function effectiveUserId(userId) {
+    return adoptedUserIds.get(userId) ?? userId;
+}
+/**
+ * Looks the user up by the computed id, or by an id previously adopted for it.
+ */
+async function getUserByIdOrAdopted(client, userId) {
+    const adopted = adoptedUserIds.get(userId);
+    if (adopted) {
+        const info = await client.getUserInfo(adopted);
+        if (info)
+            return info;
+        adoptedUserIds.delete(userId);
+    }
+    return client.getUserInfo(userId);
+}
+/**
+ * Finds an existing LiteLLM user with the given email and remembers it for
+ * the computed id. Users created outside Backstage (or before
+ * `userIdDomain` was set) often have the email as their id; LiteLLM then
+ * refuses a second user with the same email, so the record must be adopted
+ * rather than created. `getUserByEmail` only returns exact email matches.
+ */
+async function adoptUserByEmail(client, userId, email, logger) {
+    if (!email)
+        return null;
+    const byEmail = await client.getUserByEmail(email);
+    if (!byEmail?.user_id)
+        return null;
+    if (byEmail.user_id !== userId) {
+        logger.info(`Found existing LiteLLM user ${byEmail.user_id} by email ${email}, reusing for ${userId}`);
+        adoptedUserIds.set(userId, byEmail.user_id);
+    }
+    return byEmail;
+}
+/**
+ * Finds the LiteLLM user for a Backstage identity without creating it: by
+ * the computed id first, then by the catalog email (see adoptUserByEmail).
+ * Returns null when neither matches.
+ */
+async function findLiteLLMUser(client, tokenEntityRef, userId, catalogClient, auth, logger) {
+    const existing = await getUserByIdOrAdopted(client, userId);
+    if (existing)
+        return existing;
+    if (!tokenEntityRef)
+        return null;
+    const profile = await resolveUserProfile(tokenEntityRef, catalogClient, auth, logger);
+    return adoptUserByEmail(client, userId, profile.email, logger);
+}
+/**
+ * Ensures the LiteLLM user exists, returning its UserInfo. The user may have
+ * been found by email under a different id: see effectiveUserId.
  * When the user is missing and provisioning is enabled, attempts to create it.
  * When provisioning is disabled, throws a ProvisioningError with a clear message.
  */
@@ -267,30 +321,31 @@ async function getOrProvisionUser(client, tokenEntityRef, userId, provisioningEn
     if (!userId) {
         throw new ProvisioningError('User not found in LiteLLM', 'No user identity could be resolved from the request.', provisioningEnabled);
     }
-    const existing = await client.getUserInfo(userId);
+    const existing = await getUserByIdOrAdopted(client, userId);
     if (existing) {
         return existing;
     }
-    if (!provisioningEnabled) {
-        throw new ProvisioningError('User not found in LiteLLM', 'Enable litellm.provisioning.enabled in app-config.yaml or create the user manually', false);
-    }
     // Single-flight: if another request for the same userId is already
-    // provisioning, await its result instead of starting a new /user/new.
-    // This collapses the /keys + /teams + /usage page-load thundering
-    // herd into a single LiteLLM round-trip.
+    // resolving or provisioning, await its result instead of starting a new
+    // lookup and /user/new. This collapses the /keys + /teams + /usage
+    // page-load thundering herd into a single LiteLLM round-trip.
     const pending = provisioningInFlight.get(userId);
     if (pending) {
         logger.info(`LiteLLM provisioning already in flight for ${userId} — joining`);
         return pending;
     }
     const provisionPromise = (async () => {
-        const catalogRef = tokenEntityRef ?? userId;
-        const [matchedRole, profile] = await Promise.all([
-            resolveUserRole(catalogRef, roleConfigs, catalogClient, auth, logger),
-            tokenEntityRef
-                ? resolveUserProfile(tokenEntityRef, catalogClient, auth, logger)
-                : Promise.resolve({}),
-        ]);
+        const profile = tokenEntityRef
+            ? await resolveUserProfile(tokenEntityRef, catalogClient, auth, logger)
+            : {};
+        const byEmail = await adoptUserByEmail(client, userId, profile.email, logger);
+        if (byEmail) {
+            return byEmail;
+        }
+        if (!provisioningEnabled) {
+            throw new ProvisioningError('User not found in LiteLLM', 'Enable litellm.provisioning.enabled in app-config.yaml or create the user manually', false);
+        }
+        const matchedRole = await resolveUserRole(tokenEntityRef ?? userId, roleConfigs, catalogClient, auth, logger);
         const effectiveDefaults = matchedRole
             ? applyRoleOverrides(provisioningDefaults, matchedRole)
             : provisioningDefaults;
@@ -308,11 +363,13 @@ async function getOrProvisionUser(client, tokenEntityRef, userId, provisioningEn
             // The single-flight cache should prevent the parallel-409 race,
             // 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.
+            // it as "user exists" and re-fetch, by id and then by email
+            // (LiteLLM also refuses a second user with the same email).
             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);
+                const refetched = (await client.getUserInfo(userId)) ??
+                    (await adoptUserByEmail(client, userId, profile.email, logger));
                 if (refetched) {
                     return refetched;
                 }
@@ -331,7 +388,7 @@ async function getOrProvisionUser(client, tokenEntityRef, userId, provisioningEn
                 ? upstreamStatus
                 : 502;
             const errMessage = err instanceof Error ? err.message : String(err);
-            throw new ProvisioningError('LiteLLM auto-provisioning failed', `LiteLLM upstream ${upstreamStatus ?? 'error'}: ${sanitizeUpstreamMessage(errMessage)}`, true, passThrough);
+            throw new ProvisioningError('LiteLLM auto-provisioning failed', `LiteLLM upstream ${upstreamStatus ?? 'error'}: ${(0, errors_1.sanitizeUpstreamMessage)(errMessage)}`, true, passThrough);
         }
     })();
     provisioningInFlight.set(userId, provisionPromise);

package/dist/router.js

@@ -46,6 +46,7 @@ const backstage_plugin_litellm_common_1 = require("@acarmisc/backstage-plugin-li
 const teamAdmin_1 = require("./teamAdmin");
 const teamBudgetVisibility_1 = require("./teamBudgetVisibility");
 const opencode_1 = require("./opencode");
+const teamMemberUsage_1 = require("./teamMemberUsage");
 const errors_2 = require("./errors");
 const withUser_1 = require("./routes/middleware/withUser");
 const userInfoCache_1 = require("./services/userInfoCache");
@@ -90,12 +91,15 @@ async function createRouter(options) {
         maxTpm: keyMaxTpm,
         maxRpm: keyMaxRpm,
         allowedDurations: keyAllowedDurations,
+        allowedBudgetDurations: config.getOptionalStringArray('litellm.keys.allowedBudgetDurations') ??
+            backstage_plugin_litellm_common_1.DEFAULT_KEY_BUDGET_DURATIONS,
     };
     const teamMgmtEnabled = (0, teamAdmin_1.isTeamManagementEnabled)(config);
     const objectPermsEnabled = (0, teamAdmin_1.isObjectPermissionsEnabled)(config);
     const teamAdminCfg = (0, teamAdmin_1.readTeamAdminConfig)(config);
     const teamBudgetVisibility = (0, teamBudgetVisibility_1.readTeamBudgetVisibility)(config);
     const opencodeCfg = (0, opencode_1.readOpencodeConfig)(config);
+    const memberBreakdownCfg = (0, teamMemberUsage_1.readMemberBreakdownConfig)(config);
     const catalogClient = options.catalogClient ?? new catalog_client_1.CatalogClient({ discoveryApi: discovery });
     if (provisioningEnabled) {
         logger.info(`LiteLLM auto-provisioning enabled — defaults: budget=$${provisioningDefaults.maxBudget}/${provisioningDefaults.budgetDuration}, models=${provisioningDefaults.models.length
@@ -109,8 +113,16 @@ async function createRouter(options) {
         teamBudgetVisibility.hideTeamBudgetForManagers) {
         logger.info(`LiteLLM team budget hiding enabled — members: ${teamBudgetVisibility.hideTeamBudgetForMembers}, managers: ${teamBudgetVisibility.hideTeamBudgetForManagers}`);
     }
+    // LiteLLM user id of a Backstage user: the computed id, or the id of an
+    // existing user with the same catalog email.
+    const resolveMemberUserId = async (userEntityRef) => {
+        const computed = (0, provisioning_1.toLiteLLMUserId)(userEntityRef, userIdDomain);
+        await (0, provisioning_1.findLiteLLMUser)(client, userEntityRef, computed, catalogClient, auth, logger);
+        return (0, provisioning_1.effectiveUserId)(computed);
+    };
     // Build shared RouterContext with config and helpers
     const ctx = {
+        resolveMemberUserId,
         client,
         catalogClient,
         auth,
@@ -133,6 +145,7 @@ async function createRouter(options) {
         teamAdminCfg,
         teamBudgetVisibility,
         opencodeCfg,
+        memberBreakdownCfg,
         // Helper functions - defined inline below this object
         authorizeKeyAction: async (req, keyId) => {
             // Express middleware should have populated req.res.locals with user info
@@ -140,7 +153,8 @@ async function createRouter(options) {
                 throw new errors_1.NotAllowedError('User identity not found in request');
             }
             const tokenEntityRef = req.res.locals.tokenEntityRef;
-            const userId = req.res.locals.userId;
+            // The LiteLLM user may exist under a different id, found by email.
+            const userId = await resolveMemberUserId(tokenEntityRef);
             const ownKeys = await client.listKeys(userId);
             const key = ownKeys.find(k => (k.token ?? k.key) === keyId);
             if (!key) {
@@ -148,22 +162,6 @@ async function createRouter(options) {
             }
             return { tokenEntityRef, userId, key };
         },
-        sendOwnershipError: (err, res) => {
-            // Handle NotAllowedError from authorizeKeyAction
-            if (err instanceof errors_1.NotAllowedError) {
-                res.status(403).json({ error: err.message });
-                return true;
-            }
-            // Fallback for legacy errors with status and body
-            if (err && typeof err === 'object' && 'status' in err && 'body' in err) {
-                const errObj = err;
-                if (typeof errObj.status === 'number' && errObj.body) {
-                    res.status(errObj.status).json(errObj.body);
-                    return true;
-                }
-            }
-            return false;
-        },
         assertPermission: async (req, permission) => {
             const credentials = await (0, provisioning_1.resolveCredentials)(req, auth);
             if (!credentials)
@@ -281,7 +279,8 @@ async function createRouter(options) {
             // The permission framework still has the final say.
             if (teamRoleEligible) {
                 const actor = await (0, provisioning_1.resolveUserId)(req, auth);
-                const litellmUserId = actor && (0, provisioning_1.toLiteLLMUserId)(actor, userIdDomain);
+                const litellmUserId = actor &&
+                    (await resolveMemberUserId(actor));
                 const role = existing.members_with_roles?.find(m => m.user_id === litellmUserId)?.role;
                 if (actor &&
                     role &&

package/dist/routes/bridge.js

@@ -8,7 +8,7 @@ const keyService_1 = require("../services/keyService");
 const errors_1 = require("../errors");
 const backstage_plugin_litellm_common_2 = require("@acarmisc/backstage-plugin-litellm-common");
 function registerBridgeRoutes(router, ctx, bridgeOpts) {
-    const { client, logger, userIdDomain, provisioningEnabled, provisioningDefaults, roleConfigs, allowUnlimitedBudget, teamRequired, keyValidationConfig, } = ctx;
+    const { client, logger, userIdDomain, provisioningEnabled, provisioningDefaults, allowUnlimitedBudget, teamRequired, keyValidationConfig, } = ctx;
     const { config } = bridgeOpts;
     const generateKeyInputSchema = (0, backstage_plugin_litellm_common_2.createGenerateKeyInputSchema)(ctx.keyValidationConfig);
     // ---------------------------------------------------------------------------
@@ -99,8 +99,8 @@ function registerBridgeRoutes(router, ctx, bridgeOpts) {
                 if (!allowUnlimitedBudget && input.max_budget === undefined) {
                     input.max_budget = provisioningDefaults.maxBudget;
                 }
-                // ── Resolve user identity from verified claims ───────────────────────
-                const userId = (0, bridge_1.resolveBridgeUserId)(claims, bridgeIdentity);
+                // ── Resolve and provision user from verified claims ──────────────────
+                const userInfo = await (0, bridge_1.getOrProvisionUserFromClaims)(client, claims, provisioningEnabled, provisioningDefaults, logger, bridgeIdentity);
                 // ── Create key via unified service ──────────────────────────────────
                 const keyCreateCtx = {
                     client,
@@ -108,18 +108,10 @@ function registerBridgeRoutes(router, ctx, bridgeOpts) {
                         allowUnlimitedBudget,
                         teamRequired,
                     },
-                    // Bridge does not have Backstage catalogClient/auth
-                    // so provisioning from JWT claims only (no Backstage profile enrichment)
-                    catalogClient: undefined,
-                    auth: undefined,
                     logger,
                     keyValidationConfig,
-                    provisioningEnabled,
-                    provisioningDefaults,
-                    roleConfigs,
-                    userIdDomain,
                 };
-                const result = await (0, keyService_1.createKeyForUser)({ userId }, input, keyCreateCtx);
+                const result = await (0, keyService_1.createKeyForUser)({ userInfo, createdVia: 'abby-cli' }, input, keyCreateCtx);
                 res.json(result);
             }
             catch (error) {
@@ -132,23 +124,22 @@ function registerBridgeRoutes(router, ctx, bridgeOpts) {
             try {
                 const claims = await requireClaims(req);
                 const user = await (0, bridge_1.getOrProvisionUserFromClaims)(client, claims, provisioningEnabled, provisioningDefaults, logger, bridgeIdentity);
-                // Enrich team list with metadata (display names, etc.)
+                // Enrich team list with metadata (display names, etc.) in parallel
                 const teamIds = user.teams ?? [];
-                const teamMetadata = [];
-                for (const teamId of teamIds) {
+                const teamMetadata = await Promise.all(teamIds.map(async (teamId) => {
                     try {
                         const teamInfo = await client.getTeamInfo(teamId);
-                        teamMetadata.push({
+                        return {
                             id: teamId,
                             name: teamInfo.team_alias || teamId, // Use alias as display name, fallback to ID
-                        });
+                        };
                     }
                     catch (e) {
                         // If we can't fetch team info, just use the ID
                         logger.debug(`Could not fetch team info for ${teamId}: ${e.message}`);
-                        teamMetadata.push({ id: teamId });
+                        return { id: teamId };
                     }
-                }
+                }));
                 res.json({ user_id: user.user_id, teams: teamIds, team_metadata: teamMetadata });
             }
             catch (error) {

package/dist/routes/config.js

@@ -29,6 +29,9 @@ function registerConfigRoutes(router, ctx) {
                 readOnly: ctx.teamAdminCfg.readOnly,
                 memberManagerRoles: ctx.teamAdminCfg.memberManagerRoles,
             },
+            teamUsage: {
+                memberBreakdown: ctx.memberBreakdownCfg.enabled,
+            },
             display: {
                 hideTeamBudgetForMembers: ctx.teamBudgetVisibility.hideTeamBudgetForMembers,
                 hideTeamBudgetForManagers: ctx.teamBudgetVisibility.hideTeamBudgetForManagers,

package/dist/routes/context.d.ts

@@ -8,6 +8,7 @@ import { TeamAdminConfig } from '../teamAdmin';
 import type { KeyValidationConfig } from '@acarmisc/backstage-plugin-litellm-common';
 import { TeamBudgetVisibility } from '../teamBudgetVisibility';
 import { OpencodeConfig } from '../opencode';
+import { MemberBreakdownConfig } from '../teamMemberUsage';
 /**
  * Shared runtime context for all route handlers. Holds config-derived
  * constants, service clients, and helper functions needed by routes.
@@ -35,12 +36,17 @@ export interface RouterContext {
     teamAdminCfg: TeamAdminConfig;
     teamBudgetVisibility: TeamBudgetVisibility;
     opencodeCfg: OpencodeConfig;
+    memberBreakdownCfg: MemberBreakdownConfig;
+    /**
+     * LiteLLM user id of a Backstage user: the computed id, or the id of an
+     * existing LiteLLM user with the same catalog email.
+     */
+    resolveMemberUserId(userEntityRef: string): Promise<string>;
     authorizeKeyAction(req: Request, keyId: string): Promise<{
         tokenEntityRef: string;
         userId: string;
         key: VirtualKey;
     }>;
-    sendOwnershipError(err: unknown, res: Response): boolean;
     assertPermission(req: Request, permission: BasicPermission): Promise<boolean>;
     sendPermissionDenied(res: Response, permission: BasicPermission): void;
     requireTeamMgmt(res: Response): boolean;

package/dist/routes/keys.js

@@ -13,7 +13,7 @@ const withUser_1 = require("./middleware/withUser");
  * 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 { client, catalogClient, auth, logger, auditGroup, allowUnlimitedBudget, teamRequired, allowOwnerResetSpend, keyValidationConfig, authorizeKeyAction, 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) => {
@@ -35,8 +35,8 @@ function registerKeysRoutes(router, ctx) {
     });
     router.get('/keys', async (_req, res) => {
         try {
-            const userId = res.locals.userId;
             await (0, withUser_1.getProvisionedUser)(ctx, res);
+            const userId = res.locals.userId;
             const keys = await client.listKeys(userId);
             res.json(keys);
         }
@@ -55,9 +55,9 @@ function registerKeysRoutes(router, ctx) {
                 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);
+            const userId = res.locals.userId;
             // Load the caller's keys
             const keys = await client.listKeys(userId);
             // Identify expired keys (expires_at in the past)
@@ -132,7 +132,8 @@ function registerKeysRoutes(router, ctx) {
                 return;
             }
             const tokenEntityRef = res.locals.tokenEntityRef;
-            const resolvedUserId = res.locals.userId;
+            // ── Resolve and provision user ──────────────────────────────────────
+            const userInfo = await (0, withUser_1.getProvisionedUser)(ctx, res);
             // ── Create key via unified service ──────────────────────────────────
             const keyCreateCtx = {
                 client,
@@ -144,12 +145,8 @@ function registerKeysRoutes(router, ctx) {
                 auth,
                 logger,
                 keyValidationConfig,
-                provisioningEnabled,
-                provisioningDefaults,
-                roleConfigs,
-                userIdDomain,
             };
-            const result = await (0, keyService_1.createKeyForUser)({ tokenEntityRef, userId: resolvedUserId }, input, keyCreateCtx);
+            const result = await (0, keyService_1.createKeyForUser)({ tokenEntityRef, userInfo }, input, keyCreateCtx);
             res.json(result);
         }
         catch (error) {
@@ -277,8 +274,6 @@ function registerKeysRoutes(router, ctx) {
             res.json(result);
         }
         catch (error) {
-            if (sendOwnershipError(error, res))
-                return;
             (0, errors_1.sendError)(res, error, logger, 'update key');
         }
     });
@@ -299,8 +294,6 @@ function registerKeysRoutes(router, ctx) {
             res.json({ success: true });
         }
         catch (error) {
-            if (sendOwnershipError(error, res))
-                return;
             (0, errors_1.sendError)(res, error, logger, 'delete key');
         }
     });
@@ -334,8 +327,6 @@ function registerKeysRoutes(router, ctx) {
             res.json({ success: true });
         }
         catch (error) {
-            if (sendOwnershipError(error, res))
-                return;
             (0, errors_1.sendError)(res, error, logger, 'block key');
         }
     });
@@ -371,8 +362,6 @@ function registerKeysRoutes(router, ctx) {
             res.json({ success: true });
         }
         catch (error) {
-            if (sendOwnershipError(error, res))
-                return;
             (0, errors_1.sendError)(res, error, logger, 'unblock key');
         }
     });
@@ -397,8 +386,6 @@ function registerKeysRoutes(router, ctx) {
             res.json({ success: true });
         }
         catch (error) {
-            if (sendOwnershipError(error, res))
-                return;
             (0, errors_1.sendError)(res, error, logger, 'reset key spend');
         }
     });
@@ -454,10 +441,10 @@ function registerKeysRoutes(router, ctx) {
                 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);
+            await (0, withUser_1.getProvisionedUser)(ctx, res);
+            // Always filter by the caller's id: an empty user_id makes LiteLLM
+            // return org-wide activity.
+            const usage = await client.getUsage(start_date, end_date, res.locals.userId);
             res.json(usage);
         }
         catch (error) {