@zintrust/core 0.1.0 → 0.1.2

package/src/templates/project/basic/config/logging/HttpLogger.ts.tpl

@@ -0,0 +1,121 @@
+/**
+ * HTTP Endpoint Logger
+ * Sends logs to an external HTTP logging service.
+ *
+ * Enabled via env:
+ *  - HTTP_LOG_ENABLED (default: false)
+ *  - HTTP_LOG_ENDPOINT_URL
+ *  - HTTP_LOG_BATCH_SIZE (default: 50)
+ *  - HTTP_LOG_AUTH_TOKEN (optional)
+ */
+
+import { delay } from '@common/index';
+import { Env } from '@config/env';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import { HttpClient } from '@httpClient/Http';
+
+export type HttpLogEvent = {
+  timestamp: string;
+  level: 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+  message: string;
+  category?: string;
+  data?: unknown;
+  error?: string;
+};
+
+const isEnabled = (): boolean => Env.getBool('HTTP_LOG_ENABLED', false);
+
+let buffer: HttpLogEvent[] = [];
+let flushPromise: Promise<void> | undefined;
+
+const postBatch = async (events: HttpLogEvent[]): Promise<void> => {
+  const endpoint = Env.get('HTTP_LOG_ENDPOINT_URL').trim();
+  if (endpoint.length === 0) {
+    throw ErrorFactory.createConfigError(
+      'HTTP_LOG_ENDPOINT_URL is required when HTTP logging is enabled'
+    );
+  }
+
+  const token = Env.get('HTTP_LOG_AUTH_TOKEN').trim();
+
+  const builder = HttpClient.post(endpoint, {
+    sentAt: new Date().toISOString(),
+    count: events.length,
+    events,
+  });
+
+  if (token.length > 0) {
+    builder.withAuth(token, 'Bearer');
+  }
+
+  await builder.send();
+};
+
+const flushNow = async (): Promise<void> => {
+  const toSend = buffer;
+  buffer = [];
+
+  if (!isEnabled()) return;
+  if (toSend.length === 0) return;
+
+  const maxRetries = 3;
+
+  const attemptPost = async (attempt: number): Promise<void> => {
+    try {
+      await postBatch(toSend);
+    } catch {
+      if (attempt >= maxRetries) return;
+      const backoffMs = 100 * 2 ** attempt;
+      await delay(backoffMs);
+      await attemptPost(attempt + 1);
+    }
+  };
+
+  await attemptPost(0);
+};
+
+const scheduleFlush = async (): Promise<void> => {
+  if (flushPromise !== undefined) return flushPromise;
+
+  const promise = new Promise<void>((resolve) => {
+    const run = async (): Promise<void> => {
+      try {
+        await flushNow();
+      } finally {
+        resolve(undefined);
+      }
+    };
+
+    if (typeof globalThis.setTimeout !== 'function') {
+      void run();
+      return;
+    }
+
+    globalThis.setTimeout(() => {
+      void run();
+    }, 0);
+  });
+
+  flushPromise = promise.finally(() => {
+    flushPromise = undefined;
+  });
+
+  return flushPromise;
+};
+
+export const HttpLogger = Object.freeze({
+  async enqueue(event: HttpLogEvent): Promise<void> {
+    if (!isEnabled()) return Promise.resolve(); // NOSONAR
+
+    buffer.push(event);
+
+    const batchSize = Math.max(1, Env.getInt('HTTP_LOG_BATCH_SIZE', 50));
+    if (buffer.length >= batchSize) {
+      return scheduleFlush();
+    }
+
+    return scheduleFlush();
+  },
+});
+
+export default HttpLogger;

package/src/templates/project/basic/config/logging/KvLogger.ts.tpl

