jwtkit

package
v0.77.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 3, 2026 License: MIT Imports: 24 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	AccessTokenType          = "access+jwt"
	DelegatedAccessTokenType = "delegated-access+jwt"
	// RemoteApplicationAccessTokenType is the JOSE `typ` for a remote application
	// access token. It carries neither sub nor delegated_sub; identity is the
	// validated iss -> remote_application mapping.
	RemoteApplicationAccessTokenType = "remote-application-access+jwt"
)

AuthKit JOSE `typ` header values. These separate AuthKit JWT classes before claims are mapped into principals.

View Source 
const (
	// DefaultAuthKeysPath is the default directory where External Secrets mounts auth keys
	DefaultAuthKeysPath = "/vault/auth"

	// DefaultKeyReloadInterval is how often a ReloadableKeySource re-stats
	// keys.json for changes. Short keeps the post-rotation multi-replica skew
	// window small; the cost is one stat() per tick. See authkit #90.
	DefaultKeyReloadInterval = 10 * time.Second
)
View Source 
const (
	// DefaultGeneratedKeysDir is the default directory under which the
	// development GeneratedKeySource persists its auto-generated keypair.
	DefaultGeneratedKeysDir = ".runtime/authkit"
)

Variables

View Source 
var ErrUnsupportedJWK = errors.New("unsupported_jwk")

Functions

func AlgorithmForPublicKey added in v0.12.3 

func AlgorithmForPublicKey(pub crypto.PublicKey) string

AlgorithmForPublicKey returns a default JWS alg for a public key when none is specified.

func BaseRegisteredClaims 

func BaseRegisteredClaims(subject string, audiences []string, ttl time.Duration) jwt.RegisteredClaims

Helper to make base registered claims.

func JWKSToPublicKeys added in v0.12.3 

func JWKSToPublicKeys(ks JWKS) (map[string]crypto.PublicKey, error)

JWKSToPublicKeys parses all supported keys in a JWKS document.

func JWKToPublicKey added in v0.12.3 

func JWKToPublicKey(j JWK) (crypto.PublicKey, error)

JWKToPublicKey parses a single JWK into a crypto.PublicKey.

func ParsePublicKeyFromPEM added in v0.12.3 

func ParsePublicKeyFromPEM(pemText string) (crypto.PublicKey, error)

ParsePublicKeyFromPEM parses a PKIX/SPKI, certificate, or PKCS#1 RSA public key PEM.

func ParsePublicKeyFromPEMBytes added in v0.12.3 

func ParsePublicKeyFromPEMBytes(pemBytes []byte) (crypto.PublicKey, error)

ParsePublicKeyFromPEMBytes parses a supported public key PEM block.

func ServeJWKS 

func ServeJWKS(w http.ResponseWriter, r *http.Request, ks JWKS)

ServeJWKS writes JWKS JSON to the ResponseWriter.

func SetLogger added in v0.12.3 

func SetLogger(l Logger)

SetLogger installs the package-level logger used for key-load warnings. Pass nil to restore the default no-op logger.

func SignWithType added in v0.73.0 

func SignWithType(ctx context.Context, signer Signer, claims jwt.MapClaims, typ string, requireHeader bool) (string, error)

SignWithType signs claims, optionally stamping the JOSE `typ` header. It is the single home for the "assert HeaderSigner and set typ, or fall back" idiom that AuthKit's token-minting paths share:

  • typ == "": plain Sign (no typ header).
  • typ != "" && requireHeader: assert HeaderSigner; error if the signer can't stamp headers.
  • typ != "" && !requireHeader: stamp via HeaderSigner when available, else fall back to a plain Sign.

Types

type Ed25519Signer added in v0.12.3 

type Ed25519Signer struct {
	// contains filtered or unexported fields
}

Ed25519Signer signs JWTs with EdDSA (Ed25519).

func NewEd25519Signer added in v0.12.3 

func NewEd25519Signer(kid string) (*Ed25519Signer, error)

NewEd25519Signer generates a new Ed25519 key pair for development/testing.

func (*Ed25519Signer) Algorithm added in v0.12.3 

func (s *Ed25519Signer) Algorithm() string

func (*Ed25519Signer) KID added in v0.12.3 

func (s *Ed25519Signer) KID() string

func (*Ed25519Signer) PublicKey added in v0.12.3 

func (s *Ed25519Signer) PublicKey() crypto.PublicKey

func (*Ed25519Signer) Sign added in v0.12.3 

func (s *Ed25519Signer) Sign(_ context.Context, claims jwt.MapClaims) (string, error)

