Merge pull request #997 from meridianhub/stripe-identity-kyc--4--config-factory-wiring

feat: wire Stripe Identity provider into config, factory, and HTTP routes

Author: bjcoombs

services/party/cmd/main.go

@@ -223,6 +223,7 @@ func run(logger *slog.Logger) error {
 				VerificationService: verificationSvc,
 				HMACSecrets: map[string][]byte{
 					"default": []byte(verificationCfg.WebhookSecret),
+					"stripe":  []byte(verificationCfg.WebhookSecret),
 				},
 				Logger: logger,
 			},
@@ -231,6 +232,25 @@ func run(logger *slog.Logger) error {
 			return fmt.Errorf("failed to create webhook handler: %w", err)
 		}
 
+		// Register provider-specific webhook routes before the generic catch-all.
+		// For Stripe, we use the StripeWebhookAdapter which validates the Stripe-Signature
+		// header (using the Stripe endpoint signing secret) and translates the Stripe event
+		// format to our generic webhook format (signed with the generic HMAC secret).
+		if strings.ToLower(verificationCfg.Provider) == "stripe" {
+			stripeAdapter, err := httpAdapter.NewStripeWebhookAdapter(
+				httpAdapter.StripeWebhookAdapterConfig{
+					InnerHandler:    webhookHandler,
+					WebhookSecret:   []byte(verificationCfg.StripeWebhookSecret),
+					InnerHMACSecret: []byte(verificationCfg.WebhookSecret),
+					Logger:          logger,
+				},
+			)
+			if err != nil {
+				return bootstrap.Permanent(fmt.Errorf("failed to create stripe webhook adapter: %w", err))
+			}
+			httpMux.Handle("/webhooks/verification/stripe", stripeAdapter)
+		}
+
 		httpMux.HandleFunc("/webhooks/verification/", webhookHandler.HandleWebhook)
 		httpMux.HandleFunc("/health", newHTTPHealthHandler(verificationCfg))
 

services/party/config/verification.go

