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

Item Management

Name: tessl/pypi-secretstorage
Author: tessl

Handles individual secret items with comprehensive operations for storing, retrieving, and managing secret data, attributes, and metadata. Items represent individual secrets stored within collections.

Capabilities

Item Class

The main interface for working with individual secret items, providing access to secret data, attributes, labels, and metadata.

class Item:
    """Represents a secret item within a collection."""
    
    def __init__(self, connection: DBusConnection, item_path: str, session: Optional[Session] = None) -> None:
        """
        Initialize item instance.
        
        Parameters:
            connection (DBusConnection): Active D-Bus connection
            item_path (str): D-Bus object path for the item
            session (Session, optional): Encryption session
        """
    
    def __eq__(self, other: "Item") -> bool:
        """Compare items by their D-Bus object path."""
    
    # Lock/Unlock Operations
    def is_locked(self) -> bool:
        """Returns True if item is locked, False otherwise."""
    
    def ensure_not_locked(self) -> None:
        """Raises LockedException if item is locked."""
    
    def unlock(self) -> bool:
        """
        Requests unlocking the item (usually unlocks the entire collection).
        
        Returns:
            bool: False if successfully unlocked, True if prompt dismissed
        """
    
    # Secret Operations
    def get_secret(self) -> bytes:
        """
        Returns the item's secret data.
        
        Returns:
            bytes: Decrypted secret data
        
        Raises:
            LockedException: If item/collection is locked
        """
    
    def get_secret_content_type(self) -> str:
        """
        Returns the content type of the item's secret.
        
        Returns:
            str: MIME type of secret data (e.g., 'text/plain')
        
        Raises:
            LockedException: If item/collection is locked
        """
    
    def set_secret(self, secret: bytes, content_type: str = 'text/plain') -> None:
        """
        Sets the item's secret data.
        
        Parameters:
            secret (bytes): New secret data to store
            content_type (str): MIME type of the secret data
        
        Raises:
            LockedException: If item/collection is locked
        """
    
    # Attribute Operations
    def get_attributes(self) -> Dict[str, str]:
        """
        Returns item attributes as a dictionary.
        
        Returns:
            Dict[str, str]: Key-value attribute pairs used for searching
        """
    
    def set_attributes(self, attributes: Dict[str, str]) -> None:
        """
        Sets item attributes.
        
        Parameters:
            attributes (Dict[str, str]): New attribute key-value pairs
        """
    
    # Label Operations
    def get_label(self) -> str:
        """
        Returns the item's human-readable label.
        
        Returns:
            str: Item label/name
        """
    
    def set_label(self, label: str) -> None:
        """
        Sets the item's label.
        
        Parameters:
            label (str): New item label
        
        Raises:
            LockedException: If item/collection is locked
        """
    
    # Metadata Operations
    def get_created(self) -> int:
        """
        Returns UNIX timestamp when the item was created.
        
        Returns:
            int: Creation timestamp
        """
    
    def get_modified(self) -> int:
        """
        Returns UNIX timestamp when the item was last modified.
        
        Returns:
            int: Modification timestamp
        """
    
    # Item Management
    def delete(self) -> None:
        """
        Deletes the item from its collection.
        
        Raises:
            LockedException: If item/collection is locked
            PromptDismissedException: If user dismisses deletion prompt
        """

Usage Examples:

import secretstorage
from datetime import datetime

connection = secretstorage.dbus_init()
collection = secretstorage.get_default_collection(connection)

# Create an item
item = collection.create_item(
    "API Key",
    {"service": "github", "username": "johndoe"},
    b"ghp_1234567890abcdef"
)

# Retrieve secret data
secret = item.get_secret()
print(f"Secret: {secret.decode()}")

# Check content type
content_type = item.get_secret_content_type()
print(f"Content type: {content_type}")

# Work with attributes
attributes = item.get_attributes()
print(f"Service: {attributes['service']}")

# Update attributes
attributes["last_used"] = str(int(datetime.now().timestamp()))
item.set_attributes(attributes)

# Update the secret
item.set_secret(b"new_api_key_value")

# Check metadata
created = item.get_created()
modified = item.get_modified()
print(f"Created: {datetime.fromtimestamp(created)}")
print(f"Modified: {datetime.fromtimestamp(modified)}")

# Update label
item.set_label("GitHub API Key (Updated)")

# Handle locked items
if item.is_locked():
    dismissed = item.unlock()
    if not dismissed:
        secret = item.get_secret()

# Delete item when no longer needed
item.delete()

Types

from typing import Dict, Optional

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

# From secretstorage.dhcrypto
class Session:
    """Cryptographic session for secure data transfer."""

Install with Tessl CLI