✨ add HMAC validation for webhooks (#162)

Author: ianardee

src/main/java/com/mindee/CommandLineInterface.java

@@ -9,6 +9,7 @@
 import com.mindee.parsing.common.Inference;
 import com.mindee.parsing.common.PredictResponse;
 import com.mindee.product.custom.CustomV1;
+import com.mindee.product.internationalid.InternationalIdV2;
 import com.mindee.product.invoice.InvoiceV4;
 import com.mindee.product.invoicesplitter.InvoiceSplitterV1;
 import com.mindee.product.multireceiptsdetector.MultiReceiptsDetectorV1;
@@ -80,46 +81,54 @@ public static void main(String[] args) {
     System.exit(exitCode);
   }
 
-  @Command(name = "invoice", description = "Invokes the Invoice API")
+  @Command(name = "invoice", description = "Parse using Invoice")
   void invoiceMethod(
       @Parameters(index = "0", paramLabel = "<path>", scope = ScopeType.LOCAL)
       File file
   ) throws IOException {
     System.out.println(standardProductOutput(InvoiceV4.class, file));
   }
 
-  @Command(name = "receipt", description = "Invokes the Expense Receipt API")
+  @Command(name = "receipt", description = "Parse using Expense Receipt")
   void receiptMethod(
       @Parameters(index = "0", paramLabel = "<path>", scope = ScopeType.LOCAL)
       File file
   ) throws IOException {
     System.out.println(standardProductOutput(ReceiptV4.class, file));
   }
 
-  @Command(name = "multi-receipt-detector", description = "Invokes the Multi Receipts Detector API")
+  @Command(name = "multi-receipt-detector", description = "Parse using Multi Receipts Detector")
   void multiReceiptDetectorMethod(
       @Parameters(index = "0", paramLabel = "<path>", scope = ScopeType.LOCAL)
       File file
   ) throws IOException {
     System.out.println(standardProductOutput(MultiReceiptsDetectorV1.class, file));
   }
 
-  @Command(name = "passport", description = "Invokes the Passport API")
+  @Command(name = "passport", description = "Parse using Passport")
   void passportMethod(
       @Parameters(index = "0", paramLabel = "<path>", scope = ScopeType.LOCAL)
       File file
   ) throws IOException {
     System.out.println(standardProductOutput(PassportV1.class, file));
   }
 
-  @Command(name = "invoice-splitter", description = "Invokes the Invoice Splitter API")
+  @Command(name = "invoice-splitter", description = "Parse using Invoice Splitter")
   void invoiceSplitterMethod(
       @Parameters(index = "0", paramLabel = "<path>", scope = ScopeType.LOCAL)
       File file
   ) throws IOException, InterruptedException {
     System.out.println(standardProductAsyncOutput(InvoiceSplitterV1.class, file));
   }
 
+  @Command(name = "international-id", description = "Parse using International ID")
+  void internationalIdMethod(
+      @Parameters(index = "0", paramLabel = "<path>", scope = ScopeType.LOCAL)
+      File file
+  ) throws IOException, InterruptedException {
+    System.out.println(standardProductAsyncOutput(InternationalIdV2.class, file));
+  }
+
   @Command(name = "custom", description = "Invokes a Custom API")
   void customMethod(
       @Option(

src/main/java/com/mindee/input/LocalResponse.java

@@ -1,12 +1,20 @@
 package com.mindee.input;
 
+import java.io.BufferedReader;
 import java.io.File;
 import java.io.IOException;
 import java.io.InputStream;
+import java.io.InputStreamReader;
 import java.nio.charset.StandardCharsets;
 import java.nio.file.Files;
+import java.security.InvalidKeyException;
+import java.security.NoSuchAlgorithmException;
+import java.util.stream.Collectors;
+import java.util.stream.Stream;
+import javax.crypto.Mac;
+import javax.crypto.spec.SecretKeySpec;
 import lombok.Getter;
-import org.apache.pdfbox.io.IOUtils;
+import org.apache.commons.codec.binary.Hex;
 
 /**
  * A Mindee response saved locally.
@@ -17,22 +25,70 @@ public class LocalResponse {
 
   /**
    * Load from an {@link InputStream}.
+   * @param input will be decoded as UTF-8.
    */
   public LocalResponse(InputStream input) throws IOException {
-    this.file = IOUtils.toByteArray(input);
+    this.file = this.getBytes(
+        new BufferedReader(new InputStreamReader(input, StandardCharsets.UTF_8))
+            .lines()
+    );
   }
 
   /**
-   * Load from a UTF-8 {@link String}.
+   * Load from a {@link String}.
+   * @param input will be decoded as UTF-8.
    */
   public LocalResponse(String input) {
     this.file = input.getBytes(StandardCharsets.UTF_8);
   }
 
   /**
    * Load from a {@link File}.
+   * @param input will be decoded as UTF-8.
    */
   public LocalResponse(File input) throws IOException {
-    this.file = Files.readAllBytes(input.toPath());
+    this.file = this.getBytes(
+        Files.lines(input.toPath(), StandardCharsets.UTF_8)
+    );
+  }
+
+  private byte[] getBytes(Stream<String> stream) {
+    return stream.collect(Collectors.joining("")).getBytes();
+  }
+
+  /**
+   * Get the HMAC signature of the payload.
+   * @param secretKey Your secret key from the Mindee platform.
+   * @return The generated HMAC signature.
+   */
+  public String getHmacSignature(String secretKey) {
+    String algorithm = "HmacSHA256";
+    SecretKeySpec secretKeySpec = new SecretKeySpec(
+        secretKey.getBytes(StandardCharsets.UTF_8),
+        algorithm
+    );
+    Mac mac;
+    try {
+      mac = Mac.getInstance(algorithm);
+    } catch (NoSuchAlgorithmException err) {
+      // this should never happen as the algorithm is hard-coded.
+      return "";
+    }
+    try {
+      mac.init(secretKeySpec);
+    } catch (InvalidKeyException err) {
+      return "";
+    }
+    return Hex.encodeHexString(mac.doFinal(this.file));
+  }
+
+  /**
+   * Verify that the payload's signature matches the one received from the server.
+   * @param secretKey Your secret key from the Mindee platform.
+   * @param signature The signature from the "X-Mindee-Hmac-Signature" HTTP header.
+   * @return true if the signatures match.
+   */
+  public boolean isValidHmacSignature(String secretKey, String signature) {
+    return signature.equals(getHmacSignature(secretKey));
   }
 }

src/test/java/com/mindee/input/LocalInputSourceTest.java

@@ -21,7 +21,8 @@ void loadDocument_withInputStream_mustReturnAValidLocalInputSource() throws IOEx
     File file = new File("src/test/resources/file_types/pdf/multipage.pdf");
     LocalInputSource localInputSource = new LocalInputSource(
         Files.newInputStream(file.toPath()),
-        "multipage.pdf");
+        "multipage.pdf"
+    );
     Assertions.assertNotNull(localInputSource);
     Assertions.assertArrayEquals(localInputSource.getFile(), Files.readAllBytes(file.toPath()));
   }
