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

package/config.d.ts

@@ -390,6 +390,15 @@ export interface Config {
        * @default "abby-cli"
        */
       clientId?: string;
+
+      /**
+       * Email domains whose *verified* addresses may use the bridge. Defaults
+       * to `litellm.userIdDomain` when that is set. With neither configured
+       * the bridge rejects every caller. The LiteLLM user is then the same one
+       * the UI addresses (the Keycloak `preferred_username`, with
+       * `litellm.userIdDomain` applied when set) — the email is only the gate.
+       */
+      allowedEmailDomains?: string[];
     };
   };
 }

package/dist/bridge.d.ts

@@ -25,6 +25,12 @@ export interface BridgeConfig {
     issuer?: string;
     /** OIDC public client the CLI uses; checked against azp / aud. */
     clientId: string;
+    /**
+     * Email domains whose verified addresses may use the bridge. Defaults to
+     * `litellm.userIdDomain` when that is set; with neither, the bridge rejects
+     * every caller (fail closed).
+     */
+    allowedEmailDomains: string[];
 }
 export declare function readBridgeConfig(config: Config): BridgeConfig;
 /** Thrown when the bridge is misconfigured (e.g. enabled without an issuer). */
@@ -57,28 +63,41 @@ export declare class KeycloakJWTVerifier implements TokenVerifier {
 /** Builds the default verifier from config, or throws BridgeConfigError. */
 export declare function newDefaultVerifier(cfg: BridgeConfig): TokenVerifier;
 /**
- * Resolves the LiteLLM user_id from the verified claims with strict identity validation.
+ * How the bridge maps a verified token to a LiteLLM user.
+ * - `userIdDomain`: the same `litellm.userIdDomain` the UI uses to build ids.
+ * - `trustedEmailDomains`: email domains allowed to use the bridge; defaults to
+ *   `[userIdDomain]` when that is set.
+ */
+export interface BridgeIdentityOptions {
+    userIdDomain?: string;
+    trustedEmailDomains?: string[];
+}
+/**
+ * Resolves the LiteLLM user_id for a verified bridge token.
  *
- * PR-6 identity mapping:
- * - Prefer `email` with `email_verified === true` whose domain equals `userIdDomain`.
- * - If userIdDomain is unset, always reject unverified emails (guard against misconfig).
- * - Never strip an arbitrary domain from `preferred_username`.
- * - Rejects invalid/missing identity with 403.
+ * Two separate questions, answered separately:
+ * 1. Is this person allowed in? The token must carry a *verified* email whose
+ *    domain is in the trusted list (`litellm.bridge.allowedEmailDomains`,
+ *    defaulting to `litellm.userIdDomain`). With no trusted domain configured
+ *    everyone is rejected (fail closed). Failure → 403.
+ * 2. Which LiteLLM user are they? The same one the UI addresses: the Backstage
+ *    user entity name (the Keycloak `preferred_username`) run through the same
+ *    `litellm.userIdDomain` rule the UI applies. Using the email local part
+ *    here would address a different user whenever a Keycloak username differs
+ *    from the email (and would provision a duplicate). The realm is the same
+ *    IdP Backstage signs users in with, so its usernames are the entity names.
  *
- * @param claims Verified JWT claims from the bridge token
- * @param userIdDomain Expected email domain (e.g. "example.com"); if set, email must match
- * @returns The resolved LiteLLM user_id
  * @throws BridgeIdentityError (403) if identity validation fails
  */
-export declare function resolveBridgeUserId(claims: BridgeClaims, userIdDomain?: string): string;
+export declare function resolveBridgeUserId(claims: BridgeClaims, identity?: string | BridgeIdentityOptions): 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: LoggerService, userIdDomain?: string): Promise<UserInfo>;
+export declare function getOrProvisionUserFromClaims(client: LiteLLMClient, claims: BridgeClaims, provisioningEnabled: boolean, provisioningDefaults: ProvisioningDefaults, logger: LoggerService, userIdDomain?: string | BridgeIdentityOptions): 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: LoggerService, userIdDomain?: string): Promise<VirtualKey[]>;
+export declare function bridgeListKeys(client: LiteLLMClient, claims: BridgeClaims, provisioningEnabled: boolean, provisioningDefaults: ProvisioningDefaults, logger: LoggerService, userIdDomain?: string | BridgeIdentityOptions): 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: LoggerService, request: Partial<GenerateKeyRequest>, userIdDomain?: string): Promise<GenerateKeyResponse>;
+export declare function bridgeGenerateKey(client: LiteLLMClient, claims: BridgeClaims, provisioningEnabled: boolean, provisioningDefaults: ProvisioningDefaults, logger: LoggerService, request: Partial<GenerateKeyRequest>, userIdDomain?: string | BridgeIdentityOptions): Promise<GenerateKeyResponse>;

