nightpay 0.1.2 → 0.2.1

package/skills/nightpay/scripts/mip003-server.sh

@@ -7,6 +7,15 @@
 # Usage: ./mip003-server.sh [port]
 # Default port: 8090
 #
+# Required env vars:
+#   JOB_TOKEN_SECRET       — HMAC secret for job_token generation (never stored)
+#   OPERATOR_SECRET_KEY    — HMAC secret for operator dispute auth
+#
+# Optional env vars:
+#   IDEMPOTENCY_TTL_SECONDS    - dedupe window for X-Idempotency-Key (default: 86400)
+#   OPTIMISTIC_WINDOW_HOURS    — hours before auto-complete fires (default: 48)
+#   MULTISIG_THRESHOLD_SPECKS  — above this value, multisig required (default: 1000000)
+#
 # Register with Masumi after starting:
 #   curl -X POST http://localhost:3001/api/v1/registry \
 #     -H "token: $MASUMI_API_KEY" \
@@ -16,7 +25,7 @@
 #       "description": "Anonymous community bounty board — pool shielded NIGHT, hire AI agents, get ZK receipts",
 #       "apiBaseUrl": "http://your-server:8090",
 #       "capabilityName": "nightpay-bounties",
-#       "capabilityVersion": "0.1.0",
+#       "capabilityVersion": "0.2.0",
 #       "pricingUnit": "lovelace",
 #       "pricingQuantity": "0",
 #       "network": "Preprod",
@@ -27,25 +36,80 @@
 
 set -euo pipefail
 
+# ─── Terminal colors ───────────────────────────────────────────────────────────
+if [[ -t 2 ]]; then
+  GREEN=$'\e[32m'; YELLOW=$'\e[33m'; CYAN=$'\e[36m'
+  BOLD=$'\e[1m'; DIM=$'\e[2m'; RED=$'\e[31m'; RESET=$'\e[0m'
+else
+  GREEN=''; YELLOW=''; CYAN=''; BOLD=''; DIM=''; RED=''; RESET=''
+fi
+
 PORT="${1:-8090}"
 DATA_DIR="${DATA_DIR:-${HOME}/.nightpay}"
 DB_PATH="${DATA_DIR}/jobs.db"
 
+JOB_TOKEN_SECRET="${JOB_TOKEN_SECRET:?SECURITY: Set JOB_TOKEN_SECRET env var}"
+OPERATOR_SECRET_KEY="${OPERATOR_SECRET_KEY:?SECURITY: Set OPERATOR_SECRET_KEY env var}"
+OPTIMISTIC_WINDOW_HOURS="${OPTIMISTIC_WINDOW_HOURS:-48}"
+MULTISIG_THRESHOLD_SPECKS="${MULTISIG_THRESHOLD_SPECKS:-1000000}"
+OPERATOR_FEE_BPS="${OPERATOR_FEE_BPS:-200}"
+IDEMPOTENCY_TTL_SECONDS="${IDEMPOTENCY_TTL_SECONDS:-86400}"
+
 mkdir -p "$DATA_DIR"
 chmod 700 "$DATA_DIR"
 
-command -v python3 >/dev/null 2>&1 || { echo "python3 required"; exit 1; }
+command -v python3 >/dev/null 2>&1 || { echo -e "${RED}ERROR${RESET}: python3 required" >&2; exit 1; }
 
-echo "nightpay MIP-003 service starting on port $PORT..."
+echo -e "${GREEN}◆${RESET} ${BOLD}nightpay${RESET} MIP-003 service listening on ${CYAN}:${PORT}${RESET}" >&2
+echo -e "${DIM}  DB: ${DB_PATH}${RESET}" >&2
+echo -e "${DIM}  optimistic window: ${OPTIMISTIC_WINDOW_HOURS}h  |  multisig threshold: ${MULTISIG_THRESHOLD_SPECKS} specks${RESET}" >&2
 
 python3 -c "
