> For the complete documentation index, see [llms.txt](https://host2host.onibonje.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://host2host.onibonje.com/docs/09-security-and-compliance.md).

# Security and Compliance

## 1. Overview

The H2H platform handles sensitive financial data across 20+ countries. Security is embedded at every layer — perimeter, transport, data, access control, and audit — not bolted on as an afterthought.

## 2. Security Principles

| Principle             | Implementation                                        |
| --------------------- | ----------------------------------------------------- |
| Defense in depth      | Multiple security layers from gateway to core banking |
| Least privilege       | RBAC with country/partner-scoped permissions          |
| Zero trust            | mTLS between services, no implicit trust              |
| Secrets isolation     | Vault for all credentials; never in DB or code        |
| Encryption everywhere | TLS in transit, PGP for files, encryption at rest     |
| Immutable audit       | Append-only logs for transactions and config changes  |
| Fail secure           | Reject on auth/validation failure; no silent bypass   |

## 3. Perimeter Security

### 3.1 H2H Gateway

| Control         | Implementation                                   |
| --------------- | ------------------------------------------------ |
| Authentication  | mTLS certificates, API keys, SFTP key-based auth |
| Authorization   | Partner-to-product mapping in config DB          |
| IP allowlisting | Per-partner IP ranges (DB-driven)                |
| Rate limiting   | Per partner tier (gateway enforcement)           |
| DDoS protection | WAF / cloud-native DDoS mitigation               |
| TLS             | TLS 1.2+ mandatory; TLS 1.3 preferred            |

### 3.2 SFTP Security

| Control        | Implementation                               |
| -------------- | -------------------------------------------- |
| Authentication | SSH key pairs (no password auth)             |
| Key management | Keys stored in Vault; rotated per policy     |
| Chroot         | Partners restricted to assigned directories  |
| PGP encryption | Inbound files encrypted with bank public key |
| File integrity | Checksum verification on ingestion           |

### 3.3 API Security

| Control          | Implementation                                   |
| ---------------- | ------------------------------------------------ |
| Authentication   | OAuth2 client credentials, API keys, mTLS        |
| Authorization    | Scoped tokens per partner and product            |
| Input validation | Schema validation before processing              |
| OWASP compliance | Protection against injection, XSS (admin portal) |
| Request signing  | Optional HMAC signature verification per partner |

## 4. Data Protection

### 4.1 Encryption in Transit

| Channel              | Encryption                         |
| -------------------- | ---------------------------------- |
| Client → Gateway     | TLS 1.2+ / mTLS                    |
| Gateway → Runtime    | mTLS (service mesh)                |
| Runtime → Finacle    | TLS / bank-internal secure channel |
| Runtime → Kafka      | TLS + SASL                         |
| Runtime → PostgreSQL | TLS                                |
| SFTP file transfer   | SSH + PGP                          |

### 4.2 Encryption at Rest

| Data Store             | Encryption                                           |
| ---------------------- | ---------------------------------------------------- |
| PostgreSQL             | Transparent data encryption (TDE) or disk encryption |
| Kafka                  | Encrypted volumes                                    |
| Object storage (files) | Server-side encryption (SSE)                         |
| Vault                  | Encrypted storage backend                            |

### 4.3 PGP File Encryption

```
Partner encrypts file with Bank's public PGP key
        │
        ▼
SFTP upload to gateway
        │
        ▼
Runtime: crypto:pgpDecrypt (private key from Vault)
        │
        ▼
Process cleartext (in-memory only, never persisted unencrypted)
        │
        ▼
Outbound ACK: crypto:pgpEncrypt (partner's public key from config)
```

PGP key material is **never** stored in the database. Only Vault path references:

```json
{
  "pgpDecryptKeyRef": "vault:secret/pgp/bank/private-key",
  "pgpEncryptKeyRef": "vault:secret/pgp/partner/acme/public-key"
}
```

### 4.4 Data Masking

| Context        | Masking                                     |
| -------------- | ------------------------------------------- |
| Logs           | Account numbers masked (show last 4 digits) |
| Admin UI       | PAN/account masking based on role           |
| Audit export   | Full data only for authorized auditor role  |
| Partner portal | Own data only, no cross-partner visibility  |

## 5. Secrets Management

### 5.1 HashiCorp Vault

All secrets are stored in Vault:

| Secret Type          | Vault Path Pattern                            |
| -------------------- | --------------------------------------------- |
| SFTP private keys    | `secret/sftp/{country}/{partner}/private-key` |
| PGP keys             | `secret/pgp/{entity}/key`                     |
| API keys             | `secret/api/{partner}/key`                    |
| Finacle credentials  | `secret/finacle/{region}/service-account`     |
| Database credentials | `secret/db/{environment}/runtime`             |

### 5.2 Secret Access Pattern

```java
@Component
public class VaultCredentialResolver {
    public String resolvePrivateKey(String vaultPath) {
        return vaultTemplate.read(vaultPath).getData().get("key");
    }
}
```

* Runtime pods authenticate to Vault via Kubernetes service account
* Secrets are cached in-memory with short TTL (5 minutes)
* Secret rotation triggers cache invalidation via Vault event webhook

### 5.3 What Never Goes in the Database

| Prohibited                  | Alternative                             |
| --------------------------- | --------------------------------------- |
| Passwords                   | Vault                                   |
| Private keys                | Vault                                   |
| API key values              | Vault (DB stores key ID reference only) |
| PGP key material            | Vault                                   |
| Finacle service credentials | Vault                                   |

## 6. Access Control

### 6.1 Internal Users

* SSO integration with bank Active Directory (SAML/OIDC via Keycloak)
* MFA enforced for admin portal access
* Role assignments scoped by country and partner
* Session timeout per bank security policy

### 6.2 External Partners

* Dedicated Keycloak realm for partner users
* MFA on login
* IP-restricted access (optional per partner)
* API access via client credentials with scoped tokens
* mTLS for high-security partners

### 6.3 Service Accounts

* Kubernetes service accounts for pod-to-pod auth
* Vault policies per service (runtime, admin, gateway)
* No shared service accounts across environments

## 7. Audit and Compliance

### 7.1 Transaction Audit

Every transaction generates an immutable audit trail:

| Event                    | Data Captured                                |
| ------------------------ | -------------------------------------------- |
| File received            | Partner, filename, size, checksum, timestamp |
| Validation result        | Pass/fail, error codes                       |
| Transform applied        | Spec ID, version                             |
| Finacle request/response | Correlation ID, status, response code        |
| ACK generated            | Filename, delivery status                    |
| Exception                | Error type, retry count, resolution          |

Audit events are published via `EventPublisher.publish("AUDIT_EVENT", ...)` — physical topic from `event_channel_def` — and persisted to an append-only store.

### 7.2 Configuration Audit

Every configuration change is logged (see [Database-Driven Configuration](/docs/04-database-driven-configuration.md)):

* Who made the change
* What changed (before/after JSON snapshots)
* When (timestamp)
* Approval reference (Camunda process ID)
* Config version number

### 7.3 Retention Policy

| Data Type         | Retention                                   | Storage                  |
| ----------------- | ------------------------------------------- | ------------------------ |
| Transaction audit | 7+ years (per regulatory requirement)       | Append-only DB + archive |
| Config audit      | 7+ years                                    | PostgreSQL               |
| File archives     | Per partner agreement (typically 3-7 years) | Object storage           |
| Application logs  | 90 days hot, 1 year archive                 | OpenSearch               |
| Idempotency keys  | 30-90 days (configurable)                   | Redis/PostgreSQL         |

### 7.4 Regulatory Compliance

| Requirement             | Implementation                                            |
| ----------------------- | --------------------------------------------------------- |
| Data residency          | Regional deployment; data stays in-region                 |
| Right to audit          | Auditor role with read-only access to all audit data      |
| Change management       | Draft → approve → publish with full audit trail           |
| Segregation of duties   | Onboarding officer cannot publish; ops cannot edit config |
| PCI DSS (if applicable) | No card data stored; tokenization at gateway              |

## 8. Network Security

```mermaid
flowchart TB
  subgraph dmz [DMZ]
    GW[API Gateway]
    SFTP_GW[SFTP Gateway]
  end

  subgraph app [Application Zone]
    RT[Runtime Pods]
    ADMIN[Admin API]
  end

  subgraph data [Data Zone]
    DB[(PostgreSQL)]
    KAFKA[Kafka]
    VAULT[Vault]
  end

  subgraph core [Core Banking Zone]
    FIN[Finacle]
  end

  Internet -->|TLS/mTLS| dmz
  dmz -->|mTLS| app
  app -->|mTLS| data
  app -->|TLS| core
```

* Network policies restrict pod-to-pod communication
* Service mesh enforces mTLS within the application zone
* Finacle access restricted to runtime pods only
* Admin portal accessible only via bank internal network or VPN

## 9. Vulnerability Management

| Activity                                     | Frequency                           |
| -------------------------------------------- | ----------------------------------- |
| Dependency scanning (OWASP Dependency-Check) | Every CI build                      |
| Container image scanning (Trivy)             | Every image build                   |
| Penetration testing                          | Annual (or per bank policy)         |
| Security patch management                    | Critical: 48 hours; High: 7 days    |
| ArchUnit security rules                      | Every CI build (no secrets in code) |

## 10. Incident Response

| Severity                                   | Response Time | Actions                                                     |
| ------------------------------------------ | ------------- | ----------------------------------------------------------- |
| Critical (data breach, system compromise)  | Immediate     | Isolate affected pods, rotate secrets, notify security team |
| High (auth bypass, failed integrity check) | 1 hour        | Block affected partner, investigate, patch                  |
| Medium (suspicious access pattern)         | 4 hours       | Review audit logs, adjust policies                          |
| Low (failed login attempts)                | 24 hours      | Monitor, rate-limit if persistent                           |

## 11. Related Documents

* [Personas and RBAC](/docs/06-personas-and-rbac.md)
* [Database-Driven Configuration](/docs/04-database-driven-configuration.md)
* [Multi-Country Deployment](/docs/07-multi-country-deployment.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://host2host.onibonje.com/docs/09-security-and-compliance.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.