TT-17624: Add GCP provider

[vladzabolotnyi]

Description

Ticket: https://tyktech.atlassian.net/browse/TT-17624

The change introduces a provider for GCP secret manager. The provider supports multiple auth options, SA impersonation and external account.

Related Issue

Motivation and Context

Test Coverage For This Change

DEMOS

1. Showing the GCP is working only with ee build tag and value is resolved with authorized_user creds type.

Screen.Recording.2026-07-22.at.11.59.57.mov

2. Showing the GCP is working with ADC, Service Accounts with providing JSON or File

Screen.Recording.2026-07-22.at.12.11.20.mov

3. The SA Impersonation is working

Screen.Recording.2026-07-22.at.12.21.59.mov

4. Field extraction is working if stored secret has JSON format

Screen.Recording.2026-07-22.at.12.27.03.mov

5. Provider resolves value with different versions

Screen.Recording.2026-07-22.at.12.29.06.mov

6. Set is creating a new secret if key not exist or add the new version with value otherwise

GCP.Set.method.mov

7. Workload Identity Federation with External account. The gateway wasn't deployed on AWS but we used real AWS credentials to setup WIF on GCP. The resolution and api communication between cloud providers will be the same as when gateway is deployed on AWS. This test wasn't mandatory because its handled by SDK and KV library is only responsible for creds validation but its always better to be sure.

Screen.Recording.2026-07-22.at.15.51.59.mov

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Refactoring or add test (improvements in base code or adds test coverage to functionality)
• Documentation updates or improvements.

Checklist

• I have reviewed the guidelines for contributing to this repository.
• Make sure you are requesting to pull a topic/feature/bugfix branch (right side). If PRing from your fork, don't come from your master!
• Make sure you are making a pull request against our master branch (left side). Also, it would be best if you started your change off our latest master.
• My change requires a change to the documentation.
  • I have manually updated the README(s)/documentation accordingly.
  • If you've changed APIs, describe what needs to be updated in the documentation.
• I have updated the documentation accordingly.
• Modules and vendor dependencies have been updated; run go mod tidy && go mod vendor
• When updating library version must provide reason/explanation for this update.
• I have added tests to cover my changes.
• All new and existing tests passed.
• Check your code additions will not fail linting checks:
  • gofmt -s -w .
  • go vet ./...

[github-actions]

CLA Assistant Lite bot:
Thank you for your submission, we really appreciate it. Like many open-source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution. You can sign the CLA by just posting a Pull Request Comment same as the below format.

---

I have read the CLA Document and I hereby sign the CLA

---

Vlad Zabolotnyi seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You can retrigger this bot by commenting recheck in this Pull Request}

[probelabs]

This PR introduces a new provider for Google Cloud Platform (GCP) Secret Manager, enabling its use as a backend for the key-value store. The implementation is comprehensive, covering configuration, multiple authentication methods (including ADC, service account keys, Workload Identity Federation, and SA impersonation), secret retrieval (Get), and secret creation/updating (Set). A key highlight is the inclusion of a fake in-memory gRPC server for robust and isolated testing.

Files Changed Analysis

• go.mod, go.sum: Adds new dependencies for the official GCP client libraries (cloud.google.com/go/secretmanager, cloud.google.com/go/auth, etc.).
• kv/providers/gcp/ (new package): This new package encapsulates all logic for the GCP provider.
  • config.go: Defines the Config struct and the NewFactory function. It is responsible for parsing and performing exhaustive validation of the provider's configuration, including security checks for Workload Identity Federation (external_account) credentials to prevent SSRF and RCE vectors.
  • gcp.go: Contains the core implementation of the gcpProvider. It implements the kv.Setter, kv.Initializer, kv.Timeouter, and kv.Closer interfaces. It handles the logic for interacting with the GCP Secret Manager API, including fetching/setting secrets, data integrity checks via CRC32C checksums, and mapping gRPC status codes to kv error types.
  • fake_test.go: Implements a fake in-memory gRPC server that simulates the Secret Manager API. This is a crucial addition for enabling fast, reliable, and hermetic testing of the provider's logic without external dependencies.
  • gcp_internal_test.go, gcp_test.go: A comprehensive suite of new tests covering configuration parsing, client lifecycle, Get and Set method functionality, and internal logic, all leveraging the fake gRPC server.
