shrine-zip-guard 0.2.0 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 9359699bdaf1bf53ba7b23a7c271880166360df60bf26d78ef5b874cd8e605e2
4
- data.tar.gz: d353357a3022c8f981501e735ca40f1a3264cdb8bc0d42c5093be2a369609d81
3
+ metadata.gz: 100bddcd734094f0bf2b89e8119d0eace3f427bec98892e77a7431361c48ad6a
4
+ data.tar.gz: '081b28007c7f8fc5c2ec94f04960afd7a8ad56dd4b471f5ab280b7e2073cb506'
5
5
  SHA512:
6
- metadata.gz: 0c170879388c9bb5c29a50d25d74a3ce50718f30ae315b318151333b4c5e9424213ab6172254bf63302ff94ea32c456006ba4cd4334e3be3659998ed0578595c
7
- data.tar.gz: 82c23d6223bfe1c618471cf62c06b44d86a93f17779bf149bc1272b120cfc9bed557927416ca47a1b9adc3313f99bbcb5e837d0ed9665aa581da01680adbe47d
6
+ metadata.gz: a493b96e8176dca70a44543e3552a5728bd6c2fe3d86983bb60f79a30db6f45f2562cec0af20cc0006663b71f4b5876611b8ea485e1822e77dea28f012804601
7
+ data.tar.gz: a25a8083980baa5c58c53a8da85418543e39209c5032a4b8f5d128a5a4495472b3d4ac07b898617f36cfdc46834fa7272565e2013171714047a4563588e3cab2
data/.rubocop.yml CHANGED
@@ -1,5 +1,5 @@
1
1
  AllCops:
2
- TargetRubyVersion: 3.1
2
+ TargetRubyVersion: 3.3
3
3
  NewCops: enable
4
4
  SuggestExtensions: false
5
5
 
data/CHANGELOG.md CHANGED
@@ -1,6 +1,37 @@
1
1
  # Changelog
2
2
 
3
- ## [Unreleased]
3
+ ## [1.0.0] - 2026-11-16
4
+
5
+ Complete rewrite. ZIP checks moved from derivatives to Shrine validation.
6
+
7
+ ### ⚠️ Breaking Changes
8
+ - Removed the `create_derivatives` override, the `derivatives` dependency and the automatic `required_files` mode.
9
+ - Removed `with_zip`, `EncryptedZipError`, `MissingFileError` and the `fallback` option. Unknown plugin options now raise `ArgumentError`.
10
+ - Unexpected errors are no longer rescued.
11
+ - Ruby 3.1 and 3.2 are no longer supported (end of life); the minimum is Ruby 3.3.
12
+ - I18n keys moved to `shrine.zip_guard.errors.*`; per-uploader message keys were removed.
13
+
14
+ ### Added
15
+ - `validate_zip` validation helper with explicit checks: `password:`, `nested_archives:`, `required:`, and per-call `messages:` overrides.
16
+ - Recursive password check for nested archives, limited by `max_depth`, `max_entries` and `max_nested_size`.
17
+ - ZIP detection by content instead of extension.
18
+ - `ZipGuard.extract_one` for size-limited extraction of a single file, with `passthrough:` for uploads that may not be archives.
19
+ - Office documents (`.xlsx`, `.docx`, …) are recognised: allowed by `nested_archives: false`, skipped by `required:`.
20
+ - CI on Ruby 3.3, 3.4 and 4.0.
21
+
22
+ ## [0.3.0] - 2026-08-11
23
+
24
+ ### ⚠️ Breaking Changes
25
+ - `rescue ZipGuard::Error` broadened to `rescue StandardError` — now catches corrupt ZIP archives (`Zip::Error`), other unexpected errors, and custom error subclasses like `NestedFileError`. Previously these errors propagated; now they are caught and passed to the fallback handler.
26
+ - Fallback callback (`shrine_class.opts[:zip_guard][:fallback]`) is now invoked for all rescued `StandardError` errors, not just `ZipGuard::Error` subclasses.
27
+ - `create_derivatives` now explicitly returns `{}` (empty Hash) from all rescue branches. Previously it returned the `errors` array.
28
+
29
+ ### Fixed
30
+ - All rescue branches in `create_derivatives` now explicitly return `{}` instead of the error messages array.
31
+
32
+ ### Changed
33
+ - Renamed internal method `handle_zip_guard_error` to `handle_error`.
34
+ - Renamed internal method `report_fallback` to `report_error`.
4
35
 
