@zintrust/core 0.1.27 → 0.1.28

package/src/tools/storage/StorageRuntimeRegistration.ts

@@ -0,0 +1,32 @@
+import type { StorageConfigRuntime, StorageDriverConfig } from '@config/type';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import { StorageDiskRegistry } from '@storage/StorageDiskRegistry';
+
+export type StorageRuntimeConfig = StorageConfigRuntime & {
+  getDriverConfig?: (name?: string) => StorageDriverConfig;
+};
+
+export function registerDisksFromRuntimeConfig(config: StorageRuntimeConfig): void {
+  for (const [name, driverConfig] of Object.entries(config.drivers)) {
+    StorageDiskRegistry.register(name, driverConfig);
+  }
+
+  // Alias reserved name `default` to the configured default.
+  const defaultName = String(config.default ?? '').trim();
+  if (defaultName.length === 0) {
+    throw ErrorFactory.createConfigError('Storage default disk is not configured');
+  }
+
+  const resolvedDefault = config.drivers[defaultName];
+  if (resolvedDefault === undefined) {
+    throw ErrorFactory.createConfigError(`Storage default disk not configured: ${defaultName}`);
+  }
+
+  StorageDiskRegistry.register('default', resolvedDefault);
+}
+
+export const StorageRuntimeRegistration = Object.freeze({
+  registerDisksFromRuntimeConfig,
+});
+
+export default StorageRuntimeRegistration;

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

