spanforge 1.0.0__py3-none-any.whl

spanforge/sdk/registry.pyi

@@ -0,0 +1,46 @@
+"""Type stubs for spanforge.sdk.registry (DX-001)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+class ServiceStatus(str, Enum):
+    UP = "up"
+    DEGRADED = "degraded"
+    DOWN = "down"
+
+@dataclass
+class ServiceHealth:
+    status: ServiceStatus = ServiceStatus.DOWN
+    latency_ms: float = -1.0
+    last_checked_at: datetime | None = None
+
+class ServiceRegistry:
+    @classmethod
+    def get_instance(cls) -> ServiceRegistry: ...
+    @classmethod
+    def _reset_for_testing(cls) -> None: ...
+    def register(self, name: str, client: Any) -> None: ...
+    def get(self, name: str) -> Any: ...
+    def register_all(self, clients: dict[str, Any]) -> None: ...
+    def run_startup_check(
+        self,
+        endpoint: str = "",
+        *,
+        enabled_services: set[str] | None = None,
+        local_fallback_enabled: bool = True,
+        timeout_ms: int = 2000,
+    ) -> dict[str, ServiceHealth]: ...
+    def status_response(self) -> dict[str, dict[str, Any]]: ...
+    def get_health(self, name: str) -> ServiceHealth: ...
+    def update_health(self, name: str, health: ServiceHealth) -> None: ...
+    def start_background_checker(
+        self,
+        endpoint: str = "",
+        interval: float = 60.0,
+        timeout_ms: int = 2000,
+    ) -> None: ...
+    def stop_background_checker(self) -> None: ...

spanforge/sdk/scope.py

@@ -0,0 +1,279 @@
+"""spanforge.sdk.scope - SpanForge sf-scope client.
+
+Phase 1 implementation for GA runtime scope enforcement. The client stores
+local capability manifests per agent, evaluates requested actions against
+those manifests, and emits signed scope decision records via sf-audit.
+"""
+
+from __future__ import annotations
+
+import threading
+from dataclasses import dataclass, field
+from typing import Any
+
+from spanforge.namespaces.runtime_governance import ScopeDecisionPayload
+from spanforge.sdk._base import SFClientConfig, SFServiceClient
+from spanforge.sdk._exceptions import SFScopeError
+
+__all__ = ["SFScopeClient", "ScopeManifest", "ScopeStatusInfo"]
+
+
+@dataclass
+class ScopeManifest:
+    """Registered scope manifest for one agent."""
+
+    agent_id: str
+    capabilities: list[str] = field(default_factory=list)
+    resource_actions: dict[str, list[str]] = field(default_factory=dict)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if not self.agent_id:
+            raise ValueError("ScopeManifest.agent_id must be non-empty")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "agent_id": self.agent_id,
+            "capabilities": list(self.capabilities),
+            "resource_actions": {key: list(value) for key, value in self.resource_actions.items()},
+            "metadata": dict(self.metadata),
+        }
+
+
+@dataclass
+class ScopeStatusInfo:
+    """sf-scope service status."""
+
+    status: str
+    registered_agents: int
+    total_checks: int
+    blocked_checks: int
+
+
+class SFScopeClient(SFServiceClient):
+    """SpanForge runtime scope enforcement service client."""
+
+    def __init__(self, config: SFClientConfig) -> None:
+        super().__init__(config, service_name="scope")
+        self._lock = threading.Lock()
+        self._manifests: dict[str, ScopeManifest] = {}
+        self._records: dict[str, ScopeDecisionPayload] = {}
+        self._by_trace: dict[str, list[str]] = {}
+        self._total_checks = 0
+        self._blocked_checks = 0
+
+    def register_agent(
+        self,
+        *,
+        agent_id: str,
+        capabilities: list[str] | None = None,
+        resource_actions: dict[str, list[str]] | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> ScopeManifest:
+        """Register or replace the allowed capability manifest for an agent."""
+        normalized_resource_actions = {
+            resource: sorted({action for action in actions if action})
+            for resource, actions in (resource_actions or {}).items()
+            if resource
+        }
+        manifest = ScopeManifest(
+            agent_id=agent_id,
+            capabilities=sorted({item for item in (capabilities or []) if item}),
+            resource_actions=normalized_resource_actions,
+            metadata=metadata or {},
+        )
+        with self._lock:
+            self._manifests[agent_id] = manifest
+        return manifest
+
+    def get_manifest(self, agent_id: str) -> ScopeManifest | None:
+        """Return the registered manifest for *agent_id*."""
+        with self._lock:
+            return self._manifests.get(agent_id)
+
+    def evaluate(
+        self,
+        *,
+        trace_id: str,
+        agent_id: str,
+        resource: str,
+        action_name: str,
+        checked_at: str,
+        capability: str | None = None,
+        scope_id: str | None = None,
+        policy_id: str | None = None,
+        policy_action: str | None = None,
+    ) -> ScopeDecisionPayload:
+        """Evaluate a runtime action against the agent scope manifest."""
+        from spanforge.ulid import generate as _ulid
+
+        manifest = self.get_manifest(agent_id)
+        allowed, reason = self._evaluate_manifest(
+            manifest=manifest,
+            agent_id=agent_id,
+            resource=resource,
+            action_name=action_name,
+            capability=capability,
+        )
+        payload = ScopeDecisionPayload(
+            scope_id=scope_id or _ulid(),
+            trace_id=trace_id,
+            agent_id=agent_id,
+            resource=resource,
+            action_name=action_name,
+            allowed=allowed,
+            outcome=self._resolve_outcome(allowed=allowed, policy_action=policy_action),
+            reason=reason,
+            checked_at=checked_at,
+            capability=capability,
+            policy_id=policy_id,
+            policy_action=policy_action,
+        )
+
+        with self._lock:
+            self._records[payload.scope_id] = payload
+            self._by_trace.setdefault(trace_id, []).append(payload.scope_id)
+            self._total_checks += 1
+            if not payload.allowed:
+                self._blocked_checks += 1
+
+        self._emit_signed_record(payload)
+        return payload
+
+    def evaluate_with_policy(
+        self,
+        *,
+        environment: str,
+        trace_id: str,
+        agent_id: str,
+        resource: str,
+        action_name: str,
+        checked_at: str,
+        capability: str | None = None,
+        policy_client: Any | None = None,
+        control: str = "capability_enforcement",
+    ) -> ScopeDecisionPayload:
+        """Evaluate scope and attach the active runtime policy decision."""
+        manifest = self.get_manifest(agent_id)
+        allowed, _reason = self._evaluate_manifest(
+            manifest=manifest,
+            agent_id=agent_id,
+            resource=resource,
+            action_name=action_name,
+            capability=capability,
+        )
+        engine = policy_client or self._default_policy_client()
+        decision = engine.evaluate(
+            environment=environment,
+            trace_id=trace_id,
+            service="sf_scope",
+            control=control,
+            evaluated_at=checked_at,
+            observed_value=1.0 if allowed else 0.0,
+            metadata={"agent_id": agent_id, "resource": resource, "action_name": action_name},
+        )
+        return self.evaluate(
+            trace_id=trace_id,
+            agent_id=agent_id,
+            resource=resource,
+            action_name=action_name,
+            checked_at=checked_at,
+            capability=capability,
+            policy_id=decision.policy_id,
+            policy_action=decision.action,
+        )
+
+    async def evaluate_async(self, **kwargs: Any) -> ScopeDecisionPayload:
+        """Async wrapper around :meth:`evaluate`."""
+        import asyncio
+
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(None, lambda: self.evaluate(**kwargs))
+
+    def require_capability(self, agent_id: str, capability: str) -> None:
+        """Raise when an agent is missing a required capability."""
+        manifest = self.get_manifest(agent_id)
+        key_scopes = manifest.capabilities if manifest is not None else []
+        if capability not in key_scopes:
+            raise SFScopeError(required_scope=capability, key_scopes=key_scopes)
+
+    def get(self, scope_id: str) -> ScopeDecisionPayload | None:
+        """Return a previously emitted scope decision."""
+        with self._lock:
+            return self._records.get(scope_id)
+
+    def list_for_trace(self, trace_id: str) -> list[ScopeDecisionPayload]:
+        """Return all scope decisions emitted for a trace."""
+        with self._lock:
+            ids = list(self._by_trace.get(trace_id, []))
+            return [self._records[item] for item in ids if item in self._records]
+
+    def get_status(self) -> ScopeStatusInfo:
+        """Return service health and scope-evaluation counters."""
+        with self._lock:
+            return ScopeStatusInfo(
+                status="ok",
+                registered_agents=len(self._manifests),
+                total_checks=self._total_checks,
+                blocked_checks=self._blocked_checks,
+            )
+
+    def _evaluate_manifest(
+        self,
+        *,
+        manifest: ScopeManifest | None,
+        agent_id: str,
+        resource: str,
+        action_name: str,
+        capability: str | None,
+    ) -> tuple[bool, str]:
+        if manifest is None:
+            return False, f"agent '{agent_id}' has no registered scope manifest"
+        if capability is not None and capability not in manifest.capabilities:
+            return (
+                False,
+                f"agent '{agent_id}' is missing required capability '{capability}'",
+            )
+
+        allowed_actions = manifest.resource_actions.get(resource)
+        if allowed_actions is None:
+            return (
+                False,
+                f"agent '{agent_id}' is not permitted to access resource '{resource}'",
+            )
+        if action_name not in allowed_actions:
+            return (
+                False,
+                f"agent '{agent_id}' cannot perform action '{action_name}' on resource '{resource}'",
+            )
+
+        if capability is not None:
+            return (
+                True,
+                f"agent '{agent_id}' is permitted for capability '{capability}' on {resource}:{action_name}",
+            )
+        return True, f"agent '{agent_id}' is permitted on {resource}:{action_name}"
+
+    @staticmethod
+    def _resolve_outcome(*, allowed: bool, policy_action: str | None) -> str:
+        if allowed:
+            return "allow"
+        if policy_action == "block":
+            return "block"
+        if policy_action == "human_review":
+            return "human_review"
+        if policy_action == "redact":
+            return "redact"
+        return "escalate"
+
+    def _emit_signed_record(self, payload: ScopeDecisionPayload) -> None:
+        """Write the scope decision payload into sf-audit."""
+        from spanforge.sdk import sf_audit
+
+        sf_audit.append(payload.to_dict(), "spanforge.scope.v1")
+
+    @staticmethod
+    def _default_policy_client() -> Any:
+        from spanforge.sdk import sf_policy
+
+        return sf_policy

spanforge/sdk/secrets.py

@@ -0,0 +1,293 @@
+"""spanforge.sdk.secrets — SpanForge sf-secrets client.
+
+Implements the full sf-secrets API surface for Phase 2 of the SpanForge
+roadmap.  All operations run locally in-process (zero external dependencies)
+when ``config.endpoint`` is empty or when the remote service is unreachable
+and ``config.local_fallback_enabled`` is ``True``.
+
+Local-mode feature parity
+--------------------------
+*  :meth:`scan`        — scan raw text for secrets using the built-in engine.
+*  :meth:`scan_batch`  — scan multiple texts concurrently.
+*  :meth:`get_status`  — return scanner configuration and health information.
+
+Security requirements
+---------------------
+*  ``SecretHit.redacted_value`` is **always** ``"[REDACTED:<SECRET_TYPE>]"`` —
+   the matched secret value is never stored or transmitted.
+*  ``SecretStr`` API keys are never written to logs.
+*  All ``auto_blocked=True`` results should cause the caller to refuse storage
+   or further processing of the original text.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any
+
+from spanforge.sdk._base import SFClientConfig, SFServiceClient
+from spanforge.sdk._exceptions import SFSecretsError, SFSecretsScanError
+from spanforge.secrets import SecretsScanner, SecretsScanResult
+
+__all__ = ["SFSecretsClient"]
+
+_log = logging.getLogger(__name__)
+
+
+class SFSecretsClient(SFServiceClient):
+    """SpanForge sf-secrets service client.
+
+    Provides secrets scanning over the full :class:`~spanforge.secrets.SecretsScanner`
+    detection engine.  When ``config.endpoint`` is empty (local mode), all
+    logic runs in-process.  When a remote endpoint is configured, the client
+    will attempt to call the remote service and fall back to local mode if
+    ``local_fallback_enabled`` is ``True``.
+
+    Args:
+        config: :class:`~spanforge.sdk._base.SFClientConfig` instance.
+
+    Example::
+
+        from spanforge.sdk import sf_secrets
+
+        # Scan a string for secrets
+        result = sf_secrets.scan("export STRIPE_KEY=sk_live_abc123...")
+        if result.auto_blocked:
+            raise RuntimeError("Secrets detected — refusing to process")
+        safe_text = result.redacted_text
+    """
+
+    def __init__(self, config: SFClientConfig) -> None:
+        super().__init__(config, service_name="secrets")
+        self._scanner = SecretsScanner()
+
+    # ------------------------------------------------------------------
+    # scan
+    # ------------------------------------------------------------------
+
+    def scan(
+        self,
+        text: str,
+        *,
+        confidence_threshold: float = 0.75,
+        extra_allowlist: frozenset[str] | None = None,
+    ) -> SecretsScanResult:
+        """Scan *text* for secrets.
+
+        Args:
+            text:                 The raw string to scan.  May be any length.
+            confidence_threshold: Minimum confidence to include a hit in the
+                                  result (default: ``0.75``).  Zero-tolerance
+                                  types are always included.
+            extra_allowlist:      Additional literal strings to suppress.
+
+        Returns:
+            :class:`~spanforge.secrets.SecretsScanResult`.
+
+        Raises:
+            SFSecretsScanError:        If *text* is not a ``str`` or scanning fails.
+            SFSecretsBlockedError:     If ``auto_blocked=True`` and the caller should
+                                       not continue processing.  (**Not** raised
+                                       automatically — callers must check ``result.auto_blocked``
+                                       and raise this themselves if required by their policy.)
+            SFServiceUnavailableError: Circuit breaker open and fallback disabled.
+        """
+        if not isinstance(text, str):
+            msg = f"scan() requires a str; got {type(text).__name__}"
+            raise SFSecretsScanError(msg)
+
+        if self._is_local_mode() or self._config.local_fallback_enabled:
+            return self._scan_local(
+                text,
+                confidence_threshold=confidence_threshold,
+                extra_allowlist=extra_allowlist,
+            )
+        return self._scan_remote(text, confidence_threshold=confidence_threshold)
+
+    def _scan_local(
+        self,
+        text: str,
+        *,
+        confidence_threshold: float,
+        extra_allowlist: frozenset[str] | None,
+    ) -> SecretsScanResult:
+        """Run the in-process scanner."""
+        try:
+            if extra_allowlist:
+                scanner = SecretsScanner(
+                    confidence_threshold=confidence_threshold,
+                    extra_allowlist=extra_allowlist,
+                )
+            else:
+                scanner = SecretsScanner(confidence_threshold=confidence_threshold)
+            return scanner.scan(text, confidence_threshold=confidence_threshold)
+        except (TypeError, ValueError) as exc:
+            raise SFSecretsScanError(str(exc)) from exc
+        except Exception as exc:
+            raise SFSecretsError(f"Unexpected error during secrets scan: {exc}") from exc
+
+    def _scan_remote(self, text: str, *, confidence_threshold: float) -> SecretsScanResult:
+        """Call the remote sf-secrets service."""
+        from spanforge.secrets import SecretHit
+
+        body: dict[str, Any] = {
+            "text": text,
+            "confidence_threshold": confidence_threshold,
+        }
+        try:
+            raw = self._request("POST", "/secrets/scan", body=body)
+        except Exception:
+            if self._config.local_fallback_enabled:
+                _log.warning(
+                    "sf-secrets remote scan failed; falling back to local mode",
+                    exc_info=True,
+                )
+                return self._scan_local(
+                    text,
+                    confidence_threshold=confidence_threshold,
+                    extra_allowlist=None,
+                )
+            raise
+
+        hits = [
+            SecretHit(
+                secret_type=str(h.get("secret_type", "unknown")),
+                start=int(h.get("start", 0)),
+                end=int(h.get("end", 0)),
+                confidence=float(h.get("confidence", 0.75)),
+                redacted_value=str(
+                    h.get("redacted_value", f"[REDACTED:{h.get('secret_type', 'UNKNOWN').upper()}]")
+                ),
+                auto_blocked=bool(h.get("auto_blocked", False)),
+                vault_hint=str(h.get("vault_hint", "")),
+            )
+            for h in raw.get("hits", [])
+        ]
+        return SecretsScanResult(
+            detected=bool(raw.get("detected", False)),
+            hits=hits,
+            auto_blocked=bool(raw.get("auto_blocked", False)),
+            redacted_text=str(raw.get("redacted_text", text)),
+            secret_types=list(raw.get("secret_types", [])),
+            confidence_scores=list(raw.get("confidence_scores", [])),
+        )
+
+    # ------------------------------------------------------------------
+    # scan_batch
+    # ------------------------------------------------------------------
+
+    def scan_batch(
+        self,
+        texts: list[str],
+        *,
+        confidence_threshold: float = 0.75,
+    ) -> list[SecretsScanResult]:
+        """Scan a list of strings concurrently.
+
+        Uses :func:`asyncio.gather` to parallelise local scans.  If the
+        event loop is already running, falls back to sequential scanning.
+
+        Args:
+            texts:                Strings to scan.
+            confidence_threshold: Passed to each :meth:`scan` call.
+
+        Returns:
+            List of :class:`~spanforge.secrets.SecretsScanResult`, one per
+            input string, in the same order.
+
+        Raises:
+            SFSecretsScanError: If any element of *texts* is not a ``str``.
+        """
+        for i, t in enumerate(texts):
+            if not isinstance(t, str):
+                msg = f"scan_batch() element {i} is not a str; got {type(t).__name__}"
+                raise SFSecretsScanError(msg)
+
+        try:
+            return asyncio.run(
+                self._scan_batch_async(texts, confidence_threshold=confidence_threshold)
+            )
+        except RuntimeError:
+            # Event loop already running — fall back to sequential
+            return [self.scan(t, confidence_threshold=confidence_threshold) for t in texts]
+
+    async def _scan_batch_async(
+        self,
+        texts: list[str],
+        *,
+        confidence_threshold: float,
+    ) -> list[SecretsScanResult]:
+        """Async helper — scan all texts concurrently in the thread pool."""
+        loop = asyncio.get_running_loop()
+        tasks = [
+            loop.run_in_executor(
+                None,
+                lambda t=text: self.scan(t, confidence_threshold=confidence_threshold),
+            )
+            for text in texts
+        ]
+        return list(await asyncio.gather(*tasks))
+
+    # ------------------------------------------------------------------
+    # scan_async (F-10)
+    # ------------------------------------------------------------------
+
+    async def scan_async(
+        self,
+        text: str,
+        *,
+        confidence_threshold: float = 0.75,
+        extra_allowlist: frozenset[str] | None = None,
+    ) -> SecretsScanResult:
+        """Async variant of :meth:`scan`.
+
+        Runs the scan in the default executor so the event loop is not
+        blocked for large payloads.
+
+        Args:
+            text:                 The raw string to scan.
+            confidence_threshold: Minimum confidence threshold (default: 0.75).
+            extra_allowlist:      Additional literal strings to suppress.
+
+        Returns:
+            :class:`~spanforge.secrets.SecretsScanResult`.
+        """
+        import asyncio
+        import functools
+
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(
+            None,
+            functools.partial(
+                self.scan,
+                text,
+                confidence_threshold=confidence_threshold,
+                extra_allowlist=extra_allowlist,
+            ),
+        )
+
+    # ------------------------------------------------------------------
+    # get_status
+    # ------------------------------------------------------------------
+
+    def get_status(self) -> dict[str, Any]:
+        """Return scanner status and configuration.
+
+        Returns a dictionary with:
+
+        *  ``"mode"``                — ``"local"`` or ``"remote"``.
+        *  ``"local_fallback"``      — ``True`` when fallback is enabled.
+        *  ``"circuit_breaker_open"``— ``True`` when the circuit is open.
+        *  ``"pattern_count"``       — Number of patterns in the registry.
+        *  ``"zero_tolerance_types"``— List of zero-tolerance type labels.
+        """
+        from spanforge.secrets import _PATTERN_REGISTRY, _ZERO_TOLERANCE_TYPES
+
+        return {
+            "mode": "local" if self._is_local_mode() else "remote",
+            "local_fallback": self._config.local_fallback_enabled,
+            "circuit_breaker_open": self._circuit_breaker.is_open(),
+            "pattern_count": len(_PATTERN_REGISTRY) + 1,  # +1 for generic_api_key
+            "zero_tolerance_types": sorted(_ZERO_TOLERANCE_TYPES),
+        }

spanforge/sdk/secrets.pyi

@@ -0,0 +1,25 @@
+"""Type stubs for spanforge.sdk.secrets (DX-001)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from spanforge.sdk._base import SFClientConfig, SFServiceClient
+from spanforge.secrets import SecretsScanResult
+
+class SFSecretsClient(SFServiceClient):
+    def __init__(self, config: SFClientConfig) -> None: ...
+    def scan(
+        self,
+        text: str,
+        *,
+        confidence_threshold: float = 0.75,
+        extra_allowlist: frozenset[str] | None = None,
+    ) -> SecretsScanResult: ...
+    def scan_batch(
+        self,
+        texts: list[str],
+        *,
+        confidence_threshold: float = 0.75,
+    ) -> list[SecretsScanResult]: ...
+    def get_status(self) -> dict[str, Any]: ...