pwn 0.5.783 → 0.5.785

data/lib/pwn/version.rb

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

data/lib/pwn/www/app_cobalt_io.rb

@@ -5,6 +5,8 @@ require 'yaml'
 module PWN
   module WWW
     # This plugin supports app.cobalt.io actions.
+    # YubiKey OATH MFA requires explicit confirm: true because HOTP advances counters
+    # and protected OATH accounts may require authentication; no automatic repair or deletion occurs.
     module AppCobaltIO
       # Supported Method Parameters::
       # browser_obj = PWN::WWW::AppCobaltIO.open(
@@ -28,10 +30,13 @@ module PWN
       #   browser_obj: 'required - browser_obj returned from #open method',
       #   username: 'required - username',
       #   password: 'optional - passwd (will prompt if blank)',
-      #   mfa: 'optional - if true prompt for mfa token (defaults to false)'
+      #   mfa: 'optional - if true prompt for mfa token (defaults to false)',
+      #   yubikey: 'optional - Hash selecting an exact OATH account (required :account and literal :confirm true); optional :serial exact decimal String, :reader or :device_path nonempty control-free String, :connection native exchange object, :timeout finite positive seconds (default 30), in-memory :password or callable :secret_provider; serial/reader and reader/device_path are mutually exclusive; no OTP slot; explicit mfa/mfa_token values conflict'
       # )
 
       public_class_method def self.login(opts = {})
+        PWN::Plugins::AuthenticationHelper.validate_mfa_options(opts)
+        yubikey = opts[:yubikey]
         browser_obj = opts[:browser_obj]
         username = opts[:username].to_s.scrub.strip.chomp
         password = opts[:password]
@@ -54,9 +59,9 @@ module PWN
         # name: 'commit' doesn't work
         browser.button(index: 6).click! # no name or id in button element
 
-        if mfa
+        if mfa || !yubikey.nil?
           until browser.url == 'https://app.cobalt.io/dashboard'
-            browser.text_field(id: 'code').wait_until(&:present?).set(PWN::Plugins::AuthenticationHelper.mfa(prompt: 'enter mfa token'))
+            browser.text_field(id: 'code').wait_until(&:present?).set(PWN::Plugins::AuthenticationHelper.mfa(prompt: 'enter mfa token', yubikey: yubikey))
             browser.button(name: 'commit').click!
             sleep 3
           end
@@ -117,12 +122,18 @@ module PWN
             proxy: 'optional - scheme://proxy_host:port || tor'
           )
 
-          # Run login and return its result
+          # Log in with manual MFA or explicitly selected YubiKey OATH.
+          # YubiKey enables MFA even when mfa is false; failures never fall back to a prompt.
+          # Configure the service for an authenticator challenge, not SMS.
+          # Example yubikey: { account: 'EXACT_OATH_NAME', confirm: true, serial: '123456', timeout: 30 }
+          # Explicit consent is required: HOTP advances counters and protected OATH accounts may require authentication; no automatic repair or deletion occurs.
+          # Reject conflicting explicit tokens before any login action.
           #{self}.login(
             browser_obj: 'required - browser_obj returned from #open method',
             username: 'required - username value consumed by #login',
             password: 'optional - passwd (will prompt if blank)',
-            mfa: 'optional - if true prompt for mfa token (defaults to false)'
+            mfa: 'optional - if true prompt for mfa token (defaults to false)',
+            yubikey: 'optional - Hash selecting an exact OATH account (required :account and literal :confirm true); optional :serial exact decimal String, :reader or :device_path nonempty control-free String, :connection native exchange object, :timeout finite positive seconds (default 30), in-memory :password or callable :secret_provider; serial/reader and reader/device_path are mutually exclusive; no OTP slot; explicit mfa/mfa_token values conflict'
           )
 
           # Run logout and return its result

data/lib/pwn/www/bug_crowd.rb

@@ -5,6 +5,8 @@ require 'yaml'
 module PWN
   module WWW
     # This plugin supports bugcrowd.com actions.