package/dist/bridge.js

@@ -28,7 +28,8 @@ 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 };
+    const allowedEmailDomains = (config.getOptionalStringArray('litellm.bridge.allowedEmailDomains') ?? []).map(d => d.trim().toLowerCase()).filter(Boolean);
+    return { enabled, issuer, clientId, allowedEmailDomains };
 }
 /** Thrown when the bridge is misconfigured (e.g. enabled without an issuer). */
 class BridgeConfigError extends Error {
@@ -110,26 +111,40 @@ function newDefaultVerifier(cfg) {
     }
     return new KeycloakJWTVerifier({ issuer: cfg.issuer, clientId: cfg.clientId });
 }
+/** A bare string is the legacy form: `userIdDomain`, also the only trusted domain. */
+function normalizeIdentityOptions(opts) {
+    const o = typeof opts === 'string' ? { userIdDomain: opts } : opts ?? {};
+    let domains = [];
+    if (o.trustedEmailDomains?.length) {
+        domains = o.trustedEmailDomains;
+    }
+    else if (o.userIdDomain) {
+        domains = [o.userIdDomain];
+    }
+    const trusted = domains.map(d => d.toLowerCase());
+    return { userIdDomain: o.userIdDomain, trusted };
+}
 /**
- * Resolves the LiteLLM user_id from the verified claims with strict identity validation.
+ * Resolves the LiteLLM user_id for a verified bridge token.
  *
- * PR-6 identity mapping:
- * - Prefer `email` with `email_verified === true` whose domain equals `userIdDomain`.
- * - If userIdDomain is unset, always reject unverified emails (guard against misconfig).
- * - Never strip an arbitrary domain from `preferred_username`.
- * - Rejects invalid/missing identity with 403.
+ * Two separate questions, answered separately:
+ * 1. Is this person allowed in? The token must carry a *verified* email whose
+ *    domain is in the trusted list (`litellm.bridge.allowedEmailDomains`,
+ *    defaulting to `litellm.userIdDomain`). With no trusted domain configured
+ *    everyone is rejected (fail closed). Failure → 403.
+ * 2. Which LiteLLM user are they? The same one the UI addresses: the Backstage
+ *    user entity name (the Keycloak `preferred_username`) run through the same
+ *    `litellm.userIdDomain` rule the UI applies. Using the email local part
+ *    here would address a different user whenever a Keycloak username differs
+ *    from the email (and would provision a duplicate). The realm is the same
+ *    IdP Backstage signs users in with, so its usernames are the entity names.
  *
- * @param claims Verified JWT claims from the bridge token
- * @param userIdDomain Expected email domain (e.g. "example.com"); if set, email must match
- * @returns The resolved LiteLLM user_id
  * @throws BridgeIdentityError (403) if identity validation fails
  */
