@privacyscrubber/sdk 2.2.2 → 2.2.3

package/vision.d.ts

@@ -0,0 +1,56 @@
+/**
+ * TypeScript Definitions for @privacyscrubber/sdk/vision
+ */
+
+export interface ExifStripResult {
+    /** The sanitized binary buffer without EXIF/XMP/IPTC/GPS metadata. */
+    cleanBuffer: Uint8Array | Buffer;
+    /** Whether any metadata segment was found and stripped. */
+    metadataStripped: boolean;
+    /** Image format detected: 'jpeg' | 'png' | 'webp' | 'unknown'. */
+    format: string;
+    /** Array of removed segment identifiers. */
+    removedSegments: string[];
+    /** Number of bytes saved by removing metadata. */
+    bytesSaved: number;
+}
+
+export interface VisionBoundingBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    label?: string;
+}
+
+export interface VisionRedactOptions {
+    /** Fill color for blackout box (Default: '#000000'). */
+    fillColor?: string;
+    /** Border color (Default: 'rgba(0, 240, 255, 0.4)'). */
+    borderColor?: string;
+    /** Whether to render token label badges (Default: true). */
+    showLabels?: boolean;
+}
+
+/**
+ * Strips EXIF, XMP, GPS, and sensitive metadata chunks from image buffers (JPEG, PNG, WebP).
+ */
+export function stripExifMetadata(inputBuffer: Buffer | Uint8Array): ExifStripResult;
+
+/**
+ * Redacts bounding boxes on an HTML Canvas or 2D Canvas context.
+ */
+export function redactImageBoundingBoxes(
+    canvasOrCtx: any,
+    boxes?: VisionBoundingBox[],
+    options?: VisionRedactOptions
+): number;
+
+/**
+ * Generates an air-gapped SVG redaction mask overlay for headless environments.
+ */
+export function generateSvgRedactionOverlay(
+    dimensions?: { width: number; height: number },
+    boxes?: VisionBoundingBox[],
+    options?: VisionRedactOptions
+): string;

package/vision.js