+    # YubiKey OATH MFA requires explicit confirm: true because HOTP advances counters
+    # and protected OATH accounts may require authentication; no automatic repair or deletion occurs.
     module BugCrowd
       # Supported Method Parameters::
       # browser_obj = PWN::WWW::BugCrowd.open(
@@ -28,10 +30,13 @@ module PWN
       #   browser_obj: 'required - browser_obj returned from #open method',
       #   username: 'required - username',
       #   password: 'optional - passwd (will prompt if blank)',
-      #   mfa: 'optional - if true prompt for mfa token (defaults to false)'
+      #   mfa: 'optional - if true prompt for mfa token (defaults to false)',
+      #   yubikey: 'optional - Hash selecting an exact OATH account (required :account and literal :confirm true); optional :serial exact decimal String, :reader or :device_path nonempty control-free String, :connection native exchange object, :timeout finite positive seconds (default 30), in-memory :password or callable :secret_provider; serial/reader and reader/device_path are mutually exclusive; no OTP slot; explicit mfa/mfa_token values conflict'
       # )
 
       public_class_method def self.login(opts = {})
+        PWN::Plugins::AuthenticationHelper.validate_mfa_options(opts)
+        yubikey = opts[:yubikey]
         browser_obj = opts[:browser_obj]
         username = opts[:username].to_s.scrub.strip.chomp
         password = opts[:password]
@@ -51,9 +56,9 @@ module PWN
         browser.text_field(id: 'user_password').wait_until(&:present?).set(password)
         browser.button(name: 'button').click!
 
-        if mfa
+        if mfa || !yubikey.nil?
           until browser.url == 'https://bugcrowd.com/programs'
-            browser.text_field(name: 'otp_attempt').wait_until(&:present?).set(PWN::Plugins::AuthenticationHelper.mfa(prompt: 'enter mfa token'))
+            browser.text_field(name: 'otp_attempt').wait_until(&:present?).set(PWN::Plugins::AuthenticationHelper.mfa(prompt: 'enter mfa token', yubikey: yubikey))
             browser.button(name: 'commit').click!
             sleep 3
           end
@@ -114,12 +119,18 @@ module PWN
             proxy: 'optional - scheme://proxy_host:port || tor'
           )
 
-          # Run login and return its result
+          # Log in with manual MFA or explicitly selected YubiKey OATH.
+          # YubiKey enables MFA even when mfa is false; failures never fall back to a prompt.
+          # Configure the service for an authenticator challenge, not SMS.
+          # Example yubikey: { account: 'EXACT_OATH_NAME', confirm: true, serial: '123456', timeout: 30 }
+          # Explicit consent is required: HOTP advances counters and protected OATH accounts may require authentication; no automatic repair or deletion occurs.
+          # Reject conflicting explicit tokens before any login action.
           #{self}.login(
             browser_obj: 'required - browser_obj returned from #open method',
             username: 'required - username value consumed by #login',
             password: 'optional - passwd (will prompt if blank)',
-            mfa: 'optional - if true prompt for mfa token (defaults to false)'
+            mfa: 'optional - if true prompt for mfa token (defaults to false)',
+            yubikey: 'optional - Hash selecting an exact OATH account (required :account and literal :confirm true); optional :serial exact decimal String, :reader or :device_path nonempty control-free String, :connection native exchange object, :timeout finite positive seconds (default 30), in-memory :password or callable :secret_provider; serial/reader and reader/device_path are mutually exclusive; no OTP slot; explicit mfa/mfa_token values conflict'
           )
 
           # Run logout and return its result

data/lib/pwn/www/coinbase_pro.rb

@@ -5,6 +5,8 @@ require 'yaml'
 module PWN
   module WWW
     # This plugin supports tradingview.com actions.
