oasr 0.5.0__py3-none-any.whl

policy/__init__.py

@@ -0,0 +1,50 @@
+"""Execution policy system for OASR.
+
+Enforces host-level security boundaries for skill execution by defining what
+agents can and cannot do. Policy profiles are user-defined in config.toml and
+enforced at runtime before agent invocation.
+
+Usage:
+    import policy
+
+    # Load profile from config
+    profile = policy.load(config, "safe")
+
+    # Assess risk
+    needs_confirm, reasons = policy.assess_risk(
+        profile,
+        stdin_used=True,
+        instructions_file_used=False
+    )
+
+    # Get confirmation if needed
+    if needs_confirm:
+        summary = policy.summarize(profile, skill_name, agent_name)
+        if not policy.prompt_confirmation(summary, reasons):
+            return 1  # aborted
+
+This module does NOT:
+- Detect prompt injection via NLP
+- Rewrite or sanitize prompts
+- Validate skill correctness
+- Implement agent-specific permissions
+
+It DOES:
+- Load and validate policy profiles from config
+- Assess execution risk based on context
+- Require explicit confirmation for risky operations
+- Fail closed with conservative defaults
+"""
+
+from policy.defaults import SAFE as SAFE_DEFAULTS
+from policy.enforcement import assess_risk, prompt_confirmation
+from policy.profile import Profile, load, summarize
+
+__all__ = [
+    "Profile",
+    "load",
+    "summarize",
+    "assess_risk",
+    "prompt_confirmation",
+    "SAFE_DEFAULTS",
+]

policy/defaults.py

@@ -0,0 +1,27 @@
+"""Safe default execution policy profile.
+
+Conservative defaults that fail closed. Used when:
+- No config exists
+- Requested profile not found
+- Config parsing errors occur
+"""
+
+# Safe default profile - conservative and restrictive
+SAFE = {
+    "fs_read_roots": ["./"],
+    "fs_write_roots": ["./out", "./.oasr"],
+    "deny_paths": [
+        "~/.ssh",
+        "~/.aws",
+        "~/.gnupg",
+        "~/.config",
+        ".env",
+        "~/.bashrc",
+        "~/.zshrc",
+        "~/.profile",
+    ],
+    "allowed_commands": ["rg", "fd", "jq", "cat"],
+    "deny_shell": True,
+    "network": False,
+    "allow_env": False,
+}

policy/enforcement.py

