feat: add demo mode and ALTCHA integration for better security for internet deployments and showcase functionality

Author: Ivan

docker-compose.demo.yml

@@ -0,0 +1,63 @@
+# Coolify public demo stack (read-only mesh showcase, ALTCHA, session auth).
+# https://coolify.io/docs/knowledge-base/docker/compose
+#
+# Set MESHCHAT_ALTCHA_HMAC_KEY in Coolify before deploy (required below).
+# Showcase login password defaults to demo (override MESHCHAT_DEMO_AUTH_PASSWORD).
+#
+# Assign a domain in Coolify with container port 8000, for example:
+#   https://meshchatx.example.com:8000
+# The :8000 suffix is the container port for the proxy, not the public URL port.
+#
+# Coolify terminates TLS at the proxy. Plain HTTP inside the container
+# (MESHCHAT_NO_HTTPS=1) avoids a self-signed HTTPS backend. Do not add host
+# ports unless you intend to bypass the proxy.
+
+services:
+    meshchatx:
+        image: ${MESHCHAT_IMAGE:-quad4io/meshchatx:latest}
+        restart: unless-stopped
+        init: true
+        user: "1000:1000"
+        security_opt:
+            - no-new-privileges:true
+        cap_drop:
+            - ALL
+        read_only: true
+        tmpfs:
+            - /tmp:noexec,nosuid,size=256m
+            - /home/meshchat:nosuid,size=64m
+        environment:
+            - SERVICE_URL_MESHCHATX_8000
+            - MESHCHAT_DEMO_MODE=${MESHCHAT_DEMO_MODE:-1}
+            - MESHCHAT_AUTH=${MESHCHAT_AUTH:-1}
+            - MESHCHAT_AUTH_BYPASS=${MESHCHAT_AUTH_BYPASS:-0}
+            - MESHCHAT_ALTCHA_ENABLED=${MESHCHAT_ALTCHA_ENABLED:-1}
+            - MESHCHAT_ALTCHA_HMAC_KEY=${MESHCHAT_ALTCHA_HMAC_KEY:?}
+            - MESHCHAT_DEMO_AUTH_PASSWORD=${MESHCHAT_DEMO_AUTH_PASSWORD:-demo}
+            - "MESHCHAT_AUTH_PAGE_HINT=${MESHCHAT_AUTH_PAGE_HINT:-Username: demo, Password: demo}"
+            - MESHCHAT_DISABLE_PLUGINS=${MESHCHAT_DISABLE_PLUGINS:-1}
+            - MESHCHAT_HOST=${MESHCHAT_HOST:-0.0.0.0}
+            - MESHCHAT_PORT=${MESHCHAT_PORT:-8000}
+            - MESHCHAT_NO_HTTPS=${MESHCHAT_NO_HTTPS:-1}
+            - MESHCHAT_HEADLESS=${MESHCHAT_HEADLESS:-1}
+        volumes:
+            - meshchatx-config:/config
+        healthcheck:
+            test:
+                [
+                    "CMD",
+                    "python",
+                    "-c",
+                    "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/api/v1/status')",
+                ]
+            interval: 30s
+            timeout: 5s
+            retries: 3
+            start_period: 90s
+        cpus: 2.0
+        mem_limit: 1g
+        mem_reservation: 256m
+        pids_limit: 512
+
+volumes:
+    meshchatx-config:

docs/en/identity-and-security.md

@@ -36,6 +36,16 @@ Access attempts are logged. Repeated failures can trigger lockout when auth is e
 
 Reset a forgotten password with `--reset-password` or `MESHCHAT_RESET_PASSWORD=true`, then set a new password in the UI.
 
