@push.rocks/smartproxy 30.0.1 → 31.0.0

package/readme.md

@@ -118,6 +118,35 @@ SmartProxy supports three TLS handling modes:
 | `terminate` | Decrypt at proxy, forward plain HTTP to backend | Standard reverse proxy |
 | `terminate-and-reencrypt` | Decrypt at proxy, re-encrypt to backend. HTTP traffic gets full per-request routing (Host header, path matching) via the HTTP proxy; non-HTTP traffic uses a raw TLS-to-TLS tunnel | Zero-trust / defense-in-depth environments |
 
+#### Backend TLS verification
+
+The proxy verifies the certificate of every backend it connects to over TLS: `terminate-and-reencrypt` routes (HTTP, the raw TLS tunnel and raw QUIC streams), targets with `tls` behind a `terminate` route, WebSocket upgrades, and HTTP/3 backends reached over QUIC. By default it trusts the system root store, so a backend with a self-signed or private-CA certificate is refused (`502`, or a closed tunnel) until its route says how to trust it:
+
+```typescript
+{
+  name: 'internal-api',
+  match: { ports: 443, domains: 'api.example.com' },
+  action: {
+    type: 'forward',
+    targets: [{ host: '10.0.0.5', port: 8443 }],
+    tls: {
+      mode: 'terminate-and-reencrypt',
+      certificate: 'auto',
+      backend: {
+        ca: internalCaPem,          // replaces the system roots for this backend
+        serverName: 'api.internal', // sent as SNI; the certificate must carry it
+      },
+    },
+  },
+}
+```
+
+- `ca` replaces the system root store, as Node's `ca` option does. Its certificates are trusted as issuers, so a self-signed backend certificate must be an end-entity certificate (`CA:FALSE`); a self-signed CA certificate serving as the backend's own certificate is refused.
+- `serverName` defaults to the requested domain on routes that match named domains, and to the target host on routes without domains or with `*`.
+- `rejectUnauthorized: false` accepts any backend certificate; it cannot be combined with `ca`.
+- A target's `tls.backend` replaces the route's `action.tls.backend`, which replaces the proxy-wide `backendTls` option (`ca`, `rejectUnauthorized`). The whole object applies; fields are not merged.
+- Validation refuses `tls.backend` on TLS passthrough and dynamic-target routes, which never connect to the backend over TLS, as well as an empty `ca` or `serverName` and a `ca` without certificates. When the system has no root certificates, the routes that rely on them are refused at `start()` and `updateRoutes()`.
+
 ## 💡 Common Use Cases
 
 ### 🌐 HTTP to HTTPS Redirect
