JWT Hierarchy

Zester uses NATS JWTs to encode authorization claims in a three-level trust chain: operator signs account, account signs user. Each level delegates a bounded set of permissions to the level below.

Trust Chain

The chain is validated bottom-up: a user JWT is only valid if its issuer is the account (or one of the account's signing keys), and the account JWT is only valid if its issuer is the operator (or one of the operator's signing keys).

Operator JWT

The operator is the root of trust. There is typically one operator per Zester deployment.

OperatorJWTOptions

Creating an Operator JWT

operatorKP, _ := auth.GenerateKeyBundle(auth.RoleOperator)

operatorJWT, err := auth.CreateOperatorJWT(operatorKP, auth.OperatorJWTOptions{
    Name:           "prod-operator",
    StrictSignKeys: true,
    SigningKeys:    []string{signingKeyPub},
})

Account JWT

An account defines a namespace boundary and resource limits. Zester typically uses one account for all peels in an environment.

AccountJWTOptions

Creating an Account JWT

accountKP, _ := auth.GenerateKeyBundle(auth.RoleAccount)

accountJWT, err := auth.CreateAccountJWT(accountKP, operatorKP, auth.AccountJWTOptions{
    Name:       "production",
    MaxConns:   1000,
    MaxPayload: 1024 * 1024, // 1MB
    AllowPub:   []string{"zester.>"},
    AllowSub:   []string{"zester.>"},
})

The second argument (operatorKP) is the signing key -- either the operator's own key bundle or a designated signing key.

User JWT

A user JWT represents a single authenticated identity. In Zester, each peel gets its own user JWT with permissions scoped to that peel's ID.

UserJWTOptions

Creating a User JWT

userKP, _ := auth.GenerateKeyBundle(auth.RoleUser)

userJWT, err := auth.CreateUserJWT(userKP, accountKP, auth.UserJWTOptions{
    Name:          "web-server-01",
    IssuerAccount: accountKP.PublicKey,
    AllowPub:      []string{"zester.event.web-server-01.>"},
    AllowSub:      []string{"zester.cmd.web-server-01.>"},
    Expiry:        24 * time.Hour,
})

Peel User JWT Defaults

The PeelUserJWTOptions helper generates a UserJWTOptions pre-configured with the exact subjects a peel needs:

opts := auth.PeelUserJWTOptions("web-server-01", accountKP.PublicKey)

This sets the following permissions:

Publish (peel sends to):

Subscribe (peel listens to):

Full Hierarchy Generation

For bootstrapping or testing, generate a complete operator-account-user chain in one call:

operatorKP, accountKP, userKP,
operatorJWT, accountJWT, userJWT,
err := auth.GenerateFullHierarchy("prod-ops", "production", "master-user")

This creates three key bundles and three signed JWTs with default options.

Chain Validation

Validate that a set of JWTs form a valid trust chain:

err := auth.ValidateJWTChain(operatorJWT, accountJWT, userJWT)

This checks:

1. The operator JWT is well-formed and self-signed.
2. The account JWT's issuer matches the operator's public key or one of its signing keys.
3. The user JWT's issuer matches the account's public key or one of its signing keys.

Verifying a Single User JWT

For a single token, decode it and then validate issuer/expiry in your caller:

claims, err := auth.DecodeUserJWT(userJWT)
if err != nil {
    return err
}
if claims.Issuer != accountKP.PublicKey && claims.IssuerAccount != accountKP.PublicKey {
    return fmt.Errorf("user JWT not issued by expected account")
}
if claims.Expires > 0 && time.Now().Unix() > claims.Expires {
    return fmt.Errorf("user JWT expired")
}

For full trust validation, prefer ValidateJWTChain(operatorJWT, accountJWT, userJWT).

Decoding JWTs

Decode individual JWTs to inspect their claims:

operatorClaims, err := auth.DecodeOperatorJWT(operatorJWT)
accountClaims, err := auth.DecodeAccountJWT(accountJWT)
userClaims, err := auth.DecodeUserJWT(userJWT)

Signing Keys

Signing keys provide operational flexibility. Instead of using the root operator or account key for every signing operation, generate dedicated signing keys and reference them:

// Generate a signing key (same type as the parent)
signingKP, _ := auth.GenerateKeyBundle(auth.RoleOperator)

// Include it in the operator JWT
operatorJWT, _ := auth.CreateOperatorJWT(operatorKP, auth.OperatorJWTOptions{
    Name:       "prod-ops",
    SigningKeys: []string{signingKP.PublicKey},
})

// Now sign accounts with the signing key instead of the root key
accountJWT, _ := auth.CreateAccountJWT(accountKP, signingKP, auth.AccountJWTOptions{
    Name: "production",
})

Benefits of signing keys:

• The root key can stay offline (cold storage, HSM).
• Signing keys can be rotated without re-issuing the operator JWT (just add the new key and remove the old one).
• If a signing key is compromised, only JWTs signed by that key need re-issuing.