@zintrust/core 0.1.1 → 0.1.3

package/src/tools/queue/Queue.js

@@ -0,0 +1,38 @@
+import { ErrorFactory } from '../../exceptions/ZintrustError';
+const drivers = new Map();
+export const Queue = Object.freeze({
+    register(name, driver) {
+        drivers.set(name.toLowerCase(), driver);
+    },
+    get(name) {
+        const driverName = (name ?? process.env['QUEUE_DRIVER'] ?? 'inmemory')
+            .toString()
+            .trim()
+            .toLowerCase();
+        const driver = drivers.get(driverName);
+        if (!driver)
+            throw ErrorFactory.createConfigError(`Queue driver not registered: ${driverName}`);
+        return driver;
+    },
+    async enqueue(queue, payload, driverName) {
+        const driver = Queue.get(driverName);
+        return driver.enqueue(queue, payload);
+    },
+    async dequeue(queue, driverName) {
+        const driver = Queue.get(driverName);
+        return driver.dequeue(queue);
+    },
+    async ack(queue, id, driverName) {
+        const driver = Queue.get(driverName);
+        return driver.ack(queue, id);
+    },
+    async length(queue, driverName) {
+        const driver = Queue.get(driverName);
+        return driver.length(queue);
+    },
+    async drain(queue, driverName) {
+        const driver = Queue.get(driverName);
+        return driver.drain(queue);
+    },
+});
+export default Queue;

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

