Advanced Security

Advanced security is the enterprise zero-trust profile of Naylence. It provides SPIFFE/X.509 workload certificates, federated admission, and end-to-end encryption (E2E) using either sealed or channel encryption modes.

Advanced security requires the BSL-licensed naylence-advanced-security package for TypeScript or Python. Contact us for licensing details.

Overview

Advanced security (strict-overlay) is the most comprehensive security model:

Federated admission: Welcome service issues placement + attach tickets + CA grants
Cryptographic identity: SPIFFE/X.509 certificates bound to fabric placement
Dual validation: Parent sentinels validate both attach ticket AND certificate
End-to-end encryption: Sealed or channel encryption with ChaCha20-Poly1305

What advanced security provides:

Feature	Status
OAuth2/OIDC authentication	✓
Federated admission (Welcome service)	✓
X.509/SPIFFE certificates	✓
Envelope signing (EdDSA)	✓
End-to-end encryption	✓
Path-bound identity	✓
Short-lived certificates	✓

Architecture

Flow:

OAuth2 token: Node obtains a bearer token from the OAuth2 server
Welcome service: Validates token and issues:
- Placement: Which parent sentinel to attach to
- Attach ticket: Short-lived capability JWT
- CA grant: Authorization to request a certificate
CA service: Issues a SPIFFE/X.509 certificate bound to the placement
Attachment: Node presents both attach ticket AND certificate to parent
Validation: Parent validates ticket, then certificate (including path binding)
Encryption: Sealed or channel encryption is enabled for all messages

End-to-End Encryption Modes

Advanced security supports two E2E encryption modes:

Sealed Encryption

Each message is individually encrypted for its final recipient:


{
  "frame": {
    "type": "Data",
    "codec": "b64",
    "payload": "wOigrL848iSgv8qf..."
  },
  "sec": {
    "sig": { "kid": "...", "val": "..." },
    "enc": {
      "alg": "ECDH-ES+A256GCM",
      "kid": "recipient-key-id",
      "val": "..."
    }
  }
}

Properties:

Per-message encryption using ECDH-ES+A256GCM
Only the final recipient can decrypt
Works across multi-hop routing
Higher overhead per message

Channel Encryption

A persistent encrypted channel is established between nodes:


{
  "sec": {
    "enc": {
      "alg": "chacha20-poly1305-channel",
      "kid": "auto-math@fame.fabric-7snnHCFG1FA5UGV",
      "val": "07d951bb68c86085f50e57b9"
    }
  }
}

Properties:

Session-based encryption
Key setup happens once, then reused
Lower per-message overhead
Requires stickiness for load balancing (see Secure Load Balancing)

Choosing an Encryption Mode

Mode	Best For	Trade-offs
`sealed`	Multi-hop routing, stateless agents	Higher per-message overhead
`channel`	High-throughput, persistent connections	Requires stickiness for load balancing
`plaintext`	Debugging, development	No E2E encryption (signing only)

Configuration

Enable advanced security with these environment variables:

Sentinel Configuration


# Security profile
FAME_SECURITY_PROFILE=strict-overlay
 
# Admission profile
FAME_ADMISSION_PROFILE=welcome
 
# Welcome service URL
FAME_WELCOME_SERVICE_URL=https://welcome-service/v1/welcome
 
# CA configuration
FAME_CA_SERVICE_URL=https://ca-service/v1/sign
FAME_CA_CERTS=/path/to/root-ca.crt

Agent/Client Configuration


# Security profile
FAME_SECURITY_PROFILE=strict-overlay
 
# Admission profile
FAME_ADMISSION_PROFILE=welcome
 
# Encryption level
FAME_DEFAULT_ENCRYPTION_LEVEL=sealed  # or: channel, plaintext
 
# Welcome service
FAME_WELCOME_SERVICE_URL=https://welcome-service/v1/welcome
 
# CA service
FAME_CA_SERVICE_URL=https://ca-service/v1/sign
FAME_CA_CERTS=/path/to/root-ca.crt
 
# OAuth2 credentials
FAME_ADMISSION_TOKEN_URL=https://oauth2-server/oauth/token
FAME_ADMISSION_CLIENT_ID=your-client-id
FAME_ADMISSION_CLIENT_SECRET=your-client-secret

SPIFFE/X.509 Certificates

Certificates in advanced security follow the SPIFFE (Secure Production Identity Framework for Everyone) model:

What SPIFFE Provides

Workload identity: Cryptographic proof of “who” a node is
SID-based identity: Node SID is derived from its physical path in the fabric
Short-lived: Certificates expire quickly (default: 1 day)
Automatic renewal: Nodes re-request certificates as needed

Certificate Structure

Naylence issues X.509 certificates with SPIFFE-compliant identity in the Subject Alternative Name (SAN):


Subject: (empty - per SPIFFE X.509-SVID spec)
Issuer: FAME Issuing CA
Valid: 2025-12-15 to 2025-12-16 (1 day default)

