@easypayment/medusa-payment-paypal 0.9.16 → 0.9.18

package/src/modules/paypal/utils/secret-crypto.ts

@@ -1,4 +1,4 @@
-import { createCipheriv, createDecipheriv, createHash, randomBytes } from "crypto"
+import { createCipheriv, createDecipheriv, createHash, randomBytes, scryptSync } from "crypto"
 
 /**
  * Opt-in encryption-at-rest for PayPal secrets (client secret, app access
@@ -8,15 +8,35 @@ import { createCipheriv, createDecipheriv, createHash, randomBytes } from "crypt
  * default), both functions are the identity — behavior is byte-for-byte
  * unchanged, so existing deployments are unaffected.
  *
- * Format: `enc:v1:<iv_b64>:<tag_b64>:<ciphertext_b64>` using AES-256-GCM
- * (authenticated, so tampering is detected on decrypt). Legacy plaintext values
- * (no prefix) are returned as-is on decrypt, so secrets stored before
- * encryption was enabled keep working and are upgraded on the next save.
+ * Format (current): `enc:v2:<salt_b64>:<iv_b64>:<tag_b64>:<ciphertext_b64>`
+ * using AES-256-GCM with a key derived via **scrypt** over the env key and a
+ * random per-secret salt. scrypt is a memory-hard KDF, so even a low-entropy
+ * passphrase resists brute-force/rainbow-table attacks (the previous unsalted,
+ * single-pass SHA-256 did not).
+ *
+ * Format (legacy): `enc:v1:<iv_b64>:<tag_b64>:<ciphertext_b64>` with an
+ * unsalted SHA-256 key. Still decryptable so secrets written before the KDF
+ * upgrade keep working; they are transparently upgraded to v2 on the next save.
+ *
+ * Legacy plaintext values (no prefix) are returned as-is on decrypt.
  */
-const PREFIX = "enc:v1:"
+const PREFIX_V2 = "enc:v2:"
+const PREFIX_V1 = "enc:v1:"
+
+// scrypt cost parameters. N=2^14 with r=8 needs ~16MB (128*N*r), which stays
+// under Node's default 32MB scrypt memory limit while imposing a meaningful
+// per-derivation cost. Derived keys are cached, so this runs at most once per
+// (env key, salt) pair rather than on every encrypt/decrypt.
+const SCRYPT_N = 16384
+const SCRYPT_R = 8
+const SCRYPT_P = 1
+const KEY_LEN = 32
+const SALT_LEN = 16
 
 let cachedRaw: string | undefined
-let cachedKey: Buffer | null = null
+let cachedRawKey: string | null = null
+let legacyV1Key: Buffer | null = null
+const v2KeyCache = new Map<string, Buffer>()
 
 /**
  * `@types/node` 22.0-22.6 typed `Buffer` as `Buffer<ArrayBufferLike>`, which is
@@ -27,41 +47,75 @@ let cachedKey: Buffer | null = null
  */
 const bytes = (view: Buffer): Uint8Array => view as unknown as Uint8Array
 
