Final touches

Author: cstamas

src/main/java/org/codehaus/plexus/components/secdispatcher/Meta.java renamed to src/main/java/org/codehaus/plexus/components/secdispatcher/DispatcherMeta.java

@@ -1,43 +1,68 @@
 package org.codehaus.plexus.components.secdispatcher;
 
 import java.util.Collection;
+import java.util.List;
 import java.util.Optional;
 
 import static java.util.Objects.requireNonNull;
 
 /**
  * Meta description of dispatcher.
  */
-public interface Meta {
+public interface DispatcherMeta {
     class Field {
         private final String key;
         private final boolean optional;
         private final String defaultValue;
         private final String description;
+        private final List<Field> options;
 
-        private Field(String key, boolean optional, String defaultValue, String description) {
+        private Field(String key, boolean optional, String defaultValue, String description, List<Field> options) {
             this.key = requireNonNull(key);
             this.optional = optional;
             this.defaultValue = defaultValue;
             this.description = requireNonNull(description);
+            this.options = options;
         }
 
+        /**
+         * The key to be used in configuration map for field.
+         */
         public String getKey() {
             return key;
         }
 
+        /**
+         * Is configuration optional?
+         */
         public boolean isOptional() {
             return optional;
         }
 
+        /**
+         * Optional default value of the configuration.
+         */
         public Optional<String> getDefaultValue() {
             return Optional.ofNullable(defaultValue);
         }
 
+        /**
+         * The human description of the configuration.
+         */
         public String getDescription() {
             return description;
         }
 
+        /**
+         * Optional list of options, if this configuration accepts limited values. Each option is represented
+         * as field, where {@link #getKey()} represents the value to be used, and {@link #displayName()} represents
+         * the description of option. The {@link #getDefaultValue()}, if present represents the value to be used
+         * instead of {@link #getKey()}.
+         */
+        public Optional<List<Field>> getOptions() {
+            return Optional.ofNullable(options);
+        }
+
         public static Builder builder(String key) {
             return new Builder(key);
         }
@@ -47,6 +72,7 @@ public static class Builder {
             private boolean optional;
             private String defaultValue;
             private String description;
+            private List<Field> options;
 
             private Builder(String key) {
                 this.key = requireNonNull(key);
@@ -67,24 +93,29 @@ public Builder description(String description) {
                 return this;
             }
 
+            public Builder options(List<Field> options) {
+                this.options = requireNonNull(options);
+                return this;
+            }
+
             public Field build() {
-                return new Field(key, optional, defaultValue, description);
+                return new Field(key, optional, defaultValue, description, options);
             }
         }
     }
 
     /**
-     * The key of the item.
+     * The name of the dispatcher.
      */
     String name();
 
     /**
-     * Returns the display (human) name of the item.
+     * Returns the display (human) name of the dispatcher.
      */
     String displayName();
 
     /**
-     * Returns the configuration fields of the item.
+     * Returns the configuration fields of the dispatcher.
      */
     Collection<Field> fields();
 }

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

@@ -48,7 +48,7 @@ public interface SecDispatcher {
     /**
      * Returns the set of available dispatcher metadata, never {@code null}.
      */
-    Set<Meta> availableDispatchers();
+    Set<DispatcherMeta> availableDispatchers();
 
     /**
      * Encrypt given plaintext string.

src/main/java/org/codehaus/plexus/components/secdispatcher/internal/DefaultSecDispatcher.java

@@ -22,13 +22,14 @@
 import java.nio.file.Paths;
 import java.util.HashMap;
 import java.util.Map;
+import java.util.Objects;
 import java.util.Set;
 import java.util.StringTokenizer;
 import java.util.stream.Collectors;
 
 import org.codehaus.plexus.components.cipher.PlexusCipher;
 import org.codehaus.plexus.components.cipher.PlexusCipherException;
-import org.codehaus.plexus.components.secdispatcher.Meta;
+import org.codehaus.plexus.components.secdispatcher.DispatcherMeta;
 import org.codehaus.plexus.components.secdispatcher.SecDispatcher;
 import org.codehaus.plexus.components.secdispatcher.SecDispatcherException;
 import org.codehaus.plexus.components.secdispatcher.model.SettingsSecurity;
@@ -59,7 +60,7 @@ public DefaultSecDispatcher(
     }
 
     @Override
-    public Set<Meta> availableDispatchers() {
+    public Set<DispatcherMeta> availableDispatchers() {
         return Set.copyOf(dispatchers.values().stream().map(Dispatcher::meta).collect(Collectors.toSet()));
     }
 
@@ -74,17 +75,25 @@ public String encrypt(String str, Map<String, String> attr) throws SecDispatcher
                 attr = new HashMap<>(attr);
             }
             if (attr.get(DISPATCHER_NAME_ATTR) == null) {
-                attr.put(DISPATCHER_NAME_ATTR, getConfiguration().getDefaultDispatcher());
+                attr.put(
+                        DISPATCHER_NAME_ATTR,
+                        requireNonNull(
+                                getConfiguration().getDefaultDispatcher(),
+                                "no default dispatcher set in configuration"));
             }
             String name = attr.get(DISPATCHER_NAME_ATTR);
             Dispatcher dispatcher = dispatchers.get(name);
             if (dispatcher == null) throw new SecDispatcherException("no dispatcher for name " + name);
+            Dispatcher.EncryptPayload payload = dispatcher.encrypt(str, attr, prepareDispatcherConfig(name));
+            if (!Objects.equals(payload.getAttributes().get(DISPATCHER_NAME_ATTR), name)) {
+                throw new SecDispatcherException("Dispatcher " + name + " bug: mismatched name attribute");
+            }
             String res = ATTR_START
-                    + attr.entrySet().stream()
+                    + payload.getAttributes().entrySet().stream()
                             .map(e -> e.getKey() + "=" + e.getValue())
                             .collect(Collectors.joining(","))
                     + ATTR_STOP;
-            res += dispatcher.encrypt(str, attr, prepareDispatcherConfig(name));
+            res += payload.getEncrypted();
             return cipher.decorate(res);
         } catch (PlexusCipherException e) {
             throw new SecDispatcherException(e.getMessage(), e);
@@ -96,9 +105,9 @@ public String decrypt(String str) throws SecDispatcherException {
         if (!isEncryptedString(str)) return str;
         try {
             String bare = cipher.unDecorate(str);
-            Map<String, String> attr = stripAttributes(bare);
+            Map<String, String> attr = requireNonNull(stripAttributes(bare));
             if (attr.get(DISPATCHER_NAME_ATTR) == null) {
-                attr.put(DISPATCHER_NAME_ATTR, getConfiguration().getDefaultDispatcher());
+                throw new SecDispatcherException("malformed password: no attribute with name");
             }
             String name = attr.get(DISPATCHER_NAME_ATTR);
             Dispatcher dispatcher = dispatchers.get(name);

src/main/java/org/codehaus/plexus/components/secdispatcher/internal/Dispatcher.java

@@ -15,9 +15,11 @@
 
 import java.util.Map;
 
-import org.codehaus.plexus.components.secdispatcher.Meta;
+import org.codehaus.plexus.components.secdispatcher.DispatcherMeta;
 import org.codehaus.plexus.components.secdispatcher.SecDispatcherException;
 
+import static java.util.Objects.requireNonNull;
+
 /**
  * Dispatcher.
  *
@@ -26,26 +28,48 @@
  *
  */
 public interface Dispatcher {
+    /**
+     * The "encrypt payload" prepared by dispatcher.
+     */
+    final class EncryptPayload {
+        private final Map<String, String> attributes;
+        private final String encrypted;
+
+        public EncryptPayload(Map<String, String> attributes, String encrypted) {
+            this.attributes = requireNonNull(attributes);
+            this.encrypted = requireNonNull(encrypted);
+        }
+
+        public Map<String, String> getAttributes() {
+            return attributes;
+        }
+
+        public String getEncrypted() {
+            return encrypted;
+        }
+    }
+
     /**
      * The metadata of this dispatcher.
      */
-    Meta meta();
+    DispatcherMeta meta();
 
     /**
-     * encrypt given plaintext string
+     * Encrypt given plaintext string. Implementation must return at least same attributes it got, but may add more
+     * attributes to returned payload.
      *
-     * @param str string to encrypt
+     * @param str string to encrypt, never {@code null}
      * @param attributes attributes, never {@code null}
      * @param config configuration from settings-security.xml, never {@code null}
-     * @return encrypted string
+     * @return encrypted string and attributes in {@link EncryptPayload}
      */
-    String encrypt(String str, Map<String, String> attributes, Map<String, String> config)
+    EncryptPayload encrypt(String str, Map<String, String> attributes, Map<String, String> config)
             throws SecDispatcherException;
 
     /**
-     * decrypt given encrypted string
+     * Decrypt given encrypted string.
      *
-     * @param str string to decrypt
+     * @param str string to decrypt, never {@code null}
      * @param attributes attributes, never {@code null}
      * @param config configuration from settings-security.xml, never {@code null}
      * @return decrypted string

src/main/java/org/codehaus/plexus/components/secdispatcher/internal/MasterSource.java

@@ -13,23 +13,36 @@
 
 package org.codehaus.plexus.components.secdispatcher.internal;
 
+import java.util.Optional;
+
 import org.codehaus.plexus.components.secdispatcher.SecDispatcherException;
 
 /**
  * Source of master password.
  */
 public interface MasterSource {
     /**
-     * Handles the URI to get master password. Implementation may do one of the following things:
+     * String describing what this source does.
+     */
+    String description();
+
+    /**
+     * Optional "config template" that may serve as basis to configure this master source. The template cannot be
+     * "reused" as is as configuration.
+     */
+    Optional<String> configTemplate();
+
+    /**
+     * Handles the config to get master password. Implementation may do one of the following things:
      * <ul>
-     *     <li>if the URI cannot be handled by given source, return {@code null}</li>
-     *     <li>if master password retrieval was attempted, but failed throw {@link SecDispatcherException}</li>
+     *     <li>if the config cannot be handled by given source, return {@code null}</li>
+     *     <li>otherwise, if master password retrieval based on config was attempted but failed, throw {@link SecDispatcherException}</li>
      *     <li>happy path: return the master password.</li>
      * </ul>
      *
-     * @param masterSource the source of master password, and opaque string.
-     * @return the master password, or {@code null} if implementation does not handle this masterSource
-     * @throws SecDispatcherException If implementation does handle this masterSource, but cannot obtain it
+     * @param config the source of master password, and opaque string.
+     * @return the master password, or {@code null} if implementation does not handle this config
+     * @throws SecDispatcherException If implementation does handle this masterSource, but cannot obtain master password
      */
-    String handle(String masterSource) throws SecDispatcherException;
+    String handle(String config) throws SecDispatcherException;
 }