pwn 0.5.784 → 0.5.785

data/documentation/Mission-Cancellation.md

@@ -0,0 +1,134 @@
+# Mission process lifetime and cancellation
+
+## Implemented boundary
+
+The curses ordinary-request path, local slash-command workers, each curses
+swarm job, and the non-curses `pwn_ai_run_steerable` entrypoint execute provider,
+controller, and tool work
+in a mission-owned Linux PID namespace. CTRL+C kills
+namespace PID 1 through a pidfd, waits for its supervisor to reap it, joins the
+IPC reader, and only then releases the UI's running state. A process group is
+not the ownership boundary: setsid, double forks, and nested child namespaces
+remain descendants of the mission namespace. Other sessions and unrelated
+processes are not signalled.
+
+There is no systemd, cgroup, application compiler, or PGID fallback.
+`PWN::AI::Agent::MissionNamespace` is Ruby code using stdlib Fiddle for Linux pidfds and
+process-death signals. Its runtime prerequisite is **util-linux `unshare`**
+(`pwn setup --profile ai`). Linux user/PID namespaces and pidfds must be enabled;
+unsupported kernels or local policy fail closed with setup guidance.
+
+Ruby recreates its timer thread after fork, so creating a user namespace from a
+Ruby fork is not supported. For ordinary launches the controller **execs** an
+`unshare --user --map-current-user --keep-caps` supervisor. That fresh Ruby
+supervisor creates a PID namespace and forks its init. It passes a pidfd back
+through a private Unix socket; the init waits for acknowledgement before running
+any request. Killing the supervisor also kills its init through PDEATHSIG.
+The controller, its cwd, and unrelated embedded PWN REPL modes are unchanged.
+
+Curses/native, legacy, slash, swarm and one-shot CLI requests use named,
+serializable descriptors, not serialized Ruby closures. Configuration, loaded
+skill metadata and routing context travel as typed JSON over inherited private
+sockets, never in argv or plaintext staging files. RequestRuntime's tool-worker
+snapshot excludes locks and caller cancellation callbacks; the enclosing owner
+provides cancellation. Replies and events remain JSON with generation fencing.
+Loaded Ruby skill scripts are required in the worker. Embedders with additional
+trusted plugin initializers can explicitly set
+`PWN::AI::Agent::MissionNamespace.bootstrap_requires = ['/absolute/plugin/bootstrap.rb']`.
+Arbitrary monkey patches, IO objects and Proc values are not serializable.
+
+For applications explicitly launched in a single-identity user namespace,
+MissionNamespace can fork its PID supervisor directly. This preserves trusted
+in-memory Ruby closures without calling unshare(NEWUSER) from Ruby. The caller
+must bootstrap explicitly with `unshare --user --map-current-user --keep-caps`;
+there is no automatic re-exec of an embedded application. The unit-test runner
+uses this real-kernel mode for in-memory mocks; exec/PTy fixtures explicitly
+force the ordinary descriptor path. Both paths create a real per-mission PID
+namespace and reject unavailable containment.
+
+Ordinary-request events carry a generation; swarm child messages carry job
+IDs, and console swarm callbacks carry an epoch invalidated by CTRL+C.
+Provider calls, including ordinary-request title refresh, remain in the child.
+Steering uses a separate JSON control pipe. The UI never deserializes Ruby
+objects from the child.
+
+## Detached jobs
+
+Detached jobs started by a tool inside a mission inherit that mission's
+namespace. They can continue after the individual tool returns, but **not**
+after mission completion, cancellation, or namespace-owner death. Normal
+mission completion also tears down remaining detached descendants. This is
+intentionally different from cross-session durable jobs. A standalone
+`AISandbox.protect_call` without an enclosing mission creates its own namespace
+and ends that lifetime when the call ends.
+
+Existing files and already-submitted remote operations are not rolled back.
+The local process guarantee does not revoke work accepted by an external
+service or remote host. Kernel-blocked uninterruptible I/O may delay reaping;
+the UI must remain busy rather than claim readiness early.
+
+## Controller-state separation
+
+Tool workers are denied writes to their RequestRuntime artifact/checkpoint
+root, including its spill directories and inherited descriptors. The actual
+worker-symlink -> parent-spill reproducer now fails at the worker's symlink
+with permission denied, and the synthetic source directory remains unchanged.
+The audited controller stores (sessions/traces, transcript artifacts,
+learning/policy/metrics, skills, logs, vault/configuration and mission state) are
+also excluded from worker grants. See the finite writer checklist in
+[Runtime-Source-Protection](Runtime-Source-Protection.md). Unspecified tool
+writes stay in `~/.pwn/workspaces/runtime`; another path is allowed only when
+the original operator request names it. Naming a missing file grants its parent,
+including when that parent contains unrelated unreadable directories, so the
+named file can be created. Controller state and tool output
+workspaces must be disjoint: a parent directory containing protected state
+cannot safely receive a broad Landlock write grant.
+
+## Verification and remaining scope
+
+RSpec owns the subprocess fixtures under `spec/support/harness/mission_*.rb`.
+`spec/integration/mission_cancel_spec.rb` exercises ordinary console next-request
+readiness and generation fencing, blocked-provider descendants, setsid escape,
+normal-exit double forks, unrelated-process preservation, mission-lived tool
+jobs, swarm cancellation, and fail-closed bootstrap. The namespace-denial
+fixture injects EPERM; namespace creation/teardown tests use the real kernel.
+`spec/integration/controller_spill_spec.rb` exercises actual RequestRuntime,
+Dispatch, sandbox restriction, and parent spill persistence with synthetic paths.
+
+Local slash-command maintenance/model/MCP workers now use the same hard process
+ownership. Their completion and UI-state messages are generation-fenced JSON;
+CTRL+C reaps the owner before returning ready. Maintenance already committed
+before cancellation is not rolled back. Model persistence decrypts and encrypts
+in memory; its staging file contains only ciphertext (or is empty). An offline
+SIGKILL regression interrupts encryption startup and verifies unchanged original
+ciphertext and absence of plaintext in the abandoned stage. Native curses PTY
+coverage includes cancellation during a blocked local command and a successful
+next mission.
+
+The legacy regex-ReAct fallback now runs its provider/parser/tool loop in the
+same MissionProcess owner. Completed history is transferred by JSON; native
+containment failures are terminal rather than an excuse to retry uncontained.
+Its actual after_read hook and PTY fixture cover detached Ruby/bash descendants,
+CTRL+C, no late writes and a successful next request. Workspace policy
+clarification does not block these offline gates.
+
+Native PTY regressions drive actual terminal CTRL+C through both the curses
+console and `pwn_ai_run_steerable`, assert no late descendant writes, then complete
+a second mission. Compiler-free package acceptance builds and installs into a
+private scratch GEM_HOME with compiler/make commands replaced by failing shims,
+activates that exact specification, checks an empty extensions list and no
+mission shared object, then executes a descriptor. Root and nonroot acceptance
+must be reported separately; these are offline checks, not provider or hardware
+evidence.
+
+Root loses host-wide DAC override when it enters a user namespace. A host-root
+mission therefore cannot traverse another user's mode-0700 home merely because
+its parent could. Test roots and deployment workspaces must be traversable by
+the mapped host identity. Do not chmod the operator's home to make a fixture
+pass. Filesystem fixtures beneath a private nonroot HOME must use that identity,
+including when their outer test runner is root. The integrated root fixture uses
+an isolated mount namespace: only its task-owned scratch layout is bound at a
+root-traversable path, with HOME, TMPDIR and inherited stdout/stderr logs opened
+inside that layout. Inherited logs opened below the inaccessible real home would
+correctly fail the protected-descriptor preflight. Neither the host mount table
+nor the operator's directory permissions are changed.

