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

package/dist/router.js

@@ -37,88 +37,60 @@ exports.ProvisioningError = void 0;
 exports.createRouter = createRouter;
 const express_1 = __importStar(require("express"));
 const plugin_permission_common_1 = require("@backstage/plugin-permission-common");
+const errors_1 = require("@backstage/errors");
 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 backstage_plugin_litellm_common_1 = require("@acarmisc/backstage-plugin-litellm-common");
 const teamAdmin_1 = require("./teamAdmin");
 const teamBudgetVisibility_1 = require("./teamBudgetVisibility");
 const opencode_1 = require("./opencode");
-const teamCreateInFlight = new Map();
-/** Backoff schedule for `withTeamFetchRetry` — 3 retries over ~1.3s total. */
-const TEAM_FETCH_RETRY_DELAYS_MS = [100, 300, 900];
-/**
- * Only 5xx (and network/timeout) failures are treated as transient — a 4xx
- * like "team not found" or "forbidden" is a deterministic answer from the
- * upstream and retrying it would just add latency for the same result.
- */
-function isRetryableTeamFetchError(err) {
-    if (err instanceof client_1.LiteLLMUpstreamError) {
-        return err.status >= 500;
-    }
-    return true;
-}
-/**
- * Retries a LiteLLM team-info fetch with the given backoff schedule.
- *
- * LiteLLM proxies are commonly run behind multiple replicas; a request can
- * land on a replica that hasn't yet caught up with a very recent write
- * (team create/update, membership change), or on one that is transiently
- * unhealthy. Both surface as a failed `getTeamInfo` call that would
- * otherwise be swallowed (e.g. GET /teams silently drops the team from the
- * response) or bubble up as a spurious 500/404 right after a write this
- * same request just made. A short retry smooths over that window without
- * masking a genuine, persistent failure.
- */
-async function withTeamFetchRetry(fn, delaysMs = TEAM_FETCH_RETRY_DELAYS_MS) {
-    for (let attempt = 0;; attempt++) {
-        try {
-            return await fn();
-        }
-        catch (err) {
-            if (attempt >= delaysMs.length || !isRetryableTeamFetchError(err)) {
-                throw err;
-            }
-            await new Promise(resolve => setTimeout(resolve, delaysMs[attempt]));
-        }
-    }
-}
-/**
- * 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;
-    }
-}
+const errors_2 = require("./errors");
+const withUser_1 = require("./routes/middleware/withUser");
+const userInfoCache_1 = require("./services/userInfoCache");
+const config_1 = require("./routes/config");
+const keys_1 = require("./routes/keys");
+const opencode_2 = require("./routes/opencode");
+const teams_1 = require("./routes/teams");
+const objectPermissions_1 = require("./routes/objectPermissions");
+const teamUsage_1 = require("./routes/teamUsage");
+const bridge_1 = require("./routes/bridge");
+const teamFetch_1 = require("./http/teamFetch");
 async function createRouter(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');
     // Publicly reachable LiteLLM proxy URL, used to build ready-to-paste
-    // snippets in the frontend. Falls back to baseUrl (the internal URL the
-    // backend calls) when the operator has not configured a public one.
-    const publicBaseUrl = config.getOptionalString('litellm.publicBaseUrl') ?? baseUrl;
-    const client = options.client ?? new client_1.LiteLLMClient({ baseUrl, masterKey });
+    // snippets in the frontend. Only exposed if explicitly configured.
+    // When unset, returned as null to the FE.
+    const publicBaseUrl = config.getOptionalString('litellm.publicBaseUrl') ?? null;
+    // Support contact for unprovisioned users (optional).
+    const supportContact = config.getOptionalString('litellm.supportContact');
+    const baseClient = options.client ?? new client_1.LiteLLMClient({ baseUrl, masterKey });
+    // Wrap client with userInfoCache. TTL is configurable (default 10s, 0 disables).
+    const userInfoCacheTtlSeconds = config.getOptionalNumber('litellm.cache.userInfoTtlSeconds') ?? 10;
+    const client = userInfoCacheTtlSeconds > 0
+        ? (0, userInfoCache_1.withUserInfoCache)(baseClient, { ttlMs: userInfoCacheTtlSeconds * 1000 })
+        : baseClient;
     const { enabled: provisioningEnabled, defaults: provisioningDefaults } = (0, provisioning_1.readProvisioningDefaults)(config);
     const roleConfigs = (0, provisioning_1.readRoleConfigs)(config);
     const auditGroup = config.getOptionalString('litellm.audit.group');
     const allowUnlimitedBudget = config.getOptionalBoolean('litellm.keyGeneration.allowUnlimitedBudget') ?? false;
     const teamRequired = config.getOptionalBoolean('litellm.keyGeneration.teamRequired') ?? true;
+    const allowOwnerResetSpend = config.getOptionalBoolean('litellm.keys.allowOwnerResetSpend') ?? false;
+    // Key validation ceilings (PR-2)
+    const keyMaxBudget = config.getOptionalNumber('litellm.keys.maxBudget') ?? 100;
+    const keyMaxTpm = config.getOptionalNumber('litellm.keys.maxTpm') ?? 100000;
+    const keyMaxRpm = config.getOptionalNumber('litellm.keys.maxRpm') ?? 1000;
+    const keyAllowedDurations = config.getOptionalStringArray('litellm.keys.allowedDurations') ?? backstage_plugin_litellm_common_1.DEFAULT_KEY_DURATIONS;
+    const keyValidationConfig = {
+        maxBudget: keyMaxBudget,
+        maxTpm: keyMaxTpm,
+        maxRpm: keyMaxRpm,
+        allowedDurations: keyAllowedDurations,
+    };
     const teamMgmtEnabled = (0, teamAdmin_1.isTeamManagementEnabled)(config);
     const objectPermsEnabled = (0, teamAdmin_1.isObjectPermissionsEnabled)(config);
     const teamAdminCfg = (0, teamAdmin_1.readTeamAdminConfig)(config);
@@ -137,1312 +109,179 @@ async function createRouter(options) {
         teamBudgetVisibility.hideTeamBudgetForManagers) {
         logger.info(`LiteLLM team budget hiding enabled — members: ${teamBudgetVisibility.hideTeamBudgetForMembers}, managers: ${teamBudgetVisibility.hideTeamBudgetForManagers}`);
     }
-    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
-    // plugin-router level, so each plugin must attach its own.
-    router.use(express_1.default.json());
-    router.get('/health', (_req, res) => {
-        res.json({ status: 'ok', provisioning: provisioningEnabled });
-    });
-    // Exposes the public LiteLLM proxy URL so the frontend can build
-    // ready-to-paste curl / OpenAI-SDK snippets for freshly generated keys.
-    router.get('/config', (_req, res) => {
-        res.json({
-            baseUrl: publicBaseUrl,
-            keyGeneration: { allowUnlimitedBudget, teamRequired },
-            opencode: { enabled: opencodeCfg.enabled },
-            teamManagement: {
-                enabled: teamMgmtEnabled,
-                maxBudgetCeiling: teamAdminCfg.maxBudgetCeiling,
-                allowUnlimitedBudget: teamAdminCfg.allowUnlimitedBudget,
-                objectPermissionsEnabled: objectPermsEnabled,
-            },
-            display: {
-                hideTeamBudgetForMembers: teamBudgetVisibility.hideTeamBudgetForMembers,
-                hideTeamBudgetForManagers: teamBudgetVisibility.hideTeamBudgetForManagers,
-            },
-        });
-    });
-    // Self-hosted OpenAPI 3.1 contract — lets integrators read a spec instead
-    // of router.ts. No swagger-ui dependency; serve the JSON and point external
-    // renderers (Stoplight, Swagger UI hosted elsewhere) at this endpoint.
-    router.get('/openapi.json', (_req, res) => {
-        res.json(openapi_1.openApiSpec);
-    });
-    // Provisioning dry-run: resolves which role a Backstage group maps to and
-    // echoes the effective defaults, collapsing the config → deploy → test loop
-    // into one request. Admin-gated by the audit group (same RBAC as /audit).
-    router.get('/provisioning/preview', async (req, res) => {
-        if (!auditGroup) {
-            res.status(403).json({ error: 'Preview is not configured (litellm.audit.group not set)' });
-            return;
-        }
-        const tokenEntityRef = await (0, provisioning_1.resolveUserId)(req, auth);
-        if (!tokenEntityRef) {
-            res.status(401).json({ error: 'Authentication required' });
-            return;
-        }
-        const allowed = await (0, provisioning_1.isUserMemberOfGroup)(tokenEntityRef, auditGroup, catalogClient, auth, logger);
-        if (!allowed) {
-            res.status(403).json({ error: 'Access denied: not a member of the audit group' });
-            return;
-        }
-        const group = req.query.group?.trim();
-        if (!group) {
-            res.status(400).json({ error: 'group query parameter is required (e.g. group=group:default/ai-platform)' });
-            return;
-        }
-        if (!roleConfigs.length) {
-            res.json({
-                group,
-                matched_role: null,
-                effective_defaults: provisioningDefaults,
-                note: 'No litellm.provisioning.roles configured — every group receives the base defaults.',
-            });
-            return;
-        }
-        try {
-            const matched = roleConfigs.find(rc => rc.group === group);
-            const effective = matched
-                ? (0, provisioning_1.applyRoleOverrides)(provisioningDefaults, matched)
-                : provisioningDefaults;
-            res.json({
-                group,
-                matched_role: matched?.group ?? null,
-                effective_defaults: effective,
-            });
-        }
-        catch (error) {
-            logger.error('Failed to resolve provisioning preview', error);
-            res.status(500).json({ error: error.message });
-        }
-    });
-    router.get('/user/info', async (req, res) => {
-        try {
-            const tokenEntityRef = await (0, provisioning_1.resolveUserId)(req, auth);
-            const userId = tokenEntityRef
-                ? (0, provisioning_1.toLiteLLMUserId)(tokenEntityRef, userIdDomain)
-                : req.query.user_id;
-            const userInfo = await (0, provisioning_1.getOrProvisionUser)(client, tokenEntityRef, userId, provisioningEnabled, provisioningDefaults, roleConfigs, catalogClient, auth, logger);
-            const canViewAudit = auditGroup && tokenEntityRef
-                ? await (0, provisioning_1.isUserMemberOfGroup)(tokenEntityRef, auditGroup, catalogClient, auth, logger)
-                : false;
-            res.json({ ...userInfo, can_view_audit: canViewAudit });
-        }
-        catch (error) {
-            if (error instanceof provisioning_1.ProvisioningError) {
-                res.status(error.status).json(error.body);
-                return;
-            }
-            logger.error('Failed to fetch user info', error);
-            res.status(500).json({ error: error.message });
-        }
-    });
-    router.get('/keys', async (req, res) => {
-        try {
-            const tokenEntityRef = await (0, provisioning_1.resolveUserId)(req, auth);
-            const userId = tokenEntityRef
-                ? (0, provisioning_1.toLiteLLMUserId)(tokenEntityRef, userIdDomain)
-                : req.query.user_id;
-            await (0, provisioning_1.getOrProvisionUser)(client, tokenEntityRef, userId, provisioningEnabled, provisioningDefaults, roleConfigs, catalogClient, auth, logger);
-            const keys = await client.listKeys(userId);
-            res.json(keys);
-        }
-        catch (error) {
-            if (error instanceof provisioning_1.ProvisioningError) {
-                res.status(error.status).json(error.body);
-                return;
+    // Build shared RouterContext with config and helpers
+    const ctx = {
+        client,
+        catalogClient,
+        auth,
+        permissions,
+        logger,
+        baseUrl,
+        publicBaseUrl,
+        supportContact,
+        userIdDomain,
+        provisioningEnabled,
+        provisioningDefaults,
+        roleConfigs,
+        auditGroup,
+        allowUnlimitedBudget,
+        teamRequired,
+        allowOwnerResetSpend,
+        keyValidationConfig,
+        teamMgmtEnabled,
+        objectPermsEnabled,
+        teamAdminCfg,
+        teamBudgetVisibility,
+        opencodeCfg,
+        // Helper functions - defined inline below this object
+        authorizeKeyAction: async (req, keyId) => {
+            // Express middleware should have populated req.res.locals with user info
+            if (!req.res || !req.res.locals.tokenEntityRef || !req.res.locals.userId) {
+                throw new errors_1.NotAllowedError('User identity not found in request');
+            }
+            const tokenEntityRef = req.res.locals.tokenEntityRef;
+            const userId = req.res.locals.userId;
+            const ownKeys = await client.listKeys(userId);
+            const key = ownKeys.find(k => (k.token ?? k.key) === keyId);
+            if (!key) {
+                throw new errors_1.NotAllowedError('Access denied: key does not belong to the caller');
+            }
+            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;
+                }
             }
-            logger.error('Failed to list keys', error);
-            res.status(500).json({ error: error.message });
-        }
-    });
-    // ── Key ownership guard ──────────────────────────────────────────────────
-    //
-    // Every key-mutation route below runs under the LiteLLM master key, so
-    // without an explicit check any authenticated Backstage user could act on
-    // any key whose token they learn (audit logs expose truncated tokens, and
-    // anyone who has held the raw key knows it). We fetch the caller's own key
-    // list and 403 if the target token isn't in it.
-    //
-    // Returns the caller's LiteLLM user_id (when resolvable) so handlers can
-    // stamp it in logs without re-deriving it.
-    async function authorizeKeyAction(req, keyId) {
-        const tokenEntityRef = await (0, provisioning_1.resolveUserId)(req, auth);
-        const userId = tokenEntityRef
-            ? (0, provisioning_1.toLiteLLMUserId)(tokenEntityRef, userIdDomain)
-            : req.query.user_id;
-        if (!userId) {
-            throw Object.assign(new Error('Cannot verify key ownership without an authenticated user'), {
-                status: 403,
-                body: { error: 'Cannot verify key ownership without an authenticated user' },
+            return false;
+        },
+        assertPermission: async (req, permission) => {
+            const credentials = await (0, provisioning_1.resolveCredentials)(req, auth);
+            if (!credentials)
+                return false;
+            const [decision] = await permissions.authorize([{ permission }], {
+                credentials,
             });
-        }
-        const ownKeys = await client.listKeys(userId);
-        const owns = ownKeys.some(k => (k.token ?? k.key) === keyId);
-        if (!owns) {
-            throw Object.assign(new Error('Access denied: key does not belong to the caller'), {
-                status: 403,
-                body: { error: 'Access denied: key does not belong to the caller' },
+            return decision.result === plugin_permission_common_1.AuthorizeResult.ALLOW;
+        },
+        sendPermissionDenied: (res, permission) => {
+            res.status(403).json({
+                error: `Access denied: missing permission "${permission.name}"`,
             });
-        }
-        return { tokenEntityRef, userId };
-    }
-    // Normalize the ownership-guard rejection shape into a response.
-    function sendOwnershipError(err, res) {
-        if (err && typeof err.status === 'number' && err.body) {
-            res.status(err.status).json(err.body);
-            return true;
-        }
-        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
-            // number caps spend, while null/undefined means "unlimited" (LiteLLM
-            // supports null). An empty models array is intentional — in LiteLLM
-            // `models: []` means "all models the user can access" which is the
-            // desired default. Forcing a selection up front is too restrictive for
-            // the common case.
-            const body = (req.body ?? {});
-            const missing = [];
-            if (!body.alias?.trim())
-                missing.push('alias');
-            if (body.max_budget !== null &&
-                body.max_budget !== undefined &&
-                (typeof body.max_budget !== 'number' || body.max_budget <= 0)) {
-                missing.push('max_budget (positive number, or null for unlimited)');
-            }
-            if (missing.length) {
-                res.status(400).json({
-                    error: 'Missing required fields',
-                    hint: `Required: ${missing.join(', ')}`,
-                });
-                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)
-                : undefined;
-            if (resolvedUserId) {
-                await (0, provisioning_1.getOrProvisionUser)(client, tokenEntityRef, resolvedUserId, provisioningEnabled, provisioningDefaults, roleConfigs, catalogClient, auth, logger);
-            }
-            // Stamp ownership into LiteLLM key metadata. LiteLLM's native
-            // `created_by` column is only populated when the caller authenticates
-            // via JWT/SSO; we always call with the master key, so that column
-            // stays null. Enriching `metadata` makes the owner identity visible
-            // in LiteLLM's UI and queryable via API.
-            const profile = tokenEntityRef
-                ? await (0, provisioning_1.resolveUserProfile)(tokenEntityRef, catalogClient, auth, logger)
-                : {};
-            const enrichedMetadata = {
-                ...(body.metadata ?? {}),
-                created_by_backstage_user: tokenEntityRef ?? 'unknown',
-                ...(profile.email && { created_by_email: profile.email }),
-                ...(profile.displayName && {
-                    created_by_display_name: profile.displayName,
-                }),
-                created_via: 'backstage',
-                created_at_iso: new Date().toISOString(),
-            };
-            const request = {
-                ...body,
-                metadata: enrichedMetadata,
-                ...(resolvedUserId && { user_id: resolvedUserId }),
-            };
-            const result = await client.generateKey(request);
-            logger.info({ action: 'key.generate', userId: resolvedUserId ?? 'unknown', keyAlias: body.alias });
-            res.json(result);
-        }
-        catch (error) {
-            if (error instanceof provisioning_1.ProvisioningError) {
-                res.status(error.status).json(error.body);
-                return;
-            }
-            // LiteLLM's enterprise team-key hook silently overrides the requested
-            // `duration` with the team's `metadata.team_member_key_duration` when a
-            // team_id is set, before parsing it. A malformed value there 500s with
-            // this exact message regardless of what we sent — surface that instead
-            // of the opaque passthrough so it's actionable from the LiteLLM side.
-            if (typeof error.message === 'string' &&
-                error.message.includes('Invalid duration format') &&
-                req.body?.team_id) {
-                res.status(502).json({
-                    error: 'LiteLLM rejected the key duration for this team. The team has a ' +
-                        '"Team Member Key Duration" set in LiteLLM that is not in a valid ' +
-                        '<number><unit> format (e.g. "30d") and overrides whatever duration ' +
-                        'is requested. Fix or clear it in LiteLLM under Teams → this team → ' +
-                        'Team Settings, then retry.',
-                    teamId: req.body.team_id,
-                });
-                return;
-            }
-            // Preserve upstream LiteLLM status + structured error (e.g. a 400 with
-            // param "key_alias" for a duplicate alias) so the frontend can
-            // distinguish "alias taken" from a genuine server error.
-            if (error instanceof client_1.LiteLLMUpstreamError) {
-                res.status(error.status).json({
-                    error: error.message,
-                    ...(error.param ? { param: error.param } : {}),
+        },
+        requireTeamMgmt: (res) => {
+            if (!teamMgmtEnabled) {
+                res.status(403).json({
+                    error: 'Team management is disabled (requires permission.enabled and litellm.teamAdmin.group)',
                 });
-                return;
+                return false;
             }
-            logger.error('Failed to generate key', error);
-            res.status(500).json({ error: error.message });
-        }
-    });
-    // ── 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) generate/reuse a virtual key bound to the
-    //       user and optional team → 302 {redirect_uri}?key=<api-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}`);
-        router.get('/opencode/connect', async (req, res) => {
-            try {
-                // The request comes from the browser (user session), so SSO
-                // auth applies exactly like for any other UI route.
-                const tokenEntityRef = await (0, provisioning_1.resolveUserId)(req, auth);
-                if (!tokenEntityRef) {
-                    res.status(401).json({ error: 'Authentication required' });
-                    return;
-                }
-                const redirectUri = req.query.redirect_uri;
-                if (!isValidRedirectUri(redirectUri)) {
-                    res.status(400).json({
-                        error: 'Invalid redirect_uri — expected http://localhost:<port>/callback',
-                    });
-                    return;
-                }
-                if (!(await assertPermission(req, permissions_1.litellmKeyCreatePermission))) {
-                    sendPermissionDenied(res, permissions_1.litellmKeyCreatePermission);
-                    return;
-                }
-                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 so
-                // the connect flow can never mint a key billed to someone else.
-                const teamId = req.query.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;
-                    }
-                }
-                else if (opencodeCfg.requireTeam) {
-                    res.status(400).json({ error: 'A team is required for this connection' });
-                    return;
-                }
-                // Alias is stable per user+team so re-connecting rotates the same
-                // logical key slot instead of accumulating duplicates. LiteLLM
-                // rejects duplicate aliases, so on conflict we look up the existing
-                // key and reuse it (the user gets a working connection either way).
-                const alias = teamId
-                    ? `opencode-${userId}-${teamId}`
-                    : `opencode-${userId}`;
-                const existing = await client
-                    .listKeys(userId)
-                    .catch(() => []);
-                // Reuse a healthy existing key for this slot rather than failing
-                // on the alias collision LiteLLM would raise. Blocked keys are
-                // skipped so a blocked slot can be recovered by re-connecting.
-                const reusable = existing.find(k => k.key_alias === alias &&
-                    !k.blocked &&
-                    k.user_id === userId);
-                let key;
-                if (reusable?.token ?? reusable?.key) {
-                    key = reusable.token ?? reusable.key;
-                }
-                else {
-                    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,
-                    });
-                    if (!result.key) {
-                        res.status(502).json({ error: 'LiteLLM returned no key material' });
-                        return;
-                    }
-                    key = result.key;
-                }
-                const url = new URL(redirectUri);
-                url.searchParams.set('key', key);
-                if (teamId)
-                    url.searchParams.set('team', teamId);
-                logger.info({
-                    action: 'opencode.connect',
-                    userId,
-                    team: teamId ?? null,
-                    reused: Boolean(reusable?.token ?? reusable?.key),
+            return true;
+        },
+        requireObjectPerms: (res) => {
+            if (!ctx.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)',
                 });
-                res.redirect(302, url.href);
+                return false;
             }
-            catch (error) {
-                if (error instanceof provisioning_1.ProvisioningError) {
-                    res.status(error.status).json(error.body);
-                    return;
-                }
-                logger.error('OpenCode connect failed', error);
-                res.status(500).json({ error: error.message });
-            }
-        });
-    }
-    router.post('/keys/:keyId/update', async (req, res) => {
-        try {
-            const { keyId } = req.params;
-            if (!keyId) {
-                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);
-            logger.info({ action: 'key.update', userId: tokenEntityRef ?? 'unknown', keyId });
-            res.json(result);
-        }
-        catch (error) {
-            if (sendOwnershipError(error, res))
-                return;
-            logger.error('Failed to update key', error);
-            res.status(500).json({ error: error.message });
-        }
-    });
-    router.delete('/keys/:keyId', async (req, res) => {
-        try {
-            const { keyId } = req.params;
-            if (!keyId) {
-                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 });
-            res.json({ success: true });
-        }
-        catch (error) {
-            if (sendOwnershipError(error, res))
-                return;
-            logger.error('Failed to delete key', error);
-            res.status(500).json({ error: error.message });
-        }
-    });
-    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 });
-            res.json({ success: true });
-        }
-        catch (error) {
-            if (sendOwnershipError(error, res))
-                return;
-            logger.error('Failed to block key', error);
-            res.status(500).json({ error: error.message });
-        }
-    });
-    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 });
-            res.json({ success: true });
-        }
-        catch (error) {
-            if (sendOwnershipError(error, res))
-                return;
-            logger.error('Failed to unblock key', error);
-            res.status(500).json({ error: error.message });
-        }
-    });
-    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;
+            return true;
+        },
+        sendTeamError: (err, res) => {
+            (0, errors_2.sendError)(res, err, logger, 'team operation');
+        },
+        authorizeTeamSubresource: async (req, res, permission) => {
+            if (!ctx.requireTeamMgmt(res))
+                return null;
+            if (!teamAdminCfg.group) {
+                res.status(500).json({ error: 'Team management is misconfigured (group is missing)' });
+                return null;
             }
-            const { tokenEntityRef } = await authorizeKeyAction(req, keyId);
-            await client.resetKeySpend(keyId);
-            logger.info({ action: 'key.reset_spend', userId: tokenEntityRef ?? 'unknown', keyId });
-            res.json({ success: true });
-        }
-        catch (error) {
-            if (sendOwnershipError(error, res))
-                return;
-            logger.error('Failed to reset key spend', error);
-            res.status(500).json({ error: error.message });
-        }
-    });
-    router.get('/audit', async (req, res) => {
-        if (!auditGroup) {
-            res.status(403).json({ error: 'Audit log is not configured (litellm.audit.group not set)' });
-            return;
-        }
-        const tokenEntityRef = await (0, provisioning_1.resolveUserId)(req, auth);
-        if (!tokenEntityRef) {
-            res.status(401).json({ error: 'Authentication required' });
-            return;
-        }
-        const allowed = await (0, provisioning_1.isUserMemberOfGroup)(tokenEntityRef, auditGroup, catalogClient, auth, logger);
-        if (!allowed) {
-            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({
-                page: page ? Number(page) : undefined,
-                page_size: page_size ? Number(page_size) : 25,
-                start_date,
-                end_date,
-                action,
-                table_name,
-                changed_by,
+            const check = await (0, teamAdmin_1.assertTeamAdmin)({
+                req,
+                auth,
+                permissions,
+                catalogClient,
+                teamAdminGroup: teamAdminCfg.group,
+                permission,
+                logger,
             });
-            res.json(result);
-        }
-        catch (error) {
-            logger.error('Failed to fetch audit logs', error);
-            res.status(500).json({ error: error.message });
-        }
-    });
-    router.get('/models', async (_req, res) => {
-        try {
-            const models = await client.listModels();
-            res.json(models);
-        }
-        catch (error) {
-            logger.error('Failed to list models', error);
-            res.status(500).json({ error: error.message });
-        }
-    });
-    router.get('/teams', async (req, res) => {
-        try {
-            const tokenEntityRef = await (0, provisioning_1.resolveUserId)(req, auth);
-            const userId = tokenEntityRef
-                ? (0, provisioning_1.toLiteLLMUserId)(tokenEntityRef, userIdDomain)
-                : req.query.user_id;
-            const userInfo = await (0, provisioning_1.getOrProvisionUser)(client, tokenEntityRef, userId, provisioningEnabled, provisioningDefaults, roleConfigs, catalogClient, auth, logger);
-            if (!userInfo?.teams?.length) {
-                res.json([]);
-                return;
+            if (!check.ok) {
+                res.status(check.status).json({ error: check.error });
+                return null;
             }
-            const teams = await Promise.all(userInfo.teams.map(teamId => withTeamFetchRetry(() => client.getTeamInfo(teamId)).catch(err => {
-                logger.warn(`Failed to fetch team ${teamId} after retries: ${err.message}`);
+            const { teamId } = req.params;
+            if (!teamId) {
+                res.status(400).json({ error: 'teamId is required' });
                 return null;
-            })));
-            const list = teams.filter(Boolean);
-            // Member surface: strip dollar amounts when the operator hides them
-            // from members. Managers who need the numbers use /teams/managed.
-            res.json(teamBudgetVisibility.hideTeamBudgetForMembers
-                ? list.map(teamBudgetVisibility_1.redactTeamBudget)
-                : list);
-        }
-        catch (error) {
-            if (error instanceof provisioning_1.ProvisioningError) {
-                res.status(error.status).json(error.body);
-                return;
             }
-            logger.error('Failed to fetch teams', error);
-            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`);
+            let existing;
             try {
-                const result = await pending;
-                res.json(result);
+                existing = await (0, teamFetch_1.withTeamFetchRetry)(() => client.getTeamInfo(teamId));
             }
             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;
-            // Manager surface: redact dollars when hidden even from managers.
-            res.json(teamBudgetVisibility.hideTeamBudgetForManagers
-                ? (0, teamBudgetVisibility_1.redactTeamBudget)(result)
-                : 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(teamBudgetVisibility.hideTeamBudgetForManagers
-                ? (0, teamBudgetVisibility_1.redactTeamBudget)(r)
-                : 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);
-            // Manager surface: strip dollar amounts when hidden even from managers.
-            res.json(teamBudgetVisibility.hideTeamBudgetForManagers
-                ? owned.map(teamBudgetVisibility_1.redactTeamBudget)
-                : 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 withTeamFetchRetry(() => client.getTeamInfo(teamId));
-        }
-        catch (err) {
-            if (err instanceof client_1.LiteLLMUpstreamError && err.status === 404) {
-                res.status(404).json({ error: 'Team not found' });
+                if (err instanceof client_1.LiteLLMUpstreamError && err.status === 404) {
+                    res.status(404).json({ error: 'Team not found' });
+                    return null;
+                }
+                ctx.sendTeamError(err, res);
                 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`,
+            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;
+                return null;
             }
-        }
-        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;
+            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;
             }
-            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 withTeamFetchRetry(() => client.getTeamInfo(teamId));
-            res.json(teamBudgetVisibility.hideTeamBudgetForManagers
-                ? (0, teamBudgetVisibility_1.redactTeamBudget)(updated)
-                : 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,
+            return {
                 teamId,
-                member: litellmUserId,
                 owningGroup,
-            });
-            const updated = await withTeamFetchRetry(() => client.getTeamInfo(teamId));
-            res.json(teamBudgetVisibility.hideTeamBudgetForManagers
-                ? (0, teamBudgetVisibility_1.redactTeamBudget)(updated)
-                : 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(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;
-        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(teamBudgetVisibility.hideTeamBudgetForManagers
-                ? (0, teamBudgetVisibility_1.redactTeamBudget)(updated)
-                : updated);
-        }
-        catch (err) {
-            sendTeamError(err, res);
-        }
-    });
-    router.get('/teams/:teamId/usage', 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;
-            }
-            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 (teamAdminCfg.group) {
-                try {
-                    const tokenEntityRef = await (0, provisioning_1.resolveUserId)(req, auth);
-                    const isManager = !!tokenEntityRef &&
-                        (await (0, provisioning_1.isUserMemberOfGroup)(tokenEntityRef, teamAdminCfg.group, catalogClient, auth, logger));
-                    hide = isManager
-                        ? teamBudgetVisibility.hideTeamBudgetForManagers
-                        : teamBudgetVisibility.hideTeamBudgetForMembers;
-                }
-                catch (err) {
-                    logger.warn(`Team-manager check failed, hiding team spend: ${err.message}`);
-                    hide = teamBudgetVisibility.hideTeamBudgetForMembers;
-                }
-            }
-            res.json(hide ? (0, teamBudgetVisibility_1.redactTeamUsage)(usage) : usage);
-        }
-        catch (error) {
-            logger.error('Failed to fetch team usage', error);
-            res.status(500).json({ error: error.message });
-        }
-    });
-    router.get('/usage', async (req, res) => {
-        try {
-            const { start_date, end_date } = req.query;
-            if (!start_date || !end_date) {
-                res.status(400).json({ error: 'start_date and end_date are required' });
-                return;
-            }
-            const tokenEntityRef = await (0, provisioning_1.resolveUserId)(req, auth);
-            const userId = tokenEntityRef
-                ? (0, provisioning_1.toLiteLLMUserId)(tokenEntityRef, userIdDomain)
-                : req.query.user_id;
-            if (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);
-            res.json(usage);
-        }
-        catch (error) {
-            if (error instanceof provisioning_1.ProvisioningError) {
-                res.status(error.status).json(error.body);
-                return;
-            }
-            logger.error('Failed to fetch usage', error);
-            res.status(500).json({ error: error.message });
-        }
-    });
-    // ---------------------------------------------------------------------------
-    // Bridge endpoints (CLI / Abby)
-    //
-    // Authenticated by a Keycloak access token (JWKS-verified), NOT by Backstage's
-    // own auth. Lets CLI clients list/mint virtual keys without holding the master
-    // key. Gated by litellm.bridge.enabled; the verifier needs litellm.bridge.issuer.
-    const bridgeCfg = (0, bridge_1.readBridgeConfig)(config);
-    let tokenVerifier = options.tokenVerifier;
-    if (bridgeCfg.enabled && !tokenVerifier) {
-        try {
-            tokenVerifier = (0, bridge_1.newDefaultVerifier)(bridgeCfg);
-        }
-        catch (e) {
-            logger.error(`LiteLLM bridge enabled but misconfigured: ${e.message}`);
-        }
-    }
-    if (bridgeCfg.enabled && tokenVerifier) {
-        const requireClaims = async (req) => {
-            const header = req.headers.authorization ?? '';
-            const token = header.startsWith('Bearer ') ? header.slice(7) : '';
-            if (!token)
-                throw new bridge_1.BridgeAuthError('missing Bearer token');
-            return tokenVerifier.verify(token);
-        };
-        const handleBridgeError = (error, res) => {
-            if (error instanceof bridge_1.BridgeAuthError) {
-                res.status(401).json({ error: 'unauthorized', hint: error.message });
-                return;
-            }
-            if (error instanceof provisioning_1.ProvisioningError) {
-                res.status(error.status).json(error.body);
-                return;
-            }
-            logger.error('Bridge request failed', error);
-            res.status(500).json({ error: error.message });
-        };
-        router.get('/bridge/health', (_req, res) => {
-            res.json({ status: 'ok', bridge: true, clientId: bridgeCfg.clientId });
-        });
-        router.get('/bridge/keys', async (req, res) => {
-            try {
-                const claims = await requireClaims(req);
-                const keys = await (0, bridge_1.bridgeListKeys)(client, claims, provisioningEnabled, provisioningDefaults, logger, userIdDomain);
-                res.json(keys);
-            }
-            catch (error) {
-                handleBridgeError(error, res);
-            }
-        });
-        router.post('/bridge/keys', async (req, res) => {
-            try {
-                const claims = await requireClaims(req);
-                const result = await (0, bridge_1.bridgeGenerateKey)(client, claims, provisioningEnabled, provisioningDefaults, logger, (req.body ?? {}), userIdDomain);
-                res.json(result);
-            }
-            catch (error) {
-                handleBridgeError(error, res);
-            }
-        });
-        router.get('/bridge/models', async (req, res) => {
-            try {
-                await requireClaims(req); // authenticate only
-                const models = await client.listModels();
-                res.json(models);
-            }
-            catch (error) {
-                handleBridgeError(error, res);
-            }
-        });
-    }
-    else if (bridgeCfg.enabled) {
-        logger.warn('litellm.bridge.enabled is true but no verifier could be built — bridge endpoints not mounted');
-    }
+                actor: check.userEntityRef,
+                team: existing,
+            };
+        },
+    };
+    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
+    // plugin-router level, so each plugin must attach its own.
+    router.use(express_1.default.json());
+    // URL-encoded form parser for POST /opencode/connect (confirmation form).
+    router.use(express_1.default.urlencoded({ extended: false }));
+    // User-scoped routes act on the caller's own LiteLLM identity. That identity
+    // comes ONLY from a verified Backstage user principal — never from the query
+    // string or body — so service/external principals (and anonymous callers)
+    // are rejected instead of being allowed to name an arbitrary user_id.
+    const requireUser = (0, withUser_1.createRequireUser)(ctx);
+    router.use(['/user/info', '/keys', '/usage'], requireUser);
+    // Register config routes (/health, /config, /openapi.json, /provisioning/preview)
+    (0, config_1.registerConfigRoutes)(router, ctx);
+    (0, keys_1.registerKeysRoutes)(router, ctx);
+    (0, opencode_2.registerOpencodeRoutes)(router, ctx);
+    (0, teams_1.registerTeamsRoutes)(router, ctx);
+    (0, objectPermissions_1.registerObjectPermissionsRoutes)(router, ctx);
+    (0, teamUsage_1.registerTeamUsageRoutes)(router, ctx);
+    (0, bridge_1.registerBridgeRoutes)(router, ctx, { config, tokenVerifier: options.tokenVerifier });
     return router;
 }