locke 0.5.1__tar.gz

locke-0.5.1/.gitignore

@@ -0,0 +1,46 @@
+/hook_outputs/
+**/hook_outputs/
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+*.eggs/
+
+# TypeScript/Node
+node_modules/
+typescript/dist/
+*.tsbuildinfo
+# Yarn Berry (PnP + cache)
+.yarn/
+.pnp.*
+yarn.lock
+
+# Rust
+rust/target/
+*.rs.bk
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment / Secrets
+.env
+.env.*
+!.env.example
+
+# Locke runtime (plaintext config should never be committed)
+.locke/config.json
+
+hook_outputs

locke-0.5.1/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: locke
+Version: 0.5.1
+Summary: Unified credentials framework — encrypted config, OS keystore, Vaultwarden integration
+Project-URL: Homepage, https://gitlab.com/martin-wieser/locke
+Project-URL: Repository, https://gitlab.com/martin-wieser/locke
+Project-URL: Issues, https://gitlab.com/martin-wieser/locke/-/issues
+License: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: <3.15,>=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: cryptography>=42.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: keyring>=25.0
+Requires-Dist: winrt-runtime>=3.0; sys_platform == 'win32'
+Requires-Dist: winrt-windows-foundation>=3.0; sys_platform == 'win32'
+Requires-Dist: winrt-windows-security-credentials-ui>=3.0; sys_platform == 'win32'
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Locke — Python
+
+Unified credentials framework — encrypted config, OS keystore, Vaultwarden integration.
+
+## Install
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Usage
+
+### Library
+
+```python
+import locke
+
+# Load and decrypt config → flat env vars
+env = locke.load_config(".locke/config.encrypted.json")
+# env["MONGO_URI"], env["SENTRY_DSN"], etc.
+
+# Resolve a single credential
+cred = locke.resolve_credential("LOCKE_ENCRYPTION_KEY")
+
+# Get a vault secret
+secret = locke.get_vault_secret("myproject/staging/api_key")
+```
+
+### CLI
+
+```bash
+# Decrypt + flatten → shell exports
+eval $(locke env)
+
+# Decrypt to stdout
+locke decrypt
+
+# Encrypt plaintext config
+locke encrypt
+
+# Manage OS keystore
+locke keystore set LOCKE_ENCRYPTION_KEY --prompt
+locke keystore get LOCKE_ENCRYPTION_KEY
+
+# Get vault secret
+locke vault get myproject/staging/api_key
+
+# Initialize project
+locke init --project myproject --tenant staging
+```
+
+## Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `LOCKE_ENV` | Override environment detection |
+| `LOCKE_ENCRYPTION_KEY` | Encryption key (if not in keystore) |
+| `LOCKE_USE_BIOMETRIC` | Set `false` to disable biometric gating |
+| `LOCKE_VAULT_URL` | Vaultwarden server URL |
+| `LOCKE_VAULT_USERNAME` | Vaultwarden username |
+
+## Testing
+
+```bash
+cd python
+pip install -e ".[dev]"
+pytest
+```

locke-0.5.1/README.md