@@ -0,0 +1,181 @@
+/**
+ * KV Logger
+ * Writes batches of log events to a KV namespace (Cloudflare Workers compatible)
+ *
+ * Enabled via env:
+ *  - KV_LOG_ENABLED (default: false)
+ *  - KV_NAMESPACE (binding name; default: 'CACHE')
+ *  - KV_LOG_RETENTION_DAYS (default: 30)
+ */
+
+import { Cloudflare } from '@config/cloudflare';
+import { Env } from '@config/env';
+
+export type KvLogEvent = {
+  timestamp: string;
+  level: 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+  message: string;
+  category?: string;
+  data?: unknown;
+  error?: string;
+};
+
+type KVNamespace = NonNullable<ReturnType<typeof Cloudflare.getKVBinding>>;
+
+type PutOptions = { expiration?: number; expirationTtl?: number; metadata?: unknown };
+
+const getRetentionTtlSeconds = (): number => {
+  const days = Env.getInt('KV_LOG_RETENTION_DAYS', 30);
+  const safeDays = Number.isFinite(days) && days > 0 ? days : 30;
+  return safeDays * 24 * 60 * 60;
+};
+
+const getKvBindingName = (): string => {
+  const name = Env.get('KV_NAMESPACE', 'CACHE').trim();
+  return name.length > 0 ? name : 'CACHE';
+};
+
+const isEnabled = (): boolean => Env.getBool('KV_LOG_ENABLED', false);
+
+const safeRandom = (): string => {
+  try {
+    // Prefer crypto if available
+    const cryptoObj = (globalThis as unknown as { crypto?: Crypto }).crypto;
+    if (cryptoObj?.getRandomValues) {
+      const bytes = new Uint8Array(8);
+      cryptoObj.getRandomValues(bytes);
+      return Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+    }
+  } catch {
+    // fall through
+  }
+  const generate = Math.random().toString(16).slice(2); // NOSONAR
+  const fallback = generate + Math.random().toString(16).slice(2); // NOSONAR this is not used for security
+  return fallback;
+};
+
+const buildKey = (timestampIso: string): string => {
+  const date = timestampIso.slice(0, 10);
+  const hour = timestampIso.slice(11, 13);
+  return `logs:${date}:${hour}:${safeRandom()}`;
+};
+
+let buffer: KvLogEvent[] = [];
+let flushTimer: ReturnType<typeof setTimeout> | undefined;
+let flushPromise: Promise<void> | undefined;
+
+const scheduleFlush = async (): Promise<void> => {
+  if (flushPromise !== undefined) return flushPromise;
+
+  // Fixed small batching window to reduce KV write volume.
+  const windowMs = 1000;
+
+  const promise = new Promise<void>((resolve) => {
+    const run = async (): Promise<void> => {
+      try {
+        await flushNow();
+      } finally {
+        resolve(undefined);
+      }
+    };
+
+    if (typeof globalThis.setTimeout !== 'function') {
+      // microtask-ish
+      void run();
+      return;
+    }
+
+    flushTimer = globalThis.setTimeout(() => {
+      flushTimer = undefined;
+      void run();
+    }, windowMs);
+  });
+
+  flushPromise = promise.finally(() => {
+    flushPromise = undefined;
+  });
+
+  return flushPromise;
+};
+
+const getKv = (): KVNamespace | null => {
+  const bindingName = getKvBindingName();
+  return Cloudflare.getKVBinding(bindingName);
+};
+
+const putBatch = async (kv: KVNamespace, events: KvLogEvent[]): Promise<void> => {
+  if (events.length === 0) return;
+
+  const timestamp = events.at(-1)?.timestamp ?? new Date().toISOString();
+  const key = buildKey(timestamp);
+
+  const payload = JSON.stringify({
+    version: 1,
+    createdAt: new Date().toISOString(),
+    count: events.length,
+    events,
+  });
+
+  const opts: PutOptions = { expirationTtl: getRetentionTtlSeconds() };
+
+  await kv.put(key, payload, opts);
+};
+
+const flushNow = async (): Promise<void> => {
+  if (!isEnabled()) {
+    buffer = [];
+    return;
+  }
+
+  const kv = getKv();
+  if (kv === null) {
+    buffer = [];
+    return;
+  }
+
+  const toSend = buffer;
+  buffer = [];
+
+  try {
+    await putBatch(kv, toSend);
+  } catch {
+    // Best-effort: never throw from logging.
+  }
+};
+
+const flushSoon = async (): Promise<void> => {
+  if (flushPromise !== undefined) return flushPromise;
+
+  flushPromise = Promise.resolve()
+    .then(async () => flushNow())
+    .finally(() => {
+      flushPromise = undefined;
+    });
+
+  return flushPromise;
+};
+
+export const KvLogger = Object.freeze({
+  async enqueue(event: KvLogEvent): Promise<void> {
+    if (!isEnabled()) return Promise.resolve();
+
+    buffer.push(event);
+
+    // Basic size guard: flush if it gets too large
+    const maxBatch = 100;
+    if (buffer.length >= maxBatch) {
+      // Cancel scheduled flush and flush immediately
+      if (flushTimer !== undefined) {
+        globalThis.clearTimeout(flushTimer);
+        flushTimer = undefined;
+      }
+      return flushSoon();
+    }
+
+    return scheduleFlush();
+  },
+});
+
+export default KvLogger;

