dsh-mobile 0.4.5 → 0.4.7

package/lib/index.d.mts

@@ -1,3 +1,4 @@
+import { X509Certificate } from "node:crypto";
 import z from "@deepseek-ai/schemastery";
 import { ChildProcessWithoutNullStreams } from "node:child_process";
 import { Readable } from "node:stream";
@@ -261,6 +262,8 @@ interface PluginConfig {
   mobileLayoutFile?: string;
   /** Standalone browser compatibility bundle used before DSH boot. */
   mobileCompatibilityFile?: string;
+  /** Optional application-phase client package ids omitted only from the mobile boot graph. */
+  excludedClientModules?: string[];
   /** Stable public discovery identifier; it is not an authentication secret. */
   instanceId?: string;
   /** Managed CA certificate offered to the Android installer after fingerprint binding. */
@@ -301,6 +304,7 @@ interface ResolvedGatewayConfig {
   readonly customScriptFile: string;
   readonly mobileLayoutFile: string;
   readonly mobileCompatibilityFile: string;
+  readonly excludedClientModules: readonly string[];
   readonly instanceId: string;
   readonly pairingCaFile?: string;
   readonly tls: TlsConfig;
@@ -588,8 +592,8 @@ declare class MobileAccessService extends Service {
 declare function createMobileAccessService(ctx: Context): MobileAccessService;
 //#endregion
 //#region src/gateway.d.ts
-/** Replace only DSH's layout client module while retaining its complete plugin graph. */
-declare function rewriteMobileIndex(html: string): string;
+/** Rewrite the dedicated mobile graph; exclusions are opt-in and leave stock DSH unchanged. */
+declare function rewriteMobileIndex(html: string, excludedClientModules?: readonly string[]): string;
 /** Authenticated TLS edge in front of the ordinary loopback-only DSH Web server. */
 declare class MobileAccessGateway {
   readonly config: ResolvedGatewayConfig;
@@ -615,6 +619,7 @@ declare class MobileAccessGateway {
   private mdnsError;
   /** Names of the bundled mobile assets that could not be read, if any. */
   private mobileAssetError;
+  private lastModuleExclusionError;
   private bonjour;
   private pairingCaCertificate;
   private listenerPort;
@@ -649,6 +654,8 @@ declare class MobileAccessGateway {
   } | undefined, blockedUpgradeLog?: BlockedUpgradePathLog | undefined, onDiscoveryDegraded?: ((source: 'broadcast' | 'mdns', code: string) => void) | undefined);
   /** Initialize durable state, validate TLS, and bind the externally reachable listener. */
   start(): Promise<void>;
+  /** Install a newly signed provided leaf for future TLS handshakes without dropping sessions. */
+  refreshProvidedTls(): Promise<void>;
   private startDiscovery;
   private reportDiscoveryDegraded;
   private recordBroadcastFailure;
@@ -839,12 +846,51 @@ declare const FRP_CADDY_SNIPPET_PATH = "/etc/caddy/dsh-mobile-dsh.caddy";
 declare const FRP_CADDY_SNIPPET_MARKER = "# Managed by DSH Mobile - snippet, safe to delete";
 /** Exact line the main Caddyfile must contain (uncommented) for the site to load. */
 declare const FRP_CADDY_IMPORT_LINE = "import /etc/caddy/dsh-mobile-dsh.caddy";
-/** Build the Caddy site for one public host (without markers or import wiring). */
-declare function createCaddySite(publicHost: string, certDir?: string): string;
-/** Build the only supported frps config and Caddy snippet from validated user inputs. */
-declare function createRestrictedFrpServerTemplate(serverPort: number, token: string, publicOrigin: string): string;
+/**
+ * Entry TLS mode for the FRP channel.
+ *
+ * - `public-ip-cert` (default): the VPS Caddy terminates TLS with a public-CA
+ *   certificate and reverse-proxies the plaintext vhost to frps.
+ * - `self-signed`: no Caddy and no public certificate at all. frps publishes a
+ *   raw TCP proxy and the DSH gateway terminates TLS itself with a leaf signed
+ *   by its own pairing CA, which the Android app pins through `ca.cer`.
+ */
+type FrpEntryTls = 'public-ip-cert' | 'self-signed';
+/** Optional overrides for the generated Caddy site; every field defaults to the upstream value. */
+interface CaddySiteOptions {
+  readonly certDir?: string;
+  /**
+   * The user's real `vhostHTTPPort`. `attach` mode must never assume the
+   * upstream 7080: a wrong port silently disables the plaintext-exposure gate.
+   */
+  readonly vhostHttpPort?: number;
+  /** `self-signed` is a TCP passthrough and never produces a Caddy site. */
+  readonly entryTls?: FrpEntryTls;
+}
+/**
+ * Build the Caddy site for one public host (without markers or import wiring).
+ *
+ * The second parameter accepts either a bare certificate directory (the legacy
+ * signature) or a full {@link CaddySiteOptions} object, so existing callers keep
+ * working unchanged.
+ */
+declare function createCaddySite(publicHost: string, options?: CaddySiteOptions | string): string;
+/**
+ * Build the only supported frps config and Caddy snippet from validated user inputs.
+ *
+ * Default `options` reproduce the upstream artefact byte for byte; `attach` mode
+ * passes the user's real vhost port, and `self-signed` is rejected because that
+ * mode publishes a raw TCP proxy instead of an HTTP vhost.
+ */
+declare function createRestrictedFrpServerTemplate(serverPort: number, token: string, publicOrigin: string, options?: CaddySiteOptions): string;
 //#endregion
 //#region src/frp-config.d.ts
+/** How the restricted FRP channel is provisioned on the VPS. */
+type FrpMode = 'deploy' | 'attach';
+/** Public entry port used by the self-signed TCP passthrough (never 443 by requirement). */
+declare const FRP_DEFAULT_PUBLIC_PORT = 33080;
+/** Ports owned by other DSH Mobile listeners; the public entry may never reuse them. */
+declare const FRP_RESERVED_PORTS: readonly number[];
 /** Credentials and endpoints required by the restricted FRP provider. */
 interface FrpSettings {
   readonly version: 1;
@@ -852,6 +898,17 @@ interface FrpSettings {
   readonly serverPort: number;
   readonly token: string;
   readonly publicOrigin: string;
+  /**
+   * `deploy` (default) installs the plugin's own frps on the VPS.
+   * `attach` reuses an frps that already runs there and never touches it.
+   */
+  readonly mode?: FrpMode;
+  /** `public-ip-cert` (default) or the gateway-terminated `self-signed` passthrough. */
+  readonly entryTls?: FrpEntryTls;
+  /** The real `vhostHTTPPort` of the user's frps; defaults to the upstream 7080. */
+  readonly vhostHttpPort?: number;
+  /** Public entry port of the self-signed TCP proxy; defaults to 33080. */
+  readonly publicPort?: number;
 }
 /** Safe FRP configuration fields returned to the desktop UI. */
 interface FrpConfigurationStatus {
@@ -862,6 +919,12 @@ interface FrpConfigurationStatus {
   readonly vhostHttpPort: number;
   readonly storagePath: string;
   readonly errorCode?: string;
+  /** Present only when the saved configuration leaves the upstream `deploy` default. */
+  readonly mode?: FrpMode;
+  /** Present only when the saved configuration uses the self-signed entry. */
+  readonly entryTls?: FrpEntryTls;
+  /** Present only when a non-default public entry port is saved. */
+  readonly publicPort?: number;
 }
 /** Validate the FRP server hostname or IP address. */
 declare function validateFrpServerAddress(value: unknown): string;
@@ -871,7 +934,34 @@ declare function validateFrpServerPort(value: unknown): number;
 declare function validateFrpToken(value: unknown): string;
 /** Validate the public HTTPS origin used by Caddy and Android pairing. */
 declare function validateFrpPublicOrigin(value: unknown): string;
-/** Parse FRP settings at the loopback request and filesystem boundaries. */
+/** Validate the provisioning mode. */
+declare function validateFrpMode(value: unknown): FrpMode;
+/** Validate the entry TLS mode. */
+declare function validateFrpEntryTls(value: unknown): FrpEntryTls;
+/** Validate the loopback vhost port of the target frps. */
+declare function validateFrpVhostHttpPort(value: unknown): number;
+/** Validate the public entry port of the self-signed TCP proxy. */
+declare function validateFrpPublicPort(value: unknown): number;
+/** Effective provisioning mode; an absent field keeps the upstream behaviour. */
+declare function resolveFrpMode(settings: FrpSettings): FrpMode;
+/** Effective entry TLS mode; an absent field keeps the upstream behaviour. */
+declare function resolveFrpEntryTls(settings: FrpSettings): FrpEntryTls;
+/** Effective loopback vhost port; an absent field keeps the upstream behaviour. */
+declare function resolveFrpVhostHttpPort(settings: FrpSettings): number;
+/** Effective public entry port of the self-signed passthrough. */
+declare function resolveFrpPublicPort(settings: FrpSettings): number;
+/** True when the gateway terminates TLS itself behind a raw frps TCP proxy. */
+declare function isFrpSelfSignedIngress(settings: FrpSettings): boolean;
+/**
+ * Parse FRP settings at the loopback request and filesystem boundaries.
+ *
+ * Optional keys are kept only when supplied, so a legacy `settings.json` still
+ * round-trips byte for byte and every default stays the upstream behaviour.
+ * Two cross-field rules are enforced here because neither can be recovered later:
+ * the self-signed entry is a TCP passthrough and therefore attach-only, and
+ * attach mode with a public-CA entry must state the user's real vhost port —
+ * silently assuming 7080 would disable the plaintext-exposure gate.
+ */
 declare function parseFrpSettings(value: unknown): FrpSettings;
 /**
  * Merge a partial VPS request body with the saved configuration so a blank
@@ -885,7 +975,13 @@ declare function mergeSavedFrpTarget(partial: Readonly<Record<string, unknown>>,
   readonly serverAddress: string;
   readonly serverPort: number;
 };
-/** Build the single-purpose frpc configuration for the current loopback gateway. */
+/**
+ * Build the single-purpose frpc configuration for the current loopback gateway.
+ *
+ * The default (public-CA) entry is an HTTP vhost behind Caddy and is emitted byte
+ * for byte as before. The self-signed entry cannot use a vhost at all: frps only
+ * forwards raw TCP, and the gateway terminates TLS on that connection.
+ */
 declare function createFrpcToml(settings: FrpSettings, localPort: number): string;
 /** Build the matching restricted frps and Caddy templates for one VPS. */
 declare function createFrpServerTemplate(settings: FrpSettings): string;
@@ -899,7 +995,13 @@ declare class FrpConfigStore {
   constructor(stateDirectory: string);
   /** Load private settings while rejecting links, oversized files, and unknown fields. */
   initialize(): Promise<void>;
-  /** Return configuration metadata without exposing the FRP token. */
+  /**
+   * Return configuration metadata without exposing the FRP token.
+   *
+   * The optional keys appear only when the saved configuration departs from the
+   * upstream defaults, so the pre-existing field set is unchanged for every
+   * legacy configuration.
+   */
   status(): FrpConfigurationStatus;
   /** Return private settings only to the provider lifecycle. */
   settings(): FrpSettings | undefined;
@@ -911,6 +1013,226 @@ declare class FrpConfigStore {
   purge(): Promise<FrpConfigurationStatus>;
 }
 //#endregion
+//#region src/frp-attach.d.ts
+/** Default proof path used to confirm the public entry answered from this computer. */
+declare const FRP_ATTACH_DISCOVERY_PATH = "/mobile-access/discovery";
+/** Declaration printed above the VPS half of an attach template. */
+declare const FRP_ATTACH_VPS_DECLARATION: string;
+/** Declaration printed above the local half of an attach template. */
+declare const FRP_ATTACH_LOCAL_DECLARATION = "# 本机只写入 frpc.toml 并启动 frpc：不安装、不改动本机 frps，也不改动 DSH 自身配置。";
+/** Declaration for the self-signed passthrough, which keeps its CA on this computer. */
+declare const FRP_ATTACH_SELF_SIGNED_DECLARATION: string;
+/** Optional inputs for attach artefacts; every field falls back to the validated settings. */
+interface FrpAttachOptions {
+  readonly vhostHttpPort?: number;
+  readonly publicPort?: number;
+  readonly certDir?: string;
+  /** Absolute path of the plugin-written frpc.toml, used for the `frpc verify` self-check. */
+  readonly configFile?: string;
+  /** Loopback port the gateway will listen on; only a placeholder inside the copied runbook. */
+  readonly localPort?: number;
+  /**
+   * Explicit reveal of the shared token inside previews and clipboard copies.
+   *
+   * Defaults to `false`: every artefact the panel produces on its own stays
+   * masked, because the copied text lands in the system clipboard. Only the
+   * panel's dedicated "copy the frpc.toml with its token" action sets this, and
+   * the result never reaches a stored state, a log, or localStorage.
+   */
+  readonly revealToken?: boolean;
+}
+/** The two separated halves of the attach artefact, plus their combined text. */
+interface FrpAttachTemplate {
+  readonly mode: 'attach';
+  readonly vps: string;
+  readonly local: string;
+  readonly text: string;
+}
+/**
+ * Reject every attach request that could not be carried out safely before any
+ * artefact is produced. Attach never installs frps, so it must know the user's
+ * real vhost port (unless the self-signed passthrough removes the vhost entirely).
+ */
+declare function validateAttachSettings(settings: FrpSettings, options?: FrpAttachOptions): void;
+/** Shared VPS-side inputs of both the copied runbook and the panel plan. */
+interface FrpAttachVpsParts {
+  readonly publicHost: string;
+  readonly selfSigned: boolean;
+  readonly vhostHttpPort?: number;
+  readonly publicPort?: number;
+  readonly snippet: string;
+  readonly certGuide: readonly string[];
+}
+/**
+ * Derive every VPS-side value once so the copied runbook and the panel plan can
+ * never drift apart.
+ */
+declare function frpAttachVpsParts(settings: FrpSettings, options?: FrpAttachOptions): FrpAttachVpsParts;
+/**
+ * Build the attach artefact for an existing frps.
+ *
+ * The result is deliberately split in two: the VPS half contains only what the
+ * user's own server needs (Caddy snippet + import + certificate guidance, or a
+ * single firewall rule for the self-signed passthrough), and the local half
+ * contains the generated frpc.toml plus its `frpc verify` self-check. Neither
+ * half installs, rewrites, or restarts the user's frps.
+ */
+declare function createFrpAttachTemplateParts(settings: FrpSettings, options?: FrpAttachOptions): FrpAttachTemplate;
+/** Combined attach artefact, ready for the clipboard. */
+declare function createFrpAttachTemplate(settings: FrpSettings, options?: FrpAttachOptions): string;
+//#endregion
+//#region src/frp-attach-plan.d.ts
+/** Stable step identifiers; the panel maps each one to a translated title. */
+type FrpAttachStepId = 'write-snippet' | 'add-import' | 'issue-ip-cert' | 'enable-cert-timer' | 'verify-https' | 'open-public-port' | 'verify-frps' | 'verify-entry';
+/** One actionable VPS-side step; `title` is a message key, `label` the copied text. */
+interface FrpAttachPlanStep {
+  readonly id: FrpAttachStepId;
+  readonly title: string;
+  readonly label: string;
+  readonly commands: readonly string[];
+  readonly optional: boolean;
+  readonly verifyHint: string;
+}
+/** The local half of the plan: the exact frpc.toml plus its self-check command. */
+interface FrpAttachPlanLocal {
+  /** The frpc.toml as previewed: masked unless the caller explicitly revealed the token. */
+  readonly frpcToml: string;
+  /** True when `frpcToml` carries the fixed placeholder instead of the shared token. */
+  readonly tokenMasked: boolean;
+  readonly verifyCommand: string;
+  readonly configFile: string;
+  readonly declaration: string;
+}
+/** Zero-SSH plan for attaching to an frps the user already runs. */
+interface FrpAttachPlan {
+  readonly mode: 'attach';
+  readonly entryTls: FrpEntryTls;
+  readonly vhostHttpPort?: number;
+  readonly publicPort?: number;
+  readonly local: FrpAttachPlanLocal;
+  readonly vps: readonly FrpAttachPlanStep[];
+  readonly warnings: readonly string[];
+}
+/**
+ * Build the copy-only attach plan. It performs no network access, no SSH, and no
+ * filesystem write: the caller renders or copies the steps and the local frpc
+ * configuration is written by the ordinary provider lifecycle.
+ */
+declare function createFrpAttachPlan(settings: FrpSettings, options?: FrpAttachOptions): FrpAttachPlan;
+//#endregion
+//#region src/cert-renewal.d.ts
+/** Days left below which the entry certificate is reported as expiring. */
+declare const CERT_EXPIRING_DAYS = 2;
+/** Read-only lifetime verdict for one certificate; never mutates or renews anything. */
+interface CertRenewalStatus {
+  readonly state: 'ok' | 'expiring' | 'expired' | 'unknown';
+  /** Unix milliseconds of `notAfter`. */
+  readonly notAfter?: number;
+  readonly daysRemaining?: number;
+  readonly subject?: string;
+  readonly issuer?: string;
+  readonly errorCode?: string;
+}
+/** Evaluate one `notAfter` timestamp against the current clock. */
+declare function evaluateCertificateLifetime(notAfter: number, now?: number): CertRenewalStatus;
+/**
+ * Read one PEM certificate from disk and report only its lifetime.
+ *
+ * A missing or unreadable file yields `unknown` with the stable
+ * `frp_attach_cert_unknown` code so the panel can explain how to re-issue it.
+ */
+declare function readCertificateRenewal(file: string, now?: number): Promise<CertRenewalStatus>;
+/**
+ * Ask a live TLS endpoint for its leaf certificate and report its lifetime.
+ *
+ * Verification is intentionally skipped: this is a read-only lifetime probe for
+ * an endpoint whose trust anchor is already pinned elsewhere, and a self-signed
+ * leaf is the expected answer for the passthrough entry.
+ */
+declare function probeOriginCertificate(host: string, port: number, timeoutMs?: number): Promise<CertRenewalStatus>;
+//#endregion
+//#region src/frp-ingress.d.ts
+/** Private files owned by the self-signed FRP ingress. */
+interface FrpIngressPaths {
+  readonly directory: string;
+  readonly caCertFile: string;
+  readonly caKeyFile: string;
+  readonly certFile: string;
+  readonly keyFile: string;
+  readonly statusFile: string;
+}
+/** Signed ingress material plus the fingerprint the app must pin. */
+interface FrpIngressCertificate {
+  readonly paths: FrpIngressPaths;
+  readonly ca: X509Certificate;
+  readonly leaf: X509Certificate;
+  readonly caFingerprint: string;
+  readonly status: CertRenewalStatus;
+}
+/** Everything the panel needs for the on-demand self-check. */
+interface FrpIngressSelfCheck {
+  readonly mode: 'deploy' | 'attach';
+  readonly entryTls: 'public-ip-cert' | 'self-signed';
+  readonly vhostHttpPort: number;
+  readonly publicPort: number;
+  readonly publicOrigin: string;
+  /** Reachable HTTPS entry; includes the TCP proxy port in self-signed mode. */
+  readonly entryOrigin: string;
+  readonly serverAddress: string;
+  readonly serverPort: number;
+  readonly caFingerprint?: string;
+  readonly certificate?: CertRenewalStatus;
+  readonly caCertificate?: CertRenewalStatus;
+  readonly inbound: {
+    readonly listenHost: '127.0.0.1';
+    readonly allowedCidrs: readonly string[];
+  };
+}
+/** Private ingress directory, always a sibling of the remote device file. */
+declare function frpIngressPaths(stateFile: string): FrpIngressPaths;
+/**
+ * Materialize the CA and leaf the gateway terminates TLS with.
+ *
+ * The CA remains stable for paired phones; an expired CA must be re-paired, not
+ * replaced silently. The leaf is re-signed when expiring or no longer valid for
+ * the public IPv4, and the running gateway reloads it after a renewal check.
+ */
+declare function ensureFrpIngressCertificate(settings: FrpSettings, stateFile: string, now?: number, expectedCaFingerprint?: string): Promise<FrpIngressCertificate>;
+/**
+ * Build the read-only self-check payload shown in the desktop panel.
+ *
+ * No secret ever leaves this function: the CA is reported by fingerprint only,
+ * and the token is never read.
+ */
+declare function frpIngressSelfCheck(settings: FrpSettings, stateFile: string): Promise<FrpIngressSelfCheck>;
+//#endregion
+//#region src/managed-setup.d.ts
+/** One host a server leaf must be valid for: an IP literal, a DNS name, or both. */
+interface ServerCertificateTarget {
+  readonly commonName: string;
+  readonly ipAddresses?: readonly string[];
+  readonly dnsNames?: readonly string[];
+}
+/** Where a freshly signed server leaf is installed. */
+interface ServerCertificateFiles {
+  readonly certFile: string;
+  readonly keyFile: string;
+}
+/** CA material a leaf is signed with. */
+interface ServerCertificateAuthority {
+  readonly caCertFile: string;
+  readonly caKeyFile: string;
+}
+/**
+ * Sign one server leaf with an existing self-signed CA and install it privately.
+ *
+ * Both the LAN listener and the self-signed FRP ingress use this one path, so a
+ * certificate can never be produced by two divergent code paths. IP entries are
+ * required for console addresses (`type: 7`), DNS entries (`type: 2`) cover named
+ * hosts; the Android client accepts either through its pinned CA.
+ */
+declare function issueServerCertificate(authority: ServerCertificateAuthority, target: ServerCertificateTarget, output: ServerCertificateFiles, lifetimeDays?: number): Promise<void>;
+//#endregion
 //#region src/remote.d.ts
 /** Remote transports supported by the desktop plugin and Android client. */
 type RemoteProvider = 'tailscale' | 'cpolar' | 'cloudflared' | 'frp' | 'origin';
@@ -963,18 +1285,59 @@ interface FrpStatus {
   readonly origin?: string;
   readonly errorCode?: string;
 }
+/**
+ * Explicit target of the start-up discovery self-check.
+ *
+ * The target is derived from the effective entry, never assumed: the public-CA
+ * entry answers on the saved origin (443 behind Caddy, publicly trusted chain),
+ * while the self-signed entry is a raw TCP passthrough on `publicPort` whose
+ * leaf chains to the plugin's own ingress CA.
+ */
+interface FrpDiscoveryProbeTarget {
+  /** Absolute HTTPS origin to dial, including the public entry port. */
+  readonly origin: string;
+  /**
+   * PEM bundle that anchors the entry leaf in place of the system trust store.
+   * Absent keeps the default chain, which is correct for a publicly trusted
+   * certificate; it is never a way to skip verification.
+   */
+  readonly trustAnchorPem?: string;
+}
 /** Inputs for one FRP client process and authenticated DSH gateway. */
 interface FrpControllerOptions {
   readonly store: MobileAccessControlStore;
   readonly executable: string;
   readonly config: FrpConfigStore;
+  /**
+   * Plugin-wide installation identity (the LAN pairing CA fingerprint).
+   *
+   * Retained for backward compatibility and constructor validation only. It no
+   * longer takes part in the start-up self-check: that check compares against the
+   * identity of the gateway this controller created and advertises, because the
+   * self-signed FRP ingress gateway is pinned to the ingress CA fingerprint by
+   * design, and that value deliberately differs from this one.
+   */
   readonly instanceId: string;
-  readonly createGateway: (origin: string) => Promise<MobileAccessGateway>;
+  readonly createGateway: (origin: string, settings: FrpSettings) => Promise<MobileAccessGateway>;
   readonly onStatus?: (status: FrpStatus) => void;
   readonly verifyConfig?: (executable: string, configFile: string) => Promise<void>;
   readonly launchClient?: (executable: string, configFile: string) => ChildProcessWithoutNullStreams;
   readonly probeVhostExposure?: (serverAddress: string, port: number) => Promise<boolean>;
-  readonly probeDiscovery?: (origin: string, expectedInstanceId: string, signal: AbortSignal) => Promise<boolean>;
+  readonly probeDiscovery?: (target: FrpDiscoveryProbeTarget, expectedInstanceId: string, signal: AbortSignal) => Promise<boolean>;
+  /**
+   * Resolve the CA the self-check must pin for the self-signed entry.
+   *
+   * Only the composing plugin knows where the ingress material lives, so the
+   * trust anchor is injected instead of guessed here. Consulted solely for the
+   * self-signed passthrough; the public-CA entry always keeps the system trust
+   * store. A configured resolver that cannot provide the CA fails startup with
+   * `frp_ingress_ca_invalid`; the system trust store must not mask that failure.
+   */
+  readonly resolveDiscoveryTrustAnchor?: (settings: FrpSettings) => Promise<string | undefined>;
+  /** Re-issue an expiring leaf and reload the live TLS listener without changing its CA. */
+  readonly maintainIngressCertificate?: (settings: FrpSettings, gateway: MobileAccessGateway) => Promise<void>;
+  /** Test seam for the maintenance timer; the product uses a twelve-hour interval. */
+  readonly ingressCertificateCheckMs?: number;
   readonly startTimeoutMs?: number;
   readonly retryIntervalMs?: number;
 }
@@ -990,6 +1353,7 @@ declare class FrpController implements RemoteProviderController {
   private latest;
   private queue;
   private startupAbort;
+  private ingressCertificateTimer;
   constructor(options: FrpControllerOptions);
   /** Restore the remembered FRP switch without changing LAN or other providers. */
   initialize(): Promise<void>;
@@ -1008,7 +1372,21 @@ declare class FrpController implements RemoteProviderController {
   private enqueue;
   private publish;
   private start;
+  /**
+   * Derive the self-check target and trust anchor for the effective entry.
+   *
+   * The public-CA entry is reached on the saved origin itself: Caddy terminates
+   * TLS on 443 with a publicly trusted certificate, so the probe must keep the
+   * system trust store and the origin URL untouched. The self-signed entry is a
+   * raw TCP passthrough on `publicPort` whose leaf chains to the ingress CA the
+   * app pins from `pairingCaFile`; probing `publicOrigin` there would knock on
+   * 443 — where nothing listens — with a chain the system cannot verify. Both
+   * facts used to be implicit, and together they kept the channel out of `ready`
+   * until `frp_start_timeout`.
+   */
+  private discoveryCheck;
   private waitForDiscovery;
+  private scheduleIngressCertificateCheck;
   private failGeneration;
   private stop;
   private stopProcessAndGateway;
@@ -1440,5 +1818,5 @@ declare function originGatewayConfig(template: ResolvedGatewayConfig, settings:
 /** Mount the resident control route and its optional authenticated LAN gateway. */
 declare function apply(ctx: Context, config: PluginConfig): Promise<void>;
 //#endregion
-export { AUTH_PREFIX, AccessController, type AccessControllerOptions, AccessError, type AuthoritySpec, type BlockedUpgradePathEntry, BlockedUpgradePathLog, BoundedRateLimiter, CLOUDFLARED_COMPONENT_RELEASE, CSRF_COOKIE, CSRF_HEADER, CloudflaredComponentManager, type CloudflaredComponentStatus, CloudflaredController, type CloudflaredControllerOptions, type CloudflaredState, type CloudflaredStatus, type CloudflaredTunnelMode, type CloudflaredTunnelSettings, type CloudflaredTunnelStatus, CloudflaredTunnelStore, Config, DEFAULT_ORIGIN_LISTEN_PORT, FRP_VHOST_HTTP_PORT as DEFAULT_VHOST_HTTP_PORT, FRP_VHOST_HTTP_PORT, DEVICE_COOKIE, type DeviceProbeResult, type DeviceSnapshot, type DeviceStore, type DeviceSummary, type DisabledTlsConfig, EXTENSION_LIMITS, FRP_CADDY_IMPORT_LINE, FRP_CADDY_SNIPPET_MARKER, FRP_CADDY_SNIPPET_PATH, FRP_COMPONENT_RELEASES, FrpComponentManager, type FrpComponentStatus, FrpConfigStore, type FrpConfigurationStatus, FrpController, type FrpControllerOptions, type FrpSettings, type FrpState, type FrpStatus, JsonDeviceStore, JsonMobileAccessControlStore, JsonRemoteProviderStore, LOCAL_ADMIN_PREFIX, type LocalExtensionManifest, MAX_BLOCKED_UPGRADE_PATHS, MAX_EXTRA_WEBSOCKET_PATHS, MAX_WEBSOCKET_PATH_LENGTH, MemoryDeviceStore, type MobileAccessControlState, type MobileAccessControlStore, MobileAccessGateway, MobileAccessGatewayController, type MobileAccessService as MobileAccessRegistry, MobileAccessService, type MobileAccessRuntime, type MobileActionContext, type MobileExtensionClientEntry, type MobileExtensionDefinition, MobileExtensionError, type MobileExtensionManifest, type MobileExtensionStatus, type MobileHostAction, type MobileHostRoute, type MobileRouteRequest, type MobileRouteResponse, OriginConfigStore, type OriginConfigurationStatus, OriginController, type OriginControllerOptions, type OriginSettings, type OriginState, type OriginStatus, type PairingResult, type ParsedCidr, type PluginConfig, type ProvidedTlsConfig, REMOTE_PROVIDERS, type RemoteProvider, type RemoteProviderController, type RemoteProviderState, type RemoteProviderStatus, type RenewalResult, RequestTrustPolicy, type ResolvedGatewayConfig, SESSION_COOKIE, type SessionAuthorization, type SessionEndReason, type StoredDevice, TASK_EVENT_DEBOUNCE_MS, type TaskCompletionEvent, type TaskEventContext, TaskEventHub, type TaskEventSession, type TaskEventSink, type TaskEventWatcherOptions, type TaskTurnEvent, type TlsConfig, WS_PATHS, WebSocketPathStore, addressAllowed, apply, assertExtensionId, configuredRemoteProvider, createCaddySite, createFrpServerTemplate, createFrpcToml, createMobileAccessService, createRestrictedFrpServerTemplate, inject, isCloudflaredRegistration, isGloballyRoutableIpv4, isLoopbackAddress, mergeSavedCloudflaredTunnelSettings, mergeSavedFrpSettings, mergeSavedFrpTarget, name, normalizeWebSocketPaths, originGatewayConfig, parseAuthority, parseCidr, parseCloudflaredOrigin, parseCloudflaredTunnelSettings, parseControlFile, parseDeviceSnapshot, parseExtensionManifest, parseFrpSettings, parseGatewayConfig, parseMobileAccessControlState, parseOriginSettings, parseRemoteProviderState, resolveAuthority, rewriteMobileIndex, validateCloudflaredTunnelHostname, validateCloudflaredTunnelPort, validateCloudflaredTunnelToken, validateFrpPublicOrigin, validateFrpServerAddress, validateFrpServerPort, validateFrpToken, validateOriginAllowedCidrs, validateOriginListenHost, validateOriginListenPort, validateOriginPublicOrigin, validateWebSocketPath, watchTaskCompletions };
+export { AUTH_PREFIX, AccessController, type AccessControllerOptions, AccessError, type AuthoritySpec, type BlockedUpgradePathEntry, BlockedUpgradePathLog, BoundedRateLimiter, CERT_EXPIRING_DAYS, CLOUDFLARED_COMPONENT_RELEASE, CSRF_COOKIE, CSRF_HEADER, type CaddySiteOptions, type CertRenewalStatus, CloudflaredComponentManager, type CloudflaredComponentStatus, CloudflaredController, type CloudflaredControllerOptions, type CloudflaredState, type CloudflaredStatus, type CloudflaredTunnelMode, type CloudflaredTunnelSettings, type CloudflaredTunnelStatus, CloudflaredTunnelStore, Config, DEFAULT_ORIGIN_LISTEN_PORT, FRP_VHOST_HTTP_PORT as DEFAULT_VHOST_HTTP_PORT, FRP_VHOST_HTTP_PORT, DEVICE_COOKIE, type DeviceProbeResult, type DeviceSnapshot, type DeviceStore, type DeviceSummary, type DisabledTlsConfig, EXTENSION_LIMITS, FRP_ATTACH_DISCOVERY_PATH, FRP_ATTACH_LOCAL_DECLARATION, FRP_ATTACH_SELF_SIGNED_DECLARATION, FRP_ATTACH_VPS_DECLARATION, FRP_CADDY_IMPORT_LINE, FRP_CADDY_SNIPPET_MARKER, FRP_CADDY_SNIPPET_PATH, FRP_COMPONENT_RELEASES, FRP_DEFAULT_PUBLIC_PORT, FRP_RESERVED_PORTS, type FrpAttachOptions, type FrpAttachPlan, type FrpAttachPlanLocal, type FrpAttachPlanStep, type FrpAttachStepId, type FrpAttachTemplate, type FrpAttachVpsParts, FrpComponentManager, type FrpComponentStatus, FrpConfigStore, type FrpConfigurationStatus, FrpController, type FrpControllerOptions, type FrpEntryTls, type FrpIngressCertificate, type FrpIngressPaths, type FrpIngressSelfCheck, type FrpSettings, type FrpState, type FrpStatus, JsonDeviceStore, JsonMobileAccessControlStore, JsonRemoteProviderStore, LOCAL_ADMIN_PREFIX, type LocalExtensionManifest, MAX_BLOCKED_UPGRADE_PATHS, MAX_EXTRA_WEBSOCKET_PATHS, MAX_WEBSOCKET_PATH_LENGTH, MemoryDeviceStore, type MobileAccessControlState, type MobileAccessControlStore, MobileAccessGateway, MobileAccessGatewayController, type MobileAccessService as MobileAccessRegistry, MobileAccessService, type MobileAccessRuntime, type MobileActionContext, type MobileExtensionClientEntry, type MobileExtensionDefinition, MobileExtensionError, type MobileExtensionManifest, type MobileExtensionStatus, type MobileHostAction, type MobileHostRoute, type MobileRouteRequest, type MobileRouteResponse, OriginConfigStore, type OriginConfigurationStatus, OriginController, type OriginControllerOptions, type OriginSettings, type OriginState, type OriginStatus, type PairingResult, type ParsedCidr, type PluginConfig, type ProvidedTlsConfig, REMOTE_PROVIDERS, type RemoteProvider, type RemoteProviderController, type RemoteProviderState, type RemoteProviderStatus, type RenewalResult, RequestTrustPolicy, type ResolvedGatewayConfig, SESSION_COOKIE, type ServerCertificateAuthority, type ServerCertificateFiles, type ServerCertificateTarget, type SessionAuthorization, type SessionEndReason, type StoredDevice, TASK_EVENT_DEBOUNCE_MS, type TaskCompletionEvent, type TaskEventContext, TaskEventHub, type TaskEventSession, type TaskEventSink, type TaskEventWatcherOptions, type TaskTurnEvent, type TlsConfig, WS_PATHS, WebSocketPathStore, addressAllowed, apply, assertExtensionId, configuredRemoteProvider, createCaddySite, createFrpAttachPlan, createFrpAttachTemplate, createFrpAttachTemplateParts, createFrpServerTemplate, createFrpcToml, createMobileAccessService, createRestrictedFrpServerTemplate, ensureFrpIngressCertificate, evaluateCertificateLifetime, frpAttachVpsParts, frpIngressPaths, frpIngressSelfCheck, inject, isCloudflaredRegistration, isFrpSelfSignedIngress, isGloballyRoutableIpv4, isLoopbackAddress, issueServerCertificate, mergeSavedCloudflaredTunnelSettings, mergeSavedFrpSettings, mergeSavedFrpTarget, name, normalizeWebSocketPaths, originGatewayConfig, parseAuthority, parseCidr, parseCloudflaredOrigin, parseCloudflaredTunnelSettings, parseControlFile, parseDeviceSnapshot, parseExtensionManifest, parseFrpSettings, parseGatewayConfig, parseMobileAccessControlState, parseOriginSettings, parseRemoteProviderState, probeOriginCertificate, readCertificateRenewal, resolveAuthority, resolveFrpEntryTls, resolveFrpMode, resolveFrpPublicPort, resolveFrpVhostHttpPort, rewriteMobileIndex, validateAttachSettings, validateCloudflaredTunnelHostname, validateCloudflaredTunnelPort, validateCloudflaredTunnelToken, validateFrpEntryTls, validateFrpMode, validateFrpPublicOrigin, validateFrpPublicPort, validateFrpServerAddress, validateFrpServerPort, validateFrpToken, validateFrpVhostHttpPort, validateOriginAllowedCidrs, validateOriginListenHost, validateOriginListenPort, validateOriginPublicOrigin, validateWebSocketPath, watchTaskCompletions };
 //# sourceMappingURL=index.d.mts.map