taskover-mcp 1.0.1 → 1.2.0

package/image-moderator.js

@@ -0,0 +1,491 @@
+"use strict";
+
+// ---------------------------------------------------------------------------
+// Constants — Moderation policy
+// ---------------------------------------------------------------------------
+const MODERATION_POLICY = {
+  REJECT_CATEGORIES: [
+    "explicit_nudity", "sexual_content", "pornography", "sexual_anime",
+    "fetish", "graphic_gore", "hate_symbols", "illegal_content", "child_exploitation",
+  ],
+  REVIEW_CATEGORIES: [
+    "suggestive", "partial_nudity", "violence",
+  ],
+  REJECT_THRESHOLD: 0.70,
+  REVIEW_THRESHOLD: 0.40,
+  STRICT_TYPES: ["avatar", "project_image", "banner", "public_page_image"],
+  STRICT_REVIEW_THRESHOLD: 0.25,
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Classify an array of provider-returned labels against the moderation policy.
+ *
+ * @param {{ category: string, confidence: number }[]} labels
+ * @param {string} imageType - e.g. 'avatar', 'project_image', 'banner'
+ * @returns {{ decision: 'approved'|'rejected'|'needs_review', reason: string, labels: string[], score: number }}
+ */
+function classifyResponse(labels, imageType) {
+  if (!Array.isArray(labels) || labels.length === 0) {
+    return { decision: "approved", reason: "no_labels", labels: [], score: 0 };
+  }
+
+  const isStrict = MODERATION_POLICY.STRICT_TYPES.includes(imageType);
+  const reviewThreshold = isStrict
+    ? MODERATION_POLICY.STRICT_REVIEW_THRESHOLD
+    : MODERATION_POLICY.REVIEW_THRESHOLD;
+
+  let highestScore = 0;
+  const flaggedLabels = [];
+  let decision = "approved";
+  let reason = "clean";
+
+  for (const label of labels) {
+    const cat = label.category;
+    const conf = label.confidence;
+
+    if (conf > highestScore) highestScore = conf;
+
+    // --- Reject check ---
+    if (MODERATION_POLICY.REJECT_CATEGORIES.includes(cat)) {
+      if (conf >= MODERATION_POLICY.REJECT_THRESHOLD) {
+        decision = "rejected";
+        reason = "rejected_category:" + cat;
+        flaggedLabels.push(cat);
+        continue;
+      }
+      // Below reject threshold but above review threshold → needs_review
+      if (conf >= reviewThreshold) {
+        if (decision !== "rejected") {
+          decision = "needs_review";
+          reason = "review_category:" + cat;
+        }
+        flaggedLabels.push(cat);
+        continue;
+      }
+    }
+
+    // --- Review check ---
+    if (MODERATION_POLICY.REVIEW_CATEGORIES.includes(cat)) {
+      if (conf >= reviewThreshold) {
+        if (decision !== "rejected") {
+          decision = "needs_review";
+          reason = "review_category:" + cat;
+        }
+        flaggedLabels.push(cat);
+      }
+    }
+  }
+
+  return { decision, reason, labels: flaggedLabels, score: highestScore };
+}
+
+// ---------------------------------------------------------------------------
+// Backends
+// ---------------------------------------------------------------------------
+
+/** Auto-approves everything. Development and test use only. */
+class NoopBackend {
+  async moderate(_buffer, _imageType) {
+    return {
+      decision: "approved",
+      reason: "noop",
+      labels: [],
+      score: 0,
+      provider: "noop",
+    };
+  }
+}
+
+/**
+ * Wraps NoopBackend but logs a warning on every moderate() call.
+ * Used only when NODE_ENV === 'staging' and provider is 'noop'.
+ */
+class WarningNoopBackend {
+  constructor() {
+    this._inner = new NoopBackend();
+  }
+
+  async moderate(buffer, imageType) {
+    console.warn(
+      "[image-moderator] WARNING: Using noop moderation backend in staging. " +
+      "All images are auto-approved. Set IMAGE_MODERATION_PROVIDER before going to production.",
+    );
+    return this._inner.moderate(buffer, imageType);
+  }
+}
+
+/**
+ * Sends the image to an external moderation API endpoint.
+ * Placeholder implementation — wire to SightEngine, AWS Rekognition,
+ * or a custom endpoint by adapting parseProviderResponse().
+ */
+class ExternalApiBackend {
+  /**
+   * @param {{ apiKey: string, apiSecret: string, endpoint: string, timeoutMs: number }} opts
+   */
+  constructor({ apiKey, apiSecret, endpoint, timeoutMs }) {
+    if (!endpoint) {
+      throw new Error(
+        "IMAGE_MODERATION_ENDPOINT is required when using an external moderation provider.",
+      );
+    }
+    this._apiKey = apiKey || "";
+    this._apiSecret = apiSecret || "";
+    this._endpoint = endpoint;
+    this._timeoutMs = timeoutMs || 8000;
+  }
+
+  /**
+   * POST the image buffer to the configured endpoint and classify the result.
+   *
+   * @param {Buffer} buffer    - processed image bytes
+   * @param {string} imageType - e.g. 'avatar', 'project_image'
+   * @returns {Promise<{ decision: string, reason: string, labels: string[], score: number, provider: string }>}
+   */
+  async moderate(buffer, imageType) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this._timeoutMs);
+
+    try {
+      const base64Body = buffer.toString("base64");
+
+      const res = await fetch(this._endpoint, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": this._apiKey
+            ? "Bearer " + this._apiKey
+            : undefined,
+          "X-Api-Secret": this._apiSecret || undefined,
+        },
+        body: JSON.stringify({
+          image: base64Body,
+          image_type: imageType,
+        }),
+        signal: controller.signal,
+      });
+
+      if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        console.error(
+          "[image-moderator] Provider returned HTTP %d: %s",
+          res.status, text.slice(0, 200),
+        );
+        return {
+          decision: "needs_review",
+          reason: "provider_error",
+          labels: [],
+          score: 0,
+          provider: "external",
+        };
+      }
+
+      const json = await res.json();
+      const labels = this._parseProviderResponse(json);
+      const classification = classifyResponse(labels, imageType);
+
+      return {
+        ...classification,
+        provider: "external",
+      };
+    } catch (err) {
+      if (err.name === "AbortError") {
+        console.error(
+          "[image-moderator] Provider timed out after %dms",
+          this._timeoutMs,
+        );
+        return {
+          decision: "needs_review",
+          reason: "provider_timeout",
+          labels: [],
+          score: 0,
+          provider: "external",
+        };
+      }
+
+      console.error("[image-moderator] Provider error:", err.message);
+      return {
+        decision: "needs_review",
+        reason: "provider_error",
+        labels: [],
+        score: 0,
+        provider: "external",
+      };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  /**
+   * Map the raw provider JSON into a normalised label array.
+   *
+   * Adapt this method when wiring a specific service.
+   *
+   * Expected output: [{ category: string, confidence: number (0–1) }, ...]
+   *
+   * --- SightEngine example shape ---
+   * { nudity: { sexual_activity: 0.01, ... }, weapon: 0.02, ... }
+   *
+   * --- AWS Rekognition example shape ---
+   * { ModerationLabels: [{ Name: "Explicit Nudity", Confidence: 99.2 }, ...] }
+   *
+   * --- Generic / custom endpoint shape (what we expect by default) ---
+   * { labels: [{ category: "explicit_nudity", confidence: 0.95 }, ...] }
+   *
+   * @param {object} json
+   * @returns {{ category: string, confidence: number }[]}
+   */
+  _parseProviderResponse(json) {
+    // --- Generic / custom endpoint (default) ---------------------------------
+    if (Array.isArray(json.labels)) {
+      return json.labels.map((l) => ({
+        category: String(l.category || "").toLowerCase().replace(/\s+/g, "_"),
+        confidence: Number(l.confidence) || 0,
+      }));
+    }
+
+    // --- AWS Rekognition shape -----------------------------------------------
+    if (Array.isArray(json.ModerationLabels)) {
+      return json.ModerationLabels.map((l) => ({
+        category: String(l.Name || "").toLowerCase().replace(/\s+/g, "_"),
+        confidence: (Number(l.Confidence) || 0) / 100, // Rekognition uses 0–100
+      }));
+    }
+
+    // --- SightEngine shape (flat keys with sub-objects) ----------------------
+    // SightEngine returns top-level keys like "nudity", "weapon", "alcohol"
+    // each containing sub-scores. Flatten the highest sub-score per key.
+    if (typeof json === "object" && !json.labels && !json.ModerationLabels) {
+      const labels = [];
+      const skip = new Set(["status", "request", "media"]);
+      for (const [key, val] of Object.entries(json)) {
+        if (skip.has(key)) continue;
+        if (typeof val === "number") {
+          labels.push({ category: key, confidence: val });
+        } else if (typeof val === "object" && val !== null) {
+          // Take the highest sub-score within the category object
+          let maxConf = 0;
+          let maxSub = key;
+          for (const [sub, score] of Object.entries(val)) {
+            if (typeof score === "number" && score > maxConf) {
+              maxConf = score;
+              maxSub = key + "_" + sub;
+            }
+          }
+          if (maxConf > 0) {
+            labels.push({ category: maxSub, confidence: maxConf });
+          }
+        }
+      }
+      return labels;
+    }
+
+    return [];
+  }
+}
+
+/**
+ * SightEngine moderation backend.
+ * Calls https://api.sightengine.com/1.0/check.json
+ * Models: nudity2, offensive2, gore2, tobacco, recreational_drug, medical, weapon, text-content
+ */
+class SightEngineBackend {
+  constructor({ apiUser, apiSecret, timeoutMs }) {
+    if (!apiUser || !apiSecret) {
+      throw new Error("IMAGE_MODERATION_API_KEY (api_user) and IMAGE_MODERATION_API_SECRET are required for SightEngine.");
+    }
+    this._apiUser = apiUser;
+    this._apiSecret = apiSecret;
+    this._timeoutMs = timeoutMs || 8000;
+    this._endpoint = "https://api.sightengine.com/1.0/check.json";
+  }
+
+  async moderate(buffer, imageType) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this._timeoutMs);
+
+    try {
+      // SightEngine requires multipart/form-data with the image as a file under "media" key
+      const form = new FormData();
+      form.append("api_user", this._apiUser);
+      form.append("api_secret", this._apiSecret);
+      form.append("models", "nudity,offensive,gore,wad,weapon");
+      form.append("media", new Blob([buffer], { type: "image/webp" }), "image.webp");
+
+      const res = await fetch(this._endpoint, {
+        method: "POST",
+        body: form,
+        signal: controller.signal,
+      });
+
+      if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        console.error("[image-moderator] SightEngine HTTP %d: %s", res.status, text.slice(0, 1000));
+        return { decision: "needs_review", reason: "provider_error", labels: [], score: 0, provider: "sightengine" };
+      }
+
+      const json = await res.json();
+
+      if (json.status !== "success") {
+        console.error("[image-moderator] SightEngine error:", JSON.stringify(json).slice(0, 300));
+        return { decision: "needs_review", reason: "provider_error", labels: [], score: 0, provider: "sightengine" };
+      }
+
+      // Map SightEngine response to our normalized labels
+      const labels = this._parseSightEngineResponse(json);
+      const classification = classifyResponse(labels, imageType);
+
+      // DEBUG: log full response for tuning (remove after testing)
+      console.log("[image-moderator] SightEngine raw:", JSON.stringify(json).slice(0, 500));
+      console.log("[image-moderator] Parsed labels:", JSON.stringify(labels));
+      console.log("[image-moderator] Classification:", JSON.stringify(classification));
+
+      return { ...classification, provider: "sightengine" };
+    } catch (err) {
+      if (err.name === "AbortError") {
+        console.error("[image-moderator] SightEngine timed out after %dms", this._timeoutMs);
+        return { decision: "needs_review", reason: "provider_timeout", labels: [], score: 0, provider: "sightengine" };
+      }
+      console.error("[image-moderator] SightEngine error:", err.message);
+      return { decision: "needs_review", reason: "provider_error", labels: [], score: 0, provider: "sightengine" };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  /**
+   * Map SightEngine JSON to normalized labels.
+   * SightEngine response shape:
+   * {
+   *   nudity: { sexual_activity: 0.01, sexual_display: 0.02, erotica: 0.01, very_suggestive: 0.03, suggestive: 0.10, ... },
+   *   offensive: { prob: 0.02, ... },
+   *   gore: { prob: 0.01 },
+   *   weapon: 0.01,
+   *   tobacco: { prob: 0.00 },
+   *   recreational_drug: { prob: 0.00 },
+   *   ...
+   * }
+   */
+  _parseSightEngineResponse(json) {
+    const labels = [];
+
+    // Nudity — map SightEngine nudity scores to our categories
+    if (json.nudity) {
+      const n = json.nudity;
+      // v1 model fields: raw, safe, partial
+      if (n.raw != null && n.raw > 0.3) labels.push({ category: "explicit_nudity", confidence: n.raw });
+      if (n.partial != null && n.partial > 0.3) labels.push({ category: "partial_nudity", confidence: n.partial });
+      // v2 model fields (if available)
+      if (n.sexual_activity != null) labels.push({ category: "sexual_content", confidence: n.sexual_activity });
+      if (n.sexual_display != null) labels.push({ category: "explicit_nudity", confidence: n.sexual_display });
+      if (n.erotica != null) labels.push({ category: "pornography", confidence: n.erotica });
+      if (n.very_suggestive != null && n.very_suggestive > 0.3) labels.push({ category: "suggestive", confidence: n.very_suggestive });
+      if (n.suggestive != null && n.suggestive > 0.3) labels.push({ category: "suggestive", confidence: n.suggestive });
+      if (n.mildly_suggestive != null && n.mildly_suggestive > 0.5) labels.push({ category: "partial_nudity", confidence: n.mildly_suggestive });
+    }
+
+    // Offensive content
+    if (json.offensive) {
+      const prob = typeof json.offensive === "number" ? json.offensive : (json.offensive.prob || 0);
+      if (prob > 0.1) labels.push({ category: "offensive_gestures", confidence: prob });
+    }
+
+    // Gore
+    if (json.gore) {
+      const prob = typeof json.gore === "number" ? json.gore : (json.gore.prob || 0);
+      if (prob > 0.1) labels.push({ category: "graphic_gore", confidence: prob });
+    }
+
+    // Weapon
+    if (json.weapon != null) {
+      const prob = typeof json.weapon === "number" ? json.weapon : (json.weapon.prob || 0);
+      if (prob > 0.3) labels.push({ category: "violence", confidence: prob });
+    }
+
+    // Drugs
+    if (json.recreational_drug) {
+      const prob = typeof json.recreational_drug === "number" ? json.recreational_drug : (json.recreational_drug.prob || 0);
+      if (prob > 0.2) labels.push({ category: "drugs", confidence: prob });
+    }
+
+    // Tobacco
+    if (json.tobacco) {
+      const prob = typeof json.tobacco === "number" ? json.tobacco : (json.tobacco.prob || 0);
+      if (prob > 0.3) labels.push({ category: "drugs", confidence: prob });
+    }
+
+    return labels;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create the appropriate moderation backend based on environment variables.
+ *
+ * Environment variables consumed:
+ *   IMAGE_MODERATION_PROVIDER   — 'noop' (default in dev) or provider name
+ *   IMAGE_MODERATION_API_KEY    — API key for the external provider
+ *   IMAGE_MODERATION_API_SECRET — API secret for the external provider
+ *   IMAGE_MODERATION_ENDPOINT   — HTTP(S) URL for the external provider
+ *   IMAGE_MODERATION_TIMEOUT_MS — request timeout, default 8000
+ *
+ * @returns {NoopBackend | WarningNoopBackend | ExternalApiBackend}
+ */
+function createModerator() {
+  const provider = process.env.IMAGE_MODERATION_PROVIDER || "noop";
+  const nodeEnv = process.env.NODE_ENV || "development";
+
+  // --- Production safety gate (no override) ---------------------------------
+  if (nodeEnv === "production" && provider === "noop") {
+    throw new Error(
+      "FATAL: Image moderation provider is \"noop\" in production. " +
+      "Set IMAGE_MODERATION_PROVIDER to a real provider. There is no override.",
+    );
+  }
+
+  // --- Noop backends --------------------------------------------------------
+  if (provider === "noop") {
+    if (nodeEnv === "staging") {
+      return new WarningNoopBackend();
+    }
+    return new NoopBackend();
+  }
+
+  // --- SightEngine ----------------------------------------------------------
+  if (provider === "sightengine") {
+    return new SightEngineBackend({
+      apiUser: process.env.IMAGE_MODERATION_API_KEY,
+      apiSecret: process.env.IMAGE_MODERATION_API_SECRET,
+      timeoutMs: parseInt(process.env.IMAGE_MODERATION_TIMEOUT_MS || "8000", 10),
+    });
+  }
+
+  // --- Generic external provider --------------------------------------------
+  return new ExternalApiBackend({
+    apiKey: process.env.IMAGE_MODERATION_API_KEY,
+    apiSecret: process.env.IMAGE_MODERATION_API_SECRET,
+    endpoint: process.env.IMAGE_MODERATION_ENDPOINT,
+    timeoutMs: parseInt(process.env.IMAGE_MODERATION_TIMEOUT_MS || "8000", 10),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+module.exports = {
+  createModerator,
+  classifyResponse,
+  MODERATION_POLICY,
+  // Exported for testing / advanced usage
+  NoopBackend,
+  WarningNoopBackend,
+  ExternalApiBackend,
+  SightEngineBackend,
+};

package/image-processor.js

@@ -0,0 +1,160 @@
+"use strict";
+
+const sharp = require("sharp");
+const fileType = require("file-type");
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const ALLOWED_MIMES = new Set(["image/jpeg", "image/png", "image/webp"]);
+const MAX_FILE_SIZE = 5 * 1024 * 1024; // 5 MB decoded
+const MAX_DIMENSION = 4096;
+const MIN_DIMENSION = 32;
+const MAX_PIXEL_COUNT = 25_000_000; // 25 megapixels — decompression bomb guard
+const OUTPUT_QUALITY = 85;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Create an Error with a machine-readable `.code` property. */
+function codeErr(message, code) {
+  return Object.assign(new Error(message), { code });
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate magic bytes of a buffer.
+ * Returns detected MIME type or throws with a safe error message.
+ *
+ * @param {Buffer} buffer
+ * @returns {Promise<string>} detected MIME (e.g. "image/jpeg")
+ */
+async function validateMagicBytes(buffer) {
+  const result = await fileType.fromBuffer(buffer);
+  if (!result) {
+    throw codeErr("Unrecognized file format", "INVALID_FORMAT");
+  }
+  if (!ALLOWED_MIMES.has(result.mime)) {
+    throw codeErr("File type not allowed: " + result.mime, "DISALLOWED_MIME");
+  }
+  return result.mime;
+}
+
+/**
+ * Full validation and processing pipeline.
+ *
+ * 1. Size guard on raw input
+ * 2. Magic-byte validation (JPEG / PNG / WebP only)
+ * 3. Metadata read + decompression-bomb check (before full decode)
+ * 4. Strip ALL metadata (EXIF, GPS, ICC, XMP) — sharp does this by default
+ *    when re-encoding without calling `.withMetadata()`
+ * 5. Auto-orient based on EXIF rotation tag
+ * 6. Clamp dimensions to MAX_DIMENSION (preserving aspect ratio)
+ * 7. Re-encode to WebP
+ *
+ * @param {Buffer} buffer   - raw image bytes (decoded from base64)
+ * @param {string} imageType - e.g. 'avatar', 'project_image', 'banner', 'public_page_image'
+ * @returns {Promise<{
+ *   processed: Buffer,
+ *   width: number,
+ *   height: number,
+ *   detectedMime: string,
+ *   originalSize: number,
+ *   processedSize: number
+ * }>}
+ */
+async function validateAndProcess(buffer, imageType) {
+  // ---- 1. Basic input guard ------------------------------------------------
+  if (!Buffer.isBuffer(buffer) || buffer.length === 0) {
+    throw codeErr("Empty or invalid image data", "EMPTY_INPUT");
+  }
+  if (buffer.length > MAX_FILE_SIZE) {
+    throw codeErr(
+      "Image exceeds maximum size of " + (MAX_FILE_SIZE / 1024 / 1024) + "MB",
+      "TOO_LARGE",
+    );
+  }
+
+  // ---- 2. Magic-byte validation --------------------------------------------
+  const detectedMime = await validateMagicBytes(buffer);
+
+  // ---- 3. Metadata pre-check (before full pixel decode) --------------------
+  let metadata;
+  try {
+    metadata = await sharp(buffer).metadata();
+  } catch (_err) {
+    throw codeErr("Unable to read image — file may be corrupted", "CORRUPT_IMAGE");
+  }
+
+  const { width: origW, height: origH } = metadata;
+  if (!origW || !origH) {
+    throw codeErr("Unable to determine image dimensions", "NO_DIMENSIONS");
+  }
+
+  // Decompression bomb check
+  if (origW * origH > MAX_PIXEL_COUNT) {
+    throw codeErr(
+      "Image dimensions too large (max " + MAX_PIXEL_COUNT.toLocaleString() + " pixels)",
+      "DECOMPRESSION_BOMB",
+    );
+  }
+
+  // Minimum dimension check
+  if (origW < MIN_DIMENSION || origH < MIN_DIMENSION) {
+    throw codeErr(
+      "Image too small (minimum " + MIN_DIMENSION + "x" + MIN_DIMENSION + ")",
+      "TOO_SMALL",
+    );
+  }
+
+  // ---- 4-7. Process --------------------------------------------------------
+  // sharp strips ALL metadata (EXIF, ICC, XMP, GPS) by default when
+  // re-encoding — we intentionally do NOT call .withMetadata() so nothing
+  // is carried over from the original.
+  let pipeline = sharp(buffer).rotate(); // auto-orient via EXIF, then discard it
+
+  // Clamp oversized images (fit inside MAX_DIMENSION box, never enlarge)
+  if (origW > MAX_DIMENSION || origH > MAX_DIMENSION) {
+    pipeline = pipeline.resize(MAX_DIMENSION, MAX_DIMENSION, {
+      fit: "inside",
+      withoutEnlargement: true,
+    });
+  }
+
+  // Re-encode to WebP
+  let processed;
+  try {
+    processed = await pipeline
+      .webp({ quality: OUTPUT_QUALITY, effort: 4 })
+      .toBuffer({ resolveWithObject: true });
+  } catch (_err) {
+    throw codeErr("Failed to process image", "PROCESS_FAILED");
+  }
+
+  return {
+    processed: processed.data,
+    width: processed.info.width,
+    height: processed.info.height,
+    detectedMime,
+    originalSize: buffer.length,
+    processedSize: processed.data.length,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+module.exports = {
+  validateAndProcess,
+  validateMagicBytes,
+  ALLOWED_MIMES,
+  MAX_FILE_SIZE,
+  MAX_DIMENSION,
+  MIN_DIMENSION,
+  MAX_PIXEL_COUNT,
+  OUTPUT_QUALITY,
+};