metaclean 4.1.0 → 4.3.0

data/lib/metaclean/ffmpeg.rb

@@ -1,34 +1,30 @@
 # frozen_string_literal: true
 
-# Wrapper around the external `ffmpeg` binary.
-#
-# ffmpeg is used for ONE job the other tools can't do: the Matroska containers
-# (mkv/webm). ExifTool is read-only for Matroska, and mat2 has no Matroska
-# parser, so without ffmpeg those formats can't be cleaned at all. ffmpeg
-# rewrites the container while copying every stream verbatim (`-c copy`) — no
-# re-encode, so the audio/video is bit-identical and only the metadata is gone.
-#
-# Like mat2, ffmpeg can't edit in place: it muxes to a new file. We write to a
-# SecureRandom-named sibling and move it back over the source on success.
-
-require 'open3'
-require 'fileutils'
-require 'securerandom'
+require 'json'
 
 module Metaclean
   module Ffmpeg
+    NESTED_IMAGE_CODECS = %w[bmp gif mjpeg mjpegb png tiff webp].freeze
+
     module_function
 
-    # Memoized PATH check (same pattern as the other wrappers).
     def available?
       return @available if defined?(@available)
 
-      out, _err, status = Open3.capture3('ffmpeg', '-version')
-      @available = status.success?
-      # First line is "ffmpeg version 7.1.1 Copyright ..."; grab the 3rd token.
+      out, _err, status = Metaclean.capture3(
+        'ffmpeg', '-version',
+        timeout: Metaclean::PROBE_TIMEOUT,
+        max_output: Metaclean::PROBE_MAX_OUTPUT_BYTES
+      )
+      _probe_out, _probe_err, probe_status = Metaclean.capture3(
+        'ffprobe', '-version',
+        timeout: Metaclean::PROBE_TIMEOUT,
+        max_output: Metaclean::PROBE_MAX_OUTPUT_BYTES
+      )
+      @available = status.success? && probe_status.success?
       @version = @available ? out.lines.first.to_s.split[2] : nil
       @available
-    rescue Errno::ENOENT
+    rescue Errno::ENOENT, Error
       @version = nil
       @available = false
     end
@@ -37,44 +33,94 @@ module Metaclean
       available? ? @version : nil
     end
 
-    # Strips all metadata from `path` in place, losslessly. Returns true on
-    # success, raises Metaclean::Error on failure.
-    #
-    #   -map 0            keep every stream (video, audio, subtitles)
-    #   -map_metadata -1  drop global/container metadata
-    #   -map_chapters -1  drop chapter markers (they can carry titles)
-    #   -c copy           remux without re-encoding — bit-identical streams
     def strip!(path)
       raise Error, 'ffmpeg not available' unless available?
 
-      tmp  = tmp_path_for(path)
-      # Clear any stale temp from an earlier crashed run before muxing.
-      File.delete(tmp) if File.exist?(tmp)
+      source = FileOps.regular_stat!(path)
+      structure = probe_structure(path)
+      reject_unverifiable_streams!(structure[:streams])
+      FileOps.with_private_workspace(path, 'ffmpeg') do |workspace|
+        tmp = File.join(workspace, "output#{File.extname(path)}")
+        args = [
+          'ffmpeg', '-y', '-v', 'error', '-nostdin', '-i', file_url(path),
+          '-map', '0', '-map_metadata', '-1',
+          '-map_chapters', structure[:chapters].positive? ? '0' : '-1'
+        ]
+        args.concat(['-metadata:c', 'title=']) if structure[:chapters].positive?
+        append_safe_stream_languages(args, structure[:streams])
+        args.concat(['-c', 'copy', file_url(tmp)])
+
+        _out, err, status = Metaclean.capture3(*args)
+        raise Error, "ffmpeg failed: #{err.strip}" unless status.success? && File.exist?(tmp)
 
