pwn 0.5.783 → 0.5.785

data/etc/default_skills/pwn/plugins/yubikey/otp/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: pwn-plugins-yubikey-otp
+description: Use native OTP slots with explicit consent and readback.
+license: MIT
+allowed-tools: [pwn, pwn_eval]
+metadata:
+  bundled: true
+  preserve: true
+  module: PWN::Plugins::YubiKey::OTP
+  source: pwn/plugins/yubikey/otp.rb
+---
+
+# PWN::Plugins::YubiKey::OTP
+
+Native Ruby OTP application commands over the selected `Connection.exchange`
+boundary. No executable, subprocess, interpreter or network backend. HID framing
+and CRC validation belong to `Transport`; APDU status handling belongs to
+`Protocol`. The caller owns its transport connection.
+
+## Operations
+
+`execute(args: [...], connection: ...)` accepts argv **after** `otp`.
+`operations` lists ten leaves: `info`, `swap`, `ndef`, `delete`, `yubiotp`,
+`static`, `chalresp`, `calculate`, `hotp`, `settings`. Empty args return local
+metadata, not a device query. Unknown flags/commands and credential argv raise.
+
+Typed methods: `info`, `swap`, `delete_slot`, `configure_ndef`, `settings`,
+`provision_yubiotp`, `provision_static`, `provision_hotp`,
+`provision_challenge_response`, `challenge_response`, `calculate`, `help`,
+`authors`. Read runtime `help` for the full option contract.
+
+## Safe workflow
+
+1. Select the exact intended device using root transport selectors. Do not scan
+   or open real hardware in default tests. A model name does not establish its
+   supported/enabled applications.
+2. Read `info` without authentication. Firmware/status observations, not guessed
+   credentials, gate slot operations. NDEF additionally checks actual NFC support.
+3. Require literal `confirm: true` for every write or calculation. `--force` is
+   syntactic compatibility, not consent. Never provision to repair a vault-open
+   failure, stale response, wrong slot or missing device.
+4. Supply secrets as raw in-memory `key:`, `password:`, `private_id:`,
+   `access_code:` and `new_access_code:`. An explicit `secret_provider` receives
+   a missing secret's Symbol. No implicit terminal reads or factory secrets.
+   Generated material requires `secret_sink.call(field, raw_secret)`. The sink is
+   caller-controlled and must not log or publish secrets.
+5. `challenge_response(connection:, challenge:, slot: 2, confirm: true)` accepts
+   **1–64 raw bytes** and returns **20 raw HMAC-SHA1 bytes**. It never hex-encodes,
+   truncates to a TOTP or caches a response. Trailing zero challenges use distinct
+   padding. USB calculation requires OTP HID; smartcard calculation is NFC-only.
+6. `provision_challenge_response` defaults to touch-required and performs a fresh
+   native OpenSSL HMAC comparison against device output after programming and
+   separate status readback. Its default return is `:verified`; `details: true`
+   returns scoped verification metadata. `execute ['chalresp', '2']` returns the
+   metadata and follows prior CLI default
+   of no touch unless `--touch`. `--totp` explicitly decodes supplied Base32 key
+   text in memory; otherwise `key_encoding` defaults to raw. Keys 21–64 bytes
+   cannot fit this application; longer HMAC keys are SHA1-shortened per HMAC.
+7. Check `verification`, not only `verified`. Other OTP credentials/settings have
+   no secret/config export command: their verification is programming sequence
+   and slot-state readback, **not proof of keyboard output or secret equality**.
+   Known 5.0–5.4.2
+   smartcard zero-sequence responses are labeled `firmware_quirk_slot_state`;
+   HMAC provisioning must still pass the cryptographic challenge comparison.
+   Never claim that state metadata proves an NFC URI's emitted value. Failed or
+   stale readback raises an uncertainty error; no write is automatically replayed.
+
+## Formats and device restrictions
+
+- YubiOTP: public ID is lowercase modhex, private ID six raw bytes, AES key sixteen
+  raw bytes. `--serial-public-id` reads the actual API serial.
+- Static passwords: 1–38 characters; MODHEX, US, UK, DE, FR, IT, BEPO and NORMAN
+  scan-code maps. Unsupported characters fail before programming. The map data
+  retains Yubico's BSD license in source.
+- HOTP: raw HMAC key, 6/8 digits, initial counter divisible by 16 and at most
+  1048560; optional modhex/BCD token identifier.
+- NDEF: URI prefix compression or UTF8 English text, encoded prefix ≤54 bytes;
+  requires a configured slot on an NFC-capable key.
+- Settings replace omitted keyboard options with defaults, as the prior command
+  did; they do not infer hidden previous settings. Firmware 4.3.2–4.3.5 access-code
+  updates are refused without any delete/reprogram fallback.
+- Explicit YubiOTP `config_output` appends Yubico CSV only after status readback to
+  an owned, mode-0600 regular file with no symlinks/hardlinks and an exclusive
+  lock. CSV contains secrets. `--upload` is retired upstream and fails without
+  any network call. Generated secrets still require an explicit in-memory sink.
+
+## Evidence and references
+
+Offline specs use fake **connection wire responses**, real shared APDU codecs,
+RFC 2202 HMAC and RFC 6238 TOTP vectors, and an independently computed fixed
+52-byte configuration/CRC vector. These are not hardware interoperability tests.
+
+Protocol provenance: official yubikey-manager **5.9.1** source (`yubikit/yubiotp.py`,
+`yubikit/core/otp.py`, `ykman/scancodes`) and
+<https://developers.yubico.com/yubikey-personalization/Manuals/ykpersonalize.1.html>.
+Native reference header:
+<https://github.com/Yubico/yubikey-personalization/blob/master/ykcore/ykdef.h>.

