PCI Architecture

This page is the technical reference for Gatelithix’s PCI DSS 4.0.1 architecture. It covers the CDE boundary definition, PAN data flow from ingress to destruction, network segmentation, encryption scheme, audit logging, and access control — with source evidence for each control.

CDE Boundary Definition

The Cardholder Data Environment (CDE) is strictly limited to the gatelithix-pci GCP project. No system outside this project ever stores, processes, or receives raw PAN data.

Systems In CDE (gatelithix-pci project)

Systems Connected to CDE (gatelithix-core project)

These systems communicate with the CDE but never handle raw PANs. They are in scope for PCI assessment with a reduced applicable control set.

Systems Out of Scope

PAN Data Flow

Flow 1: Card Tokenization (PAN Ingress)

When a merchant tokenizes a card, the PAN follows this path:

Key guarantee: The raw PAN exists only in vault process memory for the duration of the encrypt call. The Go []byte slice is zeroed with defer before the handler returns. It is never written to disk, logged, or transmitted to any non-PCI system.

Flow 2: Payment Authorization (PAN Egress via Processor Token)

When a payment is authorized, the gateway resolves a processor token from the vault:

PAN Existence Matrix

Every location where a PAN exists, in any form:

PAN is NEVER present in:

• Core Cloud SQL (gateway database)
• Redis (rate limiting / caching)
• Cloud Pub/Sub messages
• Application logs (PAN-filter slog handler)
• Error responses to merchants
• Audit log entries (log token ref, BIN, last4 — never PAN)
• Dashboard or reporting services

Code references:

Network Segmentation

VPC Architecture

Two separate GCP projects, each with its own VPC, connected via VPC peering:

VPC peering is bidirectional (core-to-pci / pci-to-core) with custom route import/export disabled. Only private IP traffic crosses the peering link. The PCI VPC cannot reach arbitrary core resources.

Firewall Rules

Both VPCs inherit a deny-all baseline at priority 65534 (deny all ingress from 0.0.0.0/0, deny all egress to 0.0.0.0/0). Explicit allow rules at priority 900 permit only minimum required traffic:

Evidence: infra/terraform/pci/network.tf, infra/terraform/modules/vpc/main.tf

PCI Cloud SQL Isolation

• ipv4_enabled = false — no public IP address; private IP only
• ssl_mode = ENCRYPTED_ONLY — rejects non-TLS database connections
• Application uses pgx with sslmode=require
• Accessible only from the PCI VPC serverless connector (10.1.32.0/28)

Evidence: infra/terraform/pci/database.tf

Vault Cloud Run Ingress

The vault Cloud Run service uses INGRESS_TRAFFIC_ALL (required because gateway calls arrive via VPC peering private IPs, not through Cloud Run’s public URL). Network isolation is enforced at the VPC firewall level: pci-vpc-allow-core-ingress restricts inbound traffic to source 10.0.0.0/20, TCP 443 only. There is no public internet path to the vault.

Evidence: infra/terraform/pci/cloudrun.tf

Encryption

Scheme Overview

Gatelithix uses envelope encryption via Google Cloud KMS backed by Cloud HSM:

1. Data Encryption Key (DEK) — A per-PAN AES-256-GCM key generated for each card.
2. Key Encryption Key (KEK) — The Cloud KMS master key (pan-encryption-key) wraps the DEK. The KEK never leaves the HSM.
3. Storage — PCI Cloud SQL stores the encrypted PAN ciphertext and the wrapped DEK together. Neither is useful without the other, and the wrapped DEK is useless without the KMS key.

KMS Keys

Key ring: gatelithix-vault in gatelithix-pci project.

Evidence: infra/terraform/pci/kms.tf

IAM Restriction on KMS Keys

Only the vault service account (vault-sa@gatelithix-pci.iam.gserviceaccount.com) holds the following roles on PAN keys:

• roles/cloudkms.cryptoKeyEncrypterDecrypter on pan-encryption-key
• roles/cloudkms.signerVerifier on pan-fingerprint-key

No other service account, user, or service has access to these keys. Gateway, connector, and other service accounts have no KMS bindings.

Evidence: infra/terraform/pci/kms.tf IAM bindings section

Crypto-Shredding

Because the master key (pan-encryption-key) wraps all DEKs, destroying a key version makes all PANs encrypted with that version permanently unrecoverable. This enables crypto-shredding for GDPR right-to-erasure without physically deleting encrypted ciphertext rows.

Encryption in Transit

All paths carrying cardholder data use TLS 1.2 or higher:

Evidence: infra/terraform/pci/cloudrun.tf, infra/terraform/pci/database.tf, apps/vault/db/db.go (sslmode=require)

Audit Logging

What Is Logged

Every access to the vault decrypt endpoint produces an audit entry. The vault never logs the PAN itself. Each audit record contains:

Evidence: apps/vault/handlers/tokenize.go:263-278, apps/vault/handlers/resolve.go audit call

Log Storage and Retention

Audit logs flow through two sinks:

1. PCI Audit Log Bucket — Cloud Logging bucket with locked = true (tamper-resistant), 365-day retention.
2. PCI Audit Archive — Cloud Storage NEARLINE bucket with versioning and locked retention (365 days), for long-term archival.

Both sinks capture cloudaudit.googleapis.com log entries from the gatelithix-pci project.

Evidence: infra/terraform/pci/logging.tf

Tamper Protection

The audit log bucket uses locked = true on its retention policy. This prevents retention period reduction and log deletion, including by project owners. Once a log entry reaches the bucket, it cannot be modified or deleted before the retention period expires.

GCP Cloud Audit Logs also records all Admin Activity in the gatelithix-pci project (IAM changes, resource creation/deletion), providing an additional immutable audit trail.

Evidence: infra/terraform/pci/logging.tf — locked = true, retention_days = 365

Access Control

Service Account Model

Each service runs with a dedicated service account. No service account holds roles beyond what it needs.

No service account uses default credentials or has wildcard roles (roles/editor, roles/owner). All authentication uses Workload Identity — no service account key files are downloaded or stored.

Evidence: infra/terraform/pci/kms.tf, infra/terraform/core/iam.tf

Application RBAC

The gateway enforces role-based access on all API endpoints via pkg/auth/rbac.go:

All payment read queries filter by merchant_id from the auth context. Cross-tenant payment IDs return 404 (not 403) to prevent information disclosure.

Evidence: pkg/auth/rbac.go

MFA Enforcement

Evidence: GCP IAM org policy configuration; Auth0 tenant MFA policy

API Key Security

API keys are stored hashed with SHA-256 in Core Cloud SQL. The plaintext key is shown once at creation and never stored. Each API key has a unique per-key HMAC secret for webhook signature generation (resolved at request time by pkg/hmac/resolver.go). Keys can be revoked instantly from the dashboard.

Evidence: db/migrations/023_add_hmac_secret_to_api_keys.sql, pkg/hmac/resolver.go

Evidence Summary for QSA

For deployed verification commands (gcloud, terraform) for each of these controls, see PCI Verification Evidence.