-import http.server, json, uuid, sys, sqlite3, threading
-from datetime import datetime, timezone
+import http.server, json, uuid, sys, sqlite3, threading, hmac, hashlib, re, os
+from datetime import datetime, timezone, timedelta
+from urllib.parse import urlparse, parse_qs
+
+PORT                     = int(sys.argv[1])
+DB_PATH                  = sys.argv[2]
+JOB_TOKEN_SECRET         = sys.argv[3]
+OPERATOR_SECRET_KEY      = sys.argv[4]
+OPTIMISTIC_WINDOW_HOURS  = int(sys.argv[5])
+MULTISIG_THRESHOLD_SPECKS = int(sys.argv[6])
+os.environ['OPERATOR_FEE_BPS'] = sys.argv[7]
+IDEMPOTENCY_TTL_SECONDS  = int(sys.argv[8])
+
+KNOWN_STATUSES = ('running', 'awaiting_approval', 'multisig_pending', 'disputed', 'completed')
+
+# ─── Security helpers ─────────────────────────────────────────────────────────
 
-PORT = int(sys.argv[1])
-DB_PATH = sys.argv[2]
+def make_job_token(job_id):
+    # domain-separated — cannot be reused as any other HMAC in the system
+    msg = f'nightpay-job-token-v1:{job_id}'
+    return hmac.new(JOB_TOKEN_SECRET.encode(), msg.encode(), hashlib.sha256).hexdigest()
+
+def verify_job_token(job_id, token):
+    return hmac.compare_digest(make_job_token(job_id), token)
+
+def verify_work_reveal(work_commit, work, nonce):
+    # SECURITY: domain-separated reveal hash — matches gateway.sh convention
+    revealed = hashlib.sha256(f'nightpay-work-reveal-v1:{work}:{nonce}'.encode()).hexdigest()
+    return hmac.compare_digest(revealed, work_commit)
+
+def verify_operator_sig(job_id, reason, sig):
+    # Operator signs: HMAC(OPERATOR_SECRET_KEY, 'dispute:{job_id}:{reason}')
+    msg = f'dispute:{job_id}:{reason}'
+    expected = hmac.new(OPERATOR_SECRET_KEY.encode(), msg.encode(), hashlib.sha256).hexdigest()
+    return hmac.compare_digest(expected, sig)
+
+def hash_start_job_request(body):
+    # Canonical payload hash used for idempotency conflict detection.
+    payload = dict(body)
+    payload.pop('idempotency_key', None)
+    canonical = json.dumps(payload, sort_keys=True, separators=(',', ':'))
+    return hashlib.sha256(canonical.encode()).hexdigest()
+
+# ─── SQLite ───────────────────────────────────────────────────────────────────
 
-# Thread-local connections for SQLite (one per request handler thread)
 local = threading.local()
 
 def get_db():
@@ -61,18 +125,50 @@ conn = sqlite3.connect(DB_PATH)
 conn.execute('PRAGMA journal_mode=WAL')
 conn.executescript('''
     CREATE TABLE IF NOT EXISTS jobs (
-        job_id      TEXT PRIMARY KEY,
-        status      TEXT NOT NULL DEFAULT \"running\",
-        input_data  TEXT,
-        extra_input TEXT,
-        result      TEXT,
-        started_at  TEXT NOT NULL,
-        updated_at  TEXT NOT NULL
+        job_id         TEXT PRIMARY KEY,
+        status         TEXT NOT NULL DEFAULT \"running\",
+        input_data     TEXT,
+        extra_input    TEXT,
+        result         TEXT,
+        started_at     TEXT NOT NULL,
+        updated_at     TEXT NOT NULL,
+        work_commit    TEXT,
+        amount_specks  INTEGER,
+        approved_at    TEXT,
+        dispute_reason TEXT,
+        approvals      TEXT
     );
-    CREATE INDEX IF NOT EXISTS idx_jobs_status ON jobs(status);
+    CREATE INDEX IF NOT EXISTS idx_jobs_status   ON jobs(status);
+    CREATE INDEX IF NOT EXISTS idx_jobs_status_approved ON jobs(status, approved_at)
+        WHERE approved_at IS NOT NULL;
+    CREATE INDEX IF NOT EXISTS idx_jobs_approved ON jobs(approved_at)
+        WHERE approved_at IS NOT NULL;
+
+    CREATE TABLE IF NOT EXISTS idempotency_keys (
+        idem_key     TEXT PRIMARY KEY,
+        request_hash TEXT NOT NULL,
+        job_id       TEXT NOT NULL,
+        created_at   TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_idempotency_created_at ON idempotency_keys(created_at);
 ''')
