feat: upsert credential support

On macOS the credentials cannot be stored if one already exists. But we
didn't want to clobber the credentials on Save.

A new `Upsert` function is added to clobber credentials purposefully.
macOS is the only operating system that requires this to be atomic, but
others might require it too.

Signed-off-by: Alano Terblanche <18033717+Benehiko@users.noreply.github.com>

Author: Benehiko

plugins/pass/teststore/teststore.go

@@ -33,6 +33,7 @@ type MockStore struct {
 	errDelete error
 	errGet    error
 	errFilter error
+	errUpsert error
 	store     map[store.ID]store.Secret
 }
 
@@ -74,6 +75,12 @@ func WithStoreDeleteErr(err error) Option {
 	}
 }
 
+func WithStoreUpsertErr(err error) Option {
+	return func(m *MockStore) {
+		m.errUpsert = err
+	}
+}
+
 func WithStore(store map[store.ID]store.Secret) Option {
 	return func(m *MockStore) {
 		m.store = store
@@ -127,6 +134,17 @@ func (m *MockStore) Save(_ context.Context, id store.ID, secret store.Secret) er
 	return nil
 }
 
+func (m *MockStore) Upsert(_ context.Context, id store.ID, secret store.Secret) error {
+	m.lock.Lock()
+	defer m.lock.Unlock()
+	if m.errUpsert != nil {
+		return m.errUpsert
+	}
+
+	m.store[id] = secret
+	return nil
+}
+
 func (m *MockStore) Filter(_ context.Context, pattern store.Pattern) (map[store.ID]store.Secret, error) {
 	m.lock.Lock()
 	defer m.lock.Unlock()

store/keychain/keychain_darwin.go

@@ -19,6 +19,7 @@ import (
 	"errors"
 	"fmt"
 	"maps"
+	"sync"
 
 	kc "github.com/docker/secrets-engine/store/keychain/internal/go-keychain"
 
@@ -31,6 +32,7 @@ var (
 )
 
 type keychainStore[T store.Secret] struct {
+	mu                        sync.Mutex
 	serviceGroup              string
 	serviceName               string
 	factory                   store.Factory[T]
@@ -198,6 +200,21 @@ func (k *keychainStore[T]) Save(_ context.Context, id store.ID, secret store.Sec
 	return mapKeychainError(kc.AddItem(item))
 }
 
+// Upsert atomically replaces a credential in the macOS Keychain.
+//
+// The macOS Keychain does not allow overwriting an existing item via AddItem,
+// so Upsert holds a mutex and performs a Delete followed by a Save to ensure
+// no concurrent Upsert can interleave between the two operations.
+func (k *keychainStore[T]) Upsert(ctx context.Context, id store.ID, secret store.Secret) error {
+	k.mu.Lock()
+	defer k.mu.Unlock()
+
+	if err := k.Delete(ctx, id); err != nil {
+		return err
+	}
+	return k.Save(ctx, id, secret)
+}
+
 func (k *keychainStore[T]) Filter(ctx context.Context, pattern store.Pattern) (map[store.ID]store.Secret, error) {
 	// Note: Filter on macOS cannot filter by generic attributes and thus we
 	// cannot split the ID and store it in the keychain as parts for later

store/keychain/keychain_linux.go

@@ -339,6 +339,10 @@ func (k *keychainStore[T]) Save(_ context.Context, id store.ID, secret store.Sec
 	return nil
 }
 
+func (k *keychainStore[T]) Upsert(ctx context.Context, id store.ID, secret store.Secret) error {
+	return k.Save(ctx, id, secret)
+}
+
 //gocyclo:ignore
 func (k *keychainStore[T]) Filter(ctx context.Context, pattern store.Pattern) (map[store.ID]store.Secret, error) {
 	service, err := kc.NewService()

store/keychain/keychain_windows.go

@@ -336,6 +336,10 @@ func (k *keychainStore[T]) Save(_ context.Context, id store.ID, secret store.Sec
 	return mapWindowsCredentialError(g.Write())
 }
 
+func (k *keychainStore[T]) Upsert(ctx context.Context, id store.ID, secret store.Secret) error {
+	return k.Save(ctx, id, secret)
+}
+
 func (k *keychainStore[T]) Filter(ctx context.Context, pattern store.Pattern) (map[store.ID]store.Secret, error) {
 	// Note: there is no notion of a filter on Windows inside the wincred API.
 	// It has no way to even filter on known attributes.

store/mocks/mock_store.go

@@ -70,6 +70,10 @@ func (m *MockStore) Save(_ context.Context, id store.ID, secret store.Secret) er
 	return nil
 }
 
+func (m *MockStore) Upsert(ctx context.Context, id store.ID, secret store.Secret) error {
+	return m.Save(ctx, id, secret)
+}
+
 func (m *MockStore) Filter(_ context.Context, pattern store.Pattern) (map[store.ID]store.Secret, error) {
 	m.lock.Lock()
 	defer m.lock.Unlock()

store/posixage/store.go

@@ -376,6 +376,10 @@ func (f *fileStore[T]) Save(ctx context.Context, id store.ID, s store.Secret) er
 	return secretfile.Persist(id, f.filesystem, metadata, secrets)
 }
 
+func (f *fileStore[T]) Upsert(ctx context.Context, id store.ID, s store.Secret) error {
+	return f.Save(ctx, id, s)
+}
+
 type config struct {
 	logger                    logging.Logger
 	registeredDecryptionFunc  []promptCaller

store/store.go

@@ -84,6 +84,11 @@ type Store interface {
 	GetAllMetadata(ctx context.Context) (map[ID]Secret, error)
 	// Save persists credentials from the store.
 	Save(ctx context.Context, id ID, secret Secret) error
+	// Upsert atomically replaces an existing credential or inserts a new one.
+	// On stores that do not support overwriting (e.g. macOS Keychain), it
+	// deletes the existing credential and then saves the new one under a mutex
+	// to ensure the two operations are not interleaved.
+	Upsert(ctx context.Context, id ID, secret Secret) error
 	// Filter returns a map of secrets based on a [Pattern].
 	//
 	// Secrets returned will have both [Secret.SetMetadata] and [Secret.Unmarshal]