Security & Compliance
=====================

Defence in Depth
----------------

Security controls are layered across the edge, transport, application, and
data tiers.

Edge Controls
~~~~~~~~~~~~~

- **Authentication.** JWT bearer tokens (HS256) for dashboard sessions,
  prefixed API keys for programmatic access, super-admin tokens for internal
  operations, and dedicated authentication for hosted payment pages.
- **Rate limiting.** Per-tenant token-bucket rate limiting at the gateway,
  with a separate limiter for payment-link surfaces.
- **Idempotency.** Redis-backed idempotency middleware on POST requests; keys
  propagate downstream as gRPC metadata so double submission cannot double
  spend.
- **Network controls.** Allowed-host enforcement, explicit CORS policy, and
  IP whitelist middleware for partner API surfaces.
- **Tenant IP controls.** Tenants can whitelist/blacklist IP addresses for
  their API access via the Identity service.

Transport Security
~~~~~~~~~~~~~~~~~~

- TLS on all external traffic; TLS with pinned CA bundles (layered over
  native roots) for cross-environment gRPC.
- Kafka TLS with certificate-based client authentication in sandbox and live.
- Tenant and user context propagated as authenticated gRPC metadata and
  validated at each service (``x-tenant-id``, ``x-user-id``,
  ``x-session-id``).

Application Controls
~~~~~~~~~~~~~~~~~~~~

- **Per-RPC authorization interceptors** in every gRPC service; a live-access
  gate in the Identity service controls production access per tenant.
- **Dual authorization** for high-value operations: OTC orders and transfers
  require a second approver (approve/reject workflows with separate approval
  records).
- **Webhook signing.** Outbound merchant webhooks are HMAC-SHA256 signed with
  per-tenant secrets; inbound provider requests use provider-specific
  signature schemes (HMAC for Dlocal, Duplo HMAC-SHA512, Yellow Card, Fincra,
  Yolat, Thunes with a secret webhook path).
- **Custody signing.** Every mutating custody operation is user-action signed
  against Dfns with an ECDSA P-256 key (challenge–response), so wallet
  operations cannot be replayed or forged.
- **Card data.** Card PANs and sensitive authentication data are never stored;
  card processing is delegated to tokenized provider services (Coinflow
  card-on-file tokens), with card-on-file velocity limits enforced.

Data Protection
~~~~~~~~~~~~~~~

- Field-level AES encryption of sensitive columns with a dedicated
  sensitive-data key separate from the default encryption key (Identity,
  Onramp).
- KYC document data encrypted at rest with a dedicated document encryption
  key (Risk).
- All secrets held in GCP Secret Manager, namespaced per environment; Docker
  images are distroless/minimal with no embedded credentials.

Auditability & Monitoring
-------------------------

- Every service emits audit traces to the Audit service
  (``audit.events.log``); response logs and session-level request logging
  capture full request context.
- Entity-level audit-log tables in the Billing service (fees, invoices,
  subscriptions) and API-key audit logs in the Identity service.
- Kafka-driven transaction monitoring in the Risk service evaluates every
  transfer (``transactions.monitoring.initiate`` → ``passed`` / ``failed``).
- Structured logging platform-wide (zap / zerolog / tracing) with health
  endpoints on every service; operational alerts to Slack.

Compliance Posture
------------------

- **KYC / KYB.** Customer and business verification is operated through
  Sumsub (identity verification, document collection, liveness), with
  verification state gating feature activation across accounts and cards.
- **Feature gating.** The Risk service enforces feature eligibility: product
  capabilities (accounts, cards) activate only after the required
  verification level is met.
- **Sanctions / monitoring.** Transaction monitoring rules run on every
  money-movement event before settlement proceeds.
- **PCI scope minimisation.** Gravv does not store PANs; card flows run
  through PCI-DSS-compliant partner processors with tokenization.
- **Partner-delegated regulation.** Banking, card issuing, and payout
  execution are performed by regulated partners in each jurisdiction;
  Gravv maintains reconciliation and audit trails against partner records.