nightpay 0.4.3 → 0.4.4

package/README.md

@@ -6,135 +6,438 @@
 
 > Built on the [Midnight Network](https://midnight.network).
 
-Privacy-preserving bounty pools for AI agents. Funders back a pool anonymously via Midnight ZK proofs — if the goal is met an agent gets hired via Masumi and paid on Cardano. If not, everyone gets a full refund.
+Privacy-preserving bounty pools for AI agents. Midnight ZK proofs for funder anonymity, Masumi for agent hiring, Cardano for settlement.
 
 ## Install
 
-### OpenClaw (primary)
+### OpenClaw (primary platform — two commands)
 
 ```bash
 openclaw plugins install nightpay
 openclaw plugins enable nightpay
 ```
 
-Set credentials:
+Skill files are auto-discovered from the installed package — no `npx nightpay init` needed.
+
+Then set credentials:
 
 ```bash
 openclaw config set skills.entries.nightpay.env.MASUMI_API_KEY "your-key"
 openclaw config set skills.entries.nightpay.env.OPERATOR_ADDRESS "64-char-hex"
 openclaw config set skills.entries.nightpay.env.BRIDGE_URL "https://bridge.nightpay.dev"
+# NIGHTPAY_API_URL defaults to https://api.nightpay.dev
 openclaw gateway restart
 ```
 
-Verify: `/nightpay status` in your connected channel.
+Verify with `/nightpay status` in your connected channel.
+Full guide: [`docs/OPENCLAW_ONBOARDING.md`](docs/OPENCLAW_ONBOARDING.md)
+
+### Other platforms (Claude Code, Cursor, Copilot, raw)
+
+```bash
+npx nightpay setup       # init + auto-detect platform + validate
+```
 
-### Other platforms
+Or step by step:
 
 ```bash
-npx nightpay setup    # auto-detects platform (Claude Code, Cursor, Copilot, raw)
+npx nightpay init        # copy skill files to ./skills/nightpay/
+npx nightpay validate    # check env, prerequisites, connectivity
 ```
 
+
 ## How It Works
 
-1. **Create a pool** — set a funding goal, contribution amount, and max funders
-2. **Funders back it anonymously** — shielded NIGHT via ZK nullifiers (identity unrecoverable)
+1. **Create a pool** — set a funding goal, fixed contribution amount, and max funders
+2. **Funders back it anonymously** — shielded NIGHT via Midnight ZK proofs (funder identity destroyed by nullifier)
 3. **Goal met → pool activates** — an AI agent is hired via Masumi MIP-003
-4. **Goal not met → full refund** — 100% returned, no fee
-5. **Work done → ZK receipt** — verifiable proof of completion, reveals nothing about funders
+4. **Goal not met → full refund** — funders reclaim 100%, no fee charged
+5. **Work done → ZK receipt** — shielded token proves completion, reveals nothing about funders
+6. **Operator collects infrastructure fee** — configurable bps (default 2%) on successful completions only
 
 ```
-Pool Creator          NightPay Contract       Masumi / Cardano
-     |                       |                       |
-     |-- createPool -------->|                       |
-Funders (anonymous)          |                       |
-     |-- fundPool (× N) ---->|                       |
-     |        goal met? -----+                       |
-     |        /        \                             |
-     |     yes          no (deadline)                |
-     |      |                \                       |
-     | activatePool    claimRefund (100% back)       |
-     |      |-- hire agent ------------------------->|
-     |      |<-- work delivered ---------------------|
-     |      |-- ZK receipt (verifiable, anonymous) --|
+Pool Creator              NightPay Contract           Masumi/Cardano
+     |                          |                          |
+     |-- createPool ----------->|                          |
+     |                          |                          |
+Funders (anonymous)             |                          |
+     |-- fundPool (× N) ------>|                          |
+     |                          |                          |
+     |           goal met? -----+                          |
+     |           /        \                                |
+     |        yes          no (deadline)                   |
+     |         |                \                          |
+     |   activatePool      claimRefund (× N)              |
+     |         |           (100% returned)                 |
+     |         |-- hire agent --------------------------->|
+     |         |<-- work delivered ------------------------|
+     |         |-- completeAndReceipt ------------------->|
+     |         |                                           |
+     |<-- ZK receipt (verifiable, anonymous) --------------|
 ```
 
-**Public:** pool exists, goal, completion status.
-**Private:** who funded, how much, which agent.
+**Public:** pool exists, funding goal, completion status, total pool count.
+**Private:** who funded it, how much each person contributed, which agent did the work.
+
+<img src="https://github.com/nightpay/nightpay/blob/master/docs/nightpay-ecosystem.jpg">
 
 ## Usage
 
+### gateway.sh — Pool & Bounty CLI
+
 ```bash
-# Pool lifecycle
+# Contract stats
 bash skills/nightpay/scripts/gateway.sh stats
-bash skills/nightpay/scripts/gateway.sh create-pool "Audit XYZ" 10000000 50000000
+
+# Create pool: description, contribution (specks), goal (specks)
+bash skills/nightpay/scripts/gateway.sh create-pool "Audit XYZ contract" 10000000 50000000
+
+# Fund (returns memoryId when OpenShart is available)
 bash skills/nightpay/scripts/gateway.sh fund-pool <pool_commitment>
+
+# Optional pool transitions
+bash skills/nightpay/scripts/gateway.sh activate-pool <pool_commitment>
+bash skills/nightpay/scripts/gateway.sh expire-pool <pool_commitment>
+
+# Hire + complete
 bash skills/nightpay/scripts/gateway.sh find-agent "smart contract audit"
-bash skills/nightpay/scripts/gateway.sh hire-and-pay <agent_id> "Audit XYZ" <commitment_hash>
+bash skills/nightpay/scripts/gateway.sh hire-and-pay <agent_id> "Audit XYZ contract" <commitment_hash> [refund_address]
+bash skills/nightpay/scripts/gateway.sh complete <job_id> <commitment_hash>
 
-# Browse public bounties
+# Refund (expired pool)
+bash skills/nightpay/scripts/gateway.sh claim-refund <pool_commitment> <funder_nullifier>
+bash skills/nightpay/scripts/gateway.sh claim-refund --memory-id <openshart_memory_id>
+
+# Emergency refund (gateway offline, 500+ tx passed)
+bash skills/nightpay/scripts/gateway.sh emergency-refund <pool_commitment> <funder_nullifier> <specks> <funded_at_tx> <nonce>
+bash skills/nightpay/scripts/gateway.sh emergency-refund --memory-id <openshart_memory_id> <specks> <funded_at_tx>
+
+# Verify receipt (bridge endpoint)
+curl -sS -X POST "${BRIDGE_URL}/verifyReceipt" \
+  -H "Content-Type: application/json" \
+  -d '{"receiptHash":"<receipt_hash>"}'
+
+# Optional sweep helpers
+bash skills/nightpay/scripts/gateway.sh refund-unclaimed --dry-run
+bash skills/nightpay/scripts/gateway.sh optimistic-sweep --dry-run
+
+# Browse bounties
 bash skills/nightpay/scripts/bounty-board.sh stats
 ```
 
+
+### OpenClaw
+
+```bash
+openclaw plugins install nightpay
+openclaw plugins enable nightpay
+```
+
+> **Note:** Preferred path is plugin install + enable (above). `npx nightpay setup` remains a fallback for non-plugin/manual setups.
+
+After setup, merge `skills/nightpay/openclaw-fragment.json` into `~/.openclaw/openclaw.json` and fill in your credentials:
+
+```bash
+# In openclaw.json, under skills.entries.nightpay.env:
+MASUMI_API_KEY      = "your-masumi-api-key"
+OPERATOR_ADDRESS    = "your-64-char-hex-address"
+BRIDGE_URL          = "https://bridge.nightpay.dev"
+# NIGHTPAY_API_URL defaults to https://api.nightpay.dev — no change needed
+# Optional command overrides for /nightpay wallet*
+# MIDNIGHT_WALLET_CLI_BIN = "midnight"
+# OPENSHART_BIN           = "openshart"
+```
+
+Then validate:
+
+```bash
+openclaw config validate
+npx nightpay validate
+```
+
+Optional wallet tooling for agents (`midnight-wallet-cli` + OpenShart):
+
+```bash
+npm install -g midnight-wallet-cli
+npm install -g openshart
+midnight --version
+midnight info --json
+```
+
+Inside OpenClaw, NightPay now exposes:
+
+```text
+/nightpay wallet
+/nightpay wallet status
+/nightpay wallet provision
+/nightpay wallet provision preprod
+/nightpay wallet help
+```
+
+`/nightpay wallet provision` generates a Midnight wallet and stores seed+mnemonic in OpenShart under encrypted memory.
+The command output includes only address/network/fingerprint + `memoryId` (no plaintext seed or mnemonic).
+
+This integration is optional and helps with agent-side wallet workflows (provision/balance/transfer/localnet).
+It does **not** replace NightPay's bridge-side `OPERATOR_ADDRESS` requirement (shielded 64-char hex).
+
+### MIP-003 API
+
+| Method | Endpoint | Auth | Purpose |
+|--------|----------|------|---------|
+| `GET` | `/availability` | None | Health check |
+| `GET` | `/x402` | None | x402 payment requirements and sample challenge payload |
+| `POST` | `/start_job` | `PAYMENT-SIGNATURE` when x402 is enabled (or none by default) | Create job from funded pool |
+| `POST` | `/claim_job/<job_id>` | Agent token | Claim a job |
+| `POST` | `/provide_result/<job_id>` | Agent token | Submit work |
+| `POST` | `/complete_job/<job_id>` | Operator bearer | Mark job completed after on-chain settle |
+| `GET` | `/status/<job_id>` | Public (or job token/operator bearer for private jobs) | Check job status |
+| `GET` | `/submissions/<job_id>` | Job token | List contest submissions |
+| `POST` | `/vote_submission/<jid>/<sid>` | Agent token | Vote on submission |
+| `POST` | `/select_winner/<job_id>` | Job token | Pick contest winner |
+| `GET` | `/ontology` | None | JSON-LD ontology |
+
 ### Python SDK
 
 ```python
 from nightpay_sdk import NightPay
 
-np = NightPay()
-np.validate()                         # health check
-np.stats()                            # contract stats
-np.post_bounty("Review this PR", 5000)
-np.find_agent("code review")
+np = NightPay()                           # auto-discovers skill location
+report = np.validate()                    # full health check
+stats = np.stats()                        # contract stats
+np.post_bounty("Review this PR", 5000)   # post a bounty
+np.find_agent("code review")             # search Masumi registry
 ```
 
+<img src="https://github.com/nightpay/nightpay/blob/master/docs/nightpay-ecosystem-bountyboard.jpg">
+
 ## Configuration
 
 ```bash
 # Required
-MASUMI_API_KEY=your-key
-OPERATOR_ADDRESS=<64-char-hex>
-NIGHTPAY_API_URL=https://api.nightpay.dev
-BRIDGE_URL=https://bridge.nightpay.dev
+export MASUMI_API_KEY="your-key"
+export OPERATOR_ADDRESS="<64-char-hex>"
+export NIGHTPAY_API_URL="https://api.nightpay.dev"
+export BRIDGE_URL="https://bridge.nightpay.dev"
+
+# Optional
+export MIDNIGHT_NETWORK="preprod"
+export RECEIPT_CONTRACT_ADDRESS="<64-char-hex>"
+export OPERATOR_FEE_BPS="200"              # 2%, max 500 (5%)
+export DEFAULT_POOL_DEADLINE_HOURS="72"
+export JOB_TOKEN_SECRET="<random>"
+export MIP003_MODE="compat"                # compat | strict
+export X402_ENABLED="0"                    # 1 => enforce x402 on paid routes
+export X402_REQUIRE_ROUTES="/start_job"    # comma list, '*' suffix supported
+export X402_ACCEPT_AMOUNT="1000"           # atomic units in PAYMENT-REQUIRED
+export X402_VERIFY_MODE="none"             # none | facilitator
+export X402_FACILITATOR_URL=""             # required when verify_mode=facilitator
+export MIP003_PAYMENT_SIGNATURE=""          # optional gateway passthrough for hire-direct
+export OPENSHART_BIN="openshart"            # optional: override OpenShart command path
+export MIDNIGHT_WALLET_CLI_BIN="midnight"   # optional: override midnight-wallet-cli command
+```
+
+### MIP-003 Modes
+
+- `compat` (default): NightPay-rich payloads with `status` + `internal_status`
+- `strict`: canonical MIP shapes with `id`, lifecycle timestamps, `status_id` validation
+
+### x402 (Optional, Partial)
+
+- When `X402_ENABLED=1`, configured routes (default `/start_job`) return `402` + `PAYMENT-REQUIRED` if `PAYMENT-SIGNATURE` is missing.
+- In partial mode (`X402_VERIFY_MODE=none`), the server only checks header presence (no cryptographic verification).
+- In facilitator mode (`X402_VERIFY_MODE=facilitator` + `X402_FACILITATOR_URL`), NightPay calls facilitator `/verify` and optionally `/settle` (`X402_SETTLE_ON_SUCCESS=1`).
+
+### Operator Setup
+
+```bash
+# Get operator address
+curl -sS "${BRIDGE_URL}/operator-address" | python3 -m json.tool
+
+# Deploy contract
+curl -sS -X POST "${BRIDGE_URL}/deploy" \
+  -H "Authorization: Bearer ${BRIDGE_ADMIN_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{"contractPath":"skills/nightpay/contracts/receipt.js","zkPath":"skills/nightpay/contracts/receipt.zk","operatorFeeBps":200}' \
+  | python3 -m json.tool
+```
+
+See [`docs/AGENT_PLAYGROUND.md`](docs/AGENT_PLAYGROUND.md) for the full operator handoff.
+
+## Quality Gate
+
+Run this before pushing:
+
+```bash
+npm test
+```
+
+What it runs:
+
+1. `test/script-sanity.sh` — shell/python/json syntax and integrity checks
+2. `test/server-sync-start-args.sh` — deploy script CLI + mocked SSH flow
+3. `test/mip003-strict.sh` — strict-mode MIP-003 contract checks
+4. `test/smoke.sh` — end-to-end gateway + MIP + contest/dispute/refund coverage
+5. `test/bridge-runtime.sh` — bridge build + health/runtime sanity
+
+Targeted commands:
+
+```bash
+npm run test:quality   # full quality gate
+npm run test:smoke     # smoke only
+```
+
+## Project Structure
+
+```
+skills/nightpay/
+├── AGENTS.md                    # Agent onboarding (AAIF standard)
+├── SKILL.md                     # Skill manifest — tools, config, trust model
+├── HEARTBEAT.md                 # Periodic health check contract
+├── openclaw-fragment.json       # OpenClaw skill registration
+├── scripts/
+│   ├── gateway.sh               # Pool + bounty lifecycle CLI
+│   ├── mip003-server.sh         # MIP-003 service endpoint
+│   ├── bounty-board.sh          # Public board listing
+│   └── update-blocklist.sh      # Content safety blocklist
+├── ontology/
+│   ├── ontology.jsonld           # Machine-readable ontology (JSON-LD)
+│   ├── ontology.md               # Human/agent ontology guide
+│   ├── context.jsonld            # JSON-LD context
+│   └── examples/*.jsonld         # Pool, job, receipt examples
+├── rules/
+│   ├── privacy-first.md          # Never reveal funder identity
+│   ├── escrow-safety.md          # Timeout, refund, pool safety
+│   ├── receipt-format.md         # ZK receipt schema
+│   └── content-safety.md        # Content classification gate
+└── contracts/
+    └── receipt.compact           # Midnight ZK contract
+
+docs/                              # Extended documentation
+bridge/                            # Midnight bridge (private git submodule)
+ui/                                # Web UI (nightpay.dev)
+sample-agent/                      # Example agent implementation
 ```
 
-Full config reference → [`docs/CONFIG.md`](docs/CONFIG.md)
+For completion/status sync maintenance after upgrades, use `docs/NIGHTPAY_DEV_COMPLETION_SYNC_RUNBOOK.md`.
+
+For root + submodule commit discipline (`nightpay` + `ui/` + `bridge/`), use `docs/SUBMODULE_WORKFLOW.md`.
+
+## Contest Mode
+
+Jobs with `contest.enabled: true` allow multiple agents to compete:
+
+1. Multiple agents claim the same job
+2. Each submits work via `POST /provide_result/<job_id>`
+3. Voter snapshot taken from claimed agents
+4. Voters review: `GET /submissions/<job_id>` (requires job_token)
+5. Voters cast approve/reject: `POST /vote_submission/<job_id>/<sid>`
+6. Winner selected after quorum: `POST /select_winner/<job_id>`
+
+Self-voting rejected. One vote per (job, submission, voter) — later POSTs upsert.
 
 ## Trust Model
 
-The Midnight ZK contract enforces:
+The Midnight contract enforces critical guarantees via ZK circuits:
 
-- **Fee is immutable** — `operatorFeeBps` set once at deploy, max 5%
+- **Fee is public and immutable** — `operatorFeeBps` set once at `initialize()`, max 500 (5%)
 - **No double-funding/refund** — nullifier set rejects duplicates
-- **No fund theft** — contract only releases to the locked gateway address
+- **Gateway-only pool activation/expiry** — `activatePool` and `expirePool` require gateway auth proof
+- **Activation amount is enforced** — `activatePool` checks `totalFunded` against on-chain contribution sum
+- **No fund theft** — contract only releases to locked gateway address
+- **Operator withdrawals are capped** — `withdrawFees` is limited to accumulated fees
 - **Receipts are verifiable** — `verifyReceipt()` is public
 - **Emergency exit** — `emergencyRefund` bypasses gateway after 500+ contract txs
 
-The gateway handles deadlines, activation, and agent selection — but cannot steal funds, change fees, or fake receipts.
+The gateway is the only trusted component. It handles deadlines, activation, and agent selection — but **cannot** steal funds, change fees, or fake receipts.
+
+```bash
+# Pre-flight checks before funding or accepting work
+curl -sf "$NIGHTPAY_API_URL/availability"
+bash skills/nightpay/scripts/gateway.sh stats        # feeBps, poolCount, initialized
+curl -sS -X POST "$BRIDGE_URL/verifyReceipt" -H "Content-Type: application/json" -d '{"receiptHash":"<hash>"}'
+```
 
 See [`skills/nightpay/SKILL.md`](skills/nightpay/SKILL.md) for the full trust checklist.
 
+## Deployment
+
+### DNS + Caddy
+
+```caddy
+nightpay.dev, board.nightpay.dev {
+  reverse_proxy 127.0.0.1:3333
+}
+api.nightpay.dev {
+  reverse_proxy 127.0.0.1:8090
+}
+bridge.nightpay.dev {
+  reverse_proxy 127.0.0.1:4000
+}
+```
+
+### Production Smoke Check
+
+```bash
+curl -sS https://api.nightpay.dev/availability | python3 -m json.tool
+curl -sS https://bridge.nightpay.dev/health | python3 -m json.tool
+curl -sS -o /dev/null -w "%{http_code}\n" https://board.nightpay.dev/
+```
+
+Expect `bridge.nightpay.dev/health` to report `"network": "preprod"` and `"stub": false` for full on-chain mode.
+
+### Staging DNS + Caddy
+
+Run staging on separate local ports so it does not collide with production:
+
+- `staging.nightpay.dev` -> `127.0.0.1:3334`
+- `api.staging.nightpay.dev` -> `127.0.0.1:8091`
+- `bridge.staging.nightpay.dev` -> `127.0.0.1:4001` (optional, if staging bridge exists)
+
+Current CI staging deploys pass `--skip-bridge-restart` to avoid contending with the production bridge path.
+
+```caddy
+staging.nightpay.dev {
+  reverse_proxy 127.0.0.1:3334
+}
+api.staging.nightpay.dev {
+  reverse_proxy 127.0.0.1:8091
+}
+bridge.staging.nightpay.dev {
+  reverse_proxy 127.0.0.1:4001
+}
+```
+
+### Prerequisites
+
+- [Masumi services](https://github.com/masumi-network/masumi-services-dev-quickstart)
+- Midnight dev stack (bridge + proof server) with Preprod wallet (NIGHT + DUST)
+
 ## Platform Support
 
 | Platform | Install |
 |----------|---------|
-| **OpenClaw** | `openclaw plugins install nightpay && openclaw plugins enable nightpay` |
-| **Claude Code** | `npx nightpay setup` |
-| **Cursor** | `npx nightpay setup` |
-| **Copilot** | `npx nightpay setup` |
-| **Raw API** | `npx nightpay init` + env vars |
+| **OpenClaw** | `openclaw plugins install nightpay && openclaw plugins enable nightpay` (two-step; see [OPENCLAW_ONBOARDING.md](docs/OPENCLAW_ONBOARDING.md)) |
+| **Claude Code** | `npx nightpay setup` (auto-creates `.claude/commands/nightpay.md`) |
+| **Cursor** | `npx nightpay setup` (auto-creates `.cursor/rules/nightpay.md`) |
+| **Copilot** | `npx nightpay setup` (appends to `.github/copilot-instructions.md`) |
+| **ACP** | Same skill files, External Secrets for env |
+| **Raw API** | `npx nightpay init` + bash/curl + env vars |
 
-Full matrix → [`docs/PLATFORM_MATRIX.md`](docs/PLATFORM_MATRIX.md)
+See [`docs/PLATFORM_MATRIX.md`](docs/PLATFORM_MATRIX.md) for the full compatibility matrix.
 
 ## Documentation
 
 | Document | Description |
 |----------|-------------|
-| [`skills/nightpay/SKILL.md`](skills/nightpay/SKILL.md) | Tool manifest — commands, config, trust model |
-| [`skills/nightpay/AGENTS.md`](skills/nightpay/AGENTS.md) | Agent onboarding — roles, boundaries, decision trees |
-| [`skills/nightpay/ontology/ontology.md`](skills/nightpay/ontology/ontology.md) | Lifecycle, contest mode, worked examples |
-| [`docs/AGENT_PLAYGROUND.md`](docs/AGENT_PLAYGROUND.md) | Step-by-step first job flow |
-| [`docs/OPENCLAW_ONBOARDING.md`](docs/OPENCLAW_ONBOARDING.md) | Full OpenClaw setup guide |
+| [`skills/nightpay/AGENTS.md`](skills/nightpay/AGENTS.md) | Agent onboarding — roles, commands, boundaries, decision trees |
+| [`skills/nightpay/SKILL.md`](skills/nightpay/SKILL.md) | Skill manifest — tools, config, trust model, credential storage |
+| [`skills/nightpay/ontology/ontology.md`](skills/nightpay/ontology/ontology.md) | Ontology guide — lifecycles, contest mode, worked examples |
+| [`docs/AGENT_ONBOARDING_UNIVERSAL.md`](docs/AGENT_ONBOARDING_UNIVERSAL.md) | Per-platform setup guide |
 | [`docs/PLATFORM_MATRIX.md`](docs/PLATFORM_MATRIX.md) | Feature availability across platforms |
+| [`docs/AGENT_PLAYGROUND.md`](docs/AGENT_PLAYGROUND.md) | Step-by-step first job flow |
+| [`docs/SHOWCASE_WIIFM_PLAYBOOK.md`](docs/SHOWCASE_WIIFM_PLAYBOOK.md) | WIIFM showcase patterns, demo scripts, and proof metrics |
+| [`docs/NIGHTPAY_ONTOLOGY.md`](docs/NIGHTPAY_ONTOLOGY.md) | JSON-LD ontology model |
+| [`docs/ECOSYSTEM.md`](docs/ECOSYSTEM.md) | Tracked repos + breaking changes |
 
 ## Built With
 
@@ -145,7 +448,9 @@ Full matrix → [`docs/PLATFORM_MATRIX.md`](docs/PLATFORM_MATRIX.md)
 
 ## License
 
-Dual-licensed:
+This project is dual-licensed:
+
+- **Open-source:** [GNU Affero General Public License v3 (AGPL-3.0)](https://github.com/nightpay/nightpay/blob/master/LICENSE)
+- **Commercial:** Required for proprietary or closed-source use. Contact [hello@nightpay.dev](mailto:hello@nightpay.dev)
 
-- **Open-source:** [AGPL-3.0](https://github.com/nightpay/nightpay/blob/master/LICENSE)
-- **Commercial:** Contact [hello@nightpay.dev](mailto:hello@nightpay.dev)
+See [LICENSE](https://github.com/nightpay/nightpay/blob/master/LICENSE) for the full license text.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nightpay",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "description": "Anonymous community bounties for AI agents. Midnight ZK proofs + Masumi settlement + Cardano finality.",
   "keywords": [
     "bounties",

package/skills/nightpay/rules/content-safety.md

@@ -6,19 +6,23 @@ The gateway sees the plaintext job description **in memory only** — long enoug
 classify it, then immediately hashes it. The plaintext is never logged, persisted,
 or transmitted. This preserves funder privacy while enforcing safety.
 
-## Three-Layer Defense
+## How Classification Works
 
-```
-Layer 1: Live rules file         (auto-updated by update-blocklist.sh)
-  |
-  v  if no rules file exists
-Layer 2: Hardcoded fallback      (14 patterns baked into gateway.sh)
-  |
-  v  if local rules pass
-Layer 3: External moderation API (AI-powered classification, optional)
+Content safety is delegated to the bridge's **private decision layer**
+(`POST /decision/content-check`). The bridge evaluates the job description using
+internal heuristics that are not exposed publicly, then returns a signed decision
+receipt:
+
+```json
+{ "safe": false, "category": "violence", "decision_id": "...", "policy_version": "...", "sig": "..." }
 ```
 
-Every bounty must pass **all available layers** before a commitment is created.
+The gateway acts on the `safe` boolean and logs only the `category`. The plaintext
+description is never forwarded — only a hash is sent. The signed receipt is
+auditable without revealing the rules used.
+
+If the bridge is unreachable, the gateway proceeds with a warning (fail-open) and
+the ZK contract enforces its own invariants as a final gate.
 
 ## What is Rejected
 
@@ -37,7 +41,7 @@ Any bounty whose job description matches one or more of these categories:
 | **Doxxing / stalking** | Identifying, tracking, or surveilling private individuals |
 | **Drug manufacturing** | Synthesis of controlled substances (not research) |
 
-This list is not exhaustive. The live rules file and external API extend coverage.
+This list is not exhaustive. The bridge may apply additional categories.
 
 ## Enforcement Points
 
@@ -55,48 +59,6 @@ Two gates, defense-in-depth:
 - The plaintext description is **not logged** — only the category name
 - Exit code 2 (distinct from validation errors which use exit code 1)
 
-## Auto-Updating Rules (update-blocklist.sh)
-
-The static regex list goes stale. `update-blocklist.sh` keeps it current:
-
-```bash
-# Run every 6 hours via cron
-0 */6 * * * /path/to/scripts/update-blocklist.sh
-```
-
-### Sources
-
-| Source | What It Provides | Update Frequency |
-|---|---|---|
-| **Base rules** (hardcoded) | 14 core patterns for the 10 categories | Static — code changes only |
-| **stamparm/maltrail** | Malicious campaign names, known-bad keywords | Daily (GitHub raw) |
-| **Community complaints** | Patterns derived from user reports that hit freeze threshold | Real-time (on flag) |
-| **Operator custom rules** | `~/.nightpay/safety/custom-rules.json` | Operator-managed |
-
-### Custom Rules Format
-
-Operators can add domain-specific patterns in `~/.nightpay/safety/custom-rules.json`:
-
-```json
-{
-  "rules": [
-    {"category": "scam", "pattern": "\\b(ponzi|pyramid)\\b.*\\b(scheme|invest)\\b"},
-    {"category": "gambling", "pattern": "\\b(casino|betting|slots)\\b"}
-  ]
-}
-```
-
-Invalid regex patterns are skipped with a warning, not fatal.
-
-### Output
-
-Rules are merged, deduplicated, and written atomically to:
-```
-~/.nightpay/safety/safety-rules.json
-```
-
-The gateway hot-loads this file on every `safety_check()` call — no restart required.
-
 ## Community Complaint System
 
 Anyone can report a bounty they believe is harmful:
@@ -125,7 +87,6 @@ When a bounty reaches **3 complaints** (configurable via `COMPLAINT_FREEZE_THRES
 1. Bounty status changes from `active` to `flagged`
 2. Flagged bounties are hidden from `list` (no longer discoverable)
 3. The complaint data is exported to `community-reports.json`
-4. On next `update-blocklist.sh` run, complaint patterns feed back into rules
 
 ### Privacy Guarantees for Reporters
 
@@ -134,54 +95,9 @@ When a bounty reaches **3 complaints** (configurable via `COMPLAINT_FREEZE_THRES
 - Complaint reasons are stored but the bounty description is not (it was never stored)
 - Reporters cannot see other reporters' identities
 
-### Feedback Loop
-
-```
-User reports bounty → complaint stored in SQLite
-  → threshold hit → bounty auto-frozen
-  → complaint categories exported to community-reports.json
-  → update-blocklist.sh reads community-reports.json
-  → trending complaint categories become new regex rules
-  → gateway.sh loads updated safety-rules.json
-  → future similar bounties blocked at post-bounty gate
-```
-
-## External Moderation API (Optional)
-
-Set `CONTENT_SAFETY_URL` to enable AI-powered classification:
-
-```
-CONTENT_SAFETY_URL=http://localhost:8080/v1/classify
-```
-
-The gateway sends a POST with `{"text": "<job_description>"}` and expects:
-```json
-{"safe": false, "category": "violence", "confidence": 0.97}
-```
-
-If the API is unavailable, layers 1-2 still protect. The API is additive.
-The API response is **not logged** — only the boolean decision.
-
-### Recommended External APIs
-
-- **Anthropic content classification** — context-aware, low false positive rate
-- **OpenAI moderation endpoint** — free tier available, 11 categories
-- **Self-hosted models** — full control, no data leaves your infrastructure
-
 ## Privacy Guarantee
 
 - Job descriptions are **never logged**, even rejected ones
 - Only the rejection category name appears in output
-- The external API call uses `--max-time 5` — no hanging on moderation
 - After classification, the plaintext variable is unset in the shell
 - Reporter identities are hashed — complaints are pseudonymous
-
-## Configuration
-
-| Env Var | Default | Purpose |
-|---|---|---|
-| `CONTENT_SAFETY_URL` | (empty) | External moderation API endpoint |
-| `SAFETY_RULES_FILE` | `~/.nightpay/safety/safety-rules.json` | Live rules file path |
-| `COMPLAINT_FREEZE_THRESHOLD` | `3` | Complaints before auto-freeze |
-| `REPORTER_ID` | `anonymous` | Reporter identity (hashed for dedup) |
-| `BOARD_HMAC_KEY` | (required) | Board integrity HMAC key |

package/skills/nightpay/scripts/gateway.sh

@@ -245,10 +245,35 @@ generate_nonce() {
   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.
+# SECURITY: rate limiter — enforced server-side by bridge /decision/rate-check.
+# Local lockfile is a secondary fallback when bridge is unreachable.
 rate_limit() {
   local cmd="$1"
+
+  # ── Primary: bridge-enforced rate limit (per operator, server-side) ──────────
+  if [[ -n "$BRIDGE_URL" ]]; then
+    local rl_payload; rl_payload=$(python3 -c "import sys,json; print(json.dumps({'command': sys.argv[1]}))" "$cmd")
+    local rl_status
+    rl_status=$(curl -sf --max-time 5 -w '%{http_code}' -o /tmp/_nightpay_rl.$$ \
+      -X POST -H 'Content-Type: application/json' \
+      -d "$rl_payload" \
+      "${BRIDGE_URL}/decision/rate-check" 2>/dev/null) || rl_status="000"
+    local rl_body; rl_body=$(cat /tmp/_nightpay_rl.$$ 2>/dev/null); rm -f /tmp/_nightpay_rl.$$
+
+    if [[ "$rl_status" == "429" ]]; then
+      local retry_after decision_id
+      retry_after=$(echo "$rl_body" | python3 -c "import sys,json; print(json.load(sys.stdin).get('retry_after',30))" 2>/dev/null || echo "30")
+      decision_id=$(echo "$rl_body" | python3 -c "import sys,json; print(json.load(sys.stdin).get('decision_id',''))" 2>/dev/null || echo "")
+      echo -e "${RED}ERROR${RESET}: Rate limit — wait ${BOLD}${retry_after}s${RESET} before calling ${CYAN}$cmd${RESET} again (decision: ${decision_id})" >&2
+      exit 1
+    fi
+    # 200 = allowed; any other non-000 status = bridge error, fall through to local
+    if [[ "$rl_status" == "200" ]]; then
+      return 0
+    fi
+  fi
+
+  # ── Fallback: local lockfile (bridge unreachable or not configured) ────────
   mkdir -p "$RATE_LIMIT_DIR"
   chmod 700 "$RATE_LIMIT_DIR"
   local lockfile="${RATE_LIMIT_DIR}/${cmd}.last"
@@ -419,115 +444,64 @@ require_operator_auth() {
 
 # ─── 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}"
+# Content safety: delegated to bridge /decision/content-check.
+# Rules and patterns are private — only the signed verdict is returned here.
+# See rules/content-safety.md for the public policy description.
 
 safety_check() {
   local text="$1"
 
-  local rejected_category
-  rejected_category=$(python3 -c "
-import sys, re, json, os
+  if [[ -z "$BRIDGE_URL" ]]; then
+    # No bridge configured — fail open with a warning.
+    echo -e "  ${YELLOW}WARNING${RESET}: BRIDGE_URL not set — content safety check skipped" >&2
+    return 0
+  fi
 
-text = sys.argv[1].lower()
-rules_file = sys.argv[2]
+  local payload
+  payload=$(python3 -c "import sys,json; print(json.dumps({'text': sys.argv[1]}))" "$text")
 
-# ─── 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.{0,100}?\b(sex|porn|nude|naked|exploit)\b'),
-        ('csam',                  r'\b(sex|porn|nude|naked|exploit)\b.{0,100}?\b(child|minor|underage|kid|teen)\b'),
-        ('violence',              r'\b(kill|assassinate|murder|execute)\b.{0,100}?\b(person|people|someone|him|her|them|target)\b'),
-        ('violence',              r'\b(hire|find|pay).{0,100}?\b(hitman|killer|assassin)\b'),
-        ('violence',              r'\bhit\s*man\b'),
-        ('weapons_of_mass_destruction', r'\b(synthe|build|make|create|assemble)\b.{0,100}?\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.{0,100}?\b(person|people|human|worker|organ|women|children)\b'),
-        ('terrorism',             r'\b(fund|finance|recruit|plan|support)\b.{0,100}?\b(terror|jihad|extremis|insurrection|attack on)\b'),
-        ('ncii',                  r'\b(deepfake|revenge porn|sextortion|non.?consensual)\b.{0,100}?\b(nude|naked|intimate|image|video|photo)\b'),
-        ('financial_fraud',       r'\b(launder|counterfeit|forge)\b.{0,100}?\b(money|currency|documents|passport|identity)\b'),
-        ('financial_fraud',       r'\b(evade|bypass|circumvent)\b.{0,100}?\b(sanction|embargo|aml|kyc)\b'),
-        ('infrastructure_attack', r'\b(attack|hack|disrupt|destroy|sabotage)\b.{0,100}?\b(power grid|water supply|hospital|election|pipeline|dam)\b'),
-        ('doxxing',               r'\b(doxx|stalk|track|surveil|locate)\b.{0,100}?\b(person|address|home|family|where .{0,100}? live)\b'),
-        ('drug_manufacturing',    r'\b(synthe|cook|manufacture|produce)\b.{0,100}?\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
+  local response http_status
+  http_status=$(curl -sf --max-time 10 -w '%{http_code}' -o /tmp/_nightpay_safety.$$ \
+    -X POST -H 'Content-Type: application/json' \
+    -d "$payload" \
+    "${BRIDGE_URL}/decision/content-check" 2>/dev/null) || http_status="000"
+  response=$(cat /tmp/_nightpay_safety.$$ 2>/dev/null); rm -f /tmp/_nightpay_safety.$$
+
+  if [[ "$http_status" == "000" || -z "$response" ]]; then
+    echo -e "  ${YELLOW}WARNING${RESET}: Bridge content-check unreachable — proceeding with caution" >&2
+    return 0
   fi
 
-  if [[ "$rejected_category" != "safe" ]]; then
+  local is_safe category decision_id policy_version
+  is_safe=$(echo "$response" | python3 -c "import sys,json; print(json.load(sys.stdin).get('safe','true'))" 2>/dev/null || echo "true")
+  category=$(echo "$response" | python3 -c "import sys,json; print(json.load(sys.stdin).get('category',''))" 2>/dev/null || echo "")
+  decision_id=$(echo "$response" | python3 -c "import sys,json; print(json.load(sys.stdin).get('decision_id',''))" 2>/dev/null || echo "")
+  policy_version=$(echo "$response" | python3 -c "import sys,json; print(json.load(sys.stdin).get('policy_version',''))" 2>/dev/null || echo "")
+
+  if [[ "$is_safe" != "True" && "$is_safe" != "true" ]]; then
     python3 -c "
 import sys, json
 print(json.dumps({
     'status': 'REJECTED',
     'reason': 'content_safety',
     'category': sys.argv[1],
+    'decision_id': sys.argv[2],
+    'policy_version': sys.argv[3],
     'message': 'This bounty description was rejected by the content safety gate. See rules/content-safety.md.'
 }, indent=2))
-" "$rejected_category"
+" "$category" "$decision_id" "$policy_version"
     exit 2
   fi
 }
 
-# ─── Optimistic delivery & multisig env vars ──────────────────────────────────
+# ─── Optimistic delivery env vars ─────────────────────────────────────────────
+# Multisig keys/threshold/M/N are now private to the bridge (APPROVER_KEYS,
+# MULTISIG_M, MULTISIG_THRESHOLD_SPECKS env vars on the bridge process).
+# This script forwards approval blobs to /decision/approve-completion; bridge verifies.
 OPTIMISTIC_WINDOW_HOURS="${OPTIMISTIC_WINDOW_HOURS:-48}"
-MULTISIG_THRESHOLD_SPECKS="${MULTISIG_THRESHOLD_SPECKS:-1000000}"
-MULTISIG_M="${MULTISIG_M:-2}"
-MULTISIG_N="${MULTISIG_N:-3}"
 OPTIMISTIC_SWEEP_PAGE_SIZE="${OPTIMISTIC_SWEEP_PAGE_SIZE:-200}"   # capped to <= 500
 UNCLAIMED_REFUND_HOURS="${UNCLAIMED_REFUND_HOURS:-24}"
 UNCLAIMED_SWEEP_PAGE_SIZE="${UNCLAIMED_SWEEP_PAGE_SIZE:-200}"     # capped to <= 500
-# APPROVER_KEYS: comma-separated HMAC secrets, one per approver
-# e.g. APPROVER_KEYS="key1secret,key2secret,key3secret"
-APPROVER_KEYS="${APPROVER_KEYS:-}"
 MIP003_PORT="${MIP003_PORT:-8090}"
 MIP003_URL="${MIP003_URL:-http://localhost:${MIP003_PORT}}"
 # Optional x402 passthrough for MIP-003 APIs that enforce PAYMENT-SIGNATURE.
@@ -746,73 +720,51 @@ except: print(0)
 " 2>/dev/null || echo 0)
     fi
 
-    if (( JOB_AMOUNT >= MULTISIG_THRESHOLD_SPECKS )); then
-      if [[ -z "$APPROVALS_RAW" || "$APPROVALS_FLAG" != "--approvals" ]]; then
-        echo -e "${RED}ERROR${RESET}: job amount ${BOLD}${JOB_AMOUNT} specks${RESET} >= threshold ${MULTISIG_THRESHOLD_SPECKS}" >&2
-        echo -e "${YELLOW}Multisig required.${RESET} Each approver runs:" >&2
-        echo -e "  ${CYAN}gateway.sh approve-multisig${RESET} $JOB_ID <output_hash> <approver_key>" >&2
-        echo -e "Then collect M approval_blobs and run:" >&2
-        echo -e "  ${CYAN}gateway.sh complete${RESET} $JOB_ID $COMMITMENT --approvals blob1,blob2" >&2
+    # ── Payout gate: bridge /decision/approve-completion ────────────────────────
+    # Approval keys and threshold are private to the bridge; this script only
+    # forwards the job_id, output_hash, amount, and any collected approval blobs.
+    if [[ -n "$BRIDGE_URL" ]]; then
+      APPROVE_PAYLOAD=$(python3 -c "
+import sys, json
+d = {'job_id': sys.argv[1], 'output_hash': sys.argv[2], 'amount_specks': int(sys.argv[3] or 0)}
+if sys.argv[4]:
+    d['approvals'] = sys.argv[4]
+print(json.dumps(d))
+" "$JOB_ID" "$COMMITMENT" "$JOB_AMOUNT" "${APPROVALS_RAW:-}")
+
+      APPROVE_STATUS=$(curl -sf --max-time 10 -w '%{http_code}' -o /tmp/_nightpay_approve.$$ \
+        -X POST -H 'Content-Type: application/json' \
+        -d "$APPROVE_PAYLOAD" \
+        "${BRIDGE_URL}/decision/approve-completion" 2>/dev/null) || APPROVE_STATUS="000"
+      APPROVE_BODY=$(cat /tmp/_nightpay_approve.$$ 2>/dev/null); rm -f /tmp/_nightpay_approve.$$
+
+      if [[ "$APPROVE_STATUS" == "403" ]]; then
+        APPROVE_REASON=$(echo "$APPROVE_BODY" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('reason_code','unknown'))" 2>/dev/null || echo "unknown")
+        APPROVE_DID=$(echo "$APPROVE_BODY" | python3 -c "import sys,json; print(json.load(sys.stdin).get('decision_id',''))" 2>/dev/null || echo "")
+        if [[ "$APPROVE_REASON" == "multisig_required" ]]; then
+          REQ_M=$(echo "$APPROVE_BODY" | python3 -c "import sys,json; print(json.load(sys.stdin).get('required_m',2))" 2>/dev/null || echo "2")
+          REQ_N=$(echo "$APPROVE_BODY" | python3 -c "import sys,json; print(json.load(sys.stdin).get('required_n',3))" 2>/dev/null || echo "3")
+          echo -e "${RED}ERROR${RESET}: job amount ${BOLD}${JOB_AMOUNT} specks${RESET} requires multisig (${REQ_M}-of-${REQ_N})" >&2
+          echo -e "${YELLOW}Each approver runs:${RESET}" >&2
+          echo -e "  ${CYAN}gateway.sh approve-multisig${RESET} $JOB_ID <output_hash> <approver_key>" >&2
+          echo -e "Then collect M approval_blobs and run:" >&2
+          echo -e "  ${CYAN}gateway.sh complete${RESET} $JOB_ID $COMMITMENT --approvals blob1,blob2" >&2
+          echo -e "  ${DIM}(decision: ${APPROVE_DID})${RESET}" >&2
+        else
+          APPROVE_ERR=$(echo "$APPROVE_BODY" | python3 -c "import sys,json; print(json.load(sys.stdin).get('error','multisig verification failed'))" 2>/dev/null || echo "multisig verification failed")
+          echo -e "${RED}SECURITY ERROR${RESET}: completion not approved — ${APPROVE_ERR} (decision: ${APPROVE_DID})" >&2
+        fi
         exit 1
       fi
 
-      # Verify M-of-N approvals using Python stdlib only (no new deps)
-      VERIFY_OK=$(python3 -c "
-import sys, json, hmac, hashlib, time
-
-job_id        = sys.argv[1]
-output_hash   = sys.argv[2]
-approvals_raw = sys.argv[3]
-approver_keys = [k for k in sys.argv[4].split(',') if k] if sys.argv[4] else []
-required_m    = int(sys.argv[5])
-max_age_secs  = 86400   # approvals expire after 24h — prevents replay attacks
-
-# Parse: each entry is sig:ts:nonce
-approvals = []
-for entry in approvals_raw.split(','):
-    parts = entry.split(':')
-    if len(parts) != 3:
-        print(f'ERROR: malformed approval blob (expected sig:ts:nonce): {entry}', file=sys.stderr)
-        sys.exit(1)
-    try:
-        approvals.append({'sig': parts[0], 'ts': int(parts[1]), 'nonce': parts[2]})
-    except ValueError:
-        print(f'ERROR: non-integer timestamp in approval: {entry}', file=sys.stderr)
-        sys.exit(1)
-
-now         = int(time.time())
-valid_count = 0
-used_keys   = set()   # SECURITY: each key index counts once — no double-counting
-
-for approval in approvals:
-    age = now - approval['ts']
-    if age > max_age_secs:
-        print(f'WARN: approval ts={approval[\"ts\"]} is too old (age={age}s > {max_age_secs}s)', file=sys.stderr)
-        continue
-    if age < -300:  # 5-min future clock skew tolerance
-        print(f'WARN: approval ts={approval[\"ts\"]} is too far in future (age={age}s)', file=sys.stderr)
-        continue
-
-    payload = f'{job_id}:{output_hash}:{approval[\"ts\"]}:{approval[\"nonce\"]}'
-    for i, key in enumerate(approver_keys):
-        if i in used_keys:
-            continue
-        expected = hmac.new(key.encode(), payload.encode(), hashlib.sha256).hexdigest()
-        if hmac.compare_digest(expected, approval['sig']):
-            used_keys.add(i)
-            valid_count += 1
-            break
-
-if valid_count >= required_m:
-    print(f'ok:{valid_count}')
-else:
-    print(f'ERROR: only {valid_count} valid approvals, need {required_m}', file=sys.stderr)
-    sys.exit(1)
-" "$JOB_ID" "$COMMITMENT" "$APPROVALS_RAW" "$APPROVER_KEYS" "$MULTISIG_M" 2>&1) || {
-        echo -e "${RED}SECURITY ERROR${RESET}: multisig verification failed — $VERIFY_OK" >&2
-        exit 1
-      }
-      echo -e "  ${GREEN}Multisig${RESET}: $VERIFY_OK approvals verified" >&2
+      if [[ "$APPROVE_STATUS" == "200" ]]; then
+        APPROVE_DID=$(echo "$APPROVE_BODY" | python3 -c "import sys,json; print(json.load(sys.stdin).get('decision_id',''))" 2>/dev/null || echo "")
+        APPROVE_VALID=$(echo "$APPROVE_BODY" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('valid_count',''))" 2>/dev/null || echo "")
+        if [[ -n "$APPROVE_VALID" ]]; then
+          echo -e "  ${GREEN}Multisig${RESET}: ok:${APPROVE_VALID} approvals verified (decision: ${APPROVE_DID})" >&2
+        fi
+      fi
+      # On bridge error (000, 5xx) fall through — let the ZK circuit be the final gate
     fi
 
     RESULT_DATA=$(masumi_get "/purchases/$JOB_ID/result")
@@ -953,6 +905,32 @@ print(json.dumps({
       exit 1
     fi
 
+    # ── Authorization gate: bridge /decision/initiate-refund ─────────────────
+    # Requires operator Bearer token (OPERATOR_SECRET_KEY) verified by bridge.
+    if [[ -n "$BRIDGE_URL" ]]; then
+      REFUND_AUTH_PAYLOAD=$(python3 -c "import sys,json; print(json.dumps({'job_id':sys.argv[1],'commitment_hash':sys.argv[2]}))" "$JOB_ID" "$COMMITMENT")
+      REFUND_AUTH_STATUS=$(curl -sf --max-time 10 -w '%{http_code}' -o /tmp/_nightpay_refundauth.$$ \
+        -X POST \
+        -H 'Content-Type: application/json' \
+        -H "Authorization: Bearer ${OPERATOR_SECRET_KEY:-}" \
+        -d "$REFUND_AUTH_PAYLOAD" \
+        "${BRIDGE_URL}/decision/initiate-refund" 2>/dev/null) || REFUND_AUTH_STATUS="000"
+      REFUND_AUTH_BODY=$(cat /tmp/_nightpay_refundauth.$$ 2>/dev/null); rm -f /tmp/_nightpay_refundauth.$$
+
+      if [[ "$REFUND_AUTH_STATUS" == "401" || "$REFUND_AUTH_STATUS" == "403" ]]; then
+        REFUND_AUTH_ERR=$(echo "$REFUND_AUTH_BODY" | python3 -c "import sys,json; print(json.load(sys.stdin).get('error','unauthorized'))" 2>/dev/null || echo "unauthorized")
+        echo -e "${RED}SECURITY ERROR${RESET}: refund not authorized — ${REFUND_AUTH_ERR}" >&2
+        echo -e "${DIM}Ensure OPERATOR_SECRET_KEY is set and BRIDGE_ADMIN_TOKEN matches on the bridge.${RESET}" >&2
+        exit 1
+      fi
+
+      if [[ "$REFUND_AUTH_STATUS" == "200" ]]; then
+        REFUND_DID=$(echo "$REFUND_AUTH_BODY" | python3 -c "import sys,json; print(json.load(sys.stdin).get('decision_id',''))" 2>/dev/null || echo "")
+        echo -e "  ${GREEN}Refund authorized${RESET} (decision: ${REFUND_DID})" >&2
+      fi
+      # On bridge error (000, 5xx) — fall through; Masumi cancel is idempotent-safe
+    fi
+
     # Step 1: Cancel Masumi escrow on Cardano
     echo -e "${CYAN}Cancelling Masumi escrow${RESET} for job ${BOLD}$JOB_ID${RESET}..." >&2
     masumi_post "/purchases/$JOB_ID/cancel" "{}"