• kv/errors.go, kv/internal/store/cache_bypass_test.go: Minor refactoring to align error types, showing minimal impact on existing abstractions.

Architecture & Impact Assessment

• What this PR accomplishes: It integrates GCP Secret Manager as a new, fully-featured backend for the kv storage abstraction, providing users with another option for secure secret management within GCP environments.
• Key technical changes introduced:
  • A new gcpProvider that supports reading and writing secrets, adhering to the existing provider interfaces.
  • The Set method correctly handles the two-step process of creating a secret container if it doesn't exist and then adding a new version. It is also resilient to race conditions where another process creates the secret simultaneously.
  • Support for multiple GCP authentication methods: Application Default Credentials (ADC), explicit service account keys, Workload Identity Federation, and service account impersonation.
• Affected system components: This is an additive change encapsulated within the kv/providers/gcp package. It expands the capabilities of any system component that relies on the kv.Provider interface by making a new storage backend available. Existing providers are unaffected.

graph TD
    subgraph Application
        Service["Service using KV Store"]
    end

    subgraph "KV Abstraction"
        ProviderFactory["kv.ProviderFactory"]
        ProviderInterface["kv.Provider"]
    end

    subgraph "KV Providers"
        style GCPProvider fill:#d2e5ff,stroke:#333,stroke-width:2px
        GCPProvider["gcp.gcpProvider (New)"]
        ExistingProviders["... (Existing Providers)"]
    end

    subgraph "External Services"
        GCPSecretManager["GCP Secret Manager API"]
    end

    Service --> ProviderFactory
    ProviderFactory -- Creates --> ProviderInterface
    ProviderInterface -- Implemented by --> GCPProvider
    ProviderInterface -- Implemented by --> ExistingProviders
    GCPProvider -- Interacts with --> GCPSecretManager

Loading

Scope Discovery & Context Expansion

• The scope of this PR is to deliver a complete, production-ready GCP Secret Manager provider. The implementation is self-contained within the new kv/providers/gcp package.
• The provider is designed with a strong focus on security and robustness. This is evident from the detailed configuration validation in config.go (especially for external_account), support for multiple authentication patterns, and data integrity checks.
• To utilize this new provider, consumers of the kv abstraction will need to update their configurations to specify gcp as the provider type and supply the necessary project ID and authentication details. The immediate next steps would involve updating user documentation and potentially deployment configurations (e.g., Helm charts) to support this new backend.

Metadata

• Review Effort: 4 / 5
• Primary Label: feature

---

Powered by Visor from Probelabs

Last updated: 2026-07-22T11:13:24.957Z | Triggered by: pr_updated | Commit: 6ff2bf9

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

[probelabs]

Security Issues (1)

Severity	Location	Issue
🟡 Warning	kv/providers/gcp/config.go:70	The `CredentialsFile` configuration field, which is a path to a credentials file, is not validated for path traversal sequences. This path is used in two places: to read an `external_account` JSON file directly (`os.ReadFile` in `config.go`) and passed to the Google SDK (`option.WithAuthCredentialsFile` in `gcp.go`). If an attacker can control this configuration value, they could specify a path with traversal sequences (e.g., `../../..`) to read arbitrary files from the server's filesystem. While the configuration is often provided by trusted administrators, this could be a vulnerability in environments where configuration can be influenced by less-privileged actors (e.g., via an API). 💡 Suggestion In the `validateCredentials` function, add validation for the `CredentialsFile` field. Ensure the path is sanitized before use. You can use `filepath.Clean` and then check that the path does not contain `..` or is restricted to an expected base directory.

Architecture Issues (1)

