@serve.zone/dcrouter 17.2.4 → 17.4.0

package/ts/opsserver/handlers/gatewayclient.handler.ts

@@ -2,12 +2,15 @@ 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;
-  isAdmin: boolean;
-  token?: interfaces.data.IStoredApiToken;
-};
+import { CachedEmail } from '../../db/index.js';
+import {
+  type IGatewayMachineAuthContext as TAuthContext,
+  getGatewayCredentialState,
+  matchesGatewayHostnamePatterns,
+  normalizeGatewayHostname,
+  normalizeGatewayTargetHost,
+  requireGatewayMachineAuth,
+} from '../helpers/gateway-client-auth.js';
 
 type TResolvedGatewayClientOwnership = Required<Pick<plugins.servezoneInterfaces.data.IGatewayClientOwnership,
   'gatewayClientType' | 'gatewayClientId' | 'appId'
@@ -18,6 +21,8 @@ type TResolvedGatewayClientOwnership = Required<Pick<plugins.servezoneInterfaces
 
 export class GatewayClientHandler {
   public typedrouter = new plugins.typedrequest.TypedRouter();
+  private routeSyncChains = new Map<string, Promise<void>>();
+  private gatewayClientCredentialChains = new Map<string, Promise<void>>();
 
   constructor(private opsServerRef: OpsServer) {
     this.opsServerRef.typedrouter.addTypedRouter(this.typedrouter);
@@ -27,12 +32,14 @@ export class GatewayClientHandler {
   private async requireAuth(
     request: { identity?: interfaces.data.IIdentity; apiToken?: string },
     requiredScope?: interfaces.data.TApiTokenScope,
+    options: { allowCandidate?: boolean } = {},
   ): Promise<TAuthContext> {
-    const auth = await requireOpsAuth(this.opsServerRef, request, {
-      scope: requiredScope,
-      requireAdminIdentity: requiredScope?.endsWith(':write'),
-    });
-    return { userId: auth.userId, isAdmin: auth.isAdmin, token: auth.token };
+    return await requireGatewayMachineAuth(
+      this.opsServerRef,
+      request,
+      requiredScope === 'gateway-clients:write' ? 'gateway-clients:write' : 'gateway-clients:read',
+      options,
+    );
   }
 
   private async requireAdmin(
@@ -58,11 +65,150 @@ export class GatewayClientHandler {
       ),
     );
 
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<plugins.servezoneInterfaces.requests.gateway.IReq_ProvisionGatewayClientCredential>(
+        'provisionGatewayClientCredential',
+        async (dataArg) => {
+          try {
+            const userId = await this.requireAdmin(dataArg, 'tokens:manage');
+            const clientManager = this.opsServerRef.dcRouterRef.gatewayClientManager;
+            const tokenManager = this.opsServerRef.dcRouterRef.apiTokenManager;
+            if (!clientManager || !tokenManager) {
+              return { success: false, message: 'Gateway client or token management not initialized' };
+            }
+            const lockKey = this.normalizeGatewayClientLockKey(dataArg.provisioning.id);
+            return await this.withGatewayClientCredentialLock(lockKey, async () => {
+              if (dataArg.provisioning.enabled === false) {
+                return { success: false, message: 'Cannot provision a credential for a disabled gateway client' };
+              }
+              const provisioned = await clientManager.stageClientProvisioning(
+                dataArg.provisioning,
+                userId,
+              );
+              if (!provisioned.gatewayClient.enabled) {
+                return { success: false, message: 'Cannot provision a credential for a disabled gateway client' };
+              }
+              const policy = this.buildGatewayClientTokenPolicy(provisioned.gatewayClient);
+              const issuedAt = Date.now();
+              const credential = await tokenManager.createProvisionedGatewayCredentialCandidate(
+                dataArg.credentialName?.trim() || `${provisioned.gatewayClient.name} Credential`,
+                ['gateway-clients:read', 'gateway-clients:write'],
+                dataArg.expiresInDays ?? null,
+                userId,
+                policy,
+                provisioned.credentialSequence,
+                provisioned.policyDigest,
+              );
+              return {
+                success: true,
+                action: provisioned.action,
+                gatewayClient: provisioned.gatewayClient,
+                credential: {
+                  tokenId: credential.id,
+                  tokenValue: credential.rawToken,
+                  issuedAt,
+                  state: 'candidate' as const,
+                  finalizationRequired: true as const,
+                },
+              };
+            });
+          } catch (error) {
+            return { success: false, message: (error as Error).message };
+          }
+        },
+      ),
+    );
+
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<plugins.servezoneInterfaces.requests.gateway.IReq_FinalizeGatewayClientCredential>(
+        'finalizeGatewayClientCredential',
+        async (dataArg) => {
+          try {
+            if ('identity' in dataArg) {
+              return { success: false, message: 'Identity authentication cannot finalize gateway credentials' };
+            }
+            const tokenManager = this.opsServerRef.dcRouterRef.apiTokenManager;
+            const clientManager = this.opsServerRef.dcRouterRef.gatewayClientManager;
+            if (!tokenManager || !clientManager) {
+              return { success: false, message: 'Gateway client or token management not initialized' };
+            }
+            const initialToken = await tokenManager.validateToken(dataArg.apiToken);
+            if (!initialToken) {
+              return { success: false, message: 'Candidate gateway credential is invalid or revoked' };
+            }
+            const gatewayClientId = this.requireFinalizableGatewayCredential(initialToken, dataArg.tokenId);
+            return await this.withGatewayClientCredentialLock(gatewayClientId, async () => {
+              const lockedToken = await tokenManager.validateToken(dataArg.apiToken);
+              if (!lockedToken) {
+                return { success: false, message: 'Candidate gateway credential is invalid or revoked' };
+              }
+              const lockedGatewayClientId = this.requireFinalizableGatewayCredential(
+                lockedToken,
+                dataArg.tokenId,
+              );
+              if (lockedGatewayClientId !== gatewayClientId) {
+                return { success: false, message: 'Gateway credential ownership changed during finalization' };
+              }
+              const lifecycle = lockedToken.gatewayCredentialLifecycle!;
+              if (lifecycle.cleanupCompletedAt !== null) {
+                return {
+                  success: true,
+                  gatewayClientId,
+                  tokenId: dataArg.tokenId,
+                  revokedCredentialCount: lifecycle.revokedCredentialCount!,
+                  finalizedAt: lifecycle.finalizedAt!,
+                };
+              }
+              const tokenBinding = lockedToken.policy!.gatewayClient!;
+              if (lifecycle.state === 'candidate') {
+                const stagedClient = await clientManager.getClientForProvisionedCredential(
+                  gatewayClientId,
+                  tokenBinding.type,
+                  lifecycle,
+                );
+                if (!stagedClient) {
+                  return { success: false, message: 'Gateway credential policy was superseded before finalization' };
+                }
+              }
+              const activation = await tokenManager.activateProvisionedGatewayCredential(
+                dataArg.tokenId,
+                gatewayClientId,
+              );
+              await clientManager.promoteProvisionedPolicy(
+                gatewayClientId,
+                tokenBinding.type,
+                activation.lifecycle,
+              );
+              const revokedCredentialCount = await tokenManager.revokeOlderProvisionedGatewayCredentials(
+                gatewayClientId,
+                activation.lifecycle.sequence,
+                dataArg.tokenId,
+              );
+              const completed = await tokenManager.completeProvisionedGatewayCredentialHandover(
+                dataArg.tokenId,
+                gatewayClientId,
+                revokedCredentialCount,
+              );
+              return {
+                success: true,
+                gatewayClientId,
+                tokenId: dataArg.tokenId,
+                revokedCredentialCount: completed.revokedCredentialCount!,
+                finalizedAt: completed.finalizedAt!,
+              };
+            });
+          } catch (error) {
+            return { success: false, message: (error as Error).message };
+          }
+        },
+      ),
+    );
+
     this.typedrouter.addTypedHandler(
       new plugins.typedrequest.TypedHandler<plugins.servezoneInterfaces.requests.gateway.IReq_GetGatewayClientContext>(
         'getGatewayClientContext',
         async (dataArg) => {
-          const auth = await this.requireAuth(dataArg, 'gateway-clients:read');
+          const auth = await this.requireAuth(dataArg, 'gateway-clients:read', { allowCandidate: true });
           return {
             context: this.getGatewayClientContext(auth),
             capabilities: this.getGatewayCapabilities(),
@@ -89,17 +235,22 @@ export class GatewayClientHandler {
           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 };
+            const create = async () => {
+              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 };
+            };
+            return dataArg.id
+              ? await this.withGatewayClientCredentialLock(this.normalizeGatewayClientLockKey(dataArg.id), create)
+              : await create();
           } catch (error) {
             return { success: false, message: (error as Error).message };
           }
@@ -114,17 +265,23 @@ export class GatewayClientHandler {
           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' };
+          try {
+            return await this.withGatewayClientCredentialLock(this.normalizeGatewayClientLockKey(dataArg.id), async () => {
+              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' };
+            });
+          } catch (error) {
+            return { success: false, message: (error as Error).message };
+          }
         },
       ),
     );
@@ -135,9 +292,24 @@ export class GatewayClientHandler {
         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' };
+          const tokenManager = this.opsServerRef.dcRouterRef.apiTokenManager;
+          if (!manager || !tokenManager) return { success: false, message: 'Gateway client or token management not initialized' };
+          try {
+            return await this.withGatewayClientCredentialLock(this.normalizeGatewayClientLockKey(dataArg.id), async () => {
+              const existing = await manager.getClient(dataArg.id);
+              if (!existing) return { success: false, message: 'Gateway client not found' };
+              await tokenManager.revokeGatewayClientCredentials(dataArg.id);
+              const success = await manager.deleteClient(dataArg.id);
+              return {
+                success,
+                message: success
+                  ? undefined
+                  : 'Gateway client changed during credential cleanup; retry deletion',
+              };
+            });
+          } catch (error) {
+            return { success: false, message: (error as Error).message };
+          }
         },
       ),
     );
