@serve.zone/dcrouter 17.2.3 → 17.3.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/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;
+  }
 }