zerynex-python 0.2.0__py3-none-any.whl

zerynex_py/project.py

@@ -0,0 +1,313 @@
+"""Offline, non-destructive Zcash project bootstrap and real Rust integration verification.
+
+Only ships reviewed, nonspendable public test vectors. Never reads or copies
+real wallet PCZTs, keys, node credentials, or unapproved workspace files.
+"""
+from __future__ import annotations
+
+import argparse
+from importlib import resources
+import hashlib
+import json
+import os
+import stat
+from pathlib import Path
+import sys
+
+from .client import Policy, ZerynexClient, ZerynexError
+
+SCHEMA = 1
+MAX_POLICY_BYTES = 4096
+PREFIX = Path('.zerynex')
+POLICY = PREFIX / 'policy.json'
+CLEAN = PREFIX / 'fixtures' / 'clean-v6.bin'
+TRANSPARENT = PREFIX / 'fixtures' / 'transparent-v6.bin'
+MANIFEST = PREFIX / 'project.json'
+WORKFLOW = Path('.github/workflows/zerynex-privacy.yml')
+# A reviewed, immutable and publicly available release-base revision.
+ACTION_SHA = '8dcbbba5584d1f168ec688ca42cd8f185ea904d1'
+POLICY_BYTES = (json.dumps({'profile': 'external_signer', 'deny_transparent': True,
+                            'deny_sapling': False}, indent=2) + '\n').encode()
+WORKFLOW_BYTES = ('''# Synthetic, nonspendable PCZT only. Do not add wallet transactions or keys.
+name: Zcash privacy regression
+on: [push, pull_request]
+permissions:
+  contents: read
+jobs:
+  privacy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      # Review and update this pinned immutable commit deliberately.
+      - uses: Oluwa-Laughter/zerynex@''' + ACTION_SHA + '''
+        id: privacy
+        with:
+          pczt-path: .zerynex/fixtures/clean-v6.bin
+          policy-path: .zerynex/policy.json
+          fail-on-findings: 'true'
+''').encode()
+
+class ProjectError(Exception):
+    """Safe operator-facing message without exposing private project paths."""
+
+
+def _root(path: str) -> Path:
+    candidate = Path(path).expanduser().absolute()
+    if candidate.is_symlink():
+        raise ProjectError('Project root cannot be a symlink.')
+    try:
+        root = candidate.resolve(strict=True)
+        if not root.is_dir():
+            raise ProjectError('Project root must be an existing directory.')
+    except (OSError, ValueError):
+        raise ProjectError('Project root is unavailable.') from None
+    return root
+
+
+def _guard(root: Path, relative: Path, *, must_exist: bool) -> Path:
+    target = root / relative
+    for ancestor in (root, *[root.joinpath(*relative.parts[:i]) for i in range(1, len(relative.parts))]):
+        if ancestor.is_symlink() or (ancestor.exists() and not ancestor.is_dir()):
+            raise ProjectError('Project contains an unsafe destination directory.')
+    if target.is_symlink() or (target.exists() and not target.is_file()):
+        raise ProjectError('Generated project file location is unsafe.')
+    if must_exist and not target.is_file():
+        raise ProjectError('Project integration has not been initialized.')
+    if not must_exist and (target.exists() or target.is_symlink()):
+        raise ProjectError('Initialization would overwrite an existing file; no files were changed.')
+    return target
+
+
+def _assets(*, ci: bool) -> dict[Path, bytes]:
+    fixture_root = resources.files('zerynex_py').joinpath('fixtures')
+    clean = fixture_root.joinpath('clean-v6.bin').read_bytes()
+    flagged = fixture_root.joinpath('transparent-v6.bin').read_bytes()
+    if not (0 < len(clean) <= 8192 and 0 < len(flagged) <= 8192 and clean != flagged):
+        raise ProjectError('Bundled synthetic fixtures are unavailable.')
+    manifest = {'schema_version': SCHEMA, 'synthetic_only': True,
+                'fixture_sha256': {'clean-v6.bin': hashlib.sha256(clean).hexdigest(),
+                                   'transparent-v6.bin': hashlib.sha256(flagged).hexdigest()},
+                'policy_sha256': hashlib.sha256(POLICY_BYTES).hexdigest(),
+                'expected': {'clean_findings': 0, 'transparent_rule': 'PCZT-TRANSPARENT-OUTPUTS'}}
+    bundle = {POLICY: POLICY_BYTES, CLEAN: clean, TRANSPARENT: flagged,
+              MANIFEST: (json.dumps(manifest, indent=2) + '\n').encode()}
+    if ci:
+        bundle[WORKFLOW] = WORKFLOW_BYTES
+    return bundle
+
+
+def initialize(root: Path, *, ci: bool = False) -> dict[str, object]:
+    """Preflight all paths, then write with O_EXCL. Never overwrite project data."""
+    bundle = _assets(ci=ci)
+    targets = {relative: _guard(root, relative, must_exist=False) for relative in bundle}
+    created: list[Path] = []
+    try:
+        for relative, target in targets.items():
+            target.parent.mkdir(parents=True, exist_ok=True)
+            # POSIX O_NOFOLLOW hardens the already validated target path.
+            flags = os.O_CREAT | os.O_EXCL | os.O_WRONLY | getattr(os, 'O_NOFOLLOW', 0)
+            fd = os.open(target, flags, 0o644)
+            created.append(target)
+            with os.fdopen(fd, 'wb') as handle:
+                handle.write(bundle[relative])
+    except (OSError, ValueError):
+        for target in reversed(created):
+            try:
+                target.unlink()
+            except OSError:
+                pass
+        raise ProjectError('Could not safely initialize the project. New files were rolled back.') from None
+    return {'schema_version': SCHEMA, 'initialized': True, 'synthetic_only': True,
+            'ci_configured': ci, 'created_files': [x.as_posix() for x in bundle],
+            'limitation': 'No real PCZT files, node connections, wallet access, or signing.'}
+
+
+def verify(root: Path, cli: str | None) -> dict[str, object]:
+    """Verify ONLY bundled synthetic fixture hashes using the real local Rust CLI."""
+    for file in (MANIFEST, POLICY, CLEAN, TRANSPARENT):
+        _guard(root, file, must_exist=True)
+    expected = _assets(ci=False)
+    # Do not read arbitrarily long or replaced files; bundled fixture hashes must match.
+    for relative, known in expected.items():
+        target = root / relative
+        if target.stat().st_size != len(known):
+            raise ProjectError('Project synthetic fixture or policy has been changed.')
+        with target.open('rb') as handle:
+            if handle.read(len(known) + 1) != known:
+                raise ProjectError('Project synthetic fixture or policy has been changed.')
+    client = ZerynexClient(cli=cli)
+    capabilities = client.capabilities()
+    if 'analyze_pczt' not in capabilities.operations or 'binary' not in capabilities.input_formats:
+        raise ProjectError('The Rust CLI does not support PCZT analysis.')
+    policy = Policy(deny_transparent=True)
+    clean = client.analyze_file(root / CLEAN, policy)
+    transparent = client.analyze_file(root / TRANSPARENT, policy)
+    clean_ok = clean.passed and not clean.findings
+    transparent_ok = (not transparent.passed and
+                      any(f.rule == 'PCZT-TRANSPARENT-OUTPUTS' for f in transparent.findings))
+    passed = clean_ok and transparent_ok
+    return {'schema_version': SCHEMA, 'passed': passed, 'synthetic_only': True,
+            'engine': 'local_rust_cli', 'checks': {
+                'capabilities': True, 'fixture_integrity': True,
+                'clean_fixture': clean_ok, 'transparent_detection': transparent_ok,
+            }, 'limitation': 'Only known nonspendable vectors. Does not certify integration with a real wallet, node or transaction.'}
+
+
+
+# Local source policy: opt-in per PCZT. Never discover, enumerate, or upload
+# user-controlled transaction files. The trusted developer controls this tree.
+def _project_file(root: Path, raw: str) -> Path:
+    if not isinstance(raw, str) or not raw or "\x00" in raw:
+        raise ProjectError('Explicit PCZT path is required.')
+    candidate = Path(raw).expanduser()
+    if not candidate.is_absolute():
+        candidate = root / candidate
+    lexical = Path(os.path.abspath(candidate))
+    try:
+        relative = lexical.relative_to(root)
+    except ValueError:
+        raise ProjectError('PCZT must reside inside the selected project.') from None
+    if not relative.parts:
+        raise ProjectError('Select a PCZT file, not a directory.')
+    # Reject symlink traversal, even if it eventually resolves back inside
+    # the project. The file itself must be regular and bounded.
+    for i in range(1, len(relative.parts) + 1):
+        segment = root.joinpath(*relative.parts[:i])
+        if segment.is_symlink():
+            raise ProjectError('PCZT symlinks are not permitted.')
+    try:
+        fd = os.open(lexical, os.O_RDONLY | getattr(os, 'O_NOFOLLOW', 0) |
+                     getattr(os, 'O_NONBLOCK', 0))
+        try:
+            meta = os.fstat(fd)
+            if not stat.S_ISREG(meta.st_mode) or not 0 < meta.st_size <= 8 * 1024 * 1024:
+                raise ProjectError('PCZT must be a regular file of at most 8 MiB.')
+        finally:
+            os.close(fd)
+    except (OSError, ValueError):
+        raise ProjectError('Selected PCZT file is unavailable.') from None
+    return lexical
+
+
+def _policy_from_project(root: Path) -> Policy:
+    policy_path = _guard(root, POLICY, must_exist=True)
+    try:
+        fd = os.open(policy_path, os.O_RDONLY | getattr(os, 'O_NOFOLLOW', 0) |
+                     getattr(os, 'O_NONBLOCK', 0))
+        try:
+            metadata = os.fstat(fd)
+            if not stat.S_ISREG(metadata.st_mode) or not 0 < metadata.st_size <= MAX_POLICY_BYTES:
+                raise ProjectError('Project policy must be a bounded regular file.')
+            with os.fdopen(fd, 'rb', closefd=False) as stream:
+                raw = stream.read(MAX_POLICY_BYTES + 1)
+        finally:
+            os.close(fd)
+        def unique(entries: list[tuple[str, object]]) -> dict[str, object]:
+            parsed: dict[str, object] = {}
+            for key, value in entries:
+                if key in parsed:
+                    raise ValueError('duplicate')
+                parsed[key] = value
+            return parsed
+        data = json.loads(raw, object_pairs_hook=unique,
+                          parse_constant=lambda _: (_ for _ in ()).throw(ValueError('constant')))
+        if (not isinstance(data, dict) or set(data) != {'profile', 'deny_transparent', 'deny_sapling'}
+                or data['profile'] not in ('external_signer', 'restricted_handoff')
+                or type(data['deny_transparent']) is not bool
+                or type(data['deny_sapling']) is not bool):
+            raise ValueError('policy')
+        return Policy(profile=data['profile'], deny_transparent=data['deny_transparent'],
+                      deny_sapling=data['deny_sapling'])
+    except (OSError, ValueError, TypeError, UnicodeError, ZerynexError):
+        raise ProjectError('Project policy is invalid or cannot be read.') from None
+
+
+def _safe_summary(rule_ids: list[str]) -> list[str]:
+    # Field paths, arbitrary report explanations and RPC metadata must never
+    # escape into terminal output or agent logs. Output only known rule IDs.
+    from .rules import bundled_rule_catalog
+    catalog = bundled_rule_catalog()
+    known = {entry['id'] for entry in catalog['rules']}
+    if any(rule not in known for rule in rule_ids):
+        raise ProjectError('Rust engine returned an unsupported policy rule.')
+    return sorted(set(rule_ids))
+
+
+def check_project(root: Path, cli: str | None, pczt: str) -> dict[str, object]:
+    """Run one explicitly supplied PCZT through the real local Rust engine."""
+    _guard(root, MANIFEST, must_exist=True)
+    policy = _policy_from_project(root)
+    candidate = _project_file(root, pczt)
+    report = ZerynexClient(cli=cli).analyze_file(candidate, policy)
+    return {'schema_version': SCHEMA, 'passed': report.passed,
+            'input': 'explicit_local_file', 'engine': 'local_rust_cli',
+            'finding_count': len(report.findings),
+            'rule_ids': _safe_summary([item.rule for item in report.findings]),
+            'limitation': 'Structural policy findings only; not a signature, proof, anonymity or payment verification. No raw PCZT fields are returned.'}
+
+
+def compare_project(root: Path, cli: str | None, before: str, after: str) -> dict[str, object]:
+    """Check explicit stage regression; does not assume equivalent transactions."""
+    _guard(root, MANIFEST, must_exist=True)
+    policy = _policy_from_project(root)
+    baseline = _project_file(root, before)
+    candidate = _project_file(root, after)
+    if baseline == candidate:
+        raise ProjectError('Before and after PCZT files must be distinct.')
+    result = ZerynexClient(cli=cli).compare_files(baseline, candidate, policy)
+    return {'schema_version': SCHEMA, 'passed': result.passed,
+            'input': 'two_explicit_local_files',
+            'engine': 'local_rust_cli', 'no_new_findings': result.no_new_findings,
+            'before_findings_count': result.before_findings_count,
+            'after_findings_count': result.after_findings_count,
+            'added_rule_ids': _safe_summary([rule for rule, _ in result.added_findings]),
+            'resolved_rule_ids': _safe_summary([rule for rule, _ in result.resolved_findings]),
+            'limitation': 'Only selected policy regressions; not equivalent payments, proof validity or safe signing. No raw PCZT fields are returned.'}
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description='Initialize and verify offline Zerynex integration in another project.')
+    actions = parser.add_subparsers(dest='action', required=True)
+    for name in ('init', 'verify', 'check', 'compare'):
+        sub = actions.add_parser(name)
+        sub.add_argument('--project', required=True, help='Existing developer project directory')
+        sub.add_argument('--json', action='store_true', help='Sanitized machine-readable summary')
+        if name == 'init':
+            sub.add_argument('--ci', action='store_true', help='Scaffold pinned synthetic-only GitHub Action')
+        else:
+            sub.add_argument('--cli', default=os.environ.get('ZERYNEX_CLI'),
+                             help='Locally installed trusted Rust CLI path')
+        if name == 'check':
+            sub.add_argument('--pczt', required=True, help='Explicit PCZT path inside this project')
+        elif name == 'compare':
+            sub.add_argument('--before', required=True, help='Explicit earlier PCZT file')
+            sub.add_argument('--after', required=True, help='Explicit later PCZT file')
+    args = parser.parse_args()
+    try:
+        root = _root(args.project)
+        if args.action == 'init':
+            result = initialize(root, ci=args.ci)
+        elif args.action == 'verify':
+            result = verify(root, args.cli)
+        elif args.action == 'check':
+            result = check_project(root, args.cli, args.pczt)
+        else:
+            result = compare_project(root, args.cli, args.before, args.after)
+    except (ProjectError, ZerynexError, OSError, ValueError):
+        # Never echo CLI output, selected PCZT bytes or private workspace paths.
+        print('Zerynex project setup or local verification was rejected.', file=sys.stderr)
+        raise SystemExit(1) from None
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        print('Zerynex project', args.action, 'PASS' if result.get('passed', result.get('initialized')) else 'FAIL')
+        if args.action == 'init':
+            print('Synthetic-only integration created. Use verify with your trusted Rust CLI.')
+        elif args.action == 'verify':
+            print('Local Rust CLI, synthetic fixture integrity and expected rule behavior checked.')
+        else:
+            print('Explicit local PCZT policy report: no sensitive transaction content included.')
+    raise SystemExit(0 if result.get('passed', result.get('initialized')) else 2)
+
+if __name__ == '__main__':
+    main()

