Merge pull request #1214 from fluxcd/ci-jwt

auth: introduce JWT signing with JWK for CI systems

Author: matheuscscp

auth/go.mod

@@ -26,6 +26,7 @@ require (
 	github.com/fluxcd/pkg/apis/meta v1.27.0
 	github.com/fluxcd/pkg/cache v0.14.0
 	github.com/fluxcd/pkg/ssh v0.25.0
+	github.com/go-jose/go-jose/v4 v4.1.4
 	github.com/golang-jwt/jwt/v4 v4.5.2
 	github.com/golang-jwt/jwt/v5 v5.3.1
 	github.com/google/go-containerregistry v0.21.5
@@ -65,7 +66,6 @@ require (
 	github.com/evanphx/json-patch/v5 v5.9.11 // indirect
 	github.com/felixge/httpsnoop v1.0.4 // indirect
 	github.com/fxamacker/cbor/v2 v2.9.0 // indirect
-	github.com/go-jose/go-jose/v4 v4.1.4 // indirect
 	github.com/go-logr/logr v1.4.3 // indirect
 	github.com/go-logr/stdr v1.2.2 // indirect
 	github.com/go-openapi/jsonpointer v0.21.0 // indirect

auth/jwt/jwt.go

@@ -0,0 +1,143 @@
+/*
+Copyright 2026 The Flux authors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+// Package jwt issues self-signed JSON Web Tokens. It parses a private signing
+// key from a JSON Web Key (JWK) once and mints compact-serialized tokens on
+// demand, stamping the key's id into the token header so verifiers can locate the
+// matching public key.
+//
+// The signing algorithm is derived from the key type, never chosen by the caller
+// or read from the JWK's "alg" field, so it can never disagree with the key. Only
+// key types that map to a single unambiguous algorithm are supported:
+//
+//	ed25519.PrivateKey  -> EdDSA
+//	*ecdsa.PrivateKey   -> ES256 / ES384 / ES512 (by curve: P-256 / P-384 / P-521)
+//
+// RSA is intentionally unsupported: an RSA key does not determine a single
+// algorithm (RS256/384/512, PS256/384/512), so signing one would require the
+// library to pick on the caller's behalf.
+package jwt
+
+import (
+	"crypto/ecdsa"
+	"crypto/ed25519"
+	"crypto/elliptic"
+	"crypto/rand"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"time"
+
+	jose "github.com/go-jose/go-jose/v4"
+	gojwt "github.com/golang-jwt/jwt/v5"
+)
+
+// SigningKey is a private signing key, parsed from a JWK, that mints signed JWTs
+// using the algorithm determined by the key type.
+type SigningKey struct {
+	key    any
+	method gojwt.SigningMethod
+	kid    string
+}
+
+// ParseJWK parses jwk, a single JSON Web Key, and returns its private signing
+// key. The key must be of a type that maps to a single signing algorithm: an
+// Ed25519 private key (kty "OKP", crv "Ed25519") or an ECDSA private key (kty
+// "EC", crv "P-256", "P-384", or "P-521"), both carrying the private "d"
+// component. RSA keys are rejected because their algorithm is ambiguous.
+func ParseJWK(jwk string) (*SigningKey, error) {
+	var k jose.JSONWebKey
+	if err := json.Unmarshal([]byte(jwk), &k); err != nil {
+		return nil, fmt.Errorf("failed to parse JWK: %w", err)
+	}
+
+	method, err := signingMethodForKey(k.Key)
+	if err != nil {
+		return nil, err
+	}
+
+	return &SigningKey{key: k.Key, method: method, kid: k.KeyID}, nil
+}
+
+// signingMethodForKey returns the signing method uniquely determined by the
+// private key's type. It errors for key types whose algorithm is not unambiguous
+// (RSA) or that are not private signing keys.
+func signingMethodForKey(key any) (gojwt.SigningMethod, error) {
+	switch k := key.(type) {
+	case ed25519.PrivateKey:
+		return gojwt.SigningMethodEdDSA, nil
+	case *ecdsa.PrivateKey:
+		switch k.Curve {
+		case elliptic.P256():
+			return gojwt.SigningMethodES256, nil
+		case elliptic.P384():
+			return gojwt.SigningMethodES384, nil
+		case elliptic.P521():
+			return gojwt.SigningMethodES512, nil
+		default:
+			return nil, fmt.Errorf("unsupported ECDSA curve %q", k.Curve.Params().Name)
+		}
+	default:
+		return nil, fmt.Errorf("unsupported JWK key type %T: "+
+			"want an Ed25519 or ECDSA (P-256/P-384/P-521) private key", key)
+	}
+}
+
+// clockSkewLeeway backdates the "nbf" claim so a verifier whose clock runs
+// slightly behind the issuer's does not reject a freshly minted token as not yet
+// valid. It does not extend "exp": the token still expires ttl after issuance.
+const clockSkewLeeway = 30 * time.Second
+
+// Issue mints a compact-serialized JWT signed with the key, using the algorithm
+// determined by the key type. The signing key's id is set in the "kid" header
+// field. The token carries all seven registered claims (RFC 7519): iss, sub, and
+// aud as given, iat at the current time, nbf backdated by a small clock-skew
+// leeway, exp ttl after issuance, and a random jti.
+func (k *SigningKey) Issue(iss, sub, aud string, ttl time.Duration) (string, error) {
+	jti, err := newJTI()
+	if err != nil {
+		return "", err
+	}
+
+	now := time.Now()
+	claims := gojwt.RegisteredClaims{
+		Issuer:    iss,
+		Subject:   sub,
+		Audience:  gojwt.ClaimStrings{aud},
+		IssuedAt:  gojwt.NewNumericDate(now),
+		NotBefore: gojwt.NewNumericDate(now.Add(-clockSkewLeeway)),
+		ExpiresAt: gojwt.NewNumericDate(now.Add(ttl)),
+		ID:        jti,
+	}
+
+	tok := gojwt.NewWithClaims(k.method, claims)
+	tok.Header["kid"] = k.kid
+
+	signed, err := tok.SignedString(k.key)
+	if err != nil {
+		return "", fmt.Errorf("failed to sign JWT: %w", err)
+	}
+	return signed, nil
+}
+
+// newJTI returns a random 128-bit token identifier as a hex string.
+func newJTI() (string, error) {
+	var b [16]byte
+	if _, err := rand.Read(b[:]); err != nil {
+		return "", fmt.Errorf("failed to generate JWT ID: %w", err)
+	}
+	return hex.EncodeToString(b[:]), nil
+}

auth/jwt/jwt_test.go

@@ -0,0 +1,207 @@
+/*
+Copyright 2026 The Flux authors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package jwt_test
+
+import (
+	"crypto"
+	"crypto/ecdsa"
+	"crypto/ed25519"
+	"crypto/elliptic"
+	"crypto/rand"
+	"crypto/rsa"
+	"encoding/json"
+	"strings"
+	"testing"
+	"time"
+
+	jose "github.com/go-jose/go-jose/v4"
+	gojwt "github.com/golang-jwt/jwt/v5"
+
+	"github.com/fluxcd/pkg/auth/jwt"
+)
+
+func marshalJWK(t *testing.T, key jose.JSONWebKey) string {
+	t.Helper()
+	b, err := json.Marshal(key)
+	if err != nil {
+		t.Fatalf("failed to marshal JWK: %v", err)
+	}
+	return string(b)
+}
+
+func TestParseJWK_Errors(t *testing.T) {
+	_, edPriv, err := ed25519.GenerateKey(rand.Reader)
+	if err != nil {
+		t.Fatal(err)
+	}
+	rsaPriv, err := rsa.GenerateKey(rand.Reader, 2048)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	tests := []struct {
+		name    string
+		jwk     string
+		wantErr string
+	}{
+		{
+			name:    "not json",
+			jwk:     "{not json",
+			wantErr: "failed to parse JWK",
+		},
+		{
+			name:    "rsa rejected as ambiguous",
+			jwk:     marshalJWK(t, jose.JSONWebKey{Key: rsaPriv, KeyID: "a", Algorithm: "RS256"}),
+			wantErr: "unsupported JWK key type *rsa.PrivateKey",
+		},
+		{
+			name:    "public key only",
+			jwk:     marshalJWK(t, jose.JSONWebKey{Key: edPriv.Public(), KeyID: "a", Algorithm: "EdDSA"}),
+			wantErr: "unsupported JWK key type ed25519.PublicKey",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			_, err := jwt.ParseJWK(tt.jwk)
+			if err == nil || !strings.Contains(err.Error(), tt.wantErr) {
+				t.Fatalf("expected error containing %q, got: %v", tt.wantErr, err)
+			}
+		})
+	}
+}
+
+func TestSigningKey_Issue(t *testing.T) {
+	ed25519Pub, ed25519Priv, err := ed25519.GenerateKey(rand.Reader)
+	if err != nil {
+		t.Fatal(err)
+	}
+	es256 := ecKey(t, elliptic.P256())
+	es384 := ecKey(t, elliptic.P384())
+	es521 := ecKey(t, elliptic.P521())
+
+	tests := []struct {
+		name    string
+		priv    crypto.PrivateKey
+		pub     crypto.PublicKey
+		wantAlg string
+	}{
+		{"ed25519", ed25519Priv, ed25519Pub, "EdDSA"},
+		{"ecdsa P-256", es256.priv, es256.pub, "ES256"},
+		{"ecdsa P-384", es384.priv, es384.pub, "ES384"},
+		{"ecdsa P-521", es521.priv, es521.pub, "ES512"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			const kid = "my-key"
+			jwk := marshalJWK(t, jose.JSONWebKey{Key: tt.priv, KeyID: kid})
+
+			key, err := jwt.ParseJWK(jwk)
+			if err != nil {
+				t.Fatalf("ParseJWK: %v", err)
+			}
+
+			signed, err := key.Issue("https://issuer", "my-subject", "my-audience", 10*time.Second)
+			if err != nil {
+				t.Fatalf("Issue: %v", err)
+			}
+
+			claims := gojwt.MapClaims{}
+			tok, err := gojwt.NewParser().ParseWithClaims(signed, claims, func(*gojwt.Token) (any, error) {
+				return tt.pub, nil
+			})
+			if err != nil {
+				t.Fatalf("token failed to verify: %v", err)
+			}
+
+			if tok.Method.Alg() != tt.wantAlg {
+				t.Errorf("alg = %q, want %q", tok.Method.Alg(), tt.wantAlg)
+			}
+			if got := tok.Header["kid"]; got != kid {
+				t.Errorf("kid header = %v, want %q", got, kid)
+			}
+
+			if got, _ := claims.GetIssuer(); got != "https://issuer" {
+				t.Errorf("iss = %q", got)
+			}
+			if got, _ := claims.GetSubject(); got != "my-subject" {
+				t.Errorf("sub = %q", got)
+			}
+			if got, _ := claims.GetAudience(); len(got) != 1 || got[0] != "my-audience" {
+				t.Errorf("aud = %v", got)
+			}
+			iat, _ := claims.GetIssuedAt()
+			nbf, _ := claims.GetNotBefore()
+			exp, _ := claims.GetExpirationTime()
+			if iat == nil || nbf == nil || exp == nil {
+				t.Fatalf("missing time claims: iat=%v nbf=%v exp=%v", iat, nbf, exp)
+			}
+			if want := iat.Add(-30 * time.Second); !nbf.Equal(want) {
+				t.Errorf("nbf = %s, want %s (iat backdated 30s)", nbf, want)
+			}
+			if d := exp.Sub(iat.Time); d != 10*time.Second {
+				t.Errorf("lifetime = %s, want 10s", d)
+			}
+			if jti, ok := claims["jti"].(string); !ok || jti == "" {
+				t.Errorf("jti = %v, want non-empty string", claims["jti"])
+			}
+		})
+	}
+}
+
+func TestSigningKey_Issue_FreshJTIPerCall(t *testing.T) {
+	_, priv, err := ed25519.GenerateKey(rand.Reader)
+	if err != nil {
+		t.Fatal(err)
+	}
+	jwk := marshalJWK(t, jose.JSONWebKey{Key: priv, KeyID: "k"})
+	key, err := jwt.ParseJWK(jwk)
+	if err != nil {
+		t.Fatalf("ParseJWK: %v", err)
+	}
+
+	seen := make(map[string]bool)
+	for range 10 {
+		signed, err := key.Issue("iss", "sub", "aud", time.Second)
+		if err != nil {
+			t.Fatalf("Issue: %v", err)
+		}
+		claims := gojwt.MapClaims{}
+		if _, _, err := gojwt.NewParser().ParseUnverified(signed, claims); err != nil {
+			t.Fatalf("ParseUnverified: %v", err)
+		}
+		jti, _ := claims["jti"].(string)
+		if seen[jti] {
+			t.Fatalf("jti %q reused", jti)
+		}
+		seen[jti] = true
+	}
+}
+
+type ecPair struct {
+	priv *ecdsa.PrivateKey
+	pub  *ecdsa.PublicKey
+}
+
+// ecKey generates a deterministic-per-call ECDSA key pair on the given curve.
+func ecKey(t *testing.T, curve elliptic.Curve) ecPair {
+	t.Helper()
+	priv, err := ecdsa.GenerateKey(curve, rand.Reader)
+	if err != nil {
+		t.Fatalf("failed to generate ECDSA key: %v", err)
+	}
+	return ecPair{priv: priv, pub: &priv.PublicKey}
+}