@open-mercato/core 0.10.1-develop.7741.1.61a2652671 → 0.10.1-develop.7749.1.ea3edf75e3

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
+}

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

@@ -0,0 +1,83 @@
+import { LockMode } from '@mikro-orm/core'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { findOneWithDecryption, findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { AttachmentPartition } from '../data/entities'
+import { attachmentAccessRequirementsSchema } from '../data/validators'
+import { getAttachmentAccessRegistry, matchesAttachmentAccessSelector } from './access-registry'
+import type { AttachmentAccessRequirement } from './access-types'
+
+export function getDeclaredAttachmentAccessRequirements(partitionCode: string): AttachmentAccessRequirement[] {
+  const registry = getAttachmentAccessRegistry()
+  if (registry.invalid) throw new Error('[internal] Attachment access registry is invalid')
+  return registry.protectedTargets
+    .filter((target) => matchesAttachmentAccessSelector(target.targetPartition, partitionCode))
+    .map(({ resolverId, targetEntity }) => ({ resolverId, targetEntity }))
+}
+
+export function mergeAttachmentAccessRequirements(
+  current: unknown,
+  required: readonly AttachmentAccessRequirement[],
+): AttachmentAccessRequirement[] {
+  const existing = attachmentAccessRequirementsSchema.parse(current ?? [])
+  const union = new Map<string, AttachmentAccessRequirement>()
+  for (const requirement of [...existing, ...required]) {
+    union.set(JSON.stringify([requirement.resolverId, requirement.targetEntity]), { ...requirement })
+  }
+  return [...union.values()]
+}
+
+export async function syncAttachmentAccessProtection(
+  em: EntityManager,
+  options: { partitionCode?: string } = {},
+): Promise<number> {
+  const registry = getAttachmentAccessRegistry()
+  if (registry.invalid) throw new Error('[internal] Attachment access registry is invalid')
+  if (!registry.protectedTargets.length) return 0
+  const isolated = em.fork({ clear: true, useContext: false })
+  const candidates = await findWithDecryption(
+    isolated,
+    AttachmentPartition,
+    options.partitionCode ? { code: options.partitionCode } : {},
+    { orderBy: { id: 'asc' } },
+    { tenantId: null, organizationId: null },
+  )
+  if (options.partitionCode && getDeclaredAttachmentAccessRequirements(options.partitionCode).length && !candidates.length) {
+    throw new Error('[internal] Protected attachment partition is not durably configured')
+  }
+  const pending = candidates.filter((partition) => {
+    const required = getDeclaredAttachmentAccessRequirements(partition.code)
+    if (!required.length) return false
+    const existing = attachmentAccessRequirementsSchema.parse(partition.accessResolverRequirements ?? [])
+    return JSON.stringify(mergeAttachmentAccessRequirements(existing, required)) !== JSON.stringify(existing)
+  })
+  if (!pending.length) return 0
+  return isolated.transactional(async (transaction) => {
+    let changed = 0
+    for (const candidate of pending) {
+      const partition = await findOneWithDecryption(transaction, AttachmentPartition, { id: candidate.id }, {
+        lockMode: LockMode.PESSIMISTIC_WRITE,
+        refresh: true,
+      }, { tenantId: null, organizationId: null })
+      if (!partition) throw new Error('[internal] Attachment partition disappeared during access protection synchronization')
+      const existing = attachmentAccessRequirementsSchema.parse(partition.accessResolverRequirements ?? [])
+      const merged = mergeAttachmentAccessRequirements(existing, getDeclaredAttachmentAccessRequirements(partition.code))
+      if (JSON.stringify(merged) === JSON.stringify(existing)) continue
+      partition.accessResolverRequirements = merged
+      changed += 1
+    }
+    if (changed) await transaction.flush()
+    return changed
+  })
+}
+
+export async function ensureAttachmentPartitionProtection(
+  em: EntityManager,
+  partition: AttachmentPartition,
+): Promise<void> {
+  const required = getDeclaredAttachmentAccessRequirements(partition.code)
+  if (!required.length) return
+  const existing = attachmentAccessRequirementsSchema.parse(partition.accessResolverRequirements ?? [])
+  const merged = mergeAttachmentAccessRequirements(existing, required)
+  if (JSON.stringify(existing) === JSON.stringify(merged)) return
+  await syncAttachmentAccessProtection(em, { partitionCode: partition.code })
+}

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

@@ -0,0 +1,86 @@
+import { ensureAttachmentPartitionProtection } from './access-protection'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { AuthContext } from '@open-mercato/shared/lib/auth/server'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { AttachmentPartition, type Attachment } from '../data/entities'
+import { attachmentAccessRequirementsSchema } from '../data/validators'
+import { getAttachmentAccessRegistry } from './access-registry'
+import { evaluateAttachmentAccess, type AttachmentAccessContext } from './access-runner'
+import type { AttachmentAccessAction, AttachmentAccessRecord } from './access-types'
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { attachmentAccessErrorBody, throwAttachmentAccessError } from './access-errors'
+import { readAttachmentMetadata } from './metadata'
+
+export function requiresAttachmentAccessScan(partitions: readonly AttachmentPartition[]): boolean {
+  const registry = getAttachmentAccessRegistry()
+  return registry.invalid || registry.resolvers.length > 0 || registry.protectedTargets.length > 0
+    || partitions.some((partition) => {
+      const parsed = attachmentAccessRequirementsSchema.safeParse(partition.accessResolverRequirements ?? [])
+      return !parsed.success || parsed.data.length > 0
+    })
+}
+
+export async function assertAttachmentOwnerAccess(input: {
+  em: EntityManager
+  context: AttachmentAccessContext
+  auth: NonNullable<AuthContext>
+  attachment: AttachmentAccessRecord
+  action: AttachmentAccessAction
+  persistProtection?: boolean
+}): Promise<void> {
+  const partition = await findOneWithDecryption(input.em, AttachmentPartition, { code: input.attachment.partitionCode }, undefined, {
+    tenantId: input.attachment.tenantId, organizationId: input.attachment.organizationId,
+  })
+  if (!partition) await throwAttachmentAccessError(404)
+  if (input.persistProtection) await ensureAttachmentPartitionProtection(input.em, partition!)
+  const result = await evaluateAttachmentAccess({ ...input, partition: partition!, requireAuthForPublic: true })
+  if (!result.ok) await throwAttachmentAccessError(result.status)
+}
+
+export async function scanAuthorizedAttachments(input: {
+  auth: NonNullable<AuthContext>
+  context: AttachmentAccessContext
+  partitions: readonly AttachmentPartition[]
+  loadBatch(offset: number, limit: number): Promise<Attachment[]>
+  offset?: number
+  limit?: number
+  collectTags?: boolean
+  deadline?: number
+}): Promise<{ records: Attachment[]; total: number; tags: string[] }> {
+  const deadline = input.deadline ?? Date.now() + 15_000
+  const timeoutBody = await attachmentAccessErrorBody(504)
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const scan = async () => {
+    const partitions = new Map(input.partitions.map((partition) => [partition.code, partition]))
+    const records: Attachment[] = []
+    const tags = new Set<string>()
+    let total = 0
+    for (let batchOffset = 0; ; batchOffset += 100) {
+      if (Date.now() >= deadline) await throwAttachmentAccessError(504)
+      const batch = await input.loadBatch(batchOffset, 100)
+      for (const attachment of batch) {
+        if (Date.now() >= deadline) await throwAttachmentAccessError(504)
+        const partition = partitions.get(attachment.partitionCode)
+        if (!partition) continue
+        const access = await evaluateAttachmentAccess({
+          auth: input.auth, attachment, partition, action: 'metadata', context: input.context,
+          requireAuthForPublic: true,
+        })
+        if (Date.now() >= deadline || (!access.ok && access.status === 504)) await throwAttachmentAccessError(504)
+        if (!access.ok) continue
+        if (input.collectTags) for (const tag of readAttachmentMetadata(attachment.storageMetadata).tags ?? []) tags.add(tag)
+        if (total >= (input.offset ?? 0) && (input.limit === undefined || records.length < input.limit)) records.push(attachment)
+        total += 1
+      }
+      if (batch.length < 100) break
+    }
+    return { records, total, tags: [...tags].sort((left, right) => left < right ? -1 : left > right ? 1 : 0) }
+  }
+  try {
+    return await Promise.race([scan(), new Promise<never>((_resolve, reject) => {
+      timer = setTimeout(() => reject(new CrudHttpError(504, timeoutBody)), Math.max(1, deadline - Date.now()))
+    })])
+  } finally {
+    if (timer) clearTimeout(timer)
+  }
+}