@joliegg/moderation 0.6.0 → 0.9.0

package/src/rubrics/rubric.ts

@@ -0,0 +1,62 @@
+import type { ModerationCategory, Severity } from '../types';
+import type { RubricResult, RubricRule } from './types';
+
+const SEVERITY_ORDER: Record<Severity, number> = {
+  low: 0,
+  medium: 1,
+  high: 2,
+  critical: 3,
+};
+
+/**
+ * Composable classifier-to-action mapping.
+ *
+ * Callers hand a `ScoringRubric` their classifier output
+ * (`ModerationCategory[]`) and get back a decision: the recommended
+ * action, the aggregate severity, and the categories that contributed.
+ *
+ * Apps can use the ship-with defaults (`STRICT_RUBRIC`,
+ * `PERMISSIVE_RUBRIC`, `NSFW_ONLY_RUBRIC`) or pass custom rules.
+ *
+ * Rules are evaluated in input order; the highest-severity match wins
+ * the recommended action. Every matched category is returned in the
+ * result so callers can explain the decision.
+ */
+export class ScoringRubric {
+  constructor(private rules: RubricRule[]) {}
+
+  evaluate(categories: ModerationCategory[]): RubricResult {
+    const matched: ModerationCategory[] = [];
+    const reasons: string[] = [];
+
+    let best: RubricRule | null = null;
+
+    for (const category of categories) {
+      for (const rule of this.rules) {
+        const categoryMatches = rule.match.category === undefined || category.category.includes(rule.match.category);
+
+        if (!categoryMatches) {
+          continue;
+        }
+
+        if (category.confidence < rule.match.minConfidence) {
+          continue;
+        }
+
+        matched.push(category);
+        reasons.push(`${category.category} (${category.confidence.toFixed(0)}%) >= ${rule.match.minConfidence}% → ${rule.action}`);
+
+        if (!best || SEVERITY_ORDER[rule.severity] > SEVERITY_ORDER[best.severity]) {
+          best = rule;
+        }
+      }
+    }
+
+    return {
+      action: best?.action ?? null,
+      severity: best?.severity ?? 'low',
+      matched,
+      reasons,
+    };
+  }
+}

package/src/rubrics/types.ts

@@ -0,0 +1,30 @@
+import type { ModerationCategory, Severity } from '../types';
+import type { ActionType } from '../actions';
+
+export interface RubricMatch {
+  /**
+   * Category name to match. Omit for a wildcard that fires on any category.
+   * Matched with substring `includes`, so a rule for `sexual` also fires
+   * on compound categories like `sexual/minors`.
+   */
+  category?: string;
+  /** Minimum confidence (0-100) required for this rule to fire. */
+  minConfidence: number;
+}
+
+export interface RubricRule {
+  match: RubricMatch;
+  action: ActionType;
+  severity: Severity;
+}
+
+export interface RubricResult {
+  /** The action the highest-severity matched rule recommends. */
+  action: ActionType | null;
+  /** Aggregate severity — matches the winning rule, or `'low'` if nothing matched. */
+  severity: Severity;
+  /** Every category that matched at least one rule. */
+  matched: ModerationCategory[];
+  /** Human-readable explanations — one per matched rule. */
+  reasons: string[];
+}

package/src/spam/cache.ts

