@stacksjs/rpx 0.11.13 → 0.11.15

package/src/static-files.ts

@@ -0,0 +1,201 @@
+/**
+ * Static-file serving for proxy routes.
+ *
+ * A route configured with `static` serves files from a local directory instead
+ * of forwarding to an upstream. Path resolution is split into a pure function
+ * (`resolveStaticFile`) so it's trivially unit-testable, and a thin `Bun.file`
+ * wrapper (`serveStaticFile`) that does the actual I/O.
+ */
+import type { PathRewriteStyle, StaticRouteConfig } from './types'
+import * as path from 'node:path'
+
+/** Normalized static-route config (shorthand string already expanded). */
+export interface ResolvedStaticRoute {
+  dir: string
+  spa: boolean
+  pathRewriteStyle: PathRewriteStyle
+  maxAge: number
+  cleanUrls: boolean
+}
+
+export function resolveStaticRoute(
+  cfg: string | StaticRouteConfig,
+  cleanUrls: boolean,
+): ResolvedStaticRoute {
+  if (typeof cfg === 'string')
+    return { dir: cfg, spa: false, pathRewriteStyle: 'directory', maxAge: 0, cleanUrls }
+  return {
+    dir: cfg.dir,
+    spa: cfg.spa ?? false,
+    pathRewriteStyle: cfg.pathRewriteStyle ?? 'directory',
+    maxAge: cfg.maxAge ?? 0,
+    cleanUrls,
+  }
+}
+
+/** A minimal extension → MIME map covering the common web asset types. */
+const MIME_TYPES: Record<string, string> = {
+  '.html': 'text/html; charset=utf-8',
+  '.htm': 'text/html; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.map': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.otf': 'font/otf',
+  '.eot': 'application/vnd.ms-fontobject',
+  '.txt': 'text/plain; charset=utf-8',
+  '.xml': 'application/xml; charset=utf-8',
+  '.pdf': 'application/pdf',
+  '.wasm': 'application/wasm',
+  '.mp4': 'video/mp4',
+  '.webm': 'video/webm',
+  '.mp3': 'audio/mpeg',
+  '.wav': 'audio/wav',
+}
+
+export function contentTypeFor(filePath: string): string {
+  const ext = path.extname(filePath).toLowerCase()
+  return MIME_TYPES[ext] ?? 'application/octet-stream'
+}
+
+/**
+ * Decode + normalize a URL pathname into a safe relative path.
+ *
+ * Traversal safety: normalizing against a leading `/` collapses every `..`
+ * segment and clamps at the root, so the returned relative path never contains
+ * `..` and `path.join(root, rel)` can't escape `root`. Backslash, NUL and
+ * malformed percent-encoding are rejected outright (return `null`); the
+ * residual `..` guard is belt-and-suspenders.
+ */
+export function safeRelativePath(pathname: string): string | null {
+  let decoded: string
+  try {
+    decoded = decodeURIComponent(pathname)
+  }
+  catch {
+    return null
+  }
+  // Reject NUL and backslash (Windows-style) escapes outright.
+  if (decoded.includes('\0') || decoded.includes('\\'))
+    return null
+
+  // `path.posix.normalize` collapses `..`/`.`; a leading `/` keeps it rooted so
+  // a normalized result that still contains `..` means traversal above root.
+  const normalized = path.posix.normalize(`/${decoded}`)
+  if (normalized.includes('..'))
+    return null
+  // Strip the leading slash to get a path relative to the static root.
+  return normalized.replace(/^\/+/, '')
+}
+
+export interface StaticResolution {
+  /** Absolute file path to attempt to serve. */
+  filePath: string
+  /** When set, the request should 301-redirect to this clean URL. */
+  redirectTo?: string
+}
+
+/**
+ * Pure resolution of an incoming request pathname to a candidate file path on
+ * disk. Does no I/O; the caller checks existence and may fall back (SPA).
+ *
+ * Rules:
+ *  - A trailing `/` (or root) resolves to `index.html` in that directory.
+ *  - `cleanUrls` + a `.html` request → 301 to the extensionless URL.
+ *  - Extensionless paths resolve per `pathRewriteStyle`:
+ *      - `directory`: `/about` → `about/index.html`
+ *      - `flat`:      `/about` → `about.html`
+ *  - Paths with a real extension (`.css`, `.png`, …) map straight through.
+ *
+ * Returns `null` when the path is unsafe (traversal attempt).
+ */
+export function resolveStaticFile(
+  pathname: string,
+  route: ResolvedStaticRoute,
+): StaticResolution | null {
+  const rel = safeRelativePath(pathname)
+  if (rel === null)
+    return null
+
+  const ext = path.posix.extname(rel)
+
+  // `cleanUrls`: redirect explicit `.html` requests to the clean URL.
+  if (route.cleanUrls && ext === '.html') {
+    const clean = pathname.replace(/\/index\.html$/i, '/').replace(/\.html$/i, '')
+    return { filePath: path.join(route.dir, rel), redirectTo: clean || '/' }
+  }
+
+  // Directory or root request → index.html.
+  if (rel === '' || pathname.endsWith('/'))
+    return { filePath: path.join(route.dir, rel, 'index.html') }
+
+  // Asset with a concrete extension → serve directly.
+  if (ext !== '')
+    return { filePath: path.join(route.dir, rel) }
+
+  // Extensionless route → resolve by SSG style.
+  if (route.pathRewriteStyle === 'flat')
+    return { filePath: path.join(route.dir, `${rel}.html`) }
+  return { filePath: path.join(route.dir, rel, 'index.html') }
+}
+
+/**
+ * Serve a static file for the matched route. Returns a 301 for clean-URL
+ * redirects, the file with the right `Content-Type`/`Cache-Control` when it
+ * exists, the SPA `index.html` fallback when configured, or 404.
+ */
+export async function serveStaticFile(
+  pathname: string,
+  route: ResolvedStaticRoute,
+): Promise<Response> {
+  const resolution = resolveStaticFile(pathname, route)
+  if (!resolution)
+    return new Response('Forbidden', { status: 403 })
+
+  if (resolution.redirectTo)
+    return new Response(null, { status: 301, headers: { Location: resolution.redirectTo } })
+
+  const cacheControl = route.maxAge > 0
+    ? `public, max-age=${route.maxAge}`
+    : 'no-cache'
+
+  const file = Bun.file(resolution.filePath)
+  if (await file.exists()) {
+    return new Response(file, {
+      status: 200,
+      headers: {
+        'Content-Type': contentTypeFor(resolution.filePath),
+        'Cache-Control': cacheControl,
+      },
+    })
+  }
+
+  // SPA fallback: serve the root index.html so client-side routing works.
+  if (route.spa) {
+    const indexPath = path.join(route.dir, 'index.html')
+    const index = Bun.file(indexPath)
+    if (await index.exists()) {
+      return new Response(index, {
+        status: 200,
+        headers: {
+          'Content-Type': 'text/html; charset=utf-8',
+          'Cache-Control': 'no-cache',
+        },
+      })
+    }
+  }
+
+  return new Response('Not Found', { status: 404 })
+}

