Files

Devin 4cbea21d8f fix(security): fail-fast on missing JWT_SECRET, harden CSP, strip hardcoded passwords

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.

2026-04-18 19:02:27 +00:00

4.9 KiB

Raw Blame History

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 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_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 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 — 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!

4.9 KiB Raw Blame History Unescape Escape