@stacksjs/rpx 0.11.13 → 0.11.15

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/rpx",
   "type": "module",
-  "version": "0.11.13",
+  "version": "0.11.15",
   "description": "A modern and smart reverse proxy.",
   "author": "Chris Breuer <chris@stacksjs.org>",
   "license": "MIT",
@@ -69,7 +69,7 @@
   },
   "dependencies": {
     "@stacksjs/clapp": "^0.2.10",
-    "@stacksjs/tlsx": "^0.13.6"
+    "@stacksjs/tlsx": "^0.13.7"
   },
   "devDependencies": {
     "bunfig": "^0.15.6",

package/src/daemon-runner.ts

@@ -10,7 +10,7 @@
  *
  * The daemon's PID-GC reaps anything we miss if this process dies `kill -9`.
  */
-import type { PathRewrite } from './types'
+import type { PathRewrite, StaticRouteConfig } from './types'
 import * as fs from 'node:fs'
 import * as path from 'node:path'
 import * as process from 'node:process'
@@ -21,11 +21,14 @@ import { debugLog } from './utils'
 
 export interface DaemonRunnerProxy {
   id?: string
-  from: string
+  /** Upstream `host:port`. Optional when `static` is set. */
+  from?: string
   to: string
   cleanUrls?: boolean
   changeOrigin?: boolean
   pathRewrites?: PathRewrite[]
+  /** Serve a local directory for this route instead of proxying. */
+  static?: string | StaticRouteConfig
 }
 
 export interface DaemonRunnerOptions {
@@ -100,6 +103,7 @@ export async function runViaDaemon(opts: DaemonRunnerOptions): Promise<void> {
       cleanUrls: p.cleanUrls,
       changeOrigin: p.changeOrigin,
       pathRewrites: p.pathRewrites,
+      static: p.static,
     }, registryDir, verbose)
   }
 
@@ -111,8 +115,12 @@ export async function runViaDaemon(opts: DaemonRunnerOptions): Promise<void> {
     spawnEnv: opts.spawnEnv,
   })
 
-  for (const p of resolved)
-    log.success(`https://${p.to}  →  ${p.from}`)
+  for (const p of resolved) {
+    const target = p.static
+      ? `static ${typeof p.static === 'string' ? p.static : p.static.dir}`
+      : p.from
+    log.success(`https://${p.to}  →  ${target}`)
+  }
   log.info(`(via rpx daemon pid=${result.pid}; \`rpx daemon:status\` to inspect)`)
 
   if (opts.detached)

package/src/daemon.ts

@@ -16,8 +16,8 @@
  * paths are reachable without touching `~/.stacks/rpx` or :443.
  */
 /* eslint-disable no-console */
-import type { ProxyOptions, SSLConfig, TlsOption } from './types'
-import type { ProxyRoute } from './proxy-handler'
+import type { OnDemandTlsConfig, ProductionTlsConfig, ProxyOptions, SSLConfig, TlsOption } from './types'
+import type { ProxyRoute, ProxyServer as ProxyServerLike } from './proxy-handler'
 import { spawn as nodeSpawn } from 'node:child_process'
 import * as fsp from 'node:fs/promises'
 import { homedir } from 'node:os'
@@ -25,7 +25,11 @@ import * as path from 'node:path'
 import * as process from 'node:process'
 import { log } from './logger'
 import { checkExistingCertificates, generateCertificate } from './https'