@@ -0,0 +1,68 @@
+# Locke — Python
+
+Unified credentials framework — encrypted config, OS keystore, Vaultwarden integration.
+
+## Install
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Usage
+
+### Library
+
+```python
+import locke
+
+# Load and decrypt config → flat env vars
+env = locke.load_config(".locke/config.encrypted.json")
+# env["MONGO_URI"], env["SENTRY_DSN"], etc.
+
+# Resolve a single credential
+cred = locke.resolve_credential("LOCKE_ENCRYPTION_KEY")
+
+# Get a vault secret
+secret = locke.get_vault_secret("myproject/staging/api_key")
+```
+
+### CLI
+
+```bash
+# Decrypt + flatten → shell exports
+eval $(locke env)
+
+# Decrypt to stdout
+locke decrypt
+
+# Encrypt plaintext config
+locke encrypt
+
+# Manage OS keystore
+locke keystore set LOCKE_ENCRYPTION_KEY --prompt
+locke keystore get LOCKE_ENCRYPTION_KEY
+
+# Get vault secret
+locke vault get myproject/staging/api_key
+
+# Initialize project
+locke init --project myproject --tenant staging
+```
+
+## Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `LOCKE_ENV` | Override environment detection |
+| `LOCKE_ENCRYPTION_KEY` | Encryption key (if not in keystore) |
+| `LOCKE_USE_BIOMETRIC` | Set `false` to disable biometric gating |
+| `LOCKE_VAULT_URL` | Vaultwarden server URL |
+| `LOCKE_VAULT_USERNAME` | Vaultwarden username |
+
+## Testing
+
+```bash
+cd python
+pip install -e ".[dev]"
+pytest
+```

locke-0.5.1/locke/__init__.py

@@ -0,0 +1,159 @@
+"""Locke — Unified credentials framework."""
+
+import json
+import logging
+import os
+from pathlib import Path
+
+from locke.crypto import decrypt_config, encrypt_config
+from locke.flatten import flatten_config
+from locke.pipeline import resolve_credential
+
+
+def __getattr__(name: str):
+    if name == "get_vault_secret":
+        from locke.vault import get_vault_secret
+        return get_vault_secret
+    if name == "VaultClient":
+        from locke.vault import VaultClient
+        return VaultClient
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+__version__ = "0.5.1"
+__all__ = [
+    "VaultClient",
+    "decrypt_config",
+    "decrypt_config_file",
+    "encrypt_config",
+    "find_config",
+    "flatten_config",
+    "get_vault_secret",
+    "inject_env",
+    "load_config",
+    "read_locke_config",
+    "resolve_credential",
+]
+
+logger = logging.getLogger(__name__)
+
+
+def find_config(
+    project_root: str | Path,
+    env: str | None = None,
+) -> Path | None:
+    """Locate an encrypted config file using standard search order.
+
+    Searches ``project_root``, ``project_root/.locke``, and ``project_root/src``
+    for files matching ``config.encrypted.{env}.json``, then
+    ``config.encrypted.development.json``, then ``config.encrypted.json``.
+
+    Args:
+        project_root: Project root directory.
+        env: Environment name (e.g. ``"production"``).  Falls back to the
+            ``LOCKE_ENV`` env var if not provided.
+
+    Returns:
+        Path to the first matching file, or ``None``.
+    """
+    project_root = Path(project_root)
+    env = env or os.environ.get("LOCKE_ENV", "")
+
+    search_dirs = [project_root, project_root / ".locke", project_root / "src"]
+    for search_dir in search_dirs:
+        if env:
+            p = search_dir / f"config.encrypted.{env}.json"
+            if p.is_file():
+                return p
+        for fallback in ("config.encrypted.development.json", "config.encrypted.json"):
+            p = search_dir / fallback
+            if p.is_file():
+                return p
+    return None
+
+
+def decrypt_config_file(
+    config_path: str | Path,
+    key_name: str,
+) -> dict:
+    """Resolve key via pipeline, decrypt config file, return plaintext dict.
+
+    Args:
+        config_path: Path to config.encrypted.json.
+        key_name: Credential name (e.g. ``MYAPP_CONFIG_ENCRYPTION_KEY``).
+    """
+    config_path = Path(config_path)
+    with open(config_path) as f:
+        encrypted = json.load(f)
+
+    credential = resolve_credential(key_name)
+    return decrypt_config(encrypted, credential.value)
+
+
+def inject_env(
+    config: dict,
+    env_map: dict[tuple[str, ...], str],
+) -> int:
+    """Inject decrypted config values into ``os.environ``.
+
+    Existing env vars are NOT overwritten.
+
+    Args:
+        config: Decrypted nested config dict.
+        env_map: Mapping of ``(section, key)`` tuples to env var names.
+
+    Returns:
+        Number of variables set.
+    """
+    count = 0
+    for path, env_var in env_map.items():
+        value = config
+        for segment in path:
+            if isinstance(value, dict):
+                value = value.get(segment)
+            else:
+                value = None
+                break
+        if value is None or value == "":
+            continue
+        if isinstance(value, list):
+            value = ",".join(str(v) for v in value)
+        elif isinstance(value, bool):
+            value = str(value).lower()
+        else:
+            value = str(value)
+        if os.environ.get(env_var):
+            continue
+        os.environ[env_var] = value
+        count += 1
+    return count
+
+
+def read_locke_config(
+    project_root: str | Path = ".",
+) -> dict | None:
+    """Read the ``.locke/locke.json`` config if it exists.
+
+    Returns the parsed dict, or ``None`` if the file is missing.
+    """
+    locke_json = Path(project_root) / ".locke" / "locke.json"
+    if not locke_json.is_file():
+        return None
+    try:
+        with open(locke_json) as f:
+            return json.load(f)
+    except (json.JSONDecodeError, OSError) as exc:
+        logger.debug("Failed to read %s: %s", locke_json, exc)
+        return None
+
+
+def load_config(
+    config_path: str | Path,
+    key_name: str = "LOCKE_ENCRYPTION_KEY",
+) -> dict[str, str]:
+    """Resolve key, decrypt, and auto-flatten to SCREAMING_SNAKE_CASE.
+
+    For projects that need a custom env mapping, use
+    :func:`decrypt_config_file` + :func:`inject_env` instead.
+    """
+    plaintext = decrypt_config_file(config_path, key_name)
+    return flatten_config(plaintext)

