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

package/config.d.ts

@@ -2,18 +2,25 @@ export interface Config {
   litellm: {
     /**
      * Base URL of the LiteLLM proxy instance.
-     * @visibility backend
      */
     baseUrl: string;
 
     /**
      * Publicly reachable LiteLLM proxy URL. Used to build ready-to-paste
      * curl / OpenAI-SDK snippets in the frontend ("Key Generated" dialog).
-     * When omitted, the internal baseUrl is used instead.
-     * @visibility backend
+     * The value is served to the frontend via GET /config. When omitted the
+     * frontend shows "Endpoint not configured" — the internal baseUrl is
+     * never exposed.
      */
     publicBaseUrl?: string;
 
+    /**
+     * Who end users should contact when their LiteLLM account isn't set up
+     * (an email address, chat channel or URL). Served to the frontend via
+     * GET /config and shown in the "account isn't set up" panel.
+     */
+    supportContact?: string;
+
     /**
      * LiteLLM master key for admin operations. Never exposed to the frontend.
      * @visibility secret
@@ -24,7 +31,6 @@ export interface Config {
      * Email domain appended to the Backstage user entity name to form the
      * LiteLLM user_id. When set, a user named "john.doe" maps to
      * "john.doe@<userIdDomain>" in LiteLLM. Omit to use the bare entity name.
-     * @visibility backend
      */
     userIdDomain?: string;
 
@@ -78,6 +84,12 @@ export interface Config {
          */
         rpmLimit?: number;
 
+        /**
+         * LiteLLM user role applied on /user/new (e.g. "internal_user").
+         * @default "internal_user"
+         */
+        userRole?: string;
+
         /**
          * Arbitrary key-value metadata stored on the LiteLLM user record.
          * Useful for tracking source, cost centre, department, etc.
@@ -102,16 +114,12 @@ export interface Config {
         teams?: string[];
         tpmLimit?: number;
         rpmLimit?: number;
+        /** LiteLLM user role for members of this group; falls back to defaults.userRole. */
+        userRole?: string;
         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.
-     */
     /**
      * Audit log access control. When set, the /audit tab in the plugin is
      * only visible to members of the specified Backstage group.
@@ -127,6 +135,103 @@ export interface Config {
       group?: string;
     };
 
+    /**
+     * Governance ceilings for individual key creation.
+     * These are strict server-side limits; config flags (allowUnlimitedBudget,
+     * teamRequired) control what users are allowed to do, but these limits
+     * cap what they can specify.
+     */
+    keys?: {
+      /**
+       * Maximum USD budget a single key can have. Requests exceeding this
+       * are rejected with a 400 error.
+       * @default 100
+       */
+      maxBudget?: number;
+
+      /**
+       * Maximum tokens-per-minute a single key can request.
+       * Requests exceeding this are rejected with a 400 error.
+       * @default 100000
+       */
+      maxTpm?: number;
+
+      /**
+       * Maximum requests-per-minute a single key can request.
+       * Requests exceeding this are rejected with a 400 error.
+       * @default 1000
+       */
+      maxRpm?: number;
+
+      /**
+       * Allowed duration presets for keys (e.g. "1d", "7d", "30d", "90d").
+       * Requests with a duration not in this list are rejected with a 400 error.
+       * An empty array allows any duration matching the format /^\d+[smhdwy]$/.
+       * @default ["1d", "7d", "30d", "90d"]
+       */
+      allowedDurations?: string[];
+
+      /**
+       * When true, key owners can reset their key's spend counter via the
+       * "Reset Spend" button in the frontend, subject to the
+       * litellm.key.resetSpend permission. When false (the default), reset
+       * is only available to administrators, even if the permission is ALLOW.
+       * Fail-closed: enforced before the permission check.
+       * @default false
+       */
+      allowOwnerResetSpend?: boolean;
+    };
+
+    /**
+     * OpenCode SSO-connect (GET/POST /opencode/connect). Lets the OpenCode
+     * portal-auth plugin obtain a personal LiteLLM key after a browser
+     * sign-in and confirmation. Disabled by default.
+     */
+    opencode?: {
+      /**
+       * When true the /opencode/connect routes are mounted.
+       * @default false
+       */
+      enabled?: boolean;
+
+      /**
+       * Duration of freshly generated keys, in LiteLLM format (e.g. "30d").
+       * @default "30d"
+       */
+      keyDuration?: string;
+
+      /**
+       * Max budget (USD) of keys created through the connect flow.
+       * @default 50
+       */
+      maxBudget?: number;
+
+      /**
+       * When true a team must be supplied and the user must belong to it.
+       * @default false
+       */
+      requireTeam?: boolean;
+
+      /**
+       * Extra metadata stamped on keys created through this flow.
+       */
+      metadata?: { [key: string]: string };
+    };
+
+    /**
+     * Caching configuration for backend data fetches.
+     */
+    cache?: {
+      /**
+       * Time-to-live for cached getUserInfo results, in seconds.
+       * When 0, caching is disabled.
+       * Cached results are never stale within this window; mutations
+       * invalidate the cache immediately to ensure consistency.
+       * @default 10
+       */
+      userInfoTtlSeconds?: number;
+    };
+
     /**
      * Controls for the "Generate New Key" form in the frontend.
      */
@@ -161,7 +266,6 @@ export interface Config {
        * e.g. "group:default/litellm-team-admins".
        * The plugin ships a group template at catalog/litellm-team-admins.yaml.
        * When omitted the feature is disabled entirely.
-       * @visibility backend
        */
       group?: string;
 
@@ -169,7 +273,6 @@ export interface Config {
        * LiteLLM model names an admin may assign to a team.
        * Empty array => none assignable (fail-closed).
        * @default []
-       * @visibility backend
        */
       allowedModels?: string[];
 
@@ -178,21 +281,18 @@ export interface Config {
        * References access_groups defined in litellm.model_info configuration.
        * Empty array => none allowed.
        * @default []
-       * @visibility backend
        */
       allowedModelAccessGroups?: string[];
 
       /**
        * Hard USD ceiling for max_budget an admin may set on a team.
        * @default 1000
-       * @visibility backend
        */
       maxBudgetCeiling?: number;
 
       /**
        * Allow an admin to create a team with no budget cap.
        * @default false
-       * @visibility backend
        */
       allowUnlimitedBudget?: boolean;
 
@@ -200,7 +300,6 @@ export interface Config {
        * Vector-store ids/names an admin may attach as team knowledge bases.
        * Empty array => none allowed.
        * @default []
-       * @visibility backend
        */
       allowedVectorStores?: string[];
 
@@ -208,7 +307,6 @@ export interface Config {
        * MCP server ids/names an admin may attach to a team.
        * Empty array => none allowed.
        * @default []
-       * @visibility backend
        */
       allowedMcpServers?: string[];
 
@@ -217,14 +315,12 @@ export interface Config {
        * References access_groups defined in litellm.mcp_info configuration.
        * Empty array => none allowed.
        * @default []
-       * @visibility backend
        */
       allowedMcpAccessGroups?: string[];
 
       /**
        * Allow an admin to delete a team (vs. only block/deactivate).
        * @default false
-       * @visibility backend
        */
       allowTeamDelete?: boolean;
 
@@ -242,7 +338,6 @@ export interface Config {
          * When true, mount the knowledge-base and MCP management routes.
          * Still gated by the permission framework and the allowlists.
          * @default false
-         * @visibility backend
          */
         enabled?: boolean;
       };
@@ -262,7 +357,6 @@ export interface Config {
        * cards, TEAM section of the budget widget). Team managers still see
        * dollars unless hideTeamBudgetForManagers is also set.
        * @default false
-       * @visibility frontend
        */
       hideTeamBudgetForMembers?: boolean;
 
@@ -271,7 +365,6 @@ export interface Config {
        * team write responses, ManageTeamDialog budget field which becomes
        * write-only). Useful when budgets are finance-sensitive.
        * @default false
-       * @visibility frontend
        */
       hideTeamBudgetForManagers?: boolean;
     };

package/dist/bridge.d.ts

@@ -1,15 +1,19 @@
 import { Config } from '@backstage/config';
+import { LoggerService } from '@backstage/backend-plugin-api';
 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;
+    email_verified?: boolean;
     preferred_username?: string;
     name?: string;
     /** Authorized party — Keycloak sets this to the client_id of the requester. */
     azp?: string;
     aud?: string | string[];
+    /** Keycloak payload `typ` claim: 'Bearer' for access tokens, 'ID' for ID tokens. */
+    typ?: string;
 }
 /** A token verifier pluggable for tests. */
 export interface TokenVerifier {
@@ -30,6 +34,10 @@ export declare class BridgeConfigError extends Error {
 export declare class BridgeAuthError extends Error {
     readonly status = 401;
 }
+/** Thrown when the caller's identity fails validation (e.g. email domain mismatch) → maps to HTTP 403. */
+export declare class BridgeIdentityError extends Error {
+    readonly status = 403;
+}
 export interface KeycloakJWTVerifierOptions {
     issuer: string;
     clientId: string;
@@ -49,13 +57,18 @@ 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, matching exactly how
- * the UI derives it so the bridge addresses the *same* LiteLLM user (not a
- * duplicate). The UI uses toLiteLLMUserId(entityRef, userIdDomain) where the
- * Backstage entity name has been rewritten by the Keycloak user transformer:
- * because the catalog rejects '@' in entity names, usernames imported as full
- * emails are stored as their local-part. We replicate that here — strip the
- * '@domain' off the username, then apply the same userIdDomain rule.
+ * Resolves the LiteLLM user_id from the verified claims with strict identity validation.
+ *
+ * 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.
+ *
+ * @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;
 /**
@@ -64,14 +77,8 @@ export declare function resolveBridgeUserId(claims: BridgeClaims, userIdDomain?:
  * 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;
-}, userIdDomain?: string): Promise<UserInfo>;
+export declare function getOrProvisionUserFromClaims(client: LiteLLMClient, claims: BridgeClaims, provisioningEnabled: boolean, provisioningDefaults: ProvisioningDefaults, logger: LoggerService, userIdDomain?: string): 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;
-}, userIdDomain?: string): Promise<VirtualKey[]>;
+export declare function bridgeListKeys(client: LiteLLMClient, claims: BridgeClaims, provisioningEnabled: boolean, provisioningDefaults: ProvisioningDefaults, logger: LoggerService, userIdDomain?: string): 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>, userIdDomain?: string): Promise<GenerateKeyResponse>;
+export declare function bridgeGenerateKey(client: LiteLLMClient, claims: BridgeClaims, provisioningEnabled: boolean, provisioningDefaults: ProvisioningDefaults, logger: LoggerService, request: Partial<GenerateKeyRequest>, userIdDomain?: string): Promise<GenerateKeyResponse>;

package/dist/bridge.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.KeycloakJWTVerifier = exports.BridgeAuthError = exports.BridgeConfigError = void 0;
+exports.KeycloakJWTVerifier = exports.BridgeIdentityError = exports.BridgeAuthError = exports.BridgeConfigError = void 0;
 exports.readBridgeConfig = readBridgeConfig;
 exports.newDefaultVerifier = newDefaultVerifier;
 exports.resolveBridgeUserId = resolveBridgeUserId;
@@ -42,6 +42,14 @@ class BridgeAuthError extends Error {
     }
 }
 exports.BridgeAuthError = BridgeAuthError;
+/** Thrown when the caller's identity fails validation (e.g. email domain mismatch) → maps to HTTP 403. */
+class BridgeIdentityError extends Error {
+    constructor() {
+        super(...arguments);
+        this.status = 403;
+    }
+}
+exports.BridgeIdentityError = BridgeIdentityError;
 /**
  * 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
@@ -73,14 +81,23 @@ class KeycloakJWTVerifier {
         if (azp !== this.clientId && !audMatches) {
             throw new BridgeAuthError(`token not issued for client "${this.clientId}" (azp=${azp ?? 'none'})`);
         }
+        // Keycloak marks the token kind in the PAYLOAD `typ` claim ('Bearer' for
+        // access tokens, 'ID' for ID tokens); the JWT header `typ` is just 'JWT'.
+        // Reject anything that isn't an access token.
+        const typ = payload.typ;
+        if (typ && typ !== 'Bearer') {
+            throw new BridgeAuthError(`token type must be Bearer or absent, got: ${typ}`);
+        }
         return {
             sub: payload.sub ?? '',
             email: payload.email,
+            email_verified: payload.email_verified,
             preferred_username: payload
                 .preferred_username,
             name: payload.name,
             azp,
             aud,
+            typ,
         };
     }
 }
@@ -94,18 +111,41 @@ function newDefaultVerifier(cfg) {
     return new KeycloakJWTVerifier({ issuer: cfg.issuer, clientId: cfg.clientId });
 }
 /**
- * Resolves the LiteLLM user_id from the verified claims, matching exactly how
- * the UI derives it so the bridge addresses the *same* LiteLLM user (not a
- * duplicate). The UI uses toLiteLLMUserId(entityRef, userIdDomain) where the
- * Backstage entity name has been rewritten by the Keycloak user transformer:
- * because the catalog rejects '@' in entity names, usernames imported as full
- * emails are stored as their local-part. We replicate that here — strip the
- * '@domain' off the username, then apply the same userIdDomain rule.
+ * Resolves the LiteLLM user_id from the verified claims with strict identity validation.
+ *
+ * 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.
+ *
+ * @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) {
-    const raw = claims.preferred_username ?? claims.email ?? claims.sub;
-    const entityName = raw.includes('@') ? raw.split('@')[0] : raw;
-    return (0, provisioning_1.toLiteLLMUserId)(entityName, 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');
+    }
+    if (!claims.email) {
+        throw new BridgeIdentityError('no email found in token');
+    }
+    if (claims.email_verified !== true) {
+        throw new BridgeIdentityError('email is not verified');
+    }
+    const parts = claims.email.split('@');
+    if (parts.length !== 2 || !parts[0]) {
+        throw new BridgeIdentityError('malformed email in token');
+    }
+    const [localPart, domain] = parts;
+    if (domain.toLowerCase() !== userIdDomain.toLowerCase()) {
+        throw new BridgeIdentityError(`email domain mismatch: "${domain}" is not allowed for this deployment`);
+    }
+    return (0, provisioning_1.toLiteLLMUserId)(localPart, userIdDomain);
 }
 /**
  * Ensures a LiteLLM user exists for the verified identity. If the user is

package/dist/client.d.ts

@@ -10,7 +10,7 @@ export declare function normalizeRequestTags(tags: SpendLogEntry['request_tags']
  * status and the structured `param` (e.g. `key_alias`) from the upstream
  * body so the router can surface a 400 instead of collapsing everything
  * into a 500. The message is the upstream `error.message` when present,
- * otherwise the raw body text.
+ * otherwise a generic status+statusText format (never embeds raw bodies).
  */
 export declare class LiteLLMUpstreamError extends Error {
     status: number;
@@ -68,6 +68,11 @@ export declare class LiteLLMClient {
      */
     generateKey(request: GenerateKeyRequest): Promise<GenerateKeyResponse>;
     updateKey(request: UpdateKeyRequest): Promise<VirtualKey>;
+    /**
+     * Regenerates (rotates) a key by its hash, returning a new plaintext key.
+     * The LiteLLM version determines the endpoint: use POST /key/{key}/regenerate.
+     */
+    regenerateKey(keyHash: string): Promise<GenerateKeyResponse>;
     deleteKeys(request: DeleteKeyRequest): Promise<{
         success: boolean;
     }>;
@@ -180,6 +185,6 @@ export declare class LiteLLMClient {
      *   - usage_by_key    → which keys drove cost / traffic (with key_alias + team_id from metadata)
      */
     private transformDailyActivity;
-    getUsage(startDate: string, endDate: string, userId?: string): Promise<UsageMetrics>;
+    getUsage(startDate: string, endDate: string, userId: string): Promise<UsageMetrics>;
     getTeamUsage(teamId: string, startDate: string, endDate: string): Promise<UsageMetrics>;
 }

package/dist/client.js

@@ -20,11 +20,12 @@ function normalizeRequestTags(tags) {
  * status and the structured `param` (e.g. `key_alias`) from the upstream
  * body so the router can surface a 400 instead of collapsing everything
  * into a 500. The message is the upstream `error.message` when present,
- * otherwise the raw body text.
+ * otherwise a generic status+statusText format (never embeds raw bodies).
  */
 class LiteLLMUpstreamError extends Error {
     constructor(status, statusText, body) {
-        let message = `LiteLLM API error: ${status} ${statusText} - ${body}`;
+        // Default message is generic status + text; only use JSON message if present.
+        let message = `LiteLLM API error: ${status} ${statusText}`;
         let param;
         try {
             const parsed = JSON.parse(body);
@@ -36,7 +37,8 @@ class LiteLLMUpstreamError extends Error {
             }
         }
         catch {
-            // not JSON — keep the raw body in the message
+            // Not JSON — keep the generic message (no raw body embedded).
+            // Log the raw body at debug level if needed by the caller.
         }
         super(message);
         this.status = status;
@@ -112,6 +114,7 @@ class LiteLLMClient {
                 models: inner.models ?? raw?.models,
                 max_budget: inner.max_budget ?? raw?.max_budget,
                 budget_duration: inner.budget_duration ?? raw?.budget_duration,
+                budget_reset_at: inner.budget_reset_at ?? raw?.budget_reset_at,
                 spend: inner.spend ?? raw?.spend,
                 current_spend: inner.current_spend ?? raw?.current_spend,
                 soft_limit: inner.soft_limit ?? raw?.soft_limit,
@@ -119,7 +122,7 @@ class LiteLLMClient {
             };
         }
         catch (err) {
-            if (err.status === 404)
+            if (err instanceof LiteLLMUpstreamError && err.status === 404)
                 return null;
             throw err;
         }
@@ -161,7 +164,10 @@ class LiteLLMClient {
             return rawKeys.map(this.toVirtualKey);
         }
         catch (err) {
-            if (err.status === 404 || err.message.includes('not found')) {
+            if (err instanceof LiteLLMUpstreamError && err.status === 404) {
+                return [];
+            }
+            if (err instanceof Error && err.message.includes('not found')) {
                 return [];
             }
             throw err;
@@ -181,7 +187,9 @@ class LiteLLMClient {
             rpm_limit: k.rpm_limit ?? undefined,
             models: k.models ?? [],
             user_id: k.user_id ?? undefined,
+            team_id: k.team_id ?? undefined,
             blocked: k.blocked ?? undefined,
+            metadata: k.metadata ?? undefined,
         };
     }
     /**
@@ -212,6 +220,16 @@ class LiteLLMClient {
             body: JSON.stringify(request),
         });
     }
+    /**
+     * Regenerates (rotates) a key by its hash, returning a new plaintext key.
+     * The LiteLLM version determines the endpoint: use POST /key/{key}/regenerate.
+     */
+    async regenerateKey(keyHash) {
+        return this.request(`/key/${encodeURIComponent(keyHash)}/regenerate`, {
+            method: 'POST',
+            body: JSON.stringify({}),
+        });
+    }
     async deleteKeys(request) {
         return this.request('/key/delete', {
             method: 'POST',
@@ -627,19 +645,25 @@ class LiteLLMClient {
         };
     }
     async getUsage(startDate, endDate, userId) {
+        if (!userId) {
+            // An empty user_id makes LiteLLM return org-wide activity.
+            throw new Error('getUsage requires a user_id');
+        }
         const params = new URLSearchParams({
             start_date: startDate,
             end_date: endDate,
             page_size: '100',
         });
-        if (userId)
-            params.append('user_id', userId);
+        params.append('user_id', userId);
         try {
             const response = await this.request(`/user/daily/activity?${params.toString()}`);
             return this.transformDailyActivity(response);
         }
         catch (err) {
-            if (err.status === 404 || err.message.includes('not found')) {
+            if (err instanceof LiteLLMUpstreamError && err.status === 404) {
+                return this.emptyUsage();
+            }
+            if (err instanceof Error && err.message.includes('not found')) {
                 return this.emptyUsage();
             }
             throw err;
@@ -657,7 +681,10 @@ class LiteLLMClient {
             return this.transformDailyActivity(response);
         }
         catch (err) {
-            if (err.status === 404 || err.message.includes('not found')) {
+            if (err instanceof LiteLLMUpstreamError && err.status === 404) {
+                return this.emptyUsage();
+            }
+            if (err instanceof Error && err.message.includes('not found')) {
                 return this.emptyUsage();
             }
             throw err;

package/dist/errors.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Central error handling and sanitization for the LiteLLM backend.
+ *
+ * Ensures that:
+ * - Upstream auth failures (401/403) don't log out Backstage sessions
+ * - Upstream 5xx errors are generic and don't leak implementation details
+ * - Upstream 4xx errors are sanitized and capped
+ * - Non-JSON error bodies are not embedded in responses
+ * - All error logging happens server-side only
+ */
+import { Response } from 'express';
+import { LoggerService } from '@backstage/backend-plugin-api';
+/**
+ * Type guard: narrows unknown to {status: number; body: Record<string, unknown>}.
+ * Used to detect custom errors that have status and body properties.
+ */
+export declare function isHttpishError(error: unknown): error is {
+    status: number;
+    body: Record<string, unknown>;
+};
+/**
+ * Safely extract a message string from any error type.
+ * Returns empty string if no message can be extracted.
+ */
+export declare function errorMessage(error: unknown): string;
+/**
+ * Sanitizes a message by:
+ * - Stripping HTML tags
+ * - Collapsing consecutive whitespace
+ * - Truncating to 500 characters
+ *
+ * @param msg The raw message (may contain HTML, newlines, etc.)
+ * @returns A safe, printable message
+ */
+export declare function sanitizeUpstreamMessage(msg: string): string;
+/**
+ * Maps any error type to an HTTP response shape {status, body}.
+ *
+ * Behaviour:
+ * - LiteLLMUpstreamError 401/403 → 502 generic (prevent session logout)
+ * - LiteLLMUpstreamError 5xx or network → 502 generic
+ * - LiteLLMUpstreamError 4xx (other) → 400 with sanitized message + param if present
+ * - KeyServiceError / ProvisioningError / objects with status+body → pass through
+ * - Backstage-style errors (name: InputError/NotAllowedError/NotFoundError/ConflictError) → map to 400/403/404/409
+ * - Anything else → 500 (message logged server-side, not returned)
+ *
+ * @returns {status, body, logLevel} for HTTP response; undefined _logMessage is only present for 500s
+ */
+export declare function toHttpError(error: unknown): {
+    status: number;
+    body: Record<string, unknown>;
+    logLevel: 'debug' | 'info' | 'warn' | 'error';
+    _logMessage?: string;
+};
+/**
+ * Express error handler helper. Logs the real error server-side and responds
+ * via toHttpError.
+ *
+ * @param res Express Response object
+ * @param error The caught error (any type)
+ * @param logger Logger instance with error/warn/info/debug methods
+ * @param context Contextual label for the log entry (e.g. 'fetch user info')
+ */
+export declare function sendError(res: Response, error: unknown, logger: LoggerService, context: string): void;