@@ -31,7 +32,8 @@ void loadDocument_withByteArray_mustReturnAValidLocalInputSource() throws IOExce
     File file = new File("src/test/resources/file_types/pdf/multipage.pdf");
     LocalInputSource localInputSource = new LocalInputSource(
         Files.readAllBytes(file.toPath()),
-        "multipage.pdf");
+        "multipage.pdf"
+    );
     Assertions.assertNotNull(localInputSource);
     Assertions.assertArrayEquals(localInputSource.getFile(), Files.readAllBytes(file.toPath()));
   }
@@ -42,7 +44,8 @@ void loadDocument_withBase64Encoded_mustReturnAValidLocalInputSource() throws IO
     String encodedFile = Base64.encodeBase64String(Files.readAllBytes(file.toPath()));
     LocalInputSource localInputSource = new LocalInputSource(
         encodedFile,
-        "multipage.pdf");
+        "multipage.pdf"
+    );
     Assertions.assertNotNull(localInputSource);
     Assertions.assertArrayEquals(localInputSource.getFile(), Files.readAllBytes(file.toPath()));
   }

src/test/java/com/mindee/input/LocalResponseTest.java

@@ -0,0 +1,59 @@
+package com.mindee.input;
+
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Test;
+import java.io.File;
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Paths;
+
+
+public class LocalResponseTest {
+  /**
+   * Fake secret key.
+   */
+  String secretKey = "ogNjY44MhvKPGTtVsI8zG82JqWQa68woYQH";
+
+  /**
+   * Real signature using fake secret key.
+   */
+  String signature = "5ed1673e34421217a5dbfcad905ee62261a3dd66c442f3edd19302072bbf70d0";
+  
+  /**
+   * File which the signature applies to.
+   */
+  String filePath = "src/test/resources/async/get_completed_empty.json";
+
+  @Test
+  void loadDocument_withFile_mustReturnValidLocalResponse() throws IOException {
+    LocalResponse localResponse = new LocalResponse(new File(this.filePath));
+    Assertions.assertNotNull(localResponse.getFile());
+    Assertions.assertFalse(localResponse.isValidHmacSignature(
+        this.secretKey, "invalid signature is invalid")
+    );
+    Assertions.assertEquals(this.signature, localResponse.getHmacSignature(this.secretKey));
+    Assertions.assertTrue(localResponse.isValidHmacSignature(this.secretKey, this.signature));
+  }
+
+  @Test
+  void loadDocument_withString_mustReturnValidLocalResponse() {
+    LocalResponse localResponse = new LocalResponse("{'some': 'json', 'with': 'data'}");
+    Assertions.assertNotNull(localResponse.getFile());
+    Assertions.assertFalse(localResponse.isValidHmacSignature(
+        this.secretKey, "invalid signature is invalid")
+    );
+  }
+
+  @Test
+  void loadDocument_withInputStream_mustReturnValidLocalResponse() throws IOException {
+    LocalResponse localResponse = new LocalResponse(
+        Files.newInputStream(Paths.get(this.filePath))
+    );
+    Assertions.assertNotNull(localResponse.getFile());
+    Assertions.assertFalse(localResponse.isValidHmacSignature(
+        this.secretKey, "invalid signature is invalid")
+    );
+    Assertions.assertEquals(this.signature, localResponse.getHmacSignature(this.secretKey));
+    Assertions.assertTrue(localResponse.isValidHmacSignature(this.secretKey, this.signature));
+  }
+}