@luckystack/server 0.1.9 → 0.2.1

package/dist/index.js

@@ -1,6 +1,13 @@
+import {
+  applyServerArgv,
+  getParsedBundles,
+  getParsedPort,
+  parseServerArgv
+} from "./chunk-X3OSC5W3.js";
+
 // src/createServer.ts
 import http from "http";
-import { registerBindAddress, writeBootUuid, getLogger as getLogger9, getProjectConfig as getProjectConfig10, tryCatch as tryCatch7 } from "@luckystack/core";
+import { registerBindAddress, writeBootUuid, getLogger as getLogger12, getProjectConfig as getProjectConfig13, tryCatch as tryCatch9, isProduction as isProduction2 } from "@luckystack/core";
 
 // src/httpHandler.ts
 import { randomUUID } from "crypto";
@@ -8,40 +15,139 @@ import {
   allowedOrigin,
   dispatchHook as dispatchHook5,
   extractTokenFromRequest as extractTokenFromRequest3,
-  getLogger as getLogger6,
+  getLogger as getLogger7,
   getParams,
-  getProjectConfig as getProjectConfig8,
-  hasCookie
+  getProjectConfig as getProjectConfig10,
+  hasCookie,
+  readSession as readSession3,
+  tryCatchSync
 } from "@luckystack/core";
-import { getSession as getSession3 } from "@luckystack/login";
 
 // src/logSanitize.ts
 import { getProjectConfig, isRedactedLogKey } from "@luckystack/core";
 var REDACTED_PLACEHOLDER = "[REDACTED]";
+var TRUNCATED_PLACEHOLDER = "[TRUNCATED]";
+var MAX_SANITIZE_DEPTH = 40;
 var isRedactedKey = (key) => {
   if (isRedactedLogKey(key)) return true;
   return key.toLowerCase() === getProjectConfig().http.sessionCookieName.toLowerCase();
 };