+    # YubiKey OATH MFA requires explicit confirm: true because HOTP advances counters
+    # and protected OATH accounts may require authentication; no automatic repair or deletion occurs.
     module CoinbasePro
       # Supported Method Parameters::
       # browser_obj = PWN::WWW::CoinbasePro.open(
@@ -28,10 +30,13 @@ module PWN
       #   browser_obj: 'required - browser_obj returned from #open method',
       #   username: 'required - username',
       #   password: 'optional - passwd (will prompt if blank)',
-      #   mfa: 'optional - if true prompt for mfa token (defaults to false)'
+      #   mfa: 'optional - if true prompt for mfa token (defaults to false)',
+      #   yubikey: 'optional - Hash selecting an exact OATH account (required :account and literal :confirm true); optional :serial exact decimal String, :reader or :device_path nonempty control-free String, :connection native exchange object, :timeout finite positive seconds (default 30), in-memory :password or callable :secret_provider; serial/reader and reader/device_path are mutually exclusive; no OTP slot; explicit mfa/mfa_token values conflict'
       # )
 
       public_class_method def self.login(opts = {})
+        PWN::Plugins::AuthenticationHelper.validate_mfa_options(opts)
+        yubikey = opts[:yubikey]
         browser_obj = opts[:browser_obj]
         username = opts[:username].to_s.scrub.strip.chomp
         password = opts[:password]
@@ -52,9 +57,9 @@ module PWN
         browser.text_field(name: 'password').wait_until(&:present?).set(password)
         browser.button(text: 'Sign In').click!
 
-        if mfa
+        if mfa || !yubikey.nil?
           until browser.url.include?('https://pro.coinbase.com')
-            browser.text_field(name: 'token').wait_until(&:present?).set(PWN::Plugins::AuthenticationHelper.mfa(prompt: 'enter mfa token'))
+            browser.text_field(name: 'token').wait_until(&:present?).set(PWN::Plugins::AuthenticationHelper.mfa(prompt: 'enter mfa token', yubikey: yubikey))
             browser.button(text: 'Verify').click!
             sleep 3
           end
@@ -114,12 +119,18 @@ module PWN
             proxy: 'optional - scheme://proxy_host:port || tor'
           )
 
-          # Run login and return its result
+          # Log in with manual MFA or explicitly selected YubiKey OATH.
+          # YubiKey enables MFA even when mfa is false; failures never fall back to a prompt.
+          # Configure the service for an authenticator challenge, not SMS.
+          # Example yubikey: { account: 'EXACT_OATH_NAME', confirm: true, serial: '123456', timeout: 30 }
+          # Explicit consent is required: HOTP advances counters and protected OATH accounts may require authentication; no automatic repair or deletion occurs.
+          # Reject conflicting explicit tokens before any login action.
           #{self}.login(
             browser_obj: 'required - browser_obj returned from #open method',
             username: 'required - username value consumed by #login',
             password: 'optional - passwd (will prompt if blank)',
-            mfa: 'optional - if true prompt for mfa token (defaults to false)'
+            mfa: 'optional - if true prompt for mfa token (defaults to false)',
+            yubikey: 'optional - Hash selecting an exact OATH account (required :account and literal :confirm true); optional :serial exact decimal String, :reader or :device_path nonempty control-free String, :connection native exchange object, :timeout finite positive seconds (default 30), in-memory :password or callable :secret_provider; serial/reader and reader/device_path are mutually exclusive; no OTP slot; explicit mfa/mfa_token values conflict'
           )
 
           # Run logout and return its result

data/lib/pwn/www/github.rb

@@ -5,6 +5,8 @@ require 'yaml'
 module PWN
   module WWW
     # This plugin supports github.com actions.
+    # YubiKey OATH MFA requires explicit confirm: true because HOTP advances counters
+    # and protected OATH accounts may require authentication; no automatic repair or deletion occurs.
     module GitHub
       # Supported Method Parameters::
       # browser_obj = PWN::WWW::GitHub.open(
