apcore-cli 0.1.0__py3-none-any.whl

apcore_cli/security/audit.py

@@ -0,0 +1,53 @@
+"""Audit logging in JSON Lines format (FE-05)."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import os
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Literal
+
+logger = logging.getLogger("apcore_cli.security")
+
+
+class AuditLogger:
+    DEFAULT_PATH = Path.home() / ".apcore-cli" / "audit.jsonl"
+
+    def __init__(self, path: Path | None = None) -> None:
+        self._path = path or self.DEFAULT_PATH
+        self._ensure_directory()
+
+    def _ensure_directory(self) -> None:
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+
+    def log_execution(
+        self,
+        module_id: str,
+        input_data: dict,
+        status: Literal["success", "error"],
+        exit_code: int,
+        duration_ms: int,
+    ) -> None:
+        entry = {
+            "timestamp": datetime.now(UTC).isoformat(timespec="milliseconds").replace("+00:00", "Z"),
+            "user": self._get_user(),
+            "module_id": module_id,
+            "input_hash": hashlib.sha256(json.dumps(input_data, sort_keys=True).encode()).hexdigest(),
+            "status": status,
+            "exit_code": exit_code,
+            "duration_ms": duration_ms,
+        }
+        try:
+            with open(self._path, "a") as f:
+                f.write(json.dumps(entry) + "\n")
+        except OSError as e:
+            logger.warning("Could not write audit log: %s", e)
+
+    def _get_user(self) -> str:
+        try:
+            return os.getlogin()
+        except OSError:
+            return os.getenv("USER", os.getenv("USERNAME", "unknown"))

apcore_cli/security/auth.py

@@ -0,0 +1,37 @@
+"""API key authentication (FE-05)."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from apcore_cli.config import ConfigResolver
+
+
+class AuthenticationError(Exception):
+    pass
+
+
+class AuthProvider:
+    def __init__(self, config: ConfigResolver) -> None:
+        self._config = config
+
+    def get_api_key(self) -> str | None:
+        result = self._config.resolve("auth.api_key", cli_flag="--api-key", env_var="APCORE_AUTH_API_KEY")
+        if result is not None and (result.startswith("keyring:") or result.startswith("enc:")):
+            result = self._config.encryptor.retrieve(result, "auth.api_key")
+        return result
+
+    def authenticate_request(self, headers: dict) -> dict:
+        key = self.get_api_key()
+        if key is None:
+            raise AuthenticationError(
+                "Remote registry requires authentication. "
+                "Set --api-key, APCORE_AUTH_API_KEY, or auth.api_key in config."
+            )
+        headers["Authorization"] = f"Bearer {key}"
+        return headers
+
+    def handle_response(self, status_code: int) -> None:
+        if status_code in (401, 403):
+            raise AuthenticationError("Authentication failed. Verify your API key.")

apcore_cli/security/config_encryptor.py

