sync with master

[Razeen-Abdal-Rahman]

No description provided.

[github-actions]

🚨 Jira Linter Failed

Commit: 6cc0c35
Failed at: 2025-11-11 15:33:26 UTC

The Jira linter failed to validate your PR. Please check the error details below:

🔍 Click to view error details

failed to validate branch and PR title rules: branch name 'master' must contain a valid Jira ticket ID (e.g., ABC-123)

Next Steps

• Ensure your branch name contains a valid Jira ticket ID (e.g., ABC-123)
• Verify your PR title matches the branch's Jira ticket ID
• Check that the Jira ticket exists and is accessible

---

This comment will be automatically deleted once the linter passes.

[github-actions]

API Changes

no api changes detected

[probelabs]

🔍 Code Analysis Results

This pull request, despite its title, is not a simple synchronization but a major feature and enhancement release. It introduces significant improvements to OAS API management, JWT authentication, and mTLS certificate handling.

Files Changed Analysis

The changes are substantial, with 6 new files added and 16 files modified. The vast majority of the 6266 new lines are dedicated to new functionality and comprehensive test suites, particularly for OAS server regeneration and JWT nested claims. The changes are concentrated in core gateway components: apidef (API definitions), gateway (core logic, middleware), and internal/crypto (security helpers).

• New Functionality: The addition of files like apidef/oas/servers_regeneration.go, gateway/api_oas_servers.go, and gateway/mw_jwt_nested_claims_test.go signals the introduction of entirely new, complex features.
• High Impact: Modifications to critical files like gateway/api.go, gateway/mw_jwt.go, and gateway/cert.go indicate that this PR has a wide-ranging impact on the gateway's behavior.

Architecture & Impact Assessment

What this PR accomplishes

This PR delivers several key enhancements:

1. Robust OAS Server Management: Implements a new engine for intelligently regenerating the servers block in OAS API definitions, preserving user-defined URLs while correctly updating Tyk-generated ones based on API configuration (including versioning).
2. Flexible JWT Claim Handling: Adds support for nested claims (using dot notation) for identity (JWTIdentityBaseField) and policy (JWTPolicyFieldName), allowing integration with more complex JWT structures from identity providers.
3. Improved JWT Scope-Based Authorization: Removes the requirement for a JWTDefaultPolicies when using scope-to-policy mapping, enabling purely scope-based authorization. Includes a security fix to prevent privilege escalation on existing sessions.
4. Enhanced mTLS Certificate Matching: Improves the logic for selecting upstream mTLS certificates, correctly handling hosts with and without ports for both exact and wildcard matches.
5. Correct mTLS Certificate Chain Handling: Fixes an issue where leaf certificates from a client certificate chain were incorrectly added to the CA pool, ensuring proper validation of intermediate CAs.

Key Technical Changes

• OAS Server Regeneration Engine: A new module (apidef/oas/servers_regeneration.go) provides a stateful mechanism to calculate the expected Tyk-managed server URLs based on the old and new API definitions. This logic is integrated into the API create/update/patch endpoints in gateway/api.go and gateway/api_oas_servers.go.

  graph TD
      subgraph OAS API Update/Create
          A[API Request] --> B{Is OAS API?};
          B -- Yes --> C[Regenerate Servers Logic];
      end
  
      subgraph C [Server Regeneration]
          C1[1. Compute Old Tyk URLs from previous spec]
          C2[2. Remove old URLs, preserving user-added URLs]
          C3[3. Generate new Tyk URLs based on current spec]
          C4[4. Merge new Tyk URLs and user URLs]
          C1 --> C2 --> C3 --> C4 --> C5[Updated OAS Spec]
      end
  
      subgraph C3
          D{API Type?}
          D -- Versioned --> E[generateVersionedServers]
          D -- Standard --> F[generateStandardServers]
      end
  
      C --> G{Base API Versioning Changed?}
      G -- Yes --> H[Cascade update to child APIs]
  

  Loading

• Nested JWT Claim Lookup: The JWT middleware (gateway/mw_jwt.go) now uses a getClaimValue helper that first attempts a literal key match (for backward compatibility with keys containing dots) and then falls back to a nested map lookup if the key contains dot notation.

  graph TD
      A[Get Claim Field Name e.g., "user.id"] --> B{Lookup literal key "user.id"};
      B -- Found --> C[Return Value];
      B -- Not Found --> D{Perform Nested Lookup for "user", then "id"};
      D -- Found --> C;
      D -- Not Found --> E[Not Found / Fallback];
  

  Loading

