@acarmisc/backstage-plugin-litellm-backend 0.15.0 → 0.16.0

package/dist/routes/objectPermissions.js

@@ -0,0 +1,196 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerObjectPermissionsRoutes = registerObjectPermissionsRoutes;
+const backstage_plugin_litellm_common_1 = require("@acarmisc/backstage-plugin-litellm-common");
+const teamAdmin_1 = require("../teamAdmin");
+const teamBudgetVisibility_1 = require("../teamBudgetVisibility");
+function registerObjectPermissionsRoutes(router, ctx) {
+    const { client, catalogClient, auth, permissions, logger, teamAdminCfg, teamBudgetVisibility, requireObjectPerms, sendTeamError, authorizeTeamSubresource, } = ctx;
+    // ── 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;
+        if (!teamAdminCfg.group) {
+            res.status(500).json({ error: 'Team management is misconfigured (group is missing)' });
+            return;
+        }
+        const check = await (0, teamAdmin_1.assertTeamAdmin)({
+            req,
+            auth,
+            permissions,
+            catalogClient,
+            teamAdminGroup: teamAdminCfg.group,
+            permission: backstage_plugin_litellm_common_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, backstage_plugin_litellm_common_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('team.knowledgebase.set', {
+                actor,
+                teamId,
+                owningGroup,
+                vector_stores: requested,
+            });
+            res.json(teamBudgetVisibility.hideTeamBudgetForManagers
+                ? (0, teamBudgetVisibility_1.redactTeamBudget)(updated)
+                : 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;
+        if (!teamAdminCfg.group) {
+            res.status(500).json({ error: 'Team management is misconfigured (group is missing)' });
+            return;
+        }
+        const check = await (0, teamAdmin_1.assertTeamAdmin)({
+            req,
+            auth,
+            permissions,
+            catalogClient,
+            teamAdminGroup: teamAdminCfg.group,
+            permission: backstage_plugin_litellm_common_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, backstage_plugin_litellm_common_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('team.mcp.set', {
+                actor,
+                teamId,
+                owningGroup,
+                before,
+                after: requested,
+            });
+            res.json(teamBudgetVisibility.hideTeamBudgetForManagers
+                ? (0, teamBudgetVisibility_1.redactTeamBudget)(updated)
+                : updated);
+        }
+        catch (err) {
+            sendTeamError(err, res);
+        }
+    });
+}

package/dist/routes/opencode.d.ts

@@ -0,0 +1,3 @@
+import { Router } from 'express';
+import type { RouterContext } from './context';
+export declare function registerOpencodeRoutes(router: Router, ctx: RouterContext): void;

package/dist/routes/opencode.js

@@ -0,0 +1,239 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerOpencodeRoutes = registerOpencodeRoutes;
+const provisioning_1 = require("../provisioning");
+const backstage_plugin_litellm_common_1 = require("@acarmisc/backstage-plugin-litellm-common");
+const client_1 = require("../client");
+const errors_1 = require("../errors");
+/**
+ * Only loopback http://localhost:<port>/callback redirect URIs are accepted —
+ * the OpenCode plugin runs its callback listener on 127.0.0.1. This
+ * keeps the flow from being usable as an open redirect.
+ */
+function isValidRedirectUri(uri) {
+    if (!uri)
+        return false;
+    try {
+        const url = new URL(uri);
+        return (url.protocol === 'http:' &&
+            (url.hostname === 'localhost' || url.hostname === '127.0.0.1') &&
+            url.pathname === '/callback');
+    }
+    catch {
+        return false;
+    }
+}
+function registerOpencodeRoutes(router, ctx) {
+    const { client, catalogClient, auth, logger, userIdDomain, provisioningEnabled, provisioningDefaults, roleConfigs, opencodeCfg, assertPermission, sendPermissionDenied, } = ctx;
+    // ── OpenCode SSO-connect ─────────────────────────────────────────────────
+    //
+    // Client side: the opencode-portal-auth plugin. Handshake contract (see
+    // that package's README):
+    //
+    //   GET /opencode/connect?team=<id>&redirect_uri=http://localhost:<port>/callback
+    //     → (SSO-authenticated) returns an HTML confirmation form (no state change)
+    //
+    //   POST /opencode/connect with form data (team, redirect_uri)
+    //     → validates all conditions, rotates or generates a key
+    //     → 302 redirect to {redirect_uri}?key=<plaintext-key>
+    //
+    // Mounted only when litellm.opencode.enabled is true. Key creation is
+    // gated by the same litellmKeyCreatePermission as POST /keys/generate.
+    if (opencodeCfg.enabled) {
+        logger.info(`OpenCode connect endpoint enabled — duration=${opencodeCfg.keyDuration}, maxBudget=$${opencodeCfg.maxBudget}`);
+        // Helper to validate auth, permissions, redirect_uri, and team membership.
+        // Reused by both GET and POST.
+        // Returns null if validation fails (response already sent).
+        // Returns an object with validated values if all checks pass.
+        // Note: after successful validation, redirectUri is guaranteed to be a valid string.
+        const validateOpenCodeRequest = async (req, res) => {
+            const tokenEntityRef = await (0, provisioning_1.resolveUserId)(req, auth);
+            if (!tokenEntityRef) {
+                res.status(401).json({ error: 'Authentication required' });
+                return null;
+            }
+            // For GET, redirectUri is in query; for POST, it's in body.
+            const redirectUriParam = (req.query.redirect_uri || req.body.redirect_uri);
+            if (!isValidRedirectUri(redirectUriParam)) {
+                res.status(400).json({
+                    error: 'Invalid redirect_uri — expected http://localhost:<port>/callback',
+                });
+                return null;
+            }
+            // After isValidRedirectUri check, we know redirectUriParam is a valid string (! to tell TS).
+            const redirectUri = redirectUriParam;
+            if (!(await assertPermission(req, backstage_plugin_litellm_common_1.litellmKeyCreatePermission))) {
+                sendPermissionDenied(res, backstage_plugin_litellm_common_1.litellmKeyCreatePermission);
+                return null;
+            }
+            const userId = (0, provisioning_1.toLiteLLMUserId)(tokenEntityRef, userIdDomain);
+            const userInfo = await (0, provisioning_1.getOrProvisionUser)(client, tokenEntityRef, userId, provisioningEnabled, provisioningDefaults, roleConfigs, catalogClient, auth, logger);
+            // Optional team binding: must be one of the user's own teams.
+            const teamId = (req.query.team || req.body.team);
+            if (teamId) {
+                const userTeams = userInfo?.teams ?? [];
+                if (!userTeams.includes(teamId)) {
+                    res.status(403).json({
+                        error: 'Access denied: team is not one of your teams',
+                        team: teamId,
+                    });
+                    return null;
+                }
+            }
+            else if (opencodeCfg.requireTeam) {
+                res.status(400).json({ error: 'A team is required for this connection' });
+                return null;
+            }
+            return { tokenEntityRef, userId, userInfo, teamId, redirectUri };
+        };
+        router.get('/opencode/connect', async (req, res) => {
+            try {
+                const validation = await validateOpenCodeRequest(req, res);
+                if (!validation)
+                    return;
+                const { teamId, redirectUri } = validation;
+                // GET returns an HTML form without changing state (no key mint/rotate yet).
+                // The form allows the user to review the connection and submit to POST.
+                const teamDisplay = teamId ? ` for team ${escapeHtml(teamId)}` : '';
+                const html = `<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>OpenCode Connect</title>
+  <style>
+    body { font-family: system-ui, -apple-system, sans-serif; margin: 0; padding: 2rem; background: #f5f5f5; }
+    .container { max-width: 400px; margin: 0 auto; background: white; border-radius: 8px; padding: 2rem; box-shadow: 0 1px 3px rgba(0,0,0,0.1); }
+    h1 { margin-top: 0; color: #333; font-size: 1.5rem; }
+    p { color: #666; line-height: 1.5; }
+    button { background: #0066cc; color: white; border: none; padding: 0.75rem 1.5rem; border-radius: 4px; cursor: pointer; font-size: 1rem; }
+    button:hover { background: #0052a3; }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <h1>Connect to OpenCode</h1>
+    <p>This will create or rotate your OpenCode API key${teamDisplay}.</p>
+    <form method="POST">
+      <input type="hidden" name="redirect_uri" value="${escapeHtml(redirectUri)}">
+      ${teamId ? `<input type="hidden" name="team" value="${escapeHtml(teamId)}">` : ''}
+      <button type="submit">Connect</button>
+    </form>
+  </div>
+</body>
+</html>`;
+                res.set('Cache-Control', 'no-store');
+                res.set('Content-Security-Policy', "default-src 'none'; style-src 'unsafe-inline'; form-action 'self' http://localhost:* http://127.0.0.1:*");
+                res.set('Content-Type', 'text/html; charset=utf-8');
+                res.status(200).send(html);
+            }
+            catch (error) {
+                if (error instanceof provisioning_1.ProvisioningError) {
+                    res.status(error.status).json(error.body);
+                    return;
+                }
+                (0, errors_1.sendError)(res, error, logger, 'OpenCode connect GET');
+            }
+        });
+        router.post('/opencode/connect', async (req, res) => {
+            try {
+                const validation = await validateOpenCodeRequest(req, res);
+                if (!validation)
+                    return;
+                const { tokenEntityRef, userId, teamId, redirectUri } = validation;
+                // Alias is stable per user+team so re-connecting rotates the same
+                // logical key slot. Check if an existing key exists for this slot.
+                const alias = teamId ? `opencode-${userId}-${teamId}` : `opencode-${userId}`;
+                const existing = await client
+                    .listKeys(userId)
+                    .catch(() => []);
+                // Find a healthy existing key (not blocked).
+                const reusable = existing.find(k => k.key_alias === alias && !k.blocked && k.user_id === userId);
+                // Mint a brand-new key bound to this user (and team) under the slot alias.
+                const mintNewKey = async () => {
+                    const profile = await (0, provisioning_1.resolveUserProfile)(tokenEntityRef, catalogClient, auth, logger);
+                    const result = await client.generateKey({
+                        alias,
+                        duration: opencodeCfg.keyDuration,
+                        max_budget: opencodeCfg.maxBudget,
+                        team_id: teamId,
+                        metadata: {
+                            ...opencodeCfg.metadata,
+                            created_via: 'opencode-connect',
+                            created_by_backstage_user: tokenEntityRef,
+                            ...(profile.email && { created_by_email: profile.email }),
+                            ...(teamId && { opencode_team: teamId }),
+                        },
+                        user_id: userId,
+                    });
+                    return result.key;
+                };
+                let key;
+                let rotated = false;
+                if (reusable?.token ?? reusable?.key) {
+                    const keyHashOrId = (reusable.token ?? reusable.key);
+                    try {
+                        // Rotate the existing key in place via LiteLLM's key regeneration.
+                        key = (await client.regenerateKey(keyHashOrId)).key;
+                        rotated = true;
+                    }
+                    catch (err) {
+                        // Key regeneration isn't available on every LiteLLM edition. Only
+                        // "not supported / not found" answers fall back to replacing the
+                        // key (delete + generate under the same alias); auth, upstream
+                        // outages and everything else still fail the request.
+                        // Open-source LiteLLM answers with an "Enterprise feature" error
+                        // (a 500), so recognise that by message as well as by status.
+                        const unsupported = err instanceof client_1.LiteLLMUpstreamError &&
+                            ([400, 404, 405, 501].includes(err.status) ||
+                                /enterprise|premium/i.test(err.message));
+                        if (!unsupported)
+                            throw err;
+                        logger.warn('LiteLLM key regeneration unavailable; replacing the OpenCode key instead');
+                        await client.deleteKeys({ keys: [keyHashOrId] });
+                        key = await mintNewKey();
+                        rotated = true;
+                    }
+                }
+                else {
+                    key = await mintNewKey();
+                }
+                if (!key) {
+                    res.status(502).json({ error: 'LiteLLM returned no key material' });
+                    return;
+                }
+                const url = new URL(redirectUri);
+                url.searchParams.set('key', key);
+                if (teamId)
+                    url.searchParams.set('team', teamId);
+                logger.info('opencode.connect', {
+                    userId,
+                    team: teamId ?? null,
+                    rotated,
+                });
+                res.redirect(302, url.href);
+            }
+            catch (error) {
+                if (error instanceof provisioning_1.ProvisioningError) {
+                    res.status(error.status).json(error.body);
+                    return;
+                }
+                (0, errors_1.sendError)(res, error, logger, 'OpenCode connect POST');
+            }
+        });
+    }
+    /**
+     * Escape HTML special characters in strings to prevent XSS.
+     * Used when interpolating team IDs and redirect URIs into the confirmation form.
+     */
+    function escapeHtml(text) {
+        const map = {
+            '&': '&amp;',
+            '<': '&lt;',
+            '>': '&gt;',
+            '"': '&quot;',
+            "'": '&#39;',
+        };
+        return text.replace(/[&<>"']/g, c => map[c]);
+    }
+}

package/dist/routes/teamUsage.d.ts

@@ -0,0 +1,3 @@
+import { Router } from 'express';
+import type { RouterContext } from './context';
+export declare function registerTeamUsageRoutes(router: Router, ctx: RouterContext): void;

package/dist/routes/teamUsage.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerTeamUsageRoutes = registerTeamUsageRoutes;
+const provisioning_1 = require("../provisioning");
+const teamBudgetVisibility_1 = require("../teamBudgetVisibility");
+const errors_1 = require("../errors");
+const teamFetch_1 = require("../http/teamFetch");
+const withUser_1 = require("./middleware/withUser");
+function registerTeamUsageRoutes(router, ctx) {
+    const { client, catalogClient, auth, logger, provisioningEnabled, provisioningDefaults, roleConfigs, teamBudgetVisibility, } = ctx;
+    const requireUser = (0, withUser_1.createRequireUser)(ctx);
+    router.get('/teams/:teamId/usage', requireUser, async (req, res) => {
+        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;
+            }
+            // Authorize: member of the team OR a team manager
+            const tokenEntityRef = res.locals.tokenEntityRef;
+            const userId = res.locals.userId;
+            const userInfo = await (0, provisioning_1.getOrProvisionUser)(client, tokenEntityRef, userId, provisioningEnabled, provisioningDefaults, roleConfigs, catalogClient, auth, logger);
+            // Check membership: user must be in the team OR be a team manager
+            const isMember = userInfo?.teams?.includes(teamId) ?? false;
+            // A "manager" administers this specific team: team management is enabled
+            // and the caller belongs to the team's owning group (metadata.owning_group).
+            // Membership of the global team-admin group alone is not enough.
+            let isManager = false;
+            // Skip the extra lookup when it can't change the outcome: members always
+            // get through, and manager-ness only matters for members when the budget
+            // hiding flags differ between the two roles.
+            const managerCheckNeeded = ctx.teamMgmtEnabled &&
+                (!isMember ||
+                    teamBudgetVisibility.hideTeamBudgetForMembers !==
+                        teamBudgetVisibility.hideTeamBudgetForManagers);
+            if (managerCheckNeeded) {
+                try {
+                    const team = await (0, teamFetch_1.withTeamFetchRetry)(() => client.getTeamInfo(teamId));
+                    const owningGroup = typeof team.metadata?.owning_group === 'string' ? team.metadata.owning_group : undefined;
+                    if (owningGroup) {
+                        isManager = await (0, provisioning_1.isUserMemberOfGroup)(tokenEntityRef, owningGroup, catalogClient, auth, logger);
+                    }
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    logger.warn(`Team-manager check failed: ${message}`);
+                }
+            }
+            if (!isMember && !isManager) {
+                res.status(404).json({ error: 'Team not found' });
+                return;
+            }
+            const usage = await client.getTeamUsage(teamId, start_date, end_date);
+            // Spend figures would let a client derive a hidden budget
+            // (budget = spend / pct), so they follow the same hiding flags.
+            // Which flag applies depends on whether the caller is a team manager;
+            // catalog failures fail closed to the member rule.
+            let hide = teamBudgetVisibility.hideTeamBudgetForMembers;
+            if (isManager) {
+                hide = teamBudgetVisibility.hideTeamBudgetForManagers;
+            }
+            res.json(hide ? (0, teamBudgetVisibility_1.redactTeamUsage)(usage) : usage);
+        }
+        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 usage');
+        }
+    });
+}

package/dist/routes/teams.d.ts

@@ -0,0 +1,3 @@
+import { Router } from 'express';
+import type { RouterContext } from './context';
+export declare function registerTeamsRoutes(router: Router, ctx: RouterContext): void;