data/etc/default_skills/pwn/plugins/yubikey/piv/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: pwn-plugins-yubikey-piv
+description: Native PIV APDU keys, certificates, objects and crypto.
+---
+
+# PWN::Plugins::YubiKey::PIV
+
+Use native Ruby/OpenSSL PIV operations through the parent YubiKey connection and
+Protocol codec. No command-line helper, Python runtime, device discovery during
+load, or private-key export is used.
+
+## Entry points
+
+- `execute(connection:, args:, ...)`: family-relative commands (`keys generate`,
+  `certificates request`, `objects export`, `access change-pin`, and so on).
+  Empty args or an access/keys/certificates/objects group return local help.
+- `operations`: implemented leaf catalog, separate from group/help paths.
+- `verify_pin(connection:, pin:, confirm: true)` and
+  `authenticate(connection:, management_key:, confirm: true)`.
+- `sign(connection:, slot:, algorithm:, message:, pin:, confirm: true)` supports
+  RSA PKCS1/PSS, P-256/P-384 ECDSA, and Ed25519. `hash_algorithm:` defaults SHA256;
+  `prehashed: true` accepts a correctly sized digest except Ed25519 always uses
+  the complete message. RSA `padding:` is `:pkcs1` or `:pss`.
+- `decrypt(connection:, slot:, ciphertext:, padding: :oaep, pin:, confirm: true)`
+  supports RSA OAEP (hash, MGF1 hash, label), PKCS1 and explicit raw `:none`.
+- `calculate_secret(connection:, slot:, peer_public_key:, pin:, confirm: true)`
+  supports P-256/P-384 and X25519. Treat its output as raw KDF input, not an
+  application encryption key.
+
+## Consent, secrets, and output
+
+Every mutation/authentication/private-key operation requires literal
+`confirm: true`. `--force` never grants consent. PINs, PUKs, management keys,
+passwords and replacements belong in options, never argv. Management keys are
+raw binary bytes, not hex strings. A `secret_provider` callable can supply a
+missing field by Symbol, after consent. Factory credentials are never guessed.
+
+`-` as an input filename requires binary `input:`; no implicit terminal read.
+`-` as output returns raw bytes. Named output requires confirmation and is
+created exclusively with mode 0600; existing files are never overwritten.
+`keys export` only returns the public key. `public_key_source:` explicitly
+selects `:metadata` (default, firmware 5.3+), `:attestation` (4.3+) or
+`:certificate`. There is no fallback after a failed key source.
+
+Firmware gates include ROCA-vulnerable RSA generation, FIPS restrictions,
+PIN/touch policies and biometric MATCH policy detection. RSA3072/RSA4096,
+Ed25519/X25519 and move/delete require firmware 5.7+. AES management keys require
+5.4+. Supply `fips_restrictions: true` when device capability metadata identifies
+a newer FIPS device.
+
+## Management and lifecycle
+
+`access change-management-key` accepts `new_management_key:` and `--algorithm`
+TDES/AES128/AES192/AES256. `--protect` stores the new key in PIN-protected PIVMAN
+data. Explicit `use_protected_key: true` enables PIN-protected or legacy
+PIN-derived management authentication; corrupt metadata is never repaired
+implicitly. Unprotected `--generate` requires `secret_sink.call(field, bytes)`
+to securely retain the generated key before installing it. Returned status
+never includes the management key.
+
+Key generation/import accepts PIN and touch policies. Import supports native
+OpenSSL PEM/DER private keys, including encrypted inputs through `password:`.
+Certificates support PEM/DER and PKCS12 import, compressed storage, device-signed
+self-signed certificates and PKCS10 requests. The host builds ASN.1, but only
+the device private-key operation signs the TBS/request bytes. The result is
+verified with OpenSSL before storage/return. Signed or corrupt CHUID objects
+are left intact. Certificate changes update unsigned CHUID GUIDs unless
+`--no-update-chuid` is passed. `objects generate` accepts CHUID and CCC only.
+Object writes are read back and compared before reporting success. Multi-APDU
+operations are not transactions: failures must be reconciled, not auto-retried.
+
+## Reset
+
+`execute(args: ['reset'], confirm: true)` only sends reset after checking for
+enrolled biometrics; it never guesses or blocks PINs/PUKs. Firmware requires
+both retry counters to be blocked. To explicitly authorize the destructive
+blocking process, also supply `block_retries: true`. This sends deliberately
+invalid empty padded PIN and PUK references until their counters reach zero,
+with bounded attempts and decreasing-counter checks, then resets PIV. This
+wipes application data and restores factory references; biometric/full-device
+reset restrictions are not bypassed. Never enable blocking as an automatic
+recovery action.
+
+## Implementation verification rules
+
+- Encode RSA public material as SubjectPublicKeyInfo with rsaEncryption and NULL
+  parameters. Generic OpenSSL loading can interpret a bare two-INTEGER RSA
+  public sequence as DH parameters; the RSA generation/import regressions catch
+  this ambiguity.
+- For RSA PKCS1 decryption on OpenSSL 3.2+, explicitly disable implicit rejection
+  for the ephemeral padding key. Otherwise an invalid block can return synthetic
+  plaintext instead of an exception. The paired negative test requires failure.
+- Keep temporary biometric PINs within one selected session: retain a
+  `PIV::Session.new(connection: connection, confirm: true)` and call its
+  `verify_uv(request_pin: true)` and `verify_temporary_pin(bytes)` methods on
+  that same instance. Do not assume reselection preserves a temporary PIN.
+- Separate the transport `serial:` selector from `certificate_serial:` when
+  constructing certificates. Tests preserve a zero-prefixed transport selector.
+
+## Offline verification and protocol references
+
+The paired RSpec uses literal APDU fixtures and a synthetic card boundary,
+independently reconstructs imported private keys, and validates actual RSA,
+ECDSA, Ed25519, ECDH, X25519, certificate and CSR cryptography with OpenSSL.
+It never accesses a physical reader, network, credentials or live home state.
+These fixtures demonstrate host protocol behavior, not physical interoperability.
+
+Wire specifications: NIST SP 800-73; Yubico yubikey-manager 5.9.1 source files
+`yubikit/piv.py`, `ykman/piv.py`, `ykman/_cli/piv.py`. Sources were consulted as
+specifications only, not imported or executed by the implementation.

data/etc/default_skills/pwn/plugins/yubikey/protocol/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: pwn-plugins-yubikey-protocol
+description: Native binary framing for YubiKey device protocols.
+license: MIT
+allowed-tools: [pwn, pwn_eval]
+metadata:
+  bundled: true
+  preserve: true
+  module: PWN::Plugins::YubiKey::Protocol
+  source: pwn/plugins/yubikey/protocol.rb
+---
+
+# Native YubiKey protocol framing
+
+Use the shared native Ruby codec rather than reconstructing binary headers in
+callers. Preserve raw bytes, repeated TLV tags and exact identifiers. Reject
+truncated/oversized frames before issuing device operations. This module does not
+run an executable or discover hardware merely when loaded.
+
+See `PWN::Plugins::YubiKey::Protocol.help` for the current public codec surface.
+Offline framing regressions are in `spec/lib/pwn/plugins/yubikey/protocol_spec.rb`.

data/etc/default_skills/pwn/plugins/yubikey/security_domain/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: pwn-plugins-yubikey-security-domain
+description: Manage native YubiKey Security Domain keys and channels.
+license: MIT
+allowed-tools: [pwn, pwn_eval]
+metadata:
+  bundled: true
+  preserve: true
+  module: PWN::Plugins::YubiKey::SecurityDomain
+  source: pwn/plugins/yubikey/security_domain.rb
+---
+
+# Native Security Domain
+
+Use `operations`, `help`, `execute(args: ..., connection: ...)` and
+`secure_connection(connection: ..., scp: ..., kvn: ..., confirm: true)`.
+Key and certificate values stay in Ruby/OpenSSL memory, never command-line
+arguments, environment variables, logs or subprocesses. No factory keys are
+assumed. Never print key objects, raw APDUs, or key-bearing options.
+
+## Secure connection
+
+- SCP03: explicit 16-byte `key_enc`, `key_mac`, optional `key_dek` binary Strings.
+- SCP11a/b/c: explicit `card_public_key` EC pin, or trusted `ca_certificates`
+  Array of X509 objects/PEM/DER; `card_certificates` is optional leaf-last chain.
+  With only CA anchors, fetch the card bundle and verify it before authentication.
+- SCP11a/c additionally require `oce_private_key` and leaf-last `oce_certificates`;
+  optional `oce_kid` and `oce_kvn` identify the card's OCE CA key.
+- Every handshake requires literal `confirm: true`. The returned connection
+  provides `exchange(protocol: :apdu, data:, timeout:)`, `descriptor`, `close`.
+- Receipt/card cryptogram failure, malformed response, bad R-MAC, uncertain I/O,
+  or exhausted counter closes the channel. No plaintext retry or fallback.
+- SCP11b authenticates the card only. SCP11c does not grant SD administrative
+  privilege. Use SCP03 or SCP11a for SD writes.
+
+## Administrative operations
+
+`execute` implements `info`, `reset`, `keys generate`, `keys import`,
+`keys export`, `keys delete`, `keys set-allowlist`, `keys set-certificate`,
+and `keys set-ca-issuer`. Group paths only return local help metadata.
+
+Pass KID/KVN as exact unsigned decimal or `0x` hexadecimal argv tokens. Imports
+and generation require KVN 1..127. KID 1 imports the complete SCP03 keyset from
+`key_enc`, `key_mac`, `key_dek`; KID 0x11/0x13/0x15 imports an EC `key`;
+KID 0x10/0x20..0x2f imports an EC public `key` or CA `certificate`.
+All key wrapping uses the authenticated session DEK. KCV verification is mandatory.
+Private-key imports may include a matching leaf-last `certificates` bundle;
+`ski` sets an explicit CA issuer identifier, and CA certificate SKI is extracted
+when available. These are multiple card writes, not an atomic transaction;
+do not retry automatically after any failure.
+
+`keys generate` and `keys export` return PEM bytes rather than writing files.
+An optional trailing `-` is only a compatibility marker. Export never extracts
+private keys. Use `certificates:` and `ski:` for certificate/issuer storage;
+allowlist serials may be argv integers or the `serials:` Array. Mutations require
+`confirm: true` and a genuine SCP03/SCP11a wrapper. `--force` is not consent.
+Reset is deliberately plaintext-only, follows the documented bounded key-blocking
+sequence, and reads back the default-key state before reporting success.
+
+Curves are prime256v1, secp384r1, secp521r1, brainpoolP256r1,
+brainpoolP384r1 and brainpoolP512r1. P-521 private-key import is explicitly
+unsupported because its 66-byte scalar is not block-aligned for the pinned SDK's
+un-padded CBC PUT KEY encoding; key generation and public-key handling work.
+All actual card curve/capacity support remains firmware-dependent.
+
+## Evidence boundary
+
+Wire behavior is based on GlobalPlatform Card Specification 2.3 Amendments D
+(SCP03 S8/AES128) and F v1.4 (SCP11), and Yubico's official yubikit 5.9.1
+`securitydomain.py` and `core/smartcard/scp.py`. These are references, not runtime
+dependencies. NIST SP 800-38B/RFC 4493 vectors and independent synthetic APDU
+peers validate the host cryptography offline; no physical device compatibility
+is claimed. No SCP03 S16, key diversification, CRL/OCSP retrieval, or guaranteed
+Ruby/OpenSSL memory zeroization is provided. Unauthenticated post-handshake
+status-only replies fail closed rather than releasing an unverified status.