Affected System Components

• API Management: The entire lifecycle of OAS-based APIs is affected, from creation and updates to how they are exposed via the gateway.
• JWT Authentication Middleware: Core authentication logic is enhanced to be more flexible and secure.
• mTLS & Upstream Security: The reliability of mutual TLS authentication is improved, both for client-to-gateway and gateway-to-upstream connections.

Scope Discovery & Context Expansion

The scope of this PR is extensive and touches multiple core functionalities:

• OAS API Versioning: The server regeneration logic is deeply integrated with API versioning. Changes to a base API's versioning configuration (e.g., changing from URL path to query param versioning) will now automatically trigger updates to the server URLs of all its child APIs.
• JWT Identity Providers: The support for nested claims significantly broadens the range of identity providers and token formats that can be used with Tyk out-of-the-box, reducing the need for custom middleware to flatten claims.
• Policy Management: The changes to JWT scope mapping provide a more intuitive way to manage authorization. Users can now rely solely on scopes to grant access without needing a placeholder default policy, simplifying configuration.
• Certificate Management: The fixes to mTLS chain handling (internal/crypto/helpers.go) and upstream certificate matching (gateway/cert.go) will resolve subtle but critical bugs for users employing advanced mTLS configurations.

Metadata

• Review Effort: 5 / 5
• Primary Label: enhancement

---

Powered by Visor from Probelabs

Last updated: 2025-11-11T15:38:10.939Z | Triggered by: opened | Commit: 6cc0c35

💡 TIP: You can chat with Visor using /visor ask <your question>

[probelabs]

🔍 Code Analysis Results

Security Issues (1)

Severity	Location	Issue
🟡 Warning	internal/crypto/helpers.go:185-193	The function `AddCACertificatesFromChainToPool` adds single certificates to a certificate pool without verifying if they are CA certificates (i.e., the `IsCA` flag is not checked). While the comment mentions this is for backward compatibility and certificate pinning, it poses a security risk when this function is used to build a CA pool for mutual TLS (mTLS). If a user misconfigures a non-CA end-entity certificate for mTLS client validation, the gateway will incorrectly trust it as a Certificate Authority. This could allow an attacker who possesses the private key for that non-CA certificate to sign new certificates and bypass mTLS authentication. 💡 Suggestion When handling a single certificate, consider checking if `certToAdd.IsCA` is true before adding it to the pool, especially when the pool is intended for client certificate validation. If non-CA certificates must be supported for pinning, consider separating the logic for building pinning pools from mTLS CA pools, or at a minimum, log a prominent warning when a non-CA certificate is added to a CA trust pool.

Architecture Issues (1)

Severity	Location	Issue
🟡 Warning	gateway/mw_jwt.go:388-424	The log messages at lines 388 and 424 have been changed to use a question mark `?` instead of an em dash `—` (e.g., "... URL %s ? ignoring"). This makes the log message's intent unclear and appears to be an unintentional typo. 💡 Suggestion Revert the question marks `?` back to em dashes `—` or rephrase the log messages for clarity. For example, use `... — ignoring` or `..., ignoring.`.

Performance Issues (1)

Severity	Location	Issue
🟡 Warning	gateway/api_oas_servers.go:108-138	When a base API with a large number of versioned child APIs is updated, the `updateChildAPIsServersGW` function sequentially updates each child API. This could lead to a significant delay in the API update operation, as it involves loading and regenerating the OAS spec for every child. For a base API with hundreds of versions, this synchronous loop could become a performance bottleneck for configuration changes. 💡 Suggestion Consider parallelizing the updates for child APIs. A pool of worker goroutines or simply spawning a goroutine for each child update (with a `sync.WaitGroup` to wait for completion) could significantly reduce the total time taken for the base API update operation. Care must be taken to ensure that any shared resources accessed during the update are handled in a thread-safe manner.

Quality Issues (3)

