Add keychain module

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

Author: Benehiko

keychain/README.md

@@ -0,0 +1,4 @@
+# Secrets Engine Keychain
+
+Keychain is a standalone library for use to store secrets in a standardized
+format to the OS keychain.

keychain/go.mod

@@ -0,0 +1,19 @@
+module github.com/docker/secrets-engine/keychain
+
+go 1.24.3
+
+replace github.com/docker/secrets-engine => ../
+
+require (
+	github.com/docker/secrets-engine v0.0.0-00010101000000-000000000000
+	github.com/godbus/dbus/v5 v5.1.0
+	github.com/keybase/dbus v0.0.0-20220506165403-5aa21ea2c23a
+	github.com/keybase/go-keychain v0.0.1
+	github.com/spf13/cobra v1.9.1
+)
+
+require (
+	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/spf13/pflag v1.0.6 // indirect
+	golang.org/x/crypto v0.32.0 // indirect
+)

keychain/go.sum

@@ -0,0 +1,25 @@
+github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/godbus/dbus/v5 v5.1.0 h1:4KLkAxT3aOY8Li4FRJe/KvhoNFFxo0m6fNuFUO8QJUk=
+github.com/godbus/dbus/v5 v5.1.0/go.mod h1:xhWf0FNVPg57R7Z0UbKHbJfkEywrmjJnf7w5xrFpKfA=
+github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
+github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
+github.com/keybase/dbus v0.0.0-20220506165403-5aa21ea2c23a h1:K0EAzgzEQHW4Y5lxrmvPMltmlRDzlhLfGmots9EHUTI=
+github.com/keybase/dbus v0.0.0-20220506165403-5aa21ea2c23a/go.mod h1:YPNKjjE7Ubp9dTbnWvsP3HT+hYnY6TfXzubYTBeUxc8=
+github.com/keybase/go-keychain v0.0.1 h1:way+bWYa6lDppZoZcgMbYsvC7GxljxrskdNInRtuthU=
+github.com/keybase/go-keychain v0.0.1/go.mod h1:PdEILRW3i9D8JcdM+FmY6RwkHGnhHxXwkPPMeUgOK1k=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
+github.com/spf13/cobra v1.9.1 h1:CXSaggrXdbHK9CF+8ywj8Amf7PBRmPCOJugH954Nnlo=
+github.com/spf13/cobra v1.9.1/go.mod h1:nDyEzZ8ogv936Cinf6g1RU9MRY64Ir93oCnqb9wxYW0=
+github.com/spf13/pflag v1.0.6 h1:jFzHGLGAlb3ruxLB8MhbI6A8+AQX/2eW4qeyNZXNp2o=
+github.com/spf13/pflag v1.0.6/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
+github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
+github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+golang.org/x/crypto v0.32.0 h1:euUpcYgM8WcP71gNpTqQCn6rC2t6ULUPiOzfWaXVVfc=
+golang.org/x/crypto v0.32.0/go.mod h1:ZnnJkOaASj8g0AjIduWNlq2NRxL0PlBrbKVyZ6V/Ugc=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

keychain/keychain.go

@@ -0,0 +1,66 @@
+package keychain
+
+import (
+	"errors"
+
+	"github.com/docker/secrets-engine/pkg/secrets"
+)
+
+// We depend on the secrets engine to define how secrets should look like
+// but the caller of keychain does not necessarily need to import secrets engine
+type (
+	Secret = secrets.Secret
+	Store  = secrets.Store
+	ID     = secrets.ID
+)
+
+var ParseID = secrets.ParseID
+
+var (
+	ErrCredentialNotFound    = secrets.ErrNotFound
+	ErrCollectionPathInvalid = errors.New("keychain collection path is invalid")
+)
+
+const (
+	// the docker label is the default prefix on all keys stored by the keychain
+	// e.g. io.docker.Secrets:encoded(realm/app/username)
+	dockerSecretsLabel = "io.docker.Secrets"
+)
+
+type keychainStore[T Secret] struct {
+	keyPrefix string
+	factory   func() T
+}
+
+var _ Store = &keychainStore[Secret]{}
+
+type Factory[T secrets.Secret] func() T
+
+type Options[T Secret] func(*keychainStore[T]) error
+
+func WithKeyPrefix[T Secret](prefix string) Options[T] {
+	return func(ks *keychainStore[T]) error {
+		if prefix == "" {
+			return errors.New("the prefix cannot be empty")
+		}
+		ks.keyPrefix = prefix
+		return nil
+	}
+}
+
+// New creates a new keychain store
+//
+// collectionID is a singular noun indicating the collection name, e.g. "docker"
+// factory is a function used to instantiate new secrets of type T.
+func New[T Secret](factory Factory[T], opts ...Options[T]) (Store, error) {
+	k := &keychainStore[T]{
+		factory:   factory,
+		keyPrefix: dockerSecretsLabel,
+	}
+	for _, o := range opts {
+		if err := o(k); err != nil {
+			return nil, err
+		}
+	}
+	return k, nil
+}

