sernixa-cli 0.1.1__py3-none-any.whl

sernixa_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Official Sernixa command-line client."""
+
+__version__ = "0.1.1"

sernixa_cli/__main__.py

@@ -0,0 +1,3 @@
+from .main import app
+
+app()

sernixa_cli/adapters.py

@@ -0,0 +1,279 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal
+
+
+ProviderMode = Literal["plain", "claude", "codex"]
+
+SENSITIVE_KEY_PARTS = (
+    "api_key",
+    "apikey",
+    "authorization",
+    "bearer",
+    "client_secret",
+    "password",
+    "secret",
+    "token",
+)
+
+
+class AdapterError(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class CanonicalGovernanceRequest:
+    input: dict[str, Any]
+    source: ProviderMode
+
+
+def redact_sensitive(value: Any) -> Any:
+    if isinstance(value, dict):
+        redacted: dict[str, Any] = {}
+        for key, item in value.items():
+            normalized = str(key).lower().replace("-", "_")
+            if any(part in normalized for part in SENSITIVE_KEY_PARTS):
+                redacted[str(key)] = "[redacted]"
+            else:
+                redacted[str(key)] = redact_sensitive(item)
+        return redacted
+    if isinstance(value, list):
+        return [redact_sensitive(item) for item in value]
+    return value
+
+
+def load_json_payload(content: str) -> Any:
+    if not content.strip():
+        raise AdapterError("No JSON payload received.")
+    try:
+        return json.loads(content)
+    except json.JSONDecodeError:
+        return _load_json_lines(content)
+
+
+def _load_json_lines(content: str) -> list[Any]:
+    items: list[Any] = []
+    for line_number, line in enumerate(content.splitlines(), start=1):
+        if not line.strip():
+            continue
+        try:
+            items.append(json.loads(line))
+        except json.JSONDecodeError as exc:
+            raise AdapterError(
+                f"Invalid JSON at line {line_number}, column {exc.colno}: {exc.msg}"
+            ) from exc
+    if not items:
+        raise AdapterError("No JSON payload received.")
+    return items
+
+
+def read_payload_source(path: Path | None) -> str:
+    import sys
+
+    try:
+        return path.read_text(encoding="utf-8") if path else sys.stdin.read()
+    except OSError as exc:
+        raise AdapterError(f"Unable to read payload: {exc}") from exc
+
+
+def canonicalize_payload(raw: Any, *, mode: ProviderMode) -> CanonicalGovernanceRequest:
+    if mode == "plain":
+        if not isinstance(raw, dict):
+            raise AdapterError("Governance payload must be a JSON object.")
+        return CanonicalGovernanceRequest(input=raw, source="plain")
+    if mode == "claude":
+        return CanonicalGovernanceRequest(input=_claude_to_governance(raw), source="claude")
+    if mode == "codex":
+        return CanonicalGovernanceRequest(input=_codex_to_governance(raw), source="codex")
+    raise AdapterError(f"Unsupported payload adapter: {mode}")
+
+
+def payload_from_content(content: str, *, mode: ProviderMode) -> CanonicalGovernanceRequest:
+    raw = load_json_payload(content)
+    return canonicalize_payload(raw, mode=mode)
+
+
+def _claude_to_governance(raw: Any) -> dict[str, Any]:
+    if not isinstance(raw, dict):
+        raise AdapterError("Claude hook payload must be a JSON object.")
+    tool_name = _string(raw.get("tool_name") or raw.get("name"))
+    tool_input = raw.get("tool_input")
+    if tool_input is None and isinstance(raw.get("input"), dict):
+        tool_input = raw["input"]
+    if not tool_name:
+        raise AdapterError("Claude hook payload is missing tool_name.")
+    if tool_input is None:
+        raise AdapterError("Claude hook payload is missing tool_input.")
+    if not isinstance(tool_input, dict):
+        raise AdapterError("Claude hook tool_input must be a JSON object.")
+    return _provider_tool_request(
+        source="claude",
+        hook_event_name=_string(raw.get("hook_event_name")) or "PreToolUse",
+        tool_name=tool_name,
+        tool_input=tool_input,
+        provider_context={
+            "session_id": raw.get("session_id"),
+            "transcript_path": raw.get("transcript_path"),
+            "cwd": raw.get("cwd"),
+            "tool_use_id": raw.get("tool_use_id"),
+            "user": _first_present(raw, "user", "user_id", "email", "account_id"),
+        },
+    )
+
+
+def _codex_to_governance(raw: Any) -> dict[str, Any]:
+    event = _select_codex_event(raw)
+    if not isinstance(event, dict):
+        raise AdapterError("Codex payload must be a JSON object or JSON-lines stream.")
+    tool_name = _string(event.get("tool_name") or event.get("name") or event.get("tool"))
+    tool_input = event.get("tool_input")
+    if tool_input is None:
+        if isinstance(event.get("input"), dict):
+            tool_input = event["input"]
+        elif isinstance(event.get("arguments"), dict):
+            tool_input = event["arguments"]
+        elif event.get("command") or event.get("cmd"):
+            tool_input = {"command": event.get("command") or event.get("cmd")}
+            tool_name = tool_name or "Bash"
+    if not tool_name:
+        raise AdapterError("Codex payload is missing tool_name.")
+    if tool_input is None:
+        raise AdapterError("Codex payload is missing tool_input.")
+    if not isinstance(tool_input, dict):
+        raise AdapterError("Codex hook tool_input must be a JSON object.")
+    return _provider_tool_request(
+        source="codex",
+        hook_event_name=_string(event.get("hook_event_name")) or "PreToolUse",
+        tool_name=tool_name,
+        tool_input=tool_input,
+        provider_context={
+            "session_id": event.get("session_id"),
+            "turn_id": event.get("turn_id"),
+            "transcript_path": event.get("transcript_path"),
+            "cwd": event.get("cwd"),
+            "model": event.get("model"),
+            "permission_mode": event.get("permission_mode"),
+            "tool_use_id": event.get("tool_use_id"),
+        },
+    )
+
+
+def _select_codex_event(raw: Any) -> Any:
+    if isinstance(raw, dict):
+        return raw
+    if not isinstance(raw, list):
+        return raw
+    candidates = [
+        item
+        for item in raw
+        if isinstance(item, dict)
+        and (
+            item.get("hook_event_name") in {"PreToolUse", "PermissionRequest"}
+            or item.get("tool_name")
+            or item.get("command")
+            or item.get("cmd")
+        )
+    ]
+    if not candidates:
+        raise AdapterError("No recognizable Codex tool event found in JSON-lines stream.")
+    return candidates[-1]
+
+
+def _provider_tool_request(
+    *,
+    source: ProviderMode,
+    hook_event_name: str,
+    tool_name: str,
+    tool_input: dict[str, Any],
+    provider_context: dict[str, Any],
+) -> dict[str, Any]:
+    sanitized_input = redact_sensitive(tool_input)
+    action = _action_for_tool(tool_name, sanitized_input)
+    return {
+        "schema_version": "sernixa.governance_request.v1",
+        "source": source,
+        "provider": source,
+        "hook_event_name": hook_event_name,
+        "tool_name": tool_name,
+        "action": action["action"],
+        "operation_class": action["operation_class"],
+        "resource": action.get("resource"),
+        "intent": action.get("intent"),
+        "parameters": sanitized_input,
+        "provider_context": {
+            key: value
+            for key, value in redact_sensitive(provider_context).items()
+            if value is not None
+        },
+    }
+
+
+def _action_for_tool(tool_name: str, tool_input: dict[str, Any]) -> dict[str, Any]:
+    normalized = tool_name.lower()
+    if normalized in {"bash", "shell"}:
+        command = _string(tool_input.get("command"))
+        return {
+            "action": "shell.execute",
+            "operation_class": "shell",
+            "resource": command,
+            "intent": _string(tool_input.get("description")),
+        }
+    if normalized in {"write", "edit", "multiedit", "apply_patch"}:
+        return {
+            "action": "file.write",
+            "operation_class": "write",
+            "resource": _string(tool_input.get("file_path"))
+            or _string(tool_input.get("path"))
+            or _string(tool_input.get("command")),
+            "intent": _string(tool_input.get("description")),
+        }
+    if normalized in {"read", "glob", "grep", "ls"}:
+        return {
+            "action": "file.read",
+            "operation_class": "read",
+            "resource": _string(tool_input.get("file_path"))
+            or _string(tool_input.get("path"))
+            or _string(tool_input.get("pattern")),
+            "intent": _string(tool_input.get("description")),
+        }
+    if normalized in {"webfetch", "websearch"}:
+        return {
+            "action": "network.request",
+            "operation_class": "network",
+            "resource": _string(tool_input.get("url")) or _string(tool_input.get("query")),
+            "intent": _string(tool_input.get("prompt")),
+        }
+    if normalized.startswith("mcp__"):
+        return {
+            "action": "mcp.tool",
+            "operation_class": "mcp",
+            "resource": tool_name,
+            "intent": _string(tool_input.get("description")),
+        }
+    if normalized == "agent":
+        return {
+            "action": "agent.delegate",
+            "operation_class": "delegate",
+            "resource": _string(tool_input.get("subagent_type")),
+            "intent": _string(tool_input.get("prompt")) or _string(tool_input.get("description")),
+        }
+    return {
+        "action": f"tool.{normalized}",
+        "operation_class": "tool",
+        "resource": tool_name,
+        "intent": _string(tool_input.get("description")),
+    }
+
+
+def _string(value: Any) -> str | None:
+    return value.strip() if isinstance(value, str) and value.strip() else None
+
+
+def _first_present(payload: dict[str, Any], *keys: str) -> Any:
+    for key in keys:
+        if payload.get(key) is not None:
+            return payload[key]
+    return None

sernixa_cli/config.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from platformdirs import user_config_path
+
+DEFAULT_BASE_URL = "https://api.sernixa.com"
+
+
+class ConfigError(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True)
+class CliConfig:
+    api_key: str
+    base_url: str = DEFAULT_BASE_URL
+
+
+def config_path() -> Path:
+    override = os.getenv("SERNIXA_CONFIG_FILE", "").strip()
+    if override:
+        return Path(override).expanduser()
+    return user_config_path("sernixa", appauthor=False) / "config.json"
+
+
+def plan_session_path() -> Path:
+    override = os.getenv("SERNIXA_PLAN_SESSION_FILE", "").strip()
+    if override:
+        return Path(override).expanduser()
+    return user_config_path("sernixa", appauthor=False) / "plan-session.json"
+
+
+def save_plan_session(evaluation: dict[str, object]) -> Path:
+    token = evaluation.get("plan_token")
+    proofs = evaluation.get("step_proofs")
+    if not isinstance(token, str) or not token or not isinstance(proofs, list):
+        raise ConfigError(
+            "Approved plan response did not include a plan token and step proofs."
+        )
+    session = {
+        "plan_id": evaluation.get("plan_id"),
+        "plan_hash": evaluation.get("plan_hash"),
+        "plan_token": token,
+        "plan_token_id": evaluation.get("plan_token_id"),
+        "plan_token_expires_at": evaluation.get("plan_token_expires_at"),
+        "policy_version_id": evaluation.get("policy_version_id"),
+        "step_proofs": proofs,
+        "consumed_proof_ids": [],
+        "allowed": True,
+    }
+    path = plan_session_path()
+    path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    temporary = path.with_suffix(".tmp")
+    temporary.write_text(
+        json.dumps(session, separators=(",", ":")) + "\n", encoding="utf-8"
+    )
+    if os.name == "posix":
+        temporary.chmod(0o600)
+    temporary.replace(path)
+    if os.name == "posix":
+        path.chmod(0o600)
+    return path
+
+
+def remove_plan_session() -> bool:
+    path = plan_session_path()
+    if not path.exists():
+        return False
+    path.unlink()
+    return True
+
+
+def normalize_base_url(value: str) -> str:
+    normalized = value.strip().rstrip("/")
+    if not normalized.startswith(("https://", "http://")):
+        raise ConfigError("API base URL must start with http:// or https://.")
+    return normalized
+
+
+def save_config(config: CliConfig) -> Path:
+    path = config_path()
+    path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    temporary = path.with_suffix(".tmp")
+    temporary.write_text(json.dumps(asdict(config), indent=2) + "\n", encoding="utf-8")
+    if os.name == "posix":
+        temporary.chmod(0o600)
+    temporary.replace(path)
+    if os.name == "posix":
+        path.chmod(0o600)
+    return path
+
+
+def load_config(
+    *, require_key: bool = True, base_url_override: str | None = None
+) -> CliConfig:
+    env_key = os.getenv("SERNIXA_API_KEY", "").strip()
+    env_base_url = os.getenv("SERNIXA_BASE_URL", "").strip()
+    stored: dict[str, object] = {}
+    path = config_path()
+    if path.exists():
+        try:
+            parsed = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            raise ConfigError(f"Configuration file is unreadable: {path}") from exc
+        if not isinstance(parsed, dict):
+            raise ConfigError(f"Configuration file must contain a JSON object: {path}")
+        stored = parsed
+
+    api_key = env_key or str(stored.get("api_key") or "").strip()
+    base_url = normalize_base_url(
+        base_url_override
+        or env_base_url
+        or str(stored.get("base_url") or DEFAULT_BASE_URL)
+    )
+    if require_key and not api_key:
+        raise ConfigError("No API key configured. Run `sernixa auth login` first.")
+    return CliConfig(api_key=api_key, base_url=base_url)
+
+
+def remove_config() -> bool:
+    path = config_path()
+    if not path.exists():
+        return False
+    path.unlink()
+    return True

sernixa_cli/formatting.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+import json
+from typing import Any, Literal
+
+import typer
+
+
+Decision = Literal["allow", "deny"]
+
+
+def is_allowed(decision: dict[str, Any]) -> bool:
+    return str(decision.get("final_decision", "deny")).lower() == "allow"
+
+
+def exit_code_for_decision(decision: dict[str, Any]) -> int:
+    return 0 if is_allowed(decision) else 1
+
+
+def decision_summary(
+    backend_decision: dict[str, Any],
+    *,
+    include_raw: bool = True,
+    request: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    allowed = is_allowed(backend_decision)
+    summary: dict[str, Any] = {
+        "decision": "allow" if allowed else "deny",
+        "final_decision": backend_decision.get("final_decision", "deny"),
+        "violations": _violations(backend_decision, request=request) if not allowed else [],
+        "matched_policies": backend_decision.get("matched_policies") or [],
+        "reasons": backend_decision.get("reasons") or [],
+    }
+    if include_raw:
+        summary["raw_backend_response"] = backend_decision
+    return summary
+
+
+def render_decision(
+    backend_decision: dict[str, Any],
+    *,
+    json_output: bool = False,
+    quiet: bool = False,
+    request: dict[str, Any] | None = None,
+) -> None:
+    if quiet:
+        return
+    allowed = is_allowed(backend_decision)
+    if json_output:
+        typer.echo(json.dumps(decision_summary(backend_decision, request=request), sort_keys=True))
+        return
+    if allowed:
+        typer.secho("Allowed by Sernixa policy.", fg=typer.colors.GREEN)
+        matched = backend_decision.get("matched_policies") or []
+        if matched:
+            typer.echo(f"Matched policies: {', '.join(str(item) for item in matched)}")
+        return
+    typer.secho("Denied by Sernixa policy.", fg=typer.colors.RED, err=True)
+    for violation in _violations(backend_decision, request=request):
+        label = (
+            violation.get("policy_id")
+            or violation.get("rule")
+            or violation.get("principle")
+            or "policy"
+        )
+        category = violation.get("risk_category") or violation.get("category")
+        severity = violation.get("severity")
+        message = violation.get("message") or violation.get("reason") or "Denied by policy."
+        prefix = f"{label}"
+        if category:
+            prefix = f"{prefix} [{category}]"
+        if severity:
+            prefix = f"{prefix} severity={severity}"
+        typer.echo(f"- {prefix}: {message}", err=True)
+        if violation.get("principle"):
+            typer.echo(f"  principle: {violation['principle']}", err=True)
+        if category:
+            typer.echo(f"  risk category: {category}", err=True)
+        if violation.get("severity"):
+            typer.echo(f"  severity: {violation['severity']}", err=True)
+        if violation.get("resource"):
+            typer.echo(f"  resource: {violation['resource']}", err=True)
+        if violation.get("action"):
+            typer.echo(f"  action: {violation['action']}", err=True)
+        if violation.get("remediation"):
+            typer.echo(f"  remediation: {violation['remediation']}", err=True)
+
+
+def hook_response(provider: str, backend_decision: dict[str, Any]) -> dict[str, Any] | None:
+    if is_allowed(backend_decision):
+        return None
+    reason = "; ".join(str(item) for item in backend_decision.get("reasons") or []) or (
+        "Blocked by Sernixa policy."
+    )
+    if provider == "codex":
+        return {
+            "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "deny",
+                "permissionDecisionReason": reason,
+            }
+        }
+    if provider == "claude":
+        return {
+            "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "deny",
+                "permissionDecisionReason": reason,
+            }
+        }
+    return {"decision": "block", "reason": reason}
+
+
+def _violations(
+    backend_decision: dict[str, Any],
+    *,
+    request: dict[str, Any] | None = None,
+) -> list[dict[str, Any]]:
+    existing = backend_decision.get("violations")
+    if isinstance(existing, list):
+        return [
+            item
+            for item in existing
+            if isinstance(item, dict)
+        ]
+    reasons = backend_decision.get("reasons") or ["No policy reason was returned."]
+    matched = backend_decision.get("matched_policies") or []
+    violations: list[dict[str, Any]] = []
+    for index, reason in enumerate(reasons):
+        policy = matched[index] if index < len(matched) else (matched[0] if matched else None)
+        violations.append(
+            {
+                "policy_id": policy,
+                "rule": policy,
+                "risk_category": backend_decision.get("risk_category"),
+                "severity": backend_decision.get("severity"),
+                "message": str(reason),
+                "resource": request.get("resource") if request else None,
+                "action": request.get("action") if request else None,
+                "remediation": _first_remediation(backend_decision.get("remediation")),
+            }
+        )
+    return violations
+
+
+def _first_remediation(value: Any) -> str | None:
+    if isinstance(value, list) and value:
+        return str(value[0])
+    if isinstance(value, str):
+        return value
+    return None

sernixa_cli/hooks.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from .local_agent_targets import (
+    Provider,
+    TargetConfigError,
+    TargetID,
+    hook_snippet,
+    install_target,
+    repair_target,
+    resolve_local_agent_target,
+    target_status,
+)
+
+
+HookTarget = TargetID
+HookInstallError = TargetConfigError
+
+
+@dataclass(frozen=True)
+class HookInstallResult:
+    provider: Provider
+    target: HookTarget
+    status: str
+    path: Path
+    created: bool
+    backup_path: Path | None = None
+    error: str | None = None
+    manual_steps: list[str] | None = None
+
+
+@dataclass(frozen=True)
+class HookRepairResult:
+    provider: Provider
+    target: HookTarget
+    status: str
+    path: Path
+    backup_paths: tuple[Path, ...] = ()
+    error: str | None = None
+
+
+def hook_config_path(provider: Literal["claude", "codex"]) -> Path:
+    return resolve_local_agent_target(provider).selected_path
+
+
+def manual_steps(target: str) -> list[str]:
+    resolution = resolve_local_agent_target(target)
+    return [
+        f"Create or edit {resolution.selected_path}.",
+        "Merge in this managed Sernixa configuration:",
+        json.dumps(hook_snippet(resolution.target_id), indent=2, sort_keys=True),
+        f"Run 'sernixa hook {resolution.provider}' any time to print the hook snippet again.",
+    ]
+
+
+def install_hook(target: str) -> HookInstallResult:
+    try:
+        resolution = resolve_local_agent_target(target)
+        existed_before = resolution.selected_path.exists()
+        resolution, status, backup_path = install_target(target)
+    except HookInstallError as exc:
+        resolution = resolve_local_agent_target(target)
+        return HookInstallResult(
+            provider=resolution.provider,
+            target=resolution.target_id,
+            status="manual_required",
+            path=resolution.selected_path,
+            created=False,
+            error=str(exc),
+            manual_steps=manual_steps(target),
+        )
+    return HookInstallResult(
+        provider=resolution.provider,
+        target=resolution.target_id,
+        status=status,
+        path=resolution.selected_path,
+        created=not existed_before,
+        backup_path=backup_path,
+    )
+
+
+def hook_detected(provider: Literal["claude", "codex"]) -> bool:
+    return target_status(provider).installed
+
+
+def repair_hook(target: str) -> HookRepairResult:
+    try:
+        resolution, status, backup_paths = repair_target(target)
+    except HookInstallError as exc:
+        resolution = resolve_local_agent_target(target)
+        return HookRepairResult(
+            provider=resolution.provider,
+            target=resolution.target_id,
+            status="manual_required",
+            path=resolution.selected_path,
+            error=str(exc),
+        )
+    return HookRepairResult(
+        provider=resolution.provider,
+        target=resolution.target_id,
+        status=status,
+        path=resolution.selected_path,
+        backup_paths=backup_paths,
+    )