Severity	Location	Issue
🟢 Info	gateway/mw_jwt.go:387	Log message contains a stray question mark, which appears to be a typo or merge conflict artifact. 💡 Suggestion Remove the stray '?' from the log message for clarity.
🟢 Info	gateway/mw_jwt.go:424	Log message contains a stray question mark, which appears to be a typo or merge conflict artifact. 💡 Suggestion Remove the stray '?' from the log message for clarity.
🟡 Warning	internal/crypto/helpers.go:178-194	The function `AddCACertificatesFromChainToPool` has inconsistent behavior for single certificates versus certificate chains. For a single certificate, it is added to the pool regardless of its `IsCA` flag, which is intended for backward compatibility and pinning. However, this could lead to non-CA certificates being added to a CA pool, potentially weakening trust verification if used incorrectly. The debug log message also doesn't clearly distinguish this special handling. 💡 Suggestion Consider making the behavior more explicit. Either strictly enforce the `IsCA` flag for all cases, or improve the logging to clearly indicate when a non-CA certificate is being added to the pool for a specific reason like pinning or backward compatibility. For example: `logrus.Debug("Added single certificate to pool (pinning/compatibility)")`.

Dependency Issues (7)

Severity	Location	Issue
🔴 Critical	apidef/oas/servers_regeneration.go:1	The introduction of a new, complex server regeneration logic for OAS APIs is a significant behavioral change that impacts downstream tools like tyk-operator and the Tyk Portal. The gateway now actively manages the `servers` array, preserving user-defined entries while generating its own, especially for versioned APIs. Downstream tools that read or modify the `servers` block must be updated to align with this new logic to prevent conflicts, data loss, or displaying incorrect API URLs.
🟠 Error	gateway/mw_jwt.go:724	The validation logic for JWT-enabled APIs has changed. A default policy (`JWTDefaultPolicies`) is no longer required if a scope-to-policy mapping is configured. The `tyk-operator`'s validation webhook must be updated to reflect this relaxed validation, otherwise it will incorrectly reject valid `ApiDefinition` custom resources.
🟠 Error	apidef/validator.go:253	A new validation rule has been added that rejects API definitions where load balancing is enabled but all targets have a weight of 0 (resulting in an empty target list). This is a breaking validation change that affects `tyk-operator` and `tyk-sink`. The operator's validation webhook and sink's pre-sync validation should be updated to incorporate this rule.
🟡 Warning	gateway/mw_jwt.go:635	Support for nested JWT claims (using dot-notation for `JWTIdentityBaseField` and `JWTPolicyFieldName`) has been added. Downstream tools like `tyk-operator` need to be updated to support and document this feature in their respective schemas (e.g., the `ApiDefinition` CRD) to ensure feature parity.
🟡 Warning	internal/crypto/helpers.go:156	The logic for handling client certificate chains for mTLS (`AddCACertificatesFromChainToPool`) has been corrected to only add actual CA certificates to the trust pool, skipping the leaf certificate. This is a behavioral change that fixes a bug but could impact users who were relying on the previous incorrect behavior. This change should be clearly communicated in release notes for all dependent projects.
🟡 Warning	gateway/mw_jwt.go:388-424	The log messages on lines 388 and 424 contain a '?' character which appears to be a typo and should likely be a dash '—' or removed for clarity. For example: '...URL %s ? ignoring'. 💡 Suggestion Replace the '?' with '—' to match other log message styles or rephrase to avoid ambiguity.
🟡 Warning	internal/crypto/helpers.go:156	The function `AddCACertificatesFromChainToPool` is misleading. While it correctly adds only CA certificates from a chain (length > 1), for a single provided certificate (length == 1), it adds the certificate to the pool regardless of whether it is a CA or not. The comment mentions this is for backward compatibility, but the function name implies only CAs are ever added. 💡 Suggestion Consider renaming the function to better reflect its behavior (e.g., `AddTrustAnchorsFromCertificate`) or update the function's documentation to be very explicit about the exceptional behavior for single, non-CA certificates and the risks of misconfiguration.

✅ Connectivity Check Passed

No connectivity issues found – changes LGTM.

---

Powered by Visor from Probelabs

Last updated: 2025-11-11T15:38:12.010Z | Triggered by: opened | Commit: 6cc0c35

💡 TIP: You can chat with Visor using /visor ask <your question>