locke-0.5.1/locke/cli/_key_util.py

@@ -0,0 +1,56 @@
+"""Shared key resolution helper for CLI commands."""
+
+import os
+import sys
+
+import click
+
+from locke.pipeline import resolve_credential
+
+
+def get_key(key_source: str, key_name: str | None) -> str:
+    """Resolve an encryption key from the given source.
+
+    Args:
+        key_source: One of "keystore", "env", "prompt".
+        key_name: Credential name (required for keystore/env).
+
+    Returns:
+        The resolved key string.
+    """
+    if key_source == "prompt":
+        return click.prompt("Encryption key", hide_input=True)
+
+    if key_source == "env":
+        if not key_name:
+            click.echo("Error: --key-name required with --key-source=env", err=True)
+            sys.exit(1)
+        key = os.environ.get(key_name)
+        if not key:
+            click.echo(f"Error: {key_name} not set", err=True)
+            sys.exit(1)
+        return key
+
+    # Default: keystore (uses full pipeline: keystore → env → glab → dotenv)
+    if not key_name:
+        click.echo(
+            "Error: --key-name required (e.g. --key-name MYAPP_CONFIG_ENCRYPTION_KEY)",
+            err=True,
+        )
+        sys.exit(1)
+    cred = resolve_credential(key_name)
+    return cred.value
+
+
+KEY_NAME_OPTION = click.option(
+    "--key-name",
+    default=None,
+    help="Credential name for the encryption key (e.g. MYAPP_CONFIG_ENCRYPTION_KEY)",
+)
+
+KEY_SOURCE_OPTION = click.option(
+    "--key-source",
+    type=click.Choice(["keystore", "env", "prompt"]),
+    default="keystore",
+    help="Where to get the encryption key",
+)

locke-0.5.1/locke/cli/bio.py

