feat(gateway-clients): add managed gateway client administration and token-bound route ownership

2026-05-09 22:35:07 +00:00
parent d73b250382
commit 8dd0c3def9
22 changed files with 1287 additions and 48 deletions
@@ -3,6 +3,6 @@
 */
 export const commitinfo = {
  name: '@serve.zone/dcrouter',
-  version: '13.27.1',
+  version: '13.28.0',
  description: 'A multifaceted routing service handling mail and SMS delivery functions.'
 }
@@ -25,7 +25,7 @@ import { MetricsManager } from './monitoring/index.js';
 import { RadiusServer, type IRadiusServerConfig } from './radius/index.js';
 import { RemoteIngressManager, TunnelManager } from './remoteingress/index.js';
 import { VpnManager, type IVpnManagerConfig } from './vpn/index.js';
-import { RouteConfigManager, ApiTokenManager, ReferenceResolver, DbSeeder, TargetProfileManager } from './config/index.js';
+import { RouteConfigManager, ApiTokenManager, GatewayClientManager, ReferenceResolver, DbSeeder, TargetProfileManager } from './config/index.js';
 import type { TIpAllowEntry } from './config/classes.route-config-manager.js';
 import { SecurityLogger, ContentScanner, IPReputationChecker, SecurityPolicyManager } from './security/index.js';
 import { type IHttp3Config, augmentRoutesWithHttp3 } from './http3/index.js';