@@ -0,0 +1,94 @@
+"""Encrypted configuration storage (FE-05)."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import logging
+import os
+import socket
+
+from cryptography.exceptions import InvalidTag
+
+logger = logging.getLogger("apcore_cli.security")
+
+
+class ConfigDecryptionError(Exception):
+    pass
+
+
+class ConfigEncryptor:
+    SERVICE_NAME = "apcore-cli"
+
+    def store(self, key: str, value: str) -> str:
+        if self._keyring_available():
+            import keyring as kr
+
+            kr.set_password(self.SERVICE_NAME, key, value)
+            return f"keyring:{key}"
+        else:
+            logger.warning("OS keyring unavailable. Using file-based encryption.")
+            ciphertext = self._aes_encrypt(value)
+            return f"enc:{base64.b64encode(ciphertext).decode()}"
+
+    def retrieve(self, config_value: str, key: str) -> str:
+        if config_value.startswith("keyring:"):
+            import keyring as kr
+
+            ref_key = config_value[len("keyring:") :]
+            result = kr.get_password(self.SERVICE_NAME, ref_key)
+            if result is None:
+                raise ConfigDecryptionError(f"Keyring entry not found for '{ref_key}'.")
+            return result
+        elif config_value.startswith("enc:"):
+            ciphertext = base64.b64decode(config_value[len("enc:") :])
+            try:
+                return self._aes_decrypt(ciphertext)
+            except (InvalidTag, ValueError) as exc:
+                raise ConfigDecryptionError(
+                    f"Failed to decrypt configuration value '{key}'. Re-configure with 'apcore-cli config set {key}'."
+                ) from exc
+        else:
+            return config_value
+
+    def _keyring_available(self) -> bool:
+        try:
+            import keyring as kr
+
+            backend = kr.get_keyring()
+            return not (
+                hasattr(kr, "backends")
+                and hasattr(kr.backends, "fail")
+                and isinstance(backend, kr.backends.fail.Keyring)
+            )
+        except Exception:
+            return False
+
+    def _derive_key(self) -> bytes:
+        hostname = socket.gethostname()
+        username = os.getenv("USER", os.getenv("USERNAME", "unknown"))
+        salt = b"apcore-cli-config-v1"
+        material = f"{hostname}:{username}".encode()
+        return hashlib.pbkdf2_hmac("sha256", material, salt, iterations=100_000)
+
+    def _aes_encrypt(self, plaintext: str) -> bytes:
+        from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+
+        key = self._derive_key()
+        nonce = os.urandom(12)
+        encryptor = Cipher(algorithms.AES(key), modes.GCM(nonce)).encryptor()
+        ct = encryptor.update(plaintext.encode("utf-8")) + encryptor.finalize()
+        tag = encryptor.tag
+        # Wire format: nonce(12) + tag(16) + ciphertext
+        return nonce + tag + ct
+
+    def _aes_decrypt(self, data: bytes) -> str:
+        from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+
+        key = self._derive_key()
+        nonce = data[:12]
+        tag = data[12:28]
+        ct = data[28:]
+        decryptor = Cipher(algorithms.AES(key), modes.GCM(nonce, tag)).decryptor()
+        plaintext = decryptor.update(ct) + decryptor.finalize()
+        return plaintext.decode("utf-8")

apcore_cli/security/sandbox.py

@@ -0,0 +1,60 @@
+"""Subprocess-based execution sandboxing (FE-05)."""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import tempfile
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from apcore import Executor
+
+
+class ModuleExecutionError(Exception):
+    """Raised when a sandboxed module execution fails."""
+
+    pass
+
+
+class Sandbox:
+    def __init__(self, enabled: bool = False) -> None:
+        self._enabled = enabled
+
+    def execute(self, module_id: str, input_data: dict, executor: Executor) -> Any:
+        if not self._enabled:
+            return executor.call(module_id, input_data)
+        return self._sandboxed_execute(module_id, input_data)
+
+    def _sandboxed_execute(self, module_id: str, input_data: dict) -> Any:
+        env = {}
+        for key in ("PATH", "PYTHONPATH", "LANG", "LC_ALL"):
+            if key in os.environ:
+                env[key] = os.environ[key]
+        for key, value in os.environ.items():
+            if key.startswith("APCORE_"):
+                env[key] = value
+
+        with tempfile.TemporaryDirectory(prefix="apcore_sandbox_") as tmpdir:
+            env["HOME"] = tmpdir
+            env["TMPDIR"] = tmpdir
+
+            try:
+                result = subprocess.run(
+                    [sys.executable, "-m", "apcore_cli._sandbox_runner", module_id],
+                    input=json.dumps(input_data),
+                    capture_output=True,
+                    text=True,
+                    env=env,
+                    cwd=tmpdir,
+                    timeout=300,
+                )
+            except subprocess.TimeoutExpired as err:
+                raise ModuleExecutionError(f"Error: Module '{module_id}' timed out in sandbox.") from err
+
+            if result.returncode != 0:
+                raise ModuleExecutionError(f"Error: Module '{module_id}' execution failed: {result.stderr}")
+
+            return json.loads(result.stdout)

apcore_cli/shell.py

@@ -0,0 +1,185 @@
+"""Shell Integration — completion scripts and man pages (FE-06)."""
+
+from __future__ import annotations
+
+import sys
+from datetime import date
+
+import click
+
+from apcore_cli import __version__
+
+# Shell snippet for dynamic module ID completion (shared across shells)
+_MODULE_LIST_CMD = (
+    "apcore-cli list --format json 2>/dev/null"
+    ' | python3 -c "import sys,json;'
+    "[print(m['id']) for m in json.load(sys.stdin)]\" 2>/dev/null"
+)
+
+
+def _generate_bash_completion() -> str:
+    return (
+        "_apcore_cli_completion() {\n"
+        "    local cur prev opts\n"
+        "    COMPREPLY=()\n"
+        '    cur="${COMP_WORDS[COMP_CWORD]}"\n'
+        '    prev="${COMP_WORDS[COMP_CWORD-1]}"\n'
+        "\n"
+        "    if [[ ${COMP_CWORD} -eq 1 ]]; then\n"
+        '        opts="exec list describe completion man"\n'
+        '        COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) )\n'
+        "        return 0\n"
+        "    fi\n"
+        "\n"
+        '    if [[ "${COMP_WORDS[1]}" == "exec" && ${COMP_CWORD} -eq 2 ]]; then\n'
+        f"        local modules=$({_MODULE_LIST_CMD})\n"
+        '        COMPREPLY=( $(compgen -W "${modules}" -- ${cur}) )\n'
+        "        return 0\n"
+        "    fi\n"
+        "}\n"
+        "complete -F _apcore_cli_completion apcore-cli\n"
+    )
+
+
+def _generate_zsh_completion() -> str:
+    return (
+        "#compdef apcore-cli\n"
+        "\n"
+        "_apcore_cli() {\n"
+        "    local -a commands\n"
+        "    commands=(\n"
+        "        'exec:Execute an apcore module'\n"
+        "        'list:List available modules'\n"
+        "        'describe:Show module details'\n"
+        "        'completion:Generate shell completion script'\n"
+        "        'man:Generate man page'\n"
+        "    )\n"
+        "\n"
+        "    _arguments -C \\\n"
+        "        '1:command:->command' \\\n"
+        "        '*::arg:->args'\n"
+        "\n"
+        '    case "$state" in\n'
+        "        command)\n"
+        "            _describe -t commands 'apcore-cli commands' commands\n"
+        "            ;;\n"
+        "        args)\n"
+        '            case "${words[1]}" in\n'
+        "                exec)\n"
+        "                    local modules\n"
+        f"                    modules=($({_MODULE_LIST_CMD}))\n"
+        "                    compadd -a modules\n"
+        "                    ;;\n"
+        "            esac\n"
+        "            ;;\n"
+        "    esac\n"
+        "}\n"
+        "\n"
+        "compdef _apcore_cli apcore-cli\n"
+    )
+
+
+def _generate_fish_completion() -> str:
+    # Build the dynamic completion command for fish (needs escaped quotes)
+    fish_dyn = _MODULE_LIST_CMD.replace('"', '\\"').replace("'", "\\'")
+    return (
+        "# Fish completions for apcore-cli\n"
+        'complete -c apcore-cli -n "__fish_use_subcommand"'
+        ' -a exec -d "Execute an apcore module"\n'
+        'complete -c apcore-cli -n "__fish_use_subcommand"'
+        ' -a list -d "List available modules"\n'
+        'complete -c apcore-cli -n "__fish_use_subcommand"'
+        ' -a describe -d "Show module details"\n'
+        'complete -c apcore-cli -n "__fish_use_subcommand"'
+        ' -a completion -d "Generate shell completion script"\n'
+        'complete -c apcore-cli -n "__fish_use_subcommand"'
+        ' -a man -d "Generate man page"\n'
+        "\n"
+        'complete -c apcore-cli -n "__fish_seen_subcommand_from exec"'
+        f' -a "({fish_dyn})"\n'
+    )
+
+
+def _generate_man_page(command_name: str, command: click.Command | None, cli: click.Group) -> str:
+    """Generate a roff-formatted man page for a command."""
+    today = date.today().strftime("%Y-%m-%d")
+    cmd_upper = command_name.upper()
+
+    sections = []
+    sections.append(f'.TH "APCORE-CLI-{cmd_upper}" "1" "{today}" "apcore-cli {__version__}" "apcore-cli Manual"')
+    sections.append(".SH NAME")
+    if command:
+        desc = command.help or command_name
+        sections.append(f"apcore-cli-{command_name} \\- {desc}")
+    else:
+        sections.append(f"apcore-cli-{command_name}")
+
+    sections.append(".SH SYNOPSIS")
+    sections.append(f"\\fBapcore-cli {command_name}\\fR [OPTIONS] [ARGUMENTS]")
+
+    if command and command.help:
+        sections.append(".SH DESCRIPTION")
+        sections.append(command.help)
+
+    if command and command.params:
+        sections.append(".SH OPTIONS")
+        for param in command.params:
+            if isinstance(param, click.Option):
+                flag = ", ".join(param.opts + getattr(param, "secondary_opts", []))
+                type_name = param.type.name if hasattr(param.type, "name") else "VALUE"
+                sections.append(".TP")
+                sections.append(f"\\fB{flag}\\fR \\fI{type_name}\\fR")
+                if param.help:
+                    sections.append(param.help)
+
+    sections.append(".SH EXIT CODES")
+    sections.append(".TP\n\\fB0\\fR\nSuccess.")
+    sections.append(".TP\n\\fB1\\fR\nModule execution error.")
+    sections.append(".TP\n\\fB2\\fR\nInvalid CLI input.")
+    sections.append(".TP\n\\fB44\\fR\nModule not found, disabled, or load error.")
+    sections.append(".TP\n\\fB45\\fR\nSchema validation error.")
+    sections.append(".TP\n\\fB46\\fR\nApproval denied or timed out.")
+    sections.append(".TP\n\\fB47\\fR\nConfiguration error.")
+    sections.append(".TP\n\\fB48\\fR\nSchema circular reference.")
+    sections.append(".TP\n\\fB77\\fR\nACL denied.")
+    sections.append(".TP\n\\fB130\\fR\nExecution cancelled (SIGINT).")
+
+    sections.append(".SH SEE ALSO")
+    sections.append("\\fBapcore-cli\\fR(1), \\fBapcore-cli-list\\fR(1), \\fBapcore-cli-describe\\fR(1)")
+
+    return "\n".join(sections)
+
+
+def register_shell_commands(cli: click.Group) -> None:
+    """Register completion and man commands."""
+
+    @cli.command("completion")
+    @click.argument("shell", type=click.Choice(["bash", "zsh", "fish"]))
+    def completion_cmd(shell: str) -> None:
+        """Generate shell completion script."""
+        generators = {
+            "bash": _generate_bash_completion,
+            "zsh": _generate_zsh_completion,
+            "fish": _generate_fish_completion,
+        }
+        click.echo(generators[shell]())
+
+    @cli.command("man")
+    @click.argument("command")
+    @click.pass_context
+    def man_cmd(ctx: click.Context, command: str) -> None:
+        """Generate man page for a command."""
+        parent = ctx.parent
+        if parent is None:
+            click.echo(f"Error: Unknown command '{command}'.", err=True)
+            sys.exit(2)
+
+        parent_group = parent.command
+        cmd = parent_group.commands.get(command) if isinstance(parent_group, click.Group) else None
+
+        if cmd is None and command not in ("exec", "list", "describe", "completion", "man"):
+            click.echo(f"Error: Unknown command '{command}'.", err=True)
+            sys.exit(2)
+
+        roff = _generate_man_page(command, cmd, cli)
+        click.echo(roff)