PCI DSS v4.0.1 - Cardholder Data, CDE Scoping, Segmentation, Tokenization, SAQ Types & Payment Page Scripts

"""PCI scope reduction with a token vault - toy, stdlib only.

Concept first:
  * PAN (card number) is cardholder data; CVV2/CVC2, full track and PIN blocks are
    SENSITIVE AUTHENTICATION DATA (SAD). SAD must never be stored after
    authorization, not even encrypted (PCI DSS 3.3.1).
  * Tokenization swaps the PAN for a surrogate. Systems that only ever see tokens
    can drop out of PCI scope; the vault (and anything that can detokenize) stays in.
  * Encryption is different: whoever holds the key can decrypt, so systems storing
    encrypted PAN usually stay in scope unless the key is held by someone else.
  * Display masking: show at most BIN + last four (PCI DSS 3.4.1).
The cipher here is a dependency-free HMAC-SHA256 keystream + tag so the demo runs
anywhere; real vaults use AES-GCM with HSM/KMS-held keys.
"""
import hmac, hashlib, secrets

def luhn_ok(pan: str) -> bool:
    total, alt = 0, False
    for ch in reversed(pan):
        d = int(ch)
        if alt:
            d = d * 2 - 9 if d * 2 > 9 else d * 2
        total, alt = total + d, not alt
    return total % 10 == 0

def _stream(key: bytes, nonce: bytes, n: int) -> bytes:
    out, ctr = b"", 0
    while len(out) < n:
        out += hmac.new(key, nonce + ctr.to_bytes(4, "big"), hashlib.sha256).digest()
        ctr += 1
    return out[:n]

class Vault:
    """The only component that ever stores PAN. Lives in the CDE."""
    def __init__(self) -> None:
        self._enc_key, self._mac_key = secrets.token_bytes(32), secrets.token_bytes(32)
        self._rows: dict[str, tuple[bytes, bytes, bytes]] = {}

    def tokenize(self, pan: str, **extra) -> str:
        if extra.keys() & {"cvv", "cvc", "track", "pin"}:
            raise ValueError("refusing to store sensitive authentication data (PCI DSS 3.3.1)")
        if not luhn_ok(pan):
            raise ValueError("not a valid PAN")
        while True:   # random token, same length, keeps last 4, deliberately FAILS Luhn
            tok = "9" + "".join(secrets.choice("0123456789") for _ in range(len(pan) - 5)) + pan[-4:]
            if not luhn_ok(tok) and tok not in self._rows:
                break
        nonce = secrets.token_bytes(12)
        ct = bytes(a ^ b for a, b in zip(pan.encode(), _stream(self._enc_key, nonce, len(pan))))
        tag = hmac.new(self._mac_key, nonce + ct, hashlib.sha256).digest()
        self._rows[tok] = (nonce, ct, tag)
        return tok

    def detokenize(self, tok: str, caller: str) -> str:
        if caller != "payment-gateway-adapter":            # least privilege: one caller may detokenize
            raise PermissionError(f"{caller} may not detokenize")
        nonce, ct, tag = self._rows[tok]
        if not hmac.compare_digest(tag, hmac.new(self._mac_key, nonce + ct, hashlib.sha256).digest()):
            raise ValueError("tampered")
        return bytes(a ^ b for a, b in zip(ct, _stream(self._enc_key, nonce, len(ct)))).decode()

def mask(pan_or_token: str) -> str:
    return pan_or_token[:6] + "*" * (len(pan_or_token) - 10) + pan_or_token[-4:]

if __name__ == "__main__":
    v = Vault()
    pan = "4111111111111111"                                  # well-known test PAN
    tok = v.tokenize(pan)
    order_row = {"order": 1001, "card_token": tok, "last4": tok[-4:], "brand": "visa"}
    print("PAN Luhn valid:", luhn_ok(pan), "| token Luhn valid:", luhn_ok(tok), "| same last4:", tok[-4:] == pan[-4:])
    print("orders DB stores (out of scope if it never sees PAN):", {**order_row, "card_token": "9" + "#" * 11 + tok[-4:]})
    print("receipt shows:", mask(pan))
    print("gateway adapter detokenizes:", v.detokenize(tok, "payment-gateway-adapter") == pan)
    for caller in ("analytics-job",):
        try:
            v.detokenize(tok, caller)
        except PermissionError as e:
            print("blocked:", e)
    try:
        v.tokenize(pan, cvv="123")
    except ValueError as e:
        print("blocked:", e)

PAN Luhn valid: True | token Luhn valid: False | same last4: True
orders DB stores (out of scope if it never sees PAN): {'order': 1001, 'card_token': '9###########1111', 'last4': '1111', 'brand': 'visa'}
receipt shows: 411111******1111
gateway adapter detokenizes: True
blocked: analytics-job may not detokenize
blocked: refusing to store sensitive authentication data (PCI DSS 3.3.1)

