nsatoshi
ad69385beb
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 '***REDACTED-LEGACY-PW***' 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='***REDACTED-LEGACY-PW***' 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: ***REDACTED-LEGACY-PW***)' 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.
SolaceScan Explorer - Tiered Architecture
🚀 Quick Start - Complete Deployment
Execute this single command to complete all deployment steps:
cd ~/projects/proxmox/explorer-monorepo
bash EXECUTE_DEPLOYMENT.sh
What This Does
- ✅ Tests database connection
- ✅ Runs migration (if needed)
- ✅ Stops existing server
- ✅ Starts server with database
- ✅ Tests all endpoints
- ✅ 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 fromfrontend/withnpm run buildand 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 usingdeployment/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.shand./scripts/deploy.shnow fail fast with a deprecation message and point to the canonical Next.js deploy path. - Frontend review & tasks: frontend/FRONTEND_REVIEW.md, frontend/FRONTEND_TASKS_AND_REVIEW.md
Documentation
docs/README.md— Documentation overview and indexdocs/EXPLORER_API_ACCESS.md— API access, 502 fix, CSP, frontend deploySTART_HERE.md— Quick start with all commandsCOMPLETE_DEPLOYMENT.md— Detailed deployment stepsDEPLOYMENT_COMPLETE_FINAL.md— Final status reportREADME_DEPLOYMENT.md— Deployment quick referencedeployment/DEPLOYMENT_GUIDE.md— Full LXC/Nginx/Cloudflare deployment guidedocs/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 for the rotation checklist and 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:
git clone --recurse-submodules <repo-url>
# or after clone:
git submodule update --init --recursive
See docs/REUSABLE_COMPONENTS_EXTRACTION_PLAN.md for the full plan.
Testing
- All unit/lint:
make test— backendgo test ./...and frontendnpm 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 buildornpm test— Next.js build (includes lint) or lint + type-check only. - E2E:
make test-e2eornpm run e2efrom repo root — Playwright tests against https://blockscout.defi-oracle.io by default; useEXPLORER_URL=http://localhost:3000for 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!