@nordbyte/nordrelay 0.4.0 → 0.5.0

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,6 +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 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:
 
@@ -159,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.
@@ -178,19 +183,20 @@ Operations:
 
 - Plugin command/skill starts, stops, restarts, and inspects the connector process.
 - Manual process commands support `start`, `stop`, `restart`, `status`, and `foreground`.
-- Telegram admin commands support `/logs`, `/diagnostics`, `/restart`, and `/update`.
+- Telegram admin commands support `/logs`, `/diagnostics`, `/restart`, and `/update` for NordRelay and agent CLIs.
 - `/update` detects the install type: npm installs update with `npm install -g @nordbyte/nordrelay@latest`; source checkouts pull `origin/main`, install dependencies, run check, tests, and build, then restart.
-- `/logs` renders redacted connector and update logs with local-time timestamps, levels, file path, last-modified time, and highlighted warnings/errors.
+- `/update agents`, `/update <agent>`, `/update jobs`, `/update log <id>`, `/update cancel <id>`, and `/update input <id> <text>` manage Codex, Pi, Hermes, OpenClaw, and Claude Code updater jobs from Telegram.
+- `/logs` renders redacted connector, NordRelay update, and agent update logs with local-time timestamps, levels, file path, last-modified time, and highlighted warnings/errors.
 - Logs can be emitted as timestamped plain text or JSON records with `CONNECTOR_LOG_FORMAT`.
 - Telegram sends/edits/documents are routed through a rate-limit queue that honors Telegram retry-after responses.
 - Context metadata, queues, and preferences are written atomically with backup recovery.
 - Context metadata, queues, preferences, audit events, and locks can use JSON files or the optional SQLite state backend with `NORDRELAY_STATE_BACKEND=sqlite`.
 - Runtime config, state, and logs are written under `~/.nordrelay/`.
-- `nordrelay init` creates a private runtime config, `nordrelay doctor` validates host prerequisites, and `nordrelay web` starts a full local WebUI dashboard.
+- `nordrelay init` creates a private runtime config, `nordrelay doctor` validates host prerequisites, and `nordrelay web` starts the connector plus a full local WebUI dashboard.
 - 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.
@@ -205,6 +211,7 @@ Recommended npm setup:
 ```bash
 npm install -g @nordbyte/nordrelay
 nordrelay init
+nordrelay user list
 nordrelay doctor
 nordrelay start
 ```
@@ -214,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:
@@ -235,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
@@ -253,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:
 
@@ -270,6 +284,7 @@ Codex authentication:
 Pi setup:
 
 - Install Pi from https://pi.dev/ and confirm `pi --help` works on the host.
+- npm installs should use the current package name: `npm install -g @earendil-works/pi-coding-agent`.
 - Set `NORDRELAY_PI_ENABLED=true` in `~/.nordrelay/nordrelay.env`.
 - Keep `NORDRELAY_DEFAULT_AGENT=codex` to start chats in Codex, or set `NORDRELAY_DEFAULT_AGENT=pi` to start chats in Pi.
 - Optional: set `PI_SESSION_DIR` if your Pi sessions are not stored in `~/.pi/agent/sessions/`.
@@ -331,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:
 
@@ -354,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
 ```
@@ -374,6 +390,7 @@ Runtime files:
 - Log file: `~/.nordrelay/nordrelay.log`
 - Home override: `NORDRELAY_HOME=/custom/path`
 - Local dashboard: `nordrelay web --host 127.0.0.1 --port 31878`
+- `nordrelay start` and `nordrelay status` print the configured WebUI URL.
 
 ## WebUI Dashboard
 
@@ -383,6 +400,8 @@ Start the local WebUI:
 nordrelay web
 ```
 
+If the connector is not already running, `nordrelay web` starts it automatically before binding the dashboard.
+
 Open:
 
 ```text
@@ -403,7 +422,10 @@ The dashboard is a second NordRelay client next to Telegram. It can:
 - Browse, preview, download, ZIP, and delete artifacts.
 - Inspect the activity timeline for WebUI and mirrored CLI turns.
 - Edit all supported runtime settings from tabbed Settings groups with option selects, validation feedback, and restart actions.
-- View filtered logs, structured diagnostics, enabled channels, and agent adapters.
+- 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, 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`.
 
@@ -412,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:
 
@@ -431,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
 
@@ -440,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.
@@ -463,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.
@@ -490,12 +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 all [lines]` shows connector and self-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.
+- `/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
 
