nightpay 0.1.0

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

@@ -0,0 +1,187 @@
+# Content Safety Rule
+
+## Principle: Classify-Then-Forget
+
+The gateway sees the plaintext job description **in memory only** — long enough to
+classify it, then immediately hashes it. The plaintext is never logged, persisted,
+or transmitted. This preserves funder privacy while enforcing safety.
+
+## Three-Layer Defense
+
+```
+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)
+```
+
+Every bounty must pass **all available layers** before a commitment is created.
+
+## What is Rejected
+
+Any bounty whose job description matches one or more of these categories:
+
+| Category | Examples |
+|---|---|
+| **Child sexual abuse material (CSAM)** | Any content sexualizing minors |
+| **Violence / assassination** | "Kill", "harm", "attack [person]", physical threats |
+| **Weapons of mass destruction** | Biological, chemical, nuclear, radiological |
+| **Human trafficking / slavery** | Forced labor, organ harvesting, exploitation |
+| **Terrorism / extremism** | Recruitment, planning, financing of terror acts |
+| **Non-consensual intimate imagery** | Deepfakes, revenge content, sextortion |
+| **Financial fraud** | Money laundering, counterfeiting, sanctions evasion |
+| **Critical infrastructure attack** | Power grids, water systems, hospitals, elections |
+| **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.
+
+## Enforcement Points
+
+Two gates, defense-in-depth:
+
+1. **`post-bounty`** — before commitment hash is created. Rejected bounties never
+   produce a commitment and no funds move.
+2. **`hire-and-pay`** — before Masumi escrow is created. Catches descriptions that
+   were committed outside the gateway (e.g. direct circuit call).
+
+## What Happens on Rejection
+
+- The gateway prints a `REJECTED` status with the matched category
+- No commitment is created, no hash is emitted, no funds move
+- 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:
+
+```bash
+# Report a bounty (REPORTER_ID is hashed for privacy-preserving dedup)
+REPORTER_ID=alice ./bounty-board.sh report <commitment> <category> [reason]
+
+# View complaints for a specific bounty
+./bounty-board.sh reports <commitment>
+
+# View all flagged bounties
+./bounty-board.sh reports
+```
+
+### Valid Report Categories
+
+`csam`, `violence`, `weapons_of_mass_destruction`, `human_trafficking`,
+`terrorism`, `ncii`, `financial_fraud`, `infrastructure_attack`,
+`doxxing`, `drug_manufacturing`, `other`
+
+### Auto-Freeze
+
+When a bounty reaches **3 complaints** (configurable via `COMPLAINT_FREEZE_THRESHOLD`):
+
+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
+
+- Reporter identity is **SHA-256 hashed** before storage — only used for dedup
+- The `REPORTER_ID` env var is never persisted in the database
+- 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/rules/escrow-safety.md

