@zintrust/core 0.1.14 → 0.1.16

package/src/security/PasswordResetTokenBroker.js

@@ -0,0 +1,131 @@
+/**
+ * Password Reset Token Broker
+ *
+ * Framework-agnostic, storage-pluggable password reset token flow.
+ *
+ * - Generates high-entropy tokens for a given identifier (usually an email).
+ * - Stores only a SHA-256 hash of the token (one active token per identifier).
+ * - Supports verification and one-time consumption.
+ */
+import { ErrorFactory } from '../exceptions/ZintrustError.js';
+import { createHash, randomBytes } from '../node-singletons/crypto.js';
+const DEFAULT_TTL_MS = 30 * 60 * 1000;
+const DEFAULT_TOKEN_BYTES = 32; // 256 bits
+const createInMemoryStore = () => {
+    const map = new Map();
+    return {
+        set(record) {
+            map.set(record.identifier, record);
+        },
+        get(identifier) {
+            return map.get(identifier) ?? null;
+        },
+        delete(identifier) {
+            map.delete(identifier);
+        },
+        cleanup(now = new Date()) {
+            let removed = 0;
+            for (const [identifier, record] of map.entries()) {
+                if (now.getTime() > record.expiresAt.getTime()) {
+                    map.delete(identifier);
+                    removed++;
+                }
+            }
+            return removed;
+        },
+        clear() {
+            map.clear();
+        },
+    };
+};
+const create = (options = {}) => {
+    const store = options.store ?? createInMemoryStore();
+    const ttlMs = normalizeTtlMs(options.ttlMs ?? DEFAULT_TTL_MS);
+    const tokenBytes = normalizeTokenBytes(options.tokenBytes ?? DEFAULT_TOKEN_BYTES);
+    const now = options.now ?? (() => new Date());
+    return {
+        async createToken(identifier) {
+            const normalizedIdentifier = normalizeIdentifier(identifier);
+            const token = randomBytes(tokenBytes).toString('hex');
+            const tokenHash = sha256Hex(token);
+            const createdAt = now();
+            const expiresAt = new Date(createdAt.getTime() + ttlMs);
+            await store.set({ identifier: normalizedIdentifier, tokenHash, createdAt, expiresAt });
+            return token;
+        },
+        async verifyToken(identifier, token) {
+            const normalizedIdentifier = normalizeIdentifier(identifier);
+            const normalizedToken = normalizeToken(token);
+            const record = await store.get(normalizedIdentifier);
+            if (record === null)
+                return false;
+            if (isExpired(record, now())) {
+                await store.delete(normalizedIdentifier);
+                return false;
+            }
+            const computed = sha256Hex(normalizedToken);
+            return timingSafeEquals(record.tokenHash, computed);
+        },
+        async consumeToken(identifier, token) {
+            const normalizedIdentifier = normalizeIdentifier(identifier);
+            const ok = await this.verifyToken(normalizedIdentifier, token);
+            if (!ok)
+                return false;
+            await store.delete(normalizedIdentifier);
+            return true;
+        },
+    };
+};
+export const PasswordResetTokenBroker = Object.freeze({
+    create,
+    createInMemoryStore,
+});
+function normalizeIdentifier(identifier) {
+    if (typeof identifier !== 'string') {
+        throw ErrorFactory.createValidationError('Invalid identifier');
+    }
+    const trimmed = identifier.trim();
+    if (trimmed.length === 0) {
+        throw ErrorFactory.createValidationError('Invalid identifier');
+    }
+    return trimmed;
+}
+function normalizeToken(token) {
+    if (typeof token !== 'string') {
+        throw ErrorFactory.createValidationError('Invalid token');
+    }
+    const trimmed = token.trim();
+    if (trimmed.length === 0) {
+        throw ErrorFactory.createValidationError('Invalid token');
+    }
+    return trimmed;
+}
+function normalizeTtlMs(ttlMs) {
+    const value = Number.isFinite(ttlMs) ? Math.trunc(ttlMs) : 0;
+    if (value <= 0) {
+        throw ErrorFactory.createConfigError('Invalid password reset TTL', { ttlMs });
+    }
+    return value;
+}
+function normalizeTokenBytes(tokenBytes) {
+    const value = Number.isFinite(tokenBytes) ? Math.trunc(tokenBytes) : 0;
+    if (value <= 0) {
+        throw ErrorFactory.createConfigError('Invalid password reset token bytes', { tokenBytes });
+    }
+    return value;
+}
+function isExpired(record, now) {
+    return now.getTime() > record.expiresAt.getTime();
+}
+function sha256Hex(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function timingSafeEquals(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let result = 0;
+    for (let i = 0; i < a.length; i++) {
+        result |= (a.codePointAt(i) ?? 0) ^ (b.codePointAt(i) ?? 0);
+    }
+    return result === 0;
+}

package/src/session/SessionManager.d.ts

@@ -0,0 +1,39 @@
+export type SessionData = Record<string, unknown>;
+export interface ISession {
+    id: string;
+    get<T = unknown>(key: string): T | undefined;
+    set(key: string, value: unknown): void;
+    has(key: string): boolean;
+    forget(key: string): void;
+    all(): SessionData;
+    clear(): void;
+}
+export interface ISessionManager {
+    getIdFromCookieHeader(cookieHeader: string | undefined): string | undefined;
+    getIdFromRequest(req: {
+        getHeader: (name: string) => unknown;
+        sessionId?: unknown;
+        context?: Record<string, unknown>;
+    }): string | undefined;
+    ensureSessionId(req: {
+        getHeader: (name: string) => unknown;
+        sessionId?: unknown;
+        context: Record<string, unknown>;
+    }, res: {
+        getHeader: (name: string) => unknown;
+        setHeader: (name: string, value: string | string[]) => unknown;
+    }): Promise<string>;
+    get(sessionId: string): ISession;
+    destroy(sessionId: string): void;
+    cleanup(): number;
+}
+export interface SessionManagerOptions {
+    cookieName?: string;
+    headerName?: string;
+    ttlMs?: number;
+}
+export declare const SessionManager: Readonly<{
+    create(options?: SessionManagerOptions): ISessionManager;
+}>;
+export default SessionManager;
+//# sourceMappingURL=SessionManager.d.ts.map

package/src/session/SessionManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionManager.d.ts","sourceRoot":"","sources":["../../../src/session/SessionManager.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAElD,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;IAC7C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACvC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,GAAG,IAAI,WAAW,CAAC;IACnB,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;IAC5E,gBAAgB,CAAC,GAAG,EAAE;QACpB,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;QACrC,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACnC,GAAG,MAAM,GAAG,SAAS,CAAC;IACvB,eAAe,CACb,GAAG,EAAE;QACH,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;QACrC,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAClC,EACD,GAAG,EAAE;QACH,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;QACrC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,KAAK,OAAO,CAAC;KAChE,GACA,OAAO,CAAC,MAAM,CAAC,CAAC;IACnB,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,QAAQ,CAAC;IACjC,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,OAAO,IAAI,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAyHD,eAAO,MAAM,cAAc;qBACT,qBAAqB,GAAQ,eAAe;EA2E5D,CAAC;AAEH,eAAe,cAAc,CAAC"}

package/src/session/SessionManager.js

@@ -0,0 +1,149 @@
+import { generateSecureJobId } from '../common/uuid.js';
+const DEFAULT_OPTIONS = {
+    cookieName: 'ZIN_SESSION_ID',
+    headerName: 'x-session-id',
+    ttlMs: 7 * 24 * 60 * 60 * 1000,
+};
+function parseCookies(cookieHeader) {
+    const list = {};
+    if (cookieHeader.length === 0)
+        return list;
+    cookieHeader.split(';').forEach((cookie) => {
+        const parts = cookie.split('=');
+        const name = parts.shift()?.trim();
+        const value = parts.join('=');
+        if (name !== null && name !== undefined)
+            list[name] = decodeURIComponent(value);
+    });
+    return list;
+}
+function appendSetCookie(res, cookie) {
+    const existing = res.getHeader('Set-Cookie');
+    if (existing === undefined) {
+        res.setHeader('Set-Cookie', cookie);
+        return;
+    }
+    if (Array.isArray(existing)) {
+        const existingCookies = existing.map(String);
+        res.setHeader('Set-Cookie', [...existingCookies, cookie]);
+        return;
+    }
+    if (typeof existing === 'string') {
+        res.setHeader('Set-Cookie', [existing, cookie]);
+        return;
+    }
+    res.setHeader('Set-Cookie', cookie);
+}
+function buildSessionCookie(cookieName, sessionId) {
+    // Keep this minimal; callers can override behavior later.
+    // HttpOnly prevents JS access; SameSite=Lax is a reasonable default for app sessions.
+    return `${cookieName}=${encodeURIComponent(sessionId)}; Path=/; HttpOnly; SameSite=Lax`;
+}
+function createSessionApi(sessions, sessionId, ttlMs) {
+    const withoutKey = (data, key) => {
+        if (!Object.prototype.hasOwnProperty.call(data, key))
+            return data;
+        const record = data;
+        const { [key]: _removed, ...rest } = record;
+        return rest;
+    };
+    const ensureStored = () => {
+        const existing = sessions.get(sessionId);
+        const now = Date.now();
+        if (existing !== undefined && existing.expiresAt > now) {
+            return existing;
+        }
+        const created = { data: {}, expiresAt: now + ttlMs };
+        sessions.set(sessionId, created);
+        return created;
+    };
+    return {
+        id: sessionId,
+        get(key) {
+            return ensureStored().data[key];
+        },
+        set(key, value) {
+            const stored = ensureStored();
+            stored.data[key] = value;
+            stored.expiresAt = Date.now() + ttlMs;
+        },
+        has(key) {
+            return Object.prototype.hasOwnProperty.call(ensureStored().data, key);
+        },
+        forget(key) {
+            const stored = ensureStored();
+            stored.data = withoutKey(stored.data, key);
+            stored.expiresAt = Date.now() + ttlMs;
+        },
+        all() {
+            return { ...ensureStored().data };
+        },
+        clear() {
+            const stored = ensureStored();
+            stored.data = {};
+            stored.expiresAt = Date.now() + ttlMs;
+        },
+    };
+}
+export const SessionManager = Object.freeze({
+    create(options = {}) {
+        const config = { ...DEFAULT_OPTIONS, ...options };
+        const sessions = new Map();
+        return {
+            getIdFromCookieHeader(cookieHeader) {
+                if (cookieHeader === undefined || cookieHeader.length === 0)
+                    return undefined;
+                const cookies = parseCookies(cookieHeader);
+                return cookies[config.cookieName];
+            },
+            getIdFromRequest(req) {
+                const cookieHeader = req.getHeader('cookie');
+                if (typeof cookieHeader === 'string') {
+                    const fromCookie = this.getIdFromCookieHeader(cookieHeader);
+                    if (fromCookie !== undefined)
+                        return fromCookie;
+                }
+                const fromHeader = req.getHeader(config.headerName);
+                if (typeof fromHeader === 'string' && fromHeader.length > 0)
+                    return fromHeader;
+                if (typeof req.sessionId === 'string' && req.sessionId.length > 0)
+                    return req.sessionId;
+                const fromContext = req.context?.['sessionId'];
+                if (typeof fromContext === 'string' && fromContext.length > 0)
+                    return fromContext;
+                return undefined;
+            },
+            async ensureSessionId(req, res) {
+                const existing = this.getIdFromRequest(req);
+                const sessionId = existing ??
+                    (await Promise.resolve(generateSecureJobId('SessionManager: secure crypto API not available to generate a session id')));
+                req.context['sessionId'] = sessionId;
+                // If the cookie is missing, set it.
+                const cookieHeader = req.getHeader('cookie');
+                const fromCookie = typeof cookieHeader === 'string' ? this.getIdFromCookieHeader(cookieHeader) : undefined;
+                if (fromCookie === undefined) {
+                    appendSetCookie(res, buildSessionCookie(config.cookieName, sessionId));
+                }
+                return sessionId;
+            },
+            get(sessionId) {
+                return createSessionApi(sessions, sessionId, config.ttlMs);
+            },
+            destroy(sessionId) {
+                sessions.delete(sessionId);
+            },
+            cleanup() {
+                const now = Date.now();
+                let removed = 0;
+                for (const [id, stored] of sessions.entries()) {
+                    if (stored.expiresAt <= now) {
+                        sessions.delete(id);
+                        removed++;
+                    }
+                }
+                return removed;
+            },
+        };
+    },
+});
+export default SessionManager;

package/src/session/index.d.ts

@@ -0,0 +1,3 @@
+export { SessionManager } from './SessionManager';
+export type { ISession, ISessionManager, SessionData, SessionManagerOptions } from './SessionManager';
+//# sourceMappingURL=index.d.ts.map

package/src/session/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/session/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC"}

package/src/session/index.js

@@ -0,0 +1 @@
+export { SessionManager } from './SessionManager.js';

package/src/templates/features/Queue.ts.tpl

@@ -1,6 +1,7 @@
 // TEMPLATE_START
 
-import { generateSecureJobId, Logger } from '@zintrust/core';
+import { generateSecureJobId } from '@common/uuid';
+import { Logger } from '@config/logger';
 
 export interface QueueJob {
   id: string;
@@ -19,7 +20,7 @@ export const Queue = Object.freeze({
    * Add a job to the queue
    */
   async add<T>(data: T): Promise<string> {
-    const id = await generateSecureJobId();
+    const id = generateSecureJobId();
     const job: QueueJob = {
       id,
       data,
@@ -43,4 +44,4 @@ export const Queue = Object.freeze({
   },
 });
 
-// TEMPLATE_END
+// TEMPLATE_END

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

@@ -1,14 +1,15 @@
 /**
  * FileLogWriter (Node.js only)
- * Re-exports core FileLogWriter for optional use
+ *
+ * Provides best-effort file logging with daily + size-based rotation.
+ * This module imports Node built-ins and should be loaded only in Node environments.
  */
 
 import { ensureDirSafe } from '@zintrust/core';
+import { Env } from './env';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
-import { Env } from './env';
-
 const getCwdSafe = (): string => {
   try {
     if (typeof process === 'undefined' || typeof process.cwd !== 'function') return '';

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

@@ -4,7 +4,7 @@
  * Supports: AWS Secrets Manager, Parameter Store, Cloudflare KV, Deno env
  */
 
-import { Logger } from '@zintrust/core';
+import { Logger } from './logger';
 import type {
   GetSecretOptions,
   SecretConfig,

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

@@ -24,13 +24,15 @@ const hasOwn = (obj: Record<string, unknown>, key: string): boolean => {
 };
 
 const getDefaultBroadcaster = (drivers: BroadcastDrivers): string => {
-  const value = normalizeDriverName(Env.get('BROADCAST_DRIVER', 'inmemory'));
+  const envSelectedRaw = Env.get('BROADCAST_CONNECTION', Env.get('BROADCAST_DRIVER', 'inmemory'));
+  const value = normalizeDriverName(envSelectedRaw ?? 'inmemory');
 
-  if (value.length > 0 && hasOwn(drivers, value)) {
-    return value;
+  if (value.length > 0 && hasOwn(drivers, value)) return value;
+
+  if (envSelectedRaw.trim().length > 0) {
+    throw ErrorFactory.createConfigError(`Broadcast driver not configured: ${value}`);
   }
 
-  // Backwards-compatible default.
   return hasOwn(drivers, 'inmemory') ? 'inmemory' : (Object.keys(drivers)[0] ?? 'inmemory');
 };
 

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

@@ -23,18 +23,30 @@ const getCacheDriver = (config: CacheConfigInput, name?: string): CacheDriverCon
     throw ErrorFactory.createConfigError(`Cache store not configured: ${storeName}`);
   }
 
-  // Backwards-compatible fallback.
-  const fallback = config.drivers['memory'] ?? Object.values(config.drivers)[0];
-  if (fallback !== undefined) return fallback;
+  if (Object.keys(config.drivers ?? {}).length === 0) {
+    throw ErrorFactory.createConfigError('No cache stores are configured');
+  }
 
-  throw ErrorFactory.createConfigError('No cache stores are configured');
+  throw ErrorFactory.createConfigError(
+    `Cache default store not configured: ${storeName || '<empty>'}`
+  );
 };
 
 const cacheConfigObj = {
   /**
    * Default cache driver
    */
-  default: Env.CACHE_DRIVER,
+  default: (() => {
+    const envConnection = Env.get('CACHE_CONNECTION', '').trim();
+
+    const envDriver =
+      typeof (Env as unknown as { CACHE_DRIVER?: unknown }).CACHE_DRIVER === 'string'
+        ? String((Env as unknown as { CACHE_DRIVER?: unknown }).CACHE_DRIVER)
+        : Env.get('CACHE_DRIVER', 'memory');
+
+    const selected = envConnection.length > 0 ? envConnection : String(envDriver ?? 'memory');
+    return selected.trim().toLowerCase();
+  })(),
 
   /**
    * Cache drivers

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

@@ -13,13 +13,15 @@ const hasOwn = (obj: Record<string, unknown>, key: string): boolean => {
 };
 
 const getDefaultConnection = (connections: DatabaseConnections): string => {
-  const value = String(Env.DB_CONNECTION || '').trim();
+  const envSelectedRaw = Env.get('DB_CONNECTION', '');
+  const value = String(envSelectedRaw ?? '').trim();
 
-  if (value.length > 0 && hasOwn(connections, value)) {
-    return value;
+  if (value.length > 0 && hasOwn(connections, value)) return value;
+
+  if (envSelectedRaw.trim().length > 0) {
+    throw ErrorFactory.createConfigError(`Database connection not configured: ${value}`);
   }
 
-  // Backwards-compatible default.
   return hasOwn(connections, 'sqlite') ? 'sqlite' : (Object.keys(connections)[0] ?? 'sqlite');
 };
 

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

@@ -1,5 +1,5 @@
-import { Env } from '@zintrust/core';
-import { Logger } from '@zintrust/core';
+import { Env } from './env';
+import { Logger } from './logger';
 
 /**
  * Feature Flags State

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

@@ -3,8 +3,6 @@
  * Sealed namespace pattern - all exports through Logger namespace
  * Replaces console.* calls throughout the codebase
  */
-import { Logger } from '@zintrust/core';
-
 import { appConfig } from './app';
 import { Env } from './env';
 

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

@@ -10,7 +10,7 @@
  */
 
 import { delay } from '@zintrust/core';
-import { Env } from '@zintrust/core';
+import { Env } from '../env';
 import { ErrorFactory } from '@zintrust/core';
 import { HttpClient } from '@zintrust/core';
 

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

@@ -9,7 +9,7 @@
  *  - SLACK_LOG_BATCH_WINDOW_MS (default: 5000)
  */
 
-import { Env } from '@zintrust/core';
+import { Env } from '../env';
 import { ErrorFactory } from '@zintrust/core';
 import { HttpClient } from '@zintrust/core';
 

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

@@ -4,28 +4,38 @@
  * Sealed namespace for immutability
  */
 
-import { Env } from '@config/env';
-import type { MailConfigInput, MailDriverConfig } from '@config/type';
+import { Env } from './env';
+import type { MailConfigInput, MailDriverConfig } from './type';
 import { ErrorFactory } from '@zintrust/core';
 
+const isMailDriverConfig = (value: unknown): value is MailDriverConfig => {
+  if (typeof value !== 'object' || value === null) return false;
+  if (!('driver' in value)) return false;
+
+  const driver = (value as { driver?: unknown }).driver;
+  return typeof driver === 'string' && driver.trim().length > 0;
+};
+
 const getMailDriver = (config: MailConfigInput, name?: string): MailDriverConfig => {
-  const selected = (name ?? config.default).toString().trim();
+  const drivers = config.drivers as Record<string, unknown>;
+  const envSelectedRaw = Env.get('MAIL_CONNECTION', Env.get('MAIL_DRIVER', '')).trim();
+  const selected = (
+    name ??
+    (envSelectedRaw.length > 0 ? envSelectedRaw : undefined) ??
+    config.default
+  )
+    .toString()
+    .trim();
+
   if (selected.length === 0) {
-    const disabled = config.drivers['disabled'];
-    if (disabled !== undefined) return disabled;
+    const disabled = drivers['disabled'];
+    if (isMailDriverConfig(disabled)) return disabled;
     throw ErrorFactory.createConfigError('Mail driver not configured: disabled');
   }
 
-  if (Object.hasOwn(config.drivers, selected)) {
-    const resolved = config.drivers[selected];
-    if (resolved !== undefined) return resolved;
-  }
-
-  // Backward-compatible fallback: if the default is misconfigured, treat mail as disabled.
-  if (name === undefined) {
-    const disabled = config.drivers['disabled'];
-    if (disabled !== undefined) return disabled;
-    throw ErrorFactory.createConfigError('Mail driver not configured: disabled');
+  if (Object.hasOwn(drivers, selected)) {
+    const resolved = drivers[selected];
+    if (isMailDriverConfig(resolved)) return resolved;
   }
 
   throw ErrorFactory.createConfigError(`Mail driver not configured: ${selected}`);
@@ -35,7 +45,7 @@ const mailConfigObj = {
   /**
    * Default mail driver
    */
-  default: Env.get('MAIL_DRIVER', 'disabled').trim().toLowerCase() || 'disabled',
+  default: Env.get('MAIL_CONNECTION', Env.get('MAIL_DRIVER', 'disabled')).trim().toLowerCase(),
 
   /**
    * Default "From" identity

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

@@ -4,7 +4,7 @@
  * Sealed namespace for immutability
  */
 
-import { Env } from '@zintrust/core';
+import { Env } from './env';
 
 const microservicesConfigObj = {
   /**

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

@@ -1,13 +1,10 @@
-import {
-  CsrfMiddleware,
-  ErrorHandlerMiddleware,
-  LoggingMiddleware,
-  RateLimiter,
-  SecurityMiddleware,
-  type Middleware,
-} from '@zintrust/core';
-
 import { MiddlewareConfigType } from './type';
+import { CsrfMiddleware } from '@zintrust/core';
+import { ErrorHandlerMiddleware } from '@zintrust/core';
+import { LoggingMiddleware } from '@zintrust/core';
+import type { Middleware } from '@zintrust/core';
+import { RateLimiter } from '@zintrust/core';
+import { SecurityMiddleware } from '@zintrust/core';
 
 const shared = Object.freeze({
   log: LoggingMiddleware.create(),

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

@@ -5,13 +5,13 @@
  * Driver selection must be dynamic (tests may mutate process.env).
  */
 
-import { Env } from '@config/env';
+import { Env } from './env';
 import type {
   KnownNotificationDriverConfig,
   NotificationConfigInput,
   NotificationDrivers,
   NotificationProviders,
-} from '@config/type';
+} from './type';
 import { ErrorFactory } from '@zintrust/core';
 
 const normalizeName = (value: string): string => value.trim().toLowerCase();
@@ -21,8 +21,18 @@ const hasOwn = (obj: Record<string, unknown>, key: string): boolean => {
 };
 
 const getDefaultChannel = (drivers: NotificationDrivers): string => {
-  const value = normalizeName(Env.get('NOTIFICATION_DRIVER', 'console'));
+  const envSelectedRaw = Env.get(
+    'NOTIFICATION_CONNECTION',
+    Env.get('NOTIFICATION_DRIVER', 'console')
+  );
+  const value = normalizeName(envSelectedRaw ?? 'console');
+
   if (value.length > 0 && hasOwn(drivers, value)) return value;
+
+  if (envSelectedRaw.trim().length > 0) {
+    throw ErrorFactory.createConfigError(`Notification channel not configured: ${value}`);
+  }
+
   return hasOwn(drivers, 'console') ? 'console' : (Object.keys(drivers)[0] ?? 'console');
 };
 
@@ -43,14 +53,16 @@ const getNotificationDriver = (
     if (resolved !== undefined) return resolved;
   }
 
+  if (Object.keys(config.drivers ?? {}).length === 0) {
+    throw ErrorFactory.createConfigError('No notification channels are configured');
+  }
+
   if (isExplicitSelection) {
     throw ErrorFactory.createConfigError(`Notification channel not configured: ${channelName}`);
   }
 
-  const fallback = config.drivers['console'] ?? Object.values(config.drivers)[0];
-  if (fallback !== undefined) return fallback;
-
-  throw ErrorFactory.createConfigError('No notification channels are configured');
+  // Default selection is strict: if `default` points at an unconfigured channel, throw.
+  throw ErrorFactory.createConfigError(`Notification channel not configured: ${channelName}`);
 };
 
 const getBaseProviders = (): NotificationProviders => {