+### Demo mode and ALTCHA
+
+`MESHCHAT_DEMO_MODE=1` (or `--demo`) enables a public showcase profile: privacy mode on, plugins off, no outbound announces, and a default-deny HTTP mutation policy with mesh send blocked. Status reports `demo_mode: true`.
+
+When `MESHCHAT_ALTCHA_ENABLED=1`, login and setup require a valid [ALTCHA](https://altcha.org/docs/v2/widget-v3/) proof-of-work payload (widget v3, server challenges use `PBKDF2/SHA-256` by default). Set `MESHCHAT_ALTCHA_HMAC_KEY` to a long random secret on the server. Optional `MESHCHAT_ALTCHA_COST` tunes PoW difficulty. The widget loads from the bundled `altcha` npm package and fetches challenges from `/api/v1/auth/altcha/challenge`.
+
+`MESHCHAT_AUTH_PAGE_HINT` sets optional plain text on the login page (independent of demo mode). Demo Docker compose defaults to username and password hints for the showcase account.
+
+`MESHCHAT_AUTH_BYPASS=1` skips session auth for local testing only. Do not use it on internet-facing deployments.
+
 ## Transport security
 
 - HTTPS and WSS are on by default.

docs/en/installation.md

@@ -61,6 +61,17 @@ Default Compose maps `127.0.0.1:8000` on the host to port `8000` in the containe
 
 To bind a host directory instead, mount it at `/config`. The container runs as UID 1000. The host directory must be writable by that user.
 
+### Public demo instance (Coolify)
+
+For a read-only mesh showcase on [Coolify](https://coolify.io/docs/knowledge-base/docker/compose), deploy [`docker-compose.demo.yml`](../../docker-compose.demo.yml). For a normal (non-demo) Coolify deployment, use [`docker-compose.coolify.yml`](../../docker-compose.coolify.yml).
+
+- `MESHCHAT_DEMO_MODE=1` blocks outbound mesh actions and almost all API mutations.
+- `MESHCHAT_AUTH=1` with default showcase password `demo` (`MESHCHAT_DEMO_AUTH_PASSWORD`).
+- Optional `MESHCHAT_AUTH_PAGE_HINT` shows custom text on the login page (for example `Username: demo` and `Password: demo`). Demo compose sets a default hint.
+- `MESHCHAT_ALTCHA_ENABLED=1` and a strong `MESHCHAT_ALTCHA_HMAC_KEY` (required in demo compose via `:?`). The UI uses ALTCHA widget v3 with `PBKDF2/SHA-256` challenges from `/api/v1/auth/altcha/challenge`.
+- Assign a domain with container port **8000**, for example `https://meshchatx.example.com:8000`.
+- Do not set `MESHCHAT_AUTH_BYPASS=1` on a public host.
+
 ## Python wheel
 
 1. Download `reticulum_meshchatx-*-py3-none-any.whl` from [releases](https://github.com/Quad4-Software/MeshChatX/releases).

meshchatx.rsm

@@ -81,6 +81,12 @@
     rotate_session_csrf_token,
     validate_csrf_header,
 )
+from meshchatx.src.backend.altcha_auth import altcha_enabled_from_env
+from meshchatx.src.backend.auth_page_hint import auth_page_hint_from_env
+from meshchatx.src.backend.demo_mode import (
+    auth_bypass_from_env,
+    demo_auth_password_from_env,
+)
 from meshchatx.src.backend.database.access_attempts import (
     LOGIN_PATH,
     MAX_FAILED_BEFORE_LOCKOUT,
@@ -560,9 +566,14 @@ def __init__(
         plugins_enabled: bool = True,
         defer_network_setup: bool = False,
         headless: bool = False,
+        demo_mode: bool = False,
+        altcha_enabled: bool = False,
     ):
         self.running = True
         self.plugins_enabled = plugins_enabled
+        self.demo_mode = bool(demo_mode)
+        self.altcha_enabled = bool(altcha_enabled)
+        self.auth_page_hint = auth_page_hint_from_env()
         self._memory_diag_enabled = memory_diag_enabled
         self._mem_diag = None
         self._headless = bool(headless)
@@ -1034,6 +1045,8 @@ def local_lxmf_destination(self, value):
 
     @property
     def auth_enabled(self):
+        if auth_bypass_from_env():
+            return False
         if self.config:
             return self.config.auth_enabled.get()
         return self.auth_enabled_initial
@@ -1682,6 +1695,11 @@ def telemetry_job():
             self._sideband_telemetry_running = False
 
     def _startup_status_payload(self) -> dict:
+        demo_fields = {
+            "demo_mode": self.demo_mode,
+            "altcha_enabled": self.altcha_enabled,
+            "auth_page_hint": self.auth_page_hint,
+        }
         if self._startup_stage == "failed" or self._startup_error:
             payload = {
                 "status": "failed",
@@ -1694,6 +1712,7 @@ def _startup_status_payload(self) -> dict:
                 "https_enabled": self.use_https,
                 "is_loopback_bind": _is_loopback_bind_host(self.listen_host),
                 "plugins_enabled": self.plugins_enabled,
+                **demo_fields,
                 **self._landlock_status_dict(),
             }
             if self._startup_error:
@@ -1716,6 +1735,7 @@ def _startup_status_payload(self) -> dict:
             "https_enabled": self.use_https,
             "is_loopback_bind": _is_loopback_bind_host(self.listen_host),
             "plugins_enabled": self.plugins_enabled,
+            **demo_fields,
             **self._landlock_status_dict(),
         }
 
@@ -1831,6 +1851,7 @@ def setup_identity(self, identity: RNS.Identity):
                 )
                 if self._network_ready:
                     self._finish_deferred_startup_services()
+                self._apply_demo_mode_runtime()
                 return
 
         # Initialize Reticulum if not already done
@@ -1881,6 +1902,27 @@ def setup_identity(self, identity: RNS.Identity):
         if self._network_ready:
             self._finish_deferred_startup_services()
 
+        self._apply_demo_mode_runtime()
+
+    def _apply_demo_mode_runtime(self) -> None:
+        if not self.demo_mode:
+            return
+        ctx = self.current_context
+        if not ctx or not ctx.config:
+            return
+        self.plugins_enabled = False
+        ctx.config.privacy_mode_enabled.set(True)
+        ctx.config.auto_announce_enabled.set(False)
+        if self.auth_enabled_initial:
+            ctx.config.auth_enabled.set(True)
+        if self.auth_enabled and ctx.config.auth_password_hash.get() is None:
+            password = demo_auth_password_from_env()
+            password_hash = bcrypt.hashpw(
+                password.encode("utf-8"),
+                bcrypt.gensalt(),
+            ).decode("utf-8")
+            ctx.config.auth_password_hash.set(password_hash)
+
     def _finish_deferred_startup_services(self) -> None:
         """Start non-critical services after network_ready is published."""
         context = self.current_context
@@ -5106,6 +5148,7 @@ def _define_routes(self, routes):
             security_middleware,
             csrf_middleware,
             ip_allowlist_middleware,
+            demo_mode_middleware,
         ) = register_all_routes(routes, self)
 
         return (
@@ -5114,6 +5157,7 @@ def _define_routes(self, routes):
             security_middleware,
             csrf_middleware,
             ip_allowlist_middleware,
+            demo_mode_middleware,
         )
 
     def _encrypted_cookie_storage(self, use_https: bool) -> EncryptedCookieStorage:
