scrypto-audit-kit 0.5.0__py3-none-any.whl

scrypto_audit_kit/__init__.py

@@ -0,0 +1,56 @@
+"""scrypto-audit-kit — the deterministic Python core as an importable library.
+
+`pip install scrypto-audit-kit` makes this package importable:
+
+    from scrypto_audit_kit import static_analysis, sak_lib, attest, gen_tests
+
+    findings = static_analysis.analyze_package("path/to/your/scrypto/package")
+    verdict  = sak_lib.gate_verdict({"findings": findings}, fail_on="high")
+
+The deterministic tools (static_analysis, gen_tests, attest) and helpers (sak_lib) need
+no API key and no toolchain. The full LLM audit (audit.sh) and the MCP server's
+audit_package tool additionally need a kit clone + aider + ANTHROPIC_API_KEY — see
+docs/sdk.md for what runs where.
+
+Implementation note: the modules in this directory cross-import by bare name
+(`import sak_lib`) — the historical layout, which keeps a bare `git clone` runnable with
+no install. So that those bare imports resolve when the directory is imported as the
+`scrypto_audit_kit` package, we put the package directory on sys.path here. Converting the
+cross-imports to relative imports is tracked for a future release (see ROADMAP.md).
+"""
+import os as _os
+import sys as _sys
+
+_PKG_DIR = _os.path.dirname(_os.path.abspath(__file__))
+if _PKG_DIR not in _sys.path:
+    _sys.path.insert(0, _PKG_DIR)
+
+
+def _read_version():
+    """Kit version: the VERSION file (clone / editable install), else installed metadata."""
+    version_file = _os.path.join(_os.path.dirname(_PKG_DIR), "VERSION")
+    try:
+        with open(version_file, encoding="utf-8") as fh:
+            return fh.read().strip()
+    except OSError:
+        pass
+    try:
+        from importlib.metadata import PackageNotFoundError, version
+        try:
+            return version("scrypto-audit-kit")
+        except PackageNotFoundError:
+            return "unknown"
+    except ImportError:
+        return "unknown"
+
+
+__version__ = _read_version()
+
+# Re-export the deterministic, no-API-key core. These bind the same module objects the
+# internal cross-imports use, so `scrypto_audit_kit.sak_lib` is the one the tools call.
+import sak_lib as sak_lib  # noqa: E402
+import static_analysis as static_analysis  # noqa: E402
+import attest as attest  # noqa: E402
+import gen_tests as gen_tests  # noqa: E402
+
+__all__ = ["sak_lib", "static_analysis", "attest", "gen_tests", "__version__"]

scrypto_audit_kit/attest.py