@@ -29,10 +31,12 @@ module PWN
       #   username: 'required - username',
       #   password: 'optional - passwd (will prompt if blank)',
       #   mfa: 'optional - MFA / TOTP token string, or true to prompt (defaults to false)',
-      #   mfa_token: 'optional - MFA / TOTP token used to reach a post-authenticated state'
+      #   mfa_token: 'optional - MFA / TOTP token used to reach a post-authenticated state',
+      #   yubikey: 'optional - Hash selecting an exact OATH account (required :account and literal :confirm true); optional :serial exact decimal String, :reader or :device_path nonempty control-free String, :connection native exchange object, :timeout finite positive seconds (default 30), in-memory :password or callable :secret_provider; serial/reader and reader/device_path are mutually exclusive; no OTP slot; explicit mfa/mfa_token values conflict'
       # )
 
       public_class_method def self.login(opts = {})
+        PWN::Plugins::AuthenticationHelper.validate_mfa_options(opts)
         browser_obj = opts[:browser_obj]
         username = opts[:username].to_s.scrub.strip.chomp
         password = opts[:password]
@@ -45,6 +49,7 @@ module PWN
           password = opts[:password].to_s.scrub.strip.chomp
         end
         mfa = opts[:mfa]
+        yubikey = opts[:yubikey]
         mfa_token = opts[:mfa_token].to_s.scrub.strip.chomp
         mfa_token = mfa.to_s.scrub.strip.chomp if mfa_token.empty? && mfa.is_a?(String)
 
@@ -54,7 +59,7 @@ module PWN
         browser.text_field(name: 'password').wait_until(&:present?).set(password)
         browser.input(name: 'commit').click!
 
-        if mfa || !mfa_token.empty?
+        if mfa || !mfa_token.empty? || !yubikey.nil?
           until browser.url == 'https://github.com/' ||
                 browser.url.include?('https://github.com/dashboard') ||
                 (
@@ -63,23 +68,28 @@ module PWN
                   !browser.url.include?('/session')
                 )
 
+            mfa_field = if browser.text_field(name: 'app_otp').exist?
+                          browser.text_field(name: 'app_otp')
+                        elsif browser.text_field(id: 'app_totp').exist?
+                          browser.text_field(id: 'app_totp')
+                        elsif browser.text_field(name: 'otp').exist?
+                          browser.text_field(name: 'otp')
+                        else
+                          raise ArgumentError, 'YubiKey OATH requires an authenticator challenge, not SMS' unless yubikey.nil?
+
+                          browser.text_field(name: 'sms_otp')
+                        end
+            mfa_field.wait_until(&:present?)
+
             token = if mfa_token.empty?
-                      PWN::Plugins::AuthenticationHelper.mfa(prompt: 'enter mfa token')
+                      PWN::Plugins::AuthenticationHelper.mfa(prompt: 'enter mfa token', yubikey: yubikey)
                     else
                       consumed = mfa_token
                       mfa_token = ''
                       consumed
                     end
 
-            if browser.text_field(name: 'app_otp').exist?
-              browser.text_field(name: 'app_otp').wait_until(&:present?).set(token)
-            elsif browser.text_field(id: 'app_totp').exist?
-              browser.text_field(id: 'app_totp').wait_until(&:present?).set(token)
-            elsif browser.text_field(name: 'otp').exist?
-              browser.text_field(name: 'otp').wait_until(&:present?).set(token)
-            else
-              browser.text_field(name: 'sms_otp').wait_until(&:present?).set(token)
-            end
+            mfa_field.set(token)
 
             if browser.input(name: 'commit').exist?
               browser.input(name: 'commit').click!
@@ -151,13 +161,19 @@ module PWN
             proxy: 'optional - scheme://proxy_host:port || tor'
           )
 
