akanjs 3.1.1 → 3.1.2-rc.0

package/server/rscWorker.tsx

@@ -13,6 +13,7 @@ import {
   type AkanI18nConfig,
   DEFAULT_AKAN_I18N,
   getBasePathFromPathname,
+  LocalePath,
   Logger,
   parseSearchParams,
 } from "akanjs/common";
@@ -57,6 +58,7 @@ import {
 import { LogForwarder } from "./logging/logForwarder";
 import { ProcessMetricsCollector } from "./processMetricsCollector";
 import { RouteElementComposer, type RouteNotFoundInPlace } from "./routeElementComposer";
+import { RouteShellGate } from "./routeShellGate";
 import {
   type AkanRscPatchDecision,
   createAkanRouterState,
@@ -69,7 +71,7 @@ import {
   resolveAkanRscPatchDecision,
 } from "./routeState";
 import { type PagesContext, RouteTreeBuilder } from "./routeTreeBuilder";
-import { encodeAkanRedirectDigest } from "./rscHttp";
+import { concatBytes, encodeAkanRedirectDigest } from "./rscHttp";
 import { RscPagePrompts } from "./rscPagePrompts";
 import {
   type CachedRscResult,
@@ -623,6 +625,7 @@ export class RscRenderer {
         let effectivePatchDecision = safePatchDecision;
         const notFoundProbe = { hit: false };
         const notFound = this.#notFoundInPlace(urlObj, notFoundProbe);
+        const gate = new RouteShellGate();
         if (match && safePatchDecision.status === "patch" && safePatchDecision.patch) {
           const suffixElement = await this.#renderMatchedSuffix(
             urlObj,
@@ -638,11 +641,11 @@ export class RscRenderer {
               reason: "suffix-compose-fallback",
               commonPrefixLength: safePatchDecision.commonPrefixLength,
             };
-            element = await this.#renderMatched(urlObj, match, searchParams, notFound, { guarded: true });
+            element = await this.#renderMatched(urlObj, match, searchParams, notFound, { guarded: true, gate });
           } else element = suffixElement;
         } else if (match)
-          element = await this.#renderMatched(urlObj, match, searchParams, notFound, { guarded: admitted });
-        else element = await this.#renderNotFound(urlObj);
+          element = await this.#renderMatched(urlObj, match, searchParams, notFound, { guarded: admitted, gate });
+        else element = await this.#renderNotFound(urlObj, gate);
         const traceCacheKey =
           effectivePatchDecision.status === "patch" ? (patchCacheEntry?.key ?? cacheEntry?.key) : cacheEntry?.key;
         const ssrBlocking = getRequestFrameState<PageState>()?.ssr === "block";
@@ -662,6 +665,7 @@ export class RscRenderer {
           status: match ? undefined : 404,
           trace,
           notFoundProbe,
+          gate,
           onComplete: ({ chunks, bytes, chunksCount, control, lateControlSent }) => {
             const cacheState = shouldStoreRouteCache({
               policy: getRequestPolicy(),
@@ -894,6 +898,7 @@ export class RscRenderer {
       trace?: RscTraceMetadata;
       /** Raised by a render that answered `router.notFound()` in place, which React never reports as an error. */
       notFoundProbe?: { hit: boolean };
+      gate?: RouteShellGate;
       onComplete?: (
         result: Omit<FlightRenderResult, "cancelled">,
       ) => Promise<RouteCacheRenderState> | RouteCacheRenderState;
@@ -927,6 +932,9 @@ export class RscRenderer {
     let sentChunk = false;
     let lateControlSent = false;
     const chunks: Uint8Array[] = [];
+    
+    let holding = options.gate?.holding ? options.gate : null;
+    let held: Uint8Array | null = null;
     let reportedTheme: AkanTheme | undefined;
     const sendMeta = () => {
       if (!options.requestId || sentMeta) return;
@@ -959,6 +967,24 @@ export class RscRenderer {
     const readProbe = () => {
       if (!controlRef.current && options.notFoundProbe?.hit) controlRef.current = { type: "not-found" };
     };
+    const emit = (chunk: Uint8Array) => {
+      if (options.collectChunks) chunks.push(chunk);
+      if (!options.requestId) return;
+      sendMeta();
+      sendLateTheme();
+      this.#send({ type: "chunk", requestId: options.requestId, data: chunk });
+      sentChunk = true;
+    };
+    const releaseHeld = () => {
+      holding = null;
+      if (!held) return;
+      if (controlRef.current) {
+        sendMeta();
+        sendLateControl();
+      }
+      emit(held);
+      held = null;
+    };
 
     const sendLateControl = () => {
       const control = controlRef.current;
@@ -981,16 +1007,26 @@ export class RscRenderer {
       this.#send({ type: "late-not-found", requestId: options.requestId });
     };
     try {
+      let pendingRead: ReturnType<typeof reader.read> | null = null;
       for (;;) {
         if (options.requestId && this.#cancelledRenderRequests.has(options.requestId))
           return await cancelWith(null, true);
-        const { value, done } = await reader.read();
+        pendingRead ??= reader.read();
+        if (holding && (await Promise.race([pendingRead.then(() => false), holding.opened.then(() => true)]))) {
+          readProbe();
+          if (controlRef.current?.type === "error") return await cancelWith(controlRef.current, false);
+          releaseHeld();
+          continue;
+        }
+        const { value, done } = await pendingRead;
+        pendingRead = null;
         readProbe();
-        if (controlRef.current && !sentChunk) return await cancelWith(controlRef.current, false);
+        if (controlRef.current && !sentChunk && (!holding || controlRef.current.type === "error"))
+          return await cancelWith(controlRef.current, false);
         if (controlRef.current && sentChunk) sendLateControl();
         if (done) break;
 
-        if (!sentChunk && options.requestId) {
+        if (chunksCount === 0 && options.requestId) {
           await new Promise((resolve) => setTimeout(resolve, 0));
           readProbe();
           if (controlRef.current) return await cancelWith(controlRef.current, false);
@@ -998,13 +1034,8 @@ export class RscRenderer {
         const chunk = value instanceof Uint8Array ? value : new Uint8Array(value as ArrayBufferLike);
         bytes += chunk.byteLength;
         chunksCount += 1;
-        if (options.collectChunks) chunks.push(chunk);
-        if (options.requestId) {
-          sendMeta();
-          sendLateTheme();
-          this.#send({ type: "chunk", requestId: options.requestId, data: chunk });
-          sentChunk = true;
-        }
+        if (holding) held = held ? concatBytes(held, chunk) : chunk;
+        else emit(chunk);
       }
     } catch (error) {
       if (options.requestId && this.#cancelledRenderRequests.has(options.requestId)) {
@@ -1016,6 +1047,7 @@ export class RscRenderer {
       reader.releaseLock();
     }
     readProbe();
+    if (holding && controlRef.current?.type !== "error") releaseHeld();
     if (controlRef.current && sentChunk) sendLateControl();
     if (controlRef.current && !sentChunk)
       return { chunks, bytes, chunksCount, control: controlRef.current, lateControlSent, cancelled: false };
@@ -1065,6 +1097,7 @@ export class RscRenderer {
     trace?: RscTraceMetadata;
   }): Promise<boolean> {
     try {
+      const gate = new RouteShellGate();
       const element = await this.#renderFallbackDocument({
         kind,
         route,
@@ -1074,9 +1107,17 @@ export class RscRenderer {
         url,
         error: kind === "error" && process.env.NODE_ENV !== "production" ? error : undefined,
         digest: kind === "error" ? "AKAN_RENDER_ERROR" : undefined,
+        gate,
       });
       if (!element) return false;
-      return await this.#trySendFlight(requestId, element, clientManifest, kind === "not-found" ? 404 : 500, trace);
+      return await this.#trySendFlight(
+        requestId,
+        element,
+        clientManifest,
+        kind === "not-found" ? 404 : 500,
+        trace,
+        gate,
+      );
     } catch (fallbackError) {
       this.#logger.error(
         `render[${requestId}] custom ${kind} fallback failed: ${
@@ -1116,8 +1157,9 @@ export class RscRenderer {
     clientManifest: ClientManifest,
     status: number,
     trace?: RscTraceMetadata,
+    gate?: RouteShellGate,
   ): Promise<boolean> {
-    const result = await this.#renderFlightElement(element, clientManifest, { requestId, status, trace });
+    const result = await this.#renderFlightElement(element, clientManifest, { requestId, status, trace, gate });
     if (result.cancelled) return true;
     if (result.control) return false;
     this.#recordFlight(result);
@@ -1275,6 +1317,7 @@ export class RscRenderer {
     url,
     error,
     digest,
+    gate,
   }: {
     kind: "not-found" | "error";
     route: PathRoute | LayoutFallbackRoute;
@@ -1284,6 +1327,7 @@ export class RscRenderer {
     url: URL;
     error?: unknown;
     digest?: string;
+    gate?: RouteShellGate;
   }): Promise<ReactNode | null> {
     setRequestFrameState(
       await RouteElementComposer.resolveSsrFallbackFrameState({
@@ -1299,6 +1343,7 @@ export class RscRenderer {
       pathname,
       error,
       digest,
+      gate,
     });
     if (!body) return null;
     const viewport = await RscRenderer.#firstRootValue(route.renderRootLayouts, (render) =>
@@ -1322,7 +1367,10 @@ export class RscRenderer {
           {routeHeadSnapshot ? null : this.#renderLocaleAlternates(url)}
           {this.#renderStylesheet(pathname)}
         </head>
-        <body key="body">{body}</body>
+        <body key="body">
+          {body}
+          {gate?.holding ? <RouteShellGate.Wait until={gate.opened} /> : null}
+        </body>
       </html>
     );
   }
@@ -1359,7 +1407,7 @@ export class RscRenderer {
     match: { pathRoute: PathRoute; params: Record<string, string> },
     searchParams: Record<string, string | string[]>,
     notFound: RouteNotFoundInPlace,
-    { guarded = false }: { guarded?: boolean } = {},
+    { guarded = false, gate }: { guarded?: boolean; gate?: RouteShellGate } = {},
   ): Promise<ReactNode> {
     this.#logger.verbose(
       `composing route element pathname=${url.pathname} search=${url.search || "(none)"} params=${JSON.stringify(match.params)}`,
@@ -1390,6 +1438,7 @@ export class RscRenderer {
       searchParams,
       navKey: url.pathname + url.search,
       notFound,
+      gate,
     });
     
     return (
@@ -1406,7 +1455,10 @@ export class RscRenderer {
           {routeHeadSnapshot ? null : this.#renderLocaleAlternates(url)}
           {this.#renderStylesheet(url.pathname)}
         </head>
-        <body key="body">{body}</body>
+        <body key="body">
+          {body}
+          {gate?.holding ? <RouteShellGate.Wait until={gate.opened} /> : null}
+        </body>
       </html>
     );
   }
@@ -1439,7 +1491,7 @@ export class RscRenderer {
     });
   }
 
-  async #renderNotFound(url: URL): Promise<ReactNode> {
+  async #renderNotFound(url: URL, gate?: RouteShellGate): Promise<ReactNode> {
     const matchedFallback = RouteTreeBuilder.matchFallback(url.pathname, this.#fallbackRoutes);
     if (matchedFallback) {
       const searchParams = parseSearchParams(url.search);
@@ -1455,6 +1507,7 @@ export class RscRenderer {
           searchParams,
           pathname: url.pathname,
           url,
+          gate,
         });
         if (fallback) return fallback;
       } catch (error) {
@@ -1562,7 +1615,7 @@ export class RscRenderer {
     const publicUrl = RscRenderer.#getPublicRequestUrl(url);
     for (const lang of this.#i18n.locales) {
       const alternateUrl = new URL(publicUrl);
-      alternateUrl.pathname = RscRenderer.#replaceLocalePathSegment(publicUrl.pathname, lang);
+      alternateUrl.pathname = RscRenderer.#replaceLocalePathSegment(publicUrl.pathname, lang, this.#i18n);
       languages[lang] = alternateUrl.href;
     }
     const xDefaultUrl = new URL(publicUrl);
@@ -1612,10 +1665,9 @@ export class RscRenderer {
     return publicUrl;
   }
 
-  static #replaceLocalePathSegment(pathname: string, lang: string): string {
+  static #replaceLocalePathSegment(pathname: string, lang: string, i18n: AkanI18nConfig): string {
     const parts = pathname.split("/").filter(Boolean);
-    if (parts.length === 0) return `/${lang}`;
-    return `/${[lang, ...parts.slice(1)].join("/")}`;
+    return LocalePath.join(lang, `/${parts.slice(1).join("/")}`, i18n);
   }
 }
 

package/server/sitemap.ts

@@ -1,4 +1,4 @@
-import { type AkanI18nConfig, trimSlashes, trimTrailingSlashes } from "akanjs/common";
+import { type AkanI18nConfig, LocalePath, trimSlashes, trimTrailingSlashes } from "akanjs/common";
 import type { RouteSeedEntry } from "./artifact";
 
 export interface DefaultSitemapOptions {
@@ -26,7 +26,7 @@ export function createDefaultSitemapXml({ origin, basePath, entries, i18n }: Def
 export function createDefaultSitemapUrls({ origin, basePath, entries, i18n }: DefaultSitemapOptions): string[] {
   const normalizedOrigin = trimTrailingSlashes(origin);
   const normalizedBasePath = normalizeSegment(basePath ?? "");
-  const paths = entries.flatMap((entry) => expandStaticRoute(entry.pattern, normalizedBasePath, i18n.locales));
+  const paths = entries.flatMap((entry) => expandStaticRoute(entry.pattern, normalizedBasePath, i18n));
   return paths.map((pathname) => `${normalizedOrigin}${pathname}`);
 }
 
@@ -46,7 +46,7 @@ export function getSitemapBasePath(
   return basePaths.map(normalizeSegment).includes(normalizedHeaderBasePath) ? normalizedHeaderBasePath : undefined;
 }
 
-function expandStaticRoute(pattern: string, basePath: string, locales: readonly string[]): string[] {
+function expandStaticRoute(pattern: string, basePath: string, i18n: AkanI18nConfig): string[] {
   const segments = pattern.split("/").filter(Boolean);
   const langIndex = segments.indexOf(":lang");
   if (langIndex < 0) return [];
@@ -59,10 +59,8 @@ function expandStaticRoute(pattern: string, basePath: string, locales: readonly
     staticSegments = staticSegments.slice(1);
   }
 
-  return locales.map((locale) => {
-    const parts = [locale, ...staticSegments].filter(Boolean);
-    return `/${parts.map(encodePathSegment).join("/")}`;
-  });
+  const path = `/${staticSegments.filter(Boolean).map(encodePathSegment).join("/")}`;
+  return i18n.locales.map((locale) => LocalePath.join(locale, path, i18n));
 }
 
 function normalizePathname(pathname: string): string {

package/server/ssrFromRscRenderer.tsx

@@ -608,7 +608,14 @@ export class SsrFromRscRenderer {
         inlineBoundaries: input.inlineBoundaries,
         onError: (error, phase) => SsrFromRscRenderer.#reportRenderError(error, input, phase),
       });
-    const htmlStream = await inRequestScope(renderHtml);
+    let htmlStream: ReadableStream<Uint8Array>;
+    try {
+      htmlStream = await inRequestScope(renderHtml);
+    } catch (error) {
+      stderrSuppressor?.stop();
+      void rscForClient.cancel(error).catch(() => {});
+      throw error;
+    }
 
     const withHeadScripts = SsrFromRscRenderer.#injectHeadScriptsIntoHead(htmlStream, {
       importmap: input.importmap,
@@ -638,7 +645,7 @@ export class SsrFromRscRenderer {
     const registry = new SsrChunkRegistry<Record<string, unknown>>(
       parsePositiveInt(process.env.AKAN_SSR_CHUNK_REGISTRY_MAX_ENTRIES) ?? DEFAULT_SSR_CHUNK_REGISTRY_MAX_ENTRIES,
     );
-    g.__webpack_chunk_load__ = async (chunkId: string) => {
+    const loadChunk = async (chunkId: string) => {
       if (registry.get(chunkId)) {
         SsrFromRscRenderer.#chunkRegistryStats.ssrChunkCacheHitCount += 1;
         return;
@@ -651,6 +658,14 @@ export class SsrFromRscRenderer {
       SsrFromRscRenderer.#chunkRegistryStats.ssrChunkRegistrySize = registry.size;
       SsrFromRscRenderer.#chunkRegistryStats.ssrChunkEvictionCount = registry.evictionCount;
     };
+    g.__webpack_chunk_load__ = (chunkId: string) => {
+      const load = loadChunk(chunkId);
+      const loading = SsrFromRscRenderer.#chunkLoads();
+      const settle = () => loading.delete(load);
+      loading.add(load);
+      load.then(settle, settle);
+      return load;
+    };
     g.__webpack_require__ = (id: string) => {
       const mod = registry.get(id);
       if (!mod) throw new Error(`[ssrFromRsc] module not loaded yet: ${id}`);
@@ -662,14 +677,31 @@ export class SsrFromRscRenderer {
     const stream = await renderToReadableStream(root, {
       bootstrapScriptContent: options.bootstrap,
       
-      ...(options.inlineBoundaries ? { progressiveChunkSize: Number.POSITIVE_INFINITY } : {}),
+      progressiveChunkSize: Number.POSITIVE_INFINITY,
       onError: (error) => options.onError(error),
     });
     if (options.waitForAllReady || options.inlineBoundaries) await stream.allReady;
-    else SsrFromRscRenderer.holdPostShellErrors(stream, (error) => options.onError(error, "post-shell"));
+    else {
+      SsrFromRscRenderer.holdPostShellErrors(stream, (error) => options.onError(error, "post-shell"));
+      await SsrFromRscRenderer.#settleChunkLoads();
+    }
     return stream;
   }
 
+  static async #settleChunkLoads(): Promise<void> {
+    const loading = SsrFromRscRenderer.#chunkLoads();
+    for (let round = 0; round < 4 && loading.size > 0; round++) {
+      await Promise.allSettled(loading);
+      for (let turn = 0; turn < 2; turn++) await new Promise((resolve) => setTimeout(resolve, 0));
+    }
+  }
+
+  static #chunkLoads(): Set<Promise<void>> {
+    const g = globalThis as unknown as { __rsc_ssr_chunk_loads__?: Set<Promise<void>> };
+    g.__rsc_ssr_chunk_loads__ ??= new Set();
+    return g.__rsc_ssr_chunk_loads__;
+  }
+
   static holdPostShellErrors(stream: { allReady: Promise<void> }, report: (error: unknown) => void): void {
     void stream.allReady.catch(report);
   }

package/server/ssrTypes.ts

@@ -63,9 +63,12 @@ export interface SsrFromRscInput {
   injectThemeInitScript?: boolean;
   lateControl?: Promise<SsrLateControl | null>;
   onCancel?: (reason?: unknown) => void;
-  /** Buffers until `stream.allReady` (`pageConfig.ssr: "block"`); `AKAN_SSR_WAIT_FOR_ALL_READY=1` forces it globally. */
+  /**
+   * Buffers until `stream.allReady` and writes every Suspense boundary in place (`pageConfig.ssr: "block"`);
+   * `AKAN_SSR_WAIT_FOR_ALL_READY=1` forces it globally.
+   */
   waitForAllReady?: boolean;
-  /** Buffers like `waitForAllReady` and writes every Suspense boundary in place, for a reader that runs no script. */
+  /** Buffers like `waitForAllReady`, for a reader that runs no script. */
   inlineBoundaries?: boolean;
 }
 

package/server/staticPath.ts

@@ -1,5 +1,40 @@
+import fs from "node:fs";
 import path from "node:path";
 
+const isWithin = (child: string, parent: string) =>
+  child === parent || child.startsWith(parent.endsWith(path.sep) ? parent : parent + path.sep);
+
+const realPathOf = (target: string): string | null => {
+  try {
+    return fs.realpathSync(target);
+  } catch {
+    return null;
+  }
+};
+
+const libLinkTarget = (baseDir: string, filePath: string): string | null => {
+  const [libs, lib] = path.relative(baseDir, filePath).split(path.sep);
+  if (libs !== "libs" || !lib) return null;
+  const target = realPathOf(path.join(baseDir, libs, lib));
+  if (!target || path.basename(target) !== path.basename(baseDir)) return null;
+  const libDir = path.dirname(target);
+  return path.basename(libDir) === lib && path.basename(path.dirname(libDir)) === "libs" ? target : null;
+};
+
+export const staysInTree = (baseDir: string, filePath: string): boolean => {
+  let real: string;
+  try {
+    real = fs.realpathSync(filePath);
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    return code === "ENOENT" || code === "ENOTDIR";
+  }
+  const base = path.resolve(baseDir);
+  if (isWithin(real, realPathOf(base) ?? base)) return true;
+  const libTarget = libLinkTarget(base, filePath);
+  return !!libTarget && isWithin(real, libTarget);
+};
+
 export const resolveStaticPath = (baseDir: string, urlPath: string): string | null => {
   let decoded: string;
   try {
@@ -14,5 +49,5 @@ export const resolveStaticPath = (baseDir: string, urlPath: string): string | nu
   if (resolved === normalizedBase) return resolved;
   const baseWithSep = normalizedBase.endsWith(path.sep) ? normalizedBase : normalizedBase + path.sep;
   if (!resolved.startsWith(baseWithSep)) return null;
-  return resolved;
+  return staysInTree(normalizedBase, resolved) ? resolved : null;
 };

package/server/systemPageDocument.tsx

@@ -1,5 +1,5 @@
 import type { AkanI18nConfig } from "akanjs/common";
-import { DEFAULT_AKAN_I18N, getBasePathFromPathname } from "akanjs/common";
+import { DEFAULT_AKAN_I18N, getBasePathFromPathname, LocalePath } from "akanjs/common";
 import type { ReactNode } from "react";
 
 export type SystemPageKind = "not-found" | "error";
@@ -80,7 +80,7 @@ export const SystemPageMain = (options: Omit<SystemPageOptions, "lang" | "styles
           <a className="akan-system-action" href={options.homeHref}>
             {copy.actionLabel}
           </a>
-          <a className="akan-system-action akan-system-secondary" href={options.pathname}>
+          <a className="akan-system-action akan-system-secondary" href={getSameOriginHref(options.pathname)}>
             Try again
           </a>
         </div>
@@ -122,6 +122,8 @@ export function createSystemPageDocument(options: SystemPageOptions): ReactNode
   );
 }
 
+export const getSameOriginHref = (pathname: string): string => `/${pathname.replace(/^[\s/\\]+/, "")}`;
+
 export function getSystemPageErrorDetails(error: unknown): string {
   if (error instanceof Error) return error.stack ?? error.message;
   return String(error);
@@ -144,7 +146,7 @@ export function getSystemPageHomeHref({
     i18n,
     headerBasePath,
   });
-  return `/${[locale, basePath].filter(Boolean).join("/")}`;
+  return LocalePath.join(locale, basePath ? `/${basePath}` : "/", i18n);
 }
 
 export interface SubRouteIndexOptions {

package/server/systemPages.tsx

@@ -1,4 +1,5 @@
 import type { ReactNode } from "react";
+import { applySecurityHeaders } from "./assetHeaders";
 import {
   createSubRouteIndexDocument,
   createSystemPageDocument,
@@ -38,10 +39,13 @@ export async function createSubRouteIndexResponse(options: SubRouteIndexResponse
 }
 
 export function createSystemPageHeaders(): Headers {
-  return new Headers({
-    "Content-Type": "text/html; charset=utf-8",
-    "Cache-Control": "no-store",
-  });
+  return applySecurityHeaders(
+    new Headers({
+      "Content-Type": "text/html; charset=utf-8",
+      "Cache-Control": "no-store",
+    }),
+    { html: true },
+  );
 }
 
 export function createSystemPageFallbackText(kind: SystemPageKind): string {
@@ -70,10 +74,12 @@ async function renderDocumentResponse({
   } catch {
     return new Response(fallbackText(), {
       status,
-      headers: {
-        "Content-Type": "text/plain; charset=utf-8",
-        "Cache-Control": "no-store",
-      },
+      headers: applySecurityHeaders(
+        new Headers({
+          "Content-Type": "text/plain; charset=utf-8",
+          "Cache-Control": "no-store",
+        }),
+      ),
     });
   }
 }

package/server/tunnel/TunnelAgent.ts

@@ -10,12 +10,18 @@ import { TunnelDataSocket } from "./TunnelDataSocket";
 export interface TunnelAgentOptions {
   /** The gateway, as `wss://tunnel.akanjs.com` — scheme included, no path, no trailing slash. */
   gatewayUrl: string;
+  /** Accepts a `ws://` gateway off loopback, whose frames and token would cross the network in cleartext. */
+  allowInsecureGateway?: boolean;
   token: string;
   hostnames: string[];
   /** The local app, as `http://localhost:8282`. */
   origin: string;
   /** Where a `tcp` stream dials. Local by construction: an agent is a door into one machine, not a router. */
   tcpHost?: string;
+  /** The only ports a `tcp` stream may dial; none by default, so the gateway can reach nothing but `origin`. */
+  tcpPorts?: readonly number[];
+  /** The data sockets this agent ever holds, whatever the gateway asks for (default 128). */
+  maxSockets?: number;
   name?: string;
   /** Attempts on a link that has never gone ready before the agent gives up (default 10). */
   retryLimit?: number;
@@ -55,9 +61,18 @@ export class TunnelAgent {
   #stopped = false;
 
   constructor(options: TunnelAgentOptions) {
+    TunnelAgent.#assertGateway(options.gatewayUrl, options.allowInsecureGateway ?? false);
     this.#options = options;
   }
 
+  static #assertGateway(gatewayUrl: string, allowInsecure: boolean) {
+    const url = URL.parse(gatewayUrl);
+    if (url?.protocol === "wss:") return;
+    if (url?.protocol === "ws:" && (allowInsecure || ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)))
+      return;
+    throw new Error(`Tunnel gateway must be a wss:// URL (ws:// only on loopback), not ${gatewayUrl}`);
+  }
+
   get ready() {
     return this.#ready;
   }
@@ -220,18 +235,20 @@ export class TunnelAgent {
     const ready = this.#ready;
     if (!ready || this.#stopped) return;
     const idle = [...this.#sockets].filter((socket) => !socket.busy).length;
-    const room = Math.min(ready.idle - idle, ready.maxSockets - this.#sockets.size);
+    const ceiling = Math.min(ready.maxSockets, this.#options.maxSockets ?? tunnelWireContract.defaultMaxSockets);
+    const room = Math.min(ready.idle - idle, ceiling - this.#sockets.size);
     for (let opened = 0; opened < room; opened += 1) this.#open(ready.sessionId);
   }
 
   #open(sessionId: string) {
-    const { gatewayUrl, token, origin, tcpHost = "127.0.0.1" } = this.#options;
+    const { gatewayUrl, token, origin, tcpHost = "127.0.0.1", tcpPorts = [] } = this.#options;
     const socket = new TunnelDataSocket({
       gatewayUrl,
       token,
       sessionId,
       origin,
       tcpHost,
+      tcpPorts,
       logger: this.logger,
       onIdle: () => this.#grow(),
       onBusy: () => this.#grow(),

package/server/tunnel/TunnelDataSocket.ts

@@ -12,6 +12,8 @@ export interface TunnelDataSocketOptions {
   origin: string;
   /** Where a `tcp` stream dials; the port comes from the open frame. */
   tcpHost: string;
+  /** The ports an open frame may name; any other is refused. */
+  tcpPorts: readonly number[];
   logger: Logger;
   onIdle: (socket: TunnelDataSocket) => void;
   onBusy: (socket: TunnelDataSocket) => void;
@@ -114,7 +116,7 @@ export class TunnelDataSocket {
   }
 
   #start(open: TunnelOpenFrame) {
-    const { origin, tcpHost } = this.#options;
+    const { origin, tcpHost, tcpPorts } = this.#options;
     const link: TunnelStreamLink = {
       sendFrame: (frame) => this.#send(frame),
       sendPayload: (payload) => this.#sendPayload(payload),
@@ -125,7 +127,7 @@ export class TunnelDataSocket {
       open.kind === "websocket"
         ? new TunnelWebsocketStream(open, link, origin)
         : open.kind === "tcp"
-          ? new TunnelTcpStream(open, link, tcpHost)
+          ? new TunnelTcpStream(open, link, tcpHost, tcpPorts)
           : new TunnelHttpStream(open, link, origin);
     this.#options.onBusy(this);
     void this.#stream.run();

package/server/tunnel/TunnelHttpStream.ts

@@ -1,5 +1,5 @@
 import { type TunnelOpenFrame, tunnelWireContract } from "akanjs/common";
-import { type TunnelStream, type TunnelStreamLink, tunnelResetCodeOf } from "./tunnelStream";
+import { type TunnelStream, type TunnelStreamLink, tunnelResetCodeOf, tunnelTargetUrl } from "./tunnelStream";
 
 const reframedHeaders = new Set(["content-encoding", "content-length"]);
 
@@ -26,8 +26,13 @@ export class TunnelHttpStream implements TunnelStream {
 
   async run() {
     const { streamId, method = "GET", path = "/", headers = [] } = this.#open;
+    const target = tunnelTargetUrl(this.#origin, path);
+    if (!target) {
+      this.#link.sendFrame({ type: "reset", streamId, code: "protocol", message: "path leaves the shared origin" });
+      return;
+    }
     try {
-      const response = await fetch(`${this.#origin}${path}`, {
+      const response = await fetch(target, {
         method,
         headers: tunnelWireContract.headersOf(headers),
         body: this.#bodyStream,