@@ -0,0 +1,87 @@
+"""CLI commands for biometric session management."""
+
+from __future__ import annotations
+
+import datetime
+import time
+
+import click
+
+
+@click.group()
+def bio() -> None:
+    """Manage biometric session."""
+
+
+@bio.command()
+def logout() -> None:
+    """Invalidate the persistent biometric session.
+
+    After logout, the next keystore access will prompt Windows Hello again.
+    """
+    from locke.keystore import invalidate_bio_session
+
+    if invalidate_bio_session():
+        click.echo("Biometric session invalidated.")
+    else:
+        click.echo("No active biometric session.")
+
+
+@bio.command()
+def status() -> None:
+    """Show biometric session status."""
+    import json as json_mod
+
+    from locke.keystore import (
+        _BIO_SESSION_FILE,
+        _bio_session_ttl,
+        _biometric_enabled,
+        _compute_session_hmac,
+        _get_bio_session_dir,
+        _get_machine_id,
+        _get_username,
+        _read_bio_session,
+        check_windows_hello_available,
+    )
+
+    click.echo("Biometric status:")
+    click.echo(f"  Enabled:          {_biometric_enabled()}")
+    click.echo(f"  Windows Hello:    {check_windows_hello_available()}")
+    click.echo(f"  Session TTL:      {_bio_session_ttl():.0f}s ({_bio_session_ttl() / 86400:.1f} days)")
+
+    session_file = _get_bio_session_dir() / _BIO_SESSION_FILE
+    if not session_file.is_file():
+        click.echo("  Session:          none")
+        return
+
+    try:
+        with open(session_file) as f:
+            data = json_mod.load(f)
+        verified_at = float(data["verified_at"])
+        machine_id = str(data["machine_id"])
+        username = str(data["username"])
+        stored_hmac = str(data["hmac"])
+    except Exception as exc:
+        click.echo(f"  Session:          corrupt ({exc})")
+        return
+
+    ts = datetime.datetime.fromtimestamp(verified_at).strftime("%Y-%m-%d %H:%M:%S")
+    age = time.time() - verified_at
+    remaining = _bio_session_ttl() - age
+
+    machine_ok = machine_id == _get_machine_id()
+    user_ok = username == _get_username()
+    expected_hmac = _compute_session_hmac(verified_at, machine_id, username)
+    hmac_ok = stored_hmac == expected_hmac
+    valid = _read_bio_session()
+
+    click.echo(f"  Verified at:      {ts}")
+    click.echo(f"  Age:              {age:.0f}s ({age / 3600:.1f}h)")
+    if remaining > 0:
+        click.echo(f"  Remaining:        {remaining:.0f}s ({remaining / 3600:.1f}h)")
+    else:
+        click.echo(f"  Remaining:        expired")
+    click.echo(f"  Machine match:    {machine_ok}")
+    click.echo(f"  User match:       {user_ok}")
+    click.echo(f"  HMAC intact:      {hmac_ok}")
+    click.echo(f"  Valid:            {valid}")

locke-0.5.1/locke/cli/config_cmd.py

@@ -0,0 +1,55 @@
+"""locke config — config file discovery and management."""
+
+import sys
+
+import click
+
+
+@click.group()
+def config() -> None:
+    """Config file discovery and management."""
+
+
+@config.command(name="find")
+@click.option(
+    "--env",
+    "env_name",
+    default=None,
+    help="Environment name (e.g. development, staging, production)",
+)
+@click.option(
+    "--project-root",
+    default=".",
+    type=click.Path(exists=True, file_okay=False),
+    help="Project root directory (default: current directory)",
+)
+def config_find(env_name: str | None, project_root: str) -> None:
+    """Find the encrypted config file for an environment.
+
+    Prints the absolute path to stdout for use in shell scripts.
+    Exits with code 1 if no config file is found.
+
+    \b
+    Examples:
+        locke config find
+        locke config find --env production
+        locke config find --env staging --project-root /path/to/project
+
+    \b
+    Shell integration:
+        CONFIG=$(locke config find --env production)
+        docker run -v "$CONFIG:/app/config.encrypted.json:ro" ...
+    """
+    from locke import find_config
+
+    path = find_config(project_root, env=env_name)
+    if path:
+        click.echo(str(path.resolve()))
+    else:
+        env_display = env_name or "any"
+        click.echo(
+            f"Error: no encrypted config found for env={env_display} "
+            f"in {project_root}",
+            err=True,
+        )
+        sys.exit(1)

