Security

Naylence provides a progressive security model that lets you start simple and add layers as your requirements grow. You can move from no security to enterprise-grade zero-trust by changing security profiles and setting the appropriate environment variables.

The Security Model, in Order

1. Gated (gated): OAuth2/OIDC admission + basic identity via token claims.
2. Overlay (overlay): adds cryptographic envelope signing (tamper-evidence) using public keys.
3. Advanced (strict-overlay / advanced): upgrades identity to X.509/SPIFFE and enables end-to-end confidentiality.

Security Philosophy

Security in Naylence is built around three core principles:

1. Progressive enhancement: Start with the simplest model that meets your needs, add more when required
2. Configuration over code: Security profiles are configured via environment variables, not code changes
3. Defense in depth: Multiple layers work together (admission, identity, encryption)

TLS and Transport Security

Naylence expects TLS to be established using well-known deployment patterns—typically by running fabric nodes behind reverse proxies that handle TLS termination. In our security examples, we use Caddy  as the reverse proxy, but you’re free to choose whatever fits your infrastructure (nginx, Traefik, cloud load balancers, etc.).

TLS vs End-to-End Encryption

TLS protects data in transit between two endpoints, but in a distributed fabric messages may traverse multiple nodes (sentinels, intermediaries). The end-to-end encryption provided by the Advanced Security layer is complementary to TLS:

• TLS: Encrypts each individual connection (hop-by-hop)
• Sealed/Channel encryption: Encrypts the message payload so only the intended recipient can decrypt it, regardless of how many nodes it passes through

This means even if an intermediate node is compromised, or if TLS terminates at a proxy, the message content remains confidential.

Recommended Setup

┌─────────────────┐      TLS       ┌──────────────────┐
│  Browser/Agent  │ ◀────────────▶ │  Reverse Proxy   │
└─────────────────┘                │  (Caddy/nginx)   │
                                   └────────┬─────────┘
                                            │ internal
                                            ▼
                                   ┌──────────────────┐
                                   │  Sentinel/Node   │
                                   └──────────────────┘

For production deployments:

1. Always use TLS for external connections (handled by your proxy)
2. Add E2E encryption (sealed or channel) when you need message confidentiality across the fabric
3. Use internal networks or mTLS between proxies and nodes for additional defense in depth

Security Profiles at a Glance

What Each Layer Provides

Admission Control

How a node is authorized to join the fabric:

Identity

How nodes prove who they are:

Encryption

How messages are protected:

Choosing the Right Profile

Start Here: Do You Need Admission Control?

Do you need to control who can connect?
│
├─ No  → Use `open` profile (dev/testing only)
│
└─ Yes → Do you need message integrity beyond TLS?
         │
         ├─ No  → Use `gated` profile (OAuth2 admission)
         │
         └─ Yes → Do you need cryptographic node identity?
                  │
                  ├─ No  → Use `overlay` profile (public key signing)
                  │
                  └─ Yes → Use `strict-overlay` profile (X.509/SPIFFE)

Quick Decision Matrix

Configuration

All security behavior is controlled via environment variables:

# Security profile (how nodes communicate)
FAME_SECURITY_PROFILE=overlay
 
# Admission profile (how nodes join)
FAME_ADMISSION_PROFILE=direct
 
# Encryption level (for strict-overlay)
FAME_DEFAULT_ENCRYPTION_LEVEL=channel  # or: sealed, plaintext

Common Environment Variables

Next Steps

Explore each security section in detail:

• Gated Security — OAuth2/OIDC admission control
• Overlay Security — Envelope signing with public keys
• Advanced Security — X.509/SPIFFE with end-to-end encryption
• Secure Load Balancing — Channel encryption with sticky routing