pwn 0.5.783 → 0.5.785

data/documentation/Plugin-Degradation.md

@@ -75,6 +75,18 @@ Required: `searchsploit`. Fallback: `intel_lookup`.
 
 Required: `subfinder`, `httpx`. Fallback: `NmapIt.scan` + `Corpus.get`.
 
+## pwn-plugins-yubikey
+
+Required: `ykman` (YubiKey Manager CLI). Preflight checks executable presence
+only; it never opens a device, requests a PIN, or performs a challenge. An `ok`
+status does not establish device availability, provisioning, or authorization.
+Hardware-backed vault operations require the selected YubiKey and its existing
+HMAC-SHA1 OTP slot; missing devices, denied touch, or authentication failures
+raise without falling back to a disk master key or software MFA. Restore device
+access before retrying. Dispatch blocks the handler when vault expansion fails;
+if output redaction fails after execution, it withholds the result and reports
+that the handler executed, so verify its effects before retrying.
+
 ## pwn-plugins-credentialattack
 
 Required: `hydra`, `john`, `hashcat`. Fallback: `pwn_eval` + `Corpus`.

data/documentation/Plugins.md

@@ -1,4 +1,4 @@
-# `PWN::Plugins` - All 107 Modules
+# `PWN::Plugins` - All 108 Modules
 
 Every plugin is a plain Ruby module of `public_class_method def self.x(opts = {})`
 methods with self-documenting `.help`. Source: `lib/pwn/plugins/*.rb`.
@@ -64,6 +64,7 @@ show-source PWN::Plugins::Fuzz.http
 |---|---|
 | `OAuth2` · `BasicAuth` · `AuthenticationHelper` | credential flows |
 | `Vault` | Local encrypted configuration and engagement loot helpers; not a HashiCorp Vault client |
+| [`YubiKey`](YubiKey.md) | Guarded ykman operations, HMAC-backed authenticated vaults and OATH codes |
 
 ### Hardware / Physical
 | Module | Purpose | Doc |
@@ -97,6 +98,6 @@ show-source PWN::Plugins::Fuzz.http
 
 ## Full alphabetical list
 
-`AFLplusplus AISandbox Android ArtifactRegistry Assembly AuthenticationHelper BareSIP BasicAuth BeEF BinaryAnalysis BinaryParser BinWorkspace BlackDuckBinaryAnalysis BurpSuite BusPirate Capability CapabilityBroker Char CredentialAttack CreditCard DAOLDAP DAOMongo DAOPostgres DAOSQLite3 Debugger DefectDojo DetectOS Detonate EIN Emulator ExploitDB ExploitDev FileFu Findings Frida Fuzz GDB GDBMI GDBMi Ghidra GhidraHeadless Git Github GoogleWorkspace HackerOne Handler Httpx Hunter IPInfo IRC Jenkins JiraDataCenter Jobs JSONPathify K8s Log MailAgent Metasploit MethodCatalog MitmProxy MonkeyPatch MSR206 NessusCloud NexposeVulnScan NmapIt Nuclei OAuth2 OCR OpenAPI OpenVAS Packet PDFParse Pony PreflightChecker ProcessTube PS PWNLogger RabbitMQ Radare2 Recon REDB REPL ROP Sandbox SBOM ScannableCodes Semgrep Serial Shodan SlackClient Sock Spider Sqlmap SSN ThreadPool Tor TransparentBrowser TTYSpinner TwitterAPI URIScheme Vault VIN Voice Volatility Vsphere XXD Zaproxy`
+`AFLplusplus AISandbox Android ArtifactRegistry Assembly AuthenticationHelper BareSIP BasicAuth BeEF BinaryAnalysis BinaryParser BinWorkspace BlackDuckBinaryAnalysis BurpSuite BusPirate Capability CapabilityBroker Char CredentialAttack CreditCard DAOLDAP DAOMongo DAOPostgres DAOSQLite3 Debugger DefectDojo DetectOS Detonate EIN Emulator ExploitDB ExploitDev FileFu Findings Frida Fuzz GDB GDBMI GDBMi Ghidra GhidraHeadless Git Github GoogleWorkspace HackerOne Handler Httpx Hunter IPInfo IRC Jenkins JiraDataCenter Jobs JSONPathify K8s Log MailAgent Metasploit MethodCatalog MitmProxy MonkeyPatch MSR206 NessusCloud NexposeVulnScan NmapIt Nuclei OAuth2 OCR OpenAPI OpenVAS Packet PDFParse Pony PreflightChecker ProcessTube PS PWNLogger RabbitMQ Radare2 Recon REDB REPL ROP Sandbox SBOM ScannableCodes Semgrep Serial Shodan SlackClient Sock Spider Sqlmap SSN ThreadPool Tor TransparentBrowser TTYSpinner TwitterAPI URIScheme Vault VIN Voice Volatility Vsphere XXD YubiKey Zaproxy`
 
 [← Home](Home.md) · [Diagrams](Diagrams.md)

