@joliegg/moderation 0.6.0 → 0.9.0

package/dist/text/mentions.d.ts

@@ -0,0 +1,31 @@
+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 declare const DEFAULT_MENTION_CONFIG: MentionConfig;
+/**
+ * Mention-spam check.
+ *
+ * `@everyone` detection takes priority over other reasons.
+ */
+export declare function checkMentionSpam(counts: MentionCounts, config: MentionConfig): MentionSpamResult;

package/dist/text/mentions.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MENTION_CONFIG = void 0;
+exports.checkMentionSpam = checkMentionSpam;
+exports.DEFAULT_MENTION_CONFIG = {
+    maxUserMentions: 5,
+    maxRoleMentions: 3,
+    maxTotalMentions: 8,
+    blockEveryone: true,
+    blockHere: true,
+};
+/**
+ * Mention-spam check.
+ *
+ * `@everyone` detection takes priority over other reasons.
+ */
+function checkMentionSpam(counts, config) {
+    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/dist/text/normalize.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 declare function normalizeText(input: string): string;

package/dist/text/normalize.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeText = normalizeText;
+/**
+ * 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.
+ */
+function normalizeText(input) {
+    return input
+        .trim()
+        .toLowerCase()
+        .replace(ZERO_WIDTH, '')
+        .normalize('NFKC')
+        .replace(/\s+/g, ' ');
+}

package/dist/types/config.d.ts

@@ -0,0 +1,13 @@
+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/dist/types/config.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/index.d.ts

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

package/dist/types/index.js

@@ -1,2 +1,17 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./config"), exports);

package/package.json

@@ -1,15 +1,68 @@
 {
   "name": "@joliegg/moderation",
-  "version": "0.6.0",
+  "version": "0.9.0",
   "description": "A set of tools for chat moderation",
   "author": "Diana Islas Ocampo",
   "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./types": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./dist/types/index.js"
+    },
+    "./actions": {
+      "types": "./dist/actions.d.ts",
+      "default": "./dist/actions.js"
+    },
+    "./text": {
+      "types": "./dist/text/index.d.ts",
+      "default": "./dist/text/index.js"
+    },
+    "./spam": {
+      "types": "./dist/spam/index.d.ts",
+      "default": "./dist/spam/index.js"
+    },
+    "./raid": {
+      "types": "./dist/raid/index.d.ts",
+      "default": "./dist/raid/index.js"
+    },
+    "./rubrics": {
+      "types": "./dist/rubrics/index.d.ts",
+      "default": "./dist/rubrics/index.js"
+    },
+    "./audit": {
+      "types": "./dist/audit/index.d.ts",
+      "default": "./dist/audit/index.js"
+    },
+    "./providers/google": {
+      "types": "./dist/providers/google.d.ts",
+      "default": "./dist/providers/google.js"
+    },
+    "./providers/aws": {
+      "types": "./dist/providers/aws.d.ts",
+      "default": "./dist/providers/aws.js"
+    },
+    "./providers/webrisk": {
+      "types": "./dist/providers/webrisk.d.ts",
+      "default": "./dist/providers/webrisk.js"
+    },
+    "./providers/openai": {
+      "types": "./dist/providers/openai.d.ts",
+      "default": "./dist/providers/openai.js"
+    },
+    "./package.json": "./package.json"
+  },
   "scripts": {
-    "publish": "bun build && bun docs",
+    "prepublishOnly": "bun run build && bun run docs",
     "build": "bun eslint . && rm -rf ./dist && bun tsc --declaration",
     "docs": "typedoc",
-    "test": "node test/index.js"
+    "test": "bun test",
+    "test:integration": "bun run test/integration.ts"
   },
   "engines": {
     "node": ">=20.x"
@@ -17,19 +70,19 @@
   "devDependencies": {
     "@babel/eslint-parser": "^7.28.6",
     "@eslint/js": "^10.0.1",
-    "@typescript-eslint/eslint-plugin": "^8.56.1",
-    "@typescript-eslint/parser": "^8.56.1",
-    "dotenv": "^17.3.1",
-    "eslint": "^10.0.2",
-    "typedoc": "^0.28.17",
+    "@typescript-eslint/eslint-plugin": "^8.58.2",
+    "@typescript-eslint/parser": "^8.58.2",
+    "dotenv": "^17.4.2",
+    "eslint": "^10.2.0",
+    "typedoc": "^0.28.19",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.56.1"
+    "typescript-eslint": "^8.58.2"
   },
   "dependencies": {
-    "@aws-sdk/client-rekognition": "^3.996.0",
+    "@aws-sdk/client-rekognition": "^3.1031.0",
     "@google-cloud/language": "^7.2.1",
-    "@google-cloud/speech": "^7.2.1",
-    "axios": "^1.13.5",
+    "@google-cloud/speech": "^7.3.0",
+    "axios": "^1.15.0",
     "sharp": "^0.34.5"
   },
   "files": [
@@ -40,4 +93,4 @@
     "dist/*"
   ],
   "packageManager": "bun@1.3.4"
-}
+}

