@lenne.tech/nest-server 11.25.6 → 11.26.0

package/src/core/modules/ai/providers/openai-compatible.provider.ts

@@ -0,0 +1,329 @@
+import { BadGatewayException, Logger, ServiceUnavailableException } from '@nestjs/common';
+
+import { ConfigService } from '../../../common/services/config.service';
+import { ErrorCode } from '../../error-code';
+import {
+  ILlmProvider,
+  LlmCapabilities,
+  LlmCompletionOptions,
+  LlmMessage,
+  LlmResponse,
+  LlmToolSchema,
+} from '../interfaces/llm-provider.interface';
+import { ResolvedAiConnection } from '../interfaces/resolved-ai-connection.interface';
+
+/**
+ * Provider for OpenAI-compatible chat-completions endpoints.
+ *
+ * Works with any backend that speaks the OpenAI chat-completions shape — local
+ * runtimes or hosted endpoints alike. Implemented with the native `fetch` API so
+ * the framework core stays dependency-free and vendor-neutral.
+ *
+ * Capabilities are taken from the connection config (the admin knows what the
+ * endpoint supports). The orchestrator compensates: when `nativeTools` is false it
+ * emulates tool calling via the system prompt; when `jsonResponse` is false it
+ * relies on prompt-instructed JSON. Both are off by default (the safe, lowest
+ * common denominator) and can be enabled per connection.
+ */
+export class OpenAiCompatibleProvider implements ILlmProvider {
+  readonly capabilities: LlmCapabilities;
+  readonly name = 'openai-compatible';
+
+  private readonly logger = new Logger(OpenAiCompatibleProvider.name);
+  private readonly defaultTimeoutMs: number;
+
+  constructor(private readonly connection: ResolvedAiConnection) {
+    this.capabilities = {
+      jsonResponse: connection.supportsJsonResponse ?? false,
+      nativeTools: connection.supportsNativeTools ?? false,
+      systemPrompt: true,
+    };
+    // Default to 2 minutes for interactive prompts; overridable per connection.
+    this.defaultTimeoutMs = connection.timeoutMs ?? 120_000;
+  }
+
+  /**
+   * Send a chat completion request to the OpenAI-compatible `/chat/completions`
+   * endpoint and map the response to {@link LlmResponse}. Sends native `tools` and
+   * `response_format` only when the connection's capabilities allow it; native tool
+   * calls are mapped via {@link mapNativeToolCalls}. Aborts after the connection's
+   * timeout and maps HTTP/transport errors to a {@link ServiceUnavailableException}.
+   */
+  async chat(messages: LlmMessage[], tools: LlmToolSchema[], options?: LlmCompletionOptions): Promise<LlmResponse> {
+    const url = `${this.connection.baseUrl.replace(/\/$/, '')}/chat/completions`;
+    if (!url.startsWith('http')) {
+      this.logger.warn(`AI connection "${this.connection.name}" has no valid baseUrl: ${this.connection.baseUrl}`);
+      throw new ServiceUnavailableException(ErrorCode.AI_CONNECTION_INVALID_URL);
+    }
+    this.assertBaseUrlAllowed(url);
+
+    const body: Record<string, any> = {
+      max_tokens: options?.maxTokens ?? this.connection.defaultMaxTokens ?? 2048,
+      messages: messages.map((m) => ({
+        // Map the emulated 'tool' role to 'user' for backends that only know
+        // system/user/assistant.
+        content: this.mapMessageContent(m),
+        role: m.role === 'tool' ? 'user' : m.role,
+      })),
+      model: options?.model ?? this.connection.model,
+      stream: false,
+      temperature: options?.temperature ?? this.connection.defaultTemperature ?? 0.1,
+    };
+
+    // Attach native parameters only when the backend supports them.
+    if (this.capabilities.nativeTools && tools.length) {
+      body.tools = tools.map((t) => ({
+        function: { description: t.description, name: t.name, parameters: t.parameters },
+        type: 'function',
+      }));
+    }
+    if (this.capabilities.jsonResponse) {
+      body.response_format = { type: 'json_object' };
+    }
+
+    const timeoutMs = options?.timeoutMs ?? this.defaultTimeoutMs;
+    let response: Response;
+    try {
+      response = await fetch(url, {
+        body: JSON.stringify(body),
+        headers: {
+          Authorization: `Bearer ${this.connection.apiKey}`,
+          'Content-Type': 'application/json',
+        },
+        method: 'POST',
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+    } catch (err) {
+      const message = (err as Error)?.name === 'TimeoutError' ? `timeout after ${timeoutMs}ms` : (err as Error).message;
+      this.logger.warn(`AI request to "${this.connection.name}" failed: ${message}`);
+      throw new ServiceUnavailableException(ErrorCode.AI_PROVIDER_ERROR);
+    }
+
+    if (!response.ok) {
+      const text = await response.text().catch(() => '');
+      this.logger.warn(`AI completion failed (${response.status}) at ${url}: ${text.slice(0, 300)}`);
+      throw new BadGatewayException(ErrorCode.AI_PROVIDER_ERROR);
+    }
+
+    const result = (await response.json()) as {
+      choices?: { message?: { content?: string; tool_calls?: any[] } }[];
+      usage?: { completion_tokens?: number; prompt_tokens?: number; total_tokens?: number };
+    };
+
+    const choice = result.choices?.[0]?.message;
+    const text = choice?.content ?? '';
+    const nativeToolCalls = this.capabilities.nativeTools ? this.mapNativeToolCalls(choice?.tool_calls) : undefined;
+
+    return {
+      raw: result,
+      text,
+      toolCalls: nativeToolCalls,
+      usage: {
+        completionTokens: result.usage?.completion_tokens,
+        promptTokens: result.usage?.prompt_tokens,
+        totalTokens: result.usage?.total_tokens,
+      },
+    };
+  }
+
+  /**
+   * Optional SSRF hardening: when `ai.allowedBaseUrlHosts` is configured (non-empty),
+   * only allow requests to those hosts (matched by `host` incl. port, or bare
+   * `hostname`). Unset → permissive (so local providers like Ollama on localhost work
+   * out of the box). `baseUrl` is admin-only, so this guards a compromised/misconfigured
+   * admin, not an end-user input.
+   */
+  protected assertBaseUrlAllowed(url: string): void {
+    const allowedHosts = ConfigService.get<string[]>('ai.allowedBaseUrlHosts');
+    if (!Array.isArray(allowedHosts) || !allowedHosts.length) {
+      return;
+    }
+    let parsed: URL;
+    try {
+      parsed = new URL(url);
+    } catch {
+      throw new ServiceUnavailableException(ErrorCode.AI_CONNECTION_INVALID_URL);
+    }
+    if (!allowedHosts.includes(parsed.host) && !allowedHosts.includes(parsed.hostname)) {
+      this.logger.warn(
+        `AI connection "${this.connection.name}" host "${parsed.host}" is not in ai.allowedBaseUrlHosts`,
+      );
+      throw new ServiceUnavailableException(ErrorCode.AI_CONNECTION_NOT_AVAILABLE);
+    }
+  }
+
+  /**
+   * Probe the backend to auto-detect capabilities for flags the connection left
+   * undefined. Explicit flags are authoritative and are NOT probed. Best effort:
+   * - JSON: send `response_format: json_object`; 2xx → true, 4xx → false.
+   * - Native tools: send a trivial tool with `tool_choice: 'required'`; 2xx WITH a
+   *   `tool_calls` result → true, otherwise → false (a backend that silently ignores
+   *   tools returns no tool_calls and is treated as unsupported).
+   *
+   * Throws on a transport error so callers can treat the connection as undetected
+   * (and retry later) rather than persisting a wrong value.
+   */
+  async detectCapabilities(): Promise<{ jsonResponse?: boolean; nativeTools?: boolean }> {
+    const result: { jsonResponse?: boolean; nativeTools?: boolean } = {};
+    if (this.connection.supportsJsonResponse === undefined) {
+      const res = await this.probe({
+        max_tokens: 8,
+        messages: [{ content: 'Reply with the JSON object {"ok":true}.', role: 'user' }],
+        response_format: { type: 'json_object' },
+      });
+      result.jsonResponse = res.ok;
+    }
+    if (this.connection.supportsNativeTools === undefined) {
+      const res = await this.probe({
+        max_tokens: 8,
+        messages: [{ content: 'Call the ping tool.', role: 'user' }],
+        tool_choice: 'required',
+        tools: [
+          {
+            function: {
+              description: 'A no-op capability probe.',
+              name: 'ping',
+              parameters: { properties: {}, type: 'object' },
+            },
+            type: 'function',
+          },
+        ],
+      });
+      result.nativeTools = res.ok && !!res.json?.choices?.[0]?.message?.tool_calls?.length;
+    }
+    return result;
+  }
+
+  /**
+   * Send a minimal probe request and report whether the endpoint accepted it.
+   * `ok` is true only for a 2xx response; a 4xx (feature unsupported) yields false.
+   */
+  protected async probe(extra: Record<string, any>): Promise<{ json?: any; ok: boolean }> {
+    const url = `${this.connection.baseUrl.replace(/\/$/, '')}/chat/completions`;
+    if (!url.startsWith('http')) {
+      throw new ServiceUnavailableException(ErrorCode.AI_CONNECTION_INVALID_URL);
+    }
+    this.assertBaseUrlAllowed(url);
+    const response = await fetch(url, {
+      body: JSON.stringify({ model: this.connection.model, ...extra }),
+      headers: { Authorization: `Bearer ${this.connection.apiKey}`, 'Content-Type': 'application/json' },
+      method: 'POST',
+      signal: AbortSignal.timeout(this.connection.timeoutMs ?? 30_000),
+    });
+    if (!response.ok) {
+      return { ok: false };
+    }
+    const json = await response.json().catch(() => undefined);
+    return { json, ok: true };
+  }
+
+  /**
+   * Determine the model's total context window automatically: first an Ollama
+   * `/api/show` probe (local runtimes expose `<arch>.context_length`), then a
+   * known-model heuristic table. Best effort — returns undefined when unknown.
+   */
+  async detectContextWindow(): Promise<number | undefined> {
+    const fromBackend = await this.probeContextWindow().catch(() => undefined);
+    return fromBackend ?? this.knownContextWindow(this.connection.model);
+  }
+
+  /**
+   * Heuristic context window (tokens) for well-known model families, matched by
+   * case-insensitive substrings of the model id. Override/extend for custom models.
+   */
+  protected knownContextWindow(model: string | undefined): number | undefined {
+    const m = (model || '').toLowerCase();
+    const table: [number, string[]][] = [
+      [1_000_000, ['gemini-1.5', 'gemini-2']],
+      [200_000, ['claude']],
+      [
+        128_000,
+        ['gpt-4o', 'gpt-4.1', 'gpt-4-turbo', 'o1', 'o3', 'gpt-oss', 'mistral-large', 'mistral-small3', 'command-r'],
+      ],
+      [131_072, ['qwen2.5', 'qwen3', 'llama-3.1', 'llama3.1', 'llama-3.3', 'llama3.3']],
+      [65_536, ['mixtral']],
+      [32_768, ['qwen2', 'mistral', 'gemma2', 'gemma-2']],
+      [16_385, ['gpt-3.5']],
+      [8_192, ['llama3', 'llama-3', 'gemma']],
+    ];
+    for (const [window, keys] of table) {
+      if (keys.some((k) => m.includes(k))) {
+        return window;
+      }
+    }
+    return undefined;
+  }
+
+  /**
+   * Probe a local Ollama backend for the model's context length via `/api/show`.
+   * Returns undefined for non-Ollama endpoints or on any error.
+   */
+  protected async probeContextWindow(): Promise<number | undefined> {
+    const base = this.connection.baseUrl.replace(/\/v1\/?$/, '').replace(/\/$/, '');
+    if (!base.startsWith('http')) {
+      return undefined;
+    }
+    const response = await fetch(`${base}/api/show`, {
+      body: JSON.stringify({ name: this.connection.model }),
+      headers: { 'Content-Type': 'application/json' },
+      method: 'POST',
+      signal: AbortSignal.timeout(this.connection.timeoutMs ?? 15_000),
+    }).catch(() => undefined);
+    if (!response?.ok) {
+      return undefined;
+    }
+    const json = (await response.json().catch(() => undefined)) as { model_info?: Record<string, unknown> } | undefined;
+    const info = json?.model_info;
+    if (!info) {
+      return undefined;
+    }
+    const key = Object.keys(info).find((k) => k.endsWith('.context_length'));
+    const value = key ? info[key] : undefined;
+    return typeof value === 'number' && value > 0 ? value : undefined;
+  }
+
+  /**
+   * Map native `tool_calls` to the normalized {@link LlmResponse.toolCalls}.
+   */
+  /**
+   * Map a (possibly multi-modal) LlmMessage to the OpenAI content shape:
+   * - Plain text → `content: string` (unchanged).
+   * - Text + attachments → `content: [{type:'text',text}, {type:'image_url',image_url:{...}}, ...]`
+   * Files/PDFs with `dataUrl` are passed as `image_url` too — backends that don't
+   * support vision will warn or ignore.
+   */
+  protected mapMessageContent(m: { attachments?: any[]; content: string }): any {
+    if (!Array.isArray(m.attachments) || !m.attachments.length) {
+      return m.content;
+    }
+    const parts: any[] = [];
+    if (m.content) {
+      parts.push({ text: m.content, type: 'text' });
+    }
+    for (const a of m.attachments) {
+      const url = a?.url || a?.dataUrl;
+      if (!url) {
+        continue;
+      }
+      parts.push({ image_url: { url }, type: 'image_url' });
+    }
+    return parts.length ? parts : m.content;
+  }
+
+  protected mapNativeToolCalls(toolCalls: any[] | undefined) {
+    if (!toolCalls?.length) {
+      return undefined;
+    }
+    return toolCalls
+      .filter((c) => c?.function?.name)
+      .map((c) => {
+        let parsedArgs: Record<string, any> = {};
+        try {
+          parsedArgs = c.function.arguments ? JSON.parse(c.function.arguments) : {};
+        } catch {
+          parsedArgs = {};
+        }
+        return { arguments: parsedArgs, id: c.id, name: c.function.name };
+      });
+  }
+}

package/src/core/modules/ai/services/ai-crypto.service.ts

@@ -0,0 +1,120 @@
+import { Injectable, Logger, OnModuleInit } from '@nestjs/common';
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from 'node:crypto';
+
+import { isProductionLikeEnv } from '../../../common/helpers/cookies.helper';
+import { ConfigService } from '../../../common/services/config.service';
+
+/**
+ * AES-256-GCM wrapper for AI connection secrets (API keys).
+ *
+ * Stored shape: `"<iv_b64>.<authTag_b64>.<ciphertext_b64>"` — a dot-separated
+ * triplet that carries everything {@link decrypt} needs. The 256-bit key is
+ * derived via SHA-256 from a configurable pass-phrase, so any length works.
+ *
+ * Secret resolution order:
+ * 1. `ai.encryptionSecret` (config / `NSC__AI__ENCRYPTION_SECRET`)
+ * 2. `SECRETS_ENCRYPTION_KEY` (env)
+ * 3. an insecure development default (logs a warning on first use)
+ *
+ * Rotating the secret invalidates every value currently in the database;
+ * operators must decrypt-then-re-encrypt on rotation (out of scope here).
+ */
+@Injectable()
+export class AiCryptoService implements OnModuleInit {
+  private readonly logger = new Logger(AiCryptoService.name);
+  private warned = false;
+
+  /**
+   * Fail loud at boot in production/staging when AI is active but no real encryption
+   * secret is configured — otherwise stored API keys would be "encrypted" with a
+   * public, insecure development default. Mirrors the email/cookies production guards.
+   */
+  onModuleInit(): void {
+    this.assertProductionSafe();
+  }
+
+  /**
+   * Throw when running in a production-like environment without a configured secret.
+   * No-op in local/dev/ci/e2e (there the insecure default + a warning are acceptable).
+   */
+  assertProductionSafe(): void {
+    if (isProductionLikeEnv(ConfigService.get<string>('env')) && !this.resolveSecret()) {
+      throw new Error(
+        'AI encryption secret is required in production/staging but none is set ' +
+          '(ai.encryptionSecret / NSC__AI__ENCRYPTION_SECRET / SECRETS_ENCRYPTION_KEY). ' +
+          'Without it, stored AI API keys are encrypted with a public, insecure development ' +
+          'default. Set a random 32+ char value.',
+      );
+    }
+  }
+
+  /**
+   * Decrypt a stored cipher text. Values without the expected triplet shape are
+   * returned unchanged (tolerates legacy/plain values without crashing).
+   */
+  decrypt(cipherText: string): string {
+    if (!cipherText) {
+      return '';
+    }
+    const parts = cipherText.split('.');
+    if (parts.length !== 3) {
+      return cipherText;
+    }
+    const [ivB64, tagB64, dataB64] = parts;
+    try {
+      const iv = Buffer.from(ivB64, 'base64');
+      const tag = Buffer.from(tagB64, 'base64');
+      const data = Buffer.from(dataB64, 'base64');
+      const decipher = createDecipheriv('aes-256-gcm', this.getKey(), iv);
+      decipher.setAuthTag(tag);
+      const plain = Buffer.concat([decipher.update(data), decipher.final()]);
+      return plain.toString('utf8');
+    } catch (err) {
+      this.logger.error(`Decrypt failed: ${(err as Error).message}`);
+      throw new Error('Secret decryption failed — key mismatch or corrupted value', { cause: err });
+    }
+  }
+
+  /**
+   * Encrypt a plaintext secret. Empty/undefined input is preserved as an empty
+   * string so "set and cleared" stays distinguishable from "never set".
+   */
+  encrypt(plainText: string): string {
+    if (plainText === '' || plainText === undefined || plainText === null) {
+      return '';
+    }
+    const iv = randomBytes(12); // GCM standard: 96-bit IV
+    const cipher = createCipheriv('aes-256-gcm', this.getKey(), iv);
+    const encrypted = Buffer.concat([cipher.update(plainText, 'utf8'), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return [iv.toString('base64'), tag.toString('base64'), encrypted.toString('base64')].join('.');
+  }
+
+  /**
+   * Derive the 32-byte AES key from the configured pass-phrase. `protected` so a
+   * project can override key derivation (e.g. to source the key from a KMS).
+   */
+  /** Resolve the configured pass-phrase from config/env (no dev fallback). */
+  protected resolveSecret(): string | undefined {
+    return (
+      ConfigService.get<string>('ai.encryptionSecret') ||
+      process.env.NSC__AI__ENCRYPTION_SECRET ||
+      process.env.SECRETS_ENCRYPTION_KEY
+    );
+  }
+
+  protected getKey(): Buffer {
+    const raw = this.resolveSecret();
+    if (!raw) {
+      if (!this.warned) {
+        this.logger.warn(
+          'No AI encryption secret set (ai.encryptionSecret / NSC__AI__ENCRYPTION_SECRET / SECRETS_ENCRYPTION_KEY) — ' +
+            'using an insecure development default. DO NOT run this in production; set a random 32+ char value.',
+        );
+        this.warned = true;
+      }
+      return createHash('sha256').update('lt-nest-server-ai-dev-only-insecure-default').digest();
+    }
+    return createHash('sha256').update(raw, 'utf8').digest();
+  }
+}