epi-recorder 1.0.0__py3-none-any.whl

epi_cli/__init__.py

@@ -0,0 +1,5 @@
+"""
+EPI CLI - Command-line interface for EPI operations.
+"""
+
+__version__ = "1.0.0-keystone"

epi_cli/keys.py

@@ -0,0 +1,272 @@
+"""
+EPI CLI Keys - Ed25519 key pair management for cryptographic signing.
+
+Provides secure key generation, storage, and management following best practices.
+"""
+
+import base64
+import os
+from pathlib import Path
+from typing import Optional
+
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+
+
+class KeyManager:
+    """
+    Manages Ed25519 key pairs for EPI signing.
+    
+    Keys are stored in ~/.epi/keys/ with secure permissions:
+    - Private keys: 0600 (owner read/write only)
+    - Public keys: 0644 (owner write, all read)
+    """
+    
+    def __init__(self, keys_dir: Optional[Path] = None):
+        """
+        Initialize key manager.
+        
+        Args:
+            keys_dir: Optional custom keys directory (default: ~/.epi/keys/)
+        """
+        if keys_dir is None:
+            self.keys_dir = Path.home() / ".epi" / "keys"
+        else:
+            self.keys_dir = keys_dir
+        
+        # Ensure keys directory exists with secure permissions
+        self.keys_dir.mkdir(parents=True, exist_ok=True)
+        
+        # On Unix-like systems, set directory permissions to 0700
+        if os.name != 'nt':  # Not Windows
+            os.chmod(self.keys_dir, 0o700)
+    
+    def generate_keypair(self, name: str = "default", overwrite: bool = False) -> tuple[Path, Path]:
+        """
+        Generate an Ed25519 key pair.
+        
+        Args:
+            name: Key pair name
+            overwrite: Whether to overwrite existing keys
+            
+        Returns:
+            tuple: (private_key_path, public_key_path)
+            
+        Raises:
+            FileExistsError: If keys exist and overwrite=False
+        """
+        private_key_path = self.keys_dir / f"{name}.key"
+        public_key_path = self.keys_dir / f"{name}.pub"
+        
+        # Check for existing keys
+        if not overwrite:
+            if private_key_path.exists() or public_key_path.exists():
+                raise FileExistsError(
+                    f"Key pair '{name}' already exists. Use --overwrite to replace."
+                )
+        
+        # Generate Ed25519 key pair
+        private_key = Ed25519PrivateKey.generate()
+        public_key = private_key.public_key()
+        
+        # Serialize private key (PEM format, no encryption for simplicity in MVP)
+        private_pem = private_key.private_bytes(
+            encoding=serialization.Encoding.PEM,
+            format=serialization.PrivateFormat.PKCS8,
+            encryption_algorithm=serialization.NoEncryption()
+        )
+        
+        # Serialize public key (PEM format)
+        public_pem = public_key.public_bytes(
+            encoding=serialization.Encoding.PEM,
+            format=serialization.PublicFormat.SubjectPublicKeyInfo
+        )
+        
+        # Write private key with secure permissions
+        private_key_path.write_bytes(private_pem)
+        if os.name != 'nt':  # Unix-like systems
+            os.chmod(private_key_path, 0o600)  # Owner read/write only
+        else:  # Windows
+            # Set file to be readable only by owner
+            import stat
+            os.chmod(private_key_path, stat.S_IREAD | stat.S_IWRITE)
+        
+        # Write public key
+        public_key_path.write_bytes(public_pem)
+        if os.name != 'nt':
+            os.chmod(public_key_path, 0o644)  # Owner write, all read
+        
+        return private_key_path, public_key_path
+    
+    def load_private_key(self, name: str = "default") -> Ed25519PrivateKey:
+        """
+        Load a private key from disk.
+        
+        Args:
+            name: Key pair name
+            
+        Returns:
+            Ed25519PrivateKey: Loaded private key
+            
+        Raises:
+            FileNotFoundError: If key doesn't exist
+        """
+        key_path = self.keys_dir / f"{name}.key"
+        
+        if not key_path.exists():
+            raise FileNotFoundError(
+                f"Private key '{name}' not found. Generate with: epi keys generate --name {name}"
+            )
+        
+        key_data = key_path.read_bytes()
+        return serialization.load_pem_private_key(key_data, password=None)
+    
+    def load_public_key(self, name: str = "default") -> bytes:
+        """
+        Load a public key from disk.
+        
+        Args:
+            name: Key pair name
+            
+        Returns:
+            bytes: Public key bytes (raw 32 bytes for Ed25519)
+            
+        Raises:
+            FileNotFoundError: If key doesn't exist
+        """
+        key_path = self.keys_dir / f"{name}.pub"
+        
+        if not key_path.exists():
+            raise FileNotFoundError(
+                f"Public key '{name}' not found. Generate with: epi keys generate --name {name}"
+            )
+        
+        pem_data = key_path.read_bytes()
+        public_key = serialization.load_pem_public_key(pem_data)
+        
+        # Return raw 32-byte public key
+        return public_key.public_bytes(
+            encoding=serialization.Encoding.Raw,
+            format=serialization.PublicFormat.Raw
+        )
+    
+    def list_keys(self) -> list[dict[str, str]]:
+        """
+        List all available key pairs.
+        
+        Returns:
+            list: List of dicts with key information
+        """
+        keys = []
+        
+        # Find all .pub files
+        for pub_file in self.keys_dir.glob("*.pub"):
+            key_name = pub_file.stem
+            private_exists = (self.keys_dir / f"{key_name}.key").exists()
+            
+            keys.append({
+                "name": key_name,
+                "has_private": private_exists,
+                "has_public": True,
+                "public_path": str(pub_file),
+                "private_path": str(self.keys_dir / f"{key_name}.key") if private_exists else "N/A"
+            })
+        
+        return keys
+    
+    def export_public_key(self, name: str = "default") -> str:
+        """
+        Export public key as base64 string for sharing.
+        
+        Args:
+            name: Key pair name
+            
+        Returns:
+            str: Base64-encoded public key
+        """
+        public_key_bytes = self.load_public_key(name)
+        return base64.b64encode(public_key_bytes).decode("utf-8")
+    
+    def has_key(self, name: str = "default") -> bool:
+        """
+        Check if a key pair exists.
+        
+        Args:
+            name: Key pair name
+            
+        Returns:
+            bool: True if key pair exists
+        """
+        private_path = self.keys_dir / f"{name}.key"
+        public_path = self.keys_dir / f"{name}.pub"
+        return private_path.exists() and public_path.exists()
+    
+    def has_default_key(self) -> bool:
+        """
+        Check if default key pair exists.
+        
+        Returns:
+            bool: True if default key exists
+        """
+        return (self.keys_dir / "default.key").exists()
+
+
+def generate_default_keypair_if_missing(console_output: bool = True) -> bool:
+    """
+    Generate default key pair if it doesn't exist (frictionless first run).
+    
+    Args:
+        console_output: Whether to print console messages
+        
+    Returns:
+        bool: True if key was generated, False if already exists
+    """
+    key_manager = KeyManager()
+    
+    if key_manager.has_default_key():
+        return False
+    
+    # Generate default key pair
+    private_path, public_path = key_manager.generate_keypair("default")
+    
+    if console_output:
+        console.print("\n[bold green]🔐 Welcome to EPI![/bold green]")
+        console.print("\n[dim]Generated default Ed25519 key pair for signing:[/dim]")
+        console.print(f"  [cyan]Private:[/cyan] {private_path}")
+        console.print(f"  [cyan]Public:[/cyan]  {public_path}")
+        console.print("\n[dim]Your .epi files will be automatically signed for authenticity.[/dim]\n")
+    
+    return True
+
+
+def print_keys_table(keys: list[dict[str, str]]) -> None:
+    """
+    Print a formatted table of keys using Rich.
+    
+    Args:
+        keys: List of key information dicts
+    """
+    if not keys:
+        console.print("[yellow]No keys found. Generate with: epi keys generate[/yellow]")
+        return
+    
+    table = Table(title="EPI Key Pairs", show_header=True, header_style="bold magenta")
+    table.add_column("Name", style="cyan")
+    table.add_column("Private Key", style="green")
+    table.add_column("Public Key", style="blue")
+    
+    for key in keys:
+        private_status = "✅" if key["has_private"] else "❌"
+        public_status = "✅" if key["has_public"] else "❌"
+        
+        table.add_row(
+            key["name"],
+            f"{private_status} {key['private_path']}",
+            f"{public_status} {key['public_path']}"
+        )
+    
+    console.print(table)

