@zintrust/core 0.1.1 → 0.1.2

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

@@ -0,0 +1,63 @@
+import { ErrorFactory } from '../../../exceptions/ZintrustError';
+import { fsPromises as fs } from '../../../node-singletons/fs';
+import * as path from '../../../node-singletons/path';
+export const LocalDriver = Object.freeze({
+    async put(config, key, content) {
+        const root = config.root;
+        if (!root || root.trim() === '') {
+            throw ErrorFactory.createConfigError('Local storage root is not configured');
+        }
+        const fullPath = path.join(root, 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 = path.join(config.root, 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 = path.join(config.root, key);
+        try {
+            await fs.access(fullPath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
+    async delete(config, key) {
+        const fullPath = path.join(config.root, key);
+        try {
+            await fs.unlink(fullPath);
+        }
+        catch (err) {
+            // ignore not found
+            void err; // NOSONAR
+        }
+    },
+    url(config, key) {
+        if (config?.url === undefined || config.url.trim() === '')
+            return undefined;
+        return `${config.url.replace(/\/$/, '')}/${key}`;
+    },
+    tempUrl(config, key, _options) {
+        const url = LocalDriver.url(config, key);
+        if (url === undefined) {
+            throw ErrorFactory.createConfigError('Local storage: url is not configured (set STORAGE_URL)');
+        }
+        return url;
+    },
+});
+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"}

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

@@ -0,0 +1,73 @@
+import { ErrorFactory } from '../../../exceptions/ZintrustError';
+import { S3Driver } from '../drivers/S3';
+export const R2Driver = Object.freeze({
+    async put(config, key, content) {
+        if (typeof config.endpoint !== 'string' || config.endpoint.trim() === '') {
+            throw ErrorFactory.createConfigError('R2: missing endpoint');
+        }
+        // Delegate to S3Driver using path-style endpoint
+        const s3Config = {
+            bucket: config.bucket,
+            region: config.region ?? 'auto',
+            accessKeyId: config.accessKeyId,
+            secretAccessKey: config.secretAccessKey,
+            endpoint: config.endpoint,
+            usePathStyle: true,
+        };
+        return S3Driver.put(s3Config, key, content);
+    },
+    async get(config, key) {
+        const s3Config = {
+            bucket: config.bucket,
+            region: config.region ?? 'auto',
+            accessKeyId: config.accessKeyId,
+            secretAccessKey: config.secretAccessKey,
+            endpoint: config.endpoint,
+            usePathStyle: true,
+        };
+        return S3Driver.get(s3Config, key);
+    },
+    async exists(config, key) {
+        const s3Config = {
+            bucket: config.bucket,
+            region: config.region ?? 'auto',
+            accessKeyId: config.accessKeyId,
+            secretAccessKey: config.secretAccessKey,
+            endpoint: config.endpoint,
+            usePathStyle: true,
+        };
+        return S3Driver.exists(s3Config, key);
+    },
+    async delete(config, key) {
+        const s3Config = {
+            bucket: config.bucket,
+            region: config.region ?? 'auto',
+            accessKeyId: config.accessKeyId,
+            secretAccessKey: config.secretAccessKey,
+            endpoint: config.endpoint,
+            usePathStyle: true,
+        };
+        return S3Driver.delete(s3Config, key);
+    },
+    url(config, key) {
+        if (config.endpoint !== undefined && config.endpoint.trim() !== '') {
+            return `${config.endpoint.replace(/\/$/, '')}/${config.bucket}/${key}`;
+        }
+        return `https://${config.bucket}.r2.cloudflarestorage.com/${key}`;
+    },
+    tempUrl(config, key, options) {
+        if (typeof config.endpoint !== 'string' || config.endpoint.trim() === '') {
+            throw ErrorFactory.createConfigError('R2: missing endpoint');
+        }
+        const s3Config = {
+            bucket: config.bucket,
+            region: config.region ?? 'auto',
+            accessKeyId: config.accessKeyId,
+            secretAccessKey: config.secretAccessKey,
+            endpoint: config.endpoint,
+            usePathStyle: true,
+        };
+        return S3Driver.tempUrl(s3Config, key, options);
+    },
+});
+export default R2Driver;

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"S3.d.ts","sourceRoot":"","sources":["../../../../../src/tools/storage/drivers/S3.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,QAAQ,GAAG;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC,CAAC;AAwGF,eAAO,MAAM,QAAQ;gBACD,QAAQ,OAAO,MAAM,WAAW,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;gBA8CjE,QAAQ,OAAO,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;mBA0CpC,QAAQ,OAAO,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;mBAkCxC,QAAQ,OAAO,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;gBAoC9C,QAAQ,OAAO,MAAM,GAAG,MAAM;oBAOhC,QAAQ,OACX,MAAM,YACD;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,KAAK,GAAG,KAAK,CAAA;KAAE,GACvD,MAAM;EAqDT,CAAC;AAEH,eAAe,QAAQ,CAAC"}

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

@@ -0,0 +1,258 @@
+import { AwsSigV4 } from '../../../common/index';
+import { ErrorFactory } from '../../../exceptions/ZintrustError';
+import { createHash, createHmac } from '../../../node-singletons/crypto';
+const sha256Hex = (data) => createHash('sha256').update(data).digest('hex');
+const buildAuthorization = (params) => {
+    const canonicalUri = params.path;
+    const canonicalQueryString = '';
+    const headers = {
+        host: params.host,
+        'x-amz-date': params.amzDate,
+        'x-amz-content-sha256': params.payloadHash,
+    };
+    if (params.credentials.sessionToken !== undefined)
+        headers['x-amz-security-token'] = params.credentials.sessionToken;
+    return AwsSigV4.buildAuthorization({
+        method: params.method,
+        canonicalUri,
+        canonicalQueryString,
+        headers,
+        payloadHash: params.payloadHash,
+        region: params.region,
+        service: 's3',
+        amzDate: params.amzDate,
+        dateStamp: params.dateStamp,
+        credentials: params.credentials,
+    });
+};
+const buildHostAndPath = (config, key) => {
+    const endpoint = config.endpoint?.trim() ?? '';
+    if (endpoint !== '') {
+        // if endpoint provided, prefer path-style
+        const host = endpoint.replace(/^https?:\/\//, '').replace(/\/$/, '');
+        const path = `/${config.bucket}/${key}`;
+        return { host, path, url: `${endpoint.replace(/\/$/, '')}/${config.bucket}/${key}` };
+    }
+    const host = `${config.bucket}.s3.${config.region}.amazonaws.com`;
+    const path = `/${key}`;
+    const url = `https://${host}${path}`;
+    return { host, path, url };
+};
+const awsEncodeURIComponent = (value) => encodeURIComponent(value).replaceAll(/[!'()*]/g, (c) => `%${c.codePointAt(0)?.toString(16).toUpperCase()}`);
+const encodePathSegments = (key) => key
+    .split('/')
+    .map((seg) => awsEncodeURIComponent(seg))
+    .join('/');
+const buildCanonicalQueryString = (params) => {
+    const entries = Object.entries(params)
+        .filter(([, v]) => v !== '')
+        .map(([k, v]) => [awsEncodeURIComponent(k), awsEncodeURIComponent(v)])
+        .sort((a, b) => a[0].localeCompare(b[0]));
+    return entries.map(([k, v]) => `${k}=${v}`).join('&');
+};
+const getCredentials = (config) => {
+    const accessKeyId = config.accessKeyId ?? process.env['AWS_ACCESS_KEY_ID'] ?? '';
+    const secretAccessKey = config.secretAccessKey ?? process.env['AWS_SECRET_ACCESS_KEY'] ?? '';
+    const sessionToken = process.env['AWS_SESSION_TOKEN'] ?? undefined;
+    if (accessKeyId.trim() === '' || secretAccessKey.trim() === '') {
+        throw ErrorFactory.createConfigError('S3: missing AWS credentials');
+    }
+    return { accessKeyId, secretAccessKey, sessionToken };
+};
+const validateExpiresIn = (expiresIn) => {
+    if (!Number.isFinite(expiresIn) || expiresIn <= 0) {
+        throw ErrorFactory.createValidationError('S3: expiresIn must be a positive number', {
+            expiresIn,
+        });
+    }
+    if (expiresIn > 604800) {
+        throw ErrorFactory.createValidationError('S3: expiresIn exceeds maximum (604800 seconds)', {
+            expiresIn,
+        });
+    }
+};
+export const S3Driver = Object.freeze({
+    async put(config, key, content) {
+        const { accessKeyId, secretAccessKey, sessionToken } = getCredentials(config);
+        const { host, path, url } = buildHostAndPath(config, key);
+        const now = new Date();
+        const { amzDate, dateStamp } = AwsSigV4.toAmzDate(now);
+        const body = typeof content === 'string' ? content : Buffer.from(content);
+        const payloadHash = sha256Hex(body);
+        const { authorization } = buildAuthorization({
+            method: 'PUT',
+            host,
+            region: config.region,
+            amzDate,
+            dateStamp,
+            credentials: { accessKeyId, secretAccessKey, sessionToken },
+            payloadHash,
+            path,
+        });
+        const headers = {
+            'x-amz-date': amzDate,
+            'x-amz-content-sha256': payloadHash,
+            Authorization: authorization,
+        };
+        if (sessionToken !== undefined)
+            headers['x-amz-security-token'] = sessionToken;
+        const res = await fetch(`https://${host}${path}`, {
+            method: 'PUT',
+            headers,
+            body,
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw ErrorFactory.createConnectionError(`S3 put failed (${res.status})`, {
+                status: res.status,
+                body: text,
+            });
+        }
+        return url;
+    },
+    async get(config, key) {
+        const { accessKeyId, secretAccessKey, sessionToken } = getCredentials(config);
+        const { host, path } = buildHostAndPath(config, key);
+        const now = new Date();
+        const { amzDate, dateStamp } = AwsSigV4.toAmzDate(now);
+        const payloadHash = sha256Hex('');
+        const { authorization } = buildAuthorization({
+            method: 'GET',
+            host,
+            region: config.region,
+            amzDate,
+            dateStamp,
+            credentials: { accessKeyId, secretAccessKey, sessionToken },
+            payloadHash,
+            path,
+        });
+        const headers = {
+            'x-amz-date': amzDate,
+            'x-amz-content-sha256': payloadHash,
+            Authorization: authorization,
+        };
+        if (sessionToken !== undefined)
+            headers['x-amz-security-token'] = sessionToken;
+        const res = await fetch(`https://${host}${path}`, {
+            method: 'GET',
+            headers,
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw ErrorFactory.createNotFoundError('S3 get failed', { status: res.status, body: text });
+        }
+        const buf = Buffer.from(await res.arrayBuffer());
+        return buf;
+    },
+    async exists(config, key) {
+        try {
+            const { accessKeyId, secretAccessKey, sessionToken } = getCredentials(config);
+            const { host, path } = buildHostAndPath(config, key);
+            const now = new Date();
+            const { amzDate, dateStamp } = AwsSigV4.toAmzDate(now);
+            const payloadHash = sha256Hex('');
+            const { authorization } = buildAuthorization({
+                method: 'HEAD',
+                host,
+                region: config.region,
+                amzDate,
+                dateStamp,
+                credentials: { accessKeyId, secretAccessKey, sessionToken },
+                payloadHash,
+                path,
+            });
+            const headers = {
+                'x-amz-date': amzDate,
+                'x-amz-content-sha256': payloadHash,
+                Authorization: authorization,
+            };
+            if (sessionToken !== undefined)
+                headers['x-amz-security-token'] = sessionToken;
+            const res = await fetch(`https://${host}${path}`, { method: 'HEAD', headers });
+            return res.ok;
+        }
+        catch {
+            return false;
+        }
+    },
+    async delete(config, key) {
+        const { accessKeyId, secretAccessKey, sessionToken } = getCredentials(config);
+        const { host, path } = buildHostAndPath(config, key);
+        const now = new Date();
+        const { amzDate, dateStamp } = AwsSigV4.toAmzDate(now);
+        const payloadHash = sha256Hex('');
+        const { authorization } = buildAuthorization({
+            method: 'DELETE',
+            host,
+            region: config.region,
+            amzDate,
+            dateStamp,
+            credentials: { accessKeyId, secretAccessKey, sessionToken },
+            payloadHash,
+            path,
+        });
+        const headers = {
+            'x-amz-date': amzDate,
+            'x-amz-content-sha256': payloadHash,
+            Authorization: authorization,
+        };
+        if (sessionToken !== undefined)
+            headers['x-amz-security-token'] = sessionToken;
+        const res = await fetch(`https://${host}${path}`, { method: 'DELETE', headers });
+        if (!res.ok) {
+            const text = await res.text();
+            throw ErrorFactory.createConnectionError(`S3 delete failed (${res.status})`, {
+                status: res.status,
+                body: text,
+            });
+        }
+    },
+    url(config, key) {
+        const endpoint = config.endpoint?.trim() ?? '';
+        if (endpoint !== '')
+            return `${endpoint.replace(/\/$/, '')}/${config.bucket}/${key}`;
+        return `https://${config.bucket}.s3.${config.region}.amazonaws.com/${key}`;
+    },
+    tempUrl(config, key, options) {
+        const { accessKeyId, secretAccessKey, sessionToken } = getCredentials(config);
+        const expiresIn = options?.expiresIn ?? 900;
+        validateExpiresIn(expiresIn);
+        const method = options?.method ?? 'GET';
+        const encodedKey = encodePathSegments(key);
+        const { host, path } = buildHostAndPath(config, encodedKey);
+        const now = new Date();
+        const { amzDate, dateStamp } = AwsSigV4.toAmzDate(now);
+        const algorithm = 'AWS4-HMAC-SHA256';
+        const credentialScope = `${dateStamp}/${config.region}/s3/aws4_request`;
+        const credential = `${accessKeyId}/${credentialScope}`;
+        const queryParams = {
+            'X-Amz-Algorithm': algorithm,
+            'X-Amz-Credential': credential,
+            'X-Amz-Date': amzDate,
+            'X-Amz-Expires': String(Math.floor(expiresIn)),
+            'X-Amz-SignedHeaders': 'host',
+        };
+        if (sessionToken !== undefined)
+            queryParams['X-Amz-Security-Token'] = sessionToken;
+        const canonicalQueryString = buildCanonicalQueryString(queryParams);
+        const canonicalRequest = [
+            method,
+            path,
+            canonicalQueryString,
+            `host:${host}\n`,
+            'host',
+            'UNSIGNED-PAYLOAD',
+        ].join('\n');
+        const stringToSign = [algorithm, amzDate, credentialScope, sha256Hex(canonicalRequest)].join('\n');
+        const signingKey = AwsSigV4.deriveSigningKey({
+            secretAccessKey,
+            dateStamp,
+            region: config.region,
+            service: 's3',
+        });
+        const signature = createHmac('sha256', signingKey).update(stringToSign).digest('hex');
+        const baseUrl = `https://${host}${path}`;
+        return `${baseUrl}?${canonicalQueryString}&X-Amz-Signature=${signature}`;
+    },
+});
+export default S3Driver;

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

@@ -0,0 +1,24 @@
+import { GcsDriver } from '../../tools/storage/drivers/Gcs';
+import { LocalDriver } from './drivers/Local';
+import { R2Driver } from './drivers/R2';
+import { S3Driver } from './drivers/S3';
+export type DiskName = 'local' | 's3' | 'gcs' | 'r2';
+export type StorageDisk = {
+    driver: typeof LocalDriver | typeof S3Driver | typeof R2Driver | typeof GcsDriver;
+    config: unknown;
+};
+type TempUrlOptions = {
+    expiresIn?: number;
+    method?: 'GET' | 'PUT';
+};
+export declare const Storage: Readonly<{
+    getDisk(name?: string): StorageDisk;
+    put(disk: string | undefined, path: string, contents: string | Buffer): Promise<string>;
+    get(disk: string | undefined, path: string): Promise<Buffer>;
+    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;
+}>;
+export default Storage;
+//# sourceMappingURL=index.d.ts.map

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

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

package/src/tools/storage/index.js

@@ -0,0 +1,112 @@
+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';
+const normalizers = {
+    local: (raw) => ({
+        root: String(raw['root'] ?? ''),
+        url: typeof raw['url'] === 'string' ? raw['url'] : undefined,
+    }),
+    s3: (raw) => ({
+        bucket: String(raw['bucket'] ?? ''),
+        region: String(raw['region'] ?? ''),
+        accessKeyId: String(raw['accessKeyId'] ?? raw['key'] ?? ''),
+        secretAccessKey: String(raw['secretAccessKey'] ?? raw['secret'] ?? ''),
+        endpoint: typeof raw['endpoint'] === 'string' ? raw['endpoint'] : undefined,
+        usePathStyle: Boolean(raw['usePathStyle'] ?? raw['usePathStyleUrl'] ?? false),
+    }),
+    r2: (raw) => ({
+        bucket: String(raw['bucket'] ?? ''),
+        region: typeof raw['region'] === 'string' ? raw['region'] : undefined,
+        accessKeyId: String(raw['accessKeyId'] ?? raw['key'] ?? ''),
+        secretAccessKey: String(raw['secretAccessKey'] ?? raw['secret'] ?? ''),
+        endpoint: typeof raw['endpoint'] === 'string' ? raw['endpoint'] : undefined,
+        url: typeof raw['url'] === 'string' ? raw['url'] : undefined,
+    }),
+    gcs: (raw) => ({
+        bucket: String(raw['bucket'] ?? ''),
+        projectId: typeof raw['projectId'] === 'string' ? raw['projectId'] : undefined,
+        keyFile: typeof raw['keyFile'] === 'string' ? raw['keyFile'] : undefined,
+        url: typeof raw['url'] === 'string' ? raw['url'] : undefined,
+    }),
+};
+const normalizeDiskConfig = (driverName, raw) => {
+    return normalizers[driverName]?.(raw) ?? raw;
+};
+export const Storage = Object.freeze({
+    getDisk(name) {
+        const diskName = name ?? storageConfig.default;
+        // disk is config object; dispatch based on requested name
+        const drivers = storageConfig.drivers;
+        const config = drivers[diskName];
+        if (config === undefined)
+            throw ErrorFactory.createValidationError('Storage: unknown disk', { disk: diskName });
+        const driverName = String(config['driver'] ?? '');
+        if (driverName === 'local')
+            return { driver: LocalDriver, config: normalizeDiskConfig('local', config) };
+        if (driverName === 's3')
+            return { driver: S3Driver, config: normalizeDiskConfig('s3', config) };
+        if (driverName === 'r2')
+            return { driver: R2Driver, config: normalizeDiskConfig('r2', config) };
+        if (driverName === 'gcs')
+            return { driver: GcsDriver, config: normalizeDiskConfig('gcs', config) };
+        throw ErrorFactory.createValidationError('Storage: unsupported disk driver', {
+            driver: config['driver'],
+        });
+    },
+    async put(disk, path, contents) {
+        const d = Storage.getDisk(disk);
+        const driver = d.driver;
+        if (typeof driver.put !== 'function') {
+            throw ErrorFactory.createConfigError('Storage: driver is missing put()');
+        }
+        return driver.put(d.config, path, contents);
+    },
+    async get(disk, path) {
+        const d = Storage.getDisk(disk);
+        const driver = d.driver;
+        if (typeof driver.get !== 'function') {
+            throw ErrorFactory.createConfigError('Storage: driver is missing get()');
+        }
+        return Promise.resolve(driver.get(d.config, path));
+    },
+    async exists(disk, path) {
+        const d = Storage.getDisk(disk);
+        const driver = d.driver;
+        if (typeof driver.exists !== 'function')
+            return true;
+        return Boolean(await Promise.resolve(driver.exists(d.config, path)));
+    },
+    async delete(disk, path) {
+        const d = Storage.getDisk(disk);
+        const driver = d.driver;
+        if (typeof driver.delete !== 'function')
+            return;
+        await Promise.resolve(driver.delete(d.config, path));
+    },
+    url(disk, path) {
+        const d = Storage.getDisk(disk);
+        const driver = d.driver;
+        const url = typeof driver.url === 'function' ? driver.url(d.config, path) : undefined;
+        if (typeof url !== 'string' || url.trim() === '') {
+            throw ErrorFactory.createConfigError('Storage: driver cannot build url()');
+        }
+        return url;
+    },
+    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);
+        }
+        const url = typeof driver.url === 'function' ? driver.url(d.config, path) : undefined;
+        if (typeof url !== 'string' || url.trim() === '') {
+            throw ErrorFactory.createConfigError('Storage: driver does not support tempUrl()');
+        }
+        return url;
+    },
+});
+export default Storage;

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

@@ -0,0 +1,23 @@
+export type FakePut = {
+    disk: string;
+    path: string;
+    contents: Buffer;
+};
+export declare const FakeStorage: Readonly<{
+    _puts: Array<FakePut>;
+    put(disk: string, path: string, contents: Buffer): Promise<void>;
+    get(disk: string, path: string): Buffer<ArrayBufferLike>;
+    exists(disk: string, path: string): boolean;
+    delete(disk: string, path: string): Promise<void>;
+    url(disk: string, path: string): string;
+    tempUrl(disk: string, path: string, options?: {
+        expiresIn?: number;
+        method?: "GET" | "PUT";
+    }): string;
+    assertExists(disk: string, path: string): void;
+    assertMissing(disk: string, path: string): void;
+    getPuts(): FakePut[];
+    reset(): void;
+}>;
+export default FakeStorage;
+//# sourceMappingURL=testing.d.ts.map

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

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

package/src/tools/storage/testing.js

@@ -0,0 +1,52 @@
+import { ErrorFactory } from '../../exceptions/ZintrustError';
+export const FakeStorage = Object.freeze({
+    _puts: [],
+    async put(disk, path, contents) {
+        this._puts.push({ disk, path, contents });
+        // emulate async write
+        return Promise.resolve(); // NOSONAR
+    },
+    get(disk, path) {
+        const found = this._puts.find((p) => p.disk === disk && p.path === path);
+        if (!found)
+            throw ErrorFactory.createNotFoundError(`FakeStorage: ${disk}:${path} not found`);
+        return found.contents;
+    },
+    exists(disk, path) {
+        return this._puts.some((p) => p.disk === disk && p.path === path);
+    },
+    async delete(disk, path) {
+        // mutate the internal array rather than replacing the property (object is frozen)
+        this._puts.splice(0, this._puts.length, ...this._puts.filter((p) => !(p.disk === disk && p.path === path)));
+        return Promise.resolve(); // NOSONAR
+    },
+    // url builder is a convenience: returns a pseudo-url for testing
+    url(disk, path) {
+        return `fake://${disk}/${path}`;
+    },
+    // tempUrl builder is a convenience: matches the real API shape
+    tempUrl(disk, path, options) {
+        const expiresIn = options?.expiresIn ?? 900;
+        const method = options?.method ?? 'GET';
+        return `fake://${disk}/${path}?expiresIn=${expiresIn}&method=${method}`;
+    },
+    // Test assertions
+    assertExists(disk, path) {
+        if (!this._puts.some((p) => p.disk === disk && p.path === path)) {
+            throw ErrorFactory.createValidationError(`Expected ${disk}:${path} to exist in FakeStorage`);
+        }
+    },
+    assertMissing(disk, path) {
+        if (this._puts.some((p) => p.disk === disk && p.path === path)) {
+            throw ErrorFactory.createValidationError(`Expected ${disk}:${path} to be missing in FakeStorage`);
+        }
+    },
+    getPuts() {
+        return this._puts.slice();
+    },
+    reset() {
+        // clear the array in-place
+        this._puts.length = 0;
+    },
+});
+export default FakeStorage;