func (*Ed25519Signer) SignWithHeaders added in v0.12.3 

func (s *Ed25519Signer) SignWithHeaders(_ context.Context, claims jwt.MapClaims, headers map[string]any) (string, error)

type GeneratedKeySource 

type GeneratedKeySource struct {
	// contains filtered or unexported fields
}

GeneratedKeySource generates and persists RSA keys (for development only).

func NewGeneratedKeySource 

func NewGeneratedKeySource() (*GeneratedKeySource, error)

NewGeneratedKeySource creates a KeySource with auto-generated RSA keys, persisting them under DefaultGeneratedKeysDir (".runtime/authkit"). For a custom directory use NewGeneratedKeySourceInDir.

func NewGeneratedKeySourceInDir added in v0.26.0 

func NewGeneratedKeySourceInDir(dir string) (*GeneratedKeySource, error)

NewGeneratedKeySourceInDir creates a KeySource with auto-generated RSA keys, loading from / persisting to the given directory. An empty dir defaults to DefaultGeneratedKeysDir. Development only.

func (*GeneratedKeySource) ActiveSigner 

func (g *GeneratedKeySource) ActiveSigner() Signer

func (*GeneratedKeySource) PublicKeys 

func (g *GeneratedKeySource) PublicKeys() map[string]crypto.PublicKey

type HeaderSigner added in v0.12.0 

type HeaderSigner interface {
	Signer
	// SignWithHeaders signs claims and merges the provided extra JOSE header
	// params into the token header (kid is still set by the signer).
	SignWithHeaders(ctx context.Context, claims jwt.MapClaims, headers map[string]any) (token string, err error)
}

HeaderSigner is an extension of Signer that lets callers set extra JOSE header parameters (e.g. `typ`) on the signed token. AuthKit token minting uses it to stamp the token profile header.

type JWK 

type JWK struct {
	Kty string `json:"kty"`
	Use string `json:"use,omitempty"`
	Kid string `json:"kid,omitempty"`
	Alg string `json:"alg,omitempty"`
	// RSA
	N string `json:"n,omitempty"`
	E string `json:"e,omitempty"`
	// EC / OKP
	Crv string `json:"crv,omitempty"`
	X   string `json:"x,omitempty"`
	Y   string `json:"y,omitempty"`
}

JWK represents a JSON Web Key (RSA, EC, or OKP).

func PublicToJWK added in v0.12.3 

func PublicToJWK(pub crypto.PublicKey, kid, alg string) JWK

PublicToJWK converts a supported public key to a JWK.

type JWKS 

type JWKS struct {
	Keys []JWK `json:"keys"`
}

type KeySource 

type KeySource interface {
	ActiveSigner() Signer
	PublicKeys() map[string]crypto.PublicKey
}

KeySource provides the active signer and public keys for JWKS.

func ResolveKeySource added in v0.77.0 

func ResolveKeySource(path string, allowEphemeralDevKeys bool) (KeySource, error)

