> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vultlocal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Security

> Security policies and best practices for OLIVE

# Security Reference

Comprehensive security guide covering authentication, encryption, compliance, and operational security.

## Authentication Methods

OLIVE supports multiple authentication mechanisms for different use cases:

<CardGroup cols={2}>
  <Card title="API Keys" icon="key">
    **Third-party integrations**

    `Authorization: Bearer olive_live_xxx`
  </Card>

  <Card title="JWT Tokens" icon="lock">
    **Admin dashboard**

    `Authorization: Bearer eyJhbG...`
  </Card>

  <Card title="HMAC Signatures" icon="fingerprint">
    **POS and partner integrations**

    `X-API-Key-ID` + `X-Timestamp` + `X-Signature`
  </Card>

  <Card title="Service Auth" icon="server">
    **Internal services**

    `X-Service-Name` + `X-Service-Timestamp` + `X-Service-Signature`
  </Card>
</CardGroup>

***

## API Key Authentication

API keys are used for third-party integrations:

```bash theme={null}
curl -X GET "https://demo.api.vultlocal.com/api/v1/balance/user123" \
  -H "Authorization: Bearer olive_live_XXXXXXXXXXXXXXXX"
```

### Key Formats

| Environment | Prefix        | Example                |
| ----------- | ------------- | ---------------------- |
| Production  | `olive_live_` | `olive_live_abc123xyz` |
| Sandbox     | `olive_test_` | `olive_test_abc123xyz` |

### Key Scopes

| Scope   | Access                       |
| ------- | ---------------------------- |
| `read`  | Balance, transaction history |
| `write` | Create payments, transfers   |
| `admin` | User management, settings    |

***

## JWT Authentication

Admin dashboard uses JWT tokens:

```bash theme={null}
# Login to get token
curl -X POST "https://demo.api.vultlocal.com/api/v1/admin/login" \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@olive.example.com", "password": "secret"}'

# Response
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_in": 86400
}

# Use token
curl -H "Authorization: Bearer eyJhbG..."
```

### JWT Configuration

```yaml theme={null}
# gateway/config.yaml
auth:
  jwt_secret: "${JWT_SECRET}"  # Minimum 32 characters
  jwt_expiry: 24h
  refresh_expiry: 168h
```

<Warning>
  JWT secrets must be at least 32 characters. Use a cryptographically secure random generator.
</Warning>

***

## HMAC Authentication

POS terminals use HMAC-SHA256 signatures:

```javascript theme={null}
const crypto = require('crypto');

function generateSignature(method, path, body, timestamp, secret) {
  const payload = `${method}\n${path}\n${timestamp}\n${body}`;
  
  return crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
}

// Usage
const signature = generateSignature(
  'POST',
  '/api/v1/pos/payment',
  JSON.stringify({ amount: '150.00' }),
  new Date().toISOString(),
  'your_hmac_secret'
);
```

### Required Headers

| Header         | Description               |
| -------------- | ------------------------- |
| `X-API-Key-ID` | Partner or POS API key ID |
| `X-Signature`  | HMAC-SHA256 signature     |
| `X-Timestamp`  | RFC3339 timestamp         |

<Info>
  Signatures are valid for 5 minutes. Ensure your server clock is synchronized with NTP.
</Info>

***

## TLS Configuration

### External Traffic (TLS 1.3)

All external traffic uses TLS 1.3:

```yaml theme={null}
# gateway/config.yaml
tls:
  enabled: true
  cert_file: /certs/gateway.crt
  key_file: /certs/gateway.key
  min_version: "1.3"
```

### Internal Traffic (mTLS)

gRPC between Gateway and Wallet-Core uses mutual TLS:

```yaml theme={null}
# wallet-core/config.yaml
tls:
  enabled: true
  cert_file: /certs/wallet-core.crt
  key_file: /certs/wallet-core.key
  ca_file: /certs/ca.crt
  require_client_cert: true
```

### Certificate Rotation

