jsgui3-server 0.0.149 → 0.0.150

package/docs/books/admin-ui-authentication/03-auth-middleware-patterns.md

@@ -0,0 +1,77 @@
+# Chapter 3 — Auth Middleware Patterns for jsgui3-server
+
+## Goal
+
+Establish stable authorization guard patterns now, so future write endpoints can be added safely without redesign.
+
+## Current guard model (implemented)
+
+Admin v1 now uses explicit guard helpers in the server adapter:
+
+- authentication guard
+- role guard
+- read-role guard (`admin_read`)
+- write-role guard (`admin_write`)
+
+This keeps route registration simple and prevents ad-hoc per-endpoint checks.
+
+## Route policy baseline
+
+### Public routes
+
+- `/admin/v1/login`
+- `POST /api/admin/v1/auth/login`
+- `POST /api/admin/v1/auth/logout`
+- `GET /api/admin/v1/auth/session`
+
+### Protected read routes (`admin_read`)
+
+- `/admin/v1`
+- `GET /api/admin/v1/status`
+- `GET /api/admin/v1/resources`
+- `GET /api/admin/v1/routes`
+- `GET /api/admin/v1/events`
+
+### Reserved write route class (`admin_write`)
+
+No mutation endpoints are enabled yet, but all future write endpoints should require `admin_write` at minimum.
+
+## Guard usage pattern
+
+Use the guard wrapper at route-registration time:
+
+- read routes use read guard
+- write routes use write guard
+
+This keeps endpoint code focused on business behavior and leaves authz behavior centralized.
+
+## Response semantics
+
+- `401 Unauthorized`: no valid session.
+- `403 Forbidden`: valid session, insufficient role.
+
+These semantics are stable and should remain consistent for all future admin endpoints.
+
+## SSE policy
+
+SSE endpoint is protected by the same read-role guard.
+
+Rationale:
+- event streams can reveal sensitive internal state,
+- role checks must be equivalent to read API checks.
+
+## Next step for write endpoints
+
+When adding first mutation routes:
+
+1. register route under `/api/admin/v1/...`
+2. wrap with write-role guard
+3. add CSRF requirement before enabling browser write actions
+4. add audit logging for successful and failed mutation attempts
+
+## Minimal acceptance checklist for new admin endpoints
+
+- Has explicit required role (`admin_read` or `admin_write`)
+- Returns 401/403 correctly
+- No accidental fallback to auth-only checks
+- Included in endpoint inventory docs

package/docs/books/admin-ui-authentication/README.md

@@ -0,0 +1,25 @@
+# Admin UI Authentication for jsgui3-server
+
+This book introduces a practical, phased approach to securing the Admin UI.
+
+## Status
+
+This book is intentionally started early (before a final auth architecture decision) so implementation can proceed safely in phases.
+
+## Chapters
+
+1. [Threat model and goals](01-threat-model-and-goals.md)
+2. [Session model and token model](02-session-model-and-token-model.md)
+3. [Auth middleware patterns in jsgui3-server](03-auth-middleware-patterns.md)
+4. Login flow and logout flow (planned)
+5. Authorization and role checks (planned)
+6. CSRF, cookies, and browser hardening (planned)
+7. SSE authentication and revocation handling (planned)
+8. Operational rollout and migration plan (planned)
+
+## Scope for v1 Admin
+
+Until authentication is fully implemented:
+- Keep the admin UI read-only where possible.
+- Avoid privileged write-actions from browser controls.
+- Document all intended mutation endpoints before building them.

package/docs/books/creating-a-new-admin-ui/01-introduction-and-vision.md

