@kkuffour/solid-moderation-plugin 0.2.2 → 0.2.3

package/css-moderation-spec.md

@@ -0,0 +1,1422 @@
+# Technical Specification: Content Moderation Plugin for Community Solid Server
+
+**Version:** 1.1 (Revised)  
+**Date:** January 22, 2026  
+**Author:** Technical Architecture Team  
+**Status:** Ready for Implementation
+
+---
+
+## Table of Contents
+
+1. [Executive Summary](#executive-summary)
+2. [System Overview](#system-overview)
+3. [Architecture](#architecture)
+4. [Component Specifications](#component-specifications)
+5. [API Integration](#api-integration)
+6. [Configuration](#configuration)
+7. [Data Flow](#data-flow)
+8. [Security & Privacy](#security--privacy)
+9. [Error Handling](#error-handling)
+10. [Testing Strategy](#testing-strategy)
+11. [Deployment](#deployment)
+12. [Performance Considerations](#performance-considerations)
+13. [Future Enhancements](#future-enhancements)
+
+---
+
+## 1. Executive Summary
+
+This document specifies the design and implementation of a Content Moderation Plugin for Community Solid Server (CSS). The plugin provides automated content moderation capabilities for user-uploaded resources, leveraging external AI-powered moderation services while maintaining compliance with Solid protocol specifications.
+
+### Key Features
+
+- Automated content scanning for images, videos, and text
+- Integration with SightEngine API for AI-powered moderation
+- Configurable moderation policies per resource type
+- Asynchronous processing to minimize performance impact
+- Comprehensive logging and audit trails
+- WebID-based access control integration
+
+### Goals
+
+- Protect users from harmful content (NSFW, violence, hate speech)
+- Maintain platform compliance with legal requirements
+- Preserve Solid's decentralized architecture principles
+- Minimize latency impact on resource operations
+
+### Architectural Approach
+
+This plugin uses the `asynchronous-handlers` package (the foundation of CSS's handler architecture) rather than extending CSS internal classes directly. This approach ensures:
+- **Stability**: No dependency on CSS internal implementation details
+- **Compatibility**: Works across CSS versions that use the same AsyncHandler interface
+- **Maintainability**: Clear separation between plugin and server internals
+- **Flexibility**: Can be used with other AsyncHandler-based systems
+
+---
+
+## 2. System Overview
+
+### 2.1 Scope
+
+The Content Moderation Plugin operates as a middleware component within the CSS request handling pipeline, intercepting resource creation and update operations to perform content analysis before persistence.
+
+### 2.2 Components
+
+- **ModerationHandler**: Primary HTTP request interceptor (extends AsyncHandler)
+- **ModerationService**: Business logic coordinator
+- **SightEngineClient**: External API integration wrapper
+- **ModerationStore**: Audit log and decision persistence
+- **ConfigurationManager**: Policy and threshold management
+
+### 2.3 Technology Stack
+
+- **Runtime**: Node.js 18+ with TypeScript
+- **Handler Framework**: asynchronous-handlers (standalone package)
+- **Server Integration**: Community Solid Server via Components.js
+- **External Service**: SightEngine Moderation API
+- **Storage**: RDF/Turtle for audit logs
+- **Configuration**: JSON-LD component configuration
+
+---
+
+## 3. Architecture
+
+### 3.1 System Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                     Client Request                       │
+└────────────────────┬────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│              CSS Request Pipeline                        │
+│  ┌────────────────────────────────────────────────┐    │
+│  │         ModerationHandler                       │    │
+│  │  (extends AsyncHandler from asynchronous-      │    │
+│  │   handlers package)                             │    │
+│  │  - Intercepts POST/PUT/PATCH requests          │    │
+│  │  - Extracts content for analysis               │    │
+│  └──────────────────┬─────────────────────────────┘    │
+└────────────────────┼──────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│           ModerationService                              │
+│  ┌──────────────────────────────────────────────┐      │
+│  │  - Content type detection                     │      │
+│  │  - Policy retrieval                           │      │
+│  │  - Decision logic                             │      │
+│  └──────────┬───────────────────────┬────────────┘      │
+└────────────┼───────────────────────┼────────────────────┘
+             │                       │
+             ▼                       ▼
+┌─────────────────────┐   ┌──────────────────────┐
+│  SightEngineClient  │   │   ModerationStore    │
+│  - API calls        │   │   - Audit logging    │
+│  - Response parsing │   │   - Decision cache   │
+│  - Rate limiting    │   │   - RDF persistence  │
+└─────────────────────┘   └──────────────────────┘
+```
+
+### 3.2 Handler Architecture
+
+The plugin uses the AsyncHandler pattern which is the foundation of CSS:
+
+```
+AsyncHandler<TIn, TOut>
+├── canHandle(input: TIn): Promise<void>
+├── handle(input: TIn): Promise<TOut>
+└── handleSafe(input: TIn): Promise<TOut>
+```
+
+This pattern allows:
+- **Chaining**: Handlers can be chained using WaterfallHandler
+- **Parallelism**: Multiple handlers can run simultaneously
+- **Composition**: Handlers can be composed into complex pipelines
+- **Type Safety**: Full TypeScript support
+
+### 3.3 Integration Points
+
+**Upstream Integration:**
+- CSS request pipeline via Components.js configuration
+- Type imports from @solid/community-server (types only, not classes)
+- AsyncHandler from asynchronous-handlers package
+
+**Downstream Integration:**
+- SightEngine REST API (HTTPS)
+- CSS ResourceStore for audit logs
+- Notification system for administrators
+
+---
+
+## 4. Component Specifications
+
+### 4.1 ModerationHandler
+
+**Purpose:** Intercepts HTTP requests to trigger moderation workflow
+
+**Implementation:**
+```typescript
+import { AsyncHandler } from 'asynchronous-handlers';
+import type { Operation, ResponseDescription } from '@solid/community-server';
+
+export class ModerationHandler extends AsyncHandler<Operation, ResponseDescription> {
+  private moderationService: ModerationService;
+  private config: ModerationConfig;
+  private nextHandler: AsyncHandler<Operation, ResponseDescription>;
+
+  constructor(
+    moderationService: ModerationService,
+    config: ModerationConfig,
+    nextHandler: AsyncHandler<Operation, ResponseDescription>
+  ) {
+    super();
+    this.moderationService = moderationService;
+    this.config = config;
+    this.nextHandler = nextHandler;
+  }
+
+  async canHandle(operation: Operation): Promise<void> {
+    // Check if this operation needs moderation
+    if (!this.shouldModerate(operation)) {
+      throw new Error('Operation does not require moderation');
+    }
+  }
+
+  async handle(operation: Operation): Promise<ResponseDescription> {
+    // Extract content from operation
+    const content = await this.extractContent(operation);
+    const metadata = this.extractMetadata(operation);
+
+    // Moderate content
+    const decision = await this.moderationService.moderate(content, metadata);
+
+    // Apply decision
+    if (decision.verdict === 'rejected') {
+      throw new ForbiddenHttpError(decision.reason);
+    }
+
+    // Pass to next handler
+    return this.nextHandler.handle(operation);
+  }
+
+  private shouldModerate(operation: Operation): boolean {
+    // Check if method is in enabled methods
+    if (!this.config.enabledMethods.includes(operation.method)) {
+      return false;
+    }
+
+    // Check if path is excluded
+    for (const excludedPath of this.config.excludedPaths) {
+      if (operation.target.path.startsWith(excludedPath)) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+}
+```
+
+**Configuration Parameters:**
+- `enabledMethods`: Array of HTTP methods to moderate
+- `excludedPaths`: Resources exempt from moderation
+- `asyncProcessing`: Enable background moderation
+- `fallbackBehavior`: Action on service failure (allow/deny)
+
+### 4.2 ModerationService
+
+**Purpose:** Orchestrates moderation logic and policy enforcement
+
+**Interface:**
+```typescript
+export interface ModerationService {
+  moderate(content: Buffer, metadata: ResourceMetadata): Promise<ModerationResult>;
+  getPolicy(resourceType: string): ModerationPolicy;
+  evaluateDecision(analysis: SightEngineResponse, policy: ModerationPolicy): ModerationDecision;
+}
+
+export interface ModerationResult {
+  verdict: 'approved' | 'rejected' | 'flagged';
+  reason: string;
+  confidence: number;
+  categories: string[];
+  timestamp: Date;
+}
+
+export interface ResourceMetadata {
+  contentType: string;
+  size: number;
+  owner: string;
+  targetPath: string;
+}
+```
+
+**Key Methods:**
+
+**`moderate(content, metadata)`**
+- Detects content type (image/video/text)
+- Retrieves applicable moderation policy
+- Invokes SightEngineClient for analysis
+- Applies policy thresholds to results
+- Returns decision with justification
+
+**`getPolicy(resourceType)`**
+- Loads configuration from Components.js
+- Supports per-type policies (default, image, video, text)
+- Caches policies for performance
+
+**`evaluateDecision(analysis, policy)`**
+- Compares API scores against thresholds
+- Generates detailed justification
+- Applies multi-criteria logic (AND/OR conditions)
+
+### 4.3 SightEngineClient
+
+**Purpose:** Abstracts SightEngine API communication
+
+**Interface:**
+```typescript
+export interface SightEngineClient {
+  checkImage(imageBuffer: Buffer): Promise<SightEngineResponse>;
+  checkVideo(videoUrl: string): Promise<SightEngineResponse>;
+  checkText(text: string): Promise<SightEngineResponse>;
+}
+
+export interface SightEngineResponse {
+  status: 'success' | 'failure';
+  nudity?: {
+    sexual_activity: number;
+    sexual_display: number;
+    erotica: number;
+    raw: number;
+  };
+  weapon?: number;
+  alcohol?: number;
+  drugs?: number;
+  offensive?: {
+    prob: number;
+  };
+  gore?: {
+    prob: number;
+  };
+}
+```
+
+**Features:**
+- Automatic retry with exponential backoff
+- Rate limiting (respects SightEngine limits)
+- Response caching for duplicate content
+- Error handling and timeout management
+
+**Configuration:**
+- `apiKey`: SightEngine API key
+- `apiSecret`: SightEngine API secret
+- `baseUrl`: API endpoint (default: api.sightengine.com)
+- `timeout`: Request timeout (default: 30s)
+- `maxRetries`: Retry attempts (default: 3)
+
+### 4.4 ModerationStore
+
+**Purpose:** Persists moderation decisions for audit and appeal
+
+**Interface:**
+```typescript
+export interface ModerationStore {
+  save(decision: ModerationDecision): Promise<void>;
+  find(resourceUrl: string): Promise<ModerationDecision | undefined>;
+  list(filter: ModerationFilter): Promise<ModerationDecision[]>;
+}
+
+export interface ModerationDecision {
+  id: string;
+  resourceUrl: string;
+  verdict: 'approved' | 'rejected' | 'flagged';
+  reason: string;
+  categories: string[];
+  confidence: number;
+  timestamp: Date;
+  moderator: string; // WebID or 'system'
+  appealed: boolean;
+}
+```
+
+**Storage Schema (RDF/Turtle):**
+```turtle
+@prefix mod: <http://www.w3.org/ns/solid/moderation#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+<#decision-123> a mod:ModerationDecision ;
+  mod:resource <https://pod.example/user/image.jpg> ;
+  mod:timestamp "2026-01-22T10:30:00Z"^^xsd:dateTime ;
+  mod:verdict "rejected" ;
+  mod:reason "NSFW content detected (confidence: 0.95)" ;
+  mod:moderator <https://moderation.example/agent#ai> ;
+  mod:appealed false .
+```
+
+---
+
+## 5. API Integration
+
+### 5.1 SightEngine API Endpoints
+
+**Image Check:**
+```
+POST https://api.sightengine.com/1.0/check.json
+Content-Type: multipart/form-data
+
+Parameters:
+- media: image file (binary)
+- models: nudity,wad,offensive,gore
+- api_user: {apiKey}
+- api_secret: {apiSecret}
+```
+
+**Response Format:**
+```json
+{
+  "status": "success",
+  "nudity": {
+    "sexual_activity": 0.02,
+    "sexual_display": 0.01,
+    "erotica": 0.05,
+    "raw": 0.91
+  },
+  "weapon": 0.01,
+  "alcohol": 0.03,
+  "drugs": 0.02,
+  "offensive": {
+    "prob": 0.05
+  },
+  "gore": {
+    "prob": 0.02
+  }
+}
+```
+
+### 5.2 Moderation Models
+
+**Available Models:**
+- `nudity`: Detects nudity, sexual content
+- `wad`: Weapons, alcohol, drugs
+- `offensive`: Hate symbols, gestures
+- `gore`: Violence, graphic content
+- `text`: Profanity, hate speech (for text analysis)
+
+### 5.3 Error Handling
+
+**API Error Codes:**
+- `401`: Invalid credentials → Fail closed (reject upload)
+- `429`: Rate limit exceeded → Queue for later processing
+- `500`: Server error → Retry with backoff
+- `timeout`: Network timeout → Retry or fail open (configurable)
+
+---
+
+## 6. Configuration
+
+### 6.1 Package Dependencies
+
+**package.json:**
+```json
+{
+  "name": "@solid-contrib/moderation-plugin",
+  "version": "1.0.0",
+  "dependencies": {
+    "asynchronous-handlers": "^1.0.0",
+    "@solid/community-server": "^7.0.0",
+    "axios": "^1.6.0",
+    "componentsjs": "^6.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "jest": "^29.0.0"
+  }
+}
+```
+
+### 6.2 Components.js Configuration
+
+**Example Configuration:**
+```json
+{
+  "@context": [
+    "https://linkedsoftwaredependencies.org/bundles/npm/@solid/community-server/^7.0.0/components/context.jsonld",
+    "https://linkedsoftwaredependencies.org/bundles/npm/@solid-contrib/moderation-plugin/^1.0.0/components/context.jsonld"
+  ],
+  "@graph": [
+    {
+      "@id": "urn:moderation:default:ModerationHandler",
+      "@type": "ModerationHandler",
+      "enabledMethods": ["POST", "PUT"],
+      "excludedPaths": ["/system/", "/.well-known/"],
+      "asyncProcessing": false,
+      "fallbackBehavior": "allow",
+      "moderationService": {
+        "@id": "urn:moderation:default:ModerationService"
+      },
+      "nextHandler": {
+        "@id": "urn:solid-server:default:ResourceStore"
+      }
+    },
+    {
+      "@id": "urn:moderation:default:ModerationService",
+      "@type": "ModerationService",
+      "policies": {
+        "default": {
+          "enabled": true,
+          "thresholds": {
+            "nudity.raw": 0.7,
+            "weapon": 0.8,
+            "gore.prob": 0.8,
+            "offensive.prob": 0.7
+          },
+          "action": "reject"
+        },
+        "image/jpeg": {
+          "enabled": true,
+          "models": ["nudity", "wad", "gore", "offensive"],
+          "thresholds": {
+            "nudity.sexual_display": 0.6,
+            "weapon": 0.75
+          }
+        }
+      },
+      "sightEngineClient": {
+        "@id": "urn:moderation:default:SightEngineClient"
+      }
+    },
+    {
+      "@id": "urn:moderation:default:SightEngineClient",
+      "@type": "SightEngineClient",
+      "apiKey": "@ENV:SIGHTENGINE_API_KEY",
+      "apiSecret": "@ENV:SIGHTENGINE_API_SECRET",
+      "timeout": 30000,
+      "maxRetries": 3
+    }
+  ]
+}
+```
+
+### 6.3 Injecting into CSS Pipeline
+
+**Modifying existing CSS configuration:**
+
+To add moderation to an existing CSS instance, you need to insert the ModerationHandler into the handler chain before the ResourceStore. This can be done by:
+
+1. **Using WaterfallHandler** (from asynchronous-handlers):
+
+```json
+{
+  "@id": "urn:solid-server:default:HttpHandler",
+  "@type": "WaterfallHandler",
+  "handlers": [
+    { "@id": "urn:moderation:default:ModerationHandler" },
+    { "@id": "urn:solid-server:default:OriginalHttpHandler" }
+  ]
+}
+```
+
+2. **Or setting nextHandler on ModerationHandler**:
+
+```json
+{
+  "@id": "urn:moderation:default:ModerationHandler",
+  "@type": "ModerationHandler",
+  "nextHandler": {
+    "@id": "urn:solid-server:default:ResourceStore"
+  }
+}
+```
+
+### 6.4 Environment Variables
+
+```bash
+# SightEngine API credentials
+SIGHTENGINE_API_KEY=your_api_key
+SIGHTENGINE_API_SECRET=your_api_secret
+
+# Moderation settings
+MODERATION_ENABLED=true
+MODERATION_ASYNC=false
+MODERATION_FALLBACK=allow  # allow|deny
+
+# Logging
+MODERATION_LOG_LEVEL=info  # debug|info|warn|error
+```
+
+### 6.5 Policy Configuration
+
+**Policy Structure:**
+```typescript
+interface ModerationPolicy {
+  enabled: boolean;
+  models: string[];  // SightEngine models to use
+  thresholds: Record<string, number>;  // Score thresholds (0-1)
+  action: 'allow' | 'reject' | 'flag';
+  logDecisions: boolean;
+  notifyAdmin: boolean;
+}
+```
+
+**Threshold Semantics:**
+- Scores >= threshold trigger the action
+- Multiple thresholds evaluated with OR logic
+- Set threshold to 1.0 to disable a check
+
+---
+
+## 7. Data Flow
+
+### 7.1 Request Processing Flow
+
+```
+1. Client uploads resource (POST /user/image.jpg)
+   ↓
+2. CSS routes to handler chain
+   ↓
+3. ModerationHandler.canHandle() checks if moderation needed
+   ↓
+4. ModerationHandler.handle() called
+   ↓
+5. Extract content + metadata from request
+   ↓
+6. ModerationService.moderate(content, metadata)
+   ↓
+7. Detect content type (image/jpeg)
+   ↓
+8. Retrieve policy for image/jpeg
+   ↓
+9. SightEngineClient.checkImage(buffer)
+   ↓
+10. Parse API response scores
+    ↓
+11. Evaluate against thresholds
+    ↓
+12. Generate ModerationDecision
+    ↓
+13. Store decision in ModerationStore
+    ↓
+14. Return decision to ModerationHandler
+    ↓
+15a. If APPROVED: nextHandler.handle(operation)
+15b. If REJECTED: throw ForbiddenHttpError
+15c. If FLAGGED: nextHandler.handle() + notify admin
+```
+
+### 7.2 Handler Chain Example
+
+```typescript
+// CSS sets up the chain via Components.js:
+const pipeline = new WaterfallHandler([
+  authenticationHandler,
+  authorizationHandler,
+  moderationHandler,  // ← Our plugin inserted here
+  resourceStore
+]);
+
+// When a request comes in:
+await pipeline.handleSafe(operation);
+// The WaterfallHandler calls each handler's canHandle()
+// until one succeeds, then calls its handle()
+```
+
+---
+
+## 8. Security & Privacy
+
+### 8.1 Data Protection
+
+**Principles:**
+- Minimal data transmission: Only content being moderated sent to SightEngine
+- No permanent storage on third-party servers
+- Audit logs stored in user's pod (if permitted)
+- Encrypted API communication (TLS 1.3)
+
+### 8.2 Access Control
+
+**Moderation System Access:**
+- Only resources the requesting user has write access to are moderated
+- Moderation decisions inherit pod's access control
+- Admin interface requires special administrative role
+- Audit logs protected by WebID authentication
+
+### 8.3 API Key Security
+
+- Store credentials in environment variables
+- Never log API keys or secrets
+- Rotate keys periodically
+- Use separate keys for dev/staging/production
+- Monitor API usage for anomalies
+
+### 8.4 Privacy Considerations
+
+**User Rights:**
+- Users can request moderation decision details
+- Appeal process for rejected content
+- Option to disable moderation (admin only)
+- Audit log retention policy (default: 90 days)
+
+**Data Minimization:**
+- Don't send metadata unnecessarily
+- Redact sensitive information from logs
+- Delete temporary files immediately after processing
+
+---
+
+## 9. Error Handling
+
+### 9.1 Error Categories
+
+**1. API Errors**
+```typescript
+class ModerationAPIError extends Error {
+  constructor(
+    public statusCode: number,
+    public apiResponse: unknown,
+    message: string
+  ) {
+    super(message);
+  }
+}
+
+// Handle in SightEngineClient
+async checkImage(buffer: Buffer): Promise<SightEngineResponse> {
+  try {
+    const response = await this.apiClient.post('/check.json', formData);
+    return response.data;
+  } catch (error) {
+    if (error.response?.status === 429) {
+      throw new ModerationAPIError(429, error.response.data, 'Rate limit exceeded');
+    }
+    throw new ModerationAPIError(500, null, 'API request failed');
+  }
+}
+```
+
+**2. Configuration Errors**
+- Invalid policy configuration → Fail server startup
+- Missing API credentials → Fail server startup
+- Invalid threshold values → Log warning, use defaults
+
+**3. Content Processing Errors**
+- Unsupported content type → Skip moderation (allow)
+- Corrupted file → Reject with 400 Bad Request
+- File too large → Reject with 413 Payload Too Large
+
+### 9.2 Fallback Strategies
+
+**Service Unavailable:**
+```typescript
+interface FallbackConfig {
+  behavior: 'allow' | 'deny' | 'queue';
+  maxQueueSize: number;
+  retryInterval: number;
+}
+
+// In ModerationHandler
+async handle(operation: Operation): Promise<ResponseDescription> {
+  try {
+    const decision = await this.service.moderate(content, metadata);
+    return this.applyDecision(decision, operation);
+  } catch (error) {
+    if (this.config.fallbackBehavior === 'allow') {
+      this.logger.warn('Moderation failed, allowing content', error);
+      return this.nextHandler.handle(operation);
+    } else if (this.config.fallbackBehavior === 'deny') {
+      throw new ForbiddenHttpError('Moderation service unavailable');
+    } else {
+      return this.queueForLater(operation);
+    }
+  }
+}
+```
+
+### 9.3 User-Facing Errors
+
+**Rejection Response:**
+```http
+HTTP/1.1 403 Forbidden
+Content-Type: application/json
+
+{
+  "error": "Forbidden",
+  "message": "Resource rejected by content moderation",
+  "details": {
+    "reason": "Content violates community guidelines",
+    "categories": ["nudity"],
+    "appealUrl": "https://pod.example/.moderation/appeal"
+  }
+}
+```
+
+---
+
+## 10. Testing Strategy
+
+### 10.1 Unit Tests
+
+**Components to Test:**
+- ModerationHandler request filtering
+- ModerationService policy evaluation
+- SightEngineClient API communication
+- ModerationStore persistence
+
+**Test Cases:**
+```typescript
+import { ModerationHandler } from '../src/ModerationHandler';
+import { AsyncHandler } from 'asynchronous-handlers';
+
+describe('ModerationHandler', () => {
+  let handler: ModerationHandler;
+  let mockService: jest.Mocked<ModerationService>;
+  let mockNextHandler: jest.Mocked<AsyncHandler<Operation, ResponseDescription>>;
+
+  beforeEach(() => {
+    mockService = createMockService();
+    mockNextHandler = createMockHandler();
+    handler = new ModerationHandler(mockService, config, mockNextHandler);
+  });
+
+  describe('canHandle', () => {
+    it('should succeed for POST requests', async () => {
+      const operation = { method: 'POST', target: { path: '/test' } };
+      await expect(handler.canHandle(operation)).resolves.toBeUndefined();
+    });
+
+    it('should fail for excluded paths', async () => {
+      const operation = { method: 'POST', target: { path: '/system/test' } };
+      await expect(handler.canHandle(operation)).rejects.toThrow();
+    });
+  });
+
+  describe('handle', () => {
+    it('should reject content exceeding thresholds', async () => {
+      mockService.moderate.mockResolvedValue({
+        verdict: 'rejected',
+        reason: 'NSFW content'
+      });
+      
+      const operation = createTestOperation();
+      await expect(handler.handle(operation)).rejects.toThrow(ForbiddenHttpError);
+    });
+
+    it('should pass approved content to next handler', async () => {
+      mockService.moderate.mockResolvedValue({
+        verdict: 'approved'
+      });
+      
+      const operation = createTestOperation();
+      const result = await handler.handle(operation);
+      
+      expect(mockNextHandler.handle).toHaveBeenCalledWith(operation);
+    });
+  });
+});
+
+describe('ModerationService', () => {
+  describe('evaluateDecision', () => {
+    it('should reject content exceeding nudity threshold', () => {
+      const analysis = { nudity: { raw: 0.9 } };
+      const policy = { thresholds: { 'nudity.raw': 0.7 } };
+      const decision = service.evaluateDecision(analysis, policy);
+      expect(decision.verdict).toBe('rejected');
+    });
+
+    it('should allow content below all thresholds', () => {
+      const analysis = { nudity: { raw: 0.3 }, weapon: 0.1 };
+      const policy = { thresholds: { 'nudity.raw': 0.7, weapon: 0.8 } };
+      const decision = service.evaluateDecision(analysis, policy);
+      expect(decision.verdict).toBe('approved');
+    });
+  });
+});
+```
+
+### 10.2 Integration Tests
+
+**Scenarios:**
+1. Upload safe image → Should succeed
+2. Upload NSFW image → Should be rejected
+3. Upload with API unavailable → Should follow fallback behavior
+4. Upload to excluded path → Should skip moderation
+5. Appeal rejected decision → Should update decision record
+
+**Test Setup:**
+```typescript
+import { AppRunner } from '@solid/community-server';
+
+describe('Moderation Integration', () => {
+  let app: AppRunner;
+  let mockSightEngine: MockAdapter;
+
+  beforeAll(async () => {
+    mockSightEngine = new MockAdapter(axios);
+    app = await AppRunner.create({
+      mainModulePath: testConfigPath,
+      variables: {
+        'urn:moderation:default:SightEngineClient': createMockClient(mockSightEngine)
+      }
+    });
+    await app.start();
+  });
+
+  afterAll(async () => {
+    await app.stop();
+  });
+
+  it('should reject NSFW image upload', async () => {
+    mockSightEngine.onPost('/check.json').reply(200, {
+      status: 'success',
+      nudity: { raw: 0.95 }
+    });
+
+    const response = await fetch('http://localhost:3000/user/test.jpg', {
+      method: 'POST',
+      body: nsfwImageBuffer
+    });
+
+    expect(response.status).toBe(403);
+    const body = await response.json();
+    expect(body.details.categories).toContain('nudity');
+  });
+});
+```
+
+### 10.3 Performance Tests
+
+**Metrics to Measure:**
+- Moderation latency (target: <500ms for images)
+- Throughput (requests/second with moderation)
+- Resource usage (memory, CPU during moderation)
+- API rate limit compliance
+
+**Load Testing:**
+```typescript
+// Using k6 or similar
+import http from 'k6/http';
+import { check } from 'k6';
+
+export let options = {
+  stages: [
+    { duration: '2m', target: 50 },  // Ramp up
+    { duration: '5m', target: 50 },  // Stay at 50 users
+    { duration: '2m', target: 0 },   // Ramp down
+  ],
+};
+
+export default function() {
+  const image = open('./test-image.jpg', 'b');
+  const response = http.post('https://pod.test/user/image.jpg', {
+    file: http.file(image, 'image.jpg'),
+  });
+  
+  check(response, {
+    'status is 200 or 403': (r) => [200, 403].includes(r.status),
+    'response time < 1s': (r) => r.timings.duration < 1000,
+  });
+}
+```
+
+---
+
+## 11. Deployment
+
+### 11.1 Installation
+
+**NPM Package (Future):**
+```bash
+npm install @solid-contrib/moderation-plugin
+```
+
+**Manual Installation:**
+1. Copy plugin code to CSS installation
+2. Install dependencies: `npm install asynchronous-handlers`
+3. Update Components.js configuration
+4. Set environment variables
+5. Restart server
+
+### 11.2 Project Structure
+
+Following the hello-world-component pattern:
+
+```
+css-moderation-plugin/
+├── package.json              # With lsd:module config
+├── tsconfig.json
+├── .componentsignore
+├── src/
+│   ├── index.ts             # Export all classes
+│   ├── ModerationHandler.ts # Extends AsyncHandler
+│   ├── ModerationService.ts
+│   ├── SightEngineClient.ts
+│   └── ModerationStore.ts
+├── config/
+│   └── moderation.json      # Component instantiation
+├── test/
+│   ├── unit/
+│   │   ├── ModerationHandler.test.ts
+│   │   └── ModerationService.test.ts
+│   └── integration/
+│       └── Server.test.ts
+├── moderation-file.json     # Full CSS config
+└── moderation-partial.json  # Partial config
+```
+
+### 11.3 package.json Configuration
+
+```json
+{
+  "name": "@solid-contrib/moderation-plugin",
+  "version": "1.0.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "lsd:module": "https://linkedsoftwaredependencies.org/bundles/npm/@solid-contrib/moderation-plugin",
+  "lsd:components": "dist/components/components.jsonld",
+  "lsd:contexts": {
+    "https://linkedsoftwaredependencies.org/bundles/npm/@solid-contrib/moderation-plugin/^1.0.0/components/context.jsonld": "dist/components/context.jsonld"
+  },
+  "lsd:importPaths": {
+    "https://linkedsoftwaredependencies.org/bundles/npm/@solid-contrib/moderation-plugin/^1.0.0/components/": "dist/components/",
+    "https://linkedsoftwaredependencies.org/bundles/npm/@solid-contrib/moderation-plugin/^1.0.0/config/": "config/",
+    "https://linkedsoftwaredependencies.org/bundles/npm/@solid-contrib/moderation-plugin/^1.0.0/dist/": "dist/"
+  },
+  "scripts": {
+    "build": "npm run build:ts && npm run build:components",
+    "build:ts": "tsc",
+    "build:components": "componentsjs-generator -s src -c dist/components -r moderation -i .componentsignore"
+  }
+}
+```
+
+### 11.4 Docker Deployment
+
+**Dockerfile:**
+```dockerfile
+FROM node:18-alpine
+
+WORKDIR /app
+
+# Install CSS and moderation plugin
+COPY package*.json ./
+RUN npm ci --production
+
+COPY config/ ./config/
+COPY dist/ ./dist/
+
+# Environment variables
+ENV SIGHTENGINE_API_KEY=""
+ENV SIGHTENGINE_API_SECRET=""
+ENV MODERATION_ENABLED=true
+
+EXPOSE 3000
+
+CMD ["npx", "@solid/community-server", "-c", "config/moderation.json"]
+```
+
+**Docker Compose:**
+```yaml
+version: '3.8'
+services:
+  solid-server:
+    build: .
+    ports:
+      - "3000:3000"
+    environment:
+      - SIGHTENGINE_API_KEY=${SIGHTENGINE_API_KEY}
+      - SIGHTENGINE_API_SECRET=${SIGHTENGINE_API_SECRET}
+      - MODERATION_ENABLED=true
+      - MODERATION_FALLBACK=allow
+    volumes:
+      - ./data:/app/data
+      - ./config:/app/config
+    restart: unless-stopped
+```
+
+### 11.5 Kubernetes Deployment
+
+**Secret:**
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: sightengine-credentials
+type: Opaque
+stringData:
+  api-key: your_key_here
+  api-secret: your_secret_here
+```
+
+**Deployment:**
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: solid-server
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: solid-server
+  template:
+    metadata:
+      labels:
+        app: solid-server
+    spec:
+      containers:
+      - name: solid-server
+        image: solid-server:latest
+        ports:
+        - containerPort: 3000
+        env:
+        - name: SIGHTENGINE_API_KEY
+          valueFrom:
+            secretKeyRef:
+              name: sightengine-credentials
+              key: api-key
+        - name: SIGHTENGINE_API_SECRET
+          valueFrom:
+            secretKeyRef:
+              name: sightengine-credentials
+              key: api-secret
+        resources:
+          requests:
+            memory: "512Mi"
+            cpu: "250m"
+          limits:
+            memory: "1Gi"
+            cpu: "500m"
+```
+
+---
+
+## 12. Performance Considerations
+
+### 12.1 Optimization Strategies
+
+**1. Response Caching:**
+```typescript
+import { CachedHandler } from 'asynchronous-handlers';
+
+// Wrap the moderation handler with caching
+const cachedModerationHandler = new CachedHandler(
+  moderationHandler,
+  ['content'] // Cache based on content hash
+);
+```
+
+**2. Parallel Processing:**
+```typescript
+// For resources with multiple parts
+async moderateMultipart(parts: ResourcePart[]): Promise<ModerationDecision[]> {
+  const promises = parts.map(part => this.moderate(part.content, part.metadata));
+  return Promise.all(promises);
+}
+```
+
+**3. Streaming for Large Files:**
+```typescript
+// Stream large files in chunks
+async moderateVideo(videoStream: ReadableStream): Promise<ModerationDecision> {
+  // Upload to temporary URL accessible by SightEngine
+  const tempUrl = await this.uploadToTemp(videoStream);
+  return this.sightEngine.checkVideo(tempUrl);
+}
+```
+
+### 12.2 Resource Limits
+
+**File Size Limits:**
+- Images: 50MB maximum
+- Videos: 100MB maximum (or use streaming)
+- Text: 10MB maximum
+
+**Rate Limiting:**
+- API calls: 200/minute per SightEngine plan
+- Queue overflow: 1000 pending requests max
+- Circuit breaker: Open after 5 consecutive failures
+
+### 12.3 Monitoring Metrics
+
+**Key Metrics:**
+```typescript
+interface ModerationMetrics {
+  totalRequests: number;
+  moderatedRequests: number;
+  approvedCount: number;
+  rejectedCount: number;
+  flaggedCount: number;
+  averageLatency: number;
+  apiErrors: number;
+  cacheHitRate: number;
+}
+
+// Prometheus exposition
+app.get('/metrics', (req, res) => {
+  const metrics = metricsCollector.getMetrics();
+  res.send(promClient.register.metrics());
+});
+```
+
+**Alerts:**
+- High rejection rate (>10%)
+- API error rate (>5%)
+- Latency degradation (>1s p95)
+- Cache hit rate drop (<70%)
+
+---
+
+## 13. Future Enhancements
+
+### 13.1 Planned Features
+
+**Phase 2 (Q2 2026):**
+- User appeal system with human review workflow
+- Custom ML model training on organization's data
+- Multi-language text moderation
+- Context-aware moderation (consider surrounding metadata)
+
+**Phase 3 (Q3 2026):**
+- Federated moderation policies across pods
+- Reputation system for content creators
+- Real-time content streaming moderation
+- Integration with alternative moderation services (AWS Rekognition, Azure Content Moderator)
+
+### 13.2 Research Areas
+
+**Advanced Capabilities:**
+- Deepfake detection
+- Audio moderation for podcasts
+- Context understanding (memes, satire)
+- User-reported content integration
+- Blockchain-based audit trail
+
+**Solid Protocol Extensions:**
+- Moderation-aware access control
+- Cross-pod moderation coordination
+- Standardized moderation vocabulary (RDF)
+
+### 13.3 Community Feedback Integration
+
+**Feedback Mechanisms:**
+- GitHub issues for bug reports
+- Community forum for feature requests
+- Monthly user surveys
+- Public roadmap transparency
+
+---
+
+## Appendix A: AsyncHandler Pattern
+
+### Why AsyncHandler?
+
+The `asynchronous-handlers` package provides the foundation for CSS's architecture. Using it directly in your plugin offers several advantages:
+
+1. **Stability**: The AsyncHandler interface is stable and versioned separately from CSS
+2. **Compatibility**: Works across CSS versions using the same AsyncHandler version
+3. **Independence**: Your plugin doesn't depend on CSS internal implementation details
+4. **Reusability**: AsyncHandler pattern can be used in other contexts beyond CSS
+
+### AsyncHandler Interface
+
+```typescript
+export abstract class AsyncHandler<TIn, TOut> {
+  /**
+   * Checks whether the input can be handled.
+   * Throws an error if it cannot.
+   */
+  public abstract canHandle(input: TIn): Promise<void>;
+
+  /**
+   * Handles the input.
+   * This should only be called if canHandle did not throw an error.
+   */
+  public abstract handle(input: TIn): Promise<TOut>;
+
+  /**
+   * Helper function that combines canHandle and handle.
+   */
+  public async handleSafe(input: TIn): Promise<TOut> {
+    await this.canHandle(input);
+    return this.handle(input);
+  }
+}
+```
+
+### Composite Handlers Available
+
+From `asynchronous-handlers` package:
+
+- **WaterfallHandler**: Chains handlers, first one that can handle wins
+- **ParallelHandler**: Runs all handlers simultaneously
+- **SequenceHandler**: Runs handlers one after another
+- **CachedHandler**: Caches handler results
+- **UnionHandler**: Combines results from multiple handlers
+
+### Example Usage in CSS Context
+
+```typescript
+import { AsyncHandler, WaterfallHandler } from 'asynchronous-handlers';
+import type { Operation, ResponseDescription } from '@solid/community-server';
+
+// Your custom handler
+class MyHandler extends AsyncHandler<Operation, ResponseDescription> {
+  async canHandle(op: Operation): Promise<void> {
+    if (op.method !== 'POST') {
+      throw new Error('Only POST');
+    }
+  }
+
+  async handle(op: Operation): Promise<ResponseDescription> {
+    // Your logic here
+    return { statusCode: 200 };
+  }
+}
+
+// Combine with other handlers
+const pipeline = new WaterfallHandler([
+  new MyHandler(),
+  new AnotherHandler(),
+  new FallbackHandler()
+]);
+```
+
+---
+
+## Appendix B: Type-Only Imports from CSS
+
+When building plugins, you should **only import types** from `@solid/community-server`, not classes to extend:
+
+### ✅ Correct Imports
+
+```typescript
+// Import types (interfaces, type aliases)
+import type {
+  Operation,
+  ResponseDescription,
+  Representation,
+  ResourceIdentifier,
+  HttpError
+} from '@solid/community-server';
+
+// Import error constructors (not extended, just instantiated)
+import {
+  ForbiddenHttpError,
+  UnauthorizedHttpError,
+  NotFoundHttpError
+} from '@solid/community-server';
+```
+
+### ❌ Incorrect Imports
+
+```typescript
+// DON'T extend CSS internal handler classes
+import { OperationHandler } from '@solid/community-server';
+
+// DON'T extend CSS internal storage classes
+import { ResourceStore } from '@solid/community-server';
+
+// Instead, use AsyncHandler from asynchronous-handlers
+import { AsyncHandler } from 'asynchronous-handlers';
+```
+
+### Why This Matters
+
+- **Type imports** are safe - they're just TypeScript metadata
+- **Class inheritance** creates tight coupling to CSS internals
+- **AsyncHandler** is the stable, public API for extending CSS behavior
+- Your plugin remains compatible across CSS versions
+
+---
+
+## Appendix C: Configuration Examples
+
+### Strict Moderation
+```json
+{
+  "policies": {
+    "default": {
+      "thresholds": {
+        "nudity.raw": 0.5,
+        "weapon": 0.6,
+        "gore.prob": 0.5,
+        "offensive.prob": 0.4
+      },
+      "action": "reject"
+    }
+  }
+}
+```
+
+### Permissive Moderation
+```json
+{
+  "policies": {
+    "default": {
+      "thresholds": {
+        "nudity.sexual_activity": 0.9,
+        "weapon": 0.95,
+        "gore.prob": 0.9
+      },
+      "action": "flag"
+    }
+  }
+}
+```
+
+---
+
+## Appendix D: Troubleshooting
+
+### Common Issues
+
+**1. API Authentication Failure**
+```
+Error: 401 Unauthorized from SightEngine
+Solution: Verify SIGHTENGINE_API_KEY and SIGHTENGINE_API_SECRET are set correctly
+```
+
+**2. Rate Limit Exceeded**
+```
+Error: 429 Too Many Requests
+Solution: Implement queuing or upgrade SightEngine plan
+```
+
+**3. Moderation Not Triggering**
+```
+Issue: Uploads succeed without moderation
+Solution: Check ModerationHandler is in request pipeline before ResourceStore
+```
+
+**4. Handler Not Found**
+```
+Error: Cannot find module 'asynchronous-handlers'
+Solution: npm install asynchronous-handlers
+```
+
+**5. Type Errors with CSS Imports**
+```
+Error: Cannot extend OperationHandler
+Solution: Extend AsyncHandler from asynchronous-handlers instead
+```
+
+---
+
+## Document Revision History
+
+| Version | Date | Author | Changes |
+|---------|------|--------|---------|
+| 1.0 | 2026-01-21 | Technical Architecture Team | Initial release |
+| 1.1 | 2026-01-22 | Technical Architecture Team | Updated to use asynchronous-handlers package; corrected architectural approach |
+
+---
+
+**Document Status:** ✅ Ready for Implementation  
+**Review Status:** Approved by Technical Lead  
+**Next Review Date:** 2026-04-22
+
+**Contact:** For questions or feedback, contact the Technical Architecture Team