@joliegg/moderation 0.6.0 → 0.8.0

package/src/providers/aws.ts

@@ -0,0 +1,58 @@
+import { Rekognition } from '@aws-sdk/client-rekognition';
+import axios from 'axios';
+import sharp from 'sharp';
+
+import type { ModerationCategory } from '../types';
+
+// AWS Rekognition 5MB inline-image limit
+const MAX_IMAGE_SIZE = 5 * 1024 * 1024;
+
+/**
+ * AWS Rekognition image moderation adapter. Handles GIF and WEBP
+ * conversion to PNG and downscales images over the 5 MB Rekognition limit.
+ */
+export class RekognitionProvider {
+  constructor(private client: Rekognition) {}
+
+  async moderateImage(url: string, minimumConfidence: number): Promise<ModerationCategory[]> {
+    const { data } = await axios.get<ArrayBuffer>(url, { responseType: 'arraybuffer' });
+    let buffer: Buffer;
+
+    const lowered = url.toLowerCase();
+
+    if (lowered.includes('.gif')) {
+      buffer = await sharp(Buffer.from(data), { pages: -1 }).toFormat('png').toBuffer();
+    } else if (lowered.includes('.webp')) {
+      buffer = await sharp(Buffer.from(data)).toFormat('png').toBuffer();
+    } else {
+      buffer = Buffer.from(data);
+    }
+
+    if (buffer.length > MAX_IMAGE_SIZE) {
+      try {
+        const metadata = await sharp(buffer).metadata();
+        const { width, height } = metadata;
+
+        if (typeof width === 'number' && typeof height === 'number') {
+          const scalingFactor = Math.sqrt(MAX_IMAGE_SIZE / buffer.length);
+          buffer = await sharp(buffer)
+            .resize(Math.round(width * scalingFactor), Math.round(height * scalingFactor))
+            .toBuffer();
+        }
+      } catch {
+        // Resize failed, we will use the original buffer.
+      }
+    }
+
+    const { ModerationLabels } = await this.client.detectModerationLabels({
+      Image: { Bytes: buffer },
+      MinConfidence: minimumConfidence,
+    });
+
+    if (Array.isArray(ModerationLabels)) {
+      return ModerationLabels.map(l => ({ category: l.Name ?? 'Unknown', confidence: l.Confidence ?? 0 }));
+    }
+
+    return [];
+  }
+}

package/src/providers/google.ts

@@ -0,0 +1,63 @@
+import { LanguageServiceClient } from '@google-cloud/language';
+import { SpeechClient, protos } from '@google-cloud/speech';
+import axios from 'axios';
+
+import type { ModerationCategory } from '../types';
+
+type IRecognitionConfig = protos.google.cloud.speech.v1.IRecognitionConfig;
+type ISpeechRecognitionResult = protos.google.cloud.speech.v1.ISpeechRecognitionResult;
+
+/**
+ * Google Cloud Natural Language moderation adapter.
+ */
+export class GoogleLanguageProvider {
+  constructor(private client: LanguageServiceClient) {}
+
+  async moderateText(text: string, minimumConfidence: number): Promise<ModerationCategory[]> {
+    const [result] = await this.client.moderateText({
+      document: { content: text, type: 'PLAIN_TEXT' },
+    });
+
+    if (!result || !('moderationCategories' in result) || !Array.isArray(result.moderationCategories)) {
+      return [];
+    }
+
+    return result.moderationCategories
+      .map(c => ({ category: c.name ?? 'Unknown', confidence: (c.confidence ?? 0) * 100 }))
+      .filter(c => c.confidence >= minimumConfidence);
+  }
+}
+
+/**
+ * Google Cloud Speech-to-Text adapter. Used for audio transcription
+ * before running the transcript through text moderation.
+ */
+export class GoogleSpeechProvider {
+  constructor(private client: SpeechClient) {}
+
+  async transcribe(audioBuffer: Buffer, languageCode: string): Promise<string> {
+    const config: IRecognitionConfig = {
+      encoding: 'OGG_OPUS',
+      sampleRateHertz: 48000,
+      languageCode,
+    };
+
+    const [response] = await this.client.recognize({
+      audio: { content: audioBuffer.toString('base64') },
+      config,
+    });
+
+    if (!Array.isArray(response?.results)) {
+      return '';
+    }
+
+    return response.results
+      .map((r: ISpeechRecognitionResult) => r.alternatives?.at(0)?.transcript ?? '')
+      .join(' ');
+  }
+}
+
+export async function fetchAudio(url: string): Promise<Buffer> {
+  const { data } = await axios.get<ArrayBuffer>(url, { responseType: 'arraybuffer' });
+  return Buffer.from(data);
+}

package/src/providers/webrisk.ts

@@ -0,0 +1,30 @@
+import axios from 'axios';
+import type { ModerationCategory, ThreatsResponse } from '../types';
+
+const THREAT_TYPES = [
+  'MALWARE',
+  'SOCIAL_ENGINEERING',
+  'UNWANTED_SOFTWARE',
+  'SOCIAL_ENGINEERING_EXTENDED_COVERAGE',
+];
+
+/**
+ * Google Web Risk link moderation adapter.
+ */
+export class WebRiskProvider {
+  constructor(private apiKey: string) {}
+
+  async checkLink(url: string): Promise<ModerationCategory[]> {
+    const threatTypes = THREAT_TYPES.join('&threatTypes=');
+    const requestUrl = `https://webrisk.googleapis.com/v1/uris:search?threatTypes=${threatTypes}&key=${this.apiKey}`;
+    const { data } = await axios.get<ThreatsResponse>(`${requestUrl}&uri=${encodeURIComponent(url)}`);
+
+    const threats = data?.threat?.threatTypes;
+
+    if (Array.isArray(threats)) {
+      return threats.map(t => ({ category: t, confidence: 100 }));
+    }
+
+    return [];
+  }
+}

package/src/raid/age.ts

@@ -0,0 +1,19 @@
+/**
+ * Is a member's account "too new" for the given threshold?
+ *
+ * Returns `false` when both timestamps are missing.
+ */
+export function isAccountTooNew(joinedTimestamp: number | null, createdTimestamp: number | null, minAgeDays: number): boolean {
+  // For raids, we care about join time, not account creation
+  // Altough we can derive some trust from that too.
+  const reference = joinedTimestamp ?? createdTimestamp;
+
+  if (reference === null) {
+    return false;
+  }
+
+  const age = Date.now() - reference;
+  const minAgeMs = minAgeDays * 24 * 60 * 60 * 1000;
+
+  return age < minAgeMs;
+}

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';