@luckystack/server 0.1.0

package/dist/index.js

@@ -0,0 +1,1665 @@
+// src/createServer.ts
+import http from "http";
+import { registerBindAddress, writeBootUuid, getLogger as getLogger9, getProjectConfig as getProjectConfig10, tryCatch as tryCatch7 } from "@luckystack/core";
+
+// src/httpHandler.ts
+import { randomUUID } from "crypto";
+import {
+  allowedOrigin,
+  dispatchHook as dispatchHook5,
+  extractTokenFromRequest as extractTokenFromRequest3,
+  getLogger as getLogger6,
+  getParams,
+  getProjectConfig as getProjectConfig8,
+  hasCookie
+} from "@luckystack/core";
+import { getSession as getSession3 } from "@luckystack/login";
+
+// src/logSanitize.ts
+import { getProjectConfig, isRedactedLogKey } from "@luckystack/core";
+var REDACTED_PLACEHOLDER = "[REDACTED]";
+var isRedactedKey = (key) => {
+  if (isRedactedLogKey(key)) return true;
+  return key.toLowerCase() === getProjectConfig().http.sessionCookieName.toLowerCase();
+};
+var sanitizeForLog = (value) => {
+  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);
+  }
+  return out;
+};
+
+// src/securityHeadersRegistry.ts
+var registeredBuilder = null;
+var registerSecurityHeaders = (builder) => {
+  registeredBuilder = builder;
+};
+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,
+  routePath,
+  token,
+  requestId
+}) => {
+  const config = getProjectConfig2();
+  const isCookieMode = !config.session.basedToken;
+  const isStateChanging = req.method !== "GET" && req.method !== "OPTIONS";
+  const isCallbackPath = routePath.startsWith("/auth/callback");
+  const looksLikeFrameworkRoute = routePath.startsWith("/api/") || routePath.startsWith("/sync/") || routePath.startsWith("/auth/api/");
+  if (!(isCookieMode && isStateChanging && looksLikeFrameworkRoute && !isCallbackPath && token)) {
+    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;
+  void dispatchHook("csrfMismatch", {
+    route: routePath,
+    method: req.method,
+    requestId,
+    userId: csrfSession.id,
+    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;
+};
+
+// src/httpRoutes/csrfRoute.ts
+import { getSession as getSession2 } from "@luckystack/login";
+var handleCsrfRoute = async ({ res, routePath, token }) => {
+  if (routePath !== "/auth/csrf") return false;
+  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);
+  if (!csrfSession?.id) {
+    res.statusCode = 401;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify({ status: "error", errorCode: "auth.unauthenticated" }));
+    return true;
+  }
+  res.statusCode = 200;
+  res.setHeader("Content-Type", "application/json");
+  res.end(JSON.stringify({
+    status: "success",
+    csrfToken: csrfSession.csrfToken ?? null
+  }));
+  return true;
+};
+
+// src/httpRoutes/faviconRoute.ts
+var handleFaviconRoute = async ({ res, routePath, options }) => {
+  if (routePath !== "/favicon.ico") return false;
+  if (options.serveFavicon) {
+    await options.serveFavicon(res);
+    return true;
+  }
+  res.writeHead(404);
+  res.end();
+  return true;
+};
+
+// src/httpRoutes/healthRoutes.ts
+import {
+  computeSynchronizedEnvHashes,
+  getProjectConfig as getProjectConfig3,
+  prisma,
+  readBootUuid,
+  redis,
+  resolveEnvKey,
+  tryCatch
+} from "@luckystack/core";
+var pingPrisma = async () => {
+  const client = prisma;
+  const queryRaw = client.$queryRaw;
+  if (typeof queryRaw === "function") {
+    const [sqlError] = await tryCatch(() => queryRaw`SELECT 1`);
+    if (!sqlError) return true;
+  }
+  const runCommandRaw = client.$runCommandRaw;
+  if (typeof runCommandRaw === "function") {
+    const [mongoError] = await tryCatch(() => runCommandRaw({ ping: 1 }));
+    return !mongoError;
+  }
+  return false;
+};
+var handleLivezRoute = ({ res, routePath }) => {
+  if (routePath !== getProjectConfig3().http.liveEndpoint) return Promise.resolve(false);
+  res.statusCode = 200;
+  res.setHeader("Content-Type", "application/json");
+  res.end(JSON.stringify({ status: "live" }));
+  return Promise.resolve(true);
+};
+var handleReadyzRoute = async ({ res, routePath }) => {
+  if (routePath !== getProjectConfig3().http.readyEndpoint) return false;
+  const bootUuid = await readBootUuid();
+  const [redisError, pong] = await tryCatch(() => redis.ping());
+  const redisOk = !redisError && (pong === "PONG" || Boolean(pong));
+  const prismaOk = await pingPrisma();
+  const ready = Boolean(bootUuid) && redisOk && prismaOk;
+  res.statusCode = ready ? 200 : 503;
+  res.setHeader("Content-Type", "application/json");
+  res.end(JSON.stringify({
+    status: ready ? "ready" : "not-ready",
+    checks: { bootUuid: Boolean(bootUuid), redis: redisOk, prisma: prismaOk }
+  }));
+  return true;
+};
+var handleHealthRoute = async ({ res, routePath }) => {
+  if (routePath !== getProjectConfig3().http.healthEndpoint) return false;
+  const bootUuid = await readBootUuid();
+  const synchronizedHashes = computeSynchronizedEnvHashes();
+  res.statusCode = bootUuid ? 200 : 503;
+  res.setHeader("Content-Type", "application/json");
+  res.end(JSON.stringify({
+    status: bootUuid ? "ok" : "degraded",
+    bootUuid,
+    envKey: resolveEnvKey(),
+    synchronizedHashes
+  }));
+  return true;
+};
+
+// src/httpRoutes/testResetRoute.ts
+import {
+  clearAllHooks,
+  clearAllRateLimits,
+  getProjectConfig as getProjectConfig4,
+  formatKey,
+  redis as redis2,
+  tryCatch as tryCatch2
+} from "@luckystack/core";
+var handleTestResetRoute = async ({ req, res, routePath }) => {
+  if (routePath !== getProjectConfig4().http.testResetEndpoint) return false;
+  const nodeEnv = process.env.NODE_ENV;
+  if (nodeEnv !== "development" && nodeEnv !== "test") {
+    res.statusCode = 404;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify({ status: "error", errorCode: "notFound" }));
+    return true;
+  }
+  const requiredToken = process.env.TEST_RESET_TOKEN;
+  if (!requiredToken || req.headers["x-test-reset-token"] !== requiredToken) {
+    res.statusCode = 403;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify({ status: "error", errorCode: "auth.forbidden" }));
+    return true;
+  }
+  const cleared = [];
+  await clearAllRateLimits();
+  cleared.push("rateLimits");
+  const sessionPattern = `${formatKey("-session", "")}:*`;
+  const activeUsersPattern = `${formatKey("-activeUsers", "")}:*`;
+  const scanAndDelete = async (pattern, label) => {
+    const [error, deleted] = await tryCatch2(async () => {
+      let cursor = "0";
+      let total = 0;
+      do {
+        const [next, keys] = await redis2.scan(cursor, "MATCH", pattern, "COUNT", 200);
+        cursor = next;
+        if (Array.isArray(keys) && keys.length > 0) {
+          await redis2.del(...keys);
+          total += keys.length;
+        }
+      } while (cursor !== "0");
+      return total;
+    });
+    if (error || !deleted) return 0;
+    if (deleted > 0) cleared.push(label);
+    return deleted;
+  };
+  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") ?? "" : "";
+  if (includeFlag.split(",").map((s) => s.trim()).includes("hooks")) {
+    clearAllHooks();
+    cleared.push("hooks");
+  }
+  res.statusCode = 200;
+  res.setHeader("Content-Type", "application/json");
+  res.end(JSON.stringify({ status: "success", cleared }));
+  return true;
+};
+
+// src/httpRoutes/uploadsRoute.ts
+import { serveAvatar } from "@luckystack/core";
+var handleUploadsRoute = async ({ res, routePath }) => {
+  if (!routePath.startsWith("/uploads/")) return false;
+  await serveAvatar({ routePath, res });
+  return true;
+};
+
+// src/httpRoutes/authApiRoute.ts
+import {
+  checkRateLimit,
+  dispatchHook as dispatchHook2,
+  getLogger,
+  getProjectConfig as getProjectConfig5
+} from "@luckystack/core";
+import {
+  createOAuthState,
+  deleteSession,
+  getOAuthProviders,
+  isFullOAuthProvider,
+  loginWithCredentials
+} from "@luckystack/login";
+var parseSessionBasedTokenHeader = (headerValue) => {
+  if (headerValue === void 0) return null;
+  const value = Array.isArray(headerValue) ? headerValue[0] : headerValue;
+  if (value === "1" || value === "true") return true;
+  if (value === "0" || value === "false") return false;
+  return null;
+};
+var handleAuthApiRoute = async ({
+  req,
+  res,
+  routePath,
+  token,
+  params,
+  sessionCookieOptions
+}) => {
+  if (!routePath.startsWith("/auth/api")) return false;
+  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);
+  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 (!oauthState) {
+      res.writeHead(500, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ status: false, reason: "login.oauthStateInitFailed" }));
+      return true;
+    }
+    const clientId = encodeURIComponent(provider.clientID);
+    const callbackUrl = encodeURIComponent(provider.callbackURL);
+    const scope = encodeURIComponent(provider.scope.join(" "));
+    const state = encodeURIComponent(oauthState);
+    res.writeHead(302, {
+      Location: `${provider.authorizationURL}?client_id=${clientId}&redirect_uri=${callbackUrl}&scope=${scope}&response_type=code&prompt=select_account&state=${state}`
+    });
+    res.end();
+    return true;
+  }
+  const rateLimiting = config.rateLimiting;
+  if (rateLimiting.defaultApiLimit !== false && rateLimiting.defaultApiLimit > 0) {
+    const requesterIp = req.socket.remoteAddress ?? "unknown";
+    const { allowed, resetIn } = await checkRateLimit({
+      key: `ip:${requesterIp}:auth:credentials`,
+      limit: rateLimiting.defaultApiLimit,
+      windowMs: rateLimiting.windowMs
+    });
+    if (!allowed) {
+      void dispatchHook2("rateLimitExceeded", {
+        scope: "auth",
+        key: `ip:${requesterIp}:auth:credentials`,
+        limit: rateLimiting.defaultApiLimit,
+        windowMs: rateLimiting.windowMs,
+        count: rateLimiting.defaultApiLimit + 1,
+        route: routePath,
+        ip: requesterIp
+      });
+      res.setHeader("content-type", "application/json; charset=utf-8");
+      res.end(JSON.stringify({
+        status: false,
+        reason: "api.rateLimitExceeded",
+        errorParams: [{ key: "seconds", value: resetIn }]
+      }));
+      return true;
+    }
+  }
+  const result = await loginWithCredentials(params);
+  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");
+    res.end(JSON.stringify({ status: false, reason: reasonKey }));
+    return true;
+  }
+  if (result.newToken) {
+    if (token) await deleteSession(token);
+    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");
+    if (useSessionBasedToken) {
+      res.setHeader("X-Session-Token", result.newToken);
+    } else {
+      res.setHeader("Set-Cookie", `${sessionCookieName}=${result.newToken}; ${sessionCookieOptions}`);
+    }
+  }
+  res.end(JSON.stringify({
+    status: result.status,
+    reason: result.reason,
+    session: result.session,
+    authenticated: Boolean(result.newToken)
+  }));
+  return true;
+};
+
+// src/httpRoutes/authCallbackRoute.ts
+import { getLogger as getLogger2, getProjectConfig as getProjectConfig6 } from "@luckystack/core";
+import { deleteSession as deleteSession2, loginCallback } from "@luckystack/login";
+var handleAuthCallbackRoute = async ({
+  req,
+  res,
+  routePath,
+  token,
+  sessionCookieOptions
+}) => {
+  if (!routePath.startsWith("/auth/callback")) return false;
+  const config = getProjectConfig6();
+  const sessionCookieName = config.http.sessionCookieName;
+  const shouldLogDev = config.logging.devLogs;
+  const baseLocation = process.env.DNS || config.app.publicUrl || "/";
+  const callbackResult = await loginCallback(routePath, req, res, {
+    defaultRedirectUrl: baseLocation
+  });
+  if (!callbackResult) {
+    res.writeHead(401, { "Content-Type": "text/plain" });
+    res.end("Login failed");
+    return true;
+  }
+  if (token) await deleteSession2(token);
+  if (shouldLogDev) getLogger2().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}` });
+  } else {
+    res.setHeader("Set-Cookie", `${sessionCookieName}=${newToken}; ${sessionCookieOptions}`);
+    res.writeHead(302, { Location: redirectUrl });
+  }
+  res.end();
+  return true;
+};
+
+// src/httpRoutes/apiRoute.ts
+import {
+  captureException,
+  dispatchHook as dispatchHook3,
+  extractTokenFromRequest,
+  getLogger as getLogger3,
+  tryCatch as tryCatch3
+} from "@luckystack/core";
+import { handleHttpApiRequest } from "@luckystack/api";
+
+// src/sse.ts
+import { getProjectConfig as getProjectConfig7 } from "@luckystack/core";
+var isExpectingEventStream = (acceptHeader) => {
+  if (!acceptHeader) return false;
+  const value = Array.isArray(acceptHeader) ? acceptHeader.join(",") : acceptHeader;
+  return value.toLowerCase().includes("text/event-stream");
+};
+var queryRequestsStream = (queryString) => {
+  if (!queryString) return false;
+  const { queryParam, enabledValue } = getProjectConfig7().http.stream;
+  const params = new URLSearchParams(queryString);
+  const value = params.get(queryParam);
+  return value === enabledValue || value === "1";
+};
+var shouldUseHttpStream = ({
+  acceptHeader,
+  queryString
+}) => isExpectingEventStream(acceptHeader) || queryRequestsStream(queryString);
+var initSseResponse = (res) => {
+  res.writeHead(200, {
+    "Content-Type": "text/event-stream",
+    "Cache-Control": "no-cache, no-transform",
+    Connection: "keep-alive",
+    "X-Accel-Buffering": "no"
+  });
+  const connectedComment = getProjectConfig7().http.stream.connectedComment;
+  if (connectedComment) {
+    res.write(`${connectedComment}
+
+`);
+  }
+};
+var sendSseEvent = ({
+  res,
+  event,
+  data
+}) => {
+  if (res.writableEnded) return;
+  res.write(`event: ${event}
+`);
+  res.write(`data: ${JSON.stringify(data)}
+
+`);
+};
+
+// src/httpRoutes/apiRoute.ts
+var handleApiRoute = async ({
+  req,
+  res,
+  routePath,
+  queryString,
+  method,
+  params,
+  requestId
+}) => {
+  if (!routePath.startsWith("/api/")) return false;
+  const useHttpStream = shouldUseHttpStream({ acceptHeader: req.headers.accept, queryString });
+  let streamClosed = false;
+  if (useHttpStream) {
+    initSseResponse(res);
+    req.on("close", () => {
+      streamClosed = true;
+    });
+  }
+  const [error, handled] = await tryCatch3(async () => {
+    const httpToken = extractTokenFromRequest(req);
+    const apiName = routePath.slice(5);
+    if (!apiName) {
+      const response = {
+        status: "error",
+        httpStatus: 400,
+        message: "api.invalidName",
+        errorCode: "api.invalidName"
+      };
+      if (useHttpStream) {
+        if (!streamClosed) sendSseEvent({ res, event: "final", data: response });
+        res.end();
+        return true;
+      }
+      res.setHeader("Content-Type", "application/json");
+      res.writeHead(400);
+      res.end(JSON.stringify(response));
+      return true;
+    }
+    const apiData = typeof params === "object" ? { ...params } : {};
+    delete apiData.stream;
+    const result = await handleHttpApiRequest({
+      name: apiName,
+      data: apiData,
+      token: httpToken,
+      requesterIp: req.socket.remoteAddress ?? void 0,
+      xLanguageHeader: req.headers["x-language"],
+      acceptLanguageHeader: req.headers["accept-language"],
+      method,
+      stream: useHttpStream ? (payload) => {
+        if (streamClosed || res.writableEnded) return;
+        sendSseEvent({ res, event: "stream", data: payload });
+      } : void 0
+    });
+    if (useHttpStream) {
+      if (!streamClosed) sendSseEvent({ res, event: "final", data: result });
+      res.end();
+      return true;
+    }
+    res.setHeader("Content-Type", "application/json");
+    res.writeHead(result.httpStatus);
+    res.end(JSON.stringify(result));
+    return true;
+  }, void 0, { routePath, method, requestId, source: "httpHandler.api" });
+  if (!error) {
+    return handled ?? true;
+  }
+  getLogger3().error("http-api: top-level handler threw", error, { routePath, method, requestId });
+  captureException(error, { routePath, method, requestId, source: "httpHandler.api" });
+  void dispatchHook3("apiError", {
+    route: routePath,
+    method,
+    requestId,
+    error
+  });
+  const errResponse = {
+    status: "error",
+    httpStatus: 500,
+    message: "api.invalidRequestFormat",
+    errorCode: "api.invalidRequestFormat"
+  };
+  if (useHttpStream) {
+    if (!res.writableEnded) sendSseEvent({ res, event: "error", data: errResponse });
+    res.end();
+    return true;
+  }
+  res.setHeader("Content-Type", "application/json");
+  res.writeHead(500);
+  res.end(JSON.stringify(errResponse));
+  return true;
+};
+
+// src/httpRoutes/syncRoute.ts
+import {
+  captureException as captureException2,
+  dispatchHook as dispatchHook4,
+  extractTokenFromRequest as extractTokenFromRequest2,
+  getLogger as getLogger4,
+  tryCatch as tryCatch4
+} from "@luckystack/core";
+import { handleHttpSyncRequest } from "@luckystack/sync";
+var normalizeHttpSyncParams = (params) => {
+  const source = params ?? {};
+  const data = source.data && typeof source.data === "object" ? source.data : {};
+  return {
+    data,
+    receiver: typeof source.receiver === "string" ? source.receiver : "",
+    ignoreSelf: typeof source.ignoreSelf === "boolean" ? source.ignoreSelf : void 0,
+    cb: typeof source.cb === "string" ? source.cb : void 0
+  };
+};
+var handleSyncRoute = async ({
+  req,
+  res,
+  routePath,
+  queryString,
+  method,
+  params,
+  requestId
+}) => {
+  if (!routePath.startsWith("/sync/")) return false;
+  const useHttpStream = shouldUseHttpStream({ acceptHeader: req.headers.accept, queryString });
+  let streamClosed = false;
+  if (useHttpStream) {
+    initSseResponse(res);
+    req.on("close", () => {
+      streamClosed = true;
+    });
+  }
+  const [error, handled] = await tryCatch4(async () => {
+    if (method !== "POST") {
+      const response = {
+        status: "error",
+        message: "sync.methodNotAllowed",
+        errorCode: "sync.methodNotAllowed"
+      };
+      if (useHttpStream) {
+        if (!streamClosed) sendSseEvent({ res, event: "final", data: response });
+        res.end();
+        return true;
+      }
+      res.setHeader("Content-Type", "application/json");
+      res.writeHead(405);
+      res.end(JSON.stringify(response));
+      return true;
+    }
+    const httpToken = extractTokenFromRequest2(req);
+    const syncName = routePath.slice(6);
+    if (!syncName) {
+      const response = {
+        status: "error",
+        message: "sync.invalidName",
+        errorCode: "sync.invalidName"
+      };
+      if (useHttpStream) {
+        if (!streamClosed) sendSseEvent({ res, event: "final", data: response });
+        res.end();
+        return true;
+      }
+      res.setHeader("Content-Type", "application/json");
+      res.writeHead(400);
+      res.end(JSON.stringify(response));
+      return true;
+    }
+    const syncParams = normalizeHttpSyncParams(params);
+    const result = await handleHttpSyncRequest({
+      name: `sync/${syncName}`,
+      cb: syncParams.cb,
+      data: syncParams.data,
+      receiver: syncParams.receiver,
+      ignoreSelf: syncParams.ignoreSelf,
+      token: httpToken,
+      requesterIp: req.socket.remoteAddress ?? void 0,
+      xLanguageHeader: req.headers["x-language"],
+      acceptLanguageHeader: req.headers["accept-language"],
+      stream: useHttpStream ? (payload) => {
+        if (streamClosed || res.writableEnded) return;
+        sendSseEvent({ res, event: "stream", data: payload });
+      } : void 0
+    });
+    if (useHttpStream) {
+      if (!streamClosed) sendSseEvent({ res, event: "final", data: result });
+      res.end();
+      return true;
+    }
+    res.setHeader("Content-Type", "application/json");
+    res.writeHead(result.httpStatus ?? (result.status === "success" ? 200 : 400));
+    res.end(JSON.stringify(result));
+    return true;
+  }, void 0, { routePath, method, requestId, source: "httpHandler.sync" });
+  if (!error) {
+    return handled ?? true;
+  }
+  getLogger4().error("http-sync: top-level handler threw", error, { routePath, method, requestId });
+  captureException2(error, { routePath, method, requestId, source: "httpHandler.sync" });
+  void dispatchHook4("syncError", {
+    route: routePath,
+    method,
+    requestId,
+    error
+  });
+  const errResponse = {
+    status: "error",
+    message: "sync.invalidRequestFormat",
+    errorCode: "sync.invalidRequestFormat"
+  };
+  if (useHttpStream) {
+    if (!res.writableEnded) sendSseEvent({ res, event: "error", data: errResponse });
+    res.end();
+    return true;
+  }
+  res.setHeader("Content-Type", "application/json");
+  res.writeHead(500);
+  res.end(JSON.stringify(errResponse));
+  return true;
+};
+
+// src/httpRoutes/customRoutes.ts
+import { captureException as captureException3, getLogger as getLogger5, tryCatch as tryCatch5 } from "@luckystack/core";
+
+// src/customRoutesRegistry.ts
+var handlers = [];
+var preParamsHandlers = [];
+var registerCustomRoute = (handler, options = {}) => {
+  if (options.phase === "pre-params") {
+    preParamsHandlers.push(handler);
+    return;
+  }
+  handlers.push(handler);
+};
+var getCustomRoutes = () => handlers;
+var getPreParamsCustomRoutes = () => preParamsHandlers;
+var clearCustomRoutes = () => {
+  handlers.length = 0;
+  preParamsHandlers.length = 0;
+};
+
+// src/httpRoutes/customRoutes.ts
+var runHandler = async (handler, req, res, ctx, source) => {
+  const [error, handled] = await tryCatch5(() => handler(req, res, ctx));
+  if (error) {
+    getLogger5().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" });
+      res.end(JSON.stringify({ status: "error", errorCode: "server.customRouteFailed" }));
+    }
+    return true;
+  }
+  return Boolean(handled) || res.writableEnded;
+};
+var handlePreParamsCustomRoutes = async ({
+  req,
+  res,
+  routePath,
+  queryString,
+  method,
+  token
+}) => {
+  const ctx = { routePath, method, queryString, token };
+  for (const handler of getPreParamsCustomRoutes()) {
+    const handled = await runHandler(handler, req, res, ctx, "preParamsCustomRoute");
+    if (handled) return true;
+  }
+  return false;
+};
+var handleCustomRoutes = async ({
+  req,
+  res,
+  options,
+  routePath,
+  queryString,
+  method,
+  token
+}) => {
+  const ctx = { routePath, method, queryString, token };
+  for (const handler of getCustomRoutes()) {
+    const handled = await runHandler(handler, req, res, ctx, "customRoutesRegistry");
+    if (handled) return true;
+  }
+  if (options.customRoutes) {
+    const handled = await runHandler(options.customRoutes, req, res, ctx, "createServer.customRoutes");
+    if (handled) return true;
+  }
+  return false;
+};
+
+// 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 serveWithRewrittenUrl = async (serveFile, req, res, rewrittenUrl) => {
+  const originalUrl = req.url;
+  req.url = rewrittenUrl;
+  try {
+    await serveFile(req, res);
+  } finally {
+    req.url = originalUrl;
+  }
+};
+var handleStaticAndSpaFallback = async ({
+  req,
+  res,
+  routePath,
+  options
+}) => {
+  if (routePath.includes("/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);
+    return true;
+  }
+  if (KNOWN_STATIC_FILE_REGEX.test(routePath)) {
+    if (!options.serveFile) {
+      res.writeHead(404);
+      res.end("Not Found");
+      return true;
+    }
+    await options.serveFile(req, res);
+    return true;
+  }
+  if (path.extname(routePath)) {
+    res.writeHead(404, { "Content-Type": "text/plain" });
+    res.end("Not Found");
+    return true;
+  }
+  if (!options.serveFile) {
+    res.writeHead(404, { "Content-Type": "text/plain" });
+    res.end("Not Found");
+    return true;
+  }
+  await serveWithRewrittenUrl(options.serveFile, req, res, "/");
+  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;
+  res.setHeader("Access-Control-Allow-Origin", origin);
+  res.setHeader("Access-Control-Allow-Methods", cors.allowedMethods);
+  res.setHeader("Access-Control-Allow-Headers", cors.allowedHeaders);
+  res.setHeader("Access-Control-Expose-Headers", cors.exposedHeaders);
+  if (cors.credentials) {
+    res.setHeader("Access-Control-Allow-Credentials", "true");
+  }
+  res.setHeader("Referrer-Policy", securityHeaders.referrerPolicy);
+  res.setHeader("X-Frame-Options", securityHeaders.frameOptions);
+  res.setHeader("X-XSS-Protection", securityHeaders.xssProtection);
+  res.setHeader("X-Content-Type-Options", securityHeaders.contentTypeOptions);
+  const builder = getSecurityHeadersBuilder();
+  if (builder) {
+    try {
+      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 });
+    }
+  }
+};
+var PRE_PARAMS_ROUTES = [
+  handleCsrfRoute,
+  handleFaviconRoute,
+  handleLivezRoute,
+  handleReadyzRoute,
+  handleHealthRoute,
+  handleTestResetRoute,
+  handlePreParamsCustomRoutes
+];
+var POST_PARAMS_ROUTES = [
+  handleUploadsRoute,
+  handleAuthApiRoute,
+  handleAuthCallbackRoute,
+  handleApiRoute,
+  handleSyncRoute,
+  handleCustomRoutes,
+  handleStaticAndSpaFallback
+];
+var dispatchRoutes = async (handlers2, ctx) => {
+  for (const handler of handlers2) {
+    const handled = await handler(ctx);
+    if (handled || ctx.res.writableEnded) return true;
+  }
+  return false;
+};
+var enforceOriginPolicy = (req, res, routePath) => {
+  const origin = req.headers.origin ?? req.headers.referer ?? "";
+  const isStateChangingMethod = req.method !== "GET" && req.method !== "HEAD" && req.method !== "OPTIONS";
+  if (isOriginExemptPath(routePath)) {
+    return { origin, rejected: false };
+  }
+  if (!origin) {
+    if (isStateChangingMethod) {
+      res.statusCode = 403;
+      res.setHeader("Content-Type", "text/plain");
+      res.end("Forbidden");
+      return { origin, rejected: true };
+    }
+  } else if (!allowedOrigin(origin)) {
+    res.statusCode = 403;
+    res.setHeader("Content-Type", "text/plain");
+    res.end("Forbidden");
+    return { origin, rejected: true };
+  }
+  return { origin, rejected: false };
+};
+var refreshSessionCookieIfPresent = async ({
+  req,
+  res,
+  token,
+  sessionCookieName,
+  sessionCookieOptions
+}) => {
+  const hasTokenCookie = hasCookie(req.headers.cookie, sessionCookieName);
+  if (!hasTokenCookie || !token) return;
+  const currentSession = await getSession3(token);
+  if (currentSession?.id) {
+    res.setHeader("Set-Cookie", `${sessionCookieName}=${token}; ${sessionCookieOptions}`);
+  }
+};
+var parseRequestParams = async ({
+  req,
+  res,
+  method,
+  routePath,
+  queryString,
+  requestId,
+  shouldLogDev
+}) => {
+  let params = await getParams({ method, req, res, queryString });
+  if (res.writableEnded) return null;
+  if (params && typeof params === "object" && Object.keys(params).length > 0) {
+    if (shouldLogDev) {
+      getLogger6().debug(`[${requestId}] ${method} ${routePath}`, {
+        params: sanitizeForLog(params)
+      });
+    }
+  } else {
+    if (shouldLogDev) {
+      getLogger6().debug(`[${requestId}] ${method} ${routePath}`);
+    }
+    params = {};
+  }
+  return params;
+};
+var handleHttpRequest = async (req, res, options) => {
+  const config = getProjectConfig8();
+  const shouldLogDev = config.logging.devLogs;
+  const sessionCookieName = config.http.sessionCookieName;
+  const sessionCookieOptions = buildSessionCookieOptions(
+    config.session.expiryDays,
+    process.env.SECURE === "true",
+    config.http
+  );
+  const url = req.url ?? "/";
+  const [routePathRaw, queryStringRaw] = url.split("?");
+  const routePath = routePathRaw ?? "/";
+  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();
+  res.setHeader("X-Request-Id", requestId);
+  const safeHeaders = {};
+  for (const [k, v] of Object.entries(req.headers)) {
+    if (k === "authorization" || k === "cookie" || k === "set-cookie" || k === "x-csrf-token") continue;
+    safeHeaders[k] = Array.isArray(v) ? v.join(", ") : v ?? "";
+  }
+  const preHttpResult = await dispatchHook5("preHttpRequest", {
+    method: req.method?.toUpperCase() ?? "GET",
+    url: req.url ?? "/",
+    requestId,
+    origin,
+    headers: safeHeaders
+  });
+  if (preHttpResult.stopped) {
+    res.statusCode = preHttpResult.signal.httpStatus ?? 403;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify({ status: "error", errorCode: preHttpResult.signal.errorCode }));
+    return;
+  }
+  if (req.method === "OPTIONS") {
+    res.writeHead(204);
+    res.end();
+    return;
+  }
+  const method = req.method;
+  if (method !== "GET" && method !== "POST" && method !== "PUT" && method !== "DELETE") {
+    res.statusCode = 404;
+    res.setHeader("Content-Type", "text/plain");
+    res.end(`method: ${String(method)} not supported, use one of: GET, POST, PUT, DELETE`);
+    return;
+  }
+  const token = extractTokenFromRequest3(req);
+  await refreshSessionCookieIfPresent({ req, res, token, sessionCookieName, sessionCookieOptions });
+  const csrfRejected = await enforceCsrfOnStateChangingRequest({ req, res, routePath, token, requestId });
+  if (csrfRejected) return;
+  const baseCtx = {
+    req,
+    res,
+    options,
+    routePath,
+    queryString,
+    method,
+    token,
+    requestId,
+    sessionCookieOptions
+  };
+  if (await dispatchRoutes(PRE_PARAMS_ROUTES, { ...baseCtx, params: {} })) return;
+  const params = await parseRequestParams({
+    req,
+    res,
+    method,
+    routePath,
+    queryString,
+    requestId,
+    shouldLogDev
+  });
+  if (params === null) return;
+  await dispatchRoutes(POST_PARAMS_ROUTES, { ...baseCtx, params });
+};
+
+// src/loadSocket.ts
+import { Server as SocketIOServer } from "socket.io";
+import {
+  abortAllForSocket,
+  abortApiByResponseIndex,
+  abortSyncByCb,
+  allowedOrigin as allowedOrigin2,
+  applySocketMiddlewares,
+  attachSocketRedisAdapter,
+  setIoInstance,
+  socketEventNames,
+  buildJoinRoomResponseEventName,
+  buildLeaveRoomResponseEventName,
+  buildGetJoinedRoomsResponseEventName,
+  extractLanguageFromHeader,
+  extractTokenFromSocket,
+  getLogger as getLogger7,
+  getProjectConfig as getProjectConfig9,
+  dispatchHook as dispatchHook6,
+  normalizeErrorResponse,
+  tryCatch as tryCatch6
+} 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);
+  if (sessionLocks.get(token) === next) sessionLocks.delete(token);
+};
+var getVisibleSocketRooms = (socket, token) => {
+  return [...socket.rooms].filter((room) => typeof room === "string").filter((room) => room !== socket.id).filter((room) => !token || room !== token);
+};
+var getSessionRoomCodes = (session) => {
+  const roomCodes = Array.isArray(session.roomCodes) ? session.roomCodes.filter(
+    (roomCode) => typeof roomCode === "string" && roomCode.length > 0
+  ) : [];
+  return [...new Set(roomCodes)];
+};
+var sanitizeSessionRoomKeys = (session) => {
+  const { code: _legacyCode, codes: _legacyCodes, ...sanitizedSession } = session;
+  return sanitizedSession;
+};
+var loadSocket = (httpServer, options = {}) => {
+  const config = getProjectConfig9();
+  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)) {
+          callback(null, true);
+        } else {
+          callback(new Error("Not allowed by CORS"));
+        }
+      },
+      credentials: true
+    },
+    maxHttpBufferSize: options.maxHttpBufferSize ?? config.socket.maxHttpBufferSize,
+    pingTimeout: config.socket.pingTimeout,
+    pingInterval: config.socket.pingInterval
+  });
+  setIoInstance(io);
+  applySocketMiddlewares(io);
+  attachSocketRedisAdapter(io);
+  if (shouldLogSocketStartup) {
+    getLogger7().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 });
+    }
+    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)"}`);
+        }
+      })();
+    }
+  });
+  return io;
+};
+
+// src/verifyBootstrap.ts
+import {
+  getLogger as getLogger8,
+  isDeployConfigRegistered,
+  isLocalizedNormalizerRegistered,
+  isProjectConfigRegistered,
+  isRuntimeMapsProviderRegistered
+} from "@luckystack/core";
+var verifyBootstrap = async (requirements = {}) => {
+  const missing = [];
+  if (!isProjectConfigRegistered()) {
+    missing.push(
+      "ProjectConfig \u2014 call `registerProjectConfig({...})` from `luckystack/core/bootstrap.ts` (or your config.ts)."
+    );
+  }
+  if (requirements.requireDeployConfig && !isDeployConfigRegistered()) {
+    missing.push(
+      "DeployConfig \u2014 call `registerDeployConfig({...})` from `luckystack/deploy/deploy.config.ts`."
+    );
+  }
+  if (requirements.requireServicesConfig) {
+    const { isServicesConfigRegistered } = await import("@luckystack/core");
+    if (!isServicesConfigRegistered()) {
+      missing.push(
+        "ServicesConfig \u2014 call `registerServicesConfig({...})` from `services.config.ts`."
+      );
+    }
+  }
+  if (requirements.requireOAuthProviders) {
+    const { getOAuthProviders: getOAuthProviders2 } = await import("@luckystack/login");
+    if (getOAuthProviders2().length <= 1) {
+      missing.push(
+        "OAuth providers \u2014 call `registerOAuthProviders([...])` from `luckystack/login/oauthProviders.ts` (or skip this check if your app uses credentials only)."
+      );
+    }
+  }
+  if (!isRuntimeMapsProviderRegistered()) {
+    if (process.env.NODE_ENV === "production") {
+      missing.push(
+        "RuntimeMapsProvider \u2014 call `registerRuntimeMapsProvider({...})` from `server/prod/runtimeMaps.ts`. Without it, every api/sync request returns notFound."
+      );
+    } else {
+      getLogger8().warn(
+        "[LuckyStack] No RuntimeMapsProvider registered \u2014 api/sync requests will resolve to empty maps. Devkit hot-reload usually registers one automatically."
+      );
+    }
+  }
+  if (!isLocalizedNormalizerRegistered()) {
+    if (process.env.NODE_ENV === "production") {
+      missing.push(
+        "LocalizedNormalizer \u2014 call `registerLocalizedNormalizer({...})` from your bootstrap. Without it, error response messages will be the raw errorCode (no i18n)."
+      );
+    } else {
+      getLogger8().warn(
+        "[LuckyStack] No LocalizedNormalizer registered \u2014 error messages will pass through as the raw errorCode."
+      );
+    }
+  }
+  if (missing.length === 0) return;
+  const detail = missing.map((line, idx) => `  ${idx + 1}. ${line}`).join("\n");
+  throw new Error(
+    [
+      "[LuckyStack] Bootstrap incomplete \u2014 the following registrations are missing:",
+      detail,
+      "",
+      "See docs/ARCHITECTURE_PACKAGING.md (overlay layout) for the recommended bootstrap order."
+    ].join("\n")
+  );
+};
+
+// src/runtimeMapsLoader.ts
+import {
+  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) => {
+  const moduleRecord = moduleValue && typeof moduleValue === "object" ? moduleValue : {};
+  const apiCandidate = moduleRecord.apis;
+  const syncCandidate = moduleRecord.syncs;
+  const functionCandidate = moduleRecord.functions;
+  return {
+    apisObject: isRuntimeMapRecord(apiCandidate) ? apiCandidate : {},
+    syncObject: isRuntimeMapRecord(syncCandidate) ? syncCandidate : {},
+    functionsObject: isRuntimeMapRecord(functionCandidate) ? functionCandidate : {}
+  };
+};
+var resolvePresets = (options) => {
+  const fromOptions = options.preset;
+  if (typeof fromOptions === "string" && fromOptions.length > 0) {
+    return [fromOptions];
+  }
+  if (Array.isArray(fromOptions) && fromOptions.length > 0) {
+    return [...new Set(fromOptions)];
+  }
+  const fromArgv = getParsedBundles();
+  if (fromArgv.length > 0) {
+    return fromArgv;
+  }
+  return ["default"];
+};
+var mergeInto = (target, source, kind, fromPreset, keyOrigin) => {
+  for (const key of Object.keys(source)) {
+    const previousPreset = keyOrigin.get(key);
+    if (previousPreset !== void 0 && previousPreset !== fromPreset) {
+      throw new Error(
+        `[luckystack:runtimeMaps] ${kind} key collision: "${key}" present in both preset "${previousPreset}" and preset "${fromPreset}". Services must belong to exactly one preset (see docs/ARCHITECTURE_PACKAGING.md \xA710).`
+      );
+    }
+    keyOrigin.set(key, fromPreset);
+    target[key] = source[key];
+  }
+};
+var isProduction = () => process.env.NODE_ENV === "production";
+var createProdRuntimeMapsProvider = (options) => {
+  let prodMapsPromise = null;
+  let devkitModulePromise = null;
+  const getDevkit = async () => {
+    devkitModulePromise ??= import("@luckystack/devkit");
+    return await devkitModulePromise;
+  };
+  const loadProdRuntimeMaps = async () => {
+    if (prodMapsPromise) return await prodMapsPromise;
+    prodMapsPromise = (async () => {
+      const presets = resolvePresets(options);
+      const merged = {
+        apisObject: {},
+        syncObject: {},
+        functionsObject: {}
+      };
+      const apiOrigin = /* @__PURE__ */ new Map();
+      const syncOrigin = /* @__PURE__ */ new Map();
+      const functionOrigin = /* @__PURE__ */ new Map();
+      const loadedModules = await Promise.all(
+        presets.map(async (preset) => ({
+          preset,
+          mod: await options.loadGenerated(preset).catch(() => null)
+        }))
+      );
+      let loadedAny = false;
+      for (const { preset, mod } of loadedModules) {
+        if (!mod) {
+          console.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);
+        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(
+          `[luckystack:runtimeMaps] no presets resolved (tried: ${presets.join(", ")}). Every api/sync request will return notFound until at least one generated module loads.`
+        );
+        return emptyRuntimeMaps;
+      }
+      return merged;
+    })();
+    return await prodMapsPromise;
+  };
+  const getRuntimeApiMaps = async () => {
+    if (!isProduction()) {
+      const { devApis, devFunctions } = await getDevkit();
+      return {
+        apisObject: isRuntimeMapRecord(devApis) ? devApis : {},
+        functionsObject: isRuntimeMapRecord(devFunctions) ? devFunctions : {}
+      };
+    }
+    const { apisObject, functionsObject } = await loadProdRuntimeMaps();
+    return { apisObject, functionsObject };
+  };
+  const getRuntimeSyncMaps = async () => {
+    if (!isProduction()) {
+      const { devSyncs, devFunctions } = await getDevkit();
+      return {
+        syncObject: isRuntimeMapRecord(devSyncs) ? devSyncs : {},
+        functionsObject: isRuntimeMapRecord(devFunctions) ? devFunctions : {}
+      };
+    }
+    const { syncObject, functionsObject } = await loadProdRuntimeMaps();
+    return { syncObject, functionsObject };
+  };
+  return { getRuntimeApiMaps, getRuntimeSyncMaps };
+};
+var registerProdRuntimeMapsProvider = (options) => {
+  const provider = createProdRuntimeMapsProvider(options);
+  registerRuntimeMapsProvider(provider);
+  return provider;
+};
+
+// src/createServer.ts
+var createLuckyStackServer = async (options = {}) => {
+  if (options.loadGeneratedMaps) {
+    registerProdRuntimeMapsProvider({
+      loadGenerated: options.loadGeneratedMaps,
+      preset: options.runtimeMapsPreset
+    });
+  }
+  await verifyBootstrap({
+    requireDeployConfig: options.requireDeployConfig,
+    requireServicesConfig: options.requireServicesConfig,
+    requireOAuthProviders: options.requireOAuthProviders
+  });
+  const port = options.port ?? getParsedPort() ?? process.env.SERVER_PORT ?? 80;
+  const ip = options.ip ?? process.env.SERVER_IP ?? "127.0.0.1";
+  const enableDevTools = options.enableDevTools ?? process.env.NODE_ENV !== "production";
+  registerBindAddress({
+    ip,
+    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());
+  if (bootUuidError) {
+    throw new Error(
+      "Failed to write the boot UUID to Redis. Check REDIS_HOST / REDIS_PORT / REDIS_USERNAME / REDIS_PASSWORD and that Redis is reachable.",
+      { cause: bootUuidError }
+    );
+  }
+  const httpServer = http.createServer((req, res) => {
+    void handleHttpRequest(req, res, options);
+  });
+  const ioServer = loadSocket(httpServer, {
+    maxHttpBufferSize: options.maxHttpBufferSize
+  });
+  const listen = (callback) => new Promise((resolve) => {
+    const portValue = typeof port === "string" ? Number.parseInt(port, 10) : port;
+    httpServer.listen(portValue, ip, () => {
+      const config = getProjectConfig10();
+      if (config.logging.socketStartup || config.logging.devLogs) {
+        getLogger9().info(`Server is running on http://${ip}:${String(port)}/`);
+      }
+      callback?.();
+      resolve(httpServer);
+    });
+  });
+  return { httpServer, ioServer, listen };
+};
+
+// src/bootstrap.ts
+import path2 from "path";
+import fs from "fs";
+import { pathToFileURL } from "url";
+import { ROOT_DIR } from "@luckystack/core";
+var OVERLAY_ORDER = [
+  // Core registries first — clients, paths, routing rules. Anything below
+  // depends on these being in place.
+  "core",
+  // Deploy + services topology — needed by the router but harmless for
+  // single-instance deploys.
+  "deploy",
+  // Auth — OAuth providers + user adapter sit on top of core.
+  "login",
+  // Sentry / docs-ui / presence sit on top of core but don't block boot.
+  "sentry",
+  "presence",
+  "docs-ui",
+  // Server overlay last — typically empty, but a place to wire framework
+  // hooks (`registerHook('onSocketConnect', ...)` etc.) before listen().
+  "server"
+];
+var importIfExists = async (filePath) => {
+  if (!fs.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)) {
+    return;
+  }
+  for (const packageName of OVERLAY_ORDER) {
+    const packageDir = path2.join(overlayAbs, packageName);
+    if (!fs.existsSync(packageDir)) continue;
+    const indexCandidates = ["index.ts", "index.js"];
+    for (const candidate of indexCandidates) {
+      await importIfExists(path2.join(packageDir, candidate));
+    }
+    const entries = fs.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));
+    }
+  }
+};
+var bootstrapLuckyStack = async (options = {}) => {
+  const overlayRoot = options.overlayRoot ?? "luckystack";
+  if (!options.skipOverlayLoad) {
+    await loadOverlayFolder(overlayRoot);
+  }
+  const server = await createLuckyStackServer(options);
+  return server;
+};
+
+// src/errorFormatterRegistry.ts
+import {
+  registerErrorFormatter,
+  getErrorFormatter,
+  applyErrorFormatter
+} from "@luckystack/core";
+export {
+  applyServerArgv,
+  bootstrapLuckyStack,
+  clearCustomRoutes,
+  clearOriginExemptPaths,
+  createLuckyStackServer,
+  createProdRuntimeMapsProvider,
+  getCustomRoutes,
+  getErrorFormatter,
+  getOriginExemptPaths,
+  getParsedBundles,
+  getParsedPort,
+  getPreParamsCustomRoutes,
+  getSecurityHeadersBuilder,
+  isOriginExemptPath,
+  parseServerArgv,
+  registerCustomRoute,
+  registerErrorFormatter,
+  registerOriginExemptPath,
+  registerProdRuntimeMapsProvider,
+  registerSecurityHeaders,
+  verifyBootstrap
+};
+//# sourceMappingURL=index.js.map