keychain/keychain_dumb.go

@@ -0,0 +1,29 @@
+package keychain
+
+import (
+	"context"
+
+	"github.com/docker/secrets-engine/pkg/secrets"
+)
+
+var _ Store = &keychainStore[Secret]{}
+
+// Erase implements secrets.Store.
+func (k *keychainStore[T]) Erase(ctx context.Context, id secrets.ID) error {
+	panic("unimplemented")
+}
+
+// Get implements secrets.Store.
+func (k *keychainStore[T]) Get(ctx context.Context, id secrets.ID) (secrets.Secret, error) {
+	panic("unimplemented")
+}
+
+// GetAll implements secrets.Store.
+func (k *keychainStore[T]) GetAll(ctx context.Context) (map[secrets.ID]secrets.Secret, error) {
+	panic("unimplemented")
+}
+
+// Store implements secrets.Store.
+func (k *keychainStore[T]) Store(ctx context.Context, id secrets.ID, secret secrets.Secret) error {
+	panic("unimplemented")
+}

keychain/mocks/mock_credential.go

@@ -0,0 +1,31 @@
+package mocks
+
+import (
+	"bytes"
+	"errors"
+
+	"github.com/docker/secrets-engine/keychain"
+)
+
+type MockCredential struct {
+	Username string
+	Password string
+}
+
+var _ keychain.Secret = &MockCredential{}
+
+// Marshal implements secrets.Secret.
+func (m *MockCredential) Marshal() ([]byte, error) {
+	return []byte(m.Username + ":" + m.Password), nil
+}
+
+// Unmarshal implements secrets.Secret.
+func (m *MockCredential) Unmarshal(data []byte) error {
+	items := bytes.Split(data, []byte(":"))
+	if len(items) != 2 {
+		return errors.New("failed to unmarshal data into mock credential type")
+	}
+	m.Username = string(items[0])
+	m.Password = string(items[1])
+	return nil
+}

keychain/mocks/mock_store.go

@@ -0,0 +1,65 @@
+package mocks
+
+import (
+	"context"
+	"maps"
+	"sync"
+
+	"github.com/docker/secrets-engine/keychain"
+)
+
+type MockStore struct {
+	lock  sync.RWMutex
+	store map[keychain.ID]keychain.Secret
+}
+
+func (m *MockStore) init() {
+	if m.store == nil {
+		m.store = make(map[keychain.ID]keychain.Secret)
+	}
+}
+
+// Erase implements Store.
+func (m *MockStore) Erase(_ context.Context, id keychain.ID) error {
+	m.lock.Lock()
+	defer m.lock.Unlock()
+	m.init()
+
+	delete(m.store, id)
+	return nil
+}
+
+// Get implements Store.
+func (m *MockStore) Get(_ context.Context, id keychain.ID) (keychain.Secret, error) {
+	m.lock.RLock()
+	defer m.lock.RUnlock()
+	m.init()
+
+	secret, exists := m.store[id]
+	if !exists {
+		return nil, keychain.ErrCredentialNotFound
+	}
+	return secret, nil
+}
+
+// GetAll implements Store.
+func (m *MockStore) GetAll(_ context.Context) (map[keychain.ID]keychain.Secret, error) {
+	m.lock.RLock()
+	defer m.lock.RUnlock()
+	m.init()
+
+	// Return a copy of the store to avoid concurrent map read/write issues.
+	return maps.Clone(m.store), nil
+}
+
+// Store implements Store.
+func (m *MockStore) Store(_ context.Context, id keychain.ID, secret keychain.Secret) error {
+	m.lock.Lock()
+	defer m.lock.Unlock()
+	m.init()
+
+	m.store[id] = secret
+	return nil
+}
+
+var _ keychain.Store = &MockStore{}