@@ -0,0 +1,201 @@
+import { ErrorFactory } from '@exceptions/ZintrustError';
+
+export type GcsConfig = {
+  bucket: string;
+  projectId?: string;
+  keyFile?: string;
+  url?: string;
+};
+
+type TempUrlOptions = { expiresIn?: number; method?: 'GET' | 'PUT' };
+
+type GcsClientLike = {
+  bucket: (name: string) => {
+    file: (key: string) => {
+      save?: (content: string | Buffer) => Promise<unknown>;
+      download?: () => Promise<[Uint8Array | Buffer | string]>;
+      exists?: () => Promise<[boolean]>;
+      delete?: (options?: unknown) => Promise<unknown>;
+      getSignedUrl?: (options: unknown) => Promise<[string]>;
+    };
+  };
+};
+
+let cachedRealClient: GcsClientLike | undefined;
+
+const getInjectedStorageModule = (): unknown => {
+  return (globalThis as unknown as { __fakeGoogleCloudStorageModule?: unknown })
+    .__fakeGoogleCloudStorageModule;
+};
+
+const getInjectedFakeClient = (): GcsClientLike | undefined => {
+  const v = (globalThis as unknown as { __fakeGcsClient?: unknown }).__fakeGcsClient;
+  return v as GcsClientLike | undefined;
+};
+
+const loadRealClient = async (config: GcsConfig): Promise<GcsClientLike> => {
+  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: { Storage?: new (opts?: Record<string, unknown>) => GcsClientLike };
+  try {
+    mod = (injected ?? (await import(specifier))) as unknown as {
+      Storage?: new (opts?: Record<string, unknown>) => GcsClientLike;
+    };
+  } catch (err: unknown) {
+    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: Record<string, unknown> = {};
+  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: unknown) {
+    throw ErrorFactory.createConfigError('GCS: failed to initialize Storage client', {
+      error: err,
+    });
+  }
+};
+
+const getClient = async (config: GcsConfig): Promise<GcsClientLike> => {
+  const injected = getInjectedFakeClient();
+  if (injected !== undefined) return injected;
+  return loadRealClient(config);
+};
+
+const encodePathSegments = (key: string): string =>
+  key
+    .split('/')
+    .map((seg) => encodeURIComponent(seg))
+    .join('/');
+
+export const GcsDriver = Object.freeze({
+  url(config: GcsConfig, key: string): string | undefined {
+    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: GcsConfig, key: string, content: string | Buffer): Promise<string> {
+    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: GcsConfig, key: string): Promise<Buffer> {
+    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: GcsConfig, key: string): Promise<boolean> {
+    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: GcsConfig, key: string): Promise<void> {
+    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: unknown) {
+      void err; // NOSONAR
+    }
+  },
+
+  async tempUrl(config: GcsConfig, key: string, options?: TempUrlOptions): Promise<string> {
+    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.ts

@@ -0,0 +1,116 @@
+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 '@storage/LocalSignedUrl';
+
+export type LocalConfig = {
+  root: string;
+  url?: string;
+};
+
+export const LocalDriver = Object.freeze({
+  resolveKey(config: LocalConfig, key: string): string {
+    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: LocalConfig, key: string, content: string | Buffer): Promise<string> {
+    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: LocalConfig, key: string): Promise<Buffer> {
+    const fullPath = LocalDriver.resolveKey(config, key);
+    try {
+      return await fs.readFile(fullPath);
+    } catch (err: unknown) {
+      throw ErrorFactory.createNotFoundError('Local storage: file not found', { key, error: err });
+    }
+  },
+
+  async exists(config: LocalConfig, key: string): Promise<boolean> {
+    const fullPath = LocalDriver.resolveKey(config, key);
+    try {
+      await fs.access(fullPath);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+
+  async delete(config: LocalConfig, key: string): Promise<void> {
+    const fullPath = LocalDriver.resolveKey(config, key);
+    try {
+      await fs.unlink(fullPath);
+    } catch {
+      // ignore not found
+    }
+  },
+
+  url(config: LocalConfig, key: string): string | undefined {
+    if (config?.url === undefined || config.url.trim() === '') return undefined;
+    return `${config.url.replace(/\/$/, '')}/${key}`;
+  },
+
+  tempUrl(
+    config: LocalConfig,
+    key: string,
+    options?: { expiresIn?: number; method?: 'GET' | 'PUT' }
+  ): string {
+    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.ts

@@ -0,0 +1,99 @@
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import { S3Driver, type S3Config } from '@storage/drivers/S3';
+
+export type R2Config = {
+  bucket: string;
+  region?: string;
+  accessKeyId: string;
+  secretAccessKey: string;
+  endpoint?: string; // Cloudflare R2 endpoint (e.g., https://<accountid>.r2.cloudflarestorage.com)
+};
+
+export const R2Driver = Object.freeze({
+  async put(config: R2Config, key: string, content: string | Buffer): Promise<string> {
+    if (typeof config.endpoint !== 'string' || config.endpoint.trim() === '') {
+      throw ErrorFactory.createConfigError('R2: missing endpoint');
+    }
+
+    // Delegate to S3Driver using path-style endpoint
+    const s3Config: S3Config & { usePathStyle?: boolean } = {
+      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: R2Config, key: string): Promise<Buffer> {
+    const s3Config: S3Config & { usePathStyle?: boolean } = {
+      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: R2Config, key: string): Promise<boolean> {
+    const s3Config: S3Config & { usePathStyle?: boolean } = {
+      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: R2Config, key: string): Promise<void> {
+    const s3Config: S3Config & { usePathStyle?: boolean } = {
+      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: R2Config, key: string): string {
+    if (config.endpoint !== undefined && config.endpoint.trim() !== '') {
+      return `${config.endpoint.replace(/\/$/, '')}/${config.bucket}/${key}`;
+    }
+    return `https://${config.bucket}.r2.cloudflarestorage.com/${key}`;
+  },
+
+  tempUrl(
+    config: R2Config,
+    key: string,
+    options?: { expiresIn?: number; method?: 'GET' | 'PUT' }
+  ): string {
+    if (typeof config.endpoint !== 'string' || config.endpoint.trim() === '') {
+      throw ErrorFactory.createConfigError('R2: missing endpoint');
+    }
+
+    const s3Config: S3Config & { usePathStyle?: boolean } = {
+      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;