@acarmisc/backstage-plugin-litellm-backend 0.2.1 → 0.3.0

package/config.d.ts

@@ -97,5 +97,34 @@ export interface Config {
         metadata?: Record<string, string>;
       }>;
     };
+
+    /**
+     * CLI bridge — exposes /api/litellm/bridge/* for CLI clients (Abby) that
+     * authenticate with a Keycloak access token (JWKS-verified). Lets them
+     * list/mint virtual keys without holding the master key. Disabled by
+     * default; enable explicitly when the CLI is in use.
+     */
+    bridge?: {
+      /**
+       * When true, mount the /bridge/keys, /bridge/keys (POST), /bridge/models
+       * routes and verify caller JWTs against the Keycloak realm JWKS.
+       * @default false
+       */
+      enabled?: boolean;
+
+      /**
+       * Keycloak realm issuer used to fetch JWKS and verify the token issuer,
+       * e.g. https://auth.ces.abssrv.it/realms/solution-innovation.
+       * Required when enabled.
+       */
+      issuer?: string;
+
+      /**
+       * OIDC public client the CLI uses (default "abby-cli"). The token's
+       * azp (or aud) must equal this.
+       * @default "abby-cli"
+       */
+      clientId?: string;
+    };
   };
 }

package/dist/bridge.d.ts

@@ -0,0 +1,69 @@
+import { Config } from '@backstage/config';
+import { LiteLLMClient } from './client';
+import { GenerateKeyRequest, GenerateKeyResponse, ProvisioningDefaults, UserInfo, VirtualKey } from './types';
+/** Claims extracted from a verified Keycloak access token. */
+export interface BridgeClaims {
+    sub: string;
+    email?: string;
+    preferred_username?: string;
+    name?: string;
+    /** Authorized party — Keycloak sets this to the client_id of the requester. */
+    azp?: string;
+    aud?: string | string[];
+}
+/** A token verifier pluggable for tests. */
+export interface TokenVerifier {
+    verify(token: string): Promise<BridgeClaims>;
+}
+export interface BridgeConfig {
+    enabled: boolean;
+    /** Keycloak realm issuer, e.g. https://auth.ces.abssrv.it/realms/solution-innovation. */
+    issuer?: string;
+    /** OIDC public client the CLI uses; checked against azp / aud. */
+    clientId: string;
+}
+export declare function readBridgeConfig(config: Config): BridgeConfig;
+/** Thrown when the bridge is misconfigured (e.g. enabled without an issuer). */
+export declare class BridgeConfigError extends Error {
+}
+/** Thrown when a presented token fails verification → maps to HTTP 401. */
+export declare class BridgeAuthError extends Error {
+    readonly status = 401;
+}
+export interface KeycloakJWTVerifierOptions {
+    issuer: string;
+    clientId: string;
+}
+/**
+ * Verifies a Keycloak access token against the realm JWKS and ensures it was
+ * issued for {@link clientId} (via azp, falling back to aud). Uses jose's
+ * remote JWKS client (cached, with cooldown on errors).
+ */
+export declare class KeycloakJWTVerifier implements TokenVerifier {
+    private readonly issuer;
+    private readonly clientId;
+    private readonly jwks;
+    constructor(opts: KeycloakJWTVerifierOptions);
+    verify(token: string): Promise<BridgeClaims>;
+}
+/** Builds the default verifier from config, or throws BridgeConfigError. */
+export declare function newDefaultVerifier(cfg: BridgeConfig): TokenVerifier;
+/** Picks the LiteLLM user_id from the verified claims (email → username → sub). */
+export declare function resolveBridgeUserId(claims: BridgeClaims): string;
+/**
+ * Ensures a LiteLLM user exists for the verified identity. If the user is
+ * missing and provisioning is enabled, creates it from the JWT claims (email +
+ * name); if provisioning is disabled, throws a 404 telling the caller to log
+ * in to Backstage first (the UI is the primary provisioning entry point).
+ */
+export declare function getOrProvisionUserFromClaims(client: LiteLLMClient, claims: BridgeClaims, provisioningEnabled: boolean, provisioningDefaults: ProvisioningDefaults, logger: {
+    info: (...args: unknown[]) => void;
+}): Promise<UserInfo>;
+/** Lists the caller's virtual keys (provisioning the user first if needed). */
+export declare function bridgeListKeys(client: LiteLLMClient, claims: BridgeClaims, provisioningEnabled: boolean, provisioningDefaults: ProvisioningDefaults, logger: {
+    info: (...args: unknown[]) => void;
+}): Promise<VirtualKey[]>;
+/** Mints a new virtual key for the caller (provisioning the user first if needed). */
+export declare function bridgeGenerateKey(client: LiteLLMClient, claims: BridgeClaims, provisioningEnabled: boolean, provisioningDefaults: ProvisioningDefaults, logger: {
+    info: (...args: unknown[]) => void;
+}, request: Partial<GenerateKeyRequest>): Promise<GenerateKeyResponse>;

