@serve.zone/dcrouter 13.18.0 → 13.19.0

package/ts_web/readme.md

@@ -1,273 +1,72 @@
 # @serve.zone/dcrouter-web
 
-Web-based Operations Dashboard for DcRouter. 🖥️
+Browser UI package for dcrouter's operations dashboard. 🖥️
 
-A modern, reactive web application for monitoring and managing your DcRouter instance in real-time. Built with web components using [@design.estate/dees-element](https://code.foss.global/design.estate/dees-element) and [@design.estate/dees-catalog](https://code.foss.global/design.estate/dees-catalog).
+This package contains the browser entrypoint, app state, router, and web components that power the Ops dashboard served by dcrouter.
 
 ## Issue Reporting and Security
 
 For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
 
-## Features
-
-### 🔐 Secure Authentication
-- JWT-based login with persistent sessions (IndexedDB)
-- Automatic session expiry detection and cleanup
-- Secure username/password authentication
-
-### 📊 Overview Dashboard
-- Real-time server statistics (CPU, memory, uptime)
-- Active connection counts and email throughput
-- DNS query metrics and RADIUS session tracking
-- Auto-refreshing with configurable intervals
-
-### 🌐 Network View
-- Active connection monitoring with real-time data from SmartProxy
-- Top connected IPs with connection counts and percentages
-- Throughput rates (inbound/outbound in kbit/s, Mbit/s, Gbit/s)
-- Traffic chart with selectable time ranges
-
-### 📧 Email Management
-- **Queued** — Emails pending delivery with queue position
-- **Sent** — Successfully delivered emails with timestamps
-- **Failed** — Failed emails with resend capability
-- **Security** — Security incidents from email processing
-- Bounce record management and suppression list controls
-
-### 🔐 Certificate Management
-- Domain-centric certificate overview with status indicators
-- Certificate source tracking (ACME, provision function, static)
-- Expiry date monitoring and alerts
-- Per-domain backoff status for failed provisions
-- One-click reprovisioning per domain
-- Certificate import, export, and deletion
-
-### 🌍 Remote Ingress Management
-- Edge node registration with name, ports, and tags
-- Real-time connection status (connected/disconnected/disabled)
-- Public IP and active tunnel count per edge
-- Auto-derived port display with manual/derived breakdown
-- **Connection token generation** — one-click "Copy Token" for easy edge provisioning
-- Enable/disable, edit, secret regeneration, and delete actions
-
-### 🔐 VPN Management
-- VPN server status with forwarding mode, subnet, and WireGuard port
-- Client registration table with create, enable/disable, and delete actions
-- WireGuard config download, clipboard copy, and **QR code display** on client creation
-- QR code export for existing clients — scan with WireGuard mobile app (iOS/Android)
-- Per-client telemetry (bytes sent/received, keepalives)
-- Server public key display for manual client configuration
-
-### 📜 Log Viewer
-- Real-time log streaming
-- Filter by log level (error, warning, info, debug)
-- Search and time-range selection
-
-### 🛣️ Route & API Token Management
-- Programmatic route CRUD with enable/disable and override controls
-- API token creation, revocation, and scope management
-- Routes tab and API Tokens tab in unified view
-
-### 🛡️ Security Profiles & Network Targets
-- Create, edit, and delete reusable security profiles (IP allow/block lists, rate limits, max connections)
-- Create, edit, and delete reusable network targets (host:port destinations)
-- In-row and context menu actions for quick editing
-- Changes propagate automatically to all referencing routes
-
-### ⚙️ Configuration
-- Read-only display of current system configuration
-- Status badges for boolean values (enabled/disabled)
-- Array values displayed as pills with counts
-- Section icons and formatted byte/time values
-
-### 🛡️ Security Dashboard
-- IP reputation monitoring
-- Rate limit status across domains
-- Blocked connection tracking
-- Security event timeline
-
-## Architecture
-
-### Technology Stack
-
-| Layer | Package | Purpose |
-|-------|---------|---------|
-| **Components** | `@design.estate/dees-element` | Web component framework (lit-element based) |
-| **UI Kit** | `@design.estate/dees-catalog` | Pre-built components (tables, charts, forms, app shell) |
-| **State** | `@push.rocks/smartstate` | Reactive state management with persistent/soft modes |
-| **Routing** | Client-side router | URL-synchronized view navigation |
-| **API** | `@api.global/typedrequest` | Type-safe communication with OpsServer |
-| **Types** | `@serve.zone/dcrouter-interfaces` | Shared TypedRequest interface definitions |
-
-### Component Structure
+## What Is In Here
 
-```
-ts_web/
-├── index.ts                  # Entry point — renders <ops-dashboard>
-├── appstate.ts               # State management (all state parts + actions)
-├── router.ts                 # Client-side routing (AppRouter)
-├── plugins.ts                # Dependency imports
-└── elements/
-    ├── ops-dashboard.ts      # Main app shell
-    ├── ops-view-overview.ts  # Overview statistics
-    ├── ops-view-network.ts   # Network monitoring
-    ├── ops-view-emails.ts    # Email queue management
-    ├── ops-view-certificates.ts  # Certificate overview & reprovisioning
-    ├── ops-view-remoteingress.ts # Remote ingress edge management
-    ├── ops-view-vpn.ts       # VPN client management
-    ├── ops-view-logs.ts      # Log viewer
-    ├── ops-view-routes.ts    # Route & API token management
-    ├── ops-view-config.ts    # Configuration display
-    ├── ops-view-security.ts  # Security dashboard
-    └── shared/
-        ├── css.ts            # Shared styles
-        └── ops-sectionheading.ts  # Section heading component
-```
+| Path | Purpose |
+| --- | --- |
+| `index.ts` | Browser entrypoint that initializes routing and renders `<ops-dashboard>` |
+| `appstate.ts` | Central reactive state and action definitions |
+| `router.ts` | URL-based dashboard routing |
+| `elements/` | Dashboard views and reusable UI pieces |
 
-### State Management
-
-The app uses `@push.rocks/smartstate` v2.3+ with multiple state parts, scheduled actions with `autoPause: 'visibility'`, and batched updates:
-
-| State Part | Mode | Description |
-|-----------|------|-------------|
-| `loginStatePart` | Persistent (IndexedDB) | JWT identity and login status |
-| `statsStatePart` | Soft (memory) | Server, email, DNS, security, RADIUS, VPN metrics |
-| `configStatePart` | Soft | Current system configuration |
-| `uiStatePart` | Soft | Active view, sidebar, auto-refresh, theme |
-| `logStatePart` | Soft | Recent logs, streaming status, filters |
-| `networkStatePart` | Soft | Connections, IPs, throughput rates |
-| `emailOpsStatePart` | Soft | Email queues, bounces, suppression list |
-| `certificateStatePart` | Soft | Certificate list, summary, loading state |
-| `remoteIngressStatePart` | Soft | Edge list, statuses, new edge secret |
-| `vpnStatePart` | Soft | VPN clients, server status, new client config |
-
-### Tab Visibility Optimization
-
-The dashboard automatically pauses all background activity when the browser tab is hidden and resumes when visible:
-
-- **Auto-refresh polling** uses `createScheduledAction` with `autoPause: 'visibility'` — stops HTTP requests while the tab is sleeping
-- **In-flight guard** prevents concurrent refresh requests from piling up
-- **WebSocket connection** disconnects when hidden and reconnects when visible, preventing log entry accumulation
-- **Network traffic timer** pauses chart updates when the tab is backgrounded
-- **Log entry batching** — incoming WebSocket log pushes are buffered and flushed once per animation frame to avoid per-entry re-renders
-
-### Actions
-
-```typescript
-// Authentication
-loginAction(username, password)    // JWT login
-logoutAction()                     // Clear session
-
-// Data fetching (auto-refresh compatible)
-fetchAllStatsAction()              // Server + email + DNS + security stats
-fetchConfigurationAction()         // System configuration
-fetchRecentLogsAction()            // Log entries
-fetchNetworkStatsAction()          // Connection + throughput data
-
-// Email operations
-fetchQueuedEmailsAction()          // Pending emails
-fetchSentEmailsAction()            // Delivered emails
-fetchFailedEmailsAction()          // Failed emails
-fetchSecurityIncidentsAction()     // Security events
-fetchBounceRecordsAction()         // Bounce records
-resendEmailAction(emailId)         // Re-queue failed email
-removeFromSuppressionAction(email) // Remove from suppression list
-
-// Certificates
-fetchCertificateOverviewAction()   // All certificates with summary
-reprovisionCertificateAction(domain) // Reprovision a certificate
-deleteCertificateAction(domain)    // Delete a certificate
-importCertificateAction(cert)      // Import a certificate
-fetchCertificateExport(domain)     // Export (standalone function)
-
-// Remote Ingress
-fetchRemoteIngressAction()         // Edges + statuses
-createRemoteIngressAction(data)    // Create new edge
-updateRemoteIngressAction(data)    // Update edge settings
-deleteRemoteIngressAction(id)      // Remove edge
-regenerateRemoteIngressSecretAction(id) // New secret
-toggleRemoteIngressAction(id, enabled)  // Enable/disable
-clearNewEdgeSecretAction()         // Dismiss secret banner
-fetchConnectionToken(edgeId)       // Get connection token (standalone function)
-
-// VPN
-fetchVpnAction()                   // Clients + server status
-createVpnClientAction(data)        // Create new VPN client
-deleteVpnClientAction(clientId)    // Remove VPN client
-toggleVpnClientAction(id, enabled) // Enable/disable
-clearNewClientConfigAction()       // Dismiss config banner
-```
+## Main Views
 
-### Client-Side Routing
+The dashboard currently includes views for:
 
-```
-/overview        → Overview dashboard
-/network         → Network monitoring
-/emails          → Email management
-  /emails/queued    → Queued emails
-  /emails/sent      → Sent emails
-  /emails/failed    → Failed emails
-  /emails/security  → Security incidents
-/certificates    → Certificate management
-/remoteingress   → Remote ingress edge management
-/vpn             → VPN client management
-/routes          → Route & API token management
-/logs            → Log viewer
-/configuration   → System configuration
-/security        → Security dashboard
-```
+- overview and configuration
+- network activity and route management
+- source profiles, target profiles, and network targets
+- email activity and email domains
+- DNS providers, domains, DNS records, and certificates
+- API tokens and users
+- VPN, remote ingress, logs, and security views
 
-URL state is synchronized with the UI — bookmarking and deep linking fully supported.
+## Route Management UX
 
-## Development
+The web UI reflects dcrouter's current route ownership model:
 
-### Running Locally
+- system routes are shown separately from user routes
+- system routes are visible and toggleable
+- system routes are not directly editable or deletable
+- API routes are fully managed through the route-management forms
 
-Start DcRouter with OpsServer enabled:
+## How It Talks To dcrouter
 
-```typescript
-import { DcRouter } from '@serve.zone/dcrouter';
+The frontend uses TypedRequest and shared interfaces from `@serve.zone/dcrouter-interfaces`.
 
-const router = new DcRouter({
-  // OpsServer starts automatically on port 3000
-  smartProxyConfig: { routes: [/* your routes */] }
-});
+State actions in `appstate.ts` fetch and mutate:
 
-await router.start();
-// Dashboard at http://localhost:3000
-```
+- stats and health
+- logs
+- routes and tokens
+- certificates and ACME config
+- DNS providers, domains, and records
+- email domains and email operations
+- VPN, remote ingress, and RADIUS data
 
-### Building
+## Development Notes
+
+The browser bundle is built from this package and served by the main dcrouter package.
 
 ```bash
-# Build the bundle
 pnpm run bundle
-
-# Watch for development (auto-rebuild + restart)
 pnpm run watch
 ```
 
-The bundle is output to `./dist_serve/bundle.js` and served by the OpsServer.
-
-### Adding a New View
+The generated bundle is written into `dist_serve/` by the main build pipeline.
 
-1. Create a view component in `elements/`:
-```typescript
-import { DeesElement, customElement, html, css } from '@design.estate/dees-element';
-
-@customElement('ops-view-myview')
-export class OpsViewMyView extends DeesElement {
-  public static styles = [css`:host { display: block; padding: 24px; }`];
-
-  public render() {
-    return html`<ops-sectionheading>My View</ops-sectionheading>`;
-  }
-}
-```
+## When To Use This Package
 
-2. Add it to the dashboard tabs in `ops-dashboard.ts`
-3. Add the route in `router.ts`
-4. Add any state management in `appstate.ts`
+- Use it if you want the dashboard frontend as a package/module boundary.
+- Use the main `@serve.zone/dcrouter` package if you want the server that actually serves this UI.
 
 ## License and Legal Information