zerynex-python 0.2.0__py3-none-any.whl

zerynex_py/fixtures/rule-catalog.json

@@ -0,0 +1,95 @@
+{
+  "schema_version": 1,
+  "tool": "zerynex",
+  "rule_set_version": "1.0.0",
+  "scope": "Selected structural PCZT disclosure-policy observations only. No cryptographic proof, wallet, consensus or anonymity verification.",
+  "rules": [
+    {
+      "id": "PCZT-DUMMY-KEY",
+      "title": "Intermediate dummy signing key exposed",
+      "severity": "warning",
+      "category": "handoff",
+      "applies_to": [
+        "analysis",
+        "stage_comparison"
+      ],
+      "summary": "An accessible dummy spending key is present in an intermediate PCZT handoff."
+    },
+    {
+      "id": "PCZT-GLOBAL-METADATA",
+      "title": "Unreviewed global metadata",
+      "severity": "warning",
+      "category": "metadata",
+      "applies_to": [
+        "analysis",
+        "stage_comparison"
+      ],
+      "summary": "Global proprietary fields require an explicit disclosure review."
+    },
+    {
+      "id": "PCZT-RESTRICTED-DISCLOSURE",
+      "title": "Restricted handoff field present",
+      "severity": "warning",
+      "category": "handoff",
+      "applies_to": [
+        "analysis",
+        "stage_comparison"
+      ],
+      "summary": "The receiving role could see a field prohibited by a selected restrictive application policy."
+    },
+    {
+      "id": "PCZT-SAPLING-POLICY",
+      "title": "Sapling components denied by policy",
+      "severity": "warning",
+      "category": "pool_policy",
+      "applies_to": [
+        "analysis",
+        "stage_comparison"
+      ],
+      "summary": "Sapling components exist despite an opt-in application restriction; Sapling itself is not prohibited by Zcash consensus."
+    },
+    {
+      "id": "PCZT-STRUCTURE-DRIFT",
+      "title": "PCZT component count changed",
+      "severity": "error",
+      "category": "regression",
+      "applies_to": [
+        "stage_comparison"
+      ],
+      "summary": "A covered component count changed between intermediate stages; values and cryptographic equivalence are not compared."
+    },
+    {
+      "id": "PCZT-TRANSPARENT-INPUTS",
+      "title": "Transparent inputs denied by policy",
+      "severity": "warning",
+      "category": "pool_policy",
+      "applies_to": [
+        "analysis",
+        "stage_comparison"
+      ],
+      "summary": "Transparent inputs were found while the selected policy denies transparent components."
+    },
+    {
+      "id": "PCZT-TRANSPARENT-OUTPUTS",
+      "title": "Transparent outputs denied by policy",
+      "severity": "warning",
+      "category": "pool_policy",
+      "applies_to": [
+        "analysis",
+        "stage_comparison"
+      ],
+      "summary": "Transparent outputs were found while the selected policy denies transparent components."
+    },
+    {
+      "id": "PCZT-UNREVIEWED-METADATA",
+      "title": "Unreviewed component metadata",
+      "severity": "warning",
+      "category": "metadata",
+      "applies_to": [
+        "analysis",
+        "stage_comparison"
+      ],
+      "summary": "Proprietary input, output or action fields are present and require disclosure review."
+    }
+  ]
+}

zerynex_py/fixtures/zallet-pczt-lifecycle-contract.json

@@ -0,0 +1,87 @@
+{
+  "version": 1,
+  "methods": [
+    {
+      "name": "rpc.discover",
+      "params": []
+    },
+    {
+      "name": "pczt_create",
+      "params": [
+        {
+          "name": "from",
+          "required": true
+        },
+        {
+          "name": "amounts",
+          "required": true
+        },
+        {
+          "name": "minconf",
+          "required": false
+        },
+        {
+          "name": "privacy_policy",
+          "required": false
+        },
+        {
+          "name": "fund_source",
+          "required": false
+        }
+      ]
+    },
+    {
+      "name": "pczt_combine",
+      "params": [
+        {
+          "name": "pczts",
+          "required": true
+        }
+      ]
+    },
+    {
+      "name": "pczt_inspect",
+      "params": [
+        {
+          "name": "pczt",
+          "required": true
+        }
+      ]
+    },
+    {
+      "name": "pczt_prove",
+      "params": [
+        {
+          "name": "pczt",
+          "required": true
+        }
+      ]
+    },
+    {
+      "name": "pczt_sign",
+      "params": [
+        {
+          "name": "pczt",
+          "required": true
+        },
+        {
+          "name": "privacy_policy",
+          "required": false
+        },
+        {
+          "name": "strict",
+          "required": false
+        }
+      ]
+    },
+    {
+      "name": "pczt_extract",
+      "params": [
+        {
+          "name": "pczt",
+          "required": true
+        }
+      ]
+    }
+  ]
+}

zerynex_py/fixtures/zallet-pczt-lifecycle-synthetic-openrpc.json

