fix: secure Honcho wizard with a Dappnode-configured password

README.md

@@ -17,10 +17,31 @@ All workers share the single LLM provider you configure in the Setup Wizard.
 
 ## Getting started
 
-1. Install the Honcho package from the Dappnode admin UI
-2. Open the **Setup Wizard** at `http://setup-wizard.honcho.dappnode:8080`
-3. Pick your AI provider and enter your API key and model
-4. Restart the Honcho package to apply the configuration
+1. Install Honcho from the Dappnode admin UI and choose a **Honcho wizard password** in the installation form. Use a password manager to generate and save a strong password of 12–128 printable ASCII characters.
+2. If upgrading an existing installation, set `HONCHO_WIZARD_PASSWORD` for **setup-wizard** in Honcho's **Config** tab, then restart that service.
+3. Open the **Setup Wizard** at `http://setup-wizard.honcho.dappnode:8080` over your Dappnode VPN and unlock it with that password.
+4. Pick your AI provider and enter your API key and model.
+5. Restart the Honcho package to apply the provider configuration.
+
+## Setup Wizard access and migration
+
+The Dappnode installation form requires a separate wizard password. It is supplied as `HONCHO_WIZARD_PASSWORD` **only to the setup-wizard service**, and is never written into the shared provider `.env` or returned by a configuration read. The wizard fails startup with an actionable Config message if the password is missing or invalid. There is no default password or unauthenticated first-visitor registration.
+
+Unlocking exchanges the password for a random, server-side session lasting at most eight hours. The browser keeps only that session token in tab memory; locking or reloading requires unlocking again. Locking requests server-side revocation of the current session. All sessions are invalidated when the wizard restarts. Passwords and sessions are never printed in service logs, placed in URLs or persisted by the UI in cookies, localStorage or sessionStorage; your browser's password manager can save the password normally.
+
+Login attempts are limited to ten per minute across this wizard, including successful attempts. Established sessions remain usable during a login cooldown. Up to 32 sessions are retained; creating another revokes the oldest. All authenticated API routes reject expired or revoked sessions.
+
+To change or recover the wizard password, update `HONCHO_WIZARD_PASSWORD` in the package's **Config** tab and restart **setup-wizard**. You do not need SSH. Existing provider configuration remains unchanged. If upgrading from the earlier token-based development build, its old token is no longer accepted and its auth volume is no longer mounted or used. No credential files or provider data are automatically deleted.
+
+Dappnode manages the password as a service environment setting, visible to trusted host administrators through package configuration and Docker inspection. It is not encrypted in a separate wizard credential vault. Save it in your password manager and set it again when restoring onto another installation; the provider-configuration backup does not include it. API and deriver services do not receive this setting.
+
+The wizard no longer publishes host port 8080. Its existing Dappnode DNS address and container port remain available through Dappnode's private network. Authentication does not encrypt HTTP: use the trusted Dappnode VPN, or configure a trusted HTTPS reverse proxy. Do not expose the raw wizard over the internet or an untrusted LAN.
+
+The default accepted origin/host is `http://setup-wizard.honcho.dappnode:8080`. An administrator using a different HTTPS address must set `HONCHO_WIZARD_ORIGINS` to the exact origin (or comma-separated exact origins) and configure the proxy to preserve that `Host`. Wildcards, arbitrary forwarded headers and cross-site browser requests are not trusted. There is no wildcard CORS access.
+
+Existing `.env` configuration and provider keys are retained on upgrade. Saved keys are never returned to the browser, even after unlocking. Blank or fully masked secret fields keep existing keys; enter a replacement or explicitly select **Clear all saved provider keys** to erase them. Changing an endpoint while keys are saved requires an explicit replacement or clearing decision, to avoid sending an old provider's key to a new destination. Legacy URLs containing embedded credentials, queries or invalid syntax are withheld from the browser and listed by field name in `invalidPublicFields`; replace them with a clean URL and put the key in its dedicated field.
+
+This protects the **Setup Wizard**, not the separate Honcho memory API. The API still listens on port 8000 with authentication disabled by the upstream package entrypoint; it requires a separate access-control review. Keep that endpoint on a trusted network as well.
 
 ## Endpoint
 
