zerynex-python 0.2.0__py3-none-any.whl

zerynex_py/mcp_server.py

@@ -0,0 +1,391 @@
+"""Local-only, read-only MCP adapter for *approved synthetic fixtures*.
+
+No raw PCZT bytes, passwords, mnemonic phrases or viewing keys are returned to
+the agent. No transaction creation, signing, network API, or generic host file
+reader is exposed.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import re
+
+from .client import Policy, ZerynexClient, ZerynexError
+
+SAFE_NAME = re.compile(r"^[a-z0-9][a-z0-9_.-]{0,79}\.bin$", re.ASCII)
+
+
+def allowed_fixture(root: Path, fixture_name: str) -> Path:
+    """Permit a single simple .bin filename under an explicitly selected root."""
+    if not isinstance(fixture_name, str) or not SAFE_NAME.fullmatch(fixture_name):
+        raise ZerynexError("Only an approved synthetic fixture filename is allowed.")
+    if not root.is_dir():
+        raise ZerynexError("The configured synthetic fixture directory is unavailable.")
+    base = root.expanduser().resolve(strict=True)
+    candidate = base / fixture_name
+    if candidate.is_symlink():
+        raise ZerynexError("Symlink fixtures are not allowed.")
+    try:
+        checked = candidate.resolve(strict=True)
+    except OSError:
+        raise ZerynexError("The selected fixture is unavailable.") from None
+    if not checked.is_relative_to(base) or not checked.is_file():
+        raise ZerynexError("The selected fixture is outside the allowed directory.")
+    return checked
+
+
+def scan_fixture(
+    client: ZerynexClient,
+    root: Path,
+    fixture_name: str,
+    profile: str = "external_signer",
+    deny_transparent: bool = True,
+    deny_sapling: bool = False,
+) -> dict[str, object]:
+    """Pure handler used by MCP and unit tests; no LLM or network dependency."""
+    if profile not in ("external_signer", "restricted_handoff"):
+        raise ZerynexError("Unsupported privacy profile.")
+    if type(deny_transparent) is not bool or type(deny_sapling) is not bool:
+        raise ZerynexError("Privacy policy flags must be booleans.")
+    safe = allowed_fixture(root, fixture_name)
+    policy = Policy(
+        profile=profile,
+        deny_transparent=deny_transparent,
+        deny_sapling=deny_sapling,
+    )
+    report = client.analyze_file(safe, policy)
+    return report.agent_summary()
+
+
+def compare_synthetic_fixtures(
+    client: ZerynexClient,
+    root: Path,
+    baseline_name: str,
+    candidate_name: str,
+    profile: str = "external_signer",
+    deny_transparent: bool = True,
+    deny_sapling: bool = False,
+) -> dict[str, object]:
+    """Compare only two explicitly approved synthetic PCZT fixture basenames."""
+    if profile not in ("external_signer", "restricted_handoff"):
+        raise ZerynexError("Unsupported privacy profile.")
+    if type(deny_transparent) is not bool or type(deny_sapling) is not bool:
+        raise ZerynexError("Privacy policy flags must be booleans.")
+    baseline = allowed_fixture(root, baseline_name)
+    candidate = allowed_fixture(root, candidate_name)
+    report = client.compare_files(
+        baseline,
+        candidate,
+        Policy(
+            profile=profile,
+            deny_transparent=deny_transparent,
+            deny_sapling=deny_sapling,
+        ),
+    )
+    return report.agent_summary()
+
+
+
+# Fixed explanations are intentionally free from fixture bytes or agent-supplied
+# instructions. The authoritative result still comes from the Rust analyzer.
+RULE_GUIDANCE: dict[str, tuple[str, str]] = {
+    "PCZT-DUMMY-KEY": (
+        "An accessible intermediate dummy spending key was found.",
+        "Review the signer/prover role boundary. Do not disclose the dummy spend key to an untrusted recipient.",
+    ),
+    "PCZT-GLOBAL-METADATA": (
+        "A global proprietary metadata field is available at this handoff.",
+        "Review the metadata's necessity and redact the field in a test workflow before external handoff.",
+    ),
+    "PCZT-UNREVIEWED-METADATA": (
+        "A proprietary spend or output metadata field is available.",
+        "Review role-specific metadata and use the upstream PCZT redactor where appropriate.",
+    ),
+    "PCZT-RESTRICTED-DISCLOSURE": (
+        "A field blocked by the restricted handoff policy is present.",
+        "Check whether the receiving role really needs this field. Restricted profiles may not suit every signer.",
+    ),
+    "PCZT-SAPLING-POLICY": (
+        "Sapling components exist despite an application-level deny policy.",
+        "Review the app-specific Sapling restriction; Sapling is not inherently forbidden by Zcash consensus.",
+    ),
+    "PCZT-TRANSPARENT-INPUTS": (
+        "The PCZT includes transparent inputs under a shielded-only policy.",
+        "Review transparent input selection and policy configuration before moving to signing.",
+    ),
+    "PCZT-TRANSPARENT-OUTPUTS": (
+        "The PCZT includes transparent outputs under a shielded-only policy.",
+        "Review output construction and destination pool selection; recheck with a synthetic fixture.",
+    ),
+}
+
+
+def discover_synthetic_fixtures(root: Path) -> dict[str, object]:
+    """List a bounded subset of approved, regular .bin files without reading bytes."""
+    try:
+        base = root.expanduser().resolve(strict=True)
+        if not base.is_dir():
+            raise OSError("invalid")
+        names: list[str] = []
+        inspected = 0
+        # Avoid unbounded work on an unexpectedly large, untrusted directory.
+        for path in base.iterdir():
+            inspected += 1
+            if inspected > 256:
+                break
+            if not SAFE_NAME.fullmatch(path.name) or path.is_symlink():
+                continue
+            if not path.is_file() or not 0 < path.stat().st_size <= 8 * 1024 * 1024:
+                continue
+            names.append(path.name)
+        names.sort()
+        return {
+            "fixtures": names[:32],
+            "truncated": len(names) > 32 or inspected > 256,
+            "note": "Names from the explicitly approved synthetic-fixture root only; no bytes returned.",
+        }
+    except (OSError, ValueError):
+        raise ZerynexError("Approved synthetic-fixture directory unavailable.") from None
+
+
+def explain_policy_rule(rule_id: str) -> dict[str, str]:
+    """Explain only enumerated rules. Never echo arbitrary agent prompt contents."""
+    if not isinstance(rule_id, str) or rule_id not in RULE_GUIDANCE:
+        raise ZerynexError("Unknown supported privacy rule.")
+    from .rules import bundled_rule_catalog
+    catalog = bundled_rule_catalog()
+    definition = next((item for item in catalog['rules'] if item['id'] == rule_id), None)
+    if definition is None:
+        raise ZerynexError("Unknown supported privacy rule.")
+    meaning, next_step = RULE_GUIDANCE[rule_id]
+    return {
+        "rule": rule_id,
+        "severity": definition["severity"],
+        "category": definition["category"],
+        "rule_set_version": catalog["rule_set_version"],
+        "meaning": meaning,
+        "suggested_review": next_step,
+        "limitation": "Policy guidance, not a complete security review or cryptographic verification.",
+    }
+
+
+def evaluate_synthetic_smoke_suite(client: ZerynexClient, root: Path) -> dict[str, object]:
+    """Prove that scan + compare tool paths work with an approved bundled suite.
+
+    Expected failures are *successful test detections*. Never return file
+    contents, external absolute paths or CLI error details.
+    """
+    tests: list[dict[str, object]] = []
+
+    for name, expected_rules in (
+        ("clean-v6.bin", ()),
+        ("transparent-v6.bin", ("PCZT-TRANSPARENT-OUTPUTS",)),
+        ("flagged-v6.bin", ("PCZT-GLOBAL-METADATA",)),
+    ):
+        try:
+            result = scan_fixture(client, root, name)
+            found = sorted({finding["rule"] for finding in result["findings"]})
+            matched = found == sorted(expected_rules) and result["passed"] == (not expected_rules)
+        except (ZerynexError, OSError):
+            found = []
+            matched = False
+        tests.append({
+            "scenario": name.removesuffix(".bin"),
+            "matched_expectation": matched,
+            "detected_rules": found,
+        })
+
+    try:
+        changes = compare_synthetic_fixtures(
+            client, root, "clean-v6.bin", "flagged-v6.bin"
+        )
+        added = sorted({finding["rule"] for finding in changes["added_findings"]})
+        matched = (
+            added == ["PCZT-GLOBAL-METADATA"] and
+            changes["no_new_findings"] is False and
+            changes["passed"] is False
+        )
+    except (ZerynexError, OSError):
+        added = []
+        matched = False
+    tests.append({
+        "scenario": "clean-to-flagged",
+        "matched_expectation": matched,
+        "detected_rules": added,
+    })
+    matched_count = sum(case["matched_expectation"] is True for case in tests)
+    return {
+        "passed": matched_count == len(tests),
+        "matched": matched_count,
+        "total": len(tests),
+        "tests": tests,
+        "limitation": "Only approved synthetic PCZT fixtures. Checks policy invariants, not proofs or consensus.",
+    }
+
+
+def create_server(client: ZerynexClient, root: Path):
+    """Bind MCP tools only after the operator explicitly supplies a fixture root."""
+    try:
+        from mcp.server import MCPServer
+    except ImportError:
+        raise ZerynexError("Install the optional MCP dependency: pip install 'zerynex-python[mcp]'") from None
+
+    server = MCPServer("Zerynex Local Privacy Checks")
+
+    @server.tool()
+    def analyze_synthetic_pczt(
+        fixture_name: str,
+        profile: str = "external_signer",
+        deny_transparent: bool = True,
+        deny_sapling: bool = False,
+    ) -> dict:
+        """Analyze an approved synthetic PCZT filename. Return only limited, sanitized Rust policy findings. No wallet access."""
+        try:
+            return scan_fixture(client, root, fixture_name, profile, deny_transparent, deny_sapling)
+        except ZerynexError:
+            return {"error": "Fixture was rejected or the local analysis failed. Review root and policy settings."}
+
+    @server.tool()
+    def compare_synthetic_pczt_stages(
+        baseline_name: str,
+        candidate_name: str,
+        profile: str = "external_signer",
+        deny_transparent: bool = True,
+        deny_sapling: bool = False,
+    ) -> dict:
+        """Compare two approved synthetic PCZT fixtures locally. Returns sanitized changes, never raw data or cryptographic guarantees."""
+        try:
+            return compare_synthetic_fixtures(
+                client,
+                root,
+                baseline_name,
+                candidate_name,
+                profile,
+                deny_transparent,
+                deny_sapling,
+            )
+        except ZerynexError:
+            return {"error": "Fixture was rejected or the local stage comparison failed."}
+
+    @server.tool()
+    def list_synthetic_fixtures() -> dict:
+        """Discover permitted synthetic .bin fixture basenames; never read or return their contents."""
+        try:
+            return discover_synthetic_fixtures(root)
+        except ZerynexError:
+            return {"error": "Cannot inspect the approved fixture directory."}
+
+    @server.tool()
+    def explain_zerynex_rule(rule_id: str) -> dict:
+        """Get reviewed plain-language interpretation and suggested developer follow-up for a known Zerynex rule."""
+        try:
+            return explain_policy_rule(rule_id)
+        except ZerynexError:
+            return {"error": "Unknown supported Zerynex policy rule."}
+
+    @server.tool()
+    def run_synthetic_smoke_suite() -> dict:
+        """Run four local Rust-backed fixture checks and report which expected findings matched. Test failures stay failures."""
+        return evaluate_synthetic_smoke_suite(client, root)
+
+    @server.tool()
+    def zerynex_core_capabilities() -> dict:
+        """Discover validated local Rust CLI operations and limits; no transaction file access."""
+        from .agent_workflows import core_capabilities
+        try:
+            return core_capabilities(client)
+        except ZerynexError:
+            return {"error": "Local Rust CLI capabilities are unavailable."}
+
+    @server.tool()
+    def check_synthetic_zallet_rpc_contract(scenario: str = "baseline") -> dict:
+        """Check a bundled synthetic Zallet PCZT method schema. Scenarios: baseline, missing_method, new_required_parameter. Never connects to an RPC server."""
+        from .agent_workflows import synthetic_zallet_rpc_contract
+        try:
+            return synthetic_zallet_rpc_contract(scenario)
+        except ZerynexError:
+            return {"error": "Synthetic RPC regression scenario was rejected."}
+
+    @server.tool()
+    def audit_synthetic_refund_privacy(scenario: str = "isolated") -> dict:
+        """Audit reviewed metadata-only swap refund scenarios: isolated, risky, regression-expanded. No external paths, addresses or viewing keys."""
+        from .refund_workflows import synthetic_refund_audit
+        try:
+            return synthetic_refund_audit(scenario)
+        except ZerynexError:
+            return {"error": "Synthetic refund privacy scenario was rejected or unavailable."}
+
+    @server.tool()
+    def compare_synthetic_refund_privacy(
+        baseline: str = "risky",
+        candidate: str = "regression-expanded",
+    ) -> dict:
+        """Compare two bundled refund configurations and return only sanitized per-flow risk counts and rule IDs. No secret data."""
+        from .refund_workflows import synthetic_refund_regression
+        try:
+            return synthetic_refund_regression(baseline, candidate)
+        except ZerynexError:
+            return {"error": "Synthetic refund privacy regression was rejected or unavailable."}
+
+    @server.tool()
+    def run_zerynex_developer_preflight() -> dict:
+        """Verify local Rust/PCZT checks, bundled RPC contract and six offline synthetic refund-privacy scenarios. No wallet access."""
+        from .agent_workflows import developer_preflight
+        try:
+            return developer_preflight(client, root)
+        except ZerynexError:
+            return {"error": "Local developer preflight failed or is misconfigured."}
+
+    @server.tool()
+    def zerynex_rule_catalog() -> dict:
+        """Discover the reviewed versioned Rust rule registry. Static metadata only; no wallet, keys or PCZT bytes."""
+        try:
+            from .rules import bundled_rule_catalog
+            source = client.rule_catalog()
+            reviewed = bundled_rule_catalog()
+            if source != reviewed:
+                return {"error": "Local Rust rule catalog differs from packaged SDK; update the trusted versions."}
+            return source
+        except ZerynexError:
+            return {"error": "Local Rust rule catalog is unavailable or unsupported."}
+
+    @server.tool()
+    def zerynex_policy_schema() -> dict:
+        """Describe supported Zcash disclosure checks without accessing private files."""
+        return {
+            "profiles": ["external_signer", "restricted_handoff"],
+            "flags": {
+                "deny_transparent": "Prohibit transparent inputs and outputs.",
+                "deny_sapling": "Prohibit Sapling spends and outputs.",
+            },
+            "default_agent_policy": {
+                "profile": "external_signer",
+                "deny_transparent": True,
+                "deny_sapling": False,
+            },
+            "restrictions": "Synthetic fixtures only. Read-only. Supports comparing two stages. Does not access arbitrary paths or sign transactions.",
+            "limitations": "A pass is not a proof of privacy or Zcash consensus validity.",
+        }
+
+    return server
+
+
+def main() -> None:
+    root_text = os.environ.get("ZERYNEX_AGENT_ALLOWED_ROOT")
+    if not root_text:
+        # Keep stderr output generic; never expose environment variable values.
+        raise SystemExit("Set ZERYNEX_AGENT_ALLOWED_ROOT to a dedicated synthetic-fixture directory.")
+    try:
+        root = Path(root_text).expanduser().resolve(strict=True)
+        if not root.is_dir():
+            raise ZerynexError("Fixture root is not a directory.")
+        client = ZerynexClient()
+        server = create_server(client, root)
+    except (ZerynexError, OSError):
+        raise SystemExit("Cannot start safe local Zerynex agent server.") from None
+    # Official MCP SDK uses local stdio by default; no network listener.
+    server.run()
+
+
+if __name__ == "__main__":
+    main()

zerynex_py/node.py

@@ -0,0 +1,189 @@
+"""Read-only Zcash node readiness for application developers.
+
+Only getblockchaininfo on an explicit numeric loopback endpoint; never remote
+hosts, payment RPCs, wallet methods, transaction content or agent access.
+Cookie authentication is sourced from an operator-owned local file, never argv.
+"""
+from __future__ import annotations
+
+import argparse
+import base64
+from dataclasses import asdict, dataclass
+from http.client import HTTPConnection, HTTPException
+import json
+import math
+import os
+from pathlib import Path
+import stat
+from typing import Any
+
+from .client import ZerynexError
+from .z3 import _safe_loopback_host
+
+MAX_RESPONSE = 64 * 1024
+MAX_COOKIE = 4096
+REQUEST_ID = 'zerynex-readiness-v1'
+
+
+@dataclass(frozen=True)
+class NodeReadiness:
+    schema_version: int
+    network: str | None
+    expected_network: str
+    height: int | None
+    headers: int | None
+    header_lag: int | None
+    initial_sync_complete: bool | None
+    verification_progress: float | None
+    ready: bool
+    checks: tuple[dict[str, str], ...]
+    limitation: str = ('Local JSON-RPC chain-state observation only; not wallet readiness, '
+                       'spend authority, Zallet compatibility, consensus audit, or privacy proof.')
+
+    def as_dict(self) -> dict[str, Any]:
+        data = asdict(self)
+        data['checks'] = list(self.checks)
+        return data
+
+
+def _int(value: Any) -> int | None:
+    return value if type(value) is int and 0 <= value <= 2**32 - 1 else None
+
+
+def evaluate_blockchain_info(
+    result: object, *, expected_network: str = 'test', max_header_lag: int = 2,
+    min_verification_progress: float = 0.999,
+) -> NodeReadiness:
+    """Evaluate untrusted RPC output using an explicit, conservative policy.
+
+    No original response fields are returned; especially no hashes, addresses,
+    value pools, error messages, or opaque server-provided strings.
+    """
+    if expected_network not in ('main', 'test', 'regtest'):
+        raise ZerynexError('Expected Zcash network must be main, test, or regtest.')
+    if type(max_header_lag) is not int or not 0 <= max_header_lag <= 1000:
+        raise ZerynexError('Invalid maximum header lag.')
+    if (type(min_verification_progress) not in (int, float) or
+            not math.isfinite(min_verification_progress) or
+            not 0 < min_verification_progress <= 1):
+        raise ZerynexError('Invalid verification progress threshold.')
+    if not isinstance(result, dict):
+        raise ZerynexError('Node returned an invalid blockchain information object.')
+
+    network = result.get('chain')
+    network = network if type(network) is str and network in ('main', 'test', 'regtest') else None
+    height = _int(result.get('blocks'))
+    headers = _int(result.get('headers'))
+    header_lag = max(0, headers - height) if height is not None and headers is not None else None
+    # zcashd names this boolean initial_block_download_complete; some node
+    # variants expose initialblockdownload instead. Unknown fails closed.
+    ibd_complete = result.get('initial_block_download_complete')
+    if type(ibd_complete) is not bool:
+        ibd = result.get('initialblockdownload')
+        ibd_complete = not ibd if type(ibd) is bool else None
+    progress = result.get('verificationprogress')
+    progress = float(progress) if type(progress) in (int, float) and math.isfinite(progress) and 0 <= progress <= 1 else None
+    checks = (
+        {'code': 'NETWORK_MATCH', 'status': 'pass' if network == expected_network else 'fail' if network else 'unknown'},
+        {'code': 'CHAIN_HEIGHT', 'status': 'pass' if height is not None and headers is not None and headers >= height else 'fail' if height is not None and headers is not None else 'unknown'},
+        {'code': 'HEADER_LAG', 'status': 'pass' if header_lag is not None and header_lag <= max_header_lag else 'fail' if header_lag is not None else 'unknown'},
+        {'code': 'INITIAL_SYNC', 'status': 'pass' if ibd_complete is True else 'fail' if ibd_complete is False else 'unknown'},
+        {'code': 'VERIFICATION_PROGRESS', 'status': 'pass' if progress is not None and progress >= min_verification_progress else 'fail' if progress is not None else 'unknown'},
+    )
+    return NodeReadiness(
+        schema_version=1, network=network, expected_network=expected_network,
+        height=height, headers=headers, header_lag=header_lag,
+        initial_sync_complete=ibd_complete, verification_progress=progress,
+        ready=all(check['status'] == 'pass' for check in checks), checks=checks,
+    )
+
+
+def _cookie_authorization(cookie_file: Path | None) -> str | None:
+    if cookie_file is None:
+        return None
+    try:
+        path = Path(cookie_file)
+        flags = os.O_RDONLY | getattr(os, 'O_NOFOLLOW', 0) | getattr(os, 'O_NONBLOCK', 0)
+        if path.is_symlink():
+            raise OSError
+        fd = os.open(path, flags)
+        with os.fdopen(fd, 'rb') as stream:
+            info = os.fstat(stream.fileno())
+            if (not stat.S_ISREG(info.st_mode) or info.st_size > MAX_COOKIE or
+                    info.st_size == 0 or (info.st_mode & 0o077) != 0):
+                raise OSError
+            raw = stream.read(MAX_COOKIE + 1)
+        if len(raw) > MAX_COOKIE or b':' not in raw or any(b < 33 or b > 126 for b in raw):
+            raise OSError
+        return 'Basic ' + base64.b64encode(raw).decode('ascii')
+    except (OSError, TypeError, ValueError):
+        raise ZerynexError('RPC cookie is invalid or not owner-private (0600 or 0400).') from None
+
+
+def inspect_node_local(
+    *, host: str = '127.0.0.1', port: int = 8232, timeout: float = 1.5,
+    expected_network: str = 'test', max_header_lag: int = 2,
+    cookie_file: Path | None = None,
+) -> NodeReadiness:
+    """Make precisely one loopback-only, read-only getblockchaininfo RPC call."""
+    safe_host = _safe_loopback_host(host)
+    if type(port) is not int or not 1 <= port <= 65535:
+        raise ZerynexError('Invalid local RPC port.')
+    if type(timeout) not in (int, float) or not math.isfinite(timeout) or not 0 < timeout <= 3:
+        raise ZerynexError('RPC timeout must be between zero and three seconds.')
+    # Validate policy before network use.
+    evaluate_blockchain_info({}, expected_network=expected_network, max_header_lag=max_header_lag)
+    auth = _cookie_authorization(cookie_file)
+    headers = {'Content-Type':'application/json', 'Accept':'application/json', 'Connection':'close'}
+    if auth:
+        headers['Authorization'] = auth
+    request = json.dumps({'jsonrpc': '1.0', 'id': REQUEST_ID,
+                          'method': 'getblockchaininfo', 'params': []}, separators=(',', ':'))
+    connection = HTTPConnection(safe_host, port, timeout=float(timeout))
+    try:
+        connection.request('POST', '/', body=request, headers=headers)
+        response = connection.getresponse()
+        if response.status != 200:
+            raise ZerynexError('Local Zcash RPC is unavailable or rejected the request.')
+        if (response.getheader('Content-Length') and
+                int(response.getheader('Content-Length')) > MAX_RESPONSE):
+            raise ZerynexError('Local Zcash RPC response exceeds the size limit.')
+        body = response.read(MAX_RESPONSE + 1)
+        if len(body) > MAX_RESPONSE:
+            raise ZerynexError('Local Zcash RPC response exceeds the size limit.')
+        parsed = json.loads(body)
+        if (not isinstance(parsed, dict) or parsed.get('id') != REQUEST_ID or
+                parsed.get('error') is not None or 'result' not in parsed):
+            raise ZerynexError('Local Zcash RPC returned an invalid envelope.')
+        return evaluate_blockchain_info(parsed['result'], expected_network=expected_network,
+                                        max_header_lag=max_header_lag)
+    except ZerynexError:
+        raise
+    except (OSError, TimeoutError, HTTPException, ValueError, TypeError, UnicodeError, OverflowError):
+        raise ZerynexError('Local Zcash RPC request failed or returned invalid data.') from None
+    finally:
+        connection.close()
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description='Zerynex read-only local Zcash node compatibility probe')
+    parser.add_argument('--host', default='127.0.0.1', help='Numeric loopback or localhost only')
+    parser.add_argument('--port', type=int, default=8232)
+    parser.add_argument('--timeout', type=float, default=1.5)
+    parser.add_argument('--expect-network', default='test', choices=['main','test','regtest'])
+    parser.add_argument('--max-header-lag', type=int, default=2)
+    parser.add_argument('--cookie-file', type=Path, help='Local owner-private RPC cookie; never supply credentials on argv')
+    args = parser.parse_args()
+    try:
+        report = inspect_node_local(host=args.host,port=args.port,timeout=args.timeout,
+                                    expected_network=args.expect_network,
+                                    max_header_lag=args.max_header_lag,cookie_file=args.cookie_file)
+    except ZerynexError:
+        parser.exit(1, 'Zerynex: local node probe failed or configuration rejected.\n')
+    print(json.dumps(report.as_dict(),indent=2))
+    if not report.ready:
+        parser.exit(2)
+
+
+if __name__ == '__main__':
+    main()

zerynex_py/preflight.py

@@ -0,0 +1,42 @@
+"""Installable, offline preflight spanning Rust, synthetic PCZT and RPC checks."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+import sys
+from .agent_workflows import developer_preflight
+from .client import ZerynexClient, ZerynexError
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Run the local Zerynex developer integration preflight.")
+    parser.add_argument("--cli", default=os.environ.get("ZERYNEX_CLI", ""), help="Trusted local Rust CLI executable")
+    parser.add_argument("--fixtures", default=os.environ.get("ZERYNEX_AGENT_ALLOWED_ROOT", ""), help="Explicit synthetic PCZT fixture directory")
+    parser.add_argument("--json", action="store_true", help="Output sanitized machine-readable results")
+    options = parser.parse_args()
+    if not options.cli or not options.fixtures:
+        parser.error("Provide --cli and --fixtures or their ZERYNEX environment values.")
+    try:
+        root = Path(options.fixtures).expanduser().resolve(strict=True)
+        if not root.is_dir():
+            raise ZerynexError("Fixture root unavailable.")
+        client = ZerynexClient(cli=options.cli)
+        report = developer_preflight(client, root)
+    except (ZerynexError, OSError, ValueError):
+        print("Zerynex preflight could not evaluate the local setup.", file=sys.stderr)
+        raise SystemExit(1) from None
+    if options.json:
+        print(json.dumps(report, indent=2))
+    else:
+        print("Zerynex developer preflight:", "PASS" if report["passed"] else "FAIL")
+        print("Synthetic PCZT suite:", report["checks"]["synthetic_pczt_suite"]["matched"], "/", report["checks"]["synthetic_pczt_suite"]["total"])
+        print("Synthetic RPC contract:", "PASS" if report["checks"]["synthetic_rpc_contract"]["passed"] else "FAIL")
+        print("Synthetic refund privacy:", report["checks"]["synthetic_refund_privacy"]["matched"], "/",
+              report["checks"]["synthetic_refund_privacy"]["total"])
+    raise SystemExit(0 if report["passed"] else 2)
+
+
+if __name__ == "__main__":
+    main()