-      _out, err, status = Metaclean.capture3(
-        'ffmpeg', '-y', '-v', 'error', '-nostdin', '-i', file_url(path),
-        '-map', '0', '-map_metadata', '-1', '-map_chapters', '-1', '-c', 'copy',
-        file_url(tmp)
+        FileOps.validate_output!(tmp)
+        ensure_structure_preserved!(structure, probe_structure(tmp))
+        FileOps.ensure_same_file!(path, source)
+        FileOps.restore_metadata(tmp, source)
+        File.rename(tmp, path)
+        true
+      end
+    end
+
+    def probe_structure(path)
+      out, err, status = Metaclean.capture3(
+        'ffprobe', '-v', 'error', '-show_streams', '-show_chapters',
+        '-of', 'json', file_url(path)
       )
-      # ffmpeg can exit 0 yet write nothing on some odd inputs, so require the
-      # output to actually exist before we trust it and move it into place.
-      raise Error, "ffmpeg failed: #{err.strip}" unless status.success? && File.exist?(tmp)
-
-      FileUtils.mv(tmp, path)
-      true
-    ensure
-      # Interrupt-safety: drop the temp if we were killed between mux and rename.
-      # On the success path it's already moved, so this is a no-op.
-      File.delete(tmp) if tmp && File.exist?(tmp)
+      raise Error, "ffprobe failed: #{err.strip}" unless status.success?
+
+      data = JSON.parse(out)
+      streams = data.fetch('streams', [])
+      chapters = data.fetch('chapters', [])
+      raise TypeError unless streams.is_a?(Array) && chapters.is_a?(Array)
+
+      { streams: streams, chapters: chapters.size }
+    rescue JSON::ParserError, KeyError, TypeError => e
+      raise Error, "Could not parse ffprobe output: #{e.message}"
+    end
+
+    def reject_unverifiable_streams!(streams)
+      video_streams = streams.count { |stream| stream['codec_type'] == 'video' }
+      nested = streams.any? do |stream|
+        tags = stream['tags'].is_a?(Hash) ? stream['tags'] : {}
+        disposition = stream['disposition'].is_a?(Hash) ? stream['disposition'] : {}
+        nested_image = stream['codec_type'] == 'video' &&
+                       NESTED_IMAGE_CODECS.include?(stream['codec_name']) &&
+                       (video_streams > 1 || streams.any? { |candidate| candidate['codec_type'] == 'audio' })
+        stream['codec_type'] == 'attachment' ||
+          nested_image ||
+          disposition['attached_pic'].to_i == 1 ||
+          !tags['filename'].to_s.empty? ||
+          !tags['mimetype'].to_s.empty?
+      end
+      return unless nested
+
+      raise Error, 'Matroska contains attachments or cover art whose nested metadata cannot be verified'
+    end
+
+    def ensure_structure_preserved!(before, after)
+      before_signatures = stream_signatures(before[:streams])
+      after_signatures = stream_signatures(after[:streams])
+      unless before_signatures == after_signatures && before[:chapters] == after[:chapters]
+        raise Error, 'ffmpeg output changed the stream or chapter structure'
+      end
+    end
+
+    def stream_signatures(streams)
+      streams.map { |stream| [stream['codec_type'], stream['codec_name']] }
     end
 
-    # Sibling temp with the SAME extension (ffmpeg picks the muxer from it) in
-    # the SAME directory (so the final rename is an atomic same-fs move). The
-    # ".metaclean.tmp." marker means Runner#skip? ignores any stray leftover.
-    def tmp_path_for(path)
-      dir  = File.dirname(path)
-      ext  = File.extname(path)
-      File.join(dir, "#{Metaclean::TMP_MARKER}ff.#{Process.pid}.#{SecureRandom.hex(8)}#{ext}")
+    def append_safe_stream_languages(args, streams)
+      streams.each do |stream|
+        index = Integer(stream.fetch('index'))
+        tags = stream['tags'].is_a?(Hash) ? stream['tags'] : {}
+        language = tags['language'].to_s.downcase
+        if language.match?(/\A[a-z]{2,3}(?:-[a-z0-9]{2,8})*\z/)
+          args.concat(["-metadata:s:#{index}", "language=#{language}"])
+        end
+      end
+    rescue KeyError, TypeError, ArgumentError => e
+      raise Error, "Unexpected ffprobe stream data: #{e.message}"
     end
 
     def file_url(path)

data/lib/metaclean/file_ops.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'tmpdir'
+
+module Metaclean
+  module FileOps
+    module_function
+
+    def path_guard!(path)
+      components = component_identities(path)
+      realpath = File.realpath(path)
+      raise Error, "#{path} changed while its path was being verified" unless components == component_identities(path)
+
+      { realpath: realpath, components: components }
+    rescue SystemCallError => e
+      raise Error, "#{path} cannot be resolved safely: #{e.message}"
+    end
+
+    def ensure_path_guard!(path, expected)
+      current = path_guard!(path)
+      return if current == expected
+
+      raise Error, "#{path} or one of its parent directories changed during cleaning"
+    end
+
+    def component_identities(path)
+      components = path_components(path)
+      components.map.with_index do |component, index|
+        stat = File.lstat(component)
+        if stat.symlink? && (index == components.length - 1 || !trusted_system_symlink?(component, stat))
+          raise Error, "#{path} contains a symlink component (#{component}) — refusing to use it"
+        end
+
+        [component, stat.dev, stat.ino]
+      end
+    end
+
+    def path_components(path)
+      expanded = File.expand_path(path)
+      current = File::SEPARATOR
+      expanded.split(File::SEPARATOR).reject(&:empty?).map do |part|
+        current = File.join(current, part)
+      end
+    end
+
+    def trusted_system_symlink?(path, stat)
+      parent = File.lstat(File.dirname(path))
+      stat.uid.zero? && parent.uid.zero? && parent.mode.nobits?(0o022)
+    rescue SystemCallError
+      false
+    end
+
+    def regular_stat!(path)
+      stat = File.lstat(path)
+      raise Error, "#{path} is a symlink — refusing to use it" if stat.symlink?
+      raise Error, "#{path} is not a regular file — refusing to use it" unless stat.file?
+
+      stat
+    rescue SystemCallError => e
+      raise Error, "#{path} cannot be used: #{e.message}"
+    end
+
+    def ensure_same_file!(path, expected)
+      current = regular_stat!(path)
+      return current if same_file?(current, expected)
+
+      raise Error, "#{path} changed during cleaning — refusing to commit"
+    end
+
+    def same_file?(left, right)
+      left.dev == right.dev && left.ino == right.ino &&
+        left.size == right.size && left.mtime == right.mtime && left.ctime == right.ctime
+    end
+
+    def same_identity?(left, right)
+      left.dev == right.dev && left.ino == right.ino &&
+        left.size == right.size && left.mtime == right.mtime
+    end
+
+    def copy_exclusive(src, dest, preserve: false, expected: nil)
+      source = regular_stat!(src)
+      if expected && !same_file?(source, expected)
+        raise Error, "#{src} changed before it could be copied"
+      end
+
+      mode = source.mode & 0o7777
+      created = false
+      read_flags = File::RDONLY
+      read_flags |= File::NOFOLLOW if defined?(File::NOFOLLOW)
+
+      File.open(dest, File::WRONLY | File::CREAT | File::EXCL, mode) do |out|
+        created = true
+        File.open(src, read_flags) do |input|
+          opened = input.stat
+          raise Error, "#{src} changed while opening — refusing to copy it" unless same_file?(opened, source)
+
+          size = opened.size
+          mtime = opened.mtime
+          ctime = opened.ctime
+          IO.copy_stream(input, out)
+          finished = input.stat
+          unless finished.size == size && finished.mtime == mtime && finished.ctime == ctime
+            raise Error, "#{src} changed while it was being copied"
+          end
+        end
+      end
+
+      restore_metadata(dest, source) if preserve
+      source
+    rescue StandardError, Interrupt
+      File.delete(dest) if created && dest && File.exist?(dest)
+      raise
+    end
+
+    def restore_metadata(path, source_stat, strict: false)
+      File.chmod(source_stat.mode & 0o7777, path)
+      File.utime(source_stat.atime, source_stat.mtime, path)
+    rescue SystemCallError => e
+      raise Error, "Could not restore file permissions/timestamps: #{e.message}" if strict
+
+      nil
+    end
+
+    def prepare_in_place_commit!(cleaned, source, expected)
+      ensure_same_file!(source, expected)
+      prepared = "#{cleaned}.metadata"
+      native_metadata_copy!(source, prepared)
+      copied = regular_stat!(prepared)
+      unless copied.uid == expected.uid && copied.gid == expected.gid
+        raise Error, 'Could not preserve source ownership for in-place output'
+      end
+
+      clean_stat = regular_stat!(cleaned)
+      File.chmod((expected.mode & 0o7777) | 0o200, prepared)
+      write_flags = File::WRONLY | File::TRUNC
+      write_flags |= File::NOFOLLOW if defined?(File::NOFOLLOW)
+      File.open(prepared, write_flags) do |out|
+        File.open(cleaned, File::RDONLY) { |input| IO.copy_stream(input, out) }
+      end
+      ensure_same_file!(cleaned, clean_stat)
+      ensure_same_file!(source, expected)
+      restore_metadata(prepared, expected, strict: true)
+      validate_output!(prepared)
+      File.rename(prepared, cleaned)
+      cleaned
+    rescue StandardError, Interrupt
+      File.delete(prepared) if prepared && lexist?(prepared)
+      raise
+    end
+
+    def native_metadata_copy!(source, destination)
+      cp = find_executable('cp')
+      raise Error, 'cp is required to preserve in-place filesystem metadata' unless cp
+
+      args = if RUBY_PLATFORM.include?('darwin')
+               [cp, '-p', '--', source, destination]
+             elsif RUBY_PLATFORM.include?('linux')
+               [cp, '--preserve=all', '--', source, destination]
+             else
+               raise Error, "In-place metadata preservation is unsupported on #{RUBY_PLATFORM}"
+             end
+      _out, err, status = Metaclean.capture3(*args)
+      return if status.success?
+
+      raise Error, "Could not preserve filesystem metadata for in-place output: #{err.strip}"
+    end
+
+    def find_executable(name)
+      ENV.fetch('PATH', '').split(File::PATH_SEPARATOR).each do |directory|
+        next if directory.empty?
+
+        candidate = File.join(directory, name)
+        return candidate if File.file?(candidate) && File.executable?(candidate)
+      end
+      nil
+    end
+
+    def metadata_copy_supported?
+      (RUBY_PLATFORM.include?('darwin') || RUBY_PLATFORM.include?('linux')) &&
+        !find_executable('cp').nil?
+    end
+
+    def lexist?(path)
+      File.symlink?(path) || File.exist?(path)
+    end
+
+    def validate_output!(path)
+      stat = regular_stat!(path)
+      raise Error, "#{path} is empty — refusing to use tool output" unless stat.size.positive?
+
+      stat
+    end
+
+    def with_private_workspace(path, label)
+      parent = File.dirname(File.expand_path(path))
+      prefix = "#{TMP_MARKER}#{label}.#{Process.pid}."
+      Dir.mktmpdir(prefix, parent) do |dir|
+        secure_workspace!(dir)
+        yield dir
+      end
+    end
+
+    def secure_workspace!(directory)
+      File.chmod(0o700, directory)
+      mode = File.stat(directory).mode & 0o777
+      return true if mode.nobits?(0o077)
+
+      raise Error, "#{directory} cannot enforce a private workspace (mode #{mode.to_s(8)})"
+    rescue SystemCallError => e
+      raise Error, "#{directory} cannot enforce a private workspace: #{e.message}"
+    end
+  end
+end

data/lib/metaclean/mat2.rb

@@ -1,55 +1,31 @@
 # 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.
-    # Deliberately ABSENT: Matroska (mkv/webm) — mat2 has no parser for it; ffmpeg
-    # owns those (Strategy::FFMPEG_FORMATS). QuickTime/MP4-audio (mov/m4a) — mat2
-    # can't write them and ExifTool already cleans them, so listing them only
-    # caused a wasted mat2 spawn that always soft-skipped. WMV (ASF) IS here on
-    # purpose: mat2 CAN write it but ExifTool can't, so mat2 is the only tool that
-    # cleans .wmv — dropping it would make every .wmv permanently :failed.
     SUPPORTED_EXTS = %w[
-      pdf png jpg jpeg tif tiff gif bmp svg webp
-      mp3 flac ogg opus wav
-      mp4 avi wmv
-      docx xlsx pptx odt ods odp odg odf epub
-      zip torrent
+      epub pdf odc odf odg odi odp ods odt pptx xlsx docx torrent ncx tar
+      xht xhtml zip flac m3a mp2a mp3 mp2 m2a mpga oga spx ogg opus
+      aifc aiff aif wav bmp gif heic jpg jpe jpeg png svgz svg tiff tif
+      webp ppm css htm html text txt in def list log conf
+      mp4 mp4v mpg4 m4v wmv avi
     ].freeze
 
-    # Matches the messages mat2 prints when it can't handle a file — lets us
-    # distinguish a soft skip from a real error.
     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')
+      out, _err, status = Metaclean.capture3(
+        'mat2', '--version',
+        timeout: Metaclean::PROBE_TIMEOUT,
+        max_output: Metaclean::PROBE_MAX_OUTPUT_BYTES
+      )
       @available = status.success?
-      # `mat2 --version` prints "mat2 0.14.0" — `.split.last` grabs the
-      # version number regardless of whatever prefix appears. Captured here
-      # so `version` reuses it instead of re-spawning the binary.
       @version = @available ? out.strip.split.last : nil
       @available
-    rescue Errno::ENOENT
+    rescue Errno::ENOENT, Error
       @version = nil
       @available = false
     end
@@ -58,64 +34,39 @@ module Metaclean
       available? ? @version : 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?(Metaclean.ext_of(path))
     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)
