@stacksjs/rpx 0.11.14 → 0.11.15

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/types.ts

@@ -113,6 +113,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 +196,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>