metaclean 1.0.2

data/lib/metaclean/exiftool.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+# ───────────────────────────────────────────────────────────────────────────
+# A thin Ruby wrapper around the external `exiftool` binary.
+#
+# We use `Open3.capture3` instead of backticks or `system()` because:
+#   1. It returns stdout, stderr, and the process status separately.
+#   2. When called with multiple arguments, it bypasses the shell entirely
+#      — so a filename like `cat; rm -rf /` is treated as ONE filename, not
+#      a shell command. This is the standard way to safely shell out in Ruby.
+# ───────────────────────────────────────────────────────────────────────────
+
+require 'open3'
+require 'json'
+
+module Metaclean
+  # `module Exiftool` (vs `class`) because we want module-level methods like
+  # `Exiftool.read(path)` — there's no state to carry per instance.
+  module Exiftool
+    # `module_function` makes every method below act like a "static" method
+    # on the module *and* a private instance method (rarely used). It saves
+    # writing `def self.read` for every method.
+    module_function
+
+    # Returns true if `exiftool` is on PATH. The result is memoized in `@available`
+    # so repeated checks don't re-spawn the process.
+    #
+    # `defined?(@available)` is safer than `@available.nil?` because the
+    # cached value could legitimately be `false` — we want to skip the
+    # re-check in that case too.
+    def available?
+      return @available if defined?(@available)
+
+      _out, _err, status = Open3.capture3('exiftool', '-ver')
+      @available = status.success?
+    rescue Errno::ENOENT
+      # `Errno::ENOENT` ("no such file or directory") is what Open3 raises
+      # when the executable can't be found. We treat that as "not available".
+      @available = false
+    end
+
+    # Returns the version string, or nil if exiftool is missing/broken.
+    def version
+      return nil unless available?
+
+      out, _err, status = Open3.capture3('exiftool', '-ver')
+      status.success? ? out.strip : nil
+    rescue Errno::ENOENT
+      nil
+    end
+
+    # Hard-fail with a helpful install hint. Called from `read`/`strip!` before
+    # any work, so users see one clear message instead of a low-level Errno.
+    # The `<<~MSG ... MSG` is a "squiggly heredoc": leading indentation is
+    # stripped automatically, so the output is left-aligned.
+    def ensure_available!
+      return if available?
+
+      raise ExiftoolMissing, <<~MSG
+        ExifTool is not installed or not on PATH.
+
+        Install:
+          macOS:    brew install exiftool
+          Debian:   sudo apt install libimage-exiftool-perl
+          Fedora:   sudo dnf install perl-Image-ExifTool
+          Arch:     sudo pacman -S perl-image-exiftool
+          Windows:  scoop install exiftool   (or download exiftool.org)
+      MSG
+    end
+
+    # Reads metadata from a file and returns a flat Hash of "Group:Tag" => value.
+    #
+    # ExifTool flag glossary:
+    #   -j         JSON output (machine-parseable)
+    #   -G1        Include the family-1 group name (e.g. "EXIF", "GPS", "IPTC")
+    #   -a         Allow duplicate tags (some formats have several with same name)
+    #   -u         Include unknown/unidentified tags
+    #   -s         Short tag names (no descriptions)
+    #   -n         Numeric values (no human formatting like "1/100 sec")
+    #   -api largefilesupport=1   Allow files >4 GB
+    def read(path)
+      ensure_available!
+      out, err, status = Open3.capture3(
+        'exiftool', '-j', '-G1', '-a', '-u', '-s', '-n', '-api', 'largefilesupport=1', path.to_s
+      )
+      raise Error, "ExifTool read failed: #{err.strip}" unless status.success?
+
+      # ExifTool's JSON output is an array (one entry per file). We always
+      # pass one file, so we take the first element. `|| {}` handles the
+      # edge case where exiftool returns an empty array.
+      data = JSON.parse(out)
+      data.first || {}
+    rescue JSON::ParserError => e
+      raise Error, "Could not parse ExifTool output: #{e.message}"
+    end
+
+    # Removes every removable tag, in place. Returns true on success.
+    #
+    # `-all=` is the magic incantation: it sets every tag to nothing (= empty),
+    # which deletes them. `-overwrite_original` makes ExifTool replace the
+    # file directly instead of writing `file_original` next to it.
+    #
+    # The optional `keep_*` flags are useful because:
+    #   * Orientation tells viewers how to rotate phone photos. Removing it
+    #     can show the picture sideways.
+    #   * ICC profile tells viewers which color space the image is in.
+    #     Removing it can shift colors.
+    def strip!(path, keep_orientation: false, keep_color_profile: false)
+      ensure_available!
+
+      preserving = keep_orientation || keep_color_profile
+      args = ['exiftool', '-all=']
+
+      # `-tagsFromFile @` says "copy tags from the same file you're writing
+      # to". That sounds redundant, but combined with `-all=` running first,
+      # it means "delete everything, then re-add only the listed tags".
+      if preserving
+        args.concat(['-tagsFromFile', '@'])
+        args << '-Orientation' if keep_orientation
+        args << '-ICC_Profile' if keep_color_profile
+      end
+      args.concat(['-overwrite_original', '-q', '-q', '-api', 'largefilesupport=1', path.to_s])
+
+      _out, err, status = Open3.capture3(*args)
+      return true if status.success?
+
+      # Some minimal/odd files reject the preserve-pass. Fall back to a plain
+      # full strip — but only if we *were* preserving, otherwise the retry
+      # would be identical to the failed attempt.
+      raise Error, "ExifTool strip failed: #{err.strip}" unless preserving
+
+      _out2, err2, status2 = Open3.capture3(
+        'exiftool', '-all=', '-overwrite_original', '-q', '-q', path.to_s
+      )
+      return true if status2.success?
+
+      raise Error, "ExifTool strip failed: #{err2.strip.empty? ? err.strip : err2.strip}"
+    end
+  end
+end

