@stacksjs/rpx 0.11.14 → 0.11.16

package/src/on-demand.ts

@@ -0,0 +1,264 @@
+/**
+ * On-demand TLS for rpx: issue a real (Let's Encrypt, http-01) certificate for
+ * an unknown host the first time it's needed, gated by an `ask` callback and/or
+ * an `allowedSuffixes` allowlist.
+ *
+ * ## The Bun limitation this works around (verified on Bun 1.3.14 + 1.4.0)
+ *
+ * Bun.serve has **no working `SNICallback`**, and `server.reload({ tls })` does
+ * **NOT** update certificates at runtime. So rpx cannot mint a cert *during* the
+ * TLS handshake (the way Caddy's on-demand TLS does). Instead this manager
+ * implements on-demand as **ask-gated issuance + listener recreate**:
+ *
+ *   - rpx serves the ACME `http-01` challenge from its own `:80` listener (same
+ *     process, so the challenge token is reachable the instant we register it).
+ *   - issuance is triggered before the HTTPS request — either reactively from
+ *     the `:80` handler (first plaintext hit for the host), or programmatically
+ *     via {@link OnDemandCertManager.ensureCert} (e.g. a tunnel server
+ *     pre-warming a subdomain's cert at registration time).
+ *   - once a cert is issued it's written to `certsDir` and added to the live SNI
+ *     set; the manager then asks its host to rebuild the `:443` listener so the
+ *     new cert is actually served (a sub-second `server.stop()` + re-`Bun.serve`).
+ *
+ * Concurrency: per-host in-flight de-dupe means N concurrent `ensureCert(host)`
+ * calls drive exactly one ACME order. Failures are logged and negatively cached
+ * for a short window so we don't hammer Let's Encrypt (which is rate-limited).
+ */
+import type { Http01Store, ObtainCertificateOptions, ObtainCertificateResult } from '@stacksjs/tlsx'
+import type { OnDemandTlsConfig } from './types'
+import type { SniTlsEntry } from './sni'
+import * as fsp from 'node:fs/promises'
+import * as path from 'node:path'
+import { defaultHttp01Store, obtainCertificate } from '@stacksjs/tlsx'
+import { debugLog } from './utils'
+
+/**
+ * The issuance function the manager calls. Defaults to tlsx's
+ * {@link obtainCertificate}; tests inject a stub so the suite never touches
+ * Let's Encrypt.
+ */
+export type CertIssuer = (options: ObtainCertificateOptions) => Promise<ObtainCertificateResult>
+
+export interface OnDemandCertManagerOptions {
+  /** Resolved on-demand config (already merged with defaults). */
+  config: OnDemandTlsConfig
+  /** Where issued PEMs are written / read. Required (resolved by the caller). */
+  certsDir: string
+  /** Initial SNI set to seed from (e.g. productionCerts already on disk). */
+  initial?: SniTlsEntry[]
+  /**
+   * Called after a new cert is added to the SNI set so the host can rebuild its
+   * `:443` listener (Bun can't hot-update tls — see file header).
+   */
+  onCertAdded?: (entries: SniTlsEntry[]) => void | Promise<void>
+  /** http-01 challenge store rpx's `:80` listener serves from. */
+  http01Store?: Http01Store
+  /** Inject the issuer (tests stub this). Defaults to tlsx `obtainCertificate`. */
+  issuer?: CertIssuer
+  verbose?: boolean
+  /** How long to negatively-cache a failed host before retrying. Default 60s. */
+  negativeCacheMs?: number
+}
+
+const DEFAULT_NEGATIVE_CACHE_MS = 60_000
+
+/**
+ * True if `host` is covered by the `allowedSuffixes` allowlist: it equals a
+ * suffix, or is a subdomain of one (`a.example.com` for suffix `example.com`).
+ */
+export function matchesAllowedSuffix(host: string, suffixes: string[] | undefined): boolean {
+  if (!suffixes || suffixes.length === 0)
+    return false
+  return suffixes.some((s) => {
+    const suffix = s.startsWith('.') ? s.slice(1) : s
+    return host === suffix || host.endsWith(`.${suffix}`)
+  })
+}
+
+/** Strict-ish hostname guard so we never feed junk Host headers into ACME. */
+export function isLikelyHostname(host: string): boolean {
+  if (!host || host.length > 253)
+    return false
+  if (host.includes('/') || host.includes(':') || host.includes(' '))
+    return false
+  // No wildcards (http-01 can't do them) and must contain a dot (a real FQDN).
+  if (host.startsWith('*'))
+    return false
+  return /^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,}$/i.test(host)
+}
+
+/**
+ * Holds the live SNI cert set and lazily issues certs for approved hosts.
+ *
+ * The set is keyed by SNI server name; `ensureCert(host)` is the entry point for
+ * both the reactive `:80` path and programmatic pre-warming.
+ */
+export class OnDemandCertManager {
+  private readonly config: OnDemandTlsConfig
+  private readonly certsDir: string
+  private readonly onCertAdded?: (entries: SniTlsEntry[]) => void | Promise<void>
+  private readonly http01Store: Http01Store
+  private readonly issuer: CertIssuer
+  private readonly verbose: boolean
+  private readonly negativeCacheMs: number
+
+  /** Live SNI set, keyed by server name. */
+  private readonly certs = new Map<string, SniTlsEntry>()
+  /** In-flight issuances, keyed by host — de-dupes concurrent ensureCert calls. */
+  private readonly inFlight = new Map<string, Promise<boolean>>()
+  /** host → epoch-ms until which we refuse to retry after a failure. */
+  private readonly negativeCache = new Map<string, number>()
+
+  constructor(opts: OnDemandCertManagerOptions) {
+    this.config = opts.config
+    this.certsDir = opts.certsDir
+    this.onCertAdded = opts.onCertAdded
+    this.http01Store = opts.http01Store ?? defaultHttp01Store
+    this.issuer = opts.issuer ?? obtainCertificate
+    this.verbose = opts.verbose ?? false
+    this.negativeCacheMs = opts.negativeCacheMs ?? DEFAULT_NEGATIVE_CACHE_MS
+    for (const e of opts.initial ?? [])
+      this.certs.set(e.serverName, e)
+  }
+
+  /** The http-01 store rpx's `:80` listener must serve challenge tokens from. */
+  get challengeStore(): Http01Store {
+    return this.http01Store
+  }
+
+  /** A snapshot of the current SNI set for `Bun.serve({ tls })`. */
+  sniEntries(): SniTlsEntry[] {
+    return Array.from(this.certs.values())
+  }
+
+  /** True if a usable cert for `host` is already loaded in the live set. */
+  hasCert(host: string): boolean {
+    return this.certs.has(host)
+  }
+
+  /**
+   * Decide whether rpx may issue a cert for `host`. A host is approved when the
+   * `allowedSuffixes` allowlist matches OR `ask(host)` resolves truthy. With
+   * neither configured, every host is refused (fail-closed, anti-abuse).
+   */
+  async isApproved(host: string): Promise<boolean> {
+    if (!isLikelyHostname(host))
+      return false
+    if (matchesAllowedSuffix(host, this.config.allowedSuffixes))
+      return true
+    if (this.config.ask) {
+      try {
+        return await this.config.ask(host)
+      }
+      catch (err) {
+        debugLog('on-demand', `ask(${host}) threw: ${(err as Error).message}`, this.verbose)
+        return false
+      }
+    }
+    return false
+  }
+
+  /**
+   * Ensure a cert exists for `host`, issuing one via ACME http-01 if needed.
+   *
+   * No-ops (resolves `true`) when a cert is already loaded. Otherwise checks
+   * approval, then drives issuance — de-duping concurrent calls for the same
+   * host so only one ACME order runs. Resolves `false` when refused or on a
+   * negatively-cached failure. Never throws; errors are logged + cached.
+   */
+  async ensureCert(host: string): Promise<boolean> {
+    if (!this.config.enabled)
+      return false
+    if (this.certs.has(host))
+      return true
+
+    const inFlight = this.inFlight.get(host)
+    if (inFlight)
+      return inFlight
+
+    const until = this.negativeCache.get(host)
+    if (until !== undefined && Date.now() < until) {
+      debugLog('on-demand', `${host} negatively cached for ${until - Date.now()}ms`, this.verbose)
+      return false
+    }
+
+    const promise = this.issue(host).finally(() => {
+      this.inFlight.delete(host)
+    })
+    this.inFlight.set(host, promise)
+    return promise
+  }
+
+  private async issue(host: string): Promise<boolean> {
+    // A concurrent caller may have already loaded it while we were queued.
+    if (this.certs.has(host))
+      return true
+
+    // Maybe it's already on disk (issued by a prior run) — adopt without ACME.
+    if (await this.loadFromDisk(host))
+      return true
+
+    if (!(await this.isApproved(host))) {
+      debugLog('on-demand', `refused issuance for ${host} (not approved)`, this.verbose)
+      return false
+    }
+
+    try {
+      debugLog('on-demand', `issuing cert for ${host} (staging=${this.config.staging ?? false})`, this.verbose)
+      const result = await this.issuer({
+        domains: [host],
+        method: 'http-01',
+        http01Store: this.http01Store,
+        email: this.config.email,
+        staging: this.config.staging,
+      })
+      await this.persist(host, result.fullChainPem, result.keyPem)
+      const entry: SniTlsEntry = { serverName: host, cert: result.fullChainPem, key: result.keyPem }
+      this.certs.set(host, entry)
+      this.negativeCache.delete(host)
+      debugLog('on-demand', `issued + installed cert for ${host}`, this.verbose)
+      await this.onCertAdded?.(this.sniEntries())
+      return true
+    }
+    catch (err) {
+      this.negativeCache.set(host, Date.now() + this.negativeCacheMs)
+      debugLog('on-demand', `issuance for ${host} failed: ${(err as Error).message}`, this.verbose)
+      return false
+    }
+  }
+
+  /** Try to load an already-present `<host>.{crt,key}` pair from `certsDir`. */
+  private async loadFromDisk(host: string): Promise<boolean> {
+    const { certPath, keyPath } = this.pathsFor(host)
+    try {
+      const [cert, key] = await Promise.all([
+        fsp.readFile(certPath, 'utf8'),
+        fsp.readFile(keyPath, 'utf8'),
+      ])
+      const entry: SniTlsEntry = { serverName: host, cert, key }
+      this.certs.set(host, entry)
+      debugLog('on-demand', `adopted existing on-disk cert for ${host}`, this.verbose)
+      await this.onCertAdded?.(this.sniEntries())
+      return true
+    }
+    catch {
+      return false
+    }
+  }
+
+  private pathsFor(host: string): { certPath: string, keyPath: string } {
+    return {
+      certPath: path.join(this.certsDir, `${host}.crt`),
+      keyPath: path.join(this.certsDir, `${host}.key`),
+    }
+  }
+
+  private async persist(host: string, certPem: string, keyPem: string): Promise<void> {
+    await fsp.mkdir(this.certsDir, { recursive: true }).catch(() => {})
+    const { certPath, keyPath } = this.pathsFor(host)
+    await Promise.all([
+      fsp.writeFile(certPath, certPem, 'utf8'),
+      fsp.writeFile(keyPath, keyPem, { encoding: 'utf8', mode: 0o600 }),
+    ])
+  }
+}

