voidx 1.0.0__py3-none-any.whl

voidx/permission/sandbox.py

@@ -0,0 +1,280 @@
+"""Sandbox mode path validation — filesystem boundary enforcement."""
+
+from __future__ import annotations
+
+import re
+import shlex
+from pathlib import Path
+
+
+def _allowed(
+    path: str,
+    workspace: str,
+    extra_paths: list[str],
+    current_dir: Path | None = None,
+) -> bool:
+    """Check if the resolved path is inside workspace or extra_paths."""
+    try:
+        raw = Path(path).expanduser()
+        if raw.is_absolute():
+            resolved = raw.resolve()
+        else:
+            base = current_dir if current_dir is not None else Path(workspace)
+            resolved = (base / raw).resolve()
+    except (OSError, ValueError):
+        return True  # unresolvable → don't block, let the tool report errors
+
+    allowed = [Path(workspace).resolve()]
+    for ep in extra_paths:
+        allowed.append(Path(ep).expanduser().resolve())
+
+    for base in allowed:
+        try:
+            if resolved == base or resolved.is_relative_to(base):
+                return True
+        except (ValueError, OSError):
+            continue
+    return False
+
+
+def check_sandbox_filepath(
+    file_path: str,
+    workspace: str,
+    extra_paths: list[str],
+) -> str | None:
+    """Validate that file_path is inside the allowed workspace + extra_paths.
+
+    Returns None if the path is allowed, or a human-readable rejection reason.
+    Invalid / unresolvable paths are NOT blocked (let the tool itself report
+    the error).
+    """
+    if _allowed(file_path, workspace, extra_paths):
+        return None
+
+    return (
+        f"SANDBOX: '{file_path}' is outside the allowed workspace.\n"
+        f"  Allowed: {workspace}"
+        + (f" + {extra_paths}" if extra_paths else "")
+    )
+
+
+# ── bash command write-target extraction ──────────────────────────────
+
+# Patterns that extract write targets from common bash idioms.
+# Each captures the target path in group 1.
+_REDIR_PATTERNS = [
+    # standard redirect: cmd > /path/to/file, cmd >> /path/to/file
+    re.compile(r"\d?\s*>>?\s*(\S+)"),
+    # tee: cmd | tee /path/to/file,  cmd | tee -a /path/to/file
+    re.compile(r"\|\s*tee(?:\s+-a)?\s+(\S+)"),
+    # dd of=/dev/… (already handled by _BLOCKED in bash.py, but belt-and-suspenders)
+    re.compile(r"\bof=(\S+)"),
+]
+
+# Destructive filesystem commands whose arguments are potential write targets.
+_FS_WRITE_COMMANDS = {
+    "rm": 1,   # rm target
+    "cp": -1,   # cp src… dst  (last arg is destination)
+    "mv": -1,   # mv src… dst  (last arg is destination)
+    "ln": -1,   # ln [-s] src… dst  (last arg is destination)
+    "mkdir": 1, # mkdir dir
+    "touch": 1, # touch file
+    "install": -1, # install src… dst
+    "tee": 1,  # tee [-a] file…
+    "chmod": 0,  # chmod doesn't change filesystem layout; skip
+    "chown": 0,  # chown doesn't change filesystem layout; skip
+    "chgrp": 0,  # chgrp doesn't change filesystem layout; skip
+}
+
+# Git operations that write outside the repo (push to remote).
+# These can't be checked by path inspection, so we only flag force-push
+# which is already blocked by _BLOCKED in bash.py.
+
+
+def check_sandbox_bash(
+    command: str,
+    workspace: str,
+    extra_paths: list[str],
+) -> str | None:
+    """Validate that a bash command's write targets are within the sandbox.
+
+    Extracts redirect targets, tee targets, and destructive file ops.
+    Returns None if all targets are safe, or a rejection reason.
+
+    This is a *best-effort* check — sophisticated command obfuscation can
+    bypass it.  It is designed to catch honest mistakes, not adversarial
+    attacks.  The hard blocklist in bash.py (_BLOCKED) covers the really
+    dangerous stuff.
+    """
+    stripped = command.strip()
+    if not stripped or stripped.startswith("#"):
+        return None
+
+    write_targets: list[str] = []
+
+    # ── redirections (> / >> / | tee) ────────────────────────────────
+    for pattern in _REDIR_PATTERNS:
+        for m in pattern.finditer(stripped):
+            target = m.group(1)
+            if target and not target.startswith("&") and not target.startswith("/dev/"):
+                write_targets.append(target)
+
+    # ── destructive commands (rm/cp/mv/…) ─────────────────────────────
+    words = _shell_words(stripped)
+    prog = _program(words).lower() if words else ""
+    segment_targets = _extract_segment_targets(words, workspace)
+    write_targets.extend(segment_targets)
+
+    # ── git push remote (non-force is blocked by sandbox if workspace-write) ──
+    if _is_git_push_outside(prog, words, workspace, extra_paths):
+        return (
+            f"SANDBOX: git push writes outside the allowed workspace."
+            f"\n  Allowed: {workspace}"
+            + (f" + {extra_paths}" if extra_paths else "")
+            + "\n  Use /sandbox danger-full-access to allow git push."
+        )
+
+    # ── check each target ────────────────────────────────────────────
+    blocked_targets: list[str] = []
+    for target in write_targets:
+        # Remove surrounding quotes if present
+        clean = target.strip('"').strip("'")
+        if not clean or clean.startswith("/dev/"):
+            continue
+        if not _allowed(clean, workspace, extra_paths):
+            blocked_targets.append(target)
+
+    if blocked_targets:
+        return (
+            f"SANDBOX: bash command writes outside the allowed workspace.\n"
+            f"  Targets: {', '.join(blocked_targets[:5])}\n"
+            f"  Allowed: {workspace}"
+            + (f" + {extra_paths}" if extra_paths else "")
+        )
+
+    return None
+
+
+def _shell_words(command: str) -> list[str]:
+    try:
+        lexer = shlex.shlex(command, posix=True, punctuation_chars=True)
+        lexer.whitespace_split = True
+        return list(lexer)
+    except ValueError:
+        return command.split()
+
+
+def _extract_segment_targets(words: list[str], workspace: str) -> list[str]:
+    targets: list[str] = []
+    current_dir = Path(workspace).resolve()
+    segment: list[str] = []
+    for token in [*words, ";"]:
+        if token in (";", "&&", "||"):
+            targets.extend(_extract_command_targets(segment, workspace, current_dir))
+            if segment and _program(segment).lower() == "cd":
+                next_dir = _first_non_flag_arg(segment[1:])
+                if next_dir:
+                    raw = Path(next_dir).expanduser()
+                    current_dir = (raw if raw.is_absolute() else current_dir / raw).resolve()
+            segment = []
+            continue
+        if token in ("|", "||", "&&"):
+            targets.extend(_extract_command_targets(segment, workspace, current_dir))
+            segment = []
+            continue
+        segment.append(token)
+    return targets
+
+
+def _extract_command_targets(words: list[str], workspace: str, current_dir: Path) -> list[str]:
+    if not words:
+        return []
+    prog = _program(words).lower()
+    result: list[str] = []
+
+    for index, word in enumerate(words[:-1]):
+        if word in (">", ">>"):
+            result.extend(_resolve_targets([words[index + 1]], current_dir))
+    for word in words:
+        if word.startswith("of=") and len(word) > 3:
+            result.extend(_resolve_targets([word[3:]], current_dir))
+
+    arg_idx = _FS_WRITE_COMMANDS.get(prog)
+    if arg_idx is None:
+        return result
+    if arg_idx == 0:
+        return result
+
+    args = _program_args(words)
+    raw_targets: list[str] = []
+    if arg_idx > 0:
+        raw_targets = [w for w in args if not w.startswith("-")]
+    elif arg_idx == -1 and len(args) >= 2:
+        dest = args[-1]
+        if not dest.startswith("-"):
+            raw_targets = [dest]
+
+    result.extend(_resolve_targets(raw_targets, current_dir))
+    return result
+
+
+def _resolve_targets(raw_targets: list[str], current_dir: Path) -> list[str]:
+    result: list[str] = []
+    for target in raw_targets:
+        clean = target.strip('"').strip("'")
+        if not clean or clean.startswith("&") or clean.startswith("/dev/"):
+            continue
+        path = Path(clean).expanduser()
+        result.append(str(path if path.is_absolute() else current_dir / path))
+    return result
+
+
+def _program(words: list[str]) -> str:
+    for word in words:
+        if "=" in word and not word.startswith("=") and word.split("=", 1)[0].isidentifier():
+            continue
+        return word
+    return ""
+
+
+def _program_args(words: list[str]) -> list[str]:
+    prog_seen = False
+    args: list[str] = []
+    for word in words:
+        if not prog_seen:
+            if "=" in word and not word.startswith("=") and word.split("=", 1)[0].isidentifier():
+                continue
+            prog_seen = True
+            continue
+        args.append(word)
+    return args
+
+
+def _first_non_flag_arg(words: list[str]) -> str:
+    for word in words:
+        if not word.startswith("-"):
+            return word
+    return ""
+
+
+def _is_git_push_outside(
+    prog: str,
+    words: list[str],
+    workspace: str,
+    extra_paths: list[str],
+) -> bool:
+    """Check if git push modifies something beyond the workspace.
+
+    In workspace-write mode, git push to any remote can write outside the
+    local filesystem. Extra local write paths do not authorize remote writes.
+    """
+    if prog != "git" or len(words) < 2:
+        return False
+    if words[1] != "push":
+        return False
+    return True
+
+
+# ── export ───────────────────────────────────────────────────────────
+
+__all__ = ["check_sandbox_filepath", "check_sandbox_bash"]

