@dangao/bun-server 1.12.1 → 2.0.1

package/src/ai-guard/ai-guard-module.ts

@@ -0,0 +1,50 @@
+import { Module, MODULE_METADATA_KEY } from '../di/module';
+import type { ModuleProvider } from '../di/module';
+import { AiGuardService } from './service';
+import {
+  AI_GUARD_SERVICE_TOKEN,
+  AI_GUARD_OPTIONS_TOKEN,
+  type AiGuardModuleOptions,
+} from './types';
+
+@Module({ providers: [] })
+export class AiGuardModule {
+  /**
+   * Configure AI safety guards.
+   *
+   * @example
+   * ```typescript
+   * AiGuardModule.forRoot({
+   *   piiDetection: true,
+   *   moderation: { openaiApiKey: process.env.OPENAI_API_KEY },
+   *   promptInjection: { sensitivity: 'medium' },
+   * });
+   * ```
+   */
+  public static forRoot(options: AiGuardModuleOptions = {}): typeof AiGuardModule {
+    const service = new AiGuardService(options);
+
+    const providers: ModuleProvider[] = [
+      { provide: AI_GUARD_OPTIONS_TOKEN, useValue: options },
+      { provide: AI_GUARD_SERVICE_TOKEN, useValue: service },
+      AiGuardService,
+    ];
+
+    const existing = Reflect.getMetadata(MODULE_METADATA_KEY, AiGuardModule) || {};
+    Reflect.defineMetadata(MODULE_METADATA_KEY, {
+      ...existing,
+      providers: [...(existing.providers || []), ...providers],
+      exports: [
+        ...(existing.exports || []),
+        AI_GUARD_SERVICE_TOKEN,
+        AiGuardService,
+      ],
+    }, AiGuardModule);
+
+    return AiGuardModule;
+  }
+
+  public static reset(): void {
+    Reflect.deleteMetadata(MODULE_METADATA_KEY, AiGuardModule);
+  }
+}

package/src/ai-guard/decorators.ts

@@ -0,0 +1,21 @@
+import type { AiGuardModuleOptions } from './types';
+import { AI_GUARD_METADATA_KEY } from './types';
+
+/**
+ * Mark a controller method to run AI guard checks on the request body.
+ * Requires `AiGuardModule` to be configured.
+ *
+ * @example
+ * ```typescript
+ * \@POST('/chat')
+ * \@AiGuard({ piiDetection: true, moderation: true, promptInjection: true })
+ * public async chat(\@Body() body: { message: string }) {
+ *   // body.message has already been checked and sanitized
+ * }
+ * ```
+ */
+export function AiGuard(options: Partial<AiGuardModuleOptions> = {}): MethodDecorator {
+  return (target, propertyKey) => {
+    Reflect.defineMetadata(AI_GUARD_METADATA_KEY, options, target, propertyKey);
+  };
+}

package/src/ai-guard/detectors/content-moderator.ts