+# Idempotent migration for existing DBs (ALTER TABLE is safe — ignores dup column)
+for col_def in [
+    'ALTER TABLE jobs ADD COLUMN work_commit    TEXT',
+    'ALTER TABLE jobs ADD COLUMN amount_specks  INTEGER',
+    'ALTER TABLE jobs ADD COLUMN approved_at    TEXT',
+    'ALTER TABLE jobs ADD COLUMN dispute_reason TEXT',
+    'ALTER TABLE jobs ADD COLUMN approvals      TEXT',
+]:
+    try:
+        conn.execute(col_def)
+    except Exception:
+        pass  # column already exists — idempotent
+conn.commit()
 conn.close()
 
+# ─── HTTP handler ─────────────────────────────────────────────────────────────
+
 class MIP003Handler(http.server.BaseHTTPRequestHandler):
     def log_message(self, fmt, *args):
         print(f'[nightpay] {args[0]}')
@@ -85,10 +181,20 @@ class MIP003Handler(http.server.BaseHTTPRequestHandler):
         self.end_headers()
         self.wfile.write(body)
 
+    def _read_body(self):
+        length = int(self.headers.get('Content-Length', 0))
+        return json.loads(self.rfile.read(length)) if length else {}
+
+    def _validate_job_id(self, job_id):
+        # Mirrors validate_job_id in gateway.sh — prevents path traversal
+        return bool(re.match(r'^[a-zA-Z0-9_-]{1,128}$', job_id))
+
+    # ── GET ──────────────────────────────────────────────────────────────────
+
     def do_GET(self):
         if self.path == '/availability':
             db = get_db()
