@nordbyte/nordrelay 0.4.1 → 0.5.0

package/.env.example

@@ -1,153 +1,244 @@
-# Required: bot token from BotFather.
-TELEGRAM_BOT_TOKEN=123456789:replace-me
-
-# Required: comma-separated Telegram user ids that may administer and use the bot.
-# A fresh install only accepts messages from these admin user ids.
-TELEGRAM_ADMIN_USER_IDS=123456789
-
-# Optional role controls. Add non-admin operators or read-only users here.
-# Admin user ids are automatically allowed and do not need to be repeated.
-TELEGRAM_ALLOWED_USER_IDS=
-TELEGRAM_READONLY_USER_IDS=
-# Optional granular permission policy per role. Permissions: inspect, sessions,
-# prompt, files, settings, auth, admin. Admin always keeps admin permission.
-TELEGRAM_ROLE_POLICIES_JSON=
-
-# Backward-compatible alternative for this connector. Private chat ids usually
-# match the Telegram user id; group chat ids may be negative.
-TELEGRAM_ALLOWED_CHAT_IDS=
+# NordRelay runtime config example.
+# Access is managed with NordRelay users, groups, linked Telegram identities, and enabled Telegram group chats.
+# Create the first admin with `nordrelay init` or `nordrelay user create-admin`.
 
-# Optional explicit override. Keep false for private bots.
-TELEGRAM_ALLOW_ANY_CHAT=false
+# Telegram
+# Required Telegram bot and transport settings.
+# BotFather token.
+TELEGRAM_BOT_TOKEN=123456789:replace-me
+# polling or webhook.
+# Options: polling, webhook
+TELEGRAM_TRANSPORT=polling
+# Public base URL for webhook mode.
+TELEGRAM_WEBHOOK_URL=
+# Local webhook bind host.
+TELEGRAM_WEBHOOK_HOST=127.0.0.1
+# Local webhook bind port.
+TELEGRAM_WEBHOOK_PORT=8080
+# Webhook request path.
+TELEGRAM_WEBHOOK_PATH=/telegram/webhook
+# Optional Telegram webhook secret token.
+TELEGRAM_WEBHOOK_SECRET=
 
+# Agents
 # Agent access. Codex is enabled by default; Pi, Hermes, OpenClaw, and Claude Code are opt-in.
-# Pi requires the `pi` CLI from https://pi.dev/ on the host. Hermes uses
-# the Hermes API Server (`hermes gateway` with API_SERVER_ENABLED=true).
-# OpenClaw uses the OpenClaw Gateway WebSocket RPC endpoint.
-# Claude Code uses the Claude Agent SDK and the host `claude` CLI when present.
+# Allow Codex sessions.
 NORDRELAY_CODEX_ENABLED=true
+# Allow Pi sessions.
 NORDRELAY_PI_ENABLED=false
+# Allow Hermes sessions through the Hermes API Server.
 NORDRELAY_HERMES_ENABLED=false
+# Allow OpenClaw sessions through the OpenClaw Gateway.
 NORDRELAY_OPENCLAW_ENABLED=false
+# Allow Claude Code sessions through the Claude Agent SDK.
 NORDRELAY_CLAUDE_CODE_ENABLED=false
+# codex, pi, hermes, openclaw, or claude-code.
+# Options: codex, pi, hermes, openclaw, claude-code
 NORDRELAY_DEFAULT_AGENT=codex
 
-# Codex defaults for newly created or reattached Telegram sessions.
+# Codex
+# Codex defaults for newly created or reattached sessions.
+# Optional Codex SDK API key.
 CODEX_API_KEY=
+# Optional explicit Codex executable path.
 CODEX_CLI_PATH=
+# Force SDK-bundled CLI instead of host CLI.
 CODEX_USE_BUNDLED_CLI=false
+# Default model for new Codex threads.
 CODEX_MODEL=
+# Local state sync interval.
 CODEX_SYNC_INTERVAL_MS=10000
+# External CLI busy polling interval.
+CODEX_EXTERNAL_BUSY_CHECK_MS=5000
+# External CLI stale timeout.
+CODEX_EXTERNAL_BUSY_STALE_MS=300000
+# read-only, workspace-write, or danger-full-access.
+# Options: read-only, workspace-write, danger-full-access
 CODEX_SANDBOX_MODE=workspace-write
+# never, on-request, on-failure, or untrusted.
+# Options: never, on-request, on-failure, untrusted
 CODEX_APPROVAL_POLICY=never
-
-# Optional extra launch profiles for /launch_profiles.
-# Example: [{"id":"review","label":"Review","sandboxMode":"workspace-write","approvalPolicy":"on-request"}]
+# Additional launch profile definitions.
 CODEX_LAUNCH_PROFILES_JSON=
+# Launch profile ID used by default.
 CODEX_DEFAULT_LAUNCH_PROFILE=default
+# Expose danger-full-access profiles.
 ENABLE_UNSAFE_LAUNCH_PROFILES=false
 