-      safe    = Metaclean.safe_path(path)
+      source = FileOps.regular_stat!(path)
+      FileOps.with_private_workspace(path, 'mat2') do |workspace|
+        work = File.join(workspace, "input#{File.extname(path)}")
+        FileOps.copy_exclusive(path, work, preserve: true, expected: source)
+        cleaned = cleaned_path_for(work)
+        out, err, status = Metaclean.capture3('mat2', Metaclean.safe_path(work))
 
-      # 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)
+        if status.success?
+          return :no_metadata unless File.exist?(cleaned)
 
-      out, err, status = Metaclean.capture3('mat2', safe)
+          FileOps.validate_output!(cleaned)
+          FileOps.ensure_same_file!(path, source)
+          FileOps.restore_metadata(cleaned, source)
+          File.rename(cleaned, path)
+          return true
+        end
 
-      # Success path first. mat2 only creates `<name>.cleaned.<ext>` when it
-      # actually stripped something; no file after exit 0 means there was
-      # nothing to remove. We check exit status BEFORE the "unsupported"
-      # message so a successful run that merely warns about one embedded
-      # stream isn't misreported as a soft skip.
-      if status.success?
-        return :no_metadata unless File.exist?(cleaned)
+        combined = "#{out}\n#{err}"
+        return :unsupported if combined.match?(UNSUPPORTED_RE)
 