5
36
  ## [0.2.0] - 2026-08-06
6
37
 
data/README.md CHANGED
@@ -1,137 +1,165 @@
1
1
  # Shrine::ZipGuard
2
2
 
3
- A [Shrine](https://shrinerb.com/) plugin for safe ZIP derivative processing.
4
-
5
- It catches common ZIP errors during derivative creation — password-protected
6
- archives and missing required files — and converts them into friendly, I18n-ready
7
- error messages attached to `attacher.errors`.
3
+ A [Shrine](https://shrinerb.com/) plugin that validates uploaded ZIP archives:
4
+ it rejects password-protected archives (also when they are nested inside another
5
+ archive), can forbid nested archives and can require specific files. It also
6
+ ships a size-limited helper for extracting a single file from an archive.
8
7
 
9
8
  ## Installation
10
9
 
11
- Add this line to your application's Gemfile:
12
-
13
10
  ```ruby
14
11
  gem "shrine-zip-guard"
15
12
  ```
16
13
 
17
- And then execute:
14
+ ## Validation
15
+
16
+ ```ruby
17
+ class DocumentUploader < Shrine
18
+ plugin :zip_guard
18
19
 
19
- ```bash
20
- bundle install
20
+ Attacher.validate do
21
+ validate_zip password: false, nested_archives: false
22
+ end
23
+ end
21
24
  ```
22
25
 
23
- ## Usage
26
+ Errors are added during `assign`, so they end up in `record.errors` like any
27
+ other Shrine validation.
24
28
 
25
- ### Automatic validation
29
+ ### Checks
26
30
 
27
- If you only need to validate that the uploaded ZIP contains certain files, enable
28
- the plugin with `required_files`:
31
+ Every check is explicit. Calling `validate_zip` without any of them raises
32
+ `ArgumentError`.
29
33
 
30
- ```ruby
31
- class XmlUploader < Shrine
32
- plugin :derivatives
33
- plugin :zip_guard, required_files: ["*.xml"]
34
- end
35
- ```
34
+ | Option | Meaning |
35
+ |---|---|
36
+ | `password: false` | Rejects the archive if any entry is encrypted, at any nesting level. |
37
+ | `password: true` | Requires every file in the archive to be encrypted. |
38
+ | `nested_archives: false` | Rejects archives containing other archives. Office documents (`.docx`, `.xlsx`, `.pptx`, `.odt`, …) are allowed. |
39
+ | `nested_archives: true` | Allows nested archives (the default when the option is omitted). |
40
+ | `required: "*.xml"` | Requires a file matching the pattern in the archive root. Accepts an array; every pattern must match. |
36
41
 
37
- This checks that the ZIP is not password-protected and that it contains at least
38
- one file matching each glob pattern. Patterns are matched against the root of the
39
- archive only. If you want to allow nested files, use a recursive pattern:
42
+ Combine them in a single call:
40
43
 
41
44
  ```ruby
42
- plugin :zip_guard, required_files: ["**/*.xml"]
45
+ validate_zip password: false, nested_archives: false, required: ["*.xml"]
43
46
  ```
44
47
 
45
- For a specific subdirectory, include the path in the pattern:
48
+ Notes:
49
+
50
+ - ZIP archives are detected by their content (magic bytes), not by extension. A
51
+ password-protected ZIP renamed to `.pdf` is still rejected.
52
+ - Files that are not ZIP archives are ignored. Use `validate_mime_type` and
53
+ `validate_extension` for file types.
54
+ - Office documents are ZIP containers too. An uploaded `.xlsx`/`.docx`/… is
55
+ still checked for `password` and `nested_archives`, but `required` does not
56
+ apply to it.
57
+ - `required` patterns are matched case-insensitively against the archive root
58
+ (`File::FNM_PATHNAME | File::FNM_EXTGLOB | File::FNM_CASEFOLD`), so
59
+ `"*.{xls,xlsx}"` works. A matching file found only in a subfolder produces a
60
+ dedicated error message.
61
+ - `password: true` cannot look inside encrypted entries, so nested archives in
62
+ an encrypted archive are not inspected.
63
+ - Encrypted Office documents use a different container format (OLE) and are not
64
+ detected.
65
+
66
+ ### Limits
67
+
68
+ `password: false` inspects nested archives recursively. To protect against ZIP
69
+ bombs, inspection is limited, and an archive exceeding a limit is rejected:
46
70
 
47
71
  ```ruby
48
- plugin :zip_guard, required_files: ["data/*.xml"]
72
+ plugin :zip_guard,
73
+ max_depth: 3, # nesting levels
74
+ max_entries: 10_000, # entries across all levels
75
+ max_nested_size: 100 * 1024 * 1024 # bytes extracted from nested archives in total
49
76
  ```
50
77
 
51
- ### Custom processing with `with_zip`
78
+ The top-level archive is never extracted; only its central directory and the
79
+ first bytes of each entry are read. Nested archives are extracted to temporary
80
+ files, and the limit is enforced on the bytes actually written.
52
81
 
53
- If you need to run your own logic (for example extracting files or checking
54
- specific paths), use the `with_zip` helper inside your `Attacher.derivatives` block:
82
+ ## Extracting a single file
55
83
 
56
84
  ```ruby
57
- class XmlUploader < Shrine
58
- plugin :derivatives
59
- plugin :zip_guard
60
-
61
- Attacher.derivatives do |original|
62
- Shrine::Plugins::ZipGuard.with_zip(original, required_files: ["*.xml"]) do |zip_file|
63
- xmls = zip_file.glob("*.xml")
64
-
65
- if xmls.size == 1
66
- extracted = Tempfile.new(["extracted", ".xml"], binmode: true)
67
- extracted.write(xmls.first.get_input_stream.read)
68
- extracted.rewind
69
- { extracted_xml: extracted }
70
- else
71
- {}
72
- end
73
- end
74
- end
85
+ Shrine::Plugins::ZipGuard.extract_one(file, pattern: "*.xml", max_size: 200 * 1024 * 1024) do |xml, name|
86
+ # xml is a Tempfile with the original extension, deleted after the block
75
87
  end
76
88
  ```
77
89
 
78
- Note that `with_zip` performs its own `required_files` check, so you should not also
79
- pass `required_files` to the plugin when you provide a custom `derivatives` block.
90
+ `file` can be a `Shrine::UploadedFile`, an IO with a path, or a path.
80
91
 
81
- ## Error messages
92
+ When the upload can be either the archive or the file itself (for example an
93
+ XML or a ZIP containing it), pass `passthrough: true`. Files that are not ZIP
94
+ archives, and office documents, are then yielded as they are, with their
95
+ original filename:
82
96
 
83
- All user-facing errors are translated via I18n. The gem ships with English
84
- defaults under the `shrine.zip_guard` key:
85
-
86
- ```yaml
87
- en:
88
- shrine:
89
- zip_guard:
90
- password_protected: "ZIP file is password protected. Please upload an unprotected file."
91
- missing_file: "Archive does not contain required file matching '%{pattern}'."
92
- processing_failed: "File could not be processed. Please try again or contact support."
97
+ ```ruby
98
+ Shrine::Plugins::ZipGuard.extract_one(file, pattern: "*.{xls,xlsx}", passthrough: true) do |io, name|
99
+ # io is the extracted file or the original file
100
+ end
93
101
  ```
94
102
 
95
- ### Per-uploader custom messages
103
+ It raises
104
+ `Shrine::Plugins::ZipGuard::Error` (with a `key` and a translated `message`)
105
+ when the file is not a ZIP archive (without `passthrough`), the archive is
106
+ encrypted or invalid, or it does not contain exactly one file
107
+ matching the pattern in its root, or when the file exceeds `max_size`.
96
108
 
97
- You can override any message for a specific uploader by adding a key under
98
- `shrine.zip_guard.errors.<uploader_name>`:
109
+ Unexpected errors (storage failures, bugs) are not rescued.
110
+
111
+ ## Error messages
112
+
113
+ Messages are translated via I18n. The gem ships English defaults:
99
114
 
100
115
  ```yaml
101
116
  en:
102
117
  shrine:
103
118
  zip_guard:
104
- missing_file: "Archive does not contain required file matching '%{pattern}'."
105
119
  errors:
106
- digital_box_rd_uploader:
107
- missing_file: "XML file must be at the root level of the ZIP archive."
108
- password_protected: "This ZIP is password protected."
109
- processing_failed: "Could not process this XML ZIP."
120
+ password_forbidden: "ZIP archive is password protected. Please upload an archive without a password."
121
+ password_required: "ZIP archive must be password protected."
122
+ nested_archive: "ZIP archive must not contain other archives."
123
+ missing_file: "ZIP archive does not contain a %{name} file."
124
+ misplaced_file: "The %{name} file must be in the root of the ZIP archive, not in a subfolder."
125
+ multiple_files: "ZIP archive must contain exactly one %{name} file."
126
+ too_deep: "ZIP archive contains too many levels of nested archives."
127
+ too_large: "ZIP archive content is too large."
128
+ too_many_entries: "ZIP archive contains too many files."
129
+ invalid_archive: "File is not a valid ZIP archive."
110
130
  ```
111
131
 
112
- If the per-uploader key exists, it is used; otherwise the default key is used.
113
- The class name is converted with `underscore`, so `MyUploaders::XmlUploader`
114
- would become `my_uploaders/xml_uploader`.
115
-
116
- ## Custom fallback for unexpected errors
132
+ Override any key in your application's locale files to change a message for
133
+ the whole application.
117
134
 
118
- By default, unexpected `ZipGuard::Error` subclasses are reported to the Rails error
119
- reporter (if available) and a generic `processing_failed` message is added to
120
- `attacher.errors`. You can override this with your own handler:
135
+ To change a message for a single uploader, pass `messages:` to `validate_zip`
136
+ (like `message:` in Shrine's `validation_helpers`). Values are strings or
137
+ lambdas; lambdas receive `name:` and `pattern:` for required file errors. Keys
138
+ you leave out fall back to I18n.
121
139
 
122
140
  ```ruby
123
- plugin :zip_guard,
124
- required_files: ["*.xml"],
125
- fallback: lambda { |error, attacher|
126
- Sentry.capture_exception(error)
127
- attacher.errors << "Custom processing error: #{error.message}"
128
- }
141
+ validate_zip password: false, required: "*.{xls,xlsx}",
142
+ messages: {
143
+ missing_file: "The archive must contain the explanations spreadsheet.",
144
+ misplaced_file: ->(name:, **) { "Move the #{name} file to the root of the archive." }
145
+ }
129
146
  ```
130
147
 
148
+ Messages about required files can use `%{name}` and `%{pattern}`. `%{name}` is
149
+ derived from simple patterns (`"*.xml"` → `XML`, `"*.{xls,xlsx}"` → `XLS/XLSX`);
150
+ for other patterns it equals the pattern.
151
+
131
152
  ## Supported versions
132
153
 
133
- - Ruby >= 3.1
154
+ - Ruby >= 3.3
134
155
  - Shrine >= 3.0, < 4.0
156
+ - rubyzip >= 3.0, < 4.0
157
+
158
+ Shrine 3.9.0 and 3.10.0 raise `NoMethodError` when any validation fails on an
159
+ attacher created with `Attacher.new` (without a record) while the `model` and
160
+ `remove_invalid` plugins are loaded
161
+ ([shrine#756](https://github.com/shrinerb/shrine/issues/756)). If you validate
162
+ with standalone attachers, use Shrine 3.10.1 or later.
135
163
 
136
164
  ## License
137
165
 
@@ -1,6 +1,14 @@
1
1
  en:
2
2
  shrine:
3
3
  zip_guard:
4
- password_protected: "ZIP file is password protected. Please upload an unprotected file."
5
- missing_file: "Archive does not contain required file matching '%{pattern}'."
6
- processing_failed: "File could not be processed. Please try again or contact support."
4
+ errors:
5
+ password_forbidden: "ZIP archive is password protected. Please upload an archive without a password."
6
+ password_required: "ZIP archive must be password protected."
7
+ nested_archive: "ZIP archive must not contain other archives."
8
+ missing_file: "ZIP archive does not contain a %{name} file."
9
+ misplaced_file: "The %{name} file must be in the root of the ZIP archive, not in a subfolder."
10
+ multiple_files: "ZIP archive must contain exactly one %{name} file."
11
+ too_deep: "ZIP archive contains too many levels of nested archives."
12
+ too_large: "ZIP archive content is too large."
13
+ too_many_entries: "ZIP archive contains too many files."
14
+ invalid_archive: "File is not a valid ZIP archive."
@@ -0,0 +1,61 @@
1
+ # frozen_string_literal: true
2
+
3
+ class Shrine
4
+ module Plugins
5
+ module ZipGuard
6
+ class Extractor
7
+ def initialize(pattern:, max_size:, passthrough:)
8
+ @pattern = pattern
9
+ @max_size = max_size
10
+ @passthrough = passthrough
11
+ end
12
+
13
+ def call(file, &)
14
+ name = ZipGuard.original_name(file)
15
+ ZipGuard.with_path(file) do |path|
16
+ next extract(path, &) if ZipGuard.zip?(path) && !ZipGuard.document?(name)
17
+ raise Error, :invalid_archive unless @passthrough
18
+
19
+ File.open(path, "rb") { |io| yield io, name }
20
+ end
21
+ end
22
+
23
+ private
24
+
25
+ def extract(path)
26
+ tempfile, name = extract_entry(path)
27
+ tempfile.rewind
28
+ yield tempfile, name
29
+ ensure
30
+ tempfile&.close!
31
+ end
32
+
33
+ def extract_entry(path)
34
+ ZipGuard.open_archive(path) do |zip|
35
+ raise Error, :password_forbidden if zip.any?(&:encrypted?)
36
+
37
+ entry = find_single_entry(zip)
38
+ [extract_to_tempfile(entry), entry.name]
39
+ end
40
+ end
41
+
42
+ def extract_to_tempfile(entry)
43
+ tempfile = Tempfile.new(["zip_guard", File.extname(entry.name)], binmode: true)
44
+ ZipGuard.copy_entry(entry, tempfile, @max_size)
45
+ tempfile
46
+ rescue StandardError
47
+ tempfile&.close!
48
+ raise
49
+ end
50
+
51
+ def find_single_entry(zip)
52
+ entries = ZipGuard.glob(zip, @pattern)
53
+ Inspector.ensure_present!(zip, @pattern) if entries.empty?
54
+ raise Error.new(:multiple_files, pattern: @pattern) if entries.size > 1
55
+
56
+ entries.first
57
+ end
58
+ end
59
+ end
60
+ end
61
+ end
@@ -0,0 +1,78 @@
1
+ # frozen_string_literal: true
2
+
3
+ class Shrine
4
+ module Plugins
5
+ module ZipGuard
6
+ class Inspector
7
+ def self.ensure_present!(zip, pattern)
8
+ return if ZipGuard.glob(zip, pattern).any?
9
+ raise Error.new(:misplaced_file, pattern:) if ZipGuard.glob(zip, "**/#{pattern}").any?
10
+
11
+ raise Error.new(:missing_file, pattern:)
12
+ end
13
+
14
+ def initialize(max_depth:, max_entries:, max_nested_size:)
15
+ @max_depth = max_depth
16
+ @max_entries = max_entries
17
+ @budget = max_nested_size
18
+ @entries = 0
19
+ end
20
+
21
+ def call(path, password: nil, nested_archives: nil, required: nil)
22
+ @password = password
23
+ @nested_archives = nested_archives
24
+
25
+ inspect_archive(path, depth: 0) do |zip|
26
+ ensure_encrypted!(zip) if password == true
27
+ Array(required).each { |pattern| self.class.ensure_present!(zip, pattern) }
28
+ end
29
+ end
30
+
31
+ private
32
+
33
+ def inspect_archive(path, depth:)
34
+ ZipGuard.open_archive(path) do |zip|
35
+ count_entries!(zip)
36
+ raise Error, :password_forbidden if @password == false && zip.any?(&:encrypted?)
37
+
38
+ yield zip if block_given?
39
+ scan_entries(zip, depth) if @password == false || @nested_archives == false
40
+ end
41
+ end
42
+
43
+ def count_entries!(zip)
44
+ @entries += zip.size
45
+ raise Error, :too_many_entries if @entries > @max_entries
46
+ end
47
+
48
+ def ensure_encrypted!(zip)
49
+ files = zip.select(&:file?)
50
+ raise Error, :password_required if files.empty? || !files.all?(&:encrypted?)
51
+ end
52
+
53
+ def scan_entries(zip, depth)
54
+ zip.each do |entry|
55
+ next unless nested_archive?(entry)
56
+
57
+ raise Error, :nested_archive if @nested_archives == false && !ZipGuard.document?(entry.name)
58
+
59
+ inspect_nested(entry, depth + 1) if @password == false
60
+ end
61
+ end
62
+
63
+ def inspect_nested(entry, depth)
64
+ raise Error, :too_deep if depth > @max_depth
65
+
66
+ Tempfile.create("zip_guard", binmode: true) do |tempfile|
67
+ @budget -= ZipGuard.copy_entry(entry, tempfile, @budget)
68
+ inspect_archive(tempfile.path, depth:)
69
+ end
70
+ end
71
+
72
+ def nested_archive?(entry)
73
+ entry.file? && !entry.encrypted? && ZipGuard.archive_entry?(entry)
74
+ end
75
+ end
76
+ end
77
+ end
78
+ end
@@ -2,117 +2,183 @@
2
2
 
3
3
  require "shrine"
4
4
  require "zip"
5
+ require "zlib"
6
+ require "tempfile"
5
7
 
6
8
  class Shrine
7
9
  module Plugins
8
10
  module ZipGuard
9
- class Error < StandardError; end
10
- class EncryptedZipError < Error; end
11
-
12
- class MissingFileError < Error
13
- attr_reader :pattern
14
-
15
- def initialize(pattern)
16
- @pattern = pattern
17
- super("Archive does not contain required file matching '#{pattern}'")
11
+ DEFAULTS = {
12
+ max_depth: 3,
13
+ max_entries: 10_000,
14
+ max_nested_size: 100 * 1024 * 1024
15
+ }.freeze
16
+
17
+ SIGNATURES = ["PK\x03\x04".b, "PK\x05\x06".b, "PK\x07\x08".b].freeze
18
+ GLOB_FLAGS = File::FNM_PATHNAME | File::FNM_EXTGLOB | File::FNM_CASEFOLD
19
+ CHUNK_SIZE = 64 * 1024
20
+ DOCUMENT_EXTENSIONS = %w[
21
+ .docx .docm .dotx .dotm .xlsx .xlsm .xltx .xltm .pptx .pptm .potx .potm .odt .ods .odp .odg
22
+ ].freeze
23
+
24
+ class Error < StandardError
25
+ attr_reader :key, :options
26
+
27
+ def initialize(key, **options)
28
+ options = { name: ZipGuard.pattern_name(options[:pattern]) }.merge(options) if options.key?(:pattern)
29
+ @key = key
30
+ @options = options
31
+ super(I18n.t(key, scope: "shrine.zip_guard.errors", **options))
18
32
  end
19
33
  end
20
34
 
21
35
  class << self
22
- def with_zip(original, required_files: nil, &)
23
- return yield(nil) unless zip?(original)
36
+ def zip?(path)
37
+ File.open(path, "rb") { |file| SIGNATURES.include?(file.read(4)) }
38
+ end
24
39
 
25
- Zip::File.open(original.path) do |zip_file|
26
- raise EncryptedZipError if zip_file.any?(&:encrypted?)
40
+ def pattern_name(pattern)
41
+ match = pattern.to_s.match(/\A\*\.(?:\{([\w,]+)\}|(\w+))\z/)
42
+ return pattern.to_s unless match
27
43
 
28
- if required_files
29
- Array(required_files).each do |pattern|
30
- raise MissingFileError, pattern unless zip_file.glob(pattern).any?
31
- end
32
- end
44
+ (match[1] || match[2]).split(",").map(&:upcase).join("/")
45
+ end
46
+
47
+ def document?(name)
48
+ DOCUMENT_EXTENSIONS.include?(File.extname(name.to_s).downcase)
49
+ end
33
50
 
34
- yield zip_file
51
+ def original_name(file)
52
+ case file
53
+ when Shrine::UploadedFile then file.original_filename || file.id
54
+ when String, Pathname then File.basename(file.to_s)
55
+ else file.respond_to?(:original_filename) ? file.original_filename : File.basename(file.path.to_s)
56
+ end
57
+ end
58
+
59
+ def with_path(file, &)
60
+ case file
61
+ when String, Pathname
62
+ yield file.to_s
63
+ when Shrine::UploadedFile
64
+ return yield(file.storage.path(file.id).to_s) if file.storage.respond_to?(:path)
65
+
66
+ file.download { |tempfile| yield tempfile.path }
67
+ else
68
+ Shrine.with_file(file) { |io| yield io.path }
35
69
  end
36
70
  end
37
71
 
72
+ def open_archive(path, &)
73
+ Zip::File.open(path, &)
74
+ rescue Zip::Error, Zlib::Error
75
+ raise Error, :invalid_archive
76
+ end
77
+
78
+ def glob(zip, pattern)
79
+ zip.glob(pattern, GLOB_FLAGS).select(&:file?)
80
+ end
81
+
82
+ def archive_entry?(entry)
83
+ SIGNATURES.include?(entry.get_input_stream { |input| input.read(4) })
84
+ end
85
+
86
+ def copy_entry(entry, output, limit)
87
+ raise Error, :too_large if entry.size > limit
88
+
89
+ written = entry.get_input_stream { |input| stream(input, output, limit) }
90
+ output.flush
91
+ written
92
+ end
93
+
94
+ def extract_one(file, pattern:, max_size: DEFAULTS[:max_nested_size], passthrough: false, &)
95
+ Extractor.new(pattern:, max_size:, passthrough:).call(file, &)
96
+ end
97
+
38
98
  private
39
99
 
40
- def zip?(original)
41
- return false unless original.respond_to?(:path)
100
+ def stream(input, output, limit)
101
+ written = 0
102
+ while (chunk = input.read(CHUNK_SIZE))
103
+ written += chunk.bytesize
104
+ raise Error, :too_large if written > limit
42
105
 
43
- File.extname(original.path).downcase == ".zip"
106
+ output.write(chunk)
107
+ end
108
+ written
44
109
  end
45
110
  end
46
111
 
112
+ def self.load_dependencies(uploader, **)
113
+ uploader.plugin :validation
114
+ end
115
+
116
+ def self.configure(uploader, **opts)
117
+ unknown = opts.keys - DEFAULTS.keys
118
+ raise ArgumentError, "unknown zip_guard options: #{unknown.join(", ")}" if unknown.any?
119
+
120
+ uploader.opts[:zip_guard] = DEFAULTS.merge(uploader.opts[:zip_guard] || {}, opts)
121
+ end
122
+
47
123
  module AttacherMethods
48
- def create_derivatives(*args, **options, &)
49
- super
50
- rescue ZipGuard::EncryptedZipError
51
- errors << I18n.t(error_message_key("password_protected"))
52
- rescue ZipGuard::MissingFileError => e
53
- errors << I18n.t(error_message_key("missing_file"), pattern: e.pattern)
124
+ CHECKS = { password: [true, false], nested_archives: [true, false] }.freeze
125
+ ERROR_KEYS = %i[
126
+ password_forbidden password_required nested_archive missing_file misplaced_file
127
+ multiple_files too_deep too_large too_many_entries invalid_archive
128
+ ].freeze
129
+
130
+ def validate_zip(messages: {}, **checks)
131
+ validate_zip_checks!(checks)
132
+ validate_zip_messages!(messages)
133
+ inspect_zip(checks)
134
+ true
54
135
  rescue ZipGuard::Error => e
55
- handle_zip_guard_error(e)
136
+ errors << zip_error_message(e, messages)
137
+ false
56
138
  end
57
139
 
58
140
  private
59
141
 
60
- def error_message_key(base_key)
61
- uploader_name = shrine_class.name
62
- return "shrine.zip_guard.#{base_key}" unless uploader_name
142
+ def inspect_zip(checks)
143
+ checks = checks.except(:required) if ZipGuard.document?(ZipGuard.original_name(file))
63
144
 
64
- custom_key = "shrine.zip_guard.errors.#{underscore(uploader_name)}.#{base_key}"
65
- I18n.t(custom_key, default: nil) ? custom_key : "shrine.zip_guard.#{base_key}"
66
- end
145
+ ZipGuard.with_path(file) do |path|
146
+ next unless ZipGuard.zip?(path)
67
147
 
68
- def underscore(class_name)
69
- class_name
70
- .gsub("::", "/")
71
- .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
72
- .gsub(/([a-z\d])([A-Z])/, '\1_\2')
73
- .tr("-", "_")
74
- .downcase
148
+ Inspector.new(**shrine_class.opts[:zip_guard]).call(path, **checks)
149
+ end
75
150
  end
76
151
 
77
- def handle_zip_guard_error(error)
78
- fallback = shrine_class.opts[:zip_guard][:fallback]
152
+ def zip_error_message(error, messages)
153
+ message = messages.fetch(error.key) { return error.message }
154
+ return message unless message.respond_to?(:call)
79
155
 
80
- if fallback
81
- fallback.call(error, self)
82
- else
83
- report_fallback(error)
84
- errors << I18n.t(error_message_key("processing_failed"))
85
- end
156
+ message.arity.zero? ? message.call : message.call(**error.options)
86
157
  end
87
158
 
88
- def report_fallback(error)
89
- return unless defined?(Rails) && Rails.respond_to?(:error) && Rails.error.respond_to?(:report)
90
-
91
- Rails.error.report(error)
159
+ def validate_zip_messages!(messages)
160
+ unknown = messages.keys - ERROR_KEYS
161
+ raise ArgumentError, "unknown validate_zip messages: #{unknown.join(", ")}" if unknown.any?
92
162
  end
93
- end
94
163
 
95
- def self.configure(uploader, **opts)
96
- uploader.opts[:zip_guard] = {
97
- fallback: opts[:fallback],
98
- required_files: opts[:required_files]
99
- }
164
+ def validate_zip_checks!(checks)
165
+ raise ArgumentError, "validate_zip requires :password, :nested_archives or :required" if checks.empty?
166
+
167
+ unknown = checks.keys - CHECKS.keys - [:required]
168
+ raise ArgumentError, "unknown validate_zip options: #{unknown.join(", ")}" if unknown.any?
100
169
 
101
- return unless opts[:required_files]
170
+ CHECKS.each do |name, allowed|
171
+ next if !checks.key?(name) || allowed.include?(checks[name])
102
172
 
103
- uploader::Attacher.derivatives do |original|
104
- ZipGuard.with_zip(original, required_files: opts[:required_files]) do |_zip_file|
105
- {}
173
+ raise ArgumentError, "validate_zip #{name}: must be true or false"
106
174
  end
107
175
  end
108
176
  end
109
-
110
- def self.load_dependencies(uploader, **)
111
- uploader.plugin :derivatives
112
- uploader.plugin :validation
113
- end
114
177
  end
115
178
 
116
179
  register_plugin(:zip_guard, ZipGuard)
117
180
  end
118
181
  end
182
+
183
+ require_relative "zip_guard/inspector"
184
+ require_relative "zip_guard/extractor"
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module ShrineZipGuard
4
- VERSION = "0.2.0"
4
+ VERSION = "1.0.0"
5
5
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: shrine-zip-guard
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.2.0
4
+ version: 1.0.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Martin Dobrovodský
8
8
  autorequire:
9
9
  bindir: exe
10
10
  cert_chain: []
11
- date: 2026-08-06 00:00:00.000000000 Z
11
+ date: 2026-11-16 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: i18n
@@ -64,7 +64,8 @@ dependencies:
64
64
  - - "<"
65
65
  - !ruby/object:Gem::Version
66
66
  version: '4.0'
67
- description: Shrine plugin that catches encrypted ZIPs and missing files during derivatives.
67
+ description: Shrine validate_zip helper for password, nested archive and required
68
+ file checks, plus a size-limited single-file ZIP extractor.
68
69
  email:
69
70
  - dobrovodsky.martin@gmail.com
70
71
  executables: []
@@ -82,6 +83,8 @@ files:
82
83
  - lib/shrine-zip-guard.rb
83
84
  - lib/shrine-zip-guard/version.rb
84
85
  - lib/shrine/plugins/zip_guard.rb
86
+ - lib/shrine/plugins/zip_guard/extractor.rb
87
+ - lib/shrine/plugins/zip_guard/inspector.rb
85
88
  homepage: https://github.com/MaNi4/shrine-zip-guard
86
89
  licenses:
87
90
  - MIT
@@ -97,15 +100,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
97
100
  requirements:
98
101
  - - ">="
99
102
  - !ruby/object:Gem::Version
100
- version: 3.1.0
103
+ version: 3.3.0
101
104
  required_rubygems_version: !ruby/object:Gem::Requirement
102
105
  requirements:
103
106
  - - ">="
104
107
  - !ruby/object:Gem::Version
105
108
  version: '0'
106
109
  requirements: []
107
- rubygems_version: 3.5.16
110
+ rubygems_version: 3.5.22
108
111
  signing_key:
109
112
  specification_version: 4
110
- summary: Shrine plugin for safe ZIP derivative processing
113
+ summary: Shrine validation that rejects password-protected and nested ZIP archives
111
114
  test_files: []