jsgui3-server 0.0.149 → 0.0.151

package/docs/books/admin-ui-authentication/01-threat-model-and-goals.md

@@ -0,0 +1,124 @@
+# Chapter 1 — Threat Model and Goals
+
+## Why this chapter first
+
+Authentication design becomes expensive when started too late. The Admin UI already has telemetry endpoints and an SSE channel, so this chapter defines what we are protecting and what can wait.
+
+## Assets to protect
+
+For jsgui3-server admin surfaces, primary assets are:
+
+1. **Control-plane actions**
+   - starting/stopping resources
+   - changing runtime config
+   - registering/removing routes
+2. **Sensitive observability data**
+   - host/process metadata
+   - route inventories
+   - internal resource names and states
+3. **Availability**
+   - preventing abuse of SSE streams and expensive endpoints
+
+## Threat model (practical)
+
+### External attacker
+- Can probe `/admin` and `/api/admin/*` endpoints.
+- Tries default credentials, weak tokens, replay, or unauthenticated access.
+
+### Internal but unauthorized user
+- Has network access but should not have admin privileges.
+- Attempts to read diagnostic state or execute write actions.
+
+### Session theft and browser attacks
+- Cookie theft, CSRF, XSS-assisted token misuse.
+- Stale sessions after role changes.
+
+### Operational mistakes
+- Admin endpoint exposed publicly by accident.
+- Weak defaults in non-production become production behavior.
+
+## Security goals
+
+### G1: Default deny for admin APIs
+- Any `/api/admin/*` endpoint should require auth by default.
+- Explicit allow-list only for bootstrapping/health if needed.
+
+### G2: Separate read and write permissions
+- Read-only operators should access telemetry.
+- Mutating operations require stronger roles.
+
+### G3: Short-lived, revocable sessions
+- Session invalidation should take effect quickly.
+- SSE clients must be disconnected when auth is revoked.
+
+### G4: Browser-safe auth transport
+- Prefer secure, httpOnly cookies for web-admin sessions.
+- Apply CSRF protection for state-changing endpoints.
+
+### G5: Deployment-safe defaults
+- Clear behavior in dev vs production.
+- Explicit configuration for trusted origins and cookie policy.
+
+## Non-goals for first implementation phase
+
+To keep delivery realistic, v1 auth does **not** need:
+
+- Multi-tenant federation (SAML/OIDC enterprise SSO) on day one.
+- Fine-grained per-resource ACL matrices.
+- Full audit analytics UI before basic enforcement exists.
+
+## Phased implementation plan
+
+### Phase A — Guard rails (immediate)
+- Keep admin UI read-only while auth is incomplete.
+- Avoid adding new mutation endpoints.
+- Document intended privileged operations.
+
+### Phase B — Baseline authentication
+- Add login/logout endpoint pair.
+- Add session issuance + validation middleware.
+- Require auth for all `/api/admin/v1/*` and `/admin/v1`.
+
+### Phase C — Authorization and hardening
+- Introduce roles: `admin_read`, `admin_write`.
+- Add CSRF for write paths.
+- Add rate limiting and SSE connection caps.
+
+### Phase D — Operational maturity
+- Session revocation, inactivity expiry, and rotation.
+- Structured security/audit logs.
+- Runbook for emergency lockout and credential reset.
+
+## Design constraints from current codebase
+
+Given existing server patterns:
+
+- Admin routes are registered through router adapters.
+- SSE is already used for live events.
+- The current v1 UI is telemetry-first and can remain read-only safely.
+
+This means we can adopt auth incrementally without blocking current UI progress.
+
+## Decision points (to finalize in next chapter)
+
+1. Session storage model: in-memory vs Redis-backed.
+2. Credential source: static bootstrap admin vs user store resource.
+3. Cookie strategy: strict same-site policy for local-only admin vs configurable for reverse proxies.
+4. Role model shape: two-role minimal model vs extensible claims model.
+
+## Selected v1 decisions (current)
+
+The following decisions are now selected for v1 implementation:
+
+1. **Session storage model:** in-memory sessions.
+2. **Credential source:** user resource/store (not env-bootstrap only).
+3. **Protection scope:** protect both `/admin/v1` and `/api/admin/v1/*` immediately.
+
+These choices keep the first auth rollout simple while still enforcing an end-to-end protected admin surface.
+
+## Exit criteria for this chapter
+
+Before coding auth middleware, agree on:
+- which endpoints require `admin_read` vs `admin_write`,
+- session lifecycle requirements,
+- dev/prod default policy matrix.

package/docs/books/admin-ui-authentication/02-session-model-and-token-model.md

@@ -0,0 +1,75 @@
+# Chapter 2 — Session Model and Token Model (v1 Decision)
+
+## Chosen model for v1
+
+This project uses **stateful in-memory sessions** for admin authentication in v1.
+
+### Why this model now
+
+- Fastest path to safe protection of `/admin/v1` and `/api/admin/v1/*`.
+- Works with existing single-process server setup.
+- Easy to reason about and debug while auth surface stabilizes.
+
+### Trade-offs
+
+- Sessions are lost on server restart.
+- Not suitable for multi-instance horizontal scaling without shared storage.
+- Requires follow-up for production HA (Phase D).
+
+## Session shape
+
+A session record contains:
+
+- `session_id`
+- `user` (`username`, `roles`)
+- `created_at`
+- `expires_at`
+
+Cookie name: `jsgui_admin_v1_sid`
+
+Cookie policy (v1):
+
+- `HttpOnly`
+- `SameSite=Lax`
+- `Path=/`
+- `Secure` enabled in production mode
+
+## User credential source (v1)
+
+Credentials are validated against an **in-process user store resource-like service**.
+
+- Primary bootstrap path: `ADMIN_V1_USER` + `ADMIN_V1_PASSWORD`.
+- Development fallback (non-production only): `admin/admin`.
+- Production without explicit password keeps login disabled until configured.
+
+## Endpoint policy
+
+Public endpoints:
+
+- `POST /api/admin/v1/auth/login`
+- `POST /api/admin/v1/auth/logout`
+- `GET /api/admin/v1/auth/session`
+- `GET /admin/v1/login`
+
+Protected endpoints:
+
+- `GET /admin/v1`
+- `GET /api/admin/v1/status`
+- `GET /api/admin/v1/resources`
+- `GET /api/admin/v1/routes`
+- `GET /api/admin/v1/events`
+
+## Request flow
+
+1. Browser requests `/admin/v1`.
+2. If unauthenticated, server redirects to `/admin/v1/login`.
+3. Login form posts credentials to `/api/admin/v1/auth/login`.
+4. Server validates credentials and issues session cookie.
+5. Browser returns to `/admin/v1` and can access protected APIs.
+
+## Planned evolution (post-v1)
+
+- Move session store to Redis or equivalent shared backing store.
+- Add idle timeout refresh strategy.
+- Add session revocation events and forced SSE disconnect.
+- Add CSRF protections for write endpoints before mutation APIs launch.

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.