stripe-pci-scope-minimization

Files (1)

• SKILL.md

SKILL.md (first lines)

# Stripe PCI Scope Minimization

> Defends against **OWASP ASI03 (Identity & Privilege Abuse)** in the
> PCI-scoped credential dimension. PCI DSS classifies any system that
> processes, stores, or transmits cardholder data as "in scope" for full
> PCI compliance; "in scope" means a 12-requirement audit surface with
> teeth. The patterns here keep the application OUT of scope wherever
> possible -- token-only flows where Stripe-hosted UI handles raw card
> data, and tight discipline on the few places card-related data crosses
> the application boundary.

**Tradeoff:** Token-only flows give up some UX flexibility (Stripe's
Elements / Checkout / PaymentSheet host the card-data UI on Stripe's
domain). The benefit: the bulk of PCI DSS v4 requirements don't apply
to a SAQ-A integration where the app never sees a primary account number
(PAN). Self-hosted card data collection means SAQ-D scope: 200+ pages of
audit checklist.

---

## Why this matters

PCI DSS v4.0 (released March 2022; v4.0.1 minor revision June 2024)
has several SAQs (Self-Assessment Questionnaires); the four that decide
scope for a Stripe integration are:

- **SAQ-A**: e-commerce merchants who fully outsource cardholder-data
  handling to a PCI-DSS-validated third party. Smallest scope.
- **SAQ-A-EP**: e-commerce where the merchant's site loads the
  card-collection UI but doesn't see the card data itself.
- **SAQ-D-Merchant**: merchants who handle PAN themselves.
- **SAQ-D-Service-Provider**: for SaaS that processes card data on
  behalf of others.

Stripe's hosted flows (Checkout, PaymentSheet, Payment Element with
client-side `stripe.confirmPayment`) keep most integrations in SAQ-A.
The moment the application reads, stores, or transmits raw card data
-- even briefly, even in memory -- scope balloons.

---

## Pattern 1 -- Use Stripe's hosted card-collection UI

The card-data UI runs on Stripe's domain (via iframes or hosted-page
redirects). The application receives back a tokenized identifier (a
`PaymentMethod` id, format `pm_...`, or a `PaymentIntent` id `pi_...`)
that references the card on Stripe's side. The PAN never reaches the
application.

```ts
// Server: create a PaymentIntent that the client will confirm.
const pi = await stripe.paymentIntents.create({
  amount: 1999,
  currency: 'usd',
  customer: customerId,
  automatic_payment_methods: { enabled: true },
});

// Client: confirm using Stripe.js (loads from stripe.com -- iframed
// PCI-scoped UI on Stripe's domain). The page never touches raw PAN.
// `elements` was created with pi.client_secret and mounts the Payment Element.
const result = await stripe.confirmPayment({
  elements,  // Stripe.js managed Payment Element, scoped to Stripe's domain
  confirmParams: { return_url: 'https://example.test/checkout/complete' },
});
```

After confirmation, the application stores ONLY the `PaymentIntent.id`
or `PaymentMethod.id`. These tokens are useless to an attacker who
breaches the application database; they only function with the Stripe
secret key.

---

## Pattern 2 -- Never log card data, ever

PCI DSS v4 **Requirement 3 -- Protect Stored Account Data** restricts
storage of full PAN, sensitive authentication data (SAD: CVV, full
track data, PIN blocks), and similar. **Sensitive authentication data
SHALL NOT be stored after authorization, even if encrypted.**
**Requirement 10 -- Log and Monitor All Access** also imposes
restrictions on what audit logs may contain about cardholder data.

The simplest interpretation: do not log card-related fields. If a
log line happens to contain a PaymentIntent object from a Stripe API
response, redact the `payment_method` details before serializing.

```ts
// Redact card-related fields before logging.
function redactCardData<T extends { payment_method?: unknown; charges?: unknown }>(obj: T): T {
  const copy = JSON.parse(JSON.stringify(obj)) as T;
  if (copy.payment_method) {
    copy.payment_method = '[REDACTED]' as never;
  }
  if (copy.charges && typeof copy.charges === 'object') {
    // ... recursively redact charge.payment_method_details ...
  }
  return copy;
}

console.log('payment intent processed', redactCardData(paymentIntent));
```

This applies to error paths too -- a try / catch that logs an Error
whose `.message` contains the raw API response leaks the card details
into log storage. Use Stripe error subtypes (`Stripe.errors.*`) and log
only `err.code` + `err.type`, never the full error object.

---

## Pattern 3 -- Restrict who has access to the Stripe secret key

PCI DSS v4 **Requirement 7 -- Restrict Access to System Components**
applies to systems that touch the cardholder-data environment (CDE);
the Stripe secret key is one such credential. Discipline:

- The secret key lives in a vault (1Password, AWS Secrets Manager,
  HashiCorp Vault, Doppler), never in `.env.local` committed to git
  and never in a CI config file in plain text.

From MILTONADINA/DevOPs, MIT.

More from MILTONADINA/DevOPs