mirror of
https://github.com/Studio-Saelix/sencho.git
synced 2026-08-11 19:26:56 +00:00
feat: graduate Host Console to Community admins (#1669)
* feat: graduate Host Console to Community admins Make Host Console available to Community and Admiral admins (system:console), add host-console-community for mixed fleets, and keep opaque API tokens off the host shell. * docs: document Host Console deep links Cover root and stack-scoped Console URLs, correct the phone treatment note, and pin parse/build round-trips in senchoRoute tests. * fix: bind Host Console socket to the resolved node Treat unresolved activeNode as loading, target the WebSocket with an explicit nodeId, and wait for stack deep-link hydration so the shell cannot open on the wrong node or compose root. Add regression coverage for node/stack retargeting and fail-closed directory resolution. * fix: harden Host Console node binding, audit acting_as, and console_session tokens Reject unknown or malformed nodeIds before spawning a PTY. Record hub operators in audit_log.acting_as for remote console_session bridges. Path-scope and one-time-consume console_session JWTs so Host Console mints cannot open container exec or be replayed. * test: expect acting_as in audit CSV export header Align the CSV export assertion with the P0-2B acting_as column added to audit log exports.
This commit is contained in:
Anso
@@ -171,7 +171,7 @@ Authorises every read and every write the API exposes, **except** the universal
|
||||
| `/api/stacks/:stack/logs` (stack log stream) | yes | yes | yes |
|
||||
| `/ws/notifications` (notification stream) | yes | yes | yes |
|
||||
| `/ws` (generic exec / stats) | no | no | yes |
|
||||
| `/api/system/host-console` (host shell) | no | no | yes |
|
||||
| `/api/system/host-console` (host shell) | no | no | no |
|
||||
|
||||
A Read Only or Deploy Only token attempting an out-of-scope WebSocket upgrade is rejected with `403 Forbidden` before any frames flow.
|
||||
|
||||
@@ -268,7 +268,7 @@ API tokens are issued and revoked on the hub that authenticates the call. When y
|
||||
- **One owner per token.** Tokens are not shareable across users at the data model; only the creating user can revoke a token through the UI.
|
||||
- **Owner deletion breaks the token.** If the user who created a token is deleted, subsequent calls with that token return `401` because the auth path requires the creator to still exist. Rotate before deleting accounts.
|
||||
- **No token introspection endpoint.** There is no `GET /api/me` for an API token; client code must know its own scope.
|
||||
- **WebSocket scope restrictions.** Read Only and Deploy Only tokens cannot reach the generic `/ws` exec/stats endpoint or the host console. Full Admin can.
|
||||
- **WebSocket scope restrictions.** Read Only and Deploy Only tokens cannot reach the generic `/ws` exec/stats endpoint or the host console. Full Admin can reach `/ws` (container exec / stats) but not Host Console; Host Console always requires a signed-in browser session.
|
||||
|
||||
## Common workflows
|
||||
|
||||
|
||||
@@ -23,7 +23,8 @@ Sencho encodes the active node, the view you are on, and the deep state that vie
|
||||
| App Store | `/nodes/local/templates` | App Store on the active node |
|
||||
| Logs | `/nodes/local/logs` | Cross-fleet log aggregation |
|
||||
| Update | `/nodes/local/updates` | Fleet-wide update check |
|
||||
| Console | `/nodes/local/host-console` | Host Console, a limited-availability operator surface documented on its own page when enabled on an instance |
|
||||
| Console | `/nodes/local/host-console` | Host Console (admin role) |
|
||||
| Console in a stack | `/nodes/local/host-console/radarr` | Host Console rooted in the Radarr stack directory |
|
||||
| Audit | `/nodes/local/audit` | Audit history |
|
||||
| Settings section | `/nodes/local/settings/nodes` | Settings on the Nodes section |
|
||||
| Fleet tab | `/nodes/local/fleet/snapshots` | Fleet on the Snapshots tab (desktop) |
|
||||
@@ -86,7 +87,7 @@ On desktop, opening the stack list at `/nodes/local/stacks` canonicalizes to `/n
|
||||
|
||||
Settings follows a similar split, but only on a phone: `/nodes/local/settings` opens the section list, and `/nodes/local/settings/<section>` opens a section directly. On desktop, `/nodes/local/settings` always normalizes straight to `/nodes/local/settings/appearance`; there is no bare section-list state to land on.
|
||||
|
||||
Fleet, Resources, Security, App Store, Logs, Update, Audit, and Schedules keep the exact same URL between desktop and phone, each rendering a phone-optimized screen at that path. Console also keeps the same URL on a phone, reflowing the terminal rather than switching to a dedicated phone screen.
|
||||
Fleet, Resources, Security, App Store, Logs, Update, Audit, and Schedules keep the exact same URL between desktop and phone, each rendering a phone-optimized screen at that path. Console also keeps the same URL on a phone (`/nodes/<node>/host-console`), but Host Console is a desktop-oriented terminal: open it on a wider screen for a full interactive session.
|
||||
|
||||
On a phone, `/nodes/local/stacks/<stack>/files` opens the compose editor instead. Sencho does not expose a separate file-browser URL on a phone.
|
||||
|
||||
|
||||
@@ -26,7 +26,7 @@ The palette groups results into three sections.
|
||||
|
||||
| Group | What it contains | What happens when you pick one |
|
||||
|-------|------------------|--------------------------------|
|
||||
| **Pages** | The reachable page destinations for your tier and role (the same set Classic / Smart / mobile navigation use). **Home**, **Resources**, **Networking**, **Security**, and **App Store** appear for signed-in operators; **Fleet** appears when your role holds the `node:read` permission; **Logs**, **Update**, and **Schedules** appear for admins; **Console** is a limited-availability operator surface shown when enabled on an instance; **Audit** appears on Admiral for any role with the `system:audit` permission. See [RBAC & User Management](/features/rbac) for the full permission matrix. | Navigates to that page |
|
||||
| **Pages** | The reachable page destinations for your tier and role (the same set Classic / Smart / mobile navigation use). **Home**, **Resources**, **Networking**, **Security**, and **App Store** appear for signed-in operators; **Fleet** appears when your role holds the `node:read` permission; **Logs**, **Update**, **Schedules**, and **Console** appear for admins; **Audit** appears on Admiral for any role with the `system:audit` permission. See [RBAC & User Management](/features/rbac) for the full permission matrix. | Navigates to that page |
|
||||
| **Nodes** | Every node in your fleet, with a green dot for online and a grey dot for offline. The currently active node carries a small **ACTIVE** chip on the right. | Switches the active node without leaving the current page |
|
||||
| **Stacks** | Every compose stack on every online node, matched on the compose filename (extension included). | Switches to the stack's node and opens it in the editor |
|
||||
|
||||
|
||||
@@ -6,7 +6,7 @@ description: An interactive terminal on your host OS, directly in the browser -
|
||||
The **Console** tab opens a full interactive terminal session on the machine running Sencho. It behaves exactly like an SSH session, but without needing an SSH server, client, or key management.
|
||||
|
||||
<Note>
|
||||
The Host Console is a limited-availability operator surface. When it is present on an instance, it requires the **admin** role. [Learn more about licensing](/features/licensing).
|
||||
Host Console requires the **admin** role. [Learn more about roles](/features/rbac).
|
||||
</Note>
|
||||
|
||||
<Frame>
|
||||
@@ -27,6 +27,14 @@ The Host Console gives you a real terminal session on the Sencho host, streamed
|
||||
|
||||
Click **Console** in the top navigation bar. The session starts immediately in the `COMPOSE_DIR` root. If a stack is selected in the sidebar, the terminal opens directly inside that stack's directory instead, and a small back button appears in the masthead so you can return to the stack editor.
|
||||
|
||||
You can also open Console from a bookmark or shared link. Every Console view has a stable URL under [Deep links and URLs](/features/deep-links):
|
||||
|
||||
- `/nodes/local/host-console` opens Host Console on the local node at the compose root
|
||||
- `/nodes/local/host-console/radarr` opens the same terminal rooted in the Radarr stack directory
|
||||
- Remote nodes use their node slug the same way (for example `/nodes/nas-box-42/host-console`)
|
||||
|
||||
Console requires the **admin** role. The URL stays in the address bar on a phone, but Host Console is meant for a desktop browser.
|
||||
|
||||
## Cockpit layout
|
||||
|
||||
The Console page is a vertical stack of two surfaces.
|
||||
@@ -74,9 +82,9 @@ Environment variables whose names suggest secrets (passwords, tokens, keys, cred
|
||||
|
||||
The Host Console is one of the most powerful features in Sencho and is treated as such:
|
||||
|
||||
- **Admin role required when present.** The Host Console is a limited-availability surface; only users with the **admin** role can open a console session.
|
||||
- **Admin role required.** Only users with the **admin** role can open a console session.
|
||||
- **Browser sessions only.** Console sessions are only available from a signed-in browser session, not from API tokens.
|
||||
- **Audited.** Every console session is recorded in the audit log. Opening and closing a session each write an entry capturing the user, node, client IP, and timestamp, so shell access is fully accountable.
|
||||
- **Audited.** Every console session is recorded in the audit log. Opening and closing a session each write an entry with the session principal, node, client IP, and timestamp. When the session is opened through a remote hub bridge, the principal is `console_session` and the hub operator is recorded in `acting_as`, so remote shell access stays accountable to the signed-in admin.
|
||||
|
||||
<Warning>
|
||||
The Host Console provides unrestricted shell access to the machine running Sencho. Do not expose Sencho on a public network without HTTPS and strong authentication.
|
||||
@@ -97,7 +105,7 @@ The Host Console is one of the most powerful features in Sencho and is treated a
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Session ends immediately after connecting">
|
||||
This typically means the shell could not be found on the host. In a Docker deployment, ensure `bash` or `sh` is available inside the container. You can check by running `docker exec <container> which bash` from the host. Also verify that your user has the **admin** role and that Console is available on this instance.
|
||||
This typically means the shell could not be found on the host. In a Docker deployment, ensure `bash` or `sh` is available inside the container. You can check by running `docker exec <container> which bash` from the host. Also verify that your user has the **admin** role.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Connection drops after a short time">
|
||||
@@ -105,6 +113,6 @@ The Host Console is one of the most powerful features in Sencho and is treated a
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Console tab is not visible">
|
||||
Console appears only when the surface is present on the instance, and only for users with the **admin** role. Verify those conditions are met, then refresh the page.
|
||||
Console appears for users with the **admin** role. If you are an admin and still do not see it, refresh the page. On a remote node, the Console tab may show a lock card when that node does not support Host Console (for example a Pilot Agent node, or a Distributed API Proxy node that does not advertise Host Console).
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@@ -236,7 +236,7 @@ Bearer tokens grant full control over the remote Sencho instance. Treat them lik
|
||||
|
||||
- **Rotate immediately** if a token is compromised: open the remote instance's **Settings → Infrastructure → Nodes** and click **Generate Token** to mint a new one. The previous token is invalidated instantly.
|
||||
- Tokens are **encrypted at rest** in the local SQLite database.
|
||||
- Tokens cannot be used to open interactive terminals (Host Console or container exec). Interactive shell access always requires a real browser session on that specific instance.
|
||||
- Tokens cannot be used to open interactive terminals (Host Console or container exec). Interactive shell access requires a signed-in browser session. From the control plane you can open Host Console on a compatible Distributed API Proxy remote; Pilot Agent remotes do not offer Host Console.
|
||||
|
||||
### Transport encryption
|
||||
|
||||
|
||||
@@ -67,7 +67,8 @@ Every Sencho release ships with a static list of capabilities. The current list
|
||||
| `notifications` | Alert notifications |
|
||||
| `notification-routing` | Notification routing rules |
|
||||
| `notification-suppression` | Mute rules |
|
||||
| `host-console` | Host Console |
|
||||
| `host-console` | Host Console (legacy advertisement retained for mixed-version fleets) |
|
||||
| `host-console-community` | Host Console without a paid-license requirement on this node |
|
||||
| `container-exec` | Container exec terminal |
|
||||
| `audit-log` | Audit log |
|
||||
| `scheduled-ops` | Scheduled operations |
|
||||
@@ -94,7 +95,7 @@ Every Sencho release ships with a static list of capabilities. The current list
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
A node connected in [Pilot Agent](/features/multi-node#add-a-remote-node-pilot-agent) mode never advertises `host-console`, even after upgrading, because that feature's control-to-agent path is not yet wired through the enrollment tunnel. This is the one capability gap that upgrading the node cannot close; it only closes on a Distributed API Proxy connection.
|
||||
A node connected in [Pilot Agent](/features/multi-node#add-a-remote-node-pilot-agent) mode never advertises `host-console` or `host-console-community`, even after upgrading, because that feature's control-to-agent path is not yet wired through the enrollment tunnel. This is the one capability gap that upgrading the node cannot close; it only closes on a Distributed API Proxy connection.
|
||||
</Note>
|
||||
|
||||
A handful of capabilities gate a smaller piece of behavior rather than a whole panel, so a missing one falls back to an older behavior instead of a lock card:
|
||||
|
||||
@@ -210,7 +210,7 @@ When you manage nodes running different Sencho versions, the dashboard detects e
|
||||
|
||||
### Host console
|
||||
|
||||
Open an interactive terminal on the host OS directly in the browser with full xterm.js emulation and color support. No SSH client required. Limited-availability surface when present; admin role required. [Learn more →](/features/host-console)
|
||||
Open an interactive terminal on the host OS directly in the browser with full xterm.js emulation and color support. No SSH client required. Admin role required. [Learn more →](/features/host-console)
|
||||
|
||||
## Security and access
|
||||
|
||||
|
||||
@@ -34,7 +34,7 @@ The **Home** view is the default landing page. It is designed for a fast operati
|
||||
- The activity panel shows **Fleet Heartbeat** when remote nodes exist, or **Stack Restarts (7d)** on a local-only install.
|
||||
- **Recent Alerts** shows the latest notification feed and includes **Clear All Notifications** when there is anything to clear.
|
||||
|
||||
The top navigation starts with **Home**, **Resources**, **Networking**, **Security**, and **App Store**. **Fleet** appears when your role can read nodes. Additional operator views (**Logs**, **Update**, **Schedules**, and **Audit**) appear based on your role and license tier. **Console** is a limited-availability operator surface documented on its own page when enabled on an instance. Fleet-wide views describe the control instance, so they are hidden while a remote node is active. Choose Classic, Smart, or Compact desktop navigation under **Settings → Appearance → Navigation**; phone navigation stays on its own layout.
|
||||
The top navigation starts with **Home**, **Resources**, **Networking**, **Security**, and **App Store**. **Fleet** appears when your role can read nodes. Additional operator views (**Logs**, **Update**, **Schedules**, and **Console**) appear for admins. **Audit** appears based on your role and license tier. Fleet-wide views describe the control instance, so they are hidden while a remote node is active. Choose Classic, Smart, or Compact desktop navigation under **Settings → Appearance → Navigation**; phone navigation stays on its own layout.
|
||||
|
||||
## Stack workspace
|
||||
|
||||
|
||||
@@ -107,7 +107,7 @@ You land on **Home**, the default operational view. The health masthead reports
|
||||
|
||||
Below the stack table, **Configuration Status** summarizes notifications, alerts, automation, security, backups, thresholds, and crash detection. The neighboring activity card shows **Fleet Heartbeat** when remote nodes exist, or **Stack Restarts (7d)** on a local-only install. **Recent Alerts** shows the latest notification feed and includes **Clear All Notifications** when there is anything to clear.
|
||||
|
||||
On the local node, baseline top navigation includes **Home**, **Resources**, **Networking**, **Security**, and **App Store**. **Fleet** appears when your role can read nodes. **Logs**, **Update**, and **Schedules** appear for admins. **Console** and **Audit** depend on license, role, and whether those surfaces are enabled; hub-only views are hidden when a remote node is active. Desktop presentation (Classic bar, Smart bar, or Compact launcher) is chosen under **Settings → Appearance → Navigation**. The right side of the top bar holds global search, notifications, and the profile menu entries **Settings**, **Billing** (when a paid license is active), **Documentation**, **Open New Issue**, and **Log Out**.
|
||||
On the local node, baseline top navigation includes **Home**, **Resources**, **Networking**, **Security**, and **App Store**. **Fleet** appears when your role can read nodes. **Logs**, **Update**, **Schedules**, and **Console** appear for admins. **Audit** depends on license and role; hub-only views are hidden when a remote node is active. Desktop presentation (Classic bar, Smart bar, or Compact launcher) is chosen under **Settings → Appearance → Navigation**. The right side of the top bar holds global search, notifications, and the profile menu entries **Settings**, **Billing** (when a paid license is active), **Documentation**, **Open New Issue**, and **Log Out**.
|
||||
|
||||
The left sidebar is the stack workspace. Below the Sencho brand, it starts with the node switcher, then **Create Stack**, a bulk-mode toggle, and **Scan stacks folder** for re-indexing compose projects added outside Sencho. Use **Search stacks...** with the **All**, **Up**, **Down**, and **Updates** chips to narrow the list. On a fresh install with an empty stack list, Sencho scans your mounted compose directory automatically and shows what it found, including compose files that still need to be adopted into their own subfolder. Once stacks carry Docker Compose labels, the list groups them under those labels, with pinned stacks always floating to the top and unlabeled stacks collected at the bottom.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user