Overlay Security

Overlay security adds envelope signing on top of gated admission. When nodes attach, they exchange public keys and use them to cryptographically sign every message. This provides message integrity, tamper-evidence, and non-repudiation.

Overview

Overlay security establishes cryptographic trust between nodes themselves, not just through bearer tokens. When a node attaches to the fabric:

1. Public keys are exchanged during the handshake
2. Every envelope is signed by the sender (EdDSA)
3. Every envelope is verified by the receiver
4. SIDs (source fingerprints) track message origin

What overlay security provides:

How It Works

Key Exchange During Attach

When a node attaches to its parent, they exchange raw public keys:

┌──────────────┐                    ┌──────────────┐
│    Node      │ ──── Attach ─────▶ │   Sentinel   │
│              │ ◀─── Keys ──────── │              │
│   (generates │                    │   (generates │
│    keypair)  │                    │    keypair)  │
└──────────────┘                    └──────────────┘

After key exchange:

• Each node knows the other’s public key
• All messages between them are signed
• Signatures are verified before processing

Envelope Signing

Every message in the fabric includes a cryptographic signature:

{
  "version": "1.0",
  "id": "abc123",
  "to": "math@fame.fabric",
  "frame": { "type": "Data", "payload": "..." },
  "sec": {
    "sig": {
      "kid": "xAhddeRwu2UvuJr",
      "val": "IyaOG4hMLu...LDA"
    }
  }
}

The sec.sig field contains:

• kid: Key ID of the signing key
• val: Base64-encoded EdDSA signature

Gated vs Overlay

Why Overlay Matters

TLS protects the transport, but overlay signing protects the message:

• TLS compromise: If TLS is broken, gated messages can be modified
• Overlay resilience: Even with broken TLS, signed messages remain verifiable
• Audit trails: Signatures provide cryptographic proof of message origin
• Multi-hop routing: Signatures survive routing through multiple sentinels

Configuration

Enable overlay security by setting these environment variables:

Sentinel Configuration

# Security profile
FAME_SECURITY_PROFILE=overlay
 
# JWT validation (same as gated)
FAME_JWT_TRUSTED_ISSUER=https://your-oauth2-server.com
FAME_JWT_AUDIENCE=fame.fabric

Agent/Client Configuration

# Security profile (must match sentinel)
FAME_SECURITY_PROFILE=overlay
 
# Admission profile
FAME_ADMISSION_PROFILE=direct
 
# OAuth2 credentials (same as gated)
FAME_ADMISSION_TOKEN_URL=https://your-oauth2-server.com/oauth/token
FAME_ADMISSION_CLIENT_ID=your-client-id
FAME_ADMISSION_CLIENT_SECRET=your-client-secret

What Overlay Security Does NOT Provide

Overlay security adds message integrity but not confidentiality:

Security Properties

What You Get

1. Message integrity: Any modification to an envelope invalidates the signature
2. Authenticity: Only the holder of the private key can sign messages
3. Non-repudiation: Signed messages provide proof of origin
4. Provenance: SIDs (source fingerprints) track message lineage

What the SID Provides

The SID (Source ID) is a fingerprint derived from the node’s public key:

{
  "sid": "6KbaPqxYq8p3hjDaUw3YBH",
  ...
}

This provides:

• Consistent node identity across sessions
• Message origin tracking through the fabric
• Correlation for audit and debugging

When to Use Overlay Security

Good fit:

• You need to verify message origin
• You need tamper-evident messaging
• You need audit trails with cryptographic proof
• You’re building multi-hop topologies
• TLS alone isn’t sufficient for your threat model

Consider Advanced when:

• You need cryptographic workload identity (X.509/SPIFFE)
• You need end-to-end encryption
• You need federated admission with a Welcome service
• You have zero-trust or regulatory requirements

Running the Example

Complete runnable examples are available in both repositories:

# TypeScript
cd naylence-examples-ts/examples/security/overlay
make start    # Start all services
make run      # Run the client
 
# Python
cd naylence-examples-python/examples/security/overlay
make start    # Start all services
make run      # Run the client

What the Example Includes

• Caddy: TLS reverse proxy
• OAuth2 Server: Development token issuer
• Sentinel: Configured with FAME_SECURITY_PROFILE=overlay
• Math Agent: Connects with overlay signing enabled
• Client: Fetches token, exchanges keys, signs all messages

Seeing Signatures in Action

Run with verbose output to inspect signed envelopes:

make run-verbose

You’ll see the sec.sig field in every envelope, confirming that overlay signing is active.

Example Envelope

Here’s what a signed envelope looks like in overlay mode:

{
  "version": "1.0",
  "id": "mu2l8LmB6bvJAiL",
  "sid": "6KbaPqxYq8p3hjDaUw3YBH",
  "traceId": "Or9bha2d6tDb2yC",
  "to": "math@fame.fabric",
  "replyTo": "rpc-abc@/client/node",
  "frame": {
    "type": "Data",
    "payload": { "method": "add", "params": [3, 4] }
  },
  "ts": "2025-12-15T10:00:00.000Z",
  "sec": {
    "sig": {
      "kid": "xAhddeRwu2UvuJr",
      "val": "IyaOG4hMLuafFAv8Sd77HUb1PhKobN0lCOOu7Qpa-y59QFH_3BMO98OPbKalzoKoJEsH9tkJimA9P7c4YQ2LDA"
    }
  }
}

Notice:

• sec.sig.kid: Identifies the signing key
• sec.sig.val: The EdDSA signature over the envelope

Next Steps

• Need cryptographic identity? → Advanced Security
• Need end-to-end encryption? → Advanced Security
• Back to overview → Security