feat(core)!: ingestion security processor

[foukou19]

PR Description

What this PR Provides

• add a pluggable inbound webhook security layer with NONE, BASIC_AUTH, HMAC_SHA256, STATIC_TOKEN, and JWT_BEARER strategies
• resolve runtime secrets from environment variables using a consistent contract (MY_VAR, ${MY_VAR}, env:MY_VAR, <KEY>_env: MY_VAR, <KEY>Env: MY_VAR) without storing sensitive values in the connector configuration
• enforce fail-fast validation when a connector is created or updated so invalid security configuration is rejected before runtime processing
• standardize webhook error handling for authentication failures, forbidden credentials, disabled connectors, missing configuration, and ingestion errors through a centralized route exception mapping
• harden JWT validation by requiring HTTPS jwks_uri values, rejecting env references, and blocking private/loopback/internal hosts to reduce SSRF risk
• ensure runtime comparisons for HMAC and Basic Auth use constant-time checks to avoid timing-based credential leakage
• make HTTP header lookup robust across casing while keeping secret material out of logs and error responses
• keep the security strategy implementations aligned with the hexagonal architecture: domain port + infrastructure validators + centralized route mapping

Review

The reviewer must double-check these points:

• The reviewer has tested the feature
• The reviewer has reviewed the implementation of the feature
• The documentation has been updated
• The feature implementation respects the Technical Doc / ADR previously produced
• The Pull Request title has a ! after the type/scope to identify the breaking
  change in the release note and ensure we will release a major version.

How to test

Initial state

• ensure the application is running with the expected environment variables set for the webhook security tests
• ensure the following secret aliases exist in the runtime environment for the validation steps below:
  • MY_WEBHOOK_SECRET
  • MY_TOKEN
  • TOKEN_SECRET
  • BASIC_PASS
  • BASIC_SECRET
  • MY_SECRET
• ensure the test data is loaded for inbound webhook connectors and mappings, including the webhook connectors used in security validation tests

What to test

1. create a connector with security.type = NONE and no config

   • call POST /api/v1/inbound_webhooks
   • expect status 201
   • expect the response to contain security.type = "NONE"

2. create a connector with security.type = BASIC_AUTH

   • send username and a runtime secret alias such as BASIC_SECRET
   • call the webhook endpoint with an Authorization: Basic ... header using the matching username/password
   • expect status 201 for the creation and 2xx for a successful runtime validation

3. create a connector with security.type = STATIC_TOKEN

   • configure header_name and secret_alias
   • send the matching header value from the environment variable
   • expect the request to be accepted and processed

4. create a connector with security.type = HMAC_SHA256

   • configure header_name and secret_alias
   • compute the HMAC over the raw request body using the configured prefix and secret
   • send the signature in the custom header
   • expect success for a valid signature and 401/403 for invalid or missing values

5. create a connector with security.type = JWT_BEARER

   • configure jwks_uri, client_id_field, and client_id_values
   • send an Authorization: Bearer <jwt> header with a valid token signed by the configured JWKS provider
   • expect success when the token is valid and the configured claim matches the allow-list
   • expect 401 when the token is malformed or missing and 403 when the claims are valid but rejected

6. test runtime environment resolution

   • use values such as MY_SECRET, ${MY_SECRET}, env:MY_SECRET, MY_SECRET_env: MY_SECRET, or MY_SECRETEnv: MY_SECRET where supported
   • confirm the value is resolved at runtime from the environment and not from a persisted clear-text secret

7. test fail-fast creation rules

   • create a connector with an invalid alias format such as my-secret instead of MY_SECRET
   • expect 400 Bad Request
   • create a connector with a blank or missing required config key
   • expect 400 Bad Request

8. test SSRF protection on JWT bearer configuration

   • use a private or loopback jwks_uri such as https://localhost/... or an internal hostname
   • expect creation to fail with 400
   • use a public HTTPS JWKS endpoint
   • expect creation to succeed

Expected results