@@ -0,0 +1,362 @@
+/**
+ * PrivacyScrubber Developer SDK — Multimodal Vision Submodule (@privacyscrubber/sdk/vision)
+ * 
+ * Sub-millisecond in-memory binary metadata sanitization & bounding box redaction.
+ * Zero external dependencies. Zero network calls. 100% local RAM execution.
+ * 
+ * https://privacyscrubber.com/features/developer-sdk/
+ */
+
+/**
+ * Strips EXIF, XMP, GPS, and sensitive metadata chunks from image buffers (JPEG, PNG, WebP).
+ * Operates purely in-memory on typed arrays with sub-millisecond execution.
+ * 
+ * @param {Buffer|Uint8Array} inputBuffer - Raw image buffer
+ * @returns {{ cleanBuffer: Uint8Array|Buffer, metadataStripped: boolean, format: string, removedSegments: string[], bytesSaved: number }}
+ */
+export function stripExifMetadata(inputBuffer) {
+  if (!inputBuffer || inputBuffer.length < 8) {
+    return {
+      cleanBuffer: inputBuffer,
+      metadataStripped: false,
+      format: 'unknown',
+      removedSegments: [],
+      bytesSaved: 0
+    };
+  }
+
+  const u8 = inputBuffer instanceof Uint8Array ? inputBuffer : new Uint8Array(inputBuffer);
+  const originalSize = u8.length;
+  const removedSegments = [];
+
+  // 1. JPEG Detection & Stripping (SOI: 0xFF, 0xD8)
+  if (u8[0] === 0xFF && u8[1] === 0xD8) {
+    const chunks = [];
+    chunks.push(new Uint8Array([0xFF, 0xD8])); // Keep SOI
+    let offset = 2;
+    let stripped = false;
+
+    while (offset < u8.length - 1) {
+      if (u8[offset] !== 0xFF) {
+        // Stray byte or corrupted segment, push rest and break
+        chunks.push(u8.subarray(offset));
+        break;
+      }
+
+      const marker = u8[offset + 1];
+
+      // Standalone markers without length: RST0-RST7 (0xD0-0xD7), SOI (0xD8), EOI (0xD9)
+      if (marker === 0xD9) { // EOI
+        chunks.push(new Uint8Array([0xFF, 0xD9]));
+        break;
+      }
+      if (marker === 0x00 || (marker >= 0xD0 && marker <= 0xD7)) {
+        chunks.push(new Uint8Array([0xFF, marker]));
+        offset += 2;
+        continue;
+      }
+
+      // Check boundary for 16-bit big-endian length
+      if (offset + 3 >= u8.length) {
+        chunks.push(u8.subarray(offset));
+        break;
+      }
+
+      const length = (u8[offset + 2] << 8) | u8[offset + 3];
+      const segmentEnd = offset + 2 + length;
+      if (segmentEnd > u8.length) {
+        chunks.push(u8.subarray(offset));
+        break;
+      }
+
+      // Markers to strip:
+      // 0xE1 = APP1 (EXIF, XMP)
+      // 0xED = APP13 (Photoshop IRB, IPTC)
+      // 0xFE = COM (Comment)
+      const isExif = marker === 0xE1;
+      const isIptc = marker === 0xED;
+      const isComment = marker === 0xFE;
+
+      if (isExif || isIptc || isComment) {
+        stripped = true;
+        const segmentName = isExif ? 'APP1 (Exif/XMP)' : isIptc ? 'APP13 (IPTC)' : 'COM (Comment)';
+        removedSegments.push(segmentName);
+        offset = segmentEnd;
+      } else if (marker === 0xDA) { // SOS (Start of Scan) - compressed bitstream follows until EOI
+        chunks.push(u8.subarray(offset));
+        break;
+      } else {
+        // Keep segment (e.g. SOF, DHT, DQT, APP0 JFIF, etc.)
+        chunks.push(u8.subarray(offset, segmentEnd));
+        offset = segmentEnd;
+      }
+    }
+
+    if (stripped) {
+      let totalLen = 0;
+      for (const c of chunks) totalLen += c.length;
+      const clean = new Uint8Array(totalLen);
+      let cur = 0;
+      for (const c of chunks) {
+        clean.set(c, cur);
+        cur += c.length;
+      }
+      const isBuffer = typeof Buffer !== 'undefined' && Buffer.isBuffer(inputBuffer);
+      return {
+        cleanBuffer: isBuffer ? Buffer.from(clean.buffer, clean.byteOffset, clean.byteLength) : clean,
+        metadataStripped: true,
+        format: 'jpeg',
+        removedSegments,
+        bytesSaved: originalSize - totalLen
+      };
+    }
+
+    return {
+      cleanBuffer: inputBuffer,
+      metadataStripped: false,
+      format: 'jpeg',
+      removedSegments: [],
+      bytesSaved: 0
+    };
+  }
+
+  // 2. PNG Detection & Stripping (\x89PNG\r\n\x1a\n)
+  if (u8[0] === 0x89 && u8[1] === 0x50 && u8[2] === 0x4E && u8[3] === 0x47 &&
+      u8[4] === 0x0D && u8[5] === 0x0A && u8[6] === 0x1A && u8[7] === 0x0A) {
+    const chunks = [];
+    chunks.push(u8.subarray(0, 8)); // Keep 8-byte PNG header
+    let offset = 8;
+    let stripped = false;
+
+    // Ancillary chunk types to strip: eXIf, tEXt, zTXt, iTXt, tIME, pHYs
+    const ANCILLARY_TYPES = new Set(['eXIf', 'tEXt', 'zTXt', 'iTXt', 'tIME', 'pHYs']);
+
+    while (offset + 8 <= u8.length) {
+      const length = (u8[offset] << 24) | (u8[offset + 1] << 16) | (u8[offset + 2] << 8) | u8[offset + 3];
+      const type = String.fromCharCode(u8[offset + 4], u8[offset + 5], u8[offset + 6], u8[offset + 7]);
+      const chunkTotalLen = 12 + length; // 4 len + 4 type + data + 4 crc
+
+      if (offset + chunkTotalLen > u8.length) {
+        chunks.push(u8.subarray(offset));
+        break;
+      }
+
+      if (ANCILLARY_TYPES.has(type)) {
+        stripped = true;
+        removedSegments.push(`PNG_${type}`);
+        offset += chunkTotalLen;
+      } else {
+        chunks.push(u8.subarray(offset, offset + chunkTotalLen));
+        offset += chunkTotalLen;
+        if (type === 'IEND') break;
+      }
+    }
+
+    if (stripped) {
+      let totalLen = 0;
+      for (const c of chunks) totalLen += c.length;
+      const clean = new Uint8Array(totalLen);
+      let cur = 0;
+      for (const c of chunks) {
+        clean.set(c, cur);
+        cur += c.length;
+      }
+      const isBuffer = typeof Buffer !== 'undefined' && Buffer.isBuffer(inputBuffer);
+      return {
+        cleanBuffer: isBuffer ? Buffer.from(clean.buffer, clean.byteOffset, clean.byteLength) : clean,
+        metadataStripped: true,
+        format: 'png',
+        removedSegments,
+        bytesSaved: originalSize - totalLen
+      };
+    }
+
+    return {
+      cleanBuffer: inputBuffer,
+      metadataStripped: false,
+      format: 'png',
+      removedSegments: [],
+      bytesSaved: 0
+    };
+  }
+
+  // 3. WebP Detection & Stripping (RIFF....WEBP)
+  if (u8[0] === 0x52 && u8[1] === 0x49 && u8[2] === 0x46 && u8[3] === 0x46 &&
+      u8[8] === 0x57 && u8[9] === 0x45 && u8[10] === 0x42 && u8[11] === 0x50) {
+    const chunks = [];
+    chunks.push(u8.subarray(0, 12)); // Keep RIFF header (length will be patched)
+    let offset = 12;
+    let stripped = false;
+
+    while (offset + 8 <= u8.length) {
+      const fourCC = String.fromCharCode(u8[offset], u8[offset + 1], u8[offset + 2], u8[offset + 3]);
+      const chunkSize = u8[offset + 4] | (u8[offset + 5] << 8) | (u8[offset + 6] << 16) | (u8[offset + 7] << 24);
+      const paddedSize = chunkSize + (chunkSize % 2); // WebP chunks are 2-byte aligned
+      const totalChunkSize = 8 + paddedSize;
+
+      if (offset + totalChunkSize > u8.length) {
+        chunks.push(u8.subarray(offset));
+        break;
+      }
+
+      if (fourCC === 'EXIF' || fourCC === 'XMP ') {
+        stripped = true;
+        removedSegments.push(`WEBP_${fourCC.trim()}`);
+        offset += totalChunkSize;
+      } else {
+        chunks.push(u8.subarray(offset, offset + totalChunkSize));
+        offset += totalChunkSize;
+      }
+    }
+
+    if (stripped) {
+      let totalLen = 0;
+      for (const c of chunks) totalLen += c.length;
+      const clean = new Uint8Array(totalLen);
+      let cur = 0;
+      for (const c of chunks) {
+        clean.set(c, cur);
+        cur += c.length;
+      }
+      // Patch RIFF file size (totalLen - 8) in little-endian at bytes 4..7
+      const newRiffSize = totalLen - 8;
+      clean[4] = newRiffSize & 0xFF;
+      clean[5] = (newRiffSize >> 8) & 0xFF;
+      clean[6] = (newRiffSize >> 16) & 0xFF;
+      clean[7] = (newRiffSize >> 24) & 0xFF;
+
+      const isBuffer = typeof Buffer !== 'undefined' && Buffer.isBuffer(inputBuffer);
+      return {
+        cleanBuffer: isBuffer ? Buffer.from(clean.buffer, clean.byteOffset, clean.byteLength) : clean,
+        metadataStripped: true,
+        format: 'webp',
+        removedSegments,
+        bytesSaved: originalSize - totalLen
+      };
+    }
+
+    return {
+      cleanBuffer: inputBuffer,
+      metadataStripped: false,
+      format: 'webp',
+      removedSegments: [],
+      bytesSaved: 0
+    };
+  }
+
+  // Unsupported or raw format
+  return {
+    cleanBuffer: inputBuffer,
+    metadataStripped: false,
+    format: 'unknown',
+    removedSegments: [],
+    bytesSaved: 0
+  };
+}
+
+/**
+ * Redacts bounding boxes on an HTML Canvas or 2D Canvas context.
+ * Solid blackouts or placeholder privacy badges are drawn directly in memory.
+ * 
+ * @param {HTMLCanvasElement|CanvasRenderingContext2D} canvasOrCtx
+ * @param {Array<{x: number, y: number, width: number, height: number, label?: string}>} boxes
+ * @param {Object} [options]
+ * @param {string} [options.fillColor='#000000'] - Fill color for the redaction box
+ * @param {string} [options.borderColor='#00f0ff'] - Border highlight color
+ * @param {boolean} [options.showLabels=true] - Whether to render synthetic token label badges
+ * @returns {number} Count of redacted boxes
+ */
+export function redactImageBoundingBoxes(canvasOrCtx, boxes = [], options = {}) {
+  if (!canvasOrCtx || !Array.isArray(boxes) || boxes.length === 0) return 0;
+
+  const ctx = typeof canvasOrCtx.getContext === 'function' 
+    ? canvasOrCtx.getContext('2d') 
+    : canvasOrCtx;
+
+  if (!ctx || typeof ctx.fillRect !== 'function') return 0;
+
+  const fillColor = options.fillColor || '#000000';
+  const borderColor = options.borderColor || 'rgba(0, 240, 255, 0.4)';
+  const showLabels = options.showLabels !== false;
+
+  ctx.save();
+
+  let count = 0;
+  for (const box of boxes) {
+    if (typeof box.x !== 'number' || typeof box.y !== 'number' || 
+        typeof box.width !== 'number' || typeof box.height !== 'number') {
+      continue;
+    }
+
+    // 1. Draw solid blackout box
+    ctx.fillStyle = fillColor;
+    ctx.fillRect(box.x, box.y, box.width, box.height);
+
+    // 2. Draw subtle border
+    ctx.strokeStyle = borderColor;
+    ctx.lineWidth = 1.5;
+    ctx.strokeRect(box.x, box.y, box.width, box.height);
+
+    // 3. Render token label badge if provided
+    if (showLabels && box.label) {
+      const labelText = String(box.label);
+      ctx.font = 'bold 11px monospace';
+      const textMetrics = ctx.measureText(labelText);
+      const badgeWidth = textMetrics.width + 10;
+      const badgeHeight = 16;
+      const badgeX = box.x + 2;
+      const badgeY = box.y + 2;
+
+      ctx.fillStyle = 'rgba(10, 15, 29, 0.85)';
+      ctx.fillRect(badgeX, badgeY, badgeWidth, badgeHeight);
+
+      ctx.fillStyle = '#00f0ff';
+      ctx.fillText(labelText, badgeX + 5, badgeY + 12);
+    }
+
+    count++;
+  }
+
+  ctx.restore();
+  return count;
+}
+
+/**
+ * Generates an air-gapped SVG redaction mask overlay for headless environments.
+ * 
+ * @param {{ width: number, height: number }} dimensions
+ * @param {Array<{x: number, y: number, width: number, height: number, label?: string}>} boxes
+ * @param {Object} [options]
+ * @returns {string} Standalone SVG markup
+ */
+export function generateSvgRedactionOverlay(dimensions = { width: 800, height: 600 }, boxes = [], options = {}) {
+  const width = dimensions.width || 800;
+  const height = dimensions.height || 600;
+  const fillColor = options.fillColor || '#000000';
+  const strokeColor = options.borderColor || '#00f0ff';
+
+  const rects = (boxes || []).map((b, idx) => {
+    const label = b.label ? `<text x="${b.x + 5}" y="${b.y + 14}" font-family="monospace" font-size="11" font-weight="bold" fill="#00f0ff">${escapeXml(b.label)}</text>` : '';
+    return `
+    <g class="ps-vision-mask" id="mask-${idx}">
+      <rect x="${b.x}" y="${b.y}" width="${b.width}" height="${b.height}" fill="${fillColor}" stroke="${strokeColor}" stroke-width="1.5" />
+      ${label}
+    </g>`;
+  }).join('');
+
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${width} ${height}" width="${width}" height="${height}">
+  ${rects}
+</svg>`;
+}
+
+function escapeXml(unsafe) {
+  return String(unsafe).replace(/[<>&'"]/g, c => {
+    switch (c) {
+      case '<': return '&lt;';
+      case '>': return '&gt;';
+      case '&': return '&amp;';
+      case '\'': return '&apos;';
+      case '"': return '&quot;';
+    }
+  });
+}