-import { createProxyFetchHandler } from './proxy-handler'
+import { createProxyFetchHandler, createProxyWebSocketHandler } from './proxy-handler'
+import { matchHost } from './host-match'
+import { buildSniTlsConfig } from './sni'
+import { OnDemandCertManager } from './on-demand'
+import { resolveStaticRoute } from './static-files'
 import { gcStaleEntries, getRegistryDir, isPidAlive, readAll, watchRegistry } from './registry'
 import type { RegistryEntry } from './registry'
 import {
@@ -49,6 +53,18 @@ export interface DaemonOptions {
   hostname?: string
   /** TLS bootstrap options forwarded to httpsConfig. */
   https?: TlsOption
+  /**
+   * Production per-domain SNI certs (real PEMs on disk). When usable certs are
+   * found, the listener serves them per SNI server name instead of the dev
+   * self-signed shared cert.
+   */
+  productionCerts?: ProductionTlsConfig
+  /**
+   * On-demand TLS: lazily issue real certs for approved unknown hosts via ACME
+   * http-01 (served from this daemon's `:80` listener). Opt-in via `enabled`.
+   * Seeded with the `productionCerts`/`certsDir` certs already on disk.
+   */
+  onDemandTls?: OnDemandTlsConfig
   /** PID-GC interval in ms. Defaults to 5000. */
   gcIntervalMs?: number
 }
@@ -61,6 +77,13 @@ export interface DaemonHandle {
   httpsPort: number
   httpPort: number
   pidPath: string
+  /**
+   * Pre-warm an on-demand cert for `host` (issue it now if approved & missing,
+   * rebuilding the `:443` listener). Resolves `true` if a cert is available
+   * afterwards. No-op resolving `false` when on-demand TLS isn't enabled. Lets a
+   * tunnel server warm a subdomain's cert at registration time.
+   */
+  ensureCert: (host: string) => Promise<boolean>
 }
 
 const DEFAULT_GC_INTERVAL_MS = 5000
@@ -148,10 +171,18 @@ export async function releaseDaemonLock(rpxDir: string = getDaemonRpxDir()): Pro
  * fetch handler. The entry's `from` is normalized to `host:port`.
  */
 function entryToRoute(entry: RegistryEntry): ProxyRoute {
-  const fromUrl = new URL(entry.from.startsWith('http') ? entry.from : `http://${entry.from}`)
+  const cleanUrls = entry.cleanUrls ?? false
+  if (entry.static) {
+    return {
+      static: resolveStaticRoute(entry.static, cleanUrls),
+      cleanUrls,
+    }
+  }
+  const from = entry.from ?? 'localhost:1'
+  const fromUrl = new URL(from.startsWith('http') ? from : `http://${from}`)
   return {
     sourceHost: fromUrl.host,
-    cleanUrls: entry.cleanUrls ?? false,
+    cleanUrls,
     changeOrigin: entry.changeOrigin ?? false,
     pathRewrites: entry.pathRewrites,
   }
@@ -273,6 +304,9 @@ async function elevateDaemonToRoot(
           try { process.kill(pid, 'SIGTERM') }
           catch { /* EPERM — root-owned shared daemon */ }
         },
+        // On-demand issuance runs inside the elevated child's own runDaemon
+        // handle; this caller-side stub can't reach it directly.
+        ensureCert: () => Promise.resolve(false),
       }
     }
     // sudo exits fast when auth fails; while the daemon runs it stays alive.