-          # Run login and return its result
+          # Log in with manual MFA or explicitly selected YubiKey OATH.
+          # YubiKey enables MFA even when mfa is false; failures never fall back to a prompt.
+          # Configure the service for an authenticator challenge, not SMS.
+          # Example yubikey: { account: 'EXACT_OATH_NAME', confirm: true, serial: '123456', timeout: 30 }
+          # Explicit consent is required: HOTP advances counters and protected OATH accounts may require authentication; no automatic repair or deletion occurs.
+          # Reject conflicting explicit tokens before any login action.
           #{self}.login(
             browser_obj: 'required - browser_obj returned from #open method',
             username: 'required - username value consumed by #login',
             password: 'optional - passwd (will prompt if blank)',
             mfa: 'optional - MFA / TOTP token string, or true to prompt (defaults to false)',
-            mfa_token: 'optional - MFA / TOTP token used to reach a post-authenticated state'
+            mfa_token: 'optional - MFA / TOTP token used to reach a post-authenticated state',
+            yubikey: 'optional - Hash selecting an exact OATH account (required :account and literal :confirm true); optional :serial exact decimal String, :reader or :device_path nonempty control-free String, :connection native exchange object, :timeout finite positive seconds (default 30), in-memory :password or callable :secret_provider; serial/reader and reader/device_path are mutually exclusive; no OTP slot; explicit mfa/mfa_token values conflict'
           )
 
           # Run logout and return its result

data/lib/pwn/www/paypal.rb

@@ -5,6 +5,9 @@ require 'yaml'
 module PWN
   module WWW
     # This plugin supports paypal.com actions.
+    # Its legacy login adapter selects SMS MFA; YubiKey OATH is unsupported even
+    # with confirm: true; it is rejected before login rather than submitting
+    # an authenticator code as SMS.
     module Paypal
       # Supported Method Parameters::
       # browser_obj = PWN::WWW::Paypal.open(
@@ -86,10 +89,14 @@ module PWN
       #   browser_obj: 'required - browser_obj returned from #open method',
       #   username: 'required - username (email address)',
       #   password: 'optional - passwd (will prompt if blank)',
-      #   mfa: 'optional - if true prompt for mfa token (defaults to false)'
+      #   mfa: 'optional - if true prompt for mfa token (defaults to false)',
+      #   yubikey: 'optional - rejected: exact OATH account Hash with :serial, :reader, :device_path, :connection, :timeout is unsupported even with confirm: true; this adapter is SMS-only; explicit mfa/mfa_token values conflict; omit to use manual SMS'
       # )
 
       public_class_method def self.login(opts = {})
+        PWN::Plugins::AuthenticationHelper.validate_mfa_options(opts)
+        raise ArgumentError, 'PayPal YubiKey OATH login is unsupported by this SMS-only browser adapter' unless opts[:yubikey].nil?
+
         browser_obj = opts[:browser_obj]
         username = opts[:username].to_s.scrub.strip.chomp
         password = opts[:password]
@@ -110,7 +117,7 @@ module PWN
         browser.button(id: 'btnLogin').click!
 
         if mfa
-          # Send code to SMS
+          # Send code to SMS; this legacy adapter does not select an OATH authenticator.
           browser.button(id: 'btnSelectSoftToken').wait_until(&:present?).click!
           until browser.url == 'https://www.paypal.com/myaccount/home'
             browser.text_field(id: 'security-code').wait_until(&:present?).set(PWN::Plugins::AuthenticationHelper.mfa(prompt: 'enter mfa token'))
@@ -188,12 +195,16 @@ module PWN
             mfa: 'optional - mfa value consumed by #signup'
           )
 
-          # Run login and return its result
+          # Log in using the existing manual SMS challenge.
+          # YubiKey OATH is unsupported even with confirm: true; this SMS-only browser adapter rejects it before login.
+          # Service-level authenticator availability does not establish a compatible adapter flow.
+          # Validate options and reject conflicting explicit tokens before any login action.
           #{self}.login(
             browser_obj: 'required - browser_obj returned from #open method',
             username: 'required - username (email address)',
             password: 'optional - passwd (will prompt if blank)',