@@ -0,0 +1,127 @@
+{
+  "openrpc": "1.3.2",
+  "info": {
+    "title": "Synthetic PCZT lifecycle schema - NOT a Zallet release snapshot",
+    "version": "synthetic"
+  },
+  "methods": [
+    {
+      "name": "rpc.discover",
+      "params": []
+    },
+    {
+      "name": "pczt_create",
+      "params": [
+        {
+          "name": "from",
+          "required": true,
+          "schema": {
+            "type": "string"
+          }
+        },
+        {
+          "name": "amounts",
+          "required": true,
+          "schema": {
+            "type": "array"
+          }
+        },
+        {
+          "name": "minconf",
+          "required": false,
+          "schema": {
+            "type": "number"
+          }
+        },
+        {
+          "name": "privacy_policy",
+          "required": false,
+          "schema": {
+            "type": "string"
+          }
+        },
+        {
+          "name": "fund_source",
+          "required": false,
+          "schema": {
+            "type": "string"
+          }
+        }
+      ]
+    },
+    {
+      "name": "pczt_combine",
+      "params": [
+        {
+          "name": "pczts",
+          "required": true,
+          "schema": {
+            "type": "array"
+          }
+        }
+      ]
+    },
+    {
+      "name": "pczt_inspect",
+      "params": [
+        {
+          "name": "pczt",
+          "required": true,
+          "schema": {
+            "type": "string"
+          }
+        }
+      ]
+    },
+    {
+      "name": "pczt_prove",
+      "params": [
+        {
+          "name": "pczt",
+          "required": true,
+          "schema": {
+            "type": "string"
+          }
+        }
+      ]
+    },
+    {
+      "name": "pczt_sign",
+      "params": [
+        {
+          "name": "pczt",
+          "required": true,
+          "schema": {
+            "type": "string"
+          }
+        },
+        {
+          "name": "privacy_policy",
+          "required": false,
+          "schema": {
+            "type": "string"
+          }
+        },
+        {
+          "name": "strict",
+          "required": false,
+          "schema": {
+            "type": "boolean"
+          }
+        }
+      ]
+    },
+    {
+      "name": "pczt_extract",
+      "params": [
+        {
+          "name": "pczt",
+          "required": true,
+          "schema": {
+            "type": "string"
+          }
+        }
+      ]
+    }
+  ]
+}

zerynex_py/mcp_doctor.py