@@ -5215,6 +5259,7 @@ def run(self, host, port, launch_browser: bool, enable_https: bool = True):
             security_middleware,
             csrf_middleware,
             ip_allowlist_middleware,
+            demo_mode_middleware,
         ) = self._define_routes(routes)
 
         ssl_context = None
@@ -5324,6 +5369,7 @@ async def on_startup(app):
                 security_middleware,
                 csrf_middleware,
                 ip_allowlist_middleware,
+                demo_mode_middleware,
             ],
         )
 
@@ -5521,6 +5567,8 @@ async def telemetry_tracking_loop(self, session_id, context=None):
 
     # handle announcing
     async def announce(self, context=None):
+        if self.demo_mode:
+            return
         ctx = context or self.current_context
         if not ctx:
             return
@@ -10386,6 +10434,12 @@ def main():
         default=env_bool("MESHCHAT_AUTH", False),
         help="Enable basic authentication for the web interface. Can also be set via MESHCHAT_AUTH environment variable.",
     )
+    parser.add_argument(
+        "--demo",
+        action="store_true",
+        default=env_bool("MESHCHAT_DEMO_MODE", False),
+        help="Public demo mode: read-only mesh and blocked API mutations. Can also be set via MESHCHAT_DEMO_MODE environment variable.",
+    )
     parser.add_argument(
         "--no-https",
         action="store_true",
@@ -10648,6 +10702,16 @@ def main():
         or args.restore_db
         or args.restore_from_snapshot,
     )