package/src/templates/project/basic/config/logging/SlackLogger.ts.tpl

@@ -0,0 +1,156 @@
+/**
+ * Slack Notification Logger
+ * Sends warn/error/fatal log events to a Slack incoming webhook.
+ *
+ * Enabled via env:
+ *  - SLACK_LOG_ENABLED (default: false)
+ *  - SLACK_LOG_WEBHOOK_URL
+ *  - SLACK_LOG_LEVELS (comma-separated; default: "warn,error,fatal")
+ *  - SLACK_LOG_BATCH_WINDOW_MS (default: 5000)
+ */
+
+import { Env } from '@config/env';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import { HttpClient } from '@httpClient/Http';
+
+export type SlackLogEvent = {
+  timestamp: string;
+  level: 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+  message: string;
+  category?: string;
+  data?: unknown;
+  error?: string;
+};
+
+type SlackPayload = {
+  text?: string;
+  attachments?: Array<{ color?: string; text: string }>;
+};
+
+const isEnabled = (): boolean => Env.getBool('SLACK_LOG_ENABLED', false);
+
+const getLevels = (): Set<string> => {
+  const raw = Env.get('SLACK_LOG_LEVELS', 'warn,error,fatal');
+  return new Set(
+    raw
+      .split(',')
+      .map((s) => s.trim().toLowerCase())
+      .filter((s) => s.length > 0)
+  );
+};
+
+const levelToColor = (level: SlackLogEvent['level']): string => {
+  if (level === 'fatal' || level === 'error') return '#D50200';
+  if (level === 'warn') return '#D39E00';
+  return '#439FE0';
+};
+
+const formatEventText = (ev: SlackLogEvent): string => {
+  const header = `*${ev.level.toUpperCase()}* ${ev.message}`;
+  const metaParts: string[] = [];
+  if (ev.category !== undefined) metaParts.push(`category=${ev.category}`);
+  metaParts.push(`ts=${ev.timestamp}`);
+
+  const meta = metaParts.length > 0 ? `\n_${metaParts.join(' ')}_` : '';
+
+  const err = ev.error === undefined ? '' : `\n*error:* ${String(ev.error)}`;
+  const data = ev.data === undefined ? '' : `\n*data:* \`${JSON.stringify(ev.data)}\``;
+
+  return `${header}${meta}${err}${data}`;
+};
+
+let buffer: SlackLogEvent[] = [];
+let flushPromise: Promise<void> | undefined;
+let dedupeKeys = new Set<string>();
+
+const dedupeKeyFor = (ev: SlackLogEvent): string => {
+  const base = `${ev.level}:${ev.message}:${ev.error ?? ''}`;
+  return base.length > 500 ? base.slice(0, 500) : base;
+};
+
+const sendBatch = async (events: SlackLogEvent[]): Promise<void> => {
+  const webhookUrl = Env.get('SLACK_LOG_WEBHOOK_URL').trim();
+  if (webhookUrl.length === 0) {
+    throw ErrorFactory.createConfigError(
+      'SLACK_LOG_WEBHOOK_URL is required when Slack logging is enabled'
+    );
+  }
+
+  const lines = events.map((e) => formatEventText(e)).join('\n\n');
+
+  const payload: SlackPayload = {
+    attachments: [
+      {
+        color: levelToColor(events[0]?.level ?? 'warn'),
+        text: lines,
+      },
+    ],
+  };
+
+  await HttpClient.post(webhookUrl, payload).send();
+};
+
+const flushNow = async (): Promise<void> => {
+  const toSend = buffer;
+  buffer = [];
+  dedupeKeys = new Set<string>();
+
+  if (!isEnabled()) return;
+  if (toSend.length === 0) return;
+
+  try {
+    await sendBatch(toSend);
+  } catch {
+    // Best-effort: never throw from logging.
+  }
+};
+
+const scheduleFlush = async (): Promise<void> => {
+  if (flushPromise !== undefined) return flushPromise;
+
+  const windowMs = Math.max(0, Env.getInt('SLACK_LOG_BATCH_WINDOW_MS', 5000));
+
+  const promise = new Promise<void>((resolve) => {
+    const run = async (): Promise<void> => {
+      try {
+        await flushNow();
+      } finally {
+        resolve(undefined);
+      }
+    };
+
+    if (windowMs === 0 || typeof globalThis.setTimeout !== 'function') {
+      void run();
+      return;
+    }
+
+    globalThis.setTimeout(() => {
+      void run();
+    }, windowMs);
+  });
+
+  flushPromise = promise.finally(() => {
+    flushPromise = undefined;
+  });
+
+  return flushPromise;
+};
+
+export const SlackLogger = Object.freeze({
+  async enqueue(event: SlackLogEvent): Promise<void> {
+    if (!isEnabled()) return Promise.resolve();
+
+    const levels = getLevels();
+    if (!levels.has(event.level)) return Promise.resolve();
+
+    const key = dedupeKeyFor(event);
+    if (dedupeKeys.has(key)) return scheduleFlush();
+
+    dedupeKeys.add(key);
+    buffer.push(event);
+
+    return scheduleFlush();
+  },
+});
+
+export default SlackLogger;