data/documentation/Operability.md

@@ -57,6 +57,23 @@ PKI DMs remain unsupported. Topic `region` is an opaque prefix, not the radio's
 regulatory-band setting; `radio_index` is distinct from legacy `channel_num`.
 See [General Usage](General-PWN-Usage.md) and [REPL](pwn-REPL.md).
 
+## Current runtime contract
+
+These are source contracts. A checkout edit does not change an installed gem or
+a process that is already running. Restart after installing the matching package.
+
+| Contract | Current behavior |
+| --- | --- |
+| Tool writes | Unspecified `pwn-ai` writes and `TMPDIR` use `~/.pwn/workspaces/runtime`. Another path is writable only when the original operator request names it, including `mv`/`to`. A missing file grants its parent so the file can be created; that parent is still granted when it contains unrelated unreadable directories. `/opt/pwn` and the loaded package stay read-only. |
+| Mission lifetime | CTRL+C kills the mission through `PWN::AI::Agent::MissionNamespace`. That owner is Ruby plus util-linux `unshare` and Linux pidfds. There is no compiled `pwn_mission` extension and no systemd fallback. |
+| Recovery copies | Every PWN recovery producer uses `PWN::Backups` and `~/.pwn/backup/`, seven generation folders total. Adjacent `.bak` files are not the current producer. |
+| Housekeeping | A fresh install seeds one internal `session_cleanup` coordinator. Curriculum jobs are not seeded. Housekeeping never uses systemd. |
+
+Details: [Runtime Source Protection](Runtime-Source-Protection.md),
+[Mission Cancellation](Mission-Cancellation.md),
+[Backup Retention](Backup-Retention.md), [Cron](Cron.md),
+[Persistence](Persistence.md).
+
 ## Deployment and safe verification
 
 1. Inspect the intended checkout and preserve existing changes before upgrading.

