Add additional email address formats

Author: RohanNagar

CHANGELOG.md

@@ -105,6 +105,32 @@ Thanks, @Sprokof, for contributing (introducing `removeDots` and `adjustCase` op
 | removeSubAddress            | Remove any sub-addressing (or tagged-addressing) from the local-part of the address. For example, `[email protected]` will become `[email protected]`                                              | `removeSubAddress()` or `removeSubAddress(String)`                                |
 | performUnicodeNormalization | Perform unicode normalization on the local-part of the email address                                                                                                                                          | `performUnicodeNormalization()` or `performUnicodeNormalization(Normalizer.Form)` |
 
+
+### Additional Address Formats
+
+Version 2.0.0 introduces new additional email address formats that can be obtained from
+the `Email` object (similar to the `normalize()` method).
+
+- `Email#reference()` returns an MD5 hash of the normalized email address.
+
+  ```
+    "[email protected]" => "1aedb8d9dc4751e229a335e371db8058"
+  ```
+
+- `Email#redacted()` returns a version of the normalized email address where the local-part
+  is replaced with the SHA-1 hash of the local-part.
+
+  ```
+    "[email protected]" => "{a94a8fe5ccb19ba61c4c0873d391e987982fbbd3}@gmail.com"
+  ```
+
+- `Email#munged()` returns a version of the normalized email address where the local-part
+  and domain are obfuscated with five asterisk characters.
+
+  ```
+    "[email protected]" => "te*****@gm*****"
+  ```
+
 ---
 ## 1.6.3
 

src/main/java/com/sanctionco/jmail/Email.java

@@ -2,8 +2,10 @@
 
 import com.sanctionco.jmail.normalization.CaseOption;
 import com.sanctionco.jmail.normalization.NormalizationOptions;
-import com.sanctionco.jmail.normalization.NormalizationOptionsBuilder;
 
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import java.security.NoSuchAlgorithmException;
 import java.text.Normalizer;
 import java.util.Collections;
 import java.util.List;
@@ -235,40 +237,178 @@ public TopLevelDomain topLevelDomain() {
   }
 
   /**
-   * <p>Return a "normalized" version of this email address. The actual result of normalization
-   * depends on the configured normalization options (see {@link NormalizationOptions}),
-   * but in general this method returns a version of the email address that is the same as
-   * the original email address, except that all comments and optional parts
-   * (identifiers, source routing) are removed. For example, the address
-   * {@code "test@(comment)example.com"} will return {@code "[email protected]"}.</p>
+   * <p>Return a "normalized" version of this email address. This method returns a version of the
+   * email address that is the same as the original email address, except:</p>
+   *
+   * <ul>
+   *   <li>All comments are removed</li>
+   *   <li>All identifiers or source routing are removed</li>
+   *   <li>Any unnecessary quotes within the local-part are removed</li>
+   *   <li>The entire address is lowercased</li>
+   * </ul>
    *
-   * <p>This method uses the default set of {@link NormalizationOptions}. This default set
-   * of options can be adjusted using system properties. See {@link NormalizationOptions}
-   * for more details on which properties to set to adjust the defaults.</p>
+   * <p>For example, the address {@code "tEST@(comment)example.com"} will return
+   * {@code "[email protected]"}.</p>
    *
-   * <p>Alternatively, one can use the {@link Email#normalized(NormalizationOptions)} method
-   * and pass in a custom set of options to adjust the behavior.</p>
+   * <p>This method uses the default set of {@link NormalizationOptions} when performing
+   * normalization. Use {@link #normalized(NormalizationOptions)} instead of this method
+   * to further customize how normalization behaves.</p>
    *
    * @return the normalized version of this email address
    */
   public String normalized() {
-    return normalized(NormalizationOptions.builder().build());
+    return normalized(NormalizationOptions.DEFAULT_OPTIONS);
   }
 
   /**
    * <p>Return a "normalized" version of this email address. The actual result of normalization
    * depends on the configured normalization options, but in general this method returns
-   * a version of the email address that is the same as the original email address, except
-   * that all comments and optional parts (identifiers, source routing) are removed.
-   * For example, the address {@code "test@(comment)example.com"} will return
+   * a version of the email address that is the same as the original email address, except:</p>
+   *
+   * <ul>
+   *   <li>All comments are removed</li>
+   *   <li>All identifiers or source routing are removed</li>
+   *   <li>Any unnecessary quotes within the local-part are removed</li>
+   *   <li>The entire address is lowercased</li>
+   * </ul>
+   *
+   * <p>For example, the address {@code "tEST@(comment)example.com"} will return
    * {@code "[email protected]"}.</p>
    *
    * <p>See {@link NormalizationOptions} for more details on all of the configurable options.</p>
    *
    * @param options the {@link NormalizationOptions} to use when normalizing
    * @return the normalized version of this email address
+   * @see NormalizationOptions
    */
   public String normalized(NormalizationOptions options) {
+    return normalizedLocalPart(options) + "@" + normalizedDomain(options);
+  }
+
+  /**
+   * <p>Returns an MD5 reference to the email address. This format can be useful to share references
+   * to the email address without sharing the actual address.</p>
+   *
+   * <p>The reference is calculated by first performing normalization on the address, and then
+   * taking the MD5 hash of the normalized address. See {@link #normalized()} for more details
+   * on how normalization works.</p>
+   *
+   * <p>This method uses the default {@link NormalizationOptions}. If you wish to customize how the
+   * normalization happens, use {@link #reference(NormalizationOptions)} instead.</p>
+   *
+   * @return the MD5 reference string for the address
+   * @throws NoSuchAlgorithmException if the MD5 algorithm is unable to be loaded
+   */
+  public String reference() throws NoSuchAlgorithmException {
+    return reference(NormalizationOptions.DEFAULT_OPTIONS);
+  }
+
+  /**
+   * <p>Returns an MD5 reference to the email address. This format can be useful to share references
+   * to the email address without sharing the actual address.</p>
+   *
+   * <p>The reference is calculated by first performing normalization on the address, and then
+   * taking the MD5 hash of the normalized address. See {@link #normalized(NormalizationOptions)}
+   * for more details on how normalization works.</p>
+   *
+   * @param options the {@link NormalizationOptions} to use when normalizing
+   * @return the MD5 reference string for the address
+   * @throws NoSuchAlgorithmException if the MD5 algorithm is unable to be loaded
+   */
+  public String reference(NormalizationOptions options) throws NoSuchAlgorithmException {
+    MessageDigest md = MessageDigest.getInstance("MD5");
+
+    byte[] normalized = normalized(options).getBytes(StandardCharsets.UTF_8);
+    byte[] digest = md.digest(normalized);
+
+    return toHexString(digest);
+  }
+
+  /**
+   * <p>Returns a redacted version of the email address in the format {@code "{local-part}@domain"}.
+   * This format can be useful when storing addresses in a data store (to avoid storing the original
+   * address).</p>
+   *
+   * <p>The redacted address is calculated by first performing normalization on the address, and
+   * then taking the SHA-1 hash of the local-part of the normalized address to construct the final
+   * redacted version of the address. See {@link #normalized()} for more details on how
+   * normalization works.</p>
+   *
+   * <p>This method uses the default {@link NormalizationOptions}. If you wish to customize how the
+   * normalization happens, use {@link #redacted(NormalizationOptions)} instead.</p>
+   *
+   * @return the redacted version of the email address
+   * @throws NoSuchAlgorithmException if the SHA-A algorithm is unable to be loaded
+   */
+  public String redacted() throws NoSuchAlgorithmException {
+    return redacted(NormalizationOptions.DEFAULT_OPTIONS);
+  }
+
+  /**
+   * <p>Returns a redacted version of the email address in the format {@code "{local-part}@domain"}.
+   * This format can be useful when storing addresses in a data store (to avoid storing the original
+   * address).</p>
+   *
+   * <p>The redacted address is calculated by first performing normalization on the address, and
+   * then taking the SHA-1 hash of the local-part of the normalized address to construct the final
+   * redacted version of the address. See {@link #normalized(NormalizationOptions)} for more
+   * details on how normalization works.</p>
+   *
+   * @param options the {@link NormalizationOptions} to use when normalizing
+   * @return the redacted version of the email address
+   * @throws NoSuchAlgorithmException if the SHA-1 algorithm is unable to be loaded
+   */
+  public String redacted(NormalizationOptions options) throws NoSuchAlgorithmException {
+    MessageDigest md = MessageDigest.getInstance("SHA1");
+
+    byte[] normalizedLocalPart = normalizedLocalPart(options).getBytes(StandardCharsets.UTF_8);
+    byte[] digest = md.digest(normalizedLocalPart);
+
+    return "{" + toHexString(digest) + "}@" + normalizedDomain(options);
+  }
+
+  /**
+   * <p>Returns a munged version of the email address in the format {@code "lo*****@do*****"}.
+   * This format can be useful when displaying addresses on a user account page.
+   *
+   * <p>The munged address is calculated by first performing normalization on the address, and
+   * then taking the first two characters of both the local-part and the domain, and adding
+   * five {@code *} characters to each. See {@link #normalized()} for more
+   * details on how normalization works.</p>
+   *
+   * <p>This method uses the default {@link NormalizationOptions}. If you wish to customize how the
+   * normalization happens, use {@link #munged(NormalizationOptions)} instead.</p>
+   *
+   * @return the munged version of the email address
+   */
+  public String munged() {
+    return munged(NormalizationOptions.DEFAULT_OPTIONS);
+  }
+
+
+  /**
+   * <p>Returns a munged version of the email address in the format {@code "lo*****@do*****"}.
+   * This format can be useful when displaying addresses on a user account page.
+   *
+   * <p>The munged address is calculated by first performing normalization on the address, and
+   * then taking the first two characters of both the local-part and the domain, and adding
+   * five {@code *} characters to each. See {@link #normalized(NormalizationOptions)} for more
+   * details on how normalization works.</p>
+   *
+   * @param options the {@link NormalizationOptions} to use when normalizing
+   * @return the munged version of the email address
+   */
+  public String munged(NormalizationOptions options) {
+    String localPart = normalizedLocalPart(options);
+    localPart = localPart.length() < 2 ? localPart : localPart.substring(0, 2);
+
+    String domain = normalizedDomain(options);
+    domain = domain.length() < 2 ? domain : domain.substring(0, 2);
+
+    return localPart + "*****@" + domain + "*****";
+  }
+
+  private String normalizedLocalPart(NormalizationOptions options) {
     String localPart = options.shouldStripQuotes()
         ? localPartWithoutQuotes
         : localPartWithoutComments;
@@ -287,15 +427,34 @@ public String normalized(NormalizationOptions options) {
         ? caseOption.adjustLocalPart(localPart.replace(".", ""))
         : caseOption.adjustLocalPart(localPart);
 
-    String domain = isIpAddress
+    if (options.shouldPerformUnicodeNormalization()) {
+      localPart = Normalizer.normalize(localPart, options.getUnicodeNormalizationForm());
+    }
+
+    return localPart;
+  }
+
+  private String normalizedDomain(NormalizationOptions options) {
+    CaseOption caseOption = options.getCaseOption();
+
+    return isIpAddress
         ? "[" + this.domainWithoutComments + "]"
         : caseOption.adjustDomain(this.domainWithoutComments);
+  }
 
-    if (options.shouldPerformUnicodeNormalization()) {
-      localPart = Normalizer.normalize(localPart, options.getUnicodeNormalizationForm());
+  private String toHexString(byte[] bytes) {
+    char[] hexArray = {
+        '0', '1', '2', '3', '4', '5', '6', '7', '8', '9',
+        'a', 'b', 'c', 'd', 'e', 'f'};
+    char[] hexChars = new char[bytes.length * 2];
+
+    for (int j = 0; j < bytes.length; j++) {
+      int v = bytes[j] & 0xFF;
+      hexChars[j * 2] = hexArray[v / 16];
+      hexChars[j * 2 + 1] = hexArray[v % 16];
     }
 
-    return localPart + "@" + domain;
+    return new String(hexChars);
   }
 
   /**

src/main/java/com/sanctionco/jmail/normalization/NormalizationOptions.java

@@ -13,6 +13,11 @@
  * {@link #builder()}</p>
  */
 public class NormalizationOptions {
+  /**
+   * A default {@code NormalizationOptions} object.
+   */
+  public static final NormalizationOptions DEFAULT_OPTIONS = builder().build();
+
   private final CaseOption caseOption;
   private final boolean removeDots;
   private final boolean removeSubAddress;

src/test/java/com/sanctionco/jmail/EmailTest.java

@@ -3,6 +3,7 @@
 import com.sanctionco.jmail.normalization.CaseOption;
 import com.sanctionco.jmail.normalization.NormalizationOptions;
 
+import java.security.NoSuchAlgorithmException;
 import java.text.Normalizer;
 import java.util.stream.Stream;
 
@@ -215,6 +216,94 @@ void ensureNormalizedDoesNotStripQuotesIfInvalid(String address) {
             .build()));
   }
 
+  @Test
+  void ensureReferenceFormat() {
+    String address = "[email protected]";
+    String md5 = "1aedb8d9dc4751e229a335e371db8058";
+
+    assertThat(Email.of(address))
+        .isPresent().get()
+        .returns(md5, e -> {
+          try {
+            return e.reference();
+          } catch (NoSuchAlgorithmException ex) {
+            return "NoSuchAlgorithmException";
+          }
+        });
+
+    // With custom options
+    String capitalizedMD5 = "e307f5ddc2a641dc63ace209e17b4f80";
+
+    assertThat(Email.of(address))
+        .isPresent().get()
+        .returns(capitalizedMD5, e -> {
+          try {
+            return e.reference(NormalizationOptions.builder()
+                .adjustCase(CaseOption.UPPERCASE)
+                .build());
+          } catch (NoSuchAlgorithmException ex) {
+            return "NoSuchAlgorithmException";
+          }
+        });
+  }
+
+  @Test
+  void ensureRedactedFormat() {
+    String address = "[email protected]";
+    String redacted = "{a94a8fe5ccb19ba61c4c0873d391e987982fbbd3}@gmail.com";
+
+    assertThat(Email.of(address))
+        .isPresent().get()
+        .returns(redacted, e -> {
+          try {
+            return e.redacted();
+          } catch (NoSuchAlgorithmException ex) {
+            return "NoSuchAlgorithmException";
+          }
+        });
+
+    // With custom options
+    String capitalizedRedacted = "{984816fd329622876e14907634264e6f332e9fb3}@GMAIL.COM";
+
+    assertThat(Email.of(address))
+        .isPresent().get()
+        .returns(capitalizedRedacted, e -> {
+          try {
+            return e.redacted(NormalizationOptions.builder()
+                .adjustCase(CaseOption.UPPERCASE)
+                .build());
+          } catch (NoSuchAlgorithmException ex) {
+            return "NoSuchAlgorithmException";
+          }
+        });
+  }
+
+  @Test
+  void ensureMungedFormat() {
+    String address = "[email protected]";
+    String munged = "te*****@gm*****";
+
+    assertThat(Email.of(address))
+        .isPresent().get()
+        .returns(munged, Email::munged);
+
+    // With custom options
+    String capitalizedMunged = "TE*****@GM*****";
+
+    assertThat(Email.of(address))
+        .isPresent().get()
+        .returns(capitalizedMunged, e -> e.munged(NormalizationOptions.builder()
+            .adjustCase(CaseOption.UPPERCASE)
+            .build()));
+
+    // With a very short address
+    String shortAddress = "t@r";
+
+    assertThat(Email.of(shortAddress))
+        .isPresent().get()
+        .returns("t*****@r*****", Email::munged);
+  }
+
   static Stream<Arguments> provideValidForStripQuotes() {
     return Stream.of(
         Arguments.of("\"test.1\"@example.org", "[email protected]"),