voidx/permission/schema.py

@@ -0,0 +1,24 @@
+"""Permission types — aligned with opencode PermissionV2."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+Action = Literal["allow", "deny", "ask"]
+
+
+class Rule(BaseModel):
+    """A single permission rule.
+
+    permission: tool name or "*" (matches any tool)
+    pattern:    wildcard pattern for matching tool arguments (default "*")
+    action:     allow | deny | ask
+    """
+    permission: str
+    pattern: str = "*"
+    action: Action = "ask"
+
+
+Ruleset = list[Rule]

voidx/permission/service.py

@@ -0,0 +1,314 @@
+"""Permission service — user-facing permission state and compatibility helpers.
+
+Default rules: read-only tools are auto-allowed, write/bash/agent implement need approval.
+
+Session whitelist: once user says "always", the tool is remembered.
+Manage via /allow <tool>, /deny <tool>, /permissions commands.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+
+from pydantic import BaseModel
+
+from voidx.config import ApprovalReviewer, PermissionMode, permission_mode_defaults, permission_mode_reviewer_default
+from voidx.permission.engine import (
+    BASIC_RULES,
+    PermissionContext,
+    authorize_tool_call,
+    classify_tool_call,
+    sandbox_denial_reason,
+    tool_call_from_pattern,
+)
+from voidx.permission.schema import Action
+from voidx.ui.console import VoidConsole
+
+ui = VoidConsole()
+
+
+DEFAULT_RULES = BASIC_RULES
+
+# ── types ──────────────────────────────────────────────────────────────────
+
+class PermissionRequest(BaseModel):
+    id: str
+    session_id: str
+    tool: str
+    patterns: list[str]
+    metadata: dict = {}
+
+
+@dataclass
+class PendingEntry:
+    info: PermissionRequest
+    future: asyncio.Future
+
+
+class PermissionRejectedError(Exception):
+    def __init__(self, tool: str, pattern: str):
+        self.tool = tool
+        self.pattern = pattern
+        super().__init__(f"User rejected {tool} → {pattern}")
+
+
+# ── service ────────────────────────────────────────────────────────────────
+
+class PermissionService:
+    """Checks tool permissions with sandbox → defaults → session whitelist → ask flow."""
+
+    def __init__(
+        self,
+        permission_mode: str = "default",
+        sandbox_mode: str = "workspace-write",
+        sandbox_workspace_write: list[str] | None = None,
+        approval_policy: str = "untrusted",
+        approval_reviewer: str = "user",
+    ) -> None:
+        self._pending: dict[str, PendingEntry] = {}
+        # Session whitelist: tools the user has approved for this session
+        self._session_allow: set[str] = set()
+        self._session_deny: set[str] = set()
+        # Sandbox / approval — persistent filesystem + frequency controls
+        try:
+            parsed_mode = PermissionMode(permission_mode)
+        except ValueError:
+            parsed_mode = PermissionMode.CUSTOM
+        if (
+            parsed_mode == PermissionMode.DEFAULT
+            and (
+                sandbox_mode != "workspace-write"
+                or approval_policy != "untrusted"
+                or approval_reviewer != "user"
+            )
+        ):
+            parsed_mode = PermissionMode.CUSTOM
+        self.permission_mode = parsed_mode.value
+        if parsed_mode == PermissionMode.CUSTOM:
+            self.sandbox_mode = sandbox_mode
+            self.approval_policy = approval_policy
+            self.approval_reviewer = approval_reviewer
+        else:
+            mode_sandbox, mode_approval = permission_mode_defaults(parsed_mode)
+            self.sandbox_mode = mode_sandbox.value
+            self.approval_policy = mode_approval.value
+            self.approval_reviewer = permission_mode_reviewer_default(parsed_mode).value
+        self.sandbox_workspace_write = sandbox_workspace_write or []
+
+    # ── session whitelist management ─────────────────────────────────────
+
+    def allow(self, tool: str) -> None:
+        """Pre-approve a tool for the entire session. No more prompts."""
+        self._session_allow.add(tool)
+        self._session_deny.discard(tool)
+        ui.print(f"[dim]✓ {tool} now allowed for this session[/dim]")
+
+    def allow_silent(self, tool: str) -> None:
+        """Pre-approve a tool for the session without UI noise."""
+        self._session_allow.add(tool)
+        self._session_deny.discard(tool)
+
+    def deny(self, tool: str) -> None:
+        """Block a tool for the entire session."""
+        self._session_deny.add(tool)
+        self._session_allow.discard(tool)
+        ui.print(f"[dim]✗ {tool} now denied for this session[/dim]")
+
+    def deny_silent(self, tool: str) -> None:
+        """Block a tool for the session without UI noise."""
+        self._session_deny.add(tool)
+        self._session_allow.discard(tool)
+
+    def status_label(self) -> str:
+        if not self._session_allow and not self._session_deny:
+            return self.permission_mode_label()
+        parts: list[str] = [self.permission_mode_label()]
+        if self._session_allow:
+            parts.append(f"+{len(self._session_allow)}")
+        if self._session_deny:
+            parts.append(f"-{len(self._session_deny)}")
+        return " ".join(parts)
+
+    def set_permission_mode(self, mode: str) -> None:
+        try:
+            parsed = PermissionMode(mode)
+        except ValueError:
+            parsed = PermissionMode.CUSTOM
+        self.permission_mode = parsed.value
+        if parsed == PermissionMode.CUSTOM:
+            return
+        sandbox_mode, approval_policy = permission_mode_defaults(parsed)
+        self.sandbox_mode = sandbox_mode.value
+        self.approval_policy = approval_policy.value
+        self.approval_reviewer = permission_mode_reviewer_default(parsed).value
+        self.sandbox_workspace_write = []
+
+    def mark_custom_mode(self) -> None:
+        self.permission_mode = PermissionMode.CUSTOM.value
+
+    def permission_mode_label(self) -> str:
+        labels = {
+            PermissionMode.DEFAULT.value: "Default",
+            PermissionMode.READ_ONLY.value: "Read only",
+            PermissionMode.ACCEPT_EDITS.value: "Accept edits",
+            PermissionMode.AUTO_REVIEW.value: "Auto review",
+            PermissionMode.FULL_ACCESS.value: "Full access",
+            PermissionMode.CUSTOM.value: "Custom",
+        }
+        return labels.get(self.permission_mode, "Custom")
+
+    def status_details(self) -> tuple[str, str, str]:
+        """Return (sandbox_label, approval_label, session_label) for UI."""
+        return (
+            self._sandbox_label(),
+            self._approval_label(),
+            self._session_short(),
+        )
+
+    def _sandbox_label(self) -> str:
+        if self.sandbox_mode == "read-only":
+            return "r-o"
+        if self.sandbox_mode == "workspace-write":
+            return "w-write"
+        return "danger"
+
+    def _sandbox_short(self) -> str:
+        labels = {
+            "read-only": "r-o",
+            "workspace-write": "w-write",
+            "danger-full-access": "danger",
+        }
+        return labels.get(self.sandbox_mode, self.sandbox_mode)
+
+    def _approval_label(self) -> str:
+        labels = {
+            "untrusted": "ask",
+            "on-failure": "on-fail",
+            "on-request": "on-req",
+            "never": "auto",
+        }
+        return labels.get(self.approval_policy, self.approval_policy)
+
+    def _reviewer_label(self) -> str:
+        labels = {
+            ApprovalReviewer.USER.value: "user",
+            ApprovalReviewer.AUTO_REVIEW.value: "reviewer",
+        }
+        return labels.get(self.approval_reviewer, self.approval_reviewer)
+
+    def _session_short(self) -> str:
+        if self._session_allow and not self._session_deny:
+            return f"+{len(self._session_allow)}"
+        if self._session_deny and not self._session_allow:
+            return f"-{len(self._session_deny)}"
+        if self._session_allow and self._session_deny:
+            return f"+{len(self._session_allow)}/-{len(self._session_deny)}"
+        return "default"
+
+    def show_rules(self) -> str:
+        """Format current sandbox, approval, and session rules."""
+        lines = ["[bold]Session permissions:[/bold]"]
+        lines.append(f"  Mode: [cyan]{self.permission_mode_label()}[/cyan] ({self.permission_mode})")
+        lines.append(
+            f"  Sandbox: [cyan]{self.sandbox_mode}[/cyan]  "
+            f"Approval: [cyan]{self.approval_policy}[/cyan]  "
+            f"Reviewer: [cyan]{self.approval_reviewer}[/cyan]"
+        )
+        if self.sandbox_workspace_write:
+            lines.append(f"  Extra write paths: [dim]{', '.join(self.sandbox_workspace_write)}[/dim]")
+        lines.append("  [green]Always allowed:[/green] read, glob, grep, webfetch, websearch, todo, task_status, repo_map, lsp read tools, read-only agents, read-only bash")
+        if self._session_allow:
+            lines.append(f"  [green]Session allow:[/green] {', '.join(sorted(self._session_allow))}")
+        if self._session_deny:
+            lines.append(f"  [red]Session deny:[/red] {', '.join(sorted(self._session_deny))}")
+        lines.append("  [yellow]Ask first:[/yellow] write, edit, write-capable bash, lsp_format, agent=implement, mcp__*")
+        lines.append("")
+        lines.append("  Commands: /permission-mode  /allow <tool>  /deny <tool>  /sandbox [r-o|w-write|danger]  /approval [ask|on-fail|auto]")
+        return "\n".join(lines)
+
+    # ── sandbox ──────────────────────────────────────────────────────────
+
+    def check_sandbox(self, tool_name: str, args: dict, workspace: str) -> str | None:
+        """Sandbox layer: filesystem boundary enforcement.
+
+        Returns None if the tool call is allowed, or a human-readable
+        rejection reason.  Always returns None under danger-full-access.
+        """
+        if self.sandbox_mode == "danger-full-access":
+            return None
+
+        context = self._context(workspace=workspace)
+        return sandbox_denial_reason(
+            classify_tool_call({"name": tool_name, "args": args}),
+            context,
+        )
+
+    # ── check ────────────────────────────────────────────────────────────
+
+    async def check(
+        self,
+        tool: str,
+        pattern: str = "*",
+        session_id: str = "default",
+    ) -> Action:
+        """Check permission. Evaluates: defaults → session whitelist → ask.
+
+        Returns "allow" (proceed) or "deny" (block silently).
+        Raises PermissionRejectedError if user rejects the interactive ask.
+        """
+        action = self.decide(tool, pattern)
+        if action != "ask":
+            return action
+        return await self._ask_user(tool, pattern, session_id)
+
+    def decide(self, tool: str, pattern: str = "*") -> Action:
+        """Return the non-interactive permission decision for a tool call."""
+        return authorize_tool_call(tool_call_from_pattern(tool, pattern), self._context()).action
+
+    async def _ask_user(self, tool: str, pattern: str, session_id: str) -> Action:
+        """Interactive ask — simple text input, no raw key artifacts."""
+        ui.print("")
+        ui.print(f"  [yellow]Allow [bold]{tool}[/bold] → {pattern}?[/yellow]")
+        ui.print(f"  [a] Always  [y] Yes once  [n] No")
+        try:
+            choice = await asyncio.get_event_loop().run_in_executor(
+                None, lambda: input("  > ").strip().lower()
+            )
+        except (EOFError, KeyboardInterrupt):
+            return "deny"
+
+        if choice in ("a", "always"):
+            self._session_allow.add(tool)
+            ui.print(f"[dim]✓ {tool} allowed for this session[/dim]")
+            return "allow"
+        elif choice in ("y", "yes", ""):
+            return "allow"
+        else:
+            return "deny"
+
+    def list_pending(self) -> list[PermissionRequest]:
+        return [entry.info for entry in self._pending.values()]
+
+    def clear(self) -> None:
+        for entry in self._pending.values():
+            if not entry.future.done():
+                entry.future.set_result("deny")
+        self._pending.clear()
+
+    def clear_session_permissions(self) -> None:
+        """Reset session allow/deny whitelists."""
+        self._session_allow.clear()
+        self._session_deny.clear()
+
+    def _context(self, *, workspace: str = ".") -> PermissionContext:
+        return PermissionContext(
+            workspace=workspace,
+            permission_mode=self.permission_mode,
+            sandbox_mode=self.sandbox_mode,
+            sandbox_workspace_write=tuple(self.sandbox_workspace_write),
+            approval_policy=self.approval_policy,
+            approval_reviewer=self.approval_reviewer,
+            session_allow=frozenset(self._session_allow),
+            session_deny=frozenset(self._session_deny),
+        )

