pwn 0.5.728 → 0.5.729

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0018be9794020a4b996e0d67a076e2741ca124d475f1439a047a77ecc0667d9d'
-  data.tar.gz: 46eae2746ab67af7ace35e7dc4caa6e09897a187ec7295a6fe5b103a33262722
+  metadata.gz: '04697e334aa79768d74f64b19c7e90c8a8b0372899abdf68d83bcfd4f2dcf96b'
+  data.tar.gz: 8e8934c327d039dbfaad46d62837d1e6241af718b915deba0ed3aac240ded64b
 SHA512:
-  metadata.gz: dd8e061914bb0941234e210a8ea346d4f11dbd0babcd5137e93fe529b094826459b469f6cfb5d2e8cabdc306bbb8471df5703275035a9e8d27fc36352b50ec84
-  data.tar.gz: 4f361334ec04c20998333623be5c2d5b97ab27189dc52f1d4fda470ff40e743c38f58b1ae37b85244557a1f7eaf93954abd3baafdcb96c8bc8d57eb4fc71ff98
+  metadata.gz: 68965dcb416fa10c340a8aaa4345409313f8949de2ea17529fbe570b35022e0eaa782639941f5d1ed873542dc6d1432a20372c0c16c1365ff32c199635829921
+  data.tar.gz: cb5176d386d0d26308ad52ac292714ddb11134fe384cf994ce275326a6d6dffbfa628f5616af99b7f6d44c9cf7df0add18a4f4d9669805e85278851da1b32a17

data/documentation/Contributing.md

@@ -30,6 +30,36 @@ rake            # rubocop + rspec - must be zero offenses
 
 (`rvmsudo rake` on multi-user RVM installs.)
 
+### Optional native decoder integration tests
+
+The default `bundle exec rake` does not require `proxmark3` or `rtl_433`.
+Ruby EM4100/Acurite decoding, native input validation, missing-executable errors,
+and cancellation-before-spawn tests always run. Only real native file replays
+are excluded with RSpec metadata (`proxmark3_integration`, `rtl433_integration`),
+not marked pending or silently passed inside examples.
+
+After installing the optional clients, explicitly enable their fixture tests:
+
+```bash
+PWN_TEST_PROXMARK3=1 bundle exec rspec spec/lib/pwn/sdr/decoder/rfid_spec.rb
+PWN_TEST_RTL433=1 bundle exec rspec spec/lib/pwn/sdr/decoder/rtl433_spec.rb
+# Enable both in the full gate:
+PWN_TEST_PROXMARK3=1 PWN_TEST_RTL433=1 bundle exec rake
+```
+
+These tests use committed offline amplitude/IQ captures, not RF hardware.
+Opt-in runs fail if their client is unavailable or cannot decode the reference;
+installed versions can differ in supported protocols and output. Fixture provenance
+and tested versions are recorded in `spec/fixtures/sdr/rfid/README.md` and
+`spec/fixtures/sdr/rtl433/README.md`. Neither client is installed by the test suite.
+
+At runtime, `RFID.decode(mode: :fdxb_pm3, ...)` and
+`RTL433.decode(mode: :native, ...)` raise an actionable `IOError` when their
+executable is missing, suggesting installation or an explicit `executable:` path.
+An already-true `stop:` callback raises cancellation before spawning either client.
+Invalid inputs still raise `ArgumentError`; native decoding never silently falls
+back to another decoder or a detector.
+
 ## Adding a plugin
 
 1. `lib/pwn/plugins/my_thing.rb` following the conventions above.

data/lib/pwn/sdr/decoder/rfid.rb

@@ -191,12 +191,19 @@ module PWN
           data = File.read(path)
           raise ArgumentError, 'PM3 file must contain signed integer amplitude samples' unless data.lines.all? { |line| line.strip.match?(/\A-?\d+\z/) }
 
+          raise IOError, 'proxmark3 replay cancelled' if opts[:stop]&.call
+
           Tempfile.create(['pwn-fdxb-', '.pm3']) do |trace|
             Tempfile.create('pwn-fdxb-output-') do |output|
               trace.write(data)
               trace.flush
-              pid = Process.spawn(opts.fetch(:executable, 'proxmark3').to_s, '--incognito', '-c',
-                                  "data load -f #{trace.path}; lf fdxb demod", in: File::NULL, out: output, err: output)
+              executable = opts.fetch(:executable, 'proxmark3').to_s
+              begin
+                pid = Process.spawn(executable, '--incognito', '-c',
+                                    "data load -f #{trace.path}; lf fdxb demod", in: File::NULL, out: output, err: output)
+              rescue Errno::ENOENT
+                raise IOError, "proxmark3 executable #{executable.inspect} not found; install the optional proxmark3 client or set executable: to its path"
+              end
               deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + duration
               begin
                 loop do