package/src/actions.ts

@@ -0,0 +1,50 @@
+import type { Severity } from './types';
+
+/**
+ * Moderation actions taxonomy. These should be stable so they can be persisted
+ * as a canonical list of actions.
+ */
+export const ACTION_TYPES = {
+  TIMEOUT: 'timeout',
+  BAN: 'ban',
+  KICK: 'kick',
+  WARN: 'warn',
+  DELETE: 'delete',
+  RESTRICT: 'restrict',
+  APPEAL_APPROVE: 'appeal_approve',
+  APPEAL_DENY: 'appeal_deny',
+  MENTION_SPAM: 'mention_spam',
+  NEW_USER_RESTRICT: 'new_user_restrict',
+  SPAM_DETECTED: 'spam_detected',
+  ESCALATION: 'escalation',
+  RAID_DETECTED: 'raid_detected',
+  RAID_TIMEOUT: 'raid_timeout',
+  RAID_JOIN: 'raid_join',
+  PERMISSION_BLOCK: 'permission_block',
+  UNTIMEOUT: 'untimeout',
+  UNBAN: 'unban',
+} as const;
+
+export type ActionType = typeof ACTION_TYPES[keyof typeof ACTION_TYPES];
+
+/** Default severity per action type. */
+export const SEVERITY_BY_ACTION: Record<ActionType, Severity> = {
+  timeout: 'medium',
+  ban: 'critical',
+  kick: 'high',
+  warn: 'low',
+  delete: 'low',
+  restrict: 'medium',
+  appeal_approve: 'low',
+  appeal_deny: 'low',
+  mention_spam: 'medium',
+  new_user_restrict: 'low',
+  spam_detected: 'medium',
+  escalation: 'high',
+  raid_detected: 'critical',
+  raid_timeout: 'medium',
+  raid_join: 'low',
+  permission_block: 'low',
+  untimeout: 'low',
+  unban: 'low',
+};

package/src/audit/emitter.ts

@@ -0,0 +1,77 @@
+import type { AuditEvent, AuditEventKind, AuditEventMap } from './events';
+
+/**
+ * Subscriber handler type for a specific audit event kind. Sync or
+ * async; the emitter fire-and-forgets async handlers so slow
+ * persistence sinks don't block the enforcement path.
+ */
+export type AuditHandler<K extends AuditEventKind> = (event: AuditEventMap[K]) => void | Promise<void>;
+
+/**
+ * Typed event emitter for moderation audit events.
+ *
+ * Subscribers register for specific event kinds with full type safety.
+ * Handlers that throw are isolated — a broken subscriber never blocks
+ * other subscribers or the emitter itself.
+ *
+ * Intentionally NOT `extends EventEmitter` from `node:events`: the
+ * typing story for Node's built-in emitter is painful, and the feature
+ * set we need (on / off / emit) is small enough to implement directly.
+ */
+export class AuditTrailEmitter {
+  private handlers = new Map<AuditEventKind, Set<AuditHandler<AuditEventKind>>>();
+
+  on<K extends AuditEventKind>(kind: K, handler: AuditHandler<K>): this {
+    if (!this.handlers.has(kind)) {
+      this.handlers.set(kind, new Set());
+    }
+
+    this.handlers.get(kind)!.add(handler as AuditHandler<AuditEventKind>);
+
+    return this;
+  }
+
+  off<K extends AuditEventKind>(kind: K, handler: AuditHandler<K>): this {
+    this.handlers.get(kind)?.delete(handler as AuditHandler<AuditEventKind>);
+    return this;
+  }
+
+  emit(event: AuditEvent): void {
+    const handlers = this.handlers.get(event.kind);
+
+    if (!handlers) {
+      return;
+    }
+
+    for (const handler of handlers) {
+      try {
+        // Fire-and-forget. Async handlers are not awaited so the
+        // emitter's caller isn't blocked on slow persistence sinks.
+        // Subscribers own their own error handling for async work.
+        const result = handler(event);
+
+        if (result instanceof Promise) {
+          result.catch(err => {
+            console.error(`[Jolie::Moderation::AuditTrail] async handler error for ${event.kind}:`, err);
+          });
+        }
+      } catch (err) {
+        console.error(`[Jolie::Moderation::AuditTrail] handler error for ${event.kind}:`, err);
+      }
+    }
+  }
+
+  listenerCount(kind: AuditEventKind): number {
+    return this.handlers.get(kind)?.size ?? 0;
+  }
+
+  removeAllListeners(kind?: AuditEventKind): this {
+    if (kind) {
+      this.handlers.delete(kind);
+    } else {
+      this.handlers.clear();
+    }
+
+    return this;
+  }
+}