@@ -147,29 +319,34 @@ export class GatewayClientHandler {
         'createGatewayClientToken',
         async (dataArg) => {
           const userId = await this.requireAdmin(dataArg, 'tokens:manage');
-          const gatewayClient = await this.opsServerRef.dcRouterRef.gatewayClientManager?.getClient(dataArg.gatewayClientId);
+          const manager = this.opsServerRef.dcRouterRef.gatewayClientManager;
           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 };
+          if (!manager || !tokenManager) return { success: false, message: 'Gateway client or token management not initialized' };
+          return await this.withGatewayClientCredentialLock(this.normalizeGatewayClientLockKey(dataArg.gatewayClientId), async () => {
+            const gatewayClient = await manager.getClient(dataArg.gatewayClientId);
+            if (!gatewayClient || !gatewayClient.enabled) {
+              return { success: false, message: 'Gateway client not found or disabled' };
+            }
+            const result = await tokenManager.createToken(
+              dataArg.name?.trim() || `${gatewayClient.name} Token`,
+              ['gateway-clients:read', 'gateway-clients:write'],
+              dataArg.expiresInDays ?? null,
+              userId,
+              this.buildGatewayClientTokenPolicy(gatewayClient),
+            );
+            return { success: true, tokenId: result.id, tokenValue: result.rawToken };
+          });
+        },
+      ),
+    );
+
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<plugins.servezoneInterfaces.requests.gateway.IReq_GetGatewayClientMailOverview>(
+        'getGatewayClientMailOverview',
+        async (dataArg) => {
+          const auth = await this.requireAuth(dataArg, 'gateway-clients:read');
+          this.assertCapability(auth, 'readMail');
+          return await this.getGatewayClientMailOverview(auth, dataArg.limit);
         },
       ),
     );
@@ -201,7 +378,7 @@ export class GatewayClientHandler {
         'getGatewayClientRoutes',
         async (dataArg) => {
           const auth = await this.requireAuth(dataArg, 'gateway-clients:read');
-          this.assertCapability(auth, 'readDnsRecords');
+          this.assertCapability(auth, 'readRoutes');
           return { routes: this.listGatewayClientRoutes(auth, dataArg.gatewayClientId) };
         },
       ),
@@ -214,7 +391,7 @@ export class GatewayClientHandler {
         async (dataArg) => {
           const auth = await this.requireAuth(dataArg, 'gateway-clients:write');
           this.assertCapability(auth, 'syncRoutes');
-          return await this.syncGatewayClientRoute(auth, dataArg.ownership, dataArg.route, dataArg.enabled, dataArg.delete, dataArg.sourceProfileRef);
+          return await this.syncGatewayClientRoute(auth, dataArg.ownership, dataArg.route, dataArg.enabled, dataArg.delete, dataArg.sourceProfileRef, dataArg.dnsMode);
         },
       ),
     );