• the connector is created successfully when the configuration matches the expected contract
• secrets are not stored in cleartext and are resolved from the runtime environment
• missing or invalid authentication headers trigger 401
• wrong credentials or rejected tokens trigger 403
• disabled or absent connectors are rejected before security validation (404 / 403 depending on the business path)
• malformed compressed payloads or invalid request encoding return a controlled 400
• invalid JWT JWKS URIs are rejected during creation to prevent SSRF and internal egress
• the HTTP responses keep a standard webhook contract: 401 for authentication failure, 403 for forbidden credentials, 400 for bad config, and 422 for ingestion mapping errors when relevant

Breaking changes (if any)

• N/A

Context of the Breaking Change

No breaking API contract changes are introduced. The connector security model remains compatible with the existing webhook configuration format, but the validation contract is tightened for runtime secrets and JWT URL safety.

Result of the Breaking Change

• invalid runtime environment aliases are rejected earlier at creation time
• the configuration is hardened against private or internal JWKS endpoints
• webhook requests now fail with a more consistent security contract across strategies

Notes on implementation

The implementation keeps the strategy-specific logic explicit for readability and operational traceability:

• BasicAuthSecurityValidator and StaticTokenSecurityValidator share the same runtime secret resolution model, but they remain separate because their request semantics and validation messages are different
• HmacSha256SecurityValidator validates the raw payload exactly as received and compares the computed signature in constant time
• JwtBearerSecurityValidator handles the JWKS fetch path and JWT claim validation while enforcing SSRF-safe configuration constraints
• the route-level exception mapping is centralized in WebhookExceptionRouteBuilder and WebhookExceptionHandlerHelper, so the HTTP contract remains consistent regardless of the strategy used

[github-code-quality]

Code Coverage Overview

Languages: Java

Java / code-coverage/jacoco

The overall line coverage in commit e05ce0f in the feat/ingestion-secur... branch remains at 91%, unchanged from commit 6976334 in the main branch.

Show a line coverage summary of the most impacted files.

File	main 6976334	feat/ingestion-secur... e05ce0f	+/-
com/decathlon/i...yValidator.java	100%	78%	-22%
com/decathlon/i...yValidator.java	100%	94%	-6%
com/decathlon/i...uteBuilder.java	100%	96%	-4%
com/decathlon/i...ityService.java	97%	98%	+1%
com/decathlon/i...ationUtils.java	82%	86%	+4%
com/decathlon/i...dlerHelper.java	90%	95%	+5%
com/decathlon/i...yProcessor.java	67%	86%	+19%
com/decathlon/i...erProvider.java	33%	100%	+67%
com/decathlon/i...nException.java	0%	100%	+100%
com/decathlon/i...dException.java	0%	100%	+100%

---

_{Updated September 03, 2026 09:56 UTC}

[Copilot]

Pull request overview

Copilot reviewed 23 out of 24 changed files in this pull request and generated 2 comments.

Suppressed comments (8)

src/main/java/com/decathlon/idp_core/domain/port/WebhookSecurityStrategy.java:41

• The Domain port now defines an HTTP-header contract and names Infrastructure exceptions/status semantics. This reverses the required dependency direction: the Domain layer must not know about HTTP or Infrastructure. Keep creation-time domain validation on a domain port, and move runtime request authentication to an Infrastructure-owned strategy contract with adapter exceptions mapped by the ingestion route.

  /// Validates an incoming webhook request at runtime.
  ///
  /// @param headers the inbound HTTP headers
  /// @param rawPayload the exact inbound payload bytes (before decoding)
  /// @param config the persisted security configuration
  /// @throws
  /// com.decathlon.idp_core.infrastructure.adapters.ingestion.exception.WebhookAuthUnauthorizedException
  /// when authentication is missing or malformed (401)
  /// @throws
  /// com.decathlon.idp_core.infrastructure.adapters.ingestion.exception.WebhookAuthForbiddenException
  /// when authentication is provided but rejected (403)
  void validateRequest(Map<String, Object> headers, byte[] rawPayload, Map<String, String> config);

src/main/java/com/decathlon/idp_core/infrastructure/adapters/webhook/security/JwtBearerSecurityValidator.java:146