locke-0.5.1/locke/cli/decrypt.py

@@ -0,0 +1,111 @@
+"""locke decrypt — decrypt an encrypted config file."""
+
+import json
+import sys
+from pathlib import Path
+
+import click
+
+from locke.crypto import decrypt_config
+from locke.cli._key_util import get_key
+
+
+@click.command()
+@click.argument("config_path", required=False, default=None)
+@click.option(
+    "--config",
+    "config_opt",
+    default=None,
+    help="Path to encrypted config file (alternative to positional arg)",
+)
+@click.option(
+    "--output", "-o",
+    "output_path",
+    default=None,
+    help="Output file path (default: stdout)",
+)
+@click.option("--key-name", default=None, help="Credential name for the encryption key")
+@click.option(
+    "--key-source",
+    type=click.Choice(["keystore", "env", "prompt"]),
+    default="keystore",
+    help="Where to get the encryption key",
+)
+@click.option(
+    "--env",
+    "env_name",
+    default=None,
+    help="Environment name for auto-discovery (e.g. development, staging, production)",
+)
+@click.option(
+    "--project-root",
+    default=".",
+    help="Project root for auto-discovery (default: current directory)",
+)
+def decrypt(
+    config_path: str | None,
+    config_opt: str | None,
+    output_path: str | None,
+    key_name: str | None,
+    key_source: str,
+    env_name: str | None,
+    project_root: str,
+) -> None:
+    """Decrypt an encrypted config file.
+
+    \b
+    Examples:
+        locke decrypt config.encrypted.development.json --key-name MYAPP_CONFIG_ENCRYPTION_KEY
+        locke decrypt --env production --key-name MYAPP_CONFIG_ENCRYPTION_KEY
+        locke decrypt --key-name MYAPP_CONFIG_ENCRYPTION_KEY   # auto-discovers config
+    """
+    # Resolve input path: positional arg > --config > auto-discover
+    path_str = config_path or config_opt
+    if not path_str:
+        from locke import find_config
+        found = find_config(project_root, env=env_name)
+        if found:
+            path_str = str(found)
+            click.echo(f"Auto-discovered: {path_str}", err=True)
+        else:
+            click.echo(
+                "Error: no encrypted config file found. "
+                "Provide a path or use --env / --project-root.",
+                err=True,
+            )
+            sys.exit(1)
+
+    try:
+        with open(path_str) as f:
+            encrypted = json.load(f)
+    except FileNotFoundError:
+        click.echo(f"Error: File not found: {path_str}", err=True)
+        sys.exit(1)
+    except json.JSONDecodeError:
+        click.echo(f"Error: Invalid JSON in {path_str}", err=True)
+        sys.exit(1)
+
+    # Auto-resolve key_name from .locke/locke.json if not provided
+    if not key_name:
+        from locke import read_locke_config
+        locke_cfg = read_locke_config(project_root)
+        if locke_cfg and locke_cfg.get("keyName"):
+            key_name = locke_cfg["keyName"]
+            click.echo(f"Using key name from .locke/locke.json: {key_name}", err=True)
+
+    try:
+        key = get_key(key_source, key_name)
+        plaintext = decrypt_config(encrypted, key)
+    except Exception as exc:
+        click.echo(f"Error: {exc}", err=True)
+        sys.exit(1)
+
+    output = json.dumps(plaintext, indent=2, sort_keys=True)
+
+    if output_path:
+        with open(output_path, "w") as f:
+            f.write(output)
+            f.write("\n")
+        click.echo(f"Decrypted config written to {output_path}", err=True)
+    else:
+        click.echo(output)