@acarmisc/backstage-plugin-litellm-backend 0.2.2 → 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);
+}