feat: support injecting cryptographic keys via env vars (#119)

Add AUTH_HMAC_SECRET and JWT_PRIVATE_KEY environment variables to allow
injecting stable signing keys from external secret stores (e.g. Kubernetes
Secrets). This eliminates the need for persistent volumes just to preserve
keys across pod restarts, which previously caused 401 errors when keys
were regenerated.

Also fixes a bug where os.MkdirAll was called after LoadOrGenerateSecret,
meaning the secret file write would fail if the data directory didn't
exist yet.

Co-authored-by: Claude Opus 4.6 <[email protected]>

Author: abarisain

docs/docs/configuration.md

@@ -87,6 +87,23 @@ You can use both exact matching and glob patterns for OIDC user authorization:
 --oidc-allowed-users-glob "*@example.com"
 ```
 
+### Cryptographic Key Options
+
+- **`AUTH_HMAC_SECRET`** — Base64-encoded 32-byte secret for HMAC/cookie signing. Default: auto-generated.
+- **`JWT_PRIVATE_KEY`** — PEM-encoded RSA private key (PKCS8) for JWT signing. Default: auto-generated.
+
+When set, these environment variables take precedence over the file-based keys in `{data-path}/secret` and `{data-path}/private_key.pem`. This is useful for deployments without persistent volumes (e.g., Kubernetes) where pod restarts would otherwise regenerate keys and invalidate all existing OAuth tokens.
+
+To generate suitable values:
+
+```bash
+# Generate AUTH_HMAC_SECRET (base64-encoded 32 random bytes)
+openssl rand -base64 32
+
+# Generate JWT_PRIVATE_KEY (RSA 2048-bit PKCS8 PEM)
+openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048
+```
+
 ### Server Options
 
 | Option         | Environment Variable | Default  | Description                  |

docs/docs/examples.md

@@ -86,14 +86,17 @@ spec:
                 secretKeyRef:
                   name: mcp-auth-proxy-secrets
                   key: password
-          volumeMounts:
-            - name: data
-              mountPath: /data
+            - name: AUTH_HMAC_SECRET
+              valueFrom:
+                secretKeyRef:
+                  name: mcp-auth-proxy-keys
+                  key: auth-hmac-secret
+            - name: JWT_PRIVATE_KEY
+              valueFrom:
+                secretKeyRef:
+                  name: mcp-auth-proxy-keys
+                  key: jwt-private-key
           args: ["npx", "-y", "@modelcontextprotocol/server-filesystem", "./"]
-      volumes:
-        - name: data
-          persistentVolumeClaim:
-            claimName: mcp-auth-proxy-data
 ---
 apiVersion: v1
 kind: Service
@@ -165,9 +168,16 @@ spec:
                 secretKeyRef:
                   name: mcp-auth-proxy-secrets
                   key: password
-          volumeMounts:
-            - name: data
-              mountPath: /data
+            - name: AUTH_HMAC_SECRET
+              valueFrom:
+                secretKeyRef:
+                  name: mcp-auth-proxy-keys
+                  key: auth-hmac-secret
+            - name: JWT_PRIVATE_KEY
+              valueFrom:
+                secretKeyRef:
+                  name: mcp-auth-proxy-keys
+                  key: jwt-private-key
 
         # Your MCP server
         - name: mcp-server
@@ -176,8 +186,4 @@ spec:
             - containerPort: 8000
           # Your MCP server configuration here
           # ...
-
-      volumes:
-        - name: data
-          emptyDir: {}
 ```

pkg/mcp-proxy/main.go

@@ -2,6 +2,7 @@ package mcpproxy
 
 import (
 	"context"
+	"crypto/rsa"
 	"crypto/tls"
 	"errors"
 	"fmt"
@@ -99,9 +100,21 @@ func Run(
 		return fmt.Errorf("tlsHost requires automatic TLS; remove noAutoTLS or provide certificate files instead")
 	}
 
-	secret, err := utils.LoadOrGenerateSecret(path.Join(dataPath, "secret"))
-	if err != nil {
-		return fmt.Errorf("failed to load or generate secret: %w", err)
+	if err := os.MkdirAll(dataPath, os.ModePerm); err != nil {
+		return fmt.Errorf("failed to create data directory: %w", err)
+	}
+
+	var secret []byte
+	if envSecret := os.Getenv("AUTH_HMAC_SECRET"); envSecret != "" {
+		secret, err = utils.SecretFromBase64(envSecret)
+		if err != nil {
+			return fmt.Errorf("failed to parse AUTH_HMAC_SECRET environment variable: %w", err)
+		}
+	} else {
+		secret, err = utils.LoadOrGenerateSecret(path.Join(dataPath, "secret"))
+		if err != nil {
+			return fmt.Errorf("failed to load or generate secret: %w", err)
+		}
 	}
 
 	var config zap.Config
@@ -116,9 +129,6 @@ func Run(
 	if err != nil {
 		return fmt.Errorf("failed to build logger: %w", err)
 	}
-	if err := os.MkdirAll(dataPath, os.ModePerm); err != nil {
-		return fmt.Errorf("failed to create database directory: %w", err)
-	}
 
 	if len(proxyTarget) == 0 {
 		return fmt.Errorf("proxy target must be specified")
@@ -201,9 +211,17 @@ func Run(
 		}
 	}()
 
-	privKey, err := utils.LoadOrGeneratePrivateKey(path.Join(dataPath, "private_key.pem"))
-	if err != nil {
-		return fmt.Errorf("failed to load or generate private key: %w", err)
+	var privKey *rsa.PrivateKey
+	if envKey := os.Getenv("JWT_PRIVATE_KEY"); envKey != "" {
+		privKey, err = utils.PrivateKeyFromPEM(envKey)
+		if err != nil {
+			return fmt.Errorf("failed to parse JWT_PRIVATE_KEY environment variable: %w", err)
+		}
+	} else {
+		privKey, err = utils.LoadOrGeneratePrivateKey(path.Join(dataPath, "private_key.pem"))
+		if err != nil {
+			return fmt.Errorf("failed to load or generate private key: %w", err)
+		}
 	}
 	var providers []auth.Provider
 

pkg/utils/keys.go

@@ -4,6 +4,7 @@ import (
 	"crypto/rand"
 	"crypto/rsa"
 	"crypto/x509"
+	"encoding/base64"
 	"encoding/pem"
 	"fmt"
 	"os"
@@ -82,3 +83,30 @@ func LoadPrivateKey(keyPath string) (*rsa.PrivateKey, error) {
 
 	return privateKey.(*rsa.PrivateKey), nil
 }
+
+func SecretFromBase64(encoded string) ([]byte, error) {
+	secret, err := base64.StdEncoding.DecodeString(encoded)
+	if err != nil {
+		return nil, fmt.Errorf("failed to decode base64 secret: %w", err)
+	}
+	if len(secret) != SecretSize {
+		return nil, fmt.Errorf("decoded secret must be exactly %d bytes, got %d", SecretSize, len(secret))
+	}
+	return secret, nil
+}
+
+func PrivateKeyFromPEM(pemStr string) (*rsa.PrivateKey, error) {
+	block, _ := pem.Decode([]byte(pemStr))
+	if block == nil {
+		return nil, fmt.Errorf("failed to decode PEM block")
+	}
+	privateKey, err := x509.ParsePKCS8PrivateKey(block.Bytes)
+	if err != nil {
+		return nil, fmt.Errorf("failed to parse private key: %w", err)
+	}
+	rsaKey, ok := privateKey.(*rsa.PrivateKey)
+	if !ok {
+		return nil, fmt.Errorf("private key is not RSA")
+	}
+	return rsaKey, nil
+}

pkg/utils/keys_test.go

@@ -0,0 +1,82 @@
+package utils
+
+import (
+	"crypto/ecdsa"
+	"crypto/elliptic"
+	"crypto/rand"
+	"crypto/rsa"
+	"crypto/x509"
+	"encoding/base64"
+	"encoding/pem"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestSecretFromBase64_Valid(t *testing.T) {
+	secret := make([]byte, SecretSize)
+	_, err := rand.Read(secret)
+	require.NoError(t, err)
+
+	encoded := base64.StdEncoding.EncodeToString(secret)
+	decoded, err := SecretFromBase64(encoded)
+	require.NoError(t, err)
+	require.Equal(t, secret, decoded)
+}
+
+func TestSecretFromBase64_InvalidBase64(t *testing.T) {
+	_, err := SecretFromBase64("not-valid-base64!!!")
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "failed to decode base64")
+}
+
+func TestSecretFromBase64_WrongLength(t *testing.T) {
+	short := make([]byte, 16)
+	_, err := rand.Read(short)
+	require.NoError(t, err)
+
+	encoded := base64.StdEncoding.EncodeToString(short)
+	_, err = SecretFromBase64(encoded)
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "must be exactly 32 bytes")
+}
+
+func TestPrivateKeyFromPEM_Valid(t *testing.T) {
+	key, err := rsa.GenerateKey(rand.Reader, 2048)
+	require.NoError(t, err)
+
+	keyBytes, err := x509.MarshalPKCS8PrivateKey(key)
+	require.NoError(t, err)
+
+	pemStr := string(pem.EncodeToMemory(&pem.Block{
+		Type:  "PRIVATE KEY",
+		Bytes: keyBytes,
+	}))
+
+	parsed, err := PrivateKeyFromPEM(pemStr)
+	require.NoError(t, err)
+	require.True(t, key.Equal(parsed))
+}
+
+func TestPrivateKeyFromPEM_InvalidPEM(t *testing.T) {
+	_, err := PrivateKeyFromPEM("not a pem")
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "failed to decode PEM block")
+}
+
+func TestPrivateKeyFromPEM_NonRSAKey(t *testing.T) {
+	ecKey, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
+	require.NoError(t, err)
+
+	keyBytes, err := x509.MarshalPKCS8PrivateKey(ecKey)
+	require.NoError(t, err)
+
+	pemStr := string(pem.EncodeToMemory(&pem.Block{
+		Type:  "PRIVATE KEY",
+		Bytes: keyBytes,
+	}))
+
+	_, err = PrivateKeyFromPEM(pemStr)
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "not RSA")
+}