-            mfa: 'optional - if true prompt for mfa token (defaults to false)'
+            mfa: 'optional - if true prompt for mfa token (defaults to false)',
+            yubikey: 'optional - rejected: exact OATH account Hash with :serial, :reader, :device_path, :connection, :timeout is unsupported even with confirm: true; this adapter is SMS-only; explicit mfa/mfa_token values conflict; omit to use manual SMS'
           )
 
           # Run logout and return its result

data/lib/pwn/www/synack.rb

@@ -5,6 +5,8 @@ require 'yaml'
 module PWN
   module WWW
     # This plugin supports platform.synack.com actions.
+    # YubiKey OATH MFA requires explicit confirm: true because HOTP advances counters
+    # and protected OATH accounts may require authentication; no automatic repair or deletion occurs.
     module Synack
       # Supported Method Parameters::
       # browser_obj = PWN::WWW::Synack.open(
@@ -28,10 +30,13 @@ module PWN
       #   browser_obj: 'required - browser_obj returned from #open method',
       #   username: 'required - username',
       #   password: 'optional - passwd (will prompt if blank)',
-      #   mfa: 'optional - if true prompt for mfa token (defaults to false)'
+      #   mfa: 'optional - if true prompt for mfa token (defaults to false)',
+      #   yubikey: 'optional - Hash selecting an exact OATH account (required :account and literal :confirm true); optional :serial exact decimal String, :reader or :device_path nonempty control-free String, :connection native exchange object, :timeout finite positive seconds (default 30), in-memory :password or callable :secret_provider; serial/reader and reader/device_path are mutually exclusive; no OTP slot; explicit mfa/mfa_token values conflict'
       # )
 
       public_class_method def self.login(opts = {})
+        PWN::Plugins::AuthenticationHelper.validate_mfa_options(opts)
+        yubikey = opts[:yubikey]
         browser_obj = opts[:browser_obj]
         username = opts[:username].to_s.scrub.strip.chomp
         password = opts[:password]
@@ -51,9 +56,9 @@ module PWN
         browser.text_field(name: 'password').wait_until(&:present?).set(password)
         browser.button(class: 'btn').click!
 
-        if mfa
+        if mfa || !yubikey.nil?
           until browser.url.include?('https://platform.synack.com')
-            browser.text_field(name: 'authy_token').wait_until(&:present?).set(PWN::Plugins::AuthenticationHelper.mfa(prompt: 'enter mfa token'))
+            browser.text_field(name: 'authy_token').wait_until(&:present?).set(PWN::Plugins::AuthenticationHelper.mfa(prompt: 'enter mfa token', yubikey: yubikey))
             browser.button(class: 'btn').click!
             sleep 3
           end
@@ -114,12 +119,18 @@ module PWN
             proxy: 'optional - scheme://proxy_host:port || tor'
           )
 
-          # Run login and return its result
+          # Log in with manual MFA or explicitly selected YubiKey OATH.
+          # YubiKey enables MFA even when mfa is false; failures never fall back to a prompt.
+          # Configure the service for an authenticator challenge, not SMS.
+          # Example yubikey: { account: 'EXACT_OATH_NAME', confirm: true, serial: '123456', timeout: 30 }
+          # Explicit consent is required: HOTP advances counters and protected OATH accounts may require authentication; no automatic repair or deletion occurs.
+          # Reject conflicting explicit tokens before any login action.
           #{self}.login(
             browser_obj: 'required - browser_obj returned from #open method',
             username: 'required - username value consumed by #login',
             password: 'optional - passwd (will prompt if blank)',
-            mfa: 'optional - if true prompt for mfa token (defaults to false)'
+            mfa: 'optional - if true prompt for mfa token (defaults to false)',
+            yubikey: 'optional - Hash selecting an exact OATH account (required :account and literal :confirm true); optional :serial exact decimal String, :reader or :device_path nonempty control-free String, :connection native exchange object, :timeout finite positive seconds (default 30), in-memory :password or callable :secret_provider; serial/reader and reader/device_path are mutually exclusive; no OTP slot; explicit mfa/mfa_token values conflict'
           )
 
           # Run logout and return its result

