@open-mercato/core 0.6.2-develop.3380.1.bb14509041 → 0.6.2-develop.3400.1.d948268f50

package/src/modules/attachments/components/AttachmentPartitionSettings.tsx

@@ -37,6 +37,8 @@ type Partition = {
   isPublic: boolean
   requiresOcr: boolean
   ocrModel: string | null
+  storageDriver: string
+  configJson: Record<string, unknown> | null
   envKey: string
   createdAt: string | null
 }
@@ -45,6 +47,8 @@ type DialogState =
   | { mode: 'create' }
   | { mode: 'edit'; entry: Partition }
 
+type S3CredentialsSource = 'integration' | 'env'
+
 const DEFAULT_FORM = {
   code: '',
   title: '',
@@ -52,15 +56,36 @@ const DEFAULT_FORM = {
   isPublic: false,
   requiresOcr: true,
   ocrModel: '',
+  storageDriver: 'local',
+  s3CredentialsSource: 'integration' as S3CredentialsSource,
+  s3CredentialsEnvPrefix: '',
+  s3Bucket: '',
+  s3Region: '',
+  s3Endpoint: '',
+  s3ForcePathStyle: false,
 }
 
+const ALL_STORAGE_DRIVER_OPTIONS = [
+  { value: 'local', label: 'Local filesystem' },
+  { value: 's3', label: 'Amazon S3 / S3-compatible', requiresModule: 's3' },
+]
+
+const OCR_MODEL_DEFAULT_VALUE = '__default__'
+
 const OCR_MODEL_OPTIONS = [
-  { value: '', label: 'Default (from environment)' },
+  { value: OCR_MODEL_DEFAULT_VALUE, label: 'Default (from environment)' },
   { value: 'gpt-4o', label: 'GPT-4o (Recommended)' },
   { value: 'gpt-4o-mini', label: 'GPT-4o Mini (Faster, Lower Cost)' },
 ]
 
-export function AttachmentPartitionSettings() {
+export type AttachmentPartitionSettingsProps = {
+  s3Enabled: boolean
+}
+
+export function AttachmentPartitionSettings({ s3Enabled }: AttachmentPartitionSettingsProps) {
+  const storageDriverOptions = ALL_STORAGE_DRIVER_OPTIONS.filter(
+    (opt) => !opt.requiresModule || (opt.requiresModule === 's3' && s3Enabled),
+  )
   const t = useT()
   const { confirm, ConfirmDialogElement } = useConfirmDialog()
   const [items, setItems] = React.useState<Partition[]>([])
@@ -71,6 +96,9 @@ export function AttachmentPartitionSettings() {
   const [submitting, setSubmitting] = React.useState(false)
   const [error, setError] = React.useState<string | null>(null)
 
+  const s3Unavailable = !s3Enabled
+  const s3SelectedWhileUnavailable = s3Unavailable && form.storageDriver === 's3'
+
   const loadErrorMessage = t('attachments.partitions.errors.load', 'Failed to load partitions.')
 
   const loadItems = React.useCallback(async () => {
@@ -112,6 +140,8 @@ export function AttachmentPartitionSettings() {
 
   const openDialog = React.useCallback((state: DialogState) => {
     if (state.mode === 'edit') {
+      const cfg = state.entry.configJson ?? {}
+      const credsPrefix = typeof cfg.credentialsEnvPrefix === 'string' ? cfg.credentialsEnvPrefix : ''
       setForm({
         code: state.entry.code,
         title: state.entry.title,
@@ -119,6 +149,13 @@ export function AttachmentPartitionSettings() {
         isPublic: state.entry.isPublic,
         requiresOcr: state.entry.requiresOcr,
         ocrModel: state.entry.ocrModel ?? '',
+        storageDriver: state.entry.storageDriver ?? 'local',
+        s3CredentialsSource: credsPrefix ? 'env' : 'integration',
+        s3CredentialsEnvPrefix: credsPrefix,
+        s3Bucket: typeof cfg.bucket === 'string' ? cfg.bucket : '',
+        s3Region: typeof cfg.region === 'string' ? cfg.region : '',
+        s3Endpoint: typeof cfg.endpoint === 'string' ? cfg.endpoint : '',
+        s3ForcePathStyle: cfg.forcePathStyle === true,
       })
     } else {
       setForm(DEFAULT_FORM)
@@ -142,9 +179,42 @@ export function AttachmentPartitionSettings() {
       setError(t('attachments.partitions.errors.required', 'Code and title are required.'))
       return
     }
+    if (form.storageDriver === 's3' && form.s3CredentialsSource === 'env') {
+      if (!form.s3CredentialsEnvPrefix.trim()) {
+        setError(
+          t(
+            'attachments.partitions.errors.s3EnvPrefixRequired',
+            'Credentials env prefix is required when using a separate credentials source.',
+          ),
+        )
+        return
+      }
+      if (!form.s3Bucket.trim()) {
+        setError(
+          t(
+            'attachments.partitions.errors.s3BucketRequired',
+            'Bucket is required when using a separate credentials source.',
+          ),
+        )
+        return
+      }
+    }
     setSubmitting(true)
     setError(null)
     try {
+      const s3ConfigJson =
+        form.storageDriver === 's3'
+          ? {
+              bucket: form.s3Bucket.trim() || undefined,
+              region: form.s3Region.trim() || undefined,
+              endpoint: form.s3Endpoint.trim() || undefined,
+              forcePathStyle: form.s3ForcePathStyle || undefined,
+              ...(form.s3CredentialsSource === 'env'
+                ? { credentialsEnvPrefix: form.s3CredentialsEnvPrefix.trim() || undefined }
+                : {}),
+            }
+          : null
+
       const payload = {
         code: trimmedCode,
         title: trimmedTitle,
@@ -152,6 +222,8 @@ export function AttachmentPartitionSettings() {
         isPublic: form.isPublic,
         requiresOcr: form.requiresOcr,
         ocrModel: form.ocrModel.trim() || null,
+        storageDriver: form.storageDriver,
+        configJson: s3ConfigJson,
       }
       const method = dialog.mode === 'create' ? 'POST' : 'PUT'
       const body =
@@ -259,6 +331,15 @@ export function AttachmentPartitionSettings() {
           </span>
         ),
       },
+      {
+        header: t('attachments.partitions.table.storageDriver', 'Storage'),
+        accessorKey: 'storageDriver',
+        cell: ({ row }) => (
+          <span className="text-sm capitalize">
+            {row.original.storageDriver === 's3' ? 'S3' : row.original.storageDriver ?? 'local'}
+          </span>
+        ),
+      },
       {
         header: t('attachments.partitions.table.envKey', 'Env variable'),
         accessorKey: 'envKey',
@@ -408,8 +489,13 @@ export function AttachmentPartitionSettings() {
                   {t('attachments.partitions.form.ocrModelLabel', 'OCR Model')}
                 </Label>
                 <Select
-                  value={form.ocrModel || undefined}
-                  onValueChange={(value) => setForm((prev) => ({ ...prev, ocrModel: value ?? '' }))}
+                  value={form.ocrModel ? form.ocrModel : OCR_MODEL_DEFAULT_VALUE}
+                  onValueChange={(value) =>
+                    setForm((prev) => ({
+                      ...prev,
+                      ocrModel: value === OCR_MODEL_DEFAULT_VALUE ? '' : value,
+                    }))
+                  }
                 >
                   <SelectTrigger id="partition-ocr-model">
                     <SelectValue />
@@ -417,7 +503,12 @@ export function AttachmentPartitionSettings() {
                   <SelectContent>
                     {OCR_MODEL_OPTIONS.map((option) => (
                       <SelectItem key={option.value} value={option.value}>
-                        {t(`attachments.partitions.form.ocrModelOptions.${option.value || 'default'}`, option.label)}
+                        {t(
+                          `attachments.partitions.form.ocrModelOptions.${
+                            option.value === OCR_MODEL_DEFAULT_VALUE ? 'default' : option.value
+                          }`,
+                          option.label,
+                        )}
                       </SelectItem>
                     ))}
                   </SelectContent>
@@ -430,6 +521,175 @@ export function AttachmentPartitionSettings() {
                 </p>
               </div>
             )}
+            <div className="space-y-2">
+              <Label htmlFor="partition-storage-driver">
+                {t('attachments.partitions.form.storageDriverLabel', 'Storage Driver')}
+              </Label>
+              <select
+                id="partition-storage-driver"
+                className="w-full rounded-md border border-input bg-background px-3 py-2 text-sm"
+                value={form.storageDriver}
+                onChange={(event) => setForm((prev) => ({ ...prev, storageDriver: event.target.value }))}
+              >
+                {storageDriverOptions.map((option) => (
+                  <option
+                    key={option.value}
+                    value={option.value}
+                    disabled={option.value === 's3' && s3Unavailable}
+                  >
+                    {option.label}
+                  </option>
+                ))}
+              </select>
+              {s3Unavailable ? (
+                <p className="text-xs text-muted-foreground">
+                  {t(
+                    'attachments.partitions.form.storageDriverS3DisabledHelp',
+                    'S3 is disabled. Set OM_ENABLE_STORAGE_S3=true and restart to enable S3 partitions.',
+                  )}
+                </p>
+              ) : null}
+            </div>
+            {form.storageDriver === 's3' && (
+              <div className="space-y-3 rounded-md border bg-muted/30 p-3">
+                <p className="text-xs font-medium text-muted-foreground">
+                  {t('attachments.partitions.form.s3ConfigTitle', 'S3 Configuration')}
+                </p>
+                <div className="space-y-2">
+                  <Label htmlFor="partition-s3-creds-source">
+                    {t('attachments.partitions.form.s3CredsSourceLabel', 'Credentials source')}
+                  </Label>
+                  <select
+                    id="partition-s3-creds-source"
+                    className="w-full rounded-md border border-input bg-background px-3 py-2 text-sm"
+                    value={form.s3CredentialsSource}
+                    onChange={(event) =>
+                      setForm((prev) => ({
+                        ...prev,
+                        s3CredentialsSource: event.target.value as S3CredentialsSource,
+                        ...(event.target.value === 'integration' ? { s3CredentialsEnvPrefix: '' } : {}),
+                      }))
+                    }
+                  >
+                    <option value="integration">
+                      {t(
+                        'attachments.partitions.form.s3CredsSourceIntegration',
+                        'Use Integration Marketplace credentials',
+                      )}
+                    </option>
+                    <option value="env">
+                      {t(
+                        'attachments.partitions.form.s3CredsSourceEnv',
+                        'Use separate env-based credentials',
+                      )}
+                    </option>
+                  </select>
+                  <p className="text-xs text-muted-foreground">
+                    {form.s3CredentialsSource === 'integration'
+                      ? t(
+                          'attachments.partitions.form.s3CredsSourceIntegrationHelp',
+                          'This partition reuses the credentials, bucket, region and endpoint configured in the S3 integration. Override individual fields below only when needed.',
+                        )
+                      : t(
+                          'attachments.partitions.form.s3CredsSourceEnvHelp',
+                          'This partition uses its own credentials read from environment variables. The integration credentials are ignored. Bucket and credentials prefix are required.',
+                        )}
+                  </p>
+                </div>
+                {form.s3CredentialsSource === 'env' && (
+                  <div className="space-y-2">
+                    <Label htmlFor="partition-s3-creds-prefix">
+                      {t('attachments.partitions.form.s3CredsPrefixLabel', 'Credentials Env Prefix')}
+                    </Label>
+                    <Input
+                      id="partition-s3-creds-prefix"
+                      value={form.s3CredentialsEnvPrefix}
+                      onChange={(event) => setForm((prev) => ({ ...prev, s3CredentialsEnvPrefix: event.target.value }))}
+                      placeholder="OM_INTEGRATION_STORAGE_S3"
+                      className="font-mono"
+                    />
+                    <p className="text-xs text-muted-foreground">
+                      {t(
+                        'attachments.partitions.form.s3CredsPrefixHelp',
+                        'Reads {PREFIX}_ACCESS_KEY_ID and {PREFIX}_SECRET_ACCESS_KEY from environment variables.',
+                      )}
+                    </p>
+                  </div>
+                )}
+                <div className="space-y-2">
+                  <Label htmlFor="partition-s3-bucket">
+                    {form.s3CredentialsSource === 'integration'
+                      ? t('attachments.partitions.form.s3BucketOverrideLabel', 'Bucket override (optional)')
+                      : t('attachments.partitions.form.s3BucketLabel', 'Bucket')}
+                  </Label>
+                  <Input
+                    id="partition-s3-bucket"
+                    value={form.s3Bucket}
+                    onChange={(event) => setForm((prev) => ({ ...prev, s3Bucket: event.target.value }))}
+                    placeholder={
+                      form.s3CredentialsSource === 'integration'
+                        ? t(
+                            'attachments.partitions.form.s3BucketOverridePlaceholder',
+                            'Leave empty to use integration bucket',
+                          )
+                        : 'my-company-attachments'
+                    }
+                  />
+                </div>
+                <div className="space-y-2">
+                  <Label htmlFor="partition-s3-region">
+                    {form.s3CredentialsSource === 'integration'
+                      ? t('attachments.partitions.form.s3RegionOverrideLabel', 'Region override (optional)')
+                      : t('attachments.partitions.form.s3RegionLabel', 'Region')}
+                  </Label>
+                  <Input
+                    id="partition-s3-region"
+                    value={form.s3Region}
+                    onChange={(event) => setForm((prev) => ({ ...prev, s3Region: event.target.value }))}
+                    placeholder={
+                      form.s3CredentialsSource === 'integration'
+                        ? t(
+                            'attachments.partitions.form.s3RegionOverridePlaceholder',
+                            'Leave empty to use integration region',
+                          )
+                        : 'us-east-1'
+                    }
+                  />
+                </div>
+                <div className="space-y-2">
+                  <Label htmlFor="partition-s3-endpoint">
+                    {form.s3CredentialsSource === 'integration'
+                      ? t('attachments.partitions.form.s3EndpointOverrideLabel', 'Custom endpoint override (optional)')
+                      : t('attachments.partitions.form.s3EndpointLabel', 'Custom Endpoint')}
+                  </Label>
+                  <Input
+                    id="partition-s3-endpoint"
+                    value={form.s3Endpoint}
+                    onChange={(event) => setForm((prev) => ({ ...prev, s3Endpoint: event.target.value }))}
+                    placeholder={
+                      form.s3CredentialsSource === 'integration'
+                        ? t(
+                            'attachments.partitions.form.s3EndpointOverridePlaceholder',
+                            'Leave empty to use integration endpoint',
+                          )
+                        : 'https://fra1.digitaloceanspaces.com'
+                    }
+                  />
+                  <p className="text-xs text-muted-foreground">
+                    {t('attachments.partitions.form.s3EndpointHelp', 'Leave empty for AWS S3. Required for MinIO, DigitalOcean Spaces, etc.')}
+                  </p>
+                </div>
+                <label className="flex items-center gap-2 text-sm font-medium">
+                  <input
+                    type="checkbox"
+                    className="h-4 w-4 rounded border"
+                    checked={form.s3ForcePathStyle}
+                    onChange={(event) => setForm((prev) => ({ ...prev, s3ForcePathStyle: event.target.checked }))}
+                  />
+                  {t('attachments.partitions.form.s3ForcePathStyleLabel', 'Force Path Style (required for MinIO)')}
+                </label>
+              </div>
+            )}
             {dialog ? (
               <div className="rounded-md border bg-muted/50 px-3 py-2 text-xs text-muted-foreground">
                 <div>
@@ -444,13 +704,21 @@ export function AttachmentPartitionSettings() {
                 </code>
               </div>
             ) : null}
-            {error ? <p className="text-sm text-red-600">{error}</p> : null}
+            {s3SelectedWhileUnavailable ? (
+              <p className="text-sm text-status-error-text">
+                {t(
+                  'attachments.partitions.errors.s3Disabled',
+                  'This partition uses S3, but S3 is disabled. Set OM_ENABLE_STORAGE_S3=true and restart the app.',
+                )}
+              </p>
+            ) : null}
+            {error ? <p className="text-sm text-status-error-text">{error}</p> : null}
           </form>
           <DialogFooter>
             <Button variant="ghost" onClick={closeDialog}>
               {t('attachments.partitions.actions.cancel', 'Cancel')}
             </Button>
-            <Button onClick={() => void handleSubmit()} disabled={submitting}>
+            <Button onClick={() => void handleSubmit()} disabled={submitting || s3SelectedWhileUnavailable}>
               {dialog?.mode === 'edit'
                 ? t('attachments.partitions.actions.save', 'Save changes')
                 : t('attachments.partitions.actions.create', 'Create partition')}

package/src/modules/attachments/di.ts

@@ -0,0 +1,13 @@
+import { asFunction } from 'awilix'
+import type { AppContainer } from '@open-mercato/shared/lib/di/container'
+import { StorageDriverFactory } from './lib/drivers/driverFactory'
+
+export function register(container: AppContainer) {
+  container.register({
+    storageDriverFactory: asFunction(({ em }: { em: ConstructorParameters<typeof StorageDriverFactory>[0] }) =>
+      new StorageDriverFactory(em),
+    )
+      .singleton()
+      .proxy(),
+  })
+}

package/src/modules/attachments/lib/drivers/driverFactory.ts

@@ -0,0 +1,91 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { StorageDriver } from './types'
+import { LocalStorageDriver } from './localDriver'
+import { LegacyPublicStorageDriver } from './legacyPublicDriver'
+import { AttachmentPartition } from '../../data/entities'
+
+type DriverScope = { tenantId: string; organizationId: string }
+type CredentialEnhancer = (config: Record<string, unknown>, scope: DriverScope) => Promise<Record<string, unknown>>
+
+type DriverRegistration = { factory: (config: Record<string, unknown>) => StorageDriver }
+type EnhancerRegistration = { enhancer: CredentialEnhancer }
+
+const moduleDriverRegistry = new Map<string, DriverRegistration>()
+const moduleEnhancerRegistry = new Map<string, EnhancerRegistration>()
+
+export function registerExternalStorageDriver(
+  key: string,
+  factory: (config: Record<string, unknown>) => StorageDriver,
+): void {
+  moduleDriverRegistry.set(key, { factory })
+}
+
+export function registerExternalCredentialEnhancer(key: string, enhancer: CredentialEnhancer): void {
+  moduleEnhancerRegistry.set(key, { enhancer })
+}
+
+export class StorageDriverFactory {
+  private readonly cache = new Map<string, StorageDriver>()
+  private readonly localDriver = new LocalStorageDriver()
+  private readonly legacyPublicDriver = new LegacyPublicStorageDriver()
+  private readonly externalDrivers = new Map<string, (config: Record<string, unknown>) => StorageDriver>()
+  private readonly credentialEnhancers = new Map<string, CredentialEnhancer>()
+
+  constructor(private readonly em: EntityManager) {}
+
+  registerDriver(key: string, factory: (config: Record<string, unknown>) => StorageDriver): void {
+    this.externalDrivers.set(key, factory)
+  }
+
+  registerCredentialEnhancer(key: string, enhancer: CredentialEnhancer): void {
+    this.credentialEnhancers.set(key, enhancer)
+  }
+
+  resolveForAttachment(
+    storageDriver: string,
+    configJson?: Record<string, unknown> | null,
+  ): StorageDriver {
+    switch (storageDriver) {
+      case 'legacyPublic':
+        return this.legacyPublicDriver
+
+      case 'local':
+        return this.localDriver
+
+      default: {
+        const externalFactory =
+          this.externalDrivers.get(storageDriver) ?? moduleDriverRegistry.get(storageDriver)?.factory
+        if (externalFactory) {
+          const cacheKey = `${storageDriver}:${JSON.stringify(configJson ?? {})}`
+          const cached = this.cache.get(cacheKey)
+          if (cached) return cached
+          const driver = externalFactory(configJson ?? {})
+          this.cache.set(cacheKey, driver)
+          return driver
+        }
+        return this.localDriver
+      }
+    }
+  }
+
+  async resolveForPartition(partitionCode: string, scope?: DriverScope): Promise<StorageDriver> {
+    const partition = await this.em.findOne(AttachmentPartition, { code: partitionCode })
+    if (!partition) return this.localDriver
+
+    const driverKey = partition.storageDriver ?? 'local'
+    console.log(`[storageDriverFactory] resolveForPartition: partition=${partitionCode} driverKey=${driverKey} moduleDrivers=${[...moduleDriverRegistry.keys()].join(',')} instanceDrivers=${[...this.externalDrivers.keys()].join(',')}`)
+    let config: Record<string, unknown> = partition.configJson ?? {}
+
+    const activeEnhancer =
+      this.credentialEnhancers.get(driverKey) ?? moduleEnhancerRegistry.get(driverKey)?.enhancer
+    if (scope && activeEnhancer) {
+      config = await activeEnhancer(config, scope)
+      // Skip shared cache for scope-enhanced configs (credentials are per-tenant)
+      const externalFactory =
+        this.externalDrivers.get(driverKey) ?? moduleDriverRegistry.get(driverKey)?.factory
+      if (externalFactory) return externalFactory(config)
+    }
+
+    return this.resolveForAttachment(driverKey, config)
+  }
+}

package/src/modules/attachments/lib/drivers/index.ts

@@ -0,0 +1,4 @@
+export type { StorageDriver, StoreFilePayload, StoredFile, ReadFileResult } from './types'
+export { LocalStorageDriver } from './localDriver'
+export { LegacyPublicStorageDriver } from './legacyPublicDriver'
+export { StorageDriverFactory, registerExternalStorageDriver, registerExternalCredentialEnhancer } from './driverFactory'

package/src/modules/attachments/lib/drivers/legacyPublicDriver.ts

@@ -0,0 +1,46 @@
+import { promises as fs } from 'fs'
+import path from 'path'
+import type { StorageDriver, StoreFilePayload, StoredFile, ReadFileResult } from './types'
+
+export class LegacyPublicStorageDriver implements StorageDriver {
+  readonly key = 'legacyPublic'
+
+  store(_payload: StoreFilePayload): Promise<StoredFile> {
+    throw new Error('legacy-public driver is read-only')
+  }
+
+  async read(_partitionCode: string, storagePath: string): Promise<ReadFileResult> {
+    const absolutePath = this.resolveAbsolutePath(storagePath)
+    const buffer = await fs.readFile(absolutePath)
+    return { buffer }
+  }
+
+  async delete(_partitionCode: string, storagePath: string): Promise<void> {
+    const absolutePath = this.resolveAbsolutePath(storagePath)
+    try {
+      await fs.unlink(absolutePath)
+    } catch {
+      // best-effort removal
+    }
+  }
+
+  async toLocalPath(
+    _partitionCode: string,
+    storagePath: string,
+  ): Promise<{ filePath: string; cleanup: () => Promise<void> }> {
+    return {
+      filePath: this.resolveAbsolutePath(storagePath),
+      cleanup: async () => {},
+    }
+  }
+
+  private resolveAbsolutePath(storagePath: string): string {
+    let safeRelative = storagePath.replace(/^\/*/, '')
+    let prev: string
+    do {
+      prev = safeRelative
+      safeRelative = safeRelative.replace(/\.\.(\/|\\)/g, '')
+    } while (safeRelative !== prev)
+    return path.join(process.cwd(), safeRelative)
+  }
+}

package/src/modules/attachments/lib/drivers/localDriver.ts

@@ -0,0 +1,79 @@
+import { promises as fs } from 'fs'
+import path from 'path'
+import { randomUUID } from 'crypto'
+import { resolvePartitionRoot } from '../storage'
+import type { StorageDriver, StoreFilePayload, StoredFile, ReadFileResult } from './types'
+
+function sanitizeFileName(fileName: string): string {
+  if (!fileName) return 'file'
+  return fileName.replace(/[^a-zA-Z0-9._-]/g, '_')
+}
+
+function resolveOrgSegment(orgId: string | null | undefined): string {
+  if (typeof orgId === 'string' && orgId.trim().length > 0) return `org_${orgId}`
+  return 'org_shared'
+}
+
+function resolveTenantSegment(tenantId: string | null | undefined): string {
+  if (typeof tenantId === 'string' && tenantId.trim().length > 0) return `tenant_${tenantId}`
+  return 'tenant_shared'
+}
+
+export class LocalStorageDriver implements StorageDriver {
+  readonly key = 'local'
+
+  async store(payload: StoreFilePayload): Promise<StoredFile> {
+    const root = resolvePartitionRoot(payload.partitionCode)
+    const orgSegment = resolveOrgSegment(payload.orgId ?? null)
+    const tenantSegment = resolveTenantSegment(payload.tenantId ?? null)
+    const safeName = sanitizeFileName(payload.fileName || 'file')
+    const uniqueSuffix = randomUUID().replace(/-/g, '').slice(0, 12)
+    const storedName = `${Date.now()}_${uniqueSuffix}_${safeName}`
+    const relativePath = path.join(orgSegment, tenantSegment, storedName)
+    const absolutePath = path.join(root, relativePath)
+    await fs.mkdir(path.dirname(absolutePath), { recursive: true })
+    await fs.writeFile(absolutePath, payload.buffer)
+    return {
+      storagePath: relativePath.replace(/\\/g, '/'),
+    }
+  }
+
+  async read(partitionCode: string, storagePath: string): Promise<ReadFileResult> {
+    const absolutePath = this.resolveAbsolutePath(partitionCode, storagePath)
+    const buffer = await fs.readFile(absolutePath)
+    return { buffer }
+  }
+
+  async delete(partitionCode: string, storagePath: string): Promise<void> {
+    const absolutePath = this.resolveAbsolutePath(partitionCode, storagePath)
+    try {
+      await fs.unlink(absolutePath)
+    } catch {
+      // best-effort removal
+    }
+  }
+
+  async toLocalPath(
+    partitionCode: string,
+    storagePath: string,
+  ): Promise<{ filePath: string; cleanup: () => Promise<void> }> {
+    const filePath = this.resolveAbsolutePath(partitionCode, storagePath)
+    return {
+      filePath,
+      cleanup: async () => {
+        // no-op: local path is the real file, do not delete
+      },
+    }
+  }
+
+  private resolveAbsolutePath(partitionCode: string, storagePath: string): string {
+    let safeRelative = storagePath.replace(/^\/*/, '')
+    let prev: string
+    do {
+      prev = safeRelative
+      safeRelative = safeRelative.replace(/\.\.(\/|\\)/g, '')
+    } while (safeRelative !== prev)
+    const root = resolvePartitionRoot(partitionCode)
+    return path.join(root, safeRelative)
+  }
+}

package/src/modules/attachments/lib/drivers/types.ts

@@ -0,0 +1,28 @@
+export type StoreFilePayload = {
+  partitionCode: string
+  orgId: string | null | undefined
+  tenantId: string | null | undefined
+  fileName: string
+  buffer: Buffer
+}
+
+export type StoredFile = {
+  storagePath: string
+  driverMeta?: Record<string, unknown> | null
+}
+
+export type ReadFileResult = {
+  buffer: Buffer
+  contentType?: string
+}
+
+export interface StorageDriver {
+  readonly key: string
+  store(payload: StoreFilePayload): Promise<StoredFile>
+  read(partitionCode: string, storagePath: string): Promise<ReadFileResult>
+  delete(partitionCode: string, storagePath: string): Promise<void>
+  toLocalPath(
+    partitionCode: string,
+    storagePath: string,
+  ): Promise<{ filePath: string; cleanup: () => Promise<void> }>
+}