Add helper environment variable for debugging plugins

Setting the `AGEDEBUG` environment variable to `plugin` will cause all
plugin communications, as well as the plugin's stderr, to be printed to
the stderr of the parent process (e.g. rage).

Cargo.lock

@@ -97,6 +97,7 @@ dependencies = [
  "chacha20poly1305",
  "cookie-factory",
  "hkdf",
+ "io_tee",
  "nom",
  "rand 0.8.4",
  "secrecy",
@@ -1187,6 +1188,12 @@ dependencies = [
  "unic-langid",
 ]
 
+[[package]]
+name = "io_tee"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4b3f7cef34251886990511df1c61443aa928499d598a9473929ab5a90a527304"
+
 [[package]]
 name = "itertools"
 version = "0.10.1"

age-core/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to Rust's notion of
 to 1.0.0 are beta releases.
 
 ## [Unreleased]
+### Added
+- `age_core::io::{DebugReader, DebugWriter}`
+
+### Changed
+- `Connection::open` now returns the debugging-friendly concrete type
+  `Connection<DebugReader<ChildStdout>, DebugWriter<ChildStdin>>`.
 
 ## [0.7.1] - 2021-12-27
 ### Fixed

age-core/Cargo.toml

@@ -38,6 +38,7 @@ nom = { version = "7", default-features = false, features = ["alloc"] }
 secrecy = "0.8"
 
 # Plugin backend
+io_tee = "0.1.1"
 tempfile = { version = "3.2.0", optional = true }
 
 [features]

age-core/src/io.rs

@@ -0,0 +1,62 @@
+//! Common helpers for performing I/O.
+
+use std::io::{self, Read, Stderr, Write};
+
+use io_tee::{ReadExt, TeeReader, TeeWriter, WriteExt};
+
+/// A wrapper around a reader that optionally tees its input to `stderr` for this process.
+pub enum DebugReader<R: Read> {
+    Off(R),
+    On(TeeReader<R, Stderr>),
+}
+
+impl<R: Read> DebugReader<R> {
+    pub(crate) fn new(reader: R, debug_enabled: bool) -> Self {
+        if debug_enabled {
+            DebugReader::On(reader.tee_dbg())
+        } else {
+            DebugReader::Off(reader)
+        }
+    }
+}
+
+impl<R: Read> Read for DebugReader<R> {
+    fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
+        match self {
+            Self::Off(reader) => reader.read(buf),
+            Self::On(reader) => reader.read(buf),
+        }
+    }
+}
+
+/// A wrapper around a writer that optionally tees its output to `stderr` for this process.
+pub enum DebugWriter<W: Write> {
+    Off(W),
+    On(TeeWriter<W, Stderr>),
+}
+
+impl<W: Write> DebugWriter<W> {
+    pub(crate) fn new(writer: W, debug_enabled: bool) -> Self {
+        if debug_enabled {
+            DebugWriter::On(writer.tee_dbg())
+        } else {
+            DebugWriter::Off(writer)
+        }
+    }
+}
+
+impl<W: Write> Write for DebugWriter<W> {
+    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
+        match self {
+            Self::Off(writer) => writer.write(buf),
+            Self::On(writer) => writer.write(buf),
+        }
+    }
+
+    fn flush(&mut self) -> io::Result<()> {
+        match self {
+            Self::Off(writer) => writer.flush(),
+            Self::On(writer) => writer.flush(),
+        }
+    }
+}

age-core/src/lib.rs

@@ -12,6 +12,7 @@
 pub use secrecy;
 
 pub mod format;
+pub mod io;
 pub mod primitives;
 
 #[cfg(feature = "plugin")]

age-core/src/plugin.rs

@@ -5,13 +5,17 @@
 
 use rand::{thread_rng, Rng};
 use secrecy::Zeroize;
+use std::env;
 use std::fmt;
 use std::io::{self, BufRead, BufReader, Read, Write};
 use std::iter;
 use std::path::Path;
 use std::process::{ChildStdin, ChildStdout, Command, Stdio};
 
-use crate::format::{grease_the_joint, read, write, Stanza};
+use crate::{
+    format::{grease_the_joint, read, write, Stanza},
+    io::{DebugReader, DebugWriter},
+};
 
 pub const IDENTITY_V1: &str = "identity-v1";
 pub const RECIPIENT_V1: &str = "recipient-v1";
@@ -59,19 +63,31 @@ pub struct Connection<R: Read, W: Write> {
     _working_dir: Option<tempfile::TempDir>,
 }
 