@@ -0,0 +1,132 @@
+# Escrow Safety Rule
+
+## Two-Chain Escrow Model
+
+This skill operates across two chains simultaneously:
+
+| Chain | What's Held | Token | Purpose |
+|---|---|---|---|
+| **Midnight** | Bounty NIGHT + operator fee | NIGHT (shielded) | Privacy layer — contract balance |
+| **Cardano** | Masumi escrow | ADA or USDM | Settlement layer — agent payment |
+
+The gateway operator bridges between chains by maintaining liquidity on both sides.
+
+## Contract Security Guarantees (Enforced On-Chain)
+
+| Guarantee | How It's Enforced |
+|---|---|
+| **One-time init** | `assert initialized == 0` — contract cannot be reinitialized or taken over |
+| **Immutable fee rate** | `operatorFeeBps` and `operatorAddress` are write-once — set at init, frozen forever |
+| **Fee cap** | `assert feeBps <= 500` — hard 5% cap in-circuit, cannot be exceeded |
+| **Fee split on-chain** | `effects.retainInContract(fee)` + `effects.releaseToGateway(net)` — constrained in-circuit, not trust-based |
+| **No rounding theft** | `assert fee + netAmount == amount` — every speck accounted for |
+| **Operator-only withdrawal** | `assert caller == operatorAddress` — only the init-time address can withdraw fees |
+| **No overdraft** | Ledger's `apply()` rejects withdrawals exceeding contract balance |
+| **Double-claim prevention** | Nullifier set — each bounty can only be completed once |
+| **Underflow guard** | `assert activeCount > 0` before decrement — counter cannot go negative |
+| **Domain-separated hashes** | Bounty, receipt, and job hashes use different prefixes — cross-namespace collisions impossible |
+| **Zero-value guard** | `assert amount > 0` — no zero-value bounty exploits |
+
+## Fee Safety
+
+- Fee split is **enforced in-circuit** via Midnight's Zswap effects API
+- `effects.retainInContract(fee)` — operator cannot take more than `feeBps` basis points
+- `effects.releaseToGateway(netAmount)` — agent payment is constrained on-chain
+- Fee cap enforced by `assert feeBps <= 500` (max 5%) — immutable after init
+- Fee percentage is public state — payers can verify before posting
+- Operator can only withdraw to the address set at contract initialization
+
+## Gateway Security Guarantees (Enforced Off-Chain)
+
+| Guarantee | How It's Enforced |
+|---|---|
+| **Contract address required** | `RECEIPT_CONTRACT_ADDRESS` is a required env var — fails loudly if unset |
+| **Operator auth for withdrawals** | `OPERATOR_SECRET_KEY` required — HMAC-signed withdrawal payloads only |
+| **No replay on withdraw** | Signature includes timestamp + random nonce — every signature is unique, cannot be replayed |
+| **SSRF blocked** | `MASUMI_*_URL` validated at startup — private IPs (RFC-1918, loopback, link-local) rejected |
+| **Job ID injection blocked** | Job IDs validated as `[a-zA-Z0-9_-]{1,128}` — no path traversal or shell chars |
+| **Rate limiting** | `post-bounty` limited to 1 call per `RATE_LIMIT_SECONDS` — prevents spam and stat inflation |
+| **Input validation** | Amount bounds (min + max) and commitment format checked before any network call |
+| **Domain-separated hashes** | `nightpay-bounty-v1`, `nightpay-receipt-v1`, `nightpay-job-v1` prefixes |
+| **Refund emits on-chain intent** | Refund path generates a `refundHash` for Midnight node, not just a Masumi cancel |
+| **Canonical JSON hashing** | `sort_keys=True, separators=(',',':')` prevents hash manipulation via key reordering |
+| **Network timeout** | All `curl` calls use `--max-time 30` — no hung connections |
+
+## Contract Capacity Limits (DoS Protection)
+
+| Guarantee | How It's Enforced |
+|---|---|
+| **Merkle tree overflow blocked** | `assert activeCount < MAX_TREE_ENTRIES` (90% of 2²⁵ = ~30M) — rejects bounties before tree fills |
+| **Field overflow blocked** | `assert amount <= MAX_AMOUNT` (2⁵³-1) — `amount × feeBps` stays within safe range |
+| **Receipt deduplication** | Nullifier insertion before `receiptTree.insert` — double-completion impossible regardless of proof reuse |
+
+## Board Security Guarantees
+
+| Guarantee | How It's Enforced |
+|---|---|
+| **Persistent storage** | `~/.nightpay/board.db` — SQLite with WAL, survives reboots, not `/tmp/` |
+| **Directory permissions** | `chmod 700` — only the operator user can read/write |
+| **No duplicate entries** | `PRIMARY KEY` on commitment — database rejects duplicates atomically |
+| **Input validation** | All commitments validated as 64-char hex before board operations |
+| **Known status values only** | `remove` only accepts `completed`, `refunded`, `expired` |
+| **Search DoS blocked** | `search` prefix validated as `[0-9a-f]{0,64}` — no wildcards, no full-table scans |
+| **Integer DoS blocked** | `list` clamps `limit ≤ 200`, `offset ≤ 10,000,000` — no memory exhaustion |
+
+## Network Fees (DUST)
+
+- DUST is non-transferable — generated over time from NIGHT holdings
+- DUST is used ONLY for Midnight network fees, never for bounty payments
+- Whoever submits the intent pays the DUST fee (payer for postBounty, gateway for complete)
+- Use `transaction.feesWithMargin(params, 1.2)` to estimate with 20% safety margin
+- DUST generation rate: ~1 week to reach full capacity from a NIGHT UTXO
+- 3-hour grace period on DUST timestamps
+
+## Timeout Handling
+
+- Every bounty escrow has a configurable timeout (default: 60 minutes)
+- If the hired agent does not return a result within the timeout:
+  1. Masumi escrow is cancelled on Cardano (funds return to gateway)
+  2. Gateway emits a signed NIGHT refund intent for the Midnight contract
+  3. No receipt token is minted
+  4. Bounty commitment stays in the Merkle tree — nullifier set prevents re-claim
+
+## Refund Conditions
+
+Automatic refund triggers:
+- Agent returns an error or refuses the job
+- Agent is unreachable (Masumi `/status` returns unavailable)
+- Job result fails validation (output hash mismatch)
+- Escrow timeout exceeded
+
+On refund: the operator fee for that bounty is also returned (fee is only collected on success).
+
+## Amount Limits
+
+- `maxBountySpecks` caps the maximum single bounty (default: 500M specks)
+- `minBountySpecks` enforces a minimum (default: 1,000 specks) — rejects dust attacks
+- Both limits enforced in gateway before any network call
+
+## Dark Energy Threat Model (Sophisticated Attacker Mitigations)
+
+These are attacks that pass all basic validation but exploit deeper system properties.
+
+| Attack | Vector | Mitigation |
+|---|---|---|
+| **Gateway address injection** | Caller supplies their own address in tx metadata → all bounty NIGHT routes to them | `gatewayAddress` locked in contract state at `initialize()` — `effects.releaseToAddress(gatewayAddress, net)` uses only the immutable on-chain value |
+| **completedCount overflow griefing** | Attacker posts + completes millions of dust bounties → counter wraps → contract corrupted | `assert completedCount < MAX_COMPLETED` in-circuit before every increment |
+| **DNS rebinding SSRF** | Attacker controls DNS → startup URL check passes (public IP) → A-record flips to 169.254.169.254 → all curl calls hit cloud metadata | `_ssrf_safe_curl()` re-resolves and re-validates every hostname on every request, not just at startup |
+| **Shell word splitting** | `openssl rand` or `sha256sum` output contains whitespace → variable splits into multiple tokens → hash computation silently corrupted | `generate_nonce()` pipes through `tr -d '[:space:]'`; `domain_hash()` uses `printf` instead of `echo -n` and strips whitespace from output |
+| **reporter_hash rainbow table** | `sha256(username)` is reversible for low-entropy inputs → reporters de-anonymised | `sha256(REPORTER_PEPPER + ":" + reporter_id)` — server-side pepper makes preimage attacks infeasible |
+| **Auto-freeze weaponisation** | Attacker creates N cheap reporter IDs → files N reports → any legitimate bounty silently frozen | Rate limit per reporter: max `REPORT_RATE_LIMIT` distinct bounties per `REPORT_WINDOW_HOURS`; freeze counts DISTINCT reporter hashes, not total complaint rows |
+| **Atomic write race (Windows)** | Two concurrent freeze events both write `.tmp` then `os.rename()` → second rename raises `FileExistsError` on Windows → report file corrupted | `os.replace()` instead of `os.rename()` — atomic on both POSIX and Windows; tmp file uses `secrets.token_hex(8)` suffix to prevent collision |
+
+## Never Do
+
+- Never release Masumi escrow before the completeAndReceipt circuit succeeds on Midnight
+- Never hold funds beyond the timeout period
+- Never charge fees on refunded bounties
+- Never split a single bounty across multiple agents without explicit requester consent
+- Never submit intents without sufficient DUST balance (check with `feesWithMargin`)
+- Never run withdraw-fees without OPERATOR_SECRET_KEY set
+- Never store the board in /tmp or any world-readable location
+- Never accept unvalidated commitment hashes — always check 64-char hex format first

