@undefineds.co/xpod 0.4.14 → 0.4.16

package/dist/components/context.jsonld

@@ -1111,48 +1111,6 @@
           }
         }
       },
-      "InternalPodDataHttpHandler": {
-        "@id": "undefineds:dist/http/InternalPodDataHttpHandler.jsonld#InternalPodDataHttpHandler",
-        "@prefix": true,
-        "@context": {
-          "options_resourceStore": {
-            "@id": "undefineds:dist/http/InternalPodDataHttpHandler.jsonld#InternalPodDataHttpHandler_options_resourceStore"
-          },
-          "options_gatewayAdminProxyAuthSecret": {
-            "@id": "undefineds:dist/http/InternalPodDataHttpHandler.jsonld#InternalPodDataHttpHandler_options_gatewayAdminProxyAuthSecret"
-          },
-          "options_patchBodyParser": {
-            "@id": "undefineds:dist/http/InternalPodDataHttpHandler.jsonld#InternalPodDataHttpHandler_options_patchBodyParser"
-          },
-          "options_sparqlHandler": {
-            "@id": "undefineds:dist/http/InternalPodDataHttpHandler.jsonld#InternalPodDataHttpHandler_options_sparqlHandler"
-          },
-          "options_baseUrl": {
-            "@id": "undefineds:dist/http/InternalPodDataHttpHandler.jsonld#InternalPodDataHttpHandler_options_baseUrl"
-          },
-          "options_basePath": {
-            "@id": "undefineds:dist/http/InternalPodDataHttpHandler.jsonld#InternalPodDataHttpHandler_options_basePath"
-          },
-          "resourceStore": {
-            "@id": "undefineds:dist/http/InternalPodDataHttpHandler.jsonld#InternalPodDataHttpHandler_options_resourceStore"
-          },
-          "gatewayAdminProxyAuthSecret": {
-            "@id": "undefineds:dist/http/InternalPodDataHttpHandler.jsonld#InternalPodDataHttpHandler_options_gatewayAdminProxyAuthSecret"
-          },
-          "patchBodyParser": {
-            "@id": "undefineds:dist/http/InternalPodDataHttpHandler.jsonld#InternalPodDataHttpHandler_options_patchBodyParser"
-          },
-          "sparqlHandler": {
-            "@id": "undefineds:dist/http/InternalPodDataHttpHandler.jsonld#InternalPodDataHttpHandler_options_sparqlHandler"
-          },
-          "baseUrl": {
-            "@id": "undefineds:dist/http/InternalPodDataHttpHandler.jsonld#InternalPodDataHttpHandler_options_baseUrl"
-          },
-          "basePath": {
-            "@id": "undefineds:dist/http/InternalPodDataHttpHandler.jsonld#InternalPodDataHttpHandler_options_basePath"
-          }
-        }
-      },
       "QuotaAdminHttpHandler": {
         "@id": "undefineds:dist/http/quota/QuotaAdminHttpHandler.jsonld#QuotaAdminHttpHandler",
         "@prefix": true,
@@ -2983,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"
           },
@@ -2995,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"
           }
@@ -3013,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"
           },
@@ -3028,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"
           },
@@ -4024,6 +3998,11 @@
         "@prefix": true,
         "@context": {}
       },
+      "BuildPublicAccessRoutesOptions": {
+        "@id": "undefineds:dist/edge/reachability/RouteSetBuilder.jsonld#BuildPublicAccessRoutesOptions",
+        "@prefix": true,
+        "@context": {}
+      },
       "ReachabilitySessionService": {
         "@id": "undefineds:dist/edge/reachability/ReachabilitySessionService.jsonld#ReachabilitySessionService",
         "@prefix": true,
@@ -4033,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,
@@ -4073,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,
@@ -4093,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,
@@ -4108,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[];
     };
