akanjs 3.0.0-beta.27 → 3.0.0-beta.29

package/server/akanApp.ts

@@ -4,8 +4,9 @@ import path from "node:path";
 import { Logger } from "akanjs/common";
 import type { AkanChildRole, AkanChildStatus, AkanIpcMessage, AkanMetricsReport, AkanUpstream } from "akanjs/service";
 import { getApiPrefix, getWsPrefix, normalizeRoutePrefix, resetEnvCache } from "../base/baseEnv";
+import { CrossSiteGuard } from "../signal/CrossSiteGuard";
 import { isTraceEnabled } from "../signal/trace";
-import { makeAkanChildProxyHeaders } from "./akanAppHeaders";
+import { AKAN_CHILD_HOST, makeAkanChildProxyHeaders } from "./akanAppHeaders";
 import type { BuilderCsrReq, BuilderCsrRes, BuilderMessage, BuilderReq, BuilderRes } from "./artifact";
 import { compressResponse, encodedFileResponse } from "./contentEncoding";
 import { isPortInUseError } from "./lifecycle/portInUse";
@@ -19,6 +20,8 @@ import { RotatingLogWriter } from "./logging/rotatingLogWriter";
 import { AppInfo } from "./ops/appInfo";
 import type { OpsRoute } from "./ops/opsRoute";
 import { ProcessMetricsCollector } from "./processMetricsCollector";
+import { HostAllowlist } from "./routing/hostAllowlist";
+import { SelfExec } from "./selfExec";
 import { resolveStaticPath } from "./staticPath";
 import { getWebConfigFromEnv } from "./types";
 