@@ -0,0 +1,128 @@
+#!/usr/bin/env python3
+"""Turn a pre-audit report.json into an on-chain attestation payload + a Radix manifest.
+
+The bridge from a kit run to the L3 attestation registry (see attestation/). It reads the
+report's source_hash, hashes the report (and optionally the built wasm), counts findings by
+severity, derives the level, and renders a transaction manifest that calls `attest(...)` on a
+deployed registry component. Stdlib only. Importable + CLI; also the attestation_payload MCP tool.
+"""
+import argparse
+import hashlib
+import json
+import sys
+
+import sak_lib
+
+
+def _sha256_file(path):
+    h = hashlib.sha256()
+    with open(path, "rb") as fh:
+        for chunk in iter(lambda: fh.read(65536), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _u16(n):
+    """Clamp a count to the u16 the on-chain field accepts (so >65535 findings can't break it)."""
+    try:
+        return max(0, min(int(n), 65535))
+    except (TypeError, ValueError):
+        return 0
+
+
+def _derive_level(report):
+    """L1-static when only the static tier ran, else L2-hybrid. Derived from the harness-stamped
+    model (authoritative), not from whether findings happen to be tagged — so a clean full run
+    (0 findings) is still L2, not a spurious downgrade."""
+    model = str(report.get("kit", {}).get("model", "")).lower()
+    return "L1-static" if "static-only" in model else "L2-hybrid"
+
+
+def build_payload(report_path, wasm_path="", level=""):
+    """Compute the AttestationInput payload (the fields the registry's attest() expects)."""
+    report = sak_lib.load_report(report_path)
+    counts = sak_lib.severity_counts(report.get("findings", []))
+    kit = report.get("kit", {})
+    return {
+        "source_hash": report.get("target", {}).get("source_hash", ""),
+        "report_hash": _sha256_file(report_path),
+        "wasm_hash": _sha256_file(wasm_path) if wasm_path else "",
+        "kit_version": kit.get("version", "unknown"),
+        "checklist_version": kit.get("checklist_version", "unknown"),
+        "level": level or _derive_level(report),
+        "critical": _u16(counts.get("critical", 0)),
+        "high": _u16(counts.get("high", 0)),
+        "medium": _u16(counts.get("medium", 0)),
+        "low": _u16(counts.get("low", 0)),
+        "info": _u16(counts.get("info", 0)),
+    }
+
+
+_STR_FIELDS = ["source_hash", "report_hash", "wasm_hash", "kit_version", "checklist_version", "level"]
+_U16_FIELDS = ["critical", "high", "medium", "low", "info"]
+
+
+def render_manifest(payload, component, account, fee="10"):
+    """Render a Radix transaction manifest calling attest(AttestationInput) + depositing the NFT."""
+    def quote(v):
+        s = str(v).replace("\\", "\\\\").replace('"', '\\"')
+        s = s.replace("\n", " ").replace("\r", " ")  # no control chars in a manifest string literal
+        return '"' + s + '"'
+
+    rows = [f"        {quote(payload[k])}," for k in _STR_FIELDS]
+    rows += [f"        {int(payload[k])}u16," for k in _U16_FIELDS]
+    rows[-1] = rows[-1].rstrip(",")  # the final tuple element takes no trailing comma
+    tuple_body = "\n".join(rows)
+    return f"""# scrypto-audit-kit attestation — generated; review before submitting.
+# The account deposit method may need adjusting to your network's current API.
+CALL_METHOD
+    Address("{account}")
+    "lock_fee"
+    Decimal("{fee}")
+;
+CALL_METHOD
+    Address("{component}")
+    "attest"
+    Tuple(
+{tuple_body}
+    )
+;
+CALL_METHOD
+    Address("{account}")
+    "try_deposit_batch_or_abort"
+    Expression("ENTIRE_WORKTOP")
+    Enum<0u8>()
+;
+"""
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Attestation payload + manifest from a report.json.")
+    ap.add_argument("report", help="path to a report.json")
+    ap.add_argument("--wasm", default="", help="path to the built blueprint wasm to hash")
+    ap.add_argument("--level", default="", help="override the derived level (L1-static / L2-hybrid / ...)")
+    ap.add_argument("--component", default="", help="deployed attestation registry component address")
+    ap.add_argument("--account", default="", help="your account address (pays the fee, receives the NFT)")
+    ap.add_argument("--out-manifest", default="", help="write the manifest to this file")
+    ap.add_argument("--json", action="store_true", help="print the payload JSON (even if --component is given)")
+    args = ap.parse_args()
+
+    payload = build_payload(args.report, args.wasm, args.level)
+    sys.stderr.write(f"[attest] level {payload['level']} · {payload['critical']}C/{payload['high']}H · "
+                     f"source {payload['source_hash'][:12]}\n")
+
+    if args.component and args.account and not args.json:
+        manifest = render_manifest(payload, args.component, args.account)
+        if args.out_manifest:
+            with open(args.out_manifest, "w", encoding="utf-8") as fh:
+                fh.write(manifest)
+        else:
+            sys.stdout.write(manifest)
+    else:
+        json.dump(payload, sys.stdout, indent=2)
+        sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scrypto_audit_kit/ci-gate.py

@@ -0,0 +1,14 @@
+#!/usr/bin/env python3
+"""Compatibility shim → ci_gate.main().
+
+The gate logic lives in ci_gate.py (an importable, un-hyphenated module so it can back the
+`sak-gate` console entry point). This hyphenated path is kept verbatim because the pre-audit
+CI workflow (.github/workflows/pre-audit.yml), the docs, and tests/test_security.py invoke
+`bin/ci-gate.py` directly — they all keep working unchanged.
+"""
+import sys
+
+from ci_gate import main  # bin/ is sys.path[0] when this runs as a script
+
+if __name__ == "__main__":
+    sys.exit(main())

scrypto_audit_kit/ci_gate.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python3
+"""CI gate: fail the build when a pre-audit report has findings at/above a severity.
+
+Reads a report.json (or every *.json in a directory) and exits non-zero when any
+finding's severity is >= --fail-on. Backs an honest "pre-audit passing" badge.
+Stdlib only; shares its logic with the MCP server via sak_lib.
+
+This is the importable, un-hyphenated home of the gate CLI (it backs the `sak-gate`
+console entry point). The historical `bin/ci-gate.py` is a thin shim that calls main()
+here, so existing invocations (the pre-audit CI workflow, tests) keep working.
+"""
+import argparse
+import sys
+
+import sak_lib
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--reports", required=True, help="a report.json file or a directory of them")
+    ap.add_argument("--fail-on", default="high", help="none | critical | high | medium | low (default: high)")
+    ap.add_argument("--allow-missing", action="store_true",
+                    help="pass when no report is found (default: fail closed)")
+    args = ap.parse_args()
+
+    # Fail CLOSED: a missing, unreadable, or malformed report must not pass the gate.
+    # Shares sak_lib.collect_findings with the MCP gate so both surfaces fail closed identically.
+    try:
+        findings = sak_lib.collect_findings(args.reports, allow_missing=args.allow_missing)
+    except sak_lib.GateError as exc:
+        print(f"::error::{exc} — failing closed (use --allow-missing to opt out)", file=sys.stderr)
+        return 1
+    if findings is None:
+        print(f"warn: no report.json at {args.reports} — passing (--allow-missing)", file=sys.stderr)
+        return 0
+
+    try:
+        verdict = sak_lib.gate_verdict({"findings": findings}, args.fail_on)
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+    print(f"pre-audit gate: {verdict['total']} findings "
+          f"({sak_lib.counts_summary(verdict['counts'])}); threshold = {verdict['fail_on']}")
+    if not verdict["passed"]:
+        print(f"::error::pre-audit gate failed — found {verdict['worst']} finding(s) "
+              f"at or above '{verdict['fail_on']}'")
+        return 1
+    print("pre-audit gate passed.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scrypto_audit_kit/extract-report.py

@@ -0,0 +1,229 @@
+#!/usr/bin/env python3
+"""Split a pre-audit run into a clean markdown report + a machine-readable report.json.
+
+The model emits a human markdown report followed by a fenced ```json block conforming
+to schema/audit-report.schema.json. This script:
+
+  1. pulls the LAST valid JSON block out of the raw output,
+  2. stamps it with authoritative provenance (kit version, model, checklist version,
+     source hash, ...) — the harness knows these, the model does not,
+  3. writes report.json,
+  4. rewrites the markdown without the JSON appendix, with a one-line provenance header.
+
+Soft-fails: if no valid JSON block is found, the markdown is still written and the script
+exits 0 (the human report is never lost to a structured-output hiccup). Schema validation
+is performed only if `jsonschema` is importable — it is never a hard dependency.
+
+Stdlib only.
+"""
+import argparse
+import json
+import re
+import sys
+
+import sak_lib
+
+FENCE_RE = re.compile(r"```(?:json)?\s*\n(.*?)\n```", re.DOTALL)
+
+
+def extract_json_blocks(text):
+    """Return (span, parsed_obj) for each fenced JSON block that parses, in document order."""
+    blocks = []
+    for m in FENCE_RE.finditer(text):
+        body = m.group(1).strip()
+        if not body.startswith("{"):
+            continue
+        try:
+            obj = json.loads(body)
+        except json.JSONDecodeError:
+            continue
+        blocks.append((m.span(), obj))
+    return blocks
+
+
+def select_appendix(text, blocks, nonce):
+    """Pick the authoritative JSON block.
+
+    With a per-run `nonce`, a block is authentic ONLY if the `sak:nonce:<nonce>` marker is the
+    LAST non-whitespace content immediately before its opening fence — ADJACENCY, not a fuzzy
+    "within 200 chars" window. The old window let a small real block lend its marker to a LATER
+    attacker block (which then won as the last authed block); adjacency + scanning only the gap
+    since the previous block closes that. If MORE THAN ONE block authenticates, refuse (a run
+    carries exactly one) and prefer the FIRST otherwise. Without a nonce (static-only / legacy)
+    the last block is returned.
+
+    Returns (selected_block_or_None, authenticated, ambiguous).
+    """
+    if not nonce:
+        return (blocks[-1] if blocks else None), True, False
+    marker = f"sak:nonce:{nonce}"
+    authed = []
+    prev_end = 0
+    for span, obj in blocks:
+        start, end = span
+        preamble = text[prev_end:start]  # only the gap since the previous block — no reach-back
+        prev_end = end
+        idx = preamble.rfind(marker)
+        if idx == -1:
+            continue
+        tail = preamble[idx + len(marker):].replace("-->", "", 1)  # only the comment close may follow
+        if tail.strip() == "":
+            authed.append((span, obj))
+    if len(authed) > 1:
+        return None, False, True  # ambiguous — refuse, fail safe
+    return (authed[0] if authed else None), bool(authed), False
+
+
+def strip_json_appendix(text, span):
+    """Remove the JSON fenced block, plus the `<!-- machine-readable -->` marker and the
+    `---` rule that precede it, from the markdown."""
+    start, end = span
+    before = text[:start]
+    after = text[end:]
+    # the marker comment sits just above the block; the `---` rule sits just above that
+    before = re.sub(r"\s*<!--[^>]*?(?:machine-readable|sak:nonce:)[^>]*?-->\s*$", "\n", before, flags=re.IGNORECASE)
+    before = re.sub(r"\s*\n-{3,}[ \t]*$", "\n", before)
+    cleaned = before.rstrip() + "\n"
+    if after.strip():
+        cleaned += after.lstrip()
+    return cleaned
+
+
+def soft_validate(obj, schema_path):
+    """Best-effort schema validation. Returns a list of human-readable problems (empty = ok/skipped)."""
+    try:
+        import jsonschema  # type: ignore
+    except Exception:
+        return []  # not installed — skip silently
+    try:
+        with open(schema_path, encoding="utf-8") as fh:
+            schema = json.load(fh)
+        jsonschema.Draft202012Validator(schema).validate(obj)
+        return []
+    except FileNotFoundError:
+        return []
+    except jsonschema.ValidationError as exc:  # type: ignore
+        return [exc.message]
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--raw", required=True, help="path to the raw markdown report (read)")
+    ap.add_argument("--out-json", required=True, help="path to write report.json")
+    ap.add_argument("--out-md", required=True, help="path to write the cleaned markdown (may equal --raw)")
+    ap.add_argument("--kit-version", default="unknown")
+    ap.add_argument("--model", default="unknown")
+    ap.add_argument("--checklist-version", default="unknown")
+    ap.add_argument("--reference-set", default="")
+    ap.add_argument("--repo", default="")
+    ap.add_argument("--package", default="")
+    ap.add_argument("--source-hash", default="")
+    ap.add_argument("--files", type=int, default=0)
+    ap.add_argument("--generated-at", default="")
+    ap.add_argument("--schema", default="", help="optional schema path for soft validation")
+    ap.add_argument("--static-json", default="", help="optional JSON file of static findings to merge in")
+    ap.add_argument("--nonce", default="", help="per-run nonce; only a JSON block carrying its marker is trusted")
+    args = ap.parse_args()
+
+    with open(args.raw, encoding="utf-8") as fh:
+        raw = fh.read()
+
+    static_findings = []
+    static_ran = False
+    if args.static_json:
+        try:
+            with open(args.static_json, encoding="utf-8") as fh:
+                static_findings = json.load(fh)
+            static_ran = True  # the static pass ran (even if it found nothing) — a clean run is attestable
+        except (OSError, ValueError) as exc:
+            print(f"warn: could not read static findings {args.static_json}: {exc}", file=sys.stderr)
+
+    blocks = extract_json_blocks(raw)
+    selected, authenticated, ambiguous = select_appendix(raw, blocks, args.nonce)
+    if args.nonce and blocks and not authenticated:
+        # JSON block(s) present but none is uniquely nonce-authenticated (missing marker, or
+        # ambiguous — >1 authed). Possible injection: a blueprint getting the model to echo a
+        # forged block. Fail safe — never write report.json, and WITHHOLD the model's prose
+        # (a clean-looking narrative an operator might share) rather than emit it invisibly.
+        reason = "ambiguous nonce (more than one authenticated block)" if ambiguous else "no run nonce"
+        with open(args.out_md, "w", encoding="utf-8") as fh:
+            fh.write("# ⚠ Pre-audit REFUSED — possible prompt injection\n\n"
+                     f"The model's JSON appendix was not authenticated by this run's nonce ({reason}). "
+                     "A blueprint may have injected a forged 'all clear' block, so report.json was NOT "
+                     "written and the model's prose is withheld. Re-run the audit.\n")
+        print(f"::error::SECURITY — the JSON appendix is not nonce-authenticated ({reason}); refusing it. "
+              "report.json NOT written; re-run the audit.", file=sys.stderr)
+        return 3
+
+    span = None
+    if selected is not None:
+        span, obj = selected
+        for f in obj.get("findings", []):
+            f.setdefault("source", "llm")
+        if static_findings:  # hybrid run — merge static into the LLM findings
+            obj["findings"] = sak_lib.merge_findings(obj.get("findings", []), static_findings)
+    elif static_ran:
+        # No LLM block — assemble the report from the static pass alone (static-only tier). Build
+        # it even when the pass found NOTHING: a clean audit is a first-class, attestable result
+        # and the file-mode gate / L3 attestation both need a report.json to exist.
+        obj = sak_lib.build_report(static_findings)
+    else:
+        # Neither — keep the human report, skip JSON. Never fail the pipeline.
+        with open(args.out_md, "w", encoding="utf-8") as fh:
+            fh.write(raw if raw.endswith("\n") else raw + "\n")
+        print("warn: no machine-readable JSON block found — wrote markdown only", file=sys.stderr)
+        return 0
+
+    # Stamp authoritative provenance — overrides whatever the model put there.
+    obj["schema_version"] = "1.0"
+    kit = obj.setdefault("kit", {})
+    kit.update({
+        "version": args.kit_version,
+        "model": args.model,
+        "checklist_version": args.checklist_version,
+        "generated_at": args.generated_at,
+    })
+    if args.reference_set:
+        kit["reference_set"] = args.reference_set
+    target = obj.setdefault("target", {})
+    if args.repo:
+        target["repo"] = args.repo
+    if args.package:
+        target["package"] = args.package
+    if args.source_hash:
+        target["source_hash"] = args.source_hash
+    if args.files:
+        target["files_analyzed"] = args.files
+
+    problems = soft_validate(obj, args.schema) if args.schema else []
+    for p in problems:
+        print(f"warn: schema: {p}", file=sys.stderr)
+
+    with open(args.out_json, "w", encoding="utf-8") as fh:
+        json.dump(obj, fh, indent=2, ensure_ascii=False)
+        fh.write("\n")
+
+    # Cleaned markdown: the human body (minus the JSON appendix) + a static-findings section.
+    cleaned = strip_json_appendix(raw, span) if span is not None else (raw.rstrip() + "\n")
+    if static_findings:
+        cleaned = cleaned.rstrip() + "\n\n" + sak_lib.render_findings_md(
+            static_findings, "Static analysis (deterministic)")
+    header = (
+        f"<!-- scrypto-audit-kit {args.kit_version} · model {args.model} · "
+        f"checklist {args.checklist_version} · source {args.source_hash[:12]} · {args.generated_at} -->\n"
+    )
+    with open(args.out_md, "w", encoding="utf-8") as fh:
+        fh.write(header + cleaned)
+
+    findings = obj.get("findings", [])
+    by_sev = {}
+    for f in findings:
+        by_sev[f.get("severity", "?")] = by_sev.get(f.get("severity", "?"), 0) + 1
+    sev_str = ", ".join(f"{k}:{v}" for k, v in sorted(by_sev.items())) or "none"
+    extra = f"; {len(static_findings)} from static" if static_findings else ""
+    print(f"report.json: {len(findings)} findings ({sev_str}){extra}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scrypto_audit_kit/gen_tests.py

@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+"""Generate scrypto-test property-test scaffolds from a blueprint's surface.
+
+Deterministic, no API. Reads the `enable_method_auth!` surface (roles + per-method gating)
+and the struct's Vault fields, then emits compilable `#[test] #[ignore]` scaffolds with
+`todo!()` bodies:
+
+  - auth negative-path tests for each role-restricted method (the most-missed coverage),
+  - happy-path tests for each public method,
+  - a value-conservation invariant test when the blueprint custodies vaults.
+
+The scaffolds compile and are `#[ignore]`d, so they never break `cargo test`; the developer
+(or an agent) removes `#[ignore]` and fills in each `todo!()`. The kit stays read-only — this
+prints/returns the scaffolds, it never writes into the audited package.
+
+Stdlib only; reuses the comment/string stripper from static_analysis. Importable + CLI.
+"""
+import argparse
+import json
+import os
+import re
+import sys
+
+import static_analysis
+
+_GATING_RE = re.compile(r"(\w+)\s*=>\s*(PUBLIC|restrict_to:\s*\[\s*([\w, ]+?)\s*\])")
+_IMPL_RE = re.compile(r"\bimpl\s+(\w+)")
+_VAULT_RE = re.compile(r"(\w+)\s*:\s*(?:Vault|KeyValueStore<[^>]*\bVault\b[^>]*>)")
+
+
+def _stripped_sources(pkg_dir):
+    src_dir = os.path.join(pkg_dir, "src")
+    base = src_dir if os.path.isdir(src_dir) else pkg_dir
+    chunks = []
+    for root, _dirs, files in os.walk(base):
+        for name in sorted(files):
+            if name.endswith(".rs"):
+                with open(os.path.join(root, name), encoding="utf-8", errors="replace") as fh:
+                    chunks.append(static_analysis.strip_comments_and_strings(fh.read()))
+    return "\n".join(chunks)
+
+
+def extract_surface(pkg_dir):
+    """Return {blueprint, methods:[{name,gating,roles}], roles:[...], vault_fields:[...]}."""
+    src = _stripped_sources(pkg_dir)
+
+    methods, roles = [], set()
+    for m in _GATING_RE.finditer(src):
+        name, gating = m.group(1), m.group(2)
+        if gating.startswith("PUBLIC"):
+            methods.append({"name": name, "gating": "public", "roles": []})
+        else:
+            mr = [r.strip() for r in m.group(3).split(",") if r.strip()]
+            roles.update(mr)
+            methods.append({"name": name, "gating": "restricted", "roles": mr})
+
+    impls = _IMPL_RE.findall(src)
+    blueprint = impls[0] if impls else "Blueprint"
+    vault_fields = sorted(set(_VAULT_RE.findall(src)))
+    return {"blueprint": blueprint, "methods": methods, "roles": sorted(roles), "vault_fields": vault_fields}
+
+
+def propose_specs(surface):
+    """Turn a surface into an ordered list of property-test specs."""
+    specs = []
+    for meth in surface["methods"]:
+        if meth["gating"] == "restricted":
+            badge = " / ".join(meth["roles"]) or "required"
+            specs.append({
+                "name": f"{meth['name']}_rejects_unauthorized_caller",
+                "kind": "auth-negative",
+                "target": meth["name"],
+                "invariant": f"`{meth['name']}` must fail when called without the `{badge}` badge",
+                "hint": f"instantiate, then call {meth['name']} WITHOUT the {badge} badge and assert "
+                        f"the call fails (an auth error)",
+            })
+    for meth in surface["methods"]:
+        if meth["gating"] == "public":
+            specs.append({
+                "name": f"{meth['name']}_happy_path",
+                "kind": "happy-path",
+                "target": meth["name"],
+                "invariant": f"`{meth['name']}` succeeds on a valid call and makes the expected state change",
+                "hint": f"instantiate, call {meth['name']} with valid inputs, assert the expected result/state",
+            })
+    if surface["vault_fields"]:
+        fields = ", ".join(surface["vault_fields"])
+        specs.append({
+            "name": "value_conservation_invariant",
+            "kind": "invariant",
+            "target": None,
+            "invariant": "custodied value is conserved across operations (no value created or lost)",
+            "hint": f"after each public call, assert the sum of vault balances ({fields}) matches the "
+                    f"tracked totals — value is neither minted nor lost",
+        })
+    return specs
+
+
+def render_rust(specs, surface):
+    """Render specs as a compilable, #[ignore]d scrypto-test scaffold file."""
+    out = [
+        "//! Property-test scaffolds generated by scrypto-audit-kit.",
+        f"//! Blueprint: {surface['blueprint']}. These compile and are #[ignore]d — remove the",
+        "//! #[ignore] and fill in each todo!() to turn a coverage gap into an executable check.",
+        "#![allow(unused)]",
+        "use scrypto_test::prelude::*;",
+        "",
+    ]
+    if not specs:
+        out.append("// No role-restricted methods, public methods, or vaults detected.")
+        out.append("")
+        return "\n".join(out)
+    for spec in specs:
+        out.append(f"/// {spec['invariant']}.")
+        out.append("#[test]")
+        out.append('#[ignore = "scaffold from scrypto-audit-kit — implement, then un-ignore"]')
+        out.append(f"fn {spec['name']}() {{")
+        out.append(f'    todo!("{spec["hint"]}");')
+        out.append("}")
+        out.append("")
+    return "\n".join(out)
+
+
+def propose_tests(pkg_dir):
+    """Top-level: returns {blueprint, count, specs, rust} for a package."""
+    surface = extract_surface(pkg_dir)
+    specs = propose_specs(surface)
+    return {
+        "blueprint": surface["blueprint"],
+        "count": len(specs),
+        "specs": specs,
+        "rust": render_rust(specs, surface),
+    }
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Generate scrypto-test property-test scaffolds.")
+    ap.add_argument("package", help="path to the Scrypto package (or a src dir)")
+    ap.add_argument("--json", action="store_true", help="print the specs as JSON instead of Rust")
+    ap.add_argument("--out", help="write the Rust scaffold to this file")
+    args = ap.parse_args()
+
+    result = propose_tests(args.package)
+    if args.json:
+        json.dump({k: result[k] for k in ("blueprint", "count", "specs")}, sys.stdout, indent=2)
+        sys.stdout.write("\n")
+    elif args.out:
+        with open(args.out, "w", encoding="utf-8") as fh:
+            fh.write(result["rust"])
+    else:
+        sys.stdout.write(result["rust"])
+    sys.stderr.write(f"[gen-tests] {result['count']} scaffold(s) for {result['blueprint']}\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())