@joliegg/moderation 0.4.4 → 0.8.0

package/src/raid/detector.ts

@@ -0,0 +1,122 @@
+export interface RaidDetectorOptions {
+  /** Number of joins within the window that constitutes a raid. Default to 10 (very small community) but this really depends on community size and activity. */
+  joinThreshold?: number;
+  /** Sliding window in seconds. Default to 60 seconds (1 minute). */
+  joinWindow?: number;
+}
+
+export interface MemberJoin {
+  memberId: string;
+  joinedTimestamp: number;
+  createdTimestamp: number;
+}
+
+export interface RaidTrackResult {
+  isRaid: boolean;
+  joinCount: number;
+  windowSeconds: number;
+}
+
+export type EnableResult = 'enabled' | 'already_active' | 'already_enabling';
+
+interface JoinEvent {
+  memberId: string;
+  timestamp: number;
+}
+
+interface GuildState {
+  joins: JoinEvent[];
+  raidActive: boolean;
+}
+
+/**
+ * Platform-agnostic raid detector. Tracks recent joins per guild in a
+ * sliding window and surfaces the "raid" signal when the join count
+ * crosses the configured threshold.
+ *
+ * State transitions (`tryEnable`, `disable`) are guarded by an
+ * in-memory mutex so concurrent `handleMemberJoin` invocations during
+ * a join burst cannot both see "not active" and double-fire the
+ * enable side effects.
+ *
+ * The detector owns the sliding-window state. It does NOT own the
+ * enforcement — callers decide what to do when `isRaid` is true
+ * (timeout, kick, auto-disable timer, mod-channel alert, etc.).
+ */
+export class RaidDetector {
+  readonly joinThreshold: number;
+  readonly joinWindow: number;
+
+  private state = new Map<string, GuildState>();
+  private enabling = new Set<string>();
+
+  constructor(options: RaidDetectorOptions = {}) {
+    this.joinThreshold = options.joinThreshold ?? 10;
+    this.joinWindow = (options.joinWindow ?? 60) * 1000;
+  }
+
+  private getState(guildId: string): GuildState {
+    if (!this.state.has(guildId)) {
+      this.state.set(guildId, { joins: [], raidActive: false });
+    }
+    return this.state.get(guildId)!;
+  }
+
+  private cleanupJoins(state: GuildState, now: number): void {
+    state.joins = state.joins.filter(j => now - j.timestamp < this.joinWindow);
+  }
+
+  /**
+   * Record a join and return whether the guild has crossed the raid
+   * threshold inside the window. `tryEnable` is a separate call so the
+   * caller can act on the raid signal atomically.
+   */
+  track(guildId: string, member: MemberJoin): RaidTrackResult {
+    const now = Date.now();
+    const state = this.getState(guildId);
+    this.cleanupJoins(state, now);
+    state.joins.push({ memberId: member.memberId, timestamp: now });
+    return {
+      isRaid: state.joins.length >= this.joinThreshold,
+      joinCount: state.joins.length,
+      windowSeconds: this.joinWindow / 1000,
+    };
+  }
+
+  isActive(guildId: string): boolean {
+    return this.state.get(guildId)?.raidActive ?? false;
+  }
+
+  /**
+   * Attempt to flip the guild into raid-active state. Returns:
+   *  - 'enabled' if this call performed the transition
+   *  - 'already_active' if raid mode was already on
+   *  - 'already_enabling' if another concurrent call is mid-transition
+   */
+  async tryEnable(guildId: string): Promise<EnableResult> {
+    const state = this.getState(guildId);
+    if (state.raidActive) return 'already_active';
+    if (this.enabling.has(guildId)) return 'already_enabling';
+    this.enabling.add(guildId);
+    try {
+      state.raidActive = true;
+      return 'enabled';
+    } finally {
+      this.enabling.delete(guildId);
+    }
+  }
+
+  disable(guildId: string): void {
+    const state = this.getState(guildId);
+    state.raidActive = false;
+    this.enabling.delete(guildId);
+  }
+
+  getJoinCount(guildId: string, windowSeconds?: number): number {
+    const now = Date.now();
+    const state = this.getState(guildId);
+    const window = (windowSeconds ?? this.joinWindow / 1000) * 1000;
+
+    return state.joins.filter(j => now - j.timestamp < window).length;
+  }
+}

package/src/raid/index.ts

@@ -0,0 +1,2 @@
+export * from './detector';
+export * from './age';

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;
   };
-}
+}