@serve.zone/dcrouter 17.2.4 → 17.4.0

package/ts/dns/index.ts

@@ -1,4 +1,5 @@
 export * from './manager.dns.js';
 export * from './providers/index.js';
 export * from './classes.dns-server-runtime.js';
+export * from './classes.gateway-route-dns-reconciler.js';
 export * from './txt-record-presentation.js';

package/ts/dns/manager.dns.ts

@@ -961,6 +961,42 @@ export class DnsManager {
     return { success: true, id: doc.id };
   }
 
+  /**
+   * Adopt an already-correct record into an automation lifecycle without
+   * mutating provider DNS. The expected value fields make adoption fail closed
+   * if the provider mirror changed between inspection and persistence.
+   */
+  public async adoptRecordManagement(args: {
+    id: string;
+    name: string;
+    type: TDnsRecordType;
+    value: string;
+    ttl: number;
+    proxied: boolean;
+    managedBy: string;
+    managedOwnerId: string;
+    managedRecordKey: string;
+  }): Promise<{ success: boolean; message?: string }> {
+    const doc = await DnsRecordDoc.findById(args.id);
+    if (!doc) return { success: false, message: 'Record not found' };
+    if (
+      doc.name.toLowerCase().replace(/\.+$/, '') !== args.name.toLowerCase().replace(/\.+$/, '')
+      || doc.type !== args.type
+      || doc.value !== args.value
+      || doc.ttl !== args.ttl
+      || doc.proxied !== args.proxied
+      || doc.managedBy
+    ) {
+      return { success: false, message: 'DNS record changed before provenance adoption' };
+    }
+    doc.managedBy = args.managedBy;
+    doc.managedOwnerId = args.managedOwnerId;
+    doc.managedRecordKey = args.managedRecordKey;
+    doc.updatedAt = Date.now();
+    await doc.save();
+    return { success: true };
+  }
+
   public async updateRecord(args: {
     id: string;
     name?: string;

package/ts/email/classes.accepted-email-spool.ts

@@ -7,6 +7,7 @@ import type {
 } from '../db/documents/classes.cached.email.js';
 import type {
   Email,
+  IAcceptEnvelopeContext,
   IExtendedSmtpSession,
   IMessageAcceptanceContext,
   IMessageAcceptanceDecision,
@@ -20,6 +21,8 @@ const ACCEPTED_EMAIL_RETRY_DELAY_MS = 5 * 60_000;
 const ACCEPTED_EMAIL_QUEUE_LEASE_MS = 30 * 60_000;
 const ACCEPTED_EMAIL_SPOOL_BATCH_SIZE = 25;
 const ACCEPTED_EMAIL_STOP_DRAIN_TIMEOUT_MS = 30_000;
+/** Retention for catch-all stored inbound mail (30 days). */
+const INBOUND_STORE_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
 
 export type TSmartMtaQueueItemLike = {
   id?: string;
@@ -252,6 +255,114 @@ export class AcceptedEmailSpool {
     };
   }
 
+  /**
+   * Durable acceptance for envelopes containing at least one catch-all store
+   * route: anchors the exact raw message + metadata as a CachedEmail before
+   * SMTP 250, then dispatches any non-store recipients through SmartMTA's
+   * exact-plan executor. Store recipients are fulfilled by the anchor itself.
+   */
+  public async acceptEnvelope(
+    context: IAcceptEnvelopeContext,
+    emailServer: UnifiedEmailServer,
+  ): Promise<void> {
+    if (!this.dcRouterRef.dcRouterDb?.isReady()) {
+      throw new Error('DcRouterDb is not available for durable envelope acceptance');
+    }
+    this.throwIfMessageAcceptanceAborted(context.abortSignal);
+
+    const email = context.email;
+    const session = context.session;
+    const cachedEmail = CachedEmail.createNew();
+    this.removeHeader(email.headers, DCROUTER_CACHE_ID_HEADER);
+    email.headers[DCROUTER_CACHE_ID_HEADER] = cachedEmail.id;
+    cachedEmail.messageId = email.headers['Message-ID'] || email.headers['message-id'] || cachedEmail.id;
+    cachedEmail.from = context.envelope.mailFrom || email.from || '';
+    cachedEmail.to = context.envelope.rcptTo.length > 0
+      ? [...context.envelope.rcptTo]
+      : Array.isArray(email.to) ? email.to : [];
+    cachedEmail.cc = Array.isArray(email.cc) ? email.cc : [];
+    cachedEmail.bcc = Array.isArray(email.bcc) ? email.bcc : [];
+    cachedEmail.subject = email.subject || '';
+    cachedEmail.attachmentCount = context.attachmentCount;
+    if (context.securityResults) {
+      cachedEmail.inboundSecurityResults = JSON.stringify(context.securityResults);
+    }
+
+    // Build the exact per-recipient dispatch plan before durably committing,
+    // so an unplannable envelope is refused instead of half-anchored.
+    const idempotencyKeys = context.resolvedRecipientRoutes.map(
+      (resolution) => `${cachedEmail.id}:${resolution.recipient}`,
+    );
+    const plan = emailServer.createAcceptedEnvelopeDispatchPlan(context, idempotencyKeys);
+    const nonStoreEntries = plan.filter((entry) => entry.action.type !== 'store');
+
+    const persistedRawMessage = this.setDcRouterCacheIdHeader(
+      context.rawMessage.toString('utf8'),
+      cachedEmail.id,
+    );
+    await this.persistRawMessage(cachedEmail, persistedRawMessage);
+    cachedEmail.direction = session.authenticated ? 'outbound' : 'inbound';
+    cachedEmail.acceptedAt = Date.now();
+    cachedEmail.markStored(INBOUND_STORE_RETENTION_MS);
+    cachedEmail.routeData = JSON.stringify({
+      acceptedAt: new Date().toISOString(),
+      acceptance: 'durable-envelope',
+      recipientPlans: plan.map((entry) => ({
+        recipient: entry.recipient,
+        routeName: entry.routeName,
+        source: entry.source,
+        actionType: entry.action.type,
+      })),
+      session: {
+        id: session.id,
+        remoteAddress: session.remoteAddress,
+        clientHostname: session.clientHostname,
+        secure: !!session.secure,
+        authenticated: !!session.authenticated,
+        user: session.user,
+        envelope: context.envelope,
+      },
+    });
+    cachedEmail.updateSenderDomain();
+    cachedEmail.updateRecipientDomains();
+    try {
+      await cachedEmail.save();
+      await this.notifyEmailQueuePersisted(cachedEmail, 'envelope-stored');
+    } catch (error) {
+      await this.deleteRawMessage(cachedEmail).catch(() => undefined);
+      throw error;
+    }
+    if (context.abortSignal?.aborted) {
+      cachedEmail.markFailed('Envelope acceptance aborted before SMTP success');
+      await cachedEmail.save();
+      await this.notifyEmailQueuePersisted(cachedEmail, 'envelope-acceptance-aborted');
+      throw new Error('Envelope acceptance aborted before SMTP success');
+    }
+
+    if (nonStoreEntries.length > 0) {
+      const dispatchResult = await emailServer.dispatchAcceptedEnvelope(
+        context.rawMessage,
+        plan,
+        {
+          mailFrom: context.envelope.mailFrom,
+          session: {
+            id: session.id,
+            remoteAddress: session.remoteAddress,
+            clientHostname: session.clientHostname,
+            secure: !!session.secure,
+            authenticated: !!session.authenticated,
+          },
+        },
+      );
+      const failed = dispatchResult.results.filter(
+        (result) => result.status === 'failed' || result.status === 'rejected',
+      );
+      if (failed.length > 0) {
+        logger.log('warn', `Durable envelope ${cachedEmail.id}: ${failed.length}/${dispatchResult.results.length} non-store recipients failed dispatch: ${failed.map((result) => `${result.recipient}=${result.message || result.status}`).join('; ')}`);
+      }
+    }
+  }
+
   /** Start the interval-driven spool processor and trigger an immediate run. */
   public start(): void {
     this.clearSpoolTimer();

package/ts/email/classes.smartmta-storage-manager.ts

@@ -1,5 +1,9 @@
 import * as plugins from '../plugins.js';
-import type { IStorageManager } from '@push.rocks/smartmta';
+import type {
+  IStorageManager,
+  IStorageListPageOptions,
+  IStorageListPageResult,
+} from '@push.rocks/smartmta';
 import {
   getSmartMtaTextNamespace,
   hashSmartMtaStorageKey,
@@ -98,6 +102,58 @@ export class SmartMtaStorageManager implements IStorageManager {
       .sort();
   }
 
+  /**
+   * Bounded, deletion-stable page listing: seeks strictly beyond the last
+   * returned key, so tokens stay valid while pages are deleted and an
+   * otherwise stable prefix is always exhausted.
+   */
+  public async listPage(
+    prefix: string,
+    options: IStorageListPageOptions,
+  ): Promise<IStorageListPageResult> {
+    const normalizedPrefix = normalizeSmartMtaStorageKey(prefix);
+    getSmartMtaTextNamespace(normalizedPrefix);
+    const requestedLimit = Number.isSafeInteger(options?.limit) && options.limit > 0
+      ? options.limit
+      : 100;
+    const limit = Math.min(requestedLimit, 1000);
+    let seekAfter: string | undefined;
+    if (options?.continuationToken) {
+      const decoded = Buffer.from(options.continuationToken, 'base64url').toString('utf8');
+      if (!decoded.startsWith(normalizedPrefix)) {
+        throw new Error('SmartMTA storage continuation token does not match the requested prefix');
+      }
+      seekAfter = decoded;
+    }
+
+    const documents = await this.collection
+      .find({
+        key: {
+          ...(seekAfter ? { $gt: seekAfter } : { $gte: normalizedPrefix }),
+          $lt: `${normalizedPrefix}￿`,
+        },
+      })
+      .sort({ key: 1 })
+      .limit(limit + 1)
+      .toArray();
+
+    const hasMore = documents.length > limit;
+    const pageDocuments = documents.slice(0, limit);
+    const keys = pageDocuments
+      .map((document: ISmartMtaStorageDocument) => this.validateDocument(document).key)
+      .filter((key: string) => key.startsWith(normalizedPrefix));
+    const lastKey = pageDocuments.length > 0
+      ? (pageDocuments[pageDocuments.length - 1] as ISmartMtaStorageDocument).key
+      : undefined;
+
+    return {
+      keys,
+      ...(hasMore && lastKey
+        ? { continuationToken: Buffer.from(lastKey, 'utf8').toString('base64url') }
+        : {}),
+    };
+  }
+
   public async delete(key: string): Promise<void> {
     const normalizedKey = normalizeSmartMtaStorageKey(key);
     getSmartMtaTextNamespace(normalizedKey);

package/ts/email/smartmta-storage-policy.ts

@@ -11,6 +11,8 @@ export const smartMtaTextNamespaces: readonly ISmartMtaTextNamespace[] = Object.
   { prefix: '/email/bounces/', maxBytes: 8 * 1024 * 1024 },
   { prefix: '/email/templates/', maxBytes: 4 * 1024 * 1024 },
   { prefix: '/email/routes/config.json', maxBytes: 4 * 1024 * 1024 },
+  // SmartMTA 8.1+ accepted-envelope dispatch bookkeeping (idempotent replay records).
+  { prefix: '/email/accepted-envelope-dispatch/', maxBytes: 64 * 1024 },
   { prefix: '/security/ip-reputation-cache.json', maxBytes: 8 * 1024 * 1024 },
   { prefix: '/workhosters/mail-identities.json', maxBytes: 4 * 1024 * 1024 },
 ]);

package/ts/monitoring/classes.ops-event-manager.ts

@@ -0,0 +1,99 @@
+import * as plugins from '../plugins.js';
+import { logger } from '../logger.js';
+import {
+  OpsConfigEventDoc,
+  type IOpsConfigEventFilter,
+} from '../db/documents/classes.ops-config-event.doc.js';
+import type {
+  IOpsConfigEvent,
+  IOpsConfigEventCursor,
+  IOpsConfigEventContext,
+  TOpsConfigEventSeverity,
+} from '../../ts_interfaces/data/config-events.js';
+
+export interface IRecordOpsConfigEventOptions {
+  severity: TOpsConfigEventSeverity;
+  category: string;
+  title: string;
+  detail: string;
+  context?: IOpsConfigEventContext;
+}
+
+/** Retention for acknowledged events (90 days). */
+const ACKNOWLEDGED_RETENTION_MS = 90 * 24 * 60 * 60 * 1000;
+const PRUNE_INTERVAL_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * OpsEventManager — durable, acknowledgeable platform configuration events.
+ *
+ * These are operator-facing config conflicts (e.g. gateway DNS automation
+ * overwriting a manual record), not application runtime errors. Producers call
+ * `recordEvent()` fire-and-forget; the ops UI lists and acknowledges them.
+ *
+ * Repeated occurrences of the same unacknowledged conflict coalesce into one
+ * event (refreshed timestamp/detail) so reconcile loops cannot flood the inbox.
+ */
+export class OpsEventManager {
+  private pruneInterval: ReturnType<typeof setInterval> | null = null;
+
+  public async start(): Promise<void> {
+    this.pruneInterval = setInterval(() => {
+      OpsConfigEventDoc.pruneAcknowledged(ACKNOWLEDGED_RETENTION_MS).catch((error: unknown) => {
+        logger.log('warn', `OpsEventManager prune failed: ${(error as Error).message}`);
+      });
+    }, PRUNE_INTERVAL_MS);
+    // Prune once at startup so long-stopped instances converge immediately.
+    await OpsConfigEventDoc.pruneAcknowledged(ACKNOWLEDGED_RETENTION_MS).catch(() => 0);
+  }
+
+  public async stop(): Promise<void> {
+    if (this.pruneInterval) {
+      clearInterval(this.pruneInterval);
+      this.pruneInterval = null;
+    }
+  }
+
+  public async recordEvent(options: IRecordOpsConfigEventOptions): Promise<IOpsConfigEvent> {
+    const context = options.context || {};
+    const sourceKey = [
+      options.title,
+      context.recordName || '',
+      context.domain || '',
+      context.routeRef || '',
+    ].join('|');
+    const openDedupeKey = plugins.crypto
+      .createHash('sha256')
+      .update(sourceKey)
+      .digest('hex');
+    const now = Date.now();
+    const { event, created } = await OpsConfigEventDoc.upsertOpenEvent({
+      id: `oce_${now.toString(36)}_${Math.random().toString(36).slice(2, 10)}`,
+      openDedupeKey,
+      severity: options.severity,
+      category: options.category,
+      title: options.title,
+      detail: options.detail,
+      context,
+      createdAt: now,
+    });
+    if (created) {
+      logger.log(
+        options.severity === 'error' ? 'error' : 'warn',
+        `Platform config event [${options.category}] ${options.title}`,
+      );
+    }
+    return event.toApiObject();
+  }
+
+  public async listEvents(
+    filter: IOpsConfigEventFilter = {},
+  ): Promise<{ events: IOpsConfigEvent[]; total: number; unacknowledgedCount: number; nextCursor?: IOpsConfigEventCursor }> {
+    const { events, total, nextCursor } = await OpsConfigEventDoc.findFiltered(filter);
+    const unacknowledgedCount = await OpsConfigEventDoc.countUnacknowledged();
+    return { events: events.map((doc) => doc.toApiObject()), total, unacknowledgedCount, nextCursor };
+  }
+
+  public async acknowledgeEvents(ids: string[], userId: string): Promise<number> {
+    return OpsConfigEventDoc.acknowledgeByIds(ids, userId);
+  }
+}

package/ts/monitoring/index.ts

@@ -1 +1,2 @@
-export * from './classes.metricsmanager.js';
+export * from './classes.metricsmanager.js';
+export * from './classes.ops-event-manager.js';

package/ts/opsserver/classes.opsserver.ts

@@ -41,6 +41,7 @@ export class OpsServer {
   private acmeConfigHandler!: handlers.AcmeConfigHandler;
   private emailDomainHandler!: handlers.EmailDomainHandler;
   private gatewayClientHandler!: handlers.GatewayClientHandler;
+  private configEventHandler!: handlers.ConfigEventHandler;
   private smtpRealtimeUnsubscribe?: () => void;
   private emailQueueRealtimeUnsubscribe?: () => void;
 
@@ -105,6 +106,7 @@ export class OpsServer {
     this.acmeConfigHandler = new handlers.AcmeConfigHandler(this);
     this.emailDomainHandler = new handlers.EmailDomainHandler(this);
     this.gatewayClientHandler = new handlers.GatewayClientHandler(this);
+    this.configEventHandler = new handlers.ConfigEventHandler(this);
     this.smtpRealtimeUnsubscribe =
       this.dcRouterRef.acceptedEmailSpool?.onSmtpTransactionPersisted?.((eventArg) => {
         this.invalidateRealtime(['smtpAttempts', 'emailQueue'], {

package/ts/opsserver/handlers/certificate.handler.ts

@@ -4,6 +4,12 @@ import * as interfaces from '../../../ts_interfaces/index.js';
 import { AcmeCertDoc, ProxyCertDoc } from '../../db/index.js';
 import { logger } from '../../logger.js';
 import { requireOpsAuth } from '../helpers/auth.js';
+import {
+  hasOwnedEnabledGatewayRoute,
+  matchesGatewayHostnamePatterns,
+  normalizeGatewayHostname,
+  requireGatewayMachineAuth,
+} from '../helpers/gateway-client-auth.js';
 
 /**
  * Mirrors `SmartacmeCertMatcher.getCertificateDomainNameByDomainName` from
@@ -45,6 +51,40 @@ export class CertificateHandler {
     return auth.userId;
   }
 
+  private async requireCertificateAuth(
+    requestArg: { identity?: interfaces.data.IIdentity; apiToken?: string },
+    domainArg: string,
+    capabilityArg: 'readCertificates' | 'requestCertificates',
+  ): Promise<{ userId: string; domain: string }> {
+    const tokenManager = this.opsServerRef.dcRouterRef.apiTokenManager;
+    const candidate = requestArg.apiToken && tokenManager
+      ? await tokenManager.validateToken(requestArg.apiToken)
+      : null;
+    if (candidate?.policy?.role === 'gatewayClient') {
+      const auth = await requireGatewayMachineAuth(
+        this.opsServerRef,
+        requestArg,
+        capabilityArg === 'readCertificates' ? 'gateway-clients:read' : 'gateway-clients:write',
+      );
+      if (auth.policy?.capabilities?.[capabilityArg] !== true) {
+        throw new plugins.typedrequest.TypedResponseError(`token capability missing: ${capabilityArg}`);
+      }
+      const domain = normalizeGatewayHostname(domainArg);
+      if (!matchesGatewayHostnamePatterns(domain, auth.policy.hostnamePatterns || [], auth.managedZoneNames)) {
+        throw new plugins.typedrequest.TypedResponseError('certificate hostname is outside gateway-client policy');
+      }
+      if (!hasOwnedEnabledGatewayRoute(this.opsServerRef, auth, domain)) {
+        throw new plugins.typedrequest.TypedResponseError('certificate hostname has no owned enabled gateway route');
+      }
+      return { userId: auth.userId, domain };
+    }
+    const userId = await this.requireAuth(
+      requestArg,
+      capabilityArg === 'readCertificates' ? 'certificates:read' : 'certificates:write',
+    );
+    return { userId, domain: normalizeGatewayHostname(domainArg) };
+  }
+
   private registerHandlers(): void {
     const router = this.typedrouter;
 
@@ -66,8 +106,8 @@ export class CertificateHandler {
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_ReprovisionCertificateDomain>(
         'reprovisionCertificateDomain',
         async (dataArg) => {
-          await this.requireAuth(dataArg, 'certificates:write');
-          const result = await this.reprovisionCertificateDomain(dataArg.domain, dataArg.forceRenew);
+          const auth = await this.requireCertificateAuth(dataArg, dataArg.domain, 'requestCertificates');
+          const result = await this.reprovisionCertificateDomain(auth.domain, dataArg.forceRenew);
           if (result.success) {
             this.opsServerRef.invalidateRealtime?.('certificates', {
               changedIds: [dataArg.domain],
@@ -102,8 +142,8 @@ export class CertificateHandler {
       new plugins.typedrequest.TypedHandler<plugins.servezoneInterfaces.requests.gateway.IReq_ExportCertificate>(
         'exportCertificate',
         async (dataArg) => {
-          await this.requireAuth(dataArg, 'certificates:read');
-          return this.exportCertificate(dataArg.domain);
+          const auth = await this.requireCertificateAuth(dataArg, dataArg.domain, 'readCertificates');
+          return this.exportCertificate(auth.domain);
         }
       )
     );
@@ -113,6 +153,13 @@ export class CertificateHandler {
       new plugins.typedrequest.TypedHandler<plugins.servezoneInterfaces.requests.gateway.IReq_ImportCertificate>(
         'importCertificate',
         async (dataArg) => {
+          const tokenManager = this.opsServerRef.dcRouterRef.apiTokenManager;
+          const candidate = dataArg.apiToken && tokenManager
+            ? await tokenManager.validateToken(dataArg.apiToken)
+            : null;
+          if (candidate?.policy?.role === 'gatewayClient') {
+            throw new plugins.typedrequest.TypedResponseError('gateway-client credentials cannot import certificates');
+          }
           await this.requireAuth(dataArg, 'certificates:write');
           const result = await this.importCertificate(dataArg.cert);
           if (result.success) {

package/ts/opsserver/handlers/config-event.handler.ts

@@ -0,0 +1,62 @@
+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';
+
+/**
+ * Handlers for the platform configuration event inbox (list + acknowledge).
+ */
+export class ConfigEventHandler {
+  public typedrouter = new plugins.typedrequest.TypedRouter();
+
+  constructor(private opsServerRef: OpsServer) {
+    this.opsServerRef.typedrouter.addTypedRouter(this.typedrouter);
+    this.registerHandlers();
+  }
+
+  private registerHandlers(): void {
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_ListConfigEvents>(
+        'listConfigEvents',
+        async (dataArg) => {
+          await requireOpsAuth(this.opsServerRef, dataArg, { scope: 'config-events:read' });
+          const opsEventManager = this.opsServerRef.dcRouterRef.opsEventManager;
+          if (!opsEventManager) {
+            return { events: [], total: 0, unacknowledgedCount: 0, nextCursor: undefined };
+          }
+          return opsEventManager.listEvents({
+            acknowledged: dataArg.acknowledged,
+            severity: dataArg.severity,
+            category: dataArg.category,
+            limit: dataArg.limit,
+            cursor: dataArg.cursor,
+          });
+        },
+      ),
+    );
+
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_AcknowledgeConfigEvents>(
+        'acknowledgeConfigEvents',
+        async (dataArg) => {
+          const auth = await requireOpsAuth(this.opsServerRef, dataArg, {
+            scope: 'config-events:write',
+            requireAdminIdentity: true,
+          });
+          const opsEventManager = this.opsServerRef.dcRouterRef.opsEventManager;
+          if (!opsEventManager) {
+            return { success: false, acknowledgedCount: 0, message: 'OpsEventManager not initialized' };
+          }
+          const acknowledgedCount = await opsEventManager.acknowledgeEvents(
+            dataArg.ids || [],
+            auth.userId,
+          );
+          this.opsServerRef.invalidateRealtime?.(['configEvents'], {
+            reason: 'config-events-acknowledged',
+          });
+          return { success: true, acknowledgedCount };
+        },
+      ),
+    );
+  }
+}

package/ts/opsserver/handlers/dns-record.handler.ts

@@ -1,7 +1,10 @@
 import * as plugins from '../../plugins.js';
 import type { OpsServer } from '../classes.opsserver.js';
 import * as interfaces from '../../../ts_interfaces/index.js';
+import { logger } from '../../logger.js';
 import { requireOpsAuth } from '../helpers/auth.js';
+import { normalizeGatewayHostname } from '../helpers/gateway-client-auth.js';
+import { getActiveGatewayDnsClaims } from '../../dns/classes.gateway-route-dns-reconciler.js';
 
 /**
  * CRUD handlers for DnsRecordDoc.
@@ -62,6 +65,14 @@ export class DnsRecordHandler {
           const userId = await this.requireAuth(dataArg, 'dns-records:write');
           const dnsManager = this.opsServerRef.dcRouterRef.dnsManager;
           if (!dnsManager) return { success: false, message: 'DnsManager not initialized' };
+          const claimError = await this.rejectClaimedHostnameMutation(
+            dataArg.domainId,
+            dataArg.name,
+            dataArg.type,
+            userId,
+            'create',
+          );
+          if (claimError) return { success: false, message: claimError };
           const result = await dnsManager.createRecord({
             domainId: dataArg.domainId,
             name: dataArg.name,
@@ -87,9 +98,30 @@ export class DnsRecordHandler {
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_UpdateDnsRecord>(
         'updateDnsRecord',
         async (dataArg) => {
-          await this.requireAuth(dataArg, 'dns-records:write');
+          const userId = await this.requireAuth(dataArg, 'dns-records:write');
           const dnsManager = this.opsServerRef.dcRouterRef.dnsManager;
           if (!dnsManager) return { success: false, message: 'DnsManager not initialized' };
+          const existing = await dnsManager.getRecord(dataArg.id);
+          if (existing) {
+            const currentClaimError = await this.rejectClaimedHostnameMutation(
+              existing.domainId,
+              existing.name,
+              existing.type,
+              userId,
+              'update',
+            );
+            if (currentClaimError) return { success: false, message: currentClaimError };
+            if (dataArg.name !== undefined) {
+              const nextClaimError = await this.rejectClaimedHostnameMutation(
+                existing.domainId,
+                dataArg.name,
+                existing.type,
+                userId,
+                'update',
+              );
+              if (nextClaimError) return { success: false, message: nextClaimError };
+            }
+          }
           const result = await dnsManager.updateRecord({
             id: dataArg.id,
             name: dataArg.name,
@@ -113,9 +145,20 @@ export class DnsRecordHandler {
       new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_DeleteDnsRecord>(
         'deleteDnsRecord',
         async (dataArg) => {
-          await this.requireAuth(dataArg, 'dns-records:write');
+          const userId = await this.requireAuth(dataArg, 'dns-records:write');
           const dnsManager = this.opsServerRef.dcRouterRef.dnsManager;
           if (!dnsManager) return { success: false, message: 'DnsManager not initialized' };
+          const existing = await dnsManager.getRecord(dataArg.id);
+          if (existing) {
+            const claimError = await this.rejectClaimedHostnameMutation(
+              existing.domainId,
+              existing.name,
+              existing.type,
+              userId,
+              'delete',
+            );
+            if (claimError) return { success: false, message: claimError };
+          }
           const result = await dnsManager.deleteRecord(dataArg.id);
           if (result.success) {
             this.opsServerRef.invalidateRealtime?.(['dns', 'emailDomains'], {
@@ -128,4 +171,60 @@ export class DnsRecordHandler {
       ),
     );
   }
+
+  private async rejectClaimedHostnameMutation(
+    domainIdArg: string,
+    hostnameArg: string,
+    recordTypeArg: interfaces.data.TDnsRecordType,
+    actorArg: string,
+    actionArg: 'create' | 'update' | 'delete',
+  ): Promise<string | undefined> {
+    const dnsManager = this.opsServerRef.dcRouterRef.dnsManager;
+    if (!dnsManager) return undefined;
+    if (recordTypeArg !== 'A' && recordTypeArg !== 'AAAA' && recordTypeArg !== 'CNAME') return undefined;
+    let hostname: string;
+    try {
+      hostname = normalizeGatewayHostname(hostnameArg);
+    } catch {
+      return undefined;
+    }
+    const claims = getActiveGatewayDnsClaims(this.opsServerRef.dcRouterRef, hostname);
+    if (!claims.length) return undefined;
+    const ownerSummary = claims
+      .map((claimArg) => `${claimArg.gatewayClientId} (${claimArg.routeExternalKeys.join(', ')})`)
+      .join('; ');
+    const message = `DNS hostname ${hostname} is claimed by gateway client route(s) ${ownerSummary}; actor ${actorArg} cannot ${actionArg} ${recordTypeArg} records at this hostname`;
+    let domainName: string | undefined;
+    try {
+      domainName = (await dnsManager.getDomain(domainIdArg))?.name;
+    } catch (error) {
+      logger.log('warn', `Failed to load DNS domain context for rejected mutation on ${hostname}: ${(error as Error).message}`);
+    }
+    if (this.opsServerRef.dcRouterRef.opsEventManager) {
+      try {
+        await this.opsServerRef.dcRouterRef.opsEventManager.recordEvent({
+          severity: 'error',
+          category: 'dns-conflict',
+          title: 'Rejected manual DNS mutation on gateway-managed hostname',
+          detail: message,
+          context: {
+            domain: domainName,
+            recordName: hostname,
+            routeRef: claims.flatMap((claimArg) => claimArg.routeExternalKeys).join(', '),
+            actor: actorArg,
+          },
+        });
+      } catch (error) {
+        logger.log('warn', `Failed to record rejected gateway DNS mutation for ${hostname}: ${(error as Error).message}`);
+      }
+    }
+    try {
+      this.opsServerRef.invalidateRealtime?.('configEvents', {
+        reason: 'gateway-dns-manual-mutation-rejected',
+      });
+    } catch (error) {
+      logger.log('warn', `Failed to invalidate config events after rejected DNS mutation for ${hostname}: ${(error as Error).message}`);
+    }
+    return message;
+  }
 }