@@ -0,0 +1,80 @@
+import type { ModerationResult } from '../types';
+
+export interface ContentModeratorConfig {
+  /** OpenAI API key for the Moderation API */
+  openaiApiKey?: string;
+  /** Custom moderator function (overrides OpenAI if provided) */
+  moderator?: (text: string) => Promise<ModerationResult>;
+  /** Categories that will cause content to be flagged */
+  blockCategories?: string[];
+}
+
+/**
+ * Content moderation using OpenAI Moderation API or a custom function.
+ */
+export class ContentModerator {
+  private readonly config: ContentModeratorConfig;
+
+  public constructor(config: ContentModeratorConfig = {}) {
+    this.config = config;
+  }
+
+  /**
+   * Check text for harmful content
+   */
+  public async moderate(text: string): Promise<ModerationResult> {
+    if (this.config.moderator) {
+      return this.config.moderator(text);
+    }
+
+    if (this.config.openaiApiKey) {
+      return this.moderateWithOpenAI(text);
+    }
+
+    // No moderation configured — allow all
+    return { flagged: false, categories: {}, scores: {} };
+  }
+
+  /**
+   * Check whether the result should block the request
+   */
+  public isBlocked(result: ModerationResult): boolean {
+    if (!result.flagged) return false;
+    const blockCategories = this.config.blockCategories;
+    if (!blockCategories || blockCategories.length === 0) return true;
+    return blockCategories.some((cat) => result.categories[cat]);
+  }
+
+  private async moderateWithOpenAI(text: string): Promise<ModerationResult> {
+    const res = await fetch('https://api.openai.com/v1/moderations', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${this.config.openaiApiKey}`,
+      },
+      body: JSON.stringify({ input: text }),
+    });
+
+    if (!res.ok) {
+      // On API error, fail open (allow) to avoid disrupting service
+      return { flagged: false, categories: {}, scores: {} };
+    }
+
+    const data = await res.json() as {
+      results: Array<{
+        flagged: boolean;
+        categories: Record<string, boolean>;
+        category_scores: Record<string, number>;
+      }>;
+    };
+
+    const result = data.results[0];
+    if (!result) return { flagged: false, categories: {}, scores: {} };
+
+    return {
+      flagged: result.flagged,
+      categories: result.categories,
+      scores: result.category_scores,
+    };
+  }
+}

package/src/ai-guard/detectors/injection-detector.ts

@@ -0,0 +1,48 @@
+import type { InjectionDetectionResult } from '../types';
+
+/** Common prompt injection patterns */
+const INJECTION_PATTERNS: Array<{ pattern: RegExp; reason: string; weight: number }> = [
+  { pattern: /ignore\s+(all\s+)?previous\s+instructions?/i, reason: 'ignore_instructions', weight: 0.9 },
+  { pattern: /forget\s+(all\s+)?previous\s+instructions?/i, reason: 'forget_instructions', weight: 0.9 },
+  { pattern: /you\s+are\s+now\s+(?:a\s+)?(?:different|new|another)/i, reason: 'role_override', weight: 0.7 },
+  { pattern: /disregard\s+(?:your\s+)?(?:previous\s+)?(?:instructions?|guidelines?|rules?)/i, reason: 'disregard_rules', weight: 0.8 },
+  { pattern: /system\s*:\s*(?:you|your|ignore)/i, reason: 'fake_system_message', weight: 0.8 },
+  { pattern: /\[system\]/i, reason: 'system_tag_injection', weight: 0.6 },
+  { pattern: /act\s+as\s+(?:an?\s+)?(?:unrestricted|unfiltered|jailbreak)/i, reason: 'jailbreak_attempt', weight: 0.95 },
+  { pattern: /jailbreak|DAN\s+mode|developer\s+mode/i, reason: 'jailbreak_keyword', weight: 0.85 },
+  { pattern: /print\s+your\s+(?:system\s+)?prompt|reveal\s+your\s+instructions?/i, reason: 'prompt_extraction', weight: 0.7 },
+];
+
+/**
+ * Detects prompt injection attacks using heuristic pattern matching.
+ */
+export class PromptInjectionDetector {
+  private readonly threshold: number;
+
+  public constructor(sensitivity: 'low' | 'medium' | 'high' = 'medium') {
+    this.threshold = sensitivity === 'low' ? 0.85 : sensitivity === 'medium' ? 0.7 : 0.55;
+  }
+
+  /**
+   * Analyze text for prompt injection patterns
+   */
+  public detect(text: string): InjectionDetectionResult {
+    let maxScore = 0;
+    let detectedReason: string | undefined;
+
+    for (const { pattern, reason, weight } of INJECTION_PATTERNS) {
+      if (pattern.test(text)) {
+        if (weight > maxScore) {
+          maxScore = weight;
+          detectedReason = reason;
+        }
+      }
+    }
+
+    return {
+      detected: maxScore >= this.threshold,
+      confidence: maxScore,
+      reason: detectedReason,
+    };
+  }
+}

package/src/ai-guard/detectors/pii-detector.ts

@@ -0,0 +1,64 @@
+import type { PiiDetectionResult } from '../types';
+
+const PII_PATTERNS: Array<{ type: string; regex: RegExp; replacement: string }> = [
+  {
+    type: 'email',
+    regex: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/g,
+    replacement: '[EMAIL]',
+  },
+  {
+    type: 'phone',
+    regex: /(\+?1[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}\b/g,
+    replacement: '[PHONE]',
+  },
+  {
+    type: 'ssn',
+    regex: /\b\d{3}-\d{2}-\d{4}\b/g,
+    replacement: '[SSN]',
+  },
+  {
+    type: 'credit_card',
+    regex: /\b(?:\d[ -]?){13,16}\b/g,
+    replacement: '[CREDIT_CARD]',
+  },
+  {
+    type: 'ip_address',
+    regex: /\b(?:\d{1,3}\.){3}\d{1,3}\b/g,
+    replacement: '[IP_ADDRESS]',
+  },
+  {
+    type: 'url_with_credentials',
+    regex: /https?:\/\/[^:@\s]+:[^:@\s]+@[^\s]+/g,
+    replacement: '[URL_WITH_CREDENTIALS]',
+  },
+];
+
+/**
+ * Detects and optionally redacts PII from text using regex patterns.
+ */
+export class PiiDetector {
+  /**
+   * Analyze text for PII
+   */
+  public detect(text: string, redact = true): PiiDetectionResult {
+    const foundTypes = new Set<string>();
+    let sanitized = text;
+
+    for (const pattern of PII_PATTERNS) {
+      if (pattern.regex.test(text)) {
+        foundTypes.add(pattern.type);
+        if (redact) {
+          sanitized = sanitized.replace(pattern.regex, pattern.replacement);
+        }
+      }
+      // Reset regex lastIndex
+      pattern.regex.lastIndex = 0;
+    }
+
+    return {
+      detected: foundTypes.size > 0,
+      sanitized,
+      types: Array.from(foundTypes),
+    };
+  }
+}

package/src/ai-guard/index.ts

@@ -0,0 +1,7 @@
+export * from './types';
+export * from './decorators';
+export * from './service';
+export * from './ai-guard-module';
+export * from './detectors/pii-detector';
+export * from './detectors/content-moderator';
+export * from './detectors/injection-detector';

package/src/ai-guard/service.ts

@@ -0,0 +1,100 @@
+import { Injectable } from '../di/decorators';
+import { Inject } from '../di/decorators';
+import type { AiGuardModuleOptions, AiGuardResult } from './types';
+import { AI_GUARD_OPTIONS_TOKEN } from './types';
+import { PiiDetector } from './detectors/pii-detector';
+import { ContentModerator } from './detectors/content-moderator';
+import { PromptInjectionDetector } from './detectors/injection-detector';
+import { HttpException } from '../error/http-exception';
+
+/**
+ * AI Guard service — runs PII detection, content moderation, and prompt injection detection.
+ */
+@Injectable()
+export class AiGuardService {
+  private readonly piiDetector: PiiDetector | null;
+  private readonly contentModerator: ContentModerator | null;
+  private readonly injectionDetector: PromptInjectionDetector | null;
+  private readonly options: AiGuardModuleOptions;
+
+  public constructor(
+    @Inject(AI_GUARD_OPTIONS_TOKEN) options: AiGuardModuleOptions,
+  ) {
+    this.options = options;
+
+    this.piiDetector = options.piiDetection ? new PiiDetector() : null;
+
+    if (options.moderation) {
+      const modConfig = typeof options.moderation === 'object' ? options.moderation : {};
+      this.contentModerator = new ContentModerator(modConfig);
+    } else {
+      this.contentModerator = null;
+    }
+
+    if (options.promptInjection) {
+      const injConfig = typeof options.promptInjection === 'object' ? options.promptInjection : {};
+      this.injectionDetector = new PromptInjectionDetector(injConfig.sensitivity);
+    } else {
+      this.injectionDetector = null;
+    }
+  }
+
+  /**
+   * Check and optionally sanitize input text.
+   * Returns the guard result including sanitized input if PII redaction is enabled.
+   */
+  public async check(text: string): Promise<AiGuardResult> {
+    let workingText = text;
+
+    const result: AiGuardResult = { allowed: true };
+
+    // 1. PII Detection
+    if (this.piiDetector) {
+      const redact = typeof this.options.piiDetection === 'object'
+        ? this.options.piiDetection.redact !== false
+        : true;
+      const piiResult = this.piiDetector.detect(workingText, redact);
+      result.pii = piiResult;
+      if (redact && piiResult.detected) {
+        workingText = piiResult.sanitized;
+      }
+    }
+
+    // 2. Prompt Injection Detection
+    if (this.injectionDetector) {
+      const injResult = this.injectionDetector.detect(workingText);
+      result.injection = injResult;
+      if (injResult.detected) {
+        result.allowed = false;
+      }
+    }
+
+    // 3. Content Moderation
+    if (this.contentModerator && result.allowed) {
+      const modResult = await this.contentModerator.moderate(workingText);
+      result.moderation = modResult;
+      if (this.contentModerator.isBlocked(modResult)) {
+        result.allowed = false;
+      }
+    }
+
+    result.sanitizedInput = workingText;
+    return result;
+  }
+
+  /**
+   * Check and throw HttpException if the content is not allowed
+   */
+  public async checkOrThrow(text: string): Promise<string> {
+    const result = await this.check(text);
+    if (!result.allowed) {
+      const reason = result.injection?.detected
+        ? 'Prompt injection detected'
+        : result.moderation?.flagged
+          ? 'Content violates usage policies'
+          : 'Content not allowed';
+      throw new HttpException(400, reason);
+    }
+    return result.sanitizedInput ?? text;
+  }
+}

package/src/ai-guard/types.ts

@@ -0,0 +1,61 @@
+/**
+ * PII detection result
+ */
+export interface PiiDetectionResult {
+  detected: boolean;
+  /** Sanitized text with PII redacted */
+  sanitized: string;
+  /** Types of PII found */
+  types: string[];
+}
+
+/**
+ * Content moderation result
+ */
+export interface ModerationResult {
+  flagged: boolean;
+  categories: Record<string, boolean>;
+  scores: Record<string, number>;
+}
+
+/**
+ * Prompt injection detection result
+ */
+export interface InjectionDetectionResult {
+  detected: boolean;
+  confidence: number;
+  reason?: string;
+}
+
+/**
+ * Combined guard result
+ */
+export interface AiGuardResult {
+  allowed: boolean;
+  pii?: PiiDetectionResult;
+  moderation?: ModerationResult;
+  injection?: InjectionDetectionResult;
+  sanitizedInput?: string;
+}
+
+export interface AiGuardModuleOptions {
+  /** Enable PII detection and redaction */
+  piiDetection?: boolean | { redact?: boolean };
+  /** Content moderation configuration */
+  moderation?: boolean | {
+    /** OpenAI API key for moderation (uses OpenAI Moderation API) */
+    openaiApiKey?: string;
+    /** Custom moderation function */
+    moderator?: (text: string) => Promise<ModerationResult>;
+    /** Categories to block */
+    blockCategories?: string[];
+  };
+  /** Prompt injection detection */
+  promptInjection?: boolean | {
+    sensitivity?: 'low' | 'medium' | 'high';
+  };
+}
+
+export const AI_GUARD_SERVICE_TOKEN = Symbol('@dangao/bun-server:ai-guard:service');
+export const AI_GUARD_OPTIONS_TOKEN = Symbol('@dangao/bun-server:ai-guard:options');
+export const AI_GUARD_METADATA_KEY = '@dangao/bun-server:ai-guard:options';

package/src/conversation/conversation-module.ts

@@ -0,0 +1,63 @@
+import { Module, MODULE_METADATA_KEY } from '../di/module';
+import type { ModuleProvider } from '../di/module';
+import { ConversationService } from './service';
+import {
+  CONVERSATION_SERVICE_TOKEN,
+  CONVERSATION_OPTIONS_TOKEN,
+  type ConversationModuleOptions,
+} from './types';
+import { MemoryConversationStore } from './stores/memory-store';
+
+@Module({ providers: [] })
+export class ConversationModule {
+  /**
+   * Configure the conversation module with a store and optional auto-trim/summarize settings.
+   *
+   * @example
+   * ```typescript
+   * ConversationModule.forRoot({
+   *   store: new MemoryConversationStore(),
+   *   maxMessages: 50,
+   *   autoTrim: true,
+   *   summaryThreshold: 40,
+   *   summarizer: async (messages) => {
+   *     return await aiService.complete({ messages: [...messages, summaryRequest] }).then(r => r.content);
+   *   },
+   * });
+   * ```
+   */
+  public static forRoot(options: ConversationModuleOptions = {}): typeof ConversationModule {
+    const resolvedOptions: ConversationModuleOptions = {
+      ...options,
+      store: options.store ?? new MemoryConversationStore(),
+    };
+
+    const service = new ConversationService(resolvedOptions as ConversationModuleOptions & { store: NonNullable<ConversationModuleOptions['store']> });
+
+    const providers: ModuleProvider[] = [
+      { provide: CONVERSATION_OPTIONS_TOKEN, useValue: resolvedOptions },
+      { provide: CONVERSATION_SERVICE_TOKEN, useValue: service },
+      ConversationService,
+    ];
+
+    const existing = Reflect.getMetadata(MODULE_METADATA_KEY, ConversationModule) || {};
+    Reflect.defineMetadata(MODULE_METADATA_KEY, {
+      ...existing,
+      providers: [...(existing.providers || []), ...providers],
+      exports: [
+        ...(existing.exports || []),
+        CONVERSATION_SERVICE_TOKEN,
+        ConversationService,
+      ],
+    }, ConversationModule);
+
+    return ConversationModule;
+  }
+
+  /**
+   * Reset module state (for testing)
+   */
+  public static reset(): void {
+    Reflect.deleteMetadata(MODULE_METADATA_KEY, ConversationModule);
+  }
+}

package/src/conversation/decorators.ts

@@ -0,0 +1,47 @@
+import type { Context } from '../core/context';
+
+/**
+ * Parameter decorator — extracts the conversation ID from the request context
+ * (from query param, header, or body) and injects it into the method parameter.
+ *
+ * The decorator looks for `conversationId` in: query params → headers → request body.
+ *
+ * @example
+ * ```typescript
+ * \@POST('/chat')
+ * public async chat(
+ *   \@InjectConversation() conversationId: string | undefined,
+ *   \@Body() body: { message: string },
+ * ) {
+ *   const history = conversationId
+ *     ? await this.conversationService.getHistory(conversationId)
+ *     : [];
+ *   // ...
+ * }
+ * ```
+ */
+export function InjectConversation(): ParameterDecorator {
+  return (target, propertyKey, parameterIndex) => {
+    const existing: number[] =
+      Reflect.getMetadata('conversation:inject:params', target, propertyKey!) ?? [];
+    existing.push(parameterIndex);
+    Reflect.defineMetadata('conversation:inject:params', existing, target, propertyKey!);
+  };
+}
+
+/**
+ * Extract conversation ID from a Bun Context object.
+ * Checks: query.conversationId → headers['x-conversation-id'] → (parsed body).conversationId
+ */
+export function extractConversationId(ctx: Context): string | undefined {
+  // From query param
+  const url = new URL(ctx.request.url);
+  const fromQuery = url.searchParams.get('conversationId');
+  if (fromQuery) return fromQuery;
+
+  // From header
+  const fromHeader = ctx.request.headers.get('x-conversation-id');
+  if (fromHeader) return fromHeader;
+
+  return undefined;
+}

package/src/conversation/index.ts

@@ -0,0 +1,7 @@
+export * from './types';
+export * from './service';
+export * from './decorators';
+export * from './conversation-module';
+export * from './stores/memory-store';
+export * from './stores/redis-store';
+export * from './stores/database-store';

package/src/conversation/service.ts

@@ -0,0 +1,133 @@
+import { Injectable } from '../di/decorators';
+import { Inject } from '../di/decorators';
+import type { ConversationStore, ConversationModuleOptions, Conversation } from './types';
+import { CONVERSATION_OPTIONS_TOKEN } from './types';
+import type { AiMessage } from '../ai/types';
+
+/**
+ * Manages conversation sessions — create, retrieve, append messages,
+ * auto-trim, and optional summarization.
+ */
+@Injectable()
+export class ConversationService {
+  private readonly store: ConversationStore;
+  private readonly maxMessages: number;
+  private readonly autoTrim: boolean;
+  private readonly summaryThreshold: number | undefined;
+
+  public constructor(
+    @Inject(CONVERSATION_OPTIONS_TOKEN) options: ConversationModuleOptions,
+  ) {
+    this.store = options.store!;
+    this.maxMessages = options.maxMessages ?? 100;
+    this.autoTrim = options.autoTrim ?? true;
+    this.summaryThreshold = options.summaryThreshold;
+  }
+
+  /**
+   * Create a new conversation session
+   */
+  public async create(metadata?: Record<string, unknown>): Promise<Conversation> {
+    return this.store.create(metadata);
+  }
+
+  /**
+   * Get a conversation by ID
+   */
+  public async get(id: string): Promise<Conversation | null> {
+    return this.store.get(id);
+  }
+
+  /**
+   * Get conversation history (messages only)
+   */
+  public async getHistory(id: string): Promise<AiMessage[]> {
+    const conv = await this.store.get(id);
+    return conv?.messages ?? [];
+  }
+
+  /**
+   * Append a message and apply auto-trim / summarization if configured
+   */
+  public async appendMessage(id: string, message: AiMessage, options?: ConversationModuleOptions): Promise<void> {
+    await this.store.appendMessage(id, message);
+
+    const opts = options ?? {};
+    const summarizer = opts.summarizer;
+    const summaryThreshold = this.summaryThreshold;
+
+    if (summaryThreshold && summarizer) {
+      const conv = await this.store.get(id);
+      if (conv && conv.messages.length >= summaryThreshold) {
+        await this.summarizeAndCompress(id, conv.messages, summarizer);
+        return;
+      }
+    }
+
+    if (this.autoTrim) {
+      await this.store.trim(id, this.maxMessages);
+    }
+  }
+
+  /**
+   * Delete a conversation
+   */
+  public async delete(id: string): Promise<boolean> {
+    return this.store.delete(id);
+  }
+
+  /**
+   * List all conversation IDs
+   */
+  public async list(): Promise<string[]> {
+    return this.store.list();
+  }
+
+  /**
+   * Manually compress conversation by summarizing old messages
+   */
+  public async summarize(
+    id: string,
+    summarizer: (messages: AiMessage[]) => Promise<string>,
+  ): Promise<void> {
+    const conv = await this.store.get(id);
+    if (!conv) return;
+    await this.summarizeAndCompress(id, conv.messages, summarizer);
+  }
+
+  private async summarizeAndCompress(
+    id: string,
+    messages: AiMessage[],
+    summarizer: (messages: AiMessage[]) => Promise<string>,
+  ): Promise<void> {
+    const keepCount = Math.floor(this.maxMessages / 4);
+    const toSummarize = messages.slice(0, -keepCount);
+    const toKeep = messages.slice(-keepCount);
+
+    if (toSummarize.length === 0) return;
+
+    try {
+      const summary = await summarizer(toSummarize);
+      const summaryMessage: AiMessage = {
+        role: 'system',
+        content: `[Conversation summary: ${summary}]`,
+      };
+
+      const conv = await this.store.get(id);
+      if (!conv) return;
+
+      // Replace the conversation with summary + recent messages
+      const newMessages = [summaryMessage, ...toKeep];
+      for (const _msg of conv.messages) {
+        await this.store.trim(id, 0);
+      }
+      // Re-add compressed messages
+      for (const msg of newMessages) {
+        await this.store.appendMessage(id, msg);
+      }
+    } catch {
+      // If summarization fails, fall back to simple trim
+      await this.store.trim(id, this.maxMessages);
+    }
+  }
+}