@@ -295,6 +329,9 @@ async function elevateDaemonToRoot(
  * listeners are bound and the initial routing table is populated. Use
  * `handle.done` for the lifetime promise.
  */
+// `opts` IS used throughout; pickier's no-unused-vars mis-fires on this fn after
+// the on-demand serve refactor (its --fix would wrongly rename to `_opts`).
+// eslint-disable-next-line pickier/no-unused-vars
 export async function runDaemon(opts: DaemonOptions = {}): Promise<DaemonHandle> {
   const verbose = opts.verbose ?? false
   const rpxDir = opts.rpxDir ?? getDaemonRpxDir()
@@ -315,8 +352,10 @@ export async function runDaemon(opts: DaemonOptions = {}): Promise<DaemonHandle>
   const pidPath = await acquireDaemonLock(rpxDir)
 
   // Module-scoped state so the watcher and fetch handler share one routing view.
+  // Routing table keyed by host pattern. Lookup prefers an exact match, then
+  // the most-specific `*.suffix` wildcard (see `matchHost`).
   let routingTable = new Map<string, ProxyRoute>()
-  const getRoute = (host: string): ProxyRoute | undefined => routingTable.get(host)
+  const getRoute = (host: string): ProxyRoute | undefined => matchHost(routingTable, host)
 
   function rebuild(entries: RegistryEntry[]): void {
     const next = new Map<string, ProxyRoute>()
@@ -340,24 +379,101 @@ export async function runDaemon(opts: DaemonOptions = {}): Promise<DaemonHandle>
     debugLog('daemon', `DNS setup on start failed: ${err}`, verbose)
   })
 
-  const sslConfig = await bootstrapTls(opts, registryDir)
+  // Production per-domain SNI: serve real PEM certs (e.g. Let's Encrypt) keyed
+  // by server name on the one listener. Falls back to the dev shared cert when
+  // no usable production certs are configured.
+  let sniTls: Array<{ serverName: string, cert: string, key: string }> = []
+  if (opts.productionCerts) {
+    sniTls = await buildSniTlsConfig(opts.productionCerts, verbose)
+    if (verbose && sniTls.length > 0)
+      log.info(`SNI: serving ${sniTls.length} real cert(s): ${sniTls.map(e => e.serverName).join(', ')}`)
+  }
 
-  const httpsServer = Bun.serve({
-    port: httpsPort,
-    hostname,
-    tls: {
-      key: sslConfig.key,
-      cert: sslConfig.cert,
-      ca: sslConfig.ca,
+  const fetchHandler = createProxyFetchHandler(getRoute, verbose)
+  const wsHandler = createProxyWebSocketHandler(verbose)
+
+  // Bootstrap the dev shared cert once when there's no real SNI set, so a single
+  // SNI listener with on-demand can still answer hosts that aren't covered yet.
+  let devSslConfig: SSLConfig | null = null
+  if (sniTls.length === 0)
+    devSslConfig = await bootstrapTls(opts, registryDir)
+
+  // On-demand TLS manager (opt-in). Holds the live SNI set; lazily issues real
+  // certs for approved unknown hosts via ACME http-01 served from our :80
+  // listener (Bun can't issue at handshake time — see on-demand.ts header).
+  const onDemandCfg = opts.onDemandTls
+  const onDemand: OnDemandCertManager | null = onDemandCfg?.enabled
+    ? new OnDemandCertManager({
+        config: onDemandCfg,
+        certsDir: onDemandCfg.certsDir ?? opts.productionCerts?.certsDir ?? path.join(rpxDir, 'on-demand-certs'),
+        initial: sniTls,
+        verbose,
+        // A new cert was issued/adopted — rebuild :443 with the augmented set.
+        onCertAdded: (entries) => { void rebuildTls(entries) },
+      })
+    : null
+
+  /** Build the TLS option for Bun.serve from the current SNI set (or dev cert). */
+  function tlsFor(entries: Array<{ serverName: string, cert: string, key: string }>): unknown {
+    if (entries.length > 0)
+      return entries.map(e => ({ serverName: e.serverName, cert: e.cert, key: e.key }))
+    // No real certs: fall back to the dev self-signed shared cert.
+    return {
+      key: devSslConfig!.key,
+      cert: devSslConfig!.cert,
+      ca: devSslConfig!.ca,
       requestCert: false,
       rejectUnauthorized: false,
-    },
-    fetch: createProxyFetchHandler(getRoute, verbose),
-    error(err: Error) {
-      debugLog('daemon', `https server error: ${err}`, verbose)
-      return new Response(`Server Error: ${err.message}`, { status: 500 })
-    },
-  })
+    }
+  }
+
+  /** (Re)create the :443 listener. Factored so on-demand can rebuild it. */
+  function serveHttps(entries: Array<{ serverName: string, cert: string, key: string }>): ReturnType<typeof Bun.serve> {
+    return Bun.serve({
+      port: httpsPort,
+      hostname,
+      tls: tlsFor(entries) as any,
+      fetch(req: Request, server: unknown) {
+        return fetchHandler(req, server as ProxyServerLike)
+      },
+      websocket: wsHandler,
+      error(err: Error) {
+        debugLog('daemon', `https server error: ${err}`, verbose)
+        return new Response(`Server Error: ${err.message}`, { status: 500 })
+      },
+    })
+  }
+
+  let httpsServer = serveHttps(onDemand ? onDemand.sniEntries() : sniTls)
+
+  /**
+   * Bun has no working SNICallback and `server.reload({ tls })` does not update
+   * certs at runtime (verified Bun 1.3.14/1.4.0). So to serve a freshly-issued
+   * cert we tear the old listener down and re-bind with the augmented SNI set.
+   * The rebind is sub-second; if the OS hasn't freed the port yet we retry on a
+   * short async backoff. In-flight requests on the old listener drain
+   * (`stop(false)`). Only ever invoked from the (async) issuance callback.
+   */
+  async function rebuildTls(entries: Array<{ serverName: string, cert: string, key: string }>): Promise<void> {
+    if (stopped)
+      return
+    debugLog('daemon', `rebuilding :443 with ${entries.length} SNI cert(s)`, verbose)
+    httpsServer.stop(false)
+    let lastErr: unknown
+    for (let attempt = 0; attempt < 20 && !stopped; attempt++) {
+      try {
+        httpsServer = serveHttps(entries)
+        return
+      }
+      catch (err) {
+        // EADDRINUSE while the old socket releases — back off briefly, retry.
+        lastErr = err
+        await new Promise(resolve => setTimeout(resolve, 25))
+      }
+    }
+    // Could not rebind: the old listener is already down. Surface the failure.
+    log.error(`rpx: failed to rebuild :443 after issuing cert: ${(lastErr as Error)?.message}`)
+  }
 
   let httpServer: ReturnType<typeof Bun.serve> | null = null
   if (httpPort > 0) {
@@ -367,6 +483,22 @@ export async function runDaemon(opts: DaemonOptions = {}): Promise<DaemonHandle>
       fetch(req: Request) {
         const u = new URL(req.url)
         const host = (req.headers.get('host') ?? u.hostname).split(':')[0]
+
+        // Serve ACME http-01 challenges for in-flight on-demand issuances.
+        if (onDemand && u.pathname.startsWith('/.well-known/acme-challenge/')) {
+          const keyAuth = onDemand.challengeStore.handlePath(u.pathname)
+          if (keyAuth !== undefined)
+            return new Response(keyAuth, { status: 200, headers: { 'content-type': 'text/plain' } })
+          return new Response('challenge not found', { status: 404 })
+        }
+
+        // First plaintext hit for an approved-but-uncovered host: kick off
+        // issuance so the cert exists for the subsequent HTTPS request. We don't
+        // block the redirect on it (the browser retries over HTTPS anyway).
+        if (onDemand && !onDemand.hasCert(host)) {
+          onDemand.ensureCert(host).catch(() => {})
+        }
+
         return new Response(null, {
           status: 301,
           headers: { Location: `https://${host}${u.pathname}${u.search}` },
@@ -441,6 +573,7 @@ export async function runDaemon(opts: DaemonOptions = {}): Promise<DaemonHandle>
     httpsPort: typeof httpsServer.port === 'number' ? httpsServer.port : httpsPort,
     httpPort: httpServer && typeof httpServer.port === 'number' ? httpServer.port : httpPort,
     pidPath,
+    ensureCert: (host: string) => (onDemand ? onDemand.ensureCert(host) : Promise.resolve(false)),
   }
 }
 

package/src/host-match.ts

@@ -0,0 +1,52 @@
+/**
+ * Host-based route matching with wildcard support.
+ *
+ * The routing table is keyed by host pattern. A pattern is either an exact
+ * hostname (`api.example.com`) or a wildcard (`*.example.com`). Lookup prefers
+ * an exact match, then the most-specific (deepest-suffix) wildcard.
+ *
+ * Kept dependency-free and pure so it's reusable from both the daemon and the
+ * in-process multi-proxy path, and trivially unit-testable.
+ */
+
+export function isWildcardPattern(pattern: string): boolean {
+  return pattern.startsWith('*.')
+}
+
+/**
+ * True if `hostname` matches the wildcard `pattern` (`*.suffix`). A wildcard
+ * matches exactly one or more leading labels — `*.example.com` matches
+ * `a.example.com` and `a.b.example.com`, but NOT the bare apex `example.com`.
+ */
+export function matchesWildcard(hostname: string, pattern: string): boolean {
+  if (!isWildcardPattern(pattern))
+    return false
+  const suffix = pattern.slice(1) // '*.example.com' → '.example.com'
+  return hostname.length > suffix.length && hostname.endsWith(suffix)
+}
+
+/**
+ * Find the route value for `hostname` in a host-keyed map. Exact match wins;
+ * otherwise the matching wildcard with the longest (most-specific) suffix wins.
+ * Returns `undefined` when nothing matches.
+ */
+export function matchHost<T>(table: Map<string, T>, hostname: string): T | undefined {
+  const exact = table.get(hostname)
+  if (exact !== undefined)
+    return exact
+
+  let best: T | undefined
+  let bestLen = -1
+  for (const [pattern, value] of table) {
+    if (!isWildcardPattern(pattern))
+      continue
+    if (matchesWildcard(hostname, pattern)) {
+      const len = pattern.length - 1 // length of the matched suffix
+      if (len > bestLen) {
+        bestLen = len
+        best = value
+      }
+    }
+  }
+  return best
+}

package/src/index.ts

@@ -112,8 +112,25 @@ export type {
   StopDaemonResult,
 } from './daemon'
 
-export { createProxyFetchHandler } from './proxy-handler'
-export type { GetRoute, ProxyFetchHandler, ProxyRoute } from './proxy-handler'
+export { createProxyFetchHandler, createProxyWebSocketHandler } from './proxy-handler'
+export type { GetRoute, ProxyFetchHandler, ProxyRoute, ProxyServer } from './proxy-handler'
+
+export { isWildcardPattern, matchesWildcard, matchHost } from './host-match'
+
+export {
+  contentTypeFor,
+  resolveStaticFile,
+  resolveStaticRoute,
+  safeRelativePath,
+  serveStaticFile,
+} from './static-files'
+export type { ResolvedStaticRoute, StaticResolution } from './static-files'
+
+export { buildSniTlsConfig, serverNameFromCertFilename } from './sni'
+export type { SniTlsEntry } from './sni'
+
+export { isLikelyHostname, matchesAllowedSuffix, OnDemandCertManager } from './on-demand'
+export type { CertIssuer, OnDemandCertManagerOptions } from './on-demand'
 
 export { deriveIdFromTarget, runViaDaemon } from './daemon-runner'
 export type { DaemonRunnerOptions, DaemonRunnerProxy } from './daemon-runner'

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 }),
+    ])
+  }
+}