@moonsjs/vite 0.1.11 → 0.1.13

package/src/plugin.ts

@@ -1,7 +1,8 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { createHash } from "node:crypto";
-import { resolve as resolvePath } from "node:path";
+import { relative as relativePath, resolve as resolvePath } from "node:path";
 import {
+  MOONS_VERSION,
   MoonsError,
   fnRegistryKey,
   generateTypes,
@@ -56,6 +57,9 @@ export default function moons(options: MoonsVitePluginOptions = {}): Plugin {
   let configFilePath = "";
   let routesDir = "";
   let serverOnlyPackages: ReadonlyArray<string> = [];
+  // Addendum J.1/J.2: paritas dev & produksi (paritas E7).
+  let trustProxy = false;
+  let bodyLimitBytes: number | undefined;
   let apiDir = "";
   let apiRoutes: ApiRouteDefinition[] = [];
   let apiMiddlewares: ApiMiddlewareDefinition[] = [];
@@ -245,6 +249,8 @@ export default function moons(options: MoonsVitePluginOptions = {}): Plugin {
       const config = validateConfig(raw, { file: configFilePath, projectRoot: root });
       routesDir = resolvePath(root, config.routesDir);
       serverOnlyPackages = config.security?.serverOnlyPackages ?? [];
+      trustProxy = config.security?.trustProxy === true;
+      bodyLimitBytes = config.security?.bodyLimitBytes;
 
       // Addendum D.1: scan + validasi statis modul `src/api`.
       apiDir = resolvePath(root, config.apiDir ?? "src/api");
@@ -366,6 +372,8 @@ export default function moons(options: MoonsVitePluginOptions = {}): Plugin {
           },
           analyze: (absoluteFile) => analysisCache.get(absoluteFile) ?? analyzeFile(absoluteFile),
           apiDir,
+          configFile: configFilePath,
+          serverDir: resolvePath(root, "src/server"),
           serverOnlyPackages,
           packageCache,
         });
@@ -423,6 +431,30 @@ export default function moons(options: MoonsVitePluginOptions = {}): Plugin {
     configureServer(server) {
       installDevMiddleware(server, {
         templatePath: resolvePath(root, "index.html"),
+        // Addendum I.4 (W4): overlay devtools — data segar per request.
+        devtools: () => {
+          const toRelative = (file: string): string =>
+            file.startsWith(root) ? relativePath(root, file).split("\\").join("/") : file;
+          return {
+            routes: [...routes]
+              .sort((a, b) => a.path.localeCompare(b.path) || a.kind.localeCompare(b.kind))
+              .map((route) => ({ path: route.path, kind: route.kind, file: toRelative(route.file) })),
+            apiRoutes: [...apiRoutes]
+              .sort((a, b) => a.path.localeCompare(b.path))
+              .map((route) => ({ path: route.path, kind: "api", file: toRelative(route.file) })),
+            serverFns: [...analysisCache.values()]
+              .flatMap((analysis) =>
+                analysis.serverFns.map((fn) => ({
+                  file: toRelative(analysis.file),
+                  name: fn.name,
+                  hash: fn.hash,
+                })),
+              )
+              .sort((a, b) => a.file.localeCompare(b.file) || a.name.localeCompare(b.name)),
+            canary: options.leakTest?.canary !== undefined,
+            version: MOONS_VERSION,
+          };
+        },
         // A1: pemindaian payload SSR hanya di dev (warning), tanpa biaya di production.
         payloadScan: {
           ...(options.leakTest?.canary === undefined ? {} : { canary: options.leakTest.canary }),
@@ -432,7 +464,10 @@ export default function moons(options: MoonsVitePluginOptions = {}): Plugin {
         ...(apiRoutes.length === 0
           ? {}
           : { apiPrefix: `/${apiDir.split(/[\\/]/).filter((part) => part.length > 0).pop() ?? "api"}` }),
+        trustProxy,
+        ...(bodyLimitBytes === undefined ? {} : { bodyLimitBytes }),
       });
+      server.config.logger.info("[moons] devtools: /__moons/devtools");
     },
 
     async handleHotUpdate(context) {
@@ -541,7 +576,7 @@ function renderServerEntryBuild(
     "  onContext: (ctx) => plugins.applyExtensions(ctx),",
     "});",
     "",
-    `startNodeServer(handler, { plugins, headers: config.headers, storage: config.isr?.storage${canary === undefined ? "" : `, canary: ${JSON.stringify(canary)}`} });`,
+    `startNodeServer(handler, { plugins, headers: config.headers, storage: config.isr?.storage, trustProxy: config.security?.trustProxy, bodyLimitBytes: config.security?.bodyLimitBytes${canary === undefined ? "" : `, canary: ${JSON.stringify(canary)}`} });`,
     "",
   ].join("\n");
 }

package/src/server/dev.ts

@@ -5,7 +5,15 @@ import type { PayloadScanOptions } from "../payload-scan";
 import type { PluginRuntime } from "./plugins";
 import type { Shell } from "./shell";
 import { createDevShell } from "./shell";
-import { sendNodeResponse, toWebRequest } from "./node";
+import {
+  BodyLimitError,
+  InvalidRequestError,
+  resolveRequestUrl,
+  sendNodeResponse,
+  toWebRequest,
+} from "./node";
+import { DEFAULT_BODY_LIMIT_BYTES } from "@moonsjs/core";
+import { emptyDevtoolsData, renderDevtoolsHtml, type DevtoolsData } from "../devtools";
 
 interface DevApp {
   handler: (request: Request) => Promise<Response>;
@@ -26,7 +34,16 @@ type DevServerEntry = {
  */
 export function installDevMiddleware(
   server: ViteDevServer,
-  options: { templatePath: string; payloadScan?: PayloadScanOptions; apiPrefix?: string },
+  options: {
+    templatePath: string;
+    payloadScan?: PayloadScanOptions;
+    apiPrefix?: string;
+    /** Addendum J.1: paritas dev dengan produksi (trustProxy/bodyLimitBytes). */
+    trustProxy?: boolean;
+    bodyLimitBytes?: number;
+    /** Addendum I.4: datasource devtools overlay (dipanggil per request). */
+    devtools?: () => DevtoolsData;
+  },
 ): void {
   let appPromise: Promise<DevApp> | null = null;
 
@@ -48,11 +65,42 @@ export function installDevMiddleware(
   });
 
   server.middlewares.use((req, res, next) => {
+    // Addendum I.4 (W4): overlay dev-only — selalu data segar per request.
+    if (
+      (req.method === "GET" || req.method === "HEAD") &&
+      new URL(req.url ?? "/", "http://localhost").pathname === "/__moons/devtools"
+    ) {
+      try {
+        const data = options.devtools?.() ?? emptyDevtoolsData();
+        res.statusCode = 200;
+        res.setHeader("content-type", "text/html; charset=utf-8");
+        res.end(req.method === "HEAD" ? undefined : renderDevtoolsHtml(data));
+      } catch (error) {
+        res.statusCode = 500;
+        res.setHeader("content-type", "text/plain; charset=utf-8");
+        res.end(`[moons] devtools gagal dirender: ${String(error)}`);
+      }
+      return;
+    }
+
     if (!shouldHandle(req, options.apiPrefix)) {
       next();
       return;
     }
-    void handleRequest(getApp, req, res).catch((error: unknown) => {
+    void handleRequest(getApp, req, res, options).catch((error: unknown) => {
+      if (error instanceof InvalidRequestError) {
+        res.statusCode = 400;
+        res.setHeader("content-type", "text/plain; charset=utf-8");
+        res.end("Bad Request");
+        return;
+      }
+      if (error instanceof BodyLimitError) {
+        res.statusCode = 413;
+        res.setHeader("content-type", "text/plain; charset=utf-8");
+        res.end("Payload Too Large");
+        res.once("finish", () => req.destroy());
+        return;
+      }
       next(error as Error);
     });
   });
@@ -62,9 +110,16 @@ async function handleRequest(
   getApp: () => Promise<DevApp>,
   req: IncomingMessage,
   res: ServerResponse,
+  options: { trustProxy?: boolean; bodyLimitBytes?: number },
 ): Promise<void> {
   const app = await getApp();
-  const response = await app.handler(await toWebRequest(req));
+  const url = resolveRequestUrl(req, { trustProxy: options.trustProxy === true });
+  const isRpc = url.pathname.startsWith("/_moons/fn/");
+  const request = await toWebRequest(req, {
+    trustProxy: options.trustProxy === true,
+    ...(isRpc ? { maxBodyBytes: options.bodyLimitBytes ?? DEFAULT_BODY_LIMIT_BYTES } : {}),
+  });
+  const response = await app.handler(request);
   await sendNodeResponse(res, response);
 }
 

package/src/server/node-server.ts

@@ -1,10 +1,17 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { createServer, type Server } from "node:http";
 import { extname, join, resolve, sep } from "node:path";
-import type { PrerenderStorage } from "@moonsjs/core";
+import { DEFAULT_BODY_LIMIT_BYTES, MoonsError, type PrerenderStorage } from "@moonsjs/core";
 import { revalidatePrerendered, shouldRevalidate } from "./isr";
 import { contentTypeForPathname } from "./storage";
-import { sendNodeResponse, toWebRequest } from "./node";
+import {
+  BodyLimitError,
+  DEFAULT_SECURITY_HEADERS,
+  InvalidRequestError,
+  resolveRequestUrl,
+  sendNodeResponse,
+  toWebRequest,
+} from "./node";
 import type { PluginRuntime } from "./plugins";
 import { installGracefulShutdown } from "./shutdown";
 
@@ -52,6 +59,10 @@ export interface NodeServerOptions {
    * memakai storage ini; default: file sistem lokal.
    */
   storage?: PrerenderStorage;
+  /** Addendum J.1: percayai `x-forwarded-proto`/`x-forwarded-host` (default false). */
+  trustProxy?: boolean;
+  /** Addendum J.2: batas body RPC di transport (default `DEFAULT_BODY_LIMIT_BYTES`). */
+  bodyLimitBytes?: number;
 }
 
 /**
@@ -67,9 +78,21 @@ export function startNodeServer(
 
   const server = createServer((req, res) => {
     void (async () => {
+      let url: URL;
       try {
-        const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+        // Addendum J.1: URL/Origin mengikuti `x-forwarded-*` bila trustProxy aktif;
+        // request malformed → 400 (bukan 500 + stack).
+        url = resolveRequestUrl(req, { trustProxy: options.trustProxy === true });
+      } catch (error) {
+        if (error instanceof InvalidRequestError) {
+          console.warn(`[moons] ${error.message} — 400`);
+          respondBadRequest(res);
+          return;
+        }
+        throw error;
+      }
 
+      try {
         if (req.method === "GET" || req.method === "HEAD") {
           // Addendum I: storage bersama (bila dikonfigurasi) menggantikan file lokal.
           if (options.storage !== undefined) {
@@ -85,11 +108,7 @@ export function startNodeServer(
               });
               res.statusCode = 200;
               res.setHeader("content-type", contentTypeForPathname(url.pathname));
-              for (const [name, value] of Object.entries(options.headers ?? {})) {
-                if (!res.hasHeader(name)) {
-                  res.setHeader(name, value);
-                }
-              }
+              applyStaticHeaders(res, url.pathname, options.headers);
               res.end(req.method === "HEAD" ? undefined : Buffer.from(entry.body));
               return;
             }
@@ -107,20 +126,44 @@ export function startNodeServer(
               const body = readFileSync(staticFile);
               res.statusCode = 200;
               res.setHeader("content-type", MIME_TYPES[extname(staticFile).toLowerCase()] ?? "application/octet-stream");
-              for (const [name, value] of Object.entries(options.headers ?? {})) {
-                if (!res.hasHeader(name)) {
-                  res.setHeader(name, value);
-                }
-              }
+              applyStaticHeaders(res, url.pathname, options.headers);
               res.end(req.method === "HEAD" ? undefined : body);
               return;
             }
           }
         }
 
-        const response = await handler(await toWebRequest(req));
+        // Addendum J.2: batas body RPC ditegakkan di transport — lebih awal dari
+        // pipeline, tanpa membaca penuh; `content-length` diperiksa lebih dulu.
+        const isRpc = url.pathname.startsWith("/_moons/fn/");
+        const rpcLimit = options.bodyLimitBytes ?? DEFAULT_BODY_LIMIT_BYTES;
+        if (isRpc) {
+          const contentLength = Number(req.headers["content-length"] ?? "0");
+          if (Number.isFinite(contentLength) && contentLength > rpcLimit) {
+            res.statusCode = 413;
+            res.setHeader("content-type", "text/plain; charset=utf-8");
+            res.end(rpcBodyTooLargeText(rpcLimit, contentLength));
+            res.once("finish", () => req.destroy());
+            return;
+          }
+        }
+
+        const request = await toWebRequest(req, {
+          trustProxy: options.trustProxy === true,
+          ...(isRpc ? { maxBodyBytes: rpcLimit } : {}),
+        });
+        const response = await handler(request);
         await sendNodeResponse(res, response);
       } catch (error) {
+        if (error instanceof BodyLimitError) {
+          const isRpc = url.pathname.startsWith("/_moons/fn/");
+          res.statusCode = 413;
+          res.setHeader("content-type", "text/plain; charset=utf-8");
+          res.end(isRpc ? rpcBodyTooLargeText(error.limit, null) : "Payload Too Large");
+          // Sisa body tidak perlu dibaca — putuskan setelah respons terkirim.
+          res.once("finish", () => req.destroy());
+          return;
+        }
         console.error("[moons] server error:", error);
         res.statusCode = 500;
         res.setHeader("content-type", "text/plain; charset=utf-8");
@@ -159,6 +202,54 @@ export function startNodeServer(
   return server;
 }
 
+/**
+ * Addendum J.7: header konfigurasi (menang), default aman, dan
+ * `Cache-Control: immutable` untuk aset ber-hash di `/assets/*`.
+ */
+function applyStaticHeaders(
+  res: import("node:http").ServerResponse,
+  pathname: string,
+  configured: Record<string, string> | undefined,
+): void {
+  for (const [name, value] of Object.entries(configured ?? {})) {
+    if (!res.hasHeader(name)) {
+      res.setHeader(name, value);
+    }
+  }
+  for (const [name, value] of Object.entries(DEFAULT_SECURITY_HEADERS)) {
+    if (!res.hasHeader(name)) {
+      res.setHeader(name, value);
+    }
+  }
+  if (pathname.startsWith("/assets/") && !res.hasHeader("cache-control")) {
+    res.setHeader("cache-control", "public, max-age=31536000, immutable");
+  }
+}
+
+function respondBadRequest(res: import("node:http").ServerResponse): void {
+  res.statusCode = 400;
+  res.setHeader("content-type", "text/plain; charset=utf-8");
+  res.end("Bad Request");
+}
+
+/** 413 transport dengan format §15 yang sama seperti `rpc.ts` (Addendum J.2). */
+function rpcBodyTooLargeText(limit: number, size: number | null): string {
+  const megabytes = (bytes: number): string => (bytes / 1_000_000).toFixed(1);
+  return new MoonsError({
+    code: "E_RPC_BODY_TOO_LARGE",
+    message:
+      size === null
+        ? `body melebihi limit ${megabytes(limit)} MB`
+        : `body ${megabytes(size)} MB melebihi limit ${megabytes(limit)} MB`,
+    details:
+      "Body melebihi `security.bodyLimitBytes`; pembacaan dihentikan di transport sebelum penuh.",
+    suggestions: [
+      "Kurangi ukuran payload, atau",
+      "Naikkan security.bodyLimitBytes jika memang perlu",
+    ],
+  }).format();
+}
+
 /** Resolve file static dengan proteksi path traversal (+ manifest prerender D.5). */
 export function resolveStaticFile(clientDir: string, pathname: string): string | null {
   const target = staticFileTarget(clientDir, pathname);

package/src/server/node.ts

@@ -1,17 +1,88 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { CLIENT_IP_HEADER } from "@moonsjs/core";
 
-const MAX_BODY_BYTES = 32 * 1024 * 1024; // batas defensif transport; limit RPC §7.3 tetap berlaku
+/** Batas transport default (Addendum J.2); RPC punya batas lebih kecil dari config. */
+export const MAX_TRANSPORT_BODY_BYTES = 32 * 1024 * 1024;
 
-/** Konversi request Node → Web `Request` (body diteruskan untuk non-GET/HEAD, §7.3). */
-export async function toWebRequest(req: IncomingMessage): Promise<Request> {
-  const host = req.headers.host ?? "localhost";
-  const url = `http://${host}${req.url ?? "/"}`;
+/** Request tidak valid (Host/URL malformed) → dipetakan ke 400 oleh server. */
+export class InvalidRequestError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "InvalidRequestError";
+  }
+}
+
+/** Body melebihi batas → dipetakan ke 413; pembacaan dihentikan saat melewati. */
+export class BodyLimitError extends Error {
+  readonly limit: number;
+  constructor(limit: number) {
+    super(`request body melebihi batas ${limit} byte`);
+    this.name = "BodyLimitError";
+    this.limit = limit;
+  }
+}
+
+export interface ToWebRequestOptions {
+  /** Addendum J.1: percayai `x-forwarded-proto`/`x-forwarded-host` (default false). */
+  trustProxy?: boolean;
+  /** Batas pembacaan body (byte). Default: `MAX_TRANSPORT_BODY_BYTES`. */
+  maxBodyBytes?: number;
+}
+
+/**
+ * Rekonstruksi URL request (Addendum J.1). Tanpa `trustProxy`, origin/host
+ * murni dari header `Host` (perilaku lama, kebal spoofing `x-forwarded-*`).
+ * Malformed → `InvalidRequestError` (server memetakan ke 400).
+ */
+export function resolveRequestUrl(
+  req: IncomingMessage,
+  options: ToWebRequestOptions = {},
+): URL {
+  const hostHeader = req.headers.host ?? "localhost";
+  const trustProxy = options.trustProxy === true;
+  const proto = trustProxy ? forwardedProtocol(req.headers["x-forwarded-proto"]) : null;
+  const forwardedHostValue = trustProxy ? forwardedHost(req.headers["x-forwarded-host"]) : null;
+  const host = forwardedHostValue ?? hostHeader;
+  try {
+    return new URL(`${proto ?? "http"}://${host}${req.url ?? "/"}`);
+  } catch {
+    throw new InvalidRequestError(`header Host tidak valid: ${JSON.stringify(hostHeader)}`);
+  }
+}
+
+/** IP klien tepercaya (Addendum J.1): XFF (hanya bila trustProxy) → socket. */
+export function resolveClientIp(req: IncomingMessage, trustProxy: boolean): string | null {
+  if (trustProxy) {
+    const forwarded = firstHeaderValue(req.headers["x-forwarded-for"]);
+    if (forwarded !== null && isPlausibleIp(forwarded)) {
+      return normalizeIp(forwarded);
+    }
+  }
+  const remote = req.socket?.remoteAddress ?? null;
+  return remote === null ? null : normalizeIp(remote);
+}
+
+/** `::ffff:127.0.0.1` → `127.0.0.1`; buang zone id (`%eth0`). */
+function normalizeIp(value: string): string {
+  const withoutZone = stripZoneId(value);
+  return withoutZone.startsWith("::ffff:") ? withoutZone.slice(7) : withoutZone;
+}
+
+/** Konversi request Node → Web `Request` (body diteruskan untuk non-GET/HEAD, §7.3 + J.1/J.2). */
+export async function toWebRequest(
+  req: IncomingMessage,
+  options: ToWebRequestOptions = {},
+): Promise<Request> {
+  const url = resolveRequestUrl(req, options);
   const method = req.method ?? "GET";
 
   const headers = new Headers();
   for (const [key, value] of Object.entries(req.headers)) {
-    if (value === undefined || key === "content-length") {
+    if (value === undefined || key === "content-length" || key === CLIENT_IP_HEADER) {
       // content-length tidak disalin; fetch menghitung ulang dari body.
+      // x-moons-client-ip selalu ditimpa nilai tepercaya di bawah.
       continue;
     }
     if (Array.isArray(value)) {
@@ -23,34 +94,69 @@ export async function toWebRequest(req: IncomingMessage): Promise<Request> {
     }
   }
 
+  const clientIp = resolveClientIp(req, options.trustProxy === true);
+  if (clientIp !== null) {
+    headers.set(CLIENT_IP_HEADER, clientIp);
+  }
+
   if (method === "GET" || method === "HEAD") {
     return new Request(url, { method, headers });
   }
 
-  const body = await readBody(req);
-  return new Request(url, { method, headers, body: new Uint8Array(body) });
+  const body = await readBody(req, options.maxBodyBytes ?? MAX_TRANSPORT_BODY_BYTES);
+  // View zero-copy (bukan salinan) — Buffer selalu di atas ArrayBuffer biasa.
+  const view = new Uint8Array(body.buffer as ArrayBuffer, body.byteOffset, body.byteLength);
+  return new Request(url, { method, headers, body: view });
 }
 
-function readBody(req: IncomingMessage): Promise<Buffer> {
+/**
+ * Baca body dengan batas tegas (Addendum J.2): begitu melewati `maxBytes`,
+ * pembacaan dihentikan (pause) dan `BodyLimitError` dilempar — tidak pernah
+ * seluruh body besar masuk memori, dan hanya satu salinan buffer dibuat.
+ */
+export function readBody(req: IncomingMessage, maxBytes: number): Promise<Buffer> {
   return new Promise((resolvePromise, reject) => {
     const chunks: Buffer[] = [];
     let size = 0;
+    let settled = false;
+
+    const fail = (error: Error): void => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      req.pause();
+      reject(error);
+    };
 
     req.on("data", (chunk: Buffer) => {
+      if (settled) {
+        return;
+      }
       size += chunk.length;
-      if (size > MAX_BODY_BYTES) {
-        req.destroy();
-        reject(new Error("request body melebihi batas transport"));
+      if (size > maxBytes) {
+        fail(new BodyLimitError(maxBytes));
         return;
       }
       chunks.push(chunk);
     });
-    req.on("end", () => resolvePromise(Buffer.concat(chunks)));
-    req.on("error", (error) => reject(error));
+    req.on("end", () => {
+      if (!settled) {
+        settled = true;
+        resolvePromise(Buffer.concat(chunks));
+      }
+    });
+    req.on("error", (error) => fail(error));
   });
 }
 
-/** Tulis Web `Response` ke `ServerResponse` Node. */
+/** Addendum J.7: default aman runtime; `config.headers` tetap menang (cek hasHeader). */
+export const DEFAULT_SECURITY_HEADERS: Record<string, string> = {
+  "x-content-type-options": "nosniff",
+  "referrer-policy": "strict-origin-when-cross-origin",
+};
+
+/** Tulis Web `Response` ke `ServerResponse` Node (streaming bila ada body). */
 export async function sendNodeResponse(res: ServerResponse, response: Response): Promise<void> {
   res.statusCode = response.status;
   response.headers.forEach((value, key) => {
@@ -73,6 +179,65 @@ export async function sendNodeResponse(res: ServerResponse, response: Response):
       res.setHeader("set-cookie", single);
     }
   }
-  const body = Buffer.from(await response.arrayBuffer());
-  res.end(body);
+
+  for (const [name, value] of Object.entries(DEFAULT_SECURITY_HEADERS)) {
+    if (!res.hasHeader(name)) {
+      res.setHeader(name, value);
+    }
+  }
+
+  if (response.body === null || res.req?.method === "HEAD") {
+    res.end();
+    return;
+  }
+
+  // Addendum J.2: stream langsung — tidak ada `arrayBuffer()` penuh di memori.
+  await pipeline(
+    Readable.fromWeb(response.body as unknown as import("node:stream/web").ReadableStream),
+    res,
+  );
+}
+
+function firstHeaderValue(value: string | string[] | undefined): string | null {
+  if (value === undefined) {
+    return null;
+  }
+  const raw = Array.isArray(value) ? value[0] : value;
+  if (raw === undefined) {
+    return null;
+  }
+  const first = raw.split(",")[0]?.trim() ?? "";
+  return first.length === 0 ? null : first;
+}
+
+function forwardedProtocol(value: string | string[] | undefined): "http" | "https" | null {
+  const first = firstHeaderValue(value)?.toLowerCase() ?? null;
+  if (first === "https") {
+    return "https";
+  }
+  if (first === "http") {
+    return "http";
+  }
+  return null;
+}
+
+function forwardedHost(value: string | string[] | undefined): string | null {
+  const first = firstHeaderValue(value);
+  if (first === null || first.length === 0 || first.length > 255) {
+    return null;
+  }
+  // hostname[:port] — tolak karakter di luar himpunan aman (spasi, CRLF, /, @, ?).
+  if (!/^[A-Za-z0-9.\-[\]:]+$/.test(first)) {
+    return null;
+  }
+  return first;
+}
+
+function isPlausibleIp(value: string): boolean {
+  return value.length <= 64 && /^[0-9a-fA-F:.]+$/.test(value);
+}
+
+function stripZoneId(value: string): string {
+  const index = value.indexOf("%");
+  return index === -1 ? value : value.slice(0, index);
 }