* Rotate certificates every 90 days
* Use automated renewal (cert-manager, Let's Encrypt)
* Monitor certificate expiry with alerts

***

## Secrets Management

<Tabs>
  <Tab title="Environment Variables">
    ```bash theme={null}
    export JWT_SECRET=$(openssl rand -base64 32)
    export DATABASE_URL="postgres://user:pass@host:5432/db"
    export OPENAI_API_KEY="sk-..."
    ```
  </Tab>

  <Tab title="Kubernetes Secrets">
    ```bash theme={null}
    kubectl create secret generic olive-secrets \
      --from-literal=jwt-secret=$(openssl rand -base64 32) \
      --from-literal=db-password=secret \
      -n olive
    ```
  </Tab>

  <Tab title="HashiCorp Vault">
    ```bash theme={null}
    vault kv put secret/olive \
      jwt_secret=$(openssl rand -base64 32) \
      db_password=secret
    ```
  </Tab>
</Tabs>

<Warning>
  Never commit secrets to version control. Use environment variables or a secrets manager.
</Warning>

***

## Rate Limiting

Configure per-client rate limits:

```yaml theme={null}
# gateway/config.yaml
rate_limit:
  enabled: true
  requests_per_second: 100
  burst: 200
  by_client: true
```

### Rate Limit Headers

| Header                  | Description                 |
| ----------------------- | --------------------------- |
| `X-RateLimit-Limit`     | Maximum requests per window |
| `X-RateLimit-Remaining` | Requests remaining          |
| `X-RateLimit-Reset`     | Window reset timestamp      |

***

## Security Layers

<AccordionGroup>
  <Accordion title="Network Layer" icon="network-wired">
    * VPC isolation for internal services
    * Firewall rules restricting access
    * Network policies in Kubernetes
    * Private subnets for databases
  </Accordion>

  <Accordion title="Transport Layer" icon="lock">
    * TLS 1.3 for all external traffic
    * mTLS for internal gRPC communication
    * Certificate pinning for critical services
    * Regular certificate rotation
  </Accordion>

  <Accordion title="Application Layer" icon="code">
    * JWT/OAuth2 authentication
    * API key management with scopes
    * Rate limiting per client
    * Input validation and sanitization
  </Accordion>

  <Accordion title="Data Layer" icon="database">
    * Encrypted database connections
    * Encryption at rest (optional)
    * Comprehensive audit logging
    * Idempotency keys for operations
  </Accordion>
</AccordionGroup>

***

## PII and Data Protection

### KYC Document Handling

* Documents stored in private S3 bucket
* Access via short-lived pre-signed URLs
* No PII in application logs
* Encryption at rest with KMS

### Data Retention

| Data Type        | Retention      |
| ---------------- | -------------- |
| Transaction logs | 7 years        |
| Audit logs       | 5 years        |
| KYC documents    | Per regulation |
| Session data     | 24 hours       |

***

## Compliance

Designed to support:

<CardGroup cols={2}>
  <Card title="PCI-DSS" icon="credit-card">
    Payment card industry standards
  </Card>

  <Card title="GDPR" icon="shield-check">
    European data protection
  </Card>

  <Card title="SOC 2 Type II" icon="certificate">
    Security and availability
  </Card>

  <Card title="ISO 27001" icon="file-certificate">
    Information security management
  </Card>
</CardGroup>

***

## Threat Mitigation

| Threat               | Mitigation                              |
| -------------------- | --------------------------------------- |
| DDoS attacks         | Rate limiting, load balancing, WAF      |
| SQL injection        | Parameterized queries, input validation |
| Man-in-the-middle    | TLS/mTLS encryption                     |
| Replay attacks       | Idempotency keys, timestamps            |
| Privilege escalation | Least privilege, RBAC                   |
| Credential stuffing  | Rate limiting, account lockout          |

***

## Security Checklist

<Warning>
  Complete before production deployment.
</Warning>

### Infrastructure

* [ ] TLS/mTLS enabled on all services
* [ ] Firewall rules configured
* [ ] Network policies in place
* [ ] VPC isolation for database

### Application

* [ ] Strong JWT secret (32+ chars)
* [ ] Rate limiting enabled
* [ ] Input validation active
* [ ] Audit logging enabled

### Operations

* [ ] Monitoring and alerting
* [ ] Regular backups
* [ ] Incident response plan
* [ ] Security training completed

***

## Incident Response

<Steps>
  <Step title="Detection">
    Monitor logs and alerts for suspicious activity
  </Step>

  <Step title="Containment">
    Isolate affected systems, revoke compromised credentials
  </Step>

  <Step title="Investigation">
    Analyze audit logs and transaction history
  </Step>

  <Step title="Remediation">
    Apply fixes, patches, and security updates
  </Step>

  <Step title="Recovery">
    Restore normal operations
  </Step>

  <Step title="Post-Mortem">
    Document findings and improve processes
  </Step>
</Steps>

***

## Related

<CardGroup cols={2}>
  <Card title="Gateway Authentication" icon="key" href="/gateway/authentication">
    Detailed auth configuration
  </Card>

  <Card title="Deployment Guide" icon="rocket" href="/reference/deployment">
    Production deployment
  </Card>
</CardGroup>