@@ -74,3 +95,13 @@ Point the Hermes Dappnode package at `http://honcho.dappnode:8000`. The Honcho s
 - **Honcho**: [plastic-labs/honcho](https://github.com/plastic-labs/honcho) (AGPL-3.0)
 - **Docs**: [docs.honcho.dev](https://docs.honcho.dev)
 - **Evals**: [evals.honcho.dev](https://evals.honcho.dev)
+
+## Wizard regression tests
+
+```sh
+cd setup-wizard
+npm ci --ignore-scripts
+npm test
+```
+
+Tests use synthetic keys, temporary directories, loopback HTTP and stubbed provider responses. They cover password login, session expiry/revocation, login rate limits, redaction, explicit secret updates, origin/host checks, request limits, shell/TOML input safety, and the browser DOM unlock/edit/clear flows. No production provider or database is used. Test dependencies are not installed in the runtime image.

dappnode_package.json

@@ -29,7 +29,7 @@
   ],
   "changelog": "Initial release. Packages Honcho v3 using honcho-self-hosted config overlay with Dappnode Setup Wizard UI.",
   "warnings": {
-    "onInstall": "Complete the Setup Wizard to select your AI provider. If you choose Local Ollama, the Ollama Dappnode package must already be installed with at least one tool-calling model downloaded (e.g. qwen3:8b).",
+    "onInstall": "Choose a Honcho wizard password in the Dappnode installation form, then use it to unlock the Setup Wizard. On upgrade, set HONCHO_WIZARD_PASSWORD for setup-wizard in the package Config and restart that service. If you choose Local Ollama, install the Ollama Dappnode package and download a tool-calling model first (e.g. qwen3:8b).",
     "onReset": "Resetting this package stops all services but does NOT delete your memory database. To erase all stored memories, remove the honcho-db-data volume from the Dappnode volume manager.",
     "onRemove": "Removing this package will stop all Honcho services. Your memory database volume will be preserved unless you explicitly remove it."
   },
@@ -47,6 +47,6 @@
   },
   "categories": ["Developer tools"],
   "keywords": ["AI", "memory", "agent", "LLM", "Hermes", "Honcho"],
-  "author": Chuy García <chuy@dappnode.io> (https://github.com/dappnode)",
+  "author": "Chuy García <chuy@dappnode.io> (https://github.com/dappnode)",
   "license": "GPL-3.0"
 }

docker-compose.yml

@@ -46,8 +46,7 @@ services:
     restart: unless-stopped
     environment:
       HONCHO_CONFIG_DIR: "/config"
-    ports:
-      - "8080:8080"
+      HONCHO_WIZARD_PASSWORD: ""
     volumes:
       - honcho-config:/config
 

setup-wizard.yml

@@ -1,16 +1,18 @@
 version: "2"
 fields:
-  - id: setupNotice
+  - id: wizardPassword
     target:
       type: environment
-      name: _SETUP_NOTICE
-      service: api
-    title: Setup Instructions
+      name: HONCHO_WIZARD_PASSWORD
+      service: setup-wizard
+    title: Honcho wizard password
     description: >-
-      After installation, open the **Setup Wizard UI** at
-      http://setup-wizard.honcho.dappnode:8080 to configure your
-      AI provider, API key, and model. The Setup Wizard will write
-      all necessary environment variables for Honcho.
-    enum:
-      - "I understand"
+      Choose a separate password for the Honcho Setup Wizard. After installation,
+      open http://setup-wizard.honcho.dappnode:8080 and unlock it with this password
+      to configure your AI provider, API key, and model. You can change this
+      password later in Honcho's Config tab; restart the setup-wizard service
+      afterward. Use a password manager to generate and save a strong password.
+    secret: true
     required: true
+    pattern: '^[\x20-\x7E]{12,128}(?![\s\S])'
+    patternErrorMessage: "Use 12 to 128 printable ASCII characters."

setup-wizard/.dockerignore

@@ -0,0 +1,3 @@
+node_modules
+*.test.cjs
+package*.json

setup-wizard/.gitignore

@@ -0,0 +1 @@
+node_modules/

setup-wizard/Dockerfile

@@ -1,4 +1,8 @@
-FROM node:20-alpine
+FROM node:22.23.4-alpine3.23
+
+RUN apk add --no-cache --upgrade \
+    'ca-certificates>=20261020' \
+    'ca-certificates-bundle>=20261020'
 
 WORKDIR /app