@@ -0,0 +1,130 @@
+# Chapter 1: Introduction & Vision
+
+## Why an Admin UI?
+
+Every non-trivial server benefits from introspection. When a developer starts a jsgui3-server — whether it's a single-control demo, a multi-page application, or an API-only service — there is a wealth of internal state that is invisible from the outside:
+
+- How many resources are loaded, and are they healthy?
+- What routes have been registered, and by which publishers?
+- How large is the bundled JavaScript? The extracted CSS?
+- Is the build system working? Are there warnings?
+- Which processes are running? What is their memory consumption?
+- What observables are being published? How many clients are connected?
+
+Today, to answer any of these questions, a developer must either read console output, attach a debugger, or write custom telemetry code. The Admin UI changes this entirely.
+
+## Vision Statement
+
+**Navigate to `/admin` on any running jsgui3-server instance and immediately see everything the server knows about itself — in real time, with no configuration required.**
+
+The Admin UI is:
+
+1. **Built-in** — Ships with jsgui3-server. No extra `npm install`, no separate process, no configuration file.
+2. **Real-time** — Uses the server's own SSE and Observable infrastructure to push live updates to the browser.
+3. **Honest** — Shows only data that actually exists within the running system. No mocked values, no placeholder counts.
+4. **Dogfooded** — Constructed entirely from jsgui3 controls (div, span, h2, Panel, Button, etc.). The admin UI itself is validation that the control system works.
+5. **Safe** — Defaults to read-only. Destructive actions (restart, stop) require deliberate interaction and are guarded behind confirmation.
+
+## Audience
+
+The primary users of the Admin UI are:
+
+- **Developers** building applications with jsgui3-server during local development
+- **DevOps engineers** monitoring deployed instances
+- **Framework contributors** debugging jsgui3-server internals
+- **Curious users** who want to understand what's happening inside their server
+
+## Design Inspiration
+
+The visual design draws from Windows Aero-era interfaces — a distinctive aesthetic that communicates professionalism and polish:
+
+- **Glass-effect title bars** with gradient fills and subtle transparency
+- **Warm parchment content areas** (`#F0EDE6` → `#E8E4DC`) rather than pure white
+- **Group boxes** with inset labels — a classic UI pattern for organizing related controls
+- **Tabbed panels** for switching between related views without navigation
+- **Status bar** at the bottom with segmented information panels
+- **Subtle drop shadows** and rounded corners that add depth without distraction
+
+This aesthetic was chosen deliberately — it is visually distinct from the "flat design" dashboards common today, giving jsgui3-server its own identity while still being functional and readable.
+
+## Scope — What the Admin UI Is and Is Not
+
+### What it IS:
+
+- A dashboard showing server state, routes, processes, resources, and build output
+- A log viewer with real-time streaming
+- A route and API explorer
+- A configuration viewer (and, where safe, editor)
+- A process manager with start/stop/restart controls
+
+### What it is NOT:
+
+- A replacement for a full monitoring stack (Prometheus, Grafana, etc.)
+- A code editor or IDE
+- A database administration tool
+- A user authentication/authorization management system
+
+The Admin UI occupies the space between "console.log" and "full observability platform." It gives developers immediate insight into their server without leaving the browser.
+
+## The `/admin` Route
+
+When jsgui3-server starts, it automatically:
+
+1. Loads the `Admin_Module` from `admin-ui/v1/server.js`
+2. Attaches telemetry API endpoints under `/api/admin/*`
+3. Renders the admin UI control and serves it at `/admin`
+4. Sets up SSE endpoints for real-time data push
+
+No code change is needed in the user's application. The admin UI is always available.
+
+```
+http://localhost:8080/admin    ← Full admin dashboard
+http://localhost:8080/         ← User's application (unchanged)
+```
+
+## Versioning Strategy
+
+The admin UI lives in `admin-ui/v1/`. This explicit versioning allows:
+
+- **Parallel iteration** — A `v2/` can be developed while `v1/` remains stable
+- **A/B comparison** — Both versions can be served simultaneously for comparison
+- **Safe rollback** — If `v2/` has issues, `v1/` is always available
+- **Independent release** — The admin UI can evolve at its own pace
+
+## What Success Looks Like
+
+A developer creates a simple jsgui3-server application:
+
+```javascript
+const Server = require('jsgui3-server');
+Server.serve({
+    Ctrl: My_App,
+    port: 8080
+});
+```
+
+They navigate to `http://localhost:8080/admin` and see:
+
+- **3 stat cards** showing PID, resource count, and route count
+- **A process panel** with the main server process and any child processes
+- **A resource table** listing every resource in the pool with health status
+- **A route table** showing all registered HTTP routes with their handler types
+- **A build section** with JS bundle size, CSS size, and build timing
+- **A live activity log** streaming recent requests and events
+
+All of this appears automatically, populated with real data from the running server, updating in real time as the server handles requests.
+
+## Relationship to Existing Admin UI
+
+The existing `admin-ui/` directory contains a preliminary implementation with:
+- A sidebar/content shell in `admin-ui/client.js`
+- Basic API endpoints in `admin-ui/server.js` for resources and observables
+
+The `v1/` implementation builds on the lessons learned from this prototype while introducing:
+- Domain-specific controls (not just generic divs)
+- A comprehensive telemetry adapter layer
+- Real-time SSE-driven updates
+- The Aero-inspired visual design
+- A structured navigation system with multiple views
+
+The existing code in `admin-ui/client.js` and `admin-ui/server.js` remains as the current implementation. The `v1/` directory is a fresh start that will eventually replace it.

