Security Model

Zester implements a zero-trust security architecture with multiple independent layers protecting transport, identity, authorization, and data. Every connection is authenticated, every message is encrypted in transit, and sensitive settings are encrypted end-to-end so only the target peel can read them.

Trust Hierarchy

The core trust model follows a three-tier JWT hierarchy rooted in a single operator identity. Each level delegates bounded authority to the level below.

Transport Security

All NATS connections between peels and the master are encrypted with TLS 1.3. The implementation in pkg/bus/tls.go enforces TLS 1.3 as the minimum version -- earlier protocol versions are rejected at connection time.

Server and Client TLS Configuration

ServerTLSConfig (master side):

tlsCfg := &tls.Config{
    Certificates: []tls.Certificate{cert},
    MinVersion:   tls.VersionTLS13,
    // ClientAuth is set conditionally:
    // only when cfg.VerifyClient is true
}
if cfg.VerifyClient {
    tlsCfg.ClientAuth = tls.RequireAndVerifyClientCert
}

ClientTLSConfig (peel side):

tlsCfg := &tls.Config{
    MinVersion:   tls.VersionTLS13,
    Certificates: []tls.Certificate{cert}, // client cert for mTLS
    RootCAs:      pool,
}

Both functions enforce MinVersion: tls.VersionTLS13. There is no configuration knob to weaken this.

Mutual TLS (mTLS)

When VerifyClient is enabled (the recommended production setting), both sides must present valid certificates signed by the same CA. This provides bidirectional authentication at the transport layer before any NATS-level authentication begins.

Certificate Generation

Zester includes built-in tooling for bootstrapping a self-signed CA and issuing certificates:

The CA uses ECDSA P-256 (also known as prime256v1), providing equivalent security to RSA 3072 at a fraction of the key size and computation cost.

Identity and Authentication

Ed25519 nkeys

Every entity in Zester has an Ed25519 nkey identity managed through the KeyBundle struct in pkg/auth/keys.go. A KeyBundle contains the key pair, public key, seed, and role metadata.

Challenge-Response Authentication

nkeys use challenge-response authentication. No passwords or private keys are ever transmitted over the wire.

1. The peel presents its public key during connection.
2. The NATS server sends a random nonce.
3. The peel signs the nonce with its Ed25519 private key (the seed never leaves the peel).
4. The server verifies the signature. If valid, the connection is authenticated.

Three-Tier JWT Hierarchy

Authorization is encoded in NATS JWTs following a three-tier chain: Operator -> Account -> User. The pkg/auth/jwt.go package provides functions for creating and validating each level.

• Operator JWT -- Root of trust. Signs account JWTs. Supports signing key delegation.
• Account JWT -- Environment boundary. Signs user JWTs. Enforces resource limits.
• User JWT -- Per-peel identity. Carries subject-level publish/subscribe permissions.

The ValidateJWTChain() function verifies the complete chain:

1. Decode and validate the operator JWT (self-signed).
2. Verify the account JWT was signed by the operator or one of its signing keys.
3. Verify the user JWT was signed by the account or one of its signing keys.

Credential Files

Credential files (.creds) bundle a peel's JWT and nkey seed into a single file, produced by pkg/auth/creds.go. The BootstrapPeelCreds() function generates everything a peel needs to connect:

1. Generate a new user nkey pair.
2. Create a user JWT signed by the account key, with peel-specific subject permissions.
3. Write the .creds file with 0600 permissions.

-----BEGIN NATS USER JWT-----
eyJ0eXAiOiJKV1QiLCJhbGciOiJlZDI1NTE5LW5rZXkifQ...
------END NATS USER JWT------

************************* IMPORTANT *************************
NKEY Seed printed below can be used to sign and prove identity.
NKEYs are sensitive and should be treated as secrets.

-----BEGIN USER NKEY SEED-----
SUAM...
------END USER NKEY SEED------

Key Acceptance

Before a peel can operate, its key must be accepted by the master. The key acceptance system in pkg/auth/accept.go provides thread-safe operations and supports three acceptance modes.

Acceptance Modes

Key Lifecycle

Each KeyRecord tracks the peel ID, Ed25519 public key, X25519 curve public key (for encryption), current state, timestamps, and the identity of who accepted, rejected, or revoked the key. All operations on the key store are thread-safe.

Settings Encryption

Sensitive settings values (passwords, API keys, tokens) are encrypted with NaCl box encryption so they are only readable by the target peel. The Encryptor in pkg/auth/encrypt.go handles all cryptographic operations.

How It Works

1. The master derives an X25519 curve key from its Ed25519 nkey seed.
2. Each peel's X25519 public key is used as the encryption recipient.
3. SealSettingsValue encrypts the plaintext and produces a tagged string: ENC[nkey,<base64>].
4. The peel decrypts using its own X25519 curve key pair derived from its nkey seed.

Key Derivation

CurvePublicKeyFromSeed derives an X25519 public key from an Ed25519 nkey seed through the following chain:

Ed25519 nkey seed
    |
    v  nkeys.DecodeSeed()
    |
    v  Raw 32-byte seed
    |
    v  nkeys.EncodeSeed(PrefixByteCurve, rawSeed)
    |
    v  Curve seed
    |
    v  nkeys.FromCurveSeed()
    |
    v  X25519 key pair (public + private)

This means every peel's signing identity (its nkey) also provides an encryption identity. No additional key management is required.

Multi-Master Key Compatibility

The account seed is the root of the encryption trust chain. The master derives its X25519 curve key from the account seed and publishes the curve public key to the secrets KV bucket so peels can decrypt settings. In multi-master deployments, all masters must share the same account.seed file — otherwise each master derives a different curve key, and peels cannot decrypt settings encrypted by a different master. The seed never leaves the master; only the derived curve public key is published to KV.

Per-Peel Encryption

Each peel has a unique X25519 key pair derived from its unique nkey seed. The master encrypts settings individually for each target peel. Even if the NATS KV store is compromised, encrypted values are unreadable without the specific peel's private key. A compromised peel can only decrypt its own settings -- not those of any other peel.

NATS Subject Isolation

JWT-based subject permissions enforce strict isolation between peels at the NATS server level.

Publish permissions (peel can send to):

Subscribe permissions (peel can listen to):

Zero-Trust Principles

Zester follows zero-trust principles throughout its design: