@open-mercato/core 0.10.1-develop.7736.1.88e07906bf → 0.10.1-develop.7748.1.d745ba61aa

package/src/modules/attachments/api/route.ts

@@ -1,3 +1,10 @@
+import { LockMode } from '@mikro-orm/core'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { prepareAttachmentMutation } from '../lib/access-mutation'
+import { throwAttachmentAccessError } from '../lib/access-errors'
+import { createAttachmentAccessContext } from '../lib/access-runner'
+import { assertAttachmentOwnerAccess, requiresAttachmentAccessScan, scanAuthorizedAttachments } from '../lib/access-query'
+import { withAttachmentAccessErrors } from '../lib/access-errors'
 import { NextResponse } from 'next/server'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
@@ -5,6 +12,7 @@ import { z } from 'zod'
 import { sql } from 'kysely'
 import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
 import { buildAttachmentFileUrl, buildAttachmentImageUrl, slugifyAttachmentFileName } from '../lib/imageUrls'
+import { ensureAttachmentPartitionProtection } from '../lib/access-protection'
 import { ensureDefaultPartitions, resolveDefaultPartitionCode, sanitizePartitionCode } from '../lib/partitions'
 import { Attachment, AttachmentPartition } from '../data/entities'
 import { extractAttachmentContent } from '../lib/textExtraction'
@@ -12,7 +20,7 @@ import { requestOcrProcessing } from '../lib/ocrQueue'
 import { StorageDriverFactory } from '../lib/drivers'
 import { OcrService, shouldUseLlmOcr } from '../lib/ocrService'
 import { clearAttachmentThumbnailCache } from '../lib/thumbnailCache'
-import { removeAttachmentRecord } from '../lib/storageReferences'
+import { lockAttachmentStorageReferences, resolveAttachmentStorageRelease } from '../lib/storageReferences'
 import { assertAttachmentScopeInvariant } from '../lib/access'
 import { resolveAttachmentRequestScope } from '../lib/requestScope'
 import {
@@ -193,7 +201,7 @@ function parseFormAssignments(value: FormDataEntryValue | null): AttachmentAssig
   }
 }
 
-export async function GET(req: Request) {
+async function listRecordAttachments(req: Request) {
   const auth = await getAuthFromRequest(req)
   if (!auth || !auth.tenantId || (!auth.orgId && !auth.isSuperAdmin)) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
   const url = new URL(req.url)
@@ -217,29 +225,29 @@ export async function GET(req: Request) {
   if (orgId) filter.organizationId = orgId
   const orderBy: Record<string, 'ASC' | 'DESC'> = { createdAt: 'DESC', id: 'DESC' }
   const usePaging = typeof page === 'number' && typeof pageSize === 'number'
-  const total = usePaging ? await em.count(Attachment, filter) : null
   const currentPage = usePaging ? Math.max(1, page) : null
   const currentPageSize = usePaging ? pageSize : null
-  const totalPages = usePaging && total !== null ? Math.max(1, Math.ceil(total / currentPageSize!)) : null
   const pageOffset = usePaging ? (currentPage! - 1) * currentPageSize! : undefined
-  const items = await findWithDecryption(
-    em,
-    Attachment,
-    filter,
-    {
-      orderBy,
-      ...(usePaging
-        ? {
-            limit: currentPageSize!,
-            offset: pageOffset,
-          }
-        : { limit: ATTACHMENT_LIST_MAX_PAGE_SIZE }),
-    },
-    {
-      tenantId: auth.tenantId ?? null,
-      organizationId: orgId ?? null,
-    },
-  )
+  const partitions = await em.find(AttachmentPartition, {})
+  const protectedScan = requiresAttachmentAccessScan(partitions)
+  const scope = { tenantId: auth.tenantId ?? null, organizationId: orgId ?? null }
+  let items: Attachment[]
+  let total: number | null
+  if (protectedScan) {
+    const scanned = await scanAuthorizedAttachments({
+      auth: { ...auth, orgId }, context: createAttachmentAccessContext(container), partitions,
+      offset: pageOffset, limit: currentPageSize ?? ATTACHMENT_LIST_MAX_PAGE_SIZE,
+      loadBatch: (offset, limit) => findWithDecryption(em, Attachment, filter, { orderBy, offset, limit }, scope),
+    })
+    items = scanned.records
+    total = usePaging ? scanned.total : null
+  } else {
+    total = usePaging ? await em.count(Attachment, filter) : null
+    items = await findWithDecryption(em, Attachment, filter, {
+      orderBy, ...(usePaging ? { limit: currentPageSize!, offset: pageOffset } : { limit: ATTACHMENT_LIST_MAX_PAGE_SIZE }),
+    }, scope)
+  }
+  const totalPages = usePaging && total !== null ? Math.max(1, Math.ceil(total / currentPageSize!)) : null
   return NextResponse.json({
     items: items.map((a: any) => {
       const metadata = readAttachmentMetadata(a.storageMetadata)
@@ -269,9 +277,11 @@ export async function GET(req: Request) {
           totalPages,
         }
       : {}),
-  })
+  }, { headers: protectedScan ? { 'Cache-Control': 'private, no-store' } : undefined })
 }
 
+export const GET = withAttachmentAccessErrors(listRecordAttachments)
+
 export async function POST(req: Request) {
   const { t } = await resolveTranslations()
   const auth = await getAuthFromRequest(req)
@@ -458,6 +468,7 @@ export async function POST(req: Request) {
   if (!partition) {
     return NextResponse.json({ error: 'Storage partition is not configured.' }, { status: 400 })
   }
+  await ensureAttachmentPartitionProtection(em, partition)
   const requestedPublicOverride =
     typeof partitionOverride === 'string' &&
     partitionOverride.length > 0 &&
@@ -703,7 +714,7 @@ async function readTenantAttachmentUsageBytes(em: EntityManager, tenantId: strin
   }
 }
 
-export async function DELETE(req: Request) {
+async function deleteAttachment(req: Request) {
   const auth = await getAuthFromRequest(req)
   if (!auth || !auth.tenantId || (!auth.orgId && !auth.isSuperAdmin)) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
   const url = new URL(req.url)
@@ -724,20 +735,34 @@ export async function DELETE(req: Request) {
   const orgId = deleteScope.organizationId
   const deleteFilter: Record<string, unknown> = { id, tenantId: auth.tenantId! }
   if (orgId) deleteFilter.organizationId = orgId
-  const record = await em.findOne(Attachment, deleteFilter)
-  if (!record) return NextResponse.json({ error: 'Attachment not found' }, { status: 404 })
-  const removal = await removeAttachmentRecord(em, record)
-  if (!removal.removed) return NextResponse.json({ error: 'Attachment not found' }, { status: 404 })
+  const scopedAuth = { ...auth, orgId }
+  const outcome = await em.transactional(async (tx) => {
+    const candidate = await findOneWithDecryption(tx, Attachment, deleteFilter, undefined, {
+      tenantId: auth.tenantId, organizationId: orgId,
+    })
+    if (!candidate) return throwAttachmentAccessError(404)
+    const referenceIds = await lockAttachmentStorageReferences(tx, candidate)
+    const removal = resolveAttachmentStorageRelease(referenceIds, candidate.id)
+    if (!removal.removed) return throwAttachmentAccessError(404)
+    const record = await findOneWithDecryption(tx, Attachment, deleteFilter, {
+      lockMode: LockMode.PESSIMISTIC_WRITE, refresh: true,
+    }, { tenantId: auth.tenantId, organizationId: orgId })
+    if (!record) return throwAttachmentAccessError(404)
+    const guard = await prepareAttachmentMutation({ container, req, auth: scopedAuth, recordId: record.id, operation: 'delete' })
+    await assertAttachmentOwnerAccess({ em: tx, context: createAttachmentAccessContext(container), auth: scopedAuth, attachment: record, action: 'delete' })
+    const driver = record.storagePath ? await storageDriverFactory.resolveForPartition(record.partitionCode, {
+      tenantId: record.tenantId ?? auth.tenantId!, organizationId: record.organizationId ?? orgId ?? '',
+    }) : null
+    tx.remove(record)
+    await tx.flush()
+    return { record, driver, guard, releaseStorage: removal.releaseStorage }
+  })
+  const { record } = outcome
   await clearAttachmentThumbnailCache(record.partitionCode, record.id).catch((error) => {
     logger.error('Failed to cleanup cached thumbnails', { err: error })
   })
-  if (record.storagePath && removal.releaseStorage) {
-    const delDriver = await storageDriverFactory.resolveForPartition(record.partitionCode, {
-      tenantId: record.tenantId ?? auth.tenantId!,
-      organizationId: record.organizationId ?? orgId ?? '',
-    })
-    await delDriver.delete(record.partitionCode, record.storagePath)
-  }
+  if (outcome.driver && outcome.releaseStorage) await outcome.driver.delete(record.partitionCode, record.storagePath)
+  await outcome.guard.runAfterSuccess()
   if (dataEngine) {
     await emitCrudSideEffects({
       dataEngine,
@@ -756,6 +781,8 @@ export async function DELETE(req: Request) {
   return NextResponse.json({ ok: true })
 }
 
+export const DELETE = withAttachmentAccessErrors(deleteAttachment)
+
 export const openApi: OpenApiRouteDoc = {
   summary: 'Manage entity attachments',
   description: 'Upload and list attachments associated with module entities and records.',
@@ -770,6 +797,9 @@ export const openApi: OpenApiRouteDoc = {
       errors: [
         { status: 400, description: 'Missing entity or record identifiers', schema: errorSchema },
         { status: 401, description: 'Unauthorized', schema: errorSchema },
+        { status: 403, description: 'Owner policy denies access', schema: errorSchema },
+        { status: 404, description: 'Attachment or owner is unavailable', schema: errorSchema },
+        { status: 504, description: 'Owner authorization timed out', schema: errorSchema },
       ],
     },
     POST: {
@@ -799,6 +829,9 @@ export const openApi: OpenApiRouteDoc = {
       errors: [
         { status: 400, description: 'Missing attachment identifier', schema: errorSchema },
         { status: 401, description: 'Unauthorized', schema: errorSchema },
+        { status: 403, description: 'Owner policy denies access', schema: errorSchema },
+        { status: 404, description: 'Attachment or owner is unavailable', schema: errorSchema },
+        { status: 504, description: 'Owner authorization timed out', schema: errorSchema },
       ],
     },
   },

package/src/modules/attachments/api/transfer/route.ts

@@ -1,3 +1,12 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { LockMode } from '@mikro-orm/core'
+import { findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { Attachment } from '../../data/entities'
+import { createAttachmentAccessContext } from '../../lib/access-runner'
+import { assertAttachmentOwnerAccess } from '../../lib/access-query'
+import { withAttachmentAccessErrors, throwAttachmentAccessError } from '../../lib/access-errors'
+import { prepareAttachmentMutation } from '../../lib/access-mutation'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
 import { NextResponse } from 'next/server'
 import { z } from 'zod'
 import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
@@ -22,60 +31,72 @@ export const metadata = {
   POST: { requireAuth: true, requireFeatures: ['attachments.manage'] },
 }
 
-export async function POST(req: Request) {
+async function transferAttachments(req: Request) {
   const auth = await getAuthFromRequest(req)
   if (!auth || !auth.tenantId || !auth.orgId) {
     return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
   }
-  const json = await req.json().catch(() => null)
+  const json = await readJsonSafe(req, null)
   const parsed = transferSchema.safeParse(json)
   if (!parsed.success) {
     return NextResponse.json({ error: 'Invalid payload' }, { status: 400 })
   }
-  const { attachmentIds, entityId, fromRecordId, toRecordId } = parsed.data
-  const { resolve } = await createRequestContainer()
-  const em = resolve('em') as any
-  let AttachmentEntity: any
-  try {
-    const mod = await import('@open-mercato/core/modules/attachments/data/entities')
-    AttachmentEntity = mod.Attachment
-  } catch {
-    return NextResponse.json({ error: 'Attachment model missing' }, { status: 500 })
-  }
+  const container = await createRequestContainer()
+  const em = container.resolve<EntityManager>('em')
+  const guard = await prepareAttachmentMutation({ container, req, auth, operation: 'update', payload: parsed.data })
+  const effective = transferSchema.safeParse(guard.modifiedPayload ?? parsed.data)
+  if (!effective.success) return throwAttachmentAccessError(403)
+  const { attachmentIds, entityId, fromRecordId } = effective.data
   const filters: Record<string, unknown> = {
-    id: { $in: attachmentIds },
-    entityId,
-    tenantId: auth.tenantId,
-    organizationId: auth.orgId,
-  }
-  if (fromRecordId) {
-    filters.recordId = fromRecordId
-  }
-  const records = await em.find(AttachmentEntity, filters)
-  if (!records.length) {
-    return NextResponse.json({ error: 'Attachments not found' }, { status: 404 })
+    id: { $in: [...new Set(attachmentIds)].sort((left, right) => left < right ? -1 : left > right ? 1 : 0) }, entityId,
+    tenantId: auth.tenantId, organizationId: auth.orgId,
+    ...(fromRecordId ? { recordId: fromRecordId } : {}),
   }
-  for (const record of records) {
-    const previousRecordId = record.recordId
-    record.recordId = toRecordId
-    const metadata = readAttachmentMetadata(record.storageMetadata)
-    const nextAssignments =
-      metadata.assignments?.map((assignment) => {
-        const matchesType = assignment.type === entityId
-        const matchesRecord = fromRecordId
-          ? assignment.id === fromRecordId
-          : assignment.id === previousRecordId
-        if (matchesType && matchesRecord) {
-          return { ...assignment, id: toRecordId }
-        }
-        return assignment
-      }) ?? []
-    record.storageMetadata = mergeAttachmentMetadata(record.storageMetadata, { assignments: nextAssignments })
-  }
-  await em.persist(records).flush()
-  return NextResponse.json({ ok: true, updated: records.length })
+  const accessContext = createAttachmentAccessContext(container)
+  const outcome = await em.transactional(async (tx) => {
+    const records = await findWithDecryption(tx, Attachment, filters, {
+      orderBy: { id: 'asc' }, lockMode: LockMode.PESSIMISTIC_WRITE, refresh: true,
+    }, { tenantId: auth.tenantId, organizationId: auth.orgId })
+    if (records.length !== new Set(attachmentIds).size) return throwAttachmentAccessError(404)
+    const changes = []
+    for (const record of records) {
+      const recordPayload = { ...effective.data, attachmentIds: [record.id] }
+      const recordGuard = await prepareAttachmentMutation({
+        container, req, auth, recordId: record.id, operation: 'update', payload: recordPayload,
+      })
+      const recordEffective = transferSchema.safeParse(recordGuard.modifiedPayload ?? recordPayload)
+      if (!recordEffective.success
+        || recordEffective.data.attachmentIds.length !== 1
+        || recordEffective.data.attachmentIds[0] !== record.id
+        || recordEffective.data.entityId !== record.entityId
+        || (recordEffective.data.fromRecordId && recordEffective.data.fromRecordId !== record.recordId)) {
+        return throwAttachmentAccessError(403)
+      }
+      const destinationId = recordEffective.data.toRecordId
+      const metadata = readAttachmentMetadata(record.storageMetadata)
+      const assignments = metadata.assignments?.map((assignment) => (
+        assignment.type === entityId && assignment.id === (fromRecordId ?? record.recordId)
+          ? { ...assignment, id: destinationId } : assignment
+      )) ?? []
+      const storageMetadata = mergeAttachmentMetadata(record.storageMetadata, { assignments })
+      await assertAttachmentOwnerAccess({ em: tx, context: accessContext, auth, attachment: record, action: 'reassign', persistProtection: true })
+      await assertAttachmentOwnerAccess({ em: tx, context: accessContext, auth, attachment: { ...record, recordId: destinationId, storageMetadata }, action: 'reassign' })
+      changes.push({ record, storageMetadata, destinationId, guard: recordGuard })
+    }
+    for (const { record, storageMetadata, destinationId } of changes) {
+      record.recordId = destinationId
+      record.storageMetadata = storageMetadata
+    }
+    await tx.flush()
+    return { updated: records.length, guards: changes.map((change) => change.guard) }
+  })
+  await guard.runAfterSuccess()
+  for (const recordGuard of outcome.guards) await recordGuard.runAfterSuccess()
+  return NextResponse.json({ ok: true, updated: outcome.updated })
 }
 
+export const POST = withAttachmentAccessErrors(transferAttachments)
+
 export const openApi: OpenApiRouteDoc = {
   tag: attachmentsTag,
   summary: 'Transfer attachments between records',
@@ -95,6 +116,8 @@ export const openApi: OpenApiRouteDoc = {
         { status: 401, description: 'Unauthorized', schema: attachmentErrorSchema },
         { status: 404, description: 'Attachments not found', schema: attachmentErrorSchema },
         { status: 500, description: 'Attachment model missing', schema: attachmentErrorSchema },
+        { status: 403, description: 'Owner policy denies access', schema: attachmentErrorSchema },
+        { status: 504, description: 'Owner authorization timed out', schema: attachmentErrorSchema },
       ],
     },
   },

package/src/modules/attachments/data/entities.ts

@@ -1,6 +1,7 @@
 import { BigIntType, OptionalProps } from '@mikro-orm/core'
 import { Entity, Index, PrimaryKey, Property, Unique } from '@mikro-orm/decorators/legacy'
 import { resolveDefaultAttachmentOcrEnabled } from '../lib/ocrConfig'
+import type { AttachmentAccessRequirement } from '../lib/access-types'
 
 @Entity({ tableName: 'attachment_partitions' })
 @Unique({ name: 'attachment_partitions_code_unique', properties: ['code'] })
@@ -25,6 +26,9 @@ export class AttachmentPartition {
   @Property({ name: 'config_json', type: 'json', nullable: true })
   configJson?: Record<string, unknown> | null
 
+  @Property({ name: 'access_resolver_requirements', type: 'jsonb', nullable: true })
+  accessResolverRequirements?: AttachmentAccessRequirement[] | null
+
   @Property({ name: 'is_public', type: 'boolean', default: false })
   isPublic: boolean = false
 

package/src/modules/attachments/data/validators.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod'
+import type { AttachmentAccessResolver } from '../lib/access-types'
+
+export const attachmentAccessActionSchema = z.enum(['read', 'render', 'metadata', 'reassign', 'delete', 'export'])
+export const attachmentAccessSubjectFeaturesSchema = z.array(z.string())
+export const attachmentAccessSelectorSchema = z.string().min(1).max(200).regex(/^(?:\*|[^*\s]+(?:\.\*)?)$/)
+const resolverIdSchema = z.string().min(3).max(200).regex(/^[a-zA-Z0-9_-]+\.[a-zA-Z0-9_.-]+$/)
+
+export const attachmentAccessRequirementSchema = z.object({
+  resolverId: resolverIdSchema,
+  targetEntity: attachmentAccessSelectorSchema,
+}).strict()
+
+export const protectedAttachmentTargetSchema = attachmentAccessRequirementSchema.extend({
+  targetPartition: attachmentAccessSelectorSchema,
+})
+
+export const attachmentAccessResolverSchema = z.object({
+  id: resolverIdSchema,
+  targetPartition: attachmentAccessSelectorSchema,
+  targetEntity: attachmentAccessSelectorSchema.optional(),
+  actions: z.array(attachmentAccessActionSchema).min(1).optional(),
+  priority: z.number().finite().optional(),
+  timeoutMs: z.number().int().min(1).max(15_000).optional(),
+  resolve: z.custom<AttachmentAccessResolver['resolve']>((value) => typeof value === 'function'),
+}).strict()
+
+export const attachmentAccessRequirementsSchema = z.array(attachmentAccessRequirementSchema)
+export const attachmentAccessDecisionSchema = z.discriminatedUnion('ok', [
+  z.object({ ok: z.literal(true) }).strict(),
+  z.object({
+    ok: z.literal(false),
+    status: z.union([z.literal(401), z.literal(403), z.literal(404), z.literal(504)]),
+    reason: z.string().min(1).max(200).regex(/^[a-zA-Z0-9_.:-]+$/),
+  }).strict(),
+])

package/src/modules/attachments/di.ts

@@ -1,3 +1,4 @@
+import { createAttachmentAccessContext } from './lib/access-runner'
 import { asFunction, asValue } from 'awilix'
 import type { AppContainer } from '@open-mercato/shared/lib/di/container'
 import type { DataEngine } from '@open-mercato/shared/lib/data/engine'
@@ -9,6 +10,7 @@ import { AttachmentTargetAccessService } from './lib/target-access-service'
 import { ScopedAttachmentUploadService } from './lib/scoped-upload-service'
 
 export function register(container: AppContainer) {
+  const accessContext = () => createAttachmentAccessContext(container)
   container.register({
     attachmentQuotaRecoveryScheduler: asValue(scheduleAttachmentQuotaRecovery),
     attachmentQuotaService: asFunction(({ em }: { em: ConstructorParameters<typeof StorageDriverFactory>[0] }) =>
@@ -17,7 +19,7 @@ export function register(container: AppContainer) {
       .scoped()
       .proxy(),
     attachmentTargetAccessService: asFunction(({ em }: { em: ConstructorParameters<typeof StorageDriverFactory>[0] }) =>
-      new AttachmentTargetAccessService(em),
+      new AttachmentTargetAccessService(em, accessContext),
     )
       .scoped()
       .proxy(),
@@ -59,6 +61,7 @@ export function register(container: AppContainer) {
       cradle.em,
       cradle.storageDriverFactory,
       () => cradle.attachmentScopedUploadService ?? null,
+      accessContext,
     ))
       .scoped()
       .proxy(),

package/src/modules/attachments/generators.ts

@@ -0,0 +1,27 @@
+import type { GeneratorPlugin } from '@open-mercato/shared/modules/generators'
+
+const accessPlugin: GeneratorPlugin = {
+  id: 'attachments.access-resolvers',
+  conventionFile: 'data/attachment-access.ts',
+  importPrefix: 'ATTACHMENT_ACCESS',
+  configExpr: (importName, moduleId) =>
+    `{ moduleId: '${moduleId}', resolvers: (${importName}.attachmentAccessResolvers ?? []), protectedTargets: (${importName}.protectedAttachmentTargets ?? []) }`,
+  outputFileName: 'attachment-access.generated.ts',
+  buildOutput: ({ importSection, entriesLiteral }) => `// AUTO-GENERATED by mercato generate registry
+import type { AttachmentAccessResolverEntry } from '@open-mercato/core/modules/attachments'
+${importSection}
+
+export const attachmentAccessEntries: AttachmentAccessResolverEntry[] = [
+${entriesLiteral ? `  ${entriesLiteral}\n` : ''}]
+`,
+  bootstrapRegistration: {
+    entriesExportName: 'attachmentAccessEntries',
+    registrationImports: [
+      "import { registerAttachmentAccessResolvers } from '@open-mercato/core/modules/attachments/lib/access-registry'",
+    ],
+    buildCall: (entries) => `registerAttachmentAccessResolvers(${entries})`,
+  },
+}
+
+export const generatorPlugins: GeneratorPlugin[] = [accessPlugin]
+export default generatorPlugins

package/src/modules/attachments/i18n/de.json

@@ -1,4 +1,8 @@
 {
+  "attachments.access.forbidden": "Zugriff verweigert",
+  "attachments.access.notFound": "Anhang nicht gefunden.",
+  "attachments.access.timeout": "Zeitüberschreitung bei der Zugriffsprüfung des Anhangs. Bitte versuchen Sie es erneut.",
+  "attachments.access.unauthorized": "Nicht autorisiert",
   "attachments.errors.activeContentBlocked": "Das Hochladen aktiver Inhalte ist nicht erlaubt.",
   "attachments.errors.dangerousExecutable": "Ausführbare Dateitypen sind als Anhänge nicht erlaubt.",
   "attachments.errors.maxUploadSize": "Der Anhang überschreitet die maximal zulässige Upload-Größe.",

package/src/modules/attachments/i18n/en.json

@@ -1,4 +1,8 @@
 {
+  "attachments.access.forbidden": "Forbidden",
+  "attachments.access.notFound": "Attachment not found.",
+  "attachments.access.timeout": "Attachment authorization timed out. Please try again.",
+  "attachments.access.unauthorized": "Unauthorized",
   "attachments.errors.activeContentBlocked": "Active content uploads are not allowed.",
   "attachments.errors.dangerousExecutable": "Executable file types are not allowed as attachments.",
   "attachments.errors.maxUploadSize": "Attachment exceeds the maximum upload size.",

package/src/modules/attachments/i18n/es.json

@@ -1,4 +1,8 @@
 {
+  "attachments.access.forbidden": "Acceso denegado",
+  "attachments.access.notFound": "No se encontró el archivo adjunto.",
+  "attachments.access.timeout": "Se agotó el tiempo de comprobación de acceso al archivo adjunto. Inténtalo de nuevo.",
+  "attachments.access.unauthorized": "No autorizado",
   "attachments.errors.activeContentBlocked": "No se permite la carga de contenido activo.",
   "attachments.errors.dangerousExecutable": "No se permiten archivos ejecutables como adjuntos.",
   "attachments.errors.maxUploadSize": "El archivo adjunto supera el tamaño máximo de carga permitido.",

package/src/modules/attachments/i18n/ko.json

@@ -1,4 +1,8 @@
 {
+  "attachments.access.forbidden": "접근이 거부되었습니다",
+  "attachments.access.notFound": "첨부 파일을 찾을 수 없습니다.",
+  "attachments.access.timeout": "첨부 파일 접근 권한 확인 시간이 초과되었습니다. 다시 시도해 주세요.",
+  "attachments.access.unauthorized": "인증이 필요합니다",
   "attachments.errors.activeContentBlocked": "활성 콘텐츠 업로드는 허용되지 않습니다.",
   "attachments.errors.dangerousExecutable": "실행 파일 형식은 첨부 파일로 허용되지 않습니다.",
   "attachments.errors.maxUploadSize": "첨부 파일이 최대 업로드 크기를 초과합니다.",

package/src/modules/attachments/i18n/pl.json

@@ -1,4 +1,8 @@
 {
+  "attachments.access.forbidden": "Brak dostępu",
+  "attachments.access.notFound": "Nie znaleziono załącznika.",
+  "attachments.access.timeout": "Przekroczono czas sprawdzania dostępu do załącznika. Spróbuj ponownie.",
+  "attachments.access.unauthorized": "Brak autoryzacji",
   "attachments.errors.activeContentBlocked": "Przesyłanie treści aktywnych nie jest dozwolone.",
   "attachments.errors.dangerousExecutable": "Pliki wykonywalne nie są dozwolone jako załączniki.",
   "attachments.errors.maxUploadSize": "Załącznik przekracza maksymalny dopuszczalny rozmiar przesyłania.",

package/src/modules/attachments/index.ts

@@ -19,3 +19,21 @@ export {
   type ReadScopedAttachmentResult,
   type ReleaseScopedAttachmentInput,
 } from './lib/attachment-service'
+
+export type {
+  AttachmentAccessAction,
+  AttachmentAccessDecision,
+  AttachmentAccessInput,
+  AttachmentAccessPartition,
+  AttachmentAccessRecord,
+  AttachmentAccessRequirement,
+  AttachmentAccessResolver,
+  AttachmentAccessResolverEntry,
+  AttachmentAccessSubject,
+  AttachmentAccessTarget,
+  ProtectedAttachmentTarget,
+} from './lib/access-types'
+export { registerAttachmentAccessResolvers } from './lib/access-registry'
+export { syncAttachmentAccessProtection } from './lib/access-protection'
+export { createAttachmentAccessContext, evaluateAttachmentAccess } from './lib/access-runner'
+export type { AttachmentAccessContext, AttachmentAccessResult } from './lib/access-runner'

package/src/modules/attachments/lib/access-errors.ts

@@ -0,0 +1,32 @@
+import { CrudHttpError, isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import type { AttachmentAccessDecision } from './access-types'
+
+export async function attachmentAccessErrorBody(status: number): Promise<{ error: string }> {
+  const { t } = await resolveTranslations()
+  const key = status === 401 ? 'unauthorized' : status === 404 ? 'notFound' : status === 504 ? 'timeout' : 'forbidden'
+  return { error: t(`attachments.access.${key}`) }
+}
+
+export async function attachmentAccessErrorResponse(decision: Extract<AttachmentAccessDecision, { ok: false }>): Promise<Response> {
+  return Response.json(await attachmentAccessErrorBody(decision.status), {
+    status: decision.status, headers: { 'Cache-Control': 'private, no-store' },
+  })
+}
+
+export async function throwAttachmentAccessError(status: number): Promise<never> {
+  throw new CrudHttpError(status, await attachmentAccessErrorBody(status))
+}
+
+export function withAttachmentAccessErrors<Arguments extends unknown[]>(handler: (...args: Arguments) => Promise<Response>) {
+  return async (...args: Arguments): Promise<Response> => {
+    try {
+      return await handler(...args)
+    } catch (error) {
+      if (isCrudHttpError(error)) {
+        return Response.json(error.body, { status: error.status, headers: { 'Cache-Control': 'private, no-store' } })
+      }
+      throw error
+    }
+  }
+}

package/src/modules/attachments/lib/access-mutation.ts

@@ -0,0 +1,26 @@
+import type { AwilixContainer } from 'awilix'
+import type { AuthContext } from '@open-mercato/shared/lib/auth/server'
+import { throwAttachmentAccessError } from './access-errors'
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { runRouteMutationGuards } from '@open-mercato/shared/lib/crud/route-mutation-guard'
+
+export async function prepareAttachmentMutation(input: {
+  container: AwilixContainer
+  req: Request
+  auth: NonNullable<AuthContext>
+  recordId?: string
+  operation: 'update' | 'delete'
+  payload?: Record<string, unknown>
+}) {
+  if (!input.auth.tenantId) return throwAttachmentAccessError(401)
+  const guard = await runRouteMutationGuards({
+    container: input.container, req: input.req,
+    auth: { tenantId: input.auth.tenantId, organizationId: input.auth.orgId ?? null, userId: input.auth.sub },
+    input: {
+      resourceKind: 'attachments:attachment', resourceId: input.recordId,
+      operation: input.operation, mutationPayload: input.payload,
+    },
+  })
+  if (!guard.ok) throw new CrudHttpError(guard.errorStatus, guard.errorBody)
+  return guard
+}