data/lib/pwn/www/twitter.rb

@@ -5,6 +5,8 @@ require 'yaml'
 module PWN
   module WWW
     # This plugin supports twitter.com actions.
+    # YubiKey OATH MFA requires explicit confirm: true because HOTP advances counters
+    # and protected OATH accounts may require authentication; no automatic repair or deletion occurs.
     module Twitter
       # Supported Method Parameters::
       # browser_obj = PWN::WWW::Twitter.open(
@@ -28,10 +30,13 @@ module PWN
       #   browser_obj: 'required - browser_obj returned from #open method',
       #   username: 'required - username',
       #   password: 'optional - passwd (will prompt if blank)',
-      #   mfa: 'optional - if true prompt for mfa token (defaults to false)'
+      #   mfa: 'optional - if true prompt for mfa token (defaults to false)',
+      #   yubikey: 'optional - Hash selecting an exact OATH account (required :account and literal :confirm true); optional :serial exact decimal String, :reader or :device_path nonempty control-free String, :connection native exchange object, :timeout finite positive seconds (default 30), in-memory :password or callable :secret_provider; serial/reader and reader/device_path are mutually exclusive; no OTP slot; explicit mfa/mfa_token values conflict'
       # )
 
       public_class_method def self.login(opts = {})
+        PWN::Plugins::AuthenticationHelper.validate_mfa_options(opts)
+        yubikey = opts[:yubikey]
         browser_obj = opts[:browser_obj]
         username = opts[:username].to_s.scrub.strip.chomp
         password = opts[:password]
@@ -45,17 +50,17 @@ module PWN
         end
         mfa = opts[:mfa]
 
-        browser_obj.goto('https://twitter.com/login')
+        browser.goto('https://twitter.com/login')
 
         browser.text_field(index: 2).wait_until(&:present?).set(username)
         browser.text_field(index: 3).wait_until(&:present?).set(password)
         browser.button(index: 1).click!
 
-        if mfa
+        if mfa || !yubikey.nil?
           until browser.url == 'https://twitter.com/' ||
                 browser.url == 'https://twitter.com/home'
 
-            browser.text_field(id: 'challenge_response').wait_until(&:present?).set(PWN::Plugins::AuthenticationHelper.mfa(prompt: 'enter mfa token'))
+            browser.text_field(id: 'challenge_response').wait_until(&:present?).set(PWN::Plugins::AuthenticationHelper.mfa(prompt: 'enter mfa token', yubikey: yubikey))
             browser.button(id: 'email_challenge_submit').click!
             sleep 3
           end
@@ -116,12 +121,18 @@ module PWN
             proxy: 'optional - scheme://proxy_host:port || tor'
           )
 
-          # Run login and return its result
+          # Log in with manual MFA or explicitly selected YubiKey OATH.
+          # YubiKey enables MFA even when mfa is false; failures never fall back to a prompt.
+          # Configure the service for an authenticator challenge, not SMS.
+          # Example yubikey: { account: 'EXACT_OATH_NAME', confirm: true, serial: '123456', timeout: 30 }
+          # Explicit consent is required: HOTP advances counters and protected OATH accounts may require authentication; no automatic repair or deletion occurs.
+          # Reject conflicting explicit tokens before any login action.
           #{self}.login(
             browser_obj: 'required - browser_obj returned from #open method',
             username: 'required - username value consumed by #login',
             password: 'optional - passwd (will prompt if blank)',
-            mfa: 'optional - if true prompt for mfa token (defaults to false)'
+            mfa: 'optional - if true prompt for mfa token (defaults to false)',
+            yubikey: 'optional - Hash selecting an exact OATH account (required :account and literal :confirm true); optional :serial exact decimal String, :reader or :device_path nonempty control-free String, :connection native exchange object, :timeout finite positive seconds (default 30), in-memory :password or callable :secret_provider; serial/reader and reader/device_path are mutually exclusive; no OTP slot; explicit mfa/mfa_token values conflict'
           )
 
           # Run logout and return its result

