@luckystack/server 0.2.4 → 0.2.6

package/CLAUDE.md

@@ -61,7 +61,7 @@ One-call server bootstrap for a LuckyStack project. Wires together a raw Node.js
 
 ## Config keys (env vars + registerProjectConfig slots)
 
-- `SERVER_PORT` (env, optional) — fallback when neither `options.port` nor positional argv supplies one. Written back by `applyServerArgv()` when argv carries a port.
+- `SERVER_PORT` (env, optional) — fallback when neither `options.port` nor positional argv supplies one. Written back by `applyServerArgv()` when argv carries a port. In dev, the ACTUALLY-bound port (after any `SERVER_PORT_AUTO_INCREMENT` hop off a busy port) is advertised to `node_modules/.luckystack/dev-server.json` so the template Vite proxy follows the real port instead of the stale `.env` one (written by `devServerInfo.ts`; skipped in prod + tests, removed on exit).
 - `SERVER_IP` (env, optional, default `127.0.0.1`) — bind address fallback when `options.ip` is omitted.
 - `NODE_ENV` (env, required for security-sensitive branches) — `development` / `test` toggle devkit hot reload + REPL and gate `/_test/reset`.
 - `TEST_RESET_TOKEN` (env, required for `/_test/reset` to be reachable at all) — must match the `x-test-reset-token` request header. No fallback "no auth" mode.

package/dist/index.js