data/documentation/Persistence.md

@@ -7,8 +7,8 @@ external services and environment overrides can place evidence elsewhere.
 
 | Path | Owner | Format | Reset tool | Purpose |
 |---|---|---|---|---|
-| `pwn.yaml` | `PWN::Config` · `PWN::Plugins::Vault` | AES-encrypted YAML | `pwn-vault` | engines, keys, agent options |
-| `pwn.yaml.decryptor` | `PWN::Plugins::Vault` | key/IV | - | decrypts `pwn.yaml` (or set `PWN_DECRYPTOR_KEY`/`_IV`) |
+| `pwn.yaml` | `PWN::Config` · `PWN::Plugins::Vault` | Legacy AES-CBC or authenticated YubiKey-derived AES-GCM | `pwn-vault` | engines, keys, agent options; see [hardware vaults](YubiKey-Vaults.md) |
+| `pwn.yaml.decryptor` | `PWN::Plugins::Vault` | Legacy key/IV | - | decrypts legacy `pwn.yaml` (or set `PWN_DECRYPTOR_KEY`/`_IV`); absent for hardware-only vaults |
 | **`.schema`** | **`PWN::Migrate`** | JSON `{schema:,pwn_version:,at:}` | `pwn setup --migrate` | **schema stamp - drives the one-line drift warning on launch** |
 | `memory.json` | `PWN::Memory` | JSON array | `memory_clear` | facts · prefs · lessons · env - injected into every prompt |
 | `memory.idx` | `PWN::MemoryIndex` | JSON `{key → {sha,vec}}` | `PWN::MemoryIndex.reset` | local embedding index over `memory.json` - powers **relevance-ranked** MEMORY injection (incremental; only re-embeds changed entries) |
@@ -34,7 +34,8 @@ external services and environment overrides can place evidence elsewhere.
 | `curriculum/` | `PWN::AI::Agent::Curriculum` | JSONL | rm -rf | self-play reproducers · train/gate A/B eval sets |
 | `curriculum_kpi.jsonl` | `PWN::AI::Agent::Curriculum.practice_kpi` | JSONL | rm | outer curriculum KPI snapshots (repeating-mistake trend) |
 | `finetune/*.jsonl` | `Learning.export_finetune` · `Reward.export_dpo` | ShareGPT / OpenAI / DPO JSONL | `rm` | supervised + preference datasets - feed to a LoRA over the local model |
-| `backup/<ts>/` | `PWN::Migrate` | tree copy | rm -rf | timestamped snapshot taken before every `--migrate --fix` |
+| `workspaces/runtime/` | `PWN::Plugins::AISandbox` · `SessionCleanup.temporary` | files | operator-managed | Unspecified `pwn-ai` writes, `TMPDIR`, and registered disposable inputs such as Festival speech. Another path is writable only when the original request names it. `/opt/pwn` stays read-only |
+| `backup/<generation>/` | `PWN::Backups` | shared generations | see [Backup Retention](Backup-Retention.md) | One store, seven generation folders total, for every recovery producer including migrate |
 | `quarantine/` | `PWN::Migrate` | quarantined originals | rm -rf | corrupt/incompatible state files moved aside so the owner re-seeds |
 | `pwn_history` | Pry / pwn-ai | text | operator-managed | Shared durable input history at `~/.pwn/pwn_history` |
 
@@ -69,8 +70,9 @@ for the full `PWN::Migrate` API.
 tar czf pwn-state-$(date +%F).tgz -C "$HOME" .pwn
 ```
 
-`pwn setup --migrate --fix` also writes one automatically to
-`~/.pwn/backup/<timestamp>/` before touching anything.
+`pwn setup --migrate --fix` admits one generation through `PWN::Backups` under
+`~/.pwn/backup/` before it changes state. That store holds seven generations
+total, not a new unbounded tree per run. See [Backup Retention](Backup-Retention.md).
 
 ## Start fresh for a new engagement
 

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/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.