@@ -227,6 +404,7 @@ export class GatewayClientHandler {
         'listMailAddressBindings',
         async (dataArg) => {
           const auth = await this.requireAuth(dataArg.auth || {}, 'gateway-clients:read');
+          this.assertCapability(auth, 'readMail');
           const manager = this.opsServerRef.dcRouterRef.workAppMailManager;
           if (!manager) return { bindings: [] };
           const bindings = await manager.listMailAddressBindings({
@@ -246,7 +424,7 @@ export class GatewayClientHandler {
         'syncMailAddressBinding',
         async (dataArg) => {
           const auth = await this.requireAuth(dataArg.auth || {}, 'gateway-clients:write');
-          this.assertCapability(auth, 'syncRoutes');
+          this.assertCapability(auth, 'manageMail');
           const manager = this.opsServerRef.dcRouterRef.workAppMailManager;
           if (!manager) {
             return { success: false, message: 'WorkApp mail manager not initialized' };
@@ -271,12 +449,12 @@ export class GatewayClientHandler {
         'deleteMailAddressBinding',
         async (dataArg) => {
           const auth = await this.requireAuth(dataArg.auth || {}, 'gateway-clients:write');
-          this.assertCapability(auth, 'syncRoutes');
+          this.assertCapability(auth, 'manageMail');
           const manager = this.opsServerRef.dcRouterRef.workAppMailManager;
           if (!manager) {
             return { success: false, message: 'WorkApp mail manager not initialized' };
           }
-          if (auth.token?.policy?.role === 'gatewayClient') {
+          if (auth.policy?.role === 'gatewayClient') {
             const bindings = this.filterMailBindingsAllowed(auth, await manager.listMailAddressBindings({
               owner: this.resolveMailOwnerFilter(auth),
             }));
@@ -294,6 +472,7 @@ export class GatewayClientHandler {
         'listWorkAppMailBindings',
         async (dataArg) => {
           const auth = await this.requireAuth(dataArg.auth || {}, 'gateway-clients:read');
+          this.assertCapability(auth, 'readMail');
           const manager = this.opsServerRef.dcRouterRef.workAppMailManager;
           if (!manager) return { bindings: [] };
           const owner = this.resolveMailOwnerFilter(auth, dataArg.owner);
@@ -308,13 +487,13 @@ export class GatewayClientHandler {
         'rotateMailCredential',
         async (dataArg) => {
           const auth = await this.requireAuth(dataArg.auth || {}, 'gateway-clients:write');
-          this.assertCapability(auth, 'syncRoutes');
+          this.assertCapability(auth, 'manageMail');
           const manager = this.opsServerRef.dcRouterRef.workAppMailManager;
           if (!manager) {
             return { success: false, message: 'WorkApp mail manager not initialized' };
           }
           const owner = this.resolveMailOwnerFilter(auth);
-          if (auth.token?.policy?.role === 'gatewayClient') {
+          if (auth.policy?.role === 'gatewayClient') {
             const credentialId = dataArg.credentialId?.trim();
             const bindings = this.filterMailBindingsAllowed(auth, await manager.listMailAddressBindings({ owner }));
             const binding = bindings.find((bindingArg) => bindingArg.outboundIdentityId === credentialId
@@ -369,6 +548,7 @@ export class GatewayClientHandler {
           }
 
           const auth = await this.requireAuth(authData, 'gateway-clients:read');
+          this.assertCapability(auth, 'readMail');
           const status = await manager.getMailDeliveryStatus(dataArg.spoolItemId);
           if (!this.isMailDeliveryStatusAllowed(auth, status)) {
             return { attempts: [] };
@@ -433,18 +613,118 @@ export class GatewayClientHandler {
   }
 
   private getGatewayClientContext(auth: TAuthContext): plugins.servezoneInterfaces.data.IGatewayClientContext {
-    const policy = auth.token?.policy;
-    const role = auth.isAdmin ? 'admin' : policy?.role || 'operator';
+    const policy = auth.policy;
+    if (auth.gatewayClient && auth.credentialId) {
+      return {
+        role: 'gatewayClient',
+        credentialState: getGatewayCredentialState(auth.token!),
+        credentialId: auth.credentialId,
+        scopes: auth.token?.scopes || [],
+        gatewayClient: {
+          type: auth.gatewayClient.type,
+          id: auth.gatewayClient.id,
+          policyGeneration: auth.gatewayClient.policyGeneration,
+        },
+        hostnamePatterns: policy?.hostnamePatterns || [],
+        allowedRouteTargets: policy?.allowedRouteTargets || [],
+        capabilities: policy?.capabilities || {},
+      };
+    }
     return {
-      role,
+      role: 'admin',
       scopes: auth.token?.scopes || ['*'],
-      gatewayClient: policy?.gatewayClient,
-      hostnamePatterns: policy?.hostnamePatterns || [],
-      allowedRouteTargets: policy?.allowedRouteTargets || [],
-      capabilities: policy?.capabilities || {},
+      hostnamePatterns: [],
+      allowedRouteTargets: [],
+      capabilities: {},
     };
   }
 
+  private buildGatewayClientTokenPolicy(
+    gatewayClientArg: interfaces.data.IGatewayClient,
+  ): interfaces.data.IApiTokenPolicy {
+    return {
+      role: 'gatewayClient',
+      scopes: ['gateway-clients:read', 'gateway-clients:write'],
+      gatewayClient: {
+        type: gatewayClientArg.type,
+        id: gatewayClientArg.id,
+        policyGeneration: gatewayClientArg.policyGeneration,
+      },
+      hostnamePatterns: gatewayClientArg.hostnamePatterns,
+      allowedRouteTargets: gatewayClientArg.allowedRouteTargets,
+      capabilities: gatewayClientArg.capabilities,
+    };
+  }
+
+  private requireFinalizableGatewayCredential(
+    tokenArg: interfaces.data.IStoredApiToken,
+    expectedTokenIdArg: string,
+  ): string {
+    if (tokenArg.id !== expectedTokenIdArg) {
+      throw new Error('tokenId does not match the authenticating gateway credential');
+    }
+    if (tokenArg.policy?.role !== 'gatewayClient' || !tokenArg.policy.gatewayClient?.id) {
+      throw new Error('A bound gateway-client credential is required for finalization');
+    }
+    const lifecycle = tokenArg.gatewayCredentialLifecycle;
+    const validCandidate = lifecycle?.source === 'provisioned'
+      && lifecycle.state === 'candidate'
+      && lifecycle.finalizedAt === null;
+    const validActive = lifecycle?.source === 'provisioned'
+      && lifecycle.state === 'active'
+      && Number.isSafeInteger(lifecycle.finalizedAt)
+      && Number(lifecycle.finalizedAt) > 0;
+    if (!validCandidate && !validActive) {
+      throw new Error('Only provisioned candidate or active gateway credentials can be finalized');
+    }
+    return this.normalizeGatewayClientLockKey(tokenArg.policy.gatewayClient.id);
+  }
+
+  private async getGatewayClientMailOverview(
+    auth: TAuthContext,
+    limitArg?: number,
+  ): Promise<plugins.servezoneInterfaces.requests.gateway.IReq_GetGatewayClientMailOverview['response']> {
+    const manager = this.opsServerRef.dcRouterRef.workAppMailManager;
+    if (!manager) return { domains: [], emails: [] };
+    const owner = this.resolveMailOwnerFilter(auth);
+    const bindings = this.filterMailBindingsAllowed(
+      auth,
+      await manager.listMailAddressBindings({ owner }),
+    );
+    const ownedAddresses = new Set(bindings.map((bindingArg) => bindingArg.address.toLowerCase()));
+    const ownedDomains = Array.from(new Set(bindings.map((bindingArg) => bindingArg.domain)))
+      .sort((left, right) => left.localeCompare(right));
+    const domains = await Promise.all(ownedDomains.map(async (domainArg) => {
+      const configured = await this.opsServerRef.dcRouterRef.emailDomainManager?.getByDomain(domainArg);
+      return {
+        domain: domainArg,
+        dnsMode: configured ? 'managed' : undefined,
+        status: configured?.reconciliation?.lifecycleStatus,
+      };
+    }));
+    const limit = Math.min(Math.max(Math.floor(limitArg ?? 100), 1), 500);
+    const recent = this.opsServerRef.dcRouterRef.dcRouterDb?.isReady()
+      ? await CachedEmail.findRecent(Math.max(limit * 5, 100))
+      : [];
+    const emails = recent
+      .filter((emailArg) => {
+        const from = String(emailArg.from || '').trim().toLowerCase();
+        const recipients = (emailArg.to || []).map((addressArg) => addressArg.trim().toLowerCase());
+        return ownedAddresses.has(from) || recipients.some((addressArg) => ownedAddresses.has(addressArg));
+      })
+      .slice(0, limit)
+      .map((emailArg) => ({
+        id: emailArg.id,
+        direction: emailArg.direction,
+        from: emailArg.from,
+        to: emailArg.to?.[0],
+        subject: emailArg.subject,
+        status: emailArg.status,
+        timestamp: emailArg.acceptedAt,
+      }));
+    return { domains, emails };
+  }
+
   private async listManagedGatewayClients(): Promise<interfaces.data.IGatewayClient[]> {
     const manager = this.opsServerRef.dcRouterRef.gatewayClientManager;
     if (!manager) return [];
@@ -462,8 +742,10 @@ export class GatewayClientHandler {
     capability: keyof NonNullable<interfaces.data.IApiTokenPolicy['capabilities']>,
   ): void {
     if (auth.isAdmin) return;
-    const policy = auth.token?.policy;
-    if (!policy || policy.role !== 'gatewayClient') return;
+    const policy = auth.policy;
+    if (!policy || policy.role !== 'gatewayClient') {
+      throw new plugins.typedrequest.TypedResponseError('gateway-client credential required');
+    }
     if (policy.capabilities?.[capability] === true) return;
     throw new plugins.typedrequest.TypedResponseError(`token capability missing: ${String(capability)}`);
   }
@@ -472,7 +754,7 @@ export class GatewayClientHandler {
     auth: TAuthContext,
     requestedId?: string,
   ): { gatewayClientId?: string; gatewayClientType?: string } {
-    const policy = auth.token?.policy;
+    const policy = auth.policy;
     if (policy?.role !== 'gatewayClient') return { gatewayClientId: requestedId };
     const policyClient = policy.gatewayClient;
     if (!policyClient) {
@@ -491,7 +773,7 @@ export class GatewayClientHandler {
     auth: TAuthContext,
     ownership: plugins.servezoneInterfaces.data.IGatewayClientOwnership,
   ): TResolvedGatewayClientOwnership {
-    const policy = auth.token?.policy;
+    const policy = auth.policy;
     if (!ownership.appId?.trim()) {
       throw new plugins.typedrequest.TypedResponseError('gateway client ownership is missing appId');
     }
@@ -512,7 +794,7 @@ export class GatewayClientHandler {
         gatewayClientType: policy.gatewayClient.type,
         gatewayClientId: policy.gatewayClient.id,
         appId: ownership.appId,
-        hostname: ownership.hostname,
+        hostname: ownership.hostname ? normalizeGatewayHostname(ownership.hostname) : undefined,
         routeRef: ownership.routeRef,
       };
     }
@@ -527,7 +809,7 @@ export class GatewayClientHandler {
     auth: TAuthContext,
     owner?: Partial<plugins.servezoneInterfaces.data.IMailResourceOwner>,
   ): Partial<plugins.servezoneInterfaces.data.IMailResourceOwner> | undefined {
-    const policy = auth.token?.policy;
+    const policy = auth.policy;
     if (policy?.role !== 'gatewayClient') return owner;
     if (!policy.gatewayClient) {
       throw new plugins.typedrequest.TypedResponseError('gateway client token is missing gatewayClient binding');
@@ -557,27 +839,34 @@ export class GatewayClientHandler {
   }
 
   private assertGatewayClientOwnership(auth: TAuthContext, ownership: TResolvedGatewayClientOwnership): void {
-    const policy = auth.token?.policy;
+    const policy = auth.policy;
     if (!policy || policy.role !== 'gatewayClient') return;
     if (!ownership.hostname) return;
-    if (!this.matchesHostnamePatterns(ownership.hostname, policy.hostnamePatterns || [])) {
+    if (!matchesGatewayHostnamePatterns(ownership.hostname, policy.hostnamePatterns || [], auth.managedZoneNames)) {
       throw new plugins.typedrequest.TypedResponseError('hostname is outside token policy');
     }
   }
 
-  private assertRouteTargetsAllowed(auth: TAuthContext, route?: interfaces.data.IDcRouterRouteConfig): void {
-    const policy = auth.token?.policy;
+  private assertRouteTargetsAllowed(
+    auth: TAuthContext,
+    route?: plugins.servezoneInterfaces.data.IGatewayRouteConfig,
+  ): void {
+    const policy = auth.policy;
     if (!policy || policy.role !== 'gatewayClient' || !route) return;
     const allowedTargets = policy.allowedRouteTargets || [];
     if (allowedTargets.length === 0) {
       throw new plugins.typedrequest.TypedResponseError('gateway client token has no allowed route targets');
     }
-    const targets = ((route.action as any)?.targets || []) as Array<{ host?: string; port?: number }>;
+    const targets = route.action.targets;
     for (const target of targets) {
-      const host = String(target.host || '').trim().toLowerCase();
+      if (typeof target.host !== 'string') {
+        throw new plugins.typedrequest.TypedResponseError('gateway route target host must be a string');
+      }
+      const host = normalizeGatewayTargetHost(target.host);
       const port = Number(target.port);
       const allowed = allowedTargets.some((allowedTarget) => {
-        return allowedTarget.host.trim().toLowerCase() === host && allowedTarget.ports.includes(port);
+        return normalizeGatewayTargetHost(allowedTarget.host) === host
+          && (allowedTarget.allowAnyPort === true || allowedTarget.ports.includes(port));
       });
       if (!allowed) {
         throw new plugins.typedrequest.TypedResponseError(`route target is outside token policy: ${host}:${port}`);
@@ -593,7 +882,7 @@ export class GatewayClientHandler {
     const targetDescription = target?.smtpForward
       ? `${target.smtpForward.host.trim().toLowerCase()}:${Number(target.smtpForward.port)}`
       : 'unknown';
-    if ((auth.token?.policy?.allowedRouteTargets || []).length === 0) {
+    if ((auth.policy?.allowedRouteTargets || []).length === 0) {
       throw new plugins.typedrequest.TypedResponseError('gateway client token has no allowed route targets');
     }
     throw new plugins.typedrequest.TypedResponseError(`mail target is outside token policy: ${targetDescription}`);
@@ -603,14 +892,15 @@ export class GatewayClientHandler {
     auth: TAuthContext,
     target?: plugins.servezoneInterfaces.data.IMailInboundTarget,
   ): boolean {
-    const policy = auth.token?.policy;
+    const policy = auth.policy;
     if (!policy || policy.role !== 'gatewayClient' || !target?.smtpForward) return true;
     const allowedTargets = policy.allowedRouteTargets || [];
     if (allowedTargets.length === 0) return false;
-    const host = target.smtpForward.host.trim().toLowerCase();
+    const host = normalizeGatewayTargetHost(target.smtpForward.host);
     const port = Number(target.smtpForward.port);
     return allowedTargets.some((allowedTarget) => {
-      return allowedTarget.host.trim().toLowerCase() === host && allowedTarget.ports.includes(port);
+      return normalizeGatewayTargetHost(allowedTarget.host) === host
+        && (allowedTarget.allowAnyPort === true || allowedTarget.ports.includes(port));
     });
   }
 
@@ -641,7 +931,7 @@ export class GatewayClientHandler {
     auth: TAuthContext,
     statusArg: plugins.servezoneInterfaces.data.IMailDeliveryStatus,
   ): boolean {
-    const policy = auth.token?.policy;
+    const policy = auth.policy;
     if (!policy || policy.role !== 'gatewayClient') {
       return true;
     }
@@ -659,7 +949,7 @@ export class GatewayClientHandler {
     ownerArg: Partial<plugins.servezoneInterfaces.data.IMailResourceOwner> | undefined,
     bindingsArg: plugins.servezoneInterfaces.data.IWorkAppMailBinding[],
   ): Promise<plugins.servezoneInterfaces.data.IWorkAppMailBinding[]> {
-    if (auth.token?.policy?.role !== 'gatewayClient') return bindingsArg;
+    if (auth.policy?.role !== 'gatewayClient') return bindingsArg;
     const allowedAddressBindings = this.filterMailBindingsAllowed(
       auth,
       await managerArg.listMailAddressBindings({ owner: ownerArg }),
@@ -690,42 +980,24 @@ export class GatewayClientHandler {
     addressArg: string,
     domainArg: string,
   ): boolean {
-    const policy = auth.token?.policy;
+    const policy = auth.policy;
     if (!policy || policy.role !== 'gatewayClient') return true;
-    const normalizedDomain = domainArg.trim().toLowerCase();
+    const normalizedDomain = normalizeGatewayHostname(domainArg);
     const normalizedAddress = addressArg.trim().toLowerCase();
     if (!normalizedAddress.endsWith(`@${normalizedDomain}`)) {
       throw new plugins.typedrequest.TypedResponseError('mail address does not match domain');
     }
     const patterns = policy.hostnamePatterns || [];
-    return this.matchesHostnamePatterns(normalizedDomain, patterns)
-      || patterns.some((patternArg) => patternArg.trim().toLowerCase() === `*.${normalizedDomain}`);
-  }
-
-  private matchesHostnamePatterns(hostname: string, patterns: string[]): boolean {
-    const normalizedHostname = hostname.trim().toLowerCase();
-    if (!normalizedHostname) return false;
-    for (const pattern of patterns) {
-      const normalizedPattern = pattern.trim().toLowerCase();
-      if (!normalizedPattern) continue;
-      if (normalizedPattern === normalizedHostname) return true;
-      if (normalizedPattern.startsWith('*.')) {
-        const suffix = normalizedPattern.slice(2);
-        if (!normalizedHostname.endsWith(`.${suffix}`)) continue;
-        const prefix = normalizedHostname.slice(0, -(suffix.length + 1));
-        if (prefix && !prefix.includes('.')) return true;
-      }
-    }
-    return false;
+    return matchesGatewayHostnamePatterns(normalizedDomain, patterns, auth.managedZoneNames);
   }
 
   private getRouteHostnames(route: interfaces.data.IDcRouterRouteConfig): string[] {
     const domains = (route.match as any)?.domains;
     if (Array.isArray(domains)) {
-      return domains.map((domain) => String(domain).trim().toLowerCase()).filter(Boolean);
+      return domains.map((domain) => normalizeGatewayHostname(String(domain)));
     }
     if (typeof domains === 'string') {
-      return domains.split(',').map((domain) => domain.trim().toLowerCase()).filter(Boolean);
+      return domains.split(',').map((domain) => normalizeGatewayHostname(domain));
     }
     return [];
   }
@@ -752,9 +1024,9 @@ export class GatewayClientHandler {
       .map((routeArg) => this.toGatewayClientRoute(routeArg))
       .filter((routeArg): routeArg is plugins.servezoneInterfaces.data.IGatewayClientRoute => {
         if (!routeArg) return false;
-        if (auth.token?.policy?.role !== 'gatewayClient') return true;
+        if (auth.policy?.role !== 'gatewayClient') return true;
         return !routeArg.ownership.hostname
-          || this.matchesHostnamePatterns(routeArg.ownership.hostname, auth.token.policy.hostnamePatterns || []);
+          || matchesGatewayHostnamePatterns(routeArg.ownership.hostname, auth.policy.hostnamePatterns || [], auth.managedZoneNames);
       });
   }
 
@@ -821,7 +1093,7 @@ export class GatewayClientHandler {
 
     return docs
       .filter((domainDoc) => {
-        if (!auth.token?.policy || auth.token.policy.role !== 'gatewayClient') return true;
+        if (!auth.policy || auth.policy.role !== 'gatewayClient') return true;
         return routeHostnames.some((hostname) => this.isHostnameInDomain(hostname, domainDoc.name));
       })
       .map((domainDoc) => {
@@ -861,12 +1133,18 @@ export class GatewayClientHandler {
       const appId = metadata.gatewayClientAppId || '';
 
       for (const hostname of this.getRouteHostnames(route.route)) {
-        if (auth.token?.policy?.role === 'gatewayClient' && !this.matchesHostnamePatterns(hostname, auth.token.policy.hostnamePatterns || [])) {
+        if (auth.policy?.role === 'gatewayClient' && !matchesGatewayHostnamePatterns(hostname, auth.policy.hostnamePatterns || [], auth.managedZoneNames)) {
           continue;
         }
         const domainDoc = domains.find((domain) => this.isHostnameInDomain(hostname, domain.name));
         const domainRecords = domainDoc ? await dnsManager.listRecordsForDomain(domainDoc.id) : [];
-        const matchingRecords = domainRecords.filter((record) => record.name === hostname);
+        const matchingRecords = domainRecords.filter((record) => {
+          try {
+            return normalizeGatewayHostname(record.name) === hostname;
+          } catch {
+            return false;
+          }
+        });
         if (matchingRecords.length === 0) {
           records.push({
             id: `missing:${hostname}`,
@@ -911,8 +1189,8 @@ export class GatewayClientHandler {
   }
 
   private isHostnameInDomain(hostname: string, domainName: string): boolean {
-    const normalizedHostname = hostname.trim().toLowerCase();
-    const normalizedDomainName = domainName.trim().toLowerCase();
+    const normalizedHostname = normalizeGatewayHostname(hostname);
+    const normalizedDomainName = normalizeGatewayHostname(domainName);
     return normalizedHostname === normalizedDomainName || normalizedHostname.endsWith(`.${normalizedDomainName}`);
   }
 
@@ -923,31 +1201,144 @@ export class GatewayClientHandler {
     enabled?: boolean,
     deleteRoute?: boolean,
     sourceProfileRef?: string,
+    dnsModeArg?: plugins.servezoneInterfaces.data.TGatewayRouteDnsMode,
   ): Promise<plugins.servezoneInterfaces.data.IGatewayRouteSyncResult> {
+    const validatedRoute = route === undefined ? undefined : this.validateGatewayRouteConfig(route);
     const resolvedOwnership = this.resolveGatewayClientOwnership(auth, ownership);
     this.assertGatewayClientOwnership(auth, resolvedOwnership);
-    this.assertGatewayClientRouteOwnership(resolvedOwnership, route);
-    this.assertRouteTargetsAllowed(auth, route);
+    this.assertGatewayClientRouteOwnership(resolvedOwnership, validatedRoute);
+    this.assertRouteTargetsAllowed(auth, validatedRoute);
 
+    if (dnsModeArg === 'observe') this.assertCapability(auth, 'readDnsRecords');
+    if (dnsModeArg === 'reconcile') this.assertCapability(auth, 'syncDnsRecords');
     const manager = this.opsServerRef.dcRouterRef.routeConfigManager;
     if (!manager) {
       return { success: false, message: 'Route management not initialized' };
     }
 
     const externalKey = this.buildGatewayClientExternalKey(resolvedOwnership);
+    return await this.withRouteSyncLock(externalKey, async () => {
     const existingRoute = manager.findApiRouteByExternalKey(externalKey);
+    const dnsMode = dnsModeArg || existingRoute?.metadata?.gatewayDnsMode || 'skip';
+    const includeDns = dnsModeArg !== undefined || dnsMode !== 'skip';
+    if (dnsMode === 'observe') this.assertCapability(auth, 'readDnsRecords');
+    if (dnsMode === 'reconcile') this.assertCapability(auth, 'syncDnsRecords');
+    const reconcileDnsFor = async (
+      hostnameArg: string | undefined,
+      gatewayClientIdArg: string,
+      externalKeyArg: string,
+      deleteArg = false,
+      effectiveModeArg = dnsMode,
+    ) => {
+      const reconciler = this.opsServerRef.dcRouterRef.gatewayRouteDnsReconciler;
+      if (!reconciler) {
+        return {
+          success: effectiveModeArg === 'skip',
+          retryable: effectiveModeArg !== 'skip',
+          mode: effectiveModeArg,
+          status: effectiveModeArg === 'skip' ? 'skipped' : 'zone-unavailable',
+          hostname: hostnameArg,
+          checkedAt: Date.now(),
+          message: effectiveModeArg === 'skip' ? undefined : 'Gateway route DNS reconciliation is not initialized',
+        } satisfies plugins.servezoneInterfaces.data.IGatewayRouteDnsResult;
+      }
+      try {
+        return await reconciler.reconcileRoute({
+          externalKey: externalKeyArg,
+          hostname: hostnameArg,
+          mode: effectiveModeArg,
+          gatewayClientId: gatewayClientIdArg,
+          delete: deleteArg,
+        });
+      } catch (error) {
+        return {
+          success: false,
+          retryable: true,
+          mode: effectiveModeArg,
+          status: 'mutation-failed',
+          hostname: hostnameArg,
+          checkedAt: Date.now(),
+          message: `Gateway route DNS reconciliation failed: ${(error as Error).message}`,
+        } satisfies plugins.servezoneInterfaces.data.IGatewayRouteDnsResult;
+      }
+    };
+    const reconcileDns = async (deleteArg = false, effectiveModeArg = dnsMode) => {
+      return await reconcileDnsFor(
+        resolvedOwnership.hostname,
+        resolvedOwnership.gatewayClientId,
+        externalKey,
+        deleteArg,
+        effectiveModeArg,
+      );
+    };
 
     if (deleteRoute) {
       if (!existingRoute) {
-        return { success: true, action: 'unchanged' };
+        const dns = await reconcileDns(true, dnsMode);
+        return dns.success
+          ? { success: true, action: 'unchanged', ...(includeDns ? { dns } : {}) }
+          : { success: false, dns, message: dns.message };
+      }
+      const snapshot = structuredClone(existingRoute);
+      const existingDnsMode = snapshot.metadata?.gatewayDnsMode || dnsMode;
+      const disableResult = await manager.updateManagedRoute(existingRoute.id, {
+        enabled: false,
+      });
+      if (!disableResult.success) {
+        return { success: false, routeId: existingRoute.id, message: disableResult.message };
+      }
+      const dns = await reconcileDnsFor(
+        this.getRouteHostnames(snapshot.route)[0] || resolvedOwnership.hostname,
+        snapshot.metadata?.gatewayClientId || resolvedOwnership.gatewayClientId,
+        snapshot.metadata?.externalKey || externalKey,
+        true,
+        existingDnsMode,
+      );
+      if (!dns.success) {
+        const rollback = await manager.updateManagedRoute(existingRoute.id, {
+          route: snapshot.route,
+          enabled: snapshot.enabled,
+          metadata: snapshot.metadata,
+        }, { replaceMetadata: true, replaceRoute: true });
+        if (!rollback.success) {
+          dns.status = 'compensation-failed';
+          dns.message = `${dns.message || 'DNS cleanup failed'}; route rollback failed: ${rollback.message || 'unknown error'}`;
+        }
+        return { success: false, routeId: existingRoute.id, dns, message: dns.message };
       }
       const result = await manager.deleteManagedRoute(existingRoute.id);
-      return result.success
-        ? { success: true, action: 'deleted', routeId: existingRoute.id }
-        : { success: false, message: result.message };
+      if (result.success) {
+        return { success: true, action: 'deleted', routeId: existingRoute.id, ...(includeDns ? { dns } : {}) };
+      }
+      const rollback = await manager.updateManagedRoute(existingRoute.id, {
+        route: snapshot.route,
+        enabled: snapshot.enabled,
+        metadata: snapshot.metadata,
+      }, { replaceMetadata: true, replaceRoute: true });
+      let restoredDns = dns;
+      if (rollback.success && snapshot.enabled && existingDnsMode === 'reconcile') {
+        restoredDns = await reconcileDnsFor(
+          this.getRouteHostnames(snapshot.route)[0] || resolvedOwnership.hostname,
+          snapshot.metadata?.gatewayClientId || resolvedOwnership.gatewayClientId,
+          snapshot.metadata?.externalKey || externalKey,
+          false,
+          'reconcile',
+        );
+      }
+      return {
+        success: false,
+        dns: rollback.success && restoredDns.success ? dns : {
+          ...restoredDns,
+          status: 'compensation-failed',
+          message: !rollback.success
+            ? `${result.message || 'Route deletion failed'}; route rollback failed: ${rollback.message || 'unknown error'}`
+            : `${result.message || 'Route deletion failed'}; DNS restore failed: ${restoredDns.message || 'unknown error'}`,
+        },
+        message: result.message,
+      };
     }
 
-    if (!route) {
+    if (!validatedRoute) {
       return { success: false, message: 'route is required unless delete=true' };
     }
 
@@ -968,10 +1359,22 @@ export class GatewayClientHandler {
       gatewayClientId: resolvedOwnership.gatewayClientId,
       gatewayClientAppId: resolvedOwnership.appId,
       externalKey,
+      gatewayDnsMode: dnsMode,
     };
-    const normalizedRoute = this.normalizeGatewayClientRoute(route, resolvedOwnership, externalKey);
+    const normalizedRoute = this.normalizeGatewayClientRoute(validatedRoute, resolvedOwnership, externalKey);
 
     if (existingRoute) {
+      const snapshot = structuredClone(existingRoute);
+      const snapshotHostname = this.getRouteHostnames(snapshot.route)[0];
+      const snapshotDnsMode = snapshot.metadata?.gatewayDnsMode || 'skip';
+      const snapshotGatewayClientId = snapshot.metadata?.gatewayClientId || resolvedOwnership.gatewayClientId;
+      const snapshotExternalKey = snapshot.metadata?.externalKey || externalKey;
+      const shouldCleanPreviousDns = snapshotDnsMode === 'reconcile'
+        && Boolean(snapshotHostname)
+        && (
+          snapshotHostname !== resolvedOwnership.hostname
+          || dnsMode !== 'reconcile'
+        );
       const result = await manager.updateManagedRoute(existingRoute.id, {
         route: normalizedRoute,
         enabled: enabled ?? true,
@@ -980,17 +1383,125 @@ export class GatewayClientHandler {
         replaceMetadata: true,
         replaceRoute: true,
       });
-      return result.success
-        ? { success: true, action: 'updated', routeId: existingRoute.id }
-        : { success: false, message: result.message };
+      if (!result.success) return { success: false, message: result.message };
+      if (shouldCleanPreviousDns) {
+        const cleanupDns = await reconcileDnsFor(
+          snapshotHostname,
+          snapshotGatewayClientId,
+          snapshotExternalKey,
+          true,
+          'reconcile',
+        );
+        if (!cleanupDns.success) {
+          const compensation = await manager.updateManagedRoute(existingRoute.id, {
+            route: snapshot.route,
+            enabled: snapshot.enabled,
+            metadata: snapshot.metadata,
+          }, { replaceMetadata: true, replaceRoute: true });
+          if (compensation.success && snapshot.enabled) {
+            const restoredDns = await reconcileDnsFor(
+              snapshotHostname,
+              snapshotGatewayClientId,
+              snapshotExternalKey,
+              false,
+              'reconcile',
+            );
+            if (!restoredDns.success) {
+              cleanupDns.status = 'compensation-failed';
+              cleanupDns.message = `${cleanupDns.message || 'DNS cleanup failed'}; DNS restore failed: ${restoredDns.message || 'unknown error'}`;
+            }
+          } else if (!compensation.success) {
+            cleanupDns.status = 'compensation-failed';
+            cleanupDns.message = `${cleanupDns.message || 'DNS cleanup failed'}; route rollback failed: ${compensation.message || 'unknown error'}`;
+          }
+          return { success: false, routeId: existingRoute.id, dns: cleanupDns, message: cleanupDns.message };
+        }
+      }
+      const dns = await reconcileDns((enabled ?? true) === false);
+      if (dns.success) return { success: true, action: 'updated', routeId: existingRoute.id, ...(includeDns ? { dns } : {}) };
+      const compensation = await manager.updateManagedRoute(existingRoute.id, {
+        route: snapshot.route,
+        enabled: snapshot.enabled,
+        metadata: snapshot.metadata,
+      }, { replaceMetadata: true, replaceRoute: true });
+      if (compensation.success && shouldCleanPreviousDns && snapshot.enabled) {
+        const restoredDns = await reconcileDnsFor(
+          snapshotHostname,
+          snapshotGatewayClientId,
+          snapshotExternalKey,
+          false,
+          'reconcile',
+        );
+        if (!restoredDns.success) {
+          dns.status = 'compensation-failed';
+          dns.message = `${dns.message || 'DNS reconciliation failed'}; DNS restore failed: ${restoredDns.message || 'unknown error'}`;
+        }
+      } else if (!compensation.success) {
+        dns.status = 'compensation-failed';
+        dns.message = `${dns.message || 'DNS reconciliation failed'}; route rollback failed: ${compensation.message || 'unknown error'}`;
+      }
+      return { success: false, routeId: existingRoute.id, dns, message: dns.message };
     }
 
     const routeId = await manager.createManagedRoute(normalizedRoute, auth.userId, enabled ?? true, metadata);
-    return { success: true, action: 'created', routeId };
+    const dns = await reconcileDns((enabled ?? true) === false);
+    if (dns.success) return { success: true, action: 'created', routeId, ...(includeDns ? { dns } : {}) };
+    const compensation = await manager.deleteManagedRoute(routeId);
+    if (!compensation.success) {
+      dns.status = 'compensation-failed';
+      dns.message = `${dns.message || 'DNS reconciliation failed'}; route rollback failed: ${compensation.message || 'unknown error'}`;
+    }
+    return { success: false, routeId, dns, message: dns.message };
+    });
+  }
+
+  private normalizeGatewayClientLockKey(idArg: string): string {
+    const normalized = idArg.trim().toLowerCase()
+      .replace(/[^a-z0-9._-]/g, '-')
+      .replace(/-+/g, '-')
+      .replace(/^-|-$/g, '');
+    if (!normalized) throw new Error('gateway client id is required');
+    return normalized;
+  }
+
+  private async withGatewayClientCredentialLock<T>(
+    keyArg: string,
+    taskArg: () => Promise<T>,
+  ): Promise<T> {
+    const previous = this.gatewayClientCredentialChains.get(keyArg) || Promise.resolve();
+    const run = previous.catch(() => undefined).then(taskArg);
+    const settled = run.then(() => undefined, () => undefined);
+    this.gatewayClientCredentialChains.set(keyArg, settled);
+    try {
+      return await run;
+    } finally {
+      if (this.gatewayClientCredentialChains.get(keyArg) === settled) {
+        this.gatewayClientCredentialChains.delete(keyArg);
+      }
+    }
+  }
+
+  private async withRouteSyncLock<T>(keyArg: string, taskArg: () => Promise<T>): Promise<T> {
+    const previous = this.routeSyncChains.get(keyArg) || Promise.resolve();
+    const run = previous
+      .catch(() => undefined)
+      .then(taskArg);
+    const settled = run.then(
+      () => undefined,
+      () => undefined,
+    );
+    this.routeSyncChains.set(keyArg, settled);
+    try {
+      return await run;
+    } finally {
+      if (this.routeSyncChains.get(keyArg) === settled) {
+        this.routeSyncChains.delete(keyArg);
+      }
+    }
   }
 
   private buildGatewayClientExternalKey(ownership: TResolvedGatewayClientOwnership): string {
-    const hostname = ownership.hostname?.trim().toLowerCase();
+    const hostname = ownership.hostname ? normalizeGatewayHostname(ownership.hostname) : undefined;
     const routeRef = ownership.routeRef?.trim();
     let routeKey: string;
     if (hostname && routeRef) {
@@ -1004,7 +1515,7 @@ export class GatewayClientHandler {
     return [
       ownership.gatewayClientType,
       ownership.gatewayClientId,
-      ownership.appId,
+      ownership.appId.trim(),
       routeKey,
     ].map((part) => part.trim()).join(':');
   }
@@ -1038,6 +1549,148 @@ export class GatewayClientHandler {
     }
   }
 
+  private validateGatewayRouteConfig(
+    routeArg: unknown,
+  ): plugins.servezoneInterfaces.data.IGatewayRouteConfig {
+    const fail = (messageArg: string): never => {
+      throw new plugins.typedrequest.TypedResponseError(`invalid gateway route: ${messageArg}`);
+    };
+    const requireObject = (valueArg: unknown, labelArg: string): Record<string, unknown> => {
+      if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) {
+        return fail(`${labelArg} must be an object`);
+      }
+      const prototype = Object.getPrototypeOf(valueArg);
+      if (prototype !== Object.prototype && prototype !== null) {
+        return fail(`${labelArg} must be a plain object`);
+      }
+      return valueArg as Record<string, unknown>;
+    };
+    const requireOnlyKeys = (
+      valueArg: Record<string, unknown>,
+      allowedArg: readonly string[],
+      labelArg: string,
+    ): void => {
+      const unknownKeys = Object.keys(valueArg).filter((keyArg) => !allowedArg.includes(keyArg));
+      if (unknownKeys.length > 0) fail(`${labelArg} contains unsupported field(s): ${unknownKeys.join(', ')}`);
+    };
+    const requireString = (valueArg: unknown, labelArg: string): string => {
+      if (typeof valueArg !== 'string' || !valueArg.trim()) return fail(`${labelArg} must be a non-empty string`);
+      return valueArg.trim();
+    };
+    const requireBoolean = (valueArg: unknown, labelArg: string): boolean => {
+      if (typeof valueArg !== 'boolean') return fail(`${labelArg} must be a boolean`);
+      return valueArg;
+    };
+    const requirePort = (valueArg: unknown, labelArg: string): number => {
+      if (!Number.isSafeInteger(valueArg) || Number(valueArg) < 1 || Number(valueArg) > 65535) {
+        return fail(`${labelArg} must be an integer from 1 through 65535`);
+      }
+      return Number(valueArg);
+    };
+
+    const route = requireObject(routeArg, 'route');
+    requireOnlyKeys(route, ['name', 'match', 'action', 'priority', 'managedRouteKind', 'remoteIngress'], 'route');
+    const name = requireString(route.name, 'route.name');
+
+    const match = requireObject(route.match, 'route.match');
+    requireOnlyKeys(match, ['ports', 'domains', 'transport', 'path'], 'route.match');
+    const portValues = match.ports;
+    if (!Array.isArray(portValues) || portValues.length === 0) {
+      fail('route.match.ports must be a non-empty array');
+    }
+    const ports = (portValues as unknown[]).map((portArg, indexArg) => requirePort(portArg, `route.match.ports[${indexArg}]`));
+    let domains: string[] | undefined;
+    if (match.domains !== undefined) {
+      const domainValues = match.domains;
+      if (!Array.isArray(domainValues) || domainValues.length === 0) {
+        fail('route.match.domains must be a non-empty array when present');
+      }
+      domains = (domainValues as unknown[]).map((domainArg, indexArg) => {
+        return normalizeGatewayHostname(requireString(domainArg, `route.match.domains[${indexArg}]`));
+      });
+    }
+    let transport: 'tcp' | 'udp' | 'all' | undefined;
+    if (match.transport !== undefined) {
+      if (match.transport !== 'tcp' && match.transport !== 'udp' && match.transport !== 'all') {
+        fail('route.match.transport is unsupported');
+      }
+      transport = match.transport as 'tcp' | 'udp' | 'all';
+    }
+    const path = match.path === undefined ? undefined : requireString(match.path, 'route.match.path');
+
+    const action = requireObject(route.action, 'route.action');
+    requireOnlyKeys(action, ['type', 'targets', 'tls', 'websocket'], 'route.action');
+    if (action.type !== 'forward') fail('route.action.type must be forward');
+    const targetValues = action.targets;
+    if (!Array.isArray(targetValues) || targetValues.length === 0) {
+      fail('route.action.targets must be a non-empty array');
+    }
+    const targets = (targetValues as unknown[]).map((targetArg, indexArg) => {
+      const target = requireObject(targetArg, `route.action.targets[${indexArg}]`);
+      requireOnlyKeys(target, ['host', 'port'], `route.action.targets[${indexArg}]`);
+      return {
+        host: normalizeGatewayTargetHost(requireString(target.host, `route.action.targets[${indexArg}].host`)),
+        port: requirePort(target.port, `route.action.targets[${indexArg}].port`),
+      };
+    });
+    let tls: plugins.servezoneInterfaces.data.IGatewayRouteTls | undefined;
+    if (action.tls !== undefined) {
+      const tlsValue = requireObject(action.tls, 'route.action.tls');
+      requireOnlyKeys(tlsValue, ['mode', 'certificate'], 'route.action.tls');
+      if (tlsValue.mode !== 'terminate' && tlsValue.mode !== 'passthrough'
+        && tlsValue.mode !== 'terminate-and-reencrypt') fail('route.action.tls.mode is unsupported');
+      if (tlsValue.certificate !== undefined && tlsValue.certificate !== 'auto') {
+        fail('route.action.tls.certificate must be auto when present');
+      }
+      tls = {
+        mode: tlsValue.mode as 'terminate' | 'passthrough' | 'terminate-and-reencrypt',
+        ...(tlsValue.certificate === 'auto' ? { certificate: 'auto' as const } : {}),
+      };
+    }
+    let websocket: { enabled: boolean } | undefined;
+    if (action.websocket !== undefined) {
+      const websocketValue = requireObject(action.websocket, 'route.action.websocket');
+      requireOnlyKeys(websocketValue, ['enabled'], 'route.action.websocket');
+      websocket = { enabled: requireBoolean(websocketValue.enabled, 'route.action.websocket.enabled') };
+    }
+    let priority: number | undefined;
+    if (route.priority !== undefined) {
+      if (!Number.isSafeInteger(route.priority)) fail('route.priority must be a safe integer');
+      priority = Number(route.priority);
+    }
+    let managedRouteKind: 'letsencrypt-http01-forward' | undefined;
+    if (route.managedRouteKind !== undefined) {
+      if (route.managedRouteKind !== 'letsencrypt-http01-forward') fail('route.managedRouteKind is unsupported');
+      managedRouteKind = route.managedRouteKind as 'letsencrypt-http01-forward';
+    }
+    let remoteIngress: { enabled: boolean; edgeFilter?: string[] } | undefined;
+    if (route.remoteIngress !== undefined) {
+      const remoteValue = requireObject(route.remoteIngress, 'route.remoteIngress');
+      requireOnlyKeys(remoteValue, ['enabled', 'edgeFilter'], 'route.remoteIngress');
+      let edgeFilter: string[] | undefined;
+      if (remoteValue.edgeFilter !== undefined) {
+        const edgeFilterValues = remoteValue.edgeFilter;
+        if (!Array.isArray(edgeFilterValues)) fail('route.remoteIngress.edgeFilter must be an array');
+        edgeFilter = (edgeFilterValues as unknown[]).map((entryArg, indexArg) => {
+          return requireString(entryArg, `route.remoteIngress.edgeFilter[${indexArg}]`);
+        });
+      }
+      remoteIngress = {
+        enabled: requireBoolean(remoteValue.enabled, 'route.remoteIngress.enabled'),
+        ...(edgeFilter ? { edgeFilter } : {}),
+      };
+    }
+
+    return {
+      name,
+      match: { ports, ...(domains ? { domains } : {}), ...(transport ? { transport } : {}), ...(path ? { path } : {}) },
+      action: { type: 'forward', targets, ...(tls ? { tls } : {}), ...(websocket ? { websocket } : {}) },
+      ...(priority !== undefined ? { priority } : {}),
+      ...(managedRouteKind ? { managedRouteKind } : {}),
+      ...(remoteIngress ? { remoteIngress } : {}),
+    };
+  }
+
 
   private normalizeGatewayClientRoute(
     route: interfaces.data.IDcRouterRouteConfig,
@@ -1046,6 +1699,18 @@ export class GatewayClientHandler {
   ): interfaces.data.IDcRouterRouteConfig {
     const normalizedRoute = structuredClone(route);
     delete normalizedRoute.security;
+    normalizedRoute.match = {
+      ...normalizedRoute.match,
+      ...(this.getRouteHostnames(normalizedRoute).length
+        ? { domains: this.getRouteHostnames(normalizedRoute) }
+        : {}),
+    };
+    if (normalizedRoute.action?.targets) {
+      normalizedRoute.action.targets = normalizedRoute.action.targets.map((targetArg) => ({
+        ...targetArg,
+        host: normalizeGatewayTargetHost(targetArg.host as string),
+      }));
+    }
     if (ownership.hostname && this.getRouteHostnames(normalizedRoute).length === 0) {
       normalizedRoute.match = {
         ...normalizedRoute.match,
@@ -1069,6 +1734,9 @@ export class GatewayClientHandler {
       throw new plugins.typedrequest.TypedResponseError('routeRef ownership cannot include domains');
     }
     const ownedHostname = ownership.hostname.trim().toLowerCase();
+    if (routeDomains.length !== 1) {
+      throw new plugins.typedrequest.TypedResponseError('hostname ownership requires exactly one route domain');
+    }
     if (routeDomains.some((domainArg) => domainArg.toLowerCase() !== ownedHostname)) {
       throw new plugins.typedrequest.TypedResponseError('route domains must match ownership hostname');
     }