package/src/audit/events.ts

@@ -0,0 +1,89 @@
+import type { ActionType } from '../actions';
+import type { SpamMessageRef, SpamReason } from '../spam/cache';
+
+export type Platform = 'discord' | 'twitch';
+
+/** Base fields shared by every audit event. */
+interface AuditEventBase {
+  guildId: string;
+  platform: Platform;
+  timestamp: Date;
+}
+
+/**
+ * A moderator (human or system) performed an enforcement action.
+ * This is the primary audit log entry.
+ */
+export interface ActionEvent extends AuditEventBase {
+  kind: 'action';
+  actionType: ActionType;
+  targetId: string;
+  targetName: string;
+  moderatorId: string;
+  moderatorName: string;
+  reason: string;
+  details?: string;
+  duration?: number;
+  channelId?: string;
+  messageId?: string;
+  evidence?: string[];
+}
+
+/**
+ * Automatic spam detection fired. Independent of whether enforcement
+ * succeeded — the detection itself is the audit event.
+ */
+export interface SpamDetectedEvent extends AuditEventBase {
+  kind: 'spam_detected';
+  userId: string;
+  reason: SpamReason;
+  details?: string;
+  priorMessageIds: SpamMessageRef[];
+  channelId?: string;
+}
+
+/** Raid mode detection crossed the join-count threshold. */
+export interface RaidDetectedEvent extends AuditEventBase {
+  kind: 'raid_detected';
+  joinCount: number;
+  windowSeconds: number;
+  autoTriggered: boolean;
+}
+
+/** A message was blocked by the per-user permissions check. */
+export interface PermissionBlockEvent extends AuditEventBase {
+  kind: 'permission_block';
+  userId: string;
+  violations: string[];
+  channelId?: string;
+  messageId?: string;
+}
+
+/** An appeal was reviewed (approved or denied). */
+export interface AppealReviewedEvent extends AuditEventBase {
+  kind: 'appeal_reviewed';
+  appealId: string;
+  userId: string;
+  reviewerId: string;
+  approved: boolean;
+  note?: string;
+}
+
+/** Union of every audit event shape. Add new kinds here. */
+export type AuditEvent =
+  | ActionEvent
+  | SpamDetectedEvent
+  | RaidDetectedEvent
+  | PermissionBlockEvent
+  | AppealReviewedEvent;
+
+/** Map from event kind → concrete event type. Used by the emitter. */
+export interface AuditEventMap {
+  action: ActionEvent;
+  spam_detected: SpamDetectedEvent;
+  raid_detected: RaidDetectedEvent;
+  permission_block: PermissionBlockEvent;
+  appeal_reviewed: AppealReviewedEvent;
+}
+
+export type AuditEventKind = keyof AuditEventMap;

package/src/audit/index.ts

@@ -0,0 +1,2 @@
+export * from './events';
+export * from './emitter';

package/src/client.ts