package/src/proxy-handler.ts

@@ -33,9 +33,35 @@ export interface ProxyRoute {
   pathRewrites?: PathRewrite[]
   /** When set, serve files from a local directory instead of proxying. */
   static?: ResolvedStaticRoute
+  /**
+   * Path prefix this route is mounted under (e.g. `/docs`). Used together with
+   * {@link stripBasePathPrefix} to map request paths to the target. `/` (the
+   * host default) is a no-op.
+   */
+  basePath?: string
+  /**
+   * Whether to strip {@link basePath} from the request pathname before
+   * resolving the target.
+   *
+   * - Static routes default to `true`: a directory mounted at `/docs` serves
+   *   its own `index.html` for `/docs` and `<root>/guide` for `/docs/guide`.
+   * - Proxy routes default to `false`: most apps own their namespace (an app
+   *   mounted at `/api` expects to still see `/api/...`), matching rpx's
+   *   `PathRewrite.stripPrefix` default and nginx `proxy_pass` (no trailing
+   *   slash) behavior.
+   *
+   * When unset, the per-transport default above applies.
+   */
+  stripBasePathPrefix?: boolean
 }
 
-export type GetRoute = (hostname: string) => ProxyRoute | undefined
+/**
+ * Resolve a route for an incoming request. `pathname` enables path-based
+ * routing within a host (e.g. `/api/*` → app, `/docs*` → static dir). Callers
+ * that only route by host can ignore the second argument — it's optional so
+ * existing host-only `getRoute` callbacks remain valid.
+ */
+export type GetRoute = (hostname: string, pathname: string) => ProxyRoute | undefined
 
 export type ProxyFetchHandler = (req: Request, server?: ProxyServer) => Promise<Response | undefined>
 
