Security & Authentication

LoomCache takes security seriously. Rather than depending on a secure internal perimeter, the engine assumes a zero-trust environment with encrypted connections, robust mutual authentication, and granular, command-level Access Control Lists (ACLs).

Zero-Trust Internal Network

mTLS Handshake + RBAC + Audit Logging

API Gateway

Validates JWT

X-Auth-Roles: admin

TcpServer

TLS 1.3 Terminated

Execution

RBAC + AuditLog

[Gateway] Received external request, verified JWT

TLS & mTLS Configuration

By default, all network traffic in LoomCache should be encrypted using Transport Layer Security (TLS), with optional mutual authentication (mTLS).

• Node-to-Node (Raft Replication): This always enforces strict mTLS. To form a cluster, all peers must possess a valid certificate signed by the operator’s shared Certificate Authority (CA). Unauthenticated or rogue nodes cannot join the raft ring.
• Client-to-Node: You can toggle whether your client applications merely verify the server (requireClientAuth=false) or if the server also enforces that the client provides a signed cert (requireClientAuth=true).

Identity & API Gateway Trust

LoomCache does not validate JWT tokens or perform OIDC flows natively. Instead, it delegates identity verification to your API Gateway (e.g., Spring Cloud Gateway, Kong, Envoy).

The Trust Model:

1. The API Gateway receives the external request and validates the JWT against your Identity Provider.
2. The Gateway maps the user to backend roles and forwards trusted headers to LoomCache over an mTLS connection:
   • X-Auth-User: The authenticated username.
   • X-Auth-Roles: Comma-separated roles (e.g., ROLE_ADMIN,ROLE_GUEST).
3. LoomCache trusts these headers purely because the mTLS handshake proved the connection originated from the authorized Gateway.

Granular RBAC Permissions

Upon receiving the trusted roles, the AuthenticationHandler evaluates the command against the ACLs. LoomCache supports specific permissions for all 85 of its internal binary protocol message types.

For example, you can create a data-writer role that allows MAP_PUT, QUEUE_PUSH, and COUNTER_INCREMENT, while restricting LOCK_UNLOCK to an admin role. If a guest user attempts a write via the API, the DataOperationHandler will immediately reject the packet with an authorization error.

Async Audit Logging

To comply with enterprise requirements, LoomCache features a non-blocking AuditLogger. Every single data modification command includes an audit trail with: timestamp, nodeId, clientId, command, key, result, and durationMs. These logs are piped via virtual threads to a bounded asynchronous queue, guaranteeing that logging never negatively impacts latency or blocks the Raft replication path.