data/documentation/Reinforcement-Learning.md

@@ -359,14 +359,13 @@ This is the live control list. Track the outcomes, not source comments.
 ```ruby
 # Seeded idempotently by PWN::Cron.install_defaults (pwn setup --migrate):
 PWN::Cron.install_defaults
-# -> curriculum_practice_nightly   0 3  * * *  Curriculum.practice(limit: 3)
-# -> curriculum_offline_judge     30 3  * * *  Curriculum.offline_judge(since_hours: 24, limit: 40)
-# -> curriculum_train_weekly       0 4  * * 0  Curriculum.train_and_gate(dry_run: true)  # false only with trainer+GPU
-# -> learning_consolidate_nightly  0 5  * * *  Learning.consolidate
+# -> session_cleanup  45 3 * * *  SessionCleanup.coordinate(dry_run: false)
 ```
 
-`install_defaults` treats the legacy name `offline_judge_nightly` as an alias of
-`curriculum_offline_judge` and will not double-seed the same slot.
+Curriculum practice, judge and training are explicit opt-ins, not seeded jobs.
+Select a template from `PWN::Cron::CURRICULUM_JOBS` and explicitly create it only
+when wanted (see [Cron](Cron.md)). Deletion survives repeated default installation
+and migration. Existing jobs and legacy aliases remain unchanged.
 `pwn setup` also starts the background cron worker so these YAML jobs fire
 without a per-job crontab line.
 

data/documentation/Runtime-Source-Protection.md