• expectedAudience is silently ignored, although the security configuration contract supports camelCase variants. A caller using that spelling gets no audience validation at all. Resolve both spellings as is already done for the other JWT keys.

  private String resolveOptionalExpectedAudience(Map<String, String> config) {
    return config.get(KEY_EXPECTED_AUDIENCE_SNAKE_CASE);

src/main/java/com/decathlon/idp_core/infrastructure/adapters/webhook/security/JwtBearerSecurityValidator.java:130

• Audience validation is skipped when expected_audience is absent, and the provider's JwtValidators.createDefault() only performs default timestamp-style validation. This accepts a valid token issued for a different recipient whenever its identity claim is allow-listed, enabling cross-service token replay. Require/derive the webhook audience and always validate aud.

    if (StringUtils.hasText(optionalExpectedAudience)) {
      validateAudienceClaim(jwt, optionalExpectedAudience);
    }

src/main/java/com/decathlon/idp_core/infrastructure/adapters/webhook/security/BasicAuthSecurityValidator.java:54

• HTTP authentication scheme names are case-insensitive, but this rejects valid basic/mixed-case schemes. Use a case-insensitive prefix comparison while retaining the current credential extraction.

    if (!authorization.startsWith("Basic ")) {

src/main/java/com/decathlon/idp_core/infrastructure/adapters/webhook/security/JwtBearerSecurityValidator.java:109

• HTTP authentication scheme names are case-insensitive, but this rejects otherwise valid bearer/mixed-case authorization headers. Compare the scheme case-insensitively.

    if (!authorization.startsWith(BEARER_PREFIX)
        || authorization.substring(BEARER_PREFIX.length()).isBlank()) {

src/main/java/com/decathlon/idp_core/infrastructure/adapters/webhook/security/JwtBearerSecurityValidator.java:65

• These new mandatory JWT keys are absent from the public webhook documentation: docs/src/concepts/webhooks.md:113-119 still says JWT requires only jwks_uri, and its example at lines 165-174 now produces a 400 response. Update the documentation and example with client_id_field, client_id_values, and the audience contract.

    String clientIdValues = WebhookSecurityConfigurationUtils.required(config,
        KEY_CLIENT_ID_VALUES_SNAKE_CASE, KEY_CLIENT_ID_VALUES_CAMEL_CASE);

src/main/java/com/decathlon/idp_core/infrastructure/adapters/ingestion/exception_handler/WebhookErrorCode.java:18

• This error is also used for unsupported encodings and decompression-size violations, so reporting every failure as “invalid or corrupted” is inaccurate and hides the actionable cause. Preserve a description covering invalid, unsupported, and oversized payloads (or safely expose each WebhookDecodingException message).

  INVALID_COMPRESSED_PAYLOAD("invalid_compressed_payload", HttpStatus.BAD_REQUEST,
      LoggingLevel.WARN, "Invalid or corrupted compressed payload"),

src/test/java/com/decathlon/idp_core/infrastructure/adapters/ingestion/InboundWebhookIngestionRouteTest.java:360

• This test can pass on an authentication failure: Camel's handled exception route clears exchange.getException() and instead writes a 401 response. Moreover, the production provider constructs its own Nimbus decoder (WebhookJwtDecoderProvider.java:17-23), so the test's primary JwtDecoder mock is unused and this fake token causes a real request to auth.example.com. Mock the provider/decoder and assert that no authentication error response was produced.

    Exchange exchange = invokeValidateSecurityRoute(connector,
        Map.of("Authorization", "Bearer " + token));

    assertNull(exchange.getException());

[Copilot]

🟡 Changes recommended

Raw-body handling, JWT SSRF enforcement, architecture boundaries, and false-positive tests contain unresolved correctness and security issues.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (1)

src/main/java/com/decathlon/idp_core/domain/port/WebhookSecurityStrategy.java:39

• This domain port now defines its contract in terms of Infrastructure exceptions and HTTP status semantics, reversing the required dependency direction. Define transport-neutral domain authentication exceptions/results in the Domain layer, then map them to 401/403 exceptions exclusively in the ingestion adapter.

  /// @throws
  /// com.decathlon.idp_core.infrastructure.adapters.ingestion.exception.WebhookAuthUnauthorizedException
  /// when authentication is missing or malformed (401)
  /// @throws
  /// com.decathlon.idp_core.infrastructure.adapters.ingestion.exception.WebhookAuthForbiddenException

• Files reviewed: 27/28 changed files
• Comments generated: 9
• Review effort level: Balanced

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
80.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud