@serve.zone/dcrouter 13.25.0 → 13.26.0

package/ts_apiclient/classes.workhoster.ts

@@ -0,0 +1,49 @@
+import * as interfaces from '../ts_interfaces/index.js';
+import type { DcRouterApiClient } from './classes.dcrouterapiclient.js';
+
+export class WorkHosterManager {
+  constructor(private clientRef: DcRouterApiClient) {}
+
+  public async getCapabilities(): Promise<interfaces.data.IGatewayCapabilities> {
+    const response = await this.clientRef.request<interfaces.requests.IReq_GetGatewayCapabilities>(
+      'getGatewayCapabilities',
+      this.clientRef.buildRequestPayload() as any,
+    );
+    return response.capabilities;
+  }
+
+  public async getDomains(): Promise<interfaces.data.IWorkHosterDomain[]> {
+    const response = await this.clientRef.request<interfaces.requests.IReq_GetWorkHosterDomains>(
+      'getWorkHosterDomains',
+      this.clientRef.buildRequestPayload() as any,
+    );
+    return response.domains;
+  }
+
+  public async syncRoute(options: {
+    ownership: interfaces.data.IWorkAppRouteOwnership;
+    route: interfaces.data.IDcRouterRouteConfig;
+    enabled?: boolean;
+  }): Promise<interfaces.data.IWorkAppRouteSyncResult> {
+    return this.clientRef.request<interfaces.requests.IReq_SyncWorkAppRoute>(
+      'syncWorkAppRoute',
+      this.clientRef.buildRequestPayload({
+        ownership: options.ownership,
+        route: options.route,
+        enabled: options.enabled,
+      }) as any,
+    );
+  }
+
+  public async deleteRoute(
+    ownership: interfaces.data.IWorkAppRouteOwnership,
+  ): Promise<interfaces.data.IWorkAppRouteSyncResult> {
+    return this.clientRef.request<interfaces.requests.IReq_SyncWorkAppRoute>(
+      'syncWorkAppRoute',
+      this.clientRef.buildRequestPayload({
+        ownership,
+        delete: true,
+      }) as any,
+    );
+  }
+}

package/ts_apiclient/index.ts

@@ -7,6 +7,7 @@ export { Certificate, CertificateManager, type ICertificateSummary } from './cla
 export { ApiToken, ApiTokenBuilder, ApiTokenManager } from './classes.apitoken.js';
 export { RemoteIngress, RemoteIngressBuilder, RemoteIngressManager } from './classes.remoteingress.js';
 export { Email, EmailManager } from './classes.email.js';
+export { WorkHosterManager } from './classes.workhoster.js';
 
 // Read-only managers
 export { StatsManager } from './classes.stats.js';

package/ts_apiclient/readme.md

@@ -1,18 +1,18 @@
 # @serve.zone/dcrouter-apiclient
 
-Typed, object-oriented client for operating a running dcrouter instance. It wraps the OpsServer `/typedrequest` API in managers and resource classes so your scripts can work with routes, certificates, tokens, remote ingress edges, emails, stats, config, logs, and RADIUS without hand-rolling requests.
+`@serve.zone/dcrouter-apiclient` is the object-oriented TypeScript client for the dcrouter OpsServer API. It wraps `/typedrequest` calls in managers, builders, and resource classes for routes, certificates, API tokens, remote ingress, email, stats, config, logs, RADIUS, and WorkHoster integrations.
 
 ## 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.
 
-## Installation
+## Install
 
 ```bash
 pnpm add @serve.zone/dcrouter-apiclient
 ```
 
-You can also import the same client through the main package subpath:
+The same client is also exposed as a subpath of the main package:
 
 ```typescript
 import { DcRouterApiClient } from '@serve.zone/dcrouter/apiclient';
@@ -30,7 +30,7 @@ const client = new DcRouterApiClient({
 await client.login('admin', 'admin');
 
 const { routes, warnings } = await client.routes.list();
-console.log('route count', routes.length, 'warnings', warnings.length);
+console.log(routes.length, warnings.length);
 
 const route = await client.routes.build()
   .setName('api-gateway')
@@ -38,47 +38,46 @@ const route = await client.routes.build()
   .setAction({ type: 'forward', targets: [{ host: '127.0.0.1', port: 8080 }] })
   .save();
 
-await route.toggle(false);
+await route.toggle(true);
 ```
 