@@ -0,0 +1,162 @@
+# Runtime source protection
+
+> The mandatory worker boundary protects source and separates the finite
+> controller-state inventory below from tool writes. Checkpoint persistence also
+> uses pinned fd-relative no-follow directory operations. Process containment
+> owns detached tool jobs until mission completion/cancellation; it is not a
+> substitute for filesystem protection. Unspecified tool writes use
+> `~/.pwn/workspaces/runtime`. A path is writable outside that directory only
+> when the original operator request names it. An explicit destination grants
+> its parent even when that parent contains unrelated unreadable directories,
+> so a new file can be created there. Source checkouts stay read-only
+> even if named. See [Mission-Cancellation](Mission-Cancellation.md).
+
+A pwn-ai RequestRuntime dispatch executes its registered handler in an AISandbox
+worker. This boundary is mandatory even when the optional `ai_sandbox` profile
+is `off`. It covers shell, Ruby evaluation, other registered handlers, nested
+Dispatch calls, and fork/exec descendants including durable Jobs supervisors.
+Direct library calls made by an operator outside a RequestRuntime are not AI
+runtime tool calls and are unchanged. Legacy regex-ReAct Ruby and shell blocks
+also use the mandatory worker boundary (inside their enclosing mission); they
+no longer evaluate directly in the mission controller. The source-denial
+regression drives both languages through the actual Pry after_read hook.
+
+The host protects `/opt/pwn` when present and the real source root containing the
+loaded package. Linux Landlock ABI 3 or newer denies content writes, truncation,
+creation, removal, and linking under those roots. It resolves symlinks and `..`
+in the kernel: scripts are not rewritten. Repo reads remain available. The UI
+process does not change cwd. Relative reads use the task directory when it is
+outside protected source; otherwise they use `~/.pwn/workspaces/runtime`.
+Unnamed new files and temporary files go to that runtime directory. `/tmp`, the
+launch directory, and the rest of `~/.pwn` are not default write grants. A path
+named by the original operator request is created and granted; naming a file
+grants its parent so the file can be created. That parent grant is a directory
+rule, so a new file can still be created when the parent contains unrelated
+unreadable directories. Do not create the missing destination as a directory.
+Protected source is never granted.
+Standard null/zero/random devices are available. Other filesystem writes fail
+closed. This bounded write set permits hardlink-alias exclusion without scanning
+all mounted filesystems or changing checkout permissions.
+
+## Fail-closed requirements and restrictions
+
+- Supported syscall ABIs are Linux x86_64 and aarch64; libseccomp is required.
+  Missing enforcement prevents handler execution, rather than falling back to
+  regex checks or unsandboxed execution.
+- Landlock does not mediate file metadata changes. The worker therefore denies
+  chmod/chown, timestamp and extended-attribute mutation system-wide, including
+  outside source. Ordinary outside content writes and file creation still work.
+  Tools that need those metadata operations require a different supported
+  execution environment, not an exception to source protection.
+- Mount/namespace manipulation, ptrace/process-memory writes, and io_uring setup
+  are denied. Existing descriptors into protected roots are closed in the child.
+- Host preflight inventories multiply linked protected file identities and
+  excludes matching aliases in every writable tree. Aliases elsewhere receive
+  no write grant. Alias inventories are cached against source inode/link-count/
+  ctime fingerprints and writable-root identity; source link changes invalidate
+  that cache. Unreadable subtrees encountered during alias scanning are excluded.
+  This includes generated rdoc assets linked to installed gem assets; no source
+  files are chmodded, deleted, or automatically rewritten.
+- Protected root ancestors cannot grant inherited write permission without also
+  granting it to source. Creating a new sibling directly in such an ancestor is
+  consequently denied; use an existing writable outside directory.
+- This is a local process/filesystem effect boundary, not isolation of remote
+  services or already-running privileged daemons commanded over IPC/network.
+  It does not defend against a concurrent external actor replacing policy paths
+  or introducing new hardlink aliases after preflight. Do not run untrusted
+  external writers against the protected installation.
+- Handler-local Ruby variables and in-memory plugin state do not propagate back
+  to the UI. Persistent outputs and durable job state do. A handler that requires
+  process-local state across calls must not assume the old in-process evaluator.
+
+## Sandboxed swarm control
+
+`agent_spawn` and `agent_ask` handlers still run inside the mandatory worker.
+Their Swarm calls use a private socket to request only the controller's typed
+`spawn`/`ask` operations. The controller checks request tool permissions, rejects
+unknown fields/operations and traversal identifiers, and never invokes a
+worker-selected Registry handler, callback, Ruby expression, or filesystem path.
+Nested persona tools pass through Dispatch and get their own mandatory workers.
+
+Before launch the controller provisions the fixed swarm directory, persona file,
+and continuation lock with no-follow ancestry and regular-file/single-link
+checks. Workers cannot write the persona file, swarm subtree, or request
+checkpoint tree, nor rename their ancestors. No parent-directory write grant is
+added. Child Loop receipts remain controller-observed and are rechecked when
+merged into the parent. This preserves sandboxed spawn/ask state creation without
+allowing arbitrary controller callbacks.
+
+## Finite parent-writer audit
+
+The worker deny set now includes these controller-owned stores, even before a
+store exists. Missing paths still split the ancestor's Landlock grant, preventing
+first-write symlink planting. Existing inherited descriptors and hardlink aliases
+are covered by the same preflight as source. Store constants are resolved in the
+controller, not from model/tool output. Both lexical paths and canonical store
+aliases are denied, so a configured symlink cannot expose controller state
+through another otherwise writable directory.
+
+| Parent writer | Protected state |
+| --- | --- |
+| RequestRuntime checkpoints and EngagementMemory | Request-specific artifact root; checkpoint lock/temp/final persistence is also fd-relative/no-follow |
+| Sessions and SessionTrace | Sessions root, including support, leases, traces and requests |
+| Loop transcript compaction, ArtifactRegistry, swarm bus spills | Default artifacts root and configured ArtifactRegistry root |
+| Learning, Policy, Metrics, Reward, Mistakes, ToolGuard | Declared files/directories, learning and metrics subtrees; absent sibling staging paths cannot be planted |
+| Memory and MemoryIndex | Memory, archive and index files |
+| OpenGoal, Mission and TaskDAG | Goal file, missions and runs roots |
+| SkillReview and Curriculum | Ledger, curriculum/finetune roots, default/configured skill directories and loaded skill parents |
+| Provider credential persistence and local model configuration | Default vault/decryptor and configured driver paths |
+| Session redaction's Vault persistence | Engagements tree, legacy vault file and master-key path |
+| Log and Extrospection | Default logs and declared Extrospection stores |
+| Typed swarm controller | Swarm subtree, personas and continuation lock |
+
+The regression first reproduced an actual worker redirect of the transcript
+spill directory: after the worker returned, Loop created a file in synthetic
+protected source. It now receives permission denied, as does the earlier
+RequestRuntime spill reproducer. An independent fixture attempts 29 state
+mutations across existing directories/files and an absent staging path in both
+ordinary and symlinked-store layouts, while also creating a legitimate output in
+a disjoint workspace.
+
+Tools that directly mutate these controller stores are deliberately denied;
+only spawn/ask currently have the typed broker exception. This is not a promise
+that arbitrary in-process stateful plugins retain their old behavior. New parent
+writers or custom stores require an inventory update. The guarantee assumes a
+trusted initial controller layout and excludes concurrent external filesystem
+writers as described above; it is not a general host sandbox.
+
+## Completion evidence and uncertainty
+
+Required artifact names come from the original operator request (including
+explicit amendments), not cached model guesses or tool transcripts. Unquoted
+prose such as `i.e.` does not create a required file named `i.e`; explicitly
+quoted filenames are still honored.
+
+RequestRuntime snapshots required artifacts before dispatch and, on success,
+reads their stat, bounded head/tail and SHA-256 from the host. Successful actual
+file deltas count even if payload classification called the tool `eval` rather
+than `write`. Receipts accumulate across separate calls/iterations and survive
+transcript compaction. A failed tool, unchanged stale file, or tool stdout claim
+cannot create a receipt. Current bytes/identity must still match at completion.
+A combined write/read call does not require a ritual second call.
+
+Unknown side effects remain replay-fenced. A timeout/interruption or failed
+mutation is not erased by unrelated successful artifacts. On an attempted final
+answer the loop returns a structured `blocked` outcome with action ID and payload
+hash, instead of endlessly asking for rewrites. Exact-target operator-approved
+reconciliation is still required for genuine uncertainty; the existing HTTP
+reconciliation API is unchanged. Kernel/preflight failure before the handler
+starts is recorded as `rejected`, not falsely labeled an uncertain mutation.
+
+## Verification and deployment
+
+Offline specs exercise actual kernel workers, symlink/parent traversal denial,
+metadata denial, nested Dispatch, a detached Jobs worker, fail-closed unsupported
+protection/hardlinks, and the Loop → Dispatch → cumulative host receipt path with
+an actual generated PDF and separate text output. Provider messages in that
+replay are fixtures, not a live remote-model test.
+
+Source changes do not update an installed gem or a running pwn-ai process.
+Deploy the matching source/package files and restart the remote process through
+the operator's normal deployment procedure. Inspect the reported root/hardlink
+and kernel requirements before claiming that host is operational.

