Node'da JSON body parser'ları Stripe ve Shopify webhook imza doğrulamasını neden bozar

Tuzağın ne olduğu

dev.to'da yayımlanan bir rehber, Node ve TypeScript backend'lerinde Stripe ve Shopify webhook'ları işlenirken 401 Unauthorized yanıtlarının en sık görülen nedenini, yazarın deyişiyle şöyle ortaya koyuyor: HMAC-SHA256 imzasının sağlayıcının gönderdiği baytlar yerine JSON.stringify(req.body) üzerinden doğrulanması.

Her iki sağlayıcı da webhook teslimatlarını, ham HTTP istek gövdesi üzerinde bir HMAC-SHA256 özeti hesaplayarak imzalar. Bir isteğin gerçek olduğunu doğrulamak için alan sunucunun aynı özeti aynı baytlar üzerinde yeniden hesaplaması gerekir. Genel bir JSON body parser bu gövdeyi handler çalışmadan önce tüketip deserialize etmişse, orijinal baytlar artık elde yoktur.

Yeniden serileştirme neden hiçbir zaman eşleşmez

HMAC ayrıştırılmış veri yapıları üzerinde değil, baytlar üzerinde çalışır. Middleware payload'ı bir JavaScript nesnesine dönüştürdükten ve handler onu yeniden serileştirdikten sonra, elde edilen dize göndericinin ürettiğiyle nadiren bayt bayt aynıdır. dev.to makalesinin açıkladığı gibi, anahtarlar ve değerler arasındaki boşluklar, hangi karakterlerin kaçışlandırıldığı ve bilimsel gösterim dahil sayıların nasıl biçimlendirildiği gibi küçük farklar, SHA-256'ya girdiyi ve dolayısıyla son özeti değiştirmeye yeter. İmza karşılaştırması, webhook'un kendisi tamamen meşru olsa bile başarısız olur.

Doğru bir Stripe doğrulaması nasıl çalışır

Makalenin Stripe için referans uygulaması, yazarın güvenli desen olarak sunduğu bir diziyi izler:

• İmza başlığını parçalarına ayır ve timestamp alanı ile v1 özetini çıkar.

• Timestamp eksikse, tam sayı değilse veya yapılandırılabilir bir toleranstan — yazar varsayılan olarak 300 saniye kullanıyor — daha fazla uzaklıktaysa isteği reddet; bu, replay saldırılarını sınırlamaya yarar.

• İmzalı payload'ı timestamp, bir nokta ve UTF-8 olarak okunan ham gövde şeklinde yeniden oluştur.

• Bu dizenin webhook secret ile HMAC-SHA256 değerini hesapla.

• Hesaplanan özeti başlıkta verilenle karşılaştır; önce uzunlukların eşleştiğini kontrol et, ardından timing side channel'ları önlemek için crypto.timingSafeEqual kullan.

Shopify webhook'ları tür olarak aynı şekilde doğrulanır — ham gövde üzerinden bir HMAC — ve makale iki sağlayıcının hata modlarını özdeş sayar.

Ham gövdeye erişmek

Çözüm mimariseldir: ayrıştırılmamış bayt buffer'ının doğrulamaya kadar hayatta kalmasını sağla. Node ekosistemindeki yaygın yaklaşımlar arasında webhook route'larını genel JSON middleware'inden muaf tutmak, yalnızca bu route'lara bir parser bağlamak veya parser'ın verify callback'ini kullanarak ham buffer'ı request nesnesi üzerinde saklamak yer alır. Doğrulama buffer üzerinden yapılır ve yalnızca geçtikten sonra payload iş mantığı için bir nesneye ayrıştırılır.

dev.to yazısında ayrıca Stripe ve Shopify HMAC imzalarıyla deney yapabileceğiniz interaktif bir sandbox'a bağlantı verilir.

Neden önemli

Webhook'lar ödemeleri sonuçlandıran, fulfillment'ı güncelleyen ve abonelik durumunu değiştiren olayları taşır. Kod yanlış baytları özetlediği için doğrulama sessizce başarısız olduğunda bu olaylar ya kaybedilir ya da sonsuza dek yeniden denenir; ekipler de çoğu zaman imza kontrolünü tamamen devre dışı bırakma eğilimine girer — oysa bu, uç noktaya erişebilen herkesin sahte bir webhook göndermesini ve örneğin gerçek bir tahsilat olmadan bir faturayı ödenmiş olarak işaretlemesini sağlar.

Buradaki temel ders bu iki sağlayıcının çok ötesine genellenir: HMAC baytlar üzerinde bir sözleşmedir; dolayısıyla doğrulamadan önce gövdeyi normalize eden, yeniden biçimlendiren veya yeniden kodlayan her katman onu geçersiz kılar. JSON-parse-first middleware'in birçok Express ve serverless kurulumunda hâlâ varsayılan olmasıyla bu, en kolay başlatılabilen güvenlik hatalarından biri olmaya devam ediyor — ama neye bakacağınızı bir kez bildikten sonra düzeltilmesi en ucuz olanlardan da biri.