-## What the Client Gives You
+## Authentication
 
-| Manager | Purpose |
-| --- | --- |
-| `client.routes` | List merged routes, create API routes, toggle routes |
-| `client.certificates` | Inspect certificates and run certificate operations |
-| `client.apiTokens` | Create, list, toggle, roll, and revoke API tokens |
-| `client.remoteIngress` | Manage edge registrations, statuses, and connection tokens |
-| `client.emails` | Inspect email items and trigger resend flows |
-| `client.stats` | Health, statistics, and operational summaries |
-| `client.config` | Read the current configuration view |
-| `client.logs` | Read recent logs and log-related data |
-| `client.radius` | Manage RADIUS clients, VLANs, and sessions |
-
-## Authentication Modes
-
-| Mode | How it works |
-| --- | --- |
-| Admin login | Call `login(username, password)` and the returned identity is stored on the client |
-| API token | Pass `apiToken` in the constructor and it is injected into requests automatically |
+The client supports session login and API-token authentication.
 
 ```typescript
-const client = new DcRouterApiClient({
+const sessionClient = new DcRouterApiClient({
   baseUrl: 'https://dcrouter.example.com',
-  apiToken: 'dcr_your_token_here',
+});
+await sessionClient.login('admin', 'admin');
+
+const tokenClient = new DcRouterApiClient({
+  baseUrl: 'https://dcrouter.example.com',
+  apiToken: 'dcr_token_value',
 });
 ```
 
-Important behavior:
+`baseUrl` is normalized by removing trailing slashes. Requests are sent to `${baseUrl}/typedrequest`. `buildRequestPayload()` injects the current identity and optional API token for manager methods.
 
-- `baseUrl` is normalized, and the client automatically calls `${baseUrl}/typedrequest`
-- `buildRequestPayload()` injects the current identity and optional API token for you
-- system routes can be toggled, but only API routes are meant for edit and delete flows
+## Manager Map
 
-## Route Builder Example
+| Manager | Purpose |
+| --- | --- |
+| `client.routes` | List merged routes, build API routes, update/delete API routes, and toggle routes. |
+| `client.certificates` | Inspect certificate summaries and trigger certificate operations. |
+| `client.apiTokens` | Create, list, toggle, roll, and revoke API tokens. |
+| `client.remoteIngress` | Manage edge registrations, statuses, ports, tags, and connection tokens. |
+| `client.emails` | Inspect received/cached email items and trigger resend flows. |
+| `client.workHosters` | Manage WorkHoster-facing route/application integration calls. |
+| `client.stats` | Read health, counters, summaries, and runtime status. |
+| `client.config` | Read the current configuration view. |
+| `client.logs` | Read recent log information. |
+| `client.radius` | Manage RADIUS clients, VLAN mappings, and accounting sessions. |
+
+## Route Builder
 
 ```typescript
-const newRoute = await client.routes.build()
+const route = await client.routes.build()
   .setName('internal-app')
   .setMatch({
     ports: 443,
@@ -91,7 +90,7 @@ const newRoute = await client.routes.build()
   .setEnabled(true)
   .save();
 
-await newRoute.update({
+await route.update({
   action: {
     type: 'forward',
     targets: [{ host: '127.0.0.1', port: 3001 }],
@@ -99,17 +98,17 @@ await newRoute.update({
 });
 ```
 
-## Token and Remote Ingress Example
+System routes from `config`, `email`, and `dns` origins are designed to be toggled, not edited. Full create/update/delete behavior is for routes with origin `api`.
+
+## API Tokens and Remote Ingress
 
 ```typescript
 const token = await client.apiTokens.build()
-  .setName('ci-token')
+  .setName('automation')
   .setScopes(['routes:read', 'routes:write'])
   .setExpiresInDays(30)
   .save();
 
-console.log('copy this once:', token.tokenValue);
-
 const edge = await client.remoteIngress.build()
   .setName('edge-eu-1')
   .setListenPorts([80, 443])
@@ -118,20 +117,31 @@ const edge = await client.remoteIngress.build()
   .save();
 
 const connectionToken = await edge.getConnectionToken();
-console.log(connectionToken);
+console.log(token.tokenValue, connectionToken);
 ```
 
