akanjs 3.0.0-beta.27 → 3.0.0-beta.28

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 main.ts asks for replicas (replica, solo: false or AKAN_SOLO=false), which would start with the `bun` on the user's PATH. 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[]);
@@ -947,7 +964,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 +1092,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 +1103,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,7 @@ export class AkanServer {
   #ops: OpsRoute | null | undefined;
   #lastMetrics: AkanMetricsReport = {};
   #stopping: Promise<void> | null = null;
+  #orphanExiting = false;
   constructor(
     name = "AkanServer",
     env: BackendEnv = {},
@@ -392,7 +396,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 +409,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 {
@@ -467,6 +480,7 @@ 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",
+      crossSite: CrossSiteGuard.option(),
     } satisfies AkanIpcMessage);
     await this.#di.runSchedulerInit();
     ShutdownManager.register(this.logger, () => this.stop());
@@ -550,10 +564,16 @@ export class AkanServer {
 
   #handleParentDisconnect() {
     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/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/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,25 @@
+
+
+export class SelfExec {
+  static #beBun: string | undefined;
+
+  static adopt() {
+    const value = process.env.BUN_BE_BUN;
+    if (value === undefined) return;
+    SelfExec.#beBun = 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 {
+    return SelfExec.#beBun === undefined ? env : { ...env, BUN_BE_BUN: SelfExec.#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[];

package/server/webRouter.ts

@@ -1168,9 +1168,9 @@ export class WebRouter {
     const associations = artifact.deepLinkAssociations ?? [];
     if (pathname === APPLE_APP_SITE_ASSOCIATION_PATH) {
       const details = associations
-        .filter((association) => association.domains.length > 0 && association.iosTeamId)
+        .filter((association) => association.domains.length > 0 && association.iosTeamId && association.iosAppId)
         .map((association) => ({
-          appIDs: [`${association.iosTeamId}.${association.appId}`],
+          appIDs: [`${association.iosTeamId}.${association.iosAppId}`],
           components: [{ "/": "/*" }],
         }));
       if (details.length === 0) return null;
@@ -1180,14 +1180,17 @@ export class WebRouter {
     const packageSuffixes = process.env.AKAN_PUBLIC_ENV === "main" ? [""] : ["", ".debug"];
     const assetLinks = associations
       .filter(
-        (association) => association.domains.length > 0 && (association.androidSha256CertFingerprints?.length ?? 0) > 0,
+        (association) =>
+          association.domains.length > 0 &&
+          !!association.androidAppId &&
+          (association.androidSha256CertFingerprints?.length ?? 0) > 0,
       )
       .flatMap((association) =>
         packageSuffixes.map((suffix) => ({
           relation: ["delegate_permission/common.handle_all_urls"],
           target: {
             namespace: "android_app",
-            package_name: `${association.appId}${suffix}`,
+            package_name: `${association.androidAppId}${suffix}`,
             sha256_cert_fingerprints: association.androidSha256CertFingerprints,
           },
         })),

package/service/ipcTypes.ts

@@ -143,6 +143,7 @@ export type AkanIpcMessage =
       /** Actual websocket upstream the child bound; may differ from the preferred port when it was in use. */
       wsUpstream?: Extract<AkanUpstream, { type: "tcp" }>;
       healthPath?: string;
+      crossSite?: { allowedOrigins: string[]; enabled: boolean };
     }
   | { type: "backend-ready"; pid: number }
   | { type: "pubsub.publish"; roomId: string; data: object | object[]; origin?: string }
@@ -163,6 +164,9 @@ export type AkanIpcMessage =
   /** Hub → child: the lowest severity any subscriber wants; `null` tells the child to stop forwarding. */
   | { type: "log.level"; minSev: number | null }
   | { type: "shutdown"; signal?: string }
+  /** Desktop server → the shell that started it: the path behind a file picker grant (forServer). */
+  | { type: "file.resolve"; id: string; grant: string }
+  | { type: "file.resolved"; id: string; path?: string; mode?: "read" | "write" | "folder"; error?: string }
   | { type: "error"; message: string; stack?: string; pid?: number };
 
 export const sendAkanIpc = (message: AkanIpcMessage) => {

package/signal/CrossSiteGuard.ts

@@ -14,16 +14,23 @@ export class CrossSiteGuard {
    * Android and Windows; both WebViews send exactly that as `Origin`. */
   static readonly nativeOrigins = ["app://localhost", "https://app.localhost"] as const;
   static #enabled = true;
+  static #allowedOrigins: string[] = [];
   static #allowed = new Set<string>(CrossSiteGuard.nativeOrigins);
 
   /** Applied at boot from the mounting app's `option.ts`; the native shells stay allowed unless disabled. */
   static configure({ allowedOrigins = [], enabled = true }: CrossSiteOption) {
     CrossSiteGuard.#enabled = enabled;
+    CrossSiteGuard.#allowedOrigins = [...allowedOrigins];
     CrossSiteGuard.#allowed = new Set([...CrossSiteGuard.nativeOrigins, ...allowedOrigins]);
   }
 
+  static option(): Required<CrossSiteOption> {
+    return { allowedOrigins: [...CrossSiteGuard.#allowedOrigins], enabled: CrossSiteGuard.#enabled };
+  }
+
   static reset() {
     CrossSiteGuard.#enabled = true;
+    CrossSiteGuard.#allowedOrigins = [];
     CrossSiteGuard.#allowed = new Set(CrossSiteGuard.nativeOrigins);
   }
 

package/test/signalTestRuntime.ts

@@ -20,7 +20,7 @@ export interface SignalTestContext<Fetch = FetchProxy> {
 export type SignalTestOptions = Pick<TestServerOptions, "storage" | "workerId" | "port" | "serverMode">;
 
 type SignalServerModule = {
-  env: BackendEnv;
+  env?: BackendEnv;
   fetch: FetchProxy;
   lib: AkanLib;
 };
@@ -68,6 +68,11 @@ const importServerModule = async (type: "app" | "lib", name: string): Promise<Si
 
 const importLibModule = async (name: string): Promise<SignalServerModule> => await import(`@libs/${name}/server`);
 
+const importTestingEnv = async (type: "app" | "lib", name: string, targetModule: SignalServerModule) =>
+  type === "app"
+    ? ((await import(`@apps/${name}/env/env.server.testing`)) as { env?: BackendEnv }).env
+    : targetModule.env;
+
 export const setupSignalTestTarget = async <Fetch = FetchProxy>(
   {
     type = process.env.AKAN_TEST_TARGET_TYPE as "app" | "lib" | undefined,
@@ -96,10 +101,11 @@ export const setupSignalTestTarget = async <Fetch = FetchProxy>(
       Promise.all((libNames ?? []).filter((libName) => libName !== name).map(importLibModule)),
       importServerModule(type, name),
     ]);
+    const testingEnv = await importTestingEnv(type, name, targetModule);
     const target: SignalTestTarget = {
       type,
       name,
-      env: { ...env, ...targetModule.env },
+      env: { ...env, ...testingEnv },
       fetch: targetModule.fetch,
       libs: [...dependencyModules.map((mod) => mod.lib), targetModule.lib],
     };

package/types/base/baseEnv.d.ts

@@ -77,3 +77,4 @@ export declare const getWsPrefix: () => string;
 export declare const resetEnvCache: () => void;
 /** Cached after the first call. */
 export declare const getEnv: () => ClientEnv;
+export declare const getServerOrigin: () => string;

package/types/client/index.d.ts

@@ -8,6 +8,7 @@ export * from "./device.d.ts";
 export * from "./frameConfig.d.ts";
 export * from "./locale.d.ts";
 export * from "./makePageProto.d.ts";
+export * from "./resolveServerUrl.d.ts";
 export * from "./route.d.ts";
 export * from "./router.d.ts";
 export * from "./rscNavigation.d.ts";

package/types/client/native/accessibility.d.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/accessibility/src/index.d.ts";

package/types/client/native/app-state.d.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/app-state/src/index.d.ts";

package/types/client/native/app.d.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/app/src/index.d.ts";

package/types/client/native/appearance.d.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/appearance/src/index.d.ts";