JWKS HTTP surface 

Basil's primary protocol is gRPC over a peer-credential-attested Unix socket. The HTTP server is an opt-in build feature, and the listener is disabled by default even when it is compiled in. The one reason to enable it today is the read-only JWKS endpoint that publishes the public halves of JWT-SVID issuer keys, so ordinary verifiers (gateways, app frameworks, the standard jsonwebtoken stacks) can validate a Basil-minted JWT-SVID signature without gRPC/SPIFFE.

[jwks]
enable = true # requires --features http. No HTTP port is opened unless enable is true.
listen = "127.0.0.1:8201" # only bound when enable = true
issuer = "https://basil.example.com" # optional; enables the OIDC discovery document

[jwks.tls]
enable = true # requires a binary built with --features http-tls
cert-file = "/etc/basil/jwks-cert.pem"
key-file = "/etc/basil/jwks-key.pem"

Endpoints & behavior 

JWKS body 

The JWKS endpoints return an RFC 7517 JWK set: one JWK per issuer key version still inside the rotation grace window. Each key carries:

• RSA issuers: kty=RSA, n/e, alg=RS256.
• ECDSA P-256/P-384 issuers: kty=EC, crv=P-256/P-384, x/y, alg=ES256/ES384. (ECDSA P-521 is generic-signing only, never a JWT-SVID issuer.)
• Every key: kid (the same id Basil stamps in each token's JWS header) and use=sig.

The set is byte-identical to what the SPIFFE Workload API JWT bundle publishes for the same issuer.

Rotation & the grace window 

A JWT-SVID is stamped with a kid derived from the exact issuer key version that signed it. When you rotate an issuer (rotating keys), new tokens are signed by the new version and carry the new kid; tokens minted just before the rotation still carry the old one and remain valid until they expire on their short TTL. So the JWKS publishes every version still inside the grace window, the range [latest − grace-versions … latest] (clamped to ≥ 1). Once a version falls below the grace floor, its JWK is dropped from the set and a token still keyed to that version no longer resolves. grace-versions (default 1) controls the window width; grace-versions = 0 publishes the newest version only. The gRPC SPIFFE Workload-API JWT bundle reflects the same window from the same source, so the two surfaces never disagree.

OIDC discovery document 

With jwks.issuer set, GET /.well-known/openid-configuration returns a minimal, spec-valid document:

{
	"issuer": "https://basil.example.com",
	"jwks_uri": "https://basil.example.com/jwks.json",
	"id_token_signing_alg_values_supported": ["RS256", "ES256", "ES384"],
	"response_types_supported": ["id_token"],
	"subject_types_supported": ["public"]
}

issuer and jwks_uri are consistent by construction (same scheme/host/base; jwks_uri is issuer + the real JWKS path) so a verifier that discovers the issuer fetches the JWKS this same surface serves.

Worked example: verify a Basil JWT across a rotation 

A standard OIDC/JWKS verifier needs only the published documents. Discover the issuer, fetch the JWKS, select the key by the token's kid, and validate the RS256, ES256, or ES384 signature and aud:

# 1. Discover the issuer (only if jwks.issuer is configured).
curl -s https://basil.example.com/.well-known/openid-configuration
#   -> { "issuer": "...", "jwks_uri": "https://basil.example.com/jwks.json", ... }

# 2. Fetch the JWKS named by jwks_uri.
curl -s https://basil.example.com/jwks.json
#   -> { "keys": [ {kid:"...v2..."}, {kid:"...v1..."} ] }   # both in grace

// Pseudocode for a jsonwebtoken-style verifier (any language):
let header = decode_jws_header(token);          // -> { alg: "RS256"|"ES256"|"ES384", kid: "..." }
let jwk    = jwks.keys.find(|k| k.kid == header.kid);  // pick by kid
if jwk.is_none() { reject("kid not published - outside grace, or unknown issuer"); }
let key = rsa_public_key_from(jwk.n, jwk.e);
verify_rs256(token, key);                        // signature
require(token.aud == "my-audience");             // audience you minted for
// Do NOT assert iss == discovery issuer: Basil's iss is the SPIFFE id (see above).

Across a rotation. Suppose the issuer is at version 1 and you mint token A, then rotate to version 2 and mint token B. With grace-versions = 1 the JWKS now lists both v1's and v2's kid, so the verifier validates both A and B by selecting each token's kid. Rotate once more to version 3 (grace floor advances to 2): v1's JWK is dropped, so token A no longer resolves and is rejected, while B (v2) and any v3 token still validate. No verifier reconfiguration is needed: it always re-reads the published JWKS.

Where to go next 

• Rotating keys: how issuer rotation drives the grace window.
• Go client: a real go-oidc verifier that validates Basil JWT-SVIDs off this surface.
• Other languages: verifying JWT-SVIDs from any stack.