@@ -91,6 +96,16 @@ export declare class EdgeNodeAgent {
     private recordWithContent;
     private collectSystemMetrics;
     private buildHeartbeatMetadata;
+    /**
+     * Same-machine access point: the local runtime the agent heartbeats for.
+     *
+     * It is published as `local-only`, so it never reaches public route discovery -
+     * a loopback address is meaningless on any other machine - while managed
+     * clients still see it first (priority 10). The canonical URL stays canonical:
+     * loopback is only its access route.
+     */
+    private buildLoopbackHeartbeatRoute;
+    private resolveLoopbackTargetUrl;
     private buildLanHeartbeatRoutes;
     private buildLanHeartbeatRoute;
     private buildP2PHeartbeatRoute;

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;
     }
@@ -229,6 +231,13 @@ class EdgeNodeAgent {
     }
     buildHeartbeatMetadata(options) {
         const metadata = { ...(options.metadata ?? {}) };
+        // Every access point this node has is reported, not just the public one:
+        // clients pick the best path for where they are (`docs/multi-channel-access.md`),
+        // and a same-machine client needs the loopback entry to do that.
+        const loopbackRoute = this.buildLoopbackHeartbeatRoute(options);
+        if (loopbackRoute) {
+            metadata.routes = this.mergeHeartbeatRoutes(metadata.routes, [loopbackRoute]);
+        }
         const lanRoutes = this.buildLanHeartbeatRoutes(options);
         if (lanRoutes.length > 0) {
             metadata.routes = this.mergeHeartbeatRoutes(metadata.routes, lanRoutes);
@@ -239,6 +248,54 @@ class EdgeNodeAgent {
         }
         return metadata;
     }
+    /**
+     * Same-machine access point: the local runtime the agent heartbeats for.
+     *
+     * It is published as `local-only`, so it never reaches public route discovery -
+     * a loopback address is meaningless on any other machine - while managed
+     * clients still see it first (priority 10). The canonical URL stays canonical:
+     * loopback is only its access route.
+     */
+    buildLoopbackHeartbeatRoute(options) {
+        const target = options.p2p?.targetBaseUrl;
+        const targetUrl = this.resolveLoopbackTargetUrl(target);
+        if (!targetUrl) {
+            return undefined;
+        }
+        return {
+            id: 'loopback',
+            nodeId: options.nodeId,
+            ...(options.baseUrl ? { canonicalUrl: options.baseUrl } : {}),
+            kind: 'loopback',
+            targetUrl,
+            priority: 10,
+            requiresManagedClient: true,
+            visibility: 'local-only',
+            health: 'healthy',
+            metadata: {
+                source: 'local-runtime',
+            },
+        };
+    }
+    resolveLoopbackTargetUrl(target) {
+        if (!target) {
+            return undefined;
+        }
+        try {
+            const url = target instanceof URL ? target : new URL(String(target));
+            if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+                return undefined;
+            }
+            const hostname = url.hostname.toLowerCase().replace(/^\[|\]$/gu, '');
+            if (hostname !== 'localhost' && hostname !== '127.0.0.1' && hostname !== '::1') {
+                return undefined;
+            }
+            return url.href.endsWith('/') ? url.href : `${url.href}/`;
+        }
+        catch {
+            return undefined;
+        }
+    }
     buildLanHeartbeatRoutes(options) {
         const p2p = options.p2p;
         if (!p2p || this.normalizeBoolean(p2p.enabled) === false) {
@@ -432,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/EdgeNodeAgent.jsonld

@@ -212,6 +212,14 @@
           "@id": "undefineds:dist/edge/EdgeNodeAgent.jsonld#EdgeNodeAgent__member_buildHeartbeatMetadata",
           "memberFieldName": "buildHeartbeatMetadata"
         },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeAgent.jsonld#EdgeNodeAgent__member_buildLoopbackHeartbeatRoute",
+          "memberFieldName": "buildLoopbackHeartbeatRoute"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeAgent.jsonld#EdgeNodeAgent__member_resolveLoopbackTargetUrl",
+          "memberFieldName": "resolveLoopbackTargetUrl"
+        },
         {
           "@id": "undefineds:dist/edge/EdgeNodeAgent.jsonld#EdgeNodeAgent__member_buildLanHeartbeatRoutes",
           "memberFieldName": "buildLanHeartbeatRoutes"

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);