Crate basil_nats 

basil-nats: build NATS JWTs (the ed25519-nkey JWS profile) without holding the signing key.

NATS credentials (nsc-style) are JWTs signed by an Ed25519 NKey. This crate produces the exact wire bytes a NATS server expects, but splits signing out: you build the signing input, hand it to whatever holds the key (an HSM, a nkeys::KeyPair, or a Vault transit engine) to produce a raw 64-byte Ed25519 signature, then assemble the final token. The key never has to enter this process, which is the whole point of using it from a broker.

Wire format (matches nats-io/jwt v2 / nsc):

• header: {"typ":"JWT","alg":"ed25519-nkey"}
• jti: base32 (no pad) of SHA-512/256 over the standard claims only (aud,exp,jti="",iat,iss,name,nbf,sub). The nats object is excluded.
• header & claims: base64url no-pad; signing input is header.claims.
• signature: raw 64-byte Ed25519, base64url no-pad, appended as the 3rd part.

Claim field order does not affect validity (servers parse JSON), but the jti hash is order-sensitive, so the hash struct mirrors nats-io/jwt.

Structs

AccountClaims

Account-specific fields inside a NATS account JWT (the nats claim block for type=account). All fields are optional; empty ones are omitted from the serialized claims.

AccountExport

An account-level export of a stream or service that other accounts may import.

AccountImport

An account-level import of another account’s stream or service.

AccountJwt

A NATS account JWT to be signed by its issuing operator key.

AccountLimits

Account-wide limits (a -1 value means unlimited).

DecodedNatsJwt

A decoded compact NATS JWT.

ExternalAuthorization

External (delegated) authorization config for an account: auth is performed by an external service rather than by per-user NKeys.

JetStreamLimits

JetStream resource limits for an account or a named tier (a -1 value means unlimited).

MatchedNatsSigner

The signer that matched a token’s embedded iss.

MsgTrace

Message-trace configuration: where traced messages are reported and how often they are sampled.

NatsJwtClaims

Standard claims extracted from a decoded NATS JWT.

NatsJwtValidation

Result of validating a NATS JWT against a candidate signer set.

NatsLimits

Per-connection NATS limits (a -1 value means unlimited).

OperatorClaims

Operator-specific fields inside a NATS operator JWT (the nats claim block for type=operator). All fields are optional; empty ones are omitted.

OperatorJwt

A NATS operator JWT to be signed by its operator key (usually self-signed: iss == sub). Same signing_input/assemble split as the others.

OperatorLimits

The full operator-limits block on an account JWT: the nats, account, and jetstream limit groups (flattened into one JSON object) plus per-tier JetStream limits.

Permission

A subject allow/deny list for one direction (publish or subscribe). An empty allow means “no allow restriction”; deny always subtracts.

Permissions

A pub/sub permission pair as the account default_permissions block carries it ({"pub":{…},"sub":{…}}).

ResponsePermission

Bounds on the implicit reply-subject permissions a request grants its responder.

RoleJwt

A minimal NATS JWT for a role whose current broker RPC carries only issuer, subject, name, and expiry (server, curve, account-signer). The nats claim block is just {type, version}.

ServiceLatency

Latency-sampling configuration for an exported service.

UserJwt

A NATS user JWT to be signed by its issuing account key.

UserPermissions

Publish / subscribe permission lists for a user (empty = unrestricted within the account).

WeightedMapping

One weighted target in a subject mapping (for traffic splitting / canaries).

Enums

CandidateSigner

A caller-supplied signer candidate for NATS JWT validation.

ClusterTraffic

Which account a cluster’s system traffic is attributed to.

Error

ExportType

Whether an import/export is a one-way stream or a request/reply service.

NatsJwtValidationReason

Authoritative validation result for a decoded NATS JWT.

NkeyType

The role of a public NATS NKey, identified by its single base32 prefix letter (the first character of an encoded key string).

ResponseType

Reply cardinality of a service export.

RoleKind

The nats.type claim of a minimal role JWT minted via RoleJwt. These are the roles the broker mints through the generic role path; account, user, and operator have their own dedicated builders.

SamplingRate

How often an exported service samples latency.

Functions

assemble

Append a raw 64-byte Ed25519 signature to a signing_input, producing the final compact JWT.

decode_nats_jwt

Decode a compact NATS JWT and expose its claims plus literal signing input.

decode_public

Decode any public NKey string back to its NkeyType role and raw 32-byte Ed25519 key, verifying the CRC.

encode_public

Encode a raw 32-byte public key as the public NKey for role.

format_user_creds

Render a nsc-style NATS user .creds document from a compact user JWT and user NKey seed.

jti_for_standard_claims

Compute the NATS JWT jti: base32-nopad SHA-512/256 over the standard claims with jti itself omitted.

open_nats_curve

Decrypt a NATS xkey authenticated box.

require_public_prefix

Decode a public NKey and require a specific NkeyType role.

seal_nats_curve

Encrypt a small payload using the NATS xkey authenticated box format.

signing_input_from_claims

Build the NATS JWS signing input from a fully validated claim document.

verify_public_signature

Verify a raw Ed25519 signature against a public NKey.

xkey_public_from_private

Derive a public xkey from raw 32-byte X25519 private material.