feat(credentials): add in-place credential rotation via upsert

Introduces WithSecretName functional option to SaveCredentials, allowing
callers to provide an existing secret path for in-place upsert instead of
always generating a new UUID-based path. Updates CAS backend Update() to
pass the existing secret name on rotation, eliminating orphaned credentials
in all supported secret managers (Vault, AWS, GCP, Azure Key Vault).

Signed-off-by: Miguel Martinez Trivino <miguel@chainloop.dev>

Author: migmartri

app/controlplane/pkg/biz/casbackend.go

@@ -1,5 +1,5 @@
 //
-// Copyright 2024-2025 The Chainloop Authors.
+// Copyright 2024-2026 The Chainloop Authors.
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -429,7 +429,11 @@ func (uc *CASBackendUseCase) Update(ctx context.Context, orgID, id string, descr
 	credentialsUpdated := creds != nil
 	// We want to rotate credentials
 	if creds != nil {
-		secretName, err = uc.credsRW.SaveCredentials(ctx, orgID, creds)
+		var saveOpts []credentials.SaveOption
+		if before.SecretName != "" {
+			saveOpts = append(saveOpts, credentials.WithSecretName(before.SecretName))
+		}
+		secretName, err = uc.credsRW.SaveCredentials(ctx, orgID, creds, saveOpts...)
 		if err != nil {
 			return nil, fmt.Errorf("storing the credentials: %w", err)
 		}

app/controlplane/pkg/biz/casbackend_test.go

@@ -1,5 +1,5 @@
 //
-// Copyright 2024-2025 The Chainloop Authors.
+// Copyright 2024-2026 The Chainloop Authors.
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -264,6 +264,93 @@ func (s *casBackendTestSuite) TestNewCASBackendUseCase() {
 	}
 }
 
+// TestUpdateRotatesCredentialsInPlace verifies that Update() passes the existing SecretName
+// as a WithSecretName option so the credential store upserts in-place instead of
+// creating a new entry.
+func (s *casBackendTestSuite) TestUpdateRotatesCredentialsInPlace() {
+	ctx := context.Background()
+	existingSecretName := "org/existing-secret-path"
+	backendID := uuid.New()
+	newCreds := &credentials.OCIKeypair{Repo: "r", Username: "u", Password: "p"}
+
+	tests := []struct {
+		name               string
+		existingSecret     string
+		wantWithSecretName bool   // whether the SaveOption should carry the existing secret name
+		returnedSecretName string // what SaveCredentials mock returns
+	}{
+		{
+			name:               "existing secret name is forwarded as WithSecretName",
+			existingSecret:     existingSecretName,
+			wantWithSecretName: true,
+			returnedSecretName: existingSecretName,
+		},
+		{
+			name:               "empty secret name generates a new path",
+			existingSecret:     "",
+			wantWithSecretName: false,
+			returnedSecretName: "new-secret-path",
+		},
+	}
+
+	for _, tc := range tests {
+		s.Run(tc.name, func() {
+			s.resetMock()
+
+			before := &biz.CASBackend{
+				ID:         backendID,
+				SecretName: tc.existingSecret,
+				Provider:   backendType,
+			}
+
+			// Step 1: FindByIDInOrg returns the existing backend (consumed once).
+			s.repo.On("FindByIDInOrg", ctx, s.validUUID, backendID).Return(before, nil).Once()
+
+			// Step 2: SaveCredentials — capture SaveOption(s) to verify the secret name.
+			var capturedSecretName string
+			saveMatcher := mock.MatchedBy(func(_ interface{}) bool { return true })
+			s.credsRW.On("SaveCredentials", ctx, s.validUUID.String(), saveMatcher, mock.Anything).
+				Run(func(args mock.Arguments) {
+					// args[3] is the first SaveOption when opts is non-empty.
+					if len(args) > 3 {
+						if opt, ok := args.Get(3).(credentials.SaveOption); ok {
+							o := credentials.ApplySaveOptions([]credentials.SaveOption{opt})
+							capturedSecretName = o.SecretName
+						}
+					}
+				}).Return(tc.returnedSecretName, nil).Maybe()
+
+			// Fallback for no-opts case (empty existing secret → no WithSecretName).
+			s.credsRW.On("SaveCredentials", ctx, s.validUUID.String(), saveMatcher).
+				Return(tc.returnedSecretName, nil).Maybe()
+
+			// Step 3: repo.Update persists the change.
+			updatedBackend := &biz.CASBackend{ID: backendID, SecretName: tc.returnedSecretName, Provider: backendType}
+			s.repo.On("Update", ctx, mock.Anything).Return(updatedBackend, nil)
+
+			// Steps 4–7: PerformValidation is called internally with new creds.
+			s.repo.On("FindByID", mock.Anything, backendID).Return(updatedBackend, nil)
+			s.credsRW.On("ReadCredentials", mock.Anything, mock.Anything, mock.Anything).Return(nil)
+			s.backendProvider.On("ValidateAndExtractCredentials", mock.Anything, mock.Anything).Return(nil, nil)
+			s.repo.On("UpdateValidationStatus", mock.Anything, backendID, biz.CASBackendValidationOK, mock.Anything).Return(nil)
+
+			// Step 8: FindByIDInOrg reload after validation.
+			s.repo.On("FindByIDInOrg", ctx, s.validUUID, backendID).Return(updatedBackend, nil)
+
+			got, err := s.useCase.Update(ctx, s.validUUID.String(), backendID.String(), nil, newCreds, nil, nil, nil)
+			s.Require().NoError(err)
+			s.Equal(tc.returnedSecretName, got.SecretName)
+
+			if tc.wantWithSecretName {
+				s.Equal(existingSecretName, capturedSecretName,
+					"expected WithSecretName(%q) to be forwarded to SaveCredentials", existingSecretName)
+			} else {
+				s.Empty(capturedSecretName, "expected no WithSecretName when existingSecret is empty")
+			}
+		})
+	}
+}
+
 // Run all the tests
 func TestCASBackend(t *testing.T) {
 	suite.Run(t, new(casBackendTestSuite))

pkg/credentials/aws/mocks/SecretsManagerIface.go

@@ -26,6 +26,7 @@ import (
 	"github.com/aws/aws-sdk-go-v2/aws"
 	awscreds "github.com/aws/aws-sdk-go-v2/credentials"
 	"github.com/aws/aws-sdk-go-v2/service/secretsmanager"
+	smtypes "github.com/aws/aws-sdk-go-v2/service/secretsmanager/types"
 	"github.com/aws/aws-sdk-go-v2/service/sso/types"
 	"github.com/aws/smithy-go"
 	"github.com/chainloop-dev/chainloop/pkg/credentials"
@@ -38,6 +39,7 @@ import (
 type SecretsManagerIface interface {
 	GetSecretValue(ctx context.Context, params *secretsmanager.GetSecretValueInput, optFns ...func(*secretsmanager.Options)) (*secretsmanager.GetSecretValueOutput, error)
 	CreateSecret(ctx context.Context, params *secretsmanager.CreateSecretInput, optFns ...func(*secretsmanager.Options)) (*secretsmanager.CreateSecretOutput, error)
+	PutSecretValue(ctx context.Context, params *secretsmanager.PutSecretValueInput, optFns ...func(*secretsmanager.Options)) (*secretsmanager.PutSecretValueOutput, error)
 	DeleteSecret(ctx context.Context, params *secretsmanager.DeleteSecretInput, optFns ...func(*secretsmanager.Options)) (*secretsmanager.DeleteSecretOutput, error)
 }
 
@@ -79,21 +81,43 @@ func NewManager(opts *NewManagerOpts) (*Manager, error) {
 	}, nil
 }
 
-// Save Credentials, this is a generic function that can be used to save any type of credentials
-// as long as they can be passed to json.Marshal
-func (m *Manager) SaveCredentials(ctx context.Context, orgID string, creds any) (string, error) {
-	secretName := strings.Join([]string{m.secretPrefix, orgID, uuid.New().String()}, "/")
+// SaveCredentials saves credentials. If opts includes WithSecretName, upserts at the given path.
+func (m *Manager) SaveCredentials(ctx context.Context, orgID string, creds any, opts ...credentials.SaveOption) (string, error) {
+	o := credentials.ApplySaveOptions(opts)
+	secretName := o.SecretName
+	if secretName == "" {
+		secretName = strings.Join([]string{m.secretPrefix, orgID, uuid.New().String()}, "/")
+	}
 
 	// Store the credentials as json key pairs
 	c, err := json.Marshal(creds)
 	if err != nil {
 		return "", fmt.Errorf("marshaling credentials to be stored: %w", err)
 	}
 
-	if _, err = m.client.CreateSecret(ctx, &secretsmanager.CreateSecretInput{
-		Name: aws.String(secretName), SecretString: aws.String(string(c)),
-	}); err != nil {
-		return "", fmt.Errorf("creating secret in AWS: %w", err)
+	if o.SecretName != "" {
+		// Upsert: try to update existing secret first
+		_, err = m.client.PutSecretValue(ctx, &secretsmanager.PutSecretValueInput{
+			SecretId:     aws.String(secretName),
+			SecretString: aws.String(string(c)),
+		})
+		var notFoundErr *smtypes.ResourceNotFoundException
+		if errors.As(err, &notFoundErr) {
+			// Secret does not exist yet, create it
+			_, err = m.client.CreateSecret(ctx, &secretsmanager.CreateSecretInput{
+				Name:         aws.String(secretName),
+				SecretString: aws.String(string(c)),
+			})
+		}
+	} else {
+		_, err = m.client.CreateSecret(ctx, &secretsmanager.CreateSecretInput{
+			Name:         aws.String(secretName),
+			SecretString: aws.String(string(c)),
+		})
+	}
+
+	if err != nil {
+		return "", fmt.Errorf("saving secret in AWS: %w", err)
 	}
 
 	return secretName, nil

pkg/credentials/aws/secretmanager.go

@@ -1,5 +1,5 @@
 //
-// Copyright 2023 The Chainloop Authors.
+// Copyright 2023-2026 The Chainloop Authors.
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -24,6 +24,7 @@ import (
 
 	"github.com/aws/aws-sdk-go-v2/aws"
 	"github.com/aws/aws-sdk-go-v2/service/secretsmanager"
+	smtypes "github.com/aws/aws-sdk-go-v2/service/secretsmanager/types"
 	"github.com/aws/aws-sdk-go-v2/service/sso/types"
 	"github.com/aws/smithy-go"
 	"github.com/chainloop-dev/chainloop/pkg/credentials"
@@ -202,6 +203,75 @@ func (s *testSuite) TestReadWriteCredentials() {
 	}
 }
 
+func (s *testSuite) TestSaveCredentialsUpsert() {
+	assert := assert.New(s.T())
+	creds := &credentials.OCIKeypair{Repo: "r", Username: "u", Password: "p"}
+	existingSecretName := "org/existing-secret"
+
+	testCases := []struct {
+		name          string
+		secretName    string // non-empty = WithSecretName upsert
+		awsNotFound   bool   // simulate ResourceNotFoundException on PutSecretValue
+		expectedError bool
+	}{
+		{
+			name:       "new secret — CreateSecret called",
+			secretName: "",
+		},
+		{
+			name:       "upsert existing — PutSecretValue succeeds",
+			secretName: existingSecretName,
+		},
+		{
+			name:        "upsert not found — fallback to CreateSecret",
+			secretName:  existingSecretName,
+			awsNotFound: true,
+		},
+	}
+
+	for _, tc := range testCases {
+		s.Run(tc.name, func() {
+			initMockedManager(s)
+			m := s.mockedManager
+			mc, _ := m.client.(*mclient.SecretsManagerIface)
+			ctx := context.Background()
+
+			var saveOpts []credentials.SaveOption
+			if tc.secretName != "" {
+				saveOpts = append(saveOpts, credentials.WithSecretName(tc.secretName))
+			}
+
+			switch {
+			case tc.secretName == "":
+				// New secret path: only CreateSecret is called.
+				mc.On("CreateSecret", ctx, mock.Anything).Return(nil, nil)
+			case tc.awsNotFound:
+				// Upsert path: PutSecretValue returns not-found, then CreateSecret.
+				mc.On("PutSecretValue", ctx, mock.Anything).Return(nil, &smtypes.ResourceNotFoundException{})
+				mc.On("CreateSecret", ctx, mock.Anything).Return(nil, nil)
+			default:
+				// Upsert path: PutSecretValue succeeds directly.
+				mc.On("PutSecretValue", ctx, mock.Anything).Return(&secretsmanager.PutSecretValueOutput{}, nil)
+			}
+
+			returned, err := m.SaveCredentials(ctx, orgID, creds, saveOpts...)
+			if tc.expectedError {
+				assert.Error(err)
+				return
+			}
+			assert.NoError(err)
+
+			if tc.secretName != "" {
+				// In-place upsert must return the same path.
+				assert.Equal(tc.secretName, returned)
+			} else {
+				// New path must be auto-generated (non-empty and different from the existing one).
+				assert.NotEmpty(returned)
+			}
+		})
+	}
+}
+
 // // Create a new secret, delete it and check it does not exist antymore
 func (s *testSuite) TestDeleteCredentials() {
 	assert := assert.New(s.T())

pkg/credentials/aws/secretmanager_test.go

@@ -1,5 +1,5 @@
 //
-// Copyright 2023 The Chainloop Authors.
+// Copyright 2023-2026 The Chainloop Authors.
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -120,9 +120,14 @@ func NewManager(opts *NewManagerOpts) (*Manager, error) {
 	}, nil
 }
 
-// SaveCredentials saves credentials
-func (m *Manager) SaveCredentials(ctx context.Context, orgID string, creds any) (string, error) {
-	secretName := strings.Join([]string{m.secretPrefix, orgID, uuid.New().String()}, "-")
+// SaveCredentials saves credentials. If opts includes WithSecretName, upserts at the given path.
+func (m *Manager) SaveCredentials(ctx context.Context, orgID string, creds any, opts ...credentials.SaveOption) (string, error) {
+	o := credentials.ApplySaveOptions(opts)
+	secretName := o.SecretName
+	if secretName == "" {
+		secretName = strings.Join([]string{m.secretPrefix, orgID, uuid.New().String()}, "-")
+	}
+
 	// Store the credentials as json key pairs
 	c, err := json.Marshal(creds)
 	if err != nil {