aegisnode 0.0.1

package/src/runtime/loaders.js

@@ -0,0 +1,46 @@
+import path from 'path';
+import { pathToFileURL } from 'url';
+
+async function resolveLoader(loaderEntry, rootDir) {
+  if (typeof loaderEntry === 'function') {
+    return { loader: loaderEntry, options: {} };
+  }
+
+  if (typeof loaderEntry === 'string') {
+    const filePath = path.isAbsolute(loaderEntry)
+      ? loaderEntry
+      : path.join(rootDir, loaderEntry);
+    const loaded = await import(pathToFileURL(filePath).href);
+    return { loader: loaded.default ?? loaded, options: {} };
+  }
+
+  if (loaderEntry && typeof loaderEntry === 'object' && typeof loaderEntry.path === 'string') {
+    const filePath = path.isAbsolute(loaderEntry.path)
+      ? loaderEntry.path
+      : path.join(rootDir, loaderEntry.path);
+    const loaded = await import(pathToFileURL(filePath).href);
+    return {
+      loader: loaded.default ?? loaded,
+      options: loaderEntry.options || {},
+    };
+  }
+
+  throw new Error(`Invalid loader entry: ${JSON.stringify(loaderEntry)}`);
+}
+
+export async function runLoaders(loaderEntries, context, rootDir, logger) {
+  if (!Array.isArray(loaderEntries) || loaderEntries.length === 0) {
+    return;
+  }
+
+  for (const entry of loaderEntries) {
+    const { loader, options } = await resolveLoader(entry, rootDir);
+
+    if (typeof loader !== 'function') {
+      throw new Error('Loader module must export a function.');
+    }
+
+    logger.info('Running loader: %s', typeof entry === 'string' ? entry : 'inline-loader');
+    await loader({ ...context, options });
+  }
+}

package/src/runtime/logger.js

@@ -0,0 +1,56 @@
+import util from 'util';
+
+const LEVEL_ORDER = {
+  error: 0,
+  warn: 1,
+  info: 2,
+  debug: 3,
+  trace: 4,
+};
+
+function toLevel(level) {
+  if (!level) {
+    return 'info';
+  }
+
+  const normalized = String(level).toLowerCase();
+  return Object.prototype.hasOwnProperty.call(LEVEL_ORDER, normalized) ? normalized : 'info';
+}
+
+export function createLogger({ level = 'info', name = 'aegisnode' } = {}) {
+  const currentLevel = toLevel(level);
+
+  function shouldLog(candidateLevel) {
+    return LEVEL_ORDER[candidateLevel] <= LEVEL_ORDER[currentLevel];
+  }
+
+  function formatLine(candidateLevel, message, args) {
+    const timestamp = new Date().toISOString();
+    const rendered = util.format(message, ...args);
+    return [`[${timestamp}]`, `[${name}]`, `[${candidateLevel.toUpperCase()}]`, rendered];
+  }
+
+  return {
+    level: currentLevel,
+    error(message, ...args) {
+      if (!shouldLog('error')) return;
+      console.error(...formatLine('error', message, args));
+    },
+    warn(message, ...args) {
+      if (!shouldLog('warn')) return;
+      console.warn(...formatLine('warn', message, args));
+    },
+    info(message, ...args) {
+      if (!shouldLog('info')) return;
+      console.info(...formatLine('info', message, args));
+    },
+    debug(message, ...args) {
+      if (!shouldLog('debug')) return;
+      console.debug(...formatLine('debug', message, args));
+    },
+    trace(message, ...args) {
+      if (!shouldLog('trace')) return;
+      console.debug(...formatLine('trace', message, args));
+    },
+  };
+}

package/src/runtime/mail.js