zerynex_py/refund_privacy.py

@@ -0,0 +1,252 @@
+"""Offline, metadata-only refund linkability checks for Zcash swap integrations.
+
+This intentionally does NOT process Zcash addresses, viewing keys, spend keys,
+refund payments, PIR queries, or cryptographic secrets. References in the
+input are developer-supplied random 128-bit opaque tokens, not hashes of keys.
+Reports contain only fixed rule identifiers and aggregate counts.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+import re
+import stat
+import sys
+from typing import Any
+
+MAX_INPUT = 64 * 1024
+MAX_ENTRIES = 100
+TOKEN = re.compile(r'^[0-9a-f]{32}$')
+RULES = (
+    'SWAP-REFUND-ADDRESS-REUSE',
+    'SWAP-VIEWING-SCOPE-REUSE',
+    'SWAP-PUBLIC-REFUND-UNSCOPED',
+    'SWAP-REFUND-LOOKUP-DISCLOSURE',
+    'SWAP-SPENDING-KEY-CUSTODY-UNVERIFIED',
+)
+LIMITATION = ('Static, self-declared integration metadata only. No viewing-key cryptography, quantum-security, PIR, '
+              'wallet behavior, chain activity, or safe recovery is verified. Do not provide addresses or keys.')
+
+class RefundAuditInputError(ValueError):
+    pass
+
+
+def _record(obj: object, keys: set[str]) -> dict[str, object]:
+    if type(obj) is not dict or set(obj) != keys:
+        raise RefundAuditInputError('Invalid privacy exposure manifest shape.')
+    return obj
+
+
+def _token(value: object) -> str:
+    if type(value) is not str or not TOKEN.fullmatch(value):
+        raise RefundAuditInputError('Expected an opaque 128-bit random reference, not an address or key.')
+    return value
+
+
+def _evaluate_manifest(manifest: object) -> tuple[dict[str, object], set[tuple[str, str]]]:
+    """Evaluate declarations while retaining opaque in-memory event identity."""
+    root = _record(manifest, {'schema_version', 'flows'})
+    if type(root['schema_version']) is not int or root['schema_version'] != 1:
+        raise RefundAuditInputError('Unsupported refund audit schema.')
+    flows = root['flows']
+    if type(flows) is not list or not 1 <= len(flows) <= MAX_ENTRIES:
+        raise RefundAuditInputError('Expected 1 to 100 application-declared swap flows.')
+    normalized: list[dict[str, Any]] = []
+    seen_flow: set[str] = set()
+    keyset = {'flow_ref', 'refund_address_ref', 'viewing_scope_ref',
+              'published_publicly', 'lookup_mode', 'spending_key_custody'}
+    for item in flows:
+        row = _record(item, keyset)
+        refs = {k: _token(row[k]) for k in ('flow_ref', 'refund_address_ref', 'viewing_scope_ref')}
+        if refs['flow_ref'] in seen_flow:
+            raise RefundAuditInputError('Duplicate swap-flow record.')
+        seen_flow.add(refs['flow_ref'])
+        if type(row['published_publicly']) is not bool:
+            raise RefundAuditInputError('Expected an explicit public-disclosure boolean.')
+        if row['lookup_mode'] not in ('private_claimed', 'direct', 'unknown') or type(row['lookup_mode']) is not str:
+            raise RefundAuditInputError('Invalid wallet refund-lookup declaration.')
+        if row['spending_key_custody'] not in ('wallet_claimed', 'external', 'unknown') or type(row['spending_key_custody']) is not str:
+            raise RefundAuditInputError('Invalid spending-key custody declaration.')
+        normalized.append({**refs, 'published_publicly': row['published_publicly'],
+                           'lookup_mode': row['lookup_mode'], 'spending_key_custody': row['spending_key_custody']})
+
+    address_count: dict[str, int] = {}
+    scope_count: dict[str, int] = {}
+    for row in normalized:
+        address_count[row['refund_address_ref']] = address_count.get(row['refund_address_ref'], 0) + 1
+        scope_count[row['viewing_scope_ref']] = scope_count.get(row['viewing_scope_ref'], 0) + 1
+    findings: set[str] = set()
+    # Opaque flow references are intentionally never returned in a report.
+    events: set[tuple[str, str]] = set()
+    for row in normalized:
+        def flag(rule: str) -> None:
+            findings.add(rule)
+            events.add((row['flow_ref'], rule))
+
+        if address_count[row['refund_address_ref']] > 1:
+            flag('SWAP-REFUND-ADDRESS-REUSE')
+        if scope_count[row['viewing_scope_ref']] > 1:
+            flag('SWAP-VIEWING-SCOPE-REUSE')
+        if row['published_publicly'] and scope_count[row['viewing_scope_ref']] > 1:
+            flag('SWAP-PUBLIC-REFUND-UNSCOPED')
+        if row['lookup_mode'] != 'private_claimed':
+            flag('SWAP-REFUND-LOOKUP-DISCLOSURE')
+        if row['spending_key_custody'] != 'wallet_claimed':
+            flag('SWAP-SPENDING-KEY-CUSTODY-UNVERIFIED')
+    return {
+        'schema_version': 1, 'passed': not findings, 'flows_checked': len(normalized),
+        'public_refund_flows': sum(bool(row['published_publicly']) for row in normalized),
+        'finding_count': len(findings), 'rule_ids': sorted(findings),
+        'status': 'declaration_review_only', 'limitation': LIMITATION,
+    }, events
+
+
+def audit_manifest(manifest: object) -> dict[str, object]:
+    """Sanitized, single-manifest privacy-declaration review."""
+    return _evaluate_manifest(manifest)[0]
+
+
+def compare_manifests(baseline: object, current: object) -> dict[str, object]:
+    """Diff per-flow risk events without ever exporting opaque references.
+
+    A rule already present in the baseline can still be *new* on another
+    flow. New flow IDs are treated as new integration declarations.
+    """
+    before, old_events = _evaluate_manifest(baseline)
+    after, new_events = _evaluate_manifest(current)
+    added = new_events - old_events
+    resolved = old_events - new_events
+    return {
+        'schema_version': 1,
+        'passed': not added,
+        'status': 'declaration_regression_review_only',
+        'baseline_flows_checked': before['flows_checked'],
+        'current_flows_checked': after['flows_checked'],
+        'baseline_risk_events': len(old_events),
+        'current_risk_events': len(new_events),
+        'new_risk_events': len(added),
+        'resolved_risk_events': len(resolved),
+        'new_rule_ids': sorted({rule for _, rule in added}),
+        'resolved_rule_ids': sorted({rule for _, rule in resolved}),
+        'limitation': (
+            'Only application-declared logical flow identity and static risk changes. '
+            'It cannot attest stable wallet identity, viewing-key isolation, private lookup, '
+            'quantum resistance or transaction privacy. References are never returned.'
+        ),
+    }
+
+
+def _unique_pairs(pairs: list[tuple[str, object]]) -> dict[str, object]:
+    values: dict[str, object] = {}
+    for key, value in pairs:
+        if key in values:
+            raise RefundAuditInputError('Duplicate JSON field.')
+        values[key] = value
+    return values
+
+
+def read_manifest(path: str) -> dict[str, object]:
+    target = Path(path)
+    if target.is_symlink():
+        raise RefundAuditInputError('Symlinks are not supported.')
+    try:
+        flags = os.O_RDONLY | getattr(os, 'O_NOFOLLOW', 0) | getattr(os, 'O_NONBLOCK', 0)
+        fd = os.open(target, flags)
+        try:
+            meta = os.fstat(fd)
+            if not stat.S_ISREG(meta.st_mode) or meta.st_size <= 0 or meta.st_size > MAX_INPUT:
+                raise RefundAuditInputError('Manifest is not a bounded regular file.')
+            with os.fdopen(fd, 'rb', closefd=False) as stream:
+                raw = stream.read(MAX_INPUT + 1)
+            if len(raw) > MAX_INPUT:
+                raise RefundAuditInputError('Manifest exceeds file limit.')
+        finally:
+            os.close(fd)
+        parsed = json.loads(raw, object_pairs_hook=_unique_pairs,
+                            parse_constant=lambda _: (_ for _ in ()).throw(RefundAuditInputError('Invalid numeric constant.')))
+        if type(parsed) is not dict:
+            raise RefundAuditInputError('Manifest must be a JSON object.')
+        return parsed
+    except (OSError, UnicodeError, ValueError, TypeError):
+        raise RefundAuditInputError('Invalid local refund privacy manifest.') from None
+
+
+
+def sarif_report(report: dict[str, object]) -> dict[str, object]:
+    """Portable SARIF 2.1.0 rules without source locations or sensitive refs."""
+    expected = ('new_rule_ids' if report.get('status') == 'declaration_regression_review_only'
+                else 'rule_ids')
+    present = report.get(expected)
+    if type(present) is not list or any(type(rule) is not str or rule not in RULES for rule in present):
+        raise RefundAuditInputError('Invalid internal audit findings.')
+    ordered = sorted(set(present))
+    return {
+        '$schema': 'https://json.schemastore.org/sarif-2.1.0.json',
+        'version': '2.1.0',
+        'runs': [{
+            'tool': {'driver': {
+                'name': 'Zerynex Refund Privacy Audit',
+                'informationUri': 'https://zerynex.vercel.app/docs/refund-privacy-audit',
+                'semanticVersion': '0.1.0',
+                'rules': [
+                    {'id': name,
+                     'shortDescription': {'text': 'Review declared Zcash swap refund privacy exposure'},
+                     'helpUri': 'https://zerynex.vercel.app/docs/refund-privacy-audit'}
+                    for name in RULES
+                ],
+            }},
+            'results': [
+                {'ruleId': name, 'level': 'warning',
+                 'message': {'text': 'Application-declared refund privacy risk requires review.'}}
+                for name in ordered
+            ],
+            'properties': {
+                'declarationOnly': True,
+                'mode': 'regression' if expected == 'new_rule_ids' else 'full_audit',
+                'warningCount': len(ordered),
+                'noInputLocations': True,
+            },
+        }],
+    }
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description='Offline self-declared swap refund and viewing-key isolation audit.')
+    parser.add_argument('--manifest', required=True, help='Current local public-safe metadata JSON, never addresses or keys')
+    parser.add_argument('--baseline', help='Optional earlier metadata JSON: fail only on newly introduced per-flow risks')
+    output = parser.add_mutually_exclusive_group()
+    output.add_argument('--json', action='store_true', help='Sanitized machine-readable report')
+    output.add_argument('--sarif', action='store_true', help='Location-free SARIF 2.1.0 warnings')
+    args = parser.parse_args()
+    try:
+        if args.baseline:
+            before = read_manifest(args.baseline)
+            after = read_manifest(args.manifest)
+            try:
+                same = os.path.samefile(args.baseline, args.manifest)
+            except OSError:
+                raise RefundAuditInputError('Manifest files are unavailable.') from None
+            if same:
+                raise RefundAuditInputError('Baseline and current file must differ.')
+            report = compare_manifests(before, after)
+        else:
+            report = audit_manifest(read_manifest(args.manifest))
+    except RefundAuditInputError:
+        print('Refund privacy metadata rejected; no input contents were printed.', file=sys.stderr)
+        raise SystemExit(1) from None
+    if args.json:
+        print(json.dumps(report, indent=2))
+    elif args.sarif:
+        print(json.dumps(sarif_report(report), indent=2))
+    else:
+        if args.baseline:
+            print('Refund privacy regression:', 'NO NEW DECLARED RISKS' if report['passed'] else 'NEW RISKS DETECTED')
+            print('New events:', report['new_risk_events'], 'Rule IDs:', ', '.join(report['new_rule_ids']))
+        else:
+            print('Refund privacy metadata:', 'NO DECLARED RISKS' if report['passed'] else 'REVIEW REQUIRED')
+            print('Flows:', report['flows_checked'], 'Rule IDs:', ', '.join(report['rule_ids']))
+    raise SystemExit(0 if report['passed'] else 2)
+
+if __name__ == '__main__':
+    main()