@@ -13,26 +13,39 @@ import (
 //   - "mock": Mock provider for testing (always available)
 //   - "jumio": Jumio identity verification
 //   - "onfido": Onfido identity verification
+//   - "stripe": Stripe Identity verification
 //
 // ProviderConfig contains provider-specific settings like API keys and endpoints.
 // Required keys vary by provider.
 //
-// WebhookSecret is the HMAC secret used to verify incoming webhook signatures.
-// This prevents malicious actors from spoofing verification callbacks.
+// WebhookSecret is the HMAC secret used to verify incoming webhook signatures
+// for the generic webhook handler and as the inner HMAC secret for the Stripe
+// adapter. This prevents malicious actors from spoofing verification callbacks.
+//
+// StripeWebhookSecret is the Stripe endpoint signing secret (whsec_ prefixed)
+// used exclusively to validate the Stripe-Signature header on inbound Stripe
+// webhooks. Required when provider is "stripe".
 //
 // WebhookURL is the publicly accessible URL where providers send verification
 // callbacks. Required for production deployments.
 type VerificationConfig struct {
-	// Provider is the verification provider to use ("mock", "jumio", "onfido").
+	// Provider is the verification provider to use ("mock", "jumio", "onfido", "stripe").
 	Provider string
 
 	// ProviderConfig contains provider-specific configuration.
 	// For jumio/onfido: "api_key", "api_secret", "base_url" (optional).
+	// For stripe: "api_key", "base_url" (optional), "stripe_account" (optional).
 	ProviderConfig map[string]string
 
-	// WebhookSecret is the HMAC secret for validating webhook signatures.
+	// WebhookSecret is the HMAC secret for validating webhook signatures on the
+	// generic handler and as the inner HMAC secret for the Stripe adapter.
 	WebhookSecret string
 
+	// StripeWebhookSecret is the Stripe endpoint signing secret (whsec_ prefixed)
+	// used to validate inbound Stripe webhook signatures.
+	// Loaded from STRIPE_WEBHOOK_SECRET. Required when provider is "stripe".
+	StripeWebhookSecret string
+
 	// WebhookURL is the public URL for provider callbacks (e.g., "https://api.example.com/webhooks/verification").
 	WebhookURL string
 }
@@ -45,27 +58,32 @@ var (
 	ErrEmptyWebhookURLForNonMock    = errors.New("webhook URL is required for non-mock providers")
 	ErrMissingProviderAPIKey        = errors.New("api_key is required in provider config")
 	ErrMissingProviderAPISecret     = errors.New("api_secret is required in provider config")
+	ErrMissingStripeWebhookSecret   = errors.New("stripe_webhook_secret is required when provider is stripe (set STRIPE_WEBHOOK_SECRET)")
 	ErrMockProviderInProduction     = errors.New("mock provider not allowed in production")
 	ErrWebhookHTTPSRequired         = errors.New("webhook URL must use HTTPS in production")
 	ErrWebhookSecretTooShort        = errors.New("webhook secret must be at least 32 characters in production")
 )
 
 // SupportedProviders lists all supported verification provider names.
-var SupportedProviders = []string{"mock", "jumio", "onfido"}
+var SupportedProviders = []string{"mock", "jumio", "onfido", "stripe"}
 
 // LoadVerificationConfig loads verification configuration from environment variables.
 //
 // Required environment variables:
 //   - VERIFICATION_PROVIDER: The provider to use (required)
 //
 // Conditional environment variables (required for non-mock providers):
-//   - VERIFICATION_WEBHOOK_SECRET: HMAC secret for webhook validation
+//   - VERIFICATION_WEBHOOK_SECRET: HMAC secret for generic webhook validation
 //   - VERIFICATION_WEBHOOK_URL: Public webhook callback URL
 //
 // Provider-specific environment variables:
 //   - VERIFICATION_API_KEY: Provider API key
-//   - VERIFICATION_API_SECRET: Provider API secret
+//   - VERIFICATION_API_SECRET: Provider API secret (not required for Stripe)
 //   - VERIFICATION_BASE_URL: Provider base URL (optional, provider default used if not set)
+//
+// Stripe-specific environment variables:
+//   - STRIPE_WEBHOOK_SECRET: Stripe endpoint signing secret (whsec_ prefixed).
+//     Required when VERIFICATION_PROVIDER=stripe.
 func LoadVerificationConfig() (*VerificationConfig, error) {
 	providerConfig := make(map[string]string)
 
@@ -81,10 +99,11 @@ func LoadVerificationConfig() (*VerificationConfig, error) {
 	}
 
 	cfg := &VerificationConfig{
-		Provider:       strings.TrimSpace(os.Getenv("VERIFICATION_PROVIDER")),
-		ProviderConfig: providerConfig,
-		WebhookSecret:  strings.TrimSpace(os.Getenv("VERIFICATION_WEBHOOK_SECRET")),
-		WebhookURL:     strings.TrimSpace(os.Getenv("VERIFICATION_WEBHOOK_URL")),
+		Provider:            strings.TrimSpace(os.Getenv("VERIFICATION_PROVIDER")),
+		ProviderConfig:      providerConfig,
+		WebhookSecret:       strings.TrimSpace(os.Getenv("VERIFICATION_WEBHOOK_SECRET")),
+		StripeWebhookSecret: strings.TrimSpace(os.Getenv("STRIPE_WEBHOOK_SECRET")),
+		WebhookURL:          strings.TrimSpace(os.Getenv("VERIFICATION_WEBHOOK_URL")),
 	}
 
 	if err := cfg.Validate(); err != nil {
@@ -122,10 +141,16 @@ func (c *VerificationConfig) Validate() error {
 	if c.ProviderConfig["api_key"] == "" {
 		return ErrMissingProviderAPIKey
 	}
-	if c.ProviderConfig["api_secret"] == "" {
+	// Stripe only needs api_key; other providers require api_secret as well
+	if strings.ToLower(c.Provider) != "stripe" && c.ProviderConfig["api_secret"] == "" {
 		return ErrMissingProviderAPISecret
 	}
 
+	// Stripe requires its own endpoint signing secret (distinct from the generic HMAC secret)
+	if strings.ToLower(c.Provider) == "stripe" && c.StripeWebhookSecret == "" {
+		return ErrMissingStripeWebhookSecret
+	}
+
 	return nil
 }
 

services/party/config/verification_test.go

@@ -17,6 +17,7 @@ func clearVerificationEnv(t *testing.T) {
 		"VERIFICATION_API_KEY",
 		"VERIFICATION_API_SECRET",
 		"VERIFICATION_BASE_URL",
+		"STRIPE_WEBHOOK_SECRET",
 	}
 	for _, key := range envVars {
 		_ = os.Unsetenv(key)
@@ -261,7 +262,82 @@ func TestVerificationConfig_SupportedProviders(t *testing.T) {
 	assert.Contains(t, SupportedProviders, "mock")
 	assert.Contains(t, SupportedProviders, "jumio")
 	assert.Contains(t, SupportedProviders, "onfido")
-	assert.Len(t, SupportedProviders, 3)
+	assert.Contains(t, SupportedProviders, "stripe")
+	assert.Len(t, SupportedProviders, 4)
+}
+
+func TestLoadVerificationConfig_StripeProvider_OnlyNeedsAPIKey(t *testing.T) {
+	clearVerificationEnv(t)
+	t.Setenv("VERIFICATION_PROVIDER", "stripe")
+	t.Setenv("VERIFICATION_WEBHOOK_SECRET", "webhook-secret")
+	t.Setenv("VERIFICATION_WEBHOOK_URL", "https://api.example.com/webhooks/verification")
+	t.Setenv("VERIFICATION_API_KEY", "sk_test_my-stripe-key")
+	t.Setenv("STRIPE_WEBHOOK_SECRET", "whsec_test_stripe_endpoint_secret")
+	// No VERIFICATION_API_SECRET — Stripe does not need it
+
+	cfg, err := LoadVerificationConfig()
+
+	require.NoError(t, err)
+	assert.Equal(t, "stripe", cfg.Provider)
+	assert.Equal(t, "sk_test_my-stripe-key", cfg.ProviderConfig["api_key"])
+	assert.Empty(t, cfg.ProviderConfig["api_secret"])
+	assert.Equal(t, "whsec_test_stripe_endpoint_secret", cfg.StripeWebhookSecret)
+}
+
+func TestLoadVerificationConfig_StripeProvider_MissingStripeWebhookSecret(t *testing.T) {
+	clearVerificationEnv(t)
+	t.Setenv("VERIFICATION_PROVIDER", "stripe")
+	t.Setenv("VERIFICATION_WEBHOOK_SECRET", "webhook-secret")
+	t.Setenv("VERIFICATION_WEBHOOK_URL", "https://api.example.com/webhooks/verification")
+	t.Setenv("VERIFICATION_API_KEY", "sk_test_my-stripe-key")
+	// No STRIPE_WEBHOOK_SECRET — required for Stripe
+
+	_, err := LoadVerificationConfig()
+
+	require.Error(t, err)
+	assert.ErrorIs(t, err, ErrMissingStripeWebhookSecret)
+}
+
+func TestVerificationConfig_Validate_StripeRequiresWebhookConfig(t *testing.T) {
+	cfg := &VerificationConfig{
+		Provider:       "stripe",
+		ProviderConfig: map[string]string{"api_key": "sk_test_key"},
+		// Missing WebhookSecret and WebhookURL
+	}
+
+	err := cfg.Validate()
+
+	require.Error(t, err)
+	assert.ErrorIs(t, err, ErrEmptyWebhookSecretForNonMock)
+}
+
+func TestVerificationConfig_Validate_StripeWithoutAPISecretPasses(t *testing.T) {
+	cfg := &VerificationConfig{
+		Provider:            "stripe",
+		WebhookSecret:       "webhook-secret",
+		StripeWebhookSecret: "whsec_test_endpoint_secret",
+		WebhookURL:          "https://example.com/webhooks/verification",
+		ProviderConfig:      map[string]string{"api_key": "sk_test_key"},
+	}
+
+	err := cfg.Validate()
+
+	assert.NoError(t, err)
+}
+
+func TestVerificationConfig_Validate_StripeMissingStripeWebhookSecret(t *testing.T) {
+	cfg := &VerificationConfig{
+		Provider:            "stripe",
+		WebhookSecret:       "webhook-secret",
+		StripeWebhookSecret: "", // missing
+		WebhookURL:          "https://example.com/webhooks/verification",
+		ProviderConfig:      map[string]string{"api_key": "sk_test_key"},
+	}
+
+	err := cfg.Validate()
+
+	require.Error(t, err)
+	assert.ErrorIs(t, err, ErrMissingStripeWebhookSecret)
 }
 
 func TestVerificationConfig_ValidateForEnvironment_ProductionRejectsMock(t *testing.T) {

services/party/verification/factory.go

@@ -20,6 +20,7 @@ var (
 // Currently supported providers:
 //   - "mock": Returns a MockProvider for testing and development
 //   - "onfido": Onfido identity verification
+//   - "stripe": Stripe Identity verification
 //
 // Future providers (stubs, not yet implemented):
 //   - "jumio": Jumio identity verification
@@ -40,6 +41,8 @@ func NewProvider(cfg *config.VerificationConfig) (Provider, error) {
 		return nil, ErrUnsupportedProvider
 	case "onfido":
 		return NewOnfidoProvider(cfg, slog.Default())
+	case "stripe":
+		return NewStripeIdentityProvider(cfg, slog.Default())
 	default:
 		return nil, ErrUnsupportedProvider
 	}
@@ -78,6 +81,8 @@ func NewProviderWithOptions(cfg *config.VerificationConfig, opts ProviderOptions
 		return nil, ErrUnsupportedProvider
 	case "onfido":
 		return NewOnfidoProvider(cfg, slog.Default())
+	case "stripe":
+		return NewStripeIdentityProvider(cfg, slog.Default())
 	default:
 		return nil, ErrUnsupportedProvider
 	}

services/party/verification/factory_test.go

@@ -193,6 +193,42 @@ func TestNewProviderWithOptions_NonMockProvider_ReturnsError(t *testing.T) {
 	}
 }
 
+func TestNewProvider_StripeProvider(t *testing.T) {
+	cfg := &config.VerificationConfig{
+		Provider:            "stripe",
+		WebhookSecret:       "webhook-secret",
+		StripeWebhookSecret: "whsec_test_endpoint_secret",
+		WebhookURL:          "https://example.com/webhook",
+		ProviderConfig:      map[string]string{"api_key": "sk_test_key"},
+	}
+
+	provider, err := NewProvider(cfg)
+
+	require.NoError(t, err)
+	require.NotNil(t, provider)
+
+	_, ok := provider.(*StripeIdentityProvider)
+	assert.True(t, ok, "expected *StripeIdentityProvider type")
+}
+
+func TestNewProviderWithOptions_StripeProvider(t *testing.T) {
+	cfg := &config.VerificationConfig{
+		Provider:            "stripe",
+		WebhookSecret:       "webhook-secret",
+		StripeWebhookSecret: "whsec_test_endpoint_secret",
+		WebhookURL:          "https://example.com/webhook",
+		ProviderConfig:      map[string]string{"api_key": "sk_test_key"},
+	}
+
+	provider, err := NewProviderWithOptions(cfg, DefaultProviderOptions())
+
+	require.NoError(t, err)
+	require.NotNil(t, provider)
+
+	_, ok := provider.(*StripeIdentityProvider)
+	assert.True(t, ok, "expected *StripeIdentityProvider type")
+}
+
 func TestNewProviderWithOptions_OnfidoProvider(t *testing.T) {
 	cfg := &config.VerificationConfig{
 		Provider:       "onfido",