@@ -303,6 +310,7 @@ module PWN
             # file: explicit .pm3 signed integer AMPLITUDE trace, not SDR IQ; no hardware access.
             # Valid CRC16 required. Returns national/country ID, animal and data-block flags.
             # executable: 'proxmark3'; duration: 30s deadline; stop: callable; output/on_frame/log_file.
+            # Missing executable raises IOError with install/path guidance; already-stopped replay never spawns.
             # PM3 mode is finite offline replay; no ISO14443/ISO15693/EPC Gen2 coverage.
             # carrier_hz: 125000 default; clocks_per_bit: 64 default, or 32/16.
             # threshold: 0.5 default, normalized envelope amplitude; tune to the received levels.

data/lib/pwn/sdr/decoder/rtl433.rb

@@ -206,10 +206,14 @@ module PWN
             command.push('-R', '0')
             ids.each { |id| command.push('-R', id.to_s) }
           end
+          raise IOError, 'rtl_433 replay cancelled' if opts[:stop]&.call
+
           count = 0
           output = opts.fetch(:output, $stdout)
           deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + duration
+          started = false
           Open3.popen3(*command) do |input, stdout, stderr, worker|
+            started = true
             input.close
             buffers = { stdout => +'', stderr => +'' }
             errors = +''
@@ -269,6 +273,10 @@ module PWN
             end
           end
           { protocol: 'RTL433', mode: :native, backend: 'rtl_433', frames: count, source: path }
+        rescue Errno::ENOENT
+          raise unless started == false
+
+          raise IOError, "rtl_433 executable #{command.first.inspect} not found; install the optional rtl_433 package or set executable: to its path"
         end
 
         public_class_method def self.detect(opts = {})
@@ -333,6 +341,7 @@ module PWN
             # Native mode is finite FILE replay only: file required, no auto RF/config loading.
             # Native options: format: :cu8/:cs16/:cf32, protocols: [positive native IDs],
             # executable: 'rtl_433', duration: 30 seconds (deadline), stop: callable.
+            # Missing executable raises IOError with install/path guidance; already-stopped replay never spawns.
             # Output is per-device native JSON, device_protocol preserves native numeric ID.
             # Individual sensors/integrity depend on installed version; mic absent means not-reported.
             # sample_rate: 250000 default, >=20000; threshold: 0.5 normalized envelope amplitude.

data/lib/pwn/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PWN
-  VERSION = '0.5.728'
+  VERSION = '0.5.729'
 end

data/spec/lib/pwn/sdr/decoder/rfid_spec.rb

@@ -3,7 +3,28 @@
 require 'spec_helper'
 
 describe PWN::SDR::Decoder::RFID do
