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

package/dist/router.js

@@ -36,14 +36,18 @@ 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");
+const teamAdmin_1 = require("./teamAdmin");
+const teamCreateInFlight = new Map();
 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');
@@ -57,12 +61,18 @@ async function createRouter(options) {
     const auditGroup = config.getOptionalString('litellm.audit.group');
     const allowUnlimitedBudget = config.getOptionalBoolean('litellm.keyGeneration.allowUnlimitedBudget') ?? false;
     const teamRequired = config.getOptionalBoolean('litellm.keyGeneration.teamRequired') ?? true;
-    const catalogClient = new catalog_client_1.CatalogClient({ discoveryApi: discovery });
+    const teamMgmtEnabled = (0, teamAdmin_1.isTeamManagementEnabled)(config);
+    const objectPermsEnabled = (0, teamAdmin_1.isObjectPermissionsEnabled)(config);
+    const teamAdminCfg = (0, teamAdmin_1.readTeamAdminConfig)(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
             ? provisioningDefaults.models.join(',')
             : 'all'}, teams=[${provisioningDefaults.teams.join(',')}]`);
     }
+    if (config.getOptional('litellm.teamAdmin') && !teamMgmtEnabled) {
+        logger.warn('litellm.teamAdmin is configured but team management is disabled — set permission.enabled: true and litellm.teamAdmin.group to enable it.');
+    }
     const router = (0, express_1.Router)();
     // JSON body parser. Without this, every POST/PUT endpoint sees an empty
     // req.body. Backstage's httpRouter does not apply a body parser at the
@@ -77,6 +87,12 @@ async function createRouter(options) {
         res.json({
             baseUrl: publicBaseUrl,
             keyGeneration: { allowUnlimitedBudget, teamRequired },
+            teamManagement: {
+                enabled: teamMgmtEnabled,
+                maxBudgetCeiling: teamAdminCfg.maxBudgetCeiling ?? null,
+                allowUnlimitedBudget: teamAdminCfg.allowUnlimitedBudget,
+                objectPermissionsEnabled: objectPermsEnabled,
+            },
         });
     });
     // Self-hosted OpenAPI 3.1 contract — lets integrators read a spec instead
@@ -212,6 +228,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 +273,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 +355,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 +379,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 +398,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 +417,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 +436,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 +467,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({
@@ -460,6 +525,585 @@ async function createRouter(options) {
             res.status(500).json({ error: error.message });
         }
     });
+    function requireTeamMgmt(res) {
+        if (!teamMgmtEnabled) {
+            res.status(403).json({
+                error: 'Team management is disabled (requires permission.enabled and litellm.teamAdmin.group)',
+            });
+            return false;
+        }
+        return true;
+    }
+    function requireObjectPerms(res) {
+        if (!requireTeamMgmt(res))
+            return false;
+        if (!objectPermsEnabled) {
+            res.status(403).json({
+                error: 'Knowledge-base / MCP management is disabled (set litellm.teamAdmin.objectPermissions.enabled: true, with a permission policy and the allowlists in place)',
+            });
+            return false;
+        }
+        return true;
+    }
+    function sendTeamError(err, res) {
+        if (err instanceof client_1.LiteLLMUpstreamError) {
+            res.status(err.status).json({
+                error: err.message,
+                ...(err.param ? { param: err.param } : {}),
+            });
+        }
+        else {
+            logger.error('Team operation failed', err);
+            res.status(500).json({ error: err.message });
+        }
+    }
+    router.post('/teams', async (req, res) => {
+        if (!requireTeamMgmt(res))
+            return;
+        const check = await (0, teamAdmin_1.assertTeamAdmin)({
+            req,
+            auth,
+            permissions,
+            catalogClient,
+            teamAdminGroup: teamAdminCfg.group,
+            permission: permissions_1.litellmTeamCreatePermission,
+            logger,
+        });
+        if (!check.ok) {
+            res.status(check.status).json({ error: check.error });
+            return;
+        }
+        const v = (0, teamAdmin_1.validateTeamWriteInput)(req.body ?? {}, teamAdminCfg);
+        if (!v.ok) {
+            res.status(400).json({ error: v.error });
+            return;
+        }
+        const key = v.value.team_alias.trim().toLowerCase();
+        const pending = teamCreateInFlight.get(key);
+        if (pending) {
+            logger.info(`Team creation already in flight for ${key} — joining`);
+            try {
+                const result = await pending;
+                res.json(result);
+            }
+            catch (err) {
+                sendTeamError(err, res);
+            }
+            return;
+        }
+        const payload = {
+            team_alias: v.value.team_alias,
+            models: v.value.models,
+            ...(v.value.max_budget !== undefined && { max_budget: v.value.max_budget }),
+            ...(v.value.budget_duration && { budget_duration: v.value.budget_duration }),
+            ...(v.value.tpm_limit !== undefined && { tpm_limit: v.value.tpm_limit }),
+            ...(v.value.rpm_limit !== undefined && { rpm_limit: v.value.rpm_limit }),
+            metadata: {
+                owning_group: teamAdminCfg.group,
+                created_by_backstage_user: check.userEntityRef,
+                created_via: 'backstage',
+                created_at_iso: new Date().toISOString(),
+            },
+        };
+        const createPromise = (async () => {
+            const result = await client.createTeam(payload);
+            logger.info({
+                action: 'team.create',
+                actor: check.userEntityRef,
+                teamAlias: v.value.team_alias,
+                owningGroup: teamAdminCfg.group,
+            });
+            return result;
+        })();
+        teamCreateInFlight.set(key, createPromise);
+        try {
+            const result = await createPromise;
+            res.json(result);
+        }
+        catch (err) {
+            sendTeamError(err, res);
+        }
+        finally {
+            teamCreateInFlight.delete(key);
+        }
+    });
+    router.patch('/teams/:teamId', async (req, res) => {
+        const authz = await authorizeTeamSubresource(req, res, permissions_1.litellmTeamManagePermission);
+        if (!authz)
+            return;
+        const { teamId, owningGroup, actor, team: existing } = authz;
+        const v = (0, teamAdmin_1.validateTeamPatchInput)(req.body ?? {}, teamAdminCfg);
+        if (!v.ok) {
+            res.status(400).json({ error: v.error });
+            return;
+        }
+        // Optimistic-concurrency guard (opt-in): when the client sends the
+        // `expectedUpdatedAtIso` it based its edit on, reject if the stored value
+        // has moved on — a concurrent edit landed in between. Callers that don't
+        // send it are unaffected (last-writer-wins, as before).
+        const expected = (req.body ?? {}).expectedUpdatedAtIso;
+        if (expected !== undefined &&
+            expected !== existing.metadata?.updated_at_iso) {
+            res.status(409).json({
+                error: 'This team was modified since you loaded it. Reload and re-apply your change.',
+            });
+            return;
+        }
+        const payload = {
+            team_id: teamId,
+            ...v.value,
+            metadata: {
+                ...(existing.metadata ?? {}),
+                updated_by_backstage_user: actor,
+                updated_at_iso: new Date().toISOString(),
+            },
+        };
+        try {
+            const r = await client.updateTeam(payload);
+            logger.info({
+                action: 'team.update',
+                actor,
+                teamId,
+                owningGroup,
+            });
+            res.json(r);
+        }
+        catch (err) {
+            sendTeamError(err, res);
+        }
+    });
+    // Delete a team the caller's group owns. Gated by litellm.teamAdmin.allowTeamDelete
+    // (default false — deletion is destructive: it orphans keys and revokes access
+    // for every member). Refuses when the team id is referenced by provisioning
+    // config unless ?force=true. Prefer blocking a team over deleting it.
+    router.delete('/teams/:teamId', async (req, res) => {
+        const authz = await authorizeTeamSubresource(req, res, permissions_1.litellmTeamDeletePermission);
+        if (!authz)
+            return;
+        const { teamId, owningGroup, actor } = authz;
+        if (!teamAdminCfg.allowTeamDelete) {
+            res.status(403).json({
+                error: 'Team deletion is disabled (set litellm.teamAdmin.allowTeamDelete: true). Block the team instead.',
+            });
+            return;
+        }
+        const provisioningRefs = [
+            ...provisioningDefaults.teams,
+            ...roleConfigs.flatMap(r => r.teams ?? []),
+        ];
+        const force = String(req.query.force ?? '') === 'true';
+        if (provisioningRefs.includes(teamId) && !force) {
+            res.status(409).json({
+                error: `Team ${teamId} is referenced by litellm.provisioning config; deleting it will break user provisioning. Re-send with ?force=true to override.`,
+            });
+            return;
+        }
+        try {
+            await client.deleteTeam(teamId);
+            logger.info({ action: 'team.delete', actor, teamId, owningGroup, force });
+            res.json({ success: true });
+        }
+        catch (err) {
+            sendTeamError(err, res);
+        }
+    });
+    // Scoped listing for team admins: returns ONLY the teams whose
+    // `metadata.owning_group` equals the configured admin group, so a team admin
+    // can see and edit teams their group owns even when they are not a member.
+    // This deliberately never returns a global team list. Registered before any
+    // `/teams/:param` route so the literal path is not shadowed.
+    router.get('/teams/managed', async (req, res) => {
+        if (!requireTeamMgmt(res))
+            return;
+        const check = await (0, teamAdmin_1.assertTeamAdmin)({
+            req,
+            auth,
+            permissions,
+            catalogClient,
+            teamAdminGroup: teamAdminCfg.group,
+            permission: permissions_1.litellmTeamManagePermission,
+            logger,
+        });
+        if (!check.ok) {
+            res.status(check.status).json({ error: check.error });
+            return;
+        }
+        try {
+            const all = await client.listTeams();
+            // TODO(multi-group): when litellm.teamAdmin.group becomes a list, resolve
+            // the caller's group set and filter with includes().
+            const owned = all.filter(t => typeof t.metadata?.owning_group === 'string' &&
+                t.metadata.owning_group === teamAdminCfg.group);
+            res.json(owned);
+        }
+        catch (err) {
+            sendTeamError(err, res);
+        }
+    });
+    // ── Team member routes ──────────────────────────────────────────────────
+    //
+    // Shared preamble: team-mgmt enabled → assertTeamAdmin(members permission) →
+    // load the team and enforce the owning-group object guard (same as PATCH
+    // /teams/:id). Returns the resolved teamId + owningGroup, or null when a
+    // response has already been sent.
+    // Shared preamble for a team sub-resource mutation (members, knowledge bases,
+    // MCP servers): team-mgmt enabled → assertTeamAdmin(<the given permission>) →
+    // load the team and enforce the owning-group object guard. Returns the
+    // resolved teamId + owningGroup + actor, or null when a response was sent.
+    async function authorizeTeamSubresource(req, res, permission) {
+        if (!requireTeamMgmt(res))
+            return null;
+        const check = await (0, teamAdmin_1.assertTeamAdmin)({
+            req,
+            auth,
+            permissions,
+            catalogClient,
+            teamAdminGroup: teamAdminCfg.group,
+            permission,
+            logger,
+        });
+        if (!check.ok) {
+            res.status(check.status).json({ error: check.error });
+            return null;
+        }
+        const { teamId } = req.params;
+        if (!teamId) {
+            res.status(400).json({ error: 'teamId is required' });
+            return null;
+        }
+        let existing;
+        try {
+            existing = await client.getTeamInfo(teamId);
+        }
+        catch (err) {
+            if (err instanceof client_1.LiteLLMUpstreamError && err.status === 404) {
+                res.status(404).json({ error: 'Team not found' });
+                return null;
+            }
+            sendTeamError(err, res);
+            return null;
+        }
+        const owningGroup = typeof existing.metadata?.owning_group === 'string'
+            ? existing.metadata.owning_group
+            : undefined;
+        if (!owningGroup) {
+            res.status(403).json({
+                error: 'This team is not managed by Backstage team admins and cannot be edited here',
+            });
+            return null;
+        }
+        const owns = await (0, provisioning_1.isUserMemberOfGroup)(check.userEntityRef, owningGroup, catalogClient, auth, logger);
+        if (!owns) {
+            res
+                .status(403)
+                .json({ error: `Access denied: team is owned by ${owningGroup}` });
+            return null;
+        }
+        return { teamId, owningGroup, actor: check.userEntityRef, team: existing };
+    }
+    // Add a member to a team the caller's group owns. The member must (a) resolve
+    // to a real User in the Backstage catalog and (b) exist in LiteLLM — we
+    // provision them on the spot when auto-provisioning is enabled. Only the
+    // 'user' team role can be assigned from Backstage.
+    router.post('/teams/:teamId/members', async (req, res) => {
+        const authz = await authorizeTeamSubresource(req, res, permissions_1.litellmTeamMembersManagePermission);
+        if (!authz)
+            return;
+        const { teamId, owningGroup, actor } = authz;
+        const body = (req.body ?? {});
+        const userEntityRef = (body.userEntityRef ?? '').trim();
+        if (!userEntityRef) {
+            res.status(400).json({ error: 'userEntityRef is required' });
+            return;
+        }
+        if (body.role !== undefined && body.role !== 'user') {
+            res.status(400).json({
+                error: "only the 'user' team role can be assigned from Backstage",
+            });
+            return;
+        }
+        let maxBudgetInTeam;
+        if (body.maxBudgetInTeam !== undefined) {
+            if (typeof body.maxBudgetInTeam !== 'number' ||
+                !Number.isFinite(body.maxBudgetInTeam) ||
+                body.maxBudgetInTeam <= 0) {
+                res
+                    .status(400)
+                    .json({ error: 'maxBudgetInTeam must be a positive number' });
+                return;
+            }
+            maxBudgetInTeam = body.maxBudgetInTeam;
+        }
+        // (a) the member must be a real User in the Backstage catalog
+        try {
+            const { token } = await auth.getPluginRequestToken({
+                onBehalfOf: await auth.getOwnServiceCredentials(),
+                targetPluginId: 'catalog',
+            });
+            const entity = await catalogClient.getEntityByRef(userEntityRef, {
+                token,
+            });
+            if (!entity || entity.kind !== 'User') {
+                res.status(400).json({
+                    error: `${userEntityRef} is not a User in the Backstage catalog`,
+                });
+                return;
+            }
+        }
+        catch (err) {
+            logger.warn(`Catalog lookup failed for ${userEntityRef}: ${err.message}`);
+            res.status(400).json({
+                error: `Could not verify ${userEntityRef} in the Backstage catalog`,
+            });
+            return;
+        }
+        // (b) the member must exist in LiteLLM — provision on the spot if enabled
+        const litellmUserId = (0, provisioning_1.toLiteLLMUserId)(userEntityRef, userIdDomain);
+        try {
+            await (0, provisioning_1.getOrProvisionUser)(client, userEntityRef, litellmUserId, provisioningEnabled, provisioningDefaults, roleConfigs, catalogClient, auth, logger);
+        }
+        catch (err) {
+            if (err instanceof provisioning_1.ProvisioningError) {
+                res.status(err.status).json(err.body);
+                return;
+            }
+            throw err;
+        }
+        try {
+            await client.teamMemberAdd({
+                team_id: teamId,
+                user_id: litellmUserId,
+                role: 'user',
+                ...(maxBudgetInTeam !== undefined && {
+                    max_budget_in_team: maxBudgetInTeam,
+                }),
+            });
+            logger.info({
+                action: 'team.member.add',
+                actor,
+                teamId,
+                member: litellmUserId,
+                owningGroup,
+            });
+            const updated = await client.getTeamInfo(teamId);
+            res.json(updated);
+        }
+        catch (err) {
+            sendTeamError(err, res);
+        }
+    });
+    // Remove a member from a team the caller's group owns. The member ref comes
+    // from the `userEntityRef` query param (entity refs contain ':' and '/', so
+    // they can't be a path segment). No catalog re-check on removal.
+    router.delete('/teams/:teamId/members', async (req, res) => {
+        const authz = await authorizeTeamSubresource(req, res, permissions_1.litellmTeamMembersManagePermission);
+        if (!authz)
+            return;
+        const { teamId, owningGroup, actor } = authz;
+        const userEntityRef = String(req.query.userEntityRef ?? '').trim();
+        if (!userEntityRef) {
+            res
+                .status(400)
+                .json({ error: 'userEntityRef query parameter is required' });
+            return;
+        }
+        const litellmUserId = (0, provisioning_1.toLiteLLMUserId)(userEntityRef, userIdDomain);
+        try {
+            await client.teamMemberDelete({
+                team_id: teamId,
+                user_id: litellmUserId,
+            });
+            logger.info({
+                action: 'team.member.remove',
+                actor,
+                teamId,
+                member: litellmUserId,
+                owningGroup,
+            });
+            const updated = await client.getTeamInfo(teamId);
+            res.json(updated);
+        }
+        catch (err) {
+            sendTeamError(err, res);
+        }
+    });
+    // ── Knowledge-base (vector store) management ────────────────────────────
+    //
+    // Attaching a vector store to a team exposes its documents to every team
+    // key. Team admins may only reference stores that the operator has
+    // allowlisted in litellm.teamAdmin.allowedVectorStores — anything outside
+    // the allowlist is rejected, never silently dropped.
+    // The vector stores a team admin is allowed to attach (allowlist ∩ proxy).
+    router.get('/vector-stores', async (req, res) => {
+        if (!requireObjectPerms(res))
+            return;
+        const check = await (0, teamAdmin_1.assertTeamAdmin)({
+            req,
+            auth,
+            permissions,
+            catalogClient,
+            teamAdminGroup: teamAdminCfg.group,
+            permission: permissions_1.litellmTeamKnowledgebaseManagePermission,
+            logger,
+        });
+        if (!check.ok) {
+            res.status(check.status).json({ error: check.error });
+            return;
+        }
+        const allowed = new Set(teamAdminCfg.allowedVectorStores);
+        try {
+            const all = await client.listVectorStores();
+            res.json(all.filter(s => allowed.has(s.id) || (s.name && allowed.has(s.name))));
+        }
+        catch (err) {
+            sendTeamError(err, res);
+        }
+    });
+    // Replace the set of knowledge bases attached to a team the caller's group
+    // owns. Body: { vector_stores: string[] }. Every id must be in the
+    // allowlist. The other object_permission facets (mcp_servers) are preserved.
+    router.put('/teams/:teamId/knowledge-bases', async (req, res) => {
+        if (!requireObjectPerms(res))
+            return;
+        const authz = await authorizeTeamSubresource(req, res, permissions_1.litellmTeamKnowledgebaseManagePermission);
+        if (!authz)
+            return;
+        const { teamId, owningGroup, actor, team } = authz;
+        const requested = (req.body?.vector_stores ?? []);
+        if (!Array.isArray(requested) ||
+            !requested.every(v => typeof v === 'string')) {
+            res
+                .status(400)
+                .json({ error: 'vector_stores must be an array of strings' });
+            return;
+        }
+        const allowed = new Set(teamAdminCfg.allowedVectorStores);
+        const offenders = requested.filter(v => !allowed.has(v));
+        if (offenders.length) {
+            res.status(400).json({
+                error: `vector store(s) not in the allowed set for team admins: ${offenders.join(', ')}`,
+            });
+            return;
+        }
+        const objectPermission = {
+            ...(team.object_permission ?? {}),
+            vector_stores: requested,
+        };
+        try {
+            const updated = await client.updateTeam({
+                team_id: teamId,
+                object_permission: objectPermission,
+                // /team/update replaces metadata wholesale — re-send the merged
+                // object so owning_group / created_* survive and the change is
+                // attributed.
+                metadata: {
+                    ...(team.metadata ?? {}),
+                    updated_by_backstage_user: actor,
+                    updated_at_iso: new Date().toISOString(),
+                },
+            });
+            logger.info({
+                action: 'team.knowledgebase.set',
+                actor,
+                teamId,
+                owningGroup,
+                vector_stores: requested,
+            });
+            res.json(updated);
+        }
+        catch (err) {
+            sendTeamError(err, res);
+        }
+    });
+    // ── MCP server management ──────────────────────────────────────────────
+    //
+    // Attaching an MCP server to a team grants every team key the ability to
+    // invoke that server's tools through the model. Same allowlist + hard-reject
+    // discipline as knowledge bases, plus a structured audit event on every
+    // change so attaches are always attributable.
+    router.get('/mcp-servers', async (req, res) => {
+        if (!requireObjectPerms(res))
+            return;
+        const check = await (0, teamAdmin_1.assertTeamAdmin)({
+            req,
+            auth,
+            permissions,
+            catalogClient,
+            teamAdminGroup: teamAdminCfg.group,
+            permission: permissions_1.litellmTeamMcpManagePermission,
+            logger,
+        });
+        if (!check.ok) {
+            res.status(check.status).json({ error: check.error });
+            return;
+        }
+        const allowed = new Set(teamAdminCfg.allowedMcpServers);
+        try {
+            const all = await client.listMcpServers();
+            res.json(all.filter(s => allowed.has(s.id) || (s.name && allowed.has(s.name))));
+        }
+        catch (err) {
+            sendTeamError(err, res);
+        }
+    });
+    // Replace the set of MCP servers attached to a team the caller's group owns.
+    // Body: { mcp_servers: string[] }. Every id must be allowlisted. The
+    // vector_stores facet of object_permission is preserved.
+    router.put('/teams/:teamId/mcp-servers', async (req, res) => {
+        if (!requireObjectPerms(res))
+            return;
+        const authz = await authorizeTeamSubresource(req, res, permissions_1.litellmTeamMcpManagePermission);
+        if (!authz)
+            return;
+        const { teamId, owningGroup, actor, team } = authz;
+        const requested = (req.body?.mcp_servers ?? []);
+        if (!Array.isArray(requested) ||
+            !requested.every(v => typeof v === 'string')) {
+            res
+                .status(400)
+                .json({ error: 'mcp_servers must be an array of strings' });
+            return;
+        }
+        const allowed = new Set(teamAdminCfg.allowedMcpServers);
+        const offenders = requested.filter(v => !allowed.has(v));
+        if (offenders.length) {
+            res.status(400).json({
+                error: `MCP server(s) not in the allowed set for team admins: ${offenders.join(', ')}`,
+            });
+            return;
+        }
+        const before = team.object_permission?.mcp_servers ?? [];
+        const objectPermission = {
+            ...(team.object_permission ?? {}),
+            mcp_servers: requested,
+        };
+        try {
+            const updated = await client.updateTeam({
+                team_id: teamId,
+                object_permission: objectPermission,
+                // /team/update replaces metadata wholesale — re-send the merged
+                // object so owning_group / created_* survive and the change is
+                // attributed.
+                metadata: {
+                    ...(team.metadata ?? {}),
+                    updated_by_backstage_user: actor,
+                    updated_at_iso: new Date().toISOString(),
+                },
+            });
+            logger.info({
+                action: 'team.mcp.set',
+                actor,
+                teamId,
+                owningGroup,
+                before,
+                after: requested,
+            });
+            res.json(updated);
+        }
+        catch (err) {
+            sendTeamError(err, res);
+        }
+    });
     router.get('/teams/:teamId/usage', async (req, res) => {
         try {
             const { teamId } = req.params;