agent-core-credentials 0.8.2__py3-none-any.whl

agent_core_credentials/__init__.py

@@ -0,0 +1,67 @@
+"""agent_core_credentials — KeePass-backed credential vault.
+
+Public API for credential operations. Used by the CLI and available
+for direct import elsewhere.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from agent_core_credentials.master_password import get_master_password, set_master_password
+from agent_core_credentials.models import Credential, CredentialSummary
+from agent_core_credentials.secrets import SecretNotFoundError, get
+from agent_core_credentials.store import CredentialStore
+
+__all__ = [
+    "Credential",
+    "CredentialSummary",
+    "SecretNotFoundError",
+    "default_vault_path",
+    "delete_credential",
+    "get",
+    "get_credential",
+    "get_master_password",
+    "list_credentials",
+    "set_credential",
+    "set_master_password",
+]
+
+
+def default_vault_path() -> Path:
+    """Resolve the default vault path.
+
+    Honours the AGENT_CORE_VAULT_PATH env var if set; otherwise falls
+    back to ~/.agent-core/credentials.kdbx.
+    """
+    override = os.environ.get("AGENT_CORE_VAULT_PATH")
+    if override:
+        return Path(override)
+    return Path.home() / ".agent-core" / "credentials.kdbx"
+
+
+def get_credential(service: str) -> Credential | None:
+    """Retrieve a credential by service name."""
+    return CredentialStore(default_vault_path()).get(service)
+
+
+def set_credential(
+    service: str,
+    username: str,
+    password: str,
+    url: str = "",
+    notes: str = "",
+) -> None:
+    """Store or overwrite a credential."""
+    CredentialStore(default_vault_path()).set(service, username, password, url, notes)
+
+
+def list_credentials() -> list[CredentialSummary]:
+    """List all stored credentials without passwords."""
+    return CredentialStore(default_vault_path()).list()
+
+
+def delete_credential(service: str) -> bool:
+    """Delete a credential. Returns True if found and deleted."""
+    return CredentialStore(default_vault_path()).delete(service)

agent_core_credentials/cli.py

@@ -0,0 +1,156 @@
+"""agent-core creds CLI — manage stored credentials."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+import typer
+from pykeepass import create_database  # type: ignore[import-untyped]
+from rich import print as rprint
+
+from agent_core_credentials import default_vault_path
+from agent_core_credentials.master_password import set_master_password
+from agent_core_credentials.store import CredentialStore
+
+creds_app = typer.Typer(
+    name="creds",
+    help="Manage stored credentials.",
+    no_args_is_help=True,
+)
+
+# Default paths — overridden in tests via monkeypatch
+_vault_path = default_vault_path()
+_env_path = Path.home() / ".agent-core" / ".env"
+
+
+def _load_env() -> None:
+    """Load .env into the process environment if not already set."""
+    if os.environ.get("AGENT_CORE_VAULT_PASSWORD"):
+        return
+    if _env_path.exists():
+        for line in _env_path.read_text().splitlines():
+            if "=" in line and not line.startswith("#"):
+                key, _, value = line.partition("=")
+                os.environ.setdefault(key.strip(), value.strip())
+
+
+def _store() -> CredentialStore:
+    """Create a CredentialStore for the current vault path."""
+    _load_env()
+    return CredentialStore(_vault_path)
+
+
+@creds_app.command("init")
+def init_vault() -> None:
+    """Initialize the credential vault with a master password."""
+    if _vault_path.exists():
+        rprint(f"[red]Credential vault already exists at {_vault_path}[/red]")
+        raise typer.Exit(1)
+
+    password = typer.prompt("Master password", hide_input=True)
+    confirm = typer.prompt("Confirm password", hide_input=True)
+
+    if password != confirm:
+        rprint("[red]Passwords do not match.[/red]")
+        raise typer.Exit(1)
+
+    _vault_path.parent.mkdir(parents=True, exist_ok=True)
+    create_database(str(_vault_path), password=password)
+
+    set_master_password(_vault_path, password)
+
+    rprint(f"[green]Created credential vault at {_vault_path}[/green]")
+
+
+@creds_app.command("set")
+def set_credential(
+    service: str = typer.Argument(help="Service name (e.g. apex, etsy)"),
+) -> None:
+    """Store a credential with secure password input."""
+    username = typer.prompt("Username")
+    password = typer.prompt("Password", hide_input=True)
+    url = typer.prompt("URL (optional)", default="")
+    notes = typer.prompt("Notes (optional)", default="")
+
+    try:
+        _store().set(service, username, password, url, notes)
+    except ValueError as e:
+        rprint(f"[red]{e}[/red]")
+        raise typer.Exit(1) from None
+
+    rprint(f"[green]Saved {service}[/green]")
+
+
+@creds_app.command("get")
+def get_credential(
+    service: str = typer.Argument(help="Service name to retrieve"),
+    as_json: bool = typer.Option(False, "--json", help="Output as JSON (metadata only, no secret)"),
+) -> None:
+    """Retrieve a stored credential."""
+    try:
+        cred = _store().get(service)
+    except ValueError as e:
+        rprint(f"[red]{e}[/red]")
+        raise typer.Exit(1) from None
+
+    if cred is None:
+        rprint(f"[red]No credential found for {service}[/red]")
+        raise typer.Exit(1)
+
+    if as_json:
+        print(json.dumps({"name": cred.service, "exists": True, "length": len(cred.password)}))
+    else:
+        rprint(f"[bold]Service:[/bold]   {cred.service}")
+        rprint(f"[bold]Length:[/bold]    {len(cred.password)} chars")
+        if cred.mtime is not None:
+            rprint(f"[bold]Modified:[/bold]  {cred.mtime.strftime('%Y-%m-%d %H:%M UTC')}")
+        else:
+            rprint("[bold]Modified:[/bold]  (unknown)")
+
+
+@creds_app.command("list")
+def list_credentials(
+    as_json: bool = typer.Option(False, "--json", help="Output as JSON"),
+) -> None:
+    """List all stored credentials."""
+    try:
+        summaries = _store().list()
+    except ValueError as e:
+        rprint(f"[red]{e}[/red]")
+        raise typer.Exit(1) from None
+
+    if as_json:
+        print(
+            json.dumps(
+                [
+                    {"service": s.service, "username": s.username, "url": s.url}
+                    for s in summaries
+                ]
+            )
+        )
+    else:
+        if not summaries:
+            rprint("[yellow]No credentials stored.[/yellow]")
+            return
+        for s in summaries:
+            rprint(s.service)
+
+
+@creds_app.command("delete")
+def delete_credential(
+    service: str = typer.Argument(help="Service name to delete"),
+) -> None:
+    """Delete a stored credential."""
+    try:
+        deleted = _store().delete(service)
+    except ValueError as e:
+        rprint(f"[red]{e}[/red]")
+        raise typer.Exit(1) from None
+
+    if not deleted:
+        rprint(f"[red]No credential found for {service}[/red]")
+        raise typer.Exit(1)
+
+    rprint(f"[green]Deleted {service}[/green]")