data/documentation/Transparent-Browser.md

@@ -52,5 +52,16 @@ All four honor `proxy:` (Burp / `tor`) so attribution stays controlled, reuse
 **one** browser handle across anchors, and `close` in an `ensure`. See
 [Extrospection](Extrospection.md) for the full loop.
 
+## Jev action loop
+
+`act` and `browser_act` run only when Open WebUI is configured and its model
+list contains a Jev model. Jev receives the visible control table and returns
+one operation plus one index: `CLICK`, `TYPE_TEXT`, `SELECT`, `SCROLL_UP`,
+`SCROLL_DOWN`, `WAIT`, `DONE`, or `BLOCKED`. It does not receive screenshots
+and it does not emit selectors. If the active pwn-ai model is not Jev, that
+model still writes the field text for `TYPE_TEXT`. Other pwn-ai work stays on
+the active model. This is the indexed-action idea from
+[jev-ultrafast](https://github.com/browser-use/jev-ultrafast), not TypeSafe's
+multi-head API and not a claim of its measured latency.
 
 [← Home](Home.md) · [BurpSuite](BurpSuite.md) · [WWW](WWW.md) · [Extrospection](Extrospection.md)

data/documentation/Troubleshooting.md

@@ -32,8 +32,9 @@ $ pwn setup --migrate --dry-run  # report only
 ```
 
 Corrupt / incompatible files are moved to `~/.pwn/quarantine/` (never
-deleted); a full timestamped backup is written to `~/.pwn/backup/<ts>/`
-first. Missing config keys added by the new release are deep-merged into
+deleted). Recovery copies go to one shared generation under `~/.pwn/backup/`
+first; the store keeps seven generations total. See
+[Backup Retention](Backup-Retention.md). Missing config keys added by the new release are deep-merged into
 your encrypted `~/.pwn/pwn.yaml` **under** your existing values. See
 [Installation § Upgrading](Installation.md#upgrading--pwn-state-migration-pwnmigrate).
 

data/documentation/What-is-PWN.md

@@ -12,7 +12,7 @@ with a **tool-calling AI agent** on top that can run the same methods.
 
 | Namespace | Count | What it is |
 |---|---|---|
-| `PWN::Plugins::*` | **107** | Wrappers for external and native tooling (Burp, Nmap, Metasploit, Shodan, browsers, serial, ...) |
+| `PWN::Plugins::*` | **108** | Wrappers for external and native tooling (Burp, Nmap, Metasploit, Shodan, browsers, serial, YubiKey, ...) |
 | `PWN::SAST::*` | **48** | Static-analysis rules across C/Java/Go/Python/Ruby/Scala/PHP/TS |
 | `PWN::AWS::*` | **90** | One module per AWS service for cloud enumeration |
 | `PWN::WWW::*` | **22** | Site-specific browser automations (HackerOne, BugCrowd, GitHub, Google, LinkedIn, ...) |
@@ -20,7 +20,7 @@ with a **tool-calling AI agent** on top that can run the same methods.
 | `PWN::FFI::*` | **11** | Native bindings (including DSPNative, Capstone and Keystone): Volk · Liquid · FFTW · RTLSdr · HackRF · AdalmPluto · SoapySDR · Stdio |
 | `PWN::AI::*` | **6** engines | OpenAI, Anthropic, Grok (OAuth device-flow), Gemini, Ollama, Open WebUI |
 | `bin/` (including `pwn-ai` and `pwn-capd`) | **56** | Headless CLI executables for CI/CD |
-| Agent toolsets | **16** · **150 tools** | terminal · pwn · memory · skills · sessions · learning · metrics · policy · extrospection · cron · swarm · reward · curriculum · http · mcp · manifest |
+| Agent toolsets | **16** · **152 tools** | terminal · pwn · memory · skills · sessions · learning · metrics · policy · extrospection · cron · swarm · reward · curriculum · http · mcp · manifest |
 
 ## Three ways to use it
 

data/documentation/YubiKey-Vaults.md

@@ -0,0 +1,183 @@
+# YubiKey-backed vaults and authentication
+
+See [YubiKey device operations](YubiKey.md) for the `ykman` command families,
+provisioning safeguards and supported hardware/firmware boundaries.
+
+## Encryption model
+
+This is **hardware-derived key encryption**, not bulk encryption inside the
+YubiKey. An already provisioned OTP HMAC-SHA1 slot answers a fresh random
+32-byte challenge. Ruby derives a 32-byte encryption key using HKDF-SHA256 with
+a fresh 16-byte salt and a domain-specific context, then uses AES-256-GCM with
+a fresh nonce and a full 16-byte tag. The HMAC response and derived key exist
+transiently in the Ruby process; the slot secret is not exported. Ruby does not
+promise zeroization of copied strings.
+
+The versioned `PWN-YUBIKEY-VAULT:1` envelope authenticates its metadata as AAD.
+The public challenge, salt, slot and optional serial are stored with ciphertext,
+not in a secret sidecar. Executable paths and timeout overrides are supplied
+by the caller, never loaded from ciphertext. PINs, OTP codes and serial numbers
+are not encryption keys. HMAC-SHA1 is used as the device PRF, not as an
+unauthenticated document hash; it provides at most the slot/response security,
+not 256 bits of entropy merely because AES-256 is used.
+
+Existing Base64 AES-256-CBC files and software loot remain readable. New
+hardware protection is opt-in; no existing configuration is migrated merely by
+loading PWN. A hardware envelope never falls back to a software master key,
+passphrase or unauthenticated plaintext when a device is missing or a tag fails.
+Do not combine a software key/IV or passphrase/keyring with hardware selection.
+
+## Use an existing HMAC slot
+
+Use a key model supporting OTP HMAC challenge-response. FIDO-only Security Keys
+do not support this vault backend. Set up the slot explicitly using the device
+management interface; prefer its physical-touch policy. PWN never provisions,
+replaces, unlocks by guessing, or resets a slot in order to open a vault.
+
+```ruby
+# The named file must already contain the plaintext you intend to encrypt.
+PWN::Plugins::Vault.create(file: '/path/to/private.yaml', yubikey: { slot: 2 })
+
+# With multiple devices, explicitly select the intended device serial.
+# Serial is a placeholder; replace locally, never paste secrets into a transcript.
+selector = { slot: 2, serial: '12345678' }
+PWN::Plugins::Vault.encrypt(file: '/path/to/another.yaml', yubikey: selector)
+
+# Read-only: decrypted data exists in memory, not an intermediate file.
+config = PWN::Plugins::Vault.dump(file: '/path/to/private.yaml'); nil
+
+# Mutate YAML in memory and atomically publish ciphertext, preserving the backend.
+PWN::Plugins::Vault.update(file: '/path/to/private.yaml') do |document|
+  document[:setting] = 'replacement'
+end
+```
+
+`yubikey` is a Hash accepting `slot` (integer 1 or 2; default 2), optional
+`serial`, optional local `ykman` executable path and bounded `timeout` seconds.
+`dump`, `decrypt`, `open_credentials` and hardware loot retrieval otherwise use
+the slot/serial stored in their envelope. Selecting another serial permits an
+explicitly provisioned recovery key with the same slot secret; the authentication
+tag still has to verify. A different slot requires explicit rewrapping.
+
+`encrypt_data` / `decrypt_data` are in-memory String APIs, including arbitrary
+binary data and empty plaintext. `seal_credentials` / `open_credentials` work
+on JSON-compatible credential values. Neither API opens the live configuration
+or writes keys. `file_encrypted?` / `hardware_encrypted?` inspect format only;
+they do not prove the device is present or that a ciphertext authenticates.
+
+`decrypt(file:)` explicitly replaces ciphertext with plaintext. Use `dump`
+instead when plaintext-on-disk is unnecessary. `edit` explicitly gives a private
+0600 temporary copy to the chosen editor under `~/.pwn/workspaces/runtime`, then
+removes its private working directory. The original stays encrypted until a
+successful re-encryption and atomic replacement. Editors are trusted programs:
+their external backups, OS swap, crash dumps and an abruptly killed process are
+not a secure-erasure guarantee. The curses `/vault edit` editor works in memory
+and writes only ciphertext. Built-in file writers share its parent-directory
+advisory lock across the final baseline check and atomic rename. A stale edit
+raises rather than overwriting a newer publication. This is not a filesystem
+compare-and-swap guarantee against external writers that ignore the lock.
+
+## Conversion and recovery
+
+Before converting a legacy vault, retain its verified encrypted backup and
+legacy decryptor somewhere secure. Conversion is explicit:
+
+```ruby
+PWN::Plugins::Vault.refresh_encryption_secrets(
+  file: '/path/to/legacy.yaml',
+  key: legacy_key, iv: legacy_iv,
+  new_yubikey: { slot: 2 }
+)
+```
+
+No temporary plaintext is published during conversion. On an existing hardware
+vault, `refresh_encryption_secrets(file:)` rewraps with fresh challenge/salt/nonce;
+it does **not** change the device secret. Supply `new_yubikey:` to move to another
+already provisioned slot/device while the old one is available. An explicit
+`new_yubikey:` must be a valid selector Hash; values such as `false` are rejected
+before opening the source vault, not treated as a request for software rotation.
+Hardware access or encryption failure leaves the original ciphertext intact. Old software
+sidecars and backups are not silently deleted; retire them deliberately after
+verifying recovery.
+
+Losing or reprogramming the only usable slot loses access. A ciphertext backup
+alone is not an independent recovery key. Establish and test an appropriate
+recovery device/secret before relying on hardware-only storage. Removing a
+YubiKey does not erase an already unlocked `PWN::Env` or revoke remote tokens;
+the application retains its in-memory configuration until exit/refresh.
+
+## Integration coverage
+
+| Entry point | Hardware behavior |
+|---|---|
+| `Vault.create/encrypt/decrypt/dump/edit/refresh_encryption_secrets` | Explicit creation/conversion, automatic envelope detection on read, backend-preserving edits |
+| `Vault.seal_credentials/open_credentials` | Authenticated in-memory hardware envelopes alongside existing passphrase/keyring formats |
+| `Vault.store/fetch/offer/ingest/expand/redact` | Optional hardware-protected engagement records; metadata-only `query` does not touch hardware |
+| `BasicAuth.encode(host:)` | Resolves matching protected loot through Vault, not a separate crypto implementation |
+| `Redaction.capture` and `Recon` loot ingestion | Explicit hardware selector for new captures; locked-store failure never creates a software-key fallback |
+| `Config.default_env/refresh_env` | Explicit hardware creation; hardware loading without a legacy decryptor sidecar |
+| `Migrate.vault_drift/backfill_vault` | Read/merge through Vault, preserving hardware format and user settings |
+| `pwn-vault`, `/vault edit`, `/model`, `/system-role`, mesh settings | Backend-aware encrypted persistence; no duplicate CBC-only write path |
+| OpenAI, Anthropic, Grok and Google Workspace OAuth persistence | In-memory configuration merge, ciphertext-only atomic save; hardware unavailability reports persistence failure |
+| `AuthenticationHelper.mfa` and supported WWW login methods | Explicit exact-account OATH code lookup, separate from ordinary manual MFA |
+
+Hardware-protected loot reads may require a touch, including explicit expansion
+and secret-value redaction. Do not enable it for unattended workflows expecting
+unbounded automatic access. Background metadata discovery and help do not unlock
+hardware. Existing unrelated records are not implicitly re-encrypted. Missing
+loot stores are empty; an existing unreadable store, malformed JSON, or invalid
+record/envelope shape raises `IOError` on reads and writes, including metadata
+queries. PWN does not infer a software backend from corrupt records, generate a
+replacement master key, or overwrite the damaged store. Restore a verified backup
+before retrying.
+
+## Explicit OATH authentication
+
+Select an exact account and authorize its effects explicitly:
+
+```ruby
+code = PWN::Plugins::AuthenticationHelper.mfa(
+  yubikey: { account: 'Example:alice', serial: '12345678', confirm: true }
+); nil
+```
+
+The same `yubikey:` Hash is accepted by GitHub, Synack, Twitter, BugCrowd,
+CoinbasePro and AppCobaltIO login methods. Lookup occurs at the authenticator
+form, not during option validation. Missing/nonliteral consent is rejected before
+password prompts or navigation. Device errors do not fall back to manual MFA;
+explicit manual tokens cannot be combined with the hardware selector. PayPal's
+current SMS-only adapter rejects OATH even with consent, and GitHub's SMS-only
+challenge does not accept an authenticator code.
+
+For `pwn_web_cache_deception`, add `--yubikey-account='Example:alice'`, optionally
+`--yubikey-serial=12345678`, and the required `--yubikey-confirm` to the normal
+arguments for a compatible login module. The flag authorizes HOTP counter
+advancement, remembered-key authentication and deletion of invalid cached keys
+during account listing, and upstream `ykman` cleanup that may delete a corrupted
+OATH credential. It is required for TOTP too; PWN never silently supplies consent.
+Confirmation/serial flags without an account are rejected before login.
+
+## Scope boundaries
+
+YubiKey FIDO management is not a WebAuthn relying-party implementation. Website
+passkey login still requires the browser's genuine security-key ceremony and
+site enrollment; a generated OATH code must never be submitted to an SMS-only
+challenge. PIV/OpenPGP key management does not export non-exportable keys or
+magically replace TLS, SSH-agent or GPG-provider integrations.
+
+Radio protocol keys, packet AES-CCM, TLS inspection certificates, OAuth PKCE,
+artifact hashes, cloud KMS/HSM API clients and Jenkins private-key uploads are
+not rewritten to use hardware-derived bytes. Their stored credentials can be
+protected through Vault where appropriate.
+
+Hardware-backed loot does not encrypt Recon's raw evidence/asset files, generic
+tool-result artifacts, exports, or the filesystem as a whole. Those retain their
+existing evidence-storage behavior and need separate access/at-rest protection.
+`recon_run` advertises the same nonsecret hardware selector as `loot_query` for
+harvested loot; metadata-only Vault queries do not unlock a device, but Dispatch's
+separate output-redaction step can still require access to protected secrets.
+
+Verification uses fake device processes and synthetic HMAC responses. Tests
+exercise real Ruby encryption, authentication failures, selector validation,
+subprocess cleanup and persistence entry points, but are not evidence of a
+physical YubiKey, live website authentication or every firmware variant.