@@ -0,0 +1,137 @@
+import { Rekognition } from '@aws-sdk/client-rekognition';
+import { LanguageServiceClient } from '@google-cloud/language';
+import { SpeechClient } from '@google-cloud/speech';
+
+import { GoogleLanguageProvider, GoogleSpeechProvider, fetchAudio } from './providers/google';
+import { RekognitionProvider } from './providers/aws';
+import { WebRiskProvider } from './providers/webrisk';
+import { OpenAIModerationProvider } from './providers/openai';
+import URLBlackList from './data/url-blacklist.json';
+import URLShortenerList from './data/url-shorteners.json';
+
+import type { ModerationCategory, ModerationConfiguration, ModerationResult } from './types';
+
+/**
+ * Composes text / image / link / audio moderation across the configured
+ * providers.
+ */
+export class ModerationClient {
+  private googleLanguage?: GoogleLanguageProvider;
+  private googleSpeech?: GoogleSpeechProvider;
+  private aws?: RekognitionProvider;
+  private webRisk?: WebRiskProvider;
+  private openai?: OpenAIModerationProvider;
+  private banList: string[] = [];
+  private urlBlackList: string[] = [];
+
+  constructor(configuration: ModerationConfiguration) {
+    if (configuration.aws) {
+      this.aws = new RekognitionProvider(new Rekognition(configuration.aws));
+    }
+
+    if (typeof configuration.google?.keyFile === 'string') {
+      this.googleLanguage = new GoogleLanguageProvider(
+        new LanguageServiceClient({ keyFile: configuration.google.keyFile })
+      );
+
+      this.googleSpeech = new GoogleSpeechProvider(
+        new SpeechClient({ keyFile: configuration.google.keyFile })
+      );
+    }
+
+    if (typeof configuration.google?.apiKey === 'string') {
+      this.webRisk = new WebRiskProvider(configuration.google.apiKey);
+    }
+
+    if (typeof configuration.openai?.apiKey === 'string') {
+      this.openai = new OpenAIModerationProvider(configuration.openai.apiKey);
+    }
+
+    if (Array.isArray(configuration.banList)) {
+      this.banList = configuration.banList;
+    }
+
+    if (Array.isArray(configuration.urlBlackList)) {
+      this.urlBlackList = configuration.urlBlackList;
+    }
+  }
+
+  async moderateText(
+    text: string,
+    minimumConfidence: number = 50,
+    options: { provider?: 'google' | 'openai' | 'all' } = {},
+  ): Promise<ModerationResult> {
+    const categories: ModerationCategory[] = [];
+    const normalized = text.toLowerCase();
+    const matches = this.banList.filter(w => normalized.includes(w));
+
+    if (matches.length > 0) {
+      const words = normalized.split(' ');
+      categories.push({ category: 'BAN_LIST', confidence: (matches.length / words.length) * 100 });
+    }
+
+    const provider = options.provider ?? 'google';
+
+    if ((provider === 'google' || provider === 'all') && this.googleLanguage) {
+      const google = await this.googleLanguage.moderateText(text, minimumConfidence);
+      categories.push(...google);
+    }
+
+    if ((provider === 'openai' || provider === 'all') && this.openai) {
+      const openai = await this.openai.moderateText(text, minimumConfidence);
+      categories.push(...openai);
+    }
+
+    return { source: text, moderation: categories };
+  }
+
+  async moderateImage(url: string, minimumConfidence: number = 50): Promise<ModerationResult> {
+    if (!this.aws) {
+      return { source: url, moderation: [] };
+    }
+
+    const moderation = await this.aws.moderateImage(url, minimumConfidence);
+
+    return { source: url, moderation };
+  }
+
+  async moderateLink(url: string, allowShorteners = false): Promise<ModerationResult> {
+    try {
+      const domain = new URL(url).hostname;
+
+      if (this.urlBlackList.some(u => url.includes(u))) {
+        return { source: url, moderation: [{ category: 'CUSTOM_BLACK_LIST', confidence: 100 }] };
+      }
+
+      if (URLBlackList.some(u => u === domain)) {
+        return { source: url, moderation: [{ category: 'BLACK_LIST', confidence: 100 }] };
+      }
+
+      if (!allowShorteners && URLShortenerList.some(u => u === domain)) {
+        return { source: url, moderation: [{ category: 'URL_SHORTENER', confidence: 100 }] };
+      }
+    } catch {
+      return { source: url, moderation: [] };
+    }
+
+    if (!this.webRisk) {
+      return { source: url, moderation: [] };
+    }
+
+    const moderation = await this.webRisk.checkLink(url);
+    return { source: url, moderation };
+  }
+
+  async moderateAudio(url: string, language: string = 'en-US', minimumConfidence: number = 50): Promise<ModerationResult> {
+    if (!this.googleSpeech) {
+      return { source: url, moderation: [] };
+    }
+
+    const buffer = await fetchAudio(url);
+    const transcription = await this.googleSpeech.transcribe(buffer, language);
+
+    return this.moderateText(transcription, minimumConfidence);
+  }
+}
+
+export default ModerationClient;