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

# Security architecture

> Layered security controls protecting every stage of Lola Send's message lifecycle, from ingestion to response delivery.

Lola Send implements defense-in-depth across the entire message lifecycle. Security controls span message authentication, callback encryption, secret management, container hardening, and channel access control. Each layer operates independently — a failure in one does not compromise others.

## Security layers

| Layer                    | Mechanism                     | Purpose                                                                           |
| ------------------------ | ----------------------------- | --------------------------------------------------------------------------------- |
| Message authentication   | PayhubAuthMiddleware          | Every inbound message authenticated against identity service before agent routing |
| Encrypted callbacks      | AES encryption + HMAC signing | Payloads between Lola Send and web widgets are encrypted and integrity-verified   |
| Session tokens           | JWT with EC key pairs         | Short-lived, scoped tokens for frontend widget sessions                           |
| Phone normalization      | Standardized phone handling   | Prevents identity spoofing through format variations                              |
| Sensitive data isolation | Sealed form only              | Card data and PII never persisted in conversation state or Redis                  |
| Secret management        | Doppler                       | Production secrets injected at runtime; zero hardcoded credentials                |
| Container hardening      | Non-root `appuser`            | Docker images run as unprivileged user, reducing container escape risk            |
| Channel access control   | Allowlisting                  | WhatsApp number allowlists for controlled rollouts and phased deployments         |

## Encrypted callbacks

Lola Send uses `HttpCallbackProvider` to create secure callback URLs for communication between the chat layer and frontend web widgets. Every callback URL is constructed with two independent cryptographic protections:

* **AES encryption** — the callback payload is encrypted, ensuring confidentiality during transport between the widget and Lola Send's backend
* **HMAC signing** — the payload is signed with a secret key, ensuring integrity and preventing tampering

Callbacks enforce additional operational constraints:

* **Single-use** — each callback URL can only be invoked once. Replay attacks are structurally prevented.
* **Time-limited** — callbacks expire after a 2-hour TTL. Abandoned or stale widget sessions cannot be resumed.
* **Scoped** — each callback is bound to a specific ticket ID and operation context. A callback generated for one transaction cannot be used for another.

<Note>
  The widget cannot replay, forge, or reuse callbacks. The combination of encryption, signing, single-use enforcement, and TTL expiration ensures that callback-gated operations are tamper-resistant.
</Note>

## Secret management

All production secrets are managed through Doppler and injected at container runtime:

* No secrets are stored in source code, container images, or checked-in environment files
* GitHub Actions uses Doppler tokens to sync secrets to the deployment platform — secrets never appear in CI/CD logs
* Environment variables are the sole delivery mechanism for credentials, API keys, and encryption keys
* Doppler provides audit trails for secret access and rotation

## Container security

Lola Send's Docker images are built with a hardened, minimal configuration:

<Steps>
  <Step title="Multi-stage build">
    Multi-stage builds with `python:3.12-slim` minimize the final image surface area. Build tools and development dependencies are discarded before the production image is assembled.
  </Step>

  <Step title="Non-root execution">
    A dedicated `appuser` group and user are created at build time. The `USER appuser` directive ensures the application runs as an unprivileged user — reducing the impact of container escape vulnerabilities.
  </Step>

  <Step title="Single ingress point">
    Port 5005 is the only exposed port. All inbound traffic enters through the MessageGateway's HTTP server, which runs the full middleware pipeline before any message reaches an agent.
  </Step>
</Steps>

## Channel access control

WhatsApp deployments support number allowlisting for controlled rollouts:

* The bank defines which phone numbers can interact with Lola Send during phased deployments
* Allowlists are configured per deployment, not per agent — all agents respect the same boundary
* This enables the bank to run pilot programs with a restricted sender population before general availability

<Info>
  Every security layer described here operates at the infrastructure level, before any AI agent processes a message. The agent sees only authenticated, integrity-verified, enriched message data.
</Info>