akanjs 3.1.1-rc.0 → 3.1.1-rc.2

package/client/cookie.ts

@@ -2,14 +2,19 @@ import { getEnv } from "akanjs/base";
 import {
   authTokenKey,
   bearerTokenOf,
+  type CookieEntry,
+  CookieJar,
+  CookieSweep,
   decodeJwtPayload,
   isOwnAuthToken,
   Logger,
   legacyAuthTokenKey,
-  readAuthToken,
+  readSessionToken,
+  retiredAuthTokenKeys,
+  SessionCookies,
 } from "akanjs/common";
 import type { Account } from "akanjs/fetch";
-import { parseCookieHeader, cookies as serverCookies, headers as serverHeaders } from "akanjs/fetch";
+import { cookieJar as serverCookieJar, headers as serverHeaders } from "akanjs/fetch";
 import { secretStorage } from "./storage";
 import { fetch } from "./useClient";
 
@@ -24,26 +29,35 @@ const isCsrClient = () => {
   return env.side === "client" && env.renderMode === "csr";
 };
 
-const cookieJarKey = "akan:cookies";
-const pageKeepsCookies = () => (globalThis as { location?: Location }).location?.protocol !== "app:";
-const readCookieJar = (): Record<string, string> => {
+const storedCookiesKey = "akan:cookies";
+const pageLocation = () => (globalThis as { location?: Location }).location;
+const pageKeepsCookies = () => pageLocation()?.protocol !== "app:";
+const readStoredCookies = (): Record<string, string> => {
   try {
-    return JSON.parse(localStorage.getItem(cookieJarKey) ?? "{}") as Record<string, string>;
+    return JSON.parse(localStorage.getItem(storedCookiesKey) ?? "{}") as Record<string, string>;
   } catch {
     return {};
   }
 };
-const writeCookieJar = (jar: Record<string, string>) => {
-  localStorage.setItem(cookieJarKey, JSON.stringify(jar));
+const writeStoredCookies = (stored: Record<string, string>) => {
+  localStorage.setItem(storedCookiesKey, JSON.stringify(stored));
 };
 
-export const cookies = (): Map<string, { name: string; value: string }> => {
-  if (getEnv().side === "server") return serverCookies();
+/** Every cookie this page or request holds, a name sent more than once included. */
+export const cookieJar = (): CookieJar => {
+  if (getEnv().side === "server") return serverCookieJar();
   if (!pageKeepsCookies())
-    return new Map(Object.entries(readCookieJar()).map(([name, value]) => [name, { name, value }]));
-  return parseCookieHeader(document.cookie);
+    return CookieJar.parse(
+      Object.entries(readStoredCookies())
+        .map(([name, value]) => `${name}=${value}`)
+        .join("; "),
+    );
+  return CookieJar.parse(document.cookie);
 };
 
+/** Names held exactly once; a duplicated name is left out. */
+export const cookies = (): Map<string, CookieEntry> => cookieJar().toMap();
+
 export const setCookie = (
   key: string,
   value: string,
@@ -51,7 +65,7 @@ export const setCookie = (
 ) => {
   if (getEnv().side === "server") return;
   if (!pageKeepsCookies()) {
-    writeCookieJar({ ...readCookieJar(), [key]: value });
+    writeStoredCookies({ ...readStoredCookies(), [key]: value });
     return;
   }
   const pathAttr = path ? `; path=${path}` : "";
@@ -60,19 +74,21 @@ export const setCookie = (
   document.cookie = `${key}=${value}${pathAttr}; SameSite=${sameSite}${secureAttr}`;
 };
 
-/** Reads through `cookies()` on both sides: a hand-rolled `split("=")` cuts base64 padding and skips the `j:` form. */
-export const getCookie = (key: string): string | undefined => cookies().get(key)?.value;
+/** `undefined` for a name held more than once, as for one never set. */
+export const getCookie = (key: string): string | undefined => cookieJar().read(key).value;
 
 export const removeCookie = (key: string, options: { path: string } = { path: "/" }) => {
   
   if (getEnv().side === "server") return;
   if (!pageKeepsCookies()) {
-    const { [key]: _removed, ...rest } = readCookieJar();
-    writeCookieJar(rest);
+    const { [key]: _removed, ...rest } = readStoredCookies();
+    writeStoredCookies(rest);
     return;
   }
   
-  document.cookie = `${key}=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=${options.path};`;
+  const secureAttr = /^__(Host|Secure)-/.test(key) ? " Secure;" : "";
+  
+  document.cookie = `${key}=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=${options.path};${secureAttr}`;
 };
 export const headers = (): Map<string, string> => {
   if (getEnv().side !== "server") return new Map();
@@ -95,17 +111,15 @@ const sentAuthToken = (): string | undefined => {
 };
 
 /** The auth token this app holds: on a CSR client the one `fetch` sends first, since a native shell's page keeps no
- * session cookie; then the cookie jar, under the app-scoped key or a legacy global one. */
+ * session cookie; then the app-scoped cookie, unless it is held more than once. */
 export const getAuthToken = (): string | undefined =>
-  (isCsrClient() ? sentAuthToken() : undefined) ?? readAuthToken(getCookie);
+  (isCsrClient() ? sentAuthToken() : undefined) ?? readSessionToken(cookieJar()).token;
 
 /** The auth token this app holds in client storage — the OS credential store in a native app, localStorage elsewhere. */
-export const getStoredAuthToken = async (): Promise<string | undefined> => {
-  const scoped = await secretStorage.getItem(authTokenKey());
-  if (scoped) return scoped;
-  const legacy = await secretStorage.getItem(legacyAuthTokenKey);
-  return legacy && isOwnAuthToken(legacy) ? legacy : undefined;
-};
+export const getStoredAuthToken = async (): Promise<string | undefined> =>
+  (await secretStorage.getItem(storedAuthTokenKey())) ?? undefined;
+
+const storedAuthTokenKey = () => `${legacyAuthTokenKey}:${getEnv().appName}`;
 
 /** The current JWT's account when minted for this app and environment. Reads only the two credentials the server
  * honours — the app-scoped auth cookie (a CSR client's bearer token) and `Authorization: Bearer` — so the two never
@@ -136,9 +150,9 @@ export const setAuth = ({ jwt }: SetAuthOption) => {
   fetch.setJwt(jwt);
   
   if (!isCsrClient()) setCookie(authTokenKey(), jwt);
-  void secretStorage.setItem(authTokenKey(), jwt);
+  void secretStorage.setItem(storedAuthTokenKey(), jwt);
   
-  removeCookie(legacyAuthTokenKey);
+  for (const key of retiredAuthTokenKeys()) removeCookie(key);
   void secretStorage.removeItem(legacyAuthTokenKey);
   announceAuth();
 };
@@ -146,25 +160,56 @@ export const setAuth = ({ jwt }: SetAuthOption) => {
 interface InitAuthOption {
   jwt?: string;
 }
+
+const sweepDocumentCookies = (names: string[]) => {
+  const { hostname = "", pathname = "/" } = pageLocation() ?? {};
+  
+  for (const entry of CookieSweep.setCookies({ names, host: hostname, path: pathname })) document.cookie = entry;
+};
+
+const readCookieSession = (): string | null | undefined => {
+  const first = readSessionToken(cookieJar());
+  if (!first.duplicate) return first.token;
+  SessionCookies.report([first.duplicate], pageLocation()?.host ?? "");
+  sweepDocumentCookies([first.duplicate.name]);
+  const second = readSessionToken(cookieJar());
+  return second.duplicate ? null : second.token;
+};
+
+const expireRetiredCookies = () => {
+  const jar = cookieJar();
+  for (const key of retiredAuthTokenKeys()) if (jar.has(key)) removeCookie(key);
+};
+
 export const initAuth = ({ jwt }: InitAuthOption = {}) => {
-  const stored = getAuthToken();
-  const token = jwt ?? stored;
+  expireRetiredCookies();
+  const sent = jwt ?? (isCsrClient() ? sentAuthToken() : undefined);
+  const token = sent ?? readCookieSession();
+  if (token === null) {
+    fetch.setJwt(null);
+    return;
+  }
   if (token && !isOwnAuthToken(token)) {
     
     Logger.warn("JWT ignored: it was minted for another app or environment");
-    if (token === stored) resetAuth();
+    if (!jwt) resetAuth();
     return;
   }
-  if (token) setAuth({ jwt: token });
+  if (token && sent) setAuth({ jwt: token });
+  else if (token) {
+    
+    fetch.setJwt(token);
+    announceAuth();
+  }
   
-  Logger.verbose(`JWT ${token ? "restored from cookie" : "not found in cookie"}`);
+  Logger.verbose(`JWT ${token ? "restored" : "not found"}`);
 };
 
 export const resetAuth = () => {
   fetch.setJwt(null);
   removeCookie(authTokenKey());
-  removeCookie(legacyAuthTokenKey);
-  void secretStorage.removeItem(authTokenKey());
+  for (const key of retiredAuthTokenKeys()) removeCookie(key);
+  void secretStorage.removeItem(storedAuthTokenKey());
   void secretStorage.removeItem(legacyAuthTokenKey);
   announceAuth();
 };

package/client/route/LayoutDefinition.ts

@@ -1,3 +1,4 @@
+import { RenderScope } from "akanjs/fetch";
 import type { ReactNode } from "react";
 import type { LayoutErrorRender, LayoutModule, LayoutNotFoundRender, PageModule } from "../csrTypes";
 import { type RouteArgsShape, RouteDefinition, type RouteKind } from "./RouteDefinition";
@@ -27,12 +28,12 @@ export class LayoutDefinition<Args extends RouteArgsShape = Record<never, never>
   }
 
   notFound(render: LayoutNotFoundRender) {
-    this.#notFound = render;
+    this.#notFound = (props) => RenderScope.run(() => render(props));
     return this;
   }
 
   error(render: LayoutErrorRender) {
-    this.#error = render;
+    this.#error = (props) => RenderScope.run(() => render(props));
     return this;
   }
 

package/client/route/RouteDefinition.ts

@@ -8,6 +8,7 @@ import {
 } from "akanjs/base";
 import { parseAkanI18nEnv } from "akanjs/common";
 import { deserialize } from "akanjs/constant";
+import { RenderScope } from "akanjs/fetch";
 import type { ReactNode } from "react";
 import type { Head, LayoutModule, PageConfig, PageModule, RouteGuardProps } from "../csrTypes";
 import { AkanNotFoundError } from "../router";
@@ -145,12 +146,15 @@ export abstract class RouteDefinition<
       ...(head === undefined
         ? {}
         : typeof head === "function"
-          ? { generateHead: async (props: RouteRenderProps) => await head(this.#argsOf(props) as never) }
+          ? {
+              generateHead: async (props: RouteRenderProps) =>
+                await RenderScope.run(() => head(this.#argsOf(props) as never)),
+            }
           : { head }),
       ...(loading
         ? {
             Loading: ((props: RouteRenderProps) =>
-              loading(this.#argsOf({ ...props, searchParams: {} }) as never)) as never,
+              RenderScope.run(() => loading(this.#argsOf({ ...props, searchParams: {} }) as never))) as never,
           }
         : {}),
     };
@@ -167,7 +171,8 @@ export abstract class RouteDefinition<
   }
 
   #guardRouteOf(guard: (args: never) => void | Promise<void>) {
-    const route = async (props: RouteGuardProps) => await guard(this.#guardArgsOf(props) as never);
+    const route = async (props: RouteGuardProps) =>
+      await RenderScope.run(() => guard(this.#guardArgsOf(props) as never));
     Object.defineProperty(route, routeArgsMarker, { value: this.args.map(({ kind, name }) => ({ kind, name })) });
     return route;
   }
@@ -178,10 +183,10 @@ export abstract class RouteDefinition<
 
     const route = async (props: RouteRenderProps) => {
       const args = this.renderArgsOf(this.#argsOf(props));
-      if (!(args instanceof Promise)) return await render(args as never);
+      if (!(args instanceof Promise)) return await RenderScope.run(() => render(args as never));
       const path = Translator.getRenderPath();
       const resolved = await args;
-      return await Translator.renderAt(path, () => render(resolved as never));
+      return await Translator.renderAt(path, () => RenderScope.run(() => render(resolved as never)));
     };
     Object.defineProperty(route, routeArgsMarker, { value: this.args.map(({ kind, name }) => ({ kind, name })) });
     this.#renderRoute = { render, argCount: this.args.length, route };

package/common/IpLiteral.ts

@@ -0,0 +1,75 @@
+export class IpLiteral {
+  
+  static normalize(address: string): string {
+    const trimmed = address.trim();
+    const mapped = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/i.exec(trimmed);
+    return mapped?.[1] ?? trimmed;
+  }
+
+  static parse(entry: string): string | null {
+    const trimmed = entry.trim();
+    const bracketed = /^\[([^\]]*:[^\]]*)\](?::\d{1,5})?$/.exec(trimmed);
+    const v4WithPort = /^(\d{1,3}(?:\.\d{1,3}){3}):\d{1,5}$/.exec(trimmed);
+    const [address = "", zone, ...rest] = (bracketed?.[1] ?? v4WithPort?.[1] ?? trimmed).split("%");
+    if (rest.length) return null;
+    if (zone !== undefined && !(address.includes(":") && /^[A-Za-z0-9_.-]{1,64}$/.test(zone))) return null;
+    const bytes = IpLiteral.bytes(IpLiteral.normalize(address));
+    
+    return bytes ? IpLiteral.#format(bytes) : null;
+  }
+
+  static bytes(address: string): Uint8Array | null {
+    if (address.includes(".") && !address.includes(":")) {
+      const parts = address.split(".");
+      if (parts.length !== 4) return null;
+      const bytes = new Uint8Array(4);
+      for (const [idx, part] of parts.entries()) {
+        const value = Number(part);
+        
+        if (!/^(?:0|[1-9]\d{0,2})$/.test(part) || value > 255) return null;
+        bytes[idx] = value;
+      }
+      return bytes;
+    }
+    return address.includes(":") ? IpLiteral.#ipv6Bytes(address) : null;
+  }
+
+  static #ipv6Bytes(address: string): Uint8Array | null {
+    
+    const bare = address.split("%")[0] ?? "";
+    const halves = bare.split("::");
+    if (halves.length > 2) return null;
+    const groupsOf = (text: string) => (text ? text.split(":").filter((group) => group !== "") : []);
+    const head = groupsOf(halves[0] ?? "");
+    const tail = halves.length === 2 ? groupsOf(halves[1] ?? "") : [];
+    const filled = halves.length === 2 ? 8 - head.length - tail.length : 0;
+    if (filled < 0 || head.length + tail.length + filled !== 8) return null;
+    const groups = [...head, ...new Array(filled).fill("0"), ...tail];
+    const bytes = new Uint8Array(16);
+    for (const [idx, group] of groups.entries()) {
+      if (!/^[0-9a-f]{1,4}$/i.test(group)) return null;
+      const value = Number.parseInt(group, 16);
+      bytes[idx * 2] = value >> 8;
+      bytes[idx * 2 + 1] = value & 0xff;
+    }
+    return bytes;
+  }
+
+  static #format(bytes: Uint8Array): string {
+    if (bytes.length === 4) return bytes.join(".");
+    if (bytes.subarray(0, 10).every((byte) => byte === 0) && bytes[10] === 0xff && bytes[11] === 0xff)
+      return bytes.subarray(12).join(".");
+    const groups = Array.from({ length: 8 }, (_, idx) => ((bytes[idx * 2] ?? 0) << 8) | (bytes[idx * 2 + 1] ?? 0));
+    let runStart = -1;
+    let runLength = 1;
+    for (let start = 0; start < groups.length; ) {
+      let end = start;
+      while (end < groups.length && groups[end] === 0) end += 1;
+      if (end - start > runLength) [runStart, runLength] = [start, end - start];
+      start = Math.max(end, start + 1);
+    }
+    const hex = groups.map((group) => group.toString(16));
+    if (runStart < 0) return hex.join(":");
+    return `${hex.slice(0, runStart).join(":")}::${hex.slice(runStart + runLength).join(":")}`;
+  }
+}

package/common/TrustedProxy.ts

@@ -1,39 +1,80 @@
 import { clientAddressFromHeaders, normalizeIpAddress } from "./clientAddress";
+import { IpLiteral } from "./IpLiteral";
+import { Logger } from "./Logger";
+
+interface Cidr {
+  bytes: Uint8Array;
+  bits: number;
+}
+
+interface TrustPolicy {
+  trustAll: boolean;
+  privateRanges: boolean;
+  strict: boolean;
+  cidrs: Cidr[];
+}
+
+export interface ResolvedClient {
+  address: string | null;
+  /** Read from a trusted hop's forwarded headers rather than taken from the socket peer. */
+  forwarded: boolean;
+}
 
 export class TrustedProxy {
-  static #cidrs: { bytes: Uint8Array; bits: number }[] | null = null;
-  static #trustAll: boolean | null = null;
+  static #policy: TrustPolicy | null = null;
   
   static readonly #verdicts = new Map<string, boolean>();
   static readonly #verdictLimit = 1024;
+  static #warnedIgnoredPeer = false;
 
   static configure(list: string | null | undefined) {
+    TrustedProxy.reset();
+    TrustedProxy.#policy = TrustedProxy.#policyOf(list);
+  }
+
+  static reset() {
+    TrustedProxy.#policy = null;
     TrustedProxy.#verdicts.clear();
-    TrustedProxy.#trustAll = list?.trim() === "*";
-    TrustedProxy.#cidrs = (list ?? "")
+    TrustedProxy.#warnedIgnoredPeer = false;
+  }
+
+  static #load(): TrustPolicy {
+    TrustedProxy.#policy ??= TrustedProxy.#policyOf(process.env.AKAN_TRUSTED_PROXIES);
+    return TrustedProxy.#policy;
+  }
+
+  static #policyOf(list: string | null | undefined): TrustPolicy {
+    const entries = (list ?? "")
       .split(",")
       .map((entry) => entry.trim())
-      .filter((entry) => entry && entry !== "*")
+      .filter((entry) => entry);
+    const keywords = new Set(entries.map((entry) => entry.toLowerCase()));
+    const cidrs = entries
+      .filter((entry) => !["*", "none", "private"].includes(entry.toLowerCase()))
       .flatMap((entry) => {
         const parsed = TrustedProxy.#parseCidr(entry);
+        if (!parsed)
+          new Logger("TrustedProxy").warn(
+            `AKAN_TRUSTED_PROXIES entry "${entry}" is neither an address nor a CIDR; ignored`,
+          );
         return parsed ? [parsed] : [];
       });
-  }
-
-  static reset() {
-    TrustedProxy.#cidrs = null;
-    TrustedProxy.#trustAll = null;
-    TrustedProxy.#verdicts.clear();
-  }
-
-  static #load() {
-    if (TrustedProxy.#cidrs === null) TrustedProxy.configure(process.env.AKAN_TRUSTED_PROXIES);
+    const trustAll = keywords.has("*");
+    if (trustAll && entries.length > 1)
+      new Logger("TrustedProxy").warn(
+        `AKAN_TRUSTED_PROXIES lists "*", which trusts every peer, so its other entries change nothing`,
+      );
+    return {
+      trustAll,
+      privateRanges: !entries.length || keywords.has("private"),
+      strict: entries.length > 0 && !trustAll,
+      cidrs,
+    };
   }
 
   static isTrusted(address: string | null | undefined): boolean {
     if (!address) return false;
-    TrustedProxy.#load();
-    if (TrustedProxy.#trustAll) return true;
+    if (TrustedProxy.#load().trustAll) return true;
     const known = TrustedProxy.#verdicts.get(address);
     if (known !== undefined) return known;
     const verdict = TrustedProxy.#judge(address);
@@ -43,26 +84,45 @@ export class TrustedProxy {
   }
 
   static #judge(address: string): boolean {
-    const bytes = TrustedProxy.#toBytes(normalizeIpAddress(address));
+    const bytes = IpLiteral.bytes(normalizeIpAddress(address));
     if (!bytes) return false;
-    if (TrustedProxy.#isLocalRange(bytes)) return true;
-    return (TrustedProxy.#cidrs ?? []).some((cidr) => TrustedProxy.#inRange(bytes, cidr));
+    const policy = TrustedProxy.#load();
+    if (TrustedProxy.#isLoopback(bytes)) return true;
+    if (policy.privateRanges && TrustedProxy.#isPrivateRange(bytes)) return true;
+    return policy.cidrs.some((cidr) => TrustedProxy.#inRange(bytes, cidr));
   }
 
   /** A `null` peer is a unix socket, which only a local proxy opens, so its headers count; `undefined` is not. */
   static clientAddress(headers: Headers, peerAddress: string | null | undefined): string | null {
+    return TrustedProxy.resolve(headers, peerAddress).address;
+  }
+
+  static resolve(headers: Headers, peerAddress: string | null | undefined): ResolvedClient {
     if (peerAddress === null || TrustedProxy.isTrusted(peerAddress)) {
-      const recorded = clientAddressFromHeaders(headers);
-      if (recorded) return recorded;
-    }
-    return peerAddress ? normalizeIpAddress(peerAddress) : null;
+
+      const judge = TrustedProxy.#load().strict ? (address: string) => TrustedProxy.isTrusted(address) : undefined;
+      const recorded = clientAddressFromHeaders(headers, judge);
+      if (recorded) return { address: recorded, forwarded: true };
+    } else if (peerAddress) TrustedProxy.#noteIgnoredPeer(headers, peerAddress);
+    return { address: peerAddress ? normalizeIpAddress(peerAddress) : null, forwarded: false };
+  }
+
+  static #noteIgnoredPeer(headers: Headers, peerAddress: string) {
+    if (TrustedProxy.#warnedIgnoredPeer || !TrustedProxy.#load().strict) return;
+    if (!headers.has("x-forwarded-for") && !headers.has("x-real-ip")) return;
+    const bytes = IpLiteral.bytes(normalizeIpAddress(peerAddress));
+    if (!bytes || !TrustedProxy.#isPrivateRange(bytes)) return;
+    TrustedProxy.#warnedIgnoredPeer = true;
+    new Logger("TrustedProxy").warn(
+      `Forwarded headers from ${normalizeIpAddress(peerAddress)} are ignored: AKAN_TRUSTED_PROXIES does not list it. If it is your proxy, add its address or a CIDR that holds only your proxies.`,
+    );
   }
 
   /** For refusing an outbound fetch to a caller-chosen name: judges the address alone, never the proxy list. */
   static isPrivateAddress(address: string): boolean {
-    const bytes = TrustedProxy.#toBytes(normalizeIpAddress(address));
+    const bytes = IpLiteral.bytes(normalizeIpAddress(address));
     if (!bytes) return true;
-    if (TrustedProxy.#isLocalRange(bytes)) return true;
+    if (TrustedProxy.#isLoopback(bytes) || TrustedProxy.#isPrivateRange(bytes)) return true;
     if (bytes.length === 4) {
       const [a = 0, b = 0] = bytes;
       return a === 0 || (a === 100 && b >= 64 && b <= 127) || a >= 224;
@@ -70,31 +130,36 @@ export class TrustedProxy {
     return bytes.every((byte) => byte === 0) || bytes[0] === 0xff;
   }
 
-  /** `10/8`, `172.16/12`, `192.168/16`, `127/8`, `169.254/16`, and their IPv6 counterparts `::1`, `fc00::/7`, `fe80::/10`. */
-  static #isLocalRange(bytes: Uint8Array): boolean {
+  static #isLoopback(bytes: Uint8Array): boolean {
+    if (bytes.length === 4) return bytes[0] === 127;
+    return bytes.every((byte, idx) => (idx === 15 ? byte === 1 : byte === 0));
+  }
+
+  /** `10/8`, `172.16/12`, `192.168/16`, `169.254/16`, and their IPv6 counterparts `fc00::/7`, `fe80::/10`. */
+  static #isPrivateRange(bytes: Uint8Array): boolean {
     if (bytes.length === 4) {
       const [a = 0, b = 0] = bytes;
-      if (a === 10 || a === 127) return true;
+      if (a === 10) return true;
       if (a === 192 && b === 168) return true;
       if (a === 172 && b >= 16 && b <= 31) return true;
       return a === 169 && b === 254;
     }
     const [first = 0, second = 0] = bytes;
     if ((first & 0xfe) === 0xfc) return true;
-    if (first === 0xfe && (second & 0xc0) === 0x80) return true;
-    return bytes.every((byte, idx) => (idx === 15 ? byte === 1 : byte === 0));
+    return first === 0xfe && (second & 0xc0) === 0x80;
   }
 
-  static #parseCidr(entry: string): { bytes: Uint8Array; bits: number } | null {
-    const [address, prefix] = entry.split("/");
-    const bytes = TrustedProxy.#toBytes(address ?? "");
+  static #parseCidr(entry: string): Cidr | null {
+    const [address, prefix, ...rest] = entry.split("/");
+    if (rest.length || (prefix !== undefined && !/^\d{1,3}$/.test(prefix))) return null;
+    const bytes = IpLiteral.bytes(normalizeIpAddress(address ?? ""));
     if (!bytes) return null;
     const bits = prefix === undefined ? bytes.length * 8 : Number(prefix);
     if (!Number.isInteger(bits) || bits < 0 || bits > bytes.length * 8) return null;
     return { bytes, bits };
   }
 
-  static #inRange(bytes: Uint8Array, cidr: { bytes: Uint8Array; bits: number }): boolean {
+  static #inRange(bytes: Uint8Array, cidr: Cidr): boolean {
     if (bytes.length !== cidr.bytes.length) return false;
     const wholeBytes = cidr.bits >> 3;
     for (let idx = 0; idx < wholeBytes; idx += 1) if (bytes[idx] !== cidr.bytes[idx]) return false;
@@ -103,40 +168,4 @@ export class TrustedProxy {
     const mask = 0xff << (8 - restBits);
     return ((bytes[wholeBytes] ?? 0) & mask) === ((cidr.bytes[wholeBytes] ?? 0) & mask);
   }
-
-  static #toBytes(address: string): Uint8Array | null {
-    if (address.includes(".") && !address.includes(":")) {
-      const parts = address.split(".");
-      if (parts.length !== 4) return null;
-      const bytes = new Uint8Array(4);
-      for (const [idx, part] of parts.entries()) {
-        const value = Number(part);
-        if (!/^\d{1,3}$/.test(part) || value > 255) return null;
-        bytes[idx] = value;
-      }
-      return bytes;
-    }
-    return address.includes(":") ? TrustedProxy.#ipv6ToBytes(address) : null;
-  }
-
-  static #ipv6ToBytes(address: string): Uint8Array | null {
-    
-    const bare = address.split("%")[0] ?? "";
-    const halves = bare.split("::");
-    if (halves.length > 2) return null;
-    const groupsOf = (text: string) => (text ? text.split(":").filter((group) => group !== "") : []);
-    const head = groupsOf(halves[0] ?? "");
-    const tail = halves.length === 2 ? groupsOf(halves[1] ?? "") : [];
-    const filled = halves.length === 2 ? 8 - head.length - tail.length : 0;
-    if (filled < 0 || head.length + tail.length + filled !== 8) return null;
-    const groups = [...head, ...new Array(filled).fill("0"), ...tail];
-    const bytes = new Uint8Array(16);
-    for (const [idx, group] of groups.entries()) {
-      if (!/^[0-9a-f]{1,4}$/i.test(group)) return null;
-      const value = Number.parseInt(group, 16);
-      bytes[idx * 2] = value >> 8;
-      bytes[idx * 2 + 1] = value & 0xff;
-    }
-    return bytes;
-  }
 }

package/common/appHosts.ts

@@ -0,0 +1,32 @@
+import { getEnv } from "akanjs/base";
+
+export class AppHosts {
+  static readonly #declared = new Set<string>();
+
+  static declare(hosts: Iterable<string>) {
+    for (const host of hosts) {
+      const name = AppHosts.nameOf(host);
+      if (name) AppHosts.#declared.add(name);
+    }
+  }
+
+  static reset() {
+    AppHosts.#declared.clear();
+  }
+
+  static allows(host: string, extra: Iterable<string> = []): boolean {
+    const name = AppHosts.nameOf(host);
+    if (!name) return false;
+    const { appName, environment, serveDomain } = getEnv();
+    if (name === AppHosts.nameOf(`${appName}-${environment}.${serveDomain}`) || AppHosts.#declared.has(name))
+      return true;
+    const listed = [...(process.env.AKAN_ALLOWED_HOSTS ?? "").split(","), ...extra];
+    return listed.some((entry) => AppHosts.nameOf(entry) === name);
+  }
+
+  static nameOf(host: string): string | null {
+    const url = URL.parse(`http://${host.trim()}`);
+    if (!url || url.href !== `${url.origin}/`) return null;
+    return url.hostname.replace(/\.$/, "") || null;
+  }
+}

package/common/authCookie.ts

@@ -1,13 +1,16 @@
 
 
-/** The pre-scoping key. Read as a fallback, never written; drop it once deployments have rotated past it. */
+/** The pre-scoping key. Never read or written; sign-in and sign-out still delete it from jars written before. */
 export const legacyAuthTokenKey = "jwt";
 
-/** Matches both spellings so a signout can sweep a jar written before and after the key was scoped. */
-export const isAuthTokenKey = (key: string): boolean =>
-  key === legacyAuthTokenKey || key.startsWith(`${legacyAuthTokenKey}:`);
+/** Matches every spelling, bare, app-scoped or `__Host-`, so a signout can sweep a jar written under any of them. */
+export const isAuthTokenKey = (key: string): boolean => {
+  const name = key.startsWith("__Host-") ? key.slice("__Host-".length) : key;
+  return name === legacyAuthTokenKey || name.startsWith(`${legacyAuthTokenKey}:`);
+};
 
-const authCookiePattern = new RegExp(`(?:^|;\\s*)${legacyAuthTokenKey}(?::[^=\\s;]+)?=`);
+const authCookiePattern = new RegExp(`(?:^|;\\s*)(?:__Host-)?${legacyAuthTokenKey}(?::[^=\\s;]+)?=`);
 
+/** @deprecated Unused by the framework; parse the header with `CookieJar.parse` and test its `names()`. */
 export const cookieHeaderHasAuthToken = (cookieHeader: string | null | undefined): boolean =>
   !!cookieHeader && authCookiePattern.test(cookieHeader);