@@ -7,7 +7,7 @@ import {
 
 // src/createServer.ts
 import http from "http";
-import { registerBindAddress, writeBootUuid, getLogger as getLogger12, getProjectConfig as getProjectConfig13, tryCatch as tryCatch9, isProduction as isProduction2 } from "@luckystack/core";
+import { registerBindAddress, writeBootUuid, getLogger as getLogger13, getProjectConfig as getProjectConfig13, tryCatch as tryCatch10, isProduction as isProduction2 } from "@luckystack/core";
 
 // src/httpHandler.ts
 import { randomUUID } from "crypto";
@@ -20,6 +20,7 @@ import {
   getProjectConfig as getProjectConfig10,
   hasCookie,
   readSession as readSession3,
+  tryCatch as tryCatch7,
   tryCatchSync
 } from "@luckystack/core";
 
@@ -538,6 +539,7 @@ var handleAuthApiRoute = async ({
 
 // src/httpRoutes/authLogoutRoute.ts
 import { getLogger as getLogger2, getProjectConfig as getProjectConfig6, tryCatch as tryCatch3 } from "@luckystack/core";
+var warnedNonStrictSameSite = false;
 var handleAuthLogoutRoute = async ({ res, routePath, method, token }) => {
   if (routePath !== "/auth/logout") return false;
   if (method !== "POST") {
@@ -557,7 +559,13 @@ var handleAuthLogoutRoute = async ({ res, routePath, method, token }) => {
     }
   }
   const http2 = getProjectConfig6().http;
-  const secure = process.env.SECURE === "true";
+  if (http2.sessionCookieSameSite !== "Strict" && !warnedNonStrictSameSite) {
+    warnedNonStrictSameSite = true;
+    getLogger2().warn(
+      `/auth/logout is exempt from CSRF middleware and relies on SameSite=Strict. Current sessionCookieSameSite="${http2.sessionCookieSameSite}" weakens this protection.`
+    );
+  }
+  const secure = resolveCookieSecure(http2.sessionCookieSecure, process.env.SECURE);
   res.setHeader(
     "Set-Cookie",
     `${http2.sessionCookieName}=; HttpOnly; SameSite=${http2.sessionCookieSameSite}; Path=${http2.sessionCookiePath}; Max-Age=0; ${secure ? "Secure;" : ""}`
@@ -1166,7 +1174,7 @@ var parseRequestParams = async ({
   }
   return params;
 };
-var handleHttpRequest = async (req, res, options) => {
+var handleHttpRequestInner = async (req, res, options) => {
   const config = getProjectConfig10();
   const shouldLogDev = config.logging.devLogs;
   const sessionCookieName = config.http.sessionCookieName;
@@ -1180,13 +1188,21 @@ var handleHttpRequest = async (req, res, options) => {
   );
   const url = req.url ?? "/";
   const [routePathRaw, queryStringRaw] = url.split("?");
-  const routePath = routePathRaw ?? "/";
+  const [decodeError, decodedPath] = tryCatchSync(() => decodeURIComponent(routePathRaw ?? "/"));
+  if (decodeError || decodedPath === null) {
+    res.statusCode = 400;
+    res.setHeader("Content-Type", "text/plain");
+    res.end("Bad Request");
+    return;
+  }
+  const routePath = decodedPath;
   const queryString = queryStringRaw ?? "";
   const { origin, rejected } = enforceOriginPolicy(req, res, routePath);
   if (rejected) return;
   setSecurityHeaders(req, res, origin);
   const incomingRequestId = req.headers["x-request-id"];
-  const requestId = (Array.isArray(incomingRequestId) ? incomingRequestId[0] : incomingRequestId) ?? randomUUID();
+  const rawRequestId = Array.isArray(incomingRequestId) ? incomingRequestId[0] : incomingRequestId;
+  const requestId = rawRequestId && /^[a-zA-Z0-9-]{1,128}$/.test(rawRequestId) ? rawRequestId : randomUUID();
   res.setHeader("X-Request-Id", requestId);
   const safeHeaders = {};
   for (const [k, v] of Object.entries(req.headers)) {
@@ -1246,6 +1262,15 @@ var handleHttpRequest = async (req, res, options) => {
   if (params === null) return;
   await dispatchRoutes(POST_PARAMS_ROUTES, { ...baseCtx, params });
 };
+var handleHttpRequest = async (req, res, options) => {
+  const [error] = await tryCatch7(() => handleHttpRequestInner(req, res, options));
+  if (error && !res.writableEnded) {
+    getLogger7().error("handleHttpRequest: unhandled error", { err: error });
+    res.statusCode = 500;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify({ status: "error", errorCode: "server.internalError" }));
+  }
+};
 
 // src/loadSocket.ts
 import { Server as SocketIOServer } from "socket.io";
@@ -1271,7 +1296,7 @@ import {
   normalizeErrorResponse,
   readSession as readSession4,
   writeSession,
-  tryCatch as tryCatch7
+  tryCatch as tryCatch8
 } from "@luckystack/core";
 import { handleApiRequest } from "@luckystack/api";
 var sessionLocks = /* @__PURE__ */ new Map();
@@ -1279,7 +1304,7 @@ var withSessionLock = async (token, fn) => {
   const prev = sessionLocks.get(token) ?? Promise.resolve();
   const next = prev.then(fn, fn);
   sessionLocks.set(token, next);
-  await tryCatch7(() => next);
+  await tryCatch8(() => next);
   if (sessionLocks.get(token) === next) sessionLocks.delete(token);
 };
 var getVisibleSocketRooms = (socket, token) => {
@@ -1304,7 +1329,7 @@ var validateRoomRequest = (socket, responseIndex, token, group, preferredLocale,
     }));
     return false;
   }
-  if (!group) {
+  if (!group || group.length > 256) {
     socket.emit(buildResponseEventName(responseIndex), normalizeErrorResponse({
       response: { status: "error", errorCode: "room.invalid" },
       preferredLocale
@@ -1490,6 +1515,15 @@ var registerUpdateLocationEvent = (ctx) => {
     (newLocation) => {
       if (!token) return;
       if (!locationProviderEnabled) return;
+      if (typeof newLocation.pathName !== "string" || !newLocation.pathName.startsWith("/") || newLocation.pathName.length > 2048 || newLocation.pathName.includes("\0")) return;
+      if (newLocation.searchParams !== void 0) {
+        if (typeof newLocation.searchParams !== "object" || Array.isArray(newLocation.searchParams)) return;
+        const entries = Object.entries(newLocation.searchParams);
+        if (entries.length > 50) return;
+        for (const [k, v] of entries) {
+          if (typeof k !== "string" || k.length > 256 || typeof v !== "string" || v.length > 1024) return;
+        }
+      }
       if (shouldLogDev) {
         getLogger8().debug("updating location", { pathName: newLocation.pathName });
       }
@@ -1543,7 +1577,7 @@ var rejoinPersistedRooms = (ctx) => {
   const { socket, token, shouldLogDev } = ctx;
   if (!token) return;
   void (async () => {
-    const [rejoinError, codes] = await tryCatch7(async () => {
+    const [rejoinError, codes] = await tryCatch8(async () => {
       await socket.join(token);
       const session = await readSession4(token);
       const roomCodes = session ? getSessionRoomCodes(session) : [];
@@ -1853,7 +1887,7 @@ import {
   dispatchHook as dispatchHook7,
   flushErrorTrackers,
   getLogger as getLogger11,
-  tryCatch as tryCatch8
+  tryCatch as tryCatch9
 } from "@luckystack/core";
 var DEFAULT_SHUTDOWN_TIMEOUT_MS = 1e4;
 var withTimeout = async (label, timeoutMs, fn) => {
@@ -1866,7 +1900,7 @@ var withTimeout = async (label, timeoutMs, fn) => {
     timer.unref();
   });
   const run = (async () => {
-    const [error] = await tryCatch8(fn);
+    const [error] = await tryCatch9(fn);
     if (error) getLogger11().warn(`[shutdown] step "${label}" failed: ${error.message}`);
     return true;
   })();
@@ -1906,6 +1940,32 @@ var runGracefulShutdown = async (deps, options = {}) => {
   getLogger11().info("[shutdown] graceful shutdown complete");
 };
 
+// src/devServerInfo.ts
+import fs from "fs";
+import path2 from "path";
+import { getLogger as getLogger12 } from "@luckystack/core";
+var DEV_SERVER_FILE = ["node_modules", ".luckystack", "dev-server.json"];
+var devServerInfoPath = () => path2.join(process.cwd(), ...DEV_SERVER_FILE);
+var writeDevServerInfo = (ip, port) => {
+  try {
+    const file = devServerInfoPath();
+    fs.mkdirSync(path2.dirname(file), { recursive: true });
+    const info = { ip, port, pid: process.pid };
+    fs.writeFileSync(file, `${JSON.stringify(info, null, 2)}
+`);
+  } catch (error) {
+    getLogger12().debug(
+      `[dev-server-info] could not write port file (proxy will fall back to SERVER_PORT): ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+};
+var clearDevServerInfo = () => {
+  try {
+    fs.rmSync(devServerInfoPath(), { force: true });
+  } catch {
+  }
+};
+
 // src/createServer.ts
 var initDevTools = async () => {
   const { initConsolelog } = await import("@luckystack/core");
@@ -1931,13 +1991,13 @@ var listenLuckyStackServer = (httpServer, ip, port, callback) => new Promise((re
         return;
       }
       if (autoIncrement) {
-        getLogger12().warn(
+        getLogger13().warn(
           `Port ${String(attemptPort)} is in use \u2014 trying ${String(attemptPort + 1)} (auto-increment; set SERVER_PORT_AUTO_INCREMENT=0 to disable)`
         );
         tryListen(attemptPort + 1);
         return;
       }
-      getLogger12().error(
+      getLogger13().error(
         `Port ${String(attemptPort)} is already in use \u2014 the server did NOT start. Another \`npm run server\` is probably still running (stop it), or set SERVER_PORT to a free port, or set SERVER_PORT_AUTO_INCREMENT=1 to auto-pick the next free port.`
       );
       reject(err);
@@ -1945,9 +2005,13 @@ var listenLuckyStackServer = (httpServer, ip, port, callback) => new Promise((re
     httpServer.once("error", onError);
     httpServer.listen(attemptPort, ip, () => {
       httpServer.off("error", onError);
+      if (!isProduction2 && process.env.NODE_ENV !== "test") {
+        writeDevServerInfo(ip, attemptPort);
+        process.once("exit", clearDevServerInfo);
+      }
       const config = getProjectConfig13();
       if (config.logging.socketStartup || config.logging.devLogs) {
-        getLogger12().info(`Server is running on http://${ip}:${String(attemptPort)}/`);
+        getLogger13().info(`Server is running on http://${ip}:${String(attemptPort)}/`);
       }
       callback?.();
       resolve(httpServer);
@@ -1977,7 +2041,7 @@ var createLuckyStackServer = async (options = {}) => {
   if (enableDevTools) {
     await initDevTools();
   }
-  const [bootUuidError] = await tryCatch9(() => writeBootUuid());
+  const [bootUuidError] = await tryCatch10(() => writeBootUuid());
   if (bootUuidError) {
     throw new Error(
       "Failed to write the boot UUID to Redis. Check REDIS_HOST / REDIS_PORT / REDIS_USER / REDIS_PASSWORD and that Redis is reachable.",
@@ -1989,7 +2053,7 @@ var createLuckyStackServer = async (options = {}) => {
   });
   httpServer.on("error", (err) => {
     if (err.code === "EADDRINUSE") return;
-    getLogger12().error("[http-server] runtime error", err);
+    getLogger13().error("[http-server] runtime error", err);
   });
   const { io: ioServer, adapterClients } = loadSocket(httpServer, {
     maxHttpBufferSize: options.maxHttpBufferSize
@@ -2018,8 +2082,8 @@ var createLuckyStackServer = async (options = {}) => {
 };
 
 // src/bootstrap.ts
-import path2 from "path";
-import fs from "fs";
+import path3 from "path";
+import fs2 from "fs";
 import { pathToFileURL } from "url";
 import { ROOT_DIR } from "@luckystack/core";
 var OVERLAY_ORDER = [
@@ -2042,26 +2106,26 @@ var OVERLAY_ORDER = [
   "server"
 ];
 var importIfExists = async (filePath) => {
-  if (!fs.existsSync(filePath)) return;
+  if (!fs2.existsSync(filePath)) return;
   await import(pathToFileURL(filePath).href);
 };
 var loadOverlayFolder = async (overlayRoot) => {
-  const overlayAbs = path2.isAbsolute(overlayRoot) ? overlayRoot : path2.join(ROOT_DIR, overlayRoot);
-  if (!fs.existsSync(overlayAbs)) {
+  const overlayAbs = path3.isAbsolute(overlayRoot) ? overlayRoot : path3.join(ROOT_DIR, overlayRoot);
+  if (!fs2.existsSync(overlayAbs)) {
     return;
   }
   for (const packageName of OVERLAY_ORDER) {
-    const packageDir = path2.join(overlayAbs, packageName);
-    if (!fs.existsSync(packageDir)) continue;
+    const packageDir = path3.join(overlayAbs, packageName);
+    if (!fs2.existsSync(packageDir)) continue;
     const indexCandidates = ["index.ts", "index.js"];
     for (const candidate of indexCandidates) {
-      await importIfExists(path2.join(packageDir, candidate));
+      await importIfExists(path3.join(packageDir, candidate));
     }
-    const entries = fs.readdirSync(packageDir).toSorted();
+    const entries = fs2.readdirSync(packageDir).toSorted();
     for (const entry of entries) {
       if (indexCandidates.includes(entry)) continue;
       if (!entry.endsWith(".ts") && !entry.endsWith(".js")) continue;
-      await importIfExists(path2.join(packageDir, entry));
+      await importIfExists(path3.join(packageDir, entry));
     }
   }
 };