package/src/templates/project/basic/config/mail.ts.tpl

@@ -0,0 +1,141 @@
+/**
+ * Mail Configuration
+ * Runtime mail drivers and settings
+ * Sealed namespace for immutability
+ */
+
+import { Env } from '@config/env';
+
+export type MailDriverName = 'disabled' | 'sendgrid' | 'smtp' | 'ses' | 'mailgun';
+
+export type DisabledMailDriverConfig = {
+  driver: 'disabled';
+};
+
+export type SendGridMailDriverConfig = {
+  driver: 'sendgrid';
+  apiKey: string;
+};
+
+export type MailgunMailDriverConfig = {
+  driver: 'mailgun';
+  apiKey: string;
+  domain: string;
+  baseUrl: string;
+};
+
+// Placeholders for future drivers (kept config-first)
+export type SmtpMailDriverConfig = {
+  driver: 'smtp';
+  host: string;
+  port: number;
+  username: string;
+  password: string;
+  secure: boolean | 'starttls';
+};
+
+export type SesMailDriverConfig = {
+  driver: 'ses';
+  region: string;
+};
+
+export type MailDriverConfig =
+  | DisabledMailDriverConfig
+  | SendGridMailDriverConfig
+  | MailgunMailDriverConfig
+  | SmtpMailDriverConfig
+  | SesMailDriverConfig;
+
+type MailDrivers = {
+  disabled: DisabledMailDriverConfig;
+  sendgrid: SendGridMailDriverConfig;
+  mailgun: MailgunMailDriverConfig;
+  smtp: SmtpMailDriverConfig;
+  ses: SesMailDriverConfig;
+};
+
+type MailConfigInput = {
+  default: MailDriverName;
+  from: {
+    address: string;
+    name: string;
+  };
+  drivers: MailDrivers;
+};
+
+const getMailDriver = (config: MailConfigInput): MailDriverConfig => {
+  const defaultDriver = config.default;
+
+  if (Object.hasOwn(config.drivers, defaultDriver)) {
+    const driverName = defaultDriver as keyof MailDrivers;
+    return config.drivers[driverName];
+  }
+
+  return config.drivers.disabled;
+};
+
+const mailConfigObj = {
+  /**
+   * Default mail driver
+   */
+  default: (Env.get('MAIL_DRIVER', 'disabled') as MailDriverName) ?? 'disabled',
+
+  /**
+   * Default "From" identity
+   */
+  from: {
+    address: Env.get('MAIL_FROM_ADDRESS', ''),
+    name: Env.get('MAIL_FROM_NAME', ''),
+  },
+
+  /**
+   * Driver configs
+   */
+  drivers: {
+    disabled: {
+      driver: 'disabled' as const,
+    },
+
+    sendgrid: {
+      driver: 'sendgrid' as const,
+      apiKey: Env.get('SENDGRID_API_KEY', ''),
+    },
+
+    mailgun: {
+      driver: 'mailgun' as const,
+      apiKey: Env.get('MAILGUN_API_KEY', ''),
+      domain: Env.get('MAILGUN_DOMAIN', ''),
+      baseUrl: Env.get('MAILGUN_BASE_URL', 'https://api.mailgun.net').trim(),
+    },
+
+    smtp: {
+      driver: 'smtp' as const,
+      host: Env.get('MAIL_HOST', ''),
+      port: Env.getInt('MAIL_PORT', 587),
+      username: Env.get('MAIL_USERNAME', ''),
+      password: Env.get('MAIL_PASSWORD', ''),
+      secure: (() => {
+        const raw = Env.get('MAIL_SECURE', '').trim().toLowerCase();
+        if (raw === 'starttls') return 'starttls' as const;
+        if (raw === 'tls' || raw === 'ssl' || raw === 'smtps' || raw === 'implicit') return true;
+        if (raw === 'none' || raw === 'off' || raw === 'false' || raw === '0') return false;
+        return Env.getBool('MAIL_SECURE', false);
+      })(),
+    },
+
+    ses: {
+      driver: 'ses' as const,
+      region: Env.get('AWS_REGION', 'us-east-1'),
+    },
+  },
+
+  /**
+   * Get selected driver config
+   */
+  getDriver(): MailDriverConfig {
+    return getMailDriver(this);
+  },
+} as const;
+
+export const mailConfig = Object.freeze(mailConfigObj);
+export type MailConfig = typeof mailConfig;