@@ -79,6 +105,24 @@ function extractHostname(req: Request): string {
   return hostHeader.split(':')[0]
 }
 
+/**
+ * Strip the route's mount prefix (`basePath`) from a request pathname so a
+ * target mounted under `/docs` sees `/` for `/docs` and `/guide` for
+ * `/docs/guide`. A `/` (or empty) base strips nothing. The result always keeps
+ * a leading `/`.
+ */
+export function stripBasePath(pathname: string, basePath?: string): string {
+  if (!basePath || basePath === '/')
+    return pathname
+  if (pathname === basePath)
+    return '/'
+  if (pathname.startsWith(`${basePath}/`)) {
+    const rest = pathname.slice(basePath.length)
+    return rest === '' ? '/' : rest
+  }
+  return pathname
+}
+
 /**
  * Resolve the upstream target (`host` + `path`) for a request against a route,
  * applying any matching path rewrite.
@@ -86,9 +130,13 @@ function extractHostname(req: Request): string {
 function resolveTarget(req: Request, route: ProxyRoute, verbose?: boolean): { targetHost: string, targetPath: string, search: string } {
   const url = new URL(req.url)
   let targetHost = route.sourceHost ?? ''
-  let targetPath = url.pathname
+  // Proxy backends preserve their mount prefix by default (most apps own their
+  // `/api` namespace), opting in to stripping via `stripBasePathPrefix`.
+  // Explicit `pathRewrites` still apply on top of this.
+  const stripBase = route.stripBasePathPrefix ?? false
+  let targetPath = stripBase ? stripBasePath(url.pathname, route.basePath) : url.pathname
 
-  const rewriteMatch = resolvePathRewrite(url.pathname, route.pathRewrites)
+  const rewriteMatch = resolvePathRewrite(targetPath, route.pathRewrites)
   if (rewriteMatch) {
     targetHost = rewriteMatch.targetHost
     targetPath = rewriteMatch.targetPath
@@ -110,15 +158,20 @@ export function createProxyFetchHandler(getRoute: GetRoute, verbose?: boolean):
     const url = new URL(req.url)
     const hostname = extractHostname(req)
 
-    const route = getRoute(hostname)
+    const route = getRoute(hostname, url.pathname)
     if (!route) {
       debugLog('request', `No route found for host: ${hostname}`, verbose)
       return new Response(`No proxy configured for ${hostname}`, { status: 404 })
     }
 
-    // Static file serving short-circuits everything else.
-    if (route.static)
-      return serveStaticFile(url.pathname, route.static)
+    // Static file serving short-circuits everything else. Strip the route's
+    // mount prefix (default for static) so a dir mounted at `/docs` serves its
+    // own root for `/docs`.
+    if (route.static) {
+      const strip = route.stripBasePathPrefix ?? true
+      const staticPath = strip ? stripBasePath(url.pathname, route.basePath) : url.pathname
+      return serveStaticFile(staticPath, route.static)
+    }
 
     // WebSocket upgrade: hand the socket to Bun and dial the upstream on open.
     if (req.headers.get('upgrade')?.toLowerCase() === 'websocket') {

package/src/registry.ts

@@ -27,6 +27,14 @@ export interface RegistryEntry {
   /** Upstream `host:port`. Optional when `static` is set. */
   from?: string
   to: string