-        FileUtils.mv(cleaned, safe)
-        return true
+        raise Error, "mat2 failed: #{err.strip.empty? ? out.strip : err.strip}"
       end
-
-      # Failure path. A "not supported" message means a soft skip we report
-      # so the runner can continue with the next tool, not a hard error.
-      combined = "#{out}\n#{err}"
-      return :unsupported if combined.match?(UNSUPPORTED_RE)
-
-      # `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}"
-    ensure
-      # Interrupt-safety: if we were killed (Ctrl-C) between mat2 writing
-      # `<name>.cleaned.<ext>` and the rename, don't leave the orphan behind.
-      # On the success path it's already moved, so this is a no-op.
-      File.delete(cleaned) if cleaned && File.exist?(cleaned)
     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)

data/lib/metaclean/qpdf.rb

@@ -1,15 +1,6 @@
 # frozen_string_literal: true
 
-# Wrapper around `qpdf` — a PDF structural cleaner.
-#
-# Why qpdf on top of mat2/ExifTool? PDFs hide metadata in places those two
-# don't always reach: orphaned objects, unused image streams, old revisions.
-# qpdf rebuilds the PDF using only referenced objects — a final pass after the
-# other tools have stripped the obvious metadata.
-
-require 'open3'
-require 'fileutils'
-require 'securerandom'
+require 'json'
 
 module Metaclean
   module Qpdf