-# Pi coding agent defaults. PI_DEFAULT_MODEL accepts Pi model patterns such as
-# openai-codex/gpt-5.5. PI_DEFAULT_THINKING: off, minimal, low, medium, high, xhigh.
+# Pi
+# Pi coding agent defaults.
+# Optional Pi executable path.
 PI_CLI_PATH=
+# Optional Pi session directory.
 PI_SESSION_DIR=
+# Default Pi model slug.
 PI_DEFAULT_MODEL=
+# off, minimal, low, medium, high, or xhigh.
+# Options: off, minimal, low, medium, high, xhigh
 PI_DEFAULT_THINKING=medium
+# default, readonly, no-tools, offline, or safe-offline.
+# Options: default, readonly, no-tools, offline, safe-offline
 PI_DEFAULT_PROFILE=default
 
-# Hermes Agent defaults. HERMES_DEFAULT_REASONING: none, minimal, low,
-# medium, high, xhigh. HERMES_API_KEY must match API_SERVER_KEY when the
-# Hermes API Server is protected.
+# Hermes
+# Hermes Agent defaults. Hermes uses the Hermes API Server.
+# Optional Hermes executable path.
 HERMES_CLI_PATH=
+# Optional Hermes home directory. Defaults to ~/.hermes.
 HERMES_HOME=
+# Optional explicit Hermes state.db path.
 HERMES_STATE_DB_PATH=
+# Hermes API Server base URL.
 HERMES_API_BASE_URL=http://127.0.0.1:8642
+# Bearer token for the Hermes API Server.
 HERMES_API_KEY=
+# Default model label sent to Hermes API runs.
 HERMES_DEFAULT_MODEL=
+# none, minimal, low, medium, high, or xhigh.
+# Options: none, minimal, low, medium, high, xhigh
 HERMES_DEFAULT_REASONING=
+# default, safe, readonly, or yolo.
+# Options: default, safe, readonly, yolo
 HERMES_DEFAULT_PROFILE=default
 
-# OpenClaw Agent defaults. OPENCLAW_DEFAULT_THINKING: off, minimal, low,
-# medium, high, xhigh. Gateway token/password are optional unless your
-# OpenClaw Gateway requires shared-secret authentication.
+# OpenClaw
+# OpenClaw Agent defaults. OpenClaw uses the OpenClaw Gateway WebSocket RPC endpoint.
+# Optional OpenClaw executable path.
 OPENCLAW_CLI_PATH=
+# OpenClaw Gateway WebSocket URL.
 OPENCLAW_GATEWAY_URL=ws://127.0.0.1:18789
+# Shared-secret token for the OpenClaw Gateway.
 OPENCLAW_GATEWAY_TOKEN=
+# Shared-secret password for the OpenClaw Gateway.
 OPENCLAW_GATEWAY_PASSWORD=
+# Configured OpenClaw agent id, for example main or work.
 OPENCLAW_AGENT_ID=main
+# Optional OpenClaw home directory. Defaults to ~/.openclaw.
 OPENCLAW_HOME=
+# Optional OpenClaw state directory.
 OPENCLAW_STATE_DIR=
+# Default OpenClaw model id.
 OPENCLAW_DEFAULT_MODEL=
+# off, minimal, low, medium, high, or xhigh.
+# Options: off, minimal, low, medium, high, xhigh
 OPENCLAW_DEFAULT_THINKING=
+# default, safe, readonly, local, or deliver.
+# Options: default, safe, readonly, local, deliver
 OPENCLAW_DEFAULT_PROFILE=default
 
-# Claude Code defaults. CLAUDE_CODE_DEFAULT_EFFORT: off, low, medium, high,
-# xhigh. CLAUDE_CODE_CLI_PATH is optional; NordRelay uses `claude` on PATH or
-# the Claude Agent SDK bundled runtime.
+# Claude Code
+# Claude Code defaults. NordRelay uses the Claude Agent SDK and the host claude CLI when present.
+# Optional Claude Code executable path. Defaults to claude on PATH or the SDK bundled runtime.
 CLAUDE_CODE_CLI_PATH=
+# Optional Claude config directory. Defaults to ~/.claude.
 CLAUDE_CONFIG_DIR=
+# Default Claude Code model alias or model id.
 CLAUDE_CODE_DEFAULT_MODEL=
+# off, low, medium, high, or xhigh.
+# Options: off, low, medium, high, xhigh
 CLAUDE_CODE_DEFAULT_EFFORT=
+# default, accept-edits, plan, readonly, no-tools, or bypass-permissions.
+# Options: default, accept-edits, plan, readonly, no-tools, bypass-permissions
 CLAUDE_CODE_DEFAULT_PROFILE=default
+# Maximum agentic turns for each Claude Code prompt.
 CLAUDE_CODE_MAX_TURNS=100
 
-# Telegram output controls.
+# Operations
+# Runtime output, logging, update, and Telegram behavior controls.
+# text or json.
+# Options: text, json
 CONNECTOR_LOG_FORMAT=text
+# all, summary, errors-only, or none.
+# Options: all, summary, errors-only, none
 TOOL_VERBOSITY=summary
+# Append per-turn token usage.
 SHOW_TURN_TOKEN_USAGE=false