data/etc/default_skills/pwn/plugins/yubikey/security_domain/scp/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: pwn-plugins-yubikey-security-domain-scp
+description: Use the native SCP03 and SCP11 APDU channel wrapper.
+license: MIT
+allowed-tools: [pwn, pwn_eval]
+metadata:
+  bundled: true
+  preserve: true
+  module: PWN::Plugins::YubiKey::SecurityDomain::SCP
+  source: pwn/plugins/yubikey/security_domain/scp.rb
+---
+
+# SCP channel implementation
+
+Prefer `SecurityDomain.secure_connection` to direct `SCP.open`. Both require
+explicit keys and literal confirmation; see the parent SecurityDomain skill
+for in-memory key and certificate options. Public-key pins and certificates are
+explicit trust decisions: do not discover a card key and silently pin it. Pass
+unencrypted PEM/DER or already-decrypted OpenSSL key objects; this module never
+prompts a terminal for encrypted-PEM passwords. This module never discovers devices
+or spawns executables. Returned APDU wrappers retain verified status words,
+serialize counter/MAC updates and invalidate themselves after any uncertain
+exchange or authentication failure. Do not reuse an underlying connection after
+handshake failure, and never replace a failed channel with plaintext I/O.
+
+SCP03 supports YubiKey S8/AES128: derives S-ENC/S-MAC/S-RMAC, verifies the full
+card cryptogram, authenticates the host at security level 0x33, uses CBC with
+counter-derived IVs and ISO7816 padding, and verifies R-MAC before decryption.
+SCP11a/b/c use native OpenSSL EC agreement, SHA256 X9.63 KDF and receipt CMAC;
+certificate trust is explicit, not silently bypassed. CA validation is offline
+and does not retrieve CRLs/OCSP. No guaranteed memory erasure is claimed.
+
+The descriptor advertises `extended_apdu: true`. The shared Protocol layer must
+honor this before command chaining: upstream SCP wraps the whole command before
+transport fragmentation, not each plaintext chunk. The wrapper accepts short and
+extended input and upgrades encrypted payloads over 255 bytes to extended frames.
+Transport `61xx` fragments are collected with raw GET RESPONSE before one R-MAC
+verification, preserving the counter/MAC chain. This is continuation retrieval,
+never authentication failure fallback. Fragment count, total response size and
+elapsed time are bounded. Noncanonical receipt encodings and padding longer than
+one AES block fail closed.
+
+References: GlobalPlatform Card Specification 2.3 Amendments D/F; official
+Yubico yubikit 5.9.1 core/smartcard/scp.py and smartcard/__init__.py. Tests use
+RFC 4493 known vectors and independent synthetic card-side cryptographic
+transcripts, not implementation-produced fixture outputs or real secrets.