@@ -18,15 +9,15 @@ module Metaclean
     def available?
       return @available if defined?(@available)
 
-      out, _err, status = Open3.capture3('qpdf', '--version')
+      out, _err, status = Metaclean.capture3(
+        'qpdf', '--version',
+        timeout: Metaclean::PROBE_TIMEOUT,
+        max_output: Metaclean::PROBE_MAX_OUTPUT_BYTES
+      )
       @available = status.success?
-      # `qpdf --version` prints "qpdf version 11.9.0" on its first line. We
-      # keep just the bare number (`.split.last`) so callers don't each have
-      # to post-process it — matching Exiftool.version / Mat2.version. Captured
-      # here so `version` reuses it instead of re-spawning the binary.
       @version = @available ? out.lines.first.to_s.strip.split.last : nil
       @available
-    rescue Errno::ENOENT
+    rescue Errno::ENOENT, Error
       @version = nil
       @available = false
     end
@@ -35,45 +26,54 @@ module Metaclean
       available? ? @version : 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?
 
-      src = Metaclean.safe_path(path)
-      tmp = tmp_path_for(path)
+      source = FileOps.regular_stat!(path)
+      ensure_no_attachments!(path)
+      FileOps.with_private_workspace(path, 'qpdf') do |workspace|
+        tmp = File.join(workspace, 'output.pdf')
+        _out, err, status = Metaclean.capture3(
+          'qpdf', '--linearize', '--object-streams=generate',
+          '--remove-unreferenced-resources=yes',
+          Metaclean.safe_path(path), Metaclean.safe_path(tmp)
+        )
 