ResolveKeySource resolves the local signing-key source with a fixed, explicit precedence. It reads NO environment variables (#231 — AuthKit is a library; env is read once, at the binary boundary, and flows in as explicit arguments/config):

  1. <path>/keys.json (path empty ⇒ DefaultAuthKeysPath "/vault/auth"), served through a ReloadableKeySource so signing-key rotation (e.g. Vault Agent re-rendering the file) takes effect without a process restart.
  2. No keys.json: when allowEphemeralDevKeys is true, an auto-generated RSA dev keypair persisted under .runtime/authkit/ (DEVELOPMENT ONLY); when false — the default, fail-closed posture — a hard error.

Callers that hold key material in memory should build a source directly (NewStaticKeySourceFromPEM / StaticKeySource) instead.

type Logger added in v0.12.3 

type Logger func(format string, args ...any)

Logger receives non-fatal key-loading warnings from jwtkit. The default is a no-op logger so libraries do not write to stdout.

type PublicKeySigner added in v0.12.3 

type PublicKeySigner interface {
	Signer
	PublicKey() crypto.PublicKey
}

PublicKeySigner is implemented by in-memory signers that expose their public key.

type RSASigner 

type RSASigner struct {
	// contains filtered or unexported fields
}

Minimal in-memory RSA signer for bootstrap/dev. Production should load from KMS or DB.

func NewRSASigner 

func NewRSASigner(bits int, kid string) (*RSASigner, error)

func NewRSASignerFromPEM 

func NewRSASignerFromPEM(kid string, pemBytes []byte) (*RSASigner, error)

NewRSASignerFromPEM constructs an RSASigner from a PEM-encoded RSA private key.

func (*RSASigner) Algorithm 

func (s *RSASigner) Algorithm() string

func (*RSASigner) KID 

func (s *RSASigner) KID() string

func (*RSASigner) PrivateKey 

func (s *RSASigner) PrivateKey() *rsa.PrivateKey

func (*RSASigner) PublicKey 

func (s *RSASigner) PublicKey() crypto.PublicKey

func (*RSASigner) Sign 

func (s *RSASigner) Sign(_ context.Context, claims jwt.MapClaims) (string, error)

func (*RSASigner) SignWithHeaders added in v0.12.0 

func (s *RSASigner) SignWithHeaders(_ context.Context, claims jwt.MapClaims, headers map[string]any) (string, error)

SignWithHeaders implements HeaderSigner: it signs claims and merges extra JOSE header params (e.g. `typ`) into the token header. The signer's own kid is set last and cannot be overridden by the supplied headers.

type ReloadableKeySource added in v0.39.0 

type ReloadableKeySource struct {
	// contains filtered or unexported fields
}

ReloadableKeySource wraps a file-backed StaticKeySource and hot-reloads it when keys.json changes on disk (e.g. re-rendered by Vault Agent), so signing- key rotation never requires a process restart. It implements KeySource; reads are lock-free via an atomic pointer. A background poller re-stats keys.json at the configured interval and, on change, atomically swaps in a NEW validated keystore. A malformed/unreadable file keeps the last-good keystore — a bad render never bricks signing. See authkit #90 (AK-IMPL-3).

func NewReloadableFileKeySource added in v0.39.0 

func NewReloadableFileKeySource(path string, interval time.Duration) (*ReloadableKeySource, error)

NewReloadableFileKeySource loads keys.json from the given directory and starts a background poller that hot-reloads it every interval (<=0 → DefaultKeyReloadInterval). It errors when no valid keys.json is present, so use it only where a file source is expected — static/dev sources don't reload (in-memory material is immutable in a running process; generated keys are dev-only).

func (*ReloadableKeySource) ActiveSigner added in v0.39.0 

func (r *ReloadableKeySource) ActiveSigner() Signer

func (*ReloadableKeySource) Close added in v0.39.0 

func (r *ReloadableKeySource) Close()

Close stops the background poller. Safe to call multiple times; optional for process-lifetime sources (primarily for tests and clean shutdown).

func (*ReloadableKeySource) PublicKeys added in v0.39.0 

func (r *ReloadableKeySource) PublicKeys() map[string]crypto.PublicKey

func (*ReloadableKeySource) Reload added in v0.39.0 

func (r *ReloadableKeySource) Reload() error

Reload re-reads keys.json, validates it, and atomically swaps it in. On any read/parse/validation failure it KEEPS the current keystore and returns the error — it never serves a partial or empty key set.

type Signer 

type Signer interface {
	// Algorithm returns the JWS algorithm (e.g., RS256, EdDSA).
	Algorithm() string
	// KID returns current key id.
	KID() string
	// Sign creates a signed JWT with provided claims.
	Sign(ctx context.Context, claims jwt.MapClaims) (token string, err error)
}

Signer issues and verifies asymmetric JWTs.

func NewSignerFromPEM added in v0.12.3 

func NewSignerFromPEM(kid string, pemBytes []byte) (Signer, error)

NewSignerFromPEM constructs a Signer from a PEM-encoded private key (RSA, EC, or Ed25519).

type StaticKeySource 

type StaticKeySource struct {
	Active Signer
	Pubs   map[string]crypto.PublicKey
}

StaticKeySource is a simple in-memory implementation.

func NewStaticKeySourceFromPEM added in v0.77.0 

func NewStaticKeySourceFromPEM(activeKeyID, activePrivateKeyPEM string, publicKeysPEM map[string]string) (StaticKeySource, error)

NewStaticKeySourceFromPEM builds a StaticKeySource from explicit key material: the active signing key (kid + private-key PEM) plus optional extra verification-only public keys (kid -> public-key PEM, e.g. retired keys kept in the JWKS during rotation). It performs no I/O and reads no environment variables — callers (binaries, hosts) own where the material comes from (#231). Unparseable extra public keys are skipped with a warning, matching the keys.json loader.

func (StaticKeySource) ActiveSigner 

func (s StaticKeySource) ActiveSigner() Signer

func (StaticKeySource) PublicKeys 

func (s StaticKeySource) PublicKeys() map[string]crypto.PublicKey

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.