package/src/templates/project/basic/config/middleware.ts.tpl

@@ -0,0 +1,27 @@
+import { CsrfMiddleware } from '@middleware/CsrfMiddleware';
+import { ErrorHandlerMiddleware } from '@middleware/ErrorHandlerMiddleware';
+import { LoggingMiddleware } from '@middleware/LoggingMiddleware';
+import type { Middleware } from '@middleware/MiddlewareStack';
+import { RateLimiter } from '@middleware/RateLimiter';
+import { SecurityMiddleware } from '@middleware/SecurityMiddleware';
+
+export type MiddlewareConfig = {
+  global: Middleware[];
+  route: Record<string, Middleware>;
+};
+
+const shared = Object.freeze({
+  log: LoggingMiddleware.create(),
+  error: ErrorHandlerMiddleware.create(),
+  security: SecurityMiddleware.create(),
+  rateLimit: RateLimiter.create(),
+  csrf: CsrfMiddleware.create(),
+} satisfies Record<string, Middleware>);
+
+const middlewareConfigObj: MiddlewareConfig = {
+  global: [shared.log, shared.error, shared.security, shared.rateLimit, shared.csrf],
+  route: shared,
+};
+
+export const middlewareConfig = Object.freeze(middlewareConfigObj);
+export default middlewareConfig;

package/src/templates/project/basic/config/notification.ts.tpl

@@ -0,0 +1,86 @@
+/**
+ * Notification Configuration
+ *
+ * Config-first mapping of notification providers.
+ * Keeps runtime driver selection in one place and uses Env for safe access.
+ */
+
+import { Env } from '@config/env';
+
+export type KnownNotificationDriverName = 'console' | 'termii' | 'twilio' | 'slack';
+
+export type ConsoleNotificationDriverConfig = { driver: 'console' };
+
+export type TermiiNotificationDriverConfig = {
+  driver: 'termii';
+  apiKey: string;
+  sender: string;
+  endpoint: string;
+};
+
+export type TwilioNotificationDriverConfig = {
+  driver: 'twilio';
+  accountSid: string;
+  authToken: string;
+  fromNumber: string;
+};
+
+export type SlackNotificationDriverConfig = {
+  driver: 'slack';
+  webhookUrl: string;
+};
+
+export type KnownNotificationDriverConfig =
+  | ConsoleNotificationDriverConfig
+  | TermiiNotificationDriverConfig
+  | TwilioNotificationDriverConfig
+  | SlackNotificationDriverConfig;
+
+type NotificationProviders = {
+  console: ConsoleNotificationDriverConfig;
+  termii: TermiiNotificationDriverConfig;
+  twilio: TwilioNotificationDriverConfig;
+  slack: SlackNotificationDriverConfig;
+};
+
+const notificationConfigObj = {
+  /**
+   * Normalized notification driver name.
+   *
+   * NOTE: This intentionally supports custom driver names (e.g. project-specific drivers),
+   * so it returns a string rather than a strict union.
+   */
+  getDriverName(): string {
+    return Env.get('NOTIFICATION_DRIVER', 'console').trim().toLowerCase();
+  },
+
+  /**
+   * Provider configs.
+   */
+  providers: {
+    console: {
+      driver: 'console' as const,
+    },
+
+    termii: {
+      driver: 'termii' as const,
+      apiKey: Env.get('TERMII_API_KEY', ''),
+      sender: Env.get('TERMII_SENDER', 'Zintrust'),
+      endpoint: Env.get('TERMII_ENDPOINT', 'https://api.termii.com/sms/send'),
+    },
+
+    twilio: {
+      driver: 'twilio' as const,
+      accountSid: Env.get('TWILIO_ACCOUNT_SID', ''),
+      authToken: Env.get('TWILIO_AUTH_TOKEN', ''),
+      fromNumber: Env.get('TWILIO_FROM_NUMBER', ''),
+    },
+
+    slack: {
+      driver: 'slack' as const,
+      webhookUrl: Env.get('SLACK_WEBHOOK_URL', ''),
+    },
+  } satisfies NotificationProviders,
+} as const;
+
+export default Object.freeze(notificationConfigObj);