@mattrika/server-utils 0.0.0-stage → 1.0.0

package/index.cjs.js

@@ -0,0 +1,426 @@
+'use strict';
+
+var fs = require('fs');
+var path = require('path');
+var pino = require('pino');
+var httpException = require('hono/http-exception');
+var zodOpenapi = require('@hono/zod-openapi');
+var crypto = require('crypto');
+var argon2 = require('@node-rs/argon2');
+var httpStatusCodes = require('stoker/http-status-codes');
+var esToolkit = require('es-toolkit');
+var jwt = require('hono/jwt');
+
+const DEFAULT_PAGE_SIZE = 20;
+const MAX_PAGE_SIZE = 100;
+
+const MAX_SIZE = 1024 * 1024; // 1MB
+async function safeResponseBody(res) {
+  try {
+    const contentType = res.headers.get('content-type') || '';
+    const disposition = res.headers.get('content-disposition') || '';
+    // ❌ Skip downloads
+    if (disposition.includes('attachment')) {
+      return '[FILE DOWNLOAD SKIPPED]';
+    }
+    // ❌ Skip non-JSON responses
+    if (!contentType.includes('application/json')) {
+      return '[NON-JSON RESPONSE]';
+    }
+    const text = await res.clone().text();
+    if (!text) return undefined;
+    const size = Buffer.byteLength(text, 'utf8');
+    if (size > MAX_SIZE) return `[RESPONSE TOO LARGE: ${Math.round(size / 1024)} KB]`;
+    return JSON.parse(text);
+  } catch {
+    return '[UNREADABLE RESPONSE]';
+  }
+}
+async function safeRequestBody(req) {
+  try {
+    const contentType = req.header('content-type') || '';
+    // ❌ Skip file uploads
+    if (contentType.includes('multipart/form-data')) {
+      return '[FILE UPLOAD SKIPPED]';
+    }
+    if (!contentType.includes('application/json')) {
+      return undefined;
+    }
+    const text = await req.raw.clone().text();
+    if (!text) return undefined;
+    const size = Buffer.byteLength(text, 'utf8');
+    if (size > MAX_SIZE) return `[BODY TOO LARGE: ${Math.round(size / 1024)} KB]`;
+    return JSON.parse(text);
+  } catch {
+    return '[UNREADABLE REQUEST BODY]';
+  }
+}
+function ensureDirExists(filePath) {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, {
+      recursive: true
+    });
+  }
+}
+
+/**
+ * Checks whether APP_ENV environment variable is set to 'production' or NODE_ENV environment variable is set to 'production', in that order.
+ * @returns boolean
+ */
+function isProductionAppEnvironment() {
+  const appEnv = process?.env?.['APP_ENV'];
+  if (appEnv === 'production') return true;
+  const nodeEnv = process?.env?.['NODE_ENV'];
+  if (nodeEnv === 'production') return true;
+  return false;
+}
+
+const logFilePath = './logs/app.log';
+let transport;
+function pinoLogger() {
+  const isProd = isProductionAppEnvironment();
+  try {
+    // ensure logs folder exists
+    ensureDirExists(logFilePath);
+    transport = isProd ? pino.transport({
+      target: 'pino/file',
+      options: {
+        destination: logFilePath
+      }
+    }) : pino.transport({
+      targets: [{
+        target: 'pino-pretty',
+        options: {
+          colorize: true,
+          levelFirst: true,
+          translateTime: 'SYS:standard'
+        }
+      }]
+    });
+  } catch (err) {
+    console.error('⚠️ Logger file transport failed, falling back to stdout', err);
+    transport = undefined;
+  }
+  return pino({
+    level: process.env?.['PINO_LOG_LEVEL'] || 'info',
+    timestamp: pino.stdTimeFunctions.isoTime,
+    formatters: {
+      bindings: bindings => ({
+        pid: bindings?.['pid'],
+        host: bindings?.['hostname'],
+        node_version: process.version
+      })
+    },
+    redact: {
+      paths: ['req.headers.authorization', 'req.headers.cookie', 'req.body.password', 'req.body.confirmPassword', 'req.body.oldPassword', 'req.body.newPassword', 'req.body.token', 'req.body.refreshToken', 'req.body.accessToken', 'req.body.*.password', 'req.body.*.token', 'req.body.*.refreshToken', 'req.body.*.accessToken', 'res.body.token', 'res.body.refreshToken', 'res.body.accessToken', 'res.body.data.token', 'res.body.data.refreshToken', 'res.body.data.accessToken', 'res.body.*.token', 'res.body.*.refreshToken', 'res.body.*.accessToken'],
+      censor: '[REDACTED]'
+    }
+  }, transport);
+}
+
+const pinoLoggerMiddleware = () => {
+  return async (c, next) => {
+    const start = Date.now();
+    const logger = pinoLogger();
+    const childLogger = logger.child({
+      requestId: c.var['requestId'],
+      req: {
+        method: c.req.method,
+        path: c.req.path,
+        query: c.req.query(),
+        headers: c.req.header(),
+        body: c.req.method !== 'GET' ? await safeRequestBody(c.req) : undefined
+      }
+    });
+    c.set('logger', childLogger);
+    childLogger.info('Incoming request');
+    try {
+      await next();
+      const responseBody = await safeResponseBody(c.res);
+      childLogger.info({
+        res: {
+          status: c.res.status,
+          durationMs: Date.now() - start,
+          body: responseBody
+        }
+      }, 'Request completed');
+    } catch (err) {
+      if (err instanceof httpException.HTTPException) {
+        childLogger.warn({
+          res: {
+            status: err.status
+          },
+          error: err.message
+        }, 'HTTP error');
+        throw err;
+      }
+      childLogger.error({
+        err
+      }, 'Unhandled server error');
+      throw err;
+    }
+  };
+};
+
+const zPagination = zodOpenapi.z.object({
+  page: zodOpenapi.z.coerce.number().optional(),
+  size: zodOpenapi.z.coerce.number().optional()
+});
+const zCommonQuery = zodOpenapi.z.object({
+  search: zodOpenapi.z.string().optional(),
+  orderBy: zodOpenapi.z.string().optional(),
+  sortOrder: zodOpenapi.z.enum(['asc', 'desc']).optional()
+}).extend(zPagination.shape);
+const zId = zodOpenapi.z.object({
+  id: zodOpenapi.z.string()
+});
+const zIds = zodOpenapi.z.object({
+  ids: zodOpenapi.z.array(zodOpenapi.z.string()).min(1)
+});
+const zPassword = zodOpenapi.z.string().min(8).max(128).regex(/[A-Z]/, 'Must contain at least one uppercase letter').regex(/[0-9]/, 'Must contain at least one number').regex(/[^A-Za-z0-9\s]/, 'Must contain at least one special character');
+const zEmpty = zodOpenapi.z.object({});
+const zFile = zodOpenapi.z.object({
+  file: zodOpenapi.z.instanceof(File).openapi({
+    type: 'string',
+    format: 'binary'
+  }).optional(),
+  files: zodOpenapi.z.array(zodOpenapi.z.instanceof(File).openapi({
+    type: 'string',
+    format: 'binary'
+  })).optional()
+});
+
+// `argon2.Algorithm` is an ambient `const enum`, so its members cannot be
+// accessed when `isolatedModules` is enabled. Argon2id === 2; typing the
+// literal against the library's own option type keeps it type-safe.
+const ARGON2ID = 2;
+class CryptoService {
+  static async hash(plain) {
+    return argon2.hash(plain, {
+      algorithm: ARGON2ID,
+      memoryCost: 1 << 16,
+      // 64 MB
+      timeCost: 3,
+      parallelism: 1
+    });
+  }
+  static async verify(plain, hash) {
+    return argon2.verify(hash, plain);
+  }
+  static random64chars() {
+    // 32 bytes hex -> 64 hex chars
+    return crypto.randomBytes(32).toString('hex');
+  }
+}
+
+const zResponsePagination = zodOpenapi.z.object({
+  page: zodOpenapi.z.number(),
+  size: zodOpenapi.z.number(),
+  totalItems: zodOpenapi.z.number(),
+  totalPages: zodOpenapi.z.number()
+});
+function ApiResponse(dataSchema, description) {
+  return {
+    content: {
+      'application/json': {
+        schema: zodOpenapi.z.object({
+          data: dataSchema,
+          message: zodOpenapi.z.string(),
+          success: zodOpenapi.z.boolean(),
+          error: zodOpenapi.z.any().optional(),
+          meta: zodOpenapi.z.any().optional()
+        })
+      }
+    },
+    description
+  };
+}
+function ApiListResponse(dataSchema, description) {
+  return {
+    content: {
+      'application/json': {
+        schema: zodOpenapi.z.object({
+          data: dataSchema,
+          message: zodOpenapi.z.string(),
+          success: zodOpenapi.z.boolean(),
+          error: zodOpenapi.z.any().optional(),
+          meta: zodOpenapi.z.any().optional(),
+          pagination: zResponsePagination
+        })
+      }
+    },
+    description
+  };
+}
+// 1. Base Stream Schema
+const zStreamResponse = zodOpenapi.z.object({
+  body: zodOpenapi.z.custom(val => val instanceof ReadableStream, {
+    message: 'Body must be a ReadableStream'
+  }),
+  headers: zodOpenapi.z.object({
+    'Content-Type': zodOpenapi.z.string().default('application/octet-stream'),
+    'Content-Disposition': zodOpenapi.z.string().refine(val => val.startsWith('inline; filename="'), {
+      message: 'Must follow format: inline; filename="..."'
+    })
+  }).optional()
+});
+// 2. Generic API Response for ReadableStream
+function StreamResponse(description) {
+  return {
+    content: {
+      'application/octet-stream': {
+        schema: zStreamResponse
+      }
+    },
+    description
+  };
+}
+function ApiPdfResponse(description) {
+  return {
+    content: {
+      'application/pdf': {
+        schema: zodOpenapi.z.object({
+          format: zodOpenapi.z.literal('binary'),
+          type: zodOpenapi.z.literal('string')
+        })
+      }
+    },
+    description
+  };
+}
+
+function throwHttpError(error, defaultMessage = 'Something went wrong') {
+  const code = error instanceof Error ? Number.isNaN(error.cause) ? httpStatusCodes.INTERNAL_SERVER_ERROR : error.cause : httpStatusCodes.INTERNAL_SERVER_ERROR;
+  throw new httpException.HTTPException(code, {
+    message: error.message ?? defaultMessage
+  });
+}
+function isUniqueViolationPg(error) {
+  const e = error;
+  return e?.code === '23505'; // unique_violation
+}
+
+function toErrorCode(value) {
+  if (value === undefined || value === null || Number.isNaN(value)) {
+    return 500;
+  }
+  return typeof value === 'number' ? Math.max(value, 0) : 500;
+}
+function onErrorFn(debugLog = true) {
+  return async (err, c) => {
+    const statusCode = 'status' in err ? toErrorCode(err.status) : 'cause' in err ? toErrorCode(err.cause) : httpStatusCodes.INTERNAL_SERVER_ERROR;
+    const logger = c.get('logger');
+    logger.error({
+      err,
+      path: c.req.path,
+      method: c.req.method
+    }, 'Request failed');
+    if (debugLog) {
+      console.error(JSON.stringify(err, undefined, 2));
+    }
+    return c.json({
+      data: null,
+      error: !debugLog ? undefined : err,
+      message: err.cause ?? err.message,
+      success: false
+    }, statusCode);
+  };
+}
+
+const notFoundFn = c => {
+  return c.json({
+    success: false,
+    error: 'Not Found',
+    data: {},
+    message: `Not Found - ${c.req.path}`
+  }, httpStatusCodes.NOT_FOUND);
+};
+
+function buildPaginationResponse(page, size, total) {
+  const numPage = esToolkit.clamp(Number(page), 1) || 1;
+  const positivePage = numPage < 1 ? 1 : numPage;
+  const numSize = esToolkit.clamp(Number(size), DEFAULT_PAGE_SIZE);
+  const numTotal = esToolkit.clamp(Number(total), 0);
+  const totalPages = Math.ceil(numTotal / numSize);
+  return {
+    page: positivePage,
+    size: numSize,
+    totalItems: numTotal,
+    totalPages
+  };
+}
+
+class TokenUtil {
+  alg;
+  secret;
+  constructor(secret, alg = 'HS256') {
+    this.alg = alg;
+    this.secret = secret;
+  }
+  async create(payload, lifeSeconds = 15 * 60) {
+    if (payload.exp === undefined) {
+      // JWT NumericDate claims (`exp`) are seconds since the epoch.
+      payload.exp = Math.floor(Date.now() / 1000) + lifeSeconds;
+    }
+    return await jwt.sign(payload, this.secret, this.alg);
+  }
+  async decode(token) {
+    return await jwt.verify(token, this.secret, this.alg);
+  }
+  async decodeUnexpired(token) {
+    // Disable Hono's built-in `exp` check so an expired token resolves to
+    // `null` instead of throwing, then validate it here.
+    const {
+      exp,
+      ...rest
+    } = await jwt.verify(token, this.secret, {
+      alg: this.alg,
+      exp: false
+    });
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    if (exp !== undefined && exp <= nowSeconds) return null;
+    return {
+      exp: exp,
+      ...rest
+    };
+  }
+}
+
+function validationHook(result, _c) {
+  if (!result.success) {
+    throwHttpError(new Error('Validation error', {
+      cause: httpStatusCodes.UNPROCESSABLE_ENTITY
+    }));
+  }
+}
+
+exports.ApiListResponse = ApiListResponse;
+exports.ApiPdfResponse = ApiPdfResponse;
+exports.ApiResponse = ApiResponse;
+exports.CryptoService = CryptoService;
+exports.DEFAULT_PAGE_SIZE = DEFAULT_PAGE_SIZE;
+exports.MAX_PAGE_SIZE = MAX_PAGE_SIZE;
+exports.StreamResponse = StreamResponse;
+exports.TokenUtil = TokenUtil;
+exports.buildPaginationResponse = buildPaginationResponse;
+exports.ensureDirExists = ensureDirExists;
+exports.isProductionAppEnvironment = isProductionAppEnvironment;
+exports.isUniqueViolationPg = isUniqueViolationPg;
+exports.notFoundFn = notFoundFn;
+exports.onErrorFn = onErrorFn;
+exports.pinoLogger = pinoLogger;
+exports.pinoLoggerMiddleware = pinoLoggerMiddleware;
+exports.safeRequestBody = safeRequestBody;
+exports.safeResponseBody = safeResponseBody;
+exports.throwHttpError = throwHttpError;
+exports.validationHook = validationHook;
+exports.zCommonQuery = zCommonQuery;
+exports.zEmpty = zEmpty;
+exports.zFile = zFile;
+exports.zId = zId;
+exports.zIds = zIds;
+exports.zPagination = zPagination;
+exports.zPassword = zPassword;
+exports.zResponsePagination = zResponsePagination;
+exports.zStreamResponse = zStreamResponse;

package/index.cjs.mjs

@@ -0,0 +1,2 @@
+export * from './index.cjs.js';
+export { _default as default } from './index.cjs.default.js';

package/index.d.ts

@@ -0,0 +1 @@
+export * from "./src/index";