@kaikybrofc/omnizap-system 2.3.1 → 2.3.3

package/server/controllers/systemAdminController.js

@@ -0,0 +1,141 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { URL } from 'node:url';
+
+import logger from '../../app/utils/logger/loggerModule.js';
+
+const parseEnvBool = (value, fallback) => {
+  if (value === undefined || value === null || value === '') return fallback;
+  const normalized = String(value).trim().toLowerCase();
+  if (['1', 'true', 'yes', 'y', 'on'].includes(normalized)) return true;
+  if (['0', 'false', 'no', 'n', 'off'].includes(normalized)) return false;
+  return fallback;
+};
+
+const normalizeBasePath = (value, fallback) => {
+  const raw = String(value || '').trim() || fallback;
+  const withLeadingSlash = raw.startsWith('/') ? raw : `/${raw}`;
+  const withoutTrailingSlash = withLeadingSlash.length > 1 && withLeadingSlash.endsWith('/') ? withLeadingSlash.slice(0, -1) : withLeadingSlash;
+  return withoutTrailingSlash || fallback;
+};
+
+const STICKER_API_BASE_PATH = normalizeBasePath(process.env.STICKER_API_BASE_PATH, '/api/sticker-packs');
+const STICKER_WEB_PATH = normalizeBasePath(process.env.STICKER_WEB_PATH, '/stickers');
+const STICKER_ADMIN_WEB_PATH = `${STICKER_WEB_PATH}/admin`;
+const USER_PROFILE_WEB_PATH = normalizeBasePath(process.env.USER_PROFILE_WEB_PATH, '/user');
+const USER_SYSTEMADM_WEB_PATH = `${USER_PROFILE_WEB_PATH}/systemadm`;
+const STICKER_ADMIN_REDIRECT_TO_USER = parseEnvBool(process.env.STICKER_ADMIN_REDIRECT_TO_USER, true);
+const SITE_ORIGIN = String(process.env.SITE_ORIGIN || 'https://omnizap.shop')
+  .trim()
+  .replace(/\/+$/, '');
+
+const USER_SYSTEMADM_TEMPLATE_PATH = path.join(process.cwd(), 'public', 'user', 'systemadm', 'index.html');
+const LEGACY_STICKER_ADMIN_TEMPLATE_PATH = path.join(process.cwd(), 'public', 'stickers', 'admin', 'index.html');
+
+let stickerCatalogControllerPromise = null;
+const loadStickerCatalogController = async () => {
+  if (!stickerCatalogControllerPromise) {
+    stickerCatalogControllerPromise = import('./stickerCatalogController.js');
+  }
+  return stickerCatalogControllerPromise;
+};
+
+const sendHtml = (req, res, html) => {
+  res.statusCode = 200;
+  res.setHeader('Content-Type', 'text/html; charset=utf-8');
+  res.setHeader('Cache-Control', 'no-store');
+  res.setHeader('X-Robots-Tag', 'noindex, nofollow');
+  if (req.method === 'HEAD') {
+    res.end();
+    return;
+  }
+  res.end(html);
+};
+
+const sendJson = (req, res, statusCode, payload) => {
+  const body = JSON.stringify(payload);
+  res.statusCode = statusCode;
+  res.setHeader('Content-Type', 'application/json; charset=utf-8');
+  res.setHeader('Cache-Control', 'no-store');
+  res.setHeader('X-Robots-Tag', 'noindex, nofollow');
+  if (req.method === 'HEAD') {
+    res.end();
+    return;
+  }
+  res.end(body);
+};
+
+const sendRedirect = (res, location) => {
+  res.statusCode = 302;
+  res.setHeader('Location', location);
+  res.setHeader('Cache-Control', 'no-store');
+  res.end();
+};
+
+export const getSystemAdminRouteConfig = () => ({
+  webPath: USER_SYSTEMADM_WEB_PATH,
+  legacyWebPath: STICKER_ADMIN_WEB_PATH,
+  apiAdminBasePath: `${STICKER_API_BASE_PATH}/admin`,
+  apiAdminSessionPath: `${STICKER_API_BASE_PATH}/admin/session`,
+});
+
+export const maybeHandleSystemAdminRequest = async (req, res, { pathname, url }) => {
+  if (!['GET', 'HEAD', 'POST', 'PATCH', 'DELETE'].includes(req.method || '')) return false;
+
+  if (pathname === USER_SYSTEMADM_WEB_PATH || pathname === `${USER_SYSTEMADM_WEB_PATH}/`) {
+    if (!['GET', 'HEAD'].includes(req.method || '')) return false;
+    try {
+      const html = await fs.readFile(USER_SYSTEMADM_TEMPLATE_PATH, 'utf8');
+      sendHtml(req, res, html);
+    } catch (error) {
+      if (error?.code === 'ENOENT') {
+        sendJson(req, res, 404, { error: 'Template da pagina system admin nao encontrado.' });
+        return true;
+      }
+      logger.error('Falha ao renderizar pagina system admin.', {
+        action: 'user_system_admin_page_render_failed',
+        path: pathname,
+        error: error?.message,
+      });
+      sendJson(req, res, 500, { error: 'Falha interna ao renderizar pagina system admin.' });
+    }
+    return true;
+  }
+
+  if (pathname === STICKER_ADMIN_WEB_PATH || pathname === `${STICKER_ADMIN_WEB_PATH}/`) {
+    if (!['GET', 'HEAD'].includes(req.method || '')) return false;
+    if (STICKER_ADMIN_REDIRECT_TO_USER) {
+      const requestUrl = new URL(req.url || `${STICKER_ADMIN_WEB_PATH}/`, SITE_ORIGIN);
+      const userUrl = new URL(`${USER_SYSTEMADM_WEB_PATH}/`, SITE_ORIGIN);
+      for (const [key, value] of requestUrl.searchParams.entries()) {
+        userUrl.searchParams.append(key, value);
+      }
+      sendRedirect(res, `${userUrl.pathname}${userUrl.search}`);
+      return true;
+    }
+    try {
+      const html = await fs.readFile(LEGACY_STICKER_ADMIN_TEMPLATE_PATH, 'utf8');
+      sendHtml(req, res, html);
+    } catch (error) {
+      if (error?.code === 'ENOENT') {
+        sendJson(req, res, 404, { error: 'Template do painel admin nao encontrado.' });
+        return true;
+      }
+      logger.error('Falha ao renderizar pagina admin legado.', {
+        action: 'legacy_sticker_admin_page_render_failed',
+        path: pathname,
+        error: error?.message,
+      });
+      sendJson(req, res, 500, { error: 'Falha interna ao renderizar painel admin.' });
+    }
+    return true;
+  }
+
+  if (pathname === `${STICKER_API_BASE_PATH}/admin/session` || pathname.startsWith(`${STICKER_API_BASE_PATH}/admin/`)) {
+    const controller = await loadStickerCatalogController();
+    if (typeof controller?.maybeHandleStickerCatalogRequest !== 'function') return false;
+    return controller.maybeHandleStickerCatalogRequest(req, res, { pathname, url });
+  }
+
+  return false;
+};