-var sanitizeForLog = (value) => {
+var sanitizeWithGuards = (value, depth, seen) => {
   if (value === null || typeof value !== "object") return value;
-  if (Array.isArray(value)) return value.map((entry) => sanitizeForLog(entry));
-  const out = {};
-  for (const [key, val] of Object.entries(value)) {
-    out[key] = isRedactedKey(key) ? REDACTED_PLACEHOLDER : sanitizeForLog(val);
+  if (seen.has(value)) return TRUNCATED_PLACEHOLDER;
+  if (depth >= MAX_SANITIZE_DEPTH) return TRUNCATED_PLACEHOLDER;
+  seen.add(value);
+  try {
+    if (Array.isArray(value)) {
+      return value.map((entry) => sanitizeWithGuards(entry, depth + 1, seen));
+    }
+    const out = {};
+    for (const [key, val] of Object.entries(value)) {
+      out[key] = isRedactedKey(key) ? REDACTED_PLACEHOLDER : sanitizeWithGuards(val, depth + 1, seen);
+    }
+    return out;
+  } finally {
+    seen.delete(value);
   }
-  return out;
 };
+var sanitizeForLog = (value) => sanitizeWithGuards(value, 0, /* @__PURE__ */ new WeakSet());
 
 // src/securityHeadersRegistry.ts
-var registeredBuilder = null;
+import { createRegistry } from "@luckystack/core";
+var builderRegistry = createRegistry(null);
 var registerSecurityHeaders = (builder) => {
-  registeredBuilder = builder;
+  builderRegistry.register(builder);
+};
+var getSecurityHeadersBuilder = () => builderRegistry.get();
+
+// src/httpRoutes/csrfMiddleware.ts
+import { dispatchHook, getCookieValue, getCsrfConfig, getProjectConfig as getProjectConfig2, readSession } from "@luckystack/core";
+
+// src/capabilities.ts
+import { createRequire } from "module";
+var localRequire = createRequire(import.meta.url);
+var esmResolve = import.meta.resolve;
+var _warnedResolverMissing = false;
+var warnResolverMissingOnce = () => {
+  if (_warnedResolverMissing) return;
+  _warnedResolverMissing = true;
+  console.warn(
+    "[luckystack:capabilities] import.meta.resolve is unavailable (Node < 20.6). Optional package detection falls back to require.resolve, which cannot resolve import-only exports maps and may misreport @luckystack/* packages as absent. Upgrade to Node >= 20.6 to ensure correct capability detection."
+  );
+};
+var has = (pkg) => {
+  if (typeof esmResolve === "function") {
+    try {
+      esmResolve(pkg);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  warnResolverMissingOnce();
+  try {
+    localRequire.resolve(pkg);
+    return true;
+  } catch (error) {
+    if (error instanceof Error && error.code === "ERR_PACKAGE_PATH_NOT_EXPORTED") {
+      return true;
+    }
+    return false;
+  }
+};
+var capabilities = {
+  login: has("@luckystack/login"),
+  presence: has("@luckystack/presence"),
+  sync: has("@luckystack/sync")
+};
+var OPTIONAL_PACKAGES = [
+  "login",
+  "email",
+  "error-tracking",
+  "presence",
+  "docs-ui"
+];
+var canResolve = (specifier) => has(specifier);
+var loginMod;
+var getLogin = async () => {
+  if (loginMod !== void 0) return loginMod;
+  loginMod = capabilities.login ? await import("@luckystack/login") : null;
+  return loginMod;
+};
+var presenceMod;
+var getPresence = async () => {
+  if (presenceMod !== void 0) return presenceMod;
+  presenceMod = capabilities.presence ? await import("@luckystack/presence") : null;
+  return presenceMod;
+};
+var syncMod;
+var getSync = async () => {
+  if (syncMod !== void 0) return syncMod;
+  syncMod = capabilities.sync ? await import("@luckystack/sync") : null;
+  return syncMod;
+};
+
+// src/originExemptRegistry.ts
+var exemptPaths = [];
+var registerOriginExemptPath = (matcher) => {
+  exemptPaths.push(matcher);
+};
+var getOriginExemptPaths = () => exemptPaths;
+var clearOriginExemptPaths = () => {
+  exemptPaths.length = 0;
+};
+var isOriginExemptPath = (routePath) => exemptPaths.some((matcher) => routePath.startsWith(matcher.pathPrefix));
+
+// src/httpRoutes/timingSafeEqual.ts
+import { timingSafeEqual as cryptoTimingSafeEqual } from "crypto";
+var timingSafeStringEqual = (a, b) => {
+  const aBuf = Buffer.from(a, "utf8");
+  const bBuf = Buffer.from(b, "utf8");
+  if (aBuf.length !== bBuf.length) return false;
+  return cryptoTimingSafeEqual(aBuf, bBuf);
 };
-var getSecurityHeadersBuilder = () => registeredBuilder;
 
 // src/httpRoutes/csrfMiddleware.ts
-import { dispatchHook, getCsrfConfig, getProjectConfig as getProjectConfig2 } from "@luckystack/core";
-import { getSession } from "@luckystack/login";
 var enforceCsrfOnStateChangingRequest = async ({
   req,
   res,
@@ -51,20 +157,41 @@ var enforceCsrfOnStateChangingRequest = async ({
 }) => {
   const config = getProjectConfig2();
   const isCookieMode = !config.session.basedToken;
-  const isStateChanging = req.method !== "GET" && req.method !== "OPTIONS";
+  const isStateChanging = req.method !== "GET" && req.method !== "HEAD" && req.method !== "OPTIONS";
   const isCallbackPath = routePath.startsWith("/auth/callback");
   const isAuthBootstrap = routePath === "/auth/api/credentials";
-  const looksLikeFrameworkRoute = routePath.startsWith("/api/") || routePath.startsWith("/sync/") || routePath.startsWith("/auth/api/") && !isAuthBootstrap;
-  if (!(isCookieMode && isStateChanging && looksLikeFrameworkRoute && !isCallbackPath && token)) {
+  const isExemptFromCsrf = isAuthBootstrap || isCallbackPath || isOriginExemptPath(routePath);
+  const isCsrfCandidate = routePath.startsWith("/api/") || routePath.startsWith("/sync/") || routePath.startsWith("/auth/api/") || !routePath.startsWith("/auth/") && !routePath.startsWith("/assets/");
+  if (!(isCookieMode && isStateChanging && isCsrfCandidate && !isExemptFromCsrf)) {
     return false;
   }
-  const csrfSession = await getSession(token);
-  if (!csrfSession?.id) return false;
   const csrfConfig = getCsrfConfig();
   const headerKey = csrfConfig.headerName.toLowerCase();
   const headerValue = req.headers[headerKey];
   const provided = Array.isArray(headerValue) ? headerValue[0] : headerValue;
-  if (provided && provided === csrfSession.csrfToken) return false;
+  if (!capabilities.login) {
+    const cookieValue = getCookieValue(req.headers.cookie, csrfConfig.cookieName);
+    if (cookieValue && provided && timingSafeStringEqual(provided, cookieValue)) return false;
+    void dispatchHook("csrfMismatch", {
+      route: routePath,
+      method: req.method,
+      requestId,
+      userId: void 0,
+      providedToken: Boolean(provided)
+    });
+    res.statusCode = 403;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify({
+      status: "error",
+      errorCode: "auth.csrfMismatch",
+      message: "CSRF token missing or invalid. Fetch /auth/csrf first."
+    }));
+    return true;
+  }
+  if (!token) return false;
+  const csrfSession = await readSession(token);
+  if (!csrfSession?.id) return false;
+  if (provided && csrfSession.csrfToken && timingSafeStringEqual(provided, csrfSession.csrfToken)) return false;
   void dispatchHook("csrfMismatch", {
     route: routePath,
     method: req.method,
@@ -83,16 +210,35 @@ var enforceCsrfOnStateChangingRequest = async ({
 };
 
 // src/httpRoutes/csrfRoute.ts
-import { getSession as getSession2 } from "@luckystack/login";
+import { randomBytes } from "crypto";
+import { getCsrfConfig as getCsrfConfig2, readSession as readSession2 } from "@luckystack/core";
+var serializeCsrfCookie = (name, value, opts) => {
+  const parts = [`${name}=${value}`];
+  if (opts.httpOnly) parts.push("HttpOnly");
+  if (opts.sameSite) parts.push(`SameSite=${opts.sameSite.charAt(0).toUpperCase()}${opts.sameSite.slice(1)}`);
+  if (opts.secure) parts.push("Secure");
+  parts.push(`Path=${opts.path ?? "/"}`);
+  if (typeof opts.maxAgeMs === "number") parts.push(`Max-Age=${String(Math.floor(opts.maxAgeMs / 1e3))}`);
+  return parts.join("; ");
+};
 var handleCsrfRoute = async ({ res, routePath, token }) => {
   if (routePath !== "/auth/csrf") return false;
+  const csrfConfig = getCsrfConfig2();
+  if (!capabilities.login) {
+    const doubleSubmit = randomBytes(csrfConfig.tokenLength).toString("hex");
+    res.statusCode = 200;
+    res.setHeader("Set-Cookie", serializeCsrfCookie(csrfConfig.cookieName, doubleSubmit, csrfConfig.cookieOptions));
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify({ status: "success", csrfToken: doubleSubmit }));
+    return true;
+  }
   if (!token) {
     res.statusCode = 401;
     res.setHeader("Content-Type", "application/json");
     res.end(JSON.stringify({ status: "error", errorCode: "auth.unauthenticated" }));
     return true;
   }
-  const csrfSession = await getSession2(token);
+  const csrfSession = await readSession2(token);
   if (!csrfSession?.id) {
     res.statusCode = 401;
     res.setHeader("Content-Type", "application/json");
@@ -123,6 +269,7 @@ var handleFaviconRoute = async ({ res, routePath, options }) => {
 // src/httpRoutes/healthRoutes.ts
 import {
   computeSynchronizedEnvHashes,
+  describeHealthHashConfig,
   getProjectConfig as getProjectConfig3,
   prisma,
   readBootUuid,
@@ -169,14 +316,18 @@ var handleReadyzRoute = async ({ res, routePath }) => {
 var handleHealthRoute = async ({ res, routePath }) => {
   if (routePath !== getProjectConfig3().http.healthEndpoint) return false;
   const bootUuid = await readBootUuid();
-  const synchronizedHashes = computeSynchronizedEnvHashes();
+  const synchronizedHashes = computeSynchronizedEnvHashes(bootUuid);
   res.statusCode = bootUuid ? 200 : 503;
   res.setHeader("Content-Type", "application/json");
   res.end(JSON.stringify({
     status: bootUuid ? "ok" : "degraded",
     bootUuid,
     envKey: resolveEnvKey(),
-    synchronizedHashes
+    synchronizedHashes,
+    //? Tell the router HOW these hashes were produced (mode + whether the salt is
+    //? the `@bootUuid` sentinel) so it can hash its local values with the SAME
+    //? config instead of its own default. Never exposes a static salt (a secret).
+    healthHash: describeHealthHashConfig()
   }));
   return true;
 };
@@ -200,7 +351,9 @@ var handleTestResetRoute = async ({ req, res, routePath }) => {
     return true;
   }
   const requiredToken = process.env.TEST_RESET_TOKEN;
-  if (!requiredToken || req.headers["x-test-reset-token"] !== requiredToken) {
+  const providedToken = req.headers["x-test-reset-token"];
+  const tokenValue = Array.isArray(providedToken) ? providedToken[0] : providedToken;
+  if (!requiredToken || !tokenValue || !timingSafeStringEqual(tokenValue, requiredToken)) {
     res.statusCode = 403;
     res.setHeader("Content-Type", "application/json");
     res.end(JSON.stringify({ status: "error", errorCode: "auth.forbidden" }));
@@ -232,8 +385,7 @@ var handleTestResetRoute = async ({ req, res, routePath }) => {
   await scanAndDelete(sessionPattern, "sessions");
   await scanAndDelete(activeUsersPattern, "activeUsers");
   const rawUrl = req.url ?? "/";
-  const base = `http://${req.headers.host ?? "localhost"}`;
-  const includeFlag = URL.canParse(rawUrl, base) ? new URL(rawUrl, base).searchParams.get("include") ?? "" : "";
+  const includeFlag = URL.canParse(rawUrl, "http://localhost") ? new URL(rawUrl, "http://localhost").searchParams.get("include") ?? "" : "";
   if (includeFlag.split(",").map((s) => s.trim()).includes("hooks")) {
     clearAllHooks();
     cleared.push("hooks");
@@ -257,15 +409,14 @@ import {
   checkRateLimit,
   dispatchHook as dispatchHook2,
   getLogger,
-  getProjectConfig as getProjectConfig5
+  getProjectConfig as getProjectConfig5,
+  resolveClientIp
 } from "@luckystack/core";
-import {
-  createOAuthState,
-  deleteSession,
-  getOAuthProviders,
-  isFullOAuthProvider,
-  loginWithCredentials
-} from "@luckystack/login";
+
+// src/httpRoutes/sessionCookie.ts
+var resolveCookieSecure = (sessionCookieSecure, secureEnv) => sessionCookieSecure ?? secureEnv === "true";
+
+// src/httpRoutes/authApiRoute.ts
 var parseSessionBasedTokenHeader = (headerValue) => {
   if (headerValue === void 0) return null;
   const value = Array.isArray(headerValue) ? headerValue[0] : headerValue;
@@ -282,18 +433,26 @@ var handleAuthApiRoute = async ({
   sessionCookieOptions
 }) => {
   if (!routePath.startsWith("/auth/api")) return false;
+  const login = await getLogin();
+  if (!login) {
+    res.setHeader("content-type", "application/json; charset=utf-8");
+    res.end(JSON.stringify({ status: false, reason: "auth.disabled" }));
+    return true;
+  }
   const config = getProjectConfig5();
   const sessionCookieName = config.http.sessionCookieName;
   const shouldLogDev = config.logging.devLogs;
   const providerName = routePath.split("/")[3];
-  const provider = getOAuthProviders().find((p) => p.name === providerName);
+  const provider = login.getOAuthProviders().find((p) => p.name === providerName);
   if (!provider?.name) {
     res.setHeader("Content-Type", "application/json");
     res.end(JSON.stringify({ status: false, reason: "login.providerNotFound" }));
     return true;
   }
-  if (isFullOAuthProvider(provider)) {
-    const oauthState = await createOAuthState(provider.name);
+  if (login.isFullOAuthProvider(provider)) {
+    const reqUrl = new URL(req.url ?? "/", "http://placeholder");
+    const returnUrl = reqUrl.searchParams.get("return_url") ?? void 0;
+    const oauthState = await login.createOAuthState(provider.name, { usePkce: provider.usePkce, returnUrl });
     if (!oauthState) {
       res.writeHead(500, { "Content-Type": "application/json" });
       res.end(JSON.stringify({ status: false, reason: "login.oauthStateInitFailed" }));
@@ -302,28 +461,42 @@ var handleAuthApiRoute = async ({
     const clientId = encodeURIComponent(provider.clientID);
     const callbackUrl = encodeURIComponent(provider.callbackURL);
     const scope = encodeURIComponent(provider.scope.join(" "));
-    const state = encodeURIComponent(oauthState);
+    const state = encodeURIComponent(oauthState.state);
+    const stateTtl = config.auth.oauthStateTtlSeconds;
+    const secureFlag = resolveCookieSecure(config.http.sessionCookieSecure, process.env.SECURE) ? " Secure;" : "";
+    res.setHeader(
+      "Set-Cookie",
+      `${login.OAUTH_STATE_COOKIE_NAME}=${oauthState.stateCookie}; Path=/; HttpOnly;${secureFlag} SameSite=Lax; Max-Age=${stateTtl}`
+    );
+    const pkceParams = oauthState.codeChallenge ? `&code_challenge=${encodeURIComponent(oauthState.codeChallenge)}&code_challenge_method=S256` : "";
     res.writeHead(302, {
-      Location: `${provider.authorizationURL}?client_id=${clientId}&redirect_uri=${callbackUrl}&scope=${scope}&response_type=code&prompt=select_account&state=${state}`
+      Location: `${provider.authorizationURL}?client_id=${clientId}&redirect_uri=${callbackUrl}&scope=${scope}&response_type=code&prompt=select_account&state=${state}${pkceParams}`
     });
     res.end();
     return true;
   }
   const rateLimiting = config.rateLimiting;
-  if (rateLimiting.defaultApiLimit !== false && rateLimiting.defaultApiLimit > 0) {
-    const requesterIp = req.socket.remoteAddress ?? "unknown";
+  const requesterIp = resolveClientIp({
+    rawAddress: req.socket.remoteAddress,
+    headers: req.headers,
+    trustProxy: config.http.trustProxy,
+    trustedProxyHopCount: config.http.trustedProxyHopCount
+  });
+  const ipLimitCount = rateLimiting.defaultApiLimit !== false && rateLimiting.defaultApiLimit > 0 ? rateLimiting.defaultApiLimit : rateLimiting.auth.enabled && rateLimiting.auth.maxAttempts > 0 ? rateLimiting.auth.maxAttempts : null;
+  if (ipLimitCount !== null) {
+    const ipWindowMs = rateLimiting.defaultApiLimit === false ? rateLimiting.auth.windowMs : rateLimiting.windowMs;
     const { allowed, resetIn } = await checkRateLimit({
       key: `ip:${requesterIp}:auth:credentials`,
-      limit: rateLimiting.defaultApiLimit,
-      windowMs: rateLimiting.windowMs
+      limit: ipLimitCount,
+      windowMs: ipWindowMs
     });
     if (!allowed) {
       void dispatchHook2("rateLimitExceeded", {
         scope: "auth",
         key: `ip:${requesterIp}:auth:credentials`,
-        limit: rateLimiting.defaultApiLimit,
-        windowMs: rateLimiting.windowMs,
-        count: rateLimiting.defaultApiLimit + 1,
+        limit: ipLimitCount,
+        windowMs: ipWindowMs,
+        count: ipLimitCount + 1,
         route: routePath,
         ip: requesterIp
       });
@@ -336,7 +509,7 @@ var handleAuthApiRoute = async ({
       return true;
     }
   }
-  const result = await loginWithCredentials(params, { supersedeToken: token });
+  const result = await login.loginWithCredentials(params, { supersedeToken: token ?? void 0, requesterIp });
   if (!result?.status) {
     const reasonKey = typeof result?.reason === "string" && result.reason.length > 0 ? result.reason : "api.internalServerError";
     res.setHeader("content-type", "application/json; charset=utf-8");
@@ -344,7 +517,7 @@ var handleAuthApiRoute = async ({
     return true;
   }
   if (result.newToken) {
-    if (token) await deleteSession(token, { skipSocketLogout: true });
+    if (token) await login.deleteSession(token, { skipSocketLogout: true });
     const requestedSessionMode = parseSessionBasedTokenHeader(req.headers["x-session-based-token"]);
     const useSessionBasedToken = requestedSessionMode ?? config.session.basedToken;
     if (shouldLogDev) getLogger().debug("http: setting cookie with new token");
@@ -363,18 +536,50 @@ var handleAuthApiRoute = async ({
   return true;
 };
 
+// src/httpRoutes/authLogoutRoute.ts
+import { getLogger as getLogger2, getProjectConfig as getProjectConfig6, tryCatch as tryCatch3 } from "@luckystack/core";
+var handleAuthLogoutRoute = async ({ res, routePath, method, token }) => {
+  if (routePath !== "/auth/logout") return false;
+  if (method !== "POST") {
+    res.statusCode = 405;
+    res.setHeader("Allow", "POST");
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify({ status: "error", errorCode: "api.methodNotAllowed" }));
+    return true;
+  }
+  if (token) {
+    const login = await getLogin();
+    if (login) {
+      const [deleteError] = await tryCatch3(() => login.deleteSession(token));
+      if (deleteError) {
+        getLogger2().warn("http logout: deleteSession failed \u2014 clearing cookie anyway", { err: deleteError });
+      }
+    }
+  }
+  const http2 = getProjectConfig6().http;
+  const secure = process.env.SECURE === "true";
+  res.setHeader(
+    "Set-Cookie",
+    `${http2.sessionCookieName}=; HttpOnly; SameSite=${http2.sessionCookieSameSite}; Path=${http2.sessionCookiePath}; Max-Age=0; ${secure ? "Secure;" : ""}`
+  );
+  res.statusCode = 200;
+  res.setHeader("Content-Type", "application/json");
+  res.end(JSON.stringify({ status: "success", result: true }));
+  return true;
+};
+
 // src/httpRoutes/authProvidersRoute.ts
-import { getOAuthProviders as getOAuthProviders2 } from "@luckystack/login";
-var handleAuthProvidersRoute = ({ req, res, routePath }) => {
-  if (routePath !== "/auth/providers" || req.method !== "GET") return Promise.resolve(false);
+var handleAuthProvidersRoute = async ({ req, res, routePath }) => {
+  if (routePath !== "/auth/providers" || req.method !== "GET") return false;
+  const login = await getLogin();
+  const providers = login ? login.getOAuthProviders().map((provider) => provider.name) : [];
   res.setHeader("Content-Type", "application/json");
-  res.end(JSON.stringify({ providers: getOAuthProviders2().map((provider) => provider.name) }));
-  return Promise.resolve(true);
+  res.end(JSON.stringify({ providers }));
+  return true;
 };
 
 // src/httpRoutes/authCallbackRoute.ts
-import { getLogger as getLogger2, getProjectConfig as getProjectConfig6 } from "@luckystack/core";
-import { deleteSession as deleteSession2, loginCallback } from "@luckystack/login";
+import { getLogger as getLogger3, getProjectConfig as getProjectConfig7 } from "@luckystack/core";
 var handleAuthCallbackRoute = async ({
   req,
   res,
@@ -383,27 +588,34 @@ var handleAuthCallbackRoute = async ({
   sessionCookieOptions
 }) => {
   if (!routePath.startsWith("/auth/callback")) return false;
-  const config = getProjectConfig6();
+  const login = await getLogin();
+  if (!login) {
+    res.writeHead(404, { "Content-Type": "text/plain" });
+    res.end("Auth is not enabled");
+    return true;
+  }
+  const config = getProjectConfig7();
   const sessionCookieName = config.http.sessionCookieName;
   const shouldLogDev = config.logging.devLogs;
   const publicOrigin = (config.app.publicUrl || "").replace(/\/+$/, "");
   const loginRedirect = config.loginRedirectUrl || "/";
-  const baseLocation = /^https?:\/\//i.test(loginRedirect) ? loginRedirect : `${publicOrigin}${loginRedirect.startsWith("/") ? loginRedirect : `/${loginRedirect}`}` || "/";
-  const callbackResult = await loginCallback(routePath, req, res, {
+  const baseLocation = /^https?:\/\//i.test(loginRedirect) ? loginRedirect : `${publicOrigin}${loginRedirect.startsWith("/") ? loginRedirect : `/${loginRedirect}`}`;
+  const callbackResult = await login.loginCallback(routePath, req, res, {
     defaultRedirectUrl: baseLocation,
-    supersedeToken: token
+    supersedeToken: token ?? void 0
   });
   if (!callbackResult) {
     res.writeHead(401, { "Content-Type": "text/plain" });
     res.end("Login failed");
     return true;
   }
-  if (token) await deleteSession2(token, { skipSocketLogout: true });
-  if (shouldLogDev) getLogger2().debug("http: setting cookie or redirect with new token");
+  if (token) await login.deleteSession(token, { skipSocketLogout: true });
+  if (shouldLogDev) getLogger3().debug("http: setting cookie or redirect with new token");
   const { token: newToken, redirectUrl } = callbackResult;
   if (config.session.basedToken) {
-    const separator = redirectUrl.includes("?") ? "&" : "?";
-    res.writeHead(302, { Location: `${redirectUrl}${separator}token=${newToken}` });
+    const hashIndex = redirectUrl.indexOf("#");
+    const baseUrl = hashIndex === -1 ? redirectUrl : redirectUrl.slice(0, hashIndex);
+    res.writeHead(302, { Location: `${baseUrl}#token=${newToken}` });
   } else {
     res.setHeader("Set-Cookie", `${sessionCookieName}=${newToken}; ${sessionCookieOptions}`);
     res.writeHead(302, { Location: redirectUrl });
@@ -417,13 +629,13 @@ import {
   captureException,
   dispatchHook as dispatchHook3,
   extractTokenFromRequest,
-  getLogger as getLogger3,
-  tryCatch as tryCatch3
+  getLogger as getLogger4,
+  tryCatch as tryCatch4
 } from "@luckystack/core";
 import { handleHttpApiRequest } from "@luckystack/api";
 
 // src/sse.ts
-import { getProjectConfig as getProjectConfig7 } from "@luckystack/core";
+import { getProjectConfig as getProjectConfig8 } from "@luckystack/core";
 var isExpectingEventStream = (acceptHeader) => {
   if (!acceptHeader) return false;
   const value = Array.isArray(acceptHeader) ? acceptHeader.join(",") : acceptHeader;
@@ -431,7 +643,7 @@ var isExpectingEventStream = (acceptHeader) => {
 };
 var queryRequestsStream = (queryString) => {
   if (!queryString) return false;
-  const { queryParam, enabledValue } = getProjectConfig7().http.stream;
+  const { queryParam, enabledValue } = getProjectConfig8().http.stream;
   const params = new URLSearchParams(queryString);
   const value = params.get(queryParam);
   return value === enabledValue || value === "1";
@@ -447,7 +659,7 @@ var initSseResponse = (res) => {
     Connection: "keep-alive",
     "X-Accel-Buffering": "no"
   });
-  const connectedComment = getProjectConfig7().http.stream.connectedComment;
+  const connectedComment = getProjectConfig8().http.stream.connectedComment;
   if (connectedComment) {
     res.write(`${connectedComment}
 
@@ -460,6 +672,8 @@ var sendSseEvent = ({
   data
 }) => {
   if (res.writableEnded) return;
+  const contentType = res.getHeader("Content-Type");
+  if (typeof contentType !== "string" || !contentType.includes("text/event-stream")) return;
   res.write(`event: ${event}
 `);
   res.write(`data: ${JSON.stringify(data)}
@@ -467,6 +681,15 @@ var sendSseEvent = ({
 `);
 };
 
+// src/httpRoutes/resolveRequesterIp.ts
+import { getProjectConfig as getProjectConfig9, resolveClientIp as resolveClientIp2 } from "@luckystack/core";
+var resolveRequesterIp = (req) => {
+  const trustProxy = getProjectConfig9().http.trustProxy;
+  const trustedProxyHopCount = getProjectConfig9().http.trustedProxyHopCount;
+  const rawRemoteAddress = req.socket.remoteAddress;
+  return rawRemoteAddress || trustProxy && (req.headers["x-forwarded-for"] || req.headers["x-real-ip"]) ? resolveClientIp2({ rawAddress: rawRemoteAddress, headers: req.headers, trustProxy, trustedProxyHopCount }) : void 0;
+};
+
 // src/httpRoutes/apiRoute.ts
 var handleApiRoute = async ({
   req,
@@ -482,11 +705,15 @@ var handleApiRoute = async ({
   let streamClosed = false;
   if (useHttpStream) {
     initSseResponse(res);
-    req.on("close", () => {
+    const markClosed = () => {
       streamClosed = true;
-    });
+    };
+    req.on("close", markClosed);
+    req.on("error", markClosed);
+    req.on("aborted", markClosed);
+    res.on("error", markClosed);
   }
-  const [error, handled] = await tryCatch3(async () => {
+  const [error, handled] = await tryCatch4(async () => {
     const httpToken = extractTokenFromRequest(req);
     const apiName = routePath.slice(5);
     if (!apiName) {
@@ -508,11 +735,12 @@ var handleApiRoute = async ({
     }
     const apiData = typeof params === "object" ? { ...params } : {};
     delete apiData.stream;
+    const requesterIp = resolveRequesterIp(req);
     const result = await handleHttpApiRequest({
       name: apiName,
       data: apiData,
       token: httpToken,
-      requesterIp: req.socket.remoteAddress ?? void 0,
+      requesterIp,
       xLanguageHeader: req.headers["x-language"],
       acceptLanguageHeader: req.headers["accept-language"],
       method,
@@ -534,7 +762,7 @@ var handleApiRoute = async ({
   if (!error) {
     return handled ?? true;
   }
-  getLogger3().error("http-api: top-level handler threw", error, { routePath, method, requestId });
+  getLogger4().error("http-api: top-level handler threw", error, { routePath, method, requestId });
   captureException(error, { routePath, method, requestId, source: "httpHandler.api" });
   void dispatchHook3("apiError", {
     route: routePath,
@@ -564,10 +792,9 @@ import {
   captureException as captureException2,
   dispatchHook as dispatchHook4,
   extractTokenFromRequest as extractTokenFromRequest2,
-  getLogger as getLogger4,
-  tryCatch as tryCatch4
+  getLogger as getLogger5,
+  tryCatch as tryCatch5
 } from "@luckystack/core";
-import { handleHttpSyncRequest } from "@luckystack/sync";
 var normalizeHttpSyncParams = (params) => {
   const source = params ?? {};
   const data = source.data && typeof source.data === "object" ? source.data : {};
@@ -588,15 +815,26 @@ var handleSyncRoute = async ({
   requestId
 }) => {
   if (!routePath.startsWith("/sync/")) return false;
+  const sync = capabilities.sync ? await getSync() : null;
+  if (!sync) {
+    res.setHeader("Content-Type", "application/json");
+    res.writeHead(404);
+    res.end(JSON.stringify({ status: "error", errorCode: "sync.disabled", message: "sync.disabled" }));
+    return true;
+  }
   const useHttpStream = shouldUseHttpStream({ acceptHeader: req.headers.accept, queryString });
   let streamClosed = false;
   if (useHttpStream) {
     initSseResponse(res);
-    req.on("close", () => {
+    const markClosed = () => {
       streamClosed = true;
-    });
+    };
+    req.on("close", markClosed);
+    req.on("error", markClosed);
+    req.on("aborted", markClosed);
+    res.on("error", markClosed);
   }
-  const [error, handled] = await tryCatch4(async () => {
+  const [error, handled] = await tryCatch5(async () => {
     if (method !== "POST") {
       const response = {
         status: "error",
@@ -632,14 +870,15 @@ var handleSyncRoute = async ({
       return true;
     }
     const syncParams = normalizeHttpSyncParams(params);
-    const result = await handleHttpSyncRequest({
+    const requesterIp = resolveRequesterIp(req);
+    const result = await sync.handleHttpSyncRequest({
       name: `sync/${syncName}`,
       cb: syncParams.cb,
       data: syncParams.data,
       receiver: syncParams.receiver,
       ignoreSelf: syncParams.ignoreSelf,
       token: httpToken,
-      requesterIp: req.socket.remoteAddress ?? void 0,
+      requesterIp,
       xLanguageHeader: req.headers["x-language"],
       acceptLanguageHeader: req.headers["accept-language"],
       stream: useHttpStream ? (payload) => {
@@ -660,7 +899,7 @@ var handleSyncRoute = async ({
   if (!error) {
     return handled ?? true;
   }
-  getLogger4().error("http-sync: top-level handler threw", error, { routePath, method, requestId });
+  getLogger5().error("http-sync: top-level handler threw", error, { routePath, method, requestId });
   captureException2(error, { routePath, method, requestId, source: "httpHandler.sync" });
   void dispatchHook4("syncError", {
     route: routePath,
@@ -685,7 +924,7 @@ var handleSyncRoute = async ({
 };
 
 // src/httpRoutes/customRoutes.ts
-import { captureException as captureException3, getLogger as getLogger5, tryCatch as tryCatch5 } from "@luckystack/core";
+import { captureException as captureException3, getLogger as getLogger6, tryCatch as tryCatch6 } from "@luckystack/core";
 
 // src/customRoutesRegistry.ts
 var handlers = [];
@@ -706,9 +945,9 @@ var clearCustomRoutes = () => {
 
 // src/httpRoutes/customRoutes.ts
 var runHandler = async (handler, req, res, ctx, source) => {
-  const [error, handled] = await tryCatch5(() => handler(req, res, ctx));
+  const [error, handled] = await tryCatch6(() => handler(req, res, ctx));
   if (error) {
-    getLogger5().error(`${source} threw`, error, { routePath: ctx.routePath, method: ctx.method });
+    getLogger6().error(`${source} threw`, error, { routePath: ctx.routePath, method: ctx.method });
     captureException3(error, { routePath: ctx.routePath, method: ctx.method, source });
     if (!res.writableEnded) {
       res.writeHead(500, { "Content-Type": "application/json" });
@@ -757,6 +996,7 @@ var handleCustomRoutes = async ({
 // src/httpRoutes/staticRoutes.ts
 import path from "path";
 var KNOWN_STATIC_FILE_REGEX = /^\/(assets\/[a-zA-Z0-9_/-]+|[a-zA-Z0-9_-]+)\.(png|jpg|jpeg|gif|svg|html|css|js)$/;
+var SERVE_DENYLIST_REGEX = /(^\/server\.js$)|(\.map$)/;
 var serveWithRewrittenUrl = async (serveFile, req, res, rewrittenUrl) => {
   const originalUrl = req.url;
   req.url = rewrittenUrl;
@@ -772,14 +1012,18 @@ var handleStaticAndSpaFallback = async ({
   routePath,
   options
 }) => {
-  if (routePath.includes("/assets/")) {
+  if (SERVE_DENYLIST_REGEX.test(routePath)) {
+    res.writeHead(404, { "Content-Type": "text/plain" });
+    res.end("Not Found");
+    return true;
+  }
+  if (routePath.startsWith("/assets/")) {
     if (!options.serveFile) {
       res.writeHead(404);
       res.end("Not Found");
       return true;
     }
-    const assetPath = routePath.slice(routePath.indexOf("/assets/"));
-    await serveWithRewrittenUrl(options.serveFile, req, res, assetPath);
+    await serveWithRewrittenUrl(options.serveFile, req, res, routePath);
     return true;
   }
   if (KNOWN_STATIC_FILE_REGEX.test(routePath)) {
@@ -805,21 +1049,10 @@ var handleStaticAndSpaFallback = async ({
   return true;
 };
 
-// src/originExemptRegistry.ts
-var exemptPaths = [];
-var registerOriginExemptPath = (matcher) => {
-  exemptPaths.push(matcher);
-};
-var getOriginExemptPaths = () => exemptPaths;
-var clearOriginExemptPaths = () => {
-  exemptPaths.length = 0;
-};
-var isOriginExemptPath = (routePath) => exemptPaths.some((matcher) => routePath.startsWith(matcher.pathPrefix));
-
 // src/httpHandler.ts
 var buildSessionCookieOptions = (sessionExpiryDays, secure, http2) => `HttpOnly; SameSite=${http2.sessionCookieSameSite}; Path=${http2.sessionCookiePath}; Max-Age=${60 * 60 * 24 * sessionExpiryDays}; ${secure ? "Secure;" : ""}`;
 var setSecurityHeaders = (req, res, origin) => {
-  const { cors, securityHeaders } = getProjectConfig8().http;
+  const { cors, securityHeaders } = getProjectConfig10().http;
   res.setHeader("Access-Control-Allow-Origin", origin);
   res.setHeader("Access-Control-Allow-Methods", cors.allowedMethods);
   res.setHeader("Access-Control-Allow-Headers", cors.allowedHeaders);
@@ -833,15 +1066,16 @@ var setSecurityHeaders = (req, res, origin) => {
   res.setHeader("X-Content-Type-Options", securityHeaders.contentTypeOptions);
   const builder = getSecurityHeadersBuilder();
   if (builder) {
-    try {
+    const [error] = tryCatchSync(() => {
       const custom = builder(req);
       if (custom) {
         for (const [name, value] of Object.entries(custom)) {
           res.setHeader(name, value);
         }
       }
-    } catch (error) {
-      getLogger6().warn("securityHeadersBuilder threw \u2014 falling back to defaults", { err: error });
+    });
+    if (error) {
+      getLogger7().warn("securityHeadersBuilder threw \u2014 falling back to defaults", { err: error });
     }
   }
 };
@@ -853,6 +1087,7 @@ var PRE_PARAMS_ROUTES = [
   handleHealthRoute,
   handleTestResetRoute,
   handleAuthProvidersRoute,
+  handleAuthLogoutRoute,
   handlePreParamsCustomRoutes
 ];
 var POST_PARAMS_ROUTES = [
@@ -901,7 +1136,7 @@ var refreshSessionCookieIfPresent = async ({
 }) => {
   const hasTokenCookie = hasCookie(req.headers.cookie, sessionCookieName);
   if (!hasTokenCookie || !token) return;
-  const currentSession = await getSession3(token);
+  const currentSession = await readSession3(token);
   if (currentSession?.id) {
     res.setHeader("Set-Cookie", `${sessionCookieName}=${token}; ${sessionCookieOptions}`);
   }
@@ -919,25 +1154,28 @@ var parseRequestParams = async ({
   if (res.writableEnded) return null;
   if (params && typeof params === "object" && Object.keys(params).length > 0) {
     if (shouldLogDev) {
-      getLogger6().debug(`[${requestId}] ${method} ${routePath}`, {
+      getLogger7().debug(`[${requestId}] ${method} ${routePath}`, {
         params: sanitizeForLog(params)
       });
     }
   } else {
     if (shouldLogDev) {
-      getLogger6().debug(`[${requestId}] ${method} ${routePath}`);
+      getLogger7().debug(`[${requestId}] ${method} ${routePath}`);
     }
     params = {};
   }
   return params;
 };
 var handleHttpRequest = async (req, res, options) => {
-  const config = getProjectConfig8();
+  const config = getProjectConfig10();
   const shouldLogDev = config.logging.devLogs;
   const sessionCookieName = config.http.sessionCookieName;
   const sessionCookieOptions = buildSessionCookieOptions(
     config.session.expiryDays,
-    process.env.SECURE === "true",
+    //? Honor the explicit `http.sessionCookieSecure` override (CORE-39), else the
+    //? `SECURE` env flag — shared with the OAuth state cookie via
+    //? `resolveCookieSecure` so the two can never drift (WAVE4).
+    resolveCookieSecure(config.http.sessionCookieSecure, process.env.SECURE),
     config.http
   );
   const url = req.url ?? "/";
@@ -1018,6 +1256,8 @@ import {
   allowedOrigin as allowedOrigin2,
   applySocketMiddlewares,
   attachSocketRedisAdapter,
+  formatRoomName,
+  redis as redis3,
   setIoInstance,
   socketEventNames,
   buildJoinRoomResponseEventName,
@@ -1025,27 +1265,21 @@ import {
   buildGetJoinedRoomsResponseEventName,
   extractLanguageFromHeader,
   extractTokenFromSocket,
-  getLogger as getLogger7,
-  getProjectConfig as getProjectConfig9,
+  getLogger as getLogger8,
+  getProjectConfig as getProjectConfig11,
   dispatchHook as dispatchHook6,
   normalizeErrorResponse,
-  tryCatch as tryCatch6
+  readSession as readSession4,
+  writeSession,
+  tryCatch as tryCatch7
 } from "@luckystack/core";
 import { handleApiRequest } from "@luckystack/api";
-import { handleSyncRequest } from "@luckystack/sync";
-import { getSession as getSession4, saveSession } from "@luckystack/login";
-import {
-  initActivityBroadcaster,
-  socketConnected,
-  socketDisconnecting,
-  socketLeaveRoom
-} from "@luckystack/presence";
 var sessionLocks = /* @__PURE__ */ new Map();
 var withSessionLock = async (token, fn) => {
   const prev = sessionLocks.get(token) ?? Promise.resolve();
   const next = prev.then(fn, fn);
   sessionLocks.set(token, next);
-  await tryCatch6(() => next);
+  await tryCatch7(() => next);
   if (sessionLocks.get(token) === next) sessionLocks.delete(token);
 };
 var getVisibleSocketRooms = (socket, token) => {
@@ -1061,15 +1295,290 @@ var sanitizeSessionRoomKeys = (session) => {
   const { code: _legacyCode, codes: _legacyCodes, ...sanitizedSession } = session;
   return sanitizedSession;
 };
+var validateRoomRequest = (socket, responseIndex, token, group, preferredLocale, buildResponseEventName) => {
+  if (typeof responseIndex !== "number") return false;
+  if (!token) {
+    socket.emit(buildResponseEventName(responseIndex), normalizeErrorResponse({
+      response: { status: "error", errorCode: "auth.required" },
+      preferredLocale
+    }));
+    return false;
+  }
+  if (!group) {
+    socket.emit(buildResponseEventName(responseIndex), normalizeErrorResponse({
+      response: { status: "error", errorCode: "room.invalid" },
+      preferredLocale
+    }));
+    return false;
+  }
+  return true;
+};
+var executeRoomMutation = async (opts) => {
+  const {
+    socket,
+    token,
+    group,
+    responseIndex,
+    preferredLocale,
+    shouldLogDev,
+    buildResponseEventName,
+    preHook,
+    postHook,
+    blockedErrorCode,
+    logVerb,
+    mutate
+  } = opts;
+  const session = await readSession4(token);
+  if (!session) {
+    socket.emit(buildResponseEventName(responseIndex), normalizeErrorResponse({
+      response: { status: "error", errorCode: "session.notFound" },
+      preferredLocale
+    }));
+    return;
+  }
+  const preResult = await dispatchHook6(preHook, { token, room: group });
+  if (preResult.stopped) {
+    socket.emit(buildResponseEventName(responseIndex), normalizeErrorResponse({
+      response: {
+        status: "error",
+        errorCode: preResult.signal.errorCode || blockedErrorCode
+      },
+      preferredLocale,
+      userLanguage: session.language
+    }));
+    return;
+  }
+  const existingRoomCodes = getSessionRoomCodes(session);
+  const roomPurpose = preHook === "preRoomJoin" ? "join" : "leave";
+  const physicalRoom = formatRoomName(group, { purpose: roomPurpose, userId: session.id });
+  const nextRoomCodes = await mutate(socket, physicalRoom, group, existingRoomCodes);
+  const sanitizedSession = sanitizeSessionRoomKeys(session);
+  await writeSession(token, { ...sanitizedSession, roomCodes: nextRoomCodes });
+  const visibleRooms = getVisibleSocketRooms(socket, token);
+  socket.emit(buildResponseEventName(responseIndex), { rooms: visibleRooms });
+  if (shouldLogDev) {
+    getLogger8().debug(`Socket ${socket.id} ${logVerb} group ${group}`);
+  }
+  void dispatchHook6(postHook, { token, room: group, allRooms: visibleRooms });
+};
+var registerApiAndSyncEvents = (ctx) => {
+  const { socket, token } = ctx;
+  socket.on(socketEventNames.apiRequest, (msg) => {
+    void handleApiRequest({ msg, socket, token });
+  });
+  if (capabilities.sync) {
+    socket.on(socketEventNames.sync, (msg) => {
+      void (async () => {
+        const sync = await getSync();
+        if (sync) await sync.handleSyncRequest({ msg, socket, token });
+      })();
+    });
+  }
+};
+var registerCancellationEvents = (ctx) => {
+  const { socket } = ctx;
+  socket.on(socketEventNames.syncCancel, (data) => {
+    const cb = typeof data.cb === "string" ? data.cb : null;
+    if (!cb) return;
+    abortSyncByCb(socket.id, cb);
+  });
+  socket.on(socketEventNames.apiCancel, (data) => {
+    const responseIndex = data.responseIndex;
+    if (typeof responseIndex !== "number" && typeof responseIndex !== "string") return;
+    abortApiByResponseIndex(socket.id, responseIndex);
+  });
+};
+var registerRoomEvents = (ctx) => {
+  const { socket, token, preferredLocale, shouldLogDev } = ctx;
+  socket.on(socketEventNames.joinRoom, (data) => {
+    const group = typeof data.group === "string" ? data.group.trim() : "";
+    const responseIndex = data.responseIndex;
+    if (!validateRoomRequest(socket, responseIndex, token, group, preferredLocale, buildJoinRoomResponseEventName)) return;
+    if (!token) return;
+    void withSessionLock(token, async () => {
+      await executeRoomMutation({
+        socket,
+        token,
+        group,
+        responseIndex,
+        preferredLocale,
+        shouldLogDev,
+        buildResponseEventName: buildJoinRoomResponseEventName,
+        preHook: "preRoomJoin",
+        postHook: "postRoomJoin",
+        blockedErrorCode: "room.joinBlocked",
+        logVerb: "joined",
+        mutate: async (sock, physicalRoom, rawGroup, existingCodes) => {
+          const nextCodes = [.../* @__PURE__ */ new Set([...existingCodes, rawGroup])];
+          await sock.join(physicalRoom);
+          return nextCodes;
+        }
+      });
+    });
+  });
+  socket.on(socketEventNames.leaveRoom, (data) => {
+    const group = typeof data.group === "string" ? data.group.trim() : "";
+    const responseIndex = data.responseIndex;
+    if (!validateRoomRequest(socket, responseIndex, token, group, preferredLocale, buildLeaveRoomResponseEventName)) return;
+    if (!token) return;
+    void withSessionLock(token, async () => {
+      await executeRoomMutation({
+        socket,
+        token,
+        group,
+        responseIndex,
+        preferredLocale,
+        shouldLogDev,
+        buildResponseEventName: buildLeaveRoomResponseEventName,
+        preHook: "preRoomLeave",
+        postHook: "postRoomLeave",
+        blockedErrorCode: "room.leaveBlocked",
+        logVerb: "left",
+        mutate: async (sock, physicalRoom, rawGroup, existingCodes) => {
+          const nextCodes = existingCodes.filter((c) => c !== rawGroup);
+          await sock.leave(physicalRoom);
+          return nextCodes;
+        }
+      });
+    });
+  });
+  socket.on(socketEventNames.getJoinedRooms, (data) => {
+    const responseIndex = data.responseIndex;
+    if (typeof responseIndex !== "number") return;
+    if (!token) {
+      socket.emit(buildGetJoinedRoomsResponseEventName(responseIndex), {
+        ...normalizeErrorResponse({
+          response: { status: "error", errorCode: "auth.required" },
+          preferredLocale
+        }),
+        rooms: []
+      });
+      return;
+    }
+    socket.emit(buildGetJoinedRoomsResponseEventName(responseIndex), {
+      rooms: getVisibleSocketRooms(socket, token)
+    });
+  });
+};
+var registerDisconnectEvent = (ctx) => {
+  const { socket, token, activityBroadcasterEnabled, shouldLogDev } = ctx;
+  socket.on(socketEventNames.disconnect, (reason) => {
+    abortAllForSocket(socket.id);
+    void dispatchHook6("onSocketDisconnect", { socketId: socket.id, token, reason });
+    if (activityBroadcasterEnabled) {
+      void getPresence().then((presence) => {
+        presence?.clearActivity(socket.id);
+      });
+    }
+    if (activityBroadcasterEnabled && token) {
+      void (async () => {
+        const presence = await getPresence();
+        if (presence) presence.socketDisconnecting({ token, socket, reason });
+      })();
+    } else {
+      if (!token) return;
+      if (shouldLogDev) {
+        getLogger8().debug(`user disconnected`, { reason });
+      }
+    }
+  });
+};
+var registerUpdateLocationEvent = (ctx) => {
+  const { socket, token, activityBroadcasterEnabled, locationProviderEnabled, shouldLogDev } = ctx;
+  socket.on(
+    socketEventNames.updateLocation,
+    (newLocation) => {
+      if (!token) return;
+      if (!locationProviderEnabled) return;
+      if (shouldLogDev) {
+        getLogger8().debug("updating location", { pathName: newLocation.pathName });
+      }
+      void withSessionLock(token, async () => {
+        let returnedUser = null;
+        if (activityBroadcasterEnabled) {
+          const presence = await getPresence();
+          if (presence) {
+            returnedUser = await presence.socketLeaveRoom({ token, socket, newPath: newLocation.pathName });
+          }
+        }
+        const user = returnedUser ?? await readSession4(token);
+        if (!user) return;
+        const extendedUser = user;
+        const oldLocation = extendedUser.location;
+        const sanitizedUser = sanitizeSessionRoomKeys({ ...extendedUser, location: newLocation });
+        await writeSession(token, sanitizedUser);
+        void dispatchHook6("onLocationUpdate", { token, oldLocation, newLocation });
+      });
+    }
+  );
+};
+var registerActivityEvents = (ctx) => {
+  const { socket, token, activityBroadcasterEnabled, io } = ctx;
+  if (activityBroadcasterEnabled && token) {
+    void (async () => {
+      const presence = await getPresence();
+      if (presence) presence.initActivityBroadcaster({ socket, token });
+    })();
+  }
+  if (activityBroadcasterEnabled) {
+    void (async () => {
+      const presence = await getPresence();
+      if (!presence) return;
+      presence.startActivitySampler({ io });
+      presence.recordActivity(socket.id);
+    })();
+    socket.on(socketEventNames.activity, () => {
+      void getPresence().then((presence) => {
+        presence?.recordActivity(socket.id);
+      });
+    });
+    socket.on(socketEventNames.intentionalReconnect, () => {
+      void getPresence().then((presence) => {
+        presence?.recordActivity(socket.id);
+      });
+    });
+  }
+};
+var rejoinPersistedRooms = (ctx) => {
+  const { socket, token, shouldLogDev } = ctx;
+  if (!token) return;
+  void (async () => {
+    const [rejoinError, codes] = await tryCatch7(async () => {
+      await socket.join(token);
+      const session = await readSession4(token);
+      const roomCodes = session ? getSessionRoomCodes(session) : [];
+      const userId = session?.id ?? null;
+      for (const roomCode of roomCodes) {
+        await socket.join(formatRoomName(roomCode, { purpose: "join", userId }));
+      }
+      return roomCodes;
+    });
+    if (rejoinError) {
+      getLogger8().warn(`socket room rejoin failed for ${socket.id}`, { error: rejoinError.message });
+      return;
+    }
+    if (shouldLogDev) {
+      getLogger8().debug(`socket ${socket.id} (re)joined rooms: ${(codes ?? []).join(", ") || "(none)"}`);
+    }
+  })();
+};
 var loadSocket = (httpServer, options = {}) => {
-  const config = getProjectConfig9();
+  const config = getProjectConfig11();
   const shouldLogDev = config.logging.devLogs;
   const shouldLogSocketStartup = config.logging.socketStartup;
   const io = new SocketIOServer(httpServer, {
     cors: {
       methods: ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
       origin: (origin, callback) => {
-        if (!origin || allowedOrigin2(origin)) {
+        if (!origin) {
+          if (config.http.cors.allowOriginless) {
+            callback(null, true);
+          } else {
+            callback(new Error("Origin-less WebSocket upgrades are not allowed"));
+          }
+          return;
+        }
+        if (allowedOrigin2(origin)) {
           callback(null, true);
         } else {
           callback(new Error("Not allowed by CORS"));
@@ -1083,225 +1592,53 @@ var loadSocket = (httpServer, options = {}) => {
   });
   setIoInstance(io);
   applySocketMiddlewares(io);
-  attachSocketRedisAdapter(io);
+  const pubClient = redis3.duplicate();
+  const subClient = redis3.duplicate();
+  attachSocketRedisAdapter(io, { pubClient, subClient });
   if (shouldLogSocketStartup) {
-    getLogger7().info("SocketIO server initialized (redis adapter attached)");
+    getLogger8().info("SocketIO server initialized (redis adapter attached)");
   }
   io.on(socketEventNames.connect, (socket) => {
     const token = extractTokenFromSocket(socket);
     const activityBroadcasterEnabled = config.socketActivityBroadcaster ?? false;
     const locationProviderEnabled = config.locationProviderEnabled ?? false;
     const preferredLocale = extractLanguageFromHeader(socket.handshake.headers["x-language"]) || extractLanguageFromHeader(socket.handshake.headers["accept-language"]) || void 0;
-    if (token) {
-      void socketConnected({ token, io });
+    if (token && capabilities.presence) {
+      void (async () => {
+        const presence = await getPresence();
+        if (presence) await presence.socketConnected({ token, io });
+      })();
     }
     void dispatchHook6("onSocketConnect", {
       socketId: socket.id,
       token,
       ip: socket.handshake.address
     });
-    socket.on(socketEventNames.apiRequest, (msg) => {
-      void handleApiRequest({ msg, socket, token });
-    });
-    socket.on(socketEventNames.sync, (msg) => {
-      void handleSyncRequest({ msg, socket, token });
-    });
-    socket.on(socketEventNames.syncCancel, (data) => {
-      const cb = typeof data.cb === "string" ? data.cb : null;
-      if (!cb) return;
-      abortSyncByCb(socket.id, cb);
-    });
-    socket.on(socketEventNames.apiCancel, (data) => {
-      const responseIndex = data.responseIndex;
-      if (typeof responseIndex !== "number" && typeof responseIndex !== "string") return;
-      abortApiByResponseIndex(socket.id, responseIndex);
-    });
-    socket.on(socketEventNames.joinRoom, (data) => {
-      const group = typeof data.group === "string" ? data.group.trim() : "";
-      const responseIndex = data.responseIndex;
-      if (typeof responseIndex !== "number") return;
-      if (!token) {
-        socket.emit(buildJoinRoomResponseEventName(responseIndex), normalizeErrorResponse({
-          response: { status: "error", errorCode: "auth.required" },
-          preferredLocale
-        }));
-        return;
-      }
-      if (!group) {
-        socket.emit(buildJoinRoomResponseEventName(responseIndex), normalizeErrorResponse({
-          response: { status: "error", errorCode: "room.invalid" },
-          preferredLocale
-        }));
-        return;
-      }
-      void withSessionLock(token, async () => {
-        const session = await getSession4(token);
-        if (!session) {
-          socket.emit(buildJoinRoomResponseEventName(responseIndex), normalizeErrorResponse({
-            response: { status: "error", errorCode: "session.notFound" },
-            preferredLocale
-          }));
-          return;
-        }
-        const preResult = await dispatchHook6("preRoomJoin", { token, room: group });
-        if (preResult.stopped) {
-          socket.emit(buildJoinRoomResponseEventName(responseIndex), normalizeErrorResponse({
-            response: {
-              status: "error",
-              errorCode: preResult.signal.errorCode || "room.joinBlocked"
-            },
-            preferredLocale,
-            userLanguage: session.language
-          }));
-          return;
-        }
-        const existingRoomCodes = getSessionRoomCodes(session);
-        const nextRoomCodes = [.../* @__PURE__ */ new Set([...existingRoomCodes, group])];
-        await socket.join(group);
-        const sanitizedSession = sanitizeSessionRoomKeys(session);
-        await saveSession(token, { ...sanitizedSession, roomCodes: nextRoomCodes });
-        const visibleRooms = getVisibleSocketRooms(socket, token);
-        socket.emit(buildJoinRoomResponseEventName(responseIndex), { rooms: visibleRooms });
-        if (shouldLogDev) {
-          getLogger7().debug(`Socket ${socket.id} joined group ${group}`);
-        }
-        void dispatchHook6("postRoomJoin", { token, room: group, allRooms: visibleRooms });
-      });
-    });
-    socket.on(socketEventNames.leaveRoom, (data) => {
-      const group = typeof data.group === "string" ? data.group.trim() : "";
-      const responseIndex = data.responseIndex;
-      if (typeof responseIndex !== "number") return;
-      if (!token) {
-        socket.emit(buildLeaveRoomResponseEventName(responseIndex), normalizeErrorResponse({
-          response: { status: "error", errorCode: "auth.required" },
-          preferredLocale
-        }));
-        return;
-      }
-      if (!group) {
-        socket.emit(buildLeaveRoomResponseEventName(responseIndex), normalizeErrorResponse({
-          response: { status: "error", errorCode: "room.invalid" },
-          preferredLocale
-        }));
-        return;
-      }
-      void withSessionLock(token, async () => {
-        const session = await getSession4(token);
-        if (!session) {
-          socket.emit(buildLeaveRoomResponseEventName(responseIndex), normalizeErrorResponse({
-            response: { status: "error", errorCode: "session.notFound" },
-            preferredLocale
-          }));
-          return;
-        }
-        const preResult = await dispatchHook6("preRoomLeave", { token, room: group });
-        if (preResult.stopped) {
-          socket.emit(buildLeaveRoomResponseEventName(responseIndex), normalizeErrorResponse({
-            response: {
-              status: "error",
-              errorCode: preResult.signal.errorCode || "room.leaveBlocked"
-            },
-            preferredLocale,
-            userLanguage: session.language
-          }));
-          return;
-        }
-        const existingRoomCodes = getSessionRoomCodes(session);
-        const nextRoomCodes = existingRoomCodes.filter((roomCode) => roomCode !== group);
-        await socket.leave(group);
-        const sanitizedSession = sanitizeSessionRoomKeys(session);
-        await saveSession(token, { ...sanitizedSession, roomCodes: nextRoomCodes });
-        const visibleRooms = getVisibleSocketRooms(socket, token);
-        socket.emit(buildLeaveRoomResponseEventName(responseIndex), { rooms: visibleRooms });
-        if (shouldLogDev) {
-          getLogger7().debug(`Socket ${socket.id} left group ${group}`);
-        }
-        void dispatchHook6("postRoomLeave", { token, room: group, allRooms: visibleRooms });
-      });
-    });
-    socket.on(socketEventNames.getJoinedRooms, (data) => {
-      const responseIndex = data.responseIndex;
-      if (typeof responseIndex !== "number") return;
-      if (!token) {
-        socket.emit(buildGetJoinedRoomsResponseEventName(responseIndex), {
-          ...normalizeErrorResponse({
-            response: { status: "error", errorCode: "auth.required" },
-            preferredLocale
-          }),
-          rooms: []
-        });
-        return;
-      }
-      socket.emit(buildGetJoinedRoomsResponseEventName(responseIndex), {
-        rooms: getVisibleSocketRooms(socket, token)
-      });
-    });
-    socket.on(socketEventNames.disconnect, (reason) => {
-      abortAllForSocket(socket.id);
-      void dispatchHook6("onSocketDisconnect", { socketId: socket.id, token, reason });
-      if (activityBroadcasterEnabled && token) {
-        void socketDisconnecting({ token, socket, reason });
-      } else {
-        if (!token) return;
-        if (shouldLogDev) {
-          getLogger7().debug(`user disconnected`, { reason });
-        }
-      }
-    });
-    socket.on(
-      socketEventNames.updateLocation,
-      (newLocation) => {
-        if (!token) return;
-        if (!locationProviderEnabled) return;
-        if (shouldLogDev) {
-          getLogger7().debug("updating location", { pathName: newLocation.pathName });
-        }
-        void withSessionLock(token, async () => {
-          let returnedUser = null;
-          if (activityBroadcasterEnabled) {
-            returnedUser = await socketLeaveRoom({ token, socket, newPath: newLocation.pathName });
-          }
-          const user = returnedUser ?? await getSession4(token);
-          if (!user) return;
-          const extendedUser = user;
-          const oldLocation = extendedUser.location;
-          extendedUser.location = newLocation;
-          await saveSession(token, user);
-          void dispatchHook6("onLocationUpdate", { token, oldLocation, newLocation });
-        });
-      }
-    );
-    if (activityBroadcasterEnabled && token) {
-      initActivityBroadcaster({ socket, token });
-    }
-    if (token) {
-      void (async () => {
-        const [rejoinError, codes] = await tryCatch6(async () => {
-          await socket.join(token);
-          const session = await getSession4(token);
-          const roomCodes = session ? getSessionRoomCodes(session) : [];
-          for (const roomCode of roomCodes) {
-            await socket.join(roomCode);
-          }
-          return roomCodes;
-        });
-        if (rejoinError) {
-          getLogger7().warn(`socket room rejoin failed for ${socket.id}`, { error: rejoinError.message });
-          return;
-        }
-        if (shouldLogDev) {
-          getLogger7().debug(`socket ${socket.id} (re)joined rooms: ${(codes ?? []).join(", ") || "(none)"}`);
-        }
-      })();
-    }
+    const ctx = {
+      socket,
+      token,
+      preferredLocale,
+      activityBroadcasterEnabled,
+      locationProviderEnabled,
+      shouldLogDev,
+      io
+    };
+    registerApiAndSyncEvents(ctx);
+    registerCancellationEvents(ctx);
+    registerRoomEvents(ctx);
+    registerDisconnectEvent(ctx);
+    registerUpdateLocationEvent(ctx);
+    registerActivityEvents(ctx);
+    rejoinPersistedRooms(ctx);
   });
-  return io;
+  return { io, adapterClients: { pubClient, subClient } };
 };
 
 // src/verifyBootstrap.ts
 import {
-  getLogger as getLogger8,
+  collectSynchronizedEnvKeys,
+  getLogger as getLogger9,
+  getProjectConfig as getProjectConfig12,
   isDeployConfigRegistered,
   isLocalizedNormalizerRegistered,
   isProjectConfigRegistered,
@@ -1328,8 +1665,12 @@ var verifyBootstrap = async (requirements = {}) => {
     }
   }
   if (requirements.requireOAuthProviders) {
-    const { getOAuthProviders: getOAuthProviders3 } = await import("@luckystack/login");
-    if (getOAuthProviders3().length <= 1) {
+    const login = await getLogin();
+    if (!login) {
+      missing.push(
+        "OAuth providers required (`requireOAuthProviders`) but `@luckystack/login` is not installed. Install it, or drop the requirement if this app has no auth."
+      );
+    } else if (login.getOAuthProviders().length <= 1) {
       missing.push(
         "OAuth providers \u2014 call `registerOAuthProviders([...])` from `luckystack/login/oauthProviders.ts` (or skip this check if your app uses credentials only)."
       );
@@ -1341,7 +1682,7 @@ var verifyBootstrap = async (requirements = {}) => {
         "RuntimeMapsProvider \u2014 call `registerRuntimeMapsProvider({...})` from `server/prod/runtimeMaps.ts`. Without it, every api/sync request returns notFound."
       );
     } else {
-      getLogger8().warn(
+      getLogger9().warn(
         "[LuckyStack] No RuntimeMapsProvider registered \u2014 api/sync requests will resolve to empty maps. Devkit hot-reload usually registers one automatically."
       );
     }
@@ -1352,11 +1693,20 @@ var verifyBootstrap = async (requirements = {}) => {
         "LocalizedNormalizer \u2014 call `registerLocalizedNormalizer({...})` from your bootstrap. Without it, error response messages will be the raw errorCode (no i18n)."
       );
     } else {
-      getLogger8().warn(
+      getLogger9().warn(
         "[LuckyStack] No LocalizedNormalizer registered \u2014 error messages will pass through as the raw errorCode."
       );
     }
   }
+  if (isProjectConfigRegistered()) {
+    const synchronizedKeyCount = collectSynchronizedEnvKeys().length;
+    const healthHashMode = getProjectConfig12().http.healthHash.mode;
+    if (synchronizedKeyCount > 0 && healthHashMode === "plain") {
+      getLogger9().warn(
+        `[LuckyStack] SECURITY: /_health exposes UNSALTED sha256 fingerprints of ${String(synchronizedKeyCount)} synchronized env secret(s) by default. Set \`http.healthHash.mode\` to 'hmac' (or 'salted' with salt '@bootUuid') to stop publishing brute-forceable secret fingerprints to unauthenticated callers.`
+      );
+    }
+  }
   if (missing.length === 0) return;
   const detail = missing.map((line, idx) => `  ${idx + 1}. ${line}`).join("\n");
   throw new Error(
@@ -1371,58 +1721,25 @@ var verifyBootstrap = async (requirements = {}) => {
 
 // src/runtimeMapsLoader.ts
 import {
+  getLogger as getLogger10,
   registerRuntimeMapsProvider
 } from "@luckystack/core";
-
-// src/argv.ts
-var parsedBundles = [];
-var parsedPort = null;
-var hasRun = false;
-var PORT_PATTERN = /^\d+$/;
-var parseServerArgv = (argv) => {
-  if (argv.length > 2) {
-    throw new Error(
-      `[luckystack:argv] unexpected positional argument(s): "${argv.slice(2).join(" ")}". Usage: npm run server -- <bundle[,bundle...]> [port]`
-    );
-  }
-  const bundles = argv[0] && argv[0].length > 0 ? [...new Set(argv[0].split(",").map((s) => s.trim()).filter(Boolean))] : [];
-  let port = null;
-  const portArg = argv[1];
-  if (portArg !== void 0) {
-    if (!PORT_PATTERN.test(portArg)) {
-      throw new Error(
-        `[luckystack:argv] port argument must be numeric, got: "${portArg}". Usage: npm run server -- <bundle[,bundle...]> [port]`
-      );
-    }
-    port = Number.parseInt(portArg, 10);
-  }
-  return { bundles, port };
-};
-var applyServerArgv = () => {
-  if (hasRun) return;
-  hasRun = true;
-  const result = parseServerArgv(process.argv.slice(2));
-  parsedBundles = result.bundles;
-  parsedPort = result.port;
-  if (parsedPort !== null) {
-    process.env.SERVER_PORT = String(parsedPort);
-  }
-};
-var getParsedBundles = () => parsedBundles;
-var getParsedPort = () => parsedPort;
-
-// src/runtimeMapsLoader.ts
 var emptyRuntimeMaps = {
   apisObject: {},
   syncObject: {},
   functionsObject: {}
 };
 var isRuntimeMapRecord = (value) => Boolean(value) && typeof value === "object";
-var normalizeGeneratedModule = (moduleValue) => {
+var normalizeGeneratedModule = (moduleValue, preset) => {
   const moduleRecord = moduleValue && typeof moduleValue === "object" ? moduleValue : {};
   const apiCandidate = moduleRecord.apis;
   const syncCandidate = moduleRecord.syncs;
   const functionCandidate = moduleRecord.functions;
+  if (!isRuntimeMapRecord(apiCandidate) && !isRuntimeMapRecord(syncCandidate) && !isRuntimeMapRecord(functionCandidate)) {
+    getLogger10().warn(
+      `[luckystack:runtimeMaps] preset "${preset}" loaded but has no recognised shape (expected { apis, syncs, functions }). Verify that generateServerRequests has been run and the correct file is imported. All routes for this preset will return notFound.`
+    );
+  }
   return {
     apisObject: isRuntimeMapRecord(apiCandidate) ? apiCandidate : {},
     syncObject: isRuntimeMapRecord(syncCandidate) ? syncCandidate : {},
@@ -1484,19 +1801,19 @@ var createProdRuntimeMapsProvider = (options) => {
       let loadedAny = false;
       for (const { preset, mod } of loadedModules) {
         if (!mod) {
-          console.warn(
+          getLogger10().warn(
             `[luckystack:runtimeMaps] preset "${preset}" failed to load \u2014 skipping. Calls owned by that preset will return notFound until the generated module resolves.`
           );
           continue;
         }
         loadedAny = true;
-        const normalized = normalizeGeneratedModule(mod);
+        const normalized = normalizeGeneratedModule(mod, preset);
         mergeInto(merged.apisObject, normalized.apisObject, "api", preset, apiOrigin);
         mergeInto(merged.syncObject, normalized.syncObject, "sync", preset, syncOrigin);
         mergeInto(merged.functionsObject, normalized.functionsObject, "function", preset, functionOrigin);
       }
       if (!loadedAny) {
-        console.warn(
+        getLogger10().warn(
           `[luckystack:runtimeMaps] no presets resolved (tried: ${presets.join(", ")}). Every api/sync request will return notFound until at least one generated module loads.`
         );
         return emptyRuntimeMaps;
@@ -1535,7 +1852,113 @@ var registerProdRuntimeMapsProvider = (options) => {
   return provider;
 };
 
+// src/stopServer.ts
+import {
+  dispatchHook as dispatchHook7,
+  flushErrorTrackers,
+  getLogger as getLogger11,
+  tryCatch as tryCatch8
+} from "@luckystack/core";
+var DEFAULT_SHUTDOWN_TIMEOUT_MS = 1e4;
+var withTimeout = async (label, timeoutMs, fn) => {
+  let timer;
+  const timeout = new Promise((resolve) => {
+    timer = setTimeout(() => {
+      getLogger11().warn(`[shutdown] step "${label}" exceeded ${String(timeoutMs)}ms \u2014 moving on`);
+      resolve(false);
+    }, timeoutMs);
+    timer.unref();
+  });
+  const run = (async () => {
+    const [error] = await tryCatch8(fn);
+    if (error) getLogger11().warn(`[shutdown] step "${label}" failed: ${error.message}`);
+    return true;
+  })();
+  const completed = await Promise.race([run, timeout]);
+  if (timer) clearTimeout(timer);
+  return completed;
+};
+var closeHttpServer = (httpServer) => new Promise((resolve, reject) => {
+  httpServer.close((error) => {
+    if (error) reject(error);
+    else resolve();
+  });
+});
+var closeIoServer = (ioServer) => new Promise((resolve, reject) => {
+  void ioServer.close((error) => {
+    if (error) reject(error);
+    else resolve();
+  });
+});
+var quitRedisClient = async (client) => {
+  await client.quit();
+};
+var runGracefulShutdown = async (deps, options = {}) => {
+  const { httpServer, ioServer, adapterClients } = deps;
+  const reason = options.reason ?? "manual";
+  const timeoutMs = options.timeoutMs ?? DEFAULT_SHUTDOWN_TIMEOUT_MS;
+  getLogger11().info(`[shutdown] graceful shutdown started (reason=${reason})`);
+  const httpClosed = withTimeout("http-close", timeoutMs, () => closeHttpServer(httpServer));
+  await withTimeout("preServerStop-hook", timeoutMs, async () => {
+    await dispatchHook7("preServerStop", { reason, timeoutMs });
+  });
+  await withTimeout("flush-error-trackers", timeoutMs, () => flushErrorTrackers());
+  await withTimeout("io-close", timeoutMs, () => closeIoServer(ioServer));
+  await httpClosed;
+  await withTimeout("redis-pub-quit", timeoutMs, () => quitRedisClient(adapterClients.pubClient));
+  await withTimeout("redis-sub-quit", timeoutMs, () => quitRedisClient(adapterClients.subClient));
+  getLogger11().info("[shutdown] graceful shutdown complete");
+};
+
 // src/createServer.ts
+var initDevTools = async () => {
+  const { initConsolelog } = await import("@luckystack/core");
+  initConsolelog();
+  const devkitModuleId = "@luckystack/devkit";
+  const devkit = await import(devkitModuleId);
+  await devkit.initializeAll();
+  devkit.setupWatchers();
+  process.once("SIGINT", () => process.exit(0));
+  process.once("SIGTERM", () => process.exit(0));
+};
+var listenLuckyStackServer = (httpServer, ip, port, callback) => new Promise((resolve, reject) => {
+  const startPort = typeof port === "string" ? Number.parseInt(port, 10) : port;
+  const autoIncrementEnv = (process.env.SERVER_PORT_AUTO_INCREMENT ?? "").toLowerCase();
+  let autoIncrement;
+  if (["0", "false"].includes(autoIncrementEnv)) autoIncrement = false;
+  else if (["1", "true"].includes(autoIncrementEnv)) autoIncrement = true;
+  else autoIncrement = !isProduction2;
+  const tryListen = (attemptPort) => {
+    const onError = (err) => {
+      if (err.code !== "EADDRINUSE") {
+        reject(err);
+        return;
+      }
+      if (autoIncrement) {
+        getLogger12().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(
+        `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);
+    };
+    httpServer.once("error", onError);
+    httpServer.listen(attemptPort, ip, () => {
+      httpServer.off("error", onError);
+      const config = getProjectConfig13();
+      if (config.logging.socketStartup || config.logging.devLogs) {
+        getLogger12().info(`Server is running on http://${ip}:${String(attemptPort)}/`);
+      }
+      callback?.();
+      resolve(httpServer);
+    });
+  };
+  tryListen(startPort);
+});
 var createLuckyStackServer = async (options = {}) => {
   if (options.loadGeneratedMaps) {
     registerProdRuntimeMapsProvider({
@@ -1556,16 +1979,9 @@ var createLuckyStackServer = async (options = {}) => {
     port: typeof port === "string" ? Number.parseInt(port, 10) : port
   });
   if (enableDevTools) {
-    const { initConsolelog } = await import("@luckystack/core");
-    initConsolelog();
-    const devkitModuleId = "@luckystack/devkit";
-    const devkit = await import(devkitModuleId);
-    await devkit.initializeAll();
-    devkit.setupWatchers();
-    process.once("SIGINT", () => process.exit(0));
-    process.once("SIGTERM", () => process.exit(0));
-  }
-  const [bootUuidError] = await tryCatch7(() => writeBootUuid());
+    await initDevTools();
+  }
+  const [bootUuidError] = await tryCatch9(() => 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.",
@@ -1575,46 +1991,34 @@ var createLuckyStackServer = async (options = {}) => {
   const httpServer = http.createServer((req, res) => {
     void handleHttpRequest(req, res, options);
   });
-  const ioServer = loadSocket(httpServer, {
+  httpServer.on("error", (err) => {
+    if (err.code === "EADDRINUSE") return;
+    getLogger12().error("[http-server] runtime error", err);
+  });
+  const { io: ioServer, adapterClients } = loadSocket(httpServer, {
     maxHttpBufferSize: options.maxHttpBufferSize
   });
-  const listen = (callback) => new Promise((resolve, reject) => {
-    const startPort = typeof port === "string" ? Number.parseInt(port, 10) : port;
-    const autoIncrement = ["1", "true"].includes(
-      (process.env.SERVER_PORT_AUTO_INCREMENT ?? "").toLowerCase()
-    );
-    const tryListen = (attemptPort) => {
-      const onError = (err) => {
-        if (err.code !== "EADDRINUSE") {
-          reject(err);
-          return;
-        }
-        if (autoIncrement) {
-          getLogger9().warn(
-            `Port ${String(attemptPort)} is in use \u2014 trying ${String(attemptPort + 1)} (SERVER_PORT_AUTO_INCREMENT=1)`
-          );
-          tryListen(attemptPort + 1);
-          return;
-        }
-        getLogger9().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);
-      };
-      httpServer.once("error", onError);
-      httpServer.listen(attemptPort, ip, () => {
-        httpServer.off("error", onError);
-        const config = getProjectConfig10();
-        if (config.logging.socketStartup || config.logging.devLogs) {
-          getLogger9().info(`Server is running on http://${ip}:${String(attemptPort)}/`);
-        }
-        callback?.();
-        resolve(httpServer);
-      });
+  const listen = (callback) => listenLuckyStackServer(httpServer, ip, port, callback);
+  let shutdownPromise = null;
+  const stop = (stopOptions = {}) => {
+    shutdownPromise ??= runGracefulShutdown({ httpServer, ioServer, adapterClients }, stopOptions);
+    return shutdownPromise;
+  };
+  if (!enableDevTools) {
+    const handleSignal = (reason) => {
+      void (async () => {
+        await stop({ reason });
+        process.exit(0);
+      })();
     };
-    tryListen(startPort);
-  });
-  return { httpServer, ioServer, listen };
+    process.once("SIGTERM", () => {
+      handleSignal("SIGTERM");
+    });
+    process.once("SIGINT", () => {
+      handleSignal("SIGINT");
+    });
+  }
+  return { httpServer, ioServer, listen, stop, close: stop };
 };
 
 // src/bootstrap.ts
@@ -1665,11 +2069,26 @@ var loadOverlayFolder = async (overlayRoot) => {
     }
   }
 };
+var importOptionalPackageRegisters = async () => {
+  for (const pkg of OPTIONAL_PACKAGES) {
+    const specifier = `@luckystack/${pkg}/register`;
+    if (!canResolve(specifier)) continue;
+    await importIfExistsSpecifier(specifier);
+  }
+};
+var importIfExistsSpecifier = async (specifier) => {
+  try {
+    await import(specifier);
+  } catch {
+  }
+};
 var bootstrapLuckyStack = async (options = {}) => {
   const overlayRoot = options.overlayRoot ?? "luckystack";
   if (!options.skipOverlayLoad) {
+    await importOptionalPackageRegisters();
     await loadOverlayFolder(overlayRoot);
   }
+  await getLogin();
   const server = await createLuckyStackServer(options);
   return server;
 };