+  /**
+   * Optional path prefix this route owns under the host `to` (e.g. `'/api'`).
+   * Enables several routes to share one host, each claiming a different path
+   * (`/api` → app, `/docs` → static dir, `/` → public). Omitted (or `'/'`)
+   * means the route is the host default and behaves exactly like host-only
+   * routing did before path routing existed.
+   */
+  path?: string
   /**
    * Optional. PID of the long-running process that owns this entry. When set,
    * the daemon's PID-GC reaps the entry the moment that process dies. Omit
@@ -96,10 +104,13 @@ function isValidEntry(value: unknown): value is RegistryEntry {
   const hasFrom = typeof e.from === 'string' && e.from.length > 0
   const hasStatic = typeof e.static === 'string'
     || (!!e.static && typeof e.static === 'object' && typeof (e.static as StaticRouteConfig).dir === 'string')
+  // path is optional; when present it must be a string.
+  const pathOk = e.path === undefined || typeof e.path === 'string'
   return (
     typeof e.id === 'string' && isValidId(e.id)
     && (hasFrom || hasStatic)
     && typeof e.to === 'string' && e.to.length > 0
+    && pathOk
     && pidOk
     && typeof e.createdAt === 'string'
   )
@@ -275,6 +286,7 @@ export function watchRegistry(
           id: entry.id,
           from: entry.from,
           to: entry.to,
+          path: entry.path,
           pid: entry.pid,
           pathRewrites: entry.pathRewrites,
           cleanUrls: entry.cleanUrls,

package/src/start.ts

@@ -22,7 +22,8 @@ import { DefaultPortManager, findAvailablePort, isPortInUse } from './port-manag
 import { ProcessManager } from './process-manager'
 import { createProxyFetchHandler, createProxyWebSocketHandler } from './proxy-handler'
 import type { ProxyRoute, ProxyServer as ProxyServerLike } from './proxy-handler'
-import { isWildcardPattern, matchHost } from './host-match'
+import { isWildcardPattern } from './host-match'
+import { buildHostRoutes, matchHostRoute, normalizePathPrefix } from './host-routes'
 import { resolveStaticRoute } from './static-files'
 import { debugLog, getSudoPassword, safeStringify } from './utils'
 
@@ -849,6 +850,7 @@ export function startProxy(options: ProxyOption): void {
         id: mergedOptions.id,
         from: mergedOptions.from,
         to: mergedOptions.to,
+        path: mergedOptions.path,
         cleanUrls: mergedOptions.cleanUrls,
         changeOrigin: mergedOptions.changeOrigin,
         pathRewrites: mergedOptions.pathRewrites,
@@ -996,6 +998,7 @@ export async function startProxies(options?: ProxyOptions): Promise<void> {
           id: p.id,
           from: p.from,
           to: p.to,
+          path: p.path,
           cleanUrls: p.cleanUrls ?? mergedOptions.cleanUrls,
           changeOrigin: p.changeOrigin ?? mergedOptions.changeOrigin,
           pathRewrites: p.pathRewrites,
@@ -1004,6 +1007,7 @@ export async function startProxies(options?: ProxyOptions): Promise<void> {
           id: mergedOptions.id,
           from: mergedOptions.from,
           to: mergedOptions.to,
+          path: mergedOptions.path,
           cleanUrls: mergedOptions.cleanUrls,
           changeOrigin: mergedOptions.changeOrigin,
           pathRewrites: mergedOptions.pathRewrites,
@@ -1242,34 +1246,52 @@ export async function startProxies(options?: ProxyOptions): Promise<void> {
   if (sslConfig && proxyOptions.length > 1) {
     debugLog('proxies', `Creating shared HTTPS server for ${proxyOptions.length} domains`, verbose)
 
-    const routingTable = new Map<string, ProxyRoute>()
+    // Collect (host, path, route) tuples so several proxies can share one
+    // domain on different paths (e.g. `/api` → app, `/docs` → static dir,
+    // `/` → public). `buildHostRoutes` groups + longest-prefix-sorts them.
+    const routeEntries: Array<{ host: string, path?: string, route: ProxyRoute }> = []
+    const seenDomains = new Set<string>()
 
     for (const option of proxyOptions) {
       const domain = option.to || 'rpx.localhost'
       const cleanUrls = option.cleanUrls || false
+      const routePath = option.path
+
+      const basePath = normalizePathPrefix(routePath)
 
       // Static-file route: serve a local directory instead of proxying.
       if (option.static) {
-        routingTable.set(domain, {
-          static: resolveStaticRoute(option.static, cleanUrls),
-          cleanUrls,
+        routeEntries.push({
+          host: domain,
+          path: routePath,
+          route: { static: resolveStaticRoute(option.static, cleanUrls), cleanUrls, basePath },
         })
-        debugLog('proxies', `Route: ${domain} → static ${typeof option.static === 'string' ? option.static : option.static.dir}`, verbose)
+        debugLog('proxies', `Route: ${domain}${routePath ?? ''} → static ${typeof option.static === 'string' ? option.static : option.static.dir}`, verbose)
       }
       else {
         const fromUrl = new URL(option.from?.startsWith('http') ? option.from : `http://${option.from}`)
-        routingTable.set(domain, {
-          sourceHost: fromUrl.host,
-          cleanUrls,
-          changeOrigin: option.changeOrigin || false,
-          pathRewrites: option.pathRewrites,
+        routeEntries.push({
+          host: domain,
+          path: routePath,
+          route: {
+            sourceHost: fromUrl.host,
+            cleanUrls,
+            changeOrigin: option.changeOrigin || false,
+            pathRewrites: option.pathRewrites,
+            basePath,
+          },
         })
-        debugLog('proxies', `Route: ${domain} → ${fromUrl.host}`, verbose)
+        debugLog('proxies', `Route: ${domain}${routePath ?? ''} → ${fromUrl.host}`, verbose)
       }
 
       // Ensure hosts file entries exist for non-localhost domains. A wildcard
       // domain (`*.example.com`) has no single hosts entry — skip it. Skipped
-      // entirely when hosts management is disabled (real-server mode).
+      // entirely when hosts management is disabled (real-server mode). Add each
+      // domain once even when several path-routes share it.
+      if (seenDomains.has(domain)) {
+        continue
+      }
+      seenDomains.add(domain)
       if (hostsEnabled && !isWildcardPattern(domain) && !domain.includes('localhost') && !domain.includes('127.0.0.1')) {
         try {
           const hostsExist = await checkHosts([domain], verbose)
@@ -1300,7 +1322,11 @@ export async function startProxies(options?: ProxyOptions): Promise<void> {
       return
     }
 
-    const sharedFetchHandler = createProxyFetchHandler(host => matchHost(routingTable, host), verbose)
+    const routingTable = buildHostRoutes(routeEntries)
+    const sharedFetchHandler = createProxyFetchHandler(
+      (host, pathname) => matchHostRoute(routingTable, host, pathname),
+      verbose,
+    )
     const sharedWsHandler = createProxyWebSocketHandler(verbose)
 
     try {

package/src/types.ts

@@ -57,6 +57,13 @@ export interface BaseProxyConfig {
    */
   from?: string // localhost:5173
   to: string // stacks.localhost
