@serve.zone/dcrouter 13.30.0 → 13.32.0

package/ts/opsserver/handlers/security.handler.ts

@@ -2,6 +2,7 @@ import * as plugins from '../../plugins.js';
 import type { OpsServer } from '../classes.opsserver.js';
 import * as interfaces from '../../../ts_interfaces/index.js';
 import { MetricsManager } from '../../monitoring/index.js';
+import { requireOpsAuth } from '../helpers/auth.js';
 
 export class SecurityHandler {
   constructor(private opsServerRef: OpsServer) {
@@ -17,6 +18,7 @@ export class SecurityHandler {
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetSecurityMetrics>(
         'getSecurityMetrics',
         async (dataArg, toolsArg) => {
+          await requireOpsAuth(this.opsServerRef, dataArg, { scope: 'security:read' });
           const metrics = await this.collectSecurityMetrics();
           return {
             metrics: {
@@ -43,6 +45,7 @@ export class SecurityHandler {
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetActiveConnections>(
         'getActiveConnections',
         async (dataArg, toolsArg) => {
+          await requireOpsAuth(this.opsServerRef, dataArg, { scope: 'stats:read' });
           const connections = await this.getActiveConnections(dataArg.protocol, dataArg.state);
           const connectionInfos: interfaces.data.IConnectionInfo[] = connections.map(conn => ({
             id: conn.id,
@@ -82,6 +85,7 @@ export class SecurityHandler {
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetNetworkStats>(
         'getNetworkStats',
         async (dataArg, toolsArg) => {
+          await requireOpsAuth(this.opsServerRef, dataArg, { scope: 'stats:read' });
           // Get network stats from MetricsManager if available
           if (this.opsServerRef.dcRouterRef.metricsManager) {
             const networkStats = await this.opsServerRef.dcRouterRef.metricsManager.getNetworkStats();
@@ -136,6 +140,7 @@ export class SecurityHandler {
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetRateLimitStatus>(
         'getRateLimitStatus',
         async (dataArg, toolsArg) => {
+          await requireOpsAuth(this.opsServerRef, dataArg, { scope: 'security:read' });
           const status = await this.getRateLimitStatus(dataArg.domain, dataArg.ip);
           const limits: interfaces.data.IRateLimitInfo[] = status.limits.map(limit => ({
             domain: limit.identifier,
@@ -161,7 +166,8 @@ export class SecurityHandler {
     router.addTypedHandler(
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_ListSecurityBlockRules>(
         'listSecurityBlockRules',
-        async () => {
+        async (dataArg) => {
+          await requireOpsAuth(this.opsServerRef, dataArg, { scope: 'security:read' });
           const manager = this.opsServerRef.dcRouterRef.securityPolicyManager;
           return { rules: manager ? await manager.listBlockRules() : [] };
         },
@@ -171,7 +177,8 @@ export class SecurityHandler {
     router.addTypedHandler(
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_ListIpIntelligence>(
         'listIpIntelligence',
-        async () => {
+        async (dataArg) => {
+          await requireOpsAuth(this.opsServerRef, dataArg, { scope: 'security:read' });
           const manager = this.opsServerRef.dcRouterRef.securityPolicyManager;
           return { records: manager ? await manager.listIpIntelligence() : [] };
         },
@@ -181,7 +188,8 @@ export class SecurityHandler {
     router.addTypedHandler(
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetCompiledSecurityPolicy>(
         'getCompiledSecurityPolicy',
-        async () => {
+        async (dataArg) => {
+          await requireOpsAuth(this.opsServerRef, dataArg, { scope: 'security:read' });
           const manager = this.opsServerRef.dcRouterRef.securityPolicyManager;
           return {
             policy: manager
@@ -196,6 +204,7 @@ export class SecurityHandler {
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_ListSecurityPolicyAudit>(
         'listSecurityPolicyAudit',
         async (dataArg) => {
+          await requireOpsAuth(this.opsServerRef, dataArg, { scope: 'security:read' });
           const manager = this.opsServerRef.dcRouterRef.securityPolicyManager;
           return { events: manager ? await manager.listAuditEvents(dataArg.limit || 100) : [] };
         },
@@ -208,6 +217,10 @@ export class SecurityHandler {
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_CreateSecurityBlockRule>(
         'createSecurityBlockRule',
         async (dataArg) => {
+          const auth = await requireOpsAuth(this.opsServerRef, dataArg, {
+            scope: 'security:write',
+            requireAdminIdentity: true,
+          });
           const manager = this.opsServerRef.dcRouterRef.securityPolicyManager;
           if (!manager) return { success: false, message: 'Security policy manager not initialized' };
           const rule = await manager.createBlockRule({
@@ -216,7 +229,7 @@ export class SecurityHandler {
             matchMode: dataArg.matchMode,
             reason: dataArg.reason,
             enabled: dataArg.enabled,
-          }, dataArg.identity.userId);
+          }, auth.userId);
           return { success: true, rule };
         },
       ),
@@ -226,6 +239,10 @@ export class SecurityHandler {
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_UpdateSecurityBlockRule>(
         'updateSecurityBlockRule',
         async (dataArg) => {
+          const auth = await requireOpsAuth(this.opsServerRef, dataArg, {
+            scope: 'security:write',
+            requireAdminIdentity: true,
+          });
           const manager = this.opsServerRef.dcRouterRef.securityPolicyManager;
           if (!manager) return { success: false, message: 'Security policy manager not initialized' };
           const rule = await manager.updateBlockRule(dataArg.id, {
@@ -233,7 +250,7 @@ export class SecurityHandler {
             matchMode: dataArg.matchMode,
             reason: dataArg.reason,
             enabled: dataArg.enabled,
-          }, dataArg.identity.userId);
+          }, auth.userId);
           return rule ? { success: true, rule } : { success: false, message: 'Rule not found' };
         },
       ),
@@ -243,9 +260,13 @@ export class SecurityHandler {
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_DeleteSecurityBlockRule>(
         'deleteSecurityBlockRule',
         async (dataArg) => {
+          const auth = await requireOpsAuth(this.opsServerRef, dataArg, {
+            scope: 'security:write',
+            requireAdminIdentity: true,
+          });
           const manager = this.opsServerRef.dcRouterRef.securityPolicyManager;
           if (!manager) return { success: false, message: 'Security policy manager not initialized' };
-          const success = await manager.deleteBlockRule(dataArg.id, dataArg.identity.userId);
+          const success = await manager.deleteBlockRule(dataArg.id, auth.userId);
           return { success, message: success ? undefined : 'Rule not found' };
         },
       ),
@@ -255,6 +276,10 @@ export class SecurityHandler {
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_RefreshIpIntelligence>(
         'refreshIpIntelligence',
         async (dataArg) => {
+          await requireOpsAuth(this.opsServerRef, dataArg, {
+            scope: 'security:write',
+            requireAdminIdentity: true,
+          });
           const manager = this.opsServerRef.dcRouterRef.securityPolicyManager;
           if (!manager) return { success: false, message: 'Security policy manager not initialized' };
           const record = await manager.refreshIpIntelligence(dataArg.ipAddress);

package/ts/opsserver/handlers/source-profile.handler.ts

@@ -1,6 +1,7 @@
 import * as plugins from '../../plugins.js';
 import type { OpsServer } from '../classes.opsserver.js';
 import * as interfaces from '../../../ts_interfaces/index.js';
+import { requireOpsAuth } from '../helpers/auth.js';
 
 export class SourceProfileHandler {
   public typedrouter = new plugins.typedrequest.TypedRouter();
@@ -14,29 +15,11 @@ export class SourceProfileHandler {
     request: { identity?: interfaces.data.IIdentity; apiToken?: string },
     requiredScope?: interfaces.data.TApiTokenScope,
   ): Promise<string> {
-    if (request.identity?.jwt) {
-      try {
-        const isAdmin = await this.opsServerRef.adminHandler.adminIdentityGuard.exec({
-          identity: request.identity,
-        });
-        if (isAdmin) return request.identity.userId;
-      } catch { /* fall through */ }
-    }
-
-    if (request.apiToken) {
-      const tokenManager = this.opsServerRef.dcRouterRef.apiTokenManager;
-      if (tokenManager) {
-        const token = await tokenManager.validateToken(request.apiToken);
-        if (token) {
-          if (!requiredScope || tokenManager.hasScope(token, requiredScope)) {
-            return token.createdBy;
-          }
-          throw new plugins.typedrequest.TypedResponseError('insufficient scope');
-        }
-      }
-    }
-
-    throw new plugins.typedrequest.TypedResponseError('unauthorized');
+    const auth = await requireOpsAuth(this.opsServerRef, request, {
+      scope: requiredScope,
+      requireAdminIdentity: requiredScope?.endsWith(':write'),
+    });
+    return auth.userId;
   }
 
   private registerHandlers(): void {

package/ts/opsserver/handlers/stats.handler.ts

@@ -4,6 +4,7 @@ import * as interfaces from '../../../ts_interfaces/index.js';
 import { MetricsManager } from '../../monitoring/index.js';
 import { SecurityLogger } from '../../security/classes.securitylogger.js';
 import { commitinfo } from '../../00_commitinfo_data.js';
+import { requireOpsAuth } from '../helpers/auth.js';
 
 export class StatsHandler {
   constructor(private opsServerRef: OpsServer) {
@@ -19,6 +20,7 @@ export class StatsHandler {
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetServerStatistics>(
         'getServerStatistics',
         async (dataArg, toolsArg) => {
+          await requireOpsAuth(this.opsServerRef, dataArg, { scope: 'stats:read' });
           const stats = await this.collectServerStats();
           return {
             stats: {
@@ -42,6 +44,7 @@ export class StatsHandler {
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetEmailStatistics>(
         'getEmailStatistics',
         async (dataArg, toolsArg) => {
+          await requireOpsAuth(this.opsServerRef, dataArg, { scope: 'stats:read' });
           const emailServer = this.opsServerRef.dcRouterRef.emailServer;
           if (!emailServer) {
             return {
@@ -81,6 +84,7 @@ export class StatsHandler {
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetDnsStatistics>(
         'getDnsStatistics',
         async (dataArg, toolsArg) => {
+          await requireOpsAuth(this.opsServerRef, dataArg, { scope: 'stats:read' });
           const dnsServer = this.opsServerRef.dcRouterRef.dnsServer;
           if (!dnsServer) {
             return {
@@ -118,6 +122,7 @@ export class StatsHandler {
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetQueueStatus>(
         'getQueueStatus',
         async (dataArg, toolsArg) => {
+          await requireOpsAuth(this.opsServerRef, dataArg, { scope: 'stats:read' });
           const emailServer = this.opsServerRef.dcRouterRef.emailServer;
           const queues: interfaces.data.IQueueStatus[] = [];
           
@@ -146,6 +151,7 @@ export class StatsHandler {
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetHealthStatus>(
         'getHealthStatus',
         async (dataArg, toolsArg) => {
+          await requireOpsAuth(this.opsServerRef, dataArg, { scope: 'stats:read' });
           const health = await this.checkHealthStatus();
           return {
             health: {
@@ -171,6 +177,7 @@ export class StatsHandler {
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetCombinedMetrics>(
         'getCombinedMetrics',
         async (dataArg, toolsArg) => {
+          await requireOpsAuth(this.opsServerRef, dataArg, { scope: 'stats:read' });
           const sections = dataArg.sections || {
             server: true,
             email: true,

package/ts/opsserver/handlers/target-profile.handler.ts

@@ -1,6 +1,7 @@
 import * as plugins from '../../plugins.js';
 import type { OpsServer } from '../classes.opsserver.js';
 import * as interfaces from '../../../ts_interfaces/index.js';
+import { requireOpsAuth } from '../helpers/auth.js';
 
 export class TargetProfileHandler {
   public typedrouter = new plugins.typedrequest.TypedRouter();
@@ -14,29 +15,11 @@ export class TargetProfileHandler {
     request: { identity?: interfaces.data.IIdentity; apiToken?: string },
     requiredScope?: interfaces.data.TApiTokenScope,
   ): Promise<string> {
-    if (request.identity?.jwt) {
-      try {
-        const isAdmin = await this.opsServerRef.adminHandler.adminIdentityGuard.exec({
-          identity: request.identity,
-        });
-        if (isAdmin) return request.identity.userId;
-      } catch { /* fall through */ }
-    }
-
-    if (request.apiToken) {
-      const tokenManager = this.opsServerRef.dcRouterRef.apiTokenManager;
-      if (tokenManager) {
-        const token = await tokenManager.validateToken(request.apiToken);
-        if (token) {
-          if (!requiredScope || tokenManager.hasScope(token, requiredScope)) {
-            return token.createdBy;
-          }
-          throw new plugins.typedrequest.TypedResponseError('insufficient scope');
-        }
-      }
-    }
-
-    throw new plugins.typedrequest.TypedResponseError('unauthorized');
+    const auth = await requireOpsAuth(this.opsServerRef, request, {
+      scope: requiredScope,
+      requireAdminIdentity: requiredScope?.endsWith(':write'),
+    });
+    return auth.userId;
   }
 
   private registerHandlers(): void {

package/ts/opsserver/handlers/users.handler.ts

@@ -1,9 +1,10 @@
 import * as plugins from '../../plugins.js';
 import type { OpsServer } from '../classes.opsserver.js';
 import * as interfaces from '../../../ts_interfaces/index.js';
+import { requireOpsAuth } from '../helpers/auth.js';
 
 /**
- * Read-only handler for OpsServer user accounts. Registers on adminRouter,
+ * Handler for OpsServer user accounts. Registers on adminRouter,
  * so admin middleware enforces auth + role check before the handler runs.
  * User data is owned by AdminHandler; this handler just exposes a safe
  * projection of it via TypedRequest.
@@ -16,15 +17,57 @@ export class UsersHandler {
   private registerHandlers(): void {
     const router = this.opsServerRef.adminRouter;
 
-    // List users (admin-only, read-only)
+    // List users (admin-only)
     router.addTypedHandler(
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_ListUsers>(
         'listUsers',
-        async (_dataArg) => {
+        async (dataArg) => {
+          await requireOpsAuth(this.opsServerRef, dataArg, {
+            scope: 'users:read',
+            requireAdminIdentity: true,
+            requireAdminToken: true,
+          });
           const users = await this.opsServerRef.adminHandler.listUsers();
           return { users };
         },
       ),
     );
+
+    router.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_CreateUser>(
+        'createUser',
+        async (dataArg) => {
+          await requireOpsAuth(this.opsServerRef, dataArg, {
+            scope: 'users:manage',
+            requireAdminIdentity: true,
+            requireAdminToken: true,
+          });
+          return this.opsServerRef.adminHandler.createUser({
+            email: dataArg.email,
+            name: dataArg.name,
+            role: dataArg.role,
+            password: dataArg.password,
+            enableIdpGlobalAuth: dataArg.enableIdpGlobalAuth,
+          });
+        },
+      ),
+    );
+
+    router.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_DeleteUser>(
+        'deleteUser',
+        async (dataArg) => {
+          const auth = await requireOpsAuth(this.opsServerRef, dataArg, {
+            scope: 'users:manage',
+            requireAdminIdentity: true,
+            requireAdminToken: true,
+          });
+          return this.opsServerRef.adminHandler.deleteUser({
+            id: dataArg.id,
+            requestingUserId: auth.userId,
+          });
+        },
+      ),
+    );
   }
 }

package/ts/opsserver/handlers/vpn.handler.ts

@@ -1,6 +1,7 @@
 import * as plugins from '../../plugins.js';
 import type { OpsServer } from '../classes.opsserver.js';
 import * as interfaces from '../../../ts_interfaces/index.js';
+import { requireOpsAuth } from '../helpers/auth.js';
 
 export class VpnHandler {
   constructor(private opsServerRef: OpsServer) {
@@ -18,6 +19,7 @@ export class VpnHandler {
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetVpnClients>(
         'getVpnClients',
         async (dataArg, toolsArg) => {
+          await requireOpsAuth(this.opsServerRef, dataArg, { scope: 'vpn:read' });
           const manager = this.opsServerRef.dcRouterRef.vpnManager;
           if (!manager) {
             return { clients: [] };
@@ -49,6 +51,7 @@ export class VpnHandler {
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetVpnStatus>(
         'getVpnStatus',
         async (dataArg, toolsArg) => {
+          await requireOpsAuth(this.opsServerRef, dataArg, { scope: 'vpn:read' });
           const manager = this.opsServerRef.dcRouterRef.vpnManager;
           const vpnConfig = this.opsServerRef.dcRouterRef.options.vpnConfig;
           if (!manager) {
@@ -84,6 +87,7 @@ export class VpnHandler {
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetVpnConnectedClients>(
         'getVpnConnectedClients',
         async (dataArg, toolsArg) => {
+          await requireOpsAuth(this.opsServerRef, dataArg, { scope: 'vpn:read' });
           const manager = this.opsServerRef.dcRouterRef.vpnManager;
           if (!manager) {
             return { connectedClients: [] };
@@ -111,6 +115,10 @@ export class VpnHandler {
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_CreateVpnClient>(
         'createVpnClient',
         async (dataArg, toolsArg) => {
+          await requireOpsAuth(this.opsServerRef, dataArg, {
+            scope: 'vpn:write',
+            requireAdminIdentity: true,
+          });
           const manager = this.opsServerRef.dcRouterRef.vpnManager;
           if (!manager) {
             return { success: false, message: 'VPN not configured' };
@@ -168,6 +176,10 @@ export class VpnHandler {
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_UpdateVpnClient>(
         'updateVpnClient',
         async (dataArg, toolsArg) => {
+          await requireOpsAuth(this.opsServerRef, dataArg, {
+            scope: 'vpn:write',
+            requireAdminIdentity: true,
+          });
           const manager = this.opsServerRef.dcRouterRef.vpnManager;
           if (!manager) {
             return { success: false, message: 'VPN not configured' };
@@ -198,6 +210,10 @@ export class VpnHandler {
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_DeleteVpnClient>(
         'deleteVpnClient',
         async (dataArg, toolsArg) => {
+          await requireOpsAuth(this.opsServerRef, dataArg, {
+            scope: 'vpn:write',
+            requireAdminIdentity: true,
+          });
           const manager = this.opsServerRef.dcRouterRef.vpnManager;
           if (!manager) {
             return { success: false, message: 'VPN not configured' };
@@ -218,6 +234,10 @@ export class VpnHandler {
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_EnableVpnClient>(
         'enableVpnClient',
         async (dataArg, toolsArg) => {
+          await requireOpsAuth(this.opsServerRef, dataArg, {
+            scope: 'vpn:write',
+            requireAdminIdentity: true,
+          });
           const manager = this.opsServerRef.dcRouterRef.vpnManager;
           if (!manager) {
             return { success: false, message: 'VPN not configured' };
@@ -238,6 +258,10 @@ export class VpnHandler {
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_DisableVpnClient>(
         'disableVpnClient',
         async (dataArg, toolsArg) => {
+          await requireOpsAuth(this.opsServerRef, dataArg, {
+            scope: 'vpn:write',
+            requireAdminIdentity: true,
+          });
           const manager = this.opsServerRef.dcRouterRef.vpnManager;
           if (!manager) {
             return { success: false, message: 'VPN not configured' };
@@ -258,6 +282,10 @@ export class VpnHandler {
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_RotateVpnClientKey>(
         'rotateVpnClientKey',
         async (dataArg, toolsArg) => {
+          await requireOpsAuth(this.opsServerRef, dataArg, {
+            scope: 'vpn:write',
+            requireAdminIdentity: true,
+          });
           const manager = this.opsServerRef.dcRouterRef.vpnManager;
           if (!manager) {
             return { success: false, message: 'VPN not configured' };
@@ -281,6 +309,10 @@ export class VpnHandler {
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_ExportVpnClientConfig>(
         'exportVpnClientConfig',
         async (dataArg, toolsArg) => {
+          await requireOpsAuth(this.opsServerRef, dataArg, {
+            scope: 'vpn:write',
+            requireAdminIdentity: true,
+          });
           const manager = this.opsServerRef.dcRouterRef.vpnManager;
           if (!manager) {
             return { success: false, message: 'VPN not configured' };
@@ -301,6 +333,7 @@ export class VpnHandler {
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetVpnClientTelemetry>(
         'getVpnClientTelemetry',
         async (dataArg, toolsArg) => {
+          await requireOpsAuth(this.opsServerRef, dataArg, { scope: 'vpn:read' });
           const manager = this.opsServerRef.dcRouterRef.vpnManager;
           if (!manager) {
             return { success: false, message: 'VPN not configured' };

package/ts/opsserver/handlers/workhoster.handler.ts

@@ -1,6 +1,7 @@
 import * as plugins from '../../plugins.js';
 import type { OpsServer } from '../classes.opsserver.js';
 import * as interfaces from '../../../ts_interfaces/index.js';
+import { requireOpsAuth } from '../helpers/auth.js';
 
 type TAuthContext = {
   userId: string;
@@ -20,39 +21,23 @@ export class WorkHosterHandler {
     request: { identity?: interfaces.data.IIdentity; apiToken?: string },
     requiredScope?: interfaces.data.TApiTokenScope,
   ): Promise<TAuthContext> {
-    if (request.identity?.jwt) {
-      try {
-        const isAdmin = await this.opsServerRef.adminHandler.adminIdentityGuard.exec({
-          identity: request.identity,
-        });
-        if (isAdmin) return { userId: request.identity.userId, isAdmin: true };
-      } catch { /* fall through */ }
-    }
-
-    if (request.apiToken) {
-      const tokenManager = this.opsServerRef.dcRouterRef.apiTokenManager;
-      if (tokenManager) {
-        const token = await tokenManager.validateToken(request.apiToken);
-        if (token) {
-          if (!requiredScope || tokenManager.hasScope(token, requiredScope)) {
-            return { userId: token.createdBy, isAdmin: token.policy?.role === 'admin', token };
-          }
-          throw new plugins.typedrequest.TypedResponseError('insufficient scope');
-        }
-      }
-    }
-
-    throw new plugins.typedrequest.TypedResponseError('unauthorized');
+    const auth = await requireOpsAuth(this.opsServerRef, request, {
+      scope: requiredScope,
+      requireAdminIdentity: requiredScope?.endsWith(':write'),
+    });
+    return { userId: auth.userId, isAdmin: auth.isAdmin, token: auth.token };
   }
 
-  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 async requireAdmin(
+    request: { identity?: interfaces.data.IIdentity; apiToken?: string },
+    scope: interfaces.data.TApiTokenScope = 'gateway-clients:write',
+  ): Promise<string> {
+    const auth = await requireOpsAuth(this.opsServerRef, request, {
+      scope,
+      requireAdminIdentity: true,
+      requireAdminToken: true,
+    });
+    return auth.userId;
   }
 
   private registerHandlers(): void {
@@ -83,7 +68,7 @@ export class WorkHosterHandler {
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_ListGatewayClients>(
         'listGatewayClients',
         async (dataArg) => {
-          await this.requireAdmin(dataArg);
+          await this.requireAdmin(dataArg, 'gateway-clients:read');
           return { gatewayClients: await this.listManagedGatewayClients() };
         },
       ),
@@ -154,7 +139,7 @@ export class WorkHosterHandler {
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_CreateGatewayClientToken>(
         'createGatewayClientToken',
         async (dataArg) => {
-          const userId = await this.requireAdmin(dataArg);
+          const userId = await this.requireAdmin(dataArg, 'tokens:manage');
           const gatewayClient = await this.opsServerRef.dcRouterRef.gatewayClientManager?.getClient(dataArg.gatewayClientId);
           const tokenManager = this.opsServerRef.dcRouterRef.apiTokenManager;
           if (!gatewayClient || !gatewayClient.enabled) {

package/ts/opsserver/helpers/auth.ts

@@ -0,0 +1,91 @@
+import * as plugins from '../../plugins.js';
+import type { OpsServer } from '../classes.opsserver.js';
+import * as interfaces from '../../../ts_interfaces/index.js';
+
+export interface IAuthRequest {
+  identity?: interfaces.data.IIdentity;
+  apiToken?: string;
+}
+
+export interface IAuthRequirement {
+  scope?: interfaces.data.TApiTokenScope;
+  requireAdminIdentity?: boolean;
+  requireAdminToken?: boolean;
+}
+
+export interface IAuthContext {
+  type: 'identity' | 'apiToken';
+  userId: string;
+  role?: string;
+  isAdmin: boolean;
+  scopes: interfaces.data.TApiTokenScope[];
+  identity?: interfaces.data.IIdentity;
+  token?: interfaces.data.IStoredApiToken;
+}
+
+const typedAuthError = (messageArg: string) => {
+  return new plugins.typedrequest.TypedResponseError(messageArg);
+};
+
+export async function requireOpsAuth(
+  opsServerRefArg: OpsServer,
+  requestArg: IAuthRequest,
+  requirementArg: IAuthRequirement = {},
+): Promise<IAuthContext> {
+  let identityNeedsAdmin = false;
+  let tokenNeedsAdmin = false;
+  let tokenNeedsScope = false;
+
+  if (requestArg.identity?.jwt) {
+    const identity = await opsServerRefArg.adminHandler.validateIdentity(requestArg.identity);
+    if (identity) {
+      const isAdmin = identity.role === 'admin';
+      if (!requirementArg.requireAdminIdentity || isAdmin) {
+        return {
+          type: 'identity',
+          userId: identity.userId,
+          role: identity.role,
+          isAdmin,
+          scopes: [],
+          identity,
+        };
+      }
+      identityNeedsAdmin = true;
+    }
+  }
+
+  if (requestArg.apiToken) {
+    const tokenManager = opsServerRefArg.dcRouterRef.apiTokenManager;
+    const token = tokenManager ? await tokenManager.validateToken(requestArg.apiToken) : null;
+    if (token) {
+      if (requirementArg.requireAdminToken && token.policy?.role !== 'admin') {
+        tokenNeedsAdmin = true;
+      } else if (requirementArg.scope && !tokenManager!.hasScope(token, requirementArg.scope)) {
+        tokenNeedsScope = true;
+      } else {
+        const scopes = token.policy?.role === 'admin'
+          ? ['*' as interfaces.data.TApiTokenScope]
+          : Array.from(new Set([...(token.scopes || []), ...(token.policy?.scopes || [])]));
+        return {
+          type: 'apiToken',
+          userId: token.createdBy,
+          role: token.policy?.role || 'operator',
+          isAdmin: token.policy?.role === 'admin',
+          scopes,
+          token,
+        };
+      }
+    }
+  }
+
+  if (tokenNeedsScope) {
+    throw typedAuthError('insufficient scope');
+  }
+  if (tokenNeedsAdmin) {
+    throw typedAuthError('admin API token required');
+  }
+  if (identityNeedsAdmin) {
+    throw typedAuthError('admin identity required');
+  }
+  throw typedAuthError('unauthorized');
+}

package/ts_web/00_commitinfo_data.ts

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