package/dist/bridge.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeycloakJWTVerifier = exports.BridgeAuthError = exports.BridgeConfigError = void 0;
+exports.readBridgeConfig = readBridgeConfig;
+exports.newDefaultVerifier = newDefaultVerifier;
+exports.resolveBridgeUserId = resolveBridgeUserId;
+exports.getOrProvisionUserFromClaims = getOrProvisionUserFromClaims;
+exports.bridgeListKeys = bridgeListKeys;
+exports.bridgeGenerateKey = bridgeGenerateKey;
+/**
+ * Bridge — lets CLI clients (Abby) list/mint LiteLLM virtual keys without ever
+ * holding the LiteLLM master key.
+ *
+ * Trust model: the Backstage backend holds the master key (as it already does
+ * for the UI). A CLI authenticates with its Keycloak access token (the same
+ * Keycloak realm Backstage uses). This module verifies that JWT against the
+ * realm JWKS, resolves the caller to a LiteLLM user_id, ensures that user
+ * exists (provisioning from claims if enabled), and then lists/generates keys
+ * via the existing master-key-authed {@link LiteLLMClient}.
+ *
+ * Unlike the UI endpoints in router.ts, the bridge routes do NOT call
+ * Backstage's `auth.authenticate` (which expects a Backstage-issued token);
+ * they verify the raw Keycloak JWT themselves.
+ */
+const jose_1 = require("jose");
+const provisioning_1 = require("./provisioning");
+function readBridgeConfig(config) {
+    const enabled = config.getOptionalBoolean('litellm.bridge.enabled') ?? false;
+    const issuer = config.getOptionalString('litellm.bridge.issuer');
+    const clientId = config.getOptionalString('litellm.bridge.clientId') ?? 'abby-cli';
+    return { enabled, issuer, clientId };
+}
+/** Thrown when the bridge is misconfigured (e.g. enabled without an issuer). */
+class BridgeConfigError extends Error {
+}
+exports.BridgeConfigError = BridgeConfigError;
+/** Thrown when a presented token fails verification → maps to HTTP 401. */
+class BridgeAuthError extends Error {
+    constructor() {
+        super(...arguments);
+        this.status = 401;
+    }
+}
+exports.BridgeAuthError = BridgeAuthError;
+/**
+ * Verifies a Keycloak access token against the realm JWKS and ensures it was
+ * issued for {@link clientId} (via azp, falling back to aud). Uses jose's
+ * remote JWKS client (cached, with cooldown on errors).
+ */
+class KeycloakJWTVerifier {
+    constructor(opts) {
+        this.issuer = opts.issuer.replace(/\/$/, '');
+        this.clientId = opts.clientId;
+        this.jwks = (0, jose_1.createRemoteJWKSet)(new URL(`${this.issuer}/protocol/openid-connect/certs`));
+    }
+    async verify(token) {
+        let payload;
+        try {
+            const result = await (0, jose_1.jwtVerify)(token, this.jwks, {
+                issuer: this.issuer,
+            });
+            payload = result.payload;
+        }
+        catch (err) {
+            // Expired, bad signature, wrong issuer, malformed, JWKS unreachable, etc.
+            throw new BridgeAuthError(`invalid keycloak token: ${err.message ?? err}`);
+        }
+        const azp = payload.azp;
+        const aud = payload.aud;
+        const audMatches = Array.isArray(aud)
+            ? aud.includes(this.clientId)
+            : aud === this.clientId;
+        if (azp !== this.clientId && !audMatches) {
+            throw new BridgeAuthError(`token not issued for client "${this.clientId}" (azp=${azp ?? 'none'})`);
+        }
+        return {
+            sub: payload.sub ?? '',
+            email: payload.email,
+            preferred_username: payload
+                .preferred_username,
+            name: payload.name,
+            azp,
+            aud,
+        };
+    }
+}
+exports.KeycloakJWTVerifier = KeycloakJWTVerifier;
+/** Builds the default verifier from config, or throws BridgeConfigError. */
+function newDefaultVerifier(cfg) {
+    if (!cfg.issuer) {
+        throw new BridgeConfigError('litellm.bridge.issuer is required when litellm.bridge.enabled is true ' +
+            '(e.g. https://auth.ces.abssrv.it/realms/solution-innovation)');
+    }
+    return new KeycloakJWTVerifier({ issuer: cfg.issuer, clientId: cfg.clientId });
+}
+/** Picks the LiteLLM user_id from the verified claims (email → username → sub). */
+function resolveBridgeUserId(claims) {
+    return claims.email ?? claims.preferred_username ?? claims.sub;
+}
+/**
+ * Ensures a LiteLLM user exists for the verified identity. If the user is
+ * missing and provisioning is enabled, creates it from the JWT claims (email +
+ * name); if provisioning is disabled, throws a 404 telling the caller to log
+ * in to Backstage first (the UI is the primary provisioning entry point).
+ */
+async function getOrProvisionUserFromClaims(client, claims, provisioningEnabled, provisioningDefaults, logger) {
+    const userId = resolveBridgeUserId(claims);
+    const existing = await client.getUserInfo(userId);
+    if (existing)
+        return existing;
+    if (!provisioningEnabled) {
+        throw new provisioning_1.ProvisioningError('User not found in LiteLLM', 'No LiteLLM user for this identity. Log in to Backstage once to be provisioned, or enable litellm.provisioning.enabled.', false);
+    }
+    const profile = {
+        email: claims.email ?? claims.preferred_username,
+        displayName: claims.name ?? claims.preferred_username,
+    };
+    const created = await (0, provisioning_1.provisionUser)(client, userId, provisioningDefaults, profile, undefined, logger);
+    if (!created) {
+        throw new provisioning_1.ProvisioningError('User not found in LiteLLM', 'Provisioning attempted but returned no user — check LiteLLM logs', true, 500);
+    }
+    return created;
+}
+/** Lists the caller's virtual keys (provisioning the user first if needed). */
+async function bridgeListKeys(client, claims, provisioningEnabled, provisioningDefaults, logger) {
+    await getOrProvisionUserFromClaims(client, claims, provisioningEnabled, provisioningDefaults, logger);
+    return client.listKeys(resolveBridgeUserId(claims));
+}
+/** Mints a new virtual key for the caller (provisioning the user first if needed). */
+async function bridgeGenerateKey(client, claims, provisioningEnabled, provisioningDefaults, logger, request) {
+    await getOrProvisionUserFromClaims(client, claims, provisioningEnabled, provisioningDefaults, logger);
+    const userId = resolveBridgeUserId(claims);
+    const enriched = {
+        ...request,
+        user_id: userId,
+        metadata: {
+            ...(request.metadata ?? {}),
+            created_via: 'abby-cli',
+            created_by: userId,
+            created_at_iso: new Date().toISOString(),
+        },
+    };
+    return client.generateKey(enriched);
+}

