fix: regenerate lavamoat policy from production dependencies

The lavamoat policy was generated against dev node_modules, but both
Docker and the recommended production setup use production-only
dependencies. This caused runtime policy violations because:

1. Shared transitive packages resolve through different parent chains
   in dev vs production node_modules.
2. config.js is loaded dynamically via a computed require() in
   settings.js, so lavamoat never discovers yargs and its deps.

Regenerated the policy from production dependencies using a shim that
statically requires config.js so lavamoat discovers the full dependency
graph. Added README instructions for running from source with
production deps to match the policy.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: andreabadesso

.github/workflows/docker-smoke-test.yml

@@ -0,0 +1,56 @@
+name: docker-smoke-test
+on:
+  push:
+    branches:
+      - master
+      - release-candidate
+      - release
+  pull_request:
+    branches:
+      - master
+      - release-candidate
+      - release
+jobs:
+  smoke-test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout
+        # https://github.com/actions/checkout/releases/tag/v4.1.7
+        uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332
+
+      - name: Build Docker image
+        run: docker build -t hathor-wallet-headless .
+
+      - name: Start container
+        run: |
+          docker run -d --name headless-test \
+            -p 8000:8000 \
+            -e HEADLESS_NETWORK=testnet \
+            -e HEADLESS_SERVER=https://node1.testnet.hathor.network/v1a/ \
+            -e HEADLESS_SEED_DEFAULT="abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about" \
+            -e HEADLESS_API_KEY=ci_test_key \
+            hathor-wallet-headless
+
+      - name: Wait for service to be ready
+        run: |
+          for i in $(seq 1 30); do
+            if curl -sf -H "X-API-KEY: ci_test_key" http://localhost:8000/wallet/status > /dev/null 2>&1; then
+              echo "Service is ready"
+              exit 0
+            fi
+            sleep 1
+          done
+          echo "Service failed to start"
+          docker logs headless-test
+          exit 1
+
+      - name: Verify API responds
+        run: |
+          RESPONSE=$(curl -s -H "X-API-KEY: ci_test_key" http://localhost:8000/wallet/status)
+          echo "Response: $RESPONSE"
+          echo "$RESPONSE" | grep -q "X-Wallet-Id"
+
+      - name: Stop container
+        if: always()
+        run: docker stop headless-test || true

Makefile

@@ -89,3 +89,8 @@ xpub_from_seed: .script-build-dirs .run_xpub_from_seed .script-clean-dirs
 # Command: Derive multisig xPub from seed
 .PHONY: multisig_xpub_from_seed
 multisig_xpub_from_seed: .script-build-dirs .run_multisig_xpub_from_seed .script-clean-dirs
+
+# Command: Regenerate LavaMoat policy from production dependencies
+.PHONY: lavamoat_policy
+lavamoat_policy:
+	bash scripts/generate-lavamoat-policy.sh

README.md

@@ -12,6 +12,78 @@ A **headless wallet** is a wallet application whose interface is an API.
 
 To know how to operate and use Hathor headless wallet, see [Hathor headless wallet at Hathor docs — official technical documentation of Hathor](https://docs.hathor.network/pathways/components/headless-wallet).
 
+### Running with Docker
+
+The easiest way to run the headless wallet is with Docker. Pre-built images are available on [Docker Hub](https://hub.docker.com/r/hathornetwork/hathor-wallet-headless):
+
+```bash
+docker run -p 8000:8000 --env-file .env.headless hathornetwork/hathor-wallet-headless
+```
+
+Where `.env.headless` contains your configuration (do not commit this file):
+
+```
+HEADLESS_NETWORK=mainnet
+HEADLESS_SERVER=https://node1.mainnet.hathor.network/v1a/
+HEADLESS_SEED_DEFAULT=your seed words here
+HEADLESS_API_KEY=your_api_key
+```
+
+### Running from source
+
+Requirements: Node.js >= 22.0.0, npm >= 10.0.0.
+
+```bash
+# Install all dependencies (needed for the build step)
+npm ci
+
+# Copy and edit the configuration file
+cp config.js.template config.js
+# Edit config.js with your settings (seed, network, server, etc.)
+
+# Build the project
+npm run build
+
+# Remove dev dependencies so the runtime matches the LavaMoat policy
+rm -rf node_modules
+npm ci --only=production
+
+# Run
+npm run start:lavamoat
+```
+
+> **Note:** The [LavaMoat](https://github.com/LavaMoat/LavaMoat) security policy is generated against production dependencies. Dev dependencies change the dependency resolution paths, causing policy violations at runtime. That's why dev dependencies must be removed after building.
+
+### Development
+
+For local development without LavaMoat:
+
+```bash
+npm ci
+cp config.js.template config.js
+# Edit config.js with your settings
+
+# Run without LavaMoat (uses nodemon for auto-reload)
+npm run dev
+
+# Or build and run without LavaMoat
+npm run start
+```
+
+To test with LavaMoat locally, follow the [Running from source](#running-from-source) steps above.
+
+### Regenerating the LavaMoat policy
+
+When dependencies change, the LavaMoat policy must be regenerated. **Do not use `npm run lavamoat:policy`** — it generates the policy against dev dependencies, which won't work at runtime.
+
+Instead, use the provided script that generates the policy against production dependencies inside Docker:
+
+```bash
+make lavamoat_policy
+```
+
+This requires Docker to be running. The script builds the project with the Docker config, spins up a container with production-only `node_modules`, and runs `lavamoat --autopolicy` inside it.
+
 ## Support
 
 If after consulting the documentation, you still need **help to operate and use Hathor headless wallet**, [send a message to the `#development` channel on Hathor Discord server for assistance from Hathor team and community members](https://discord.com/channels/566500848570466316/663785995082268713).