@@ -139,6 +142,7 @@ export class AkanApp {
   #logControl: LogControlSocket | null = null;
   #logStream: LogStreamRoute | null = null;
   #ops: OpsRoute | null = null;
+  #hostAllowlist = HostAllowlist.fromEnv();
   static readonly #ansiPattern = new RegExp(`${String.fromCharCode(27)}\\[[0-?]*[ -/]*[@-~]`, "g");
   #gatewayMetrics: AkanMetricsReport = {};
   #proxyHopCount = 0;
@@ -149,6 +153,7 @@ export class AkanApp {
   #stopping = false;
 
   constructor(serverPathOrOptions: string | AkanAppOptions = "./server", options: AkanAppOptions = {}) {
+    SelfExec.adopt();
     const resolvedOptions = typeof serverPathOrOptions === "string" ? options : serverPathOrOptions;
     const serverPath = typeof serverPathOrOptions === "string" ? serverPathOrOptions : "./server";
     this.#serverPath = AkanApp.#resolveServerPath(resolvedOptions.serverPath ?? serverPath);
@@ -235,6 +240,10 @@ export class AkanApp {
       process.exit(await OpsCommand.run(process.argv.slice(3)));
     }
     if (this.#solo) return await this.#startSolo();
+    if (SelfExec.carried)
+      throw new Error(
+        "A desktop app's server runs in one process, and this one was asked for a gateway and replicas, which would start with the `bun` on the user's PATH: by `replica` or `solo: false` in main.ts, or by AKAN_SOLO=false, an AKAN_REPLICA other than one traffic replica, or AKAN_COMMAND_TYPE=start in its env. Leave them out of the app the desktop build carries.",
+      );
     Logger.role = "gateway";
     await this.#prepareRuntimeDir();
     await this.#startLogHub();
@@ -579,6 +588,7 @@ export class AkanApp {
     this.#server = Bun.serve({
       idleTimeout: 0,
       port: this.#port,
+      hostname: process.env.AKAN_LISTEN_HOST || undefined,
       fetch: (req, server) => this.#handleFetch(req, server),
       websocket: {
         idleTimeout: 0,
@@ -595,6 +605,7 @@ export class AkanApp {
   }
 
   async #handleFetch(req: Request, server: Bun.Server<GatewayWsData>): Promise<Response | undefined> {
+    if (this.#hostAllowlist && !this.#hostAllowlist.allows(req)) return this.#hostAllowlist.refuse();
     const url = new URL(req.url);
     if (url.pathname === "/_akan/app/health") return Response.json(this.#getHealthStatus());
     if (url.pathname === "/_akan/app/metrics") return Response.json(this.#getMetricsStatus());
@@ -638,6 +649,12 @@ export class AkanApp {
     const upstream = child?.upstream ? (child.wsUpstream ?? this.#getChildUpstream(child.idx, child.role).ws) : null;
     if (!child || !upstream) return new Response("No websocket upstream is ready", { status: 503 });
     const url = new URL(req.url);
+    
+    try {
+      CrossSiteGuard.assertOrigin(req, url, url.pathname === "/_akan/hmr" ? "hmr" : "websocket");
+    } catch {
+      return new Response("Forbidden", { status: 403 });
+    }
     const upstreamWs = new WebSocket(`ws://${upstream.host}:${upstream.port}${url.pathname}${url.search}`, {
       headers: makeAkanChildProxyHeaders(req, child.idx, server.requestIP(req)),
     } as unknown as string[]);
@@ -926,8 +943,10 @@ export class AkanApp {
   async #proxyResponse(req: Request, upstreamRes: Response): Promise<Response> {
     const headers = new Headers(upstreamRes.headers);
     
-    headers.delete("content-encoding");
-    headers.delete("content-length");
+    if (headers.has("content-encoding")) {
+      headers.delete("content-encoding");
+      headers.delete("content-length");
+    }
     this.#rewriteInternalLocation(headers);
     const proxied = new Response(upstreamRes.body, {
       status: upstreamRes.status,
@@ -947,7 +966,8 @@ export class AkanApp {
     if (!location) return;
     try {
       const parsed = new URL(location);
-      if (parsed.hostname === "akan-child") headers.set("location", `${parsed.pathname}${parsed.search}${parsed.hash}`);
+      if (parsed.hostname === AKAN_CHILD_HOST)
+        headers.set("location", `${parsed.pathname}${parsed.search}${parsed.hash}`);
     } catch {
     }
   }
@@ -1074,6 +1094,7 @@ export class AkanApp {
     child.upstream = message.upstream;
     child.wsUpstream = message.wsUpstream;
     child.healthPath = message.healthPath;
+    if (message.crossSite) CrossSiteGuard.configure(message.crossSite);
     child.lastPongAtMono = performance.now();
     child.restartAttempts = 0;
     
@@ -1084,7 +1105,8 @@ export class AkanApp {
     this.#federationChildCache = null;
     
     const trafficChildren = [...this.#children.values()].filter((item) => item.role !== "batch");
-    if (child.role !== "batch" && trafficChildren.every((item) => item.ready)) {
+    
+    if (!this.#stopping && child.role !== "batch" && trafficChildren.every((item) => item.ready)) {
       process.send?.({ type: "backend-ready", pid: process.pid } satisfies AkanIpcMessage);
     }
     if ([...this.#children.values()].every((item) => item.ready)) {

package/server/akanAppHeaders.ts

@@ -11,6 +11,9 @@ const HOP_BY_HOP_HEADERS = new Set([
   "upgrade",
 ]);
 
+/** The Host every request the gateway hands a replica carries; a browser never sends it to a replica's port. */
+export const AKAN_CHILD_HOST = "akan-child";
+
 export interface ProxyClientPeer {
   address: string;
   port: number;
@@ -44,6 +47,6 @@ export function makeAkanChildProxyHeaders(req: Request, childIdx: number, peer?:
   if (!headers.has("x-request-id") && process.env.AKAN_BENCH_SKIP_REQUEST_ID !== "1") {
     headers.set("x-request-id", crypto.randomUUID());
   }
-  headers.set("host", "akan-child");
+  headers.set("host", AKAN_CHILD_HOST);
   return headers;
 }

package/server/akanServer.ts

@@ -19,11 +19,13 @@ import { AgentRelayAccess } from "../signal/guards";
 import { createOpenApiDocument } from "../signal/openapi";
 import { FetchSerializer } from "../signal/serializer";
 import { SignalContext } from "../signal/signalContext";
+import { AKAN_CHILD_HOST } from "./akanAppHeaders";
 import type { AkanLib, AkanLibProps } from "./akanLib";
 import { BinaryPubsub } from "./binaryPubsub";
 import { DevtoolsRouter } from "./devtools";
 import { DiLifecycle } from "./di/diLifecycle";
 import type { HmrWsData, HmrWsHub } from "./hmr/wsHub";
+import { OrphanGroup } from "./lifecycle/orphanGroup";
 import { isPortInUseError } from "./lifecycle/portInUse";
 import { resolveRuntimeDir } from "./lifecycle/runtimeDir";
 import { ShutdownManager } from "./lifecycle/shutdownManager";
@@ -42,6 +44,7 @@ import { WebProxyRunner } from "./proxy";
 import { SignalResolver } from "./resolver";
 import { type ApiRouteInputs, ApiRouter } from "./routing/apiRouter";
 import type { AppWsData } from "./routing/appWsData";
+import { HostAllowlist } from "./routing/hostAllowlist";
 import { createSoloAppRoutes } from "./routing/soloAppRoutes";
 import {
   getWebConfigFromEnv,
@@ -167,6 +170,8 @@ export class AkanServer {
   #ops: OpsRoute | null | undefined;
   #lastMetrics: AkanMetricsReport = {};
   #stopping: Promise<void> | null = null;
+  #parentGone: boolean = false;
+  #orphanExiting = false;
   constructor(
     name = "AkanServer",
     env: BackendEnv = {},
@@ -392,7 +397,10 @@ export class AkanServer {
       }),
       data: {},
     } as Bun.WebSocketHandler<AppWsData | HmrWsData>;
-    const buildRoutes = (upgradeAppWs: ApiRouteInputs["upgradeAppWs"]) =>
+    
+    const hostAllowlist = unix ? null : HostAllowlist.fromEnv();
+    const hostname = process.env.AKAN_LISTEN_HOST || undefined;
+    const buildRoutes = (upgradeAppWs: ApiRouteInputs["upgradeAppWs"], allowlist: HostAllowlist | null) =>
       ApiRouter.buildRoutes({
         prefix: this.prefix,
         websocketPrefix: this.websocketPrefix,
@@ -402,19 +410,25 @@ export class AkanServer {
         renderEnvRoutes,
         upgradeAppWs,
         webProxyRunner,
+        hostAllowlist: allowlist,
       });
     this.#server = Bun.serve({
       idleTimeout: 0,
-      ...(unix ? { unix } : { port }),
-      routes: buildRoutes((req, data) => this.#server?.upgrade(req, { data }) ?? false),
+      ...(unix ? { unix } : { port, hostname }),
+      routes: buildRoutes((req, data) => this.#server?.upgrade(req, { data }) ?? false, hostAllowlist),
       websocket: websocketHandlers,
     } as Parameters<typeof Bun.serve>[0]);
     if (unix && process.env.AKAN_CHILD_WS_PORT) {
       const preferredWsPort = Number(process.env.AKAN_CHILD_WS_PORT);
+
       const wsServeOptions = (port: number) => ({
         idleTimeout: 0,
         port,
-        routes: buildRoutes((req, data) => this.#wsServer?.upgrade(req, { data }) ?? false),
+        hostname: "127.0.0.1",
+        routes: buildRoutes(
+          (req, data) => this.#wsServer?.upgrade(req, { data }) ?? false,
+          new HostAllowlist([AKAN_CHILD_HOST]),
+        ),
         websocket: websocketHandlers,
       });
       try {
@@ -459,7 +473,7 @@ export class AkanServer {
     this.#di.registerSchedule(this.serverMode);
     this.logger.verbose(`🚀 ${this.name} is running on ${unix ? `unix://${unix}` : `port ${port}`}`);
     const wsPort = this.#wsServer?.port;
-    process.send?.({
+    this.#sendReady({
       type: "ready",
       pid: process.pid,
       replicaIdx: Number(process.env.AKAN_REPLICA_IDX ?? 0),
@@ -467,7 +481,8 @@ export class AkanServer {
       upstream: unix ? { type: "unix", socketPath: unix } : { type: "tcp", host: "127.0.0.1", port: Number(port) },
       wsUpstream: typeof wsPort === "number" ? { type: "tcp", host: "127.0.0.1", port: wsPort } : undefined,
       healthPath: "/_akan/app/child-health",
-    } satisfies AkanIpcMessage);
+      crossSite: CrossSiteGuard.option(),
+    });
     await this.#di.runSchedulerInit();
     ShutdownManager.register(this.logger, () => this.stop());
     return this;
@@ -476,7 +491,10 @@ export class AkanServer {
   async start({ listen, web }: { listen?: boolean; web?: AkanWebOption } = {}) {
     const isNoListenCommand = process.env.AKAN_COMMAND_TYPE === "script" || process.env.AKAN_COMMAND_TYPE === "console";
     const shouldListen = (listen ?? !isNoListenCommand) && this.serverMode !== "batch";
+    
+    if (shouldListen || !isNoListenCommand) this.#registerParentIpc();
     await this.init({ routes: shouldListen, web });
+    if (this.#parentGone) return this;
     if (!shouldListen) {
       const websocket = this.#di.getWebsocketAdaptor();
       if (websocket)
@@ -486,20 +504,18 @@ export class AkanServer {
         Logger.role = this.serverMode;
         this.#metricsTimer ??= ProcessMetricsCollector.startReporting(() => this.#reportMetrics());
         this.#di.registerSchedule(this.serverMode);
-        this.#registerParentIpc();
         await this.#startLogTransport();
-        process.send?.({
+        this.#sendReady({
           type: "ready",
           pid: process.pid,
           replicaIdx: Number(process.env.AKAN_REPLICA_IDX ?? 0),
           role: this.serverMode,
-        } satisfies AkanIpcMessage);
+        });
         await this.#di.runSchedulerInit();
         ShutdownManager.register(this.logger, () => this.stop());
       }
       return this;
     }
-    this.#registerParentIpc();
     return this.listen();
   }
   stop(): Promise<void> {
@@ -546,14 +562,28 @@ export class AkanServer {
   #registerParentIpc() {
     process.on("message", (message) => this.#handleIpcMessage(message as AkanIpcMessage));
     process.on("disconnect", () => this.#handleParentDisconnect());
+    
+    if (process.send && !process.connected) this.#handleParentDisconnect();
+  }
+
+  #sendReady(message: AkanIpcMessage) {
+    if (process.send?.(message) === false) this.#handleParentDisconnect();
   }
 
   #handleParentDisconnect() {
+    if (this.#parentGone) return;
+    this.#parentGone = true;
     this.logger.warn("Parent IPC channel closed; shutting down to avoid an orphaned replica");
-    setTimeout(() => process.exit(1), this.shutdownTimeoutMs + 1_000);
+    setTimeout(() => this.#exitOrphaned(1), this.shutdownTimeoutMs + 1_000);
     void this.stop()
-      .then(() => process.exit(0))
-      .catch(() => process.exit(1));
+      .then(() => this.#exitOrphaned(0))
+      .catch(() => this.#exitOrphaned(1));
+  }
+
+  #exitOrphaned(code: number) {
+    if (this.#orphanExiting) return;
+    this.#orphanExiting = true;
+    OrphanGroup.exit(code);
   }
 
   #handleIpcMessage(message: AkanIpcMessage) {

package/server/contentEncoding.ts

@@ -32,6 +32,8 @@ const GZIP_LEVEL = 6;
 /** Under a KB the framing bytes and the call cost more than the repetition they remove. */
 const MIN_COMPRESS_BYTES = 1024;
 
+const MAX_COMPRESS_BYTES = 4 * 1024 * 1024;
+
 const compressBody = (bytes: Uint8Array, encoding: ContentEncoding) =>
   encoding === "br"
     ? brotliCompressSync(bytes, {
@@ -42,8 +44,17 @@ const compressBody = (bytes: Uint8Array, encoding: ContentEncoding) =>
       })
     : gzipSync(bytes, { level: GZIP_LEVEL });
 
+const isWholeBody = (req: Request, response: Response) =>
+  !req.headers.has("range") &&
+  !response.headers.has("content-range") &&
+  response.status >= 200 &&
+  response.status < 300 &&
+  response.status !== 206;
+
 export const compressResponse = async (req: Request, response: Response): Promise<Response> => {
   if (response.headers.has("content-encoding") || !response.body) return response;
+  if (!isWholeBody(req, response)) return response;
+  if (Number(response.headers.get("content-length")) > MAX_COMPRESS_BYTES) return response;
   if (!isCompressibleContentType(response.headers.get("content-type") ?? "")) return response;
   if (process.env.AKAN_HTTP_COMPRESS === "false" || process.env.AKAN_HTTP_COMPRESS === "0") return response;
   const acceptEncoding = req.headers.get("accept-encoding") ?? "";

package/server/index.ts

@@ -7,6 +7,7 @@ export * from "./console";
 export * from "./decorators";
 export * from "./devtools";
 export type { ChangeBatch, ChangeKind } from "./hmr/wsHub";
+export * from "./nativeFile";
 export * from "./oauth";
 export * from "./processMetricsCollector";
 export * from "./proxy";

package/server/lifecycle/orphanGroup.ts

@@ -0,0 +1,21 @@
+import { SelfExec } from "../selfExec";
+
+export class OrphanGroup {
+  static exit(code: number, { leads = SelfExec.carried && process.platform !== "win32", graceMs = 1_000 } = {}) {
+    if (!leads) process.exit(code);
+    process.removeAllListeners("SIGTERM");
+    process.on("SIGTERM", () => undefined);
+    OrphanGroup.#signal("SIGTERM");
+    setTimeout(() => {
+      OrphanGroup.#signal("SIGKILL");
+      process.exit(code);
+    }, graceMs);
+  }
+
+  static #signal(signal: NodeJS.Signals) {
+    try {
+      process.kill(-process.pid, signal);
+    } catch {
+    }
+  }
+}

package/server/nativeFile.ts

@@ -0,0 +1,107 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { lstatSync, readFileSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { getEnv } from "akanjs/base";
+import type { AkanIpcMessage } from "akanjs/service";
+
+export type NativeFileMode = "read" | "write" | "folder";
+
+type Resolved = Extract<AkanIpcMessage, { type: "file.resolved" }>;
+
+export class NativeFile {
+  static timeoutMs = 5_000;
+  static operationMode: () => string = () => getEnv().operationMode;
+  static readonly #waiting = new Map<string, (answer: Resolved) => void>();
+  static #listener: ((message: unknown) => void) | null = null;
+
+  /** The path behind `grant`, which the user must have given for `mode`. */
+  static async resolve(grant: string, mode: NativeFileMode): Promise<string> {
+    const found = grant.startsWith("dev:") ? NativeFile.#devGrant(grant) : await NativeFile.#ask(grant);
+    if (found.mode !== mode) throw new Error(`The file was granted to ${found.mode}, not to ${mode}.`);
+    return found.path;
+  }
+
+  /** A path inside a folder grant; one that climbs out of the folder is refused. */
+  static async resolveIn(grant: string, relative: string): Promise<string> {
+    const folder = await NativeFile.resolve(grant, "folder");
+    const target = path.resolve(folder, relative);
+    NativeFile.#assertInside(folder, target, relative);
+
+    NativeFile.#assertInside(NativeFile.#realPath(folder), NativeFile.#realPath(target), relative);
+    return target;
+  }
+
+  static #assertInside(folder: string, target: string, relative: string) {
+    const inside = path.relative(folder, target);
+    if (inside === ".." || inside.startsWith(`..${path.sep}`) || path.isAbsolute(inside))
+      throw new Error(`${relative} is outside the folder the user granted.`);
+  }
+
+  static #realPath(target: string): string {
+    const rest: string[] = [];
+    for (let current = target; ; current = path.dirname(current)) {
+      try {
+        return path.join(realpathSync.native(current), ...rest);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "ENOENT" || path.dirname(current) === current) throw error;
+        if (NativeFile.#exists(current)) throw new Error(`${target} is a link to nothing.`);
+        rest.unshift(path.basename(current));
+      }
+    }
+  }
+
+  static #exists(entry: string) {
+    try {
+      lstatSync(entry);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  static #ask(grant: string): Promise<{ path: string; mode: NativeFileMode }> {
+    const send = process.send?.bind(process);
+    if (!send) return Promise.reject(new Error("A file grant resolves only inside the desktop app that gave it."));
+    NativeFile.#listen();
+    const id = crypto.randomUUID();
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        NativeFile.#waiting.delete(id);
+        reject(new Error("The desktop app did not answer for the file grant."));
+      }, NativeFile.timeoutMs);
+      NativeFile.#waiting.set(id, (answer) => {
+        clearTimeout(timer);
+        NativeFile.#waiting.delete(id);
+        if (answer.path && answer.mode) resolve({ path: answer.path, mode: answer.mode });
+        else reject(new Error(answer.error ?? "The desktop app refused the file grant."));
+      });
+      send({ type: "file.resolve", id, grant } satisfies AkanIpcMessage);
+    });
+  }
+
+  static #listen() {
+    if (NativeFile.#listener) return;
+    NativeFile.#listener = (message) => {
+      const answer = message as AkanIpcMessage | null;
+      if (answer?.type === "file.resolved") NativeFile.#waiting.get(answer.id)?.(answer);
+    };
+    process.on("message", NativeFile.#listener);
+  }
+
+  static #devGrant(grant: string): { path: string; mode: NativeFileMode } {
+    
+    if (NativeFile.operationMode() !== "local")
+      throw new Error("A dev build's file grant resolves only on akan start, in operationMode local.");
+    const [, mode, encoded = "", signature = ""] = grant.split(":");
+    if (mode !== "read" && mode !== "write" && mode !== "folder") throw new Error("The file grant is malformed.");
+    const key = readFileSync(
+      process.env.AKAN_NATIVE_DEV_GRANT_KEY || path.join(homedir(), ".akan", "native", "dev-file-grant.key"),
+    );
+    const expected = createHmac("sha256", key).update(`${mode}:${encoded}`).digest();
+    const given = Buffer.from(signature, "base64url");
+    if (given.length !== expected.length || !timingSafeEqual(given, expected))
+      throw new Error("The file grant was not signed by this computer's dev build.");
+    return { path: Buffer.from(encoded, "base64url").toString(), mode };
+  }
+}

package/server/ops/appInfo.ts

@@ -7,6 +7,7 @@ export interface AppPublicInfo {
   repoName: string;
   environment: string;
   operationMode: string;
+  workspaceRoot?: string;
 }
 
 export interface AppDetailInfo extends AppPublicInfo {
@@ -39,7 +40,8 @@ export class AppInfo {
 
   static public(): AppPublicInfo {
     const { appName, repoName, environment, operationMode } = getEnv();
-    return { appName, repoName, environment, operationMode };
+    const workspaceRoot = operationMode === "local" ? process.env.AKAN_WORKSPACE_ROOT : undefined;
+    return { appName, repoName, environment, operationMode, ...(workspaceRoot ? { workspaceRoot } : {}) };
   }
 
   static detail(proc: AppProcessInfo): AppDetailInfo {

package/server/ops/opsRoute.ts

@@ -1,5 +1,6 @@
 import { Logger } from "akanjs/common";
 import { getEnv } from "../../base/baseEnv";
+import { SelfExec } from "../selfExec";
 import type { AppDetailInfo } from "./appInfo";
 import { OpsTokenVerifier } from "./opsToken";
 import { type SnapshotJobRequest, SnapshotJobs } from "./snapshotJobs";
@@ -65,8 +66,8 @@ export class OpsRoute {
     const args = ["ops", "snapshot", "--id", request.id, "--out", dir, "--db", sources.main, "--json"];
     if (sources.solid) args.push("--solid-db", sources.solid);
     if (request.includeSolid) args.push("--include-solid");
-    const proc = Bun.spawn([process.execPath, Bun.main, ...args], {
-      env: process.env,
+    const proc = Bun.spawn(SelfExec.command(Bun.main, ...args), {
+      env: SelfExec.env(),
       stdout: "pipe",
       stderr: "pipe",
     });

package/server/routing/apiRouter.ts

@@ -8,6 +8,7 @@ import { copyBunRequestFields, type WebProxyRunner } from "../proxy";
 import { SignalResolver } from "../resolver";
 import type { HttpRoutes, SignalRouteOptions, WebsocketRoutes } from "../types";
 import { AppWsData } from "./appWsData";
+import type { HostAllowlist } from "./hostAllowlist";
 
 export interface HmrStateSource {
   readonly state: {
@@ -34,6 +35,7 @@ export interface ApiRouteInputs {
   renderEnvRoutes: HttpRoutes;
   upgradeAppWs: (req: Request, data: AppWsData) => boolean;
   webProxyRunner?: WebProxyRunner | null;
+  hostAllowlist?: HostAllowlist | null;
 }
 
 type RouteValue = NonNullHttpRoutes[keyof NonNullHttpRoutes];
@@ -62,6 +64,7 @@ export class ApiRouter {
     renderEnvRoutes,
     upgradeAppWs,
     webProxyRunner,
+    hostAllowlist,
   }: ApiRouteInputs): NonNullHttpRoutes {
     const endpointEntries = Object.entries(routes ?? {}).map(
       ([p, handler]) =>
@@ -76,6 +79,12 @@ export class ApiRouter {
     const endpointPaths = new Set([...endpointEntries.map(([path]) => path), ...builtinEntries.map(([path]) => path)]);
     const routeTable = {
       [`${prefix}${websocketPrefix}` as "/api/ws"]: (req) => {
+
+        try {
+          CrossSiteGuard.assertOrigin(req, new URL(req.url), "websocket");
+        } catch {
+          return new Response("Forbidden", { status: 403 });
+        }
         const upgraded = upgradeAppWs(req, AppWsData.fromRequest(req));
         if (upgraded) return;
         return new Response("Failed to upgrade to WebSocket", { status: 500 });
@@ -84,9 +93,10 @@ export class ApiRouter {
       ...Object.fromEntries(builtinEntries),
       ...(renderEnvRoutes ?? {}),
     } as NonNullHttpRoutes;
-    return webProxyRunner
+    const served = webProxyRunner
       ? ApiRouter.#wrapRoutesWithWebProxy(routeTable, webProxyRunner, prefix, endpointPaths)
       : routeTable;
+    return hostAllowlist ? ApiRouter.#guardHosts(served, hostAllowlist) : served;
   }
 
   static buildWebsocketHandlers({
@@ -214,6 +224,15 @@ export class ApiRouter {
     ) as NonNullHttpRoutes;
   }
 
+  static #guardHosts(routes: NonNullHttpRoutes, allowlist: HostAllowlist): NonNullHttpRoutes {
+    return Object.fromEntries(
+      Object.entries(routes).map(([path, route]) => [
+        path,
+        ApiRouter.#mapRoute(route, (handler) => (req) => (allowlist.allows(req) ? handler(req) : allowlist.refuse())),
+      ]),
+    ) as NonNullHttpRoutes;
+  }
+
   static #isApiRoute(path: string, apiPrefix: string): boolean {
     const normalized = apiPrefix.replace(/\/$/, "");
     return path === normalized || path.startsWith(`${normalized}/`);
@@ -242,12 +261,16 @@ export class ApiRouter {
 
   static #mapRoute(route: RouteValue, wrap: (handler: RouteHandler) => RouteHandler): RouteValue {
     if (typeof route === "function") return wrap(route as RouteHandler) as RouteValue;
-    if (route instanceof Response) return wrap(() => route) as RouteValue;
+    if (route instanceof Response) return wrap(() => route.clone()) as RouteValue;
     if (!route || typeof route !== "object") return route;
     return Object.fromEntries(
       Object.entries(route).map(([method, handler]) => [
         method,
-        typeof handler === "function" ? wrap(handler as RouteHandler) : handler,
+        typeof handler === "function"
+          ? wrap(handler as RouteHandler)
+          : handler instanceof Response
+            ? wrap(() => handler.clone())
+            : handler,
       ]),
     ) as RouteValue;
   }

package/server/routing/hostAllowlist.ts

@@ -0,0 +1,24 @@
+
+
+export class HostAllowlist {
+  readonly #hosts: Set<string>;
+
+  constructor(hosts: Iterable<string>) {
+    this.#hosts = new Set([...hosts].map((host) => host.trim().toLowerCase()).filter(Boolean));
+  }
+
+  /** `AKAN_ALLOWED_HOSTS`: comma-separated `host:port` entries; unset or blank serves every Host. */
+  static fromEnv(env: Record<string, string | undefined> = process.env): HostAllowlist | null {
+    const allowlist = new HostAllowlist((env.AKAN_ALLOWED_HOSTS ?? "").split(","));
+    return allowlist.#hosts.size ? allowlist : null;
+  }
+
+  allows(req: Request): boolean {
+    const host = req.headers.get("host")?.trim().toLowerCase();
+    return !!host && this.#hosts.has(host);
+  }
+
+  refuse(): Response {
+    return new Response("Forbidden", { status: 403 });
+  }
+}

package/server/selfExec.ts

@@ -0,0 +1,33 @@
+interface SelfExecGlobal {
+  [key: symbol]: string | undefined;
+}
+
+export class SelfExec {
+  
+  static readonly #key = Symbol.for("akan.selfExec.beBun");
+
+  static get #beBun(): string | undefined {
+    return (globalThis as unknown as SelfExecGlobal)[SelfExec.#key];
+  }
+
+  static adopt() {
+    const value = process.env.BUN_BE_BUN;
+    if (value === undefined) return;
+    (globalThis as unknown as SelfExecGlobal)[SelfExec.#key] = value;
+    delete process.env.BUN_BE_BUN;
+  }
+
+  /** A desktop app's carried server: only its shell starts the app executable as Bun. */
+  static get carried(): boolean {
+    return SelfExec.#beBun !== undefined;
+  }
+
+  static env(env: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+    const beBun = SelfExec.#beBun;
+    return beBun === undefined ? env : { ...env, BUN_BE_BUN: beBun };
+  }
+
+  static command(script: string, ...args: string[]): string[] {
+    return [process.execPath, ...process.execArgv, script, ...args];
+  }
+}

package/server/types.tsx

@@ -125,7 +125,9 @@ export const getWebConfigFromEnv = (): AkanWebConfig => {
 
 export interface MobileDeepLinkAssociation {
   targetName: string;
-  appId: string;
+  /** Null when the target names no id for the platform; that platform then gets no association. */
+  iosAppId: string | null;
+  androidAppId: string | null;
   domains: string[];
   iosTeamId?: string;
   androidSha256CertFingerprints?: string[];