@@ -0,0 +1,342 @@
+import { createHash } from 'node:crypto';
+import { normalizeText } from '../text/normalize';
+
+/**
+ * MD5 hash for content fingerprinting.
+ *
+ * Prefers Bun.CryptoHasher when available, falls back to node:crypto
+ */
+const md5 = (input: string): string => {
+  // @ts-expect-error — Bun global is not in node types
+  if (typeof Bun !== 'undefined' && Bun.CryptoHasher) {
+    // @ts-expect-error — same
+    const hasher = new Bun.CryptoHasher('md5');
+    hasher.update(input);
+    return hasher.digest('hex');
+  }
+
+  return createHash('md5').update(input).digest('hex');
+};
+
+export interface SpamCacheOptions {
+  /** Maximum messages allowed within the rate-limit window. Default 8. */
+  rateLimit?: number;
+  /** Rate-limit window in seconds. Default 10. */
+  rateLimitWindow?: number;
+  /** How many identical messages trigger a duplicate alert. Default 3. */
+  duplicateThreshold?: number;
+  /** Duplicate-detection window in seconds. Default 30. */
+  duplicateWindow?: number;
+  /** Daytime timeout duration in minutes. Default 180. */
+  timeoutDurationDay?: number;
+  /** Hour of day (0-23) when nighttime timeouts start. Default 23. */
+  nightStartHour?: number;
+  /** Hour of day (0-23) when nighttime timeouts end. Default 11. */
+  nightEndHour?: number;
+  /** IANA timezone for night detection. Default 'America/Mexico_City'. */
+  timezone?: string;
+  /** LRU capacity for tracked users. Default 10000. */
+  maxUsers?: number;
+}
+
+export interface SpamContent {
+  text?: string;
+  attachments?: { name: string; size: number }[];
+  stickerIds?: string[];
+  messageId?: string | null;
+  channelId?: string | null;
+}
+
+export interface SpamMessageRef {
+  messageId: string;
+  channelId: string;
+}
+
+export type SpamReason = 'rate_limit' | 'duplicate';
+
+export interface SpamResult {
+  isSpam: boolean;
+  reason: SpamReason | null;
+  details: string | null;
+  /**
+   * Message references that contributed to the spam trigger.
+   */
+  priorMessageIds?: SpamMessageRef[];
+}
+
+export interface SpamCacheStats {
+  trackedUsers: number;
+  maxUsers: number;
+  totalTimestamps: number;
+  totalHashes: number;
+  config: {
+    rateLimit: number;
+    rateLimitWindowSeconds: number;
+    duplicateThreshold: number;
+    duplicateWindowSeconds: number;
+    timeoutDurationDayMinutes: number;
+    nightHours: string;
+    timezone: string;
+    isNightTime: boolean;
+    currentTimeoutMinutes: number;
+  };
+}
+
+interface TimestampEntry {
+  time: number;
+  channelId: string | null;
+  messageId: string | null;
+}
+
+interface HashEntry {
+  hash: string;
+  timestamp: number;
+  messageId: string | null;
+  channelId: string | null;
+}
+
+interface UserTracking {
+  timestamps: TimestampEntry[];
+  messageHashes: HashEntry[];
+}
+
+/**
+ * Spam Cache. Tracks per-user message timestamps and content hashes to detect
+ * three kinds of abuse:
+ *
+ *  - Rate limit: too many messages in a rolling window
+ *  - Duplicate: the same content repeated across messages
+ *  - Cross-channel: the same user hopping channels in quick succession
+ *
+ * Consumers are responsible for calling `cleanup()` periodically to
+ * evict expired entries.
+ */
+export class SpamCache {
+  readonly rateLimit: number;
+  readonly rateLimitWindow: number;
+  readonly duplicateThreshold: number;
+  readonly duplicateWindow: number;
+  readonly timeoutDurationDay: number;
+  readonly nightStartHour: number;
+  readonly nightEndHour: number;
+  readonly timezone: string;
+  readonly maxUsers: number;
+
+  private userTracking = new Map<string, UserTracking>();
+
+  constructor(options: SpamCacheOptions = {}) {
+    this.rateLimit = options.rateLimit ?? 8;
+    this.rateLimitWindow = (options.rateLimitWindow ?? 10) * 1000;
+    this.duplicateThreshold = options.duplicateThreshold ?? 3;
+    this.duplicateWindow = (options.duplicateWindow ?? 30) * 1000;
+    this.timeoutDurationDay = options.timeoutDurationDay ?? 180;
+    this.nightStartHour = options.nightStartHour ?? 23;
+    this.nightEndHour = options.nightEndHour ?? 11;
+    this.timezone = options.timezone ?? 'America/Mexico_City';
+    this.maxUsers = options.maxUsers ?? 10000;
+  }
+
+  private hashContent(content: string): string {
+    return md5(normalizeText(content));
+  }
+
+  private generateContentId(options: SpamContent): string {
+    const { text, attachments = [], stickerIds = [] } = options;
+    const parts: string[] = [];
+
+    if (text && text.trim()) {
+      parts.push(`text:${this.hashContent(text)}`);
+    }
+
+    if (attachments.length > 0) {
+      const fingerprints = attachments.map(a => `${a.name}:${a.size}`).sort();
+      parts.push(`attachments:${this.hashContent(fingerprints.join('|'))}`);
+    }
+
+    if (stickerIds.length > 0) {
+      const sorted = [...stickerIds].sort();
+      parts.push(`stickers:${sorted.join(',')}`);
+    }
+
+    if (parts.length === 0) {
+      return `empty:${Date.now()}`;
+    }
+
+    return parts.join('::');
+  }
+
+  private getTracking(userId: string): UserTracking {
+    if (!this.userTracking.has(userId)) {
+      if (this.userTracking.size >= this.maxUsers) {
+        const firstKey = this.userTracking.keys().next().value;
+
+        if (firstKey !== undefined) {
+          this.userTracking.delete(firstKey);
+        }
+      }
+
+      this.userTracking.set(userId, { timestamps: [], messageHashes: [] });
+    }
+
+    return this.userTracking.get(userId)!;
+  }
+
+  private cleanupTracking(tracking: UserTracking, now: number): void {
+    tracking.timestamps = tracking.timestamps.filter(e => now - e.time < this.rateLimitWindow);
+    tracking.messageHashes = tracking.messageHashes.filter(e => now - e.timestamp < this.duplicateWindow);
+  }
+
+  track(userId: string, content: SpamContent): SpamResult {
+    const now = Date.now();
+    const tracking = this.getTracking(userId);
+
+    this.cleanupTracking(tracking, now);
+
+    const messageId = content.messageId ?? null;
+    const channelId = content.channelId ?? null;
+    const contentId = this.generateContentId(content);
+
+    tracking.timestamps.push({ time: now, channelId, messageId });
+
+    const collectPriorMessageIds = (): SpamMessageRef[] =>
+      tracking.timestamps
+        .filter(t => t.messageId && t.channelId)
+        .map(t => ({ messageId: t.messageId!, channelId: t.channelId! }));
+
+    if (tracking.timestamps.length > this.rateLimit) {
+      return {
+        isSpam: true,
+        reason: 'rate_limit',
+        details: `Sent ${tracking.timestamps.length} messages in ${this.rateLimitWindow / 1000} seconds (limit: ${this.rateLimit})`,
+        priorMessageIds: collectPriorMessageIds(),
+      };
+    }
+
+    const uniqueChannels = new Set(tracking.timestamps.map(t => t.channelId).filter(Boolean)).size;
+    if (uniqueChannels >= 3) {
+      return {
+        isSpam: true,
+        reason: 'rate_limit',
+        details: `Cross-channel spam detected: Posted in ${uniqueChannels} channels in ${this.rateLimitWindow / 1000} seconds`,
+        priorMessageIds: collectPriorMessageIds(),
+      };
+    }
+
+    if (!contentId.startsWith('empty:')) {
+      const duplicates = tracking.messageHashes.filter(e => e.hash === contentId);
+      const duplicateCount = duplicates.length;
+
+      tracking.messageHashes.push({ hash: contentId, timestamp: now, messageId, channelId });
+
+      if (duplicateCount >= this.duplicateThreshold - 1) {
+        const priorMessageIds = duplicates
+          .filter(e => e.messageId && e.channelId)
+          .map(e => ({ messageId: e.messageId!, channelId: e.channelId! }));
+
+        return {
+          isSpam: true,
+          reason: 'duplicate',
+          details: `Sent the same content ${duplicateCount + 1} times in ${this.duplicateWindow / 1000} seconds (limit: ${this.duplicateThreshold})`,
+          priorMessageIds,
+        };
+      }
+    } else {
+      tracking.messageHashes.push({ hash: contentId, timestamp: now, messageId, channelId });
+    }
+
+    return { isSpam: false, reason: null, details: null };
+  }
+
+  reset(userId: string): void {
+    this.userTracking.delete(userId);
+  }
+
+  clear(): void {
+    this.userTracking.clear();
+  }
+
+  getStats(): SpamCacheStats {
+    let totalTimestamps = 0;
+    let totalHashes = 0;
+
+    for (const tracking of this.userTracking.values()) {
+      totalTimestamps += tracking.timestamps.length;
+      totalHashes += tracking.messageHashes.length;
+    }
+
+    return {
+      trackedUsers: this.userTracking.size,
+      maxUsers: this.maxUsers,
+      totalTimestamps,
+      totalHashes,
+      config: {
+        rateLimit: this.rateLimit,
+        rateLimitWindowSeconds: this.rateLimitWindow / 1000,
+        duplicateThreshold: this.duplicateThreshold,
+        duplicateWindowSeconds: this.duplicateWindow / 1000,
+        timeoutDurationDayMinutes: this.timeoutDurationDay,
+        nightHours: `${this.nightStartHour}:00 - ${this.nightEndHour}:00`,
+        timezone: this.timezone,
+        isNightTime: this.isNightTime(),
+        currentTimeoutMinutes: this.getTimeoutDurationMinutes(),
+      },
+    };
+  }
+
+  private getCurrentTime(): { hour: number; minute: number } {
+    const now = new Date();
+    const hour = parseInt(
+      new Intl.DateTimeFormat('en-US', { timeZone: this.timezone, hour: 'numeric', hour12: false }).format(now)
+    );
+
+    const minute = parseInt(
+      new Intl.DateTimeFormat('en-US', { timeZone: this.timezone, minute: 'numeric' }).format(now)
+    );
+
+    return { hour, minute };
+  }
+
+  isNightTime(): boolean {
+    const { hour } = this.getCurrentTime();
+
+    if (this.nightStartHour > this.nightEndHour) {
+      return hour >= this.nightStartHour || hour < this.nightEndHour;
+    }
+
+    return hour >= this.nightStartHour && hour < this.nightEndHour;
+  }
+
+  getMinutesUntilNightEnd(): number {
+    const { hour, minute } = this.getCurrentTime();
+    const hoursUntilEnd =
+      hour >= this.nightStartHour ? (24 - hour) + this.nightEndHour : this.nightEndHour - hour;
+    const totalMinutes = hoursUntilEnd * 60 - minute;
+
+    return Math.max(totalMinutes, 60);
+  }
+
+  getTimeoutDurationMinutes(): number {
+    return this.isNightTime() ? this.getMinutesUntilNightEnd() : this.timeoutDurationDay;
+  }
+
+  getTimeoutDurationMs(): number {
+    return this.getTimeoutDurationMinutes() * 60 * 1000;
+  }
+
+  cleanup(): number {
+    const now = Date.now();
+    const toDelete: string[] = [];
+
+    for (const [userId, tracking] of this.userTracking.entries()) {
+      this.cleanupTracking(tracking, now);
+
+      if (tracking.timestamps.length === 0 && tracking.messageHashes.length === 0) {
+        toDelete.push(userId);
+      }
+    }
+
+    toDelete.forEach(userId => this.userTracking.delete(userId));
+
+    return toDelete.length;
+  }
+}