-## What This Package Does Not Do
+## What This Package Is Not
 
 - It does not start dcrouter.
-- It does not bundle the dashboard.
-- It does not replace the raw interfaces package when you want low-level TypedRequest contracts.
+- It does not serve or bundle the Ops dashboard.
+- It does not replace `@serve.zone/dcrouter-interfaces` when you want raw TypedRequest contracts.
+
+Use `@serve.zone/dcrouter` for the server runtime and `@serve.zone/dcrouter-interfaces` for shared request/data types.
+
+## Development
+
+This folder is published from the dcrouter monorepo via `tspublish.json` with order `5`.
+
+Useful source entry points:
 
-Use `@serve.zone/dcrouter` to run the server and `@serve.zone/dcrouter-interfaces` for the shared request/data types.
+- `index.ts` exports the public client surface.
+- `classes.dcrouterapiclient.ts` owns authentication and request dispatch.
+- `classes.route.ts` owns route resources and builders.
+- `classes.remoteingress.ts`, `classes.apitoken.ts`, `classes.radius.ts`, and the other manager files wrap focused API domains.
 
 ## License and Legal Information
 
-This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](../license) file.
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [license](../license) file.
 
 **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
 
@@ -143,7 +153,7 @@ Use of these trademarks must comply with Task Venture Capital GmbH's Trademark G
 
 ### Company Information
 
-Task Venture Capital GmbH  
+Task Venture Capital GmbH
 Registered at District Court Bremen HRB 35230 HB, Germany
 
 For any legal inquiries or further information, please contact us via email at hello@task.vc.

package/ts_web/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/dcrouter',
-  version: '13.25.0',
+  version: '13.26.0',
   description: 'A multifaceted routing service handling mail and SMS delivery functions.'
 }

package/ts_web/appstate.ts

@@ -2506,7 +2506,12 @@ export const fetchUsersAction = usersStatePart.createAction(async (statePartArg)
   }
 });
 
-export async function createApiToken(name: string, scopes: interfaces.data.TApiTokenScope[], expiresInDays?: number | null) {
+export async function createApiToken(
+  name: string,
+  scopes: interfaces.data.TApiTokenScope[],
+  expiresInDays?: number | null,
+  policy?: any,
+) {
   const context = getActionContext();
   const request = new plugins.domtools.plugins.typedrequest.TypedRequest<
     interfaces.requests.IReq_CreateApiToken
@@ -2516,6 +2521,7 @@ export async function createApiToken(name: string, scopes: interfaces.data.TApiT
     identity: context.identity!,
     name,
     scopes,
+    policy,
     expiresInDays,
   });
 }

package/ts_web/elements/access/ops-view-apitokens.ts

