@kkuffour/solid-moderation-plugin 0.2.2 → 0.3.0

package/src/ModerationMixin.ts

@@ -1,153 +0,0 @@
-import { Readable } from 'node:stream';
-import { promises as fs } from 'node:fs';
-import type { Operation } from '@solid/community-server';
-import { getLoggerFor, ForbiddenHttpError, guardStream } from '@solid/community-server';
-import type { ModerationConfig } from './ModerationConfig';
-import { SightEngineProvider } from './providers/SightEngineProvider';
-import { ModerationStore } from './ModerationStore';
-
-export class ModerationMixin {
-  protected readonly logger = getLoggerFor(this);
-  private readonly moderationConfig: ModerationConfig;
-  private readonly moderationStore?: ModerationStore;
-
-  public constructor(moderationConfig: ModerationConfig) {
-    this.moderationConfig = moderationConfig;
-    this.moderationStore = moderationConfig.auditLoggingEnabled ?
-      new ModerationStore(moderationConfig.auditLoggingStorePath) :
-      undefined;
-  }
-
-  public async moderateContent(operation: Operation): Promise<void> {
-    if (!this.moderationConfig.enabled || !operation.body?.data) {
-      return;
-    }
-
-    const contentType = operation.body.metadata.contentType;
-    if (contentType?.startsWith('image/') && this.moderationConfig.imagesEnabled) {
-      await this.moderateImageContent(operation);
-    } else if (contentType?.startsWith('text/') && this.moderationConfig.textEnabled) {
-      await this.moderateTextContent(operation);
-    } else if (contentType?.startsWith('video/') && this.moderationConfig.videoEnabled) {
-      await this.moderateVideoContent(operation);
-    }
-  }
-
-  private async moderateImageContent(operation: Operation): Promise<void> {
-    const chunks: Buffer[] = [];
-    for await (const chunk of operation.body.data) {
-      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk as Uint8Array));
-    }
-    const buffer = Buffer.concat(chunks);
-    operation.body.data = guardStream(Readable.from(buffer));
-
-    const tempFile = `/tmp/moderation_${Date.now()}.jpg`;
-    await fs.writeFile(tempFile, buffer);
-
-    try {
-      const client = new SightEngineProvider(
-        this.moderationConfig.sightEngineApiUser,
-        this.moderationConfig.sightEngineApiSecret,
-      );
-      const result = await client.analyzeImage(tempFile);
-      this.logger.info(`MODERATION: Image analysis result - nudity score: ${result.nudity?.raw}, threshold: ${this.moderationConfig.imageNudityThreshold}`);
-
-      if (result.nudity?.raw && result.nudity.raw > this.moderationConfig.imageNudityThreshold) {
-        if (this.moderationStore) {
-          await this.moderationStore.recordViolation({
-            contentType: 'image',
-            resourcePath: operation.target.path,
-            violations: [{ model: 'nudity', score: result.nudity.raw, threshold: this.moderationConfig.imageNudityThreshold }],
-            contentSize: buffer.length,
-          });
-        }
-        throw new ForbiddenHttpError('Upload blocked: Content violates community guidelines');
-      }
-    } catch (error: unknown) {
-      if (error instanceof ForbiddenHttpError) {
-        throw error;
-      }
-      this.logger.warn(`MODERATION: Image check failed (fail-open): ${error}`);
-    } finally {
-      await fs.unlink(tempFile).catch(() => {});
-    }
-  }
-
-  private async moderateTextContent(operation: Operation): Promise<void> {
-    const chunks: Buffer[] = [];
-    for await (const chunk of operation.body.data) {
-      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk as Uint8Array));
-    }
-    const buffer = Buffer.concat(chunks);
-    const text = buffer.toString('utf8');
-    operation.body.data = guardStream(Readable.from(buffer));
-
-    if (!text?.trim()) {
-      return;
-    }
-
-    try {
-      const client = new SightEngineProvider(
-        this.moderationConfig.sightEngineApiUser,
-        this.moderationConfig.sightEngineApiSecret,
-      );
-      const result = await client.analyzeText(text);
-
-      if (result.sexual > this.moderationConfig.textSexualThreshold || result.toxic > this.moderationConfig.textToxicThreshold) {
-        if (this.moderationStore) {
-          await this.moderationStore.recordViolation({
-            contentType: 'text',
-            resourcePath: operation.target.path,
-            violations: [{ model: 'text', score: Math.max(result.sexual, result.toxic), threshold: Math.min(this.moderationConfig.textSexualThreshold, this.moderationConfig.textToxicThreshold) }],
-            contentSize: buffer.length,
-          });
-        }
-        throw new ForbiddenHttpError('Upload blocked: Content violates community guidelines');
-      }
-    } catch (error: unknown) {
-      if (error instanceof ForbiddenHttpError) {
-        throw error;
-      }
-      this.logger.warn(`MODERATION: Text check failed (fail-open): ${error}`);
-    }
-  }
-
-  private async moderateVideoContent(operation: Operation): Promise<void> {
-    const chunks: Buffer[] = [];
-    for await (const chunk of operation.body.data) {
-      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk as Uint8Array));
-    }
-    const buffer = Buffer.concat(chunks);
-    operation.body.data = guardStream(Readable.from(buffer));
-
-    const tempFile = `/tmp/moderation_${Date.now()}.mp4`;
-    await fs.writeFile(tempFile, buffer);
-
-    try {
-      const client = new SightEngineProvider(
-        this.moderationConfig.sightEngineApiUser,
-        this.moderationConfig.sightEngineApiSecret,
-      );
-      const result = await client.analyzeVideo(tempFile);
-
-      if (result.nudity?.raw && result.nudity.raw > this.moderationConfig.videoNudityThreshold) {
-        if (this.moderationStore) {
-          await this.moderationStore.recordViolation({
-            contentType: 'video',
-            resourcePath: operation.target.path,
-            violations: [{ model: 'nudity', score: result.nudity.raw, threshold: this.moderationConfig.videoNudityThreshold }],
-            contentSize: buffer.length,
-          });
-        }
-        throw new ForbiddenHttpError('Upload blocked: Content violates community guidelines');
-      }
-    } catch (error: unknown) {
-      if (error instanceof ForbiddenHttpError) {
-        throw error;
-      }
-      this.logger.warn(`MODERATION: Video check failed (fail-open): ${error}`);
-    } finally {
-      await fs.unlink(tempFile).catch(() => {});
-    }
-  }
-}

