@joliegg/moderation 0.6.0 → 0.8.0

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