@@ -0,0 +1,98 @@
+"""Policy enforcement logic - risk assessment and confirmation prompts.
+
+Determines when execution requires user confirmation and handles the
+confirmation flow.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from policy.profile import Profile
+
+
+def assess_risk(
+    profile: Profile,
+    stdin_used: bool,
+    instructions_file_used: bool,
+    force_confirm: bool = False,
+) -> tuple[bool, list[str]]:
+    """Determine if execution requires user confirmation based on risk triggers.
+
+    Risk triggers:
+    1. Input from stdin (non-interactive) or file
+    2. Profile is not "safe"
+    3. Environment exposure enabled
+    4. Network enabled
+    5. Shell execution allowed
+    6. Force confirmation flag set
+
+    Args:
+        profile: Policy profile being used
+        stdin_used: True if stdin is non-tty (piped input)
+        instructions_file_used: True if prompt read from file
+        force_confirm: Force confirmation even if otherwise safe
+
+    Returns:
+        Tuple of (requires_confirmation, reasons)
+        where reasons is list of human-readable trigger descriptions
+    """
+    reasons = []
+
+    if force_confirm:
+        reasons.append("Explicit confirmation requested (--confirm)")
+
+    if stdin_used:
+        reasons.append("Input from stdin (non-interactive)")
+
+    if instructions_file_used:
+        reasons.append("Prompt loaded from file")
+
+    if profile.name != "safe":
+        reasons.append(f"Non-safe profile '{profile.name}' in use")
+
+    if profile.allow_env:
+        reasons.append("Environment variable access enabled")
+
+    if profile.network:
+        reasons.append("Network access enabled")
+
+    if not profile.deny_shell:
+        reasons.append("Shell execution allowed")
+
+    return (len(reasons) > 0, reasons)
+
+
+def prompt_confirmation(
+    policy_summary: str,
+    reasons: list[str],
+) -> bool:
+    """Display policy summary and prompt for user confirmation.
+
+    Args:
+        policy_summary: Formatted policy summary from profile.summarize()
+        reasons: List of risk trigger reasons
+
+    Returns:
+        True if user confirms, False otherwise
+
+    Notes:
+        - Writes to stderr (not stdout)
+        - Handles Ctrl+C gracefully (returns False)
+        - Default answer is No (safe)
+    """
+    print(policy_summary, file=sys.stderr)
+    print(file=sys.stderr)
+
+    if reasons:
+        print("⚠  This execution requires confirmation due to:", file=sys.stderr)
+        for reason in reasons:
+            print(f"   - {reason}", file=sys.stderr)
+        print(file=sys.stderr)
+
+    try:
+        response = input("Proceed? [y/N] ").strip().lower()
+        return response in ("y", "yes")
+    except (EOFError, KeyboardInterrupt):
+        print("\nAborted.", file=sys.stderr)
+        return False

policy/profile.py

@@ -0,0 +1,185 @@
+"""Policy profile definitions and loading.
+
+Defines what agents can do during skill execution. Profiles are user-defined
+in config.toml and enforced at runtime.
+"""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from policy.defaults import SAFE
+
+
+@dataclass
+class Profile:
+    """Execution policy profile defining agent capabilities and restrictions.
+
+    Attributes:
+        name: Profile identifier (e.g., "safe", "dev")
+        fs_read_roots: Allowed filesystem read locations
+        fs_write_roots: Allowed filesystem write locations
+        deny_paths: Explicitly denied paths (takes precedence)
+        allowed_commands: Permitted shell commands
+        deny_shell: If True, deny all shell/subprocess execution
+        network: Allow network access
+        allow_env: Allow reading environment variables
+    """
+
+    name: str
+    fs_read_roots: list[str] = field(default_factory=lambda: ["./"])
+    fs_write_roots: list[str] = field(default_factory=lambda: ["./out", "./.oasr"])
+    deny_paths: list[str] = field(
+        default_factory=lambda: [
+            "~/.ssh",
+            "~/.aws",
+            "~/.gnupg",
+            "~/.config",
+            ".env",
+            "~/.bashrc",
+            "~/.zshrc",
+            "~/.profile",
+        ]
+    )
+    allowed_commands: list[str] = field(default_factory=lambda: ["rg", "fd", "jq", "cat"])
+    deny_shell: bool = True
+    network: bool = False
+    allow_env: bool = False
+
+    def __post_init__(self):
+        """Resolve and normalize paths after initialization."""
+        self.fs_read_roots = [self._resolve_path(p) for p in self.fs_read_roots]
+        self.fs_write_roots = [self._resolve_path(p) for p in self.fs_write_roots]
+        self.deny_paths = [self._resolve_path(p) for p in self.deny_paths]
+
+    def _resolve_path(self, path: str) -> str:
+        """Resolve path: expand ~, make absolute if relative to cwd.
+
+        Relative paths are workspace-relative (relative to current directory).
+        Tilde (~) is expanded to user home directory.
+
+        Args:
+            path: Path string (may contain ~, be relative or absolute)
+
+        Returns:
+            Normalized absolute path string
+        """
+        p = Path(path).expanduser()
+        if not p.is_absolute():
+            p = Path.cwd() / p
+        return str(p.resolve())
+
+
+def load(config: dict[str, Any], profile_name: str, cwd: Path | None = None) -> Profile:
+    """Load a policy profile from config with fallback to safe defaults.
+
+    Args:
+        config: Full config dict (may contain profiles.<name> tables)
+        profile_name: Name of profile to load (e.g., "safe", "dev")
+        cwd: Working directory for relative path resolution (default: current)
+
+    Returns:
+        Profile with merged defaults + user overrides
+
+    Notes:
+        - Missing profiles fall back to hardcoded safe defaults
+        - Malformed config falls back to safe + logs warning
+        - All paths are resolved to absolute paths
+        - Fail-closed behavior: errors → safe defaults
+    """
+    if cwd:
+        # Temporarily change directory context for path resolution
+        import os
+
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(cwd)
+            return _load_impl(config, profile_name)
+        finally:
+            os.chdir(old_cwd)
+    else:
+        return _load_impl(config, profile_name)
+
+
+def _load_impl(config: dict[str, Any], profile_name: str) -> Profile:
+    """Internal implementation of load()."""
+    # Start with safe defaults
+    profile_data = SAFE.copy()
+
+    # Try to load user-defined profile
+    try:
+        profiles = config.get("profiles", {})
+        if profile_name in profiles:
+            user_profile = profiles[profile_name]
+            # Merge user overrides
+            for key in SAFE.keys():
+                if key in user_profile:
+                    profile_data[key] = user_profile[key]
+        elif profile_name != "safe":
+            # Warn if non-safe profile doesn't exist, but continue with safe defaults
+            print(
+                f"⚠ Warning: Profile '{profile_name}' not found in config. Using 'safe' defaults.",
+                file=sys.stderr,
+            )
+    except Exception as e:
+        # Fail closed: any error in config parsing → safe defaults
+        print(
+            f"⚠ Warning: Error loading profile config: {e}. Using 'safe' defaults.",
+            file=sys.stderr,
+        )
+
+    return Profile(name=profile_name, **profile_data)
+
+
+def summarize(profile: Profile, skill_name: str, agent_name: str) -> str:
+    """Generate human-readable policy summary for confirmation prompt.
+
+    Args:
+        profile: Policy profile to summarize
+        skill_name: Name of skill being executed
+        agent_name: Name of agent being used
+
+    Returns:
+        Formatted multi-line string suitable for stderr output
+    """
+    lines = [
+        "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
+        "EXECUTION POLICY REVIEW",
+        "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
+        f"Skill:             {skill_name}",
+        f"Agent:             {agent_name}",
+        f"Profile:           {profile.name}",
+        f"Network:           {'allowed' if profile.network else 'denied'}",
+        f"Environment:       {'allowed' if profile.allow_env else 'denied'}",
+        f"Shell:             {'allowed' if not profile.deny_shell else 'denied'}",
+    ]
+
+    # Format allowed commands (truncate if too long)
+    if profile.allowed_commands:
+        commands = ", ".join(profile.allowed_commands)
+        if len(commands) > 60:
+            commands = commands[:57] + "..."
+        lines.append(f"Allowed commands:  {commands}")
+    else:
+        lines.append("Allowed commands:  (none)")
+
+    # Format paths (show first few, indicate if more)
+    lines.append(f"Read roots:        {', '.join(profile.fs_read_roots[:3])}")
+    if len(profile.fs_read_roots) > 3:
+        lines.append(f"                   ... and {len(profile.fs_read_roots) - 3} more")
+
+    lines.append(f"Write roots:       {', '.join(profile.fs_write_roots[:3])}")
+    if len(profile.fs_write_roots) > 3:
+        lines.append(f"                   ... and {len(profile.fs_write_roots) - 3} more")
+
+    # Show some deny paths (not all - could be long)
+    if profile.deny_paths:
+        deny_sample = profile.deny_paths[:5]
+        lines.append(f"Deny paths:        {', '.join(deny_sample)}")
+        if len(profile.deny_paths) > 5:
+            lines.append(f"                   ... and {len(profile.deny_paths) - 5} more")
+
+    return "\n".join(lines)

registry.py

@@ -0,0 +1,173 @@
+"""Registry management for ~/.oasr/registry.toml."""
+
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
+import tomli_w
+
+from config import OASR_DIR, ensure_skills_dir
+from manifest import create_manifest, delete_manifest, save_manifest
+
+REGISTRY_FILE = OASR_DIR / "registry.toml"
+
+
+@dataclass
+class SkillEntry:
+    """A registered skill entry."""
+
+    path: str
+    name: str
+    description: str
+
+    def to_dict(self) -> dict[str, str]:
+        """Convert to dictionary for TOML serialization."""
+        return {
+            "path": self.path,
+            "name": self.name,
+            "description": self.description,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, str]) -> "SkillEntry":
+        """Create from dictionary."""
+        return cls(
+            path=data.get("path", ""),
+            name=data.get("name", ""),
+            description=data.get("description", ""),
+        )
+
+
+def load_registry(registry_path: Path | None = None) -> list[SkillEntry]:
+    """Load registry from TOML file.
+
+    Args:
+        registry_path: Override registry file path. Defaults to ~/.oasr/registry.toml.
+
+    Returns:
+        List of registered skill entries.
+    """
+    path = registry_path or REGISTRY_FILE
+
+    if not path.exists():
+        return []
+
+    with open(path, "rb") as f:
+        data = tomllib.load(f)
+
+    skills = data.get("skill", [])
+    return [SkillEntry.from_dict(s) for s in skills]
+
+
+def save_registry(entries: list[SkillEntry], registry_path: Path | None = None) -> None:
+    """Save registry to TOML file.
+
+    Args:
+        entries: List of skill entries to save.
+        registry_path: Override registry file path. Defaults to ~/.skills/registry.toml.
+    """
+    path = registry_path or REGISTRY_FILE
+    ensure_skills_dir()
+
+    data = {"skill": [e.to_dict() for e in entries]}
+
+    with open(path, "wb") as f:
+        tomli_w.dump(data, f)
+
+
+def add_skill(
+    entry: SkillEntry,
+    registry_path: Path | None = None,
+    create_manifest_artifact: bool = True,
+) -> bool:
+    """Add or update a skill in the registry.
+
+    Args:
+        entry: Skill entry to add.
+        registry_path: Override registry file path.
+        create_manifest_artifact: Whether to create/update the manifest artifact.
+
+    Returns:
+        True if skill was added, False if it was updated (already existed).
+    """
+    entries = load_registry(registry_path)
+    is_new = True
+
+    for i, existing in enumerate(entries):
+        if existing.name == entry.name or existing.path == entry.path:
+            entries[i] = entry
+            is_new = False
+            break
+
+    if is_new:
+        entries.append(entry)
+
+    save_registry(entries, registry_path)
+
+    if create_manifest_artifact:
+        manifest = create_manifest(
+            name=entry.name,
+            source_path=entry.path,  # Keep as string (can be URL or path)
+            description=entry.description,
+        )
+        save_manifest(manifest)
+
+    return is_new
+
+
+def remove_skill(
+    name_or_path: str,
+    registry_path: Path | None = None,
+    delete_manifest_artifact: bool = True,
+) -> bool:
+    """Remove a skill from the registry by name or path.
+
+    Args:
+        name_or_path: Skill name or path to remove.
+        registry_path: Override registry file path.
+        delete_manifest_artifact: Whether to delete the manifest artifact.
+
+    Returns:
+        True if skill was removed, False if not found.
+    """
+    entries = load_registry(registry_path)
+    removed_name = None
+
+    new_entries = []
+    for e in entries:
+        if e.name == name_or_path or e.path == name_or_path:
+            removed_name = e.name
+        else:
+            new_entries.append(e)
+
+    if removed_name:
+        save_registry(new_entries, registry_path)
+        if delete_manifest_artifact:
+            delete_manifest(removed_name)
+        return True
+
+    return False
+
+
+def find_skill(name_or_path: str, registry_path: Path | None = None) -> SkillEntry | None:
+    """Find a skill by name or path.
+
+    Args:
+        name_or_path: Skill name or path to find.
+        registry_path: Override registry file path.
+
+    Returns:
+        Skill entry if found, None otherwise.
+    """
+    entries = load_registry(registry_path)
+
+    for entry in entries:
+        if entry.name == name_or_path or entry.path == name_or_path:
+            return entry
+
+    return None