-      _out, err, status = Metaclean.capture3(
-        'qpdf', '--linearize', '--object-streams=generate',
-        '--remove-unreferenced-resources=yes', src, Metaclean.safe_path(tmp)
-      )
+        success = status.success? || status.exitstatus == 3
+        raise Error, "qpdf failed: #{err.strip}" unless success && File.exist?(tmp)
+
+        FileOps.validate_output!(tmp)
+        validate_pdf!(tmp)
+        FileOps.ensure_same_file!(path, source)
+        FileOps.restore_metadata(tmp, source)
+        File.rename(tmp, path)
+        true
+      end
+    end
 
-      # qpdf has a quirk: exit code 3 means "succeeded with warnings" (output
-      # is still produced and valid). We treat that the same as success.
+    def ensure_no_attachments!(path)
+      out, err, status = Metaclean.capture3(
+        'qpdf', '--json', '--json-key=attachments', Metaclean.safe_path(path)
+      )
       success = status.success? || status.exitstatus == 3
-      raise Error, "qpdf failed: #{err.strip}" unless success && File.exist?(tmp)
+      raise Error, "qpdf could not inspect PDF attachments: #{err.strip}" unless success
+
+      attachments = JSON.parse(out).fetch('attachments')
+      raise Error, 'Unexpected qpdf attachment inventory' unless attachments.is_a?(Hash)
+      return if attachments.empty?
 
-      FileUtils.mv(tmp, src)
-      true
-    ensure
-      # Interrupt-safety: drop the temp if we died (or failed) before the
-      # rename. On success it's already moved, so this is a no-op.
-      File.delete(tmp) if tmp && File.exist?(tmp)
+      raise Error, 'PDF contains embedded attachments whose nested metadata cannot be verified'
+    rescue JSON::ParserError, KeyError => e
+      raise Error, "Could not parse qpdf attachment inventory: #{e.message}"
     end
 
-    # Short sibling temp in the same directory: same-fs rename, unpredictable
-    # name, and no risk of exceeding filename length by appending to a long PDF.
-    def tmp_path_for(path)
-      File.join(File.dirname(path), "#{Metaclean::TMP_MARKER}qpdf.#{Process.pid}.#{SecureRandom.hex(8)}.pdf")
+    def validate_pdf!(path)
+      _out, err, status = Metaclean.capture3(
+        'qpdf', '--check', Metaclean.safe_path(path)
+      )
+      return true if status.success? || status.exitstatus == 3
+
+      raise Error, "qpdf produced an invalid PDF: #{err.strip}"
     end
   end
 end