+  /**
+   * Optional path prefix this route owns under the host `to` (e.g. `'/api'`).
+   * Lets multiple routes share one host, each serving a different path —
+   * `/api` proxied to an app, `/docs` from a static dir, `/` from another.
+   * The longest matching prefix wins; omit (or `'/'`) for the host default.
+   */
+  path?: string
   start?: StartOptions
   pathRewrites?: PathRewrite[]
   /**
@@ -113,6 +120,60 @@ export interface ProductionTlsConfig {
   certsDir?: string
 }
 
+/**
+ * On-demand TLS: issue a real (Let's Encrypt, http-01) certificate for an
+ * unknown host the first time it's needed, gated by an `ask` callback and/or an
+ * `allowedSuffixes` allowlist to prevent abuse.
+ *
+ * ## Why this is "ask-gated issuance + listener recreate", not at-handshake
+ *
+ * Bun (verified on 1.3.14 + 1.4.0) has **no working SNICallback** and
+ * `server.reload({ tls })` does **not** update certs at runtime. So rpx cannot
+ * mint a cert during the TLS handshake the way Caddy's on-demand TLS does.
+ * Instead rpx:
+ *   1. Sees the first plaintext request for the host on its `:80` listener.
+ *   2. Asks `ask(host)` / checks `allowedSuffixes`; if approved, drives the
+ *      ACME http-01 flow (serving the challenge from its own `:80`).
+ *   3. Writes the PEMs into `certsDir` and rebuilds the `:443` listener with the
+ *      augmented SNI cert set (a sub-second `server.stop()` + re-`Bun.serve`).
+ * The subsequent HTTPS request then finds the freshly-issued cert.
+ *
+ * Issuance can also be triggered programmatically via the manager's
+ * `ensureCert(host)` (e.g. a tunnel server pre-warming a subdomain's cert on
+ * registration) so the cert exists before the first browser hit.
+ */
+export interface OnDemandTlsConfig {
+  /** Master switch. On-demand TLS is opt-in; default `false`. */
+  enabled?: boolean
+  /**
+   * Gate issuance for a given hostname. Return `true` to allow rpx to obtain a
+   * cert, `false` to refuse. Combined with {@link allowedSuffixes} (a host is
+   * approved if either the suffix allowlist matches OR `ask` returns true). If
+   * neither is provided, on-demand issuance refuses every host.
+   */
+  ask?: (host: string) => boolean | Promise<boolean>
+  /**
+   * Allowlist of domain suffixes that may be auto-issued without consulting
+   * `ask`. A host matches a suffix when it equals it or ends with `.<suffix>`
+   * (so `example.com` allows `example.com` and `a.example.com`).
+   */
+  allowedSuffixes?: string[]
+  /** Contact email for the ACME account (recommended by Let's Encrypt). */
+  email?: string
+  /**
+   * Use Let's Encrypt **staging** (untrusted but un-rate-limited) instead of
+   * production. Default `false` (real, trusted, rate-limited certs).
+   */
+  staging?: boolean
+  /**
+   * Directory where issued PEMs are written (`<host>.crt` / `<host>.key`) and
+   * from which existing certs are loaded. Should match the SNI `certsDir` so
+   * issued certs survive restarts. Defaults to the daemon's productionCerts
+   * `certsDir` when wired through the daemon.
+   */
+  certsDir?: string
+}
+
 export interface SharedProxyConfig {
   https: boolean | TlsOption
   cleanup: boolean | CleanupOptions
@@ -142,6 +203,11 @@ export interface SharedProxyConfig {
    * instead of the dev self-signed shared cert.
    */
   productionCerts?: ProductionTlsConfig
+  /**
+   * On-demand TLS: lazily issue a real cert for an unknown (but approved) host
+   * the first time it's needed. Opt-in — see {@link OnDemandTlsConfig}.
+   */
+  onDemandTls?: OnDemandTlsConfig
 }
 
 export type SharedProxyOptions = Partial<SharedProxyConfig>