@zintrust/core 0.1.28 → 0.1.30

package/src/tools/queue/drivers/Database.js

@@ -0,0 +1,123 @@
+import { Env } from '../../../config/env.js';
+import { Logger } from '../../../config/logger.js';
+import { ErrorFactory } from '../../../exceptions/ZintrustError.js';
+import { useDatabase } from '../../../orm/Database.js';
+import { QueryBuilder } from '../../../orm/QueryBuilder.js';
+export const DatabaseQueue = (() => {
+    const connections = new Map();
+    const getConnection = (connectionName) => {
+        const name = connectionName ?? Env.get('DB_CONNECTION', 'default');
+        if (!connections.has(name)) {
+            connections.set(name, useDatabase(undefined, name));
+        }
+        const connection = connections.get(name);
+        if (!connection) {
+            throw ErrorFactory.createConfigError(`Database connection '${name}' not found`);
+        }
+        return connection;
+    };
+    const getTableName = () => Env.get('QUEUE_DB_TABLE', 'queue_jobs');
+    return {
+        async enqueue(queue, payload, connectionName) {
+            const db = getConnection(connectionName);
+            const tableName = getTableName();
+            const result = await QueryBuilder.create(tableName, db).insert({
+                queue,
+                payload: JSON.stringify(payload),
+                attempts: 0,
+                max_attempts: Env.getInt('QUEUE_DB_RETRY_ATTEMPTS', 3),
+                created_at: new Date(),
+                available_at: new Date(),
+            });
+            const jobId = result.id;
+            Logger.info(`[DatabaseQueue] Job enqueued: ${jobId} to queue: ${queue}`);
+            return jobId;
+        },
+        async dequeue(queue, connectionName) {
+            const db = getConnection(connectionName);
+            const tableName = getTableName();
+            const visibilityTimeout = Env.getInt('QUEUE_DB_VISIBILITY_TIMEOUT', 30);
+            const timeoutDate = new Date(Date.now() - visibilityTimeout * 1000);
+            // Try to reserve a job using atomic update
+            const result = await db.transaction(async (trx) => {
+                const job = await QueryBuilder.create(tableName, trx)
+                    .select('id', 'payload', 'attempts', 'max_attempts')
+                    .where('queue', '=', queue)
+                    .where('available_at', '<=', new Date())
+                    .where('reserved_at', '=', null)
+                    .orWhere('reserved_at', '<=', timeoutDate)
+                    .where('failed_at', '=', null)
+                    .orderBy('available_at', 'ASC')
+                    .limit(1)
+                    .first();
+                if (!job)
+                    return null;
+                // Check if job has exceeded max attempts
+                if (job.attempts >= job.max_attempts) {
+                    // Move to dead letter queue
+                    await QueryBuilder.create('queue_jobs_failed', trx).insert({
+                        original_id: job.id,
+                        queue,
+                        payload: job.payload,
+                        attempts: job.attempts,
+                        failed_at: new Date(),
+                        error_message: 'Max attempts exceeded',
+                    });
+                    // Remove from active queue
+                    await QueryBuilder.create(tableName, trx).where('id', '=', job.id).delete();
+                    Logger.warn(`[DatabaseQueue] Job ${job.id} exceeded max attempts (${job.max_attempts}), moved to dead letter queue`);
+                    return null;
+                }
+                // Calculate exponential backoff delay
+                const backoffDelay = Math.min(Math.pow(2, job.attempts) * 1000, 30000); // Max 30 seconds
+                const nextAvailableAt = new Date(Date.now() + backoffDelay);
+                // Reserve the job and set next available time
+                await QueryBuilder.create(tableName, trx)
+                    .where('id', '=', job.id)
+                    .update({
+                    reserved_at: new Date(),
+                    attempts: job.attempts + 1,
+                    available_at: nextAvailableAt,
+                });
+                Logger.debug(`[DatabaseQueue] Job ${job.id} reserved, attempt ${job.attempts + 1}/${job.max_attempts}, next available at ${nextAvailableAt.toISOString()}`);
+                return job;
+            });
+            if (!result)
+                return undefined;
+            return {
+                id: result.id,
+                payload: JSON.parse(result.payload),
+                attempts: result.attempts,
+            };
+        },
+        async ack(queue, id, connectionName) {
+            const db = getConnection(connectionName);
+            const tableName = getTableName();
+            await QueryBuilder.create(tableName, db)
+                .where('id', '=', id)
+                .where('queue', '=', queue)
+                .delete();
+            Logger.debug(`[DatabaseQueue] Job acknowledged: ${id} from queue: ${queue}`);
+        },
+        async length(queue, connectionName) {
+            const db = getConnection(connectionName);
+            const tableName = getTableName();
+            const result = await QueryBuilder.create(tableName, db)
+                .select('id')
+                .where('queue', '=', queue)
+                .where('available_at', '<=', new Date())
+                .where('reserved_at', '=', null)
+                .orWhere('reserved_at', '<=', new Date(Date.now() - Env.getInt('QUEUE_DB_VISIBILITY_TIMEOUT', 30) * 1000))
+                .where('failed_at', '=', null)
+                .get();
+            return result?.length ?? 0;
+        },
+        async drain(queue, connectionName) {
+            const db = getConnection(connectionName);
+            const tableName = getTableName();
+            await QueryBuilder.create(tableName, db).where('queue', '=', queue).delete();
+            Logger.info(`[DatabaseQueue] Queue drained: ${queue}`);
+        },
+    };
+})();
+export default DatabaseQueue;