@@ -0,0 +1,225 @@
+import nodemailer from 'nodemailer';
+
+function isPlainObject(value) {
+  return Boolean(value) && Object.prototype.toString.call(value) === '[object Object]';
+}
+
+function asNonEmptyString(value, fallback = '') {
+  if (typeof value !== 'string') {
+    return fallback;
+  }
+
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : fallback;
+}
+
+function asPositiveInteger(value, fallback) {
+  const parsed = Number(value);
+  if (Number.isFinite(parsed) && parsed > 0) {
+    return Math.floor(parsed);
+  }
+  return fallback;
+}
+
+function isConfiguredTransport(value) {
+  if (typeof value === 'string') {
+    return value.trim().length > 0;
+  }
+
+  return isPlainObject(value) && Object.keys(value).length > 0;
+}
+
+function normalizeMailDefaults(rawDefaults, rawMail) {
+  const defaults = isPlainObject(rawDefaults) ? rawDefaults : {};
+
+  return {
+    ...defaults,
+    from: asNonEmptyString(defaults.from, asNonEmptyString(rawMail?.from)),
+    replyTo: asNonEmptyString(defaults.replyTo, asNonEmptyString(rawMail?.replyTo)),
+  };
+}
+
+export function normalizeMailConfig(rawMail) {
+  if (rawMail === false || rawMail === null || rawMail === undefined) {
+    return {
+      enabled: false,
+      defaults: {},
+      transport: {},
+      transportFactory: null,
+      transporter: null,
+      verifyOnStartup: false,
+    };
+  }
+
+  const mail = isPlainObject(rawMail) ? rawMail : {};
+  const transport = typeof mail.transport === 'string' && mail.transport.trim().length > 0
+    ? mail.transport.trim()
+    : isPlainObject(mail.transport)
+      ? { ...mail.transport }
+      : {};
+  const transporter = mail.transporter && typeof mail.transporter.sendMail === 'function'
+    ? mail.transporter
+    : null;
+  const transportFactory = typeof mail.transportFactory === 'function'
+    ? mail.transportFactory
+    : null;
+
+  const enabled = mail.enabled === true
+    || transporter !== null
+    || transportFactory !== null
+    || isConfiguredTransport(transport);
+
+  return {
+    enabled,
+    defaults: normalizeMailDefaults(mail.defaults, mail),
+    transport,
+    transportFactory,
+    transporter,
+    verifyOnStartup: mail.verifyOnStartup === true,
+  };
+}
+
+function createMailDisabledError() {
+  const error = new Error('Mail is disabled. Enable settings.mail and configure a transport to send email.');
+  error.code = 'AEGIS_MAIL_DISABLED';
+  error.statusCode = 503;
+  return error;
+}
+
+function normalizeEnvelopeField(value) {
+  if (Array.isArray(value)) {
+    const normalized = value
+      .map((entry) => (typeof entry === 'string' ? entry.trim() : entry))
+      .filter(Boolean);
+    return normalized.length > 0 ? normalized : null;
+  }
+
+  if (typeof value === 'string' && value.trim().length > 0) {
+    return value.trim();
+  }
+
+  return null;
+}
+
+function listRecipients(payload) {
+  return ['to', 'cc', 'bcc']
+    .map((field) => normalizeEnvelopeField(payload[field]))
+    .flatMap((value) => (Array.isArray(value) ? value : value ? [value] : []));
+}
+
+function buildMailPayload(message, mailConfig) {
+  if (!isPlainObject(message)) {
+    throw new Error('Mail payload must be an object.');
+  }
+
+  const payload = {
+    ...mailConfig.defaults,
+    ...message,
+  };
+
+  if (!payload.from && mailConfig.defaults.from) {
+    payload.from = mailConfig.defaults.from;
+  }
+
+  if (!payload.replyTo && mailConfig.defaults.replyTo) {
+    payload.replyTo = mailConfig.defaults.replyTo;
+  }
+
+  const hasRecipient = Boolean(
+    normalizeEnvelopeField(payload.to)
+    || normalizeEnvelopeField(payload.cc)
+    || normalizeEnvelopeField(payload.bcc),
+  );
+
+  if (!hasRecipient) {
+    throw new Error('Mail payload must include at least one recipient in "to", "cc", or "bcc".');
+  }
+
+  if (!payload.from) {
+    throw new Error('Mail payload must include "from" or configure settings.mail.defaults.from.');
+  }
+
+  return payload;
+}
+
+async function resolveTransporter(mailConfig) {
+  if (mailConfig.transporter) {
+    return mailConfig.transporter;
+  }
+
+  if (mailConfig.transportFactory) {
+    const created = await mailConfig.transportFactory(mailConfig);
+    if (!created || typeof created.sendMail !== 'function') {
+      throw new Error('settings.mail.transportFactory must return a transporter with sendMail().');
+    }
+    return created;
+  }
+
+  return nodemailer.createTransport(mailConfig.transport);
+}
+
+export async function createMailManager(rawMailConfig, logger) {
+  const mailConfig = normalizeMailConfig(rawMailConfig);
+  const runtimeLogger = logger && typeof logger.info === 'function'
+    ? logger
+    : { info() {} };
+
+  if (!mailConfig.enabled) {
+    const disabled = async () => {
+      throw createMailDisabledError();
+    };
+
+    return {
+      enabled: false,
+      config: mailConfig,
+      transporter: null,
+      send: disabled,
+      sendMail: disabled,
+      verify: disabled,
+      close: async () => {},
+    };
+  }
+
+  const transporter = await resolveTransporter(mailConfig);
+
+  if (mailConfig.verifyOnStartup && typeof transporter.verify === 'function') {
+    await transporter.verify();
+    runtimeLogger.info('Mail transport verified successfully.');
+  }
+
+  const send = async (message) => {
+    const payload = buildMailPayload(message, mailConfig);
+    const info = await transporter.sendMail(payload);
+    const recipients = listRecipients(payload).join(', ') || '(none)';
+    runtimeLogger.info(
+      'Mail sent: messageId=%s to=%s',
+      info?.messageId || '(none)',
+      recipients,
+    );
+    return info;
+  };
+
+  const verify = async () => {
+    if (typeof transporter.verify !== 'function') {
+      return true;
+    }
+
+    return transporter.verify();
+  };
+
+  const close = async () => {
+    if (typeof transporter.close === 'function') {
+      await transporter.close();
+    }
+  };
+
+  return {
+    enabled: true,
+    config: mailConfig,
+    transporter,
+    send,
+    sendMail: send,
+    verify,
+    close,
+  };
+}