@@ -199,12 +199,25 @@ export class OpsViewApiTokens extends DeesElement {
   private async showCreateTokenDialog() {
     const { DeesModal } = await import('@design.estate/dees-catalog');
 
-    const allScopes: TApiTokenScope[] = [
+    const allScopes = [
+      '*',
       'routes:read',
       'routes:write',
       'config:read',
+      'certificates:read',
+      'certificates:write',
       'tokens:read',
       'tokens:manage',
+      'domains:read',
+      'domains:write',
+      'dns-records:read',
+      'dns-records:write',
+      'email-domains:read',
+      'email-domains:write',
+      'gateway-clients:read',
+      'gateway-clients:write',
+      'workhosters:read',
+      'workhosters:write',
     ];
 
     await DeesModal.createAndShow({
@@ -218,10 +231,15 @@ export class OpsViewApiTokens extends DeesElement {
           <dees-input-tags
             .key=${'scopes'}
             .label=${'Token Scopes'}
-            .value=${['routes:read', 'routes:write']}
+            .value=${['gateway-clients:read', 'gateway-clients:write']}
             .suggestions=${allScopes}
             .required=${true}
           ></dees-input-tags>
+          <dees-input-text .key=${'policyRole'} .label=${'Policy Role'} .description=${'admin, gatewayClient, or operator'}></dees-input-text>
+          <dees-input-text .key=${'gatewayClientType'} .label=${'Gateway Client Type'} .description=${'For gatewayClient tokens: onebox, cloudly, or custom'}></dees-input-text>
+          <dees-input-text .key=${'gatewayClientId'} .label=${'Gateway Client ID'} .description=${'Required for gatewayClient tokens'}></dees-input-text>
+          <dees-input-text .key=${'hostnamePatterns'} .label=${'Hostname Patterns'} .description=${'Comma separated, e.g. *.apps.example.com'}></dees-input-text>
+          <dees-input-text .key=${'allowedRouteTarget'} .label=${'Allowed Route Target'} .description=${'Optional host:ports, e.g. 203.0.113.10:80,443'}></dees-input-text>
           <dees-input-text .key=${'expiresInDays'} .label=${'Expires in'} .description=${'Number of days; leave blank for no expiration'}></dees-input-text>
         </dees-form>
       `,
@@ -247,6 +265,7 @@ export class OpsViewApiTokens extends DeesElement {
             const rawScopes: string[] = tagsInput?.getValue?.() || tagsInput?.value || formData.scopes || [];
             const scopes = rawScopes
               .filter((s: string) => allScopes.includes(s as any)) as TApiTokenScope[];
+            const policy = this.buildPolicy(formData, scopes);
 
             const expiresInDays = formData.expiresInDays
               ? parseInt(formData.expiresInDays, 10)
@@ -255,7 +274,7 @@ export class OpsViewApiTokens extends DeesElement {
             await modalArg.destroy();
 
             try {
-              const response = await appstate.createApiToken(formData.name, scopes, expiresInDays);
+              const response = await appstate.createApiToken(formData.name, scopes, expiresInDays, policy);
               if (response.success && response.tokenValue) {
                 // Refresh the list first so it's ready when user dismisses the modal
                 await appstate.routeManagementStatePart.dispatchAction(appstate.fetchApiTokensAction, null);
@@ -289,6 +308,42 @@ export class OpsViewApiTokens extends DeesElement {
     });
   }
 
+  private buildPolicy(formData: any, scopes: TApiTokenScope[]): any | undefined {
+    const role = String(formData.policyRole || '').trim();
+    if (!role) return undefined;
+    const policy: any = {
+      role,
+      scopes,
+    };
+    if (role === 'gatewayClient') {
+      const type = String(formData.gatewayClientType || 'onebox').trim() as 'onebox' | 'cloudly' | 'custom';
+      const id = String(formData.gatewayClientId || '').trim();
+      if (id) {
+        policy.gatewayClient = { type, id };
+      }
+      policy.hostnamePatterns = String(formData.hostnamePatterns || '')
+        .split(',')
+        .map((pattern) => pattern.trim())
+        .filter(Boolean);
+      const target = String(formData.allowedRouteTarget || '').trim();
+      if (target.includes(':')) {
+        const [host, portsValue] = target.split(':');
+        policy.allowedRouteTargets = [{
+          host: host.trim(),
+          ports: portsValue.split(',').map((port) => Number(port.trim())).filter((port) => Number.isInteger(port)),
+        }];
+      }
+      policy.capabilities = {
+        readDomains: true,
+        readDnsRecords: true,
+        syncRoutes: true,
+        syncDnsRecords: false,
+        requestCertificates: false,
+      };
+    }
+    return policy;
+  }
+
   private async showRollTokenDialog(token: interfaces.data.IApiTokenInfo) {
     const { DeesModal } = await import('@design.estate/dees-catalog');
 

package/ts_web/readme.md

@@ -1,6 +1,6 @@
 # @serve.zone/dcrouter-web
 
-Browser-side frontend for the dcrouter Ops dashboard. This folder is the SPA entrypoint, router, app state, and web-component UI rendered by OpsServer.
+`@serve.zone/dcrouter-web` is the browser-side Ops dashboard module for dcrouter. It provides the SPA entry point, route synchronization, app state, and web-component views that OpsServer serves from the main dcrouter runtime.
 
 ## Issue Reporting and Security
 
@@ -8,10 +8,12 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 
 ## What It Boots
 
-- `index.ts` initializes the app router and renders `<ops-dashboard>` into `document.body`
-- `router.ts` defines top-level dashboard routes and subviews
-- `appstate.ts` holds reactive state, TypedRequest actions, and TypedSocket log streaming
-- `elements/` contains the dashboard shell and feature views
+| File | Purpose |
+| --- | --- |
+| `index.ts` | Initializes the app router and renders `<ops-dashboard>` into `document.body`. |
+| `router.ts` | Defines top-level dashboard routes, subviews, redirects, and URL/state synchronization. |
+| `appstate.ts` | Holds reactive login, UI, config, stats, route, DNS, email, remote ingress, VPN, and log state. |
+| `elements/` | Contains the dashboard shell and feature-specific Dees web components. |
 
 ## View Map
 
@@ -20,37 +22,52 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 | `overview` | `stats`, `configuration` |
 | `network` | `activity`, `routes`, `sourceprofiles`, `networktargets`, `targetprofiles`, `remoteingress`, `vpn` |
 | `email` | `log`, `security`, `domains` |
+| `logs` | flat view |
 | `access` | `apitokens`, `users` |
 | `security` | `overview`, `blocked`, `authentication` |
 | `domains` | `providers`, `domains`, `dns`, `certificates` |
-| `logs` | flat view |
 
-## How It Talks To dcrouter
+## Runtime Communication
+
+The dashboard talks to the dcrouter OpsServer through:
+
+- TypedRequest calls for normal API actions
+- shared contracts from `@serve.zone/dcrouter-interfaces`
+- TypedSocket log streaming for live operational output
+- Dees web components and app-state subscriptions for UI updates
+- QR code rendering for VPN client UX
+
+## Usage
+
+This package is primarily consumed by the main dcrouter build and served by OpsServer. Install it directly only when you intentionally need the dashboard module boundary.
+
+```bash
+pnpm add @serve.zone/dcrouter-web
+```
 
-- TypedRequest for the main API surface
-- shared request and data contracts from `@serve.zone/dcrouter-interfaces`
-- TypedSocket for real-time log streaming
-- QR code generation for VPN client UX
+For the full server and hosted dashboard, use `@serve.zone/dcrouter`.
 
-## Development Notes
+## Development
 
-This package is the frontend module boundary, but it is built and served as part of the main workspace.
+This folder is published from the dcrouter monorepo via `tspublish.json` with order `4`.
 
 ```bash
 pnpm run build
 pnpm run watch
 ```
 
-The built dashboard assets are emitted into `dist_serve/` by the workspace build pipeline.
+The dcrouter build emits served dashboard assets into `dist_serve/`.
 
-## What This Package Is For
+Useful source entry points:
 
-- Use it when you want the dashboard frontend as its own published module boundary.
-- Use `@serve.zone/dcrouter` when you want the server that actually hosts this UI and the backend API.
+- `index.ts` boots the frontend.
+- `router.ts` owns URL/view state synchronization.
+- `elements/ops-dashboard.ts` defines the app shell and tab map.
+- `elements/network/`, `elements/domains/`, `elements/email/`, `elements/security/`, `elements/access/`, and `elements/overview/` hold feature views.
 
 ## License and Legal Information
 
-This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](../license) file.
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [license](../license) file.
 
 **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
 
@@ -62,7 +79,7 @@ Use of these trademarks must comply with Task Venture Capital GmbH's Trademark G
 
 ### Company Information
 
-Task Venture Capital GmbH  
+Task Venture Capital GmbH
 Registered at District Court Bremen HRB 35230 HB, Germany
 
 For any legal inquiries or further information, please contact us via email at hello@task.vc.