@dbx-tools/tunnel 0.6.105 → 0.6.107

package/src/gate.ts

@@ -47,7 +47,7 @@ export interface GateOptions {
    * inert (everything passes through) - a tunnel with no public domain gates
    * nothing.
    */
-  publicDomain?: string;
+  publicDomain?: string | readonly string[];
   /**
    * Extra `x-` request headers tunnel traffic may forward (unioned with the
    * built-in allow-list). Every other `x-` header is stripped from tunnel traffic.
@@ -64,14 +64,18 @@ export interface GateOptions {
 }
 
 /**
- * True when the request's `Host` is the tunnel's public domain - i.e. it came in
- * over portr. Case-insensitive; the optional `:port` is ignored. When no public
- * domain is configured, nothing is tunnel traffic.
+ * True when the request's `Host` is one of the tunnel's public domains - i.e. it
+ * came in over Portr or FRP. Case-insensitive; the optional `:port` is ignored.
+ * When no public domain is configured, nothing is tunnel traffic.
  */
-export function isTunnelHost(req: IncomingMessage, publicDomain: string | undefined): boolean {
+export function isTunnelHost(
+  req: IncomingMessage,
+  publicDomain: string | readonly string[] | undefined,
+): boolean {
   if (!publicDomain) return false;
   const host = (req.headers.host ?? "").toLowerCase().split(":")[0];
-  return host === publicDomain.toLowerCase().split(":")[0];
+  const domains = typeof publicDomain === "string" ? [publicDomain] : publicDomain;
+  return domains.some((domain) => host === domain.toLowerCase().split(":")[0]);
 }
 
 /**

package/src/interceptor.ts

@@ -1,6 +1,6 @@
 /**
  * `tunnelInterceptor()` - the {@link Interceptor} that fronts an app with a public
- * portr tunnel, consuming the {@link InterceptorContext} `@dbx-tools/appkit`'s
+ * portr and/or frp tunnel, consuming the {@link InterceptorContext} `@dbx-tools/appkit`'s
  * `createApp` hands it.
  *
  * The tunnel runs IN-PROCESS: the APP is the main process and hands this interceptor
@@ -17,15 +17,19 @@
  * @module
  */
 
+import type { ChildProcess } from "node:child_process";
 import type { Interceptor, InterceptorContext } from "@dbx-tools/appkit";
 import { log, object } from "@dbx-tools/shared-core";
+import { installFrp, resolveFrpConfig, startFrp, writeFrpConfig } from "./frp.ts";
 import { installPortr, resolvePortrConfig, startPortr, writePortrConfig } from "./portr.ts";
 
 const logger = log.logger("tunnel:interceptor");
 
 /** Options for {@link tunnelInterceptor} (each also resolvable from env). */
 export interface TunnelInterceptorOptions {
-  /** portr `<subdomain>.<server>` to serve on. Env `TUNNEL_PUBLIC_DOMAIN`. */
+  /** Tunnel clients to run. Env `DBX_TOOLS_TUNNEL_TRANSPORT`; defaults to `portr`. */
+  transport?: TunnelTransport;
+  /** Public host to serve on. Env `TUNNEL_PUBLIC_DOMAIN`. */
   publicDomain?: string;
   /** portr subdomain (else derived from {@link publicDomain}). */
   subdomain?: string;
@@ -35,6 +39,32 @@ export interface TunnelInterceptorOptions {
    * (then `8000`), which is the port the platform routes to.
    */
   port?: number;
+  /** frps control host; defaults to the FRP public domain. Env `FRP_SERVER`. */
+  frpServer?: string;
+  /** FRP public HTTP host. Env `TUNNEL_FRP_PUBLIC_DOMAIN`. */
+  frpPublicDomain?: string;
+  /** frps control port. Env `FRP_SERVER_PORT`; defaults to `443`. */
+  frpServerPort?: number;
+  /** frpc transport protocol. Env `FRP_PROTOCOL`; defaults to `wss`. */
+  frpProtocol?: string;
+  /** frps auth token. Env `FRP_TOKEN` (or `TUNNEL_TOKEN`). */
+  frpToken?: string;
+  /** frp proxy registration name. Env `FRP_PROXY_NAME`. */
+  frpProxyName?: string;
+}
+
+/** Public tunnel clients supported by the interceptor and CLI. */
+export type TunnelTransport = "portr" | "frp" | "both";
+
+/** Resolve and validate the tunnel transport selector. */
+export function resolveTunnelTransport(transport?: string): TunnelTransport {
+  const resolved =
+    transport ??
+    process.env.DBX_TOOLS_TUNNEL_TRANSPORT ??
+    process.env.TUNNEL_TRANSPORT ??
+    "portr";
+  if (resolved === "portr" || resolved === "frp" || resolved === "both") return resolved;
+  throw new TypeError(`invalid tunnel transport: ${resolved} (expected portr, frp, or both)`);
 }
 
 /** Resolve the public port portr should target: explicit, else the Apps contract. */
@@ -45,9 +75,8 @@ function resolvePublicPort(port?: number): number {
 /**
  * Build the tunnel {@link Interceptor}. Pass it to `createApp({ interceptor })`.
  *
- * A no-op (logs and returns) when no portr tunnel is configured - no `PORTR_TOKEN`
- * or no resolvable `<subdomain>.<server>` - so an app can register it
- * unconditionally and only actually tunnels where the deployment wired portr.
+ * A no-op (logs and returns) when none of the selected tunnel clients resolve
+ * usable configuration, so an app can register it unconditionally.
  *
  * @example
  * import { appkit } from "@dbx-tools/appkit";
@@ -65,25 +94,45 @@ export function tunnelInterceptor(options: TunnelInterceptorOptions = {}): Inter
     }
 
     const port = resolvePublicPort(options.port);
-    const portrConfig = resolvePortrConfig({
-      publicDomain: options.publicDomain,
-      subdomain: options.subdomain,
-      port,
-    });
-    if (!portrConfig) {
-      logger.info("no PORTR_TOKEN/TUNNEL_PUBLIC_DOMAIN - the app runs without a public tunnel");
-      return;
+    const transport = resolveTunnelTransport(options.transport);
+    const children: ChildProcess[] = [];
+    if (transport === "portr" || transport === "both") {
+      const portrConfig = resolvePortrConfig({
+        publicDomain: options.publicDomain,
+        subdomain: options.subdomain,
+        port,
+      });
+      if (portrConfig) {
+        const portrEnv = await installPortr();
+        await writePortrConfig(portrConfig, portrEnv);
+        children.push(await startPortr(portrConfig, portrEnv));
+      } else {
+        logger.info("portr not configured (requires PORTR_TOKEN and TUNNEL_PUBLIC_DOMAIN)");
+      }
     }
-
-    const portrEnv = await installPortr();
-    await writePortrConfig(portrConfig, portrEnv);
-    const portr = await startPortr(portrConfig, portrEnv);
-    ctx.bindProcess(portr);
-
+    if (transport === "frp" || transport === "both") {
+      const frpConfig = resolveFrpConfig({
+        publicDomain: options.frpPublicDomain,
+        server: options.frpServer,
+        serverPort: options.frpServerPort,
+        protocol: options.frpProtocol,
+        token: options.frpToken,
+        proxyName: options.frpProxyName,
+        port,
+      });
+      if (frpConfig) {
+        const frpEnv = await installFrp();
+        const configPath = await writeFrpConfig(frpConfig, frpEnv);
+        children.push(startFrp(frpConfig, frpEnv, configPath));
+      } else {
+        logger.info("frp not configured (requires TUNNEL_PUBLIC_DOMAIN)");
+      }
+    }
+    if (!children.length) return;
+    for (const child of children) ctx.bindProcess(child);
     ctx.onLifecycle("shutdown", () => {
-      if (!portr.killed) portr.kill("SIGTERM");
+      for (const child of children) if (!child.killed) child.kill("SIGTERM");
     });
-
-    logger.info(`tunnel bound: portr -> :${port} (${portrConfig.subdomain}.${portrConfig.server})`);
+    logger.info(`tunnel bound: ${transport} -> :${port}`);
   };
 }

package/src/plugin.ts

@@ -166,6 +166,8 @@ export interface AuthGateConfig extends BasePluginConfig, AuthStorageConfig {
    * traffic).
    */
   publicDomain?: string;
+  /** Additional public tunnel domains accepted by the gate. */
+  publicDomains?: string | string[];
   /**
    * Extra `x-` request headers tunnel traffic may forward (literal / glob /
    * `/regex/`), unioned with the built-in allow-list. Env `TUNNEL_FORWARD_HEADERS`.
@@ -213,8 +215,10 @@ export interface ResolvedAuthGateConfig {
   sessionCutoffMs: number;
   /** Same-origin path returned after logout. */
   logoutRedirectPath: string;
-  /** Public domain that identifies portr traffic by `Host`; `undefined` = inert. */
+  /** Primary public domain; `undefined` when Portr is not configured. */
   publicDomain?: string;
+  /** All public tunnel domains accepted by the gate. */
+  publicDomains: string[];
   /** Extra `x-` headers tunnel traffic may forward (unioned with the defaults). */
   forwardHeaders: string[];
   /** Path prefixes to gate beyond `/api/` (e.g. `/ws`). */
@@ -249,6 +253,8 @@ export function resolveAuthGateConfig(config: AuthGateConfig): ResolvedAuthGateC
       (coreConfig.text("AUTH_STORAGE", TUNNEL_CONFIG) as AuthStorageMode | undefined),
     sqlitePath: config.sqlitePath ?? coreConfig.text("AUTH_SQLITE_PATH", TUNNEL_CONFIG),
   });
+  const publicDomain = coreConfig.string(config.publicDomain, "PUBLIC_DOMAIN", TUNNEL_CONFIG);
+  const frpPublicDomain = coreConfig.text("FRP_PUBLIC_DOMAIN", TUNNEL_CONFIG);
   return {
     // Both sources are unioned rather than one overriding: a deployment-wide
     // TUNNEL_AUTH_ALLOW and a per-invocation `--allow` should both grant access.
@@ -280,7 +286,16 @@ export function resolveAuthGateConfig(config: AuthGateConfig): ResolvedAuthGateC
       coreConfig.string(config.logoutRedirectPath, "AUTH_LOGOUT_REDIRECT", TUNNEL_CONFIG) ??
         DEFAULTS.logoutRedirectPath,
     ),
-    publicDomain: coreConfig.string(config.publicDomain, "PUBLIC_DOMAIN", TUNNEL_CONFIG),
+    publicDomain,
+    publicDomains: [
+      ...new Set(
+        [
+          publicDomain,
+          frpPublicDomain,
+          ...string.parseList(config.publicDomains),
+        ].filter((value): value is string => !!value),
+      ),
+    ],
     forwardHeaders: [
       ...string.parseList(config.forwardHeaders),
       ...string.parseList(coreConfig.text("FORWARD_HEADERS", TUNNEL_CONFIG)),
@@ -404,7 +419,7 @@ export class AuthGatePlugin extends Plugin<AuthGateConfig> {
     logger.info("ready", {
       patterns: this.resolved.allow.length,
       sessionTtlSeconds: this.resolved.sessionTtlSeconds,
-      publicDomain: this.resolved.publicDomain ?? null,
+      publicDomains: this.resolved.publicDomains,
       insecure: this.resolved.insecure,
       storage: this.resolved.storage,
       logoutRedirectPath: this.resolved.logoutRedirectPath,
@@ -434,7 +449,7 @@ export class AuthGatePlugin extends Plugin<AuthGateConfig> {
     }
     mountGateOnContext(context, {
       gate: this.exports(),
-      publicDomain: this.resolved.publicDomain,
+      publicDomain: this.resolved.publicDomains,
       forwardHeaders: this.resolved.forwardHeaders,
       gatePaths: this.resolved.gatePaths,
     });