package/src/ModerationOperationHandler.ts

@@ -1,64 +0,0 @@
-import { getLoggerFor } from '@solid/community-server';
-import type { ModerationConfig } from './ModerationConfig';
-import type { ResponseDescription, OperationHandlerInput, OperationHandler } from '@solid/community-server';
-import { ModerationMixin } from './ModerationMixin';
-
-/**
- * Wraps an OperationHandler to add content moderation for operations with body data.
- * Checks PUT, POST, and PATCH operations before passing them to the wrapped handler.
- *
- * @module
- */
-export class ModerationOperationHandler {
-  protected readonly logger = getLoggerFor(this);
-  private readonly source: OperationHandler;
-  private readonly moderationMixin: ModerationMixin;
-
-  public constructor(
-    source: OperationHandler,
-    enabled: boolean,
-    auditLoggingEnabled: boolean,
-    auditLoggingStorePath: string,
-    sightEngineApiUser: string,
-    sightEngineApiSecret: string,
-    imagesEnabled: boolean,
-    textEnabled: boolean,
-    videoEnabled: boolean,
-    imageNudityThreshold: number,
-    textSexualThreshold: number,
-    textToxicThreshold: number,
-    videoNudityThreshold: number,
-  ) {
-    this.source = source;
-    this.moderationMixin = new ModerationMixin({
-      enabled,
-      auditLoggingEnabled,
-      auditLoggingStorePath,
-      sightEngineApiUser,
-      sightEngineApiSecret,
-      imagesEnabled,
-      textEnabled,
-      videoEnabled,
-      imageNudityThreshold,
-      textSexualThreshold,
-      textToxicThreshold,
-      videoNudityThreshold,
-    });
-  }
-
-  public async canHandle(input: OperationHandlerInput): Promise<void> {
-    return this.source.canHandle(input);
-  }
-
-  public async handle(input: OperationHandlerInput): Promise<ResponseDescription> {
-    const { operation } = input;
-
-    // Only moderate operations with body data
-    if (operation.body?.data && [ 'PUT', 'POST', 'PATCH' ].includes(operation.method)) {
-      this.logger.info(`MODERATION: Checking ${operation.method} request to ${operation.target.path}`);
-      await this.moderationMixin.moderateContent(operation);
-    }
-
-    return this.source.handle(input);
-  }
-}