@@ -678,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`.
@@ -698,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:
 
@@ -721,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:
@@ -820,6 +836,7 @@ NordRelay wrapper:
 - `NORDRELAY_HOME`: config/state/log directory override. Defaults to `~/.nordrelay`.
 - `NORDRELAY_SOURCE_ROOT`: runtime source root override. Useful when the plugin is launched from Codex cache.
 - `NORDRELAY_UPDATE_METHOD`: optional `auto`, `npm`, or `git` self-update method override. Auto uses git when the runtime root has a `.git` directory and npm otherwise.
+- Agent updates from the dashboard and Telegram use each agent's native updater where possible: `codex update`, `pi update pi`, `hermes update --yes`, `openclaw update --yes`, and `claude update`.
 - `NORDRELAY_KEEP_PENDING_UPDATES`: set true to avoid dropping pending Telegram updates on start.
 - `NORDRELAY_FORWARD_TOOL_OUTPUT`: backward-compatible alias that sets `TOOL_VERBOSITY=all` when `TOOL_VERBOSITY` is unset.
 - `NORDRELAY_STATE_FILE`: internal state-file path passed by the wrapper.
@@ -859,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.
 
@@ -1023,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.

package/dist/access-control.js

@@ -1,11 +1,68 @@
-const ALL_PERMISSIONS = [
+import { permissionForWebRequestFromContract } from "./web-api-contract.js";
+export const ALL_PERMISSIONS = [
     "inspect",
-    "sessions",
-    "prompt",
-    "files",
-    "settings",
-    "auth",
-    "admin",
+    "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",
+    "audit.read",
+];
+export const ADMIN_GROUP_ID = "admin";
+export const USER_GROUP_ID = "user";
+export const READONLY_GROUP_ID = "readonly";
+export const BUILTIN_GROUPS = [
+    {
+        id: ADMIN_GROUP_ID,
+        name: "Admin",
+        description: "Full access to every NordRelay feature, user management, updates, and system controls.",
+        permissions: ALL_PERMISSIONS,
+        system: true,
+    },
+    {
+        id: USER_GROUP_ID,
+        name: "User",
+        description: "Normal read/write use of agents, sessions, prompts, files, and personal agent auth.",
+        permissions: [
+            "inspect",
+            "sessions.read",
+            "sessions.write",
+            "prompt.send",
+            "prompt.abort",
+            "files.read",
+            "files.write",
+            "settings.read",
+            "auth.manage",
+            "queue.read",
+            "queue.write",
+        ],
+        system: true,
+    },
+    {
+        id: READONLY_GROUP_ID,
+        name: "Read Only",
+        description: "Read-only access to status, sessions, activity, and artifacts.",
+        permissions: [
+            "inspect",
+            "sessions.read",
+            "files.read",
+            "settings.read",
+        ],
+        system: true,
+    },
 ];
 const COMMAND_PERMISSIONS = new Map([
     ["start", "inspect"],
@@ -15,138 +72,93 @@ const COMMAND_PERMISSIONS = new Map([
     ["version", "inspect"],
     ["channels", "inspect"],
     ["agents", "inspect"],
-    ["diagnostics", "admin"],
     ["tasks", "inspect"],
     ["progress", "inspect"],
-    ["activity", "inspect"],
-    ["audit", "admin"],
-    ["mirror", "settings"],
-    ["notify", "settings"],
-    ["workspaces", "sessions"],
-    ["voice", "inspect"],
-    ["agent", "settings"],
-    ["session", "sessions"],
-    ["sessions", "sessions"],
-    ["switch", "sessions"],
-    ["pinned", "sessions"],
-    ["pin", "sessions"],
-    ["unpin", "sessions"],
-    ["attach", "sessions"],
-    ["handback", "sessions"],
-    ["new", "sessions"],
-    ["sync", "sessions"],
-    ["lock", "sessions"],
-    ["unlock", "sessions"],
-    ["locks", "sessions"],
-    ["queue", "inspect"],
-    ["cancel", "prompt"],
-    ["clearqueue", "prompt"],
-    ["retry", "prompt"],
-    ["abort", "prompt"],
-    ["stop", "prompt"],
-    ["artifacts", "files"],
-    ["launch", "settings"],
-    ["launch_profiles", "settings"],
-    ["launch-profiles", "settings"],
-    ["fast", "settings"],
-    ["model", "settings"],
-    ["reasoning", "settings"],
-    ["effort", "settings"],
+    ["activity", "sessions.read"],
     ["auth", "inspect"],
-    ["login", "auth"],
-    ["logout", "auth"],
-    ["logs", "admin"],
-    ["restart", "admin"],
-    ["update", "admin"],
+    ["voice", "inspect"],
+    ["whoami", "inspect"],
+    ["diagnostics", "diagnostics.read"],
+    ["logs", "logs.read"],
+    ["audit", "audit.read"],
+    ["restart", "system.restart"],
+    ["update", "updates.run"],
+    ["workspaces", "sessions.read"],
+    ["session", "sessions.read"],
+    ["sessions", "sessions.read"],
+    ["pinned", "sessions.read"],
+    ["locks", "sessions.read"],
+    ["queue", "queue.read"],
+    ["artifacts", "files.read"],
+    ["agent", "settings.write"],
+    ["mirror", "settings.write"],
+    ["notify", "settings.write"],
+    ["launch", "settings.write"],
+    ["launch_profiles", "settings.write"],
+    ["launch-profiles", "settings.write"],
+    ["fast", "settings.write"],
+    ["model", "settings.write"],
+    ["reasoning", "settings.write"],
+    ["effort", "settings.write"],
+    ["login", "auth.manage"],
+    ["logout", "auth.manage"],
+    ["new", "sessions.write"],
+    ["switch", "sessions.write"],
+    ["attach", "sessions.write"],
+    ["handback", "sessions.write"],
+    ["sync", "sessions.write"],
+    ["pin", "sessions.write"],
+    ["unpin", "sessions.write"],
+    ["lock", "sessions.write"],
+    ["unlock", "sessions.write"],
+    ["retry", "prompt.send"],
+    ["clearqueue", "queue.write"],
+    ["cancel", "queue.write"],
+    ["abort", "prompt.abort"],
+    ["stop", "prompt.abort"],
+    ["register_chat", "users.write"],
+    ["chat_access", "users.write"],
+    ["link", "inspect"],
 ]);
-export function createDefaultRolePolicies() {
-    return {
-        admin: new Set(ALL_PERMISSIONS),
-        operator: new Set(["inspect", "sessions", "prompt", "files", "settings", "auth"]),
-        readonly: new Set(["inspect", "sessions"]),
-    };
-}
-export function parseRolePoliciesJson(raw) {
-    const policies = createDefaultRolePolicies();
-    if (!raw) {
-        return policies;
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch (error) {
-        throw new Error(`Invalid TELEGRAM_ROLE_POLICIES_JSON: ${error instanceof Error ? error.message : String(error)}`);
-    }
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-        throw new Error("TELEGRAM_ROLE_POLICIES_JSON must be an object keyed by role");
-    }
-    for (const [role, rawPermissions] of Object.entries(parsed)) {
-        if (!isTelegramRole(role)) {
-            throw new Error(`Invalid TELEGRAM_ROLE_POLICIES_JSON role: ${role}`);
-        }
-        policies[role] = parsePermissionList(rawPermissions, role);
-    }
-    if (!policies.admin.has("admin")) {
-        policies.admin.add("admin");
-    }
-    return policies;
-}
-export function hasTelegramPermission(policies, role, permission) {
-    return policies[role].has(permission) || policies[role].has("admin");
-}
 export function permissionForCommand(command) {
     if (!command) {
-        return "inspect";
+        return null;
     }
-    return COMMAND_PERMISSIONS.get(command.toLowerCase()) ?? "inspect";
+    return COMMAND_PERMISSIONS.get(command.toLowerCase()) ?? null;
 }
 export function permissionForCallbackData(callbackData) {
     if (!callbackData) {
-        return "inspect";
+        return null;
     }
     if (callbackData === "noop_page") {
         return "inspect";
     }
     if (/^(sess_|ws_)/.test(callbackData)) {
-        return "sessions";
+        return "sessions.write";
     }
     if (/^(launch_|launchconfirm_|model_|effort_|agent_)/.test(callbackData)) {
-        return "settings";
+        return "settings.write";
+    }
+    if (callbackData.startsWith("upd_")) {
+        return "updates.run";
     }
     if (callbackData.startsWith("approval_") || callbackData.startsWith("codex_abort:") || callbackData.startsWith("agent_abort:")) {
-        return "prompt";
+        return "prompt.abort";
     }
     if (callbackData.startsWith("queue_")) {
-        return "prompt";
+        return "queue.write";
+    }
+    if (callbackData.startsWith("artifact_delete")) {
+        return "files.write";
     }
     if (callbackData.startsWith("artifact_")) {
-        return "files";
+        return "files.read";
     }
-    return "inspect";
-}
-export function isTelegramRole(value) {
-    return value === "admin" || value === "operator" || value === "readonly";
+    return null;
 }
-function parsePermissionList(rawPermissions, role) {
-    if (rawPermissions === "*") {
-        return new Set(ALL_PERMISSIONS);
-    }
-    if (!Array.isArray(rawPermissions)) {
-        throw new Error(`TELEGRAM_ROLE_POLICIES_JSON.${role} must be an array or "*"`);
-    }
-    const permissions = new Set();
-    for (const rawPermission of rawPermissions) {
-        if (rawPermission === "*") {
-            return new Set(ALL_PERMISSIONS);
-        }
-        if (typeof rawPermission !== "string" || !isTelegramPermission(rawPermission)) {
-            throw new Error(`Invalid TELEGRAM_ROLE_POLICIES_JSON permission for ${role}: ${String(rawPermission)}`);
-        }
-        permissions.add(rawPermission);
-    }
-    return permissions;
+export function permissionForWebRequest(method, pathname) {
+    return permissionForWebRequestFromContract(method, pathname);
 }
-function isTelegramPermission(value) {
+export function isPermission(value) {
     return ALL_PERMISSIONS.includes(value);
 }