+# Allow /login and /logout.
 ENABLE_TELEGRAM_LOGIN=true
+# Send Telegram reactions.
 ENABLE_TELEGRAM_REACTIONS=false
+# Minimum send interval.
 TELEGRAM_RATE_LIMIT_MIN_INTERVAL_MS=80
+# Minimum edit interval.
 TELEGRAM_EDIT_MIN_INTERVAL_MS=1200
-TELEGRAM_TRANSPORT=polling
-TELEGRAM_WEBHOOK_URL=
-TELEGRAM_WEBHOOK_HOST=127.0.0.1
-TELEGRAM_WEBHOOK_PORT=8080
-TELEGRAM_WEBHOOK_PATH=/telegram/webhook
-TELEGRAM_WEBHOOK_SECRET=
+# off, status, final, or full.
+# Options: off, status, final, full
 TELEGRAM_CLI_MIRROR_MODE=status
+# Minimum mirrored edit interval.
 TELEGRAM_CLI_MIRROR_MIN_UPDATE_MS=4000
+# off, minimal, or all.
+# Options: off, minimal, all
 TELEGRAM_NOTIFY_MODE=minimal
+# HH-HH or blank.
 TELEGRAM_QUIET_HOURS=
+# Additional comma-separated regex patterns.
 TELEGRAM_REDACT_PATTERNS=
+# auto, npm, or git.
+# Options: auto, npm, git
+NORDRELAY_UPDATE_METHOD=
+
+# Artifacts
+# File, artifact, and retention controls.
+# Max inbound/outbound file size.
 MAX_FILE_SIZE=20971520
+# Days before pruning.
 ARTIFACT_RETENTION_DAYS=7
+# Maximum artifact turns retained.
 ARTIFACT_MAX_TURNS=30
+# Maximum inbox dirs retained.
 ARTIFACT_MAX_INBOX_DIRS=30
+# Extra ignored dirs or relative paths.
 ARTIFACT_IGNORE_DIRS=
+# Extra ignored glob patterns.
 ARTIFACT_IGNORE_GLOBS=
+# Automatically send artifact files.
 TELEGRAM_AUTO_SEND_ARTIFACTS=false
 
-# State and team controls. Use sqlite for a single-file state database when
-# better-sqlite3 is available; json keeps separate human-readable files.
+# Workspace
+# State and workspace guardrails.
+# Restrict selectable workspaces.
+WORKSPACE_ALLOWED_ROOTS=
+# Warn for broad workspace roots.
+WORKSPACE_WARN_ROOTS=
+# json or sqlite.
+# Options: json, sqlite
 NORDRELAY_STATE_BACKEND=json
+# Retained audit events.
 NORDRELAY_AUDIT_MAX_EVENTS=1000
+# Write-lock TTL.
 NORDRELAY_SESSION_LOCK_TTL_MS=1800000
+# NPM version cache TTL.
 NORDRELAY_VERSION_CACHE_TTL_MS=3600000
 
-# Local WebUI dashboard. Binding to 0.0.0.0 requires either token auth or
-# basic auth; startup fails without one of these credentials.
-NORDRELAY_DASHBOARD_HOST=127.0.0.1
-NORDRELAY_DASHBOARD_PORT=31878
-NORDRELAY_DASHBOARD_TOKEN=
-NORDRELAY_DASHBOARD_USER=
-NORDRELAY_DASHBOARD_PASSWORD=
-NORDRELAY_ENV_FILE=
-
-# Optional workspace guardrails. Leave WORKSPACE_ALLOWED_ROOTS empty to allow
-# all workspaces discovered from enabled agent state.
-WORKSPACE_ALLOWED_ROOTS=
-WORKSPACE_WARN_ROOTS=
-
-# Optional voice transcription fallback. Local parakeet-coreml is used first
-# when installed; OpenAI Whisper is used when OPENAI_API_KEY is set.
+# Voice
+# Optional voice transcription settings.
+# Whisper fallback API key.
 OPENAI_API_KEY=
+# auto, parakeet, faster-whisper, or openai.
+# Options: auto, parakeet, faster-whisper, openai
 VOICE_PREFERRED_BACKEND=auto
+# Default transcription language.
 VOICE_DEFAULT_LANGUAGE=
+# Do not send voice transcripts as prompts.
 VOICE_TRANSCRIBE_ONLY=false
+# Python executable.
 FASTER_WHISPER_PYTHON=.venv/bin/python
+# Model name.
 FASTER_WHISPER_MODEL=base
+# cpu, cuda, etc.
 FASTER_WHISPER_DEVICE=cpu
+# int8, float16, etc.
 FASTER_WHISPER_COMPUTE_TYPE=int8
+# Fixed transcription language.
 FASTER_WHISPER_LANGUAGE=
+# Transcription timeout.
 FASTER_WHISPER_TIMEOUT_MS=600000