package/src/runtime/upload.js

@@ -0,0 +1,272 @@
+import crypto from 'crypto';
+import fs from 'fs/promises';
+import path from 'path';
+import multer from 'multer';
+
+function asNonEmptyString(value, fallback = '') {
+  if (typeof value !== 'string') {
+    return fallback;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : fallback;
+}
+
+function asPositiveInteger(value, fallback) {
+  const parsed = Number(value);
+  if (Number.isFinite(parsed) && parsed > 0) {
+    return Math.floor(parsed);
+  }
+  return fallback;
+}
+
+function parseBytes(value, fallback) {
+  if (typeof value === 'number' && Number.isFinite(value) && value > 0) {
+    return Math.floor(value);
+  }
+
+  if (typeof value !== 'string') {
+    return fallback;
+  }
+
+  const normalized = value.trim().toLowerCase();
+  if (!normalized) {
+    return fallback;
+  }
+
+  const match = normalized.match(/^(\d+(?:\.\d+)?)\s*(b|kb|mb|gb)?$/i);
+  if (!match) {
+    return fallback;
+  }
+
+  const amount = Number(match[1]);
+  if (!Number.isFinite(amount) || amount <= 0) {
+    return fallback;
+  }
+
+  const unit = String(match[2] || 'b').toLowerCase();
+  const multiplier = unit === 'gb'
+    ? 1024 * 1024 * 1024
+    : unit === 'mb'
+      ? 1024 * 1024
+      : unit === 'kb'
+        ? 1024
+        : 1;
+
+  return Math.max(1, Math.floor(amount * multiplier));
+}
+
+function normalizeStringList(value, { lowerCase = false } = {}) {
+  const source = Array.isArray(value)
+    ? value
+    : (typeof value === 'string' ? value.split(',') : []);
+
+  const normalized = source
+    .map((entry) => asNonEmptyString(entry))
+    .filter(Boolean)
+    .map((entry) => (lowerCase ? entry.toLowerCase() : entry));
+
+  return [...new Set(normalized)];
+}
+
+function normalizeExtensions(value) {
+  return normalizeStringList(value, { lowerCase: true })
+    .map((entry) => (entry.startsWith('.') ? entry : `.${entry}`));
+}
+
+function normalizeUploadDirectory(rawDir, rootDir) {
+  const dir = asNonEmptyString(rawDir, 'uploads');
+  return path.isAbsolute(dir) ? dir : path.join(rootDir, dir);
+}
+
+export function normalizeUploadsConfig(rawUploads, rootDir) {
+  const uploads = rawUploads && typeof rawUploads === 'object' ? rawUploads : {};
+  const directory = normalizeUploadDirectory(uploads.dir, rootDir);
+
+  return {
+    enabled: uploads.enabled !== false,
+    dir: asNonEmptyString(uploads.dir, 'uploads'),
+    directory,
+    createDir: uploads.createDir !== false,
+    preserveExtension: uploads.preserveExtension !== false,
+    maxFileSize: parseBytes(uploads.maxFileSize, 5 * 1024 * 1024),
+    maxFiles: asPositiveInteger(uploads.maxFiles, 5),
+    maxFields: asPositiveInteger(uploads.maxFields, 50),
+    maxFieldSize: parseBytes(uploads.maxFieldSize, 1024 * 1024),
+    allowedMimeTypes: normalizeStringList(uploads.allowedMimeTypes, { lowerCase: true }),
+    allowedExtensions: normalizeExtensions(uploads.allowedExtensions),
+    allowApiMultipart: uploads.allowApiMultipart !== false,
+  };
+}
+
+function randomName(bytes = 16) {
+  if (typeof crypto.randomUUID === 'function') {
+    return crypto.randomUUID().replace(/-/g, '');
+  }
+  return crypto.randomBytes(bytes).toString('hex');
+}
+
+function getExtension(fileName, preserveExtension) {
+  if (!preserveExtension) {
+    return '';
+  }
+  const ext = path.extname(String(fileName || '')).toLowerCase();
+  return ext && ext.length <= 10 ? ext : '';
+}
+
+function createUploadError(code, message, statusCode) {
+  const error = new Error(message);
+  error.code = code;
+  error.statusCode = statusCode;
+  return error;
+}
+
+function resolveUploadError(error) {
+  if (!error) {
+    return null;
+  }
+
+  if (typeof error.statusCode === 'number' && error.statusCode >= 400) {
+    return error;
+  }
+
+  const multerCode = String(error.code || '');
+  switch (multerCode) {
+    case 'LIMIT_FILE_SIZE':
+      return createUploadError(multerCode, 'Uploaded file exceeds the configured size limit.', 413);
+    case 'LIMIT_FILE_COUNT':
+      return createUploadError(multerCode, 'Too many files uploaded.', 413);
+    case 'LIMIT_FIELD_COUNT':
+      return createUploadError(multerCode, 'Too many form fields submitted.', 413);
+    case 'LIMIT_FIELD_VALUE':
+      return createUploadError(multerCode, 'A form field exceeds the configured size limit.', 413);
+    case 'LIMIT_UNEXPECTED_FILE':
+      return createUploadError(multerCode, 'Unexpected file field.', 400);
+    default:
+      return createUploadError('UPLOAD_ERROR', error.message || 'Upload failed.', 400);
+  }
+}
+
+function createDiskStorage(uploadConfig) {
+  return multer.diskStorage({
+    destination(_req, _file, callback) {
+      callback(null, uploadConfig.directory);
+    },
+    filename(_req, file, callback) {
+      callback(null, `${randomName()}${getExtension(file?.originalname, uploadConfig.preserveExtension)}`);
+    },
+  });
+}
+
+function createFileFilter(uploadConfig) {
+  return (_req, file, callback) => {
+    const mimeType = String(file?.mimetype || '').toLowerCase();
+    const extension = path.extname(String(file?.originalname || '')).toLowerCase();
+
+    if (
+      uploadConfig.allowedMimeTypes.length > 0
+      && !uploadConfig.allowedMimeTypes.includes(mimeType)
+    ) {
+      callback(createUploadError(
+        'AEGIS_UPLOAD_MIME_NOT_ALLOWED',
+        `File type "${mimeType || 'unknown'}" is not allowed.`,
+        415,
+      ));
+      return;
+    }
+
+    if (
+      uploadConfig.allowedExtensions.length > 0
+      && !uploadConfig.allowedExtensions.includes(extension)
+    ) {
+      callback(createUploadError(
+        'AEGIS_UPLOAD_EXTENSION_NOT_ALLOWED',
+        `File extension "${extension || '(none)'}" is not allowed.`,
+        415,
+      ));
+      return;
+    }
+
+    callback(null, true);
+  };
+}
+
+function createMulterOptions(uploadConfig) {
+  return {
+    storage: createDiskStorage(uploadConfig),
+    limits: {
+      fileSize: uploadConfig.maxFileSize,
+      files: uploadConfig.maxFiles,
+      fields: uploadConfig.maxFields,
+      fieldSize: uploadConfig.maxFieldSize,
+    },
+    fileFilter: createFileFilter(uploadConfig),
+  };
+}
+
+function wrapUploadMiddleware(middleware) {
+  return (req, res, next) => {
+    middleware(req, res, (error) => {
+      if (!error) {
+        next();
+        return;
+      }
+
+      const resolved = resolveUploadError(error);
+      if (res.headersSent) {
+        next(resolved);
+        return;
+      }
+
+      res.status(resolved.statusCode || 400).json({
+        error: resolved.message || 'Upload failed.',
+      });
+    });
+  };
+}
+
+export async function createUploadManager(uploadConfig, logger) {
+  if (!uploadConfig?.enabled) {
+    return null;
+  }
+
+  if (uploadConfig.createDir) {
+    await fs.mkdir(uploadConfig.directory, { recursive: true });
+  }
+
+  const uploader = multer(createMulterOptions(uploadConfig));
+  logger.debug(
+    'Uploads enabled: dir=%s maxFileSize=%s maxFiles=%s',
+    uploadConfig.directory,
+    uploadConfig.maxFileSize,
+    uploadConfig.maxFiles,
+  );
+
+  return {
+    config: {
+      ...uploadConfig,
+      directory: uploadConfig.directory,
+    },
+    single(fieldName) {
+      return wrapUploadMiddleware(uploader.single(String(fieldName || 'file')));
+    },
+    array(fieldName, maxCount = undefined) {
+      const count = typeof maxCount === 'number' && Number.isFinite(maxCount) && maxCount > 0
+        ? Math.floor(maxCount)
+        : undefined;
+      return wrapUploadMiddleware(uploader.array(String(fieldName || 'files'), count));
+    },
+    fields(definitions) {
+      return wrapUploadMiddleware(uploader.fields(Array.isArray(definitions) ? definitions : []));
+    },
+    any() {
+      return wrapUploadMiddleware(uploader.any());
+    },
+    none() {
+      return wrapUploadMiddleware(uploader.none());
+    },
+  };
+}
+
+export function isMultipartRequestContentType(contentType) {
+  return String(contentType || '').toLowerCase().includes('multipart/form-data');
+}