// PCI DSS scoping: which systems are in scope under three checkout designs?
// Concept: the CDE is every system that stores, processes or transmits account
// data. Systems that CONNECT to the CDE or can AFFECT ITS SECURITY (IdP, CI/CD,
// logging, jump hosts, the web server that serves the payment page) are in scope
// too. Segmentation and outsourcing shrink the set; the SAQ you qualify for
// follows from who controls the payment page and who touches the PAN.

type Role = "CDE" | "connected/security-impacting" | "out of scope";
interface System { name: string; touchesPan: boolean; links: string[]; servesPaymentPage?: boolean }
interface Design { name: string; systems: System[]; pageFrom: "merchant" | "merchant-js" | "psp-iframe" }

function classify(d: Design): Map<string, Role> {
  const role = new Map<string, Role>();
  for (const s of d.systems) role.set(s.name, s.touchesPan ? "CDE" : "out of scope");
  for (const s of d.systems) {
    if (role.get(s.name) === "CDE") continue;
    const linked = s.links.some((l) => role.get(l) === "CDE") ||
      d.systems.some((o) => role.get(o.name) === "CDE" && o.links.includes(s.name));
    if (linked || s.servesPaymentPage) role.set(s.name, "connected/security-impacting");
  }
  // if YOUR code builds the payment form (A-EP), anything that can change the page
  // server (IdP that grants deploy rights, CI/CD that ships it) is security-impacting too
  if (d.pageFrom === "merchant-js") {
    const page = d.systems.find((s) => s.servesPaymentPage);
    for (const l of page?.links ?? []) if (l === "IdP/SSO" || l === "CI/CD") role.set(l, "connected/security-impacting");
  }
  return role;
}

function saq(d: Design, role: Map<string, Role>): string {
  const merchantTouchesPan = d.systems.some((s) => s.touchesPan && !s.name.startsWith("PSP"));
  if (merchantTouchesPan) return "SAQ D (or ROC if Level 1)";
  if (d.pageFrom === "merchant-js") return "SAQ A-EP (your page controls how card data reaches the PSP)";
  if (d.pageFrom === "psp-iframe") return "SAQ A (all payment fields served by the PSP; confirm script-attack protection)";
  return "SAQ D";
}

const shared: System[] = [
  { name: "IdP/SSO", touchesPan: false, links: [] },
  { name: "CI/CD", touchesPan: false, links: [] },
  { name: "analytics warehouse", touchesPan: false, links: ["orders DB"] },
  { name: "orders DB", touchesPan: false, links: [] },
];
const designs: Design[] = [
  { name: "A) form posts PAN to your API", pageFrom: "merchant", systems: [
    { name: "web app", touchesPan: true, links: ["orders DB", "IdP/SSO", "CI/CD"], servesPaymentPage: true },
    { name: "payments API", touchesPan: true, links: ["orders DB", "IdP/SSO", "CI/CD", "PSP"] },
    { name: "PSP", touchesPan: true, links: [] }, ...shared] },
  { name: "B) your JS posts PAN straight to PSP", pageFrom: "merchant-js", systems: [
    { name: "web app", touchesPan: false, links: ["orders DB", "IdP/SSO", "CI/CD"], servesPaymentPage: true },
    { name: "PSP", touchesPan: true, links: [] }, ...shared] },
  { name: "C) PSP-hosted iframe fields + tokens", pageFrom: "psp-iframe", systems: [
    { name: "web app", touchesPan: false, links: ["orders DB", "IdP/SSO", "CI/CD"], servesPaymentPage: true },
    { name: "PSP", touchesPan: true, links: [] }, ...shared] },
];

for (const d of designs) {
  const role = classify(d);
  const yours = [...role.entries()].filter(([n]) => !n.startsWith("PSP"));
  const inScope = yours.filter(([, r]) => r !== "out of scope");
  console.log(`== ${d.name}`);
  console.log(`   in scope (yours): ${inScope.map(([n, r]) => `${n}[${r === "CDE" ? "CDE" : "conn"}]`).join(", ") || "none"}`);
  console.log(`   validation: ${saq(d, role)}`);
}

== A) form posts PAN to your API
   in scope (yours): web app[CDE], payments API[CDE], IdP/SSO[conn], CI/CD[conn], orders DB[conn]
   validation: SAQ D (or ROC if Level 1)
== B) your JS posts PAN straight to PSP
   in scope (yours): web app[conn], IdP/SSO[conn], CI/CD[conn]
   validation: SAQ A-EP (your page controls how card data reaches the PSP)
== C) PSP-hosted iframe fields + tokens
   in scope (yours): web app[conn]
   validation: SAQ A (all payment fields served by the PSP; confirm script-attack protection)