data/etc/default_skills/pwn/plugins/yubikey/transport/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: pwn-plugins-yubikey-transport
+description: Use native HIDAPI and PC/SC YubiKey transports.
+license: MIT
+allowed-tools: [pwn, pwn_eval]
+metadata:
+  bundled: true
+  preserve: true
+  module: PWN::Plugins::YubiKey::Transport
+  source: pwn/plugins/yubikey/transport.rb
+---
+
+# Native YubiKey transport
+
+## Procedure
+
+1. `Transport.available?(application: :piv)` probes **host shared libraries only**.
+   Optional `backend: :hid` or `:pcsc` narrows the probe. Requiring the module and
+   checking availability never initialize HIDAPI, enumerate devices, establish a
+   PC/SC context, or open hardware. Availability does not prove permission,
+   service health, card presence, or application support.
+2. `Transport.devices(timeout: 5)` explicitly enumerates HID interfaces and
+   PC/SC readers. Reader descriptors do not prove that a card is inserted.
+   `backend:`, exact `serial:`, `reader:` and `device_path:` filter inventory.
+   This inventory call does not connect to cards to obtain their serials.
+3. `Transport.open(application: :otp, serial: '0007', timeout: 30)` selects one
+   endpoint or raises on absent/ambiguous selection. Preserve the operator's
+   exact serial String; never normalize, trim or parse it as an Integer.
+   Use `device_path:` or `reader:` for serial-less Security Key models. A reader
+   explicitly selects PC/SC, including OTP/management smartcard variants. Generic
+   NFC readers require explicit selection. Default OTP/FIDO prefers matching HID;
+   other applications prefer PC/SC. PC/SC ownership is exclusive, with no shared
+   fallback, process killing, automatic authentication or command replay.
+4. Call `connection.exchange(opts)` and always close in `ensure`. The descriptor's
+   `:protocol` is authoritative:
+   - `:otp`: `command:` byte, binary `data:` up to 64 bytes, optional
+     `response_length:`. CRC is checked and removed; status writes require a
+     programming-sequence acknowledgment. Command `0` with empty data reads six
+     status bytes without writing a command. Supply expected data lengths whenever
+     known; variable-length replies require an unambiguous CRC/padding boundary.
+   - `:ctap`: `command:` in 1..127, excluding internal INIT/CANCEL/KEEPALIVE/ERROR,
+     binary `data:` up to 7609 bytes. `open` performs nonce-checked CTAPHID INIT and
+     exposes `:version` and `:capabilities`. Responses retain the CTAP status byte.
+   - `:apdu`: binary `data:` containing the complete C-APDU. The result is the
+     complete R-APDU **including SW1/SW2**; shared `Protocol.apdu` owns chaining,
+     GET RESPONSE and application-status validation.
+5. `timeout:` is a finite positive monotonic budget. Optional `cancelled:` is a
+   callable returning truthy to stop; `on_keepalive:` receives 1 (processing) or
+   2 (touch/user presence). Callbacks must be bounded and thread-safe. They run
+   on the connection's owner worker. Never log packet bodies or secret replies.
+
+## Lifecycle and limits
+
+- A transport error, interrupted exchange or deadline retires the connection.
+  CTAPHID CANCEL / OTP reset is sent serially after the current native call.
+  Application-error status bytes are returned unchanged and do not retire it.
+  Do not expect subsequent application cleanup on a retired connection to work.
+- `close` is idempotent. `:closed` means native cleanup completed; `:closing`
+  means it is deferred. Timed-out C calls retain their owned thread, buffers and
+  handle until the native call returns. Never kill that Ruby thread or close its
+  in-flight handle: this would risk a use-after-free and is not native cancellation.
+- HID interrupt reads use `hid_read_timeout`. HID feature/write calls and PC/SC
+  `SCardTransmit` have no portable hard deadline. `SCardCancel` does not universally
+  cancel transmit. A permanently stuck driver may retain a thread and native
+  resources indefinitely; a bounded Ruby waiter is not driver-independent abort.
+- Explicit serial selection may perform read-only OTP identity APDUs, with a
+  management-information fallback using shared Protocol codecs when OTP is
+  disabled. Unobservable identities fail closed; no serial is invented.
+- PC/SC `:transport` derives from the Yubico ATR USB/NFC distinction; it is not
+  cryptographic device/vendor attestation. HID transport is USB. NEO's historic
+  cached-programming-sequence workaround is not issued automatically; uncertain
+  acknowledgments fail rather than trigger an implicit write or retry.
+
+## Offline verification
+
+Run `bundle exec rspec spec/lib/pwn/plugins/yubikey/transport_spec.rb` and focused
+RuboCop on the paired source/spec. Default tests use fake native C-library/IO
+boundaries with independent fixed CTAPHID and OTP CRC/framing fixtures. They
+exercise ordering, bounds, exact selectors, platform ABI widths/wide strings,
+blocked-call ownership, cancellation, and native cleanup without real hardware.
+Linux library-symbol load checks are separate from physical interoperability;
+Windows/macOS ABI simulations are not tests executed on those operating systems.
+
+## Protocol provenance
+
+This is a native Ruby implementation, not a launcher or a vendored SDK runtime.
+Protocol references:
+
+- YubiKey Manager 5.9.1 `yubikit/core/otp.py`, `yubikit/yubiotp.py`, and
+  `ykman/pcsc/__init__.py` (read-only reference).
+- python-fido2 2.2.1 `fido2/hid/__init__.py` (read-only reference), and the
+  [FIDO HID protocol](https://fidoalliance.org/specs/fido-v2.1-ps-20210615/fido-client-to-authenticator-protocol-v2.1-ps-20210615.html#usb-hid).
+- [HIDAPI 0.14.0 C header](https://github.com/libusb/hidapi/blob/hidapi-0.14.0/hidapi/hidapi.h).
+- [PC/SC ABI definitions](https://github.com/LudovicRousseau/PCSC/blob/master/src/PCSC/wintypes.h):
+  Unix `DWORD=unsigned long`, Darwin `DWORD=uint32`, Windows handles pointer-sized;
+  exported PCI symbols avoid guessed structure packing.
+- [Microsoft SCardCancel](https://learn.microsoft.com/en-us/windows/win32/api/winscard/nf-winscard-scardcancel)
+  and [SCardTransmit](https://learn.microsoft.com/en-us/windows/win32/api/winscard/nf-winscard-scardtransmit).

data/etc/default_skills/pwn/redaction/SKILL.md

@@ -6,13 +6,14 @@ allowed-tools: [pwn, pwn_eval]
 metadata:
   bundled: true
   generated: true
+  preserve: true
   module: PWN::Redaction
   source: pwn/redaction.rb
 ---
 
 # PWN::Redaction
 
-Write-boundary redaction; reject cyclic or over-100-level containers before inspecting secrets. Never opens a credential store.
+Write-boundary redaction; reject cyclic or over-100-level containers before inspecting secrets. `redact` never opens a credential store; `capture` can explicitly store ordinary secret matches.
 
 ## When to use
 
@@ -26,6 +27,17 @@ Class methods take `(opts = {})` and read `opts`.
 
 ## How to call
 
+PINs, PUKs, MFA/OTP values, access codes, management keys, OATH secrets, static
+passwords and SCP key fields use the constant `[REDACTED]` mask in hashes and
+key-value text. Do not replace those masks with hash markers: low-entropy values
+can be brute-forced from unsalted digests. `capture` masks these fields without
+storing them. Ordinary API/password tokens retain the existing digest behavior.
+
+For other captured loot, pass `yubikey: {slot: 2, serial: '12345678', timeout: 30}`
+to select hardware encryption. Hardware capture failure must leave the returned
+text redacted and must never trigger software fallback. A returned capture
+reference is not proof of successful persistence; verify metadata separately.
+
 ```ruby
 PWN::Redaction.help
 PWN::Redaction.redact(opts)

data/lib/pwn/ai/agent/dispatch.rb

@@ -72,11 +72,14 @@ module PWN
           violation = JSONSchemer.schema(JSON.parse(JSON.generate(type_schema))).validate(JSON.parse(JSON.generate(args))).first
           return schema_denial(violation.transform_keys(&:to_sym)) if violation
 
-          blob = args.inspect
           if defined?(PWN::Plugins::Vault)
-            blob = PWN::Plugins::Vault.expand(text: blob)
-            args = expand_vault_args(args: args)
+            begin
+              args = expand_vault_args(args: args)
+            rescue StandardError
+              return JSON.generate(success: false, code: 'VAULT_EXPANSION_FAILED', error: 'Vault access failed; check the selected device and retry. The tool was not executed.')
+            end
           end
+          blob = args.inspect
           denied = Manifest.check(opts.merge(name: entry.name, args: args))
           return JSON.generate(denied) if denied
 
@@ -129,7 +132,11 @@ module PWN
           begin
             runtime = Thread.current[:pwn_request_runtime]
             result = if runtime
-                       runtime.execute_tool(name: entry.name, args: args, effect: effect(name: entry.name, args: args), action_id: tool_call[:id] || tool_call['id']) { entry.handler.call(args) }
+                       runtime.execute_tool(name: entry.name, args: args, effect: effect(name: entry.name, args: args), action_id: tool_call[:id] || tool_call['id']) do
+                         PWN::Plugins::AISandbox.protect_call(handler: { name: entry.name, args: args }, runtime: runtime, workspace: runtime.contract[:cwd], write_roots: runtime.contract[:required_artifacts]) do
+                           entry.handler.call(args)
+                         end
+                       end
                      else
                        entry.handler.call(args)
                      end
@@ -141,13 +148,18 @@ module PWN
           result = Result.page(value: result, entry: entry, session_id: opts[:session_id])
           result = ToolGuard.quarantine_output(text: result) if defined?(ToolGuard) && result.is_a?(String) && ToolGuard.respond_to?(:quarantine_output)
           note_taint(text: result)
-          if defined?(PWN::Plugins::Vault) && result.is_a?(String)
-            result = PWN::Plugins::Vault.redact(text: result)
-          elsif defined?(PWN::Plugins::Vault) && result.is_a?(Hash)
-            result = JSON.parse(PWN::Plugins::Vault.redact(text: JSON.generate(Result.utf8_value(value: result))))
+          begin
+            if defined?(PWN::Plugins::Vault) && result.is_a?(String)
+              result = PWN::Plugins::Vault.redact(text: result)
+            elsif defined?(PWN::Plugins::Vault) && (result.is_a?(Hash) || result.is_a?(Array))
+              result = JSON.parse(PWN::Plugins::Vault.redact(text: JSON.generate(Result.utf8_value(value: result))))
+            end
+          rescue StandardError
+            return JSON.generate(success: false, code: 'VAULT_REDACTION_FAILED', handler_executed: true,
+                                 error: 'Vault redaction failed; result withheld. The tool already executed; verify its effects before retrying.')
           end
           response = { success: true, result: result, effect: effect(name: entry.name, args: args) }
-          response[:success] = false if result.is_a?(Hash) && (result[:error] || result['error'] || result[:success] == false || result['success'] == false)
+          response[:success] = false if result.is_a?(Hash) && (result[:error] || result['error'] || result[:success] == false || result['success'] == false || result[:ok] == false || result['ok'] == false || (result.key?(:exit) && result[:exit] != 0) || (result.key?('exit') && result['exit'] != 0))
           response[:budget] = telemetry if telemetry
           if telemetry && telemetry[:remaining_s].zero?
             response[:success] = false
@@ -591,13 +603,12 @@ module PWN
 
         private_class_method def self.expand_vault_args(opts = {})
           args = opts[:args]
-          return args unless args.is_a?(Hash)
-
-          args.transform_values do |v|
-            v.is_a?(String) ? PWN::Plugins::Vault.expand(text: v) : v
+          case args
+          when Hash then args.transform_values { |value| expand_vault_args(args: value) }
+          when Array then args.map { |value| expand_vault_args(args: value) }
+          when String then PWN::Plugins::Vault.expand(text: args)
+          else args
           end
-        rescue StandardError
-          opts[:args]
         end
 
         private_class_method def self.note_taint(opts = {})

data/lib/pwn/ai/agent/extrospection.rb

@@ -3572,16 +3572,15 @@ module PWN
             [true, log]
           when :festival
             # Use plugin if text file available
-            tmp = File.join(Dir.tmpdir, "pwn_tts_#{Process.pid}.txt")
-            File.write(tmp, text)
+            require_relative '../../../../etc/default_cron/session_cleanup' unless defined?(PWN::SessionCleanup)
             begin
-              require 'pwn/plugins/voice' unless defined?(PWN::Plugins::Voice)
-              PWN::Plugins::Voice.text_to_speech(text_path: tmp)
-              [true, 'festival via PWN::Plugins::Voice']
+              PWN::SessionCleanup.temporary(bytes: text) do |tmp|
+                require 'pwn/plugins/voice' unless defined?(PWN::Plugins::Voice)
+                PWN::Plugins::Voice.text_to_speech(text_path: tmp)
+                [true, 'festival via PWN::Plugins::Voice']
+              end
             rescue StandardError => e
               [false, "#{e.class}: #{e.message}"]
-            ensure
-              FileUtils.rm_f(tmp)
             end
           else
             [false, "unsupported TTS engine: #{engine}"]