+
+# Dashboard
+# Local WebUI dashboard. User login is required for every page, API route, SSE stream, artifact download, and health endpoint.
+# WebUI bind host.
+NORDRELAY_DASHBOARD_HOST=127.0.0.1
+# WebUI bind port.
+NORDRELAY_DASHBOARD_PORT=31878
+# Optional explicit env-file path used by the CLI wrapper and dashboard.
+NORDRELAY_ENV_FILE=

package/README.md

@@ -36,9 +36,9 @@ Session control:
 - `/status`, `/health`, and `/version` report connector runtime health from Telegram.
 - `/tasks` and `/progress` show the current turn status, queue length, active tool, elapsed time, and last error.
 - `/activity` shows a compact timeline of recent rollout events for the active thread, with filters and export.
-- `/diagnostics` reports redacted runtime, config, role, Telegram rate-limit, mirror, voice, session, queue, and progress details for admins.
+- `/diagnostics` reports redacted runtime, config, user/group authorization, Telegram rate-limit, mirror, voice, session, queue, and progress details.
 - `/lock`, `/unlock`, and `/locks` provide a team write-lock for shared sessions so one user can operate while others watch.
-- `/audit` shows recent prompt, queue, lock, and command audit events for admins.
+- `/audit` shows recent prompt, queue, lock, command, authentication, permission-denied, user, group, Telegram-link, Telegram-chat, and web-session audit events for admins.
 
 Adapter architecture:
 
@@ -46,7 +46,7 @@ Adapter architecture:
 - `/channels` shows available and planned messaging adapters for Discord, WhatsApp, Slack, and Matrix.
 - Codex, Pi, Hermes, OpenClaw, and Claude Code are implemented as agent adapters.
 - `/agents` shows available/planned agent adapters and whether Codex, Pi, Hermes, OpenClaw, and Claude Code are enabled.
-- Shared command-action renderers keep channel-neutral responses for adapter lists, queues, artifacts, logs, and update jobs separate from Telegram-specific keyboards and delivery.
+- Shared command-action renderers and a channel runtime contract keep inbound commands, outbound messages, typing, files, inline actions, and streaming-ready delivery separate from Telegram-specific API calls.
 
 Codex runtime:
 
@@ -160,13 +160,17 @@ Telegram output:
 
 Authentication and safety:
 
-- Telegram access requires `TELEGRAM_ADMIN_USER_IDS` by default; a fresh install only accepts those admin user ids.
-- `TELEGRAM_ALLOWED_USER_IDS` can add non-admin operators.
-- `TELEGRAM_ALLOWED_CHAT_IDS` is supported for private chats, groups, and backward compatibility.
-- `TELEGRAM_ALLOW_ANY_CHAT=true` is an explicit unsafe override for temporary local setup only.
-- `TELEGRAM_ADMIN_USER_IDS` restricts admin-only commands such as `/logs`, `/restart`, and `/update`.
-- `TELEGRAM_READONLY_USER_IDS` can inspect status and sessions but cannot send prompts or run mutating commands by default.
-- `TELEGRAM_ROLE_POLICIES_JSON` can override role permissions for `admin`, `operator`, and `readonly`.
+- WebUI login is required for every dashboard page, API route, SSE stream, artifact download, and health endpoint.
+- Access is managed through NordRelay users, groups, permissions, web sessions, and linked Telegram identities.
+- Built-in groups are `Admin`, `User`, and `Read Only`; custom groups can be created in the WebUI and can restrict allowed agents, workspace roots, and Telegram chats.
+- The last active admin cannot be disabled or demoted, and web sessions are revoked when passwords or group memberships change.
+- Admins can review and revoke active WebUI sessions from the Users page.
+- Telegram private chats require a linked active NordRelay user.
+- Telegram group and forum chats must be registered before use; admins can run `/register_chat` in the chat or enable chats in the WebUI.
+- `/whoami` shows the linked NordRelay account and groups.
+- `/link <code>` links a Telegram account to a NordRelay user after a link code is created in the WebUI or with `nordrelay user link-code`.
+- WebUI login and Telegram link attempts are rate-limited to reduce brute-force risk.
+- User, group, Telegram-link, Telegram-chat, web-session, login, and permission-denied events are written to the audit log.
 - `/auth` reports Codex authentication, Pi provider environment health, Hermes API Server reachability, OpenClaw Gateway reachability, or Claude Code CLI auth for the selected agent.
 - `/login` starts Telegram-managed CLI auth for Codex, Hermes, or Claude Code when enabled.
 - `/logout` signs out of CLI auth for Codex, Hermes, or Claude Code; Codex logout is disabled while `CODEX_API_KEY` is in use.
@@ -192,7 +196,7 @@ Operations:
 - The WebUI has responsive header/sidebar/footer navigation, live chat streaming, session controls, queue/artifact/log/diagnostic views, and settings management.
 - The WebUI supports light and dark themes, tabbed settings groups, paginated session browsing, and chat uploads for images, documents, and audio transcription.
 - The WebUI exposes REST and SSE endpoints for chat streaming, sessions, settings, queue, artifacts, logs, health, and diagnostics.
