Some slight improvements

Author: cstamas

src/main/java/org/codehaus/plexus/components/secdispatcher/PinEntry.java

@@ -32,7 +32,9 @@
 import static java.util.Objects.requireNonNull;
 
 /**
- * Inspired by <a href="https://velvetcache.org/2023/03/26/a-peek-inside-pinentry/">A peek inside pinentry</a>
+ * Inspired by <a href="https://velvetcache.org/2023/03/26/a-peek-inside-pinentry/">A peek inside pinentry</a>.
+ * Also look at <a href="https://gorbe.io/posts/gnupg/pinentry/documentation/">Pinentry Documentation</a>.
+ * Finally, source mirror is at <a href="https://github.com/gpg/pinentry">gpg/pinentry</a>.
  */
 public class PinEntry {
     public enum Outcome {
@@ -43,59 +45,96 @@ public enum Outcome {
         FAILED;
     }
 
-    public record Result<T>(Outcome outcome, T payload) {}
+    public record Result(Outcome outcome, String payload) {}
 
     private final Logger logger = LoggerFactory.getLogger(getClass());
     private final String cmd;
     private final LinkedHashMap<String, String> commands;
 
+    /**
+     * Creates pin entry instance that will use the passed in cmd executable.
+     */
     public PinEntry(String cmd) {
         this.cmd = requireNonNull(cmd);
         this.commands = new LinkedHashMap<>();
     }
 
+    /**
+     * Sets a "stable key handle" for caching purposes. Optional.
+     */
     public PinEntry setKeyInfo(String keyInfo) {
         requireNonNull(keyInfo);
-        commands.put("SETKEYINFO", keyInfo);
         commands.put("OPTION", "allow-external-password-cache");
+        commands.put("SETKEYINFO", keyInfo);
         return this;
     }
 
+    /**
+     * Sets the OK button label, by default "Ok".
+     */
     public PinEntry setOk(String msg) {
         requireNonNull(msg);
         commands.put("SETOK", msg);
         return this;
     }
 
+    /**
+     * Sets the CANCEL button label, by default "Cancel".
+     */
     public PinEntry setCancel(String msg) {
         requireNonNull(msg);
         commands.put("SETCANCEL", msg);
         return this;
     }
 
+    /**
+     * Sets the window title.
+     */
     public PinEntry setTitle(String title) {
         requireNonNull(title);
         commands.put("SETTITLE", title);
         return this;
     }
 
+    /**
+     * Sets additional test in window.
+     */
     public PinEntry setDescription(String desc) {
         requireNonNull(desc);
         commands.put("SETDESC", desc);
         return this;
     }
 
+    /**
+     * Sets the prompt.
+     */
     public PinEntry setPrompt(String prompt) {
         requireNonNull(prompt);
         commands.put("SETPROMPT", prompt);
         return this;
     }
 
+    /**
+     * If set, window will show "Error: xxx", usable for second attempt (ie "bad password").
+     */
+    public PinEntry setError(String error) {
+        requireNonNull(error);
+        commands.put("SETERROR", error);
+        return this;
+    }
+
+    /**
+     * Usable with {@link #getPin()}, window will contain two input fields and will force user to type in same
+     * input in both fields, ie to "confirm" the pin.
+     */
     public PinEntry confirmPin() {
-        commands.put("SETREPEAT", cmd);
+        commands.put("SETREPEAT", null);
         return this;
     }
 
+    /**
+     * Sets the window timeout, if no button pressed and timeout passes, Result will by {@link Outcome#TIMEOUT}.
+     */
     public PinEntry setTimeout(Duration timeout) {
         long seconds = timeout.toSeconds();
         if (seconds < 0) {
@@ -105,22 +144,31 @@ public PinEntry setTimeout(Duration timeout) {
         return this;
     }
 
-    public Result<String> getPin() throws IOException {
+    /**
+     * Initiates a "get pin" dialogue with input field(s) using previously set options.
+     */
+    public Result getPin() throws IOException {
         commands.put("GETPIN", null);
         return execute();
     }
 
-    public Result<String> confirm() throws IOException {
+    /**
+     * Initiates a "confirmation" dialogue (no input) using previously set options.
+     */
+    public Result confirm() throws IOException {
         commands.put("CONFIRM", null);
         return execute();
     }
 
-    public Result<String> message() throws IOException {
+    /**
+     * Initiates a "message" dialogue (no input) using previously set options.
+     */
+    public Result message() throws IOException {
         commands.put("MESSAGE", null);
         return execute();
     }
 
-    private Result<String> execute() throws IOException {
+    private Result execute() throws IOException {
         Process process = new ProcessBuilder(cmd).start();
         BufferedReader reader = process.inputReader();
         BufferedWriter writer = process.outputWriter();
@@ -141,20 +189,20 @@ private Result<String> execute() throws IOException {
                 expectOK(reader);
             }
         }
-        Result<String> result = lastExpect(reader);
+        Result result = lastExpect(reader);
         writer.write("BYE");
         writer.newLine();
         writer.flush();
         try {
             process.waitFor(5, TimeUnit.SECONDS);
             int exitCode = process.exitValue();
             if (exitCode != 0) {
-                return new Result<>(Outcome.FAILED, "Exit code: " + exitCode);
+                return new Result(Outcome.FAILED, "Exit code: " + exitCode);
             } else {
                 return result;
             }
         } catch (Exception e) {
-            return new Result<>(Outcome.FAILED, e.getMessage());
+            return new Result(Outcome.FAILED, e.getMessage());
         }
     }
 
@@ -166,7 +214,7 @@ private void expectOK(BufferedReader in) throws IOException {
         }
     }
 
-    private Result<String> lastExpect(BufferedReader in) throws IOException {
+    private Result lastExpect(BufferedReader in) throws IOException {
         while (true) {
             String response = in.readLine();
             logger.debug("< {}", response);
@@ -178,47 +226,49 @@ private Result<String> lastExpect(BufferedReader in) throws IOException {
             }
             if (response.startsWith("ERR")) {
                 if (response.contains("83886142")) {
-                    return new Result<>(Outcome.TIMEOUT, response);
+                    return new Result(Outcome.TIMEOUT, response);
                 }
                 if (response.contains("83886179")) {
-                    return new Result<>(Outcome.CANCELED, response);
+                    return new Result(Outcome.CANCELED, response);
                 }
                 if (response.contains("83886194")) {
-                    return new Result<>(Outcome.NOT_CONFIRMED, response);
+                    return new Result(Outcome.NOT_CONFIRMED, response);
                 }
             }
             if (response.startsWith("D")) {
-                return new Result<>(Outcome.SUCCESS, response.substring(2));
+                return new Result(Outcome.SUCCESS, response.substring(2));
             }
             if (response.startsWith("OK")) {
-                return new Result<>(Outcome.SUCCESS, response);
+                return new Result(Outcome.SUCCESS, response);
             }
         }
     }
 
     public static void main(String[] args) throws IOException {
-        Result<String> pinResult = new PinEntry("/usr/bin/pinentry-gnome3")
-                .setTimeout(Duration.ofSeconds(5))
+        // check what pinentry apps you have and replace the execName
+        String cmd = "/usr/bin/pinentry-gnome3";
+        Result pinResult = new PinEntry(cmd)
+                .setTimeout(Duration.ofSeconds(15))
                 .setKeyInfo("maven:masterPassword")
                 .setTitle("Maven Master Password")
                 .setDescription("Please enter the Maven master password")
-                .setPrompt("Master password")
-                .setOk("Her you go!")
+                .setPrompt("Password")
+                .setOk("Here you go!")
                 .setCancel("Uh oh, rather not")
                 // .confirmPin() (will not let you through if you cannot type same thing twice)
                 .getPin();
         if (pinResult.outcome() == Outcome.SUCCESS) {
-            Result<String> confirmResult = new PinEntry("/usr/bin/pinentry-gnome3")
+            Result confirmResult = new PinEntry(cmd)
                     .setTitle("Password confirmation")
-                    .setDescription("Please confirm that the password you entered is correct")
-                    .setPrompt("Is the password '" + pinResult.payload() + "' the one you want?")
+                    .setPrompt("Please confirm the password")
+                    .setDescription("Is the password '" + pinResult.payload() + "' the one you want?")
                     .confirm();
             if (confirmResult.outcome() == Outcome.SUCCESS) {
-                new PinEntry("/usr/bin/pinentry-gnome3")
+                new PinEntry(cmd)
                         .setTitle("Password confirmed")
-                        .setDescription("You confirmed your password")
                         .setPrompt("The password '" + pinResult.payload() + "' is confirmed.")
-                        .confirm();
+                        .setDescription("You confirmed your password")
+                        .message();
             } else {
                 System.out.println(confirmResult);
             }

src/main/java/org/codehaus/plexus/components/secdispatcher/internal/sources/PinEntryMasterSource.java

@@ -31,7 +31,7 @@
 import org.codehaus.plexus.components.secdispatcher.SecDispatcherException;
 
 /**
- * Inspired by <a href="https://velvetcache.org/2023/03/26/a-peek-inside-pinentry/">A peek inside pinentry</a>
+ * Master source using {@link PinEntry}
  */
 @Singleton
 @Named(PinEntryMasterSource.NAME)
@@ -55,9 +55,9 @@ public Optional<String> configTemplate() {
     @Override
     public String doHandle(String s) throws SecDispatcherException {
         try {
-            PinEntry.Result<String> result = new PinEntry(s)
+            PinEntry.Result result = new PinEntry(s)
                     .setTimeout(Duration.ofSeconds(30))
-                    .setKeyInfo("maven:masterPassword")
+                    .setKeyInfo("Maven: n/masterPassword")
                     .setTitle("Maven Master Password")
                     .setDescription("Please enter the Maven master password")
                     .setPrompt("Maven master password")