@undefineds.co/xpod 0.4.15 → 0.4.16

package/dist/cli/commands/start.js

@@ -4,7 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.startCommand = void 0;
-exports.resolveIngressPort = resolveIngressPort;
+exports.describeIngressDecision = describeIngressDecision;
 exports.resolveCliOidcIssuer = resolveCliOidcIssuer;
 exports.resolveManagedEdgeAgentConfig = resolveManagedEdgeAgentConfig;
 exports.resolveChildDatabaseUrl = resolveChildDatabaseUrl;
@@ -16,7 +16,7 @@ const fs_1 = __importDefault(require("fs"));
 const global_logger_factory_1 = require("global-logger-factory");
 const supervisor_1 = require("../../supervisor");
 const runtime_1 = require("../../runtime");
-const SakuraFrpTunnelProvider_1 = require("../../tunnel/SakuraFrpTunnelProvider");
+const ingress_port_1 = require("../../runtime/ingress-port");
 const css_process_1 = require("../../runtime/css-process");
 const oidc_issuer_1 = require("../../runtime/oidc-issuer");
 const AuthMode_1 = require("../../authorization/AuthMode");
@@ -107,17 +107,30 @@ exports.startCommand = {
         const cssPort = await (0, runtime_1.getFreePortForWildcard)(requestedCssPort);
         const requestedApiPort = resolveServicePort(process.env.API_PORT, cssPort + 1, new Set([mainPort, cssPort]));
         const apiPort = await (0, runtime_1.getFreePortForWildcard)(requestedApiPort);
-        // Remote forwarding (managed tunnels, P2P data plane) terminates on this machine, so
-        // its origin is a dedicated ingress port instead of the gateway port: the Gateway
-        // never treats requests accepted there as local. An explicit override is honoured;
-        // otherwise the OS assigns a loopback port, because neighbouring ports may already
-        // belong to another service this deployment planned.
-        // The port is a fact of whichever tunnel forwards to us: an explicit override pins it,
-        // and the SakuraFrp console's own 本地端口 is read back from the provider, so the
-        // operator never types the same number twice. Only an unmanaged ingress is ephemeral.
-        // A pinned port is taken as-is: silently moving it would leave the tunnel pointing at a
-        // port nobody listens on.
-        const ingressPort = await resolveIngressPort(provisionedConfig, mainPort);
+        // Remote forwarding (managed tunnels, P2P data plane) terminates on this machine, so its
+        // origin is a dedicated ingress port instead of the gateway port: the Gateway never treats
+        // requests accepted there as local.
+        //
+        // Order (see `resolveIngressPort`): an explicit `XPOD_GATEWAY_INGRESS_PORT` wins; otherwise
+        // the *active* profile's provider console decides — for a console-owned tunnel the runtime
+        // adopts the port that console already declares (SakuraFrp's `local_port`, the Cloudflare
+        // dashboard's remote configuration read back through the connector) instead of asking the
+        // operator to edit the console; only an entry nobody declares is derived from the gateway
+        // port (gateway+3..+9).
+        //
+        // Both strict sources are strict: a port that somebody else holds fails the start with the
+        // occupant named (pid, command line, cwd), and nothing is ever signalled or silently moved
+        // to another port - the tunnel forwards to a number, so it must find this runtime there.
+        const ingress = await (0, ingress_port_1.resolveIngressPort)({
+            mainPort,
+            env: process.env,
+            profiles: provisionedConfig.tunnelProfiles ?? [],
+            ...(provisionedConfig.tunnelActiveProfileId
+                ? { activeProfileId: provisionedConfig.tunnelActiveProfileId }
+                : {}),
+            reservedPorts: [mainPort, cssPort, apiPort],
+        });
+        const ingressPort = ingress.port;
         // Published so the API can tell the operator which address a tunnel must forward to.
         process.env.XPOD_GATEWAY_INGRESS_PORT = String(ingressPort);
         const runtimeRoot = path_1.default.join(process.cwd(), '.xpod/runtime/legacy-css');
@@ -143,6 +156,7 @@ exports.startCommand = {
         console.log(`  Gateway: ${baseUrl} (${argv.host}:${mainPort})`);
         console.log(`  CSS (internal): http://localhost:${cssPort}`);
         console.log(`  API (internal): http://localhost:${apiPort}`);
+        console.log(`  Tunnel entry: http://127.0.0.1:${ingressPort} — ${describeIngressDecision(ingress)}`);
         if (externalOidcIssuer) {
             console.log(`  SP mode: Cloud IdP = ${externalOidcIssuer}`);
         }
@@ -235,36 +249,26 @@ exports.startCommand = {
 /**
  * Where remote-forwarded traffic lands on this machine.
  *
- * Order: explicit `XPOD_GATEWAY_INGRESS_PORT` → the active SakuraFrp tunnel's assigned local
- * port → an OS-assigned loopback port. The first two are strict, because a tunnel that
- * forwards to a specific port cannot follow us somewhere else.
+ * The decision (explicit pin → the active profile's console declaration → the gateway-derived
+ * entry) lives in `src/runtime/ingress-port.ts`, together with the strict "taken means taken"
+ * check and the occupant naming. This only reports the outcome, so the startup banner says
+ * whether the entry was pinned, adopted from a console, or derived from the gateway port.
  */
-/**
- * The port a remote tunnel forwards to: the Gateway's tunnel entry.
- *
- * It is derived from the Gateway port by the same rule the runtime uses, so the CLI can hand
- * it to the managed edge agent before the runtime binds it. A console that forwards somewhere
- * else is a mismatch the tunnel provider reports from its own read-back - the runtime never
- * moves its gate to match a console.
- */
-async function resolveIngressPort(provisionedConfig, mainPort) {
-    const port = await (0, runtime_1.findGatewayIngressPort)(mainPort);
-    const active = provisionedConfig.tunnelProfiles?.find((profile) => profile.id === provisionedConfig.tunnelActiveProfileId) ?? provisionedConfig.tunnelProfiles?.find((profile) => profile.provider === 'sakura_frp');
-    if (active?.provider === 'sakura_frp') {
-        const credential = active.credentialEnvKey
-            ? process.env[active.credentialEnvKey] ?? process.env.SAKURA_TUNNEL_TOKEN
-            : process.env.SAKURA_TUNNEL_TOKEN;
-        const assigned = await (0, SakuraFrpTunnelProvider_1.resolveSakuraAssignedLocalPort)(credential);
-        if (assigned !== undefined && assigned !== port) {
-            (0, global_logger_factory_1.getLoggerFor)('XpodStart').warn(`The Sakura console forwards to local port ${assigned}, but this runtime's tunnel entry is ${port}; `
-                + `update the tunnel's local port in the console to ${port}`);
-        }
+function describeIngressDecision(ingress) {
+    if (ingress.source === 'explicit') {
+        return `pinned by XPOD_GATEWAY_INGRESS_PORT`;
+    }
+    if (ingress.source === 'console-declared' && ingress.declared) {
+        return `adopted from the ${ingress.declared.provider} console (${ingress.declared.readBack})`;
     }
-    return port;
+    return 'derived from the gateway port (gateway+3..+9)';
 }
 function resolveCliOidcIssuer(env, provisionedIssuer, edition) {
+    // A remembered loopback issuer is residue from a run that served it; this one does not, so the
+    // local edition falls back to the Cloud identity instead of a port with no listener.
+    const remembered = (0, oidc_issuer_1.isLoopbackIssuer)(provisionedIssuer) ? undefined : provisionedIssuer;
     return (0, oidc_issuer_1.resolveExternalOidcIssuer)(env)
-        ?? (0, oidc_issuer_1.resolveExternalOidcIssuer)({ SOLID_OIDC_ISSUER: provisionedIssuer })
+        ?? (0, oidc_issuer_1.resolveExternalOidcIssuer)({ SOLID_OIDC_ISSUER: remembered })
         ?? (edition === 'local' ? oidc_issuer_1.DEFAULT_LOCAL_OIDC_ISSUER : undefined);
 }
 function resolveManagedEdgeAgentConfig(config, gatewayPort, ingressPort, runtimeEnv = {}) {

package/dist/cli/commands/stop.js

@@ -39,11 +39,17 @@ exports.stopCommand = {
         }
         try {
             const res = await fetch(`${baseUrl}/service/status`);
-            if (!res.ok) {
+            // 503 means the gateway is reachable but degraded (a supervised child is down or gave up).
+            // Stopping a half-dead instance must stay possible, so only other failures are fatal.
+            const degraded = res.status === 503;
+            if (!res.ok && !degraded) {
                 throw new output_1.CliCommandError('server_not_reachable', 'Service not reachable or already stopped.', 1, {
                     status: res.status,
                 });
             }
+            if (degraded && !argv.json) {
+                console.log('Instance is degraded (a supervised service is not running); stopping it anyway.');
+            }
             const statuses = (await res.json());
             const running = statuses.filter((s) => s.status === 'running');
             if (running.length === 0) {

package/dist/components/components.jsonld

@@ -138,6 +138,7 @@
     "undefineds:dist/edge/reachability/ManagedRouteSelector.jsonld",
     "undefineds:dist/edge/reachability/CanonicalFetch.jsonld",
     "undefineds:dist/edge/reachability/P2PDataPlane.jsonld",
+    "undefineds:dist/edge/reachability/P2PDataPlaneCrypto.jsonld",
     "undefineds:dist/edge/reachability/P2PSignalingClient.jsonld",
     "undefineds:dist/edge/reachability/TcpP2PDataPlaneTransport.jsonld",
     "undefineds:dist/edge/reachability/TcpP2PSignalingSession.jsonld",

package/dist/components/context.jsonld

@@ -2941,6 +2941,10 @@
           "options_cloudflaredPath": {
             "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider_options_cloudflaredPath"
           },
+          "options_env": {
+            "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider_options_env",
+            "@container": "@list"
+          },
           "options_connectTimeoutMs": {
             "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider_options_connectTimeoutMs"
           },
@@ -2953,6 +2957,10 @@
           "cloudflaredPath": {
             "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider_options_cloudflaredPath"
           },
+          "env": {
+            "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider_options_env",
+            "@container": "@list"
+          },
           "connectTimeoutMs": {
             "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider_options_connectTimeoutMs"
           }
@@ -2971,6 +2979,10 @@
           "options_ngrokPath": {
             "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider_options_ngrokPath"
           },
+          "options_env": {
+            "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider_options_env",
+            "@container": "@list"
+          },
           "options_agentApiUrl": {
             "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider_options_agentApiUrl"
           },
@@ -2986,6 +2998,10 @@
           "ngrokPath": {
             "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider_options_ngrokPath"
           },
+          "env": {
+            "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider_options_env",
+            "@container": "@list"
+          },
           "agentApiUrl": {
             "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider_options_agentApiUrl"
           },
@@ -3996,6 +4012,16 @@
           }
         }
       },
+      "InvalidP2PSessionRequestError": {
+        "@id": "undefineds:dist/edge/reachability/ReachabilitySessionService.jsonld#InvalidP2PSessionRequestError",
+        "@prefix": true,
+        "@context": {}
+      },
+      "NodeMetadataConflictError": {
+        "@id": "undefineds:dist/edge/reachability/ReachabilitySessionService.jsonld#NodeMetadataConflictError",
+        "@prefix": true,
+        "@context": {}
+      },
       "P2PActiveSessionLimitExceededError": {
         "@id": "undefineds:dist/edge/reachability/ReachabilitySessionService.jsonld#P2PActiveSessionLimitExceededError",
         "@prefix": true,
@@ -4036,11 +4062,21 @@
         "@prefix": true,
         "@context": {}
       },
+      "P2PDataPlaneRequestOptions": {
+        "@id": "undefineds:dist/edge/reachability/P2PDataPlane.jsonld#P2PDataPlaneRequestOptions",
+        "@prefix": true,
+        "@context": {}
+      },
       "P2PDataPlaneTransport": {
         "@id": "undefineds:dist/edge/reachability/P2PDataPlane.jsonld#P2PDataPlaneTransport",
         "@prefix": true,
         "@context": {}
       },
+      "P2PDataPlaneLimitsOptions": {
+        "@id": "undefineds:dist/edge/reachability/P2PDataPlane.jsonld#P2PDataPlaneLimitsOptions",
+        "@prefix": true,
+        "@context": {}
+      },
       "P2PDataPlaneFetchOptions": {
         "@id": "undefineds:dist/edge/reachability/P2PDataPlane.jsonld#P2PDataPlaneFetchOptions",
         "@prefix": true,
@@ -4056,6 +4092,25 @@
         "@prefix": true,
         "@context": {}
       },
+      "P2PDataPlaneSecurityError": {
+        "@id": "undefineds:dist/edge/reachability/P2PDataPlaneCrypto.jsonld#P2PDataPlaneSecurityError",
+        "@prefix": true,
+        "@context": {
+          "message": {
+            "@id": "undefineds:dist/edge/reachability/P2PDataPlaneCrypto.jsonld#P2PDataPlaneSecurityError_message"
+          }
+        }
+      },
+      "P2PDataPlaneKeys": {
+        "@id": "undefineds:dist/edge/reachability/P2PDataPlaneCrypto.jsonld#P2PDataPlaneKeys",
+        "@prefix": true,
+        "@context": {}
+      },
+      "SealedDataPlaneFrame": {
+        "@id": "undefineds:dist/edge/reachability/P2PDataPlaneCrypto.jsonld#SealedDataPlaneFrame",
+        "@prefix": true,
+        "@context": {}
+      },
       "P2PSignalingClientOptions": {
         "@id": "undefineds:dist/edge/reachability/P2PSignalingClient.jsonld#P2PSignalingClientOptions",
         "@prefix": true,
@@ -4071,6 +4126,11 @@
         "@prefix": true,
         "@context": {}
       },
+      "P2PDataPlaneSecurityOptions": {
+        "@id": "undefineds:dist/edge/reachability/TcpP2PDataPlaneTransport.jsonld#P2PDataPlaneSecurityOptions",
+        "@prefix": true,
+        "@context": {}
+      },
       "TcpP2PDataPlaneTransportOptions": {
         "@id": "undefineds:dist/edge/reachability/TcpP2PDataPlaneTransport.jsonld#TcpP2PDataPlaneTransportOptions",
         "@prefix": true,

package/dist/dns/cloudflare/CloudflareDnsProvider.d.ts

@@ -31,9 +31,18 @@ export declare class CloudflareDnsProvider implements ListableDnsProvider {
      */
     private getZoneId;
     /**
-     * 查找现有 DNS 记录
+     * 查找现有 DNS 记录。
+     *
+     * `type` 与 `value` 都会下推到 API 查询里，返回**全部**匹配项而不是 `response[0]`：
+     * 调用方要按类型判断能不能动这条记录，靠“第一条”猜类型正是 N14 的成因。
      */
+    private findRecords;
     private findRecord;
+    /**
+     * 是否与目标类型互斥：CNAME 不能与任何其他记录共存（RFC 1034），其余组合（含 TXT 与
+     * A/AAAA、MX 与 A/AAAA）都可以并存。
+     */
+    private static isMutuallyExclusive;
     /**
      * 调用 Cloudflare API
      */

package/dist/dns/cloudflare/CloudflareDnsProvider.js

@@ -27,32 +27,34 @@ class CloudflareDnsProvider {
         const zoneId = await this.getZoneId(options.domain);
         const fullName = this.buildFullName(options.subdomain, options.domain);
         const ttl = options.ttl ?? 1; // Cloudflare: 1 = auto
-        // 查找所有同名记录（不限类型），以处理 CNAME 与 A/AAAA 冲突
-        const existing = await this.findRecord(zoneId, fullName);
+        // 一次拉回该名字下的全部记录，再按类型判断（审计 N14）。
+        // 旧实现只取第一条、类型不同就删除——于是 `_acme-challenge` 的 TXT 或同一名字下的 MX
+        // 会被“为写 A 记录”误删。
+        const records = await this.findRecords(zoneId, fullName);
+        const existing = records.find((record) => record.type === options.type);
         if (existing) {
-            // 如果现有记录类型不同（如 CNAME vs AAAA），必须先删除旧记录
-            if (existing.type !== options.type) {
-                this.logger.info(`发现 DNS 类型冲突 (现有: ${existing.type}, 目标: ${options.type})，正在删除旧记录 ${fullName}...`);
-                await this.callApi(`zones/${zoneId}/dns_records/${existing.id}`, 'DELETE');
-                // 删除后继续执行创建逻辑
-            }
-            else {
-                // 类型相同，检查内容是否需要更新
-                if (existing.content === options.value && (existing.ttl === ttl || ttl === 1)) {
-                    this.logger.debug(`DNS 记录已存在且一致，跳过更新 ${fullName} ${options.type}`);
-                    return;
-                }
-                // 更新现有记录
-                await this.callApi(`zones/${zoneId}/dns_records/${existing.id}`, 'PATCH', {
-                    type: options.type,
-                    name: fullName,
-                    content: options.value,
-                    ttl,
-                    proxied: false, // DNS-01 验证需要关闭代理
-                });
-                this.logger.info(`已更新 DNS 记录 ${fullName} ${options.type}`);
+            // 类型相同，检查内容是否需要更新
+            if (existing.content === options.value && (existing.ttl === ttl || ttl === 1)) {
+                this.logger.debug(`DNS 记录已存在且一致，跳过更新 ${fullName} ${options.type}`);
                 return;
             }
+            // 更新现有记录
+            await this.callApi(`zones/${zoneId}/dns_records/${existing.id}`, 'PATCH', {
+                type: options.type,
+                name: fullName,
+                content: options.value,
+                ttl,
+                proxied: false, // DNS-01 验证需要关闭代理
+            });
+            this.logger.info(`已更新 DNS 记录 ${fullName} ${options.type}`);
+            return;
+        }
+        // 只有 CNAME 与其他记录类型互斥（RFC 1034）：写 A/AAAA 前要清掉同名 CNAME，写 CNAME 前
+        // 要清掉同名 A/AAAA。MX/TXT 等类型可以与 A/AAAA 共存，必须原样保留。
+        const conflicting = records.find((record) => CloudflareDnsProvider.isMutuallyExclusive(options.type, record.type));
+        if (conflicting) {
+            this.logger.info(`发现互斥 DNS 记录 (现有: ${conflicting.type}, 目标: ${options.type})，删除该记录 ${conflicting.id} (${fullName})...`);
+            await this.callApi(`zones/${zoneId}/dns_records/${conflicting.id}`, 'DELETE');
         }
         // 创建新记录
         await this.callApi(`zones/${zoneId}/dns_records`, 'POST', {
@@ -71,12 +73,19 @@ class CloudflareDnsProvider {
         }
         const zoneId = await this.getZoneId(options.domain);
         const fullName = this.buildFullName(options.subdomain, options.domain);
-        // 删除时也要支持泛查找，以防类型传错，但通常 deleteRecord 会传 type
-        const existing = await this.findRecord(zoneId, fullName, options.type, options.value);
+        // 删除必须带类型（接口里 type 是必填）：按“同名 + 同类型（+ 同内容）”精确匹配，
+        // 绝不退化成“删这个名字下的第一条记录”。
+        const matches = await this.findRecords(zoneId, fullName, options.type, options.value);
+        const existing = matches[0];
         if (!existing) {
             this.logger.debug(`DNS 记录不存在，跳过删除 ${fullName} ${options.type}`);
             return;
         }
+        if (existing.type !== options.type) {
+            // API 不该返回别的类型；真返回了就宁可不删，也不动别人的记录。
+            this.logger.warn(`拒绝删除类型不匹配的记录 ${fullName}：请求 ${options.type}，返回 ${existing.type}`);
+            return;
+        }
         await this.callApi(`zones/${zoneId}/dns_records/${existing.id}`, 'DELETE');
         this.logger.info(`已删除 DNS 记录 ${fullName} ${options.type}`);
     }
@@ -130,9 +139,12 @@ class CloudflareDnsProvider {
         throw new Error(`找不到域名 ${domain} 的任何所属 Zone，请检查域名是否正确或手动提供 zoneId`);
     }
     /**
-     * 查找现有 DNS 记录
+     * 查找现有 DNS 记录。
+     *
+     * `type` 与 `value` 都会下推到 API 查询里，返回**全部**匹配项而不是 `response[0]`：
+     * 调用方要按类型判断能不能动这条记录，靠“第一条”猜类型正是 N14 的成因。
      */
-    async findRecord(zoneId, fullName, type, value) {
+    async findRecords(zoneId, fullName, type, value) {
         const params = new URLSearchParams({
             name: fullName,
         });
@@ -143,7 +155,26 @@ class CloudflareDnsProvider {
             params.set('content', value);
         }
         const response = await this.callApi(`zones/${zoneId}/dns_records?${params.toString()}`, 'GET');
-        return response[0];
+        return Array.isArray(response) ? response : [];
+    }
+    async findRecord(zoneId, fullName, type, value) {
+        return (await this.findRecords(zoneId, fullName, type, value)).find((record) => type === undefined || record.type === type);
+    }
+    /**
+     * 是否与目标类型互斥：CNAME 不能与任何其他记录共存（RFC 1034），其余组合（含 TXT 与
+     * A/AAAA、MX 与 A/AAAA）都可以并存。
+     */
+    static isMutuallyExclusive(target, existing) {
+        if (existing === target) {
+            return false;
+        }
+        if (target === 'TXT') {
+            return false;
+        }
+        if (existing === 'CNAME') {
+            return true;
+        }
+        return target === 'CNAME' && (existing === 'A' || existing === 'AAAA');
     }
     /**
      * 调用 Cloudflare API

package/dist/edge/EdgeNodeAgent.d.ts

@@ -34,6 +34,11 @@ export interface EdgeNodeAgentOptions {
         certificatePath: string;
         fullChainPath?: string;
         renewBeforeDays?: number;
+        /** 后台续期检查间隔（默认 6 小时）；仅在本地 ACME 模式使用。 */
+        renewalCheckIntervalMs?: number;
+        /** 续期失败后的首次重试延迟（默认 60 秒，指数增长到上限）。 */
+        renewalRetryBaseDelayMs?: number;
+        renewalRetryMaxDelayMs?: number;
         propagationDelayMs?: number;
         postDeployCommand?: string[];
     };

package/dist/edge/EdgeNodeAgent.js

@@ -106,6 +106,8 @@ class EdgeNodeAgent {
         this.p2pAcceptRunning = false;
         void this.frpManager?.stop();
         this.clusterCertificate?.stop();
+        // 停止后不该再有后台续期：一个已停的 agent 不该继续向 CA 发请求。
+        this.localCertificate?.stopAutoRenewal();
         this.localCertificate = undefined;
         this.clusterCertificate = undefined;
     }
@@ -487,6 +489,12 @@ class EdgeNodeAgent {
             if (issued && acmeOptions.postDeployCommand && acmeOptions.postDeployCommand.length > 0) {
                 await this.runPostDeploy(acmeOptions.postDeployCommand);
             }
+            // 启动即检查只解决"开机时过期"，节点长期运行要靠后台续期（审计 N15）。
+            manager.startAutoRenewal({
+                intervalMs: acmeOptions.renewalCheckIntervalMs,
+                retryBaseDelayMs: acmeOptions.renewalRetryBaseDelayMs,
+                retryMaxDelayMs: acmeOptions.renewalRetryMaxDelayMs,
+            });
         }
         catch (error) {
             this.logger.error(`自动签发证书失败：${error.message}`);

package/dist/edge/acme/AcmeCertificateManager.d.ts

@@ -1,3 +1,4 @@
+import { type CertificateRenewalSchedulerStatus } from './CertificateRenewalScheduler';
 import type { DnsProvider } from '../../dns/DnsProvider';
 /**
  * DNS 验证处理器接口
@@ -60,9 +61,29 @@ export declare class AcmeCertificateManager {
     private readonly renewBeforeDays;
     private readonly propagationDelayMs;
     private issuing;
+    private renewalScheduler?;
     constructor(options: AcmeCertificateManagerOptions);
     ensureCertificate(): Promise<boolean>;
     readCertificateStatus(): Promise<RuntimeCertificateStatus>;
+    /**
+     * Starts the background renewal loop (audit N15).
+     *
+     * `ensureCertificate()` only looks at startup: a long-running node needed someone to call
+     * `renewCertificate()` by hand before the certificate expired. The scheduler checks on an
+     * interval, renews when the status is due, and backs off when the CA is unreachable.
+     */
+    startAutoRenewal(options?: {
+        intervalMs?: number;
+        retryBaseDelayMs?: number;
+        retryMaxDelayMs?: number;
+    }): void;
+    /**
+     * Stops the loop but keeps its final status readable: "why did it stop renewing" is exactly
+     * the question an operator asks after a failed renewal, and a discarded scheduler cannot
+     * answer it.
+     */
+    stopAutoRenewal(): void;
+    getRenewalSchedulerStatus(): CertificateRenewalSchedulerStatus | undefined;
     isAvailable(): boolean;
     renewCertificate(): Promise<RuntimeCertificateRenewalResult>;
     private extractDomainsFromCertificate;
@@ -71,6 +92,9 @@ export declare class AcmeCertificateManager {
     private issueCertificateFromCA;
     private ensureAccount;
     private loadOrCreateAccountKey;
+    /** 写私钥：创建时就用 0600，并对已存在的文件再 chmod 一次。 */
+    private writePrivateFile;
+    private restrictFileMode;
     private readOptionalFile;
     private ensureDirectory;
     private delay;

package/dist/edge/acme/AcmeCertificateManager.js

@@ -10,6 +10,7 @@ const promises_1 = require("node:fs/promises");
 const node_crypto_1 = require("node:crypto");
 const acme_client_1 = __importDefault(require("acme-client"));
 const global_logger_factory_1 = require("global-logger-factory");
+const CertificateRenewalScheduler_1 = require("./CertificateRenewalScheduler");
 const DnsChallengeClient_1 = require("./DnsChallengeClient");
 const utils_1 = require("./utils");
 /**
@@ -52,10 +53,16 @@ class LocalDnsChallengeHandler {
 }
 exports.LocalDnsChallengeHandler = LocalDnsChallengeHandler;
 const DEFAULT_DIRECTORY_URL = acme_client_1.default.directory.letsencrypt.production;
+// Staging is deliberately NOT in the default failover list: a staging certificate is not trusted
+// by any browser, so a production deployment that "succeeded" through it would be serving a
+// broken endpoint while reporting success (audit N15). ZeroSSL is a real alternative CA.
 const DEFAULT_FALLBACK_URLS = [
-    acme_client_1.default.directory.letsencrypt.staging, // Staging as fallback for testing
-    'https://acme.zerossl.com/v2/DV90', // ZeroSSL as alternative CA
+    'https://acme.zerossl.com/v2/DV90',
 ];
+/** A staging/test directory: certificates from here are not trusted by clients. */
+function isStagingDirectory(directoryUrl) {
+    return /staging|acme-staging/iu.test(directoryUrl);
+}
 class AcmeCertificateManager {
     constructor(options) {
         this.logger = (0, global_logger_factory_1.getLoggerFor)(this);
@@ -83,6 +90,8 @@ class AcmeCertificateManager {
         this.email = options.email;
         this.domains = options.domains;
         this.directoryUrl = options.directoryUrl ?? DEFAULT_DIRECTORY_URL;
+        // A staging CA only ever appears here because the operator listed it explicitly; the
+        // defaults never add one (audit N15).
         this.fallbackDirectoryUrls = options.fallbackDirectoryUrls ?? DEFAULT_FALLBACK_URLS;
         this.accountKeyPath = options.accountKeyPath;
         this.certificateKeyPath = options.certificateKeyPath;
@@ -126,6 +135,39 @@ class AcmeCertificateManager {
             return { status: 'missing' };
         }
     }
+    /**
+     * Starts the background renewal loop (audit N15).
+     *
+     * `ensureCertificate()` only looks at startup: a long-running node needed someone to call
+     * `renewCertificate()` by hand before the certificate expired. The scheduler checks on an
+     * interval, renews when the status is due, and backs off when the CA is unreachable.
+     */
+    startAutoRenewal(options = {}) {
+        if (this.renewalScheduler) {
+            // Already created: start() is a no-op while running, and restarts it after a stop.
+            this.renewalScheduler.start();
+            return;
+        }
+        this.renewalScheduler = new CertificateRenewalScheduler_1.CertificateRenewalScheduler({
+            readStatus: async () => await this.readCertificateStatus(),
+            renew: async () => {
+                await this.renewCertificate();
+            },
+            ...options,
+        });
+        this.renewalScheduler.start();
+    }
+    /**
+     * Stops the loop but keeps its final status readable: "why did it stop renewing" is exactly
+     * the question an operator asks after a failed renewal, and a discarded scheduler cannot
+     * answer it.
+     */
+    stopAutoRenewal() {
+        this.renewalScheduler?.stop();
+    }
+    getRenewalSchedulerStatus() {
+        return this.renewalScheduler?.getStatus();
+    }
     isAvailable() {
         return this.domains.some((domain) => domain.trim().length > 0)
             && this.email.trim().length > 0
@@ -180,12 +222,21 @@ class AcmeCertificateManager {
         if (this.fullChainPath) {
             await this.ensureDirectory((0, node_path_1.dirname)(this.fullChainPath));
         }
-        // Try primary CA first, then fallback CAs
+        // Try the primary CA first, then the failover chain. The chain is exactly what the operator
+        // configured: the defaults contain no staging CA, so a production deployment cannot silently
+        // end up serving a certificate no client trusts (audit N15).
         const directoryUrls = [this.directoryUrl, ...this.fallbackDirectoryUrls];
+        const stagingInChain = directoryUrls.filter(isStagingDirectory);
+        if (stagingInChain.length > 0 && !isStagingDirectory(this.directoryUrl)) {
+            this.logger.warn(`ACME 失败切换链包含 staging CA（${stagingInChain.join(', ')}）：该 CA 签发的证书客户端不信任`);
+        }
         let lastError;
         for (const directoryUrl of directoryUrls) {
             try {
                 await this.issueCertificateFromCA(directoryUrl);
+                if (isStagingDirectory(directoryUrl)) {
+                    this.logger.warn(`证书由 staging CA 签发，客户端不会信任：${directoryUrl}`);
+                }
                 return; // Success!
             }
             catch (error) {
@@ -196,8 +247,9 @@ class AcmeCertificateManager {
                 }
             }
         }
-        // All CAs failed
-        throw new Error(`所有 ACME CA 都失败。最后错误: ${lastError?.message}`);
+        // All CAs failed: name every CA that was tried, so the operator does not have to guess.
+        throw new Error(`所有 ACME CA 都失败（已尝试 ${directoryUrls.length} 个：${directoryUrls.join(', ')}）。`
+            + `最后错误: ${lastError?.message}`);
     }
     async issueCertificateFromCA(directoryUrl) {
         this.logger.info(`使用 ACME CA: ${directoryUrl}`);
@@ -228,7 +280,8 @@ class AcmeCertificateManager {
                 await this.dnsHandler.removeChallenge(recordName);
             },
         });
-        await node_fs_1.promises.writeFile(this.certificateKeyPath, privateKey.toString());
+        // 私钥 0600（证书本身是公开材料，保持默认权限即可）：审计 N18。
+        await this.writePrivateFile(this.certificateKeyPath, privateKey.toString());
         await node_fs_1.promises.writeFile(this.certificatePath, certificate);
         if (this.fullChainPath) {
             await node_fs_1.promises.writeFile(this.fullChainPath, certificate);
@@ -255,13 +308,28 @@ class AcmeCertificateManager {
     async loadOrCreateAccountKey(path) {
         const existing = await this.readOptionalFile(path);
         if (existing) {
+            // 旧版本可能留下了 0644 的账户私钥，读到就顺手收紧。
+            await this.restrictFileMode(path);
             return existing.toString();
         }
         await this.ensureDirectory((0, node_path_1.dirname)(path));
         const key = await acme_client_1.default.crypto.createPrivateKey();
-        await node_fs_1.promises.writeFile(path, key);
+        await this.writePrivateFile(path, key.toString());
         return key.toString();
     }
+    /** 写私钥：创建时就用 0600，并对已存在的文件再 chmod 一次。 */
+    async writePrivateFile(path, contents) {
+        await node_fs_1.promises.writeFile(path, contents, { encoding: 'utf8', mode: 0o600 });
+        await this.restrictFileMode(path);
+    }
+    async restrictFileMode(path) {
+        try {
+            await node_fs_1.promises.chmod(path, 0o600);
+        }
+        catch (error) {
+            this.logger.warn(`无法收紧私钥文件权限 ${path}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
     async readOptionalFile(path) {
         try {
             return await node_fs_1.promises.readFile(path);