-- Binding the dashboard to `0.0.0.0` is refused unless `NORDRELAY_DASHBOARD_TOKEN` or `NORDRELAY_DASHBOARD_USER` plus `NORDRELAY_DASHBOARD_PASSWORD` is configured.
+- The dashboard can bind to `127.0.0.1` or `0.0.0.0`; user login and session cookies are mandatory in both modes.
 - Telegram can run with long polling or an HTTP webhook via `TELEGRAM_TRANSPORT=webhook`.
 - Version freshness checks are cached with `NORDRELAY_VERSION_CACHE_TTL_MS` to keep `/version` responsive.
 - CI includes typecheck, tests, package dry run, npm audit, and a separate secret-scan workflow.
@@ -207,6 +211,7 @@ Recommended npm setup:
 ```bash
 npm install -g @nordbyte/nordrelay
 nordrelay init
+nordrelay user list
 nordrelay doctor
 nordrelay start
 ```
@@ -216,9 +221,16 @@ npm is the fastest install path and is the recommended default for normal use. `
 Non-interactive setup is also supported:
 
 ```bash
-nordrelay init --token 123456789:replace-me --admin-id 123456789
+nordrelay init \
+  --token 123456789:replace-me \
+  --admin-email you@example.com \
+  --admin-name "Your Name" \
+  --admin-password "replace-with-a-long-password" \
+  --telegram-user-id 123456789
 ```
 
+`--telegram-user-id` is optional, but linking the first admin during setup is the fastest way to use Telegram immediately.
+
 Source checkout setup:
 
 Install dependencies and build the runtime:
@@ -237,14 +249,13 @@ Create the Telegram bot:
 2. Run `/newbot`.
 3. Choose a display name and bot username.
 4. Copy the bot token into `TELEGRAM_BOT_TOKEN` in `~/.nordrelay/nordrelay.env`.
-5. Find your Telegram user id with a trusted id helper bot, for example `@userinfobot`, or from Telegram API tooling.
-6. Put your user id into `TELEGRAM_ADMIN_USER_IDS`.
+5. Create the first admin user with `nordrelay init` or `nordrelay user create-admin`.
+6. Link Telegram from the WebUI, with `nordrelay user link-telegram`, or by creating a link code and sending `/link <code>` to the bot.
 
 Minimal private-bot `~/.nordrelay/nordrelay.env`:
 
 ```dotenv
 TELEGRAM_BOT_TOKEN=123456789:replace-me
-TELEGRAM_ADMIN_USER_IDS=123456789
 NORDRELAY_CODEX_ENABLED=true
 NORDRELAY_PI_ENABLED=false
 NORDRELAY_HERMES_ENABLED=false
@@ -255,13 +266,14 @@ CODEX_SANDBOX_MODE=workspace-write
 CODEX_APPROVAL_POLICY=never
 ```
 
-Optional non-admin operators can be added with:
-
-```dotenv
-TELEGRAM_ALLOWED_USER_IDS=234567890,345678901
-```
+User and Telegram access management:
 
-Do not use `TELEGRAM_ALLOW_ANY_CHAT=true` for normal coding sessions. It makes the bot reachable from any Telegram chat that can message it.
+- `nordrelay init` creates the first admin user and writes `~/.nordrelay/users.json`.
+- `nordrelay user create-admin --email you@example.com --name "Your Name"` creates another admin.
+- `nordrelay user create --email dev@example.com --name "Dev" --group user` creates a normal user.
+- `nordrelay user link-telegram --email you@example.com --telegram-user-id 123456789` links a Telegram account directly.
+- `nordrelay user link-code --email you@example.com` creates a short-lived code that the user sends as `/link <code>` to the bot.
+- Group chats are disabled until an admin enables them from the WebUI or runs `/register_chat` inside the group.
 
 Codex authentication:
 
@@ -334,7 +346,7 @@ Where Codex exposes namespaced plugin commands, this also works:
 /nordrelay:remote
 ```
 
-The old unnamespaced `/remote` command is no longer required and current Codex TUI builds do not register it as a top-level plugin slash command. The command is only a process-manager shortcut; Telegram contains the actual controls.
+The command is only a process-manager shortcut; Telegram contains the actual controls.
 
 Manual process commands:
 
@@ -357,6 +369,7 @@ node plugins/nordrelay/scripts/nordrelay.mjs status
 node plugins/nordrelay/scripts/nordrelay.mjs restart
 node plugins/nordrelay/scripts/nordrelay.mjs stop
 node plugins/nordrelay/scripts/nordrelay.mjs foreground