-function resolveBridgeUserId(claims, userIdDomain) {
-    // The bridge maps identities by verified email only. Without a configured
-    // domain we can't tell our users from another tenant's, and stripping the
-    // domain would merge alice@a.com and alice@b.com — fail closed.
-    if (!userIdDomain) {
-        throw new BridgeIdentityError('litellm.userIdDomain must be configured to use the CLI bridge');
+function resolveBridgeUserId(claims, identity) {
+    const { userIdDomain, trusted } = normalizeIdentityOptions(identity);
+    if (trusted.length === 0) {
+        throw new BridgeIdentityError('set litellm.bridge.allowedEmailDomains (or litellm.userIdDomain) to use the CLI bridge');
     }
     if (!claims.email) {
         throw new BridgeIdentityError('no email found in token');
@@ -141,11 +156,12 @@ function resolveBridgeUserId(claims, userIdDomain) {
     if (parts.length !== 2 || !parts[0]) {
         throw new BridgeIdentityError('malformed email in token');
     }
-    const [localPart, domain] = parts;
-    if (domain.toLowerCase() !== userIdDomain.toLowerCase()) {
+    const [emailLocalPart, domain] = parts;
+    if (!trusted.includes(domain.toLowerCase())) {
         throw new BridgeIdentityError(`email domain mismatch: "${domain}" is not allowed for this deployment`);
     }
-    return (0, provisioning_1.toLiteLLMUserId)(localPart, userIdDomain);
+    const name = claims.preferred_username?.trim() || emailLocalPart;
+    return (0, provisioning_1.toLiteLLMUserId)(name, userIdDomain);
 }
 /**
  * Ensures a LiteLLM user exists for the verified identity. If the user is

package/dist/index.cjs.js

@@ -12616,7 +12616,8 @@ 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 };
+  const allowedEmailDomains = (config.getOptionalStringArray("litellm.bridge.allowedEmailDomains") ?? []).map((d) => d.trim().toLowerCase()).filter(Boolean);
+  return { enabled, issuer, clientId, allowedEmailDomains };
 }
 var BridgeConfigError = class extends Error {
 };
@@ -12686,10 +12687,22 @@ function newDefaultVerifier(cfg) {
   }
   return new KeycloakJWTVerifier({ issuer: cfg.issuer, clientId: cfg.clientId });
 }
-function resolveBridgeUserId(claims, userIdDomain) {
-  if (!userIdDomain) {
+function normalizeIdentityOptions(opts) {
+  const o = typeof opts === "string" ? { userIdDomain: opts } : opts ?? {};
+  let domains = [];
+  if (o.trustedEmailDomains?.length) {
+    domains = o.trustedEmailDomains;
+  } else if (o.userIdDomain) {
+    domains = [o.userIdDomain];
+  }
+  const trusted = domains.map((d) => d.toLowerCase());
+  return { userIdDomain: o.userIdDomain, trusted };
+}
+function resolveBridgeUserId(claims, identity) {
+  const { userIdDomain, trusted } = normalizeIdentityOptions(identity);
+  if (trusted.length === 0) {
     throw new BridgeIdentityError(
-      "litellm.userIdDomain must be configured to use the CLI bridge"
+      "set litellm.bridge.allowedEmailDomains (or litellm.userIdDomain) to use the CLI bridge"
     );
   }
   if (!claims.email) {
@@ -12702,13 +12715,14 @@ function resolveBridgeUserId(claims, userIdDomain) {
   if (parts.length !== 2 || !parts[0]) {
     throw new BridgeIdentityError("malformed email in token");
   }
-  const [localPart, domain] = parts;
-  if (domain.toLowerCase() !== userIdDomain.toLowerCase()) {
+  const [emailLocalPart, domain] = parts;
+  if (!trusted.includes(domain.toLowerCase())) {
     throw new BridgeIdentityError(
       `email domain mismatch: "${domain}" is not allowed for this deployment`
     );
   }
-  return toLiteLLMUserId(localPart, userIdDomain);
+  const name = claims.preferred_username?.trim() || emailLocalPart;
+  return toLiteLLMUserId(name, userIdDomain);
 }
 async function getOrProvisionUserFromClaims(client, claims, provisioningEnabled, provisioningDefaults, logger, userIdDomain) {
   const userId = resolveBridgeUserId(claims, userIdDomain);
@@ -12794,6 +12808,10 @@ function registerBridgeRoutes(router, ctx, bridgeOpts) {
   const { config } = bridgeOpts;
   const generateKeyInputSchema = (0, import_backstage_plugin_litellm_common7.createGenerateKeyInputSchema)(ctx.keyValidationConfig);
   const bridgeCfg = readBridgeConfig(config);
+  const bridgeIdentity = {
+    userIdDomain,
+    trustedEmailDomains: bridgeCfg.allowedEmailDomains
+  };
   let tokenVerifier = bridgeOpts.tokenVerifier;
   if (bridgeCfg.enabled && !tokenVerifier) {
     try {
@@ -12844,7 +12862,7 @@ function registerBridgeRoutes(router, ctx, bridgeOpts) {
           provisioningEnabled,
           provisioningDefaults,
           logger,
-          userIdDomain
+          bridgeIdentity
         );
         res.json(keys);
       } catch (error) {
@@ -12864,7 +12882,7 @@ function registerBridgeRoutes(router, ctx, bridgeOpts) {
           return;
         }
         const input = parseResult.data;
-        const userId = resolveBridgeUserId(claims, userIdDomain);
+        const userId = resolveBridgeUserId(claims, bridgeIdentity);
         const keyCreateCtx = {
           client,
           config: {