keystash 0.1.0__py3-none-any.whl

keystash/__init__.py

@@ -0,0 +1,3 @@
+"""keystash — local-first encrypted vault for API keys, tokens and passwords."""
+
+__version__ = "0.1.0"

keystash/__main__.py

@@ -0,0 +1,6 @@
+"""Allow `python -m keystash`."""
+
+from .cli import cli
+
+if __name__ == "__main__":
+    cli()

keystash/cli.py

@@ -0,0 +1,602 @@
+"""keystash command-line interface."""
+
+from __future__ import annotations
+
+import getpass
+import json
+import os
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import List, Optional
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from . import __version__, clipboard
+from .gen import generate
+from .model import Entry, parse_expires
+from .search import search as fuzzy_search
+from .vault import (
+    BAD_PASSWORD,
+    Vault,
+    VaultError,
+)
+
+app = typer.Typer(
+    name="keystash",
+    help="Local-first encrypted vault for API keys, tokens and passwords.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+console = Console()
+err_console = Console(stderr=True)
+
+CONTEXT_SETTINGS = {"help_option_names": ["-h", "--help"]}
+
+
+class State:
+    vault_path: Optional[Path] = None
+
+
+state = State()
+
+
+def version_callback(value: bool) -> None:
+    if value:
+        console.print(f"keystash {__version__}")
+        raise typer.Exit()
+
+
+@app.callback(context_settings=CONTEXT_SETTINGS)
+def main(
+    vault: Optional[Path] = typer.Option(
+        None,
+        "--vault",
+        "-V",
+        help="Path to the vault file (default: $KEYSTASH_VAULT or ~/.keystash/vault.json).",
+        envvar="KEYSTASH_VAULT",
+    ),
+    version: bool = typer.Option(
+        False, "--version", callback=version_callback, is_eager=True
+    ),
+) -> None:
+    state.vault_path = vault
+
+
+# ---------------------------------------------------------------- helpers
+
+
+def resolve_vault() -> Vault:
+    return Vault(state.vault_path)
+
+
+def ask_password() -> str:
+    password = os.environ.get("KEYSTASH_PASSWORD")
+    if password is not None:
+        return password
+    try:
+        return getpass.getpass("Master password: ")
+    except (EOFError, KeyboardInterrupt):
+        raise typer.Exit(1) from None
+
+
+def fail(message: str, code: int = 1) -> "typer.Exit":
+    err_console.print(f"[red]error:[/red] {message}")
+    return typer.Exit(code)
+
+
+def load_vault() -> Vault:
+    vault = resolve_vault()
+    try:
+        vault.load(ask_password())
+    except VaultError as e:
+        if e.code == BAD_PASSWORD:
+            raise fail(str(e)) from None
+        raise fail(str(e)) from None
+    return vault
+
+
+def _mask(secret: str) -> str:
+    if len(secret) <= 8:
+        return "•" * len(secret)
+    return secret[:4] + "•" * (len(secret) - 8) + secret[-4:]
+
+
+def _shell_quote(value: str) -> str:
+    return "'" + value.replace("'", "'\\''") + "'"
+
+
+def _expiry_markup(entry: Entry) -> str:
+    if entry.expires_at is None:
+        return "[dim]—[/dim]"
+    left = entry.days_left() or 0
+    if entry.is_expired():
+        return f"[red]{entry.expires_at} (expired)[/red]"
+    if left <= 7:
+        return f"[yellow]{entry.expires_at} ({left}d)[/yellow]"
+    return str(entry.expires_at)
+
+
+def _parse_tags(raw: Optional[str]) -> List[str]:
+    if not raw:
+        return []
+    return [t.strip() for t in raw.split(",") if t.strip()]
+
+
+def _confirm(message: str) -> bool:
+    return typer.confirm(message, default=False)
+
+
+# ---------------------------------------------------------------- commands
+
+
+@app.command()
+def init() -> None:
+    """Create a new vault with a master password."""
+    vault = resolve_vault()
+    if vault.exists():
+        raise fail(f"Vault already exists at {vault.path}")
+    if os.environ.get("KEYSTASH_PASSWORD"):
+        password = os.environ["KEYSTASH_PASSWORD"]
+    else:
+        password = getpass.getpass("Set master password: ")
+        confirm = getpass.getpass("Confirm master password: ")
+        if password != confirm:
+            raise fail("Passwords do not match.")
+    if not password:
+        raise fail("Master password cannot be empty.")
+    vault.create(password)
+    console.print(f"[green]Vault created at {vault.path}[/green]")
+    console.print(
+        "Tip: point [bold]KEYSTASH_VAULT[/bold] at a cloud-synced folder "
+        "(iCloud/SeaDrive/Dropbox) to keep multiple machines in sync — the file "
+        "is encrypted, so syncing it is safe."
+    )
+
+
+@app.command()
+def add(
+    name: str = typer.Argument(..., help="Entry name, e.g. openai-prod."),
+    secret: Optional[str] = typer.Option(
+        None, "--secret", "-s", help="The secret value (will prompt if omitted)."
+    ),
+    generate_len: Optional[int] = typer.Option(
+        None, "--generate", "-g", help="Generate a random secret of this length instead."
+    ),
+    username: Optional[str] = typer.Option(None, "--username", "-u"),
+    url: Optional[str] = typer.Option(None, "--url"),
+    tags: Optional[str] = typer.Option(None, "--tags", "-t", help="Comma-separated tags."),
+    notes: Optional[str] = typer.Option(None, "--notes", "-n"),
+    env_var: Optional[str] = typer.Option(
+        None, "--env-var", "-e", help="Env var name used by `run` and `env`."
+    ),
+    expires: Optional[str] = typer.Option(
+        None, "--expires", help="Expiry date, YYYY-MM-DD."
+    ),
+    force: bool = typer.Option(False, "--force", "-f", help="Overwrite existing entry."),
+) -> None:
+    """Add a new entry."""
+    if expires:
+        try:
+            parse_expires(expires)
+        except ValueError:
+            raise fail("--expires must be YYYY-MM-DD") from None
+    vault = load_vault()
+    if secret is None and generate_len is None:
+        secret = getpass.getpass(f"Secret for '{name}': ")
+    if generate_len is not None:
+        try:
+            secret = generate(generate_len)
+        except ValueError as e:
+            raise fail(str(e)) from None
+    if not secret:
+        raise fail("Secret cannot be empty.")
+    entry = Entry(
+        name=name,
+        secret=secret,
+        username=username or "",
+        url=url or "",
+        tags=_parse_tags(tags),
+        notes=notes or "",
+        env_var=env_var or "",
+        expires_at=parse_expires(expires),
+    )
+    try:
+        vault.add(entry, overwrite=force)
+    except VaultError as e:
+        raise fail(str(e)) from None
+    vault.save(ask_password())
+    console.print(f"[green]Added[/green] {name} [dim]→ env {entry.default_env_var}[/dim]")
+
+
+@app.command()
+def get(
+    name: str = typer.Argument(...),
+    copy: bool = typer.Option(False, "--copy", "-c", help="Copy to clipboard instead of printing."),
+    reveal: bool = typer.Option(False, "--reveal", "-r", help="Show the full secret."),
+    quiet: bool = typer.Option(False, "--quiet", "-q", help="Print only the raw secret (for scripting)."),
+) -> None:
+    """Show / copy an entry's secret."""
+    vault = load_vault()
+    try:
+        entry = vault.get(name)
+    except VaultError as e:
+        raise fail(str(e), code=3) from None
+    if entry.is_expired() and not quiet:
+        console.print(
+            f"[yellow]warning:[/yellow] '{entry.name}' expired on {entry.expires_at}",
+            style="dim",
+        )
+    if copy:
+        if clipboard.copy(entry.secret):
+            console.print(
+                f"[green]Copied '{entry.name}' to clipboard[/green] "
+                f"[dim](auto-clears in {clipboard.CLEAR_AFTER_SECONDS}s)[/dim]"
+            )
+        else:
+            raise fail("No clipboard helper found (pbcopy/wl-copy/xclip/clip).")
+        return
+    if quiet:
+        typer.echo(entry.secret)
+        return
+    shown = entry.secret if reveal else _mask(entry.secret)
+    body = (
+        f"[bold]secret:[/bold] {shown}\n"
+        f"[bold]env:[/bold] {entry.default_env_var}\n"
+        f"[bold]username:[/bold] {entry.username or '—'}\n"
+        f"[bold]url:[/bold] {entry.url or '—'}\n"
+        f"[bold]tags:[/bold] {', '.join(entry.tags) or '—'}\n"
+        f"[bold]expires:[/bold] {entry.expires_at or '—'}\n"
+        f"[bold]notes:[/bold] {entry.notes or '—'}"
+    )
+    console.print(Panel(body, title=entry.name, subtitle=f"updated {entry.updated_at:%Y-%m-%d}"))
+    if not reveal:
+        console.print("[dim]Use --reveal to show, --copy to copy.[/dim]")
+
+
+@app.command("ls")
+def list_entries(
+    query: Optional[str] = typer.Argument(None, help="Fuzzy search pattern."),
+    tag: Optional[str] = typer.Option(None, "--tag", help="Filter by tag."),
+    json_out: bool = typer.Option(False, "--json", help="Machine-readable output."),
+) -> None:
+    """List entries, optionally fuzzy-searching."""
+    vault = load_vault()
+    entries = fuzzy_search(vault.entries, query or "")
+    if tag:
+        entries = [e for e in entries if tag in e.tags]
+    if json_out:
+        typer.echo(
+            json.dumps(
+                [
+                    {
+                        "name": e.name,
+                        "env_var": e.default_env_var,
+                        "tags": e.tags,
+                        "expires_at": e.expires_at.isoformat() if e.expires_at else None,
+                        "expired": e.is_expired(),
+                    }
+                    for e in entries
+                ],
+                indent=2,
+            )
+        )
+        return
+    if not entries:
+        console.print("[dim]No matching entries.[/dim]")
+        return
+    table = Table(title=f"{vault.path} · {len(entries)} entry(ies)")
+    table.add_column("Name", style="cyan")
+    table.add_column("Env var", style="green")
+    table.add_column("Tags")
+    table.add_column("Expires")
+    table.add_column("Updated", style="dim")
+    for e in entries:
+        table.add_row(
+            e.name,
+            e.default_env_var,
+            ", ".join(e.tags),
+            _expiry_markup(e),
+            f"{e.updated_at:%Y-%m-%d}",
+        )
+    console.print(table)
+
+
+@app.command()
+def rm(
+    name: str = typer.Argument(...),
+    force: bool = typer.Option(False, "--force", "-f", help="Skip confirmation."),
+) -> None:
+    """Delete an entry."""
+    vault = load_vault()
+    try:
+        vault.get(name)
+    except VaultError as e:
+        raise fail(str(e), code=3) from None
+    if not force and not _confirm(f"Delete '{name}' permanently?"):
+        raise typer.Abort()
+    vault.remove(name)
+    vault.save(ask_password())
+    console.print(f"[green]Deleted[/green] {name}")
+
+
+@app.command()
+def edit(
+    name: str = typer.Argument(...),
+    secret: Optional[str] = typer.Option(None, "--secret", "-s", help="Replace the secret."),
+    username: Optional[str] = typer.Option(None, "--username", "-u"),
+    url: Optional[str] = typer.Option(None, "--url"),
+    tags: Optional[str] = typer.Option(None, "--tags", "-t"),
+    notes: Optional[str] = typer.Option(None, "--notes", "-n"),
+    env_var: Optional[str] = typer.Option(None, "--env-var", "-e"),
+    expires: Optional[str] = typer.Option(None, "--expires"),
+    clear_expires: bool = typer.Option(False, "--clear-expires"),
+) -> None:
+    """Update fields of an existing entry (only provided fields change)."""
+    if expires:
+        try:
+            parse_expires(expires)
+        except ValueError:
+            raise fail("--expires must be YYYY-MM-DD") from None
+    vault = load_vault()
+    try:
+        entry = vault.get(name)
+    except VaultError as e:
+        raise fail(str(e), code=3) from None
+    changes = {}
+    if secret is not None:
+        changes["secret"] = secret
+    if username is not None:
+        changes["username"] = username
+    if url is not None:
+        changes["url"] = url
+    if tags is not None:
+        changes["tags"] = _parse_tags(tags)
+    if notes is not None:
+        changes["notes"] = notes
+    if env_var is not None:
+        changes["env_var"] = env_var
+    if clear_expires:
+        changes["expires_at"] = None
+    elif expires is not None:
+        changes["expires_at"] = parse_expires(expires)
+    if not changes:
+        raise fail("Nothing to change — pass at least one field option.")
+    vault.add(entry.with_updates(**changes), overwrite=True)
+    vault.save(ask_password())
+    console.print(f"[green]Updated[/green] {name}")
+
+
+@app.command()
+def gen(
+    length: int = typer.Argument(24, min=8, help="Secret length."),
+    no_symbols: bool = typer.Option(False, "--no-symbols", help="Alphanumeric only."),
+    save_name: Optional[str] = typer.Option(
+        None, "--save", help="Save the generated secret as a new entry with this name."
+    ),
+    tags: Optional[str] = typer.Option(None, "--tags", "-t"),
+    expires: Optional[str] = typer.Option(None, "--expires"),
+) -> None:
+    """Generate a strong random secret (optionally save it)."""
+    try:
+        value = generate(length, symbols=not no_symbols)
+    except ValueError as e:
+        raise fail(str(e)) from None
+    if not save_name:
+        typer.echo(value)
+        return
+    vault = load_vault()
+    entry = Entry(
+        name=save_name,
+        secret=value,
+        tags=_parse_tags(tags),
+        expires_at=parse_expires(expires),
+    )
+    try:
+        vault.add(entry, overwrite=False)
+    except VaultError as e:
+        raise fail(str(e)) from None
+    vault.save(ask_password())
+    console.print(f"[green]Generated & saved[/green] {save_name} ({length} chars)")
+
+
+def _select_entries(vault: Vault, names: List[str], tag: Optional[str]) -> List[Entry]:
+    if names:
+        missing = [n for n in names if n not in vault.entries]
+        if missing:
+            raise fail(f"No such entr{'y' if len(missing) == 1 else 'ies'}: {', '.join(missing)}", code=3)
+        return [vault.entries[n] for n in names]
+    if tag:
+        selected = [e for e in vault.entries.values() if tag in e.tags]
+        if not selected:
+            raise fail(f"No entries tagged '{tag}'.", code=3)
+        return selected
+    raise fail("Specify entry names or --tag.")
+
+
+@app.command()
+def env(
+    names: List[str] = typer.Argument(None, help="Entry names."),
+    tag: Optional[str] = typer.Option(None, "--tag", help="All entries with this tag."),
+) -> None:
+    """Print `export` lines so you can run: eval "$(keystash env openai)". """
+    vault = load_vault()
+    for entry in _select_entries(vault, list(names or []), tag):
+        typer.echo(f"export {entry.default_env_var}={_shell_quote(entry.secret)}")
+
+
+@app.command(context_settings={"allow_extra_args": True, "ignore_unknown_options": True})
+def run(
+    ctx: typer.Context,
+    name: List[str] = typer.Option(
+        None, "--name", "-n", help="Entry to inject (repeatable)."
+    ),
+    tag: Optional[str] = typer.Option(None, "--tag", "-t", help="Inject all entries with this tag."),
+    quiet: bool = typer.Option(True, "--quiet/--no-quiet", help="Hide which vars are injected."),
+) -> None:
+    """Run a command with selected secrets injected as env vars.
+
+    Everything after `--` is the command to run:
+
+        keystash run -n openai -n anthropic -- python train.py
+        keystash run --tag llm -- python train.py
+    """
+    cmd = list(ctx.args)
+    if cmd and cmd[0] == "--":  # defensive: some click versions keep the separator
+        cmd = cmd[1:]
+    if not cmd:
+        raise fail("Usage: keystash run [-n NAME]... [--tag TAG] -- COMMAND [ARGS...]")
+    vault = load_vault()
+    selected = _select_entries(vault, name, tag)
+    environ = dict(os.environ)
+    for entry in selected:
+        environ[entry.default_env_var] = entry.secret
+        if not quiet:
+            console.print(f"[dim]+ {entry.default_env_var}[/dim]")
+    try:
+        completed = subprocess.run(cmd, env=environ, check=False)
+    except FileNotFoundError:
+        raise fail(f"Command not found: {cmd[0]}") from None
+    raise typer.Exit(completed.returncode)
+
+
+@app.command("import")
+def import_entries(
+    file: Path = typer.Argument(..., exists=True, readable=True, help=".env or JSON file."),
+    prefix: str = typer.Option("", "--prefix", help="Strip this prefix from names."),
+    tags: Optional[str] = typer.Option("imported", "--tags", "-t"),
+    force: bool = typer.Option(False, "--force", "-f"),
+) -> None:
+    """Bulk-import entries from a .env or JSON file (and delete the source file's risk)."""
+    text = file.read_text(encoding="utf-8")
+    pairs: List[tuple[str, str]] = []
+    if file.suffix == ".json":
+        try:
+            data = json.loads(text)
+        except json.JSONDecodeError:
+            raise fail("Invalid JSON file.") from None
+        items = data.items() if isinstance(data, dict) else None
+        if items is None:
+            raise fail("JSON must be an object mapping name → secret.")
+        for k, v in items:
+            if isinstance(v, dict) and "secret" in v:
+                pairs.append((str(k), str(v["secret"])))
+            else:
+                pairs.append((str(k), str(v)))
+    else:
+        for line in text.splitlines():
+            line = line.strip()
+            if not line or line.startswith("#") or "=" not in line:
+                continue
+            key, _, value = line.partition("=")
+            value = value.strip().strip("'\"")
+            pairs.append((key.strip(), value))
+    if prefix:
+        pairs = [(k[len(prefix):] if k.startswith(prefix) else k, v) for k, v in pairs]
+    vault = load_vault()
+    now = datetime.now(timezone.utc)
+    count = 0
+    for name, secret in pairs:
+        if not name or not secret:
+            continue
+        entry = Entry(
+            name=name,
+            secret=secret,
+            tags=_parse_tags(tags),
+            created_at=now,
+            updated_at=now,
+        )
+        vault.add(entry, overwrite=force)
+        count += 1
+    vault.save(ask_password())
+    console.print(f"[green]Imported {count} entr{'y' if count == 1 else 'ies'}[/green]")
+    console.print(
+        "[yellow]Remember to delete the plaintext source file and remove it from any git history.[/yellow]"
+    )
+
+
+@app.command()
+def export(
+    out: Optional[Path] = typer.Option(None, "--out", "-o", help="Write to file instead of stdout."),
+    format: str = typer.Option("json", "--format", "-f", help="json or dotenv."),
+    include_secrets: bool = typer.Option(False, "--with-secrets", help="Include secret values."),
+) -> None:
+    """Export entries (metadata by default, secrets only with --with-secrets)."""
+    if format not in ("json", "dotenv"):
+        raise fail("--format must be json or dotenv.")
+    vault = load_vault()
+    entries = sorted(vault.entries.values(), key=lambda e: e.name)
+    if format == "dotenv":
+        lines = []
+        for e in entries:
+            if include_secrets:
+                lines.append(f"{e.default_env_var}={e.secret}")
+            else:
+                lines.append(f"{e.default_env_var}=")
+        payload = "\n".join(lines) + "\n"
+    else:
+        payload = json.dumps(
+            {
+                e.name: {
+                    **{k: v for k, v in e.to_dict().items() if k != "secret"},
+                    "secret": e.secret if include_secrets else None,
+                }
+                for e in entries
+            },
+            indent=2,
+        )
+    if out:
+        out.write_text(payload, encoding="utf-8")
+        console.print(f"[green]Exported {len(entries)} entries to {out}[/green]")
+    else:
+        typer.echo(payload, nl=False)
+
+
+@app.command()
+def status() -> None:
+    """Show vault status and expiring entries."""
+    vault = resolve_vault()
+    if not vault.exists():
+        raise fail(f"No vault at {vault.path} — run `keystash init` first.", code=3)
+    console.print(f"[bold]Vault:[/bold] {vault.path}")
+    vault.load(ask_password())
+    total = len(vault.entries)
+    expired = [e for e in vault.entries.values() if e.is_expired()]
+    soon = [
+        e
+        for e in vault.entries.values()
+        if not e.is_expired() and e.days_left() is not None and (e.days_left() or 0) <= 7
+    ]
+    console.print(f"[bold]Entries:[/bold] {total}")
+    if expired:
+        console.print(
+            Panel(
+                "\n".join(f"• {e.name} — expired {e.expires_at}" for e in expired),
+                title="[red]Expired[/red]",
+            )
+        )
+    if soon:
+        console.print(
+            Panel(
+                "\n".join(f"• {e.name} — {e.days_left()}d left" for e in soon),
+                title="[yellow]Expiring within 7 days[/yellow]",
+            )
+        )
+    if not expired and not soon:
+        console.print("[green]No expired or expiring entries.[/green]")
+
+
+def cli() -> None:
+    try:
+        app()
+    except VaultError as e:  # defensive: surface as friendly error
+        err_console.print(f"[red]error:[/red] {e}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    cli()

keystash/clipboard.py

@@ -0,0 +1,65 @@
+"""Clipboard copy with best-effort delayed clear.
+
+The delayed clear runs in a detached child process so it survives this CLI's
+exit. Best-effort by design: if no clipboard helper is found, copy still
+succeeds and we simply skip the auto-clear.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+
+CLEAR_AFTER_SECONDS = 30
+
+
+def _copy_cmd() -> list[str] | None:
+    if sys.platform == "darwin":
+        if shutil.which("pbcopy"):
+            return ["pbcopy"]
+        return None
+    if sys.platform == "win32":
+        if shutil.which("clip"):
+            return ["clip"]
+        return None
+    for candidate in ("wl-copy", "xclip", "xsel"):
+        if shutil.which(candidate):
+            return [candidate]
+    return None
+
+
+def _clear_cmd(seconds: int) -> list[str] | None:
+    if sys.platform == "darwin" and shutil.which("pbcopy"):
+        return ["bash", "-c", f'sleep {seconds}; printf "" | pbcopy']
+    if sys.platform == "win32" and shutil.which("clip"):
+        return ["cmd", "/c", f"timeout /t {seconds} >nul & cls & echo off | clip"]
+    for wl, xs in (("wl-copy", "wl-copy"), ("xclip", "xclip"), ("xsel", "xsel")):
+        if shutil.which(wl):
+            if xs == "xclip":
+                return ["bash", "-c", f'sleep {seconds}; printf "" | xclip -selection clipboard']
+            if xs == "xsel":
+                return ["bash", "-c", f'sleep {seconds}; printf "" | xsel --clipboard --input']
+            return ["bash", "-c", f'sleep {seconds}; printf "" | wl-copy']
+    return None
+
+
+def copy(text: str, *, auto_clear_after: int = CLEAR_AFTER_SECONDS) -> bool:
+    cmd = _copy_cmd()
+    if cmd is None:
+        return False
+    subprocess.run(cmd, input=text.encode("utf-8"), check=True)
+    if auto_clear_after > 0:
+        clear = _clear_cmd(auto_clear_after)
+        if clear:
+            try:
+                subprocess.Popen(
+                    clear,
+                    stdin=subprocess.DEVNULL,
+                    stdout=subprocess.DEVNULL,
+                    stderr=subprocess.DEVNULL,
+                    start_new_session=True,
+                )
+            except OSError:
+                pass
+    return True

keystash/gen.py

@@ -0,0 +1,33 @@
+"""Random secret generation backed by the `secrets` module."""
+
+from __future__ import annotations
+
+import secrets
+import string
+
+AMBIGUOUS = set("Il1O0o|`'\";:,.")
+
+
+def generate(
+    length: int = 24,
+    *,
+    symbols: bool = True,
+    no_ambiguous: bool = True,
+) -> str:
+    if length < 8:
+        raise ValueError("length must be at least 8")
+    pools = [string.ascii_lowercase, string.ascii_uppercase, string.digits]
+    if symbols:
+        pools.append("!@#$%^&*()-_=+[]{}<>?")
+    if no_ambiguous:
+        pools = ["".join(c for c in pool if c not in AMBIGUOUS) for pool in pools]
+    alphabet = "".join(pools)
+    # Guarantee at least one char from every class, then fill randomly.
+    chars = [secrets.choice(pool) for pool in pools]
+    chars += [secrets.choice(alphabet) for _ in range(length - len(chars))]
+    secrets.SystemRandom().shuffle(chars)
+    return "".join(chars)
+
+
+def token_hex_compat(nbytes: int = 32) -> str:
+    return secrets.token_hex(nbytes)

keystash/model.py

@@ -0,0 +1,81 @@
+"""Entry model: one stored secret with metadata."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field, replace
+from datetime import date, datetime, timezone
+from typing import Any, Optional
+
+ENTRY_VERSION = 1
+
+
+def parse_expires(value: Optional[str]) -> Optional[date]:
+    """Parse a user-supplied expiry as YYYY-MM-DD. Returns None for empty input."""
+    if not value:
+        return None
+    return date.fromisoformat(value.strip())
+
+
+@dataclass
+class Entry:
+    name: str
+    secret: str
+    username: str = ""
+    url: str = ""
+    tags: list[str] = field(default_factory=list)
+    notes: str = ""
+    env_var: str = ""
+    expires_at: Optional[date] = None
+    created_at: datetime = field(
+        default_factory=lambda: datetime.now(timezone.utc)
+    )
+    updated_at: datetime = field(
+        default_factory=lambda: datetime.now(timezone.utc)
+    )
+
+    @property
+    def default_env_var(self) -> str:
+        if self.env_var:
+            return self.env_var
+        cleaned = re.sub(r"[^A-Za-z0-9]+", "_", self.name).strip("_").upper()
+        return cleaned or "KEYSTASH_ENTRY"
+
+    def is_expired(self, today: Optional[date] = None) -> bool:
+        if self.expires_at is None:
+            return False
+        return self.expires_at <= (today or date.today())
+
+    def days_left(self, today: Optional[date] = None) -> Optional[int]:
+        if self.expires_at is None:
+            return None
+        return (self.expires_at - (today or date.today())).days
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "version": ENTRY_VERSION,
+            "name": self.name,
+            "secret": self.secret,
+            "username": self.username,
+            "url": self.url,
+            "tags": list(self.tags),
+            "notes": self.notes,
+            "env_var": self.env_var,
+            "expires_at": self.expires_at.isoformat() if self.expires_at else None,
+            "created_at": self.created_at.isoformat(),
+            "updated_at": self.updated_at.isoformat(),
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Entry":
+        known = {f for f in cls.__dataclass_fields__}  # noqa: C416
+        payload = {k: v for k, v in data.items() if k in known and k != "version"}
+        payload["expires_at"] = parse_expires(payload.get("expires_at"))
+        payload["created_at"] = datetime.fromisoformat(payload["created_at"])
+        payload["updated_at"] = datetime.fromisoformat(payload["updated_at"])
+        payload["tags"] = [str(t) for t in payload.get("tags") or []]
+        return cls(**payload)
+
+    def with_updates(self, **changes: Any) -> "Entry":
+        changes["updated_at"] = datetime.now(timezone.utc)
+        return replace(self, **changes)

keystash/search.py

@@ -0,0 +1,47 @@
+"""Dependency-free fuzzy scoring used by `ls` and selection prompts."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from .model import Entry
+
+
+def _is_subsequence(needle: str, haystack: str) -> bool:
+    it = iter(haystack)
+    return all(ch in it for ch in needle)
+
+
+def score_entry(query: str, entry: Entry) -> Optional[int]:
+    """Return a relevance score, or None when the entry does not match at all."""
+    q = query.strip().lower()
+    if not q:
+        return 0
+    name = entry.name.lower()
+    if name == q:
+        return 100
+    if name.startswith(q):
+        return 90
+    if q in name:
+        return 80
+    for tag in entry.tags:
+        if tag.lower() == q:
+            return 75
+        if q in tag.lower():
+            return 70
+    for text in (entry.username, entry.url, entry.notes, entry.default_env_var):
+        if text and q in text.lower():
+            return 50
+    if _is_subsequence(q, name):
+        return 60
+    return None
+
+
+def search(entries: dict, query: str) -> list[Entry]:
+    scored = []
+    for entry in entries.values():
+        s = score_entry(query, entry)
+        if s is not None:
+            scored.append((s, entry.name.lower(), entry))
+    scored.sort(key=lambda t: (-t[0], t[1]))
+    return [entry for _, _, entry in scored]

keystash/vault.py

@@ -0,0 +1,143 @@
+"""Encrypted vault storage.
+
+On-disk format (single JSON file, safe to sync through any cloud drive):
+
+    {
+      "version": 1,
+      "kdf": {"name": "PBKDF2-HMAC-SHA256", "salt": "<hex>", "iterations": 600000},
+      "cipher": "Fernet",
+      "payload": "<fernet token>"
+    }
+
+The Fernet token encrypts a JSON document ``{"entries": {name: entry_dict}}``.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import stat
+from pathlib import Path
+from typing import Dict, Optional
+
+from cryptography.fernet import Fernet, InvalidToken
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
+
+from .model import Entry
+
+VAULT_VERSION = 1
+DEFAULT_ITERATIONS = 600_000
+DEFAULT_VAULT_PATH = Path(os.environ.get("KEYSTASH_VAULT", "~/.keystash/vault.json"))
+
+VAULT_EXISTS = "vault_exists"
+BAD_PASSWORD = "bad_password"
+NOT_FOUND = "not_found"
+
+
+class VaultError(Exception):
+    """Raised with a machine-readable ``code`` and a human message."""
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+def derive_key(password: str, salt: bytes, iterations: int) -> bytes:
+    kdf = PBKDF2HMAC(
+        algorithm=hashes.SHA256(), length=32, salt=salt, iterations=iterations
+    )
+    return base64.urlsafe_b64encode(kdf.derive(password.encode("utf-8")))
+
+
+class Vault:
+    def __init__(self, path: Optional[os.PathLike | str] = None) -> None:
+        self.path = Path(path or DEFAULT_VAULT_PATH).expanduser()
+        self.entries: Dict[str, Entry] = {}
+        self.iterations = DEFAULT_ITERATIONS
+
+    # -- lifecycle ---------------------------------------------------------
+
+    def exists(self) -> bool:
+        return self.path.exists()
+
+    def create(self, password: str) -> None:
+        if self.exists():
+            raise VaultError(VAULT_EXISTS, f"Vault already exists at {self.path}")
+        self._write(password, {})
+
+    def load(self, password: str) -> None:
+        raw = self._read_file()
+        salt = bytes.fromhex(raw["kdf"]["salt"])
+        self.iterations = int(raw["kdf"].get("iterations", DEFAULT_ITERATIONS))
+        key = derive_key(password, salt, self.iterations)
+        try:
+            plaintext = Fernet(key).decrypt(raw["payload"].encode("ascii"))
+        except InvalidToken:
+            raise VaultError(BAD_PASSWORD, "Wrong master password.") from None
+        data = json.loads(plaintext.decode("utf-8"))
+        self.entries = {
+            name: Entry.from_dict(d) for name, d in data.get("entries", {}).items()
+        }
+
+    def save(self, password: str) -> None:
+        if not self.exists():
+            raise VaultError(NOT_FOUND, "Vault not initialized — run `keystash init` first.")
+        self._write(password, self.entries)
+
+    # -- entry operations --------------------------------------------------
+
+    def add(self, entry: Entry, *, overwrite: bool = False) -> None:
+        if entry.name in self.entries and not overwrite:
+            raise VaultError(
+                VAULT_EXISTS, f"Entry '{entry.name}' already exists (use --force to overwrite)."
+            )
+        self.entries[entry.name] = entry
+
+    def get(self, name: str) -> Entry:
+        if name not in self.entries:
+            raise VaultError(NOT_FOUND, f"No entry named '{name}'.")
+        return self.entries[name]
+
+    def remove(self, name: str) -> Entry:
+        entry = self.get(name)
+        del self.entries[name]
+        return entry
+
+    # -- internals -----------------------------------------------------------
+
+    def _write(self, password: str, entries: Dict[str, Entry]) -> None:
+        salt = os.urandom(16)
+        key = derive_key(password, salt, DEFAULT_ITERATIONS)
+        payload = json.dumps(
+            {"entries": {name: e.to_dict() for name, e in entries.items()}}
+        ).encode("utf-8")
+        doc = {
+            "version": VAULT_VERSION,
+            "kdf": {
+                "name": "PBKDF2-HMAC-SHA256",
+                "salt": salt.hex(),
+                "iterations": DEFAULT_ITERATIONS,
+            },
+            "cipher": "Fernet",
+            "payload": Fernet(key).encrypt(payload).decode("ascii"),
+        }
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = self.path.with_suffix(self.path.suffix + ".tmp")
+        tmp.write_text(json.dumps(doc, indent=2), encoding="utf-8")
+        try:
+            os.chmod(tmp, stat.S_IRUSR | stat.S_IWUSR)  # 0600
+        except OSError:
+            pass
+        tmp.replace(self.path)
+
+    def _read_file(self) -> dict:
+        if not self.exists():
+            raise VaultError(
+                NOT_FOUND, f"No vault at {self.path} — run `keystash init` first."
+            )
+        try:
+            return json.loads(self.path.read_text(encoding="utf-8"))
+        except json.JSONDecodeError:
+            raise VaultError("corrupt", f"Vault file {self.path} is not valid JSON.") from None

keystash-0.1.0.dist-info/METADATA

@@ -0,0 +1,144 @@
+Metadata-Version: 2.5
+Name: keystash
+Version: 0.1.0
+Summary: Local-first encrypted vault for API keys, tokens and passwords — one file, fuzzy search, env injection, expiry tracking.
+Project-URL: Homepage, https://github.com/thu-lawyer/keystash
+Project-URL: Repository, https://github.com/thu-lawyer/keystash
+Project-URL: Issues, https://github.com/thu-lawyer/keystash/issues
+Project-URL: Changelog, https://github.com/thu-lawyer/keystash/releases
+Author: thu-lawyer
+License: MIT
+License-File: LICENSE
+Keywords: api-key,cli,developer-tools,password,password-manager,secrets,token,vault
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Requires-Dist: cryptography>=41.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# keystash 🔑
+
+**Local-first encrypted vault for API keys, tokens and passwords — one file, fuzzy search, env injection, expiry tracking.**
+
+Your LLM API keys, cloud tokens and passwords are scattered across `.env` files, shell
+histories and notes apps. `keystash` puts them in **one encrypted file** that you own:
+no server, no account, no subscription. Sync that file with iCloud / Dropbox / SeaDrive /
+Syncthing — it's ciphertext, so syncing it is safe.
+
+```bash
+pip install keystash
+```
+
+## Why keystash
+
+| | keystash | pass / gopass | Bitwarden / 1Password | Infisical / Vault |
+|---|---|---|---|---|
+| Setup | `pip install` + one password | GPG key ceremony | Account + app | Self-host a server |
+| Storage | one encrypted file you own | many GPG files | vendor cloud | server |
+| Offline | ✅ always | ✅ | partial | ❌ |
+| Dev workflow (env injection, `run`) | ✅ built-in | ❌ | ❌ | ✅ (heavy) |
+| Token expiry tracking | ✅ built-in | ❌ | ❌ | enterprise |
+
+## Quick start
+
+```bash
+# 1. Create your vault (encrypted with AES-128-CBC + HMAC, PBKDF2-HMAC-SHA256 600k iters)
+keystash init
+
+# 2. Store a secret
+keystash add openai --secret sk-... --tags llm,prod --expires 2027-01-31 --env-var OPENAI_API_KEY
+
+# 3. Retrieve it
+keystash get openai              # masked preview
+keystash get openai -c           # → clipboard, auto-clears after 30 s
+keystash get openai -q           # raw secret for scripts: export K=$(keystash get openai -q)
+
+# 4. Find things (fuzzy)
+keystash ls                      # everything, expiry warnings included
+keystash ls oprod                # fuzzy: matches openai-prod
+keystash ls --tag llm --json
+
+# 5. Inject secrets into any command — nothing touches your shell or disk
+keystash run -n openai -n anthropic -- python train.py
+keystash run --tag llm -- python train.py
+eval "$(keystash env --tag llm)" # or export them explicitly
+
+# 6. Migrate off plaintext .env files
+keystash import .env             # then delete the .env file
+```
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `init` | Create the vault |
+| `add NAME` | Store a secret (`-s` value, `-g LEN` to generate, `-t` tags, `--expires YYYY-MM-DD`, `--env-var`) |
+| `get NAME` | Show (`-r` reveal), copy (`-c`), raw output (`-q`) |
+| `ls [QUERY]` | List / fuzzy search (`--tag`, `--json`) |
+| `edit NAME` | Update any field in place |
+| `rm NAME` | Delete an entry |
+| `gen [LEN]` | Generate a strong secret (`--save NAME` to store it) |
+| `env NAME…` / `--tag` | Print `export` lines for shell eval |
+| `run -n NAME… -- CMD` | Run a command with secrets injected as env vars (`--tag` selects by tag) |
+| `import FILE` | Bulk-import `.env` or JSON |
+| `export` | Export metadata (or secrets with `--with-secrets`) as JSON / dotenv |
+| `status` | Vault health + expired / expiring-soon report |
+
+## Multi-machine sync
+
+The vault is a single encrypted file. Point `KEYSTASH_VAULT` at any synced folder:
+
+```bash
+export KEYSTASH_VAULT="~/CloudStorage/SeaDrive/vault.json"   # or iCloud, Dropbox, …
+```
+
+Each write re-encrypts with a fresh random salt, so last-writer-wins applies —
+prefer one writer per vault at a time, like any sync file.
+
+## Security model
+
+- **Cipher:** Fernet (AES-128-CBC + HMAC-SHA256, encrypt-then-MAC) via `cryptography`.
+- **Key derivation:** PBKDF2-HMAC-SHA256, 600 000 iterations, per-save 128-bit random salt.
+- **File mode:** `0600`; nothing is ever written to disk in plaintext.
+- **Clipboard:** copied secrets are auto-cleared after 30 s (best effort, detached process).
+- **No network.** No telemetry. The CLI is fully offline.
+- Secrets live in process memory only while a command runs; Python cannot guarantee
+  zeroization after exit — the same is true of any CLI in a GC'd language.
+
+## Environment variables
+
+| Variable | Purpose |
+|---|---|
+| `KEYSTASH_VAULT` | Vault file path (also `--vault`) |
+| `KEYSTASH_PASSWORD` | Master password (for scripts/CI; prefer the interactive prompt) |
+
+## Development
+
+```bash
+git clone https://github.com/thu-lawyer/keystash && cd keystash
+uv pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+[MIT](LICENSE)

keystash-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+keystash/__init__.py,sha256=R-dspzH6j4hthcyppwpqypHfLVyU6TwAtfRh_a2wOQA,106
+keystash/__main__.py,sha256=d1PJkDvFKuZeJLHZhFW8W5OO_JTOQqtLlz4cB4rz0Jg,94
+keystash/cli.py,sha256=kY76YnEpHzC9dWJL669VPMXFwD8qIYBVqcawoyz0VYc,20325
+keystash/clipboard.py,sha256=yy9I8UpoCocluJbbPYIM8tAPc5mysEvH-nil_oQU7F0,2179
+keystash/gen.py,sha256=BrGIET7JIpHvUgS78DGRFN8myY7gfciCEIHT5xhX6AQ,977
+keystash/model.py,sha256=tjGY3OxNaRTgk4resbfTirvbNiKOEISHYQacJaxX78U,2764
+keystash/search.py,sha256=JQKTB7M2z5XzyldIPc3ormN8ginRlPo6ojcTkTi2nUE,1298
+keystash/vault.py,sha256=9EL7Zt4c7IIFJ43j8rmyAeihKprWhZ2xE688iv0KRQw,4965
+keystash-0.1.0.dist-info/METADATA,sha256=ImeDftCF73fwTAOdDFsy7h-a6XGCoYVz4Z00udrBWpg,5674
+keystash-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+keystash-0.1.0.dist-info/entry_points.txt,sha256=Rawsg87kLbU7PCS15qYqIrrtxmTzn8n-dn9WvWD7pAE,46
+keystash-0.1.0.dist-info/licenses/LICENSE,sha256=IfKtxamU913_kDwh_BNnyTWw_gcb0ypWPUANmrpe9CY,1067
+keystash-0.1.0.dist-info/RECORD,,

keystash-0.1.0.dist-info/WHEEL

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

keystash-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+keystash = keystash.cli:app

keystash-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 thu-lawyer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.