store: add Filter function

This patch adds the `Filter` function on the `Store` interface. This
allows a store provider from filtering secrets based on partial IDs and
attributes.

This is necessary to reduce the number of calls made to the underlying
store and to standardize how searches happen on a set secrets. In the
keychain package the underlying store would prompt the user (in most
cases) when a secret's encrypted data is retrieved. Fetching secrets
could become an expensive operation, especially when fetching all
secrets.

Hopefully, the Filter function would allow getting only the necessary
secrets required for an application without prompting the user too much.

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

Author: Benehiko

store/examples/secret.go

@@ -10,6 +10,7 @@ import (
 type secret struct {
 	AccessToken  string
 	RefreshToken string
+	Attributes   map[string]string
 }
 
 var _ secrets.Secret = &secret{}
@@ -27,3 +28,7 @@ func (s *secret) Unmarshal(data []byte) error {
 	s.AccessToken, s.RefreshToken = string(tokens[0]), string(tokens[1])
 	return nil
 }
+
+func (s *secret) Metadata() map[string]string {
+	return s.Attributes
+}

store/keychain/cmd/main.go

@@ -41,12 +41,8 @@ func newCommand() (*cobra.Command, error) {
 			}
 
 			var e error
-			for k, v := range secrets {
-				vv, err := v.Marshal()
-				if err != nil {
-					e = errors.Join(e, err)
-				}
-				fmt.Printf("\nID: %s\nValue: %s\n", k, vv)
+			for _, v := range secrets {
+				fmt.Printf("\nID: %s\n", v)
 			}
 			return e
 		},

store/keychain/keychain_darwin.go

@@ -3,6 +3,7 @@ package keychain
 import (
 	"context"
 	"errors"
+	"strings"
 
 	kc "github.com/keybase/go-keychain"
 
@@ -94,7 +95,7 @@ func (k *keychainStore[T]) Get(_ context.Context, id store.ID) (store.Secret, er
 	return secret, nil
 }
 
-func (k *keychainStore[T]) GetAll(context.Context) (map[store.ID]store.Secret, error) {
+func (k *keychainStore[T]) GetAll(context.Context) ([]store.ID, error) {
 	item := newKeychainItem("", k)
 
 	// We use the MatchLimitAll attribute to query for multiple items from the
@@ -107,23 +108,13 @@ func (k *keychainStore[T]) GetAll(context.Context) (map[store.ID]store.Secret, e
 		return nil, mapKeychainError(err)
 	}
 
-	creds := make(map[store.ID]store.Secret, len(results))
+	creds := make([]store.ID, len(results))
 	for _, result := range results {
 		id, err := store.ParseID(result.Account)
 		if err != nil {
-			return nil, err
-		}
-
-		i, err := getItemWithData(id.String(), k)
-		if err != nil {
-			return nil, err
-		}
-
-		secret := k.factory()
-		if err := secret.Unmarshal(i.Data); err != nil {
-			return nil, err
+			continue
 		}
-		creds[id] = secret
+		creds = append(creds, id)
 	}
 	return creds, nil
 }
@@ -143,9 +134,69 @@ func (k *keychainStore[T]) Save(_ context.Context, id store.ID, secret store.Sec
 	// it is a user-friendly name for the item, which is displayed in the keychain UI.
 	// https://developer.apple.com/documentation/security/ksecattrlabel
 	item.SetLabel(k.itemLabel(id))
+
+	parts := strings.SplitSeq(id.String(), "/")
+	for p := range parts {
+		if p == "" {
+			continue
+		}
+		item.SetString(p, p)
+	}
+
+	for k, v := range secret.Metadata() {
+		item.SetString(k, v)
+	}
+
 	return mapKeychainError(kc.AddItem(item))
 }
 
+func (k *keychainStore[T]) Filter(ctx context.Context, id store.ID, attributes map[string]string) (map[store.ID]store.Secret, error) {
+	item := newKeychainItem("", k)
+
+	// We use the MatchLimitAll attribute to query for multiple items from the
+	// store. It cannot be used with item.SetReturnData.
+	// https://developer.apple.com/documentation/security/secitemcopymatching(_:_:)#Discussion
+	item.SetMatchLimit(kc.MatchLimitAll)
+
+	parts := strings.SplitSeq(id.String(), "/")
+	for p := range parts {
+		if p == "" {
+			continue
+		}
+		item.SetString(p, p)
+	}
+
+	for k, v := range attributes {
+		item.SetString(k, v)
+	}
+
+	results, err := kc.QueryItem(item)
+	if err != nil {
+		return nil, mapKeychainError(err)
+	}
+
+	creds := make(map[store.ID]store.Secret)
+	for _, result := range results {
+		id, err := store.ParseID(result.Account)
+		if err != nil {
+			continue
+		}
+
+		i, err := getItemWithData(id.String(), k)
+		if err != nil {
+			return nil, err
+		}
+
+		secret := k.factory()
+		if err := secret.Unmarshal(i.Data); err != nil {
+			return nil, err
+		}
+		creds[id] = secret
+	}
+
+	return creds, nil
+}
+
 func mapKeychainError(err error) error {
 	if err == nil {
 		return nil

store/keychain/keychain_linux.go

@@ -7,7 +7,9 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"maps"
 	"slices"
+	"strings"
 
 	"github.com/keybase/dbus"
 	kc "github.com/keybase/go-keychain/secretservice"
@@ -208,7 +210,7 @@ func (k *keychainStore[T]) Get(_ context.Context, id store.ID) (store.Secret, er
 	return secret, nil
 }
 
-func (k *keychainStore[T]) GetAll(context.Context) (map[store.ID]store.Secret, error) {
+func (k *keychainStore[T]) GetAll(context.Context) ([]store.ID, error) {
 	service, err := kc.NewService()
 	if err != nil {
 		return nil, err
@@ -245,32 +247,23 @@ func (k *keychainStore[T]) GetAll(context.Context) (map[store.ID]store.Secret, e
 		return nil, store.ErrCredentialNotFound
 	}
 
-	credentials := make(map[store.ID]store.Secret, len(itemPaths))
+	credentials := make([]store.ID, 0)
 	for _, itemPath := range itemPaths {
-		value, err := service.GetSecret(itemPath, *session)
-		if err != nil {
-			return nil, err
-		}
-
 		attributes, err := service.GetAttributes(itemPath)
 		if err != nil {
 			return nil, err
 		}
 
 		attrID, ok := attributes["id"]
 		if !ok {
-			return nil, errors.New("secret attributes does not contain `id` field")
+			continue
 		}
 
-		secret := k.factory()
-		if err := secret.Unmarshal(value); err != nil {
-			return nil, err
-		}
 		secretID, err := store.ParseID(attrID)
 		if err != nil {
-			return nil, err
+			continue
 		}
-		credentials[secretID] = secret
+		credentials = append(credentials, secretID)
 	}
 
 	return credentials, nil
@@ -318,6 +311,17 @@ func (k *keychainStore[T]) Save(_ context.Context, id store.ID, secret store.Sec
 	}
 
 	attributes := newItemAttributes(id.String(), k)
+
+	parts := strings.SplitSeq(id.String(), "/")
+	for p := range parts {
+		if p == "" {
+			continue
+		}
+		attributes[p] = p
+	}
+
+	maps.Copy(attributes, secret.Metadata())
+
 	label := k.itemLabel(id)
 	properties := kc.NewSecretProperties(label, attributes)
 
@@ -328,3 +332,81 @@ func (k *keychainStore[T]) Save(_ context.Context, id store.ID, secret store.Sec
 
 	return nil
 }
+
+func (k *keychainStore[T]) Filter(ctx context.Context, id store.ID, attributes map[string]string) (map[store.ID]store.Secret, error) {
+	service, err := kc.NewService()
+	if err != nil {
+		return nil, err
+	}
+
+	session, err := service.OpenSession(kc.AuthenticationDHAES)
+	if err != nil {
+		return nil, err
+	}
+	defer service.CloseSession(session)
+
+	objectPath, err := getDefaultCollection(service)
+	if err != nil {
+		return nil, err
+	}
+
+	err = isCollectionUnlocked(objectPath, service)
+	if err != nil && !errors.Is(err, errCollectionLocked) {
+		return nil, err
+	}
+	if errors.Is(err, errCollectionLocked) {
+		if err := service.Unlock([]dbus.ObjectPath{objectPath}); err != nil {
+			return nil, err
+		}
+	}
+
+	itemAttr := newItemAttributes("", k)
+	maps.Copy(itemAttr, attributes)
+
+	parts := strings.SplitSeq(id.String(), "/")
+	for p := range parts {
+		if p == "" {
+			continue
+		}
+		itemAttr[p] = p
+	}
+
+	itemPaths, err := service.SearchCollection(objectPath, itemAttr)
+	if err != nil {
+		return nil, fmt.Errorf("failed to search collection: %w", err)
+	}
+
+	if len(itemPaths) == 0 {
+		return nil, store.ErrCredentialNotFound
+	}
+
+	credentials := make(map[store.ID]store.Secret, len(itemPaths))
+	for _, itemPath := range itemPaths {
+		value, err := service.GetSecret(itemPath, *session)
+		if err != nil {
+			return nil, err
+		}
+
+		attributes, err := service.GetAttributes(itemPath)
+		if err != nil {
+			return nil, err
+		}
+
+		attrID, ok := attributes["id"]
+		if !ok {
+			return nil, errors.New("secret attributes does not contain `id` field")
+		}
+
+		secret := k.factory()
+		if err := secret.Unmarshal(value); err != nil {
+			return nil, err
+		}
+		secretID, err := store.ParseID(attrID)
+		if err != nil {
+			return nil, err
+		}
+		credentials[secretID] = secret
+	}
+
+	return credentials, nil
+}