+    if auth_bypass_from_env():
+        print(
+            "WARNING: MESHCHAT_AUTH_BYPASS=1 disables web UI authentication",
+            file=sys.stderr,
+            flush=True,
+        )
+
+    demo_mode = bool(args.demo)
+    altcha_on = altcha_enabled_from_env()
+
     reticulum_meshchat = ReticulumMeshChat(
         identity,
         args.storage_dir,
@@ -10663,9 +10727,11 @@ def main():
         rns_loglevel=rns_log_cli,
         migration_context=migration_context,
         memory_diag_enabled=args.memory_diag,
-        plugins_enabled=not args.disable_plugins,
+        plugins_enabled=(not args.disable_plugins) and not demo_mode,
         defer_network_setup=not needs_immediate_network,
         headless=bool(args.headless),
+        demo_mode=demo_mode,
+        altcha_enabled=altcha_on,
     )
 
     # store recovery on app for wiring with identity context

meshchatx/meshchat.py

@@ -0,0 +1,95 @@
+# SPDX-License-Identifier: 0BSD
+
+"""ALTCHA proof-of-work verification for login and setup."""
+
+from __future__ import annotations
+
+import os
+import time
+from typing import Any
+
+import altcha
+from aiohttp import web
+
+from meshchatx.src.env_utils import env_bool
+
+ALTCHA_INVALID_CODE = "altcha_invalid"
+ALTCHA_ALGORITHM = "PBKDF2/SHA-256"
+ALTCHA_DEFAULT_COST = 2000
+
+
+def altcha_enabled_from_env() -> bool:
+    return env_bool("MESHCHAT_ALTCHA_ENABLED", False)
+
+
+def altcha_hmac_secret() -> str | None:
+    raw = os.environ.get("MESHCHAT_ALTCHA_HMAC_KEY", "").strip()
+    return raw or None
+
+
+def altcha_configured() -> bool:
+    return altcha_enabled_from_env() and bool(altcha_hmac_secret())
+
+
+def altcha_pow_cost() -> int:
+    raw = os.environ.get("MESHCHAT_ALTCHA_COST", "").strip()
+    if not raw:
+        return ALTCHA_DEFAULT_COST
+    try:
+        return max(100, int(raw))
+    except ValueError:
+        return ALTCHA_DEFAULT_COST
+
+
+def create_altcha_challenge_dict() -> dict[str, Any]:
+    secret = altcha_hmac_secret()
+    if not secret:
+        msg = "MESHCHAT_ALTCHA_HMAC_KEY is required when ALTCHA is enabled"
+        raise RuntimeError(msg)
+    expires_at = int(time.time()) + 300
+    challenge = altcha.create_challenge(
+        ALTCHA_ALGORITHM,
+        altcha_pow_cost(),
+        hmac_secret=secret,
+        expires_at=expires_at,
+    )
+    return challenge.to_dict()
+
+
+def verify_altcha_submission(payload: Any) -> tuple[bool, str | None]:
+    secret = altcha_hmac_secret()
+    if not secret:
+        return False, "altcha_not_configured"
+    if payload is None:
+        return False, ALTCHA_INVALID_CODE
+    if isinstance(payload, dict):
+        import json
+
+        payload = json.dumps(payload)
+    if not isinstance(payload, str) or not payload.strip():
+        return False, ALTCHA_INVALID_CODE
+    try:
+        result = altcha.verify_solution(payload.strip(), secret)
+    except Exception:
+        return False, ALTCHA_INVALID_CODE
+    if not result.verified:
+        err = result.error or ALTCHA_INVALID_CODE
+        return False, err
+    return True, None
+
+
+def altcha_error_response(code: str) -> web.Response:
+    return web.json_response(
+        {"error": "ALTCHA verification failed", "code": code},
+        status=400,
+    )
+
+
+async def require_altcha_payload(request, data: dict) -> web.Response | None:
+    if not altcha_enabled_from_env():
+        return None
+    payload = data.get("altcha")
+    ok, code = verify_altcha_submission(payload)
+    if not ok:
+        return altcha_error_response(code or ALTCHA_INVALID_CODE)
+    return None

meshchatx/src/backend/altcha_auth.py

@@ -0,0 +1,12 @@
+# SPDX-License-Identifier: 0BSD
+
+"""Optional login page hint text from environment."""
+
+from __future__ import annotations
+
+import os
+
+
+def auth_page_hint_from_env() -> str | None:
+    raw = os.environ.get("MESHCHAT_AUTH_PAGE_HINT", "").strip()
+    return raw or None