@stacksjs/rpx 0.11.15 → 0.11.17

package/src/host-routes.ts

@@ -0,0 +1,147 @@
+/**
+ * Path-aware routing within a single host.
+ *
+ * `host-match.ts` answers "which host pattern owns this hostname?" (exact wins,
+ * then most-specific wildcard). That is sufficient when every host maps to a
+ * single backend. But a single domain often needs to serve several things at
+ * once — e.g. `stacksjs.com/api/*` proxied to an app on `:3000`,
+ * `stacksjs.com/docs*` served from `/var/www/docs`, and `stacksjs.com/` served
+ * from `/var/www/public`. That requires a second routing dimension: the
+ * request **path**.
+ *
+ * This module layers path routing on top of host routing without disturbing
+ * host-only routing:
+ *   - Each host pattern maps to a list of `(path, route)` entries.
+ *   - Lookup first resolves the host (reusing `matchHost` semantics), then picks
+ *     the entry whose `path` is the longest prefix of the request pathname.
+ *   - A host with a single entry whose `path` is `'/'` (or empty) behaves
+ *     exactly like the old host-only table — full backward compatibility.
+ *
+ * Kept dependency-free and pure so it's reusable from both the daemon and the
+ * in-process multi-proxy path, and trivially unit-testable.
+ */
+import { isWildcardPattern, matchesWildcard } from './host-match'
+
+/** One path-scoped route under a host. */
+export interface PathRoute<T> {
+  /**
+   * Path prefix this route owns, e.g. `'/api'`. `'/'` (or `''`) is the host
+   * default that catches everything not claimed by a more specific prefix.
+   */
+  path: string
+  /** The route value (e.g. a {@link import('./proxy-handler').ProxyRoute}). */
+  route: T
+}
+
+/**
+ * A host-keyed routing table where each host owns an ordered set of
+ * path-scoped routes. Build it with {@link buildHostRoutes}.
+ */
+export type HostRoutes<T> = Map<string, Array<PathRoute<T>>>
+
+/**
+ * Normalize a path prefix to a leading-slash, no-trailing-slash form so prefix
+ * comparisons are predictable. `''`/`undefined`/`'/'` all normalize to `'/'`
+ * (the host default). `'/api/'` → `'/api'`, `'docs'` → `'/docs'`.
+ */
+export function normalizePathPrefix(path: string | undefined): string {
+  if (!path || path === '/')
+    return '/'
+  let p = path.trim()
+  if (!p.startsWith('/'))
+    p = `/${p}`
+  // Strip trailing slashes (but keep the root '/').
+  p = p.replace(/\/+$/, '')
+  return p === '' ? '/' : p
+}
+
+/**
+ * True if `pathname` is matched by the prefix `prefix`. The root prefix `'/'`
+ * matches everything. A non-root prefix matches when the pathname equals it
+ * (`/api`), or continues with a `/` (`/api/x`) — so `/api` does NOT match
+ * `/apifoo`, only a real path-segment boundary.
+ */
+export function pathPrefixMatches(pathname: string, prefix: string): boolean {
+  if (prefix === '/')
+    return true
+  if (pathname === prefix)
+    return true
+  return pathname.startsWith(`${prefix}/`)
+}
+
+/**
+ * Build a {@link HostRoutes} table from a flat list of entries. Entries are
+ * grouped by host; within each host the path-routes are sorted longest-prefix
+ * first so {@link matchHostRoute} can take the first match. If two entries
+ * collide on the same (host, path) the later one wins (matching `Map.set`).
+ */
+export function buildHostRoutes<T>(
+  entries: Array<{ host: string, path?: string, route: T }>,
+): HostRoutes<T> {
+  const byHost = new Map<string, Map<string, T>>()
+  for (const e of entries) {
+    const prefix = normalizePathPrefix(e.path)
+    let paths = byHost.get(e.host)
+    if (!paths) {
+      paths = new Map<string, T>()
+      byHost.set(e.host, paths)
+    }
+    paths.set(prefix, e.route)
+  }
+
+  const table: HostRoutes<T> = new Map()
+  for (const [host, paths] of byHost) {
+    const list: Array<PathRoute<T>> = []
+    for (const [path, route] of paths)
+      list.push({ path, route })
+    // Longest prefix first; '/' (length 1) naturally sorts last as the default.
+    list.sort((a, b) => b.path.length - a.path.length)
+    table.set(host, list)
+  }
+  return table
+}
+
+/**
+ * Find the path-route list for `hostname` in a {@link HostRoutes} table. Exact
+ * host match wins; otherwise the most-specific (deepest-suffix) wildcard wins —
+ * mirroring {@link import('./host-match').matchHost}.
+ */
+export function matchHostList<T>(table: HostRoutes<T>, hostname: string): Array<PathRoute<T>> | undefined {
+  const exact = table.get(hostname)
+  if (exact !== undefined)
+    return exact
+
+  let best: Array<PathRoute<T>> | undefined
+  let bestLen = -1
+  for (const [pattern, value] of table) {
+    if (!isWildcardPattern(pattern))
+      continue
+    if (matchesWildcard(hostname, pattern)) {
+      const len = pattern.length - 1
+      if (len > bestLen) {
+        bestLen = len
+        best = value
+      }
+    }
+  }
+  return best
+}
+
+/**
+ * Resolve a (hostname, pathname) pair to a single route value. First the host
+ * is resolved ({@link matchHostList}); then the longest matching path prefix
+ * within that host wins. Returns `undefined` when no host matches, or a host
+ * matches but no path prefix (including the `'/'` default) covers the request.
+ */
+export function matchHostRoute<T>(table: HostRoutes<T>, hostname: string, pathname: string): T | undefined {
+  const list = matchHostList(table, hostname)
+  if (!list)
+    return undefined
+  // `list` is pre-sorted longest-prefix-first, so the first match is the most
+  // specific one ('/' is last and matches everything as the host default).
+  for (const entry of list) {
+    if (pathPrefixMatches(pathname, entry.path))
+      return entry.route
+  }
+  return undefined
+}