@@ -485,12 +514,11 @@ import { SmartProxy } from '@push.rocks/smartproxy';
 const proxy = new SmartProxy({
   routes: [{
     name: 'nftables-fast',
-    match: { ports: 443, domains: 'fast.example.com' },
+    match: { ports: 5432 },
     action: {
       type: 'forward',
       forwardingEngine: 'nftables',
-      targets: [{ host: 'backend', port: 8080 }],
-      tls: { mode: 'terminate', certificate: 'auto' },
+      targets: [{ host: '10.0.0.20', port: 5432 }],
       nftables: {
         protocol: 'tcp',
         preserveSourceIP: true  // Backend sees real client IP
@@ -500,6 +528,8 @@ const proxy = new SmartProxy({
 });
 ```
 
+The kernel forwards every packet on the listed ports to one IPv4 target before the proxy sees it, so an nftables route matches by port only. Route validation refuses an nftables route that sets `security` or `headers`; `match.domains`, `path`, `headers`, `clientIp`, `tlsVersion`, `protocol` or `inboundProxyProtocol`, or a port range; TLS termination, `websocket`, `advanced` or `sendProxyProtocol`; or more than one target, a target `match`, or a target host other than one IPv4 address. A route with `enabled: false` installs no rules.
+
 ### 🔒 SNI Passthrough (TLS Passthrough)
 
 Forward encrypted traffic to backends without terminating TLS — the proxy routes based on the SNI hostname alone:
@@ -532,13 +562,13 @@ const proxy = new SmartProxy({
     name: 'dynamic-backend',
     match: {
       ports: 443,
-      domains: 'app.example.com'
+      domains: ['app.example.com', 'premium.example.com']
     },
     action: {
       type: 'forward',
       targets: [{
         host: (context) => {
-          return context.path?.startsWith('/premium')
+          return context.domain === 'premium.example.com'
             ? 'premium-backend'
             : 'standard-backend';
         },
@@ -550,7 +580,9 @@ const proxy = new SmartProxy({
 });
 ```
 
-> **Note:** Routes with dynamic functions (host/port callbacks) are automatically relayed through the TypeScript socket handler server, since JavaScript functions can't be serialized to Rust.
+> **Note:** Routes with dynamic functions (host/port callbacks) are automatically relayed through the TypeScript socket handler server, since JavaScript functions can't be serialized to Rust. The relay resolves one target per connection and forwards the whole connection to it. The functions see `context.domain` (the SNI, or the `Host` of a plaintext HTTP request), `context.clientIp` and `context.port`, but no request data such as `context.path`. Header and URL rewrites (`headers`, `advanced`) do not apply on these routes.
+>
+> Dynamic targets work with IP filtering, `maxConnections`, TLS `terminate` and `passthrough`, and `port: 'preserve'`. Route validation refuses dynamic targets together with settings the relay cannot honour: more than one target, a target `match`, `sendProxyProtocol`, TLS `terminate-and-reencrypt` or `tls.backend`, `backendTransport: 'udp'`, `match.path`, `match.headers`, `match.transport: 'udp'` or `'all'`, and the HTTP-only controls `basicAuth`, `jwtAuth`, `rateLimit`, `challenge` and `websocket.allowedOrigins`. Use static targets for those.
 
 ### 🔀 Protocol-Specific Routing
 
@@ -588,6 +620,8 @@ const tcpOnlyRoute: IRouteConfig = {
 
 > **Note:** Omitting `protocol` (the default) matches any protocol. For TLS routes, protocol detection happens *after* TLS termination — during the initial SNI-based route match, `protocol` is not yet known and the route is allowed to match. The protocol restriction is enforced after the proxy peeks at the decrypted data.
 
+> **HTTP/3:** HTTP/3 requests arrive over QUIC on the UDP listener, so only routes that listen on UDP (`transport: 'udp'` or `'all'`) serve them, and a request only a TCP route serves is answered `421 Misdirected Request`; `protocol: 'quic'`, `'http3'`, `'http'` and an omitted `protocol` all match them. The QUIC connection itself is accepted under a UDP-listening route with `protocol: 'quic'`, `'http3'` or no `protocol`, or with `protocol: 'http'` and `action.udp.quic.enableHttp3`. Only routes with `enableHttp3` terminate HTTP/3; the others forward the QUIC connection raw.
+
 ### 🔒 Security Controls
 
 Comprehensive per-route security options:
@@ -619,14 +653,18 @@ Comprehensive per-route security options:
     },
 
     // Authentication
-    basicAuth: { users: [{ username: 'admin', password: 'secret' }] },
-    jwtAuth: { secret: 'your-jwt-secret', algorithm: 'HS256' }
+    basicAuth: { enabled: true, users: [{ username: 'admin', password: 'secret' }] },
+    jwtAuth: { enabled: true, secret: 'your-jwt-secret', algorithm: 'HS256' }
   }
 }
 ```
 
 Security options are configured directly on each route's `security` property — no separate helpers needed.
 
+`maxConnections` caps a route's concurrent connections across all listeners: an HTTP request or upgraded WebSocket holds a slot while it is in flight, and a raw TCP connection, a raw QUIC connection or a UDP session holds one for its lifetime. A connection above the cap is closed (HTTP requests get `429`).
+
+Basic auth, JWT auth, rate limits, challenges and `action.websocket.allowedOrigins` run in the HTTP layer only, so a route that enables one of them must serve HTTP. Validation refuses such a route when it is a socket-handler route, uses TLS passthrough, matches `protocol: 'tcp'`, or listens on UDP (`transport: 'udp'` or `'all'`) without `action.udp.quic.enableHttp3`.
+
 IP entries are validated against what the Rust engine can match, and an entry the engine would never match is refused:
 
 - **Security lists** (`ipAllowList` plain and domain-scoped, `ipBlockList`, `defaults.security`, `securityPolicy.blockedIps`/`blockedCidrs`): `*`, an IPv4 or IPv6 address in any textual form, or an address prefix such as `192.0.2.0/24` or `2001:db8::1/128` (prefix lengths up to 32 or 128; host bits may be set). Clients that arrive as IPv4-mapped IPv6 are matched as IPv4, so write `192.0.2.1`, not `::ffff:192.0.2.1`. Wildcards and ranges are refused.
@@ -778,6 +816,8 @@ const proxy = new SmartProxy({
 
 Inbound PROXY protocol is never enabled by the global trust list alone. Declare `match.inboundProxyProtocol` on the listener route with `mode: 'optional'` or `mode: 'required'`; omit it or use `mode: 'reject'` for direct-client listeners. A policy can define its own `trustedProxyIPs`; otherwise explicit `optional` and `required` policies inherit the global `trustedProxyIPs` list.
 
+On a UDP listener that serves QUIC, an `optional` or `required` policy puts a relay in front of the QUIC endpoint to read the PROXY v2 headers. A new source address gets a relay session only for a datagram that starts a QUIC connection (a long-header packet in a datagram of at least 1200 bytes) or continues one the endpoint issued (a client that moved to a new address); other datagrams are dropped. The relay holds at most 16,384 sessions and 256 per client IP address (the PROXY source IP behind a trusted proxy), and closes a session after about two minutes without traffic.
+
 ### 🏗️ Custom Certificate Provisioning
 
 Supply your own certificates or integrate with external certificate providers:
@@ -800,10 +840,13 @@ const proxy = new SmartProxy({
     };
   },
   certProvisionFallbackToAcme: true,  // Fall back to ACME if callback fails
+  acme: { email: 'ssl@example.com' }, // 'http01' and the fallback order through the built-in ACME client
   routes: [...]
 });
 ```
 
+`'http01'` and the ACME fallback order the domain's certificate through the Rust engine's ACME client, which answers the HTTP-01 challenge on `acme.port`. Both need `acme` with an `email`. The engine serves the issued certificate, and SmartProxy records its validity, so sweeps skip the domain until its renewal window. While a `certProvisionFunction` is set, the engine orders only on these requests and the provisioning sweeps own renewal. A failed order emits `certificate-failed` and starts the failure cooldown, and a failed `'http01'` order takes no ACME fallback. Certificates the engine issues are not passed to `certStore.save()`, so a restart orders them again.
+
 ### 💾 Consumer-Managed Certificate Storage
 
 SmartProxy **never writes certificates to disk**. Instead, you own all persistence through the `certStore` interface. This gives you full control — store certs in a database, cloud KMS, encrypted vault, or wherever makes sense for your infrastructure:
@@ -926,6 +969,8 @@ interface IRouteMatch {
 type TPortRange = number | Array<number | { from: number; to: number }>;
 ```
 
+> **Path and headers:** A TCP connection is routed by its port, SNI or `Host`, and client address before its requests are read; `path` and `headers` are matched for each HTTP request. A connection whose TLS a route terminates (or plain HTTP to a route without TLS) is admitted under that route while only its path or headers are unknown, and each request then goes to the route that matches it, under that route's security; a request no route serves is answered `502 No route matched`. A route with `path` or `headers` serves only HTTP, so other data on its connections is closed.
+
 ### Action Types
 
 | Type | Description |
@@ -976,6 +1021,13 @@ interface IRouteTls {
   ciphers?: string;
   honorCipherOrder?: boolean;
   sessionTimeout?: number;
+  backend?: IRouteBackendTls;       // Backend certificate verification (see "Backend TLS verification")
+}
+
+interface IRouteBackendTls {
+  rejectUnauthorized?: boolean;     // false accepts any backend certificate (default: verify)
+  ca?: string;                      // PEM certificates replacing the system root store
+  serverName?: string;              // SNI and checked name (default: requested domain, else target host)
 }
 ```
 
@@ -1189,6 +1241,9 @@ interface ISmartProxyOptions {
   trustedProxyIPs?: string[];               // Global trusted IP/CIDR list for explicit inbound policies
   sendProxyProtocol?: boolean;              // Send PROXY protocol to targets
 
+  // Default backend certificate verification; a route or target tls.backend replaces it
+  backendTls?: { ca?: string; rejectUnauthorized?: boolean };
+
   // Timeouts
   connectionTimeout?: number;               // Backend connection timeout (default: 60s)
   initialDataTimeout?: number;              // Initial data/SNI timeout (default: 60s)
@@ -1198,8 +1253,8 @@ interface ISmartProxyOptions {
   gracefulShutdownTimeout?: number;         // Shutdown grace period (default: 30s)
 
   // Connection limits
-  maxConnectionsPerIP?: number;             // Per-IP connection limit (default: 100)
-  connectionRateLimitPerMinute?: number;    // Per-IP rate limit (default: 300/min)
+  maxConnectionsPerIP?: number | null;      // Per-IP simultaneous connections (default: 100; null: no limit)
+  connectionRateLimitPerMinute?: number | null; // Per-IP new connections per minute (default: 300; null: no limit)
   securityPolicy?: {
     blockedIps?: string[];
     blockedCidrs?: string[];
@@ -1341,7 +1396,7 @@ try {
 
 ### Certificate Issues
 - ✅ Ensure domain DNS points to your server
-- ✅ Port 80 must be accessible for ACME HTTP-01 challenges
+- ✅ Port 80 (`acme.port`) must be reachable for ACME HTTP-01 challenges. When a route listens on that port, the proxy answers pending challenge requests there before route matching; otherwise it binds the port only while an order runs
 - ✅ Check DNS propagation with `dig` or `nslookup`
 - ✅ Verify the email in ACME configuration is valid
 - ✅ Use `getCertificateStatus('route-name')` to check cert state
@@ -1351,6 +1406,7 @@ try {
 - ✅ Verify security rules aren't blocking legitimate traffic
 - ✅ Test with `curl -v` for detailed connection output
 - ✅ Enable debug logging with `enableDetailedLogging: true`
+- ✅ A `502` from a TLS backend with a self-signed or private-CA certificate: set `tls.backend.ca` or `rejectUnauthorized: false` (see "Backend TLS verification")
 
 ### Rust Binary Not Found
 
@@ -1358,7 +1414,7 @@ SmartProxy searches for the Rust binary in this order:
 1. `rustBinaryPath` option in `ISmartProxyOptions`
 2. `SMARTPROXY_RUST_BINARY` environment variable
 3. Platform-specific npm package (`@push.rocks/smartproxy-linux-x64`, etc.)
-4. `dist_rust/rustproxy_linux_amd64_musl` / `dist_rust/rustproxy_linux_arm64_musl` relative to the package root (static musl binaries built by `tsrust` and shipped in the package; they run on glibc and musl hosts alike), then `dist_rust/rustproxy`
+4. `dist_rust/rustproxy_linux_amd64_musl` / `dist_rust/rustproxy_linux_arm64_musl` relative to the package root (static musl binaries built by `rsrepo` and shipped in the package; they run on glibc and musl hosts alike), then `dist_rust/rustproxy`
 5. Local dev build (`./rust/target/release/rustproxy`)
 6. System PATH (`rustproxy`)
 
@@ -1366,6 +1422,7 @@ SmartProxy searches for the Rust binary in this order:
 
 ### QUIC / HTTP3 Caveats
 - **GREASE frames are disabled.** The underlying h3 crate sends [GREASE frames](https://www.rfc-editor.org/rfc/rfc9114.html#frame-reserved) by default to test protocol extensibility. However, some HTTP/3 clients and servers don't properly ignore unknown frame types, causing 400/500 errors or stream hangs ([h3#206](https://github.com/hyperium/h3/issues/206)). SmartProxy disables GREASE on both the server side (for incoming H3 requests) and the client side (for H3 backend connections) to maximize compatibility.
+- **Raw QUIC routes open a TCP connection per stream.** A route without `enableHttp3` forwards each bidirectional QUIC stream to its first target over its own TCP connection: plain with `tls.mode: 'terminate'`, verified TLS with `'terminate-and-reencrypt'` (see [Backend TLS verification](#backend-tls-verification)). A stream that sees no data for 60 seconds, counting the backend connect and handshake, is closed.
 - **Route security follows the SNI.** Before the QUIC handshake the client's hostname is unknown, so only a route that matches every hostname has its `security` applied there. Otherwise the route is chosen from the handshake's SNI, as on TCP, and that route's `security` applies; a connection without SNI matches no domain-restricted route. HTTP/3 requests are then routed and checked by their `:authority`.
 - **HTTP/3 is pre-release.** The h3 ecosystem (h3 0.0.8, h3-quinn 0.0.10, quinn 0.11) is still pre-1.0. Expect rough edges.
 
@@ -1373,7 +1430,7 @@ SmartProxy searches for the Rust binary in this order:
 - ✅ Use NFTables forwarding for high-traffic routes (Linux only)
 - ✅ Enable connection keep-alive where appropriate
 - ✅ Use `getMetrics()` and `getStatistics()` to identify bottlenecks
-- ✅ Adjust `maxConnectionsPerIP` and `connectionRateLimitPerMinute` based on your workload
+- ✅ Adjust `maxConnectionsPerIP` and `connectionRateLimitPerMinute` based on your workload. Both count connections per source IP as the listener sees it, before the SNI or any request is read. Behind a reverse proxy that does not send PROXY protocol (such as an HTTP hop that pools its backend connections), every client arrives from the proxy's address and shares one budget; set the limits to `null` there to turn them off and enforce them at the edge that sees the real clients. Omitting a limit keeps its default; `0`, negative and non-integer values are refused, `0` never read as "no limit".
 - ✅ Use `passthrough` TLS mode when backend can handle TLS directly
 
 ## 🏆 Best Practices

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartproxy',
-  version: '30.0.1',
+  version: '31.0.0',
   description: 'A powerful proxy package with unified route-based configuration for high traffic management. Features include SSL/TLS support, flexible routing patterns, WebSocket handling, advanced security options, and automatic ACME certificate management.'
 }

package/ts/index.ts

@@ -7,7 +7,7 @@ export { SmartProxy } from './proxies/smart-proxy/index.js';
 export { SharedRouteManager as RouteManager } from './core/routing/route-manager.js';
 
 // Export smart-proxy models
-export type { ISmartProxyOptions, ISmartProxySecurityPolicy, ISmartProxyChallengeOptions, IConnectionRecord, IRouteConfig, IRouteMatch, IRouteAction, IRouteFixedResponse, IRouteTls, IRouteContext, TDatagramHandler, IDatagramInfo, IActiveConnectionSnapshot, IActiveConnectionSnapshotOptions, IActiveConnectionSnapshotPage } from './proxies/smart-proxy/models/index.js';
+export type { ISmartProxyOptions, ISmartProxySecurityPolicy, ISmartProxyChallengeOptions, IConnectionRecord, IRouteConfig, IRouteMatch, IRouteAction, IRouteFixedResponse, IRouteTls, IRouteBackendTls, IRouteContext, TDatagramHandler, IDatagramInfo, IActiveConnectionSnapshot, IActiveConnectionSnapshotOptions, IActiveConnectionSnapshotPage } from './proxies/smart-proxy/models/index.js';
 export type { TSmartProxyCertProvisionObject, ICertProvisionEventComms, ICertificateIssuedEvent, ICertificateFailedEvent } from './proxies/smart-proxy/models/interfaces.js';
 export * from './proxies/smart-proxy/utils/index.js';
 

package/ts/proxies/index.ts

@@ -7,4 +7,4 @@ export { SmartProxy } from './smart-proxy/index.js';
 export { SharedRouteManager as SmartProxyRouteManager } from '../core/routing/route-manager.js';
 export * from './smart-proxy/utils/index.js';
 // Export smart-proxy models except IAcmeOptions
-export type { ISmartProxyOptions, IConnectionRecord, IRouteConfig, IRouteMatch, IRouteAction, IRouteTls, IRouteContext } from './smart-proxy/models/index.js';
+export type { ISmartProxyOptions, IConnectionRecord, IRouteConfig, IRouteMatch, IRouteAction, IRouteTls, IRouteBackendTls, IRouteContext } from './smart-proxy/models/index.js';

package/ts/proxies/smart-proxy/models/interfaces.ts

@@ -27,7 +27,7 @@ export interface ISmartProxyCertStore {
   /** Remove a cert (optional) */
   remove?: (domain: string) => Promise<void>;
 }
-import type { IRouteConfig } from './route-types.js';
+import type { IRouteBackendTls, IRouteConfig } from './route-types.js';
 
 export interface ISmartProxySecurityPolicy {
   blockedIps?: string[];
@@ -147,6 +147,12 @@ export interface ISmartProxyOptions {
   trustedProxyIPs?: string[];  // Global trusted IP/CIDR list for inbound PROXY protocol
   sendProxyProtocol?: boolean;  // Global option to send PROXY protocol to all targets
 
+  /**
+   * Default verification of TLS backends; a route's or target's `tls.backend` replaces it.
+   * `serverName` belongs to routes and targets.
+   */
+  backendTls?: Omit<IRouteBackendTls, 'serverName'>;
+
   // Global/default settings
   defaults?: {
     target?: {
@@ -199,8 +205,16 @@ export interface ISmartProxyOptions {
   enableRandomizedTimeouts?: boolean; // Randomize timeouts slightly to prevent thundering herd
 
   // Rate limiting and security
-  maxConnectionsPerIP?: number; // Maximum simultaneous connections from a single IP
-  connectionRateLimitPerMinute?: number; // Max new connections per minute from a single IP
+  /**
+   * Maximum simultaneous connections from a single source IP. Omitted: 100. `null`: no per-IP
+   * limit. Must be a positive integer otherwise; 0 and negative values are refused.
+   */
+  maxConnectionsPerIP?: number | null;
+  /**
+   * Maximum new connections per minute from a single source IP. Omitted: 300. `null`: no per-IP
+   * rate limit. Must be a positive integer otherwise; 0 and negative values are refused.
+   */
+  connectionRateLimitPerMinute?: number | null;
   securityPolicy?: ISmartProxySecurityPolicy; // Global ingress block policy, enforced before routing
 
   /** Runtime-only challenge enforcement settings. Never store this in route configs. */

package/ts/proxies/smart-proxy/models/route-types.ts

@@ -134,6 +134,30 @@ export interface IRouteTls {
   ciphers?: string;                // OpenSSL cipher string
   honorCipherOrder?: boolean;      // Use server's cipher preferences
   sessionTimeout?: number;         // TLS session timeout in seconds
+  backend?: IRouteBackendTls;      // How the proxy verifies a TLS backend (terminate-and-reencrypt, TLS targets, HTTP/3)
+}
+
+/**
+ * Verification of a TLS backend the proxy connects to.
+ *
+ * The whole object applies: a target's `tls.backend`, else the route's `action.tls.backend`,
+ * else the proxy-wide `backendTls`, else the system root store. Without `ca` or
+ * `rejectUnauthorized: false`, a self-signed or private-CA backend fails verification.
+ */
+export interface IRouteBackendTls {
+  /** `false` accepts any backend certificate (default: verify) */
+  rejectUnauthorized?: boolean;
+  /**
+   * PEM certificates that replace the system root store for this backend, like Node's `ca`.
+   * A certificate is trusted as an issuer, so a self-signed backend certificate must not be a
+   * CA certificate (`basicConstraints CA:TRUE`).
+   */
+  ca?: string;
+  /**
+   * Name sent as SNI and checked against the backend certificate. Defaults to the requested
+   * domain on routes with named domains, else the backend host.
+   */
+  serverName?: string;
 }
 
 /**
@@ -169,7 +193,10 @@ export interface IRouteSecurity {
   // Connection limits
   maxConnections?: number;      // Maximum concurrent connections
   
-  // Authentication
+  /**
+   * @deprecated Not supported: route validation refuses a route that sets it.
+   * Use basicAuth or jwtAuth.
+   */
   authentication?: IRouteAuthentication;
   
   // Rate limiting

package/ts/proxies/smart-proxy/models/rust-types.ts

@@ -64,7 +64,15 @@ export interface IRustRouteValidationErrorData {
   routes: IRustRouteValidationIssue[];
 }
 
-export interface IRustAcmeOptions extends Omit<IAcmeOptions, 'routeForwards'> {}
+export interface IRustAcmeOptions extends Omit<IAcmeOptions, 'routeForwards'> {
+  /**
+   * Whether the engine orders certificates for `certificate: 'auto'` routes at start
+   * and renews them on its own timer (default: true). SmartProxy sets it to false when
+   * a `certProvisionFunction` owns provisioning: the engine then orders a certificate
+   * only when `provisionCertificate` asks for one.
+   */
+  autoProvision?: boolean;
+}
 
 export interface IRustChallengeOptions extends Required<Pick<
   ISmartProxyChallengeOptions,
@@ -76,6 +84,7 @@ export interface IRustProxyOptions {
   preserveSourceIp?: boolean;
   trustedProxyIPs?: string[];
   sendProxyProtocol?: boolean;
+  backendTls?: ISmartProxyOptions['backendTls'];
   defaults?: IRustDefaultConfig;
   connectionTimeout?: number;
   initialDataTimeout?: number;
@@ -93,8 +102,10 @@ export interface IRustProxyOptions {
   enableDetailedLogging?: boolean;
   enableTlsDebugLogging?: boolean;
   enableRandomizedTimeouts?: boolean;
-  maxConnectionsPerIp?: number;
-  connectionRateLimitPerMinute?: number;
+  /** `null`: no per-IP limit (the engine's `None`). */
+  maxConnectionsPerIp?: number | null;
+  /** `null`: no per-IP rate limit (the engine's `None`). */
+  connectionRateLimitPerMinute?: number | null;
   keepAliveTreatment?: ISmartProxyOptions['keepAliveTreatment'];
   keepAliveInactivityMultiplier?: number;
   extendedKeepAliveLifetime?: number;
@@ -119,6 +130,13 @@ export interface IRustCertificateStatus {
   isValid: boolean;
 }
 
+/** A certificate the engine ordered through ACME and now serves. */
+export interface IRustProvisionedCertificate {
+  domain: string;
+  /** The issued certificate chain in PEM; the private key stays in the engine. */
+  cert: string;
+}
+
 export interface IRustThroughputSample {
   timestampMs: number;
   bytesIn: number;

package/ts/proxies/smart-proxy/rust-proxy-bridge.ts

@@ -3,6 +3,7 @@ import { logger } from '../../core/utils/logger.js';
 import {
   RUST_ROUTE_VALIDATION_ERROR_CODE,
   type IRustCertificateStatus,
+  type IRustProvisionedCertificate,
   type IRustChallengeOptions,
   type IRustMetricsSnapshot,
   type IRustProxyOptions,
@@ -105,7 +106,7 @@ type TSmartProxyCommands = {
   getStatistics:           { params: Record<string, never>;              result: IRustStatistics };
   getActiveConnectionSnapshots: { params: IActiveConnectionSnapshotOptions; result: IActiveConnectionSnapshot[] };
   getActiveConnectionSnapshotPage: { params: IActiveConnectionSnapshotOptions; result: IActiveConnectionSnapshotPage };
-  provisionCertificate:    { params: { routeName: string };              result: void };
+  provisionCertificate:    { params: { routeName: string; domain?: string }; result: IRustProvisionedCertificate };
   renewCertificate:        { params: { routeName: string };              result: void };
   getCertificateStatus:    { params: { routeName: string };              result: IRustCertificateStatus | null };
   getListeningPorts:       { params: Record<string, never>;              result: { ports: number[] } };
@@ -302,8 +303,17 @@ export class RustProxyBridge extends plugins.EventEmitter {
     return this.bridge.sendCommand('getActiveConnectionSnapshotPage', options);
   }
 
-  public async provisionCertificate(routeName: string): Promise<void> {
-    await this.bridge.sendCommand('provisionCertificate', { routeName });
+  /**
+   * Order a certificate through the engine's ACME client: for `domain`, which the
+   * route must serve, or else for the route's first domain. `timeoutMs` overrides
+   * the bridge request timeout; an order can take minutes.
+   */
+  public async provisionCertificate(
+    routeName: string,
+    domain?: string,
+    timeoutMs?: number,
+  ): Promise<IRustProvisionedCertificate> {
+    return this.bridge.sendCommand('provisionCertificate', { routeName, domain }, { timeoutMs });
   }
 
   public async renewCertificate(routeName: string): Promise<void> {