epi_cli/main.py

@@ -0,0 +1,106 @@
+"""
+EPI CLI Main - Entry point for the EPI command-line interface.
+
+Provides the main CLI application with frictionless first-run experience.
+"""
+
+import typer
+from rich.console import Console
+
+from epi_cli.keys import generate_default_keypair_if_missing
+
+# Create Typer app
+app = typer.Typer(
+    name="epi",
+    help="EPI - Evidence Packaged Infrastructure for AI workflows",
+    add_completion=False,
+    no_args_is_help=True,
+    rich_markup_mode="rich"
+)
+
+console = Console()
+
+
+@app.callback()
+def main_callback():
+    """
+    Main callback - runs before any command.
+    
+    Implements frictionless first run by auto-generating default key pair.
+    """
+    # Auto-generate default keypair if missing (frictionless first run)
+    generate_default_keypair_if_missing(console_output=True)
+
+
+@app.command()
+def version():
+    """Show EPI version information."""
+    from epi_core import __version__
+    console.print(f"[bold]EPI[/bold] version [cyan]{__version__}[/cyan]")
+    console.print("[dim]The PDF for AI workflows[/dim]")
+
+
+# Import and register subcommands
+# These will be added as they're implemented
+
+# Phase 1: verify command
+from epi_cli.verify import verify_app
+app.add_typer(verify_app, name="verify", help="Verify .epi file integrity and authenticity")
+
+# Phase 2: record command
+from epi_cli.record import app as record_app
+app.add_typer(record_app, name="record", help="Record a workflow into a .epi file")
+
+# Phase 3: view command
+from epi_cli.view import app as view_app
+app.add_typer(view_app, name="view", help="View .epi file in browser")
+
+# Phase 1: keys command (for manual key management)
+@app.command()
+def keys(
+    action: str = typer.Argument(..., help="Action: generate, list, or export"),
+    name: str = typer.Option("default", "--name", "-n", help="Key pair name"),
+    overwrite: bool = typer.Option(False, "--overwrite", help="Overwrite existing keys")
+):
+    """Manage Ed25519 key pairs for signing."""
+    from epi_cli.keys import KeyManager, print_keys_table
+    
+    key_manager = KeyManager()
+    
+    if action == "generate":
+        try:
+            private_path, public_path = key_manager.generate_keypair(name, overwrite=overwrite)
+            console.print(f"\n[bold green]✅ Generated key pair:[/bold green] {name}")
+            console.print(f"  [cyan]Private:[/cyan] {private_path}")
+            console.print(f"  [cyan]Public:[/cyan]  {public_path}\n")
+        except FileExistsError as e:
+            console.print(f"[red]❌ Error:[/red] {e}")
+            raise typer.Exit(1)
+    
+    elif action == "list":
+        keys_list = key_manager.list_keys()
+        print_keys_table(keys_list)
+    
+    elif action == "export":
+        try:
+            public_key_b64 = key_manager.export_public_key(name)
+            console.print(f"\n[bold]Public key for '{name}':[/bold]")
+            console.print(f"[cyan]{public_key_b64}[/cyan]\n")
+        except FileNotFoundError as e:
+            console.print(f"[red]❌ Error:[/red] {e}")
+            raise typer.Exit(1)
+    
+    else:
+        console.print(f"[red]❌ Unknown action:[/red] {action}")
+        console.print("[dim]Valid actions: generate, list, export[/dim]")
+        raise typer.Exit(1)
+
+
+# Entry point for CLI
+def cli_main():
+    """CLI entry point (called by `epi` command)."""
+    app()
+
+
+if __name__ == "__main__":
+    cli_main()