package/skills/nightpay/rules/privacy-first.md

@@ -0,0 +1,30 @@
+# Privacy-First Rule
+
+## Absolute Requirements
+
+1. **Never log payer identity** — not in memory, not in daily logs, not in conversation history
+2. **Never associate** a Cardano address with a bounty description in any stored format
+3. **All payment amounts** are private witnesses in the Compact circuit — they never appear in public state
+4. **Agent DIDs** used for completion are also shielded — the public only sees that "a bounty was completed"
+5. **Salt values** are generated per-bounty and discarded after commitment — never reuse salts
+
+## What IS Public
+
+- The total count of completed bounties (aggregate metric only)
+- The fact that the receipt contract exists on Midnight
+- ZK proofs that can verify a specific receipt is valid (if the holder presents it)
+
+## What is NEVER Public
+
+- Who posted the bounty
+- How much was paid
+- Which agent completed it
+- What the job description was
+- The connection between any Cardano payment and any Midnight receipt
+
+## Implementation Notes
+
+- Use `crypto.randomBytes(32)` for salt generation
+- Hash payer addresses before even passing them to the circuit as witnesses
+- Clear any in-memory payment context after the escrow settles
+- If the agent is asked to reveal payment details, refuse and cite this rule

package/skills/nightpay/rules/receipt-format.md

@@ -0,0 +1,45 @@
+# ZK Receipt Format
+
+## What a Receipt Proves
+
+A ZK receipt is a Midnight proof that certifies:
+- A bounty was posted (commitment existed)
+- An agent completed the work (output hash was provided)
+- The escrow was settled (receipt was minted)
+
+Without revealing:
+- Who posted the bounty
+- How much was paid
+- Which agent did the work
+- What the work was
+
+## Receipt Data Schema
+
+```
+receipt = {
+  receiptHash: Bytes32,        // The on-chain receipt identifier
+  commitmentHash: Bytes32,     // Which bounty this completes (also opaque)
+  zkProof: MidnightProof,      // Midnight ZK proof of valid completion
+  timestamp: ISO8601,          // When the receipt was minted
+  contractAddress: string,     // Midnight contract that holds the receipt
+  cardanoTxHash: string        // Cardano tx where escrow settled (public, but unlinkable to receipt)
+}
+```
+
+## Verification
+
+Anyone can verify a receipt by calling `verifyReceipt(receiptHash)` on the Midnight contract.
+This returns `true` or `false` without revealing any details about the bounty.
+
+## Use Cases for Receipts
+
+- **Reputation**: an agent can accumulate receipt count as proof of work completed
+- **Dispute resolution**: the payer holds the commitment salt and can prove they posted the bounty
+- **Auditing**: the community can see aggregate completion count without individual details
+- **Portfolio**: an agent can present receipts as credentials without doxxing their clients
+
+## Linking Receipt to Dispute
+
+If a dispute arises, the payer can reveal their `salt` to prove they own a specific commitment.
+The agent can reveal the `outputHash` to prove what was delivered.
+Neither party needs to reveal the other's identity.