@easypayment/medusa-payment-paypal 0.9.15 → 0.9.17

package/src/modules/paypal/payment-provider/service.ts

@@ -31,6 +31,7 @@ import {
 } from "../utils/currencies"
 import type PayPalModuleService from "../service"
 import { getPayPalWebhookActionAndData } from "./webhook-utils"
+import { paypalFetch } from "../utils/paypal-fetch"
 
 type Options = {}
 
@@ -110,7 +111,7 @@ class PayPalPaymentProvider extends AbstractPaymentProvider<Options> {
 
   private async getOrderDetails(orderId: string) {
     const { accessToken, base } = await this.getPayPalAccessToken()
-    const resp = await fetch(`${base}/v2/checkout/orders/${encodeURIComponent(orderId)}`, {
+    const resp = await paypalFetch(`${base}/v2/checkout/orders/${encodeURIComponent(orderId)}`, {
       method: "GET",
       headers: {
         Authorization: `Bearer ${accessToken}`,
@@ -395,7 +396,7 @@ class PayPalPaymentProvider extends AbstractPaymentProvider<Options> {
           data.session_id || data.cart_id || data.payment_collection_id || undefined,
       }
 
-      const ppResp = await fetch(`${base}/v2/checkout/orders`, {
+      const ppResp = await paypalFetch(`${base}/v2/checkout/orders`, {
         method: "POST",
         headers: {
           Authorization: `Bearer ${accessToken}`,
@@ -430,7 +431,7 @@ class PayPalPaymentProvider extends AbstractPaymentProvider<Options> {
       if (existingAuthorization) {
         authorization = order
       } else {
-        const authorizeResp = await fetch(
+        const authorizeResp = await paypalFetch(
           `${base}/v2/checkout/orders/${encodeURIComponent(newOrderId)}/authorize`,
           {
             method: "POST",
@@ -613,7 +614,7 @@ class PayPalPaymentProvider extends AbstractPaymentProvider<Options> {
       ).toUpperCase()
 
       if (!authorizationId && resolvedIntent === "AUTHORIZE") {
-        const authorizeResp = await fetch(
+        const authorizeResp = await paypalFetch(
           `${base}/v2/checkout/orders/${encodeURIComponent(orderId)}/authorize`,
           {
             method: "POST",
@@ -668,7 +669,7 @@ class PayPalPaymentProvider extends AbstractPaymentProvider<Options> {
         ? `${base}/v2/payments/authorizations/${encodeURIComponent(authorizationId)}/capture`
         : `${base}/v2/checkout/orders/${encodeURIComponent(orderId)}/capture`
 
-      const ppResp = await fetch(captureUrl, {
+      const ppResp = await paypalFetch(captureUrl, {
         method: "POST",
         headers: {
           Authorization: `Bearer ${accessToken}`,
@@ -781,7 +782,7 @@ class PayPalPaymentProvider extends AbstractPaymentProvider<Options> {
         refundPayload.note_to_payer = refundReason
       }
 
-      const ppResp = await fetch(`${base}/v2/payments/captures/${encodeURIComponent(captureId)}/refund`, {
+      const ppResp = await paypalFetch(`${base}/v2/payments/captures/${encodeURIComponent(captureId)}/refund`, {
         method: "POST",
         headers: {
           Authorization: `Bearer ${accessToken}`,
@@ -871,7 +872,7 @@ class PayPalPaymentProvider extends AbstractPaymentProvider<Options> {
         const { accessToken, base } = await this.getPayPalAccessToken()
         const requestId = this.getIdempotencyKey(input, `void-${authorizationId}`)
 
-        const resp = await fetch(
+        const resp = await paypalFetch(
           `${base}/v2/payments/authorizations/${encodeURIComponent(authorizationId)}/void`,
           {
             method: "POST",
@@ -901,9 +902,9 @@ class PayPalPaymentProvider extends AbstractPaymentProvider<Options> {
         })
       } else if (captureId) {
         const { accessToken, base } = await this.getPayPalAccessToken()
-        const requestId = this.getIdempotencyKey(input, `refund-${captureId}`)
+        const requestId = this.getIdempotencyKey(input, `cancel-refund-${captureId}`)
 
-        const resp = await fetch(`${base}/v2/payments/captures/${encodeURIComponent(captureId)}/refund`, {
+        const resp = await paypalFetch(`${base}/v2/payments/captures/${encodeURIComponent(captureId)}/refund`, {
           method: "POST",
           headers: {
             Authorization: `Bearer ${accessToken}`,

package/src/modules/paypal/payment-provider/webhook-utils.ts

@@ -66,6 +66,18 @@ function resolveEventType(payload: ProviderWebhookPayload["payload"]) {
   return raw?.event_type || raw?.eventType
 }
 
+/**
+ * Maps a PayPal webhook payload to the generic Medusa payment-provider webhook
+ * result (the `getWebhookActionAndData` hook on AbstractPaymentProvider).
+ *
+ * NOTE: the authoritative webhook handling for this plugin is the dedicated
+ * `/store/paypal/webhook` route (signature verification, replay window,
+ * dedup, dead-letter retry). This helper exists only for the framework's
+ * generic `/hooks/payment/:provider` path. The `session_id` returned here is
+ * derived from the PayPal resource `custom_id`, which this plugin sets to the
+ * cart id (see create-order) — so consumers must resolve the cart, not treat
+ * it as a payment-session id directly.
+ */
 export function getPayPalWebhookActionAndData(
   payload: ProviderWebhookPayload["payload"]
 ): WebhookActionResult {

package/src/modules/paypal/service.ts

@@ -1,4 +1,6 @@
 import { MedusaService } from "@medusajs/framework/utils"
+import { paypalFetch } from "./utils/paypal-fetch"
+import { decryptSecret, encryptSecret } from "./utils/secret-crypto"
 import PayPalConnection from "./models/paypal_connection"
 import PayPalMetric from "./models/paypal_metric"
 import PayPalSettings from "./models/paypal_settings"
@@ -15,6 +17,28 @@ type Status =
   | "connected"
   | "revoked"
 
+const SENSITIVE_KEY_RE =
+  /secret|password|client_secret|access_token|refresh_token|authorization|auth_code|api[_-]?key/i
+
+/**
+ * Defensive redaction for audit logs: replace values of keys that look
+ * sensitive with "[REDACTED]". Bounded depth/breadth so a pathological payload
+ * can't blow up logging.
+ */
+function redactSensitive(value: unknown, depth = 0): unknown {
+  if (depth > 6 || value === null || typeof value !== "object") {
+    return value
+  }
+  if (Array.isArray(value)) {
+    return value.slice(0, 50).map((v) => redactSensitive(v, depth + 1))
+  }
+  const out: Record<string, unknown> = {}
+  for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+    out[k] = SENSITIVE_KEY_RE.test(k) ? "[REDACTED]" : redactSensitive(v, depth + 1)
+  }
+  return out
+}
+
 class PayPalModuleService extends MedusaService({
   PayPalConnection,
   PayPalMetric,
@@ -131,7 +155,10 @@ class PayPalModuleService extends MedusaService({
     const creds = meta?.credentials?.[env] || {}
     return {
       clientId: creds.client_id || creds.clientId || undefined,
-      clientSecret: creds.client_secret || creds.clientSecret || undefined,
+      // Secrets are encrypted at rest when PAYPAL_ENCRYPTION_KEY is set; decrypt
+      // here so every consumer (auth, status) sees plaintext. Legacy plaintext
+      // values pass through unchanged.
+      clientSecret: decryptSecret(creds.client_secret || creds.clientSecret) || undefined,
       sellerMerchantId:
         creds.seller_merchant_id ||
         creds.sellerMerchantId ||
@@ -217,7 +244,7 @@ class PayPalModuleService extends MedusaService({
     const baseUrl = env === "live" ? "https://api-m.paypal.com" : "https://api-m.sandbox.paypal.com"
     const accessToken = accessTokenOverride ?? await this.getAppAccessToken()
 
-    const resp = await fetch(
+    const resp = await paypalFetch(
       `${baseUrl}/v1/customer/partners/${encodeURIComponent(
         partnerMerchantId
       )}/merchant-integrations/${encodeURIComponent(merchantId)}`,
@@ -258,7 +285,7 @@ class PayPalModuleService extends MedusaService({
     const body = new URLSearchParams()
     body.set("grant_type", "client_credentials")
 
-    const res = await fetch(`${baseUrl}/v1/oauth2/token`, {
+    const res = await paypalFetch(`${baseUrl}/v1/oauth2/token`, {
       method: "POST",
       headers: {
         "Content-Type": "application/x-www-form-urlencoded",
@@ -314,7 +341,7 @@ class PayPalModuleService extends MedusaService({
     ).trim() || null
 
     try {
-      const userInfoResp = await fetch(`${baseUrl}/v1/identity/oauth2/userinfo?schema=paypalv1`, {
+      const userInfoResp = await paypalFetch(`${baseUrl}/v1/identity/oauth2/userinfo?schema=paypalv1`, {
         method: "GET",
         headers: {
           Authorization: `Bearer ${accessToken}`,
@@ -337,7 +364,7 @@ class PayPalModuleService extends MedusaService({
 
     if (partnerMerchantId) {
       try {
-        const credsResp = await fetch(
+        const credsResp = await paypalFetch(
           `${baseUrl}/v1/customer/partners/${encodeURIComponent(
             partnerMerchantId
           )}/merchant-integrations/credentials/`,
@@ -406,7 +433,8 @@ class PayPalModuleService extends MedusaService({
       id: row.id,
       status: c.clientId && c.clientSecret ? "connected" : "disconnected",
       seller_client_id: c.clientId || null,
-      seller_client_secret: c.clientSecret || null,
+      // c.clientSecret is decrypted (from getEnvCreds); re-encrypt for the column.
+      seller_client_secret: encryptSecret(c.clientSecret) || null,
       seller_merchant_id: c.sellerMerchantId || null,
       seller_email: c.sellerEmail || null,
       metadata: {
@@ -493,7 +521,7 @@ class PayPalModuleService extends MedusaService({
       form.append("products[]", p)
     })
 
-    const res = await fetch(onboarding.partner_service_url, {
+    const res = await paypalFetch(onboarding.partner_service_url, {
       method: "POST",
       headers: { "Content-Type": "application/x-www-form-urlencoded" },
       body: form.toString(),
@@ -634,7 +662,7 @@ class PayPalModuleService extends MedusaService({
 
     const basic = Buffer.from(`${input.sharedId}:`).toString("base64")
 
-    const tokenRes = await fetch(`${baseUrl}/v1/oauth2/token`, {
+    const tokenRes = await paypalFetch(`${baseUrl}/v1/oauth2/token`, {
       method: "POST",
       headers: {
         "Content-Type": "application/x-www-form-urlencoded",
@@ -668,7 +696,7 @@ class PayPalModuleService extends MedusaService({
       throw new Error("Missing PayPal partner merchant id configuration.")
     }
 
-    const credRes = await fetch(
+    const credRes = await paypalFetch(
       `${baseUrl}/v1/customer/partners/${encodeURIComponent(partnerMerchantId)}/merchant-integrations/credentials/`,
       {
         method: "GET",
@@ -767,9 +795,13 @@ class PayPalModuleService extends MedusaService({
     const nextSellerEmail =
       (input.sellerEmail || "").trim() || existingCreds.sellerEmail || row?.seller_email || null
 
+    // Encrypt once and store the same ciphertext in both the metadata copy and
+    // the denormalized column (no-op when encryption is disabled).
+    const storedClientSecret = encryptSecret(input.clientSecret)
+
     const nextCreds = {
       client_id: input.clientId,
-      client_secret: input.clientSecret,
+      client_secret: storedClientSecret,
       merchant_id: nextSellerMerchantId,
       seller_merchant_id: nextSellerMerchantId,
       seller_email: nextSellerEmail,
@@ -780,7 +812,7 @@ class PayPalModuleService extends MedusaService({
         environment: env,
         status: "connected",
         seller_client_id: input.clientId,
-        seller_client_secret: input.clientSecret,
+        seller_client_secret: storedClientSecret,
         seller_merchant_id: nextSellerMerchantId,
         seller_email: nextSellerEmail,
         app_access_token: null,
@@ -811,7 +843,7 @@ class PayPalModuleService extends MedusaService({
       id: row.id,
       status: "connected",
       seller_client_id: input.clientId,
-      seller_client_secret: input.clientSecret,
+      seller_client_secret: storedClientSecret,
       seller_merchant_id: nextSellerMerchantId,
       seller_email: nextSellerEmail,
       app_access_token: null,
@@ -909,7 +941,7 @@ class PayPalModuleService extends MedusaService({
       return webhookIds[env] || ""
     }
 
-    const listResp = await fetch(`${baseUrl}/v1/notifications/webhooks`, {
+    const listResp = await paypalFetch(`${baseUrl}/v1/notifications/webhooks`, {
       headers: {
         Authorization: `Bearer ${accessToken}`,
         "Content-Type": "application/json",
@@ -929,7 +961,7 @@ class PayPalModuleService extends MedusaService({
     let webhookId = existing?.id ? String(existing.id) : ""
 
     if (!webhookId) {
-      const createResp = await fetch(`${baseUrl}/v1/notifications/webhooks`, {
+      const createResp = await paypalFetch(`${baseUrl}/v1/notifications/webhooks`, {
         method: "POST",
         headers: {
           Authorization: `Bearer ${accessToken}`,
@@ -1095,7 +1127,9 @@ class PayPalModuleService extends MedusaService({
     const expiresAt = row.app_access_token_expires_at ? new Date(row.app_access_token_expires_at as string) : null
     if (row.app_access_token && expiresAt) {
       const msLeft = expiresAt.getTime() - Date.now()
-      if (msLeft > 2 * 60 * 1000) return row.app_access_token as string
+      // Token is encrypted at rest when a key is configured; decrypt the cached
+      // value (legacy plaintext passes through unchanged).
+      if (msLeft > 2 * 60 * 1000) return decryptSecret(row.app_access_token as string) as string
     }
 
     if (this.tokenRefreshPromise) {
@@ -1118,7 +1152,7 @@ class PayPalModuleService extends MedusaService({
     const body = new URLSearchParams()
     body.set("grant_type", "client_credentials")
 
-    const res = await fetch(`${baseUrl}/v1/oauth2/token`, {
+    const res = await paypalFetch(`${baseUrl}/v1/oauth2/token`, {
       method: "POST",
       headers: {
         "Content-Type": "application/x-www-form-urlencoded",
@@ -1141,7 +1175,7 @@ class PayPalModuleService extends MedusaService({
 
     await this.updatePayPalConnections({
       id: row.id,
-      app_access_token: accessToken,
+      app_access_token: encryptSecret(accessToken),
       app_access_token_expires_at: newExpiresAt as unknown as Date,
     })
 
@@ -1154,7 +1188,7 @@ class PayPalModuleService extends MedusaService({
 
     const accessToken = await this.getAppAccessToken()
 
-    const res = await fetch(`${baseUrl}/v1/identity/generate-token`, {
+    const res = await paypalFetch(`${baseUrl}/v1/identity/generate-token`, {
       method: "POST",
       headers: {
         Authorization: `Bearer ${accessToken}`,
@@ -1261,7 +1295,7 @@ class PayPalModuleService extends MedusaService({
 
     const accessToken = await this.getAppAccessToken()
 
-    const resp = await fetch(
+    const resp = await paypalFetch(
       `${base}/v2/checkout/orders/${encodeURIComponent(orderId)}`,
       {
         method: "GET",
@@ -1344,7 +1378,28 @@ class PayPalModuleService extends MedusaService({
     })
   }
 
-  async recordAuditEvent(_eventType: string, _metadata?: Record<string, unknown>) {
+  /**
+   * Emit an audit event as a single structured log line.
+   *
+   * The dedicated audit-log table was removed; for high-volume/containerized
+   * deployments the audit trail lives in aggregated stdout logs. This records a
+   * greppable `paypal_audit` line (filter on `"log":"paypal_audit"`) with
+   * sensitive keys redacted. It never throws — audit logging must not break the
+   * caller's payment flow.
+   */
+  async recordAuditEvent(eventType: string, metadata?: Record<string, unknown>) {
+    try {
+      console.info(
+        JSON.stringify({
+          log: "paypal_audit",
+          event_type: eventType,
+          at: new Date().toISOString(),
+          ...(metadata ? { metadata: redactSensitive(metadata) } : {}),
+        })
+      )
+    } catch {
+      // never let audit logging interfere with the payment flow
+    }
     return null
   }
 
@@ -1398,7 +1453,7 @@ class PayPalModuleService extends MedusaService({
     await Promise.all(
       urls.map(async (url) => {
         try {
-          const resp = await fetch(url, {
+          const resp = await paypalFetch(url, {
             method: "POST",
             headers: {
               "Content-Type": "application/json",

package/src/modules/paypal/utils/amounts.ts

@@ -3,12 +3,18 @@ const ZERO_DECIMAL_CURRENCIES = new Set([
   "CLP",
   "DJF",
   "GNF",
+  // PayPal does NOT support decimals for HUF, JPY and TWD — even though HUF and
+  // TWD have 2 ISO 4217 minor digits, PayPal rejects amounts like "1000.00" for
+  // them (DECIMAL_PRECISION). They must be sent as whole numbers ("1000").
+  // See https://developer.paypal.com/api/rest/reference/currency-codes/
+  "HUF",
   "JPY",
   "KMF",
   "KRW",
   "MGA",
   "PYG",
   "RWF",
+  "TWD",
   "UGX",
   "VND",
   "VUV",
@@ -17,7 +23,7 @@ const ZERO_DECIMAL_CURRENCIES = new Set([
   "XPF",
 ])
 
-const THREE_DECIMAL_CURRENCIES = new Set(["BHD", "JOD", "KWD", "OMR", "TND"])
+const THREE_DECIMAL_CURRENCIES = new Set(["BHD", "IQD", "JOD", "KWD", "OMR", "TND"])
 
 export function getCurrencyExponent(currencyCode: string) {
   const code = currencyCode.toUpperCase()
@@ -30,12 +36,15 @@ export function getCurrencyExponent(currencyCode: string) {
   return 2
 }
 
-export function formatAmountForPayPal(
-  minorAmount: number,
-  currencyCode: string
-) {
+/**
+ * Format a Medusa amount for the PayPal REST API.
+ *
+ * Medusa passes monetary amounts to payment providers in MAJOR units
+ * (e.g. `10` for €10.00), and PayPal's Orders/Payments API also expects major
+ * units as a string (e.g. `"10.00"`). So this only fixes the decimal precision
+ * for the currency — it must NOT divide/convert to minor units.
+ */
+export function formatAmountForPayPal(amount: number, currencyCode: string) {
   const exponent = getCurrencyExponent(currencyCode)
-  const factor = 10 ** exponent
-  const majorAmount = Number(minorAmount || 0) / factor
-  return majorAmount.toFixed(exponent)
+  return Number(amount || 0).toFixed(exponent)
 }

package/src/modules/paypal/utils/payment-session.ts

@@ -0,0 +1,104 @@
+import type { IPaymentModuleService } from "@medusajs/framework/types"
+import { Modules } from "@medusajs/framework/utils"
+import { isPayPalProviderId } from "./provider-ids"
+
+/**
+ * Shared PayPal payment-session helpers.
+ *
+ * `create-order` and `capture-order` must agree on (a) which payment session
+ * belongs to a cart and (b) how the PayPal order id is stored/read on it —
+ * otherwise the capture's fail-closed binding (the order id stored by
+ * create-order must equal the one being captured) can never be satisfied.
+ * Keeping the logic here, resolved through the Payment module service
+ * (`Modules.PAYMENT`), guarantees both routes use the same, correct path.
+ */
+
+export type PayPalCartSession = {
+  session_id: string
+  session_data: Record<string, any>
+  session_status: string
+}
+
+/**
+ * Resolve the cart's active PayPal payment session (wallet or card). When a
+ * cart has more than one PayPal session, the most recently created one wins —
+ * both create-order and capture-order rely on this same selection so they
+ * always read and write the same session.
+ */
+export async function findPayPalSessionForCart(
+  cartId: string,
+  scope: any
+): Promise<PayPalCartSession | null> {
+  try {
+    const query = scope.resolve("query")
+    const { data: carts } = await query.graph({
+      entity: "cart",
+      fields: [
+        "id",
+        "payment_collection.payment_sessions.id",
+        "payment_collection.payment_sessions.data",
+        "payment_collection.payment_sessions.status",
+        "payment_collection.payment_sessions.provider_id",
+        "payment_collection.payment_sessions.created_at",
+      ],
+      filters: { id: cartId },
+    })
+    const cart = carts?.[0]
+    const sessions = cart?.payment_collection?.payment_sessions || []
+    const session = sessions
+      .filter((s: any) => isPayPalProviderId(s.provider_id))
+      .sort(
+        (a: any, b: any) =>
+          new Date(b.created_at || 0).getTime() - new Date(a.created_at || 0).getTime()
+      )[0]
+
+    if (!session) return null
+
+    return {
+      session_id: session.id,
+      session_data: (session.data || {}) as Record<string, any>,
+      session_status: session.status,
+    }
+  } catch (e: any) {
+    console.warn("[PayPal] findPayPalSessionForCart failed:", e?.message)
+    return null
+  }
+}
+
+/**
+ * Read the PayPal order id stored on a session's `data`. Accepts both the
+ * canonical `data.paypal.order_id` and the legacy top-level `data.order_id`.
+ * Returns null when none is present.
+ */
+export function getStoredPayPalOrderId(
+  sessionData?: Record<string, any> | null
+): string | null {
+  const paypal = (sessionData?.paypal || {}) as Record<string, unknown>
+  const id = String(paypal.order_id || sessionData?.order_id || "")
+  return id || null
+}
+
+/**
+ * Shallow-merge `extraData` into a payment session's `data`, preserving the
+ * session's amount/currency. Callers that update the nested `paypal` object are
+ * responsible for spreading its existing keys (see `getStoredPayPalOrderId`).
+ */
+export async function updatePayPalSessionData(
+  sessionId: string,
+  extraData: Record<string, any>,
+  scope: any
+): Promise<void> {
+  try {
+    const paymentModule = scope.resolve(Modules.PAYMENT) as IPaymentModuleService
+    const [existing] = await paymentModule.listPaymentSessions({ id: [sessionId] }, { take: 1 })
+    const mergedData = { ...(existing?.data || {}), ...extraData }
+    await (paymentModule as any).updatePaymentSession({
+      id: sessionId,
+      data: mergedData,
+      amount: existing?.amount,
+      currency_code: existing?.currency_code,
+    })
+  } catch (e: any) {
+    console.error("[PayPal] updatePayPalSessionData failed:", e?.message)
+  }
+}

package/src/modules/paypal/utils/paypal-auth.ts

@@ -3,30 +3,3 @@ export function getPayPalApiBase(environment: string): string {
     ? "https://api-m.paypal.com"
     : "https://api-m.sandbox.paypal.com"
 }
-
-const BN_CODE = "MBJTechnolabs_SI_SPB"
-
-export async function getPayPalAccessToken(opts: {
-  environment: string
-  client_id: string
-  client_secret: string
-}): Promise<{ accessToken: string; base: string }> {
-  const base = getPayPalApiBase(opts.environment)
-  const auth = Buffer.from(`${opts.client_id}:${opts.client_secret}`).toString("base64")
-  const resp = await fetch(`${base}/v1/oauth2/token`, {
-    method: "POST",
-    headers: {
-      Authorization: `Basic ${auth}`,
-      "Content-Type": "application/x-www-form-urlencoded",
-      "PayPal-Partner-Attribution-Id": BN_CODE,
-    },
-    body: "grant_type=client_credentials",
-    signal: AbortSignal.timeout(30_000),
-  })
-  const text = await resp.text()
-  if (!resp.ok) {
-    throw new Error(`PayPal token error (${resp.status}): ${text}`)
-  }
-  const json = JSON.parse(text)
-  return { accessToken: String(json.access_token), base }
-}

package/src/modules/paypal/utils/paypal-fetch.ts

@@ -0,0 +1,30 @@
+/**
+ * Default timeout (ms) for all server-side outbound PayPal HTTP calls.
+ *
+ * Without a timeout, a slow or hung PayPal socket holds a Node request handler
+ * (and any DB connection it owns) open indefinitely; under load these
+ * accumulate and exhaust the event loop / connection pool, cascading into
+ * checkout-wide failures. Override with PAYPAL_HTTP_TIMEOUT_MS.
+ */
+export const PAYPAL_HTTP_TIMEOUT_MS = (() => {
+  const v = Number(process.env.PAYPAL_HTTP_TIMEOUT_MS)
+  return Number.isFinite(v) && v > 0 ? v : 30_000
+})()
+
+/**
+ * `fetch` that always enforces a timeout for PayPal / outbound calls. If the
+ * caller already supplies an AbortSignal, it is respected as-is (the caller is
+ * assumed to manage its own deadline).
+ */
+export function paypalFetch(
+  input: string | URL,
+  init: RequestInit = {}
+): Promise<Response> {
+  if (init.signal) {
+    return fetch(input, init)
+  }
+  return fetch(input, {
+    ...init,
+    signal: AbortSignal.timeout(PAYPAL_HTTP_TIMEOUT_MS),
+  })
+}

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

@@ -0,0 +1,94 @@
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from "crypto"
+
+/**
+ * Opt-in encryption-at-rest for PayPal secrets (client secret, app access
+ * token).
+ *
+ * Activated only when `PAYPAL_ENCRYPTION_KEY` is set. When it is unset (the
+ * 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.
+ */
+const PREFIX = "enc:v1:"
+
+let cachedRaw: string | undefined
+let cachedKey: Buffer | null = null
+
+/**
+ * `@types/node` 22.0-22.6 typed `Buffer` as `Buffer<ArrayBufferLike>`, which is
+ * rejected where the `crypto` APIs and `Buffer.concat` expect a plain
+ * `Uint8Array` (the regression was fixed in 22.8). Narrowing each byte view to
+ * `Uint8Array` at the call boundary sidesteps it without changing runtime
+ * behavior, and stays valid on every other `@types/node` / TypeScript version.
+ */
+const bytes = (view: Buffer): Uint8Array => view as unknown as Uint8Array
+
+function getKey(): Buffer | 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
+  }
+  return cachedKey
+}
+
+export function isSecretEncryptionEnabled(): boolean {
+  return getKey() !== null
+}
+
+export function isEncrypted(value: unknown): boolean {
+  return typeof value === "string" && value.startsWith(PREFIX)
+}
+
+/**
+ * Encrypt a secret for storage. Returns the input unchanged when no key is
+ * configured or when the value is empty/already encrypted.
+ */
+export function encryptSecret<T extends string | null | undefined>(value: T): T | string {
+  if (!value) {
+    return value
+  }
+  const key = getKey()
+  if (!key || isEncrypted(value)) {
+    return value
+  }
+  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")}`
+}
+
+/**
+ * Decrypt a stored secret. Returns non-encrypted (legacy plaintext) values
+ * unchanged. Throws if the value is encrypted but no key is configured, or if
+ * authentication fails (wrong key / tampering).
+ */
+export function decryptSecret<T extends string | null | undefined>(value: T): T | string {
+  if (!value || !isEncrypted(value)) {
+    return value
+  }
+  const key = getKey()
+  if (!key) {
+    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)
+  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")
+}