package/src/spam/index.ts

@@ -0,0 +1 @@
+export * from './cache';

package/src/text/index.ts

@@ -0,0 +1,2 @@
+export * from './normalize';
+export * from './mentions';

package/src/text/mentions.ts

@@ -0,0 +1,91 @@
+export interface MentionConfig {
+  /** Maximum number of distinct user mentions per message. */
+  maxUserMentions: number;
+  /** Maximum number of distinct role mentions per message. */
+  maxRoleMentions: number;
+  /** Maximum number of total mentions (user + role) per message. */
+  maxTotalMentions: number;
+  /** Whether to treat `@everyone` as spam for the sender. */
+  blockEveryone: boolean;
+  /** Whether to treat `@here` as spam for the sender. */
+  blockHere: boolean;
+}
+
+export interface MentionCounts {
+  userMentions: number;
+  roleMentions: number;
+  hasEveryone: boolean;
+  hasHere: boolean;
+}
+
+export type MentionSpamReason =
+  | 'mention_everyone'
+  | 'mention_here'
+  | 'mention_users'
+  | 'mention_roles'
+  | 'mention_total';
+
+export interface MentionSpamResult {
+  isSpam: boolean;
+  reason: MentionSpamReason | null;
+  details: string | null;
+}
+
+export const DEFAULT_MENTION_CONFIG: MentionConfig = {
+  maxUserMentions: 5,
+  maxRoleMentions: 3,
+  maxTotalMentions: 8,
+  blockEveryone: true,
+  blockHere: true,
+};
+
+/**
+ * Mention-spam check.
+ *
+ * `@everyone` detection takes priority over other reasons.
+ */
+export function checkMentionSpam(counts: MentionCounts, config: MentionConfig): MentionSpamResult {
+  if (config.blockEveryone && counts.hasEveryone) {
+    return {
+      isSpam: true,
+      reason: 'mention_everyone',
+      details: '@everyone mentioned without permission',
+    };
+  }
+
+  if (config.blockHere && counts.hasHere) {
+    return {
+      isSpam: true,
+      reason: 'mention_here',
+      details: '@here mentioned without permission',
+    };
+  }
+
+  if (counts.userMentions > config.maxUserMentions) {
+    return {
+      isSpam: true,
+      reason: 'mention_users',
+      details: `${counts.userMentions} user mentions (limit: ${config.maxUserMentions})`,
+    };
+  }
+
+  if (counts.roleMentions > config.maxRoleMentions) {
+    return {
+      isSpam: true,
+      reason: 'mention_roles',
+      details: `${counts.roleMentions} role mentions (limit: ${config.maxRoleMentions})`,
+    };
+  }
+
+  const total = counts.userMentions + counts.roleMentions;
+
+  if (total > config.maxTotalMentions) {
+    return {
+      isSpam: true,
+      reason: 'mention_total',
+      details: `${total} total mentions (limit: ${config.maxTotalMentions})`,
+    };
+  }
+
+  return { isSpam: false, reason: null, details: null };
+}

