feat: add webhook HMAC verification helper methods

feat: add webhook HMAC verification helper methods

Author: stainless-bot

README.md

@@ -43,12 +43,23 @@ LithicClient client = LithicOkHttpClient.builder()
     .build();
 ```
 
-Alternately, set the environment variable `LITHIC_API_KEY` and use `LithicOkHttpClient.fromEnv()`:
+Alternately, use `LithicOkHttpClient.fromEnv()` to read client arguments from environment variables:
 
 ```java
 LithicClient client = LithicClient.fromEnv();
+
+// Note: you can also call fromEnv() from the client builder, for example if you need to set additional properties
+LithicClient client = LithicOkHttpClient.builder()
+    .fromEnv()
+    // ... set properties on the builder
+    .build();
 ```
 
+| Property      | Environment variable    | Required | Default value |
+| ------------- | ----------------------- | -------- | ------------- |
+| apiKey        | `LITHIC_API_KEY`        | true     | —             |
+| webhookSecret | `LITHIC_WEBHOOK_SECRET` | false    | —             |
+
 Read the documentation for more configuration options.
 
 ---

lithic-java-client-okhttp/src/main/kotlin/com/lithic/api/client/okhttp/LithicOkHttpClient.kt

@@ -1,8 +1,10 @@
 package com.lithic.api.client.okhttp
 
+import com.fasterxml.jackson.databind.json.JsonMapper
 import com.lithic.api.client.LithicClient
 import com.lithic.api.client.LithicClientImpl
 import com.lithic.api.core.ClientOptions
+import java.time.Clock
 import java.time.Duration
 
 class LithicOkHttpClient private constructor() {
@@ -25,6 +27,10 @@ class LithicOkHttpClient private constructor() {
 
         fun baseUrl(baseUrl: String) = apply { this.baseUrl = baseUrl }
 
+        fun jsonMapper(jsonMapper: JsonMapper) = apply { clientOptions.jsonMapper(jsonMapper) }
+
+        fun clock(clock: Clock) = apply { clientOptions.clock(clock) }
+
         fun apiKey(apiKey: String) = apply { clientOptions.apiKey(apiKey) }
 
         fun headers(headers: Map<String, Iterable<String>>) = apply {
@@ -51,6 +57,10 @@ class LithicOkHttpClient private constructor() {
             clientOptions.responseValidation(responseValidation)
         }
 
+        fun webhookSecret(webhookSecret: String?) = apply {
+            clientOptions.webhookSecret(webhookSecret)
+        }
+
         fun fromEnv() = apply { clientOptions.fromEnv() }
 
         fun build(): LithicClient {

lithic-java-client-okhttp/src/main/kotlin/com/lithic/api/client/okhttp/LithicOkHttpClientAsync.kt

@@ -1,8 +1,10 @@
 package com.lithic.api.client.okhttp
 
+import com.fasterxml.jackson.databind.json.JsonMapper
 import com.lithic.api.client.LithicClientAsync
 import com.lithic.api.client.LithicClientAsyncImpl
 import com.lithic.api.core.ClientOptions
+import java.time.Clock
 import java.time.Duration
 
 class LithicOkHttpClientAsync private constructor() {
@@ -25,6 +27,10 @@ class LithicOkHttpClientAsync private constructor() {
 
         fun baseUrl(baseUrl: String) = apply { this.baseUrl = baseUrl }
 
+        fun jsonMapper(jsonMapper: JsonMapper) = apply { clientOptions.jsonMapper(jsonMapper) }
+
+        fun clock(clock: Clock) = apply { clientOptions.clock(clock) }
+
         fun apiKey(apiKey: String) = apply { clientOptions.apiKey(apiKey) }
 
         fun headers(headers: Map<String, Iterable<String>>) = apply {
@@ -51,6 +57,10 @@ class LithicOkHttpClientAsync private constructor() {
             clientOptions.responseValidation(responseValidation)
         }
 
+        fun webhookSecret(webhookSecret: String?) = apply {
+            clientOptions.webhookSecret(webhookSecret)
+        }
+
         fun fromEnv() = apply { clientOptions.fromEnv() }
 
         fun build(): LithicClientAsync {

lithic-java-core/src/main/kotlin/com/lithic/api/client/LithicClient.kt

@@ -24,6 +24,8 @@ interface LithicClient {
 
     fun transactions(): TransactionService
 
+    fun webhooks(): WebhookService
+
     /** API status check */
     @JvmOverloads
     fun apiStatus(

lithic-java-core/src/main/kotlin/com/lithic/api/client/LithicClientAsync.kt

@@ -25,6 +25,8 @@ interface LithicClientAsync {
 
     fun transactions(): TransactionServiceAsync
 
+    fun webhooks(): WebhookServiceAsync
+
     /** API status check */
     @JvmOverloads
     fun apiStatus(

lithic-java-core/src/main/kotlin/com/lithic/api/client/LithicClientAsyncImpl.kt

@@ -44,6 +44,8 @@ constructor(
         TransactionServiceAsyncImpl(clientOptions)
     }
 
+    private val webhooks: WebhookServiceAsync by lazy { WebhookServiceAsyncImpl(clientOptions) }
+
     override fun accounts(): AccountServiceAsync = accounts
 
     override fun accountHolders(): AccountHolderServiceAsync = accountHolders
@@ -60,6 +62,8 @@ constructor(
 
     override fun transactions(): TransactionServiceAsync = transactions
 
+    override fun webhooks(): WebhookServiceAsync = webhooks
+
     private val apiStatusHandler: Handler<ApiStatus> =
         jsonHandler<ApiStatus>(clientOptions.jsonMapper).withErrorHandler(errorHandler)
 

lithic-java-core/src/main/kotlin/com/lithic/api/client/LithicClientImpl.kt

@@ -41,6 +41,8 @@ constructor(
 
     private val transactions: TransactionService by lazy { TransactionServiceImpl(clientOptions) }
 
+    private val webhooks: WebhookService by lazy { WebhookServiceImpl(clientOptions) }
+
     override fun accounts(): AccountService = accounts
 
     override fun accountHolders(): AccountHolderService = accountHolders
@@ -57,6 +59,8 @@ constructor(
 
     override fun transactions(): TransactionService = transactions
 
+    override fun webhooks(): WebhookService = webhooks
+
     private val apiStatusHandler: Handler<ApiStatus> =
         jsonHandler<ApiStatus>(clientOptions.jsonMapper).withErrorHandler(errorHandler)
 

lithic-java-core/src/main/kotlin/com/lithic/api/core/ClientOptions.kt

@@ -5,13 +5,16 @@ import com.google.common.collect.ArrayListMultimap
 import com.google.common.collect.ListMultimap
 import com.lithic.api.core.http.HttpClient
 import com.lithic.api.core.http.RetryingHttpClient
+import java.time.Clock
 
 class ClientOptions
 private constructor(
     @get:JvmName("httpClient") val httpClient: HttpClient,
     @get:JvmName("jsonMapper") val jsonMapper: JsonMapper,
+    @get:JvmName("clock") val clock: Clock,
     @get:JvmName("headers") val headers: ListMultimap<String, String>,
     @get:JvmName("responseValidation") val responseValidation: Boolean,
+    @get:JvmName("webhookSecret") val webhookSecret: String?,
 ) {
 
     companion object {
@@ -29,15 +32,19 @@ private constructor(
 
         private var httpClient: HttpClient? = null
         private var jsonMapper: JsonMapper? = null
+        private var clock: Clock? = null
         private var headers: MutableMap<String, MutableList<String>> = mutableMapOf()
         private var responseValidation: Boolean = false
         private var maxRetries: Int = 2
         private var apiKey: String? = null
+        private var webhookSecret: String? = null
 
         fun httpClient(httpClient: HttpClient) = apply { this.httpClient = httpClient }
 
         fun jsonMapper(jsonMapper: JsonMapper) = apply { this.jsonMapper = jsonMapper }
 
+        fun clock(clock: Clock) = apply { this.clock = clock }
+
         fun headers(headers: Map<String, Iterable<String>>) = apply {
             this.headers.clear()
             putAllHeaders(headers)
@@ -65,7 +72,12 @@ private constructor(
 
         fun apiKey(apiKey: String) = apply { this.apiKey = apiKey }
 
-        fun fromEnv() = apply { System.getenv("LITHIC_API_KEY")?.let { apiKey(it) } }
+        fun webhookSecret(webhookSecret: String?) = apply { this.webhookSecret = webhookSecret }
+
+        fun fromEnv() = apply {
+            System.getenv("LITHIC_API_KEY")?.let { apiKey(it) }
+            System.getenv("LITHIC_WEBHOOK_SECRET")?.let { webhookSecret(it) }
+        }
 
         fun build(): ClientOptions {
             checkNotNull(httpClient) { "`httpClient` is required but was not set" }
@@ -87,8 +99,10 @@ private constructor(
                     .maxRetries(maxRetries)
                     .build(),
                 jsonMapper ?: jsonMapper(),
+                clock ?: Clock.systemUTC(),
                 headers.toUnmodifiable(),
                 responseValidation,
+                webhookSecret,
             )
         }
     }

lithic-java-core/src/main/kotlin/com/lithic/api/services/async/WebhookServiceAsync.kt

@@ -0,0 +1,13 @@
+@file:Suppress("OVERLOADS_INTERFACE") // See https://youtrack.jetbrains.com/issue/KT-36102
+
+package com.lithic.api.services.async
+
+import com.google.common.collect.ListMultimap
+import com.lithic.api.models.Event
+
+interface WebhookServiceAsync {
+
+    fun unwrap(payload: String, headers: ListMultimap<String, String>, secret: String?): Event
+
+    fun verifySignature(payload: String, headers: ListMultimap<String, String>, secret: String?)
+}

lithic-java-core/src/main/kotlin/com/lithic/api/services/async/WebhookServiceAsyncImpl.kt

@@ -0,0 +1,104 @@
+package com.lithic.api.services.async
+
+import com.fasterxml.jackson.core.JsonProcessingException
+import com.google.common.collect.ListMultimap
+import com.lithic.api.core.ClientOptions
+import com.lithic.api.core.http.HttpResponse.Handler
+import com.lithic.api.errors.LithicError
+import com.lithic.api.errors.LithicException
+import com.lithic.api.models.Event
+import com.lithic.api.services.errorHandler
+import java.security.MessageDigest
+import java.time.Duration
+import java.time.Instant
+import java.util.Base64
+import javax.crypto.Mac
+import javax.crypto.spec.SecretKeySpec
+
+class WebhookServiceAsyncImpl
+constructor(
+    private val clientOptions: ClientOptions,
+) : WebhookServiceAsync {
+
+    private val errorHandler: Handler<LithicError> = errorHandler(clientOptions.jsonMapper)
+
+    override fun unwrap(
+        payload: String,
+        headers: ListMultimap<String, String>,
+        secret: String?
+    ): Event {
+        verifySignature(payload, headers, secret)
+        return try {
+            clientOptions.jsonMapper.readValue(payload, Event::class.java)
+        } catch (e: JsonProcessingException) {
+            throw LithicException("Invalid event payload", e)
+        }
+    }
+
+    override fun verifySignature(
+        payload: String,
+        headers: ListMultimap<String, String>,
+        secret: String?
+    ) {
+        val webhookSecret =
+            secret
+                ?: clientOptions.webhookSecret
+                    ?: throw LithicException(
+                    "The webhook secret must either be set using the env var, LITHIC_WEBHOOK_SECRET, on the client class, or passed to this method"
+                )
+
+        val whsecret =
+            try {
+                Base64.getDecoder().decode(webhookSecret.removePrefix("whsec_"))
+            } catch (e: RuntimeException) {
+                throw LithicException("Invalid webhook secret")
+            }
+
+        val msgId =
+            headers.get("webhook-id").getOrNull(0)
+                ?: throw LithicException("Could not find webhook-id header")
+        val msgSignture =
+            headers.get("webhook-signature").getOrNull(0)
+                ?: throw LithicException("Could not find webhook-signature header")
+        val msgTimestamp =
+            headers.get("webhook-timestamp").getOrNull(0)
+                ?: throw LithicException("Could not find webhook-timestamp header")
+
+        val timestamp =
+            try {
+                Instant.ofEpochSecond(msgTimestamp.toLong())
+            } catch (e: RuntimeException) {
+                throw LithicException("Invalid signature headers", e)
+            }
+        val now = Instant.now(clientOptions.clock)
+
+        if (timestamp.isBefore(now.minus(Duration.ofMinutes(5)))) {
+            throw LithicException("Webhook timestamp too old")
+        }
+        if (timestamp.isAfter(now.plus(Duration.ofMinutes(5)))) {
+            throw LithicException("Webhook timestamp too new")
+        }
+
+        val mac = Mac.getInstance("HmacSHA256")
+        mac.init(SecretKeySpec(whsecret, "HmacSHA256"))
+        val expectedSignature =
+            mac.doFinal("$msgId.${timestamp.epochSecond}.$payload".toByteArray())
+
+        msgSignture.splitToSequence(" ").forEach {
+            val parts = it.split(",")
+            if (parts.size != 2) {
+                return@forEach
+            }
+
+            if (parts[0] != "v1") {
+                return@forEach
+            }
+
+            if (MessageDigest.isEqual(Base64.getDecoder().decode(parts[1]), expectedSignature)) {
+                return
+            }
+        }
+
+        throw LithicException("None of the given webhook signatures match the expected signature")
+    }
+}