package/src/ModerationRecord.ts

@@ -1,19 +0,0 @@
-/**
- * Record of a content moderation violation for admin review.
- */
-export interface ModerationRecord {
-  id: string;
-  timestamp: Date;
-  contentType: 'image' | 'text' | 'video';
-  resourcePath: string;
-  userWebId?: string;
-  userAgent?: string;
-  clientIp?: string;
-  violations: {
-    model: string;
-    score: number;
-    threshold: number;
-  }[];
-  contentSize: number;
-  contentHash?: string;
-}

package/src/ModerationResourceStore.ts

@@ -1,227 +0,0 @@
-import type { ResourceStore, ChangeMap, Representation, ResourceIdentifier, RepresentationPreferences, Conditions, Patch } from '@solid/community-server';
-import { getLoggerFor, ForbiddenHttpError, guardedStreamFrom } from '@solid/community-server';
-import { writeFileSync, unlinkSync } from 'fs';
-import type { SightEngineProvider } from './providers/SightEngineProvider';
-
-/**
- * @module
- * Wraps a ResourceStore to add content moderation on write operations.
- */
-export class ModerationResourceStore implements ResourceStore {
-  private readonly logger = getLoggerFor(this);
-  private readonly source: ResourceStore;
-  private readonly client: SightEngineProvider;
-  private readonly enabled: boolean;
-  private readonly imageNudityThreshold: number;
-  private readonly textSexualThreshold: number;
-  private readonly textToxicThreshold: number;
-  private readonly videoNudityThreshold: number;
-
-  public constructor(
-    source: ResourceStore,
-    client: SightEngineProvider,
-    enabled: boolean,
-    imageNudityThreshold: number,
-    textSexualThreshold: number,
-    textToxicThreshold: number,
-    videoNudityThreshold: number,
-  ) {
-    this.source = source;
-    this.client = client;
-    this.enabled = enabled;
-    this.imageNudityThreshold = imageNudityThreshold;
-    this.textSexualThreshold = textSexualThreshold;
-    this.textToxicThreshold = textToxicThreshold;
-    this.videoNudityThreshold = videoNudityThreshold;
-
-    this.logger.info('ModerationResourceStore initialized');
-    this.logger.info(`  Enabled: ${enabled}`);
-    this.logger.info(`  Thresholds: image=${imageNudityThreshold}, text=${textSexualThreshold}/${textToxicThreshold}, video=${videoNudityThreshold}`);
-  }
-
-  public async hasResource(identifier: ResourceIdentifier): Promise<boolean> {
-    return this.source.hasResource(identifier);
-  }
-
-  public async getRepresentation(
-    identifier: ResourceIdentifier,
-    preferences: RepresentationPreferences,
-    conditions?: Conditions,
-  ): Promise<Representation> {
-    return this.source.getRepresentation(identifier, preferences, conditions);
-  }
-
-  public async setRepresentation(
-    identifier: ResourceIdentifier,
-    representation: Representation,
-    conditions?: Conditions,
-  ): Promise<ChangeMap> {
-    await this.moderateRepresentation(identifier, representation);
-    return this.source.setRepresentation(identifier, representation, conditions);
-  }
-
-  public async addResource(
-    container: ResourceIdentifier,
-    representation: Representation,
-    conditions?: Conditions,
-  ): Promise<ChangeMap> {
-    await this.moderateRepresentation(container, representation);
-    return this.source.addResource(container, representation, conditions);
-  }
-
-  public async deleteResource(
-    identifier: ResourceIdentifier,
-    conditions?: Conditions,
-  ): Promise<ChangeMap> {
-    return this.source.deleteResource(identifier, conditions);
-  }
-
-  public async modifyResource(
-    identifier: ResourceIdentifier,
-    patch: Patch,
-    conditions?: Conditions,
-  ): Promise<ChangeMap> {
-    return this.source.modifyResource(identifier, patch, conditions);
-  }
-
-  private async moderateRepresentation(
-    identifier: ResourceIdentifier,
-    representation: Representation,
-  ): Promise<void> {
-    if (!this.enabled || !representation.data) {
-      return;
-    }
-
-    const contentType = representation.metadata.contentType;
-    if (!contentType) {
-      return;
-    }
-
-    const shouldModerate = this.shouldModerateContentType(contentType);
-    if (!shouldModerate) {
-      return;
-    }
-
-    this.logger.info(`Moderating ${contentType} upload to ${identifier.path}`);
-
-    try {
-      const chunks: Buffer[] = [];
-      for await (const chunk of representation.data) {
-        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
-      }
-      const buffer = Buffer.concat(chunks);
-
-      if (contentType.startsWith('image/')) {
-        await this.moderateImage(identifier.path, buffer, contentType);
-      } else if (contentType.startsWith('video/')) {
-        await this.moderateVideo(identifier.path, buffer, contentType);
-      } else if (contentType.startsWith('text/')) {
-        await this.moderateText(identifier.path, buffer);
-      }
-
-      representation.data = guardedStreamFrom(buffer);
-
-    } catch (error: unknown) {
-      if (error instanceof ForbiddenHttpError) {
-        throw error;
-      }
-      this.logger.error(`Moderation failed for ${identifier.path}: ${(error as Error).message}`);
-      this.logger.warn('Allowing content through due to moderation failure (fail-open policy)');
-      
-      // Re-create stream from buffer if we have it
-      const chunks: Buffer[] = [];
-      try {
-        for await (const chunk of representation.data) {
-          chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
-        }
-        representation.data = guardedStreamFrom(Buffer.concat(chunks));
-      } catch {
-        // Stream already consumed, can't recover
-      }
-    }
-  }
-
-  private shouldModerateContentType(contentType: string): boolean {
-    return contentType.startsWith('image/') || 
-           contentType.startsWith('video/') || 
-           contentType.startsWith('text/');
-  }
-
-  private async moderateImage(path: string, buffer: Buffer, contentType: string): Promise<void> {
-    const tempFile = `/tmp/moderation_${Date.now()}.${this.getFileExtension(contentType)}`;
-    writeFileSync(tempFile, buffer);
-
-    try {
-      const result = await this.client.analyzeImage(tempFile);
-
-      if (result.nudity?.raw && result.nudity.raw > this.imageNudityThreshold) {
-        this.logger.warn(`Image BLOCKED: ${path} - nudity score ${result.nudity.raw.toFixed(2)} > ${this.imageNudityThreshold}`);
-        throw new ForbiddenHttpError(`Image contains inappropriate content (nudity: ${result.nudity.raw.toFixed(2)})`);
-      }
-
-      this.logger.info(`Image APPROVED: ${path}`);
-    } finally {
-      try {
-        unlinkSync(tempFile);
-      } catch {
-        this.logger.warn(`Failed to cleanup temp file: ${tempFile}`);
-      }
-    }
-  }
-
-  private async moderateVideo(path: string, buffer: Buffer, contentType: string): Promise<void> {
-    const tempFile = `/tmp/moderation_${Date.now()}.${this.getFileExtension(contentType)}`;
-    writeFileSync(tempFile, buffer);
-
-    try {
-      const result = await this.client.analyzeVideo(tempFile);
-
-      if (result.nudity?.raw && result.nudity.raw > this.videoNudityThreshold) {
-        this.logger.warn(`Video BLOCKED: ${path} - nudity score ${result.nudity.raw.toFixed(2)} > ${this.videoNudityThreshold}`);
-        throw new ForbiddenHttpError(`Video contains inappropriate content (nudity: ${result.nudity.raw.toFixed(2)})`);
-      }
-
-      this.logger.info(`Video APPROVED: ${path}`);
-    } finally {
-      try {
-        unlinkSync(tempFile);
-      } catch {
-        this.logger.warn(`Failed to cleanup temp file: ${tempFile}`);
-      }
-    }
-  }
-
-  private async moderateText(path: string, buffer: Buffer): Promise<void> {
-    const text = buffer.toString('utf-8');
-    const result = await this.client.analyzeText(text);
-
-    const violations: string[] = [];
-
-    if (result.sexual > this.textSexualThreshold) {
-      violations.push(`sexual content (${result.sexual.toFixed(2)} > ${this.textSexualThreshold})`);
-    }
-
-    if (result.toxic > this.textToxicThreshold) {
-      violations.push(`toxic content (${result.toxic.toFixed(2)} > ${this.textToxicThreshold})`);
-    }
-
-    if (violations.length > 0) {
-      this.logger.warn(`Text BLOCKED: ${path} - ${violations.join(', ')}`);
-      throw new ForbiddenHttpError(`Text contains inappropriate content: ${violations.join(', ')}`);
-    }
-
-    this.logger.info(`Text APPROVED: ${path}`);
-  }
-
-  private getFileExtension(contentType: string): string {
-    const map: Record<string, string> = {
-      'image/jpeg': 'jpg',
-      'image/png': 'png',
-      'image/gif': 'gif',
-      'image/webp': 'webp',
-      'video/mp4': 'mp4',
-      'video/webm': 'webm',
-    };
-    return map[contentType] || 'bin';
-  }
-}

