@zintrust/core 0.1.2 → 0.1.4

package/README.md

@@ -1,6 +1,6 @@
 # Getting Started with Zintrust
 
-Welcome to Zintrust, a production-grade TypeScript backend framework with proven architectural patterns and zero external dependencies.
+Welcome to Zintrust, a production-grade TypeScript backend framework with proven architectural patterns and a minimal core (no Express/Fastify). The published npm package also includes a few runtime dependencies for the CLI and developer experience.
 
 ## Quick Start (2 minutes)
 
@@ -20,7 +20,7 @@ Your API is now running at `http://localhost:7777`
 
 ## What is Zintrust?
 
-Zintrust is a **zero-dependency** backend framework built on:
+Zintrust is a **minimal-core** backend framework built on:
 
 - ✅ **Pure Node.js** - No Express, Fastify, or external HTTP libraries
 - ✅ **Type-Safe** - Strict TypeScript with 100% type coverage

package/bin/zintrust.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"zintrust.d.ts","sourceRoot":"","sources":["../../bin/zintrust.ts"],"names":[],"mappings":";AAEA;;;;;GAKG;AAmEH,OAAO,EAAE,CAAC"}
+{"version":3,"file":"zintrust.d.ts","sourceRoot":"","sources":["../../bin/zintrust.ts"],"names":[],"mappings":";AAEA;;;;;GAKG;AA8FH,OAAO,EAAE,CAAC"}

package/bin/zintrust.js

