@zintrust/core 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zintrust/core",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "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/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/routes/api.ts.tpl

@@ -7,6 +7,7 @@ import { UserController } from '@app/Controllers/UserController';
 import { Env } from '@config/env';
 import { registerBroadcastRoutes } from '@routes/broadcast';
 import { registerHealthRoutes } from '@routes/health';
+import { registerStorageRoutes } from '@routes/storage';
 import { type IRouter, Router } from '@routing/Router';
 
 export function registerRoutes(router: IRouter): void {
@@ -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/storage.ts.tpl

@@ -0,0 +1,42 @@
+import { HTTP_HEADERS } from '@config/constants';
+import { Env } from '@config/env';
+import { type IRouter, Router } from '@routing/Router';
+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/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;uBAQvC,MAAM,QAAQ,MAAM;wBAMnB,MAAM,QAAQ,MAAM;;;EAgBxC,CAAC;AAEH,eAAe,WAAW,CAAC"}

package/src/tools/storage/testing.js

@@ -25,7 +25,7 @@ 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';
         return `fake://${disk}/${path}?expiresIn=${expiresIn}&method=${method}`;