-function getKey(): Buffer | null {
+/** The raw env key (trimmed), or null when encryption is disabled. */
+function getRawKey(): string | null {
   const raw = (process.env.PAYPAL_ENCRYPTION_KEY || "").trim()
   if (raw !== cachedRaw) {
     cachedRaw = raw
-    // Accept a key of any length/format; derive a stable 32-byte AES key.
-    cachedKey = raw ? createHash("sha256").update(raw).digest() : null
+    cachedRawKey = raw || null
+    // The unsalted SHA-256 key is only needed to decrypt legacy v1 values.
+    legacyV1Key = raw ? createHash("sha256").update(raw).digest() : null
+    v2KeyCache.clear()
+  }
+  return cachedRawKey
+}
+
+/** Derive (and cache) the AES key for a v2 secret from the env key + salt. */
+function deriveV2Key(raw: string, salt: Buffer): Buffer {
+  const cacheKey = `${raw}::${salt.toString("base64")}`
+  let key = v2KeyCache.get(cacheKey)
+  if (!key) {
+    key = scryptSync(raw, bytes(salt), KEY_LEN, {
+      N: SCRYPT_N,
+      r: SCRYPT_R,
+      p: SCRYPT_P,
+    })
+    v2KeyCache.set(cacheKey, key)
   }
-  return cachedKey
+  return key
+}
+
+function gcmDecrypt(key: Buffer, ivB64: string, tagB64: string, ctB64: string): string {
+  const decipher = createDecipheriv("aes-256-gcm", bytes(key), bytes(Buffer.from(ivB64, "base64")))
+  decipher.setAuthTag(bytes(Buffer.from(tagB64, "base64")))
+  const plaintext = Buffer.concat([
+    bytes(decipher.update(bytes(Buffer.from(ctB64, "base64")))),
+    bytes(decipher.final()),
+  ])
+  return plaintext.toString("utf8")
 }
 
 export function isSecretEncryptionEnabled(): boolean {
-  return getKey() !== null
+  return getRawKey() !== null
 }
 
 export function isEncrypted(value: unknown): boolean {
-  return typeof value === "string" && value.startsWith(PREFIX)
+  return (
+    typeof value === "string" &&
+    (value.startsWith(PREFIX_V2) || value.startsWith(PREFIX_V1))
+  )
 }
 
 /**
  * Encrypt a secret for storage. Returns the input unchanged when no key is
- * configured or when the value is empty/already encrypted.
+ * configured or when the value is empty/already encrypted. Always writes the
+ * current (v2) format.
  */
 export function encryptSecret<T extends string | null | undefined>(value: T): T | string {
   if (!value) {
     return value
   }
-  const key = getKey()
-  if (!key || isEncrypted(value)) {
+  const raw = getRawKey()
+  if (!raw || isEncrypted(value)) {
     return value
   }
+  const salt = randomBytes(SALT_LEN)
+  const key = deriveV2Key(raw, salt)
   const iv = randomBytes(12)
   const cipher = createCipheriv("aes-256-gcm", bytes(key), bytes(iv))
   const ciphertext = Buffer.concat([bytes(cipher.update(String(value), "utf8")), bytes(cipher.final())])
   const tag = cipher.getAuthTag()
-  return `${PREFIX}${iv.toString("base64")}:${tag.toString("base64")}:${ciphertext.toString("base64")}`
+  return `${PREFIX_V2}${salt.toString("base64")}:${iv.toString("base64")}:${tag.toString("base64")}:${ciphertext.toString("base64")}`
 }
 
 /**
@@ -73,22 +127,31 @@ export function decryptSecret<T extends string | null | undefined>(value: T): T
   if (!value || !isEncrypted(value)) {
     return value
   }
-  const key = getKey()
-  if (!key) {
+  const raw = getRawKey()
+  if (!raw) {
     throw new Error(
       "PayPal secret is encrypted but PAYPAL_ENCRYPTION_KEY is not set. Restore the key to decrypt stored credentials."
     )
   }
-  const body = String(value).slice(PREFIX.length)
+
+  if (String(value).startsWith(PREFIX_V2)) {
+    const body = String(value).slice(PREFIX_V2.length)
+    const [saltB64, ivB64, tagB64, ctB64] = body.split(":")
+    if (!saltB64 || !ivB64 || !tagB64 || !ctB64) {
+      throw new Error("PayPal secret ciphertext is malformed.")
+    }
+    const key = deriveV2Key(raw, Buffer.from(saltB64, "base64"))
+    return gcmDecrypt(key, ivB64, tagB64, ctB64)
+  }
+
+  // Legacy v1 (unsalted SHA-256 key).
+  const body = String(value).slice(PREFIX_V1.length)
   const [ivB64, tagB64, ctB64] = body.split(":")
   if (!ivB64 || !tagB64 || !ctB64) {
     throw new Error("PayPal secret ciphertext is malformed.")
   }
-  const decipher = createDecipheriv("aes-256-gcm", bytes(key), bytes(Buffer.from(ivB64, "base64")))
-  decipher.setAuthTag(bytes(Buffer.from(tagB64, "base64")))
-  const plaintext = Buffer.concat([
-    bytes(decipher.update(bytes(Buffer.from(ctB64, "base64")))),
-    bytes(decipher.final()),
-  ])
-  return plaintext.toString("utf8")
+  if (!legacyV1Key) {
+    throw new Error("PayPal secret is encrypted but PAYPAL_ENCRYPTION_KEY is not set.")
+  }
+  return gcmDecrypt(legacyV1Key, ivB64, tagB64, ctB64)
 }

package/src/modules/paypal/utils/webhook-verify.ts

@@ -0,0 +1,61 @@
+/**
+ * Helpers for calling PayPal's `verify-webhook-signature` API correctly.
+ *
+ * PayPal computes the expected signature over the EXACT bytes it transmitted.
+ * Re-serializing the parsed body (`JSON.stringify(req.body)`) can change those
+ * bytes — key ordering, non-ASCII escaping (`José` vs `José`), number and
+ * whitespace formatting — which makes verification intermittently return
+ * FAILURE for legitimate webhooks. When the original raw body is available we
+ * inject it verbatim as `webhook_event`; otherwise we fall back to serializing
+ * the parsed body so behavior never regresses.
+ */
+
+/** Normalize Medusa's `req.rawBody` (a Buffer when `preserveRawBody` is set) to a string. */
+export function rawBodyToString(rawBody: unknown): string | null {
+  if (rawBody == null) {
+    return null
+  }
+  if (typeof rawBody === "string") {
+    return rawBody.length > 0 ? rawBody : null
+  }
+  if (Buffer.isBuffer(rawBody)) {
+    return rawBody.length > 0 ? rawBody.toString("utf8") : null
+  }
+  if (rawBody instanceof Uint8Array) {
+    return rawBody.length > 0 ? Buffer.from(rawBody).toString("utf8") : null
+  }
+  return null
+}
+
+/**
+ * Compose the JSON request body for `verify-webhook-signature`.
+ *
+ * `fields` are the transmission headers + webhook_id; `webhookEventJson` is the
+ * raw webhook body verbatim (preferred) or a serialized fallback. Undefined /
+ * null header values are omitted. The webhook event is concatenated as raw JSON
+ * (not re-encoded) so the bytes PayPal hashes match what it signed.
+ */
+export function composeVerifyRequestBody(
+  fields: Record<string, string | undefined | null>,
+  webhookEventJson: string
+): string {
+  const head = Object.entries(fields)
+    .filter(([, v]) => v !== undefined && v !== null)
+    .map(([k, v]) => `${JSON.stringify(k)}:${JSON.stringify(v)}`)
+    .join(",")
+  return `{${head}${head ? "," : ""}"webhook_event":${webhookEventJson}}`
+}
+
+/**
+ * Pick the bytes to use for `webhook_event`: the raw body when present and
+ * non-blank, otherwise a JSON serialization of the parsed body.
+ */
+export function resolveWebhookEventJson(
+  rawBody: string | null | undefined,
+  parsedBody: unknown
+): string {
+  if (typeof rawBody === "string" && rawBody.trim().length > 0) {
+    return rawBody
+  }
+  return JSON.stringify(parsedBody ?? {})
+}