package/src/ModerationStore.ts

@@ -1,41 +0,0 @@
-import { promises as fs } from 'node:fs';
-import { join } from 'node:path';
-import { getLoggerFor } from '@solid/community-server';
-import type { ModerationRecord } from './ModerationRecord';
-
-/**
- * Service for storing moderation violation records.
- */
-export class ModerationStore {
-  protected readonly logger = getLoggerFor(this);
-
-  private readonly storePath: string;
-
-  public constructor(storePath = './data/moderation-logs') {
-    this.storePath = storePath;
-  }
-
-  public async recordViolation(record: Omit<ModerationRecord, 'id' | 'timestamp'>): Promise<void> {
-    try {
-      await fs.mkdir(this.storePath, { recursive: true });
-
-      const fullRecord: ModerationRecord = {
-        ...record,
-        id: this.generateId(),
-        timestamp: new Date(),
-      };
-
-      const filename = `${new Date().toISOString().split('T')[0]}.jsonl`;
-      const filepath = join(this.storePath, filename);
-      const logEntry = `${JSON.stringify(fullRecord)}\n`;
-
-      await fs.appendFile(filepath, logEntry);
-    } catch (error: unknown) {
-      this.logger.error(`Failed to record moderation violation: ${String(error)}`);
-    }
-  }
-
-  private generateId(): string {
-    return Date.now().toString(36) + Math.random().toString(36).slice(2);
-  }
-}