package/src/tools/queue/drivers/InMemory.d.ts

@@ -0,0 +1,10 @@
+import type { QueueMessage } from '../../queue/Queue';
+export declare const InMemoryQueue: {
+    readonly enqueue: <T = unknown>(queue: string, payload: T) => Promise<string>;
+    readonly dequeue: <T = unknown>(queue: string) => Promise<QueueMessage<T> | undefined>;
+    readonly ack: (_queue: string, _id: string) => Promise<void>;
+    readonly length: (queue: string) => Promise<number>;
+    readonly drain: (queue: string) => Promise<void>;
+};
+export default InMemoryQueue;
+//# sourceMappingURL=InMemory.d.ts.map

package/src/tools/queue/drivers/InMemory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InMemory.d.ts","sourceRoot":"","sources":["../../../../../src/tools/queue/drivers/InMemory.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAIvD,eAAO,MAAM,aAAa;uBAQR,CAAC,mBAAmB,MAAM,WAAW,CAAC,KAAG,OAAO,CAAC,MAAM,CAAC;uBAmBxD,CAAC,mBAAmB,MAAM,KAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;2BAW7D,MAAM,OAAO,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;6BAKjC,MAAM,KAAG,OAAO,CAAC,MAAM,CAAC;4BAOzB,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;CAMzC,CAAC;AAEL,eAAe,aAAa,CAAC"}

package/src/tools/queue/drivers/InMemory.js

@@ -0,0 +1,55 @@
+import { generateUuid } from '../../../common/utility.js';
+export const InMemoryQueue = (() => {
+    const store = new Map();
+    const ensure = (queue) => {
+        if (!store.has(queue))
+            store.set(queue, []);
+    };
+    return {
+        async enqueue(queue, payload) {
+            await Promise.resolve();
+            ensure(queue);
+            const id = generateUuid();
+            const msg = {
+                id,
+                payload: payload,
+                attempts: 0,
+                enqueuedAt: Date.now(),
+            };
+            const arr = store.get(queue);
+            if (arr && arr.length > 0) {
+                arr.push(msg);
+            }
+            else {
+                store.set(queue, [msg]);
+            }
+            return id;
+        },
+        async dequeue(queue) {
+            await Promise.resolve();
+            ensure(queue);
+            const arr = store.get(queue);
+            if (arr && arr.length > 0) {
+                const msg = arr.shift();
+                return msg;
+            }
+            return undefined;
+        },
+        async ack(_queue, _id) {
+            // in-memory dequeue already removed the message; ack is a no-op
+            await Promise.resolve();
+        },
+        async length(queue) {
+            await Promise.resolve();
+            ensure(queue);
+            const arr = store.get(queue);
+            return Array.isArray(arr) ? arr.length : 0;
+        },
+        async drain(queue) {
+            await Promise.resolve();
+            ensure(queue);
+            store.set(queue, []);
+        },
+    };
+})();
+export default InMemoryQueue;

package/src/tools/queue/drivers/Redis.d.ts

@@ -0,0 +1,10 @@
+import type { QueueMessage } from '../../queue/Queue';
+export declare const RedisQueue: {
+    readonly enqueue: <T = unknown>(queue: string, payload: T) => Promise<string>;
+    readonly dequeue: <T = unknown>(queue: string) => Promise<QueueMessage<T> | undefined>;
+    readonly ack: (_queue: string, _id: string) => Promise<void>;
+    readonly length: (queue: string) => Promise<number>;
+    readonly drain: (queue: string) => Promise<void>;
+};
+export default RedisQueue;
+//# sourceMappingURL=Redis.d.ts.map