-  it 'decodes independent ISO11784/11785 FDX-B amplitude captures with the native offline client' do
+  it 'reports an actionable missing native executable without emitting frames' do
+    Dir.mktmpdir('pwn-missing-backend-') do |dir|
+      executable = File.join(dir, 'proxmark3')
+      frames = []
+      output = StringIO.new
+      expect do
+        described_class.decode(mode: :fdxb_pm3, file: 'spec/fixtures/sdr/rfid/fdxb_animal.pm3',
+                               executable: executable, output: output, on_frame: ->(frame) { frames << frame })
+      end.to raise_error(IOError, /proxmark3.*not found.*install.*executable:/i)
+      expect(frames).to be_empty
+      expect(output.string).to be_empty
+    end
+  end
+
+  it 'cancels an already stopped native replay before spawning' do
+    expect(Process).not_to receive(:spawn)
+    expect do
+      described_class.decode(mode: :fdxb_pm3, file: 'spec/fixtures/sdr/rfid/fdxb_animal.pm3', stop: -> { true })
+    end.to raise_error(IOError, /cancelled/)
+  end
+
+  it 'decodes independent ISO11784/11785 FDX-B amplitude captures with the native offline client', :proxmark3_integration do
     %w[animal extended].each do |variant|
       frames = []
       result = described_class.decode(mode: :fdxb_pm3, file: "spec/fixtures/sdr/rfid/fdxb_#{variant}.pm3",
@@ -17,12 +38,16 @@ describe PWN::SDR::Decoder::RFID do
     end
   end
 
-  it 'rejects automatic RF and emits no identity for an incomplete native amplitude trace' do
+  it 'rejects automatic RF and supports cancellation without the native client' do
     allow(PWN::SDR::Decoder::Base).to receive(:run_iq).and_raise('unexpected automatic RF')
     expect { described_class.decode(mode: :fdxb_pm3) }.to raise_error(ArgumentError, /explicit/)
     path = 'spec/fixtures/sdr/rfid/fdxb_animal.pm3'
     expect { described_class.decode(mode: :fdxb_pm3, file: path, source: :rtl_sdr) }.to raise_error(ArgumentError, /live/)
     expect { described_class.decode(mode: :fdxb_pm3, file: path, stop: -> { true }) }.to raise_error(IOError, /cancelled/)
+  end
+
+  it 'emits no identity for an incomplete native amplitude trace', :proxmark3_integration do
+    path = 'spec/fixtures/sdr/rfid/fdxb_animal.pm3'
     Tempfile.create(['fdxb-short-', '.pm3']) do |file|
       file.write(File.readlines(path).first(100).join)
       file.flush

data/spec/lib/pwn/sdr/decoder/rtl433_spec.rb

@@ -3,6 +3,27 @@
 require 'spec_helper'
 
 describe PWN::SDR::Decoder::RTL433 do
+  it 'reports an actionable missing native executable without emitting frames' do
+    Dir.mktmpdir('pwn-missing-backend-') do |dir|
+      executable = File.join(dir, 'rtl_433')
+      frames = []
+      output = StringIO.new
+      expect do
+        described_class.decode(mode: :native, file: 'spec/fixtures/sdr/rtl433/toyota.cu8',
+                               executable: executable, output: output, on_frame: ->(frame) { frames << frame })
+      end.to raise_error(IOError, /rtl_433.*not found.*install.*executable:/i)
+      expect(frames).to be_empty
+      expect(output.string).to be_empty
+    end
+  end
+
+  it 'cancels an already stopped native replay before spawning' do
+    expect(Open3).not_to receive(:popen3)
+    expect do
+      described_class.decode(mode: :native, file: 'spec/fixtures/sdr/rtl433/toyota.cu8', stop: -> { true })
+    end.to raise_error(IOError, /cancelled/)
+  end
+
   it 'decodes six real over-air Acurite packets with payloads matching the upstream reference' do
     demod = described_class::AcuriteIQ.new(rate: 250_000)
     frames = []
@@ -30,7 +51,7 @@ describe PWN::SDR::Decoder::RTL433 do
     expect { described_class.decode(mode: :all) }.to raise_error(ArgumentError, /mode/)
   end
 
-  it 'replays OOK and FSK native catalogue decoders against published captures' do
+  it 'replays OOK and FSK native catalogue decoders against published captures', :rtl433_integration do
     %w[acurite_th_609_001 wh31 toyota].each do |name|
       frames = []
       result = described_class.decode(mode: :native, file: "spec/fixtures/sdr/rtl433/#{name}.cu8",
@@ -44,7 +65,7 @@ describe PWN::SDR::Decoder::RTL433 do
     end
   end
 
-  it 'requires explicit native files, validates formats and supports native protocol selection' do
+  it 'requires explicit native files and validates formats and protocol selection without the native client' do
     allow(PWN::SDR::Decoder::Base).to receive(:run_iq).and_raise('unexpected automatic RF')
     expect { described_class.decode(mode: :native) }.to raise_error(ArgumentError, /explicit file/)
     path = 'spec/fixtures/sdr/rtl433/toyota.cu8'
@@ -52,6 +73,10 @@ describe PWN::SDR::Decoder::RTL433 do
     expect { described_class.decode(mode: :native, file: path, source: :rtl_sdr) }.to raise_error(ArgumentError, /live source/)
     expect { described_class.decode(mode: :native, file: path, protocols: [0]) }.to raise_error(ArgumentError, /protocol/)
     expect { described_class.decode(mode: :native, file: path, stop: -> { true }) }.to raise_error(IOError, /cancelled/)
+  end
+
+  it 'supports native protocol selection', :rtl433_integration do
+    path = 'spec/fixtures/sdr/rtl433/toyota.cu8'
     expect(described_class.decode(mode: :native, file: path, protocols: [11], output: StringIO.new)[:frames]).to eq(0)
     expect(described_class.decode(mode: :native, file: path, protocols: [88], output: StringIO.new)[:frames]).to eq(1)
   end

data/spec/spec_helper.rb

@@ -19,6 +19,8 @@ Dir[File.join(__dir__, 'support', '**', '*.rb')].each { |f| require f }
 # ─────────────────────────────────────────────────────────────────────────────
 RSpec.configure do |config|
   config.filter_run_excluding :local_embeddings unless ENV['PWN_TEST_EMBED_ENDPOINT'] && ENV['PWN_SQLITE_VEC_EXTENSION']
+  config.filter_run_excluding :proxmark3_integration unless ENV['PWN_TEST_PROXMARK3'] == '1'
+  config.filter_run_excluding :rtl433_integration unless ENV['PWN_TEST_RTL433'] == '1'
 
   next if ENV['PWN_SPEC_VERBOSE']
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pwn
 version: !ruby/object:Gem::Version
-  version: 0.5.728
+  version: 0.5.729
 platform: ruby
 authors:
 - 0day Inc.