Subject Alternative Name (SAN):
  URI: spiffe://naylence.fame/nodes/<node-sid>

Key Usage: digitalSignature (critical)
Extended Key Usage: clientAuth, serverAuth

Custom Extensions:
  - SID: <node-sid>
  - Node ID: <node-id>
  - Logicals: ["math@fame.fabric", ...]

The SPIFFE ID encodes:

Trust domain: naylence.fame (configurable)
Path: /nodes/<node-sid> (derived from physical path)

SID-Based Identity

The node’s SID (Source ID) is computed as a secure digest of its physical path in the fabric:


Physical path: /sentinel/math-agent
SID: sha256(physical_path) → base62 encoded → "6KbaPqxYq8p3hjDaUw3YBH"
SPIFFE ID: spiffe://naylence.fame/nodes/6KbaPqxYq8p3hjDaUw3YBH

This ensures:

Deterministic identity from fabric position
Cryptographic binding between certificate and physical topology
No manual identity assignment required

Certificate Validation

When a node attaches, the parent sentinel validates:

Certificate chain: Signed by trusted CA
SID match: Certificate SID matches computed SID for the physical path
Logical hosts: Requested logicals are permitted for this node
Expiration: Certificate is within validity period

Welcome and CA Services

Advanced security requires two additional services:

Welcome Service

The Welcome service handles federated admission:

Validates the OAuth2 token
Determines where the node should attach (placement)
Issues a short-lived attach ticket
Issues a CA grant (authorization to request a certificate)

CA Service

The CA service issues SPIFFE/X.509 certificates:

Validates the CA grant
Issues a certificate bound to the placement
Certificates are short-lived (automatic expiry)

The examples include development-only Welcome and CA services. In production, integrate with your own identity provider and certificate authority.

Example Envelope

Here’s what an encrypted envelope looks like:


{
  "version": "1.0",
  "id": "mu2l8LmB6bvJAiL",
  "sid": "6KbaPqxYq8p3hjDaUw3YBH",
  "to": "math@fame.fabric",
  "frame": {
    "type": "Data",
    "codec": "b64",
    "payload": "wOigrL848iSgv8qfUdntQTwMzEVRYBSTQLqY7Vwui7lJMHm2Akuze3gL5jBH0GKqw99canUn1EsrA6vss51OGgFyDTLbwz5rljcATB9TA8X7wERTvtUa8QWsaMfC5LFYJuc/nZsRqX7pZAXC3FWFvgwAUw==",
    "pd": "4Fg9MfgDCY09YqN0ep7Ntx"
  },
  "sec": {
    "sig": {
      "kid": "xAhddeRwu2UvuJr",
      "val": "IyaOG4hMLuafFAv8Sd77HUb1PhKobN0lCOOu7Qpa-y59QFH_3BMO98OPbKalzoKoJEsH9tkJimA9P7c4YQ2LDA"
    },
    "enc": {
      "alg": "chacha20-poly1305-channel",
      "kid": "auto-math@fame.fabric-7snnHCFG1FA5UGV",
      "val": "07d951bb68c86085f50e57b9"
    }
  }
}

Notice:

frame.payload: Encrypted data (base64)
sec.sig: Envelope signature (integrity)
sec.enc: Encryption metadata (confidentiality)

When to Use Advanced Security

Good fit:

Enterprise zero-trust deployments
Regulated industries (finance, healthcare)
Multi-tenant fabrics
Cross-organization federations
When you need cryptographic workload identity
When you need end-to-end encryption

May be overkill for:

Single-tenant internal deployments
Development environments
Simple authentication requirements

Running the Example

Complete runnable examples are available in both repositories:


# TypeScript
cd naylence-examples-ts/examples/security/advanced
make start    # Start all services (including Welcome and CA)
make run      # Run the client
 
# Python
cd naylence-examples-python/examples/security/advanced
make start    # Start all services
make run      # Run the client

What the Example Includes

Caddy: TLS reverse proxy
OAuth2 Server: Development token issuer
Welcome Service: Admission with placement + tickets
CA Service: SPIFFE/X.509 certificate authority
Sentinel: Configured with FAME_SECURITY_PROFILE=strict-overlay
Math Agent: Full admission + identity flow
Client: Complete flow with encrypted RPC calls

Seeing Encryption in Action

Run with verbose output to see encrypted envelopes:


make run-verbose

You’ll see both sec.sig (signing) and sec.enc (encryption) in every envelope.

Federated Fabric

Advanced security enables secure federated fabric — multiple organizations can interconnect their fabrics with cryptographic trust:

Each organization runs its own Welcome/CA services
Cross-organization trust via certificate chain
End-to-end encryption across organization boundaries
No single point of trust compromise

Next Steps

Need load balancing with encryption? → Secure Load Balancing
Back to overview → Security