@joliegg/moderation 0.4.4 → 0.8.0

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/client.ts

@@ -0,0 +1,121 @@
+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 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 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 (Array.isArray(configuration.banList)) {
+      this.banList = configuration.banList;
+    }
+
+    if (Array.isArray(configuration.urlBlackList)) {
+      this.urlBlackList = configuration.urlBlackList;
+    }
+  }
+
+  async moderateText(text: string, minimumConfidence: number = 50): 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 });
+    }
+
+    if (!this.googleLanguage) {
+      return { source: text, moderation: categories };
+    }
+
+    const googleCategories = await this.googleLanguage.moderateText(text, minimumConfidence);
+
+    return { source: text, moderation: [...categories, ...googleCategories] };
+  }
+
+  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;

package/src/{url-blacklist.json → data/url-blacklist.json}

@@ -42322,6 +42322,7 @@
   "getvalorant.fun",
   "getviplocals1.com",
   "getvottak.com",
+  "getwix.pro",
   "getx2.net",
   "getx2tesla.com",
   "getxtrade.com",

package/src/index.ts

@@ -1,277 +1,3 @@
-import axios from 'axios';
-
-import { Rekognition } from '@aws-sdk/client-rekognition';
-import { LanguageServiceClient } from '@google-cloud/language';
-import { SpeechClient, protos } from '@google-cloud/speech';
-
-import sharp from 'sharp';
-
-import URLBlackList from './url-blacklist.json';
-import URLShortenerList from './url-shorteners.json';
-
-
-import { ModerationCategory, ModerationConfiguration, ModerationResult, ThreatsResponse } from './types';
-
-
-type IRecognitionConfig = protos.google.cloud.speech.v1.IRecognitionConfig;
-
-type ISpeechRecognitionResult = protos.google.cloud.speech.v1.ISpeechRecognitionResult;
-
-const MAX_IMAGE_SIZE = 5 * 1024 * 1024; // 5MB in bytes for Rekognition limit
-
-/**
- * Moderation Client
- *
- * @class ModerationClient
- */
-class ModerationClient {
-
-  private rekognitionClient?: Rekognition;
-  private googleLanguageClient?: LanguageServiceClient;
-  private googleSpeechClient?: SpeechClient;
-  private googleAPIKey?: string;
-  private banList?: string[] = [];
-  private urlBlackList?: string[] = [];
-
-  /**
-   *
-   * @param {ModerationConfiguration} configuration
-   */
-  constructor (configuration: ModerationConfiguration) {
-    if (configuration.aws) {
-      this.rekognitionClient = new Rekognition(configuration.aws);
-    }
-
-    if (typeof configuration.google?.keyFile === 'string') {
-      this.googleLanguageClient = new LanguageServiceClient({ keyFile: configuration.google.keyFile });
-      this.googleSpeechClient = new SpeechClient({ keyFile: configuration.google.keyFile });
-    }
-
-    if (typeof configuration.google?.apiKey === 'string') {
-      this.googleAPIKey = configuration.google.apiKey;
-    }
-
-    if (Array.isArray(configuration.banList)) {
-      this.banList = configuration.banList;
-    }
-
-    if (Array.isArray(configuration.urlBlackList)) {
-      this.urlBlackList = configuration.urlBlackList;
-    }
-  }
-
-  /**
-   * Returns a list of moderation categories detected on a text
-   *
-   * @param {string} text  The text to moderate
-   * @param {number} [minimumConfidence = 50] The minimum confidence required for a category to be considered
-   *
-   * @returns {Promise<ModerationResult>} The list of results that were detected with the minimum confidence specified
-   */
-  async moderateText (text: string, minimumConfidence: number = 50): Promise<ModerationResult> {
-    const categories: ModerationCategory[] = [];
-
-    if (Array.isArray(this.banList)) {
-      const normalizedText = text.toLowerCase();
-      const matches = this.banList.filter(w => normalizedText.indexOf(w) > -1);
-
-      if (matches.length > 0) {
-        const words = normalizedText.split(' ');
-
-        categories.push({
-          category: 'BAN_LIST',
-          confidence: (matches.length / words.length) * 100,
-        });
-      }
-    }
-
-
-    if (typeof this.googleLanguageClient === 'undefined') {
-      return { source: text, moderation: categories };
-    }
-
-    const [ result ] = await this.googleLanguageClient.moderateText({
-      document: {
-        content: text,
-        type: 'PLAIN_TEXT',
-      },
-    });
-
-    if (result && 'moderationCategories' in result) {
-      if (Array.isArray(result.moderationCategories)) {
-        const results = result.moderationCategories.map(c => ({
-          category: c.name ?? 'Unknown',
-          confidence: (c.confidence ?? 0) * 100,
-        })).filter(c => c.confidence >= minimumConfidence);
-        return { source: text, moderation: [...categories, ...results] };
-      }
-    }
-
-    return { source: text, moderation: [] };
-  }
-
-  /**
-   * Returns a list of moderation categories detected on an image
-   *
-   * @param {string} url
-   * @param {number} [minimumConfidence = 50]  The minimum confidence required for a category to be considered
-   *
-   *
-   * @returns {Promise<ModerationResult[]>} The list of results that were detected with the minimum confidence specified
-   */
-  async moderateImage (url: string, minimumConfidence: number = 50): Promise<ModerationResult> {
-    if (typeof this.rekognitionClient === 'undefined') {
-      return { source: url, moderation: [] };
-    }
-
-    const { data } = await axios.get<string>(url, { responseType: 'arraybuffer' });
-
-    let buffer: Buffer | null = null;
-
-    // GIFs will be split into frames
-    if (url.toLowerCase().indexOf('.gif') > -1) {
-      buffer = await sharp(data, { pages: -1 }).toFormat('png').toBuffer();
-    } else if (url.toLowerCase().indexOf('.webp') > -1) {
-      buffer = await sharp(data).toFormat('png').toBuffer();
-    } else {
-       // Download image as binary data
-      buffer = Buffer.from(data, 'binary');
-    }
-
-    // Ensure image is not larger than 5MB (Rekognition limit)
-    if (buffer.length > MAX_IMAGE_SIZE) {
-      try {
-        // Calculate new dimensions to reduce size
-        const metadata = await sharp(buffer).metadata();
-
-        const { width, height } = metadata;
-
-        if (typeof width !== 'number' || typeof height !== 'number') {
-          throw new Error('Invalid image metadata');
-        }
-
-        // Calculate the scaling factor
-        const scalingFactor = Math.sqrt(MAX_IMAGE_SIZE / buffer.length);
-
-        // Calculate new dimensions
-        const newWidth = Math.floor(width * scalingFactor);
-        const newHeight = Math.floor(height * scalingFactor);
-
-        const resizedBuffer = await sharp(buffer)
-          .resize(Math.round(newWidth), Math.round(newHeight))
-          .toBuffer();
-
-        buffer = resizedBuffer;
-      } catch (error) {
-        // We can't resize the image. We'll skip the resize and try to process it as is
-      }
-    }
-
-    const { ModerationLabels } = await this.rekognitionClient.detectModerationLabels({
-      Image: {
-        Bytes: buffer
-      },
-      MinConfidence: minimumConfidence
-    });
-
-    if (Array.isArray(ModerationLabels)) {
-      const moderation = ModerationLabels.map(l => ({
-        category: l.Name ?? 'Unknown',
-        confidence: l.Confidence ?? 0,
-      }));
-
-      return { source: url, moderation };
-    }
-
-    return { source: url, moderation: [] };
-  }
-
-  async moderateLink (url: string, allowShorteners = false): Promise<ModerationResult> {
-    try {
-      const domain = new URL(url).hostname;
-
-      const blacklisted = this.urlBlackList?.some(u => url.indexOf(u) > -1);
-
-      if (blacklisted) {
-        return { source: url, moderation: [{ category: 'CUSTOM_BLACK_LIST', confidence: 100 }] };
-      }
-
-      const globallyBlacklisted = URLBlackList.some(u => u === domain);
-
-      if (globallyBlacklisted) {
-        return { source: url, moderation: [{ category: 'BLACK_LIST', confidence: 100 }] };
-      }
-
-      if (!allowShorteners) {
-        const isShortened = URLShortenerList.some(u => u === domain);
-
-        if (isShortened) {
-          return { source: url, moderation: [{ category: 'URL_SHORTENER', confidence: 100 }] };
-        }
-      }
-    } catch (error) {
-      // Invalid URL
-      return { source: url, moderation: [] };
-    }
-
-    if (typeof this.googleAPIKey !== 'string') {
-      return { source: url, moderation: [] };
-    }
-
-    const types = [
-      'MALWARE',
-      'SOCIAL_ENGINEERING',
-      'UNWANTED_SOFTWARE',
-      'SOCIAL_ENGINEERING_EXTENDED_COVERAGE'
-    ];
-
-    const threatTypes = types.join('&threatTypes=');
-    const requestUrl = `https://webrisk.googleapis.com/v1/uris:search?threatTypes=${threatTypes}&key=${this.googleAPIKey}`;
-
-    const { data } = await axios.get<ThreatsResponse>(`${requestUrl}&uri=${encodeURIComponent(url)}`);
-
-    const threats = data?.threat?.threatTypes;
-
-    if (Array.isArray(threats)) {
-      const moderation = threats.map(t => ({
-        category: t,
-        confidence: 100,
-      }));
-
-      return { source: url, moderation };
-    }
-
-    return { source: url, moderation: [] };
-  }
-
-  async moderateAudio (url: string, language: string = 'en-US', minimumConfidence: number = 50): Promise<ModerationResult> {
-    if (typeof this.googleSpeechClient === 'undefined') {
-      return { source: url, moderation: [] };
-    }
-
-    const { data } = await axios.get<string>(url, { responseType: 'arraybuffer' });
-
-
-    const options: IRecognitionConfig = {
-      encoding: 'OGG_OPUS',
-      sampleRateHertz: 48000,
-      languageCode: language,
-    };
-
-    const [ response ] = await this.googleSpeechClient.recognize ({
-      audio: { content: Buffer.from(data, 'binary').toString('base64') },
-      config: options,
-    });
-
-    if (!Array.isArray(response?.results)) {
-      return { source: url, moderation: [] };
-    }
-
-    const transcription = response?.results?.map((result: ISpeechRecognitionResult) => result.alternatives?.at(0)?.transcript ?? '').join(' ');
-
-    return this.moderateText(transcription, minimumConfidence);
-  }
-
-}
-
-export default ModerationClient;
+export { ModerationClient, default } from './client';
+export * from './types';
+export * from './actions';

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