package/src/tools/queue/drivers/Redis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Redis.d.ts","sourceRoot":"","sources":["../../../../../src/tools/queue/drivers/Redis.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,eAAO,MAAM,UAAU;uBAEL,CAAC,mBAAmB,MAAM,WAAW,CAAC,KAAG,OAAO,CAAC,MAAM,CAAC;uBAKxD,CAAC,mBAAmB,MAAM,KAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;2BAK7D,MAAM,OAAO,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;6BAKjC,MAAM,KAAG,OAAO,CAAC,MAAM,CAAC;4BAKzB,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;CAKzC,CAAC;AAEL,eAAe,UAAU,CAAC"}

package/src/tools/queue/drivers/Redis.js

@@ -0,0 +1,26 @@
+import { ensureDriver } from '../../../config/redis.js';
+export const RedisQueue = (() => {
+    return {
+        async enqueue(queue, payload) {
+            const driver = await ensureDriver();
+            return driver.enqueue(queue, payload);
+        },
+        async dequeue(queue) {
+            const driver = await ensureDriver();
+            return driver.dequeue(queue);
+        },
+        async ack(_queue, _id) {
+            const driver = await ensureDriver();
+            await driver.ack(_queue, _id);
+        },
+        async length(queue) {
+            const driver = await ensureDriver();
+            return driver.length(queue);
+        },
+        async drain(queue) {
+            const driver = await ensureDriver();
+            await driver.drain(queue);
+        },
+    };
+})();
+export default RedisQueue;

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

@@ -0,0 +1,9 @@
+/**
+ * Queue Module Exports
+ * Centralized exports for advanced queue patterns
+ */
+export { createAdvancedQueue, type AdvancedQueue } from './AdvancedQueue';
+export { createDeduplicationBuilder, type DeduplicationBuilder } from './DeduplicationBuilder';
+export { createLockProvider, createMemoryLockProvider, createRedisLockProvider, getLockProvider, registerLockProvider, } from './LockProvider';
+export type { AdvancedJobOptions, DeduplicationOptions, JobResult, Lock, LockOptions, LockProvider, LockProviderConfig, LockStatus, QueueConfig, ReleaseCondition, } from '../../types/Queue';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/tools/queue/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,mBAAmB,EAAE,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC/E,OAAO,EAAE,0BAA0B,EAAE,KAAK,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACpG,OAAO,EACL,kBAAkB,EAClB,wBAAwB,EACxB,uBAAuB,EACvB,eAAe,EACf,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAG7B,YAAY,EACV,kBAAkB,EAClB,oBAAoB,EACpB,SAAS,EACT,IAAI,EACJ,WAAW,EACX,YAAY,EACZ,kBAAkB,EAClB,UAAU,EACV,WAAW,EACX,gBAAgB,GACjB,MAAM,eAAe,CAAC"}

package/src/tools/queue/index.js

@@ -0,0 +1,7 @@
+/**
+ * Queue Module Exports
+ * Centralized exports for advanced queue patterns
+ */
+export { createAdvancedQueue } from './AdvancedQueue.js';
+export { createDeduplicationBuilder } from './DeduplicationBuilder.js';
+export { createLockProvider, createMemoryLockProvider, createRedisLockProvider, getLockProvider, registerLockProvider, } from './LockProvider.js';

package/src/tools/redis/RedisKeyManager.d.ts

@@ -0,0 +1,66 @@
+export declare const METRICS_PREFIX: string;
+export declare const HEALTH_PREFIX: string;
+/**
+ * Creates a prefixed Redis key
+ * @param key - Original key name
+ * @returns Prefixed key in format: {prefix}-{key}
+ */
+export declare function createRedisKey(key: string): string;
+/**
+ * Creates a prefixed queue key
+ * @param queueName - Original queue name
+ * @returns Prefixed queue key
+ */
+export declare function createQueueKey(queueName: string): string;
+/**
+ * Creates a prefixed BullMQ queue key
+ * BullMQ uses specific patterns like 'bull:queue-name'
+ * @param queueName - Original queue name
+ * @returns Prefixed BullMQ queue key
+ */
+export declare function createBullMQKey(queueName: string): string;
+/**
+ * Creates a prefixed worker key
+ * @param workerName - Original worker name
+ * @returns Prefixed worker key
+ */
+export declare function createWorkerKey(workerName: string): string;
+/**
+ * Creates a prefixed session key
+ * @param sessionId - Session ID
+ * @returns Prefixed session key
+ */
+export declare function createSessionKey(sessionId: string): string;
+/**
+ * Creates a prefixed cache key
+ * @param cacheKey - Cache key
+ * @returns Prefixed cache key
+ */
+export declare function createCacheKey(cacheKey: string): string;
+/**
+ * Extracts original key from prefixed key
+ * @param prefixedKey - Full prefixed key
+ * @returns Original key without prefix
+ */
+export declare function extractOriginalKey(prefixedKey: string): string;
+/**
+ * Checks if a key belongs to this application
+ * @param key - Redis key to check
+ * @returns True if key belongs to this application
+ */
+export declare function isAppKey(key: string): boolean;
+/**
+ * Gets the current prefix
+ * @returns Current application prefix
+ */
+export declare function getPrefix(): string;
+export declare const getBullMQSafeQueueName: () => string;
+export type RedisKeyType = 'queue' | 'bullmq' | 'worker' | 'session' | 'cache' | 'custom';
+/**
+ * Creates a prefixed key based on type
+ * @param type - Type of key
+ * @param key - Original key
+ * @returns Prefixed key
+ */
+export declare function createKeyByType(type: RedisKeyType, key: string): string;
+//# sourceMappingURL=RedisKeyManager.d.ts.map