agent_core_credentials/master_password.py

@@ -0,0 +1,217 @@
+"""Master password store — OS keyring (primary) + owner-only encrypted file (fallback).
+
+Strategy pattern: ``_KeyringStore`` and ``EncryptedFileStore`` each implement
+``get() -> str | None`` and ``set(password: str) -> None``.  ``_get_backend()``
+selects the strategy at runtime by probing the keyring.  ``get_master_password``
+and ``set_master_password`` are the public entry-points.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import os
+from pathlib import Path
+
+import keyring
+import keyring.errors
+from cryptography.fernet import Fernet, InvalidToken
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+KEYRING_SERVICE: str = "agent-core"
+_ENV_PATH: Path = Path.home() / ".agent-core" / ".env"
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _username_for(vault_path: Path) -> str:
+    """Return the per-vault keyring username (absolute path string)."""
+    return str(vault_path.resolve())
+
+
+def _hash_for(vault_path: Path) -> str:
+    """Return first 12 hex chars of sha256(resolved vault path) for filename suffixes."""
+    digest = hashlib.sha256(str(vault_path.resolve()).encode()).hexdigest()
+    return digest[:12]
+
+
+# ---------------------------------------------------------------------------
+# EncryptedFileStore — owner-only Fernet-encrypted file fallback
+# ---------------------------------------------------------------------------
+
+
+class EncryptedFileStore:
+    """Owner-only encrypted file fallback for headless Linux/CI environments.
+
+    Two files are written next to the vault:
+      - ``_key_path``: 32-byte Fernet key (generated once, chmod 0o600).
+      - ``_data_path``: Fernet-encrypted master password (chmod 0o600).
+
+    Both files use a hash suffix so multiple vaults in the same directory
+    don't collide.
+    """
+
+    def __init__(self, vault_path: Path) -> None:
+        h = _hash_for(vault_path)
+        self._key_path: Path = vault_path.parent / f".vault-key-{h}"
+        self._data_path: Path = vault_path.parent / f".vault-pass-{h}"
+
+    def _load_key(self) -> bytes:
+        """Load or generate the Fernet key.  Writes 0o600 on creation."""
+        if self._key_path.exists():
+            return self._key_path.read_bytes()
+        key = Fernet.generate_key()
+        self._key_path.write_bytes(key)
+        os.chmod(self._key_path, 0o600)
+        return key
+
+    def get(self) -> str | None:
+        """Return the decrypted password, or None if absent or unreadable."""
+        if not self._data_path.exists():
+            return None
+        key = self._load_key()
+        f = Fernet(key)
+        try:
+            ciphertext = self._data_path.read_bytes()
+            return f.decrypt(ciphertext).decode("utf-8")
+        except InvalidToken:
+            # Key was regenerated (old key deleted); old ciphertext is unreadable.
+            logger.debug(
+                "EncryptedFileStore: InvalidToken — key/data file mismatch; returning None",
+            )
+            return None
+
+    def set(self, password: str) -> None:
+        """Encrypt and persist the password.  Both files are chmod 0o600."""
+        key = self._load_key()
+        f = Fernet(key)
+        ciphertext = f.encrypt(password.encode("utf-8"))
+        self._data_path.write_bytes(ciphertext)
+        os.chmod(self._data_path, 0o600)
+
+
+# ---------------------------------------------------------------------------
+# _KeyringStore — OS keyring (primary) backend
+# ---------------------------------------------------------------------------
+
+
+class _KeyringStore:
+    """OS keyring backend (macOS Keychain, Windows Credential Manager, Secret Service)."""
+
+    def __init__(self, vault_path: Path) -> None:
+        self._username: str = _username_for(vault_path)
+
+    def get(self) -> str | None:
+        """Return the password from the keyring, or None if not stored."""
+        return keyring.get_password(KEYRING_SERVICE, self._username)
+
+    def set(self, password: str) -> None:
+        """Persist the password in the keyring."""
+        keyring.set_password(KEYRING_SERVICE, self._username, password)
+
+
+# ---------------------------------------------------------------------------
+# Backend factory
+# ---------------------------------------------------------------------------
+
+
+def _get_backend(vault_path: Path) -> _KeyringStore | EncryptedFileStore:
+    """Return the appropriate backend by probing the OS keyring.
+
+    A harmless read is performed on a non-secret probe key.  If ``get_password``
+    returns ``None`` (no entry exists — the normal case) the keyring is
+    functional; ``_KeyringStore`` is returned.  If it raises any exception
+    (``NoKeyringError`` on headless Linux/CI, or any other error), fall back
+    to ``EncryptedFileStore``.
+    """
+    try:
+        keyring.get_password("__agent-core-probe__", "__probe__")
+        logger.debug("_get_backend: OS keyring available; using _KeyringStore")
+        return _KeyringStore(vault_path)
+    except Exception as exc:  # noqa: BLE001
+        logger.debug("_get_backend: keyring unavailable (%s); using EncryptedFileStore", exc, exc_info=True)
+        return EncryptedFileStore(vault_path)
+
+
+# ---------------------------------------------------------------------------
+# .env migration helpers
+# ---------------------------------------------------------------------------
+
+
+def _read_env_file_password(env_path: Path) -> str | None:
+    """Parse env_path line by line; return AGENT_CORE_VAULT_PASSWORD value or None."""
+    if not env_path.exists():
+        return None
+    for line in env_path.read_text().splitlines():
+        stripped = line.strip()
+        if stripped.startswith("#"):
+            continue
+        if stripped.startswith("AGENT_CORE_VAULT_PASSWORD="):
+            value = stripped[len("AGENT_CORE_VAULT_PASSWORD="):]
+            return value if value else None
+    return None
+
+
+def _scrub_env_file_password(env_path: Path) -> None:
+    """Remove all non-comment AGENT_CORE_VAULT_PASSWORD= lines from env_path.
+
+    No-op if the file does not exist.  Idempotent.
+    """
+    if not env_path.exists():
+        return
+    original = env_path.read_text()
+    lines = original.splitlines(keepends=True)
+    kept = [
+        line
+        for line in lines
+        if not (
+            not line.strip().startswith("#")
+            and "AGENT_CORE_VAULT_PASSWORD=" in line
+        )
+    ]
+    env_path.write_text("".join(kept))
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def get_master_password(
+    vault_path: Path,
+    env_path: Path = _ENV_PATH,
+) -> str | None:
+    """Return the master password for vault_path, migrating from .env if needed.
+
+    Resolution order:
+    1. Backend (keyring or encrypted file).
+    2. Plaintext ``AGENT_CORE_VAULT_PASSWORD`` in ``env_path`` — triggers a
+       one-time migration: write to backend, scrub from ``.env``.
+    3. Return ``None`` if neither source has a password.
+    """
+    backend = _get_backend(vault_path)
+    stored = backend.get()
+    if stored:
+        return stored
+
+    env_password = _read_env_file_password(env_path)
+    if env_password:
+        logger.debug("get_master_password: migrating password from .env to backend")
+        backend.set(env_password)
+        _scrub_env_file_password(env_path)
+        return env_password
+
+    return None
+
+
+def set_master_password(vault_path: Path, password: str) -> None:
+    """Persist the master password for vault_path in the active backend."""
+    _get_backend(vault_path).set(password)

agent_core_credentials/models.py

@@ -0,0 +1,27 @@
+"""Credential data models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+
+
+@dataclass
+class Credential:
+    """A stored credential with all fields."""
+
+    service: str
+    username: str
+    password: str
+    url: str = ""
+    notes: str = ""
+    mtime: datetime | None = None
+
+
+@dataclass
+class CredentialSummary:
+    """A credential summary without the password."""
+
+    service: str
+    username: str
+    url: str = ""