@@ -0,0 +1,152 @@
+"""Verify a REAL local MCP stdio connection and Rust-backed synthetic suite.
+
+A standalone diagnostic; never reads or prints transaction contents. No
+HTTP service, provider account or AI model is involved.
+"""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import os
+from pathlib import Path
+import shutil
+import sys
+
+
+async def check(server: Path, cli: Path, fixtures: Path) -> dict[str, object]:
+    try:
+        from mcp import Client
+        from mcp.client.stdio import StdioServerParameters
+    except ImportError:
+        raise RuntimeError("Install the optional MCP Python SDK before running the doctor.") from None
+
+    params = StdioServerParameters(
+        command=str(server),
+        args=[],
+        env={
+            "ZERYNEX_CLI": str(cli),
+            "ZERYNEX_AGENT_ALLOWED_ROOT": str(fixtures),
+        },
+    )
+    async with Client(params, raise_exceptions=True, read_timeout_seconds=35) as agent:
+        tools = await agent.list_tools()
+        names = sorted(tool.name for tool in tools.tools)
+        needed = {
+            "analyze_synthetic_pczt",
+            "compare_synthetic_pczt_stages",
+            "list_synthetic_fixtures",
+            "explain_zerynex_rule",
+            "run_synthetic_smoke_suite",
+            "zerynex_policy_schema",
+            "zerynex_core_capabilities",
+            "zerynex_rule_catalog",
+            "check_synthetic_zallet_rpc_contract",
+            "run_zerynex_developer_preflight",
+            "audit_synthetic_refund_privacy",
+            "compare_synthetic_refund_privacy",
+        }
+        if not needed.issubset(names):
+            raise RuntimeError("Local server does not expose all expected MCP capabilities.")
+        registry = await agent.call_tool("zerynex_rule_catalog", {})
+        rule_data = registry.structured_content
+        if not isinstance(rule_data, dict):
+            from mcp.types import TextContent
+            blocks = [item for item in registry.content if isinstance(item, TextContent)]
+            rule_data = json.loads(blocks[0].text) if len(blocks) == 1 else None
+        if not isinstance(rule_data, dict) or rule_data.get("rule_set_version") != "1.0.0" or len(rule_data.get("rules", [])) != 8:
+            raise RuntimeError("Installed Rust rule registry and bundled SDK are incompatible.")
+        suite = await agent.call_tool("run_synthetic_smoke_suite", {})
+        result = suite.structured_content
+        # Some supported protocol versions return text blocks instead.
+        if not isinstance(result, dict):
+            from mcp.types import TextContent
+            blocks = [item for item in suite.content if isinstance(item, TextContent)]
+            if len(blocks) != 1:
+                raise RuntimeError("Invalid structured response from the MCP tool.")
+            result = json.loads(blocks[0].text)
+        if not isinstance(result, dict):
+            raise RuntimeError("Invalid synthetic suite response.")
+        ok = result.get("passed") is True and result.get("total") == 4 and result.get("matched") == 4
+        readiness = await agent.call_tool("run_zerynex_developer_preflight", {})
+        preflight = readiness.structured_content
+        if not isinstance(preflight, dict):
+            from mcp.types import TextContent
+            blocks = [item for item in readiness.content if isinstance(item, TextContent)]
+            preflight = json.loads(blocks[0].text) if len(blocks) == 1 else None
+        if not isinstance(preflight, dict):
+            raise RuntimeError("Invalid developer preflight response.")
+        regression = await agent.call_tool("check_synthetic_zallet_rpc_contract", {"scenario": "new_required_parameter"})
+        drift = regression.structured_content
+        if not isinstance(drift, dict):
+            from mcp.types import TextContent
+            blocks = [item for item in regression.content if isinstance(item, TextContent)]
+            drift = json.loads(blocks[0].text) if len(blocks) == 1 else None
+        if not isinstance(drift, dict):
+            raise RuntimeError("Invalid regression response.")
+        safe_case = await agent.call_tool("audit_synthetic_refund_privacy", {"scenario": "isolated"})
+        unsafe_case = await agent.call_tool("audit_synthetic_refund_privacy", {"scenario": "risky"})
+        delta = await agent.call_tool("compare_synthetic_refund_privacy",
+                                      {"baseline": "risky", "candidate": "regression-expanded"})
+        def content_data(value):
+            data = value.structured_content
+            if not isinstance(data, dict):
+                from mcp.types import TextContent
+                blocks = [item for item in value.content if isinstance(item, TextContent)]
+                data = json.loads(blocks[0].text) if len(blocks) == 1 else None
+            return data if isinstance(data, dict) else {}
+        refund_ready = (content_data(safe_case).get("report", {}).get("passed") is True
+                        and content_data(unsafe_case).get("report", {}).get("finding_count") == 5
+                        and content_data(delta).get("report", {}).get("new_risk_events") == 1
+                        and preflight.get("checks", {}).get("synthetic_refund_privacy", {}).get("matched") == 6)
+        ready = preflight.get("passed") is True and preflight.get("synthetic_only") is True
+        negative = (drift.get("contract_passed") is False and drift.get("matched_expectation") is True
+                    and drift.get("finding_count") == 1)
+        return {
+            "connected": True,
+            "tool_count": len(names),
+            "tools": names,
+            "suite_passed": ok,
+            "suite_matched": result.get("matched", 0),
+            "suite_total": result.get("total", 4),
+            "preflight_passed": ready,
+            "rpc_regression_detected": negative,
+            "refund_privacy_verified": refund_ready,
+            "note": "MCP stdio subprocess and real Rust CLI. Synthetic inputs only.",
+        }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Check a local Zerynex MCP server against synthetic fixtures.")
+    parser.add_argument("--cli", default=os.environ.get("ZERYNEX_CLI", ""), help="Absolute path to the trusted Rust CLI")
+    parser.add_argument("--fixtures", default=os.environ.get("ZERYNEX_AGENT_ALLOWED_ROOT", ""), help="Absolute synthetic-only fixture directory")
+    parser.add_argument("--server", default=shutil.which("zerynex-mcp") or "", help="Absolute path to local zerynex-mcp executable")
+    parser.add_argument("--json", action="store_true", help="Print a sanitized JSON outcome")
+    args = parser.parse_args()
+    # Avoid including user paths in errors, logs, and diagnostic output.
+    if not args.cli or not args.fixtures or not args.server:
+        parser.error("Provide --cli, --fixtures and --server for an explicit local setup.")
+    try:
+        cli, fixtures, server = (Path(path).expanduser().resolve(strict=True)
+                                 for path in (args.cli, args.fixtures, args.server))
+        if not cli.is_file() or not server.is_file() or not fixtures.is_dir():
+            raise RuntimeError("Invalid configured local paths.")
+        report = asyncio.run(check(server, cli, fixtures))
+    except Exception:  # MCP transport can raise ExceptionGroup; always redact errors.
+        print("Zerynex MCP connection or synthetic suite failed. Check local setup.", file=sys.stderr)
+        raise SystemExit(1) from None
+    if args.json:
+        print(json.dumps(report, indent=2))
+    else:
+        print("MCP stdio: connected")
+        print("Discovered tools:", report["tool_count"])
+        print("Synthetic Rust checks:", str(report["suite_matched"]) + "/" + str(report["suite_total"]))
+        print("Developer preflight:", "PASS" if report["preflight_passed"] else "FAIL")
+        print("Synthetic RPC drift detected:", "YES" if report["rpc_regression_detected"] else "NO")
+        print("Synthetic refund privacy:", "PASS" if report["refund_privacy_verified"] else "FAIL")
+        print("Result:", "PASS" if report["suite_passed"] and report["preflight_passed"] and report["rpc_regression_detected"] and report["refund_privacy_verified"] else "FAIL")
+    raise SystemExit(0 if report["suite_passed"] and report["preflight_passed"] and report["rpc_regression_detected"] and report["refund_privacy_verified"] else 2)
+
+
+if __name__ == "__main__":
+    main()