voidx/permission/wildcard.py

@@ -0,0 +1,34 @@
+"""Wildcard pattern matching — aligned with opencode Wildcard.match()."""
+
+import re
+import sys
+
+
+def match(input_str: str, pattern: str) -> bool:
+    """Match string against wildcard pattern.
+
+    *  → .*
+    ?  → .
+    /  ↔ \\  normalized for cross-platform
+
+    Examples:
+      match("bash", "*") → True
+      match("read", "edit") → False
+      match(".env", "*.env") → True
+      match("git push", "git *") → True
+      match("src/foo.py", "src/**/*.py") → True  (** treated as *)
+    """
+    normalized = input_str.replace("\\", "/")
+
+    escaped = (
+        pattern.replace("\\", "/")
+        .replace("**", "*")  # ** is same as * for our purposes
+    )
+
+    # Escape regex specials, then convert wildcards
+    escaped = re.escape(escaped)
+    escaped = escaped.replace(r"\*", ".*")
+    escaped = escaped.replace(r"\?", ".")
+
+    flags = re.IGNORECASE if sys.platform == "win32" else re.NOFLAG
+    return bool(re.match("^" + escaped + "$", normalized, flags))

voidx/skills/__init__.py

@@ -0,0 +1,18 @@
+"""Local skill support for voidx."""
+
+from __future__ import annotations
+
+from voidx.skills.registry import SkillParseError, SkillRegistry, parse_skill_file
+from voidx.skills.schema import SkillDefinition, SkillMatch, SkillMeta, SkillSelectionConfig
+from voidx.skills.service import SkillService
+
+__all__ = [
+    "SkillDefinition",
+    "SkillMatch",
+    "SkillMeta",
+    "SkillParseError",
+    "SkillRegistry",
+    "SkillSelectionConfig",
+    "SkillService",
+    "parse_skill_file",
+]