nightpay 0.1.0

package/skills/nightpay/scripts/gateway.sh

@@ -0,0 +1,578 @@
+#!/usr/bin/env bash
+# nightpay gateway — orchestrates the bounty lifecycle with fee mechanism
+#
+# SECURITY MODEL:
+#   - RECEIPT_CONTRACT is required — no silent no-ops against empty address
+#   - withdraw-fees requires OPERATOR_SECRET_KEY for signing (operator-only)
+#   - All hashes are domain-separated to prevent cross-namespace collisions
+#   - refund path cancels Masumi escrow AND emits a signed on-chain NIGHT refund intent
+#   - Amount bounds enforced (min + max) before any network call
+#   - commitment_hash format validated before any network call
+#   - curl has --max-time 30 to prevent hung connections
+#
+# Usage: ./gateway.sh <command> [args...]
+#
+# Commands:
+#   post-bounty     <job_description> <amount_night_specks>
+#   find-agent      <capability_query>
+#   hire-and-pay    <agent_id> <job_description> <commitment_hash>
+#   check-job       <job_id>
+#   complete        <job_id> <commitment_hash>
+#   refund          <job_id> <commitment_hash>
+#   withdraw-fees   [amount_specks]        # operator-only: requires OPERATOR_SECRET_KEY
+#   stats                                  # public contract stats
+
+set -euo pipefail
+
+# ─── Required env vars ────────────────────────────────────────────────────────
+MASUMI_PAYMENT_URL="${MASUMI_PAYMENT_URL:-http://localhost:3001/api/v1}"
+MASUMI_REGISTRY_URL="${MASUMI_REGISTRY_URL:-http://localhost:3000/api/v1}"
+MASUMI_API_KEY="${MASUMI_API_KEY:?SECURITY: Set MASUMI_API_KEY}"
+MIDNIGHT_NETWORK="${MIDNIGHT_NETWORK:-testnet}"
+OPERATOR_ADDRESS="${OPERATOR_ADDRESS:?SECURITY: Set OPERATOR_ADDRESS}"
+OPERATOR_FEE_BPS="${OPERATOR_FEE_BPS:-200}"
+MAX_BOUNTY_SPECKS="${MAX_BOUNTY_SPECKS:-500000000}"
+MIN_BOUNTY_SPECKS="${MIN_BOUNTY_SPECKS:-1000}"  # SECURITY: reject dust bounties
+
+# Midnight bridge — if set, gateway calls the bridge for real on-chain transactions.
+# If not set, gateway runs in local/stub mode (computes hashes locally, no chain).
+BRIDGE_URL="${BRIDGE_URL:-}"
+
+# SECURITY: contract address is REQUIRED — fail loudly rather than silently
+# routing funds to a void address
+RECEIPT_CONTRACT="${RECEIPT_CONTRACT_ADDRESS:?SECURITY: Set RECEIPT_CONTRACT_ADDRESS — funds cannot be routed without it}"
+
+# ─── Rate limiting ────────────────────────────────────────────────────────────
+# SECURITY: prevent bounty spam that inflates activeCount and floods Masumi.
+# Uses a per-command lockfile with a minimum interval between invocations.
+# Default: max 1 post-bounty per 5 seconds. Override with RATE_LIMIT_SECONDS.
+RATE_LIMIT_DIR="${RATE_LIMIT_DIR:-${HOME}/.nightpay/ratelimit}"
+RATE_LIMIT_SECONDS="${RATE_LIMIT_SECONDS:-5}"
+
+COMMAND="${1:?Usage: gateway.sh <command> [args...]}"
+shift
+
+# ─── Helpers ──────────────────────────────────────────────────────────────────
+
+# SECURITY: SSRF guard — only allow http/https to non-RFC-1918, non-loopback hosts.
+# Blocks: 127.x, 10.x, 172.16-31.x, 192.168.x, 169.254.x (cloud metadata), ::1
+validate_url() {
+  local url="$1"
+  python3 -c "
+import sys, urllib.parse, ipaddress, socket
+
+url = sys.argv[1]
+parsed = urllib.parse.urlparse(url)
+
+if parsed.scheme not in ('http', 'https'):
+    print('ERROR: URL must use http or https scheme'); sys.exit(1)
+
+host = parsed.hostname
+if not host:
+    print('ERROR: URL has no hostname'); sys.exit(1)
+
+# Resolve and check for private/loopback addresses
+try:
+    addrs = socket.getaddrinfo(host, None)
+    for addr in addrs:
+        ip = ipaddress.ip_address(addr[4][0])
+        if ip.is_private or ip.is_loopback or ip.is_link_local or ip.is_reserved:
+            # Allow localhost explicitly for dev — controlled by ALLOW_LOCAL_URLS
+            import os
+            if os.environ.get('ALLOW_LOCAL_URLS') == '1':
+                sys.exit(0)
+            print(f'ERROR: SSRF blocked — {ip} is a private/internal address'); sys.exit(1)
+except socket.gaierror:
+    print(f'ERROR: Cannot resolve host {host}'); sys.exit(1)
+
+print('ok')
+" "$url" || exit 1
+}
+
+# Validate URLs at startup — fail before any command runs
+# Skip SSRF check for localhost (dev mode) if ALLOW_LOCAL_URLS=1
+if [[ "${ALLOW_LOCAL_URLS:-0}" != "1" ]]; then
+  _url_check=$(python3 -c "
+import sys, urllib.parse, ipaddress
+for url in sys.argv[1:]:
+    parsed = urllib.parse.urlparse(url)
+    if parsed.scheme not in ('http','https'):
+        print(f'ERROR: {url} — must be http/https'); sys.exit(1)
+print('ok')
+" "$MASUMI_PAYMENT_URL" "$MASUMI_REGISTRY_URL" 2>&1) || {
+    echo "SECURITY ERROR: Invalid Masumi URL — $_url_check" >&2; exit 1
+  }
+fi
+
+# DARK ENERGY: DNS rebinding guard — re-resolve the hostname on every request
+# and verify it is still a non-private IP. An attacker who controls the DNS
+# server can pass the startup check (public IP) then flip the A-record to
+# 169.254.169.254 (AWS metadata) for subsequent calls. We re-resolve per call.
+_ssrf_safe_curl() {
+  local url="$1"; shift
+  python3 -c "
+import sys, urllib.parse, ipaddress, socket, os
+url = sys.argv[1]
+parsed = urllib.parse.urlparse(url)
+host = parsed.hostname or ''
+try:
+    addrs = socket.getaddrinfo(host, None)
+    for addr in addrs:
+        ip = ipaddress.ip_address(addr[4][0])
+        if ip.is_private or ip.is_loopback or ip.is_link_local or ip.is_reserved:
+            if os.environ.get('ALLOW_LOCAL_URLS') == '1':
+                sys.exit(0)
+            print(f'SSRF blocked: {ip}', file=sys.stderr); sys.exit(1)
+except socket.gaierror as e:
+    print(f'DNS error: {e}', file=sys.stderr); sys.exit(1)
+" "$url" || { echo "SECURITY ERROR: SSRF guard blocked request to $url" >&2; exit 1; }
+  curl -sf --max-time 30 "$@" "$url"
+}
+
+masumi_get() {
+  _ssrf_safe_curl "${MASUMI_REGISTRY_URL}${1}" \
+    -H "Authorization: Bearer $MASUMI_API_KEY"
+}
+
+masumi_post() {
+  _ssrf_safe_curl "${MASUMI_PAYMENT_URL}${1}" \
+    -X POST \
+    -H "Authorization: Bearer $MASUMI_API_KEY" \
+    -H "Content-Type: application/json" \
+    -d "$2"
+}
+
+generate_nonce() {
+  # SECURITY: cryptographically secure 32-byte random nonce.
+  # `openssl rand -hex 32` always outputs exactly 64 lowercase hex chars + newline.
+  # No spaces, no special chars — safe from word splitting in all contexts.
+  # We strip the newline explicitly so callers can safely use $() without concern.
+  openssl rand -hex 32 | tr -d '[:space:]'
+}
+
+# SECURITY: rate limiter — prevents bounty spam and Masumi flooding.
+# Creates a per-command lockfile; rejects calls within RATE_LIMIT_SECONDS of last call.
+rate_limit() {
+  local cmd="$1"
+  mkdir -p "$RATE_LIMIT_DIR"
+  chmod 700 "$RATE_LIMIT_DIR"
+  local lockfile="${RATE_LIMIT_DIR}/${cmd}.last"
+  if [[ -f "$lockfile" ]]; then
+    local last_ts; last_ts=$(cat "$lockfile" 2>/dev/null || echo 0)
+    local now; now=$(date +%s)
+    local diff=$(( now - last_ts ))
+    if (( diff < RATE_LIMIT_SECONDS )); then
+      echo "ERROR: Rate limit — wait $(( RATE_LIMIT_SECONDS - diff ))s before calling $cmd again" >&2
+      exit 1
+    fi
+  fi
+  date +%s > "$lockfile"
+}
+
+# SECURITY: domain-separated hashes prevent cross-namespace collisions.
+# A bounty commitment can never equal a receipt hash even with identical inputs.
+domain_hash() {
+  # DARK ENERGY: word splitting guard — pipe through tr to guarantee the output
+  # is exactly 64 hex chars with no whitespace. sha256sum outputs "hash  -\n";
+  # awk extracts field 1, tr strips any residual whitespace. Safe to use unquoted
+  # in arithmetic but we always double-quote hash variables regardless.
+  local domain="$1"; local data="$2"
+  printf '%s:%s' "$domain" "$data" | sha256sum | awk '{print $1}' | tr -d '[:space:]'
+}
+
+compute_bounty_commitment() { domain_hash "nightpay-bounty-v1"  "$1"; }
+compute_receipt_hash()      { domain_hash "nightpay-receipt-v1" "$1"; }
+compute_job_hash()          { domain_hash "nightpay-job-v1"     "$1"; }
+
+compute_fee() { echo $(( $1 * OPERATOR_FEE_BPS / 10000 )); }
+compute_net() { local fee; fee=$(compute_fee "$1"); echo $(( $1 - fee )); }
+
+# Call midnight bridge service if BRIDGE_URL is set
+bridge_post() {
+  local endpoint="$1"; local payload="$2"
+  if [[ -z "$BRIDGE_URL" ]]; then
+    return 1  # no bridge — caller falls back to local computation
+  fi
+  _ssrf_safe_curl "${BRIDGE_URL}${endpoint}" \
+    -X POST \
+    -H "Content-Type: application/json" \
+    -d "$payload"
+}
+
+bridge_get() {
+  local endpoint="$1"
+  if [[ -z "$BRIDGE_URL" ]]; then
+    return 1
+  fi
+  _ssrf_safe_curl "${BRIDGE_URL}${endpoint}" \
+    -H "Content-Type: application/json"
+}
+
+validate_amount() {
+  local amount="$1"
+  # SECURITY: enforce integer type, min, and max before any network call
+  if ! [[ "$amount" =~ ^[0-9]+$ ]]; then
+    echo "ERROR: amount must be a positive integer (specks)"; exit 1
+  fi
+  if (( amount < MIN_BOUNTY_SPECKS )); then
+    echo "ERROR: Amount $amount below minimum $MIN_BOUNTY_SPECKS specks"; exit 1
+  fi
+  if (( amount > MAX_BOUNTY_SPECKS )); then
+    echo "ERROR: Amount $amount exceeds maximum $MAX_BOUNTY_SPECKS specks"; exit 1
+  fi
+}
+
+validate_commitment() {
+  # SECURITY: commitment must be a 64-char hex string — reject malformed inputs
+  if ! [[ "$1" =~ ^[0-9a-f]{64}$ ]]; then
+    echo "ERROR: commitment_hash must be a 64-character lowercase hex string"; exit 1
+  fi
+}
+
+validate_job_id() {
+  # SECURITY: job IDs must be alphanumeric + hyphens only.
+  # Prevents path traversal (../../), shell injection, and API endpoint manipulation.
+  if ! [[ "$1" =~ ^[a-zA-Z0-9_-]{1,128}$ ]]; then
+    echo "ERROR: job_id must be alphanumeric/hyphens/underscores, max 128 chars"; exit 1
+  fi
+}
+
+# SECURITY: operator must authenticate before fee withdrawal.
+# Requires OPERATOR_SECRET_KEY env var — prevents unauthorized parties from
+# draining accumulated fees even if they have shell access to the gateway.
+# SECURITY: payload includes a timestamp + random nonce — prevents replay attacks.
+# The same HMAC can never be reused because the nonce is different every call.
+require_operator_auth() {
+  if [[ -z "${OPERATOR_SECRET_KEY:-}" ]]; then
+    echo "SECURITY ERROR: withdraw-fees requires OPERATOR_SECRET_KEY env var." >&2
+    echo "This prevents unauthorized parties from draining accumulated fees." >&2
+    exit 1
+  fi
+  local payload="$1"
+  local ts; ts=$(date +%s)
+  local nonce; nonce=$(generate_nonce)
+  # Include timestamp + nonce in signed payload — every signature is unique
+  local full_payload="${payload}:ts=${ts}:nonce=${nonce}"
+  local sig; sig=$(echo -n "$full_payload" | openssl dgst -sha256 -hmac "$OPERATOR_SECRET_KEY" | awk '{print $2}')
+  # Return sig:ts:nonce so the Midnight contract can verify freshness
+  echo "${sig}:${ts}:${nonce}"
+}
+
+# ─── Content Safety ────────────────────────────────────────────────────────────
+# SAFETY: classify-then-forget — checks job description in-memory, never logs it.
+# Three layers: live rules file > hardcoded fallback > external moderation API.
+# Rules auto-updated by update-blocklist.sh (cron). See rules/content-safety.md.
+
+CONTENT_SAFETY_URL="${CONTENT_SAFETY_URL:-}"
+SAFETY_RULES_FILE="${SAFETY_RULES_FILE:-${HOME}/.nightpay/safety/safety-rules.json}"
+
+safety_check() {
+  local text="$1"
+
+  local rejected_category
+  rejected_category=$(python3 -c "
+import sys, re, json, os
+
+text = sys.argv[1].lower()
+rules_file = sys.argv[2]
+
+# ─── Layer 1: load live rules file if available (updated by update-blocklist.sh)
+rules = []
+if os.path.exists(rules_file):
+    try:
+        with open(rules_file) as f:
+            data = json.load(f)
+        rules = [(r['category'], r['pattern']) for r in data.get('rules', [])
+                 if 'category' in r and 'pattern' in r]
+    except (json.JSONDecodeError, KeyError):
+        pass  # fall through to hardcoded
+
+# ─── Layer 2: hardcoded fallback if no rules file or it failed to load
+if not rules:
+    rules = [
+        ('csam',                  r'\b(child|minor|underage|kid|teen)\b.*\b(sex|porn|nude|naked|exploit)\b'),
+        ('csam',                  r'\b(sex|porn|nude|naked|exploit)\b.*\b(child|minor|underage|kid|teen)\b'),
+        ('violence',              r'\b(kill|assassinate|murder|execute)\b.*\b(person|people|someone|him|her|them|target)\b'),
+        ('violence',              r'\b(hire|find|pay).*\b(hitman|killer|assassin)\b'),
+        ('violence',              r'\bhit\s*man\b'),
+        ('weapons_of_mass_destruction', r'\b(synthe|build|make|create|assemble)\b.*\b(bomb|bioweapon|chemical weapon|nerve agent|sarin|anthrax|ricin|nuclear|dirty bomb|explosive device)\b'),
+        ('human_trafficking',     r'\b(traffic|smuggle|exploit|enslave)\b.*\b(person|people|human|worker|organ|women|children)\b'),
+        ('terrorism',             r'\b(fund|finance|recruit|plan|support)\b.*\b(terror|jihad|extremis|insurrection|attack on)\b'),
+        ('ncii',                  r'\b(deepfake|revenge porn|sextortion|non.?consensual)\b.*\b(nude|naked|intimate|image|video|photo)\b'),
+        ('financial_fraud',       r'\b(launder|counterfeit|forge)\b.*\b(money|currency|documents|passport|identity)\b'),
+        ('financial_fraud',       r'\b(evade|bypass|circumvent)\b.*\b(sanction|embargo|aml|kyc)\b'),
+        ('infrastructure_attack', r'\b(attack|hack|disrupt|destroy|sabotage)\b.*\b(power grid|water supply|hospital|election|pipeline|dam)\b'),
+        ('doxxing',               r'\b(doxx|stalk|track|surveil|locate)\b.*\b(person|address|home|family|where .* live)\b'),
+        ('drug_manufacturing',    r'\b(synthe|cook|manufacture|produce)\b.*\b(meth|fentanyl|heroin|cocaine|mdma|lsd)\b'),
+    ]
+
+for category, pattern in rules:
+    try:
+        if re.search(pattern, text):
+            print(category)
+            sys.exit(0)
+    except re.error:
+        continue  # skip malformed patterns from feeds
+
+print('safe')
+" "$text" "$SAFETY_RULES_FILE" 2>/dev/null) || rejected_category="safe"
+
+  # ─── Layer 3: external moderation API (catches what regex misses)
+  if [[ "$rejected_category" == "safe" && -n "$CONTENT_SAFETY_URL" ]]; then
+    local api_payload
+    api_payload=$(python3 -c "
+import sys, json
+print(json.dumps({'text': sys.argv[1]}))
+" "$text")
+    local response
+    response=$(curl -sf --max-time 5 -X POST \
+      -H 'Content-Type: application/json' \
+      -d "$api_payload" \
+      "$CONTENT_SAFETY_URL" 2>/dev/null) || response=""
+
+    if [[ -n "$response" ]]; then
+      rejected_category=$(echo "$response" | python3 -c "
+import sys, json
+try:
+    d = json.load(sys.stdin)
+    if not d.get('safe', True):
+        print(d.get('category', 'unsafe'))
+    else:
+        print('safe')
+except: print('safe')
+" 2>/dev/null) || rejected_category="safe"
+    fi
+  fi
+
+  if [[ "$rejected_category" != "safe" ]]; then
+    python3 -c "
+import sys, json
+print(json.dumps({
+    'status': 'REJECTED',
+    'reason': 'content_safety',
+    'category': sys.argv[1],
+    'message': 'This bounty description was rejected by the content safety gate. See rules/content-safety.md.'
+}, indent=2))
+" "$rejected_category"
+    exit 2
+  fi
+}
+
+# ─── Commands ─────────────────────────────────────────────────────────────────
+
+case "$COMMAND" in
+
+  post-bounty)
+    JOB_DESC="${1:?Usage: post-bounty <job_description> <amount_specks>}"
+    AMOUNT="${2:?Usage: post-bounty <job_description> <amount_specks>}"
+
+    rate_limit "post-bounty"   # SECURITY: max 1 post per RATE_LIMIT_SECONDS
+    validate_amount "$AMOUNT"
+    safety_check "$JOB_DESC"
+
+    FEE=$(compute_fee "$AMOUNT")
+    NET=$(compute_net "$AMOUNT")
+    NONCE=$(generate_nonce)
+    JOB_HASH=$(compute_job_hash "$JOB_DESC")
+
+    # SECURITY: domain-separated commitment — matches what the Compact circuit produces
+    COMMITMENT=$(compute_bounty_commitment "nullifier:${AMOUNT}:${JOB_HASH}:${NONCE}")
+
+    # If bridge is running, submit real on-chain transaction
+    if [[ -n "$BRIDGE_URL" ]]; then
+      BRIDGE_PAYLOAD=$(python3 -c "
+import sys, json
+print(json.dumps({'jobHash': sys.argv[1], 'amount': int(sys.argv[2]), 'nonce': sys.argv[3]}))
+" "$JOB_HASH" "$AMOUNT" "$NONCE")
+      BRIDGE_RESULT=$(bridge_post "/postBounty" "$BRIDGE_PAYLOAD" 2>/dev/null) && {
+        TX_ID=$(echo "$BRIDGE_RESULT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('txId',''))" 2>/dev/null)
+        ON_CHAIN=$(echo "$BRIDGE_RESULT" | python3 -c "import sys,json; d=json.load(sys.stdin); print('false' if d.get('stub') else 'true')" 2>/dev/null)
+        echo "  Midnight TX: $TX_ID (on-chain: $ON_CHAIN)" >&2
+      } || echo "  WARNING: Bridge unavailable — commitment computed locally only" >&2
+    fi
+
+    # SECURITY: nonce printed once for the caller to store securely.
+    # NOT persisted by the gateway — loss of nonce means the caller cannot
+    # prove bounty ownership in a dispute.
+    python3 -c "
+import sys, json
+print(json.dumps({
+    'commitment': sys.argv[1],
+    'nonce': sys.argv[2],
+    'jobHash': sys.argv[3],
+    'amount': int(sys.argv[4]),
+    'operatorFee': int(sys.argv[5]),
+    'netToAgent': int(sys.argv[6]),
+    'feeBps': int(sys.argv[7]),
+    'receiptContract': sys.argv[8],
+    'network': sys.argv[9],
+    'status': 'posted',
+    'warning': 'Store your nonce securely — it cannot be recovered and is required for dispute resolution'
+}, indent=2))
+" "$COMMITMENT" "$NONCE" "$JOB_HASH" "$AMOUNT" "$FEE" "$NET" "$OPERATOR_FEE_BPS" "$RECEIPT_CONTRACT" "$MIDNIGHT_NETWORK"
+    ;;
+
+  find-agent)
+    CAPABILITY="${1:?Usage: find-agent <capability_query>}"
+    ENCODED=$(python3 -c "import urllib.parse,sys; print(urllib.parse.quote(sys.argv[1]))" "$CAPABILITY")
+    masumi_get "/agents?capability=${ENCODED}&limit=5"
+    ;;
+
+  hire-and-pay)
+    AGENT_ID="${1:?Usage: hire-and-pay <agent_id> <job_description> <commitment_hash>}"
+    JOB_DESC="${2:?Usage: hire-and-pay <agent_id> <job_description> <commitment_hash>}"
+    COMMITMENT="${3:?Usage: hire-and-pay <agent_id> <job_description> <commitment_hash>}"
+
+    validate_commitment "$COMMITMENT"
+    safety_check "$JOB_DESC"
+
+    PAYLOAD=$(python3 -c "
+import sys, json
+print(json.dumps({
+    'agentIdentifier': sys.argv[1],
+    'input': {
+        'description': sys.argv[2],
+        'commitmentHash': sys.argv[3],
+        'receiptContract': sys.argv[4],
+        'network': sys.argv[5]
+    }
+}))
+" "$AGENT_ID" "$JOB_DESC" "$COMMITMENT" "$RECEIPT_CONTRACT" "$MIDNIGHT_NETWORK")
+    masumi_post "/purchases" "$PAYLOAD"
+    ;;
+
+  check-job)
+    JOB_ID="${1:?Usage: check-job <job_id>}"
+    validate_job_id "$JOB_ID"   # SECURITY: prevent path traversal / injection
+    masumi_get "/purchases/$JOB_ID/status"
+    ;;
+
+  complete)
+    JOB_ID="${1:?Usage: complete <job_id> <commitment_hash>}"
+    COMMITMENT="${2:?Usage: complete <job_id> <commitment_hash>}"
+
+    validate_job_id "$JOB_ID"       # SECURITY: prevent path traversal
+    validate_commitment "$COMMITMENT"
+
+    RESULT_DATA=$(masumi_get "/purchases/$JOB_ID/result")
+
+    # SECURITY: canonical JSON (sorted keys, no whitespace) prevents hash
+    # manipulation via key reordering or whitespace changes in the API response
+    OUTPUT_HASH=$(echo "$RESULT_DATA" | python3 -c "
+import sys, json, hashlib
+d = json.load(sys.stdin)
+canonical = json.dumps(d, sort_keys=True, separators=(',',':'))
+print(hashlib.sha256(canonical.encode()).hexdigest())
+") || { echo "ERROR: Failed to parse job result as JSON — refusing to mint receipt"; exit 1; }
+
+    COMPLETION_NONCE=$(generate_nonce)
+
+    # SECURITY: domain-separated receipt hash — cannot be forged from bounty inputs
+    RECEIPT_HASH=$(compute_receipt_hash "${COMMITMENT}:${OUTPUT_HASH}:${COMPLETION_NONCE}")
+
+    # If bridge is running, submit real completeAndReceipt circuit call
+    BRIDGE_TX_ID=""
+    BRIDGE_ON_CHAIN="false"
+    if [[ -n "$BRIDGE_URL" ]]; then
+      BRIDGE_PAYLOAD=$(python3 -c "
+import sys, json
+print(json.dumps({'bountyCommitment': sys.argv[1], 'outputHash': sys.argv[2]}))
+" "$COMMITMENT" "$OUTPUT_HASH")
+      BRIDGE_RESULT=$(bridge_post "/completeAndReceipt" "$BRIDGE_PAYLOAD" 2>/dev/null) && {
+        BRIDGE_TX_ID=$(echo "$BRIDGE_RESULT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('txId',''))" 2>/dev/null)
+        BRIDGE_ON_CHAIN=$(echo "$BRIDGE_RESULT" | python3 -c "import sys,json; d=json.load(sys.stdin); print('false' if d.get('stub') else 'true')" 2>/dev/null)
+        echo "  Midnight TX: $BRIDGE_TX_ID (on-chain: $BRIDGE_ON_CHAIN)" >&2
+      } || echo "  WARNING: Bridge unavailable — receipt computed locally only" >&2
+    fi
+
+    python3 -c "
+import sys, json
+print(json.dumps({
+    'receiptHash': sys.argv[1],
+    'outputHash': sys.argv[2],
+    'commitment': sys.argv[3],
+    'completionNonce': sys.argv[4],
+    'status': 'completed',
+    'midnightNetwork': sys.argv[5],
+    'receiptContract': sys.argv[6],
+    'midnightTxId': sys.argv[7] or None,
+    'onChain': sys.argv[8] == 'true'
+}, indent=2))
+" "$RECEIPT_HASH" "$OUTPUT_HASH" "$COMMITMENT" "$COMPLETION_NONCE" "$MIDNIGHT_NETWORK" "$RECEIPT_CONTRACT" "$BRIDGE_TX_ID" "$BRIDGE_ON_CHAIN"
+    ;;
+
+  refund)
+    JOB_ID="${1:?Usage: refund <job_id> <commitment_hash>}"
+    COMMITMENT="${2:?Usage: refund <job_id> <commitment_hash>}"
+
+    validate_job_id "$JOB_ID"       # SECURITY: prevent path traversal
+    validate_commitment "$COMMITMENT"
+
+    # Step 1: Cancel Masumi escrow on Cardano
+    echo "Cancelling Masumi escrow for job $JOB_ID..." >&2
+    masumi_post "/purchases/$JOB_ID/cancel" "{}"
+
+    # Step 2: Emit on-chain NIGHT refund intent for the Midnight contract.
+    # SECURITY: the contract's nullifier set ensures the bounty cannot be
+    # re-claimed after a refund is submitted. The refundHash is the payload
+    # the operator submits to the Midnight node to release NIGHT to the funder.
+    REFUND_NONCE=$(generate_nonce)
+    REFUND_HASH=$(compute_bounty_commitment "refund:${COMMITMENT}:${REFUND_NONCE}")
+
+    python3 -c "
+import sys, json
+print(json.dumps({
+    'commitment': sys.argv[1],
+    'refundHash': sys.argv[2],
+    'jobId': sys.argv[3],
+    'receiptContract': sys.argv[4],
+    'network': sys.argv[5],
+    'status': 'refunded',
+    'note': 'Submit refundHash to the Midnight contract to release NIGHT back to funder'
+}, indent=2))
+" "$COMMITMENT" "$REFUND_HASH" "$JOB_ID" "$RECEIPT_CONTRACT" "$MIDNIGHT_NETWORK"
+    ;;
+
+  withdraw-fees)
+    AMOUNT="${1:-all}"
+
+    # SECURITY: operator must sign the withdrawal — prevents anyone else
+    # who has shell access from draining the accumulated fee balance
+    SIG=$(require_operator_auth "${OPERATOR_ADDRESS}:${AMOUNT}")
+
+    python3 -c "
+import sys, json
+print(json.dumps({
+    'operatorAddress': sys.argv[1],
+    'withdrawAmount': sys.argv[2],
+    'operatorSignature': sys.argv[3],
+    'receiptContract': sys.argv[4],
+    'network': sys.argv[5],
+    'status': 'submitted',
+    'note': 'Submit this payload to the Midnight contract withdrawFees() circuit'
+}, indent=2))
+" "$OPERATOR_ADDRESS" "$AMOUNT" "$SIG" "$RECEIPT_CONTRACT" "$MIDNIGHT_NETWORK"
+    ;;
+
+  stats)
+    echo "Querying nightpay stats from $RECEIPT_CONTRACT on $MIDNIGHT_NETWORK..." >&2
+    if [[ -n "$BRIDGE_URL" ]]; then
+      bridge_get "/stats" && exit 0
+      echo "  WARNING: Bridge unavailable — showing placeholder" >&2
+    fi
+    python3 -c "
+import sys, json
+print(json.dumps({
+    'receiptContract': sys.argv[1],
+    'network': sys.argv[2],
+    'query': 'getStats()',
+    'note': 'Set BRIDGE_URL to get live on-chain stats'
+}, indent=2))
+" "$RECEIPT_CONTRACT" "$MIDNIGHT_NETWORK"
+    ;;
+
+  *)
+    echo "Commands: post-bounty, find-agent, hire-and-pay, check-job, complete, refund, withdraw-fees, stats"
+    exit 1
+    ;;
+esac