Severity	Location	Issue
🟡 Warning	kv/errors.go:41	The `StoreName` field was removed from the public error type `kv.StoreUnavailableError`. This is a breaking API change that could affect consumers of this library who might be inspecting this error type's fields. While the change simplifies the struct, it's important to ensure this breaking change is intentional and aligned with the project's versioning strategy. 💡 Suggestion If this breaking change is unintentional or not permissible at this stage, consider reintroducing the `StoreName` field, perhaps marking it as deprecated. If the change is intentional, ensure it is properly documented in release notes as a breaking change.

Security Issues (1)

Severity	Location	Issue
🟡 Warning	kv/providers/gcp/config.go:70	The `CredentialsFile` configuration field, which is a path to a credentials file, is not validated for path traversal sequences. This path is used in two places: to read an `external_account` JSON file directly (`os.ReadFile` in `config.go`) and passed to the Google SDK (`option.WithAuthCredentialsFile` in `gcp.go`). If an attacker can control this configuration value, they could specify a path with traversal sequences (e.g., `../../..`) to read arbitrary files from the server's filesystem. While the configuration is often provided by trusted administrators, this could be a vulnerability in environments where configuration can be influenced by less-privileged actors (e.g., via an API). 💡 Suggestion In the `validateCredentials` function, add validation for the `CredentialsFile` field. Ensure the path is sanitized before use. You can use `filepath.Clean` and then check that the path does not contain `..` or is restricted to an expected base directory.

\n\n ### Architecture Issues (1)

Severity	Location	Issue
🟡 Warning	kv/errors.go:41	The `StoreName` field was removed from the public error type `kv.StoreUnavailableError`. This is a breaking API change that could affect consumers of this library who might be inspecting this error type's fields. While the change simplifies the struct, it's important to ensure this breaking change is intentional and aligned with the project's versioning strategy. 💡 Suggestion If this breaking change is unintentional or not permissible at this stage, consider reintroducing the `StoreName` field, perhaps marking it as deprecated. If the change is intentional, ensure it is properly documented in release notes as a breaking change.

\n\n ### ✅ Performance Check Passed

No performance issues found – changes LGTM.

Quality Issues (1)

Severity	Location	Issue
🟡 Warning	kv/providers/gcp/fake_test.go:155	The error returned by `srv.Serve(lis)` in a background goroutine is ignored. An unhandled error here can lead to non-deterministic or hard-to-debug test failures, such as timeouts, without a clear root cause. This poses a risk to test suite reliability and maintainability. 💡 Suggestion Propagate the error from the goroutine to the main test function, for example by using a channel or an `errgroup`, and fail the test explicitly if `srv.Serve` returns an unexpected error. This ensures that server setup failures are caught and reported clearly.

---

Powered by Visor from Probelabs

Last updated: 2026-07-22T11:13:10.900Z | Triggered by: pr_updated | Commit: 6ff2bf9

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

[vladzabolotnyi]

/visor

The CredentialsFile configuration field is used to read a file from the filesystem (e.g., in helpers.go's validateExternalAccount) without prior validation. If an attacker can control this configuration value, they could specify a path with traversal sequences (e.g., ../..) to read arbitrary files from the server's filesystem, limited by the application's permissions. This could lead to sensitive information disclosure.

Its false positive because the person who controls the value of credentials_file controls the whole machine where app is running.

[probelabs]

---

Powered by Visor from Probelabs

Last updated: 2026-07-21T12:43:56.391Z | Triggered by: vladzabolotnyi | Commit: 4aafcfc

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

[vladzabolotnyi]

⚠️ PR doesn't introduce new sonarqube issues but inherits them from parent. They're going to be fixed in one parent PR.

[sonarqubecloud]

Quality Gate passed

Issues
7 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud

[github-actions]

🚨 Jira Linter Failed

Commit: 6ff2bf9
Failed at: 2026-07-22 12:53:37 UTC

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

🔍 Click to view error details

configuration error: Jira user email is required for API authentication

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.

[mativm02]

LGTM