-impl Connection<ChildStdout, ChildStdin> {
-    /// Start a plugin binary with the given state machine.
+impl Connection<DebugReader<ChildStdout>, DebugWriter<ChildStdin>> {
+    /// Starts a plugin binary with the given state machine.
+    ///
+    /// If the `AGEDEBUG` environment variable is set to `plugin`, then all messages sent
+    /// to and from the plugin, as well as anything the plugin prints to its `stderr`,
+    /// will be printed to the `stderr` of the parent process.
     pub fn open(binary: &Path, state_machine: &str) -> io::Result<Self> {
         let working_dir = tempfile::tempdir()?;
+        let debug_enabled = env::var("AGEDEBUG").map(|s| s == "plugin").unwrap_or(false);
         let process = Command::new(binary.canonicalize()?)
             .arg(format!("--age-plugin={}", state_machine))
             .current_dir(working_dir.path())
             .stdin(Stdio::piped())
             .stdout(Stdio::piped())
-            .stderr(Stdio::piped())
+            .stderr(if debug_enabled {
+                Stdio::inherit()
+            } else {
+                Stdio::null()
+            })
             .spawn()?;
-        let input = BufReader::new(process.stdout.expect("could open stdout"));
-        let output = process.stdin.expect("could open stdin");
+        let input = BufReader::new(DebugReader::new(
+            process.stdout.expect("could open stdout"),
+            debug_enabled,
+        ));
+        let output = DebugWriter::new(process.stdin.expect("could open stdin"), debug_enabled);
         Ok(Connection {
             input,
             output,

age-plugin/examples/age-plugin-unencrypted.rs

@@ -25,6 +25,7 @@ impl RecipientPluginV1 for RecipientPlugin {
         plugin_name: &str,
         _bytes: &[u8],
     ) -> Result<(), recipient::Error> {
+        eprintln!("age-plugin-unencrypted: RecipientPluginV1::add_recipient called");
         if plugin_name == PLUGIN_NAME {
             // A real plugin would store the recipient here.
             Ok(())
@@ -42,6 +43,7 @@ impl RecipientPluginV1 for RecipientPlugin {
         plugin_name: &str,
         _bytes: &[u8],
     ) -> Result<(), recipient::Error> {
+        eprintln!("age-plugin-unencrypted: RecipientPluginV1::add_identity called");
         if plugin_name == PLUGIN_NAME {
             // A real plugin would store the identity.
             Ok(())
@@ -58,6 +60,7 @@ impl RecipientPluginV1 for RecipientPlugin {
         file_keys: Vec<FileKey>,
         mut callbacks: impl Callbacks<recipient::Error>,
     ) -> io::Result<Result<Vec<Vec<Stanza>>, Vec<recipient::Error>>> {
+        eprintln!("age-plugin-unencrypted: RecipientPluginV1::wrap_file_keys called");
         // A real plugin would wrap the file key here.
         let _ = callbacks
             .message("This plugin doesn't have any recipient-specific logic. It's unencrypted!")?;
@@ -84,6 +87,7 @@ impl IdentityPluginV1 for IdentityPlugin {
         plugin_name: &str,
         _bytes: &[u8],
     ) -> Result<(), identity::Error> {
+        eprintln!("age-plugin-unencrypted: IdentityPluginV1::add_identity called");
         if plugin_name == PLUGIN_NAME {
             // A real plugin would store the identity.
             Ok(())
@@ -100,6 +104,7 @@ impl IdentityPluginV1 for IdentityPlugin {
         files: Vec<Vec<Stanza>>,
         mut callbacks: impl Callbacks<identity::Error>,
     ) -> io::Result<HashMap<usize, Result<FileKey, Vec<identity::Error>>>> {
+        eprintln!("age-plugin-unencrypted: IdentityPluginV1::unwrap_file_keys called");
         let mut file_keys = HashMap::with_capacity(files.len());
         for (file_index, stanzas) in files.into_iter().enumerate() {
             for stanza in stanzas {

age/src/plugin.rs

@@ -2,6 +2,7 @@
 
 use age_core::{
     format::{FileKey, Stanza},
+    io::{DebugReader, DebugWriter},
     plugin::{Connection, IDENTITY_V1, RECIPIENT_V1},
     secrecy::ExposeSecret,
 };
@@ -163,7 +164,10 @@ impl Plugin {
             .map_err(|_| binary_name)
     }
 
-    fn connect(&self, state_machine: &str) -> io::Result<Connection<ChildStdout, ChildStdin>> {
+    fn connect(
+        &self,
+        state_machine: &str,
+    ) -> io::Result<Connection<DebugReader<ChildStdout>, DebugWriter<ChildStdin>>> {
         Connection::open(&self.0, state_machine)
     }
 }

fuzz-afl/Cargo.lock

@@ -63,6 +63,7 @@ dependencies = [
  "chacha20poly1305",
  "cookie-factory",
  "hkdf",
+ "io_tee",
  "nom",
  "rand 0.8.4",
  "secrecy",
@@ -497,6 +498,12 @@ dependencies = [
  "unic-langid",
 ]
 
+[[package]]
+name = "io_tee"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4b3f7cef34251886990511df1c61443aa928499d598a9473929ab5a90a527304"
+
 [[package]]
 name = "lazy_static"
 version = "1.4.0"

fuzz/Cargo.lock

@@ -50,6 +50,7 @@ dependencies = [
  "chacha20poly1305",
  "cookie-factory",
  "hkdf",
+ "io_tee",
  "nom",
  "rand 0.8.4",
  "secrecy",
@@ -437,6 +438,12 @@ dependencies = [
  "unic-langid",
 ]
 
+[[package]]
+name = "io_tee"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4b3f7cef34251886990511df1c61443aa928499d598a9473929ab5a90a527304"
+
 [[package]]
 name = "lazy_static"
 version = "1.4.0"