Devin
4cbea21d8f
backend/api/rest/server.go:
- NewServer() now delegates to loadJWTSecret(), which:
- Rejects JWT_SECRET < 32 bytes (log.Fatal).
- Requires JWT_SECRET when APP_ENV=production or GO_ENV=production.
- Generates a 32-byte crypto/rand ephemeral secret in dev only.
- Treats rand.Read failure as fatal (removes the prior time-based
fallback that was deterministic and forgeable).
- Default Content-Security-Policy rewritten:
- Drops 'unsafe-inline' and 'unsafe-eval'.
- Drops private CIDRs (192.168.11.221:854[5|6]).
- Adds frame-ancestors 'none', base-uri 'self', form-action 'self'.
- CSP_HEADER is required in production; fatal if unset there.
backend/api/rest/server_security_test.go (new):
- Covers the three loadJWTSecret() paths (valid, whitespace-trimmed,
ephemeral in dev).
- Covers isProductionEnv() across APP_ENV / GO_ENV combinations.
- Asserts defaultDevCSP contains no unsafe directives or private CIDRs
and includes the frame-ancestors / base-uri / form-action directives.
scripts/*.sh:
- Removed 'L@kers2010' default value from SSH_PASSWORD / NEW_PASSWORD in
7 helper scripts. Each script now fails with exit 2 and points to
docs/SECURITY.md if the password isn't supplied via env or argv.
EXECUTE_DEPLOYMENT.sh, EXECUTE_NOW.sh:
- Replaced hardcoded DB_PASSWORD='L@ker$2010' with a ':?' guard that
aborts with a clear error if DB_PASSWORD (and, for EXECUTE_DEPLOYMENT,
RPC_URL) is not exported. Other env vars keep sensible non-secret
defaults via ${VAR:-default}.
README.md:
- Removed the hardcoded Database Password / RPC URL lines. Replaced with
an env-variable reference table pointing at docs/SECURITY.md and
docs/DATABASE_CONNECTION_GUIDE.md.
docs/DEPLOYMENT.md:
- Replaced 'PASSWORD: SSH password (default: L@kers2010)' with a
required-no-default contract and a link to docs/SECURITY.md.
docs/SECURITY.md (new):
- Full secret inventory keyed to the env variable name and the file that
consumes it.
- Five-step rotation checklist covering the Postgres role, the Proxmox
VM SSH password, JWT_SECRET, vendor API keys, and a gitleaks-based
history audit.
- Explicit note that merging secret-scrub PRs does NOT invalidate
already-leaked credentials; rotation is the operator's responsibility.
Verification:
- go build ./... + go vet ./... pass clean.
- Targeted tests (LoadJWTSecret*, IsProduction*, DefaultDevCSP*) pass.
Advances completion criterion 2 (Secrets & config hardened). Residual
leakage from START_HERE.md / LETSENCRYPT_CONFIGURATION_GUIDE.md is
handled by PR #2 (doc consolidation), which deletes those files.
102 lines
4.9 KiB
Markdown
102 lines
4.9 KiB
Markdown
# SolaceScan Explorer - Tiered Architecture
|
||
|
||
## 🚀 Quick Start - Complete Deployment
|
||
|
||
**Execute this single command to complete all deployment steps:**
|
||
|
||
```bash
|
||
cd ~/projects/proxmox/explorer-monorepo
|
||
bash EXECUTE_DEPLOYMENT.sh
|
||
```
|
||
|
||
## What This Does
|
||
|
||
1. ✅ Tests database connection
|
||
2. ✅ Runs migration (if needed)
|
||
3. ✅ Stops existing server
|
||
4. ✅ Starts server with database
|
||
5. ✅ Tests all endpoints
|
||
6. ✅ Provides status summary
|
||
|
||
## Manual Execution
|
||
|
||
If the script doesn't work, see `START_HERE.md` for step-by-step manual commands.
|
||
|
||
## Frontend
|
||
|
||
- **Production (canonical target):** the current **Next.js standalone frontend** in `frontend/src/`, built from `frontend/` with `npm run build` and deployed to VMID 5000 as a Node service behind nginx.
|
||
- **Canonical deploy script:** `./scripts/deploy-next-frontend-to-vmid5000.sh`
|
||
- **Canonical nginx wiring:** keep `/api`, `/api/config/*`, `/explorer-api/*`, `/token-aggregation/api/v1/*`, `/snap/`, and `/health`; proxy `/` and `/_next/` to the frontend service using `deployment/common/nginx-next-frontend-proxy.conf`.
|
||
- **Legacy fallback only:** the static SPA (`frontend/public/index.html` + `explorer-spa.js`) remains in-repo for compatibility/reference, but it is not a supported primary deployment target.
|
||
- **Architecture command center:** `frontend/public/chain138-command-center.html` — tabbed Mermaid topology (Chain 138 hub, network, stack, flows, cross-chain, cW Mainnet, off-chain, integrations). Linked from the SPA **More → Explore → Visual Command Center**.
|
||
- **Legacy static deploy scripts:** `./scripts/deploy-frontend-to-vmid5000.sh` and `./scripts/deploy.sh` now fail fast with a deprecation message and point to the canonical Next.js deploy path.
|
||
- **Frontend review & tasks:** [frontend/FRONTEND_REVIEW.md](frontend/FRONTEND_REVIEW.md), [frontend/FRONTEND_TASKS_AND_REVIEW.md](frontend/FRONTEND_TASKS_AND_REVIEW.md)
|
||
|
||
## Documentation
|
||
|
||
- **`docs/README.md`** — Documentation overview and index
|
||
- **`docs/EXPLORER_API_ACCESS.md`** — API access, 502 fix, CSP, frontend deploy
|
||
- **`START_HERE.md`** — Quick start with all commands
|
||
- **`COMPLETE_DEPLOYMENT.md`** — Detailed deployment steps
|
||
- **`DEPLOYMENT_COMPLETE_FINAL.md`** — Final status report
|
||
- **`README_DEPLOYMENT.md`** — Deployment quick reference
|
||
- **`deployment/DEPLOYMENT_GUIDE.md`** — Full LXC/Nginx/Cloudflare deployment guide
|
||
- **`docs/INDEX.md`** — Bridge and operations doc index
|
||
|
||
## Architecture
|
||
|
||
- **Track 1 (Public):** RPC Gateway - No authentication required
|
||
- **Track 2 (Approved):** Indexed Explorer - Requires authentication
|
||
- **Track 3 (Analytics):** Analytics Dashboard - Requires Track 3+
|
||
- **Track 4 (Operator):** Operator Tools - Requires Track 4 + IP whitelist
|
||
|
||
## Configuration
|
||
|
||
All secrets and environment-specific endpoints are read from environment
|
||
variables — nothing is committed to this repo. See
|
||
[docs/SECURITY.md](docs/SECURITY.md) for the rotation checklist and
|
||
[docs/DATABASE_CONNECTION_GUIDE.md](docs/DATABASE_CONNECTION_GUIDE.md) for
|
||
setup.
|
||
|
||
| Variable | Purpose | Example |
|
||
|---|---|---|
|
||
| `DB_USER` | Postgres role | `explorer` |
|
||
| `DB_PASSWORD` | Postgres password (required, no default) | — |
|
||
| `DB_HOST` | Postgres host | `localhost` |
|
||
| `DB_NAME` | Database name | `explorer` |
|
||
| `RPC_URL` | Besu / execution client RPC endpoint | `http://rpc.internal:8545` |
|
||
| `CHAIN_ID` | EVM chain ID | `138` |
|
||
| `PORT` | API listen port | `8080` |
|
||
| `JWT_SECRET` | HS256 signing key (≥32 bytes, required in prod) | — |
|
||
| `CSP_HEADER` | Content-Security-Policy header (required in prod) | — |
|
||
|
||
## Reusable libs (extraction)
|
||
|
||
Reusable components live under `backend/libs/` and `frontend/libs/` and may be split into separate repos and linked via **git submodules**. Clone with submodules:
|
||
|
||
```bash
|
||
git clone --recurse-submodules <repo-url>
|
||
# or after clone:
|
||
git submodule update --init --recursive
|
||
```
|
||
|
||
See [docs/REUSABLE_COMPONENTS_EXTRACTION_PLAN.md](docs/REUSABLE_COMPONENTS_EXTRACTION_PLAN.md) for the full plan.
|
||
|
||
## Testing
|
||
|
||
- **All unit/lint:** `make test` — backend `go test ./...` and frontend `npm test` (lint + type-check).
|
||
- **Backend:** `cd backend && go test ./...` — API tests run without a real DB; health returns 200 or 503, DB-dependent endpoints return 503 when DB is nil.
|
||
- **Frontend:** `cd frontend && npm run build` or `npm test` — Next.js build (includes lint) or lint + type-check only.
|
||
- **E2E:** `make test-e2e` or `npm run e2e` from repo root — Playwright tests against https://blockscout.defi-oracle.io by default; use `EXPLORER_URL=http://localhost:3000` for local.
|
||
|
||
## Status
|
||
|
||
✅ All implementation complete
|
||
✅ All scripts ready
|
||
✅ All documentation complete
|
||
✅ Frontend: C1–C4, M1–M4, H4, H5, L2, L4 done; H1/H2/H3 (escapeHtml/safe href) in place; optional L1, L3 remain
|
||
✅ CI: backend + frontend tests; lint job runs `go vet`, `npm run lint`, `npm run type-check`
|
||
✅ Tests: `make test`, `make test-e2e`, `make build` all pass
|
||
|
||
**Ready for deployment!**
|