package/src/util/GuardedStream.ts

@@ -1,101 +0,0 @@
-import { getLoggerFor } from '@solid/community-server';
-
-const logger = getLoggerFor('GuardedStream');
-
-// Using symbols to make sure we don't override existing parameters
-const guardedErrors = Symbol('guardedErrors');
-const guardedTimeout = Symbol('guardedTimeout');
-
-// Private fields for guarded streams
-class Guard {
-  // Workaround for the fact that we don't initialize this variable as expected
-  declare private [guardedErrors]: Error[];
-  private [guardedTimeout]?: NodeJS.Timeout;
-}
-
-/**
- * A stream that is guarded from emitting errors when there are no listeners.
- * If an error occurs while no listener is attached,
- * it will store the error and emit it once a listener is added (or a timeout occurs).
- */
-export type Guarded<T extends NodeJS.EventEmitter = NodeJS.EventEmitter> = T & Guard;
-
-/**
- * Determines whether the stream is guarded against emitting errors.
- */
-export function isGuarded<T extends NodeJS.EventEmitter>(stream: T): stream is Guarded<T> {
-  return typeof (stream as unknown as Guarded)[guardedErrors] === 'object';
-}
-
-/**
- * Callback that is used when a stream emits an error and no other error listener is attached.
- * Used to store the error and start the logger timer.
- *
- * It is important that this listener always remains attached for edge cases where an error listener gets removed
- * and the number of error listeners is checked immediately afterwards.
- * See https://github.com/CommunitySolidServer/CommunitySolidServer/pull/462#issuecomment-758013492 .
- */
-function guardingErrorListener(this: Guarded, error: Error): void {
-  // Only fall back to this if no new listeners are attached since guarding started.
-  const errorListeners = this.listeners('error');
-  if (errorListeners.at(-1) === guardingErrorListener) {
-    this[guardedErrors].push(error);
-    if (!this[guardedTimeout]) {
-      this[guardedTimeout] = setTimeout((): void => {
-        logger.error(`No error listener was attached but error was thrown: ${error.message}`);
-      }, 1000);
-    }
-  }
-}
-
-/**
- * Callback that is used when a new listener is attached and there are errors that were not emitted yet.
- */
-function emitStoredErrors(this: Guarded, event: string, func: (error: Error) => void): void {
-  if (event === 'error' && func !== guardingErrorListener) {
-    // Cancel an error timeout
-    if (this[guardedTimeout]) {
-      clearTimeout(this[guardedTimeout]);
-      this[guardedTimeout] = undefined;
-    }
-
-    // Emit any errors that were guarded
-    const errors = this[guardedErrors];
-    if (errors.length > 0) {
-      this[guardedErrors] = [];
-      setImmediate((): void => {
-        for (const error of errors) {
-          this.emit('error', error);
-        }
-      });
-    }
-  }
-}
-
-/**
- * Makes sure that listeners always receive the error event of a stream,
- * even if it was thrown before the listener was attached.
- *
- * When guarding a stream it is assumed that error listeners already attached should be ignored,
- * only error listeners attached after the stream is guarded will prevent an error from being logged.
- *
- * If the input is already guarded the guard will be reset,
- * which means ignoring error listeners already attached.
- *
- * @param stream - Stream that can potentially throw an error.
- *
- * @returns The stream.
- */
-export function guardStream<T extends NodeJS.EventEmitter>(stream: T): Guarded<T> {
-  const guarded = stream as Guarded<T>;
-  if (isGuarded(stream)) {
-    // This makes sure the guarding error listener is the last one in the list again
-    guarded.removeListener('error', guardingErrorListener);
-    guarded.on('error', guardingErrorListener);
-  } else {
-    guarded[guardedErrors] = [];
-    guarded.on('error', guardingErrorListener);
-    guarded.on('newListener', emitStoredErrors);
-  }
-  return guarded;
-}