scc-cli 1.4.1__py3-none-any.whl

scc_cli/marketplace/trust.py

@@ -0,0 +1,244 @@
+"""Trust validation for federated team configurations (Phase 2).
+
+This module provides:
+- TrustViolationError: Raised when a team violates org trust grants
+- SecurityViolationError: Raised when org security policies are violated
+- validate_marketplace_source(): Validate marketplace URL against patterns
+- validate_team_config_trust(): Two-layer validation for team configs
+- get_source_url(): Extract URL from any MarketplaceSource type
+
+Trust Model:
+    Orgs define trust grants that control what teams can do:
+    - inherit_org_marketplaces: Can team use org's marketplaces?
+    - allow_additional_marketplaces: Can team define their own?
+    - marketplace_source_patterns: Which URLs are allowed for team marketplaces?
+
+Security Model:
+    Org security rules (blocked_plugins, etc.) are ALWAYS enforced,
+    regardless of team configuration or trust grants.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from scc_cli.marketplace.constants import IMPLICIT_MARKETPLACES
+from scc_cli.marketplace.normalize import (
+    matches_any_url_pattern,
+    normalize_url_for_matching,
+)
+
+if TYPE_CHECKING:
+    from scc_cli.marketplace.schema import (
+        MarketplaceSource,
+        TeamConfig,
+        TrustGrant,
+    )
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Exceptions
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+class TrustViolationError(ValueError):
+    """Raised when a federated team violates org trust grants.
+
+    This occurs when a team:
+    - Defines marketplaces without allow_additional_marketplaces
+    - Uses marketplace sources not matching allowed patterns
+    - Defines a marketplace name that conflicts with org/implicit marketplaces
+    """
+
+    def __init__(self, team_name: str, violation: str) -> None:
+        self.team_name = team_name
+        self.violation = violation
+        super().__init__(f"Trust violation for team '{team_name}': {violation}")
+
+
+class SecurityViolationError(ValueError):
+    """Raised when org security policies are violated.
+
+    This occurs when:
+    - A plugin matches security.blocked_plugins pattern
+    - A plugin references a blocked marketplace
+    - Other org-level security rules are violated
+
+    Security rules are ALWAYS enforced, regardless of trust grants.
+    """
+
+    def __init__(self, plugin_ref: str, reason: str) -> None:
+        self.plugin_ref = plugin_ref
+        self.reason = reason
+        super().__init__(f"Security violation: Plugin '{plugin_ref}' blocked - {reason}")
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Helper Functions
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def get_source_url(source: MarketplaceSource) -> str | None:
+    """Extract URL from any MarketplaceSource type for pattern matching.
+
+    Args:
+        source: Any MarketplaceSource variant (GitHub, Git, URL, Directory)
+
+    Returns:
+        Normalized URL string for remote sources, None for directory sources
+
+    Examples:
+        >>> get_source_url(MarketplaceSourceGitHub(source="github", owner="org", repo="plugins"))
+        'github.com/org/plugins'
+
+        >>> get_source_url(MarketplaceSourceDirectory(source="directory", path="/local"))
+        None
+    """
+    # Import here to avoid circular imports
+    from scc_cli.marketplace.schema import (
+        MarketplaceSourceDirectory,
+        MarketplaceSourceGit,
+        MarketplaceSourceGitHub,
+        MarketplaceSourceURL,
+    )
+
+    if isinstance(source, MarketplaceSourceGitHub):
+        # Construct GitHub URL: github.com/owner/repo
+        return f"github.com/{source.owner}/{source.repo}"
+
+    if isinstance(source, MarketplaceSourceGit):
+        # Normalize the git clone URL
+        return normalize_url_for_matching(source.url)
+
+    if isinstance(source, MarketplaceSourceURL):
+        # Normalize the HTTPS URL
+        return normalize_url_for_matching(source.url)
+
+    if isinstance(source, MarketplaceSourceDirectory):
+        # Directory sources are local, no URL to match
+        return None
+
+    # Unknown source type - shouldn't happen with proper typing
+    return None
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Validation Functions
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def validate_marketplace_source(
+    source: MarketplaceSource,
+    allowed_patterns: list[str],
+    team_name: str,
+) -> None:
+    """Validate a marketplace source against allowed URL patterns.
+
+    Directory sources are always allowed (org-local).
+    Remote sources must match at least one allowed pattern.
+
+    Args:
+        source: MarketplaceSource to validate
+        allowed_patterns: List of URL glob patterns (with ** support)
+        team_name: Team name for error messages
+
+    Raises:
+        TrustViolationError: If source doesn't match any allowed pattern
+    """
+    url = get_source_url(source)
+
+    # Directory sources are org-local, always allowed
+    if url is None:
+        return
+
+    # Remote sources must match an allowed pattern
+    if not allowed_patterns:
+        raise TrustViolationError(
+            team_name=team_name,
+            violation=(
+                f"Marketplace source '{url}' not allowed (no patterns defined). "
+                "Ask org admin to add marketplace_source_patterns to the team's trust grant."
+            ),
+        )
+
+    matched = matches_any_url_pattern(url, allowed_patterns)
+    if matched is None:
+        patterns_str = ", ".join(allowed_patterns)
+        raise TrustViolationError(
+            team_name=team_name,
+            violation=(
+                f"Marketplace source '{url}' doesn't match any allowed pattern. "
+                f"Allowed patterns: [{patterns_str}]. "
+                "Ask org admin to add a matching pattern, or use an allowed source."
+            ),
+        )
+
+
+def validate_team_config_trust(
+    team_config: TeamConfig,
+    trust: TrustGrant,
+    team_name: str,
+    org_marketplaces: dict[str, Any],
+) -> None:
+    """Validate team config against trust grants (two-layer validation).
+
+    Layer 1: Check if team is allowed to define marketplaces at all
+    Layer 2: Validate each marketplace source against allowed patterns
+
+    Also checks for marketplace name collisions with:
+    - Org-defined marketplaces (keys in org_marketplaces)
+    - Implicit marketplaces (claude-plugins-official, etc.)
+
+    Args:
+        team_config: External team configuration to validate
+        trust: Trust grant from org to this team
+        team_name: Team name for error messages
+        org_marketplaces: Dict of org-defined marketplaces (for collision check)
+
+    Raises:
+        TrustViolationError: If team violates any trust constraint
+    """
+    # No marketplaces defined - nothing to validate
+    if not team_config.marketplaces:
+        return
+
+    # Layer 1: Check if team is allowed to define marketplaces
+    if not trust.allow_additional_marketplaces:
+        names = list(team_config.marketplaces.keys())
+        raise TrustViolationError(
+            team_name=team_name,
+            violation=(
+                f"Team defines marketplaces ({names}) but trust grant has "
+                "allow_additional_marketplaces=False. Ask org admin to enable."
+            ),
+        )
+
+    # Check for marketplace name collisions
+    for mp_name in team_config.marketplaces:
+        # Collision with org marketplace?
+        if mp_name in org_marketplaces:
+            raise TrustViolationError(
+                team_name=team_name,
+                violation=(
+                    f"Team marketplace '{mp_name}' conflicts with org-defined marketplace. "
+                    "Choose a different name."
+                ),
+            )
+
+        # Collision with implicit marketplace?
+        if mp_name in IMPLICIT_MARKETPLACES:
+            raise TrustViolationError(
+                team_name=team_name,
+                violation=(
+                    f"Team marketplace '{mp_name}' conflicts with implicit marketplace. "
+                    f"Reserved names: {list(IMPLICIT_MARKETPLACES)}. Choose a different name."
+                ),
+            )
+
+    # Layer 2: Validate each marketplace source against allowed patterns
+    for mp_name, source in team_config.marketplaces.items():
+        validate_marketplace_source(
+            source=source,
+            allowed_patterns=trust.marketplace_source_patterns,
+            team_name=team_name,
+        )

scc_cli/models/__init__.py

@@ -0,0 +1,41 @@
+"""Data models for SCC exception system and plugin audit."""
+
+from scc_cli.models.exceptions import (
+    AllowTargets,
+    BlockReason,
+    Exception,
+    ExceptionFile,
+    exception_file_from_json,
+    exception_file_to_json,
+    generate_local_id,
+)
+from scc_cli.models.plugin_audit import (
+    AuditOutput,
+    HookInfo,
+    ManifestResult,
+    ManifestStatus,
+    MCPServerInfo,
+    ParseError,
+    PluginAuditResult,
+    PluginManifests,
+)
+
+__all__ = [
+    # Exception system models
+    "AllowTargets",
+    "BlockReason",
+    "Exception",
+    "ExceptionFile",
+    "exception_file_from_json",
+    "exception_file_to_json",
+    "generate_local_id",
+    # Plugin audit models
+    "AuditOutput",
+    "HookInfo",
+    "ManifestResult",
+    "ManifestStatus",
+    "MCPServerInfo",
+    "ParseError",
+    "PluginAuditResult",
+    "PluginManifests",
+]

scc_cli/models/exceptions.py

@@ -0,0 +1,273 @@
+"""Define exception system data models for SCC Phase 2.1.
+
+Provide the core data structures for the time-bounded exception system
+that lets developers unblock themselves from delegation failures while
+preserving security boundaries.
+
+Key concepts:
+- BlockReason: Distinguishes SECURITY (policy-only override) from
+  DELEGATION (local override allowed)
+- AllowTargets: Specifies plugins, mcp_servers, base_images to allow
+- Exception: A single time-bounded exception with metadata
+- ExceptionFile: Envelope with schema versioning for forward compatibility
+"""
+
+from __future__ import annotations
+
+import json
+import secrets
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Literal
+
+
+class BlockReason(Enum):
+    """Classifies why something was blocked.
+
+    SECURITY: Blocked by org security policy. Only policy exceptions
+              (PR-approved) can override.
+    DELEGATION: Denied because team not delegated for additions.
+                Local overrides (self-serve) can unblock.
+    """
+
+    SECURITY = "security"
+    DELEGATION = "delegation"
+
+
+@dataclass
+class AllowTargets:
+    """Specifies what an exception allows.
+
+    SCC-shaped targets only:
+    - plugins: Plugin IDs/names to allow
+    - mcp_servers: SCC-managed MCP server names to allow
+    - base_images: Docker image refs/patterns to allow
+    """
+
+    plugins: list[str] = field(default_factory=list)
+    mcp_servers: list[str] = field(default_factory=list)
+    base_images: list[str] = field(default_factory=list)
+
+    def is_empty(self) -> bool:
+        """Return True if no targets are specified."""
+        return not self.plugins and not self.mcp_servers and not self.base_images
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to dictionary."""
+        return {
+            "plugins": self.plugins,
+            "mcp_servers": self.mcp_servers,
+            "base_images": self.base_images,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> AllowTargets:
+        """Deserialize from dictionary, handling missing keys gracefully."""
+        return cls(
+            plugins=d.get("plugins", []),
+            mcp_servers=d.get("mcp_servers", []),
+            base_images=d.get("base_images", []),
+        )
+
+
+@dataclass
+class Exception:
+    """A time-bounded exception that allows specific resources.
+
+    Required fields:
+    - id: Unique identifier (local-YYYYMMDD-XXXX for local, user-provided for policy)
+    - created_at: RFC3339 timestamp in UTC
+    - expires_at: RFC3339 timestamp in UTC
+    - reason: Required non-empty explanation
+    - scope: "policy" or "local"
+    - allow: AllowTargets specifying what to allow
+
+    Optional metadata:
+    - created_by: Username/email of creator
+    - created_on: Hostname where created
+    - source: Derived at runtime (org|team|project|repo|user)
+
+    Forward compatibility:
+    - _extra: Dict preserving unknown fields from newer schema versions
+    """
+
+    id: str
+    created_at: str
+    expires_at: str
+    reason: str
+    scope: Literal["policy", "local"]
+    allow: AllowTargets
+
+    # Optional metadata
+    created_by: str | None = None
+    created_on: str | None = None
+    source: str | None = None
+
+    # Forward compatibility
+    _extra: dict[str, Any] = field(default_factory=dict)
+
+    def is_expired(self) -> bool:
+        """Return True if exception has expired."""
+        now = datetime.now(timezone.utc)
+        # Parse expires_at as RFC3339
+        expires = datetime.fromisoformat(self.expires_at.replace("Z", "+00:00"))
+        return now > expires
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to dictionary, including _extra fields."""
+        result: dict[str, Any] = {
+            "id": self.id,
+            "created_at": self.created_at,
+            "expires_at": self.expires_at,
+            "reason": self.reason,
+            "scope": self.scope,
+            "allow": self.allow.to_dict(),
+        }
+
+        # Add optional metadata if present
+        if self.created_by is not None:
+            result["created_by"] = self.created_by
+        if self.created_on is not None:
+            result["created_on"] = self.created_on
+        if self.source is not None:
+            result["source"] = self.source
+
+        # Include _extra fields at top level for roundtrip
+        result.update(self._extra)
+
+        return result
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> Exception:
+        """Deserialize from dictionary, preserving unknown fields in _extra."""
+        known_keys = {
+            "id",
+            "created_at",
+            "expires_at",
+            "reason",
+            "scope",
+            "allow",
+            "created_by",
+            "created_on",
+            "source",
+        }
+
+        # Extract _extra fields
+        extra = {k: v for k, v in d.items() if k not in known_keys}
+
+        return cls(
+            id=d["id"],
+            created_at=d["created_at"],
+            expires_at=d["expires_at"],
+            reason=d["reason"],
+            scope=d["scope"],
+            allow=AllowTargets.from_dict(d.get("allow", {})),
+            created_by=d.get("created_by"),
+            created_on=d.get("created_on"),
+            source=d.get("source"),
+            _extra=extra,
+        )
+
+
+@dataclass
+class ExceptionFile:
+    """Envelope for exception storage with schema versioning.
+
+    Provides forward compatibility through:
+    - schema_version: Current schema version (1)
+    - tool_version: SCC version that wrote the file
+    - min_scc_version: Minimum SCC version required to parse
+    - _extra: Preserves unknown fields for roundtrip
+
+    When reading files:
+    - Local stores with newer schema: warn + ignore (fail-open)
+    - Policy exceptions with newer schema: warn + ignore entirely (fail-closed)
+    """
+
+    schema_version: int = 1
+    tool_version: str | None = None
+    min_scc_version: str | None = None
+    exceptions: list[Exception] = field(default_factory=list)
+    _extra: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to dictionary with stable exception ordering."""
+        # Sort exceptions by created_at, then by id for stable ordering
+        sorted_exceptions = sorted(
+            self.exceptions,
+            key=lambda e: (e.created_at, e.id),
+        )
+
+        result: dict[str, Any] = {
+            "schema_version": self.schema_version,
+            "exceptions": [e.to_dict() for e in sorted_exceptions],
+        }
+
+        # Add optional metadata if present
+        if self.tool_version is not None:
+            result["tool_version"] = self.tool_version
+        if self.min_scc_version is not None:
+            result["min_scc_version"] = self.min_scc_version
+
+        # Include _extra fields at top level
+        result.update(self._extra)
+
+        return result
+
+    def to_json(self) -> str:
+        """Serialize to JSON with sorted keys and 2-space indentation."""
+        return json.dumps(self.to_dict(), sort_keys=True, indent=2)
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> ExceptionFile:
+        """Deserialize from dictionary, preserving unknown fields."""
+        known_keys = {
+            "schema_version",
+            "tool_version",
+            "min_scc_version",
+            "exceptions",
+        }
+
+        # Extract _extra fields
+        extra = {k: v for k, v in d.items() if k not in known_keys}
+
+        # Parse exceptions list
+        exceptions = [Exception.from_dict(e) for e in d.get("exceptions", [])]
+
+        return cls(
+            schema_version=d.get("schema_version", 1),
+            tool_version=d.get("tool_version"),
+            min_scc_version=d.get("min_scc_version"),
+            exceptions=exceptions,
+            _extra=extra,
+        )
+
+    @classmethod
+    def from_json(cls, json_str: str) -> ExceptionFile:
+        """Parse JSON string into ExceptionFile."""
+        return cls.from_dict(json.loads(json_str))
+
+
+def generate_local_id() -> str:
+    """Generate a unique local exception ID.
+
+    Format: local-YYYYMMDD-XXXX
+    Where XXXX is 4 random hex characters.
+
+    Example: local-20251221-a3f2
+    """
+    today = datetime.now(timezone.utc).strftime("%Y%m%d")
+    random_hex = secrets.token_hex(2)  # 2 bytes = 4 hex chars
+    return f"local-{today}-{random_hex}"
+
+
+# Convenience functions for JSON operations
+def exception_file_to_json(ef: ExceptionFile) -> str:
+    """Serialize ExceptionFile to JSON string."""
+    return ef.to_json()
+
+
+def exception_file_from_json(json_str: str) -> ExceptionFile:
+    """Parse JSON string into ExceptionFile."""
+    return ExceptionFile.from_json(json_str)