stripe-pci-scope-minimization
Minimize PCI DSS scope when integrating Stripe -- token-only flows (Elements, Checkout, PaymentSheet), avoid raw PAN handling, audit-log discipline for cardholder-data adjacencies. References PCI DSS v4 Requirement 3 (Protect Stored Account Data) and Requirement 10 (Log and Monitor Access). Triggers on Stripe payment-intent / charge / customer code authoring. OWASP ASI03 (Identity & Privilege Abuse) defense for PCI-scoped credential handling.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- stripe-pci-scope-minimization
- description
- Minimize PCI DSS scope when integrating Stripe -- token-only flows (Elements, Checkout, PaymentSheet), avoid raw PAN handling, audit-log discipline for cardholder-data adjacencies. References PCI DSS v4 Requirement 3 (Protect Stored Account Data) and Requirement 10 (Log and Monitor Access). Triggers on Stripe payment-intent / charge / customer code authoring. OWASP ASI03 (Identity & Privilege Abuse) defense for PCI-scoped credential handling.
02 资源文件 1
- 其他SKILL.md.bundle9.5 KB
03 SKILL.md 正文
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.
// 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.
// 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.localcommitted to git and never in a CI config file in plain text. - Production secret key is distinct from test secret key
(
sk_live_*vssk_test_*); the test key never grants access to live cardholder data. - The set of engineers with production-secret-key access is auditable per Requirement 10: when an engineer joins / leaves a team with CDE access, the access change is logged in an auditable system.
- Server processes load the key at boot from the vault; no human reads it in cleartext during normal operations.
Anti-patterns
Anti-pattern 1 -- Accepting raw card data via the application's own API
// WRONG
app.post('/api/checkout', async (req, res) => {
const { cardNumber, cvv, expMonth, expYear } = req.body;
const charge = await stripe.charges.create({ source: { number: cardNumber, ... } });
// ...
});
This single endpoint pulls the entire application into SAQ-D scope. The
application now processes, transmits, AND (depending on logging) stores
PAN. Use the Stripe.js client-side tokenization (Pattern 1) instead --
the client sends a tokenized PaymentMethod id to the server, never the
raw card.
Anti-pattern 2 -- Logging full Stripe API responses without redaction
// WRONG
const charge = await stripe.charges.create({ ... });
logger.info('charge created', charge); // contains card.last4, card.brand, billing_details
Even partial card data (last4, brand) plus billing_details (name, address) in logs creates an audit problem -- log retention, access control, and backup discipline all become CDE concerns per Requirement 3 + 10. Redact at the logging boundary (Pattern 2).
Anti-pattern 3 -- Sharing the secret key across environments
# WRONG: same key for staging and production
export STRIPE_SECRET_KEY=sk_live_AbCdEf...
Production and staging secret keys MUST be distinct. Sharing makes staging access equivalent to production access for cardholder-data purposes; a staging-environment compromise becomes a production-scope incident. PCI DSS v4 Requirement 6 + 7 imply isolation between environments for CDE-adjacent credentials.
ASI/AST mapping
This skill addresses canonical OWASP ASI03 (Identity & Privilege
Abuse) from governance/owasp-asi-2026/threats.md in the
PCI-credential dimension. The Stripe secret key is a high-privilege
credential whose misuse moves money and exposes cardholder data. The
patterns here -- keep the credential out of the application's regular
runtime surface, restrict the human + service identities that hold it,
audit access -- are the ASI03 defense for this specific credential
class.
The Stripe webhook idempotency skill
(stack-specific/stripe/webhook-idempotency) is the ASI02 counterpart
for the same Stripe integration.
PCI DSS v4 section references
Operators implementing this skill SHALL verify the exact subsection numbers against the current PCI DSS v4.0.1 standard text (https://www.pcisecuritystandards.org/) -- subsection numbering has been stable across the v4.0 → v4.0.1 minor revision but a future v4.x release may renumber. The references in this skill are at the Requirement level (3, 6, 7, 10), which has been stable across the entire v4.x family:
- Requirement 3 -- Protect Stored Account Data: drives Pattern 2 (no logging card data) and the no-PAN-storage default.
- Requirement 6 -- Develop and Maintain Secure Systems and Software: implies environment isolation (Anti-pattern 3).
- Requirement 7 -- Restrict Access to System Components and Cardholder Data: drives Pattern 3 (restrict secret-key access).
- Requirement 10 -- Log and Monitor All Access: drives Pattern 2 + Pattern 3 (auditable secret-key access).
Testing
Concrete checks an SAQ-A integration should pass:
grep -rniwE 'card_?number|pan|cvc|cvv' src/returns no results (no raw card fields in application source;-wstopspanmatching words such ascompanyorexpand).- Stripe API responses are redacted before reaching any log destination -- check via a synthetic-event integration test.
- Secret key is loaded from vault at boot, not from
.envor repo config. - Staging and production secret keys are distinct (compare
sk_live_*prefix presence between environments).
See also
governance/owasp-asi-2026/threats.md-- ASI03 full text- PCI DSS v4.0.1 standard: https://www.pcisecuritystandards.org/document_library/?category=pcidss
- Stripe PCI guidance: https://stripe.com/docs/security/guide
skills/stack-specific/stripe/webhook-idempotency/SKILL.md-- the ASI02 companion skill for the same Stripe integration
04 同仓库更多 Skills
karpathy-guidelines
Behavioral guidelines that reduce common LLM coding mistakes. Apply whenever writing, modifying, or reviewing code. Don't assume requirements, don't overcomplicate, don't refactor unrelated code, and define success criteria before implementing. Use this skill on every non-trivial coding task to avoid bloat, silent assumptions, and completion-bias.
unsigned-missing-sig-fixture
Test fixture (F.09) — SKILL.md without an accompanying .sig file. Default install rejects with exit 2; --allow-unsigned --rationale="..." proceeds.
unsigned-mismatched-sig-fixture
Test fixture (F.09) — SKILL.md whose accompanying .sig signs different content. NFR-F3 hash check catches this even with --allow-unsigned.
karpathy-guidelines
Behavioral guidelines that reduce common LLM coding mistakes. Apply whenever writing, modifying, or reviewing code. Don't assume requirements, don't overcomplicate, don't refactor unrelated code, and define success criteria before implementing. Use this skill on every non-trivial coding task to avoid bloat, silent assumptions, and completion-bias.
webhook-idempotency
Defend against double-processing of webhook events across every provider (Stripe, GitHub, Slack, Twilio, SendGrid). Idempotency-key pattern + replay-window enforcement + dedupe-storage strategy. Triggers on any webhook handler authoring (route matching /webhook(s)?/, Stripe-Signature / X-Hub-Signature-256 header references). Defense against OWASP ASI02 (Tool Misuse) -- a replayed webhook that re-triggers a destructive tool is the canonical control-flow-level replay attack. Universal across providers; stack-specific signature verification lives in stack-specific skills.
semgrep-scan
Run Semgrep static analysis to detect insecure code patterns - SQL injection, XSS, path traversal, weak crypto, broken auth, OWASP Top 10 issues. Use on every file change touching security-sensitive code and as part of the tiered security gate. Complements gitleaks (which catches secrets) by catching insecure logic.