+node plugins/nordrelay/scripts/nordrelay.mjs user list
 node plugins/nordrelay/scripts/nordrelay.mjs doctor
 node plugins/nordrelay/scripts/nordrelay.mjs web
 ```
@@ -411,8 +424,8 @@ The dashboard is a second NordRelay client next to Telegram. It can:
 - Edit all supported runtime settings from tabbed Settings groups with option selects, validation feedback, and restart actions.
 - View filtered connector/update/agent-update logs, structured diagnostics, enabled channels, and agent adapters.
 - Inspect a per-agent capability matrix showing model, reasoning, launch, fast mode, attachments, activity, usage, auth, login/logout, and handback support.
-- Check NordRelay and agent CLI versions, then start Codex, Pi, Hermes, OpenClaw, or Claude Code updates from outdated version rows with live output, cancel, full-log, and stdin response controls for interactive updaters.
-- Load dashboard CSS and client JavaScript as authenticated static assets instead of inline HTML, keeping the server shell, style, and browser client modules separate.
+- Check NordRelay and agent CLI versions, then start Codex, Pi, Hermes, OpenClaw, or Claude Code updates from outdated version rows with live output, cancel, delete-log, and stdin response controls for interactive updaters.
+- Build dashboard CSS and client JavaScript from modular source assets through esbuild, then serve them as authenticated static assets instead of inline HTML.
 
 Dashboard API endpoints are served under `/api/*`. Streaming uses `GET /api/events`.
 
@@ -421,13 +434,9 @@ Dashboard auth:
 ```dotenv
 NORDRELAY_DASHBOARD_HOST=127.0.0.1
 NORDRELAY_DASHBOARD_PORT=31878
-NORDRELAY_DASHBOARD_TOKEN=replace-with-random-token
-# or:
-NORDRELAY_DASHBOARD_USER=admin
-NORDRELAY_DASHBOARD_PASSWORD=replace-with-random-password
 ```
 
-When `NORDRELAY_DASHBOARD_HOST=0.0.0.0`, NordRelay refuses to start the dashboard unless token or basic auth is configured. Login cookies use `SameSite=Strict`, and every dashboard route, API endpoint, SSE stream, artifact download, and health endpoint requires the same auth.
+The dashboard always requires NordRelay email/password login. Login cookies use `SameSite=Strict`, and every dashboard route, API endpoint, SSE stream, artifact download, and health endpoint requires an authenticated active user with the matching permission.
 
 Webhook mode:
 
@@ -440,7 +449,7 @@ TELEGRAM_WEBHOOK_PATH=/telegram/webhook
 TELEGRAM_WEBHOOK_SECRET=replace-with-random-secret
 ```
 
-Run NordRelay behind your reverse proxy so the public URL forwards to `http://127.0.0.1:8080/telegram/webhook`. `GET /healthz` returns a simple health check.
+Run NordRelay behind your reverse proxy so the public URL forwards to `http://127.0.0.1:8080/telegram/webhook`. Dashboard health checks are available to authenticated WebUI sessions through `/healthz` and `/api/health`.
 
 ## Telegram Commands
 
@@ -449,6 +458,9 @@ Run NordRelay behind your reverse proxy so the public URL forwards to `http://12
 - `/channels` shows available and planned messaging adapters.
 - `/agents` shows available and planned coding-agent adapters.
 - `/agent` selects the active agent for this Telegram context.
+- `/link <code>` links the Telegram account to a NordRelay user.
+- `/whoami` shows the linked NordRelay user, groups, and permissions.
+- `/register_chat` enables the current Telegram group or forum chat for NordRelay when the linked user has user-management permission.
 - `/new` starts a new thread. If the selected agent knows multiple workspaces, Telegram shows a workspace picker.
 - `/session` shows current thread details.
 - `/sessions` opens a paginated recent-session picker.
@@ -472,7 +484,7 @@ Run NordRelay behind your reverse proxy so the public URL forwards to `http://12
 - `/cancel <queue-id>` removes one queued prompt; the queue id is the short code shown in messages such as `Queued prompt 332kmt`.
 - `/clearqueue` clears queued prompts for this Telegram context.
 - `/activity [all|tools|errors|user|agent|tasks] [limit] [since 1h] [export]` shows or exports rollout activity for the active thread.
-- `/audit [limit]` shows recent audit events. Admin only.
+- `/audit [limit]` shows recent audit events. Requires `audit.read`.
 - `/lock` locks writes for this Telegram session to the current user.
 - `/unlock` releases the current session write lock.
 - `/locks` lists active write locks.
@@ -499,14 +511,14 @@ Run NordRelay behind your reverse proxy so the public URL forwards to `http://12
 - `/status` reports connector runtime status.
 - `/health` reports runtime health, auth, PIDs, Codex CLI, Pi CLI, Hermes CLI, OpenClaw CLI, Claude Code CLI, and state DB.
 - `/version` reports connector, Codex CLI, Pi CLI, Hermes CLI, OpenClaw CLI, and Claude Code CLI paths plus installed/latest NordRelay, Codex, Pi, Hermes, OpenClaw, and Claude Code versions with status icons.
-- `/logs [lines]` shows a redacted, timestamped connector log tail. Admin only.
-- `/logs update [lines]` shows the self-update log. Admin only.
-- `/logs agent [lines]` shows the aggregate agent updater log. Admin only.
-- `/logs all [lines]` shows connector, self-update, and agent update logs together. Admin only.
-- `/diagnostics` shows redacted connector diagnostics. Admin only.
-- `/restart` restarts the connector process. Admin only.
-- `/update` updates through npm or git depending on the detected install type, then restarts only on success. Admin only.
-- `/update agents`, `/update <agent>`, `/update jobs`, `/update log <id>`, `/update cancel <id>`, and `/update input <id> <text>` manage agent CLI update jobs. Admin only.
+- `/logs [lines]` shows a redacted, timestamped connector log tail. Requires `logs.read`.
+- `/logs update [lines]` shows the self-update log. Requires `logs.read`.
+- `/logs agent [lines]` shows the aggregate agent updater log. Requires `logs.read`.
+- `/logs all [lines]` shows connector, self-update, and agent update logs together. Requires `logs.read`.
+- `/diagnostics` shows redacted connector diagnostics. Requires `logs.read`.
+- `/restart` restarts the connector process. Requires `system.restart`.
+- `/update` updates through npm or git depending on the detected install type, then restarts only on success. Requires `updates.run`.
+- `/update agents`, `/update <agent>`, `/update jobs`, `/update log <id>`, `/update cancel <id>`, and `/update input <id> <text>` manage agent CLI update jobs. Requires `updates.run`.
 
 ## Command Examples
 
@@ -689,12 +701,6 @@ Voice transcription uses `OPENAI_API_KEY`, not `CODEX_API_KEY`.
 Telegram:
 
 - `TELEGRAM_BOT_TOKEN`: required BotFather token.
-- `TELEGRAM_ADMIN_USER_IDS`: required comma-separated Telegram user ids allowed to use admin commands. Admin ids are automatically allowed to use the bot.
-- `TELEGRAM_ALLOWED_USER_IDS`: optional comma-separated non-admin Telegram user ids allowed to use the bot.
-- `TELEGRAM_READONLY_USER_IDS`: comma-separated Telegram user ids that can inspect status and sessions but cannot run prompts or mutating commands.
-- `TELEGRAM_ALLOWED_CHAT_IDS`: comma-separated chat ids allowed to use the bot. Group ids may be negative.
-- `TELEGRAM_ALLOW_ANY_CHAT`: allows all chats when `true`. Keep `false` unless you intentionally want an open bot.
-- `TELEGRAM_ROLE_POLICIES_JSON`: optional JSON object mapping roles to permissions. Permissions are `inspect`, `sessions`, `prompt`, `files`, `settings`, `auth`, and `admin`.
 - `TELEGRAM_RATE_LIMIT_MIN_INTERVAL_MS`: minimum interval for normal Telegram API sends. Defaults to `80`.
 - `TELEGRAM_EDIT_MIN_INTERVAL_MS`: minimum interval for Telegram message edits. Defaults to `1200`.
 - `TELEGRAM_TRANSPORT`: `polling` or `webhook`. Defaults to `polling`.
@@ -709,11 +715,13 @@ Telegram:
 - `TELEGRAM_QUIET_HOURS`: optional quiet-hour range in `HH-HH` format, for example `22-7`.
 - `TELEGRAM_REDACT_PATTERNS`: comma-separated regular expressions for additional Telegram/log redaction.
 
-Role policy example:
+User management:
 
-```dotenv
-TELEGRAM_ROLE_POLICIES_JSON={"readonly":["inspect","sessions"],"operator":["inspect","sessions","prompt","files"],"admin":"*"}
-```
+- Users, groups, Telegram identities, Telegram group-chat access, and web sessions are stored in `~/.nordrelay/users.json`.
+- Manage users in the WebUI Users page or with `nordrelay user list`, `create-admin`, `create`, `reset-password`, `link-telegram`, and `link-code`.
+- Built-in groups are `admin`, `user`, and `readonly`.
+- Group permissions include `inspect`, `sessions.read`, `sessions.write`, `prompt.send`, `prompt.abort`, `files.read`, `files.write`, `settings.read`, `settings.write`, `auth.manage`, `diagnostics.read`, `logs.read`, `logs.clear`, `queue.read`, `queue.write`, `updates.run`, `system.restart`, `users.read`, `users.write`, and `audit.read`.
+- Custom groups can also restrict access to specific agent ids, workspace roots, and Telegram chat ids.
 
 Agent selection:
 
@@ -732,9 +740,6 @@ Dashboard:
 
 - `NORDRELAY_DASHBOARD_HOST`: dashboard bind host. Defaults to `127.0.0.1`.
 - `NORDRELAY_DASHBOARD_PORT`: dashboard bind port. Defaults to `31878`.
-- `NORDRELAY_DASHBOARD_TOKEN`: optional dashboard bearer/login token. Required when binding to `0.0.0.0` unless basic auth is configured.
-- `NORDRELAY_DASHBOARD_USER`: optional dashboard basic-auth user.
-- `NORDRELAY_DASHBOARD_PASSWORD`: optional dashboard basic-auth password. Required with `NORDRELAY_DASHBOARD_USER`.
 - `NORDRELAY_ENV_FILE`: optional explicit env-file path used by the wrapper and edited by the dashboard settings page. Defaults to `~/.nordrelay/nordrelay.env`.
 
 Codex:
@@ -871,14 +876,14 @@ Unsafe profiles are intentionally gated. Telegram asks for confirmation before a
 
 ## Security Notes
 
-- Always set `TELEGRAM_ADMIN_USER_IDS`; a fresh install refuses to start without at least one admin user id.
-- Prefer `TELEGRAM_ADMIN_USER_IDS` and `TELEGRAM_ALLOWED_USER_IDS` over `TELEGRAM_ALLOWED_CHAT_IDS` for private bots.
-- Use `TELEGRAM_ALLOWED_CHAT_IDS` for groups or forum topics only when you trust the entire chat.
-- Do not leave `TELEGRAM_ALLOW_ANY_CHAT=true` enabled after setup.
+- Create the first admin user during setup and keep that account protected with a strong password.
+- Link Telegram accounts only to active NordRelay users that should control agents remotely.
+- Enable Telegram group/forum chats only when the whole chat context is trusted for the permissions granted to linked users.
+- Review group permissions before granting `prompt.send`, `prompt.abort`, `files.write`, `settings.write`, `updates.run`, `system.restart`, or `users.write`.
 - Treat `danger-full-access` as equivalent to shell access on the host.
 - Treat uploaded files as untrusted input. They are staged inside the active workspace so the selected sandbox policy still matters.
 - Keep `CODEX_API_KEY`, `HERMES_API_KEY`, `OPENCLAW_GATEWAY_TOKEN`, `OPENCLAW_GATEWAY_PASSWORD`, and `OPENAI_API_KEY` in `~/.nordrelay/nordrelay.env` or host secret management.
-- In group chats, remember that any allowed user can prompt the selected agent in that chat context.
+- In group chats, remember that any linked user with prompt permissions can prompt the selected agent in that chat context.
 - Use `TOOL_VERBOSITY=summary` or `errors-only` when command output may include sensitive data.
 - Review and unsafe launch profiles add a Telegram approve/deny gate before each turn starts.
 
@@ -1035,19 +1040,24 @@ npm run build
 - `plugins/nordrelay/`: Codex plugin bundle with manifest, skill, command, icon, and process wrapper.
 - `plugins/nordrelay/scripts/nordrelay.mjs`: process manager for `start`, `stop`, `restart`, `status`, and `foreground`.
 - `src/index.ts`: runtime entrypoint, config load, auth check, state-file writes, polling lifecycle, shutdown.
-- `src/bot.ts`: Telegram command handlers, callbacks, message streaming, file/photo/voice handling, artifacts, and error handling.
+- `src/bot.ts`: Telegram prompt/session runtime, streaming, file/photo/voice handling, artifacts, and error handling.
+- `src/telegram-access-commands.ts`, `src/telegram-update-commands.ts`, and `src/telegram-command-menu.ts`: focused Telegram command groups for access linking, update jobs, and command menu registration.
+- `src/channel-adapter.ts`, `src/channel-runtime.ts`, and `src/channel-actions.ts`: channel descriptors, generic command routing, outbound delivery contracts, and channel-neutral command responses.
+- `src/config-metadata.ts`: shared setting metadata used by the WebUI settings page and generated `.env.example`.
+- `src/webui/`: focused WebUI source assets for core runtime state/API helpers, overview rendering, live events, chat/session workflows, admin pages, and CSS sections.
 - `src/bot-preferences.ts`: per-context mirror, notification, quiet-hour, and voice preference persistence.
 - `src/telegram-rate-limit.ts`: centralized Telegram API send/edit/document rate limiting and retry-after tracking.
 - `src/persistence.ts`: atomic JSON/text writes with backup recovery.
 - `src/redaction.ts`: common secret redaction and custom redaction pattern support.
 - `src/workspace-policy.ts`: workspace allow/warn root evaluation.
-- `src/access-control.ts`: Telegram role permissions and command/callback permission mapping.
+- `src/access-control.ts`: user/group permission definitions and command/callback/WebUI permission mapping.
 - `src/codex-session.ts`: Codex SDK service for new/resumed threads, streaming events, abort, model, reasoning, launch profiles, and handback.
 - `src/pi-session.ts`: Pi RPC service for JSONL RPC sessions, streaming events, abort, model, thinking, launch profiles, and handback.
 - `src/hermes-session.ts`: Hermes API Server service for streamed runs, stop, model, reasoning, launch profiles, attachments, and handback.
 - `src/openclaw-session.ts`: OpenClaw Gateway service for streamed runs, cancel, model, thinking, launch profiles, attachments, and handback.
 - `src/claude-code-session.ts`: Claude Agent SDK service for streamed runs, abort, model, effort, launch profiles, attachments, and handback.
 - `src/session-registry.ts`: per-chat/topic session registry and persisted context metadata.
+- `test/agent-adapter-contract.test.ts`: shared adapter contract coverage for descriptors, capability flags, reasoning options, launch profiles, and `AgentSessionService` method parity.
 - `src/session-format.ts`: compact Telegram rendering for session details, token usage, and limits.
 - `src/codex-state.ts`: reader for Codex `~/.codex/state_*.sqlite` thread, workspace, model, reasoning, sandbox, and approval metadata.
 - `src/pi-state.ts`: reader for Pi session JSONL files, activity timelines, diagnostics, and external busy detection.