data/lib/pwn.rb

@@ -24,6 +24,7 @@ module PWN
   autoload :Memory, 'pwn/memory'
   autoload :MemoryIndex, 'pwn/memory_index'
   autoload :Migrate, 'pwn/migrate'
+  autoload :Backups, 'pwn/backups'
   autoload :ModuleSkills, 'pwn/module_skills'
   autoload :Sessions, 'pwn/sessions'
   autoload :SessionTrace, 'pwn/session_trace'

data/scripts/build_gate.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+# Run only the validation gate, never installation. Keep one bounded, private
+# log even when a terminal disconnects or the child exits without a summary.
+require 'fileutils'
+require 'open3'
+
+abort 'Usage: ruby scripts/build_gate.rb command [args...]' if ARGV.empty?
+
+limit = 1_048_576
+path = File.join(Dir.home, '.pwn', 'logs', 'build-gate.log')
+FileUtils.mkdir_p(File.dirname(path), mode: 0o700)
+File.open(path, File::RDWR | File::CREAT | File::NOFOLLOW, 0o600) do |log|
+  abort "Build gate already running; log: #{path}" unless log.flock(File::LOCK_EX | File::LOCK_NB)
+
+  log.chmod(0o600)
+  log.truncate(0)
+  log.sync = true
+  $stdout.sync = true
+  append = lambda do |bytes|
+    if log.size + bytes.bytesize > limit
+      log.rewind
+      retained = (log.read + bytes).byteslice(-limit, limit)
+      log.rewind
+      log.truncate(0)
+      log.write(retained)
+    else
+      log.seek(0, IO::SEEK_END)
+      log.write(bytes)
+    end
+  end
+  emit = lambda do |bytes|
+    append.call(bytes)
+    begin
+      $stdout.write(bytes)
+    rescue Errno::EPIPE, IOError
+      # Continue draining the child into the durable log after stream loss.
+      nil
+    end
+  end
+  emit.call("Build gate log: #{path} (last #{limit} bytes; replaced on next run)\n")
+  emit.call("Gate launcher: uid=#{Process.uid} ruby=#{RUBY_VERSION} cwd=#{Dir.pwd} HOME=#{Dir.home}\n")
+  status = nil
+  Open3.popen2e(*ARGV) do |input, output, waiter|
+    input.close
+    loop { emit.call(output.readpartial(16_384)) }
+  rescue EOFError
+    status = waiter.value
+  end
+  result = status.signaled? ? "signal=#{Signal.signame(status.termsig)}" : "exit=#{status.exitstatus}"
+  emit.call("\nBuild gate #{result}\n")
+  unless status.success?
+    log.rewind
+    tail = log.read.byteslice(-16_384, 16_384) || log.tap(&:rewind).read
+    warn "\nBuild gate failed (#{result}). Build gate log: #{path}\n#{tail}"
+  end
+  exit(status.exitstatus || (128 + status.termsig))
+end

data/spec/documentation/installation_md_spec.rb

@@ -66,7 +66,7 @@ RSpec.describe 'documentation/Installation.md' do
     it 'programmatic API section is truthful' do
       expect(PWN::Setup).to respond_to(:check, :deps, :list_profiles, :pkg_manager, :migrate)
       expect(PWN::Setup.check(io: StringIO.new).keys)
-        .to eq(%i[ok native_gems_missing toolchain_missing state pkg_manager os arch])
+        .to eq(%i[ok native_gems_missing toolchain_missing state pkg_manager os arch native_libraries_missing])
       expect(PWN::Setup.pkg_manager.keys).to eq(%i[key install sudo])
       expect(PWN::Setup.constants).to include(:NATIVE_GEMS, :TOOLCHAIN, :PROFILES)
     end