@viaalink/caddy-api-client 0.0.0-stage → 0.10.0

package/dist/index-BmimANG7.d.ts

@@ -0,0 +1,1920 @@
+import { a6 as CaddyClient } from './client-Bf2QoSWQ.js';
+import { Q as ServiceRouteOptions$1, k as CaddyRoute, l as HealthCheckRouteOptions, m as HostRouteOptions, P as PathRouteOptions, W as LoadBalancerRouteOptions$1, X as DialAddress, j as CaddyRouteHandler, Y as SecurityHeaders, Z as BasicAuthOptions, _ as AddDomainWithAutoTlsOptions, $ as DomainConfig, a0 as AddDomainWithTlsOptions, a1 as UpdateDomainOptions, a2 as DeleteDomainOptions, a3 as Domain, T as TlsConnectionPolicy } from './types-DIjkvykh.js';
+import { a7 as Config, O as InternalIssuer, z as AutomationPolicy, d as AutoHTTPSConfig } from './caddy-http-DLxwstYo.js';
+
+/**
+ * Route builder functions for Caddy
+ */
+
+/**
+ * Build routes for a service (host-based and/or path-based)
+ * @param options - Service route options
+ * @returns Array of Caddy routes
+ * @throws {ValidationError} If options fail validation (e.g., invalid dial address)
+ */
+declare function buildServiceRoutes(options: ServiceRouteOptions$1): CaddyRoute[];
+/**
+ * Build a health check route
+ * @param options - Health check route options
+ * @returns Caddy route for health check
+ * @throws {ValidationError} If options fail validation
+ */
+declare function buildHealthCheckRoute(options: HealthCheckRouteOptions): CaddyRoute;
+/**
+ * Build a host-based route
+ * @param options - Host route options
+ * @returns Caddy route
+ * @throws {ValidationError} If options fail validation (e.g., invalid dial address)
+ */
+declare function buildHostRoute(options: HostRouteOptions): CaddyRoute;
+/**
+ * Build a path-based route
+ * @param options - Path route options
+ * @returns Caddy route
+ * @throws {ValidationError} If options fail validation (e.g., invalid dial address)
+ */
+declare function buildPathRoute(options: PathRouteOptions): CaddyRoute;
+/**
+ * Build a load balancer route
+ * @param options - Load balancer options
+ * @returns Caddy route with load balancing
+ * @throws {ValidationError} If options fail validation (e.g., invalid upstreams)
+ */
+declare function buildLoadBalancerRoute(options: LoadBalancerRouteOptions$1): CaddyRoute;
+/**
+ * Build a reverse proxy handler
+ * @param dial - Dial address (host:port or https://host:port)
+ * @param options - Optional transport configuration
+ * @returns Reverse proxy handler
+ *
+ * @example
+ * // HTTP backend (default)
+ * buildReverseProxyHandler("nginx:80")
+ *
+ * @example
+ * // HTTPS backend with TLS
+ * buildReverseProxyHandler("https://internal-service:443")
+ *
+ * @example
+ * // HTTPS backend with custom TLS settings
+ * buildReverseProxyHandler("internal-service:443", {
+ *   tls: true,
+ *   tlsServerName: "internal.example.com",
+ *   tlsInsecureSkipVerify: false
+ * })
+ */
+declare function buildReverseProxyHandler(dial: DialAddress, options?: {
+    tls?: boolean;
+    tlsServerName?: string;
+    tlsInsecureSkipVerify?: boolean;
+    tlsTrustedCACerts?: string;
+    /** Response headers to delete (e.g., ["Content-Security-Policy"]) */
+    deleteResponseHeaders?: string[];
+    /** Flush interval for streaming/WebSocket. -1 disables buffering. */
+    flushInterval?: number;
+}): CaddyRouteHandler;
+/**
+ * Build a security headers handler
+ * @param headers - Security headers configuration
+ * @returns Headers handler
+ */
+declare function buildSecurityHeadersHandler(headers: SecurityHeaders): CaddyRouteHandler;
+/**
+ * Build a basic auth handler
+ * Supports both single account (legacy) and multiple accounts
+ *
+ * @param auth - Basic auth configuration
+ * @returns Basic auth handler
+ * @throws {Error} If no valid accounts are provided (username + passwordHash or accounts array required)
+ *
+ * @example
+ * // Single account (legacy)
+ * buildBasicAuthHandler({
+ *   enabled: true,
+ *   username: "admin",
+ *   passwordHash: "$2a$10$...",
+ *   realm: "Admin Area"
+ * })
+ *
+ * @example
+ * // Multiple accounts (recommended)
+ * buildBasicAuthHandler({
+ *   enabled: true,
+ *   accounts: [
+ *     { username: "admin", password: "$2a$10$..." },
+ *     { username: "user", password: "$2a$10$..." }
+ *   ],
+ *   realm: "Protected Area",
+ *   hash: { algorithm: "bcrypt", cost: 10 }
+ * })
+ */
+declare function buildBasicAuthHandler(auth: BasicAuthOptions): CaddyRouteHandler;
+/**
+ * Build a rewrite handler (strip path prefix)
+ * @param prefix - Path prefix to strip
+ * @returns Rewrite handler
+ */
+declare function buildRewriteHandler(prefix: string): CaddyRouteHandler;
+/**
+ * Build an ingress tag header handler
+ * @param tag - Ingress tag value
+ * @returns Headers handler
+ */
+declare function buildIngressTagHeadersHandler(tag: string): CaddyRouteHandler;
+/**
+ * Build a project identity header handler
+ * @param projectId - Project identifier value
+ * @returns Headers handler
+ */
+declare function buildProjectIdHeadersHandler(projectId: string): CaddyRouteHandler;
+/**
+ * Build CORS/CSP headers for iframe embedding
+ *
+ * `allowedOrigin` is a CSP `frame-ancestors` source list: one source or
+ * several, space-separated, wildcards allowed. CORS headers are added only
+ * when it is `*` or one exact origin, because `Access-Control-Allow-Origin`
+ * takes nothing else; a list there is invalid, and a browser rejects it.
+ * @param allowedOrigin - Allowed origin or frame-ancestors source list (optional, defaults to "*")
+ * @returns Headers handler
+ */
+declare function buildIframeHeadersHandler(allowedOrigin?: string): CaddyRouteHandler;
+/**
+ * Build a redirect route for domain redirects (www <-> non-www)
+ * @param options - Redirect configuration
+ * @returns Caddy route for redirect
+ */
+declare function buildRedirectRoute(options: {
+    fromHost: string;
+    toHost: string;
+    permanent?: boolean;
+    statusCode?: 301 | 302 | 307 | 308;
+    id?: string;
+}): CaddyRoute;
+/**
+ * Build a compression (encode) handler
+ * Supports gzip, zstd, and brotli compression
+ * @param options - Compression options
+ * @returns Encode handler
+ */
+declare function buildCompressionHandler(options?: {
+    gzip?: boolean;
+    zstd?: boolean;
+    brotli?: boolean;
+}): CaddyRouteHandler;
+/**
+ * Build a WWW redirect route (www.example.com ↔ example.com)
+ *
+ * Common patterns:
+ * - "www-to-domain": www.example.com → example.com
+ * - "domain-to-www": example.com → www.example.com
+ *
+ * @param options - WWW redirect options
+ * @returns Caddy route that redirects between www and non-www versions
+ *
+ * @example
+ * // Redirect www.example.com → example.com
+ * const route = buildWwwRedirect({
+ *   domain: "example.com",
+ *   mode: "www-to-domain",
+ *   permanent: true
+ * });
+ *
+ * @example
+ * // Redirect example.com → www.example.com
+ * const route = buildWwwRedirect({
+ *   domain: "example.com",
+ *   mode: "domain-to-www",
+ *   permanent: true
+ * });
+ */
+declare function buildWwwRedirect(options: {
+    domain: string;
+    mode: "www-to-domain" | "domain-to-www";
+    permanent?: boolean;
+    priority?: number;
+}): CaddyRoute;
+/**
+ * Build a route that forwards traffic through MITMproxy for inspection
+ *
+ * This is a convenience function that creates a route pointing to a MITMproxy
+ * instance running in reverse proxy mode. Use this to transparently intercept
+ * and inspect HTTP traffic for debugging without modifying client or backend code.
+ *
+ * @param options - MITMproxy route configuration
+ * @returns Caddy route configured to forward through MITMproxy
+ *
+ * @example
+ * ```typescript
+ * // Route traffic for api.example.com through MITMproxy
+ * const route = buildMitmproxyRoute({
+ *   host: "api.example.com",
+ *   mitmproxyHost: "localhost",
+ *   mitmproxyPort: 8080,
+ * });
+ * await client.addRoute("https_server", route, "api_debug");
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Route with custom backend (MITMproxy forwards to this backend)
+ * const route = buildMitmproxyRoute({
+ *   host: "api.example.com",
+ *   mitmproxyHost: "mitmproxy",
+ *   mitmproxyPort: 8080,
+ *   backendHost: "backend-service",
+ *   backendPort: 3000,
+ * });
+ * ```
+ */
+declare function buildMitmproxyRoute(options: {
+    /** Host pattern to match (e.g., "api.example.com") */
+    host: string;
+    /** MITMproxy host (e.g., "localhost" or "mitmproxy-container") */
+    mitmproxyHost: string;
+    /** MITMproxy proxy port (default: 8080) */
+    mitmproxyPort?: number;
+    /** Backend host that MITMproxy should forward to (optional, for documentation) */
+    backendHost?: string;
+    /** Backend port that MITMproxy should forward to (optional, for documentation) */
+    backendPort?: number;
+    /** Route ID for Caddy (optional) */
+    id?: string;
+    /** Route priority (optional) */
+    priority?: number;
+}): CaddyRoute;
+/**
+ * Create a hot-swappable route pair for enabling/disabling MITMproxy interception
+ *
+ * Returns both a direct route and a MITMproxy-intercepted route with the same ID.
+ * Use this to easily toggle between direct and intercepted traffic at runtime.
+ *
+ * @param options - Configuration for the route pair
+ * @returns Object with direct and proxied route configurations
+ *
+ * @example
+ * ```typescript
+ * const routes = buildMitmproxyRoutePair({
+ *   host: "api.example.com",
+ *   backendHost: "backend-service",
+ *   backendPort: 3000,
+ *   mitmproxyHost: "mitmproxy",
+ *   routeId: "api_route",
+ * });
+ *
+ * // Start with direct routing
+ * await client.addRoute("https_server", routes.direct, routes.direct["@id"]);
+ *
+ * // Hot-swap to enable interception (no downtime)
+ * await client.removeRouteById("https_server", routes.direct["@id"]);
+ * await client.addRoute("https_server", routes.proxied, routes.proxied["@id"]);
+ *
+ * // Hot-swap back to direct (disable interception)
+ * await client.removeRouteById("https_server", routes.proxied["@id"]);
+ * await client.addRoute("https_server", routes.direct, routes.direct["@id"]);
+ * ```
+ */
+declare function buildMitmproxyRoutePair(options: {
+    /** Host pattern to match */
+    host: string;
+    /** Backend service host */
+    backendHost: string;
+    /** Backend service port */
+    backendPort: number;
+    /** MITMproxy host */
+    mitmproxyHost: string;
+    /** MITMproxy proxy port (default: 8080) */
+    mitmproxyPort?: number;
+    /** Route ID (used for both routes) */
+    routeId: string;
+    /** Route priority (optional) */
+    priority?: number;
+}): {
+    /** Direct route (Client → Caddy → Backend) */
+    direct: CaddyRoute;
+    /** Proxied route (Client → Caddy → MITMproxy → Backend) */
+    proxied: CaddyRoute;
+};
+/**
+ * Options for building an iframe-embeddable proxy route
+ */
+interface IframeProxyRouteOptions {
+    /** Path prefix for the route (e.g., "/panel") */
+    pathPrefix: string;
+    /** Upstream host to proxy to */
+    upstreamHost: string;
+    /** Upstream port to proxy to */
+    upstreamPort: number;
+    /** Route ID (optional, auto-generated from pathPrefix if not provided) */
+    routeId?: string;
+    /** Whether to enable iframe embedding headers (default: true) */
+    iframeEmbed?: boolean;
+    /** Custom Host header to send to upstream (for DNS rebinding bypass) */
+    overrideHost?: string;
+}
+/**
+ * Build a route for proxying a web UI with iframe embedding support
+ *
+ * This creates a route that proxies a web interface and optionally adds
+ * headers to allow embedding in iframes. Can also override Host/Origin
+ * headers for services with DNS rebinding protection.
+ *
+ * @param options - Iframe proxy route configuration
+ * @returns Caddy route for iframe-embeddable proxy
+ *
+ * @example
+ * ```typescript
+ * // Proxy a web panel at /panel/* to panel-service:8080
+ * const route = buildIframeProxyRoute({
+ *   pathPrefix: "/panel",
+ *   upstreamHost: "panel-service",
+ *   upstreamPort: 8080,
+ *   iframeEmbed: true,
+ * });
+ *
+ * // Proxy with DNS rebinding bypass (e.g., for mitmweb)
+ * const mitmRoute = buildIframeProxyRoute({
+ *   pathPrefix: "/mitmproxy",
+ *   upstreamHost: "mitmproxy",
+ *   upstreamPort: 8081,
+ *   overrideHost: "127.0.0.1:8081",
+ * });
+ * ```
+ */
+declare function buildIframeProxyRoute(options: IframeProxyRouteOptions): CaddyRoute;
+/**
+ * @deprecated Use buildIframeProxyRoute instead
+ */
+declare function buildMitmproxyWebUiRoute(options: {
+    pathPrefix: string;
+    mitmproxyHost: string;
+    mitmproxyWebPort?: number;
+    routeId?: string;
+    iframeEmbed?: boolean;
+}): CaddyRoute;
+/**
+ * Options for building a WebSocket proxy route
+ */
+interface WebSocketProxyRouteOptions {
+    /** WebSocket path to match (e.g., "/ws", "/updates") */
+    path: string;
+    /** Upstream host to proxy to */
+    upstreamHost: string;
+    /** Upstream port to proxy to */
+    upstreamPort: number;
+    /** Route ID (optional) */
+    routeId?: string;
+    /** Custom Host header to send to upstream (for DNS rebinding bypass) */
+    overrideHost?: string;
+}
+/**
+ * Build a route for WebSocket proxy
+ *
+ * This creates a route that proxies WebSocket connections to an upstream
+ * service. Can optionally override Host/Origin headers for services
+ * with DNS rebinding protection.
+ *
+ * @param options - WebSocket route configuration
+ * @returns Caddy route for WebSocket proxy
+ *
+ * @example
+ * ```typescript
+ * // Simple WebSocket proxy
+ * const route = buildWebSocketProxyRoute({
+ *   path: "/ws",
+ *   upstreamHost: "ws-server",
+ *   upstreamPort: 8080,
+ * });
+ *
+ * // WebSocket with DNS rebinding bypass
+ * const mitmRoute = buildWebSocketProxyRoute({
+ *   path: "/updates",
+ *   upstreamHost: "mitmproxy",
+ *   upstreamPort: 8081,
+ *   overrideHost: "127.0.0.1:8081",
+ * });
+ * ```
+ */
+declare function buildWebSocketProxyRoute(options: WebSocketProxyRouteOptions): CaddyRoute;
+/**
+ * @deprecated Use buildWebSocketProxyRoute instead
+ */
+declare function buildMitmproxyWebSocketRoute(options: {
+    path?: string;
+    mitmproxyHost: string;
+    mitmproxyWebPort?: number;
+    routeId?: string;
+}): CaddyRoute;
+/**
+ * Build a header handler that removes restrictive headers for iframe embedding
+ *
+ * Removes X-Frame-Options, Content-Security-Policy, and X-Xss-Protection
+ * headers while adding permissive CORS and frame-ancestors headers.
+ *
+ * @param options - Handler options
+ * @returns Headers handler for iframe embedding
+ *
+ * @example
+ * ```typescript
+ * const handler = buildIframePermissiveHandler();
+ * // Use in a route's handle array
+ * ```
+ */
+declare function buildIframePermissiveHandler(options?: {
+    /** Headers to delete (default: ["X-Frame-Options", "Content-Security-Policy", "X-Xss-Protection"]) */
+    deleteHeaders?: string[];
+    /** CORS origin (default: "*") */
+    corsOrigin?: string;
+}): CaddyRouteHandler;
+/**
+ * Build a header handler for DNS rebinding bypass
+ *
+ * Sets Host and Origin headers to bypass MITMproxy's DNS rebinding protection.
+ * Use this when proxying to MITMproxy from a different hostname.
+ *
+ * @param options - Handler options
+ * @returns Headers handler for request modification
+ *
+ * @example
+ * ```typescript
+ * const handler = buildDnsRebindingBypassHandler({
+ *   targetHost: "127.0.0.1:8081",
+ * });
+ * ```
+ */
+declare function buildDnsRebindingBypassHandler(options: {
+    /** Target host:port (e.g., "127.0.0.1:8081") */
+    targetHost: string;
+}): CaddyRouteHandler;
+/**
+ * Options for building a file server route
+ */
+interface FileServerRouteOptions {
+    /** Path prefix to match (e.g., "/static/*") */
+    path: string;
+    /** Root directory to serve files from */
+    root: string;
+    /** Enable directory browsing */
+    browse?: boolean;
+    /** Custom browse template file path */
+    browseTemplate?: string;
+    /** File patterns to hide (e.g., [".git", ".env"]) */
+    hidePatterns?: string[];
+    /** Index file names (default: ["index.html"]) */
+    indexNames?: string[];
+    /** Enable precompressed file support (gzip, brotli) */
+    precompressed?: boolean;
+    /** Route ID */
+    id?: string;
+    /** Route priority */
+    priority?: number;
+}
+/**
+ * Build a file server route for serving static files
+ *
+ * @param options - File server route configuration
+ * @returns Caddy route for static file serving
+ *
+ * @example
+ * ```typescript
+ * // Basic static file serving
+ * const route = buildFileServerRoute({
+ *   path: "/static/*",
+ *   root: "/var/www/static",
+ * });
+ *
+ * // With directory browsing and hidden files
+ * const route = buildFileServerRoute({
+ *   path: "/files/*",
+ *   root: "/var/www/files",
+ *   browse: true,
+ *   hidePatterns: [".git", ".env", "*.secret"],
+ *   precompressed: true,
+ * });
+ * ```
+ */
+declare function buildFileServerRoute(options: FileServerRouteOptions): CaddyRoute;
+/**
+ * Options for building a templates route
+ */
+interface TemplatesRouteOptions {
+    /** Path prefix to match (e.g., "/*.html") */
+    path: string;
+    /** Root directory for template files */
+    fileRoot: string;
+    /** MIME types to process as templates */
+    mimeTypes?: string[];
+    /** Custom delimiters (default: ["{{", "}}"]) */
+    delimiters?: [string, string];
+    /** Route ID */
+    id?: string;
+    /** Route priority */
+    priority?: number;
+}
+/**
+ * Build a templates route for server-side template rendering
+ *
+ * @param options - Templates route configuration
+ * @returns Caddy route for template processing
+ *
+ * @example
+ * ```typescript
+ * // Process HTML files as templates
+ * const route = buildTemplatesRoute({
+ *   path: "/*.html",
+ *   fileRoot: "/var/www/templates",
+ *   mimeTypes: ["text/html"],
+ * });
+ *
+ * // With custom delimiters
+ * const route = buildTemplatesRoute({
+ *   path: "/*.tmpl",
+ *   fileRoot: "/templates",
+ *   delimiters: ["<%", "%>"],
+ * });
+ * ```
+ */
+declare function buildTemplatesRoute(options: TemplatesRouteOptions): CaddyRoute;
+/**
+ * Options for building an error route
+ */
+interface ErrorRouteOptions {
+    /** Route matchers (optional, applies to all requests if not specified) */
+    match?: {
+        path?: string[];
+        host?: string[];
+    };
+    /** HTTP status code */
+    statusCode: number;
+    /** Error message body */
+    message?: string;
+    /** Custom headers to include */
+    headers?: Record<string, string[]>;
+    /** Route ID */
+    id?: string;
+    /** Route priority */
+    priority?: number;
+}
+/**
+ * Build an error route that returns a static error response
+ *
+ * @param options - Error route configuration
+ * @returns Caddy route for error response
+ *
+ * @example
+ * ```typescript
+ * // Simple 404 handler
+ * const route = buildErrorRoute({
+ *   statusCode: 404,
+ *   message: "Page not found",
+ * });
+ *
+ * // JSON error response for API
+ * const route = buildErrorRoute({
+ *   match: { path: ["/api/*"] },
+ *   statusCode: 500,
+ *   message: '{"error":"Internal server error"}',
+ *   headers: { "Content-Type": ["application/json"] },
+ * });
+ * ```
+ */
+declare function buildErrorRoute(options: ErrorRouteOptions): CaddyRoute;
+/**
+ * Options for building a request body handler
+ */
+interface RequestBodyHandlerOptions {
+    /** Maximum request body size in bytes */
+    maxSize: number;
+}
+/**
+ * Build a request body handler for limiting request body size
+ *
+ * @param options - Request body handler configuration
+ * @returns Request body handler
+ *
+ * @example
+ * ```typescript
+ * // Limit request body to 10MB
+ * const handler = buildRequestBodyHandler({ maxSize: 10 * 1024 * 1024 });
+ * ```
+ */
+declare function buildRequestBodyHandler(options: RequestBodyHandlerOptions): CaddyRouteHandler;
+/**
+ * Options for building a vars handler
+ */
+interface VarsHandlerOptions {
+    /** Variables to set (key-value pairs) */
+    vars: Record<string, string>;
+}
+/**
+ * Build a vars handler for setting request variables
+ *
+ * @param options - Vars handler configuration
+ * @returns Vars handler
+ *
+ * @example
+ * ```typescript
+ * // Set custom variables for downstream handlers
+ * const handler = buildVarsHandler({
+ *   vars: {
+ *     root: "/var/www",
+ *     backend: "api-server",
+ *     environment: "production",
+ *   }
+ * });
+ * ```
+ */
+declare function buildVarsHandler(options: VarsHandlerOptions): CaddyRouteHandler;
+/**
+ * Options for building a tracing handler
+ */
+interface TracingHandlerOptions {
+    /** Span name for tracing */
+    span?: string;
+}
+/**
+ * Build a tracing handler for distributed tracing
+ *
+ * @param options - Tracing handler configuration
+ * @returns Tracing handler
+ *
+ * @example
+ * ```typescript
+ * const handler = buildTracingHandler({ span: "http.request" });
+ * ```
+ */
+declare function buildTracingHandler(options?: TracingHandlerOptions): CaddyRouteHandler;
+/**
+ * Options for building a map handler
+ */
+interface MapHandlerOptions {
+    /** Source placeholder (e.g., "{http.request.uri.path}") */
+    source: string;
+    /** Destination placeholder names (e.g., ["{my_var}"]) */
+    destinations: string[];
+    /** Mappings from input patterns to outputs */
+    mappings: {
+        input: string;
+        outputs: string[];
+    }[];
+    /** Default outputs if no mappings match */
+    defaults?: string[];
+}
+/**
+ * Build a map handler for variable mapping
+ *
+ * @param options - Map handler configuration
+ * @returns Map handler
+ *
+ * @example
+ * ```typescript
+ * // Map request paths to backend names
+ * const handler = buildMapHandler({
+ *   source: "{http.request.uri.path}",
+ *   destinations: ["{backend}"],
+ *   mappings: [
+ *     { input: "/api/*", outputs: ["api-server"] },
+ *     { input: "/admin/*", outputs: ["admin-server"] },
+ *   ],
+ *   defaults: ["default-server"],
+ * });
+ * ```
+ */
+declare function buildMapHandler(options: MapHandlerOptions): CaddyRouteHandler;
+
+/**
+ * Valid Caddy configuration adapters
+ */
+type CaddyAdapter = "caddyfile" | "json" | "yaml" | "nginx" | "apache";
+/**
+ * Options for loading configuration files
+ */
+interface LoadConfigOptions {
+    /** Caddy Admin API URL (default: http://127.0.0.1:2019) */
+    adminUrl?: string;
+    /** Request timeout in milliseconds (default: 5000) */
+    timeout?: number;
+}
+/**
+ * Detect the appropriate adapter based on file extension
+ *
+ * @param path - Path to the configuration file
+ * @returns The detected adapter type
+ *
+ * @example
+ * ```typescript
+ * detectAdapter("./config.json");     // "json"
+ * detectAdapter("./config.yaml");     // "yaml"
+ * detectAdapter("./Caddyfile");       // "caddyfile"
+ * detectAdapter("./unknown.txt");     // "caddyfile" (default)
+ * ```
+ */
+declare function detectAdapter(path: string): CaddyAdapter;
+/**
+ * Load a configuration file and convert it to Caddy JSON format
+ *
+ * Reads the file from disk, auto-detects the format (or uses the provided adapter),
+ * and uses Caddy's /adapt endpoint to convert it to JSON configuration.
+ *
+ * @param path - Path to the configuration file
+ * @param adapter - Adapter to use (auto-detected from extension if not provided)
+ * @param options - Loading options (adminUrl, timeout)
+ * @returns The parsed Caddy configuration object
+ *
+ * @throws {ValidationError} If the file content is empty or invalid
+ * @throws {CaddyApiError} If Caddy cannot parse the configuration
+ * @throws {NetworkError} If unable to connect to Caddy Admin API
+ * @throws {TimeoutError} If the request times out
+ *
+ * @example
+ * ```typescript
+ * // Auto-detect format from extension
+ * const config = await loadConfig("./config.json");
+ *
+ * // Explicitly specify adapter
+ * const config = await loadConfig("./my-config", "caddyfile");
+ *
+ * // With custom Caddy URL
+ * const config = await loadConfig("./Caddyfile", undefined, {
+ *   adminUrl: "http://caddy:2019"
+ * });
+ * ```
+ */
+declare function loadConfig(path: string, adapter?: CaddyAdapter, options?: LoadConfigOptions): Promise<Config & Record<string, unknown>>;
+/**
+ * Load a Caddyfile and convert it to Caddy JSON format
+ *
+ * Convenience function for loading Caddyfile-formatted configuration.
+ * Equivalent to `loadConfig(path, "caddyfile", options)`.
+ *
+ * @param path - Path to the Caddyfile
+ * @param options - Loading options (adminUrl, timeout)
+ * @returns The parsed Caddy configuration object
+ *
+ * @throws {ValidationError} If the file content is empty or invalid
+ * @throws {CaddyApiError} If Caddy cannot parse the Caddyfile
+ * @throws {NetworkError} If unable to connect to Caddy Admin API
+ * @throws {TimeoutError} If the request times out
+ *
+ * @example
+ * ```typescript
+ * const config = await loadCaddyfile("./Caddyfile");
+ *
+ * // Modify the config
+ * config.apps.http.servers.srv0.routes.push(myNewRoute);
+ *
+ * // Apply to running Caddy
+ * await client.applyConfig(config);
+ * ```
+ */
+declare function loadCaddyfile(path: string, options?: LoadConfigOptions): Promise<Config & Record<string, unknown>>;
+
+/**
+ * Domain management with TLS automation
+ */
+
+/**
+ * Add a domain with automatic TLS (Let's Encrypt)
+ * @param options - Domain configuration
+ * @returns Domain configuration
+ * @throws {ValidationError} If options fail validation
+ * @throws {DomainAlreadyExistsError} If domain already exists
+ * @throws {CaddyApiError} If Caddy API returns an error
+ */
+declare function addDomainWithAutoTls(options: AddDomainWithAutoTlsOptions): Promise<DomainConfig>;
+/**
+ * Add a domain with custom TLS certificate
+ * @param options - Domain configuration with cert files
+ * @returns Domain configuration
+ * @throws {ValidationError} If options fail validation
+ * @throws {DomainAlreadyExistsError} If domain already exists
+ * @throws {CaddyApiError} If Caddy API returns an error
+ */
+declare function addDomainWithTls(options: AddDomainWithTlsOptions): Promise<DomainConfig>;
+/**
+ * Update an existing domain
+ * @param options - Update options
+ * @returns Updated domain configuration
+ * @throws {ValidationError} If options fail validation
+ * @throws {DomainNotFoundError} If domain does not exist
+ * @throws {CaddyApiError} If Caddy API returns an error
+ */
+declare function updateDomain(options: UpdateDomainOptions): Promise<DomainConfig>;
+/**
+ * Delete a domain and clean up associated certificates
+ * @param options - Delete options
+ * @throws {ValidationError} If options fail validation
+ * @throws {DomainNotFoundError} If domain does not exist
+ * @throws {CaddyApiError} If Caddy API returns an error
+ */
+declare function deleteDomain(options: DeleteDomainOptions): Promise<void>;
+/**
+ * Get domain configuration
+ * @param domain - Domain name
+ * @param adminUrl - Caddy Admin API URL
+ * @returns Domain configuration or null if not found
+ */
+declare function getDomainConfig(domain: Domain, adminUrl?: string): Promise<DomainConfig | null>;
+/**
+ * Rotate TLS certificate for a domain
+ * Adds new certificate while keeping the old one temporarily for zero-downtime rotation
+ * @param domain - Domain name
+ * @param newCertFile - Path to new certificate file
+ * @param newKeyFile - Path to new private key file
+ * @param adminUrl - Caddy Admin API URL
+ * @returns Certificate tag of the newly added certificate
+ */
+declare function rotateCertificate(domain: Domain, newCertFile: string, newKeyFile: string, adminUrl?: string): Promise<string>;
+/**
+ * Remove old certificates for a domain after rotation
+ * Call this after verifying the new certificate is working
+ * @param domain - Domain name
+ * @param keepCertTag - Certificate tag to keep (usually the newest)
+ * @param adminUrl - Caddy Admin API URL
+ * @returns Number of certificates removed
+ */
+declare function removeOldCertificates(domain: Domain, keepCertTag: string, adminUrl?: string): Promise<number>;
+/**
+ * List all configured domains across all servers
+ * Extracts unique hostnames from all routes in all servers
+ *
+ * @param adminUrl - Caddy admin API URL (optional, defaults to http://127.0.0.1:2019)
+ * @returns Array of unique domain names
+ *
+ * @example
+ * const domains = await listDomains();
+ * console.log(domains); // ["example.com", "www.example.com", "api.example.com"]
+ */
+declare function listDomains(adminUrl?: string): Promise<string[]>;
+
+/**
+ * TLS connection policy builders and utilities
+ */
+
+/**
+ * Common TLS 1.3 cipher suites (recommended)
+ */
+declare const TLS_1_3_CIPHER_SUITES: readonly ["TLS_AES_128_GCM_SHA256", "TLS_AES_256_GCM_SHA384", "TLS_CHACHA20_POLY1305_SHA256"];
+/**
+ * Common TLS 1.2 cipher suites (recommended)
+ */
+declare const TLS_1_2_CIPHER_SUITES: readonly ["TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256", "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256", "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384", "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384", "TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256", "TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256"];
+/**
+ * Modern cipher suites (TLS 1.2 + 1.3, secure)
+ */
+declare const MODERN_CIPHER_SUITES: ("TLS_AES_128_GCM_SHA256" | "TLS_AES_256_GCM_SHA384" | "TLS_CHACHA20_POLY1305_SHA256" | "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256" | "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256" | "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384" | "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384" | "TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256" | "TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256")[];
+/**
+ * Recommended elliptic curves (in order of preference)
+ */
+declare const RECOMMENDED_CURVES: readonly ["x25519", "secp256r1", "secp384r1"];
+/**
+ * ALPN protocols for HTTP/3, HTTP/2, and HTTP/1.1
+ */
+declare const HTTP_ALPN_PROTOCOLS: readonly ["h3", "h2", "http/1.1"];
+/**
+ * ALPN protocols for HTTP/2 and HTTP/1.1 (no HTTP/3)
+ */
+declare const HTTP2_ALPN_PROTOCOLS: readonly ["h2", "http/1.1"];
+/**
+ * ALPN protocols for HTTP/1.1 only
+ */
+declare const HTTP1_ALPN_PROTOCOLS: readonly ["http/1.1"];
+/**
+ * Options for building TLS connection policy
+ */
+interface TlsConnectionPolicyOptions {
+    /** SNI hostnames to match (e.g., ["example.com", "*.example.com"]) */
+    sni?: string[];
+    /** Certificate tags to select (any_tag) */
+    certificateTags?: string[];
+    /** Certificate tags required (all_tags) */
+    requiredCertificateTags?: string[];
+    /** Minimum TLS version ("1.2" or "1.3") */
+    protocolMin?: "1.2" | "1.3";
+    /** Maximum TLS version ("1.2" or "1.3") */
+    protocolMax?: "1.2" | "1.3";
+    /** Cipher suites to allow (or "modern" for recommended suites) */
+    cipherSuites?: string[] | "modern";
+    /** Elliptic curves to allow (or "recommended") */
+    curves?: string[] | "recommended";
+    /** ALPN protocols (or "http3", "http2", "http1") */
+    alpn?: string[] | "http3" | "http2" | "http1";
+    /** Client authentication mode */
+    clientAuthMode?: "request" | "require" | "verify_if_given";
+    /** Client CA certificate files */
+    clientCaCertFiles?: string[];
+}
+/**
+ * Build a TLS connection policy
+ *
+ * @param options - TLS policy options
+ * @returns TLS connection policy object
+ *
+ * @example
+ * ```typescript
+ * // Modern TLS 1.3 only with HTTP/3
+ * const policy = buildTlsConnectionPolicy({
+ *   sni: ["example.com"],
+ *   certificateTags: ["example-cert"],
+ *   protocolMin: "1.3",
+ *   cipherSuites: "modern",
+ *   curves: "recommended",
+ *   alpn: "http3"
+ * });
+ * ```
+ */
+declare function buildTlsConnectionPolicy(options: TlsConnectionPolicyOptions): TlsConnectionPolicy;
+/**
+ * Build a modern, secure TLS policy (TLS 1.3 with HTTP/3 support)
+ *
+ * @param options - Basic options (sni, certificateTags)
+ * @returns Secure TLS connection policy
+ *
+ * @example
+ * ```typescript
+ * const policy = buildModernTlsPolicy({
+ *   sni: ["example.com"],
+ *   certificateTags: ["example-cert"]
+ * });
+ * ```
+ */
+declare function buildModernTlsPolicy(options: {
+    sni?: string[];
+    certificateTags?: string[];
+}): TlsConnectionPolicy;
+/**
+ * Build a compatible TLS policy (TLS 1.2+, HTTP/2 support, broader compatibility)
+ *
+ * @param options - Basic options (sni, certificateTags)
+ * @returns Compatible TLS connection policy
+ *
+ * @example
+ * ```typescript
+ * const policy = buildCompatibleTlsPolicy({
+ *   sni: ["example.com"],
+ *   certificateTags: ["example-cert"]
+ * });
+ * ```
+ */
+declare function buildCompatibleTlsPolicy(options: {
+    sni?: string[];
+    certificateTags?: string[];
+}): TlsConnectionPolicy;
+/**
+ * The shape Caddy expects in `policy.issuers[]` for the internal issuer:
+ * Caddy's generated {@link InternalIssuer} type (`ca`, `lifetime`,
+ * `sign_with_root`) plus the `module: "internal"` discriminator that
+ * Caddy's module system adds at the JSON boundary. See:
+ *   https://caddyserver.com/docs/json/apps/tls/automation/policies/issuers/internal/
+ */
+type InternalIssuerJson = InternalIssuer & {
+    module: "internal";
+};
+/**
+ * Options for {@link buildAutomationPoliciesWithInternalFallback}.
+ */
+interface InternalFallbackPoliciesOptions {
+    /**
+     * If `true` (default), prepend an explicit policy scoping the internal
+     * issuer to `*.localhost` + `localhost`. The catch-all below would
+     * handle these too, but Caddy already treats `.localhost` specially in
+     * its built-in auto-HTTPS rules and emitting this policy is documentary.
+     */
+    includeLocalhostPolicy?: boolean;
+    /**
+     * Optional override for the internal issuer used by the localhost
+     * policy and the catch-all (e.g. a custom CA id or `lifetime`).
+     * Caddy core's {@link InternalIssuer} fields, minus the `module`
+     * discriminator (added automatically). Defaults to an empty issuer
+     * (i.e. `{ module: "internal" }`).
+     */
+    internalIssuer?: InternalIssuer;
+}
+/**
+ * Build a TLS `automation.policies` array whose final entry is an
+ * unscoped (catch-all) policy that uses Caddy's `internal` issuer.
+ *
+ * **Why this exists.** Without an unscoped catch-all, any hostname not
+ * matched by a more-specific policy hits Caddy's default behavior:
+ * obtain a Let's Encrypt cert via HTTP-01 / TLS-ALPN-01. For Caddy
+ * instances behind a tunnel/edge that already terminates TLS, or
+ * running on a private network with no inbound port 80/443, that's
+ * always wrong: the ACME challenge can't be solved, every renewal job
+ * fails, and the log fills with `"obtaining certificate: ... context
+ * canceled"` and `"no solvers available for remaining challenges"`.
+ *
+ * The fix is a terminal policy with no `subjects` field that uses the
+ * internal (self-signed) issuer. Caddy's own schema describes
+ * `AutomationPolicy.subjects` as a *filter, not a command*; omitting it
+ * means "match anything not already matched."
+ *
+ * **Adding ACME-DNS or other plugin-backed issuers**: don't pass them
+ * here. Construct a typed plugin policy via the plugin's schema (under
+ * `src/plugins/<plugin-name>/`) and merge it into the policy array
+ * before this catch-all in the calling code. This builder intentionally
+ * exposes no `unknown`-shaped passthrough.
+ *
+ * Policy order produced:
+ *   1. (default) `subjects: ["*.localhost", "localhost"]` → internal
+ *   2. **Catch-all** (no `subjects`) → internal
+ *
+ * @example
+ * ```typescript
+ * const { policies } = buildAutomationPoliciesWithInternalFallback();
+ * // [
+ * //   { subjects: ["*.localhost", "localhost"], issuers: [{ module: "internal" }] },
+ * //   { issuers: [{ module: "internal" }] },
+ * // ]
+ * ```
+ *
+ * @param options - {@link InternalFallbackPoliciesOptions}
+ * @returns Object shaped for `apps.tls.automation`.
+ */
+declare function buildAutomationPoliciesWithInternalFallback(options?: InternalFallbackPoliciesOptions): {
+    policies: AutomationPolicy[];
+};
+/**
+ * Walk a Caddy `routes[]` tree (or any nested fragment) and collect every
+ * non-internal hostname referenced in `match[].host[]`.
+ *
+ * Recurses into Caddy's `subroute` handler shape, where nested routes
+ * live at `handle[].routes[]`. Hostnames Caddy already treats as internal
+ * (`localhost`, `*.localhost`, `.localhost` suffixes, literal IPs) are
+ * filtered out — see {@link isInternalHost}.
+ *
+ * Useful as input to {@link buildAutomaticHttpsConfig} when you want
+ * `automatic_https.skip` to mirror the actual route topology rather than
+ * a fixed list maintained somewhere else.
+ *
+ * @param routes - A Caddy `server.routes` array (or any nested fragment).
+ * @returns Sorted, de-duplicated list of non-internal hostnames.
+ */
+declare function collectExternalHostsFromRoutes(routes: unknown): string[];
+/**
+ * Options for {@link buildAutomaticHttpsConfig}. Mirrors Caddy core's
+ * generated {@link AutoHTTPSConfig} (camelCased for the TypeScript API,
+ * but emitted to Caddy's snake_case shape).
+ */
+interface AutomaticHttpsConfigOptions {
+    /**
+     * Hostnames to add to `automatic_https.skip` — Caddy disables automatic
+     * HTTPS (cert acquisition AND HTTP→HTTPS redirect) for these.
+     * Internal hosts (see {@link isInternalHost}) are filtered out and
+     * duplicates are de-duplicated.
+     */
+    skip?: string[];
+    /**
+     * Hostnames to add to `automatic_https.skip_certificates` — Caddy will
+     * not obtain certs for these but will still install the HTTP→HTTPS
+     * redirect. Use when the host is reachable on HTTPS via a manually-
+     * loaded cert.
+     */
+    skipCerts?: string[];
+    /** Sets `automatic_https.disable_redirects: true`. */
+    disableRedirects?: boolean;
+    /** Sets `automatic_https.disable: true` (entire pipeline off). */
+    disable?: boolean;
+    /** Sets `automatic_https.disable_certificates: true` (cert mgmt off, redirects stay). */
+    disableCertificates?: boolean;
+    /** Sets `automatic_https.ignore_loaded_certificates: true`. */
+    ignoreLoadedCertificates?: boolean;
+}
+/**
+ * Build a Caddy `automatic_https` config block.
+ *
+ * Symmetric to {@link collectExternalHostsFromRoutes}: pass the result of
+ * that walker as `skip` to derive the skip list dynamically from the live
+ * routes.
+ *
+ * Returns `undefined` when no field would be set, so the caller can
+ * conditionally assign without polluting the config with empty objects:
+ *
+ *   const auto = buildAutomaticHttpsConfig({ skip: hosts, disableRedirects: true });
+ *   if (auto) server.automatic_https = auto;
+ *
+ * @see https://caddyserver.com/docs/json/apps/http/servers/automatic_https/
+ */
+declare function buildAutomaticHttpsConfig(options?: AutomaticHttpsConfigOptions): AutoHTTPSConfig | undefined;
+/**
+ * Drop `automatic_https.skip` entries that would shadow an external-
+ * ACME policy (Caddy evaluates skip via the same host-matcher as
+ * routes). Three-way check, case-insensitive: exact match; candidate-
+ * wildcard covers ACME host; ACME-host wildcard covers candidate.
+ * Always returns a fresh array.
+ *
+ * @example
+ * filterAcmeManagedFromSkip(["*.pro.com"], new Set(["app.pro.com"]))   // []
+ * filterAcmeManagedFromSkip(["app.pro.com"], new Set(["*.pro.com"]))   // []
+ * filterAcmeManagedFromSkip(["*.pro.com"], new Set(["api.other.com"])) // ["*.pro.com"]
+ */
+declare function filterAcmeManagedFromSkip(candidates: string[], acmeManagedHosts: Set<string>): string[];
+/**
+ * Set `apps.pki.certificate_authorities.local.install_trust`.
+ * Idempotent. Mutates in place. Throws when an intermediate node
+ * exists but isn't an object — silent retyping would corrupt unrelated
+ * state.
+ *
+ * Motivating case: on Windows the local CA's first issuance triggers
+ * UAC + `certutil` (5–30 s), blocking the admin API.
+ *
+ * @example
+ * applyLocalCaInstallTrust(cfg, false) // skip trust install
+ */
+declare function applyLocalCaInstallTrust(config: Record<string, unknown>, installTrust: boolean): void;
+
+/**
+ * Caddy host-matcher subset for config builders and diagnostics.
+ * Covers what `automatic_https.skip` and `match.host[]` accept in
+ * practice: exact, leading-wildcard single-label, generic glob.
+ */
+/**
+ * True when `host` matches `pattern`:
+ *   - Exact: `pattern === host`.
+ *   - Single-label `*.tld`: matches one extra label (case-sensitive).
+ *     Only fires when the tail is a literal — `*.api-*.tld` is a
+ *     generic glob, not a single-label match.
+ *   - Generic glob: `*` becomes `.*` (crosses dots intentionally —
+ *     only the single-label branch enforces label boundaries).
+ *
+ * Case-sensitive — lowercase both inputs for case-insensitive match.
+ *
+ * @example
+ * hostMatchesPattern("foo.example.com", "*.example.com")     // true
+ * hostMatchesPattern("a.b.example.com", "*.example.com")     // false
+ * hostMatchesPattern("api-a.b.example.com", "api-*.example.com") // true (glob crosses dots)
+ */
+declare function hostMatchesPattern(host: string, pattern: string): boolean;
+
+/**
+ * ACME-DNS automation policy builder. Emits the wrapper-level shape:
+ *   { subjects, issuers: [{ module: "acme", challenges: { dns: { provider: { name } } }, … }] }
+ *
+ * Provider credentials are NOT modelled here — Caddy reads them from
+ * env vars (CLOUDFLARE_API_TOKEN, …). Layer typed `caddy-dns/*` shapes
+ * via `providerConfig` (opaque passthrough).
+ */
+
+/** Friendly DNS provider name → Caddy module name. Frozen. */
+declare const ACME_DNS_PROVIDER_MODULE_MAP: Readonly<Record<string, string>>;
+/**
+ * Resolve a provider name to its Caddy module name. Trims + lower-cases
+ * (Caddy module identifiers are lower-case). Unknown names pass through
+ * normalised — `"MyProvider"` → `"myprovider"`.
+ */
+declare function resolveAcmeDnsProviderModule(name: string): string;
+/** Options for {@link buildAcmeDnsPolicy}. */
+interface AcmeDnsPolicyOptions {
+    /** Hostnames the policy applies to. Non-empty; entries are trimmed. */
+    subjects: string[];
+    /** DNS provider name. Trim + lower-case normalised; passes through unknowns. */
+    dnsProvider: string;
+    /** Override ACME directory URL (`ca`). */
+    ca?: string;
+    /** Account email registered with the ACME server. */
+    email?: string;
+    /**
+     * Opaque provider-config passthrough. Reserved keys throw: `name`
+     * (owned by `dnsProvider`) and `module` (issuer-level discriminator,
+     * not a provider field).
+     */
+    providerConfig?: Record<string, unknown>;
+}
+/**
+ * Build an ACME-DNS automation policy. Use with
+ * {@link buildAutomationPoliciesWithInternalFallback} by prepending.
+ *
+ * Provider discriminator is `name`, not `module` — see Caddy core
+ * `caddytls/automation.go`: `caddy:"namespace=dns.providers inline_key=name"`.
+ *
+ * @example
+ * buildAcmeDnsPolicy({ subjects: ["example.com"], dnsProvider: "cloudflare" })
+ */
+declare function buildAcmeDnsPolicy(options: AcmeDnsPolicyOptions): AutomationPolicy;
+
+/**
+ * Route Ordering and Priority System
+ *
+ * Provides explicit route ordering to replace implicit array-based ordering.
+ * Routes are sorted by priority (lower number = higher priority) and then by
+ * path specificity.
+ *
+ * @module caddy/ordering
+ */
+
+/**
+ * Standard route priorities for common patterns
+ * Lower numbers are evaluated first
+ */
+declare const ROUTE_PRIORITIES: Record<string, number>;
+/**
+ * Calculate implicit priority from route match patterns
+ * Used when explicit priority is not set
+ *
+ * Priority is calculated based on:
+ * 1. Path specificity (exact > prefix > wildcard)
+ * 2. Host specificity (exact > wildcard)
+ * 3. Number of matchers (more = more specific)
+ *
+ * @param route - Route to analyze
+ * @returns Calculated priority (0-100, lower = higher priority)
+ *
+ * @example
+ * calculateRoutePriority({ match: [{ path: ["/health"] }] }) // Returns ~0 (health check)
+ * calculateRoutePriority({ match: [{ path: ["/api/*"] }] })  // Returns ~30 (specific path)
+ * calculateRoutePriority({ match: [{ path: ["/*"] }] })      // Returns ~90 (wildcard)
+ */
+declare function calculateRoutePriority(route: CaddyRoute): number;
+/**
+ * Sort routes by priority and specificity
+ * Routes with lower priority numbers are placed first
+ * Within same priority, more specific routes come first
+ *
+ * @param routes - Routes to sort
+ * @returns Sorted routes (does not mutate input)
+ *
+ * @example
+ * const routes = [
+ *   { match: [{ path: ["/*"] }] },           // Wildcard
+ *   { match: [{ path: ["/health"] }] },      // Health
+ *   { match: [{ path: ["/api/*"] }] },       // API
+ * ];
+ * const sorted = sortRoutes(routes);
+ * // Order: health, api, wildcard
+ */
+declare function sortRoutes(routes: CaddyRoute[]): CaddyRoute[];
+/**
+ * Validate route ordering against expected rules
+ * Throws if ordering would cause routing issues
+ *
+ * @param routes - Routes to validate (should already be sorted)
+ * @throws {Error} If route ordering violates rules
+ *
+ * @example
+ * const routes = sortRoutes([healthRoute, apiRoute, catchAll]);
+ * validateRouteOrdering(routes); // No error
+ *
+ * validateRouteOrdering([catchAll, healthRoute]); // Throws error
+ */
+declare function validateRouteOrdering(routes: CaddyRoute[]): void;
+/**
+ * Insert route with relative positioning
+ * Allows inserting routes before/after specific route IDs
+ *
+ * @param routes - Existing routes
+ * @param route - Route to insert
+ * @param options - Positioning options
+ * @returns New routes array with route inserted
+ *
+ * @example
+ * // Insert at beginning
+ * insertRouteRelative(routes, newRoute, { position: "beginning" })
+ *
+ * // Insert after health check
+ * insertRouteRelative(routes, newRoute, { afterId: "global-health" })
+ *
+ * // Insert before catch-all
+ * insertRouteRelative(routes, newRoute, { beforeId: "catch-all" })
+ */
+declare function insertRouteRelative(routes: CaddyRoute[], route: CaddyRoute, options?: {
+    beforeId?: string;
+    afterId?: string;
+    position?: "beginning" | "end";
+}): CaddyRoute[];
+
+/**
+ * High-level helper functions for common Caddy routing patterns
+ *
+ * These helpers encode .asd production patterns and best practices,
+ * hiding Caddy JSON complexity behind clean, semantic APIs.
+ *
+ * @module caddy/helpers
+ */
+
+/**
+ * Options for creating a health check route
+ */
+interface HealthRouteOptions {
+    /** Instance identifier (e.g., "prod-cluster-1") */
+    instanceId: string;
+    /** Health check path (default: "/health") */
+    path?: string;
+    /** Number of services in this instance */
+    services?: number;
+    /** Instance version */
+    version?: string;
+    /** Project identifier for X-ASD-Project header */
+    projectId?: string;
+}
+/**
+ * Options for creating service routes
+ */
+interface ServiceRouteOptions {
+    /** Route identifier */
+    id: string;
+    /** Host to match (e.g., "api.localhost") */
+    host: string;
+    /** Path to match (default: "/*") */
+    path?: string;
+    /** Upstream backend (dial address or array of upstreams) */
+    upstream: string | {
+        dial: string;
+    }[];
+    /** Service identifier for X-ASD-Service-ID header */
+    serviceId?: string;
+    /** Service type for X-ASD-Service-Type header */
+    serviceType?: string;
+    /** Enable compression (default: true) */
+    enableCompression?: boolean;
+    /** Additional response headers */
+    headers?: Record<string, string[]>;
+    /** Explicit priority (optional) */
+    priority?: number;
+    /** Project identifier for X-ASD-Project header */
+    projectId?: string;
+}
+/**
+ * Options for creating basic auth routes
+ */
+interface BasicAuthRouteOptions {
+    /** Route identifier */
+    id?: string;
+    /** Host to match */
+    host: string;
+    /** Path to match (omit for domain-level auth) */
+    path?: string;
+    /** User accounts with bcrypt password hashes */
+    accounts: {
+        username: string;
+        password: string;
+    }[];
+    /** Upstream backend */
+    upstream: string | {
+        dial: string;
+    }[];
+    /** Authentication realm */
+    realm?: string;
+    /** Service identifier */
+    serviceId?: string;
+    /** Service type */
+    serviceType?: string;
+    /** Additional response headers */
+    headers?: Record<string, string[]>;
+    /** Explicit priority (optional) */
+    priority?: number;
+    /** Project identifier for X-ASD-Project header */
+    projectId?: string;
+}
+/**
+ * Options for creating load balancer routes
+ */
+interface LoadBalancerRouteOptions {
+    /** Route identifier */
+    id: string;
+    /** Host to match */
+    host: string;
+    /** Path to match (default: "/*") */
+    path?: string;
+    /** Array of upstream backends */
+    upstreams: string[] | {
+        dial: string;
+    }[];
+    /** Load balancing policy */
+    policy?: "round_robin" | "least_conn" | "ip_hash" | "first" | "random";
+    /** Enable active health checks */
+    healthCheck?: {
+        path?: string;
+        interval?: string;
+        timeout?: string;
+    };
+    /** Service identifier */
+    serviceId?: string;
+    /** Additional response headers */
+    headers?: Record<string, string[]>;
+}
+/**
+ * Options for creating path rewrite routes
+ */
+interface RewriteRouteOptions {
+    /** Route identifier */
+    id: string;
+    /** Host to match */
+    host: string;
+    /** Path prefix to match and strip */
+    pathPrefix: string;
+    /** Upstream backend */
+    upstream: string | {
+        dial: string;
+    }[];
+    /** Service identifier */
+    serviceId?: string;
+    /** Additional response headers */
+    headers?: Record<string, string[]>;
+}
+/**
+ * Create a standardized global health check route
+ * Always evaluated first, accessible from any host
+ *
+ * @param options - Health check configuration
+ * @returns Health check route with priority 0
+ *
+ * @example
+ * const health = createHealthRoute({
+ *   instanceId: "prod-cluster-1",
+ *   services: 10,
+ *   version: "1.0.0",
+ * });
+ */
+declare function createHealthRoute(options: HealthRouteOptions): CaddyRoute;
+/**
+ * Create service routes with standard security headers
+ * Returns single route (no redirect in this version)
+ *
+ * @param options - Service configuration
+ * @returns Service route
+ *
+ * @example
+ * const route = createServiceRoute({
+ *   id: "api-service",
+ *   host: "api.localhost",
+ *   path: "/api/*",
+ *   upstream: "backend:8080",
+ *   serviceId: "api-backend-v1",
+ *   serviceType: "api",
+ * });
+ */
+declare function createServiceRoute(options: ServiceRouteOptions): CaddyRoute;
+/**
+ * Create Basic Auth protected route (domain or path-level)
+ *
+ * @param options - Authentication configuration
+ * @returns Auth-protected route
+ *
+ * @example
+ * // Domain-level auth (entire domain protected)
+ * const route = createBasicAuthRoute({
+ *   host: "admin.localhost",
+ *   accounts: [
+ *     { username: "admin", password: "$2a$14$..." },
+ *     { username: "superadmin", password: "$2a$14$..." },
+ *   ],
+ *   upstream: "admin-backend:8080",
+ *   realm: "Admin Dashboard",
+ * });
+ *
+ * @example
+ * // Path-level auth (specific paths protected)
+ * const route = createBasicAuthRoute({
+ *   host: "api.localhost",
+ *   path: "/admin/*",
+ *   accounts: [{ username: "apiuser", password: "$2a$14$..." }],
+ *   upstream: "api-backend:8080",
+ *   realm: "API Admin",
+ * });
+ */
+declare function createBasicAuthRoute(options: BasicAuthRouteOptions): CaddyRoute;
+/**
+ * Create load-balanced route with health checks
+ *
+ * @param options - Load balancer configuration
+ * @returns Load-balanced route
+ *
+ * @example
+ * const route = createLoadBalancerRoute({
+ *   id: "api-lb",
+ *   host: "api.localhost",
+ *   upstreams: ["backend-1:8080", "backend-2:8080", "backend-3:8080"],
+ *   policy: "round_robin",
+ *   healthCheck: {
+ *     path: "/health",
+ *     interval: "10s",
+ *     timeout: "2s",
+ *   },
+ * });
+ */
+declare function createLoadBalancerRoute(options: LoadBalancerRouteOptions): CaddyRoute;
+/**
+ * Create path rewriting route
+ * Strips path prefix before proxying to backend
+ *
+ * @param options - Rewrite configuration
+ * @returns Route with path rewriting
+ *
+ * @example
+ * const route = createRewriteRoute({
+ *   id: "api-rewrite",
+ *   host: "app.localhost",
+ *   pathPrefix: "/api/v1",
+ *   upstream: "backend:3000",
+ * });
+ * // Request to /api/v1/users → backend receives /users
+ */
+declare function createRewriteRoute(options: RewriteRouteOptions): CaddyRoute;
+/**
+ * Create redirect route (www ↔ domain)
+ *
+ * @param options - Redirect configuration
+ * @returns Redirect route
+ *
+ * @example
+ * // Redirect www.example.com → example.com
+ * const route = createRedirectRoute({
+ *   from: "www.example.com",
+ *   to: "example.com",
+ * });
+ *
+ * @example
+ * // Redirect example.com → www.example.com with custom status code
+ * const route = createRedirectRoute({
+ *   from: "example.com",
+ *   to: "www.example.com",
+ *   statusCode: 301, // Or 302, 307, 308
+ * });
+ */
+declare function createRedirectRoute(options: {
+    id?: string;
+    from: string;
+    to: string;
+    permanent?: boolean;
+    statusCode?: 301 | 302 | 307 | 308;
+}): CaddyRoute;
+
+interface CertificateInfo {
+    serialNumber: string;
+    subject: string;
+    issuer: string;
+    notBefore: Date;
+    notAfter: Date;
+}
+/**
+ * Parse PEM certificate and extract metadata
+ * @param pemCert - PEM-encoded certificate
+ * @returns Certificate metadata
+ */
+declare function parseCertificate(pemCert: string): CertificateInfo;
+/**
+ * Generate unique certificate tag for tracking in Caddy
+ * Format: {domain}-{serial}-{timestamp}
+ * @param domain - Domain name
+ * @param serialNumber - Certificate serial number (hex)
+ * @returns Unique certificate tag
+ */
+declare function generateCertTag(domain: string, serialNumber: string): string;
+/**
+ * Split certificate bundle into individual certificates
+ * Handles multi-certificate PEM files (certificate chains)
+ * @param bundle - PEM bundle containing one or more certificates
+ * @returns Array of individual PEM certificates
+ */
+declare function splitCertificateBundle(bundle: string): string[];
+/**
+ * Extract certificate serial number as hex string
+ * @param pemCert - PEM-encoded certificate
+ * @returns Serial number in hexadecimal format
+ */
+declare function extractSerialNumber(pemCert: string): string;
+/**
+ * Check if certificate is expired
+ * @param pemCert - PEM-encoded certificate
+ * @returns True if certificate is expired
+ */
+declare function isCertificateExpired(pemCert: string): boolean;
+/**
+ * Check if certificate expires within the specified days
+ * @param pemCert - PEM-encoded certificate
+ * @param days - Number of days to check
+ * @returns True if certificate expires within the specified days
+ */
+declare function isCertificateExpiringSoon(pemCert: string, days: number): boolean;
+/**
+ * Get days until certificate expiration
+ * @param pemCert - PEM-encoded certificate
+ * @returns Days until expiration (negative if expired)
+ */
+declare function getDaysUntilExpiration(pemCert: string): number;
+
+/**
+ * Certificate Management Abstraction
+ *
+ * Provides a unified interface for all certificate operations,
+ * bundling certificate utilities and domain TLS management.
+ *
+ * @module caddy/certificates
+ */
+
+/**
+ * Certificate metadata with additional context
+ */
+interface CertificateWithMetadata extends CertificateInfo {
+    /** Certificate tag in Caddy config */
+    tag: string;
+    /** Whether certificate is expired */
+    isExpired: boolean;
+    /** Whether certificate expires soon (within threshold) */
+    expiringSoon: boolean;
+    /** Days until expiration (negative if expired) */
+    daysUntilExpiration: number;
+}
+/**
+ * Options for certificate rotation
+ */
+interface RotateCertificateOptions {
+    /** Domain name */
+    domain: string;
+    /** Path to new certificate file */
+    certPath: string;
+    /** Path to new private key file */
+    keyPath: string;
+    /** Caddy admin API URL (optional, defaults to client URL) */
+    adminUrl?: string;
+    /** Whether to remove old certificates after rotation */
+    cleanupOld?: boolean;
+}
+/**
+ * Result of certificate rotation operation
+ */
+interface RotationResult {
+    /** New certificate tag */
+    tag: string;
+    /** Number of old certificates removed (if cleanup enabled) */
+    removedCount?: number;
+}
+/**
+ * Certificate expiration check result
+ */
+interface ExpirationCheckResult {
+    /** Whether any certificates are expiring soon */
+    hasExpiring: boolean;
+    /** Certificates that are expiring or expired */
+    expiringCertificates: CertificateWithMetadata[];
+    /** All certificates for the domain */
+    allCertificates: CertificateWithMetadata[];
+}
+/**
+ * Certificate Manager
+ *
+ * Unified interface for certificate operations.
+ * Bundles certificate inspection, rotation, cleanup, and monitoring.
+ *
+ * @example
+ * const manager = new CertificateManager(client);
+ *
+ * // Inspect certificate
+ * const info = await manager.inspect(certPem);
+ *
+ * // Rotate certificate
+ * const result = await manager.rotate({
+ *   domain: "example.com",
+ *   certPath: "/path/to/new-cert.pem",
+ *   keyPath: "/path/to/new-key.pem",
+ *   cleanupOld: true,
+ * });
+ *
+ * // Check expiration
+ * const check = await manager.checkExpiration("example.com", 30);
+ * if (check.hasExpiring) {
+ *   console.log(`${check.expiringCertificates.length} certs expiring soon`);
+ * }
+ */
+declare class CertificateManager {
+    private client;
+    constructor(client: CaddyClient);
+    /**
+     * Inspect certificate metadata from PEM string
+     *
+     * @param certPem - PEM-encoded certificate
+     * @returns Certificate information
+     *
+     * @example
+     * const info = await manager.inspect(certPem);
+     * console.log(`Serial: ${info.serialNumber}`);
+     * console.log(`Expires: ${info.notAfter}`);
+     */
+    inspect(certPem: string): Promise<CertificateInfo>;
+    /**
+     * Rotate certificate with zero downtime
+     *
+     * Process:
+     * 1. Load new certificate and key
+     * 2. Generate unique tag
+     * 3. Add new certificate to Caddy
+     * 4. Update domain's TLS automation to use new certificate
+     * 5. Optionally remove old certificates
+     *
+     * @param options - Rotation options
+     * @returns Rotation result with new tag and cleanup count
+     *
+     * @example
+     * const result = await manager.rotate({
+     *   domain: "example.com",
+     *   certPath: "/certs/new-cert.pem",
+     *   keyPath: "/certs/new-key.pem",
+     *   cleanupOld: true,
+     * });
+     * console.log(`New tag: ${result.tag}`);
+     * console.log(`Removed ${result.removedCount} old certificates`);
+     */
+    rotate(options: RotateCertificateOptions): Promise<RotationResult>;
+    /**
+     * Remove old certificates after rotation
+     *
+     * Removes all certificates for the domain except the one with the specified tag.
+     *
+     * @param domain - Domain name
+     * @param keepTag - Certificate tag to keep
+     * @param adminUrl - Optional Caddy admin URL
+     * @returns Number of certificates removed
+     *
+     * @example
+     * const removed = await manager.cleanupOld("example.com", "example.com-abc123-1234567890");
+     * console.log(`Removed ${removed} old certificates`);
+     */
+    cleanupOld(domain: string, keepTag: string, adminUrl?: string): Promise<number>;
+    /**
+     * List all certificates for a domain
+     *
+     * Queries Caddy configuration to find all certificates tagged with the domain.
+     *
+     * @param domain - Domain name
+     * @returns Array of certificates with metadata
+     *
+     * @example
+     * const certs = await manager.list("example.com");
+     * for (const cert of certs) {
+     *   console.log(`Tag: ${cert.tag}, Expires: ${cert.notAfter}`);
+     * }
+     */
+    list(domain: string): Promise<CertificateWithMetadata[]>;
+    /**
+     * Check if any certificates are expiring soon
+     *
+     * @param domain - Domain name
+     * @param thresholdDays - Days before expiration to consider "expiring soon" (default: 30)
+     * @returns Expiration check result
+     *
+     * @example
+     * const check = await manager.checkExpiration("example.com", 30);
+     * if (check.hasExpiring) {
+     *   for (const cert of check.expiringCertificates) {
+     *     console.log(`Certificate ${cert.tag} expires in ${cert.daysUntilExpiration} days`);
+     *   }
+     * }
+     */
+    checkExpiration(domain: string, thresholdDays?: number): Promise<ExpirationCheckResult>;
+    /**
+     * Generate a certificate tag for a domain
+     *
+     * Tags are in format: `{domain}-{serial}-{timestamp}`
+     *
+     * @param domain - Domain name
+     * @param certPem - PEM-encoded certificate
+     * @returns Certificate tag
+     *
+     * @example
+     * const tag = await manager.generateTag("example.com", certPem);
+     * // Returns: "example.com-abc123def456-1234567890"
+     */
+    generateTag(domain: string, certPem: string): Promise<string>;
+    /**
+     * Check if certificate is expired
+     *
+     * @param certPem - PEM-encoded certificate
+     * @returns True if certificate is expired
+     *
+     * @example
+     * const isExpired = await manager.isExpired(certPem);
+     * if (isExpired) {
+     *   console.log("Certificate is expired!");
+     * }
+     */
+    isExpired(certPem: string): Promise<boolean>;
+    /**
+     * Check if certificate expires soon
+     *
+     * @param certPem - PEM-encoded certificate
+     * @param thresholdDays - Days before expiration (default: 30)
+     * @returns True if certificate expires within threshold
+     *
+     * @example
+     * const expiringSoon = await manager.isExpiringSoon(certPem, 30);
+     * if (expiringSoon) {
+     *   console.log("Certificate expires soon!");
+     * }
+     */
+    isExpiringSoon(certPem: string, thresholdDays?: number): Promise<boolean>;
+    /**
+     * Get days until certificate expiration
+     *
+     * @param certPem - PEM-encoded certificate
+     * @returns Days until expiration (negative if expired)
+     *
+     * @example
+     * const days = await manager.getDaysUntilExpiration(certPem);
+     * console.log(`Certificate expires in ${days} days`);
+     */
+    getDaysUntilExpiration(certPem: string): Promise<number>;
+}
+/**
+ * Create a new CertificateManager instance
+ *
+ * @param client - CaddyClient instance
+ * @returns CertificateManager
+ *
+ * @example
+ * import { CaddyClient, createCertificateManager } from "caddy-api-client";
+ *
+ * const client = new CaddyClient();
+ * const manager = createCertificateManager(client);
+ *
+ * const result = await manager.rotate({
+ *   domain: "example.com",
+ *   certPath: "/certs/cert.pem",
+ *   keyPath: "/certs/key.pem",
+ * });
+ */
+declare function createCertificateManager(client: CaddyClient): CertificateManager;
+
+/**
+ * Authentication utilities for Caddy
+ * Provides bcrypt password hashing for HTTP Basic Auth
+ */
+/**
+ * Hash a password using bcrypt
+ * This uses Node.js crypto module to generate bcrypt hashes
+ * compatible with Caddy's basic_auth handler.
+ *
+ * @param password - Plain text password
+ * @param rounds - Bcrypt cost factor (default: 10, range: 4-31)
+ * @returns Promise resolving to bcrypt hash string
+ * @throws Error if rounds is outside valid range (4-31) or bcrypt module is not installed
+ *
+ * @example
+ * const hash = await hashPassword("my-secret-password");
+ * // Returns: $2a$10$... (bcrypt hash)
+ */
+declare function hashPassword(password: string, rounds?: number): Promise<string>;
+/**
+ * Verify a password against a bcrypt hash
+ * Useful for testing authentication configurations
+ *
+ * @param password - Plain text password
+ * @param hash - Bcrypt hash to verify against
+ * @returns Promise resolving to true if password matches
+ *
+ * @example
+ * const isValid = await verifyPassword("my-password", hash);
+ */
+declare function verifyPassword(password: string, hash: string): Promise<boolean>;
+/**
+ * Generate a bcrypt hash synchronously using Caddy's caddy hash-password command
+ * This is useful for generating hashes without the bcrypt npm module
+ *
+ * @param password - Plain text password
+ * @returns Promise resolving to bcrypt hash or instructions
+ *
+ * @example
+ * const hash = await hashPasswordWithCaddy("my-password");
+ */
+declare function hashPasswordWithCaddy(password: string): Promise<string>;
+/**
+ * Create basic auth account configuration for Caddy
+ *
+ * @param username - Username for authentication
+ * @param password - Plain text password (will be hashed with bcrypt)
+ * @param options - Optional configuration
+ * @returns Promise resolving to account object with hashed password
+ *
+ * @example
+ * const account = await createBasicAuthAccount("admin", "secret123");
+ * // Returns: { username: "admin", password: "$2a$10$..." }
+ */
+declare function createBasicAuthAccount(username: string, password: string, options?: {
+    rounds?: number;
+    useCaddyCLI?: boolean;
+}): Promise<{
+    username: string;
+    password: string;
+}>;
+/**
+ * Create multiple basic auth accounts at once
+ *
+ * @param users - Array of {username, password} pairs
+ * @param options - Optional configuration
+ * @returns Promise resolving to array of account objects with hashed passwords
+ *
+ * @example
+ * const accounts = await createBasicAuthAccounts([
+ *   { username: "admin", password: "admin-pass" },
+ *   { username: "user", password: "user-pass" }
+ * ]);
+ */
+declare function createBasicAuthAccounts(users: {
+    username: string;
+    password: string;
+}[], options?: {
+    rounds?: number;
+    useCaddyCLI?: boolean;
+}): Promise<{
+    username: string;
+    password: string;
+}[]>;
+
+export { buildCompressionHandler as $, type RotateCertificateOptions as A, type BasicAuthRouteOptions as B, type CaddyAdapter as C, type RotationResult as D, type ExpirationCheckResult as E, hashPassword as F, verifyPassword as G, type HealthRouteOptions as H, hashPasswordWithCaddy as I, createBasicAuthAccount as J, createBasicAuthAccounts as K, type LoadConfigOptions as L, buildServiceRoutes as M, buildHealthCheckRoute as N, buildHostRoute as O, buildPathRoute as P, buildLoadBalancerRoute as Q, ROUTE_PRIORITIES as R, type ServiceRouteOptions as S, buildReverseProxyHandler as T, buildSecurityHeadersHandler as U, buildBasicAuthHandler as V, buildRewriteHandler as W, buildIngressTagHeadersHandler as X, buildProjectIdHeadersHandler as Y, buildIframeHeadersHandler as Z, buildRedirectRoute as _, loadCaddyfile as a, buildWwwRedirect as a0, buildMitmproxyRoute as a1, buildMitmproxyRoutePair as a2, type IframeProxyRouteOptions as a3, buildIframeProxyRoute as a4, buildMitmproxyWebUiRoute as a5, type WebSocketProxyRouteOptions as a6, buildWebSocketProxyRoute as a7, buildMitmproxyWebSocketRoute as a8, buildIframePermissiveHandler as a9, type InternalIssuerJson as aA, type InternalFallbackPoliciesOptions as aB, buildAutomationPoliciesWithInternalFallback as aC, collectExternalHostsFromRoutes as aD, type AutomaticHttpsConfigOptions as aE, buildAutomaticHttpsConfig as aF, filterAcmeManagedFromSkip as aG, applyLocalCaInstallTrust as aH, hostMatchesPattern as aI, ACME_DNS_PROVIDER_MODULE_MAP as aJ, resolveAcmeDnsProviderModule as aK, type AcmeDnsPolicyOptions as aL, buildAcmeDnsPolicy as aM, type CertificateInfo as aN, parseCertificate as aO, generateCertTag as aP, splitCertificateBundle as aQ, extractSerialNumber as aR, isCertificateExpired as aS, isCertificateExpiringSoon as aT, getDaysUntilExpiration as aU, buildDnsRebindingBypassHandler as aa, type FileServerRouteOptions as ab, buildFileServerRoute as ac, type TemplatesRouteOptions as ad, buildTemplatesRoute as ae, type ErrorRouteOptions as af, buildErrorRoute as ag, type RequestBodyHandlerOptions as ah, buildRequestBodyHandler as ai, type VarsHandlerOptions as aj, buildVarsHandler as ak, type TracingHandlerOptions as al, buildTracingHandler as am, type MapHandlerOptions as an, buildMapHandler as ao, TLS_1_3_CIPHER_SUITES as ap, TLS_1_2_CIPHER_SUITES as aq, MODERN_CIPHER_SUITES as ar, RECOMMENDED_CURVES as as, HTTP_ALPN_PROTOCOLS as at, HTTP2_ALPN_PROTOCOLS as au, HTTP1_ALPN_PROTOCOLS as av, type TlsConnectionPolicyOptions as aw, buildTlsConnectionPolicy as ax, buildModernTlsPolicy as ay, buildCompatibleTlsPolicy as az, addDomainWithAutoTls as b, addDomainWithTls as c, detectAdapter as d, deleteDomain as e, listDomains as f, getDomainConfig as g, removeOldCertificates as h, calculateRoutePriority as i, insertRouteRelative as j, createHealthRoute as k, loadConfig as l, createServiceRoute as m, createBasicAuthRoute as n, createLoadBalancerRoute as o, createRewriteRoute as p, createRedirectRoute as q, rotateCertificate as r, sortRoutes as s, type LoadBalancerRouteOptions as t, updateDomain as u, validateRouteOrdering as v, type RewriteRouteOptions as w, CertificateManager as x, createCertificateManager as y, type CertificateWithMetadata as z };