package/src/types.ts

@@ -24,11 +24,47 @@ export interface PathRewrite {
   stripPrefix?: boolean
 }
 
+/**
+ * How a static-file route maps request paths to files on disk.
+ *
+ * - `directory` (default): `/about` → `<root>/about/index.html` (SSG dir style).
+ * - `flat`: `/about` → `<root>/about.html` (flat-file style).
+ */
+export type PathRewriteStyle = 'directory' | 'flat'
+
+export interface StaticRouteConfig {
+  /** Absolute path to the directory served for this route. */
+  dir: string
+  /**
+   * Single-page-app fallback: serve `index.html` for any path that doesn't
+   * resolve to a real file (so client-side routing works). Default: `false`.
+   */
+  spa?: boolean
+  /**
+   * Extensionless-URL resolution style for `.html` files. Default: `directory`.
+   */
+  pathRewriteStyle?: PathRewriteStyle
+  /**
+   * `Cache-Control` max-age (seconds) for served files. Default: `0`.
+   */
+  maxAge?: number
+}
+
 export interface BaseProxyConfig {
-  from: string // localhost:5173
+  /**
+   * Upstream `host:port` to forward to (e.g. `localhost:5173`). Optional when
+   * `static` is set (the route serves files from disk instead of proxying).
+   */
+  from?: string // localhost:5173
   to: string // stacks.localhost
   start?: StartOptions
   pathRewrites?: PathRewrite[]
+  /**
+   * Serve a local directory for this route instead of proxying to `from`.
+   * Provide an absolute directory path (shorthand) or a {@link StaticRouteConfig}.
+   * When set, `from` is optional; exactly one of `from`/`static` must be present.
+   */
+  static?: string | StaticRouteConfig
   /**
    * Stable id used when registering this proxy with the rpx daemon. Derived
    * from `to` if omitted. Must match `/^[a-zA-Z0-9._-]+$/` and be ≤128 chars.
@@ -48,6 +84,89 @@ export interface CleanupConfig {
 
 export type CleanupOptions = Partial<CleanupConfig>
 
+/**
+ * A real PEM cert+key pair on disk for one SNI server name.
+ */
+export interface DomainCert {
+  /** Absolute path to the PEM certificate (fullchain). */
+  certPath: string
+  /** Absolute path to the PEM private key. */
+  keyPath: string
+}
+
+/**
+ * Production TLS using real certs (e.g. Let's Encrypt) served per-domain via
+ * SNI on a single listener. Provide either an explicit `domains` map or a
+ * `certsDir` convention.
+ */
+export interface ProductionTlsConfig {
+  /**
+   * Explicit per-domain cert/key files keyed by SNI server name. Use
+   * `*.example.com` for a wildcard server name.
+   */
+  domains?: Record<string, DomainCert>
+  /**
+   * Directory of PEM files following the convention `<domain>.crt` /
+   * `<domain>.key`. A wildcard pair `_wildcard.<apex>.crt` /
+   * `_wildcard.<apex>.key` is registered under server name `*.<apex>`.
+   */
+  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
@@ -64,6 +183,24 @@ export interface SharedProxyConfig {
    * `:443` (Valet-style). Default: `false` for backward compatibility.
    */
   viaDaemon?: boolean
+  /**
+   * Master switch for all `/etc/hosts` reads/writes. Set to `false` on a real
+   * server with real DNS so rpx never touches `/etc/hosts`. When omitted, the
+   * legacy behavior applies (driven by `cleanup.hosts`). `cleanup: { hosts:
+   * false }` also disables hosts management.
+   */
+  hostsManagement?: boolean
+  /**
+   * Production per-domain SNI certs (Let's Encrypt PEMs already on disk). When
+   * provided, the listener serves a different real cert per SNI server name
+   * 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>

package/dist/chunk-kbnzcycw.js

@@ -1 +0,0 @@
-import{$ as j,S as a,T as b,U as c,V as d,W as e,X as f,Y as g,Z as h,_ as i,aa as k,ba as l,ca as m,da as n}from"./chunk-pncxrxde.js";import"./chunk-zs1tyy8z.js";export{l as tearDownDevelopmentDns,k as syncDevelopmentDnsFromRegistry,d as stopDnsServer,c as startDnsServer,h as setupResolver,j as setupDevelopmentDns,f as resolverFilePath,m as removeResolver,i as removeLegacyTldResolvers,n as reconcileStaleDevelopmentDns,e as isDnsServerRunning,g as contentLooksLikeRpxResolver,b as RPX_RESOLVER_MARKER,a as DNS_PORT};