@@ -5,8 +5,63 @@
  * Usage: zintrust [command] [options]
  * Shortcuts: zin, z
  */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const loadPackageVersionFast = () => {
+    try {
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        const packagePath = path.join(here, '../package.json');
+        const packageJson = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
+        return typeof packageJson.version === 'string' ? packageJson.version : '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+};
+const stripLeadingScriptArg = (rawArgs) => {
+    if (rawArgs.length === 0)
+        return rawArgs;
+    const first = rawArgs[0];
+    const looksLikeScript = typeof first === 'string' && (first.endsWith('.ts') || first.endsWith('.js'));
+    return looksLikeScript ? rawArgs.slice(1) : rawArgs;
+};
+const getArgsFromProcess = () => {
+    const rawArgs = process.argv.slice(2);
+    return { rawArgs, args: stripLeadingScriptArg(rawArgs) };
+};
+const isVersionRequest = (args) => {
+    return args.includes('-v') || args.includes('--version');
+};
+const shouldDebugArgs = (rawArgs) => {
+    return process.env['ZINTRUST_CLI_DEBUG_ARGS'] === '1' && rawArgs.includes('--verbose');
+};
+const handleCliFatal = async (error, context) => {
+    try {
+        const { Logger } = await import('../src/config/logger');
+        Logger.error(context, error);
+    }
+    catch {
+        // best-effort logging
+    }
+    try {
+        const { ErrorHandler } = await import('../src/cli/ErrorHandler');
+        ErrorHandler.handle(error);
+    }
+    catch {
+        // best-effort error handling
+    }
+    process.exit(1);
+};
 async function main() {
     try {
+        // Fast path: print version and exit without bootstrapping the CLI.
+        // This keeps `zin -v` / `zin --version` snappy and avoids any debug output.
+        const { rawArgs: _rawArgs0, args: args0 } = getArgsFromProcess();
+        if (isVersionRequest(args0)) {
+            process.stdout.write(`${loadPackageVersionFast()}\n`);
+            return;
+        }
         const { EnvFileLoader } = await import('../src/cli/utils/EnvFileLoader');
         EnvFileLoader.ensureLoaded();
         const { CLI } = await import('../src/cli/CLI');
@@ -14,8 +69,8 @@ async function main() {
         // When executing via tsx (e.g. `npx tsx bin/zin.ts ...`), the script path can
         // appear as the first element of `process.argv.slice(2)`. Commander expects
         // args to start at the command name, so we strip a leading script path if present.
-        const rawArgs = process.argv.slice(2);
-        if (process.env['ZINTRUST_CLI_DEBUG_ARGS'] === '1') {
+        const { rawArgs, args } = getArgsFromProcess();
+        if (shouldDebugArgs(rawArgs)) {
             try {
                 process.stderr.write(`[zintrust-cli] process.argv=${JSON.stringify(process.argv)}\n`);
                 process.stderr.write(`[zintrust-cli] rawArgs=${JSON.stringify(rawArgs)}\n`);
@@ -24,45 +79,12 @@ async function main() {
                 // ignore
             }
         }
-        const args = rawArgs.length > 0 &&
-            (rawArgs[0]?.endsWith('.ts') === true || rawArgs[0]?.endsWith('.js') === true)
-            ? rawArgs.slice(1)
-            : rawArgs;
         await cli.run(args);
     }
     catch (error) {
-        try {
-            const { Logger } = await import('../src/config/logger');
-            Logger.error('CLI execution failed', error);
-        }
-        catch {
-            // best-effort logging
-        }
-        try {
-            const { ErrorHandler } = await import('../src/cli/ErrorHandler');
-            ErrorHandler.handle(error);
-        }
-        catch {
-            // best-effort error handling
-        }
-        process.exit(1);
+        await handleCliFatal(error, 'CLI execution failed');
     }
 }
 await main().catch(async (error) => {
-    try {
-        const { Logger } = await import('../src/config/logger');
-        Logger.error('CLI fatal error', error);
-    }
-    catch {
-        // best-effort logging
-    }
-    try {
-        const { ErrorHandler } = await import('../src/cli/ErrorHandler');
-        ErrorHandler.handle(error);
-    }
-    catch {
-        // best-effort error handling
-    }
-    process.exit(1);
+    await handleCliFatal(error, 'CLI fatal error');
 });
-export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zintrust/core",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Production-grade TypeScript backend framework for JavaScript",
   "homepage": "https://zintrust.com",
   "repository": {
@@ -13,6 +13,20 @@
   "type": "module",
   "main": "src/index.js",
   "types": "src/index.d.ts",
+  "dependencies": {
+    "bcrypt": "^6.0.0",
+    "better-sqlite3": "^12.5.0",
+    "chalk": "^5.6.2",
+    "commander": "^14.0.2",
+    "inquirer": "^13.1.0",
+    "jsonwebtoken": "^9.0.3",
+    "tsx": "^4.21.0"
+  },
+  "overrides": {
+    "node-forge": "1.3.3",
+    "cross-spawn": "^7.0.5",
+    "glob": "^11.1.0"
+  },
   "bin": {
     "zintrust": "bin/zintrust.js",
     "zin": "bin/zin.js",

package/src/cli/BaseCommand.js

@@ -17,7 +17,7 @@ export const BaseCommand = Object.freeze({
         const getCommand = () => {
             const command = new Command(config.name);
             command.description(config.description);
-            command.option('-v, --verbose', 'Enable verbose output');
+            command.option('--verbose', 'Enable verbose output');
             // Add custom options
             if (config.addOptions) {
                 config.addOptions(command);

package/src/cli/CLI.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CLI.d.ts","sourceRoot":"","sources":["../../../src/cli/CLI.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAyBH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,MAAM,WAAW,IAAI;IACnB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,UAAU,IAAI,OAAO,CAAC;CACvB;AAqLD;;;;;;;GAOG;AACH,eAAO,MAAM,GAAG;cACJ,IAAI;EAed,CAAC"}
+{"version":3,"file":"CLI.d.ts","sourceRoot":"","sources":["../../../src/cli/CLI.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAyBH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,MAAM,WAAW,IAAI;IACnB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,UAAU,IAAI,OAAO,CAAC;CACvB;AAsLD;;;;;;;GAOG;AACH,eAAO,MAAM,GAAG;cACJ,IAAI;EAed,CAAC"}

package/src/cli/CLI.js

@@ -159,12 +159,13 @@ const handleExecutionError = (error, version, log = true) => {
  */
 const runCLI = async (program, version, args) => {
     try {
-        // Always show banner
-        ErrorHandler.banner(version);
-        // If version is requested, we've already shown the banner which includes the version.
+        // If version is requested, let Commander print it (no banner, fast/clean output).
         if (args.includes('-v') || args.includes('--version')) {
+            await program.parseAsync(['node', 'zintrust', ...args]);
             return;
         }
+        // Always show banner for normal commands
+        ErrorHandler.banner(version);
         // Show help if no arguments provided
         if (args.length === 0) {
             program.help();

package/src/cli/commands/NewCommand.d.ts

@@ -3,7 +3,7 @@
  * Handles creation of new Zintrust projects
  */
 import { CommandOptions, IBaseCommand } from '../BaseCommand';
-type TemplateType = 'basic' | 'api' | 'microservice';
+type TemplateType = 'basic' | 'api' | 'microservice' | 'fullstack';
 type DatabaseType = 'sqlite' | 'mysql' | 'postgresql' | 'mongodb';
 interface NewProjectConfigResult {
     template: TemplateType;
@@ -19,8 +19,9 @@ interface INewCommand extends IBaseCommand {
     getQuestions(name: string, defaults: NewProjectConfigResult): InquirerQuestion[];
     getSafeEnv(): NodeJS.ProcessEnv;
     getGitBinary(): string;
-    runScaffolding(name: string, config: NewProjectConfigResult, overwrite?: boolean): Promise<unknown>;
-    initializeGit(name: string): void;
+    runScaffolding(basePath: string, name: string, config: NewProjectConfigResult, overwrite?: boolean): Promise<unknown>;
+    initializeGit(projectPath: string): void;
+    promptForPackageManager(defaultPm: string): Promise<string | null>;
 }
 /**
  * New Command Factory

package/src/cli/commands/NewCommand.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NewCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/NewCommand.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAe,cAAc,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAY7E,KAAK,YAAY,GAAG,OAAO,GAAG,KAAK,GAAG,cAAc,CAAC;AACrD,KAAK,YAAY,GAAG,QAAQ,GAAG,OAAO,GAAG,YAAY,GAAG,SAAS,CAAC;AAYlE,UAAU,sBAAsB;IAC9B,QAAQ,EAAE,YAAY,CAAC;IACvB,QAAQ,EAAE,YAAY,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,KAAK,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAiMhD,UAAU,WAAY,SAAQ,YAAY;IACxC,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;IACxF,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;IACzF,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,sBAAsB,GAAG,gBAAgB,EAAE,CAAC;IACjF,UAAU,IAAI,MAAM,CAAC,UAAU,CAAC;IAChC,YAAY,IAAI,MAAM,CAAC;IACvB,cAAc,CACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,sBAAsB,EAC9B,SAAS,CAAC,EAAE,OAAO,GAClB,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAwID;;;GAGG;AACH,eAAO,MAAM,UAAU;IACrB;;OAEG;cACO,WAAW;EAGrB,CAAC"}
+{"version":3,"file":"NewCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/NewCommand.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAe,cAAc,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAY7E,KAAK,YAAY,GAAG,OAAO,GAAG,KAAK,GAAG,cAAc,GAAG,WAAW,CAAC;AACnE,KAAK,YAAY,GAAG,QAAQ,GAAG,OAAO,GAAG,YAAY,GAAG,SAAS,CAAC;AAYlE,UAAU,sBAAsB;IAC9B,QAAQ,EAAE,YAAY,CAAC;IACvB,QAAQ,EAAE,YAAY,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,KAAK,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAsOhD,UAAU,WAAY,SAAQ,YAAY;IACxC,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;IACxF,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;IACzF,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,sBAAsB,GAAG,gBAAgB,EAAE,CAAC;IACjF,UAAU,IAAI,MAAM,CAAC,UAAU,CAAC;IAChC,YAAY,IAAI,MAAM,CAAC;IACvB,cAAc,CACZ,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,sBAAsB,EAC9B,SAAS,CAAC,EAAE,OAAO,GAClB,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACpE;AAmOD;;;GAGG;AACH,eAAO,MAAM,UAAU;IACrB;;OAEG;cACO,WAAW;EAGrB,CAAC"}

package/src/cli/commands/NewCommand.js

@@ -70,14 +70,14 @@ const toConfigResult = (config) => ({
 const getQuestions = (name, defaults) => {
     return [
         {
-            type: 'list',
+            type: 'rawlist',
             name: 'template',
             message: 'Project template:',
-            choices: ['basic', 'api', 'microservice'],
+            choices: ['basic', 'api', 'microservice', 'fullstack'],
             default: defaults.template,
         },
         {
-            type: 'list',
+            type: 'rawlist',
             name: 'database',
             message: 'Database driver:',
             choices: ['sqlite', 'mysql', 'postgresql', 'mongodb'],
@@ -150,6 +150,27 @@ const isFailureResult = (result) => {
     const maybe = result;
     return maybe.success === false;
 };
+const promptForPackageManager = async (defaultPm) => {
+    const choices = [
+        { name: 'npm', value: 'npm' },
+        { name: 'yarn', value: 'yarn' },
+        { name: 'pnpm', value: 'pnpm' },
+        { name: 'bun', value: 'bun' },
+        { name: 'Skip installation', value: null },
+    ];
+    const answer = await PromptHelper.prompt([
+        {
+            type: 'rawlist',
+            name: 'packageManager',
+            message: 'Select package manager for dependency installation:',
+            choices,
+            default: defaultPm,
+        },
+    ]);
+    if (typeof answer !== 'object' || answer === null)
+        return null;
+    return answer['packageManager'] ?? null;
+};
 const installDependencies = async (projectPath, log, packageManager, force = false) => {
     // Respect CI by default — avoid network installs in CI unless explicitly allowed
     const isCi = Boolean(process.env['CI']);
@@ -158,6 +179,10 @@ const installDependencies = async (projectPath, log, packageManager, force = fal
         log.info('Skipping automatic dependency installation in CI environment.');
         return;
     }
+    if (packageManager === null) {
+        log.info('⏭️  Skipping dependency installation (not selected).');
+        return;
+    }
     log.info('📦 Installing dependencies (this may take a minute)...');
     const pm = packageManager ?? resolvePackageManager();
     const args = ['install'];
@@ -175,7 +200,7 @@ const installDependencies = async (projectPath, log, packageManager, force = fal
 };
 const addOptions = (command) => {
     command.argument('<name>', 'Project name');
-    command.option('--template <type>', 'Project template (basic, api, microservice)', 'basic');
+    command.option('--template <type>', 'Project template (basic, api, microservice, fullstack)', 'basic');
     command.option('--database <type>', 'Database driver (sqlite, mysql, postgresql)', 'sqlite');
     command.option('--port <number>', 'Default port number', '3003');
     command.option('--author <name>', 'Project author');
@@ -189,31 +214,90 @@ const addOptions = (command) => {
     command.option('--force', 'Overwrite existing directory');
     command.option('--overwrite', 'Overwrite existing directory');
 };
-const executeNewCommand = async (options, command) => {
-    try {
-        const argName = options.args?.[0];
-        const projectName = argName ?? (await PromptHelper.projectName('my-zintrust-app', true));
-        if (!projectName)
-            throw ErrorFactory.createCliError('Project name is required');
-        const config = await command.getProjectConfig(projectName, options);
-        command.info(chalk.bold(`\n🚀 Creating new Zintrust project in ${projectName}...\n`));
-        const overwrite = options['overwrite'] === true || options['force'] === true ? true : undefined;
-        const result = await command.runScaffolding(projectName, config, overwrite);
-        if (isFailureResult(result)) {
-            throw ErrorFactory.createCliError(result.message ?? 'Project scaffolding failed', result);
-        }
-        if (options['git'] !== false) {
-            command.initializeGit(projectName);
+const resolveProjectName = async (options) => {
+    const argName = options.args?.[0];
+    const projectName = argName ?? (await PromptHelper.projectName('my-zintrust-app', true));
+    if (!projectName)
+        throw ErrorFactory.createCliError('Project name is required');
+    return projectName;
+};
+const resolveProjectTarget = async (options) => {
+    const input = await resolveProjectName(options);
+    const isPathLike = input.includes('/') || input.includes('\\');
+    if (!isPathLike) {
+        return {
+            basePath: process.cwd(),
+            name: input,
+            projectPath: path.resolve(process.cwd(), input),
+            display: input,
+            cdPath: input,
+        };
+    }
+    const projectPath = path.resolve(process.cwd(), input);
+    const name = path.basename(projectPath);
+    const basePath = path.dirname(projectPath);
+    const cdPath = input.startsWith('/') ? projectPath : input;
+    return {
+        basePath,
+        name,
+        projectPath,
+        display: input,
+        cdPath,
+    };
+};
+const createProject = async (target, options, command) => {
+    const config = await command.getProjectConfig(target.name, options);
+    command.info(chalk.bold(`\n🚀 Creating new Zintrust project in ${target.display}...\n`));
+    const overwrite = options['overwrite'] === true || options['force'] === true ? true : undefined;
+    const result = await command.runScaffolding(target.basePath, target.name, config, overwrite);
+    if (isFailureResult(result)) {
+        throw ErrorFactory.createCliError(result.message ?? 'Project scaffolding failed', result);
+    }
+};
+const maybeInitializeGit = (options, command, target) => {
+    if (options['git'] !== false) {
+        command.initializeGit(target.projectPath);
+    }
+};
+const maybeInstallDependencies = async (options, command, target) => {
+    if (options['install'] === false)
+        return;
+    const projectPath = target.projectPath;
+    let pm = options['packageManager'] ??
+        options['package-manager'];
+    // If no package manager specified and not in non-interactive mode, prompt user
+    if (pm === undefined && options['interactive'] !== false && options['no-interactive'] !== true) {
+        const defaultPm = resolvePackageManager();
+        const selectedPm = await command.promptForPackageManager(defaultPm);
+        if (selectedPm === null) {
+            command.info('⏭️  Skipping dependency installation.');
+            pm = '__skip__'; // Signal to skip installation
         }
-        if (options['install'] !== false) {
-            const projectPath = path.resolve(process.cwd(), projectName);
-            const pm = options['packageManager'] ??
-                options['package-manager'];
-            const force = options['install'] === true;
-            await installDependencies(projectPath, command, pm, force);
+        else {
+            pm = selectedPm;
         }
-        command.success(`\n✨ Project ${projectName} created successfully!`);
-        command.info(`\nNext steps:\n  cd ${projectName}\n  npm run dev\n`);
+    }
+    const force = options['install'] === true;
+    if (pm === '__skip__')
+        return;
+    const effectivePm = pm ?? resolvePackageManager();
+    await installDependencies(projectPath, command, pm, force);
+    return effectivePm;
+};
+const executeNewCommand = async (options, command) => {
+    try {
+        const target = await resolveProjectTarget(options);
+        await createProject(target, options, command);
+        maybeInitializeGit(options, command, target);
+        const installedWithPm = await maybeInstallDependencies(options, command, target);
+        command.success(`\n✨ Project ${target.name} created successfully!`);
+        const optPm = options['packageManager'] ??
+            options['package-manager'];
+        const effectivePm = installedWithPm ?? optPm ?? resolvePackageManager();
+        const runDevCmd = effectivePm === 'yarn' || effectivePm === 'pnpm'
+            ? `${effectivePm} dev`
+            : `${effectivePm} run dev`;
+        command.info(`\nNext steps:\n  cd ${target.cdPath}\n  ${runDevCmd}\n`);
     }
     catch (error) {
         throw ErrorFactory.createCliError(`Project creation failed: ${extractErrorMessage(error)}`, error);
@@ -257,8 +341,8 @@ const createNewCommandInstance = () => {
         getProjectConfig: async (name, options) => {
             return commandInstance.promptForConfig(name, options);
         },
-        runScaffolding: async (name, config, overwrite) => {
-            return ProjectScaffolder.scaffold(process.cwd(), {
+        runScaffolding: async (basePath, name, config, overwrite) => {
+            return ProjectScaffolder.scaffold(basePath, {
                 name,
                 force: overwrite === true,
                 template: config.template,
@@ -268,12 +352,14 @@ const createNewCommandInstance = () => {
                 description: config.description,
             });
         },
-        initializeGit: (name) => {
-            const projectPath = path.resolve(process.cwd(), name);
+        initializeGit: (projectPath) => {
             if (checkGitInstalled()) {
                 initializeGitRepo(projectPath, commandInstance);
             }
         },
+        promptForPackageManager: async (defaultPm) => {
+            return promptForPackageManager(defaultPm);
+        },
         execute: async (options) => {
             await executeNewCommand(options, commandInstance);
         },

package/src/cli/scaffolding/ProjectScaffolder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ProjectScaffolder.d.ts","sourceRoot":"","sources":["../../../../src/cli/scaffolding/ProjectScaffolder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,cAAc,GAAG,sBAAsB,CAAC;AAEpD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,cAAc,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACtD,YAAY,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,eAAe,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAAC;IACpE,cAAc,IAAI,MAAM,CAAC;IACzB,sBAAsB,IAAI,OAAO,CAAC;IAClC,iBAAiB,IAAI,MAAM,CAAC;IAC5B,WAAW,CAAC,OAAO,CAAC,EAAE,sBAAsB,GAAG,MAAM,CAAC;IACtD,gBAAgB,IAAI,OAAO,CAAC;IAC5B,aAAa,IAAI,OAAO,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;CAC3E;AAqWD,wBAAgB,qBAAqB,IAAI,MAAM,EAAE,CAEhD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAMrE;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG;IAChE,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAsBA;AAwID;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,GAAE,MAAsB,GAAG,kBAAkB,CAsB/F;AAED,wBAAsB,eAAe,CACnC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,qBAAqB,CAAC,CAEhC;AAED;;GAEG;AACH,eAAO,MAAM,iBAAiB;;;;;;EAM5B,CAAC"}
+{"version":3,"file":"ProjectScaffolder.d.ts","sourceRoot":"","sources":["../../../../src/cli/scaffolding/ProjectScaffolder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,cAAc,GAAG,sBAAsB,CAAC;AAEpD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,cAAc,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACtD,YAAY,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,eAAe,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAAC;IACpE,cAAc,IAAI,MAAM,CAAC;IACzB,sBAAsB,IAAI,OAAO,CAAC;IAClC,iBAAiB,IAAI,MAAM,CAAC;IAC5B,WAAW,CAAC,OAAO,CAAC,EAAE,sBAAsB,GAAG,MAAM,CAAC;IACtD,gBAAgB,IAAI,OAAO,CAAC;IAC5B,aAAa,IAAI,OAAO,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;CAC3E;AAqWD,wBAAgB,qBAAqB,IAAI,MAAM,EAAE,CAEhD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAsBrE;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG;IAChE,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAsBA;AAwID;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,GAAE,MAAsB,GAAG,kBAAkB,CAsB/F;AAED,wBAAsB,eAAe,CACnC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,qBAAqB,CAAC,CAEhC;AAED;;GAEG;AACH,eAAO,MAAM,iBAAiB;;;;;;EAM5B,CAAC"}

package/src/cli/scaffolding/ProjectScaffolder.js

@@ -317,7 +317,21 @@ export function getTemplate(name) {
     if (!fallback)
         return undefined;
     const disk = loadTemplateFromDisk(name, fallback);
-    return disk ?? fallback;
+    if (disk)
+        return disk;
+    // If we don't have a dedicated disk template yet (e.g. fullstack/api/microservice),
+    // fall back to the starter project's file set so generated projects are runnable.
+    if (name !== 'basic') {
+        const basicFallback = TEMPLATE_MAP.get('basic');
+        const basicDisk = basicFallback ? loadTemplateFromDisk('basic', basicFallback) : undefined;
+        if (basicDisk) {
+            return {
+                ...fallback,
+                files: basicDisk.files,
+            };
+        }
+    }
+    return fallback;
 }
 export function validateOptions(options) {
     const errors = [];

package/src/index.d.ts

@@ -24,6 +24,10 @@ export { QueryBuilder } from './orm/QueryBuilder';
 export type { IRelationship } from './orm/Relationships';
 export { Router } from './routing/Router';
 export type { IRouter } from './routing/Router';
+export { delay, ensureDirSafe } from './common/index';
+export { HttpClient } from './tools/http/Http';
+export type { IHttpRequest, IHttpResponse } from './tools/http/Http';
+export type { DatabaseConfig, ID1Database } from './orm/DatabaseAdapter';
 export { MemoryProfiler } from './profiling/MemoryProfiler';
 export { N1Detector } from './profiling/N1Detector';
 export { QueryLogger } from './profiling/QueryLogger';
@@ -32,12 +36,13 @@ export type { MemoryDelta, MemorySnapshot, N1Pattern, ProfileReport, QueryLogEnt
 export { ValidationError } from './validation/ValidationError';
 export type { FieldError } from './validation/ValidationError';
 export { Schema, Validator } from './validation/Validator';
+export type { ISchema, SchemaType } from './validation/Validator';
 export { CsrfTokenManager } from './security/CsrfTokenManager';
-export type { CsrfTokenData } from './security/CsrfTokenManager';
+export type { CsrfTokenData, CsrfTokenManagerType, ICsrfTokenManager, } from './security/CsrfTokenManager';
 export { Encryptor } from './security/Encryptor';
 export { Hash } from './security/Hash';
 export { JwtManager } from './security/JwtManager';
-export type { JwtOptions, JwtPayload } from './security/JwtManager';
+export type { IJwtManager, JwtAlgorithm, JwtManagerType, JwtOptions, JwtPayload, } from './security/JwtManager';
 export { Xss } from './security/Xss';
 export { XssProtection } from './security/XssProtection';
 export { ErrorFactory } from './exceptions/ZintrustError';

package/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}

package/src/index.js

@@ -18,6 +18,10 @@ export { Database, resetDatabase, useDatabase } from './orm/Database';
 export { Model } from './orm/Model';
 export { QueryBuilder } from './orm/QueryBuilder';
 export { Router } from './routing/Router';
+// Common
+export { delay, ensureDirSafe } from './common/index';
+// HTTP Client
+export { HttpClient } from './tools/http/Http';
 // Profiling
 export { MemoryProfiler } from './profiling/MemoryProfiler';
 export { N1Detector } from './profiling/N1Detector';

package/src/scripts/TemplateSync.js

@@ -85,7 +85,10 @@ const syncProjectTemplateDir = (params) => {
     let updated = 0;
     let skipped = 0;
     for (const file of files) {
-        const baseKey = `${params.baseDirRel}/${file.relPath}`;
+        const checksumSaltPart = typeof params.checksumSalt === 'string' && params.checksumSalt.length > 0
+            ? `|${params.checksumSalt}`
+            : '';
+        const baseKey = `${params.baseDirRel}/${file.relPath}${checksumSaltPart}`;
         const currentHash = hashFile(file.absPath);
         const storedHash = params.checksums[baseKey];
         const outRel = `${file.relPath}.tpl`;
@@ -108,6 +111,29 @@ const syncProjectTemplateDir = (params) => {
     }
     return { updated, skipped, total: files.length };
 };
+const rewriteStarterTemplateImports = (relPath, content) => {
+    if (!relPath.endsWith('.ts') && !relPath.endsWith('.tsx') && !relPath.endsWith('.mts')) {
+        return content;
+    }
+    // Starter templates should import framework APIs from the public package surface,
+    // not from internal path-alias modules that only exist in the framework repo.
+    return (content
+        .replaceAll("'@routing/Router'", "'@zintrust/core'")
+        .replaceAll("'@orm/Database'", "'@zintrust/core'")
+        .replaceAll("'@orm/QueryBuilder'", "'@zintrust/core'")
+        .replaceAll("'@orm/DatabaseAdapter'", "'@zintrust/core'")
+        .replaceAll("'@exceptions/ZintrustError'", "'@zintrust/core'")
+        .replaceAll("'@common/index'", "'@zintrust/core'")
+        .replaceAll("'@httpClient/Http'", "'@zintrust/core'")
+        // Handle double-quoted module specifiers too
+        .replaceAll('"@routing/Router"', '"@zintrust/core"')
+        .replaceAll('"@orm/Database"', '"@zintrust/core"')
+        .replaceAll('"@orm/QueryBuilder"', '"@zintrust/core"')
+        .replaceAll('"@orm/DatabaseAdapter"', '"@zintrust/core"')
+        .replaceAll('"@exceptions/ZintrustError"', '"@zintrust/core"')
+        .replaceAll('"@common/index"', '"@zintrust/core"')
+        .replaceAll('"@httpClient/Http"', '"@zintrust/core"'));
+};
 const syncRegistryMappings = (params) => {
     let updated = 0;
     let skipped = 0;
@@ -190,6 +216,8 @@ const syncStarterProjectTemplates = (params) => {
         baseDirRel: 'src/config',
         templateDirRel: `${params.projectRoot}/config`,
         description: 'Starter project config/* (from src/config/*)',
+        transformContent: rewriteStarterTemplateImports,
+        checksumSalt: 'starter-imports-v1',
     });
     const s3 = syncProjectTemplateDir({
         checksums: params.checksums,
@@ -202,6 +230,8 @@ const syncStarterProjectTemplates = (params) => {
         baseDirRel: 'routes',
         templateDirRel: `${params.projectRoot}/routes`,
         description: 'Starter project routes/*',
+        transformContent: rewriteStarterTemplateImports,
+        checksumSalt: 'starter-imports-v1',
     });
     const s5 = syncStarterEnvTemplate({
         checksums: params.checksums,

package/src/security/XssProtection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"XssProtection.d.ts","sourceRoot":"","sources":["../../../src/security/XssProtection.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAoSH;;GAEG;AACH,eAAO,MAAM,UAAU,GAAI,KAAK,OAAO,KAAG,MAGzC,CAAC;AAEF,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACjC,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAChC,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAAC;CAClC;AAED;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,cAO1B,CAAC"}
+{"version":3,"file":"XssProtection.d.ts","sourceRoot":"","sources":["../../../src/security/XssProtection.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA2SH;;GAEG;AACH,eAAO,MAAM,UAAU,GAAI,KAAK,OAAO,KAAG,MAGzC,CAAC;AAEF,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACjC,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAChC,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAAC;CAClC;AAED;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,cAO1B,CAAC"}

package/src/security/XssProtection.js

@@ -36,8 +36,12 @@ const sanitizeHtml = (html) => {
     // Remove iframe, object, embed, and base tags
     sanitized = sanitized.replaceAll(/<(?:iframe|object|embed|base)\b[\s\S]*?>/gi, '');
     sanitized = sanitized.replaceAll(/<\/(?:iframe|object|embed|base)>/gi, '');
-    // Remove event handlers (on*)
-    sanitized = sanitized.replaceAll(/\bon\w+\s*=\s*(?:'[^']*'|"[^"]*"|`[^`]*`|[^\s>]*)/gi, '');
+    // Remove event handlers (on*). Re-apply until stable to avoid incomplete multi-character sanitization.
+    let previousSanitized;
+    do {
+        previousSanitized = sanitized;
+        sanitized = sanitized.replaceAll(/\bon\w+\s*=\s*(?:'[^']*'|"[^"]*"|`[^`]*`|[^\s>]*)/gi, '');
+    } while (sanitized !== previousSanitized);
     // Remove dangerous protocols in URL-bearing attributes.
     // This uses the same protocol normalization logic as encodeHref to prevent obfuscations like:
     //   href="jav&#x61;script:..." or href="java\nscript:..." or href="%6a%61..."

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

@@ -5,7 +5,7 @@
  * This module imports Node built-ins and should be loaded only in Node environments.
  */
 
-import { ensureDirSafe } from '@common/index';
+import { ensureDirSafe } from '@zintrust/core';
 import { Env } from '@config/env';
 import * as fs from '@node-singletons/fs';
 import * as path from '@node-singletons/path';

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

@@ -5,7 +5,7 @@
  */
 
 import { Logger } from '@config/logger';
-import { ErrorFactory } from '@exceptions/ZintrustError';
+import { ErrorFactory } from '@zintrust/core';
 
 export interface CloudflareKV {
   get(key: string): Promise<string | null>;

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

@@ -1,5 +1,5 @@
 import { appConfig } from '@config/app';
-import { ErrorFactory } from '@exceptions/ZintrustError';
+import { ErrorFactory } from '@zintrust/core';
 
 export type StartupConfigValidationError = {
   key: string;

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

@@ -5,7 +5,7 @@
  * This keeps runtime-specific globals out of adapters/drivers.
  */
 
-import type { DatabaseConfig, ID1Database } from '@orm/DatabaseAdapter';
+import type { DatabaseConfig, ID1Database } from '@zintrust/core';
 
 export type WorkersEnv = Record<string, unknown>;
 

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

@@ -9,10 +9,10 @@
  *  - HTTP_LOG_AUTH_TOKEN (optional)
  */
 
-import { delay } from '@common/index';
+import { delay } from '@zintrust/core';
 import { Env } from '@config/env';
-import { ErrorFactory } from '@exceptions/ZintrustError';
-import { HttpClient } from '@httpClient/Http';
+import { ErrorFactory } from '@zintrust/core';
+import { HttpClient } from '@zintrust/core';
 
 export type HttpLogEvent = {
   timestamp: string;

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

@@ -10,8 +10,8 @@
  */
 
 import { Env } from '@config/env';
-import { ErrorFactory } from '@exceptions/ZintrustError';
-import { HttpClient } from '@httpClient/Http';
+import { ErrorFactory } from '@zintrust/core';
+import { HttpClient } from '@zintrust/core';
 
 export type SlackLogEvent = {
   timestamp: string;

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

@@ -7,7 +7,7 @@
 import { appConfig } from '@config/app';
 import { Env } from '@config/env';
 import { Logger } from '@config/logger';
-import { ErrorFactory } from '@exceptions/ZintrustError';
+import { ErrorFactory } from '@zintrust/core';
 
 /**
  * Helper to warn about missing secrets

package/src/templates/project/basic/package.json.tpl

@@ -11,7 +11,7 @@
     "type-check": "tsc --noEmit"
   },
   "dependencies": {
-    "@zintrust/core": "^0.1.1"
+    "@zintrust/core": "^0.1.4"
   },
   "devDependencies": {
     "tsx": "^4.21.0",

package/src/templates/project/basic/routes/api.ts.tpl

@@ -7,7 +7,8 @@ import { UserController } from '@app/Controllers/UserController';
 import { Env } from '@config/env';
 import { registerBroadcastRoutes } from '@routes/broadcast';
 import { registerHealthRoutes } from '@routes/health';
-import { type IRouter, Router } from '@routing/Router';
+import { registerStorageRoutes } from '@routes/storage';
+import { type IRouter, Router } from '@zintrust/core';
 
 export function registerRoutes(router: IRouter): void {
   const userController = UserController.create();
@@ -23,6 +24,7 @@ function registerPublicRoutes(router: IRouter): void {
   registerRootRoute(router);
   registerHealthRoutes(router);
   registerBroadcastRoutes(router);
+  registerStorageRoutes(router);
 }
 
 function registerRootRoute(router: IRouter): void {

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

@@ -5,7 +5,7 @@
  * Provider setup and secret provisioning remain CLI-only.
  */
 
-import { type IRouter, Router } from '@routing/Router';
+import { type IRouter, Router } from '@zintrust/core';
 
 export function registerBroadcastRoutes(router: IRouter): void {
   Router.get(router, '/broadcast/health', async (_req, res) => {

package/src/templates/project/basic/routes/health.ts.tpl

@@ -7,9 +7,9 @@ import { appConfig } from '@/config';
 import { RuntimeHealthProbes } from '@/health/RuntimeHealthProbes';
 import { Env } from '@config/env';
 import { Logger } from '@config/logger';
-import { useDatabase } from '@orm/Database';
-import { QueryBuilder } from '@orm/QueryBuilder';
-import { type IRouter, Router } from '@routing/Router';
+import { useDatabase } from '@zintrust/core';
+import { QueryBuilder } from '@zintrust/core';
+import { type IRouter, Router } from '@zintrust/core';
 
 export function registerHealthRoutes(router: IRouter): void {
   registerHealthRoute(router);

package/src/templates/project/basic/routes/storage.ts.tpl

@@ -0,0 +1,42 @@
+import { HTTP_HEADERS } from '@config/constants';
+import { Env } from '@config/env';
+import { type IRouter, Router } from '@zintrust/core';
+import { LocalSignedUrl } from '@storage/LocalSignedUrl';
+import { Storage } from '@storage/index';
+
+export function registerStorageRoutes(router: IRouter): void {
+  Router.get(router, '/storage/download', async (req, res) => {
+    const tokenRaw = req.getQueryParam('token');
+    const token = typeof tokenRaw === 'string' ? tokenRaw : '';
+
+    if (token.trim() === '') {
+      res.setStatus(400).json({ message: 'Missing token' });
+      return;
+    }
+
+    const appKey = Env.get('APP_KEY', '');
+    if (appKey.trim() === '') {
+      res.setStatus(500).json({ message: 'Storage signing is not configured' });
+      return;
+    }
+
+    try {
+      const payload = LocalSignedUrl.verifyToken(token, appKey);
+
+      // Only local disk is supported by this route.
+      if (payload.disk !== 'local') {
+        res.setStatus(400).json({ message: 'Unsupported disk' });
+        return;
+      }
+
+      const contents = await Storage.get('local', payload.key);
+
+      res.setHeader(HTTP_HEADERS.CONTENT_TYPE, 'application/octet-stream');
+      res.setStatus(200).send(contents);
+    } catch {
+      res.setStatus(403).json({ message: 'Invalid or expired token' });
+    }
+  });
+}
+
+export default registerStorageRoutes;

package/src/templates/project/basic/tsconfig.json.tpl

@@ -1,5 +1,6 @@
 {
   "compilerOptions": {
+    "baseUrl": ".",
     "outDir": "./dist",
     "rootDir": "./",
     "module": "ESNext",
@@ -10,9 +11,22 @@
     "paths": {
       "@/*": ["./src/*"],
       "@app/*": ["./app/*"],
+      "@toolkit/*": ["./app/Toolkit/*"],
       "@config/*": ["./config/*"],
       "@routes/*": ["./routes/*"],
-      "@database/*": ["./database/*"]
+      "@database/*": ["./database/*"],
+
+      "@tools/*": ["./src/tools/*"],
+      "@httpClient/*": ["./src/tools/http/*"],
+      "@templates": ["./src/tools/templates/index.ts"],
+      "@templates/*": ["./src/tools/templates/*"],
+      "@mail/*": ["./src/tools/mail/*"],
+      "@storage": ["./src/tools/storage/index.ts"],
+      "@storage/*": ["./src/tools/storage/*"],
+      "@drivers/*": ["./src/tools/storage/drivers/*"],
+      "@notification/*": ["./src/tools/notification/*"],
+      "@broadcast/*": ["./src/tools/broadcast/*"],
+      "@queue/*": ["./src/tools/queue/*"]
     }
   },
   "include": ["src/**/*", "app/**/*", "routes/**/*", "database/**/*", "config/**/*"],

package/src/tools/http/Http.d.ts

@@ -1,6 +1,5 @@
 /**
  * Http Client - Fluent HTTP request builder
- * Laravel-style HTTP client for making authenticated requests
  *
  * Usage:
  *   await HttpClient.get('https://api.example.com/users').withAuth(token).send();
@@ -23,7 +22,6 @@ export interface IHttpRequest {
 }
 /**
  * HTTP Client - Sealed namespace for making HTTP requests
- * Provides Laravel-style fluent API
  */
 export declare const HttpClient: Readonly<{
     /**

package/src/tools/http/Http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Http.d.ts","sourceRoot":"","sources":["../../../../src/tools/http/Http.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,EAAsB,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAElF,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE9D;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAAC;IACtD,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,YAAY,CAAC;IAC3D,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,YAAY,CAAC;IACnE,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,YAAY,CAAC;IAChE,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,CAAC;IACtC,MAAM,IAAI,YAAY,CAAC;IACvB,MAAM,IAAI,YAAY,CAAC;IACvB,IAAI,IAAI,OAAO,CAAC,aAAa,CAAC,CAAC;CAChC;AAiJD;;;GAGG;AACH,eAAO,MAAM,UAAU;IACrB;;OAEG;aACM,MAAM,GAAG,YAAY;IAI9B;;OAEG;cACO,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,YAAY;IAQ/D;;OAEG;aACM,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,YAAY;IAQ9D;;OAEG;eACQ,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,YAAY;IAQhE;;OAEG;gBACS,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,YAAY;EAOjE,CAAC;AAEH,eAAe,UAAU,CAAC"}
+{"version":3,"file":"Http.d.ts","sourceRoot":"","sources":["../../../../src/tools/http/Http.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,EAAsB,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAElF,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE9D;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAAC;IACtD,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,YAAY,CAAC;IAC3D,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,YAAY,CAAC;IACnE,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,YAAY,CAAC;IAChE,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,CAAC;IACtC,MAAM,IAAI,YAAY,CAAC;IACvB,MAAM,IAAI,YAAY,CAAC;IACvB,IAAI,IAAI,OAAO,CAAC,aAAa,CAAC,CAAC;CAChC;AAiJD;;GAEG;AACH,eAAO,MAAM,UAAU;IACrB;;OAEG;aACM,MAAM,GAAG,YAAY;IAI9B;;OAEG;cACO,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,YAAY;IAQ/D;;OAEG;aACM,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,YAAY;IAQ9D;;OAEG;eACQ,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,YAAY;IAQhE;;OAEG;gBACS,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,YAAY;EAOjE,CAAC;AAEH,eAAe,UAAU,CAAC"}

package/src/tools/http/Http.js

@@ -1,6 +1,5 @@
 /**
  * Http Client - Fluent HTTP request builder
- * Laravel-style HTTP client for making authenticated requests
  *
  * Usage:
  *   await HttpClient.get('https://api.example.com/users').withAuth(token).send();
@@ -118,7 +117,6 @@ const createRequestBuilder = (method, url, initialBody) => {
 };
 /**
  * HTTP Client - Sealed namespace for making HTTP requests
- * Provides Laravel-style fluent API
  */
 export const HttpClient = Object.freeze({
     /**

package/src/tools/storage/LocalSignedUrl.d.ts

@@ -0,0 +1,12 @@
+export type LocalSignedUrlPayload = {
+    disk: 'local';
+    key: string;
+    exp: number;
+    method: 'GET';
+};
+export declare const LocalSignedUrl: Readonly<{
+    createToken(payload: LocalSignedUrlPayload, secret: string): string;
+    verifyToken(token: string, secret: string, nowMs?: number): LocalSignedUrlPayload;
+}>;
+export default LocalSignedUrl;
+//# sourceMappingURL=LocalSignedUrl.d.ts.map

package/src/tools/storage/LocalSignedUrl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LocalSignedUrl.d.ts","sourceRoot":"","sources":["../../../../src/tools/storage/LocalSignedUrl.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,qBAAqB,GAAG;IAClC,IAAI,EAAE,OAAO,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,KAAK,CAAC;CACf,CAAC;AA8DF,eAAO,MAAM,cAAc;yBACJ,qBAAqB,UAAU,MAAM,GAAG,MAAM;uBAyBhD,MAAM,UAAU,MAAM,UAAS,MAAM,GAAgB,qBAAqB;EA2C7F,CAAC;AAEH,eAAe,cAAc,CAAC"}

package/src/tools/storage/LocalSignedUrl.js

@@ -0,0 +1,108 @@
+import { ErrorFactory } from '../../exceptions/ZintrustError';
+import { createHmac } from '../../node-singletons/crypto';
+const base64UrlEncode = (value) => {
+    const base64 = Buffer.isBuffer(value)
+        ? value.toString('base64')
+        : Buffer.from(value).toString('base64');
+    // replace characters used in regular base64 and remove any trailing '=' padding
+    let result = base64.replaceAll('+', '-').replaceAll('/', '_');
+    // Remove trailing '=' characters without using a regex to avoid potential super-linear backtracking.
+    while (result.endsWith('=')) {
+        result = result.slice(0, -1);
+    }
+    return result;
+};
+const base64UrlDecodeToString = (value) => {
+    const padded = value + '==='.slice((value.length + 3) % 4);
+    const base64 = padded.replaceAll('-', '+').replaceAll('_', '/');
+    return Buffer.from(base64, 'base64').toString('utf8');
+};
+const 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;
+};
+const assertValidKey = (key) => {
+    if (key.trim() === '') {
+        throw ErrorFactory.createValidationError('Local signed url: key is required');
+    }
+    // Hard fail on obvious traversal / absolute paths.
+    // Keep this strict; keys should be relative like `uploads/a.png`.
+    if (key.startsWith('/') || key.startsWith('\\')) {
+        throw ErrorFactory.createValidationError('Local signed url: key must be relative');
+    }
+    const segments = key.split(/[/\\]+/g);
+    if (segments.some((s) => s === '..' || s === '.')) {
+        throw ErrorFactory.createValidationError('Local signed url: invalid key');
+    }
+    if (key.includes('\0')) {
+        throw ErrorFactory.createValidationError('Local signed url: invalid key');
+    }
+};
+const sign = (payloadEncoded, secret) => {
+    if (secret.trim() === '') {
+        throw ErrorFactory.createConfigError('Local signed url: signing secret not configured (set APP_KEY)');
+    }
+    const signature = createHmac('sha256', secret).update(payloadEncoded).digest();
+    return base64UrlEncode(signature);
+};
+export const LocalSignedUrl = Object.freeze({
+    createToken(payload, secret) {
+        assertValidKey(payload.key);
+        if (payload.disk !== 'local') {
+            throw ErrorFactory.createValidationError('Local signed url: unsupported disk', {
+                disk: payload.disk,
+            });
+        }
+        if (payload.method !== 'GET') {
+            throw ErrorFactory.createValidationError('Local signed url: unsupported method', {
+                method: payload.method,
+            });
+        }
+        if (!Number.isFinite(payload.exp) || payload.exp <= 0) {
+            throw ErrorFactory.createValidationError('Local signed url: invalid expiration');
+        }
+        const payloadEncoded = base64UrlEncode(JSON.stringify(payload));
+        const signatureEncoded = sign(payloadEncoded, secret);
+        return `${payloadEncoded}.${signatureEncoded}`;
+    },
+    verifyToken(token, secret, nowMs = Date.now()) {
+        if (token.trim() === '') {
+            throw ErrorFactory.createValidationError('Local signed url: token is required');
+        }
+        const parts = token.split('.');
+        if (parts.length !== 2) {
+            throw ErrorFactory.createValidationError('Local signed url: malformed token');
+        }
+        const payloadEncoded = parts[0] ?? '';
+        const signatureEncoded = parts[1] ?? '';
+        const expectedSignature = sign(payloadEncoded, secret);
+        if (!timingSafeEquals(signatureEncoded, expectedSignature)) {
+            throw ErrorFactory.createSecurityError('Local signed url: invalid signature');
+        }
+        let payload;
+        try {
+            payload = JSON.parse(base64UrlDecodeToString(payloadEncoded));
+        }
+        catch (err) {
+            throw ErrorFactory.createValidationError('Local signed url: invalid payload', { error: err });
+        }
+        const p = payload;
+        if (p.disk !== 'local' ||
+            typeof p.key !== 'string' ||
+            typeof p.exp !== 'number' ||
+            p.method !== 'GET') {
+            throw ErrorFactory.createValidationError('Local signed url: invalid payload');
+        }
+        assertValidKey(p.key);
+        if (p.exp < nowMs) {
+            throw ErrorFactory.createSecurityError('Local signed url: token expired');
+        }
+        return p;
+    },
+});
+export default LocalSignedUrl;

package/src/tools/storage/drivers/Local.d.ts

@@ -3,12 +3,13 @@ export type LocalConfig = {
     url?: string;
 };
 export declare const LocalDriver: Readonly<{
+    resolveKey(config: LocalConfig, key: string): string;
     put(config: LocalConfig, key: string, content: string | Buffer): Promise<string>;
     get(config: LocalConfig, key: string): Promise<Buffer>;
     exists(config: LocalConfig, key: string): Promise<boolean>;
     delete(config: LocalConfig, key: string): Promise<void>;
     url(config: LocalConfig, key: string): string | undefined;
-    tempUrl(config: LocalConfig, key: string, _options?: {
+    tempUrl(config: LocalConfig, key: string, options?: {
         expiresIn?: number;
         method?: "GET" | "PUT";
     }): string;

package/src/tools/storage/drivers/Local.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Local.d.ts","sourceRoot":"","sources":["../../../../../src/tools/storage/drivers/Local.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,eAAO,MAAM,WAAW;gBACJ,WAAW,OAAO,MAAM,WAAW,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;gBAkBpE,WAAW,OAAO,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;mBASvC,WAAW,OAAO,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;mBAU3C,WAAW,OAAO,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;gBAUjD,WAAW,OAAO,MAAM,GAAG,MAAM,GAAG,SAAS;oBAM/C,WAAW,OACd,MAAM,aACA;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,KAAK,GAAG,KAAK,CAAA;KAAE,GACxD,MAAM;EAST,CAAC;AAEH,eAAe,WAAW,CAAC"}
+{"version":3,"file":"Local.d.ts","sourceRoot":"","sources":["../../../../../src/tools/storage/drivers/Local.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,eAAO,MAAM,WAAW;uBACH,WAAW,OAAO,MAAM,GAAG,MAAM;gBAuBlC,WAAW,OAAO,MAAM,WAAW,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;gBAapE,WAAW,OAAO,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;mBASvC,WAAW,OAAO,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;mBAU3C,WAAW,OAAO,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;gBASjD,WAAW,OAAO,MAAM,GAAG,MAAM,GAAG,SAAS;oBAM/C,WAAW,OACd,MAAM,YACD;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,KAAK,GAAG,KAAK,CAAA;KAAE,GACvD,MAAM;EA4BT,CAAC;AAEH,eAAe,WAAW,CAAC"}

package/src/tools/storage/drivers/Local.js

@@ -1,13 +1,28 @@
+import { Env } from '../../../config/env';
 import { ErrorFactory } from '../../../exceptions/ZintrustError';
 import { fsPromises as fs } from '../../../node-singletons/fs';
 import * as path from '../../../node-singletons/path';
+import { LocalSignedUrl } from '../LocalSignedUrl';
 export const LocalDriver = Object.freeze({
-    async put(config, key, content) {
-        const root = config.root;
-        if (!root || root.trim() === '') {
+    resolveKey(config, key) {
+        if (!config.root || config.root.trim() === '') {
             throw ErrorFactory.createConfigError('Local storage root is not configured');
         }
-        const fullPath = path.join(root, key);
+        if (key.trim() === '') {
+            throw ErrorFactory.createValidationError('Local storage: key is required');
+        }
+        if (key.startsWith('/') || key.startsWith('\\')) {
+            throw ErrorFactory.createValidationError('Local storage: key must be relative');
+        }
+        const segments = key.split(/[/\\]+/g);
+        if (segments.some((s) => s === '..' || s === '.')) {
+            throw ErrorFactory.createValidationError('Local storage: invalid key');
+        }
+        const fullPath = path.resolve(path.join(config.root, key));
+        return fullPath;
+    },
+    async put(config, key, content) {
+        const fullPath = LocalDriver.resolveKey(config, key);
         const dir = path.dirname(fullPath);
         await fs.mkdir(dir, { recursive: true });
         if (typeof content === 'string') {
@@ -19,7 +34,7 @@ export const LocalDriver = Object.freeze({
         return fullPath;
     },
     async get(config, key) {
-        const fullPath = path.join(config.root, key);
+        const fullPath = LocalDriver.resolveKey(config, key);
         try {
             return await fs.readFile(fullPath);
         }
@@ -28,7 +43,7 @@ export const LocalDriver = Object.freeze({
         }
     },
     async exists(config, key) {
-        const fullPath = path.join(config.root, key);
+        const fullPath = LocalDriver.resolveKey(config, key);
         try {
             await fs.access(fullPath);
             return true;
@@ -38,13 +53,12 @@ export const LocalDriver = Object.freeze({
         }
     },
     async delete(config, key) {
-        const fullPath = path.join(config.root, key);
+        const fullPath = LocalDriver.resolveKey(config, key);
         try {
             await fs.unlink(fullPath);
         }
-        catch (err) {
+        catch {
             // ignore not found
-            void err; // NOSONAR
         }
     },
     url(config, key) {
@@ -52,12 +66,24 @@ export const LocalDriver = Object.freeze({
             return undefined;
         return `${config.url.replace(/\/$/, '')}/${key}`;
     },
-    tempUrl(config, key, _options) {
-        const url = LocalDriver.url(config, key);
-        if (url === undefined) {
+    tempUrl(config, key, options) {
+        if (options?.method === 'PUT') {
+            throw ErrorFactory.createValidationError('Local storage: tempUrl does not support PUT');
+        }
+        if (config?.url === undefined || config.url.trim() === '') {
             throw ErrorFactory.createConfigError('Local storage: url is not configured (set STORAGE_URL)');
         }
-        return url;
+        const appKey = Env.get('APP_KEY', '');
+        if (appKey.trim() === '') {
+            throw ErrorFactory.createConfigError('Local storage: APP_KEY is required for signed tempUrl()');
+        }
+        // Ensure key is safe before embedding in a signed token.
+        LocalDriver.resolveKey(config, key);
+        const expiresInMs = Math.max(1, options?.expiresIn ?? 60_000);
+        const exp = Date.now() + expiresInMs;
+        const token = LocalSignedUrl.createToken({ disk: 'local', key, exp, method: 'GET' }, appKey);
+        const baseUrl = config.url.replace(/\/$/, '');
+        return `${baseUrl}/download?token=${encodeURIComponent(token)}`;
     },
 });
 export default LocalDriver;

package/src/tools/storage/index.d.ts

@@ -18,7 +18,7 @@ export declare const Storage: Readonly<{
     exists(disk: string | undefined, path: string): Promise<boolean>;
     delete(disk: string | undefined, path: string): Promise<void>;
     url(disk: string | undefined, path: string): string;
-    tempUrl(disk: string | undefined, path: string, options?: TempUrlOptions): string;
+    tempUrl(disk: string | undefined, path: string, options?: TempUrlOptions): Promise<string>;
 }>;
 export default Storage;
 //# sourceMappingURL=index.d.ts.map

package/src/tools/storage/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/tools/storage/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAE/C,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,IAAI,GAAG,KAAK,GAAG,IAAI,CAAC;AAErD,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,EAAE,OAAO,WAAW,GAAG,OAAO,QAAQ,GAAG,OAAO,QAAQ,GAAG,OAAO,SAAS,CAAC;IAClF,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,KAAK,cAAc,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,KAAK,GAAG,KAAK,CAAA;CAAE,CAAC;AAsCrE,eAAO,MAAM,OAAO;mBACH,MAAM,GAAG,WAAW;cAqBnB,MAAM,GAAG,SAAS,QAAQ,MAAM,YAAY,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;cAW7E,MAAM,GAAG,SAAS,QAAQ,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;iBAW/C,MAAM,GAAG,SAAS,QAAQ,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;iBASnD,MAAM,GAAG,SAAS,QAAQ,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;cASzD,MAAM,GAAG,SAAS,QAAQ,MAAM,GAAG,MAAM;kBAYrC,MAAM,GAAG,SAAS,QAAQ,MAAM,YAAY,cAAc,GAAG,MAAM;EAiBjF,CAAC;AAEH,eAAe,OAAO,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/tools/storage/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAGxD,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAE/C,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,IAAI,GAAG,KAAK,GAAG,IAAI,CAAC;AAErD,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,EAAE,OAAO,WAAW,GAAG,OAAO,QAAQ,GAAG,OAAO,QAAQ,GAAG,OAAO,SAAS,CAAC;IAClF,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,KAAK,cAAc,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,KAAK,GAAG,KAAK,CAAA;CAAE,CAAC;AAsCrE,eAAO,MAAM,OAAO;mBACH,MAAM,GAAG,WAAW;cAqBnB,MAAM,GAAG,SAAS,QAAQ,MAAM,YAAY,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;cAW7E,MAAM,GAAG,SAAS,QAAQ,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;iBAW/C,MAAM,GAAG,SAAS,QAAQ,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;iBASnD,MAAM,GAAG,SAAS,QAAQ,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;cASzD,MAAM,GAAG,SAAS,QAAQ,MAAM,GAAG,MAAM;kBAY/B,MAAM,GAAG,SAAS,QAAQ,MAAM,YAAY,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;EAqBhG,CAAC;AAEH,eAAe,OAAO,CAAC"}

package/src/tools/storage/index.js

@@ -1,7 +1,6 @@
+import { GcsDriver } from '../../tools/storage/drivers/Gcs';
 import { storageConfig } from '../../config/storage';
 import { ErrorFactory } from '../../exceptions/ZintrustError';
-// import { GcsDriver } from './drivers/Gcs';
-import { GcsDriver } from '../../tools/storage/drivers/Gcs';
 import { LocalDriver } from './drivers/Local';
 import { R2Driver } from './drivers/R2';
 import { S3Driver } from './drivers/S3';
@@ -71,7 +70,7 @@ export const Storage = Object.freeze({
         if (typeof driver.get !== 'function') {
             throw ErrorFactory.createConfigError('Storage: driver is missing get()');
         }
-        return Promise.resolve(driver.get(d.config, path));
+        return driver.get(d.config, path);
     },
     async exists(disk, path) {
         const d = Storage.getDisk(disk);
@@ -96,11 +95,11 @@ export const Storage = Object.freeze({
         }
         return url;
     },
-    tempUrl(disk, path, options) {
+    async tempUrl(disk, path, options) {
         const d = Storage.getDisk(disk);
         const driver = d.driver;
         if (typeof driver.tempUrl === 'function') {
-            return driver.tempUrl(d.config, path, options);
+            return Promise.resolve(driver.tempUrl(d.config, path, options));
         }
         const url = typeof driver.url === 'function' ? driver.url(d.config, path) : undefined;
         if (typeof url !== 'string' || url.trim() === '') {

package/src/tools/storage/testing.d.ts

@@ -13,7 +13,7 @@ export declare const FakeStorage: Readonly<{
     tempUrl(disk: string, path: string, options?: {
         expiresIn?: number;
         method?: "GET" | "PUT";
-    }): string;
+    }): Promise<string>;
     assertExists(disk: string, path: string): void;
     assertMissing(disk: string, path: string): void;
     getPuts(): FakePut[];

package/src/tools/storage/testing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../../../../src/tools/storage/testing.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,OAAO,GAAG;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAIF,eAAO,MAAM,WAAW;WACT,KAAK,CAAC,OAAO,CAAC;cAEX,MAAM,QAAQ,MAAM,YAAY,MAAM;cAM5C,MAAM,QAAQ,MAAM;iBAMjB,MAAM,QAAQ,MAAM;iBAId,MAAM,QAAQ,MAAM;cAW7B,MAAM,QAAQ,MAAM;kBAKhB,MAAM,QAAQ,MAAM,YAAY;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,KAAK,GAAG,KAAK,CAAA;KAAE;uBAOzE,MAAM,QAAQ,MAAM;wBAMnB,MAAM,QAAQ,MAAM;;;EAgBxC,CAAC;AAEH,eAAe,WAAW,CAAC"}
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../../../../src/tools/storage/testing.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,OAAO,GAAG;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAIF,eAAO,MAAM,WAAW;WACT,KAAK,CAAC,OAAO,CAAC;cAEX,MAAM,QAAQ,MAAM,YAAY,MAAM;cAM5C,MAAM,QAAQ,MAAM;iBAMjB,MAAM,QAAQ,MAAM;iBAId,MAAM,QAAQ,MAAM;cAW7B,MAAM,QAAQ,MAAM;kBAMtB,MAAM,QACN,MAAM,YACF;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,KAAK,GAAG,KAAK,CAAA;KAAE;uBASvC,MAAM,QAAQ,MAAM;wBAMnB,MAAM,QAAQ,MAAM;;;EAgBxC,CAAC;AAEH,eAAe,WAAW,CAAC"}

package/src/tools/storage/testing.js

@@ -25,9 +25,10 @@ export const FakeStorage = Object.freeze({
         return `fake://${disk}/${path}`;
     },
     // tempUrl builder is a convenience: matches the real API shape
-    tempUrl(disk, path, options) {
+    async tempUrl(disk, path, options) {
         const expiresIn = options?.expiresIn ?? 900;
         const method = options?.method ?? 'GET';
+        await Promise.resolve();
         return `fake://${disk}/${path}?expiresIn=${expiresIn}&method=${method}`;
     },
     // Test assertions