@zintrust/core 0.1.28 → 0.1.30

package/src/tools/storage/StorageRuntimeRegistration.ts

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

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

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

@@ -1,99 +0,0 @@
-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;