package/dist/client.d.ts

@@ -8,6 +8,11 @@ export declare class LiteLLMClient {
     /**
      * Returns null when the user is not found in LiteLLM (404).
      * Throws on all other errors so callers know something went wrong.
+     *
+     * LiteLLM's `/user/info` wraps the user row inside `user_info` and returns
+     * `teams` as an array of full team objects, not team_id strings. We flatten
+     * `user_info` onto the top level and reduce `teams` to a string[] of ids so
+     * the rest of the code can rely on the UserInfo contract.
      */
     getUserInfo(userId?: string): Promise<UserInfo | null>;
     createUser(payload: CreateUserRequest): Promise<CreateUserResponse>;
@@ -48,6 +53,16 @@ export declare class LiteLLMClient {
     deleteKeys(request: DeleteKeyRequest): Promise<{
         success: boolean;
     }>;
+    /**
+     * Returns the proxy's model catalogue normalised to the ModelInfo shape.
+     *
+     * Prefers `/model/info` which exposes `model_name`, `mode`, capability flags
+     * and per-token costs. Falls back to OpenAI-compatible `/models` (which only
+     * returns `{id}`) so the dropdown still works on installs where `/model/info`
+     * isn't reachable. Without this normalisation the UI saw blank labels and
+     * a single "other" group because `/models` doesn't populate `model_name`
+     * or `mode`.
+     */
     listModels(): Promise<ModelInfo[]>;
     getTeamInfo(teamId: string): Promise<TeamInfo>;
     private emptyUsage;

package/dist/client.js

@@ -36,11 +36,34 @@ class LiteLLMClient {
     /**
      * Returns null when the user is not found in LiteLLM (404).
      * Throws on all other errors so callers know something went wrong.
+     *
+     * LiteLLM's `/user/info` wraps the user row inside `user_info` and returns
+     * `teams` as an array of full team objects, not team_id strings. We flatten
+     * `user_info` onto the top level and reduce `teams` to a string[] of ids so
+     * the rest of the code can rely on the UserInfo contract.
      */
     async getUserInfo(userId) {
         const query = userId ? `?user_id=${encodeURIComponent(userId)}` : '';
         try {
-            return await this.request(`/user/info${query}`);
+            const raw = await this.request(`/user/info${query}`);
+            const inner = raw?.user_info ?? {};
+            const teamIds = Array.isArray(raw?.teams)
+                ? raw.teams
+                    .map((t) => (typeof t === 'string' ? t : t?.team_id))
+                    .filter((t) => typeof t === 'string')
+                : [];
+            return {
+                user_id: raw?.user_id ?? inner.user_id ?? userId ?? '',
+                user_email: inner.user_email ?? raw?.user_email,
+                email: inner.email ?? raw?.email,
+                teams: teamIds,
+                models: inner.models ?? raw?.models,
+                max_budget: inner.max_budget ?? raw?.max_budget,
+                spend: inner.spend ?? raw?.spend,
+                current_spend: inner.current_spend ?? raw?.current_spend,
+                soft_limit: inner.soft_limit ?? raw?.soft_limit,
+                hard_limit: inner.hard_limit ?? raw?.hard_limit,
+            };
         }
         catch (err) {
             if (err.status === 404)
@@ -143,9 +166,53 @@ class LiteLLMClient {
             body: JSON.stringify(request),
         });
     }
+    /**
+     * Returns the proxy's model catalogue normalised to the ModelInfo shape.
+     *
+     * Prefers `/model/info` which exposes `model_name`, `mode`, capability flags
+     * and per-token costs. Falls back to OpenAI-compatible `/models` (which only
+     * returns `{id}`) so the dropdown still works on installs where `/model/info`
+     * isn't reachable. Without this normalisation the UI saw blank labels and
+     * a single "other" group because `/models` doesn't populate `model_name`
+     * or `mode`.
+     */
     async listModels() {
-        const response = await this.request('/models');
-        return Array.isArray(response) ? response : response.data ?? [];
+        try {
+            const response = await this.request('/model/info');
+            const data = Array.isArray(response?.data) ? response.data : [];
+            const normalised = data.map((m) => {
+                const info = m.model_info ?? {};
+                const params = m.litellm_params ?? {};
+                return {
+                    model_name: m.model_name ?? params.model ?? info.id ?? '',
+                    mode: info.mode ?? m.mode ?? 'chat',
+                    supports_function_calling: info.supports_function_calling ?? m.supports_function_calling,
+                    supports_vision: info.supports_vision ?? m.supports_vision,
+                    input_cost_per_token: info.input_cost_per_token ?? params.input_cost_per_token,
+                    output_cost_per_token: info.output_cost_per_token ?? params.output_cost_per_token,
+                };
+            });
+            const filtered = normalised.filter(m => m.model_name);
+            if (filtered.length)
+                return filtered;
+        }
+        catch {
+            // fall through to /models
+        }
+        const fallback = await this.request('/models');
+        const data = Array.isArray(fallback)
+            ? fallback
+            : Array.isArray(fallback?.data)
+                ? fallback.data
+                : [];
+        return data
+            .map((m) => ({
+            model_name: m.model_name ?? m.id ?? '',
+            mode: m.mode ?? 'chat',
+            supports_function_calling: m.supports_function_calling,
+            supports_vision: m.supports_vision,
+        }))
+            .filter((m) => m.model_name);
     }
     async getTeamInfo(teamId) {
         return this.request(`/team/info?team_id=${encodeURIComponent(teamId)}`);