@@ -276,6 +276,7 @@ export class DcRouter {
  // Programmatic config API
  public routeConfigManager?: RouteConfigManager;
  public apiTokenManager?: ApiTokenManager;
+  public gatewayClientManager?: GatewayClientManager;
  public referenceResolver?: ReferenceResolver;
  public targetProfileManager?: TargetProfileManager;

@@ -617,6 +618,8 @@ export class DcRouter {
            );
            this.apiTokenManager = new ApiTokenManager();
            await this.apiTokenManager.initialize();
+            this.gatewayClientManager = new GatewayClientManager();
+            await this.gatewayClientManager.initialize();
            await this.routeConfigManager.initialize(
              this.seedConfigRoutes as import('../ts_interfaces/data/remoteingress.js').IDcRouterRouteConfig[],
              this.seedEmailRoutes as import('../ts_interfaces/data/remoteingress.js').IDcRouterRouteConfig[],
@@ -634,6 +637,7 @@ export class DcRouter {
          .withStop(async () => {
            this.routeConfigManager = undefined;
            this.apiTokenManager = undefined;
+            this.gatewayClientManager = undefined;
            this.referenceResolver = undefined;
            this.targetProfileManager = undefined;
          })
@@ -1101,6 +1105,7 @@ export class DcRouter {
        });

        const scheduler = this.certProvisionScheduler;
+        smartProxyConfig.certProvisionFallbackToAcme = false;
        smartProxyConfig.certProvisionFunction = async (domain, eventComms) => {
          // If SmartAcme is not yet ready (still starting or retrying), fall back to HTTP-01
          if (!this.smartAcmeReady) {
@@ -1149,10 +1154,10 @@ export class DcRouter {
            await scheduler.clearBackoff(domain);
            return result;
          } catch (err: unknown) {
-            // Record failure for backoff tracking
-            await scheduler.recordFailure(domain, (err as Error).message);
-            eventComms.warn(`SmartAcme DNS-01 failed for ${domain}: ${(err as Error).message}, falling back to http-01`);
-            return 'http01';
+            const message = `DNS-01 failed for ${domain}: ${(err as Error).message}`;
+            await scheduler.recordFailure(domain, message);
+            eventComms.warn(message);
+            throw new Error(message);
          }
        };
      }
@@ -0,0 +1,117 @@
+import * as plugins from '../plugins.js';
+import { GatewayClientDoc } from '../db/index.js';
+import type { IGatewayClient } from '../../ts_interfaces/data/workhoster.js';
+
+const defaultCapabilities: IGatewayClient['capabilities'] = {
+  readDomains: true,
+  readDnsRecords: true,
+  syncRoutes: true,
+  syncDnsRecords: false,
+  requestCertificates: false,
+};
+
+export class GatewayClientManager {
+  public async initialize(): Promise<void> {}
+
+  public async listClients(): Promise<IGatewayClient[]> {
+    const docs = await GatewayClientDoc.findAll();
+    return docs.map((doc) => this.toPublicClient(doc));
+  }
+
+  public async getClient(id: string): Promise<IGatewayClient | null> {
+    const doc = await GatewayClientDoc.findById(id);
+    return doc ? this.toPublicClient(doc) : null;
+  }
+
+  public async createClient(options: {
+    id?: string;
+    type: IGatewayClient['type'];
+    name: string;
+    description?: string;
+    hostnamePatterns?: string[];
+    allowedRouteTargets?: IGatewayClient['allowedRouteTargets'];
+    capabilities?: IGatewayClient['capabilities'];
+    createdBy: string;
+  }): Promise<IGatewayClient> {
+    const id = this.normalizeId(options.id || `${options.type}-${plugins.uuid.v4()}`);
+    if (!id) {
+      throw new Error('gateway client id is required');
+    }
+    if (await GatewayClientDoc.findById(id)) {
+      throw new Error('gateway client already exists');
+    }
+
+    const now = Date.now();
+    const doc = new GatewayClientDoc();
+    doc.id = id;
+    doc.type = options.type;
+    doc.name = options.name.trim();
+    doc.description = options.description?.trim() || undefined;
+    doc.hostnamePatterns = this.normalizeStringList(options.hostnamePatterns || []);
+    doc.allowedRouteTargets = this.normalizeAllowedRouteTargets(options.allowedRouteTargets || []);
+    doc.capabilities = { ...defaultCapabilities, ...(options.capabilities || {}) };
+    doc.enabled = true;
+    doc.createdAt = now;
+    doc.updatedAt = now;
+    doc.createdBy = options.createdBy;
+    await doc.save();
+    return this.toPublicClient(doc);
+  }
+
+  public async updateClient(
+    id: string,
+    patch: Partial<Pick<IGatewayClient, 'name' | 'description' | 'hostnamePatterns' | 'allowedRouteTargets' | 'capabilities' | 'enabled'>>,
+  ): Promise<IGatewayClient | null> {
+    const doc = await GatewayClientDoc.findById(id);
+    if (!doc) return null;
+    if (patch.name !== undefined) doc.name = patch.name.trim();
+    if (patch.description !== undefined) doc.description = patch.description.trim() || undefined;
+    if (patch.hostnamePatterns !== undefined) doc.hostnamePatterns = this.normalizeStringList(patch.hostnamePatterns);
+    if (patch.allowedRouteTargets !== undefined) doc.allowedRouteTargets = this.normalizeAllowedRouteTargets(patch.allowedRouteTargets);
+    if (patch.capabilities !== undefined) doc.capabilities = { ...defaultCapabilities, ...patch.capabilities };
+    if (patch.enabled !== undefined) doc.enabled = patch.enabled;
+    doc.updatedAt = Date.now();
+    await doc.save();
+    return this.toPublicClient(doc);
+  }
+
+  public async deleteClient(id: string): Promise<boolean> {
+    const doc = await GatewayClientDoc.findById(id);
+    if (!doc) return false;
+    await doc.delete();
+    return true;
+  }
+
+  private normalizeId(id: string): string {
+    return id.trim().toLowerCase().replace(/[^a-z0-9._-]/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '');
+  }
+
+  private normalizeStringList(values: string[]): string[] {
+    return values.map((value) => value.trim().toLowerCase()).filter(Boolean);
+  }
+
+  private normalizeAllowedRouteTargets(targets: IGatewayClient['allowedRouteTargets']): IGatewayClient['allowedRouteTargets'] {
+    return targets
+      .map((target) => ({
+        host: target.host.trim().toLowerCase(),
+        ports: target.ports.filter((port) => Number.isInteger(port) && port > 0 && port <= 65535),
+      }))
+      .filter((target) => target.host && target.ports.length > 0);
+  }
+
+  private toPublicClient(doc: GatewayClientDoc): IGatewayClient {
+    return {
+      id: doc.id,
+      type: doc.type,
+      name: doc.name,
+      description: doc.description,
+      hostnamePatterns: doc.hostnamePatterns || [],
+      allowedRouteTargets: doc.allowedRouteTargets || [],
+      capabilities: doc.capabilities || {},
+      enabled: doc.enabled,
+      createdAt: doc.createdAt,
+      updatedAt: doc.updatedAt,
+      createdBy: doc.createdBy,
+    };
+  }
+}
@@ -2,6 +2,7 @@
 export * from './validator.js';
 export { RouteConfigManager } from './classes.route-config-manager.js';
 export { ApiTokenManager } from './classes.api-token-manager.js';
+export { GatewayClientManager } from './classes.gateway-client-manager.js';
 export { ReferenceResolver } from './classes.reference-resolver.js';
 export { DbSeeder } from './classes.db-seeder.js';
-export { TargetProfileManager } from './classes.target-profile-manager.js';
+export { TargetProfileManager } from './classes.target-profile-manager.js';
@@ -0,0 +1,54 @@
+import * as plugins from '../../plugins.js';
+import { DcRouterDb } from '../classes.dcrouter-db.js';
+import type { IApiTokenPolicy, TGatewayClientType } from '../../../ts_interfaces/data/route-management.js';
+
+const getDb = () => DcRouterDb.getInstance().getDb();
+
+@plugins.smartdata.Collection(() => getDb())
+export class GatewayClientDoc extends plugins.smartdata.SmartDataDbDoc<GatewayClientDoc, GatewayClientDoc> {
+  @plugins.smartdata.unI()
+  @plugins.smartdata.svDb()
+  public id!: string;
+
+  @plugins.smartdata.svDb()
+  public type!: TGatewayClientType;
+
+  @plugins.smartdata.svDb()
+  public name: string = '';
+
+  @plugins.smartdata.svDb()
+  public description?: string;
+
+  @plugins.smartdata.svDb()
+  public hostnamePatterns: string[] = [];
+
+  @plugins.smartdata.svDb()
+  public allowedRouteTargets: NonNullable<IApiTokenPolicy['allowedRouteTargets']> = [];
+
+  @plugins.smartdata.svDb()
+  public capabilities: NonNullable<IApiTokenPolicy['capabilities']> = {};
+
+  @plugins.smartdata.svDb()
+  public enabled: boolean = true;
+
+  @plugins.smartdata.svDb()
+  public createdAt!: number;
+
+  @plugins.smartdata.svDb()
+  public updatedAt!: number;
+
+  @plugins.smartdata.svDb()
+  public createdBy!: string;
+
+  constructor() {
+    super();
+  }
+
+  public static async findById(id: string): Promise<GatewayClientDoc | null> {
+    return await GatewayClientDoc.getInstance({ id });
+  }
+
+  public static async findAll(): Promise<GatewayClientDoc[]> {
+    return await GatewayClientDoc.getInstances({});
+  }
+}
@@ -8,6 +8,7 @@ export * from './classes.security-policy-audit.doc.js';
 // Config document classes
 export * from './classes.route.doc.js';
 export * from './classes.api-token.doc.js';
+export * from './classes.gateway-client.doc.js';
 export * from './classes.source-profile.doc.js';
 export * from './classes.target-profile.doc.js';
 export * from './classes.network-target.doc.js';
@@ -307,6 +307,11 @@ export class CertificateHandler {
        }
      }

+      if (backoffInfo && status !== 'valid' && status !== 'expiring') {
+        status = 'failed';
+        error = error || backoffInfo.lastError;
+      }
+
      certificates.push({
        domain,
        routeNames: info.routeNames,
@@ -45,6 +45,16 @@ export class WorkHosterHandler {
    throw new plugins.typedrequest.TypedResponseError('unauthorized');
  }

+  private async requireAdmin(request: { identity?: interfaces.data.IIdentity }): Promise<string> {
+    if (request.identity?.jwt) {
+      const isAdmin = await this.opsServerRef.adminHandler.adminIdentityGuard.exec({
+        identity: request.identity,
+      });
+      if (isAdmin) return request.identity.userId;
+    }
+    throw new plugins.typedrequest.TypedResponseError('admin identity required');
+  }
+
  private registerHandlers(): void {
    this.typedrouter.addTypedHandler(
      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetGatewayCapabilities>(
@@ -56,6 +66,122 @@ export class WorkHosterHandler {
      ),
    );

+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetGatewayClientContext>(
+        'getGatewayClientContext',
+        async (dataArg) => {
+          const auth = await this.requireAuth(dataArg, 'gateway-clients:read');
+          return {
+            context: this.getGatewayClientContext(auth),
+            capabilities: this.getGatewayCapabilities(),
+          };
+        },
+      ),
+    );
+
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_ListGatewayClients>(
+        'listGatewayClients',
+        async (dataArg) => {
+          await this.requireAdmin(dataArg);
+          return { gatewayClients: await this.listManagedGatewayClients() };
+        },
+      ),
+    );
+
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_CreateGatewayClient>(
+        'createGatewayClient',
+        async (dataArg) => {
+          const userId = await this.requireAdmin(dataArg);
+          const manager = this.opsServerRef.dcRouterRef.gatewayClientManager;
+          if (!manager) return { success: false, message: 'Gateway client management not initialized' };
+          try {
+            const gatewayClient = await manager.createClient({
+              id: dataArg.id,
+              type: dataArg.type,
+              name: dataArg.name,
+              description: dataArg.description,
+              hostnamePatterns: dataArg.hostnamePatterns,
+              allowedRouteTargets: dataArg.allowedRouteTargets,
+              capabilities: dataArg.capabilities,
+              createdBy: userId,
+            });
+            return { success: true, gatewayClient };
+          } catch (error) {
+            return { success: false, message: (error as Error).message };
+          }
+        },
+      ),
+    );
+
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_UpdateGatewayClient>(
+        'updateGatewayClient',
+        async (dataArg) => {
+          await this.requireAdmin(dataArg);
+          const manager = this.opsServerRef.dcRouterRef.gatewayClientManager;
+          if (!manager) return { success: false, message: 'Gateway client management not initialized' };
+          const gatewayClient = await manager.updateClient(dataArg.id, {
+            name: dataArg.name,
+            description: dataArg.description,
+            hostnamePatterns: dataArg.hostnamePatterns,
+            allowedRouteTargets: dataArg.allowedRouteTargets,
+            capabilities: dataArg.capabilities,
+            enabled: dataArg.enabled,
+          });
+          return gatewayClient
+            ? { success: true, gatewayClient }
+            : { success: false, message: 'Gateway client not found' };
+        },
+      ),
+    );
+
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_DeleteGatewayClient>(
+        'deleteGatewayClient',
+        async (dataArg) => {
+          await this.requireAdmin(dataArg);
+          const manager = this.opsServerRef.dcRouterRef.gatewayClientManager;
+          if (!manager) return { success: false, message: 'Gateway client management not initialized' };
+          const success = await manager.deleteClient(dataArg.id);
+          return { success, message: success ? undefined : 'Gateway client not found' };
+        },
+      ),
+    );
+
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_CreateGatewayClientToken>(
+        'createGatewayClientToken',
+        async (dataArg) => {
+          const userId = await this.requireAdmin(dataArg);
+          const gatewayClient = await this.opsServerRef.dcRouterRef.gatewayClientManager?.getClient(dataArg.gatewayClientId);
+          const tokenManager = this.opsServerRef.dcRouterRef.apiTokenManager;
+          if (!gatewayClient || !gatewayClient.enabled) {
+            return { success: false, message: 'Gateway client not found or disabled' };
+          }
+          if (!tokenManager) {
+            return { success: false, message: 'Token management not initialized' };
+          }
+          const result = await tokenManager.createToken(
+            dataArg.name?.trim() || `${gatewayClient.name} Token`,
+            ['gateway-clients:read', 'gateway-clients:write'],
+            dataArg.expiresInDays ?? null,
+            userId,
+            {
+              role: 'gatewayClient',
+              scopes: ['gateway-clients:read', 'gateway-clients:write'],
+              gatewayClient: { type: gatewayClient.type, id: gatewayClient.id },
+              hostnamePatterns: gatewayClient.hostnamePatterns,
+              allowedRouteTargets: gatewayClient.allowedRouteTargets,
+              capabilities: gatewayClient.capabilities,
+            },
+          );
+          return { success: true, tokenId: result.id, tokenValue: result.rawToken };
+        },
+      ),
+    );
+
    this.typedrouter.addTypedHandler(
      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetGatewayClientDomains>(
        'getGatewayClientDomains',
@@ -183,6 +309,30 @@ export class WorkHosterHandler {
    };
  }

+  private getGatewayClientContext(auth: TAuthContext): interfaces.data.IGatewayClientContext {
+    const policy = auth.token?.policy;
+    const role = auth.isAdmin ? 'admin' : policy?.role || 'operator';
+    return {
+      role,
+      scopes: auth.token?.scopes || ['*'],
+      gatewayClient: policy?.gatewayClient,
+      hostnamePatterns: policy?.hostnamePatterns || [],
+      allowedRouteTargets: policy?.allowedRouteTargets || [],
+      capabilities: policy?.capabilities || {},
+    };
+  }
+
+  private async listManagedGatewayClients(): Promise<interfaces.data.IGatewayClient[]> {
+    const manager = this.opsServerRef.dcRouterRef.gatewayClientManager;
+    if (!manager) return [];
+    const clients = await manager.listClients();
+    const tokens = this.opsServerRef.dcRouterRef.apiTokenManager?.listTokens() || [];
+    return clients.map((client) => ({
+      ...client,
+      tokenCount: tokens.filter((token) => token.policy?.gatewayClient?.id === client.id).length,
+    }));
+  }
+
  private buildExternalKey(ownership: interfaces.data.IWorkAppRouteOwnership): string {
    return [
      ownership.workHosterType,
@@ -212,15 +362,38 @@ export class WorkHosterHandler {
    return policyClient.id;
  }

-  private assertGatewayClientOwnership(auth: TAuthContext, ownership: interfaces.data.IGatewayClientOwnership): void {
+  private resolveGatewayClientOwnership(
+    auth: TAuthContext,
+    ownership: interfaces.data.IGatewayClientOwnership,
+  ): Required<interfaces.data.IGatewayClientOwnership> {
+    const policy = auth.token?.policy;
+    if (policy?.role === 'gatewayClient') {
+      if (!policy.gatewayClient) {
+        throw new plugins.typedrequest.TypedResponseError('gateway client token is missing gatewayClient binding');
+      }
+      if (ownership.gatewayClientType && ownership.gatewayClientType !== policy.gatewayClient.type) {
+        throw new plugins.typedrequest.TypedResponseError('gateway client token cannot act for this ownership');
+      }
+      if (ownership.gatewayClientId && ownership.gatewayClientId !== policy.gatewayClient.id) {
+        throw new plugins.typedrequest.TypedResponseError('gateway client token cannot act for this ownership');
+      }
+      return {
+        gatewayClientType: policy.gatewayClient.type,
+        gatewayClientId: policy.gatewayClient.id,
+        appId: ownership.appId,
+        hostname: ownership.hostname,
+      };
+    }
+
+    if (!ownership.gatewayClientType || !ownership.gatewayClientId) {
+      throw new plugins.typedrequest.TypedResponseError('gateway client ownership is missing type or id');
+    }
+    return ownership as Required<interfaces.data.IGatewayClientOwnership>;
+  }
+
+  private assertGatewayClientOwnership(auth: TAuthContext, ownership: Required<interfaces.data.IGatewayClientOwnership>): void {
    const policy = auth.token?.policy;
    if (!policy || policy.role !== 'gatewayClient') return;
-    if (!policy.gatewayClient) {
-      throw new plugins.typedrequest.TypedResponseError('gateway client token is missing gatewayClient binding');
-    }
-    if (ownership.gatewayClientType !== policy.gatewayClient.type || ownership.gatewayClientId !== policy.gatewayClient.id) {
-      throw new plugins.typedrequest.TypedResponseError('gateway client token cannot act for this ownership');
-    }
    if (!this.matchesHostnamePatterns(ownership.hostname, policy.hostnamePatterns || [])) {
      throw new plugins.typedrequest.TypedResponseError('hostname is outside token policy');
    }
@@ -403,7 +576,8 @@ export class WorkHosterHandler {
    enabled?: boolean,
    deleteRoute?: boolean,
  ): Promise<interfaces.data.IGatewayClientRouteSyncResult> {
-    this.assertGatewayClientOwnership(auth, ownership);
+    const resolvedOwnership = this.resolveGatewayClientOwnership(auth, ownership);
+    this.assertGatewayClientOwnership(auth, resolvedOwnership);
    this.assertRouteTargetsAllowed(auth, route);

    const manager = this.opsServerRef.dcRouterRef.routeConfigManager;
@@ -411,7 +585,7 @@ export class WorkHosterHandler {
      return { success: false, message: 'Route management not initialized' };
    }

-    const externalKey = this.buildGatewayClientExternalKey(ownership);
+    const externalKey = this.buildGatewayClientExternalKey(resolvedOwnership);
    const existingRoute = manager.findApiRouteByExternalKey(externalKey);

    if (deleteRoute) {
@@ -430,15 +604,15 @@ export class WorkHosterHandler {

    const metadata: interfaces.data.IRouteMetadata = {
      ownerType: 'gatewayClient',
-      gatewayClientType: ownership.gatewayClientType,
-      gatewayClientId: ownership.gatewayClientId,
-      gatewayClientAppId: ownership.appId,
-      workHosterType: ownership.gatewayClientType,
-      workHosterId: ownership.gatewayClientId,
-      workAppId: ownership.appId,
+      gatewayClientType: resolvedOwnership.gatewayClientType,
+      gatewayClientId: resolvedOwnership.gatewayClientId,
+      gatewayClientAppId: resolvedOwnership.appId,
+      workHosterType: resolvedOwnership.gatewayClientType,
+      workHosterId: resolvedOwnership.gatewayClientId,
+      workAppId: resolvedOwnership.appId,
      externalKey,
    };
-    const normalizedRoute = this.normalizeGatewayClientRoute(route, ownership, externalKey);
+    const normalizedRoute = this.normalizeGatewayClientRoute(route, resolvedOwnership, externalKey);

    if (existingRoute) {
      const result = await manager.updateRoute(existingRoute.id, {
@@ -455,7 +629,7 @@ export class WorkHosterHandler {
    return { success: true, action: 'created', routeId };
  }

-  private buildGatewayClientExternalKey(ownership: interfaces.data.IGatewayClientOwnership): string {
+  private buildGatewayClientExternalKey(ownership: Required<interfaces.data.IGatewayClientOwnership>): string {
    return [
      ownership.gatewayClientType,
      ownership.gatewayClientId,
@@ -478,7 +652,7 @@ export class WorkHosterHandler {

  private normalizeGatewayClientRoute(
    route: interfaces.data.IDcRouterRouteConfig,
-    ownership: interfaces.data.IGatewayClientOwnership,
+    ownership: Required<interfaces.data.IGatewayClientOwnership>,
    externalKey: string,
  ): interfaces.data.IDcRouterRouteConfig {
    const normalizedRoute = { ...route };