@@ -0,0 +1,10 @@
+import { 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,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAIlD,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/uuid';
+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 { 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":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAelD,eAAO,MAAM,UAAU;uBAuDL,CAAC,mBAAmB,MAAM,WAAW,CAAC,KAAG,OAAO,CAAC,MAAM,CAAC;uBAQxD,CAAC,mBAAmB,MAAM,KAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;2BAY7D,MAAM,OAAO,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;6BAMjC,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,91 @@
+import { generateUuid } from '../../../common/uuid';
+import { ErrorFactory } from '../../../exceptions/ZintrustError';
+const getRedisUrl = () => {
+    const url = (process.env['REDIS_URL'] ?? '').trim();
+    return url.length > 0 ? url : null;
+};
+export const RedisQueue = (() => {
+    let client = null;
+    let connected = false;
+    const ensureClient = async () => {
+        if (connected && client !== null)
+            return client;
+        const url = getRedisUrl();
+        if (url === null)
+            throw ErrorFactory.createConfigError('Redis queue driver requires REDIS_URL');
+        // Import lazily so package is optional for environments that don't use Redis
+        // Prefer real 'redis' package when available, otherwise allow tests to inject a fake client
+        try {
+            // Dynamically import the redis package if available (optional dependency)
+            // Tests can inject a fake client on `globalThis.__fakeRedisClient` if the package is absent.
+            // Dynamically import the redis package if available (optional dependency)
+            const mod = (await import('redis'));
+            const createClient = mod.createClient;
+            client = createClient({ url });
+            if (typeof client.connect === 'function') {
+                try {
+                    // Await connect to ensure readiness; network errors will be surfaced
+                    await client.connect();
+                    connected = true;
+                }
+                catch (connectionError) {
+                    connected = false;
+                    // log non-fatally — operations will surface errors as needed
+                    // eslint-disable-next-line no-console
+                    console.warn('Redis client connect failed:', String(connectionError));
+                }
+            }
+            else {
+                connected = true;
+            }
+        }
+        catch {
+            const globalFake = globalThis
+                .__fakeRedisClient;
+            if (globalFake === undefined) {
+                throw ErrorFactory.createConfigError("Redis queue driver requires the 'redis' package or a test fake client set in globalThis.__fakeRedisClient");
+            }
+            client = globalFake;
+            connected = true;
+        }
+        if (client === null)
+            throw ErrorFactory.createConfigError('Redis client could not be initialized');
+        return client;
+    };
+    return {
+        async enqueue(queue, payload) {
+            const cli = await ensureClient();
+            const id = generateUuid();
+            const msg = JSON.stringify({ id, payload, attempts: 0 });
+            await cli.rPush(queue, msg);
+            return id;
+        },
+        async dequeue(queue) {
+            const cli = await ensureClient();
+            const raw = await cli.lPop(queue);
+            if (raw === null)
+                return undefined;
+            try {
+                const parsed = JSON.parse(raw);
+                return parsed;
+            }
+            catch (err) {
+                throw ErrorFactory.createTryCatchError('Failed to parse queue message', err);
+            }
+        },
+        async ack(_queue, _id) {
+            // Simple list-based queue removes on dequeue, so ack is a no-op here.
+            // For visibility timeout or retry semantics, implement BRPOPLPUSH and a processing list.
+            return Promise.resolve(); // NOSONAR
+        },
+        async length(queue) {
+            const cli = await ensureClient();
+            return cli.lLen(queue);
+        },
+        async drain(queue) {
+            const cli = await ensureClient();
+            await cli.del(queue);
+        },
+    };
+})();
+export default RedisQueue;

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/Gcs.d.ts

@@ -0,0 +1,20 @@
+export type GcsConfig = {
+    bucket: string;
+    projectId?: string;
+    keyFile?: string;
+    url?: string;
+};
+type TempUrlOptions = {
+    expiresIn?: number;
+    method?: 'GET' | 'PUT';
+};
+export declare const GcsDriver: Readonly<{
+    url(config: GcsConfig, key: string): string | undefined;
+    put(config: GcsConfig, key: string, content: string | Buffer): Promise<string>;
+    get(config: GcsConfig, key: string): Promise<Buffer>;
+    exists(config: GcsConfig, key: string): Promise<boolean>;
+    delete(config: GcsConfig, key: string): Promise<void>;
+    tempUrl(config: GcsConfig, key: string, options?: TempUrlOptions): Promise<string>;
+}>;
+export default GcsDriver;
+//# sourceMappingURL=Gcs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Gcs.d.ts","sourceRoot":"","sources":["../../../../../src/tools/storage/drivers/Gcs.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,SAAS,GAAG;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,KAAK,cAAc,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,KAAK,GAAG,KAAK,CAAA;CAAE,CAAC;AA+ErE,eAAO,MAAM,SAAS;gBACR,SAAS,OAAO,MAAM,GAAG,MAAM,GAAG,SAAS;gBAWrC,SAAS,OAAO,MAAM,WAAW,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;gBAkBlE,SAAS,OAAO,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;mBAiBrC,SAAS,OAAO,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;mBAgBzC,SAAS,OAAO,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;oBAiBrC,SAAS,OAAO,MAAM,YAAY,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;EA8BxF,CAAC;AAEH,eAAe,SAAS,CAAC"}

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

@@ -0,0 +1,152 @@
+import { ErrorFactory } from '../../../exceptions/ZintrustError';
+let cachedRealClient;
+const getInjectedStorageModule = () => {
+    return globalThis
+        .__fakeGoogleCloudStorageModule;
+};
+const getInjectedFakeClient = () => {
+    const v = globalThis.__fakeGcsClient;
+    return v;
+};
+const loadRealClient = async (config) => {
+    if (cachedRealClient !== undefined)
+        return cachedRealClient;
+    // Avoid a string-literal import so TypeScript doesn't require the module at build time.
+    const specifier = '@google-cloud/storage';
+    const injected = getInjectedStorageModule();
+    let mod;
+    try {
+        mod = (injected ?? (await import(specifier)));
+    }
+    catch (err) {
+        throw ErrorFactory.createConfigError('GCS: missing optional dependency @google-cloud/storage (install it or inject globalThis.__fakeGcsClient for tests)', { error: err });
+    }
+    if (typeof mod.Storage !== 'function') {
+        throw ErrorFactory.createConfigError('GCS: @google-cloud/storage did not export Storage');
+    }
+    const opts = {};
+    if (typeof config.projectId === 'string' && config.projectId.trim() !== '') {
+        opts['projectId'] = config.projectId;
+    }
+    if (typeof config.keyFile === 'string' && config.keyFile.trim() !== '') {
+        opts['keyFilename'] = config.keyFile;
+    }
+    try {
+        cachedRealClient = new mod.Storage(opts);
+        return cachedRealClient;
+    }
+    catch (err) {
+        throw ErrorFactory.createConfigError('GCS: failed to initialize Storage client', {
+            error: err,
+        });
+    }
+};
+const getClient = async (config) => {
+    const injected = getInjectedFakeClient();
+    if (injected !== undefined)
+        return injected;
+    return loadRealClient(config);
+};
+const encodePathSegments = (key) => key
+    .split('/')
+    .map((seg) => encodeURIComponent(seg))
+    .join('/');
+export const GcsDriver = Object.freeze({
+    url(config, key) {
+        const bucket = String(config.bucket ?? '').trim();
+        if (bucket === '')
+            return undefined;
+        const base = typeof config.url === 'string' ? config.url.trim() : '';
+        if (base !== '')
+            return `${base.replace(/\/$/, '')}/${key}`;
+        const encodedKey = encodePathSegments(key);
+        return `https://storage.googleapis.com/${encodeURIComponent(bucket)}/${encodedKey}`;
+    },
+    async put(config, key, content) {
+        const bucket = String(config.bucket ?? '').trim();
+        if (bucket === '')
+            throw ErrorFactory.createConfigError('GCS: bucket is not configured');
+        const client = await getClient(config);
+        const file = client.bucket(bucket).file(key);
+        if (typeof file.save !== 'function') {
+            throw ErrorFactory.createConfigError('GCS: client is missing file.save()');
+        }
+        await file.save(content);
+        const url = GcsDriver.url(config, key);
+        if (url === undefined)
+            return '';
+        return url;
+    },
+    async get(config, key) {
+        const bucket = String(config.bucket ?? '').trim();
+        if (bucket === '')
+            throw ErrorFactory.createConfigError('GCS: bucket is not configured');
+        const client = await getClient(config);
+        const file = client.bucket(bucket).file(key);
+        if (typeof file.download !== 'function') {
+            throw ErrorFactory.createConfigError('GCS: client is missing file.download()');
+        }
+        const [data] = await file.download();
+        if (Buffer.isBuffer(data))
+            return data;
+        if (typeof data === 'string')
+            return Buffer.from(data);
+        return Buffer.from(data);
+    },
+    async exists(config, key) {
+        const bucket = String(config.bucket ?? '').trim();
+        if (bucket === '')
+            throw ErrorFactory.createConfigError('GCS: bucket is not configured');
+        const client = await getClient(config);
+        const file = client.bucket(bucket).file(key);
+        if (typeof file.exists !== 'function') {
+            // if client doesn't support exists, assume true (matches Storage.exists default behavior)
+            return true;
+        }
+        const [exists] = await file.exists();
+        return Boolean(exists);
+    },
+    async delete(config, key) {
+        const bucket = String(config.bucket ?? '').trim();
+        if (bucket === '')
+            throw ErrorFactory.createConfigError('GCS: bucket is not configured');
+        const client = await getClient(config);
+        const file = client.bucket(bucket).file(key);
+        if (typeof file.delete !== 'function')
+            return;
+        try {
+            // google-cloud-storage supports ignoreNotFound, but keep it flexible for fakes
+            await file.delete({ ignoreNotFound: true });
+        }
+        catch (err) {
+            void err; // NOSONAR
+        }
+    },
+    async tempUrl(config, key, options) {
+        const bucket = String(config.bucket ?? '').trim();
+        if (bucket === '')
+            throw ErrorFactory.createConfigError('GCS: bucket is not configured');
+        const expiresIn = options?.expiresIn ?? 900;
+        if (!Number.isFinite(expiresIn) || expiresIn <= 0) {
+            throw ErrorFactory.createValidationError('GCS: expiresIn must be a positive number', {
+                expiresIn,
+            });
+        }
+        if (expiresIn > 604800) {
+            throw ErrorFactory.createValidationError('GCS: expiresIn exceeds 7 days', {
+                expiresIn,
+            });
+        }
+        const method = options?.method ?? 'GET';
+        const action = method === 'PUT' ? 'write' : 'read';
+        const client = await getClient(config);
+        const file = client.bucket(bucket).file(key);
+        if (typeof file.getSignedUrl !== 'function') {
+            throw ErrorFactory.createConfigError('GCS: client is missing file.getSignedUrl()');
+        }
+        const expires = Date.now() + expiresIn * 1000;
+        const [url] = await file.getSignedUrl({ version: 'v4', action, expires });
+        return url;
+    },
+});
+export default GcsDriver;

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

@@ -0,0 +1,18 @@
+export type LocalConfig = {
+    root: string;
+    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?: {
+        expiresIn?: number;
+        method?: "GET" | "PUT";
+    }): string;
+}>;
+export default LocalDriver;
+//# sourceMappingURL=Local.d.ts.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,89 @@
+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({
+    resolveKey(config, key) {
+        if (!config.root || config.root.trim() === '') {
+            throw ErrorFactory.createConfigError('Local storage root is not configured');
+        }
+        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') {
+            await fs.writeFile(fullPath, content, 'utf8');
+        }
+        else {
+            await fs.writeFile(fullPath, content);
+        }
+        return fullPath;
+    },
+    async get(config, key) {
+        const fullPath = LocalDriver.resolveKey(config, key);
+        try {
+            return await fs.readFile(fullPath);
+        }
+        catch (err) {
+            throw ErrorFactory.createNotFoundError('Local storage: file not found', { key, error: err });
+        }
+    },
+    async exists(config, key) {
+        const fullPath = LocalDriver.resolveKey(config, key);
+        try {
+            await fs.access(fullPath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
+    async delete(config, key) {
+        const fullPath = LocalDriver.resolveKey(config, key);
+        try {
+            await fs.unlink(fullPath);
+        }
+        catch {
+            // ignore not found
+        }
+    },
+    url(config, key) {
+        if (config?.url === undefined || config.url.trim() === '')
+            return undefined;
+        return `${config.url.replace(/\/$/, '')}/${key}`;
+    },
+    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)');
+        }
+        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/drivers/R2.d.ts

@@ -0,0 +1,20 @@
+export type R2Config = {
+    bucket: string;
+    region?: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    endpoint?: string;
+};
+export declare const R2Driver: Readonly<{
+    put(config: R2Config, key: string, content: string | Buffer): Promise<string>;
+    get(config: R2Config, key: string): Promise<Buffer>;
+    exists(config: R2Config, key: string): Promise<boolean>;
+    delete(config: R2Config, key: string): Promise<void>;
+    url(config: R2Config, key: string): string;
+    tempUrl(config: R2Config, key: string, options?: {
+        expiresIn?: number;
+        method?: "GET" | "PUT";
+    }): string;
+}>;
+export default R2Driver;
+//# sourceMappingURL=R2.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"R2.d.ts","sourceRoot":"","sources":["../../../../../src/tools/storage/drivers/R2.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,QAAQ,GAAG;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,eAAO,MAAM,QAAQ;gBACD,QAAQ,OAAO,MAAM,WAAW,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;gBAkBjE,QAAQ,OAAO,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;mBAapC,QAAQ,OAAO,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;mBAaxC,QAAQ,OAAO,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;gBAa9C,QAAQ,OAAO,MAAM,GAAG,MAAM;oBAQhC,QAAQ,OACX,MAAM,YACD;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,KAAK,GAAG,KAAK,CAAA;KAAE,GACvD,MAAM;EAgBT,CAAC;AAEH,eAAe,QAAQ,CAAC"}