akanjs 3.0.0-alpha.71 → 3.0.0-alpha.73

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-alpha.71",
+  "version": "3.0.0-alpha.73",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/server/akanApp.ts

@@ -18,6 +18,7 @@ import { LogHub } from "./logging/logHub";
 import { LogStreamRoute } from "./logging/logStreamRoute";
 import { RotatingLogWriter } from "./logging/rotatingLogWriter";
 import { ProcessMetricsCollector } from "./processMetricsCollector";
+import { resolveStaticPath } from "./staticPath";
 import { getWebConfigFromEnv } from "./types";
 
 interface ChildState {
@@ -669,7 +670,7 @@ export class AkanApp {
     if (!this.#web.ssr) return null;
     const clientPrefix = "/_akan/client/";
     if (url.pathname.startsWith(clientPrefix)) {
-      const filePath = this.#safeResolve(
+      const filePath = resolveStaticPath(
         path.join(this.#artifactDir, "client"),
         url.pathname.slice(clientPrefix.length),
       );
@@ -684,7 +685,7 @@ export class AkanApp {
 
     for (const prefix of ["/_akan/styles/", "/_akan/fonts/"]) {
       if (!url.pathname.startsWith(prefix)) continue;
-      const filePath = this.#safeResolve(this.#artifactDir, url.pathname.slice("/_akan/".length));
+      const filePath = resolveStaticPath(this.#artifactDir, url.pathname.slice("/_akan/".length));
       if (!filePath) return new Response("Not Found", { status: 404 });
       const file = Bun.file(filePath);
       if (!(await file.exists())) return new Response("Not Found", { status: 404 });
@@ -1018,23 +1019,6 @@ export class AkanApp {
     return new Response(Bun.file(filePath).stream(), { headers });
   }
 
-  #safeResolve(baseDir: string, urlPath: string): string | null {
-    let decoded: string;
-    try {
-      decoded = decodeURIComponent(urlPath);
-    } catch {
-      return null;
-    }
-    if (decoded.includes("\0")) return null;
-    const normalizedBase = path.resolve(baseDir);
-    const rel = decoded.replace(/^[/\\]+/, "");
-    const resolved = path.resolve(normalizedBase, rel);
-    if (resolved === normalizedBase) return resolved;
-    const baseWithSep = normalizedBase.endsWith(path.sep) ? normalizedBase : `${normalizedBase}${path.sep}`;
-    if (!resolved.startsWith(baseWithSep)) return null;
-    return resolved;
-  }
-
   #makeProxyHeaders(req: Request, childIdx: number, server?: Bun.Server<GatewayWsData>) {
     return makeAkanChildProxyHeaders(req, childIdx, server?.requestIP(req));
   }

package/server/akanAppHeaders.ts

@@ -1,4 +1,4 @@
-import { normalizeIpAddress } from "akanjs/common";
+import { TrustedProxy } from "akanjs/common";
 
 const HOP_BY_HOP_HEADERS = new Set([
   "connection",
@@ -23,10 +23,16 @@ export function makeAkanChildProxyHeaders(req: Request, childIdx: number, peer?:
   for (const key of HOP_BY_HOP_HEADERS) headers.delete(key);
   const forwardedFor = headers.get("x-forwarded-for");
 
-  const clientAddress = headers.get("x-real-ip") ?? (peer ? normalizeIpAddress(peer.address) : "127.0.0.1");
+  const clientAddress = TrustedProxy.clientAddress(headers, peer?.address);
   const host = headers.get("host");
-  headers.set("x-real-ip", clientAddress);
-  headers.set("x-forwarded-for", forwardedFor ? `${forwardedFor}, ${clientAddress}` : clientAddress);
+
+  if (clientAddress) {
+    headers.set("x-real-ip", clientAddress);
+    headers.set("x-forwarded-for", forwardedFor ? `${forwardedFor}, ${clientAddress}` : clientAddress);
+  } else {
+    headers.delete("x-real-ip");
+    headers.delete("x-forwarded-for");
+  }
   if (peer && !headers.has("x-forwarded-port")) headers.set("x-forwarded-port", String(peer.port));
   headers.set("x-forwarded-host", headers.get("x-forwarded-host") ?? host ?? new URL(req.url).host);
   headers.set(

package/server/akanOption.ts

@@ -1,6 +1,6 @@
 import type { BackendEnv, PromiseOrObject } from "akanjs/base";
 import type { Adaptor, AdaptorCls, LlmOption } from "akanjs/service";
-import type { GuardCls, MiddlewareCls } from "akanjs/signal";
+import type { CrossSiteOption, GuardCls, MiddlewareCls } from "akanjs/signal";
 import type { McpServerOption } from "./akanServer";
 import type { WebProxyRegistration } from "./proxy";
 import { HostBasePathWebProxy, LocaleWebProxy } from "./proxy";
@@ -22,6 +22,7 @@ export class AkanOption<Env extends BackendEnv = BackendEnv> {
   readonly #getLlms: ((env: Env) => LlmOption)[] = [];
   #mcp: boolean | McpServerOption | undefined;
   #agentAccess: GuardCls | GuardCls[] | null | undefined;
+  #crossSite: CrossSiteOption | undefined;
   constructor() {
     this.#getUses = [];
   }
@@ -62,6 +63,15 @@ export class AkanOption<Env extends BackendEnv = BackendEnv> {
     this.#agentAccess = guards;
     return this;
   }
+  /**
+   * Which other origins may drive a mutation, on top of the one serving the request and the native shells.
+   * Needed only by a browser client hosted somewhere else — a separate admin domain, a partner embed. The gate
+   * itself is on by default and `{ enabled: false }` is for an API no browser reaches.
+   */
+  setCrossSite(crossSite: CrossSiteOption) {
+    this.#crossSite = crossSite;
+    return this;
+  }
   /** Settings for whichever adaptor fills `LlmAdaptorRole`, injected into it as the `llmOption` use. */
   setLlm(llmOrFn: LlmOption | ((env: Env) => LlmOption)) {
     if (typeof llmOrFn === "function") this.#getLlms.push(llmOrFn);
@@ -87,6 +97,9 @@ export class AkanOption<Env extends BackendEnv = BackendEnv> {
   getAgentAccess(): GuardCls | GuardCls[] | null | undefined {
     return this.#agentAccess;
   }
+  getCrossSite(): CrossSiteOption | undefined {
+    return this.#crossSite;
+  }
   getLlm(env: Env): LlmOption {
     return Object.assign({}, ...this.#getLlms.map((fn) => fn(env)));
   }

package/server/akanServer.ts

@@ -13,6 +13,7 @@ import type {
   SolidConfig,
 } from "akanjs/service";
 import type { ServerSignal, ServerSignalCls, WebsocketPublishData } from "akanjs/signal";
+import { CrossSiteGuard } from "../signal/CrossSiteGuard";
 import { AgentRelayAccess } from "../signal/guards";
 import { createOpenApiDocument } from "../signal/openapi";
 import { FetchSerializer } from "../signal/serializer";
@@ -198,6 +199,8 @@ export class AkanServer {
       if (mcp !== undefined) this.setMcp(mcp);
       const agentAccess = lib.option.getAgentAccess();
       if (agentAccess !== undefined) AgentRelayAccess.use(agentAccess);
+      const crossSite = lib.option.getCrossSite();
+      if (crossSite !== undefined) CrossSiteGuard.configure(crossSite);
     });
     this.setMcp(options?.mcp ?? this.mcp);
     this.serverMode = serverMode;

package/server/cachePolicy.ts

@@ -1,3 +1,4 @@
+import { originFromRequest } from "akanjs/common";
 import { type AkanDynamicUsage, type AkanRequestPolicy, parseCookieHeader } from "akanjs/fetch";
 
 export const DEFAULT_ROUTE_CACHE_TTL_SECONDS = 30;
@@ -93,17 +94,7 @@ export function combineMinRevalidate(...values: Array<number | false | null | un
 }
 
 export function getClientFacingOrigin(request: Request, url = new URL(request.url)): string {
-  const forwardedProto = request.headers.get("x-forwarded-proto")?.split(",")[0]?.trim();
-  const forwardedHost = request.headers.get("x-forwarded-host")?.split(",")[0]?.trim();
-  const host = forwardedHost ?? request.headers.get("host")?.split(",")[0]?.trim();
-  const proto = forwardedProto ?? url.protocol.slice(0, -1);
-  if (host && proto) {
-    try {
-      return new URL(`${proto}://${host}`).origin;
-    } catch {
-    }
-  }
-  return url.origin;
+  return originFromRequest(request.headers, url);
 }
 
 export function isPublicRouteCacheableRequest(request: Request): boolean {

package/server/decorators.ts

@@ -1,4 +1,8 @@
-
+/**
+ * Method decorators for a server class: `@Transaction`, `@Try`, `@CacheMethod`. Kept because `libs/util`'s
+ * storage adaptors use `@Try` on their remote calls; new code follows the adaptor rule instead
+ * (`catch` → `logger.error` → `return null`).
+ */
 
 type DecoratedInstance = {
   logger?: { warn?: (message: string) => void; trace?: (message: string) => void };
@@ -50,8 +54,13 @@ export const Transaction = (): MethodDecorator => {
   }) as MethodDecorator;
 };
 
-/** Method decorator that caches method results for the given timeout in milliseconds. */
-export const Cache = (timeout = 1000, getCacheKey?: (...args: unknown[]) => string): MethodDecorator => {
+/**
+ * Method decorator that caches method results for the given timeout in milliseconds.
+ *
+ * Not `Cache` — `akanjs/signal` exports a `Cache` **middleware class**, and an app importing both barrels got
+ * one name meaning two things.
+ */
+export const CacheMethod = (timeout = 1000, getCacheKey?: (...args: unknown[]) => string): MethodDecorator => {
   return ((_target: unknown, key: string, descriptor: PropertyDescriptor) => {
     const originMethod = descriptor.value as (this: unknown, ...args: unknown[]) => unknown;
     const cacheMap = new Map<string, unknown>();

package/server/devtools/constantSerializer.ts

@@ -66,7 +66,14 @@ export class ConstantSerializer {
       values[key] = DevtoolsJson.toSafe(value);
     }
 
-    return { models, scalars, enums, values, primitives: PrimitiveRegistry.getNames().sort(), relations };
+    return {
+      models,
+      scalars,
+      enums,
+      values,
+      primitives: PrimitiveRegistry.getNames().sort((a, b) => a.localeCompare(b)),
+      relations,
+    };
   }
 
   static #serializeView(modelRef: ConstantCls | undefined, modelType: ConstantType): ConstantModelView {

package/server/di/diLifecycle.ts

@@ -267,8 +267,28 @@ export class DiLifecycle {
     return selected;
   }
 
-  /** Run every init stage in dependency order and collect the generated routes. */
+  /**
+   * Run every init stage in dependency order and collect the generated routes.
+   *
+   * A stage runs its tasks in parallel and reports every failure, which means the ones that *succeeded*
+   * alongside a failure are live: connections opened, timers armed, `onInit` done. The error then propagates and
+   * the process usually exits, so this rarely mattered — but a caller that catches and retries (a test harness,
+   * a dev restart) accumulated them. `destroyAll` already walks the stages in reverse and skips what was never
+   * registered, so the wind-down is the one that already exists.
+   */
   async initializeAll(): Promise<SignalRoutes> {
+    try {
+      return await this.#initializeAll();
+    } catch (error) {
+      await this.destroyAll().catch((destroyError: unknown) => {
+        
+        this.logger.warn(`Failed to unwind a partial init: ${reasonMessage(destroyError)}`);
+      });
+      throw error;
+    }
+  }
+
+  async #initializeAll(): Promise<SignalRoutes> {
     await this.#initializeUses();
     await this.#initializeAdaptor();
     await this.#initializeServerSignal();

package/server/di/resolveHierarchy.ts

@@ -37,8 +37,8 @@ export function topologicalStages<T extends DependencyNode>(graph: Map<string, T
 
     const next: string[] = [];
     for (const key of queue) {
-      for (const dependent of dependents.get(key)!) {
-        const newDegree = inDegree.get(dependent)! - 1;
+      for (const dependent of dependents.get(key) ?? []) {
+        const newDegree = (inDegree.get(dependent) ?? 0) - 1;
         inDegree.set(dependent, newDegree);
         if (newDegree === 0) next.push(dependent);
       }
@@ -47,7 +47,7 @@ export function topologicalStages<T extends DependencyNode>(graph: Map<string, T
   }
 
   if (processed !== graph.size) {
-    const remaining = [...graph.keys()].filter((k) => inDegree.get(k)! > 0);
+    const remaining = [...graph.keys()].filter((k) => (inDegree.get(k) ?? 0) > 0);
     const cycle = traceCycle(graph, remaining);
     throw new Error(`Circular dependency detected: ${cycle.join(" → ")}`);
   }

package/server/imageOptimizer.ts

@@ -5,6 +5,7 @@ import { Logger } from "akanjs/common";
 import { isAnimatedImage } from "./animatedImage";
 import { ImageOptimizerError } from "./imageOptimizerError";
 import { Semaphore } from "./semaphore";
+import { resolveStaticPath } from "./staticPath";
 import {
   type AkanImageConfig,
   type AkanImageFormat,
@@ -260,7 +261,7 @@ export class ImageOptimizer {
 
   async #readLocalImage(href: string): Promise<ImageSource> {
     const url = new URL(href, "http://local.akan");
-    const filePath = ImageOptimizer.#safeResolve(this.#publicDir, url.pathname);
+    const filePath = resolveStaticPath(this.#publicDir, url.pathname);
     if (!filePath) throw new ImageOptimizerError(400, '"url" parameter is not allowed');
     const file = Bun.file(filePath);
     if (!(await file.exists())) throw new ImageOptimizerError(404, "Image not found");
@@ -455,22 +456,6 @@ export class ImageOptimizer {
     }
   }
 
-  static #safeResolve(baseDir: string, urlPath: string): string | null {
-    let decoded: string;
-    try {
-      decoded = decodeURIComponent(urlPath);
-    } catch {
-      return null;
-    }
-    if (decoded.includes("\0")) return null;
-    const normalizedBase = path.resolve(baseDir);
-    const rel = decoded.replace(/^[/\\]+/, "");
-    const resolved = path.resolve(normalizedBase, rel);
-    if (resolved === normalizedBase) return resolved;
-    const baseWithSep = normalizedBase.endsWith(path.sep) ? normalizedBase : normalizedBase + path.sep;
-    return resolved.startsWith(baseWithSep) ? resolved : null;
-  }
-
   static async #readResponseBuffer(res: Response, maxBytes: number): Promise<Buffer> {
     const contentLength = Number.parseInt(res.headers.get("content-length") ?? "0", 10);
     if (contentLength > maxBytes) throw new ImageOptimizerError(413, "Remote image is too large");

package/server/mcp/McpDispatcher.ts

@@ -6,6 +6,7 @@ import { NoDocumentError } from "akanjs/document";
 import type { InjectRegistry, LiveRegistry } from "akanjs/service";
 import type { Endpoint, EndpointCls } from "../../signal/endpoint";
 import type { EndpointInfo } from "../../signal/endpointInfo";
+import { Exception } from "../../signal/exception";
 import type { GuardCls } from "../../signal/guard";
 import {
   McpDocument,
@@ -277,9 +278,14 @@ export class McpDispatcher {
     if (!modelType) return value;
     try {
       return mask(ConstantRegistry.getModelRef(refName, modelType), value);
-    } catch {
+    } catch (error) {
 
-      return value;
+      McpDispatcher.logger.error(
+        `MCP could not mask a "${refName}" (${modelType}) result, so it was not sent: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+      throw new Exception.Error("The server failed to complete this request.");
     }
   }
 

package/server/resolver/database.resolver.ts

@@ -1,6 +1,6 @@
 import type { PromiseOrObject } from "akanjs/base";
 import { applyMixins, capitalize } from "akanjs/common";
-import { type ConstantModel, DEFAULT_PAGE_SIZE, type QueryOf } from "akanjs/constant";
+import { type ConstantModel, type QueryOf, resolvePageLimit, resolvePageSkip } from "akanjs/constant";
 import {
   assertFilterFitsCrud,
   CacheDatabase,
@@ -32,7 +32,7 @@ import {
   DatabaseAdaptorRole,
   type DocumentStore,
 } from "akanjs/service";
-import { getCurrentTrace, traceDataLoaderBatch } from "akanjs/signal";
+import { Exception, getCurrentTrace, traceDataLoaderBatch } from "akanjs/signal";
 
 /**
  * Times a store query and records it against the active request trace (no-op when
@@ -57,13 +57,18 @@ export class DatabaseResolver {
   ): { adaptor: AdaptorCls<DatabaseInstance>; schema: DocumentSchema } {
     const [modelName, className]: [string, string] = [database.refName, capitalize(database.refName)];
 
-    const resolveSort = (sortKey?: string | null) =>
-      sortKey ? (getFilterSortByKey(database.filter, sortKey) as { [key: string]: 1 | -1 }) : null;
+    const resolveSort = (sortKey?: string | null): { [key: string]: 1 | -1 } | null => {
+      if (!sortKey) return null;
+      const sort = getFilterSortByKey(database.filter, sortKey) as { [key: string]: 1 | -1 } | undefined;
+      if (!sort) throw new Exception.BadRequest(`Unknown sort key for ${modelName}: ${sortKey}`);
+      return sort;
+    };
     const getListQuery = (query?: QueryOf<any>, queryOption?: ListQueryOption) => {
       const find = query ?? {};
       const sort = resolveSort(queryOption?.sort);
-      const skip = Number(queryOption?.skip ?? 0);
-      const limit = queryOption?.limit === null ? DEFAULT_PAGE_SIZE : Number(queryOption?.limit ?? 0);
+      const skip = resolvePageSkip(queryOption?.skip);
+
+      const limit = queryOption?.limit === undefined ? 0 : resolvePageLimit(queryOption.limit);
       const select = queryOption?.select;
       const sample = queryOption?.sample;
       return { find, sort, skip, limit, select, sample };
@@ -71,7 +76,7 @@ export class DatabaseResolver {
     const getFindQuery = (query?: QueryOf<any>, queryOption?: FindQueryOption) => {
       const find = query ?? {};
       const sort = resolveSort(queryOption?.sort);
-      const skip = Number(queryOption?.skip ?? 0);
+      const skip = resolvePageSkip(queryOption?.skip);
       const select = queryOption?.select;
       const sample = queryOption?.sample ?? false;
       return { find, sort, skip, select, sample };
@@ -316,7 +321,7 @@ export class DatabaseResolver {
         return this.__get(id);
       }
       async __load(id?: string) {
-        return (id ? await this.__loader.load(id) : null) as any | null;
+        return (id ? await this.__loader.load(id) : null) as unknown;
       }
       async [`load${className}`](id?: string) {
         return this.__load(id);

package/server/resolver/signal.resolver.ts

@@ -13,7 +13,7 @@ import {
   SLICE_META,
 } from "akanjs/base";
 import { capitalize, Logger } from "akanjs/common";
-import { deserialize, serialize } from "akanjs/constant";
+import { deserialize, resolvePageLimit, resolvePageSkip, serialize } from "akanjs/constant";
 import { documentQueryHelper } from "akanjs/document";
 import {
   type AkanJob,
@@ -275,8 +275,8 @@ export class SignalResolver {
           ._addInternalArgs(sliceInfo.internalArgs)
           .exec(async function (this: any, ...requestArgs: any) {
             const args = requestArgs.slice(0, argLength);
-            const skip = Number(requestArgs[argLength] ?? 0);
-            const limit = Number(requestArgs[argLength + 1] ?? 20);
+            const skip = resolvePageSkip(requestArgs[argLength]);
+            const limit = resolvePageLimit(requestArgs[argLength + 1]);
             const sort = requestArgs[argLength + 2] ?? "latest";
             const internalArgs = requestArgs.slice(argLength + 3);
             const query = assertSliceQuery(

package/server/routeTreeBuilder.ts

@@ -3,7 +3,6 @@ import type {
   LayoutModule,
   LayoutProps,
   PageProps,
-  PageState,
   PathRoute,
   ResolveHead,
   Route,
@@ -20,26 +19,13 @@ import {
   routeSegmentToTreePath,
 } from "akanjs/common";
 import { createElement } from "react";
-import { validatePageConfig } from "../client/frameConfig";
+import { defaultPageState, validatePageConfig } from "../client/frameConfig";
 import { resolveHeadExport, resolveMetadataHead } from "./metadata";
 
 type RouteModuleKindWithOverrides = "page" | "layout" | "overrides";
 
 export type PagesContext = Record<string, () => Promise<RouteModule>>;
 
-export const defaultPageState: PageState = {
-  transition: "none",
-  topSafeArea: 0,
-  bottomSafeArea: 0,
-  topInset: 0,
-  bottomInset: 0,
-  gesture: true,
-  cache: false,
-  ssr: "stream",
-  topSafeAreaColor: "transparent",
-  bottomSafeAreaColor: "transparent",
-};
-
 export interface RouteModuleCacheStats {
   moduleCount: number;
   loadedModuleCount: number;

package/server/routing/apiRouter.ts

@@ -1,7 +1,7 @@
 import { dayjs } from "akanjs/base";
 import { type Logger, websocketAuthContract } from "akanjs/common";
 import type { InjectRegistry } from "akanjs/service";
-import { Exception, SignalContext, type WebsocketReqData } from "akanjs/signal";
+import { Exception, SignalContext, SignalFailure, type WebsocketReqData } from "akanjs/signal";
 import { compressResponse } from "../contentEncoding";
 import type { HmrWsData, HmrWsHub } from "../hmr/wsHub";
 import { copyBunRequestFields, type WebProxyRunner } from "../proxy";
@@ -166,12 +166,11 @@ export class ApiRouter {
             ws.send(JSON.stringify({ ...error.toJSON(), timestamp: new Date().toISOString() }));
             return;
           }
-          const errMsg = error instanceof Error ? error.message : String(error);
           if (!SignalContext.wasReported(error)) {
-            logger.error(errMsg);
-            console.error(error);
+            logger.error(error instanceof Error ? (error.stack ?? error.message) : String(error));
           }
-          ws.send(JSON.stringify({ error: errMsg, statusCode: 500, timestamp: new Date().toISOString(), at: dayjs() }));
+          
+          ws.send(JSON.stringify({ ...SignalFailure.body(error), at: dayjs() }));
         }
       },
       close: (ws) => {

package/server/routing/appWsData.ts

@@ -1,4 +1,4 @@
-import { clientAddressFromHeaders, clientPortFromHeaders, forwardedHeaders, normalizeIpAddress } from "akanjs/common";
+import { clientAddressFromHeaders, clientPortFromHeaders, forwardedHeaders, TrustedProxy } from "akanjs/common";
 
 const CREDENTIAL_HEADERS = ["authorization", "cookie", "user-agent"] as const;
 
@@ -36,14 +36,11 @@ export class AppWsData {
       else data.headers.delete("cookie");
     }
     data.account = undefined;
-    data.resolvedAuthorization = undefined;
   }
   createdAt: number;
   headers: Headers;
   cookies: Bun.CookieMap;
   account?: unknown;
-  /** The `authorization` value `account` was resolved from, so each frame need not re-verify it. */
-  resolvedAuthorization?: string;
   /**
    * Identity of this connection, minted here so every app socket carries one from its first frame and
    * adaptors and endpoints only ever read it. Per-connection and process-local — a reconnect gets a new
@@ -51,7 +48,13 @@ export class AppWsData {
    * It outlives a credential swap on purpose: the socket is still the same socket.
    */
   socketId: string;
-  /** The caller's address as the nearest proxy recorded it, or null when nothing did. */
+  /**
+   * The caller's address as the nearest proxy recorded it, or null when nothing did.
+   *
+   * The handshake headers alone cannot say whether a proxy wrote them or the client did, so this trusts them —
+   * a socket that reached a child came through the gateway, which already resolved the question. `ipOf` is what
+   * an endpoint should read: it has the peer, so it can decide.
+   */
   get ip(): string | null {
     return clientAddressFromHeaders(this.headers);
   }
@@ -61,7 +64,7 @@ export class AppWsData {
   }
   /** The address to answer on: what a proxy recorded, else this socket's own peer. */
   ipOf(ws: Bun.ServerWebSocket<unknown>): string | null {
-    return this.ip ?? (ws.remoteAddress ? normalizeIpAddress(ws.remoteAddress) : null);
+    return TrustedProxy.clientAddress(this.headers, ws.remoteAddress);
   }
   constructor(headers: Headers) {
     this.createdAt = Date.now();

package/server/staticPath.ts

@@ -0,0 +1,34 @@
+import path from "node:path";
+
+/**
+ * The file a URL path names inside one directory, or `null` when it names something outside it.
+ *
+ * Every static route the web router serves goes through here, so this is the single place a request path stops
+ * being a string and becomes a file. The order matters: percent-decoding first (so `%2e%2e` is seen as `..`),
+ * then a NUL check (a truncating byte in a path), then `path.resolve` to collapse the traversal, then
+ * containment against the base **with a separator** — without it `/public-secrets` passes a `/public` check.
+ *
+ * Symlinks are followed, like nginx and `serve-static` do: `akan sync` builds `public/libs/<lib>` as a link to
+ * `<workspaceRoot>/libs/<lib>/public`, so a link out of the tree is how a lib ships its assets, not an attack.
+ * Refusing those would 404 every lib asset under `akan start` and nothing else — `akan build` copies `public/`
+ * with `dereference: true`, so a built app has no links left to refuse. Traversal is what the string checks
+ * above stop, and they run before any of this touches the filesystem.
+ *
+ * Callers check existence after this, so a path that resolves to nothing is handed back and 404s there.
+ */
+export const resolveStaticPath = (baseDir: string, urlPath: string): string | null => {
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(urlPath);
+  } catch {
+    return null;
+  }
+  if (decoded.includes("\0")) return null;
+  const normalizedBase = path.resolve(baseDir);
+  const rel = decoded.replace(/^[/\\]+/, "");
+  const resolved = path.resolve(normalizedBase, rel);
+  if (resolved === normalizedBase) return resolved;
+  const baseWithSep = normalizedBase.endsWith(path.sep) ? normalizedBase : normalizedBase + path.sep;
+  if (!resolved.startsWith(baseWithSep)) return null;
+  return resolved;
+};