Skip to content

feat: virtual demo endpoints + Settings UX overhaul (closes #211)#214

Merged
rado0x54 merged 9 commits into
developfrom
feat/demo-endpoints
May 18, 2026
Merged

feat: virtual demo endpoints + Settings UX overhaul (closes #211)#214
rado0x54 merged 9 commits into
developfrom
feat/demo-endpoints

Conversation

@rado0x54
Copy link
Copy Markdown
Owner

@rado0x54 rado0x54 commented May 18, 2026

Closes #211.

Summary

  • Adds demoEndpoints config — virtual, config-only endpoints merged into every account's endpoint list, gated by a per-account showDemoEndpoints toggle (default on).
  • Trims onboarding to 3 steps (Welcome → Passkey → Notifications); users land in the app and see demo endpoints immediately.
  • Consolidates per-integration help into a new collapsible Settings → Setup tab and aligns the primary-action affordances across all Settings pages.
  • Renames Settings → Keys to Passkeys; file-based SSH keys split into a separate admin-only Other SSH Keys tab.
  • Demo endpoints are exposed to MCP agents (list, read, connect), and operator-supplied descriptions flow through to the MCP list_endpoints response.

What's in

Demo endpoints

  • New demoEndpoints config block (same shape as seedAdminEndpoints, plus optional description).
  • Virtual / config-only — never copied into the endpoints table; merged into GET /api/endpoints at read time via stable demo:<hash> ids.
  • New accounts.show_demo_endpoints column (migration 0008_demo_endpoints_support); default on for everyone.
  • /api/auth/me returns showDemoEndpoints + demoEndpointsAvailable so the UI hides the whole Demo section on deployments with no demo entries configured.
  • Mutation endpoints reject demo:* ids (REST + MCP) with a clear "read-only" error.
  • Audit log relies on the existing no-FK design — demo session rows resolve labels at read time from the merged live list.
  • seedAdminEndpoints also gains the optional description field, plumbed through to the seed insert.

MCP integration

  • AgentSession.listEndpoints() merges demo entries when the account's toggle is on.
  • AgentSession.createSession() resolves demo:* ids via the synthesizer, so agents can open demo sessions.
  • shellwatch_manage_endpoints list/read merge demo entries (list gated by toggle; read works regardless so a known id stays resolvable); create/update/delete refuse demo:* ids.

Onboarding

  • Stripped Server Setup, Endpoints, MCP/API key, and Advanced steps.

Settings → Setup tab (new)

  • Five collapsible cards: SSH Server, Endpoint Setup, MCP Client, ShellWatch Agent, ShellWatch PAM. Each carries a brief explanation and minimum-step setup; Endpoint Setup includes a full field reference (Label / Address / Description / UV / Agent Forwarding) with an explicit callout on the Description's role for MCP agents.
  • Docs footer links to docs.shellwatch.ai. Agent install link points at the agent/v* release stream on GitHub.
  • MCP URL renders the actual origin. Notes OpenSSH 10.3+ client requirement for the agent flow.

Settings → Passkeys (renamed from Keys)

  • File-based SSH keys split into a separate admin-only Other SSH Keys tab (only visible when admin AND has file keys registered).

Add Endpoint

  • When the user has no own endpoints, the modal prepends a Server Setup wizard step (sshd config + their actual passkey's authorized_keys line, scoped with the real account name).
  • Address input shows a gray shellwatch@ prefix + yellow warning on blur when no user was typed; both disappear on focus.
  • formatEndpointAddress always renders the username (even the default shellwatch) so the wire-level user is unambiguous in the UI.

Aligned action affordances

  • Add passkey / Add Endpoint / Generate API Key all live below their lists, left-aligned (.register-section pattern).
  • Generate API Key now opens a two-stage modal: form (label + scopes) → key reveal (copy once).

Sidebar

  • Demo endpoints get a demo signal-chip below the label, reusing the global .badge convention (6px accent-colored dot + lowercase text).

Out of scope (decided)

  • Per-endpoint key-delivery mechanism — withdrawn after the design conversation. The demo container handles auth via blanket-allow on a private Docker network + ForceCommand pinning. The feat /demo/authorized-keys and its revert commit in this branch document that decision.

Test plan

  • pnpm typecheck, pnpm check:svelte, pnpm lint, pnpm spdx:check clean
  • pnpm test — 336 unit tests pass (was 330)
  • pnpm test:integration — 138 integration tests pass (was 131)
  • New: src/test/integration/demo-endpoints-flow.test.ts — REST merge (toggle on/off), PUT/DELETE rejection on demo:*, POST /api/sessions opens demo regardless of toggle, 404 on unknown demo id.
  • New: extended src/mcp/server.test.ts — MCP list merges/excludes per toggle, read resolves demo regardless, create/update/delete reject demo:*.
  • Manual: walk register flow as a new user — 3 steps, lands in app, sees demo endpoints
  • Manual: with no own endpoints, Add Endpoint → server-setup wizard step; Continue → form
  • Manual: with own endpoints, Add Endpoint → form modal directly
  • Manual: Settings → Setup: each card expands/collapses; SSH Server copy buttons work
  • Manual: Settings → API Keys: Generate → form modal → key reveal modal → Copy works
  • Manual: Address input: type "host" + blur → gray shellwatch@ prefix + yellow warning; focus → both disappear
  • Manual: Demo endpoints toggle off hides them, on shows them; audit log resolves the label
  • Manual: Other SSH Keys tab visible only when admin AND has file keys
  • Manual: Vanilla deployment (no demoEndpoints in config) does NOT show the Demo section
  • Manual: MCP list_endpoints call surfaces demo entries with their description

rado0x54 added 9 commits May 17, 2026 23:40
Demo auth is now handled inside the demo container (blanket-allow on a private docker network), no per-user pubkey lookup needed. See #211.
Onboarding drops Server Setup, Endpoints, MCP and Advanced steps; users land in the app right after passkey + notifications. Endpoints page no longer carries the UV hint-block, gains an Add Endpoint wizard that prepends a Server Setup step for first-time users, and renders the default shellwatch@ prefix as a gray adornment with a warning on blur. New /settings/setup tab consolidates the lifted help content. /settings/keys renamed to Passkeys; file-based SSH keys move to a separate admin-only Other SSH Keys tab. formatEndpointAddress always renders the username so the wire-level user is unambiguous in the UI.
Add Endpoint and Generate API Key now sit below the list, left-aligned, in the same .register-section pattern as Add passkey. Generate API Key opens a form modal (label + scopes) instead of an inline form; the existing key-display modal still shows the minted key. Demo Endpoints toggle moves to sit next to the section headline instead of the right edge.
… cards

Replace the three-section Setup tab with five collapsible cards (SSH Server, Endpoint, MCP Client, ShellWatch Agent, ShellWatch PAM). Each card has a short explanation and minimum-step setup; Endpoint Setup adds a full field reference covering Label, Address, Description (with a callout on its role for MCP agents), UV, and SSH Agent Forwarding. MCP URL renders the actual origin; Agent install link points at the dedicated agent/v* release stream on GitHub; OpenSSH 10.3+ client requirement noted for the Agent flow. PAM step 3 spells out that the endpoint needs agent forwarding so SSH_AUTH_SOCK is forwarded. ServerSetupGuide placeholder shows a realistic example webauthn-sk one-liner.
…nts to MCP

SeedEndpointSchema gains an optional description (max 1000 chars), which propagates to seedAdminEndpoints inserts and to the demo-endpoint synthesizer — so operator-configured context now surfaces in MCP's list_endpoints response. AgentSession and the shellwatch_manage_endpoints tool merge demo entries into the per-account list when accounts.showDemoEndpoints is on; read resolves demo:* ids via the synthesizer; create/update/delete reject demo ids with a clear error. AgentSession.createSession also resolves demo ids so MCP-driven session opens reach demo principals.
…coverage, signal-chip badge

Hide the Demo Endpoints section + toggle on deployments with no demoEndpoints in config (new demoEndpointsAvailable field on /api/auth/me). Thread $account?.name into the wizard's ServerSetupGuide so the authorized_keys comment carries the real account, not 'user'. Sidebar gains a demo signal-chip below the endpoint label, reusing the global .badge convention. Doc comments on the showDemoEndpoints visibility-vs-auth semantics and on the seed-export side effect of formatEndpointAddress always emitting the username. Locks in the c228350 MCP demo wiring with 7 REST + 6 MCP integration tests.
Two-case unit test for the field that gates the Settings → Endpoints demo section: false when the operator configured no demoEndpoints, true when at least one is present. Behavior was indirectly exercised in demo-endpoints-flow.test.ts; this nails it down in the most direct test surface.
@rado0x54 rado0x54 merged commit e2033ef into develop May 18, 2026
16 checks passed
@rado0x54 rado0x54 deleted the feat/demo-endpoints branch May 18, 2026 12:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add public demo SSH server (ssh.shellwatch.ai) with per-user ASCII/game sessions

1 participant