-            total = db.execute('SELECT COUNT(*) FROM jobs').fetchone()[0]
+            total  = db.execute('SELECT COUNT(*) FROM jobs').fetchone()[0]
             active = db.execute('SELECT COUNT(*) FROM jobs WHERE status = ?', ('running',)).fetchone()[0]
             self.respond(200, {
                 'status': 'available',
@@ -107,6 +213,14 @@ class MIP003Handler(http.server.BaseHTTPRequestHandler):
                     'amount_specks': {
                         'type': 'integer',
                         'description': 'Bounty amount in NIGHT specks'
+                    },
+                    'work_commit': {
+                        'type': 'string',
+                        'description': 'sha256(nightpay-work-reveal-v1:{work}:{nonce}) — commit before reveal'
+                    },
+                    'idempotency_key': {
+                        'type': 'string',
+                        'description': 'Optional replay-safe key; also accepted via X-Idempotency-Key header'
                     }
                 },
                 'required': ['description', 'amount_specks']
@@ -114,6 +228,9 @@ class MIP003Handler(http.server.BaseHTTPRequestHandler):
 
         elif self.path.startswith('/status/'):
             job_id = self.path.split('/')[-1]
+            if not self._validate_job_id(job_id):
+                self.respond(400, {'error': 'invalid job_id format'})
+                return
             db = get_db()
             row = db.execute('SELECT * FROM jobs WHERE job_id = ?', (job_id,)).fetchone()
             if not row:
@@ -128,37 +245,418 @@ class MIP003Handler(http.server.BaseHTTPRequestHandler):
                     job['result'] = json.loads(job['result'])
                 self.respond(200, job)
 
+        elif self.path.startswith('/jobs'):
+            # GET /jobs?status=<value>&limit=<n>&offset=<n>&approved_before=<iso8601>
+            # used by optimistic-sweep and dashboards.
+            parsed = urlparse(self.path)
+            params = parse_qs(parsed.query)
+            status_filter = params.get('status', [None])[0]
+            approved_before = params.get('approved_before', [None])[0]
+
+            # SECURITY: clamp pagination to bounded values
+            try:
+                limit = int(params.get('limit', ['100'])[0])
+                offset = int(params.get('offset', ['0'])[0])
+            except ValueError:
+                self.respond(400, {'error': 'limit and offset must be integers'})
+                return
+            if limit < 1 or limit > 500:
+                self.respond(400, {'error': 'limit must be between 1 and 500'})
+                return
+            if offset < 0 or offset > 1000000:
+                self.respond(400, {'error': 'offset must be between 0 and 1000000'})
+                return
+
+            # SECURITY: whitelist status values - prevents SQL injection via status param
+            if status_filter and status_filter not in KNOWN_STATUSES:
+                self.respond(400, {'error': f'unknown status filter: {status_filter}'})
+                return
+
+            if approved_before:
+                try:
+                    datetime.fromisoformat(approved_before.replace('Z', '+00:00'))
+                except ValueError:
+                    self.respond(400, {'error': 'approved_before must be ISO-8601'})
+                    return
+
+            db = get_db()
+            if status_filter and approved_before:
+                rows = db.execute(
+                    'SELECT job_id, status, approved_at, amount_specks, input_data '
+                    'FROM jobs '
+                    'WHERE status = ? AND approved_at IS NOT NULL AND approved_at <= ? '
+                    'ORDER BY approved_at ASC, job_id ASC '
+                    'LIMIT ? OFFSET ?',
+                    (status_filter, approved_before, limit, offset)
+                ).fetchall()
+            elif status_filter:
+                rows = db.execute(
+                    'SELECT job_id, status, approved_at, amount_specks, input_data '
+                    'FROM jobs '
+                    'WHERE status = ? '
+                    'ORDER BY updated_at DESC, job_id ASC '
+                    'LIMIT ? OFFSET ?',
+                    (status_filter, limit, offset)
+                ).fetchall()
+            elif approved_before:
+                rows = db.execute(
+                    'SELECT job_id, status, approved_at, amount_specks, input_data '
+                    'FROM jobs '
+                    'WHERE approved_at IS NOT NULL AND approved_at <= ? '
+                    'ORDER BY approved_at ASC, job_id ASC '
+                    'LIMIT ? OFFSET ?',
+                    (approved_before, limit, offset)
+                ).fetchall()
+            else:
+                rows = db.execute(
+                    'SELECT job_id, status, approved_at, amount_specks, input_data '
+                    'FROM jobs '
+                    'ORDER BY updated_at DESC, job_id ASC '
+                    'LIMIT ? OFFSET ?',
+                    (limit, offset)
+                ).fetchall()
+
+            jobs = []
+            for r in rows:
+                j = dict(r)
+                if j.get('input_data'):
+                    try:
+                        j['input_data'] = json.loads(j['input_data'])
+                    except Exception:
+                        pass
+                jobs.append(j)
+
+            self.respond(200, {
+                'jobs': jobs,
+                'limit': limit,
+                'offset': offset,
+                'count': len(jobs),
+                'has_more': len(jobs) == limit
+            })
+
         else:
             self.respond(404, {'error': 'not found'})
 
+    # ── POST ─────────────────────────────────────────────────────────────────
+
     def do_POST(self):
-        length = int(self.headers.get('Content-Length', 0))
-        body = json.loads(self.rfile.read(length)) if length else {}
+        body = self._read_body()
 
         if self.path == '/start_job':
-            job_id = str(uuid.uuid4())
-            now = datetime.now(timezone.utc).isoformat()
+            # Validate optional work_commit
+            work_commit = body.get('work_commit')
+            if work_commit is not None:
+                if not re.match(r'^[0-9a-f]{64}$', str(work_commit)):
+                    self.respond(400, {'error': 'work_commit must be 64-char lowercase hex sha256'})
+                    return
+
+            # Validate optional amount_specks
+            amount_specks = body.get('amount_specks')
+            if amount_specks is not None:
+                try:
+                    amount_specks = int(amount_specks)
+                    if amount_specks < 0:
+                        raise ValueError
+                except (ValueError, TypeError):
+                    self.respond(400, {'error': 'amount_specks must be a non-negative integer'})
+                    return
+
+            # Optional idempotency key: header and body must match if both provided.
+            idem_header = self.headers.get('X-Idempotency-Key', '').strip()
+            idem_body_raw = body.get('idempotency_key')
+            idem_body = str(idem_body_raw).strip() if idem_body_raw is not None else ''
+            if idem_header and idem_body and idem_header != idem_body:
+                self.respond(400, {'error': 'idempotency_key body value does not match X-Idempotency-Key header'})
+                return
+
+            idempotency_key = idem_header or idem_body or None
+            request_hash = None
+            if idempotency_key is not None:
+                if not re.match(r'^[A-Za-z0-9._:-]{8,128}$', idempotency_key):
+                    self.respond(400, {'error': 'idempotency key must match [A-Za-z0-9._:-] and be 8-128 chars'})
+                    return
+                request_hash = hash_start_job_request(body)
+
+            now_dt = datetime.now(timezone.utc)
+            now = now_dt.isoformat()
             db = get_db()
+
+            if idempotency_key:
+                # BEGIN IMMEDIATE serializes writers and prevents duplicate inserts for same key.
+                db.execute('BEGIN IMMEDIATE')
+                try:
+                    if IDEMPOTENCY_TTL_SECONDS > 0:
+                        cutoff = (now_dt - timedelta(seconds=IDEMPOTENCY_TTL_SECONDS)).isoformat()
+                        db.execute('DELETE FROM idempotency_keys WHERE created_at < ?', (cutoff,))
+
+                    existing = db.execute(
+                        'SELECT request_hash, job_id FROM idempotency_keys WHERE idem_key = ?',
+                        (idempotency_key,)
+                    ).fetchone()
+
+                    if existing:
+                        if not hmac.compare_digest(existing['request_hash'], request_hash):
+                            db.rollback()
+                            self.respond(409, {'error': 'idempotency key already used with different payload'})
+                            return
+
+                        job_id = existing['job_id']
+                        row = db.execute(
+                            'SELECT status FROM jobs WHERE job_id = ?',
+                            (job_id,)
+                        ).fetchone()
+                        db.rollback()
+
+                        if not row:
+                            self.respond(500, {'error': 'idempotency mapping references missing job'})
+                            return
+
+                        self.respond(200, {
+                            'job_id': job_id,
+                            'job_token': make_job_token(job_id),
+                            'status': row['status'],
+                            'idempotent_replay': True
+                        })
+                        return
+
+                    job_id = str(uuid.uuid4())
+                    db.execute(
+                        '''INSERT INTO jobs(job_id, status, input_data, work_commit, amount_specks, started_at, updated_at)
+                           VALUES (?, ?, ?, ?, ?, ?, ?)''',
+                        (job_id, 'running', json.dumps(body.get('input_data', {})),
+                         work_commit, amount_specks, now, now)
+                    )
+                    db.execute(
+                        '''INSERT INTO idempotency_keys(idem_key, request_hash, job_id, created_at)
+                           VALUES (?, ?, ?, ?)''',
+                        (idempotency_key, request_hash, job_id, now)
+                    )
+                    db.commit()
+                except Exception:
+                    db.rollback()
+                    raise
+            else:
+                job_id = str(uuid.uuid4())
+                db.execute(
+                    '''INSERT INTO jobs(job_id, status, input_data, work_commit, amount_specks, started_at, updated_at)
+                       VALUES (?, ?, ?, ?, ?, ?, ?)''',
+                    (job_id, 'running', json.dumps(body.get('input_data', {})),
+                     work_commit, amount_specks, now, now)
+                )
+                db.commit()
+
+            # SECURITY: job_token is ephemeral - derived on demand, never stored
+            job_token = make_job_token(job_id)
+            response = {
+                'job_id':    job_id,
+                'job_token': job_token,
+                'status':    'running'
+            }
+            if idempotency_key:
+                response['idempotency_key'] = idempotency_key
+            self.respond(200, response)
+
+        elif self.path.startswith('/provide_input/'):
+            job_id = self.path.split('/')[-1]
+
+            # SECURITY: validate job_id format
+            if not self._validate_job_id(job_id):
+                self.respond(400, {'error': 'invalid job_id format'})
+                return
+
+            # SECURITY: require valid job_token — hard cutover, no legacy fallback
+            auth_header = self.headers.get('Authorization', '')
+            if not auth_header.startswith('Bearer '):
+                self.respond(401, {'error': 'Authorization: Bearer <job_token> required'})
+                return
+            provided_token = auth_header[len('Bearer '):]
+            if not verify_job_token(job_id, provided_token):
+                self.respond(403, {'error': 'invalid job_token'})
+                return
+
+            db  = get_db()
+            row = db.execute(
+                'SELECT work_commit, amount_specks, status FROM jobs WHERE job_id = ?',
+                (job_id,)
+            ).fetchone()
+            if not row:
+                self.respond(404, {'error': 'job not found'})
+                return
+
+            # SECURITY: only accept input while job is still running
+            if row['status'] != 'running':
+                self.respond(409, {'error': f'job is not running (status: {row[\"status\"]})'})
+                return
+
+            # SECURITY: commit-reveal verification (skipped if no work_commit — backward compat)
+            work_commit = row['work_commit']
+            if work_commit is not None:
+                work  = body.get('work')
+                nonce = body.get('work_nonce')
+                if not work or not nonce:
+                    self.respond(400, {'error': 'work and work_nonce required for commit-reveal jobs'})
+                    return
+                if not verify_work_reveal(work_commit, str(work), str(nonce)):
+                    self.respond(400, {'error': 'commit-reveal mismatch: sha256(nightpay-work-reveal-v1:work:nonce) != work_commit'})
+                    return
+
+            now           = datetime.now(timezone.utc)
+            amount_specks = row['amount_specks'] or 0
+
+            # Determine delivery path
+            if amount_specks >= MULTISIG_THRESHOLD_SPECKS:
+                next_status = 'multisig_pending'
+                approved_at = None  # no auto-approve until M-of-N collected
+            else:
+                next_status = 'awaiting_approval'
+                approved_at = (now + timedelta(hours=OPTIMISTIC_WINDOW_HOURS)).isoformat()
+
             db.execute(
-                'INSERT INTO jobs(job_id, status, input_data, started_at, updated_at) VALUES (?, ?, ?, ?, ?)',
-                (job_id, 'running', json.dumps(body.get('input_data', {})), now, now)
+                '''UPDATE jobs
+                   SET extra_input = ?, status = ?, approved_at = ?, updated_at = ?
+                   WHERE job_id = ?''',
+                (json.dumps(body), next_status, approved_at, now.isoformat(), job_id)
             )
             db.commit()
-            self.respond(200, {'job_id': job_id, 'status': 'running'})
+            self.respond(200, {
+                'status':      next_status,
+                'approved_at': approved_at,
+                'message':     'work accepted, optimistic window started'
+                               if next_status == 'awaiting_approval'
+                               else 'work accepted, awaiting multisig approval'
+            })
 
-        elif self.path.startswith('/provide_input/'):
+        elif self.path.startswith('/provide_result/'):
+            # ClawWork-compatible: agent delivers final work output + artifact paths.
+            # Mirrors ClawWork's submit_work tool: accepts work_output + artifact_file_paths,
+            # sets job to awaiting_approval (or multisig_pending for high-value jobs),
+            # and returns payment economics so the calling agent sees its net payout.
             job_id = self.path.split('/')[-1]
-            db = get_db()
+
+            if not self._validate_job_id(job_id):
+                self.respond(400, {'error': 'invalid job_id format'})
+                return
+
+            # SECURITY: require valid job_token
+            auth_header = self.headers.get('Authorization', '')
+            if not auth_header.startswith('Bearer '):
+                self.respond(401, {'error': 'Authorization: Bearer <job_token> required'})
+                return
+            provided_token = auth_header[len('Bearer '):]
+            if not verify_job_token(job_id, provided_token):
+                self.respond(403, {'error': 'invalid job_token'})
+                return
+
+            work_output = str(body.get('work_output', ''))
+            artifact_paths = body.get('artifact_file_paths', [])
+            if not isinstance(artifact_paths, list):
+                artifact_paths = []
+
+            if len(work_output) < 10:
+                self.respond(400, {'error': 'work_output must be at least 10 chars'})
+                return
+
+            db  = get_db()
+            row = db.execute(
+                'SELECT work_commit, amount_specks, status FROM jobs WHERE job_id = ?',
+                (job_id,)
+            ).fetchone()
+            if not row:
+                self.respond(404, {'error': 'job not found'})
+                return
+            if row['status'] != 'running':
+                self.respond(409, {'error': f'job is not running (status: {row["status"]})'})
+                return
+
+            now           = datetime.now(timezone.utc)
+            amount_specks = row['amount_specks'] or 0
+            fee_bps       = int(os.environ.get('OPERATOR_FEE_BPS', '200'))
+            fee           = amount_specks * fee_bps // 10000
+            net_to_agent  = amount_specks - fee
+
+            if amount_specks >= MULTISIG_THRESHOLD_SPECKS:
+                next_status = 'multisig_pending'
+                approved_at = None
+            else:
+                next_status = 'awaiting_approval'
+                approved_at = (now + timedelta(hours=OPTIMISTIC_WINDOW_HOURS)).isoformat()
+
+            result_payload = json.dumps({
+                'work_output':      work_output[:500],  # store truncated — full output is agent-side
+                'artifact_paths':   artifact_paths,
+                'artifact_count':   len(artifact_paths),
+            })
+
+            db.execute(
+                '''UPDATE jobs
+                   SET result = ?, status = ?, approved_at = ?, updated_at = ?
+                   WHERE job_id = ?''',
+                (result_payload, next_status, approved_at, now.isoformat(), job_id)
+            )
+            db.commit()
+
+            self.respond(200, {
+                'status':        next_status,
+                'approved_at':   approved_at,
+                'artifact_count': len(artifact_paths),
+                # Economics footer — ClawWork-compatible shape
+                'economics': {
+                    'amount_specks': amount_specks,
+                    'fee':           fee,
+                    'net_to_agent':  net_to_agent,
+                    'fee_bps':       fee_bps,
+                },
+                'message': (
+                    'work accepted, optimistic window started'
+                    if next_status == 'awaiting_approval'
+                    else 'work accepted, awaiting multisig approval'
+                ),
+            })
+
+        elif self.path.startswith('/dispute/'):
+            job_id = self.path.split('/')[-1]
+
+            if not self._validate_job_id(job_id):
+                self.respond(400, {'error': 'invalid job_id format'})
+                return
+
+            reason = str(body.get('reason', 'no reason given'))[:500]
+
+            # SECURITY: either the job_token holder OR the operator can dispute
+            auth_header   = self.headers.get('Authorization', '')
+            op_sig_header = self.headers.get('X-Operator-Sig', '')
+            authorized    = False
+
+            if auth_header.startswith('Bearer '):
+                token = auth_header[len('Bearer '):]
+                if verify_job_token(job_id, token):
+                    authorized = True
+
+            if not authorized and op_sig_header:
+                if verify_operator_sig(job_id, reason, op_sig_header):
+                    authorized = True
+
+            if not authorized:
+                self.respond(403, {'error': 'dispute requires valid job_token or X-Operator-Sig'})
+                return
+
+            db  = get_db()
             now = datetime.now(timezone.utc).isoformat()
             cur = db.execute(
-                'UPDATE jobs SET extra_input = ?, updated_at = ? WHERE job_id = ?',
-                (json.dumps(body), now, job_id)
+                '''UPDATE jobs SET status = 'disputed', dispute_reason = ?, updated_at = ?
+                   WHERE job_id = ? AND status = 'awaiting_approval' ''',
+                (reason, now, job_id)
             )
             if cur.rowcount == 0:
-                self.respond(404, {'error': 'job not found'})
+                # Check if job exists at all
+                exists = db.execute('SELECT status FROM jobs WHERE job_id = ?', (job_id,)).fetchone()
+                if not exists:
+                    self.respond(404, {'error': 'job not found'})
+                else:
+                    self.respond(409, {'error': f'job cannot be disputed in current state (status: {exists[\"status\"]})'})
             else:
                 db.commit()
-                self.respond(200, {'status': 'input_received'})
+                self.respond(200, {'status': 'disputed', 'reason': reason})
 
         else:
             self.respond(404, {'error': 'not found'})
@@ -169,6 +667,8 @@ class ThreadedHTTPServer(http.server.ThreadingHTTPServer):
 httpd = ThreadedHTTPServer(('0.0.0.0', PORT), MIP003Handler)
 print(f'[nightpay] MIP-003 threaded service ready on port {PORT}')
 print(f'[nightpay] DB: {DB_PATH}')
-print(f'[nightpay] Endpoints: /availability, /input_schema, /start_job, /status/<id>, /provide_input/<id>')
+print(f'[nightpay] Optimistic window: {OPTIMISTIC_WINDOW_HOURS}h | Multisig threshold: {MULTISIG_THRESHOLD_SPECKS} specks | Fee: {os.environ.get('OPERATOR_FEE_BPS','200')} bps')
+print(f'[nightpay] Idempotency TTL: {IDEMPOTENCY_TTL_SECONDS}s (X-Idempotency-Key)')
+print(f'[nightpay] Endpoints: /availability /input_schema /start_job /status/<id> /provide_input/<id> /provide_result/<id> /dispute/<id> /jobs?status=&limit=&offset=&approved_before=')
 httpd.serve_forever()
-" "$PORT" "$DB_PATH"
+" "$PORT" "$DB_PATH" "$JOB_TOKEN_SECRET" "$OPERATOR_SECRET_KEY" "$OPTIMISTIC_WINDOW_HOURS" "$MULTISIG_THRESHOLD_SPECKS" "$OPERATOR_FEE_BPS" "$IDEMPOTENCY_TTL_SECONDS"