package/server/controllers/userController.js

@@ -0,0 +1,87 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import logger from '../../app/utils/logger/loggerModule.js';
+
+const normalizeBasePath = (value, fallback) => {
+  const raw = String(value || '').trim() || fallback;
+  const withLeadingSlash = raw.startsWith('/') ? raw : `/${raw}`;
+  const withoutTrailingSlash = withLeadingSlash.length > 1 && withLeadingSlash.endsWith('/') ? withLeadingSlash.slice(0, -1) : withLeadingSlash;
+  return withoutTrailingSlash || fallback;
+};
+
+const STICKER_API_BASE_PATH = normalizeBasePath(process.env.STICKER_API_BASE_PATH, '/api/sticker-packs');
+const USER_PROFILE_WEB_PATH = normalizeBasePath(process.env.USER_PROFILE_WEB_PATH, '/user');
+const USER_DASHBOARD_TEMPLATE_PATH = path.join(process.cwd(), 'public', 'user', 'index.html');
+
+const USER_API_PATHS = new Set([`${STICKER_API_BASE_PATH}/auth/google/session`, `${STICKER_API_BASE_PATH}/me`, `${STICKER_API_BASE_PATH}/bot-contact`]);
+
+let stickerCatalogControllerPromise = null;
+const loadStickerCatalogController = async () => {
+  if (!stickerCatalogControllerPromise) {
+    stickerCatalogControllerPromise = import('./stickerCatalogController.js');
+  }
+  return stickerCatalogControllerPromise;
+};
+
+const sendHtml = (req, res, html) => {
+  res.statusCode = 200;
+  res.setHeader('Content-Type', 'text/html; charset=utf-8');
+  res.setHeader('Cache-Control', 'no-store');
+  res.setHeader('X-Robots-Tag', 'noindex, nofollow');
+  if (req.method === 'HEAD') {
+    res.end();
+    return;
+  }
+  res.end(html);
+};
+
+const sendJson = (req, res, statusCode, payload) => {
+  const body = JSON.stringify(payload);
+  res.statusCode = statusCode;
+  res.setHeader('Content-Type', 'application/json; charset=utf-8');
+  res.setHeader('Cache-Control', 'no-store');
+  res.setHeader('X-Robots-Tag', 'noindex, nofollow');
+  if (req.method === 'HEAD') {
+    res.end();
+    return;
+  }
+  res.end(body);
+};
+
+export const getUserRouteConfig = () => ({
+  webPath: USER_PROFILE_WEB_PATH,
+  apiBasePath: STICKER_API_BASE_PATH,
+});
+
+export const maybeHandleUserRequest = async (req, res, { pathname, url }) => {
+  if (!['GET', 'HEAD', 'POST', 'PATCH', 'DELETE'].includes(req.method || '')) return false;
+
+  if (pathname === USER_PROFILE_WEB_PATH || pathname === `${USER_PROFILE_WEB_PATH}/`) {
+    if (!['GET', 'HEAD'].includes(req.method || '')) return false;
+    try {
+      const html = await fs.readFile(USER_DASHBOARD_TEMPLATE_PATH, 'utf8');
+      sendHtml(req, res, html);
+    } catch (error) {
+      if (error?.code === 'ENOENT') {
+        sendJson(req, res, 404, { error: 'Template da pagina de usuario nao encontrado.' });
+        return true;
+      }
+      logger.error('Falha ao renderizar pagina de usuario.', {
+        action: 'user_page_render_failed',
+        path: pathname,
+        error: error?.message,
+      });
+      sendJson(req, res, 500, { error: 'Falha interna ao renderizar pagina de usuario.' });
+    }
+    return true;
+  }
+
+  if (USER_API_PATHS.has(pathname)) {
+    const controller = await loadStickerCatalogController();
+    if (typeof controller?.maybeHandleStickerCatalogRequest !== 'function') return false;
+    return controller.maybeHandleStickerCatalogRequest(req, res, { pathname, url });
+  }
+
+  return false;
+};