package/src/text/normalize.ts

@@ -0,0 +1,43 @@
+/**
+ * Invisible / zero-width Unicode code points that users sometimes insert
+ * between letters to bypass substring-based filters. NFKC normalization
+ * does NOT collapse these on its own, so we strip them explicitly before
+ * normalizing.
+ *
+ * - U+200B Zero-Width Space
+ * - U+200C Zero-Width Non-Joiner
+ * - U+200D Zero-Width Joiner
+ * - U+200E Left-to-Right Mark
+ * - U+200F Right-to-Left Mark
+ * - U+2060 Word Joiner
+ * - U+FEFF Zero-Width No-Break Space (BOM)
+ */
+// Matching individual zero-width code points by design (we are stripping
+// them, not joining anything). ESLint's no-misleading-character-class
+// flags this since \u200d is the Zero-Width Joiner; the warning does not
+// apply here because every code point in the class is a literal target.
+// eslint-disable-next-line no-misleading-character-class
+const ZERO_WIDTH = /[\u200b\u200c\u200d\u200e\u200f\u2060\ufeff]/gu;
+
+/**
+ * Canonicalizes user-submitted text for content matching:
+ *
+ *  1. trim surrounding whitespace
+ *  2. lowercase
+ *  3. strip zero-width / invisible characters
+ *  4. NFKC normalize (collapses bold, italic, fullwidth, circled,
+ *     small-caps, and other compatibility variants to ASCII)
+ *  5. collapse internal whitespace runs to single spaces
+ *
+ * Useful for spam hashing, ban-list matching, and any other comparison
+ * where users should not be able to defeat a match by visually similar
+ * but technically distinct input.
+ */
+export function normalizeText(input: string): string {
+  return input
+    .trim()
+    .toLowerCase()
+    .replace(ZERO_WIDTH, '')
+    .normalize('NFKC')
+    .replace(/\s+/g, ' ');
+}

package/src/types/config.ts

@@ -0,0 +1,14 @@
+import type { RekognitionClientConfig } from '@aws-sdk/client-rekognition';
+
+export interface ModerationConfiguration {
+  aws?: RekognitionClientConfig;
+  google?: {
+    apiKey?: string;
+    keyFile?: string;
+  };
+  openai?: {
+    apiKey?: string;
+  };
+  banList?: string[];
+  urlBlackList?: string[];
+}

package/src/types/index.ts

@@ -1,19 +1,13 @@
-import { RekognitionClientConfig } from '@aws-sdk/client-rekognition';
+export * from './config';
 
-export interface ModerationConfiguration {
-  aws?: RekognitionClientConfig;
-  google?: {
-    apiKey?: string;
-    keyFile?: string;
-  };
-  banList?: string[];
-  urlBlackList?: string[];
-}
+export type Severity = 'low' | 'medium' | 'high' | 'critical';
 
 export interface ModerationCategory {
   category: string;
   confidence: number;
+  severity?: Severity;
 }
+
 export interface ModerationResult {
   source: string;
   moderation: ModerationCategory[];
@@ -29,4 +23,4 @@ export interface ThreatsResponse {
     threatTypes: string[];
     expireTime: string;
   };
-}
+}