package/src/tools/redis/RedisKeyManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RedisKeyManager.d.ts","sourceRoot":"","sources":["../../../../src/tools/redis/RedisKeyManager.ts"],"names":[],"mappings":"AAYA,eAAO,MAAM,cAAc,QAA8B,CAAC;AAC1D,eAAO,MAAM,aAAa,QAA6B,CAAC;AAExD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAgBlD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAM9D;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE7C;AAED;;;GAGG;AACH,wBAAgB,SAAS,IAAI,MAAM,CAElC;AAED,eAAO,MAAM,sBAAsB,QAAO,MAEzC,CAAC;AAGF,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE1F;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAiBvE"}

package/src/tools/redis/RedisKeyManager.js

@@ -0,0 +1,126 @@
+import { appConfig } from '../../config/app.js';
+import { Logger } from '../../config/logger.js';
+/**
+ * Redis Key Management Utility
+ *
+ * Centralizes Redis key prefixing using appConfigObj.prefix
+ * to prevent key collisions across different applications/environments
+ */
+const PREFIX = appConfig.prefix;
+export const METRICS_PREFIX = `${PREFIX}_worker:metrics:`;
+export const HEALTH_PREFIX = `${PREFIX}_worker:health:`;
+/**
+ * Creates a prefixed Redis key
+ * @param key - Original key name
+ * @returns Prefixed key in format: {prefix}-{key}
+ */
+export function createRedisKey(key) {
+    if (!key) {
+        Logger.warn('RedisKeyManager: Empty key provided');
+        return PREFIX;
+    }
+    // Remove leading/trailing colons and ensure proper format
+    // Using safe string operations instead of regex to prevent ReDoS
+    let cleanKey = key;
+    while (cleanKey.startsWith(':')) {
+        cleanKey = cleanKey.slice(1);
+    }
+    while (cleanKey.endsWith(':')) {
+        cleanKey = cleanKey.slice(0, -1);
+    }
+    return `${PREFIX}:${cleanKey}`;
+}
+/**
+ * Creates a prefixed queue key
+ * @param queueName - Original queue name
+ * @returns Prefixed queue key
+ */
+export function createQueueKey(queueName) {
+    return createRedisKey(`queue:${queueName}`);
+}
+/**
+ * Creates a prefixed BullMQ queue key
+ * BullMQ uses specific patterns like 'bull:queue-name'
+ * @param queueName - Original queue name
+ * @returns Prefixed BullMQ queue key
+ */
+export function createBullMQKey(queueName) {
+    return createRedisKey(`bull:${queueName}`);
+}
+/**
+ * Creates a prefixed worker key
+ * @param workerName - Original worker name
+ * @returns Prefixed worker key
+ */
+export function createWorkerKey(workerName) {
+    return createRedisKey(`worker:${workerName}`);
+}
+/**
+ * Creates a prefixed session key
+ * @param sessionId - Session ID
+ * @returns Prefixed session key
+ */
+export function createSessionKey(sessionId) {
+    return createRedisKey(`session:${sessionId}`);
+}
+/**
+ * Creates a prefixed cache key
+ * @param cacheKey - Cache key
+ * @returns Prefixed cache key
+ */
+export function createCacheKey(cacheKey) {
+    return createRedisKey(`cache:${cacheKey}`);
+}
+/**
+ * Extracts original key from prefixed key
+ * @param prefixedKey - Full prefixed key
+ * @returns Original key without prefix
+ */
+export function extractOriginalKey(prefixedKey) {
+    if (!prefixedKey.startsWith(`${PREFIX}:`)) {
+        return prefixedKey;
+    }
+    return prefixedKey.substring(`${PREFIX}:`.length);
+}
+/**
+ * Checks if a key belongs to this application
+ * @param key - Redis key to check
+ * @returns True if key belongs to this application
+ */
+export function isAppKey(key) {
+    return key.startsWith(`${PREFIX}:`);
+}
+/**
+ * Gets the current prefix
+ * @returns Current application prefix
+ */
+export function getPrefix() {
+    return PREFIX;
+}
+export const getBullMQSafeQueueName = () => {
+    return PREFIX;
+};
+/**
+ * Creates a prefixed key based on type
+ * @param type - Type of key
+ * @param key - Original key
+ * @returns Prefixed key
+ */
+export function createKeyByType(type, key) {
+    switch (type) {
+        case 'queue':
+            return createQueueKey(key);
+        case 'bullmq':
+            return createBullMQKey(key);
+        case 'worker':
+            return createWorkerKey(key);
+        case 'session':
+            return createSessionKey(key);
+        case 'cache':
+            return createCacheKey(key);
+        case 'custom':
+            return createRedisKey(key);
+        default:
+            return createRedisKey(key);
+    }
+}

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.js';
+import { createHmac } from '../../node-singletons/crypto.js';
+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/StorageDiskRegistry.d.ts