epi_cli/record.py

@@ -0,0 +1,192 @@
+"""
+EPI CLI Record - Capture AI workflow into a portable .epi file.
+
+Usage:
+  epi record --out run.epi -- python script.py [args...]
+
+This command:
+- Prepares a recording workspace
+- Patches LLM libraries in the child process
+- Captures environment snapshot (env.json)
+- Runs the user command with secret redaction enabled by default
+- Packages everything into a .epi
+- Auto-signs the manifest with the default Ed25519 key
+"""
+
+import os
+import shlex
+import sys
+import tempfile
+import time
+import zipfile
+from datetime import datetime
+from pathlib import Path
+from typing import List, Optional
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+
+from epi_core.container import EPIContainer
+from epi_core.schemas import ManifestModel
+from epi_core.trust import sign_manifest, sign_manifest_inplace
+from epi_cli.keys import KeyManager
+from epi_recorder.environment import save_environment_snapshot
+
+console = Console()
+
+
+def _ensure_python_command(cmd: List[str]) -> List[str]:
+    """
+    Ensure the command is run with Python if it looks like a Python script.
+    If the user provided `python ...`, leave as-is.
+    If the command is a .py file, prepend current Python executable.
+    """
+    if not cmd:
+        return cmd
+    first = cmd[0]
+    if first.lower().endswith('.py'):
+        return [sys.executable] + cmd
+    return cmd
+
+
+def _build_env_for_child(steps_dir: Path, enable_redaction: bool) -> dict:
+    """
+    Build environment variables for child process to enable recording via sitecustomize.
+    """
+    env = os.environ.copy()
+
+    # Indicate recording mode and where to write steps
+    env["EPI_RECORD"] = "1"
+    env["EPI_STEPS_DIR"] = str(steps_dir)
+    env["EPI_REDACT"] = "1" if enable_redaction else "0"
+
+    # Create a temporary bootstrap dir with sitecustomize.py
+    bootstrap_dir = Path(tempfile.mkdtemp(prefix="epi_bootstrap_"))
+    sitecustomize = bootstrap_dir / "sitecustomize.py"
+    sitecustomize.write_text(
+        "from epi_recorder.bootstrap import initialize_recording\n",
+        encoding="utf-8",
+    )
+
+    # Prepend bootstrap dir and project root to PYTHONPATH
+    project_root = Path(__file__).resolve().parent.parent
+    existing = env.get("PYTHONPATH", "")
+    sep = os.pathsep
+    env["PYTHONPATH"] = f"{bootstrap_dir}{sep}{project_root}{(sep + existing) if existing else ''}"
+
+    return env
+
+
+app = typer.Typer(name="record", help="Record a workflow into a .epi file")
+
+
+@app.callback(invoke_without_command=True)
+def record(
+    ctx: typer.Context,
+    out: Path = typer.Option(..., "--out", help="Output .epi file path"),
+    name: Optional[str] = typer.Option(None, "--name", help="Optional run name"),
+    tag: Optional[str] = typer.Option(None, "--tag", help="Optional tag/label"),
+    no_sign: bool = typer.Option(False, "--no-sign", help="Do not sign the manifest"),
+    no_redact: bool = typer.Option(False, "--no-redact", help="Disable secret redaction"),
+    include_all_env: bool = typer.Option(False, "--include-all-env", help="Capture all env vars (redacted)"),
+    command: List[str] = typer.Argument(..., help="Command to execute after --"),
+):
+    """
+    Record a command and package the run into a .epi file.
+    """
+    if not command:
+        console.print("[red]❌ No command provided[/red]")
+        raise typer.Exit(1)
+
+    # Normalize command
+    cmd = _ensure_python_command(command)
+
+    # Prepare workspace
+    temp_workspace = Path(tempfile.mkdtemp(prefix="epi_record_"))
+    steps_dir = temp_workspace  # steps.jsonl lives here
+    env_json = temp_workspace / "env.json"
+
+    # Capture environment snapshot
+    save_environment_snapshot(env_json, include_all_env_vars=include_all_env, redact_env_vars=True)
+
+    # Build child environment and run
+    child_env = _build_env_for_child(steps_dir, enable_redaction=(not no_redact))
+
+    # Create stdout/stderr logs
+    stdout_log = temp_workspace / "stdout.log"
+    stderr_log = temp_workspace / "stderr.log"
+
+    console.print(f"[dim]Recording:[/dim] {' '.join(shlex.quote(c) for c in cmd)}")
+
+    import subprocess
+
+    start = time.time()
+    with open(stdout_log, "wb") as out_f, open(stderr_log, "wb") as err_f:
+        proc = subprocess.Popen(cmd, env=child_env, stdout=out_f, stderr=err_f)
+        rc = proc.wait()
+    duration = round(time.time() - start, 3)
+
+    # Build manifest
+    manifest = ManifestModel(
+        cli_command=" ".join(shlex.quote(c) for c in cmd),
+    )
+
+    # Package into .epi
+    out = out if str(out).endswith(".epi") else out.with_suffix(".epi")
+    EPIContainer.pack(temp_workspace, manifest, out)
+
+    # Auto-sign manifest inside .epi (without re-packing)
+    signed = False
+    if not no_sign:
+        try:
+            km = KeyManager()
+            priv = km.load_private_key("default")
+            
+            # Read manifest from ZIP
+            import json as _json
+            with zipfile.ZipFile(out, "r") as zf:
+                raw = zf.read("manifest.json").decode("utf-8")
+                data = _json.loads(raw)
+            
+            # Sign manifest
+            from epi_core.schemas import ManifestModel as _MM
+            from epi_core.trust import sign_manifest as _sign
+            m = _MM(**data)
+            sm = _sign(m, priv, "default")
+            signed_json = sm.model_dump_json(indent=2)
+            
+            # Replace manifest in ZIP (avoid duplicate)
+            temp_zip = out.with_suffix(".epi.tmp")
+            with zipfile.ZipFile(out, "r") as zf_in:
+                with zipfile.ZipFile(temp_zip, "w", zipfile.ZIP_DEFLATED) as zf_out:
+                    # Copy all files except manifest.json
+                    for item in zf_in.namelist():
+                        if item != "manifest.json":
+                            zf_out.writestr(item, zf_in.read(item))
+                    # Write signed manifest
+                    zf_out.writestr("manifest.json", signed_json)
+            
+            # Replace original with updated ZIP
+            temp_zip.replace(out)
+            signed = True
+        except Exception as e:
+            console.print(f"[yellow]⚠️  Signing failed:[/yellow] {e}")
+
+    # Final output panel
+    size_mb = out.stat().st_size / (1024 * 1024)
+    title = "✅ Recording complete" if rc == 0 else "⚠️ Recording finished with errors"
+    panel = Panel(
+        f"[bold]File:[/bold] {out}\n"
+        f"[bold]Size:[/bold] {size_mb:.1f} MB\n"
+        f"[bold]Duration:[/bold] {duration}s\n"
+        f"[bold]Exit code:[/bold] {rc}\n"
+        f"[bold]Signed:[/bold] {'Yes' if signed else 'No'}\n"
+        f"[dim]Verify:[/dim] epi verify {shlex.quote(str(out))}",
+        title=title,
+        border_style="green" if rc == 0 else "yellow",
+    )
+    console.print(panel)
+
+    # Exit with child return code
+    raise typer.Exit(rc)