agent_core_credentials/secrets.py

@@ -0,0 +1,66 @@
+"""secrets.get() — vault-first, env-fallback secret accessor.
+
+Resolution order:
+  1. Vault entry with ``service == name`` — returns ``cred.password``.
+  2. ``os.environ.get(name)`` — env fallback for migration safety.
+  3. Raises ``SecretNotFoundError`` if neither source has the secret.
+
+Vault failures (no vault file, bad password, any pykeepass error) are caught,
+logged at DEBUG, and fall through silently to the env fallback.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+
+log = logging.getLogger(__name__)
+
+
+class SecretNotFoundError(Exception):
+    """Raised when neither the vault nor os.environ contains the named secret."""
+
+
+def _open_store():
+    """Open the credential store against the default vault path.
+
+    Isolated into its own function so tests can monkeypatch it without
+    touching the real vault.
+    """
+    from agent_core_credentials import default_vault_path
+    from agent_core_credentials.store import CredentialStore
+
+    return CredentialStore(default_vault_path())
+
+
+def get(name: str) -> str:
+    """Return the secret named *name*.
+
+    Resolution order:
+    1. Vault entry whose ``service`` field equals *name*.
+    2. ``os.environ[name]`` (migration fallback — works while vault is
+       being populated).
+    3. Raises :exc:`SecretNotFoundError`.
+
+    Any exception thrown while opening or querying the vault is caught
+    and logged at DEBUG so that a missing / locked vault never hard-fails
+    a call that could succeed from the environment.
+    """
+    # --- vault path ---
+    try:
+        store = _open_store()
+        cred = store.get(name)
+        if cred is not None and cred.password:
+            return cred.password
+    except Exception:
+        log.debug("vault lookup failed for %r — falling through to env", name, exc_info=True)
+
+    # --- env fallback ---
+    value = os.environ.get(name)
+    if value:
+        return value
+
+    raise SecretNotFoundError(
+        f"Secret {name!r} not found in vault or environment. "
+        "Populate the vault entry or set the env var before starting."
+    )

agent_core_credentials/store.py

@@ -0,0 +1,134 @@
+"""KeePass credential store — pykeepass wrapper."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pykeepass import PyKeePass, create_database  # type: ignore[import-untyped]
+
+from agent_core_credentials.master_password import get_master_password
+from agent_core_credentials.models import Credential, CredentialSummary
+
+
+class CredentialStore:
+    """CRUD operations on an encrypted KeePass vault.
+
+    Each operation opens the vault, performs the action, and saves/closes.
+    The master password is fetched from the OS keyring or owner-only encrypted
+    file fallback via ``get_master_password()``.
+
+    Args:
+        vault_path: Path to the .kdbx file. Created on first write.
+        _master_password: Optional DI override for the master password (tests).
+    """
+
+    def __init__(self, vault_path: Path, *, _master_password: str | None = None) -> None:
+        """Initialize the store with a path to the vault file."""
+        self.vault_path = vault_path
+        self._password_override = _master_password
+
+    def _get_password(self) -> str:
+        """Return the master password from override DI or the active backend."""
+        if self._password_override is not None:
+            return self._password_override
+        result = get_master_password(self.vault_path)
+        if not result:
+            msg = (
+                "No master password found. Run 'agent-core-creds init' to initialize "
+                "the vault, or ensure the OS keyring is accessible."
+            )
+            raise ValueError(msg)
+        return result
+
+    def _open(self) -> PyKeePass:
+        """Open the existing vault; raise ``FileNotFoundError`` if it's absent.
+
+        Reads and deletes must NOT create a vault — silently creating an empty
+        ``.kdbx`` on a read masks a missing or misconfigured vault (and can
+        shadow the real one). Only the write path may create; see
+        :meth:`_open_or_create`.
+        """
+        # Validate the master-password config first (a config error is more
+        # fundamental), then require the vault to already exist.
+        password = self._get_password()
+        if not self.vault_path.exists():
+            raise FileNotFoundError(
+                f"credentials vault not found at {self.vault_path}; "
+                "set a credential (or run the init command) to create it"
+            )
+        return PyKeePass(str(self.vault_path), password=password)
+
+    def _open_or_create(self) -> PyKeePass:
+        """Open the vault, creating an empty one if it's absent.
+
+        Only the explicit write path (:meth:`set`) may call this — a missing
+        vault on first write is expected.
+        """
+        password = self._get_password()
+        if not self.vault_path.exists():
+            return create_database(str(self.vault_path), password=password)
+        return PyKeePass(str(self.vault_path), password=password)
+
+    def get(self, service: str) -> Credential | None:
+        """Retrieve a credential by service name."""
+        kp = self._open()
+        entry = kp.find_entries(title=service, first=True)
+        if entry is None:
+            return None
+        return Credential(
+            service=entry.title,
+            username=entry.username or "",
+            password=entry.password or "",
+            url=entry.url or "",
+            notes=entry.notes or "",
+            mtime=entry.mtime,
+        )
+
+    def set(
+        self,
+        service: str,
+        username: str,
+        password: str,
+        url: str = "",
+        notes: str = "",
+    ) -> None:
+        """Store or overwrite a credential (creates the vault on first write)."""
+        kp = self._open_or_create()
+        existing = kp.find_entries(title=service, first=True)
+        if existing:
+            existing.username = username
+            existing.password = password
+            existing.url = url
+            existing.notes = notes
+        else:
+            kp.add_entry(
+                kp.root_group,
+                title=service,
+                username=username,
+                password=password,
+                url=url,
+                notes=notes,
+            )
+        kp.save()
+
+    def list(self) -> list[CredentialSummary]:
+        """List all stored credentials without passwords."""
+        kp = self._open()
+        return [
+            CredentialSummary(
+                service=entry.title,
+                username=entry.username or "",
+                url=entry.url or "",
+            )
+            for entry in kp.entries
+        ]
+
+    def delete(self, service: str) -> bool:
+        """Delete a credential by service name."""
+        kp = self._open()
+        entry = kp.find_entries(title=service, first=True)
+        if entry is None:
+            return False
+        kp.delete_entry(entry)
+        kp.save()
+        return True