@@ -0,0 +1,14 @@
+declare function register(name: string, config: unknown): void;
+declare function has(name: string): boolean;
+declare function get(name: string): unknown;
+declare function list(): string[];
+declare function reset(): void;
+export declare const StorageDiskRegistry: Readonly<{
+    register: typeof register;
+    has: typeof has;
+    get: typeof get;
+    list: typeof list;
+    reset: typeof reset;
+}>;
+export default StorageDiskRegistry;
+//# sourceMappingURL=StorageDiskRegistry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"StorageDiskRegistry.d.ts","sourceRoot":"","sources":["../../../../src/tools/storage/StorageDiskRegistry.ts"],"names":[],"mappings":"AASA,iBAAS,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CAIrD;AAED,iBAAS,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAElC;AAED,iBAAS,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAOlC;AAED,iBAAS,IAAI,IAAI,MAAM,EAAE,CAExB;AAED,iBAAS,KAAK,IAAI,IAAI,CAErB;AAED,eAAO,MAAM,mBAAmB;;;;;;EAM9B,CAAC;AAEH,eAAe,mBAAmB,CAAC"}

package/src/tools/storage/StorageDiskRegistry.js

@@ -0,0 +1,36 @@
+import { ErrorFactory } from '../../exceptions/ZintrustError.js';
+const registry = new Map();
+const normalizeKey = (name) => String(name ?? '')
+    .trim()
+    .toLowerCase();
+function register(name, config) {
+    const key = normalizeKey(name);
+    if (key === '')
+        return;
+    registry.set(key, config);
+}
+function has(name) {
+    return registry.has(normalizeKey(name));
+}
+function get(name) {
+    const key = normalizeKey(name);
+    const cfg = registry.get(key);
+    if (cfg === undefined) {
+        throw ErrorFactory.createConfigError(`Storage disk not registered: ${name}`);
+    }
+    return cfg;
+}
+function list() {
+    return Array.from(registry.keys()).sort((a, b) => a.localeCompare(b));
+}
+function reset() {
+    registry.clear();
+}
+export const StorageDiskRegistry = Object.freeze({
+    register,
+    has,
+    get,
+    list,
+    reset,
+});
+export default StorageDiskRegistry;

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

@@ -0,0 +1,16 @@
+export type StorageDriverEntry = {
+    driver: unknown;
+    normalize?: (raw: Record<string, unknown>) => Record<string, unknown>;
+};
+declare function register(driverName: string, entry: StorageDriverEntry): void;
+declare function get(driverName: string): StorageDriverEntry | undefined;
+declare function has(driverName: string): boolean;
+declare function list(): string[];
+export declare const StorageDriverRegistry: Readonly<{
+    register: typeof register;
+    get: typeof get;
+    has: typeof has;
+    list: typeof list;
+}>;
+export default StorageDriverRegistry;
+//# sourceMappingURL=StorageDriverRegistry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"StorageDriverRegistry.d.ts","sourceRoot":"","sources":["../../../../src/tools/storage/StorageDriverRegistry.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvE,CAAC;AAIF,iBAAS,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAErE;AAED,iBAAS,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAE/D;AAED,iBAAS,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAExC;AAED,iBAAS,IAAI,IAAI,MAAM,EAAE,CAExB;AAED,eAAO,MAAM,qBAAqB;;;;;EAKhC,CAAC;AAEH,eAAe,qBAAqB,CAAC"}