package/src/https.ts

@@ -783,8 +783,8 @@ export async function isCertTrusted(
     // Different check methods per platform
     if (process.platform === 'darwin') {
       if (options?.serverName)
-        return isRootCaTrustedForSsl(certPath, options.serverName, { verbose: options.verbose })
-      return isRootCaFingerprintInKeychains(certPath, { verbose: options.verbose })
+        return isRootCaTrustedForSsl(certPath, options.serverName, { verbose: options?.verbose })
+      return isRootCaFingerprintInKeychains(certPath, { verbose: options?.verbose })
     }
     else if (process.platform === 'win32') {
       // On Windows, use PowerShell to check the certificate store

package/src/index.ts

@@ -112,11 +112,23 @@ export type {
   StopDaemonResult,
 } from './daemon'
 
-export { createProxyFetchHandler, createProxyWebSocketHandler } from './proxy-handler'
+export { createProxyFetchHandler, createProxyWebSocketHandler, stripBasePath } from './proxy-handler'
 export type { GetRoute, ProxyFetchHandler, ProxyRoute, ProxyServer } from './proxy-handler'
 
 export { isWildcardPattern, matchesWildcard, matchHost } from './host-match'
 
+export { createOriginGuard } from './origin-guard'
+export type { OriginGuard, OriginGuardOptions } from './origin-guard'
+
+export {
+  buildHostRoutes,
+  matchHostList,
+  matchHostRoute,
+  normalizePathPrefix,
+  pathPrefixMatches,
+} from './host-routes'
+export type { HostRoutes, PathRoute } from './host-routes'
+
 export {
   contentTypeFor,
   resolveStaticFile,

package/src/origin-guard.ts

@@ -0,0 +1,105 @@
+/**
+ * Origin verification guard for "CDN in front of rpx" topologies.
+ *
+ * When rpx is the origin behind a CDN (e.g. CloudFront → rpx), the origin host
+ * is publicly resolvable, so a client could resolve it and hit rpx directly,
+ * bypassing the CDN's caching/WAF. The standard mitigation is a shared secret:
+ * the CDN injects a secret request header on the origin fetch, and the origin
+ * rejects any request to the protected hosts that lacks it.
+ *
+ * `createOriginGuard` returns a tiny pre-router gate you place in front of your
+ * fetch handler. It only guards the listed hosts (exact or `*.wildcard`) — every
+ * other host (e.g. apps served directly, not via the CDN) passes through
+ * untouched. ACME HTTP-01 challenge paths are exempt by default so cert renewal
+ * keeps working on the open `:80` listener.
+ *
+ * @example
+ * const guard = createOriginGuard({
+ *   header: 'x-origin-verify',
+ *   value: process.env.ORIGIN_SECRET!,
+ *   hosts: ['stacksjs.com', 'www.stacksjs.com', 'origin.stacksjs.com'],
+ * })
+ * Bun.serve({ fetch: req => guard(req) ?? handler(req, server) })
+ */
+import { matchesWildcard } from './host-match'
+
+export interface OriginGuardOptions {
+  /** Header the CDN injects on the origin hop (case-insensitive), e.g. `x-origin-verify`. */
+  header: string
+  /** Expected secret value. Requests to protected hosts must carry `header: value`. */
+  value: string
+  /** Hosts to protect — exact (`stacksjs.com`) or wildcard (`*.stacksjs.com`). Others pass through. */
+  hosts: string[]
+  /**
+   * Request paths exempt from the check (prefix match). Defaults to the ACME
+   * HTTP-01 challenge prefix so cert issuance/renewal is never blocked.
+   */
+  exemptPaths?: string[]
+  /** Body returned on rejection. Defaults to a short plain-text message. */
+  forbiddenMessage?: string
+}
+
+export interface OriginGuard {
+  /** Returns a 403 Response to short-circuit, or `undefined` to let the request proceed. */
+  (req: Request): Response | undefined
+  /** Whether a given hostname is in the protected set. */
+  protects: (hostname: string) => boolean
+}
+
+const DEFAULT_EXEMPT = ['/.well-known/acme-challenge/']
+
+function hostnameOf(req: Request): string {
+  const hostHeader = req.headers.get('host')
+  if (hostHeader)
+    return hostHeader.split(':')[0].toLowerCase()
+  try {
+    return new URL(req.url).hostname.toLowerCase()
+  }
+  catch {
+    return ''
+  }
+}
+
+export function createOriginGuard(options: OriginGuardOptions): OriginGuard {
+  const header = options.header.toLowerCase()
+  const exact = new Set<string>()
+  const wildcards: string[] = []
+  for (const h of options.hosts) {
+    const host = h.toLowerCase()
+    if (host.startsWith('*.'))
+      wildcards.push(host)
+    else
+      exact.add(host)
+  }
+  const exemptPaths = options.exemptPaths ?? DEFAULT_EXEMPT
+  const forbidden = options.forbiddenMessage
+    ?? 'Forbidden: direct origin access is not allowed; requests must arrive via the CDN.\n'
+
+  const protects = (hostname: string): boolean => {
+    const h = hostname.toLowerCase()
+    return exact.has(h) || wildcards.some(w => matchesWildcard(h, w))
+  }
+
+  const guard: OriginGuard = ((req: Request): Response | undefined => {
+    const host = hostnameOf(req)
+    if (!protects(host))
+      return undefined
+
+    let pathname = '/'
+    try {
+      pathname = new URL(req.url).pathname
+    }
+    catch {
+      // fall through with '/'
+    }
+    if (exemptPaths.some(p => pathname.startsWith(p)))
+      return undefined
+
+    if (req.headers.get(header) === options.value)
+      return undefined
+
+    return new Response(forbidden, { status: 403, headers: { 'content-type': 'text/plain' } })
+  }) as OriginGuard
+  guard.protects = protects
+  return guard
+}

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[]
   /**