data/lib/metaclean/mat2.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+# ───────────────────────────────────────────────────────────────────────────
+# Wrapper around the external `mat2` (Metadata Anonymisation Toolkit 2).
+#
+# mat2 is stricter than ExifTool on certain formats (DOCX/PDF/PNG): instead
+# of blacklisting known tags, it rebuilds the file from scratch keeping only
+# the bytes it understands. The trade-off is that mat2 supports fewer formats.
+#
+# mat2's CLI quirk: it does NOT overwrite the original. It writes a new file
+# named `<name>.cleaned.<ext>` next to it. We adapt by renaming that result
+# back over the source after a successful run.
+# ───────────────────────────────────────────────────────────────────────────
+
+require 'open3'
+require 'fileutils'
+
+module Metaclean
+  module Mat2
+    # File extensions we know mat2 can handle. Keep this list conservative —
+    # if mat2 doesn't actually support an extension, the call will fail
+    # gracefully via UNSUPPORTED_RE below, but we'd rather not even try.
+    SUPPORTED_EXTS = %w[
+      pdf png jpg jpeg tif tiff gif bmp svg webp
+      mp3 flac ogg opus wav m4a
+      mp4 avi mkv mov wmv webm
+      docx xlsx pptx odt ods odp odg odf epub
+      zip torrent
+    ].freeze
+
+    # Regex matching the messages mat2 prints when it can't handle a file.
+    # We use this to distinguish "soft skip" from a real error.
+    # `i` flag = case-insensitive.
+    UNSUPPORTED_RE = /(not supported|isn't supported|cannot be cleaned|unsupported file)/i.freeze
+
+    module_function
+
+    # Memoized PATH check (same pattern as Exiftool.available?).
+    def available?
+      return @available if defined?(@available)
+
+      _out, _err, status = Open3.capture3('mat2', '--version')
+      @available = status.success?
+    rescue Errno::ENOENT
+      @available = false
+    end
+
+    def version
+      return nil unless available?
+
+      out, _err, status = Open3.capture3('mat2', '--version')
+      # `mat2 --version` prints "mat2 0.14.0" — `.split.last` grabs the
+      # version number regardless of whatever prefix appears.
+      status.success? ? out.strip.split.last : nil
+    rescue Errno::ENOENT
+      nil
+    end
+
+    # Quick check before we even try mat2 on a file. Used by Strategy to
+    # decide whether to add :mat2 to the pipeline.
+    def supports?(path)
+      return false unless available?
+
+      SUPPORTED_EXTS.include?(File.extname(path).downcase.delete('.'))
+    end
+
+    # Strips metadata from `path` in place. Returns:
+    #   true           — stripped successfully
+    #   :no_metadata   — mat2 ran but found nothing to strip
+    #   :unsupported   — mat2 cannot handle this file type
+    # Raises Metaclean::Error on hard failure.
+    #
+    # We return symbols (instead of always raising) so the runner can show a
+    # friendly "skipped" message and continue with the next tool.
+    def strip!(path)
+      raise Error, 'mat2 not available' unless available?
+
+      cleaned = cleaned_path_for(path)
+
+      # Defensive: if a stale `<name>.cleaned.<ext>` exists from an earlier
+      # crashed run, remove it so we don't accidentally use old data.
+      File.delete(cleaned) if File.exist?(cleaned)
+
+      out, err, status = Open3.capture3('mat2', path.to_s)
+      combined = "#{out}\n#{err}"
+
+      # Soft skip — mat2 itself told us it can't process this file.
+      # Defensive: if mat2 still wrote a partial `<name>.cleaned.<ext>`,
+      # remove it so a later run doesn't pick up stale output.
+      if combined.match?(UNSUPPORTED_RE)
+        File.delete(cleaned) if File.exist?(cleaned)
+        return :unsupported
+      end
+
+      unless status.success?
+        File.delete(cleaned) if File.exist?(cleaned)
+        # `err.strip.empty? ? out.strip : err.strip` picks whichever stream
+        # has actual content — some tools log to stdout, others to stderr.
+        raise Error, "mat2 failed: #{err.strip.empty? ? out.strip : err.strip}"
+      end
+
+      # mat2 only creates `<name>.cleaned.<ext>` when it actually stripped
+      # something. If the file didn't exist after a successful run, there
+      # was nothing to remove.
+      if File.exist?(cleaned)
+        FileUtils.mv(cleaned, path.to_s)
+        true
+      else
+        :no_metadata
+      end
+    end
+
+    # Builds the path mat2 will write to: `name.cleaned.ext`.
+    # We use File.dirname/basename/join instead of string concatenation so
+    # this works on Windows (\ separator) too.
+    def cleaned_path_for(path)
+      dir  = File.dirname(path)
+      ext  = File.extname(path)
+      stem = File.basename(path, ext)
+      File.join(dir, "#{stem}.cleaned#{ext}")
+    end
+  end
+end

data/lib/metaclean/qpdf.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+# ───────────────────────────────────────────────────────────────────────────
+# Wrapper around `qpdf` — a PDF structural cleaner.
+#
+# Why qpdf in addition to mat2/ExifTool? PDFs can carry metadata in places
+# those two don't always reach: orphaned objects, unused image streams,
+# old revisions kept in the file. qpdf rebuilds the PDF from scratch using
+# only the objects actually referenced by the document. That's a great
+# final pass after the other tools have stripped the obvious metadata.
+# ───────────────────────────────────────────────────────────────────────────
+
+require 'open3'
+require 'fileutils'
+
+module Metaclean
+  module Qpdf
+    module_function
+
+    def available?
+      return @available if defined?(@available)
+
+      _out, _err, status = Open3.capture3('qpdf', '--version')
+      @available = status.success?
+    rescue Errno::ENOENT
+      @available = false
+    end
+
+    def version
+      return nil unless available?
+
+      out, _err, status = Open3.capture3('qpdf', '--version')
+      # `qpdf --version` prints multiple lines starting with the version line.
+      # `.lines.first` grabs only that line.
+      status.success? ? out.lines.first.to_s.strip : nil
+    rescue Errno::ENOENT
+      nil
+    end
+
+    # Rebuilds a PDF in place. The qpdf flags here:
+    #   --linearize                          → optimize for streaming/web
+    #   --object-streams=generate            → bundle objects efficiently
+    #   --remove-unreferenced-resources=yes  → drop unused content (the
+    #                                           privacy-relevant part!)
+    #
+    # qpdf can't write back to the same file, so we use the standard
+    # "atomic write" pattern: write to a temp file, then rename it on top of
+    # the original. `File.rename` (used internally by `FileUtils.mv` for
+    # same-filesystem moves) is atomic on POSIX — either the swap completes
+    # or nothing changes. No "half-written" state is ever visible.
+    def rebuild!(path)
+      raise Error, 'qpdf not available' unless available?
+
+      # Including `Process.pid` in the temp name avoids collisions if two
+      # metaclean processes happen to run at the same time on shared storage.
+      tmp = "#{path}.qpdf.tmp.#{Process.pid}"
+
+      _out, err, status = Open3.capture3(
+        'qpdf', '--linearize', '--object-streams=generate',
+        '--remove-unreferenced-resources=yes', path.to_s, tmp
+      )
+
+      # qpdf has a quirk: exit code 3 means "succeeded with warnings" (output
+      # is still produced and valid). We treat that the same as success.
+      success = status.success? || status.exitstatus == 3
+      unless success
+        File.delete(tmp) if File.exist?(tmp)
+        raise Error, "qpdf failed: #{err.strip}"
+      end
+
+      FileUtils.mv(tmp, path.to_s)
+      true
+    end
+  end
+end