package/docs/books/creating-a-new-admin-ui/02-architecture-and-data-flow.md

@@ -0,0 +1,298 @@
+# Chapter 2: Architecture & Data Flow
+
+## Overview
+
+The Admin UI follows a classic client-server architecture that leverages jsgui3's isomorphic rendering pipeline. The server renders the initial HTML, the client activates controls and begins fetching live data through a set of JSON API endpoints and SSE streams.
+
+```
+┌──────────────────────────────────────────────────────────┐
+│                    Browser (Client)                       │
+│                                                          │
+│  ┌─────────────┐  ┌──────────────┐  ┌────────────────┐  │
+│  │ Admin Shell  │  │ Domain Ctrls │  │  SSE Client    │  │
+│  │ (sidebar,    │──│ (stat cards, │──│ (EventSource   │  │
+│  │  toolbar,    │  │  tables,     │  │  for live      │  │
+│  │  status bar) │  │  panels)     │  │  updates)      │  │
+│  └──────┬───────┘  └──────┬───────┘  └───────┬────────┘  │
+│         │                 │                   │           │
+│─────────┼─────────────────┼───────────────────┼───────────│
+│  fetch('/api/admin/*')    │    EventSource('/api/admin/   │
+│         │                 │         events')  │           │
+└─────────┼─────────────────┼───────────────────┼───────────┘
+          │                 │                   │
+          ▼                 ▼                   ▼
+┌──────────────────────────────────────────────────────────┐
+│                 jsgui3-server (Node.js)                   │
+│                                                          │
+│  ┌──────────────────────────────────────────────────┐    │
+│  │              Admin Module (v1/server.js)          │    │
+│  │                                                   │    │
+│  │  ┌───────────┐  ┌───────────┐  ┌──────────────┐  │    │
+│  │  │ Telemetry │  │ Snapshot  │  │ SSE Broadcast│  │    │
+│  │  │ Collector │  │ Endpoints │  │ Channel      │  │    │
+│  │  └─────┬─────┘  └─────┬─────┘  └──────┬───────┘  │    │
+│  └────────┼───────────────┼───────────────┼──────────┘    │
+│           │               │               │               │
+│  ┌────────▼───────────────▼───────────────▼──────────┐    │
+│  │            Server Internals                        │    │
+│  │                                                    │    │
+│  │  resource_pool  server_router  http_servers        │    │
+│  │  function_pubs  sse_publisher  process.memoryUsage │    │
+│  └────────────────────────────────────────────────────┘    │
+└──────────────────────────────────────────────────────────┘
+```
+
+## Component Hierarchy
+
+The admin UI is composed of nested jsgui3 controls that follow the standard lifecycle pattern. The hierarchy is:
+
+```
+Admin_Page (extends Active_HTML_Document)
+├── Admin_Toolbar
+│   ├── Button (Refresh)
+│   ├── Button (Stop)
+│   ├── Separator
+│   ├── Button (Restart)
+│   ├── Separator
+│   ├── Button (Logs)
+│   ├── Status_Indicator (Server Online)
+│   └── Version_Label
+├── Admin_Sidebar
+│   ├── Server_Identity_Card
+│   ├── Nav_Section ("OVERVIEW")
+│   │   ├── Nav_Item (Dashboard) [active]
+│   │   ├── Nav_Item (Processes)
+│   │   └── Nav_Item (Resources)
+│   ├── Nav_Section ("SERVER")
+│   │   ├── Nav_Item (Routes)
+│   │   ├── Nav_Item (Bundles)
+│   │   └── Nav_Item (API)
+│   ├── Nav_Section ("DIAGNOSTICS")
+│   │   ├── Nav_Item (Metrics)
+│   │   ├── Nav_Item (Logs)
+│   │   └── Nav_Item (Inspector)
+│   ├── Health_Summary
+│   └── Boot_Status
+├── Admin_Content_Area
+│   ├── [Dashboard View]
+│   │   ├── Stat_Card (Main Process)
+│   │   ├── Stat_Card (Child Processes)
+│   │   ├── Stat_Card (Resource Pool)
+│   │   ├── Stat_Card (Routes)
+│   │   ├── Stat_Card (Requests/Min)
+│   │   ├── Process_Panel (group box)
+│   │   ├── Resource_Table (group box)
+│   │   ├── Tabbed_Panel (Routes & API | Build | Config | Logs)
+│   │   ├── Server_Lifecycle_Diagram
+│   │   ├── Config_Panel (group box)
+│   │   └── Activity_Log (group box)
+│   ├── [Processes View]
+│   ├── [Resources View]
+│   ├── [Routes View]
+│   ├── [Logs View]
+│   └── ...
+└── Admin_Status_Bar
+    ├── Status_Segment (Ready status)
+    ├── Status_Segment (Memory)
+    ├── Status_Segment (Uptime)
+    └── Status_Segment (Requests/min)
+```
+
+## Data Flow Patterns
+
+### Pattern 1: Snapshot Polling
+
+For data that changes infrequently (configuration, route table, resource list), the client fetches a JSON snapshot on demand:
+
+```
+Client                          Server
+  │                               │
+  │── GET /api/admin/snapshot ───▶│
+  │                               │── Collects data from:
+  │                               │   resource_pool.summary
+  │                               │   server_router routes
+  │                               │   process.memoryUsage()
+  │                               │   os.cpus(), os.networkInterfaces()
+  │◀── 200 { snapshot } ─────────│
+  │                               │
+  │── Renders controls ──────────│
+```
+
+### Pattern 2: SSE Real-Time Stream
+
+For data that changes frequently (request counts, log entries, process health), the client opens an SSE connection:
+
+```
+Client                          Server
+  │                               │
+  │── GET /api/admin/events ────▶│
+  │   Accept: text/event-stream   │
+  │                               │── Opens SSE channel
+  │◀── event: connected ─────────│
+  │                               │
+  │◀── event: request_log ───────│  (on each HTTP request)
+  │◀── event: resource_change ───│  (on pool state change)
+  │◀── event: build_complete ────│  (on bundle rebuild)
+  │◀── event: heartbeat ─────────│  (every 15s keep-alive)
+  │                               │
+```
+
+### Pattern 3: Command Dispatch
+
+For admin actions (restart server, rebuild bundle), the client sends POST requests:
+
+```
+Client                          Server
+  │                               │
+  │── POST /api/admin/action ───▶│
+  │   { "action": "restart" }     │
+  │                               │── Validates action
+  │                               │── Executes action
+  │◀── 200 { result } ───────────│
+  │                               │
+  │◀── event: server_restarting ──│  (via SSE)
+  │◀── event: server_ready ──────│  (via SSE)
+```
+
+## Isomorphic Rendering Pipeline
+
+The admin UI follows the standard jsgui3 isomorphic pattern:
+
+### Server-Side (Initial Load)
+
+1. User navigates to `/admin`
+2. `HTTP_Webpage_Publisher` creates a `Server_Static_Page_Context`
+3. `Admin_Page` constructor runs → `compose()` builds the DOM tree server-side
+4. `ctrl.active()` is called to finalize the tree
+5. HTML is rendered to string and sent to the browser
+6. JS bundle (`/admin/js/js.js`) and CSS bundle (`/admin/css/css.css`) are included via `<script>` and `<link>` tags
+
+### Client-Side (Activation)
+
+1. Browser parses HTML — the admin UI is immediately visible (server-rendered)
+2. JS bundle loads and executes
+3. `Admin_Page.activate()` fires:
+   - Binds event listeners to sidebar navigation
+   - Opens SSE connection to `/api/admin/events`
+   - Fetches initial snapshot from `/api/admin/snapshot`
+   - Populates controls with live data
+
+This means the admin UI has **zero time-to-first-paint** for the structural layout, with data populating as the JS bundle activates.
+
+## Module Boundary
+
+The admin UI maintains a clean module boundary with the host server:
+
+```
+Host Server (server.js)                Admin Module (admin-ui/v1/server.js)
+┌────────────────────────┐             ┌────────────────────────────┐
+│                        │             │                            │
+│  resource_pool ───────▶│─────────────│▶ get_resources_tree()     │
+│  server_router ───────▶│─────────────│▶ get_routes_list()        │
+│  http_servers  ───────▶│─────────────│▶ get_server_status()      │
+│  function_pubs ───────▶│─────────────│▶ get_publishers_list()    │
+│  process       ───────▶│─────────────│▶ get_process_info()       │
+│                        │             │                            │
+│  NO modifications to   │             │  Read-only access to       │
+│  core server behavior  │             │  server properties         │
+│                        │             │                            │
+└────────────────────────┘             └────────────────────────────┘
+```
+
+The Admin Module:
+- **Reads** from `server.resource_pool`, `server.server_router`, `server.http_servers`
+- **Subscribes** to events on `resource_pool` for state changes
+- **Collects** Node.js `process.memoryUsage()`, `os.cpus()`, `os.uptime()`
+- **Does NOT** modify how the server handles user routes or processes requests
+
+The only write operations the admin module provides are:
+- Restarting child processes (via `Process_Resource.restart()`)
+- Stopping/starting resources (via `Resource_Pool.start/stop`)
+
+These use the existing resource API surface — no new capabilities are added to the server itself.
+
+## File Organization
+
+```
+admin-ui/
+└── v1/
+    ├── client.js              # Client entry — exports Admin_Page control
+    ├── server.js              # Admin_Module class — telemetry adapter
+    ├── controls/
+    │   ├── admin_shell.js     # Root shell: toolbar + sidebar + content + status bar
+    │   ├── stat_card.js       # Reusable stat card control
+    │   ├── process_panel.js   # Process tree with fork visualization
+    │   ├── resource_table.js  # Resource pool table
+    │   ├── route_table.js     # Route listing with method badges
+    │   ├── log_viewer.js      # Scrolling log output
+    │   ├── build_status.js    # Bundle size and build info
+    │   ├── config_panel.js    # Configuration display/editor
+    │   ├── sidebar.js         # Sidebar with navigation sections
+    │   ├── toolbar.js         # Top toolbar with action buttons
+    │   ├── status_bar.js      # Bottom status bar
+    │   ├── nav_item.js        # Individual navigation item
+    │   ├── group_box.js       # Classic group box with inset label
+    │   ├── tab_panel.js       # Tabbed content switcher
+    │   ├── health_badge.js    # Colored health indicator
+    │   ├── method_badge.js    # HTTP method badge (GET, POST, etc.)
+    │   └── data_table.js      # Generic sortable data table
+    └── css/
+        └── admin-tokens.css   # Design tokens for the Aero theme
+```
+
+## Dependency Graph
+
+```
+client.js
+    └── Admin_Page (extends Active_HTML_Document)
+        ├── Admin_Toolbar
+        │   └── jsgui3 controls: div, span, Button
+        ├── Admin_Sidebar
+        │   ├── Nav_Item
+        │   └── Health_Badge
+        ├── Admin_Content_Area
+        │   ├── Stat_Card
+        │   ├── Process_Panel
+        │   │   └── Health_Badge
+        │   ├── Resource_Table
+        │   │   ├── Data_Table
+        │   │   └── Health_Badge
+        │   ├── Route_Table
+        │   │   ├── Data_Table
+        │   │   └── Method_Badge
+        │   ├── Tab_Panel
+        │   ├── Group_Box
+        │   ├── Log_Viewer
+        │   ├── Build_Status
+        │   └── Config_Panel
+        └── Admin_Status_Bar
+
+server.js
+    └── Admin_Module
+        ├── Reads: server.resource_pool
+        ├── Reads: server.server_router
+        ├── Reads: server.http_servers
+        ├── Reads: server.function_publishers
+        ├── Uses:  HTTP_SSE_Publisher (for /api/admin/events)
+        └── Uses:  process, os modules
+```
+
+## Request Routing
+
+All admin routes live under the `/admin` and `/api/admin/` prefixes:
+
+| Route | Method | Purpose |
+|-------|--------|---------|
+| `/admin` | GET | Serve the admin UI HTML page |
+| `/admin/js/js.js` | GET | Client JavaScript bundle |
+| `/admin/css/css.css` | GET | Extracted CSS bundle |
+| `/api/admin/snapshot` | GET | Full server state snapshot |
+| `/api/admin/resources` | GET | Resource pool listing |
+| `/api/admin/routes` | GET | Route table |
+| `/api/admin/processes` | GET | Process information |
+| `/api/admin/config` | GET | Server configuration |
+| `/api/admin/build` | GET | Build/bundle status |
+| `/api/admin/events` | GET | SSE stream for real-time updates |
+| `/api/admin/action` | POST | Execute admin action (restart, etc.) |
+
+All endpoints are registered by the `Admin_Module.attach_to_router()` method, which receives the `server_router` from the host server.