package/server/http/httpServer.js

@@ -1,9 +1,11 @@
 import http from 'node:http';
+
 import logger from '../../app/utils/logger/loggerModule.js';
 import { getMetricsServerConfig, isMetricsEnabled, recordHttpRequest, resolveRouteGroup } from '../../app/observability/metrics.js';
+import { applyCachePolicy } from '../middleware/cachePolicy.js';
+import { applySecurityHeaders } from '../middleware/securityHeaders.js';
+import { getIndexRouteConfigs, routeRequest } from '../routes/indexRouter.js';
 import { parseRequestUrl, normalizeRequestId } from './requestContext.js';
-import { maybeHandleMetricsRoute } from '../routes/metricsRoute.js';
-import { getStickerCatalogRouteConfig, maybeHandleStickerCatalogRoute } from '../routes/stickerCatalogRoute.js';
 
 let server = null;
 let serverStarted = false;
@@ -12,6 +14,7 @@ export const startHttpServer = () => {
   if (!isMetricsEnabled() || serverStarted) return;
 
   const { host, port, path: metricsPath } = getMetricsServerConfig();
+
   server = http.createServer(async (req, res) => {
     const requestStartedAt = Date.now();
     const requestId = normalizeRequestId(req.headers['x-request-id']);
@@ -19,10 +22,22 @@ export const startHttpServer = () => {
 
     const parsedUrl = parseRequestUrl(req, host, port);
     const pathname = parsedUrl.pathname;
+
+    let routeConfigs = null;
+    try {
+      routeConfigs = await getIndexRouteConfigs();
+    } catch (error) {
+      logger.error('Erro ao carregar configuracao de rotas.', {
+        error: error?.message,
+      });
+    }
+
     let routeGroup = resolveRouteGroup({
       pathname,
       metricsPath,
-      catalogConfig: null,
+      catalogConfig: routeConfigs?.stickerConfig || null,
+      userConfig: routeConfigs?.userConfig || null,
+      systemAdminConfig: routeConfigs?.systemAdminConfig || null,
     });
 
     res.once('finish', () => {
@@ -35,31 +50,36 @@ export const startHttpServer = () => {
     });
 
     try {
-      const catalogConfig = await getStickerCatalogRouteConfig();
-      routeGroup = resolveRouteGroup({
+      applySecurityHeaders(req, res);
+      applyCachePolicy(req, res, { pathname });
+
+      await routeRequest(req, res, {
         pathname,
+        url: parsedUrl,
         metricsPath,
-        catalogConfig,
+        configs: routeConfigs,
       });
-      const handledByCatalog = await maybeHandleStickerCatalogRoute(req, res, {
+
+      routeGroup = resolveRouteGroup({
         pathname,
-        url: parsedUrl,
+        metricsPath,
+        catalogConfig: routeConfigs?.stickerConfig || null,
+        userConfig: routeConfigs?.userConfig || null,
+        systemAdminConfig: routeConfigs?.systemAdminConfig || null,
       });
-      if (handledByCatalog) return;
     } catch (error) {
-      logger.error('Erro ao inicializar rotas web de sticker packs.', {
+      logger.error('Falha ao processar request HTTP.', {
+        path: pathname,
+        method: req.method,
         error: error?.message,
       });
-    }
 
-    const handledMetrics = await maybeHandleMetricsRoute(req, res, {
-      pathname,
-      metricsPath,
-    });
-    if (handledMetrics) return;
-
-    res.statusCode = 404;
-    res.end('Not Found');
+      if (!res.writableEnded) {
+        res.statusCode = 500;
+        res.setHeader('Content-Type', 'application/json; charset=utf-8');
+        res.end(JSON.stringify({ error: 'Internal Server Error' }));
+      }
+    }
   });
 
   server.listen(port, host, () => {
@@ -70,21 +90,41 @@ export const startHttpServer = () => {
       metrics_path: metricsPath,
     });
 
-    getStickerCatalogRouteConfig()
-      .then((config) => {
-        if (!config?.enabled) return;
-        logger.info('Catalogo web de sticker packs habilitado', {
-          web_path: config.webPath,
-          api_base_path: config.apiBasePath,
-          orphan_api_path: config.orphanApiPath,
-          data_public_path: config.dataPublicPath,
-          data_public_dir: config.dataPublicDir,
-          host,
-          port,
-        });
+    getIndexRouteConfigs()
+      .then(({ userConfig, systemAdminConfig, stickerConfig }) => {
+        if (userConfig?.webPath) {
+          logger.info('Rotas web de usuario habilitadas', {
+            web_path: userConfig.webPath,
+            api_base_path: userConfig.apiBasePath,
+            host,
+            port,
+          });
+        }
+
+        if (systemAdminConfig?.webPath) {
+          logger.info('Rotas system admin habilitadas', {
+            web_path: systemAdminConfig.webPath,
+            legacy_web_path: systemAdminConfig.legacyWebPath,
+            api_admin_base_path: systemAdminConfig.apiAdminBasePath,
+            host,
+            port,
+          });
+        }
+
+        if (stickerConfig?.enabled && stickerConfig?.webPath) {
+          logger.info('Catalogo web de sticker packs habilitado', {
+            web_path: stickerConfig.webPath,
+            api_base_path: stickerConfig.apiBasePath,
+            orphan_api_path: stickerConfig.orphanApiPath,
+            data_public_path: stickerConfig.dataPublicPath,
+            data_public_dir: stickerConfig.dataPublicDir,
+            host,
+            port,
+          });
+        }
       })
       .catch((error) => {
-        logger.warn('Nao foi possivel carregar configuracao do catalogo de sticker packs.', {
+        logger.warn('Nao foi possivel carregar configuracao das rotas na inicializacao.', {
           error: error?.message,
         });
       });

package/server/middleware/cachePolicy.js

@@ -0,0 +1,24 @@
+import { URL } from 'node:url';
+
+import { isAssetPath } from './cachePolicyHelpers.js';
+
+export const applyCachePolicy = (req, res, { pathname } = {}) => {
+  const resolvedPathname = pathname || new URL(req.url || '/', 'http://localhost').pathname;
+
+  if (isAssetPath(resolvedPathname)) {
+    res.setHeader('Cache-Control', 'public, max-age=31536000, immutable');
+    return;
+  }
+
+  if (resolvedPathname === '/sitemap.xml' || resolvedPathname.startsWith('/stickers')) {
+    res.setHeader('Cache-Control', 'public, max-age=60');
+    return;
+  }
+
+  if (resolvedPathname.startsWith('/api/')) {
+    res.setHeader('Cache-Control', 'no-store');
+    return;
+  }
+
+  res.setHeader('Cache-Control', 'no-store');
+};

package/server/middleware/cachePolicyHelpers.js

@@ -0,0 +1 @@
+export const isAssetPath = (pathname = '') => pathname === '/stickers/assets/styles.css' || pathname === '/stickers/assets/catalog.js' || pathname.startsWith('/stickers/assets/');

package/server/middleware/rateLimit.js

@@ -0,0 +1,89 @@
+const rateLimitBuckets = new Map();
+let pruneAt = 0;
+
+const parseNumber = (value, fallback, min, max) => {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.max(min, Math.min(max, Math.floor(parsed)));
+};
+
+const RATE_LIMIT_TRUST_PROXY = ['1', 'true', 'yes', 'on'].includes(
+  String(process.env.RATE_LIMIT_TRUST_PROXY || '')
+    .trim()
+    .toLowerCase(),
+);
+
+const getClientIp = (req) => {
+  if (RATE_LIMIT_TRUST_PROXY) {
+    const forwarded = req.headers['x-forwarded-for'];
+    if (typeof forwarded === 'string' && forwarded.trim()) {
+      const [first] = forwarded
+        .split(',')
+        .map((part) => part.trim())
+        .filter(Boolean);
+      if (first) return first;
+    }
+  }
+
+  return req.socket?.remoteAddress || 'unknown';
+};
+
+const pruneBuckets = (windowMs, nowMs) => {
+  if (nowMs - pruneAt < windowMs) return;
+  pruneAt = nowMs;
+
+  for (const [key, bucket] of rateLimitBuckets.entries()) {
+    if (nowMs - bucket.start > windowMs) {
+      rateLimitBuckets.delete(key);
+    }
+  }
+};
+
+const sendTooManyRequests = (req, res, retryAfterSeconds) => {
+  if (res.writableEnded) return;
+  res.statusCode = 429;
+  res.setHeader('Content-Type', 'application/json; charset=utf-8');
+  res.setHeader('Retry-After', String(Math.max(1, retryAfterSeconds)));
+  if (req.method === 'HEAD') {
+    res.end();
+    return;
+  }
+  res.end(JSON.stringify({ error: 'Too Many Requests' }));
+};
+
+export const createRateLimit = ({ windowMs = 60_000, max = 60, keyPrefix = 'global' } = {}) => {
+  const safeWindowMs = parseNumber(windowMs, 60_000, 1_000, 60 * 60 * 1000);
+  const safeMax = parseNumber(max, 60, 1, 100_000);
+  const safeKeyPrefix = String(keyPrefix || 'global').trim() || 'global';
+
+  return (req, res) => {
+    const nowMs = Date.now();
+    pruneBuckets(safeWindowMs, nowMs);
+
+    const ip = getClientIp(req);
+    const key = `${safeKeyPrefix}:${ip}`;
+    const existing = rateLimitBuckets.get(key);
+
+    if (!existing || nowMs - existing.start > safeWindowMs) {
+      rateLimitBuckets.set(key, { start: nowMs, count: 1 });
+      return true;
+    }
+
+    existing.count += 1;
+    if (existing.count <= safeMax) return true;
+
+    const retryAfterSeconds = Math.ceil((safeWindowMs - (nowMs - existing.start)) / 1000);
+    sendTooManyRequests(req, res, retryAfterSeconds);
+    return false;
+  };
+};
+
+export const createAdminApiRateLimit = () => {
+  const windowMs = parseNumber(process.env.ADMIN_RATE_LIMIT_WINDOW_MS, 60_000, 1_000, 60 * 60 * 1000);
+  const max = parseNumber(process.env.ADMIN_RATE_LIMIT_MAX, 30, 1, 100_000);
+  return createRateLimit({
+    windowMs,
+    max,
+    keyPrefix: 'admin_api',
+  });
+};

package/server/middleware/requestLogger.js

@@ -0,0 +1,16 @@
+import logger from '../../app/utils/logger/loggerModule.js';
+
+export const attachRequestLogger = (req, res, { pathname = '', requestId = '', startedAt = Date.now() } = {}) => {
+  if (req.__requestLoggerAttached) return;
+  req.__requestLoggerAttached = true;
+
+  res.once('finish', () => {
+    logger.info('HTTP request', {
+      request_id: requestId || null,
+      method: req.method || 'UNKNOWN',
+      path: pathname || null,
+      status_code: res.statusCode,
+      duration_ms: Math.max(0, Date.now() - Number(startedAt || Date.now())),
+    });
+  });
+};

package/server/middleware/requireAdminAuth.js

@@ -0,0 +1,42 @@
+import logger from '../../app/utils/logger/loggerModule.js';
+
+const ADMIN_TOKEN = String(process.env.ADMIN_TOKEN || process.env.ADMIN_API_TOKEN || '').trim();
+
+const extractAdminTokenFromRequest = (req) => {
+  const headerToken = String(req.headers['x-admin-token'] || '').trim();
+  if (headerToken) return headerToken;
+
+  const authorizationHeader = String(req.headers.authorization || '').trim();
+  if (!authorizationHeader) return '';
+
+  const match = authorizationHeader.match(/^Bearer\s+(.+)$/i);
+  return String(match?.[1] || '').trim();
+};
+
+const sendUnauthorized = (res) => {
+  if (res.writableEnded) return;
+  res.statusCode = 401;
+  res.setHeader('Content-Type', 'application/json; charset=utf-8');
+  res.setHeader('Cache-Control', 'no-store');
+  res.end(JSON.stringify({ error: 'Unauthorized' }));
+};
+
+/**
+ * Camada opcional de auth de admin.
+ * Quando `ADMIN_TOKEN` nao estiver configurado, delega para a auth interna do controller.
+ */
+export const requireAdminAuth = (req, res) => {
+  if (!ADMIN_TOKEN) return true;
+
+  const requestToken = extractAdminTokenFromRequest(req);
+  if (requestToken && requestToken === ADMIN_TOKEN) return true;
+
+  logger.warn('Tentativa de acesso admin sem token valido.', {
+    action: 'admin_auth_token_invalid',
+    method: req.method || 'UNKNOWN',
+    path: req.url || '',
+    remote_address: req.socket?.remoteAddress || null,
+  });
+  sendUnauthorized(res);
+  return false;
+};

package/server/middleware/securityHeaders.js

@@ -0,0 +1,6 @@
+export const applySecurityHeaders = (_req, res) => {
+  res.setHeader('X-Content-Type-Options', 'nosniff');
+  res.setHeader('X-Frame-Options', 'DENY');
+  res.setHeader('Referrer-Policy', 'strict-origin-when-cross-origin');
+  res.setHeader('Permissions-Policy', 'geolocation=(), microphone=(), camera=()');
+};

package/server/routes/admin/systemAdminRouter.js

@@ -0,0 +1,56 @@
+let systemAdminControllerPromise = null;
+
+const loadSystemAdminController = async () => {
+  if (!systemAdminControllerPromise) {
+    systemAdminControllerPromise = import('../../controllers/systemAdminController.js');
+  }
+  return systemAdminControllerPromise;
+};
+
+const normalizeBasePath = (value, fallback) => {
+  const raw = String(value || '').trim() || fallback;
+  const withLeadingSlash = raw.startsWith('/') ? raw : `/${raw}`;
+  const withoutTrailingSlash = withLeadingSlash.length > 1 && withLeadingSlash.endsWith('/') ? withLeadingSlash.slice(0, -1) : withLeadingSlash;
+  return withoutTrailingSlash || fallback;
+};
+
+const startsWithPath = (pathname, prefix) => {
+  if (!pathname || !prefix) return false;
+  if (pathname === prefix) return true;
+  return pathname.startsWith(`${prefix}/`);
+};
+
+const DEFAULT_USER_SYSTEM_ADMIN_WEB_PATH = '/user/systemadm';
+const DEFAULT_LEGACY_STICKER_ADMIN_WEB_PATH = '/stickers/admin';
+const DEFAULT_STICKER_ADMIN_API_BASE_PATH = '/api/sticker-packs/admin';
+const DEFAULT_STICKER_ADMIN_API_SESSION_PATH = '/api/sticker-packs/admin/session';
+
+export const getSystemAdminRouterConfig = async () => {
+  const controller = await loadSystemAdminController();
+  const legacyConfig = (typeof controller?.getSystemAdminRouteConfig === 'function' ? controller.getSystemAdminRouteConfig() : null) || {};
+  return {
+    webPath: normalizeBasePath(legacyConfig.webPath, DEFAULT_USER_SYSTEM_ADMIN_WEB_PATH),
+    legacyWebPath: normalizeBasePath(legacyConfig.legacyWebPath, DEFAULT_LEGACY_STICKER_ADMIN_WEB_PATH),
+    apiAdminBasePath: normalizeBasePath(legacyConfig.apiAdminBasePath, DEFAULT_STICKER_ADMIN_API_BASE_PATH),
+    apiAdminSessionPath: normalizeBasePath(legacyConfig.apiAdminSessionPath, DEFAULT_STICKER_ADMIN_API_SESSION_PATH),
+  };
+};
+
+export const shouldHandleSystemAdminPath = (pathname, systemAdminConfig = null) => {
+  const resolvedConfig = systemAdminConfig || {
+    webPath: DEFAULT_USER_SYSTEM_ADMIN_WEB_PATH,
+    legacyWebPath: DEFAULT_LEGACY_STICKER_ADMIN_WEB_PATH,
+    apiAdminBasePath: DEFAULT_STICKER_ADMIN_API_BASE_PATH,
+    apiAdminSessionPath: DEFAULT_STICKER_ADMIN_API_SESSION_PATH,
+  };
+
+  if (startsWithPath(pathname, resolvedConfig.webPath)) return true;
+  if (startsWithPath(pathname, resolvedConfig.legacyWebPath)) return true;
+  return false;
+};
+
+export const maybeHandleSystemAdminRequest = async (req, res, { pathname, url }) => {
+  const controller = await loadSystemAdminController();
+  if (typeof controller?.maybeHandleSystemAdminRequest !== 'function') return false;
+  return controller.maybeHandleSystemAdminRequest(req, res, { pathname, url });
+};

package/server/routes/health/healthRouter.js

@@ -0,0 +1,41 @@
+const sendJson = (req, res, statusCode, payload) => {
+  if (res.writableEnded) return true;
+  res.statusCode = statusCode;
+  res.setHeader('Content-Type', 'application/json; charset=utf-8');
+  if (req.method === 'HEAD') {
+    res.end();
+    return true;
+  }
+  res.end(JSON.stringify(payload));
+  return true;
+};
+
+const isAllowedMethod = (method) => method === 'GET' || method === 'HEAD';
+
+export const shouldHandleHealthPath = (pathname) => pathname === '/healthz' || pathname === '/readyz';
+
+export const maybeHandleHealthRequest = async (req, res, { pathname }) => {
+  if (!shouldHandleHealthPath(pathname)) return false;
+
+  if (!isAllowedMethod(req.method || '')) {
+    return sendJson(req, res, 405, { error: 'Method Not Allowed' });
+  }
+
+  if (pathname === '/healthz') {
+    return sendJson(req, res, 200, {
+      ok: true,
+      service: 'omnizap',
+      type: 'health',
+    });
+  }
+
+  if (pathname === '/readyz') {
+    return sendJson(req, res, 200, {
+      ok: true,
+      service: 'omnizap',
+      type: 'ready',
+    });
+  }
+
+  return false;
+};