tessl/pypi-secretstorage

Python bindings to FreeDesktop.org Secret Service API for secure password and credential storage

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Search Operations

Name: tessl/pypi-secretstorage
Author: tessl

Provides powerful search capabilities for finding secret items using attribute-based queries. Supports both global searches across all collections and collection-specific searches.

Capabilities

Global Item Search

Searches for items across all available collections using attribute matching, providing a comprehensive way to find secrets system-wide.

def search_items(connection: DBusConnection, attributes: Dict[str, str]) -> Iterator[Item]:
    """
    Returns items from all collections matching the given attributes.
    
    Parameters:
        connection (DBusConnection): Active D-Bus connection
        attributes (Dict[str, str]): Key-value pairs to match against item attributes
    
    Returns:
        Iterator[Item]: Generator yielding matching items from all collections
    
    Note:
        Searches both locked and unlocked collections, but may return items
        that require unlocking before accessing their secret data.
    """

Collection-Specific Search

Searches within a specific collection for items matching given attributes, useful when working with organized secret storage.

# Available as method on Collection class
class Collection:
    def search_items(self, attributes: Dict[str, str]) -> Iterator[Item]:
        """
        Returns items from this collection matching the given attributes.
        
        Parameters:
            attributes (Dict[str, str]): Key-value pairs to match
        
        Returns:
            Iterator[Item]: Generator yielding matching items from this collection
        """

Usage Examples:

import secretstorage

connection = secretstorage.dbus_init()

# Global search across all collections
# Find all database passwords
db_items = list(secretstorage.search_items(
    connection, 
    {"type": "database", "environment": "production"}
))

# Find specific application credentials
app_items = list(secretstorage.search_items(
    connection,
    {"application": "myapp", "username": "admin"}
))

# Collection-specific search
collection = secretstorage.get_default_collection(connection)
local_items = list(collection.search_items({"service": "github"}))

# Search with multiple criteria
complex_search = list(secretstorage.search_items(
    connection,
    {
        "application": "web-browser",
        "domain": "example.com",
        "username": "john.doe"
    }
))

# Handle search results
for item in app_items:
    print(f"Found item: {item.get_label()}")
    attributes = item.get_attributes()
    print(f"  Application: {attributes.get('application')}")
    print(f"  Username: {attributes.get('username')}")
    
    # Check if item is accessible
    if not item.is_locked():
        secret = item.get_secret()
        print(f"  Secret length: {len(secret)} bytes")
    else:
        print("  Item is locked")

# Search for items by partial attribute matching
# Note: SecretStorage requires exact attribute matching
email_items = []
for item in secretstorage.search_items(connection, {}):  # Get all items
    attrs = item.get_attributes()
    if any("email" in key.lower() or "mail" in key.lower() for key in attrs.keys()):
        email_items.append(item)

# Organize search results by application
from collections import defaultdict

results_by_app = defaultdict(list)
for item in secretstorage.search_items(connection, {}):
    attrs = item.get_attributes()
    app = attrs.get("application", "unknown")
    results_by_app[app].append(item)

for app, items in results_by_app.items():
    print(f"{app}: {len(items)} items")

Search Patterns

Common Attribute Keys

Applications typically use these standard attribute keys for consistent searching:

application: Application name (e.g., "firefox", "chrome", "myapp")
service: Service name (e.g., "github", "gmail", "database")
username: Username or account identifier
domain: Domain or server name
protocol: Protocol type (e.g., "https", "ssh", "ftp")
server: Server hostname or IP
port: Port number
type: Secret type (e.g., "password", "token", "key")

Search Best Practices

# Use specific attributes for precise matching
specific_items = list(secretstorage.search_items(
    connection,
    {
        "application": "myapp",
        "server": "api.example.com",
        "username": "service_account"
    }
))

# Fallback search with broader criteria
if not specific_items:
    broader_items = list(secretstorage.search_items(
        connection,
        {"application": "myapp"}
    ))

# Check for empty results
items = list(secretstorage.search_items(connection, {"nonexistent": "key"}))
if not items:
    print("No matching items found")

# Handle multiple matches
matches = list(secretstorage.search_items(connection, {"service": "email"}))
if len(matches) > 1:
    print(f"Found {len(matches)} email accounts:")
    for item in matches:
        attrs = item.get_attributes()
        print(f"  - {attrs.get('username', 'unknown')}@{attrs.get('domain', 'unknown')}")

Types

from typing import Dict, Iterator

# From jeepney.io.blocking (external dependency)
class DBusConnection:
    """D-Bus connection for communicating with system services."""

# From secretstorage.item
class Item:
    """Represents a secret item within a collection."""

Install with Tessl CLI