feat(faucet): built-in Faucet UI served by faucet service (MetaMask + token + rate limits)

[BioMark3r]

Motivation

• Provide a simple browser UI served directly by the existing faucet so developers can request funds without a separate app while keeping server-side protections intact.
• Preserve and expose existing API endpoints (/health, POST /faucet, GET /status/:txHash) and rate-limiting/token requirements for safety.

Description

• Serve a static UI from the faucet server by mounting tools/faucet/public and adding GET /ui (changes in tools/faucet/server.js).
• Add UI assets: tools/faucet/public/index.html, tools/faucet/public/app.js, and tools/faucet/public/styles.css implementing MetaMask connect (auto-fill), token storage in localStorage (qik_faucet_token), health polling, faucet requests with X-FAUCET-TOKEN, tx-status polling, and simple copy buttons.
• Normalize and improve server responses for UI consumption: user-friendly 401 payload for missing/invalid token, consistent 429 rate-limit payload (error: "rate_limited", message, retryAfterSec), clearer /health and /status/:txHash error shapes, and validation messages (changes in tools/faucet/server.js).
• Keep/enforce rate limits server-side: per-IP (1/min) and per-destination (1/5min) windows with proper retry response formatting.
• Improve startup diagnostics and logs to print listen URL, faucet signer address, chainId, and signer balance, failing fast if RPC is unreachable (changes in tools/faucet/server.js).
• Makefile UX updates: make faucet-up now prints the UI and health URLs and a new make faucet-ui target prints localhost + best-effort LAN URLs (changes in Makefile).
• README updates: Add UI usage instructions, token requirement, MetaMask behavior, and the existing prefunding reminder (changes in README.md).

Testing

• Static checks: node --check tools/faucet/server.js and node --check tools/faucet/public/app.js succeeded.
• make faucet-ui executed and printed the expected local and LAN URLs (success).
• Functional smoke tests against a local mocked JSON-RPC backend were run by starting a mock RPC + faucet instance and exercising endpoints with curl; results:
  • GET / and GET /ui returned the UI HTML (success).
  • GET /health returned 200 with { ok: true, chainId, latestBlock } (success).
  • POST /faucet without X-FAUCET-TOKEN returned 401 with the JSON { error: "unauthorized", message: "Missing or invalid X-FAUCET-TOKEN" } (success).
  • POST /faucet with token exercised tx submission and error paths from the mocked RPC and returned appropriate txHash or 500/tx_failed messages depending on the RPC behavior (observed behavior validated).
  • Rate-limit behavior was exercised and produced 429 responses with retryAfterSec (success).
• Attempted a Playwright screenshot of the UI, but the Chromium browser process crashed in this environment (SIGSEGV), so automated browser screenshot capture failed (environmental issue, not a code regression).

---

Codex Task