@zintrust/core 0.1.27 → 0.1.28

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

@@ -0,0 +1,347 @@
+import { readEnvString } from '@common/ExternalServiceUtils';
+import { AwsSigV4 } from '@common/index';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import { createHash, createHmac } from '@node-singletons/crypto';
+
+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;
+};
+
+const sha256Hex = (data: string | Uint8Array): string =>
+  createHash('sha256').update(data).digest('hex');
+
+const buildAuthorization = (params: {
+  method: string;
+  host: string;
+  region: string;
+  amzDate: string;
+  dateStamp: string;
+  credentials: { accessKeyId: string; secretAccessKey: string; sessionToken?: string };
+  payloadHash: string;
+  path: string;
+}): { authorization: string; signedHeaders: string } => {
+  const canonicalUri = params.path;
+  const canonicalQueryString = '';
+
+  const headers: Record<string, string> = {
+    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: S3Config,
+  key: string
+): { host: string; path: string; url: string } => {
+  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: string): string =>
+  encodeURIComponent(value).replaceAll(
+    /[!'()*]/g,
+    (c) => `%${c.codePointAt(0)?.toString(16).toUpperCase()}`
+  );
+
+const encodePathSegments = (key: string): string =>
+  key
+    .split('/')
+    .map((seg) => awsEncodeURIComponent(seg))
+    .join('/');
+
+const buildCanonicalQueryString = (params: Record<string, string>): string => {
+  const entries = Object.entries(params)
+    .filter(([, v]) => v !== '')
+    .map(([k, v]) => [awsEncodeURIComponent(k), awsEncodeURIComponent(v)] as const)
+    .sort((a, b) => a[0].localeCompare(b[0]));
+
+  return entries.map(([k, v]) => `${k}=${v}`).join('&');
+};
+
+const getCredentials = (config: S3Config): GS3Cred => {
+  const accessKeyId = config.accessKeyId || readEnvString('AWS_ACCESS_KEY_ID');
+  const secretAccessKey = config.secretAccessKey || readEnvString('AWS_SECRET_ACCESS_KEY');
+  const sessionToken = readEnvString('AWS_SESSION_TOKEN') || undefined;
+
+  if (accessKeyId.trim() === '' || secretAccessKey.trim() === '') {
+    throw ErrorFactory.createConfigError('S3: missing AWS credentials');
+  }
+  return { accessKeyId, secretAccessKey, sessionToken };
+};
+
+const validateExpiresIn = (expiresIn: number): void => {
+  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: S3Config, key: string, content: string | Buffer): Promise<string> {
+    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: Record<string, string> = {
+      '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: S3Config, key: string): Promise<Buffer> {
+    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: Record<string, string> = {
+      '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: S3Config, key: string): Promise<boolean> {
+    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: Record<string, string> = {
+        '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: S3Config, key: string): Promise<void> {
+    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: Record<string, string> = {
+      '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: S3Config, key: string): string {
+    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: S3Config,
+    key: string,
+    options?: { expiresIn?: number; method?: 'GET' | 'PUT' }
+  ): string {
+    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: Record<string, string> = {
+      '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.ts

@@ -0,0 +1,217 @@
+import { storageConfig } from '@config/storage';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import { LocalDriver } from '@storage/drivers/Local';
+import { StorageDiskRegistry } from '@storage/StorageDiskRegistry';
+import { StorageDriverRegistry } from '@storage/StorageDriverRegistry';
+
+export type DiskName = 'local' | 's3' | 'gcs' | 'r2';
+
+export type StorageDisk = {
+  driver: unknown;
+  config: unknown;
+};
+
+type TempUrlOptions = { expiresIn?: number; method?: 'GET' | 'PUT' };
+
+const normalizers: Record<string, (raw: Record<string, unknown>) => Record<string, unknown>> = {
+  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: string,
+  raw: Record<string, unknown>
+): Record<string, unknown> => {
+  return normalizers[driverName]?.(raw) ?? raw;
+};
+
+const resolveDiskConfigFromRegistry = (name?: string): Record<string, unknown> | undefined => {
+  const selected = String(name ?? '').trim();
+  const hasSelection = name !== undefined && selected.length > 0;
+
+  const registryKey = hasSelection ? selected : 'default';
+  if (!StorageDiskRegistry.has(registryKey)) return undefined;
+
+  return StorageDiskRegistry.get(registryKey) as Record<string, unknown>;
+};
+
+const resolveDiskConfigFromStorageConfig = (name?: string): Record<string, unknown> | undefined => {
+  const maybeGetDriverConfig = (storageConfig as unknown as { getDriverConfig?: unknown })
+    .getDriverConfig;
+
+  if (typeof maybeGetDriverConfig !== 'function') return undefined;
+
+  // Important: call as a method to preserve `this` binding.
+  return (storageConfig as unknown as { getDriverConfig: (n?: string) => unknown }).getDriverConfig(
+    name
+  ) as Record<string, unknown>;
+};
+
+const resolveDiskConfigFromLegacyConfig = (name?: string): Record<string, unknown> | undefined => {
+  const selected = String(name ?? '').trim();
+  const hasSelection = name !== undefined && selected.length > 0;
+
+  const drivers = (storageConfig as unknown as { drivers?: Record<string, unknown> }).drivers ?? {};
+  const defaultName = String(
+    (storageConfig as unknown as { default?: unknown }).default ?? 'local'
+  ).trim();
+
+  const requestedName = hasSelection ? selected : defaultName;
+  const diskName = requestedName === 'default' ? defaultName : requestedName;
+
+  if (diskName !== '' && Object.prototype.hasOwnProperty.call(drivers, diskName)) {
+    return drivers[diskName] as Record<string, unknown>;
+  }
+
+  if (hasSelection && selected !== 'default') {
+    throw ErrorFactory.createConfigError(`Storage disk not configured: ${diskName}`);
+  }
+
+  return (
+    (drivers['local'] as Record<string, unknown> | undefined) ??
+    (Object.values(drivers)[0] as Record<string, unknown> | undefined)
+  );
+};
+
+export const Storage = Object.freeze({
+  getDisk(name?: string): StorageDisk {
+    const config =
+      resolveDiskConfigFromRegistry(name) ??
+      resolveDiskConfigFromStorageConfig(name) ??
+      resolveDiskConfigFromLegacyConfig(name);
+
+    if (config === undefined) {
+      throw ErrorFactory.createConfigError('Storage: no disks are configured');
+    }
+
+    const driverName = String(config['driver'] ?? '')
+      .trim()
+      .toLowerCase();
+
+    if (driverName === 'local') {
+      return { driver: LocalDriver, config: normalizeDiskConfig('local', config) };
+    }
+
+    const entry = StorageDriverRegistry.get(driverName);
+    if (entry === undefined) {
+      if (driverName === 's3' || driverName === 'r2' || driverName === 'gcs') {
+        throw ErrorFactory.createConfigError(
+          `Storage driver not registered: ${driverName} (run \`zin add storage:${driverName}\` / \`npm i @zintrust/storage-${driverName}\`)`
+        );
+      }
+
+      throw ErrorFactory.createValidationError('Storage: unsupported disk driver', {
+        driver: config['driver'],
+      });
+    }
+
+    const normalizedConfig =
+      typeof entry.normalize === 'function'
+        ? entry.normalize(config)
+        : normalizeDiskConfig(driverName, config);
+
+    return { driver: entry.driver, config: normalizedConfig };
+  },
+
+  async put(disk: string | undefined, path: string, contents: string | Buffer): Promise<string> {
+    const d = Storage.getDisk(disk);
+    const driver = d.driver as {
+      put: (config: unknown, key: string, content: string | Buffer) => Promise<string>;
+    };
+    if (typeof driver.put !== 'function') {
+      throw ErrorFactory.createConfigError('Storage: driver is missing put()');
+    }
+    return driver.put(d.config, path, contents);
+  },
+
+  async get(disk: string | undefined, path: string): Promise<Buffer> {
+    const d = Storage.getDisk(disk);
+    const driver = d.driver as {
+      get: (config: unknown, key: string) => Promise<Buffer> | Buffer;
+    };
+    if (typeof driver.get !== 'function') {
+      throw ErrorFactory.createConfigError('Storage: driver is missing get()');
+    }
+    return driver.get(d.config, path);
+  },
+
+  async exists(disk: string | undefined, path: string): Promise<boolean> {
+    const d = Storage.getDisk(disk);
+    const driver = d.driver as {
+      exists?: (config: unknown, key: string) => Promise<boolean> | boolean;
+    };
+    if (typeof driver.exists !== 'function') return true;
+    return Boolean(await driver.exists(d.config, path));
+  },
+
+  async delete(disk: string | undefined, path: string): Promise<void> {
+    const d = Storage.getDisk(disk);
+    const driver = d.driver as {
+      delete?: (config: unknown, key: string) => Promise<void> | void;
+    };
+    if (typeof driver.delete !== 'function') return;
+    await driver.delete(d.config, path);
+  },
+
+  url(disk: string | undefined, path: string): string {
+    const d = Storage.getDisk(disk);
+    const driver = d.driver as {
+      url?: (config: unknown, key: string) => string | undefined;
+    };
+    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;
+  },
+
+  async tempUrl(disk: string | undefined, path: string, options?: TempUrlOptions): Promise<string> {
+    const d = Storage.getDisk(disk);
+    const driver = d.driver as {
+      tempUrl?: (
+        config: unknown,
+        key: string,
+        options?: TempUrlOptions
+      ) => string | Promise<string>;
+      url?: (config: unknown, key: string) => string | undefined;
+    };
+
+    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;
+
+export { StorageDiskRegistry } from '@storage/StorageDiskRegistry';

package/src/tools/storage/testing.ts

@@ -0,0 +1,80 @@
+export type FakePut = {
+  disk: string;
+  path: string;
+  contents: Buffer;
+};
+
+import { ErrorFactory } from '@exceptions/ZintrustError';
+
+export const FakeStorage = Object.freeze({
+  _puts: [] as Array<FakePut>,
+
+  async put(disk: string, path: string, contents: Buffer) {
+    this._puts.push({ disk, path, contents });
+    // emulate async write
+    return Promise.resolve(); // NOSONAR
+  },
+
+  get(disk: string, path: string) {
+    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: string, path: string) {
+    return this._puts.some((p) => p.disk === disk && p.path === path);
+  },
+
+  async delete(disk: string, path: string) {
+    // 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: string, path: string) {
+    return `fake://${disk}/${path}`;
+  },
+
+  // tempUrl builder is a convenience: matches the real API shape
+  async tempUrl(
+    disk: string,
+    path: string,
+    options?: { expiresIn?: number; method?: 'GET' | 'PUT' }
+  ) {
+    const expiresIn = options?.expiresIn ?? 900;
+    const method = options?.method ?? 'GET';
+    await Promise.resolve();
+    return `fake://${disk}/${path}?expiresIn=${expiresIn}&method=${method}`;
+  },
+
+  // Test assertions
+  assertExists(disk: string, path: string) {
+    if (!this._puts.some((p) => p.disk === disk && p.path === path)) {
+      throw ErrorFactory.createValidationError(`Expected ${disk}:${path} to exist in FakeStorage`);
+    }
+  },
+
+  assertMissing(disk: string, path: string) {
+    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;