mirror of
https://github.com/Studio-Saelix/sencho.git
synced 2026-08-12 11:47:11 +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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user