agent_core_credentials-0.8.2.dist-info/METADATA

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: agent-core-credentials
+Version: 0.8.2
+Summary: KeePass-backed credential vault for agent-core agents
+License-Expression: MIT
+Requires-Python: >=3.12
+Requires-Dist: cryptography>=41.0
+Requires-Dist: keyring>=24.0
+Requires-Dist: pykeepass>=4.1.1.post1
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12

agent_core_credentials-0.8.2.dist-info/RECORD

@@ -0,0 +1,11 @@
+agent_core_credentials/__init__.py,sha256=rBEA_pPjRPkLBfbCWzgQIW3-_brN7Uj2QxyfLwW-MJc,1927
+agent_core_credentials/cli.py,sha256=wEryTVD0R5o14vHgH31ROsN2MPm5gziC_3PQB2ArKyw,4807
+agent_core_credentials/master_password.py,sha256=DbzRFE_XouYUhmvibLckbwOhVIULNIGaawFst0kwr6I,7844
+agent_core_credentials/models.py,sha256=qk3SrE0-zdxIAZKS0ggylLn5k99V75imXn_6_D1Jaig,480
+agent_core_credentials/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agent_core_credentials/secrets.py,sha256=GZJm56k9BcR2ZtPlQr_5_st52b7YzjjBzo9lCn4xME8,2081
+agent_core_credentials/store.py,sha256=XgwiPlyr53F3PzUiSWTpoltc5p4T7cnIccMDyg9-xwI,4834
+agent_core_credentials-0.8.2.dist-info/METADATA,sha256=3CyNeGgTtQFlPgY-aVg_lDyynWlouNfXwbaYAWBg7Xc,331
+agent_core_credentials-0.8.2.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+agent_core_credentials-0.8.2.dist-info/entry_points.txt,sha256=eaSA66yx6RVt8WTmN4OZS3KYCAGuuioUMJlH08a7xpQ,74
+agent_core_credentials-0.8.2.dist-info/RECORD,,

agent_core_credentials-0.8.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agent_core_credentials-0.8.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agent-core-creds = agent_core_credentials.cli:creds_app