akanjs 3.0.0-alpha.71 → 3.0.0-alpha.72

package/package.json

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

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/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,39 @@
+import fs from "node:fs";
+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.
+ *
+ * `path.resolve` works on the string and does not follow links, so a symlink inside the tree can still point
+ * out of it. Callers check existence after this, so a path that resolves to nothing is handed back and 404s
+ * there; only a link that really leads outside is refused.
+ */
+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;
+  try {
+
+    const realBase = fs.realpathSync(normalizedBase);
+    const realBaseWithSep = realBase.endsWith(path.sep) ? realBase : realBase + path.sep;
+    const real = fs.realpathSync(resolved);
+    if (real !== realBase && !real.startsWith(realBaseWithSep)) return null;
+  } catch {
+  }
+  return resolved;
+};

package/server/webRouter.ts

@@ -55,6 +55,7 @@ import { type RscRedirectMethod, type RscRedirectStatus, type RscRenderResult, R
 import { createDefaultSitemapXml, getSitemapBasePath } from "./sitemap";
 import { SsrFromRscRenderer } from "./ssrFromRscRenderer";
 import type { RscTraceMetadata, SsrManifest } from "./ssrTypes";
+import { resolveStaticPath } from "./staticPath";
 import { createSubRouteIndexResponse, createSystemPageResponse, getSystemPageHomeHref } from "./systemPages";
 import { type BaseBuildArtifact, type HttpRoutes, type RenderState, resolveWebConfig } from "./types";
 
@@ -411,16 +412,14 @@ export class WebRouter {
     <script type="module" src="/csr.js"></script>
   </body>
 </html>`;
-              return new Response(this.#withCsrHmr(htmlText), {
-                headers: { "Content-Type": "text/html; charset=utf-8" },
-              });
+              return new Response(this.#withCsrHmr(htmlText), { headers: WebRouter.#htmlResponseHeaders(200) });
             },
           }
         : {}),
       [`${clientServePrefix}/*`]: async (req) => {
         this.#requestStats.staticAsset += 1;
         const url = new URL(req.url);
-        const filePath = WebRouter.#safeResolve(clientOutputDir, url.pathname.slice(clientServePrefix.length + 1));
+        const filePath = resolveStaticPath(clientOutputDir, url.pathname.slice(clientServePrefix.length + 1));
         if (!filePath) return new Response("Not Found", { status: 404 });
         return WebRouter.#fileResponse(req, filePath, {
           contentType: Bun.file(filePath).type || "application/javascript",
@@ -431,7 +430,7 @@ export class WebRouter {
         this.#requestStats.staticAsset += 1;
         const url = new URL(req.url);
         if (this.#prodMode) {
-          const filePath = WebRouter.#safeResolve(this.#artifactDir, url.pathname.slice("/_akan/".length));
+          const filePath = resolveStaticPath(this.#artifactDir, url.pathname.slice("/_akan/".length));
           if (filePath) {
             return WebRouter.#fileResponse(req, filePath, {
               contentType: "text/css; charset=utf-8",
@@ -449,7 +448,7 @@ export class WebRouter {
       "/_akan/fonts/*": (req) => {
         this.#requestStats.staticAsset += 1;
         const url = new URL(req.url);
-        const filePath = WebRouter.#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 });
         return WebRouter.#fileResponse(req, filePath, {
           contentType: Bun.file(filePath).type || "font/woff2",
@@ -524,10 +523,10 @@ export class WebRouter {
         this.#requestStats.staticAsset += 1;
         const firebaseConfig = await WebRouter.#resolveFirebaseClientConfig();
         return new Response(WebRouter.#createFirebaseMessagingServiceWorker(firebaseConfig), {
-          headers: {
-            "Content-Type": "application/javascript; charset=utf-8",
-            "Cache-Control": "no-store",
-          },
+          headers: WebRouter.#baseAssetHeaders({
+            contentType: "application/javascript; charset=utf-8",
+            cacheControl: "no-store",
+          }),
         });
       },
       "/*": async (req) => {
@@ -544,12 +543,10 @@ export class WebRouter {
             const csrHtml = await this.#resolveCsrHtml(csrOutputDir, url.pathname);
             if (!csrHtml) return this.#csrUnavailableResponse(url.pathname);
             const html = await Bun.file(csrHtml).text();
-            return new Response(this.#withCsrHmr(html), {
-              headers: { "Content-Type": "text/html; charset=utf-8" },
-            });
+            return new Response(this.#withCsrHmr(html), { headers: WebRouter.#htmlResponseHeaders(200) });
           }
 
-          const csrAssetPath = path.extname(url.pathname) ? WebRouter.#safeResolve(csrOutputDir, url.pathname) : null;
+          const csrAssetPath = path.extname(url.pathname) ? resolveStaticPath(csrOutputDir, url.pathname) : null;
           if (csrAssetPath && (await Bun.file(csrAssetPath).exists())) {
             this.#requestStats.staticAsset += 1;
             return WebRouter.#fileResponse(req, csrAssetPath, {
@@ -559,7 +556,7 @@ export class WebRouter {
           }
         }
 
-        const filePath = WebRouter.#safeResolve(publicDir, url.pathname);
+        const filePath = resolveStaticPath(publicDir, url.pathname);
         if (filePath) {
           if (await Bun.file(filePath).exists()) {
             this.#requestStats.staticAsset += 1;
@@ -607,12 +604,9 @@ export class WebRouter {
           const htmlCacheEntry = htmlCacheDecision.entry;
           const cachedHtml = htmlCacheEntry ? this.#getCachedHtml(htmlCacheEntry.key) : null;
           if (cachedHtml) {
-            return new Response(cachedHtml, {
-              headers: {
-                "Content-Type": "text/html; charset=utf-8",
-                "X-Akan-Cache": "HIT",
-              },
-            });
+            const cachedHeaders = WebRouter.#htmlResponseHeaders(200);
+            cachedHeaders.set("X-Akan-Cache", "HIT");
+            return new Response(cachedHtml, { headers: cachedHeaders });
           }
           const rscResult = await this.#rsc.renderWithMeta(req, {
             clientManifest: manifest.clientManifest,
@@ -993,7 +987,7 @@ export class WebRouter {
   static #htmlResponseHeaders(status: number): Headers {
     const headers = new Headers({ "Content-Type": "text/html; charset=utf-8" });
     if (status >= 400) headers.set("Cache-Control", "no-store");
-    return headers;
+    return WebRouter.#applySecurityHeaders(headers, { html: true });
   }
   #withCsrHmr(html: string): string {
     if (this.#prodMode) return html;
@@ -1249,7 +1243,7 @@ self.addEventListener("notificationclick", (event) => {
       i18n: artifact.i18n,
     });
     const filename = basePath ? `${basePath}.html` : "index.html";
-    const filePath = WebRouter.#safeResolve(csrOutputDir, filename);
+    const filePath = resolveStaticPath(csrOutputDir, filename);
     return filePath && fs.existsSync(filePath) ? filePath : null;
   }
 
@@ -1334,10 +1328,27 @@ self.addEventListener("notificationclick", (event) => {
     return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
   }
 
+  /**
+   * Headers every response carries, whatever it is.
+   *
+   * `nosniff` because `Bun.file().type` falls back to `application/octet-stream` for an extension it does not
+   * know, and a sniffing browser then guesses again — on a `public/` tree the app serves from its own origin,
+   * that guess is script execution. `Referrer-Policy` because route paths carry ids.
+   *
+   * `X-Frame-Options` is on the HTML only: framing an image or a stylesheet means nothing, and the header is
+   * what stops a page authenticated by a `SameSite=None` cookie from being clickjacked inside somebody else's.
+   */
+  static #applySecurityHeaders(headers: Headers, { html = false } = {}): Headers {
+    headers.set("X-Content-Type-Options", "nosniff");
+    headers.set("Referrer-Policy", "strict-origin-when-cross-origin");
+    if (html) headers.set("X-Frame-Options", "SAMEORIGIN");
+    return headers;
+  }
+
   static #baseAssetHeaders(options: { contentType: string; cacheControl?: string }): Headers {
     const headers = new Headers({ "Content-Type": options.contentType });
     if (options.cacheControl) headers.set("Cache-Control", options.cacheControl);
-    return headers;
+    return WebRouter.#applySecurityHeaders(headers);
   }
 
   static #weakEtag(size: number, mtimeMs: number): string {
@@ -1359,21 +1370,4 @@ self.addEventListener("notificationclick", (event) => {
     const sinceMs = Date.parse(ifModifiedSince);
     return Number.isFinite(sinceMs) && sinceMs >= lastModifiedMs;
   }
-
-  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;
-    if (!resolved.startsWith(baseWithSep)) return null;
-    return resolved;
-  }
 }

package/service/adapt.ts

@@ -8,11 +8,7 @@ export interface Adaptor {
   onDestroy(): Promise<void> | void;
 }
 
-export type AdaptorCls<
-  Methods = any,
-  
-  InjectMap extends Record<string, InjectInfo> = {},
-> = Cls<
+export type AdaptorCls<Methods = any, InjectMap extends Record<string, InjectInfo> = Record<never, never>> = Cls<
   Methods & ExtractInjectInfoObject<InjectMap> & Adaptor,
   { readonly [INJECT_META]: InjectMap; readonly refName: string }
 >;