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

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

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

@@ -0,0 +1,117 @@
+import { matchesEntity } from '@open-mercato/shared/lib/crud/mutation-guard-registry'
+import { attachmentAccessResolverSchema, protectedAttachmentTargetSchema } from '../data/validators'
+import type {
+  AttachmentAccessAction,
+  AttachmentAccessRecord,
+  AttachmentAccessResolver,
+  AttachmentAccessResolverEntry,
+  AttachmentAccessTarget,
+  ProtectedAttachmentTarget,
+} from './access-types'
+
+const GLOBAL_KEY = '__openMercatoAttachmentAccessRegistry__'
+
+type RegisteredResolver = AttachmentAccessResolver & {
+  moduleOrder: number
+  declarationOrder: number
+}
+
+type Registry = {
+  invalid: boolean
+  resolvers: readonly RegisteredResolver[]
+  protectedTargets: readonly ProtectedAttachmentTarget[]
+}
+
+const emptyRegistry: Registry = Object.freeze({ invalid: false, resolvers: [], protectedTargets: [] })
+
+export function getAttachmentAccessRegistry(): Registry {
+  return (globalThis as Record<string, unknown>)[GLOBAL_KEY] as Registry | undefined ?? emptyRegistry
+}
+
+export function registerAttachmentAccessResolvers(entries: readonly AttachmentAccessResolverEntry[]): void {
+  const globalState = globalThis as Record<string, unknown>
+  globalState[GLOBAL_KEY] = { invalid: true, resolvers: [], protectedTargets: [] } satisfies Registry
+  const resolvers: RegisteredResolver[] = []
+  const protectedTargets: ProtectedAttachmentTarget[] = []
+  const ids = new Set<string>()
+  for (const [moduleOrder, entry] of entries.entries()) {
+    if (typeof entry.moduleId !== 'string' || !entry.moduleId || !Array.isArray(entry.resolvers)) {
+      throw new Error('[internal] Invalid attachment access registry entry')
+    }
+    for (const [declarationOrder, raw] of entry.resolvers.entries()) {
+      const resolver = attachmentAccessResolverSchema.parse(raw)
+      if (!resolver.id.startsWith(`${entry.moduleId}.`) || ids.has(resolver.id)) {
+        throw new Error('[internal] Attachment access resolver IDs must be unique and owned by their module')
+      }
+      ids.add(resolver.id)
+      resolvers.push(Object.freeze({
+        ...resolver,
+        actions: resolver.actions ? Object.freeze([...resolver.actions]) : undefined,
+        moduleOrder,
+        declarationOrder,
+      }))
+    }
+    for (const raw of entry.protectedTargets ?? []) {
+      const target = protectedAttachmentTargetSchema.parse(raw)
+      if (!target.resolverId.startsWith(`${entry.moduleId}.`)) {
+        throw new Error('[internal] Attachment access requirements must name their module resolver')
+      }
+      protectedTargets.push(Object.freeze(target))
+    }
+  }
+  resolvers.sort((left, right) => (
+    (left.priority ?? 50) - (right.priority ?? 50)
+    || left.moduleOrder - right.moduleOrder
+    || left.declarationOrder - right.declarationOrder
+  ))
+  globalState[GLOBAL_KEY] = Object.freeze({
+    invalid: false,
+    resolvers: Object.freeze(resolvers),
+    protectedTargets: Object.freeze(protectedTargets),
+  }) satisfies Registry
+}
+
+export function matchesAttachmentAccessSelector(selector: string, value: string): boolean {
+  return matchesEntity(selector, value)
+}
+
+export function matchesAttachmentAccessTargets(selector: string, targets: readonly AttachmentAccessTarget[]): boolean {
+  return selector === '*' || targets.some((target) => matchesAttachmentAccessSelector(selector, target.entityId))
+}
+
+export function matchesAttachmentAccessResolver(
+  resolver: AttachmentAccessResolver,
+  partitionCode: string,
+  targets: readonly AttachmentAccessTarget[],
+  action: AttachmentAccessAction,
+): boolean {
+  return matchesAttachmentAccessSelector(resolver.targetPartition, partitionCode)
+    && matchesAttachmentAccessTargets(resolver.targetEntity ?? '*', targets)
+    && (!resolver.actions || resolver.actions.includes(action))
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+export function collectAttachmentAccessTargets(attachment: AttachmentAccessRecord): readonly AttachmentAccessTarget[] {
+  const targets: AttachmentAccessTarget[] = []
+  function append(entityId: unknown, recordId: unknown, origin: AttachmentAccessTarget['origin']) {
+    if (typeof entityId !== 'string' || !entityId.trim()) return
+    const target = Object.freeze({
+      entityId: entityId.trim(),
+      recordId: typeof recordId === 'string' ? recordId.trim() : '',
+      origin,
+    })
+    if (!targets.some((candidate) => candidate.entityId === target.entityId && candidate.recordId === target.recordId)) {
+      targets.push(target)
+    }
+  }
+  append(attachment.entityId, attachment.recordId, 'primary')
+  const assignments = isRecord(attachment.storageMetadata) ? attachment.storageMetadata.assignments : undefined
+  const entries = Array.isArray(assignments) ? assignments : isRecord(assignments) ? [assignments] : []
+  for (const assignment of entries) {
+    if (isRecord(assignment)) append(assignment.type, assignment.id, 'assignment')
+  }
+  return Object.freeze(targets)
+}

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

@@ -0,0 +1,183 @@
+import type { AwilixContainer } from 'awilix'
+import type { AuthContext } from '@open-mercato/shared/lib/auth/server'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { getTelemetryRuntime } from '@open-mercato/shared/lib/telemetry/runtime'
+import type { Attachment, AttachmentPartition } from '../data/entities'
+import { attachmentAccessDecisionSchema, attachmentAccessRequirementsSchema, attachmentAccessSubjectFeaturesSchema } from '../data/validators'
+import { checkAttachmentAccess } from './access'
+import {
+  collectAttachmentAccessTargets,
+  getAttachmentAccessRegistry,
+  matchesAttachmentAccessResolver,
+  matchesAttachmentAccessSelector,
+  matchesAttachmentAccessTargets,
+} from './access-registry'
+import type {
+  AttachmentAccessAction, AttachmentAccessDecision, AttachmentAccessPartition,
+  AttachmentAccessRecord, AttachmentAccessSubject,
+} from './access-types'
+
+const logger = createLogger('attachments').child({ component: 'access' })
+const DEFAULT_TIMEOUT_MS = 1500
+
+type RbacProjectionService = {
+  loadAcl(subject: string, scope: { tenantId: string | null; organizationId: string | null }): Promise<{
+    isSuperAdmin: boolean; organizations: string[] | null
+  }>
+  getEffectiveFeatures(subject: string, scope: { tenantId: string | null; organizationId: string | null }): Promise<string[]>
+}
+
+export type AttachmentAccessContext = {
+  container: AwilixContainer
+  subjects: Map<string, Promise<AttachmentAccessSubject>>
+  resolverCaches: Map<string, Map<string, unknown>>
+}
+
+export function createAttachmentAccessContext(container: AwilixContainer): AttachmentAccessContext {
+  return { container, subjects: new Map(), resolverCaches: new Map() }
+}
+
+export type AttachmentAccessResult = AttachmentAccessDecision & { protected: boolean }
+
+class AccessTimeout extends Error {}
+
+async function withinBudget<Result>(work: () => Promise<Result>, timeoutMs: number, controller: AbortController): Promise<Result> {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  try {
+    return await Promise.race([
+      Promise.resolve().then(work),
+      new Promise<never>((_resolve, reject) => {
+        timer = setTimeout(() => {
+          controller.abort()
+          reject(new AccessTimeout('[internal] Attachment access evaluation timed out'))
+        }, timeoutMs)
+      }),
+    ])
+  } finally {
+    if (timer) clearTimeout(timer)
+  }
+}
+
+async function projectSubject(
+  context: AttachmentAccessContext,
+  auth: NonNullable<AuthContext>,
+  attachment: AttachmentAccessRecord,
+): Promise<AttachmentAccessSubject> {
+  const scope = {
+    tenantId: attachment.tenantId ?? auth.tenantId ?? null,
+    organizationId: attachment.organizationId ?? auth.orgId ?? null,
+  }
+  const key = JSON.stringify([auth.sub, scope.tenantId, scope.organizationId])
+  let pending = context.subjects.get(key)
+  if (!pending) {
+    pending = (async () => {
+      const rbac = context.container.resolve<RbacProjectionService>('rbacService')
+      const acl = await rbac.loadAcl(auth.sub, scope)
+      const userFeatures = attachmentAccessSubjectFeaturesSchema.parse(await rbac.getEffectiveFeatures(auth.sub, scope))
+      if (typeof acl.isSuperAdmin !== 'boolean') {
+        throw new Error('[internal] Invalid attachment subject projection')
+      }
+      if (!acl.isSuperAdmin && acl.organizations && scope.organizationId
+        && !acl.organizations.includes(scope.organizationId) && !acl.organizations.includes('__all__')) {
+        throw new Error('[internal] Attachment subject is outside its current organization grants')
+      }
+      return Object.freeze({
+        auth: Object.freeze({
+          sub: auth.sub, tenantId: scope.tenantId, orgId: scope.organizationId,
+          isApiKey: auth.isApiKey === true, userId: auth.userId, keyId: auth.keyId,
+          isSuperAdmin: acl.isSuperAdmin,
+        }),
+        ...scope,
+        userFeatures: Object.freeze([...userFeatures]),
+        isSuperAdmin: acl.isSuperAdmin,
+      })
+    })()
+    context.subjects.set(key, pending)
+  }
+  return pending
+}
+
+export async function evaluateAttachmentAccess(input: {
+  auth: AuthContext | undefined
+  attachment: AttachmentAccessRecord
+  partition: AttachmentAccessPartition
+  action: AttachmentAccessAction
+  context?: AttachmentAccessContext | null
+  requireAuthForPublic?: boolean
+}): Promise<AttachmentAccessResult> {
+  const { auth, attachment, partition, action, context } = input
+  const baseline = checkAttachmentAccess(auth, attachment as Attachment, partition as AttachmentPartition, { requireAuthForPublic: input.requireAuthForPublic })
+  if (!baseline.ok) return { ok: false, status: baseline.status === 401 ? 401 : 403, reason: 'scope', protected: false }
+  const deny = (status: 401 | 403 | 404 | 504, reason: string, resolverId?: string): AttachmentAccessResult => {
+    logger.info('Attachment owner access denied', { resolverId, action, attachmentId: attachment.id, reason })
+    return { ok: false, status, reason, protected: true }
+  }
+  const registry = getAttachmentAccessRegistry()
+  if (registry.invalid) return deny(403, 'invalid_registry')
+  const parsedRequirements = attachmentAccessRequirementsSchema.safeParse(partition.accessResolverRequirements ?? [])
+  if (!parsedRequirements.success) return deny(403, 'invalid_requirements')
+  const targets = collectAttachmentAccessTargets(attachment)
+  const requirements = [...parsedRequirements.data, ...registry.protectedTargets.filter((target) => (
+    matchesAttachmentAccessSelector(target.targetPartition, partition.code)
+  ))].filter((requirement) => matchesAttachmentAccessTargets(requirement.targetEntity, targets))
+  const resolvers = registry.resolvers.filter((resolver) => matchesAttachmentAccessResolver(resolver, partition.code, targets, action))
+  if (!requirements.length && !resolvers.length) return { ok: true, protected: false }
+  if (!auth) return deny(401, 'authentication_required')
+  for (const requirement of requirements) {
+    const requiredTargets = targets.filter((target) => matchesAttachmentAccessSelector(requirement.targetEntity, target.entityId))
+    const provider = resolvers.find((resolver) => resolver.id === requirement.resolverId)
+    if (!provider || (requiredTargets.length
+      ? requiredTargets.some((target) => !matchesAttachmentAccessSelector(provider.targetEntity ?? '*', target.entityId))
+      : (provider.targetEntity ?? '*') !== '*')) return deny(403, 'required_resolver_missing', requirement.resolverId)
+    if (targets.some((target) => matchesAttachmentAccessSelector(requirement.targetEntity, target.entityId) && !target.recordId)) {
+      return deny(403, 'invalid_owner', requirement.resolverId)
+    }
+  }
+  if (!context) return deny(403, 'policy_context_missing')
+  let subject: AttachmentAccessSubject
+  try {
+    subject = await withinBudget(() => projectSubject(context, auth, attachment), DEFAULT_TIMEOUT_MS, new AbortController())
+  } catch (error) {
+    getTelemetryRuntime()?.reportError(new Error('[internal] Attachment subject projection failed'), {
+      module: 'attachments', code: 'attachments.subject_projection_failed', attributes: { attachmentId: attachment.id, action },
+    })
+    return deny(error instanceof AccessTimeout ? 504 : 403, 'subject_projection_failed')
+  }
+  const liveBaseline = checkAttachmentAccess({ ...auth, roles: [], isSuperAdmin: subject.isSuperAdmin }, attachment as Attachment, partition as AttachmentPartition, { requireAuthForPublic: input.requireAuthForPublic })
+  if (!liveBaseline.ok) return deny(403, 'current_scope')
+  for (const resolver of resolvers) {
+    const controller = new AbortController()
+    let cache = context.resolverCaches.get(resolver.id)
+    if (!cache) {
+      cache = new Map()
+      context.resolverCaches.set(resolver.id, cache)
+    }
+    try {
+      const raw = await withinBudget(() => resolver.resolve(Object.freeze({
+        action, subject,
+        attachment: Object.freeze({
+          id: attachment.id, entityId: attachment.entityId, recordId: attachment.recordId,
+          partitionCode: attachment.partitionCode, tenantId: attachment.tenantId,
+          organizationId: attachment.organizationId, fileName: attachment.fileName, mimeType: attachment.mimeType,
+        }),
+        partition: Object.freeze({
+          code: partition.code, isPublic: partition.isPublic,
+          tenantId: partition.tenantId, organizationId: partition.organizationId,
+        }),
+        targets, container: context.container, cache, signal: controller.signal,
+      })), resolver.timeoutMs ?? DEFAULT_TIMEOUT_MS, controller)
+      const decision = attachmentAccessDecisionSchema.parse(raw)
+      if (!decision.ok) return deny(decision.status, decision.reason, resolver.id)
+    } catch (error) {
+      controller.abort()
+      getTelemetryRuntime()?.reportError(new Error(error instanceof AccessTimeout
+        ? '[internal] Attachment resolver exceeded its time budget'
+        : '[internal] Attachment resolver failed or returned an invalid decision'), {
+        module: 'attachments', code: 'attachments.resolver_failed',
+        attributes: { resolverId: resolver.id, attachmentId: attachment.id, action },
+      })
+      return deny(error instanceof AccessTimeout ? 504 : 403, error instanceof AccessTimeout ? 'resolver_timeout' : 'resolver_failed', resolver.id)
+    }
+  }
+  return { ok: true, protected: true }
+}

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

@@ -0,0 +1,78 @@
+import type { AwilixContainer } from 'awilix'
+import type { AuthContext } from '@open-mercato/shared/lib/auth/server'
+
+export type AttachmentAccessAction = 'read' | 'render' | 'metadata' | 'reassign' | 'delete' | 'export'
+
+export type AttachmentAccessTarget = Readonly<{
+  entityId: string
+  recordId: string
+  origin: 'primary' | 'assignment'
+}>
+
+export type AttachmentAccessRequirement = Readonly<{
+  resolverId: string
+  targetEntity: string
+}>
+
+export type ProtectedAttachmentTarget = AttachmentAccessRequirement & Readonly<{
+  targetPartition: string
+}>
+
+export type AttachmentAccessRecord = {
+  id: string
+  entityId: string
+  recordId: string
+  partitionCode: string
+  tenantId?: string | null
+  organizationId?: string | null
+  fileName: string
+  mimeType: string
+  storageMetadata?: unknown
+}
+
+export type AttachmentAccessPartition = {
+  code: string
+  isPublic: boolean
+  tenantId?: string | null
+  organizationId?: string | null
+  accessResolverRequirements?: unknown
+}
+
+export type AttachmentAccessSubject = Readonly<{
+  auth: Readonly<NonNullable<AuthContext>>
+  userFeatures: readonly string[]
+  tenantId: string | null
+  organizationId: string | null
+  isSuperAdmin: boolean
+}>
+
+export type AttachmentAccessInput = Readonly<{
+  action: AttachmentAccessAction
+  subject: AttachmentAccessSubject
+  attachment: Readonly<Omit<AttachmentAccessRecord, 'storageMetadata'>>
+  partition: Readonly<Omit<AttachmentAccessPartition, 'accessResolverRequirements'>>
+  targets: readonly AttachmentAccessTarget[]
+  container: AwilixContainer
+  cache: Map<string, unknown>
+  signal: AbortSignal
+}>
+
+export type AttachmentAccessDecision =
+  | { ok: true }
+  | { ok: false; status: 401 | 403 | 404 | 504; reason: string }
+
+export type AttachmentAccessResolver = Readonly<{
+  id: string
+  targetPartition: string
+  targetEntity?: string
+  actions?: readonly AttachmentAccessAction[]
+  priority?: number
+  timeoutMs?: number
+  resolve(input: AttachmentAccessInput): Promise<AttachmentAccessDecision>
+}>
+
+export type AttachmentAccessResolverEntry = {
+  moduleId: string
+  resolvers: readonly unknown[]
+  protectedTargets?: readonly unknown[]
+}

package/src/modules/attachments/lib/attachment-service.ts

@@ -1,3 +1,5 @@
+import { evaluateAttachmentAccess, type AttachmentAccessContext } from './access-runner'
+import { throwAttachmentAccessError } from './access-errors'
 import type { EntityManager } from '@mikro-orm/postgresql'
 import type { AuthContext } from '@open-mercato/shared/lib/auth/server'
 import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
@@ -249,6 +251,7 @@ export class DefaultAttachmentService implements AttachmentService {
     private readonly em: EntityManager,
     private readonly storageDriverFactory: StorageDriverFactory,
     private readonly resolveScopedUploadService?: (() => ScopedAttachmentUploadService | null) | null,
+    private readonly resolveAccessContext?: (() => AttachmentAccessContext) | null,
   ) {}
 
   validateUpload(input: {
@@ -368,10 +371,11 @@ export class DefaultAttachmentService implements AttachmentService {
     )
     if (!partition) throw new CrudHttpError(500, { error: 'Attachment partition is not configured' })
 
-    const access = checkAttachmentAccess(input.auth, attachment, partition, { requireAuthForPublic: true })
-    if (!access.ok) {
-      throw new CrudHttpError(access.status, { error: access.status === 401 ? 'Unauthorized' : 'Forbidden' })
-    }
+    const access = await evaluateAttachmentAccess({
+      auth: input.auth, attachment, partition, action: 'read',
+      context: this.resolveAccessContext?.(), requireAuthForPublic: true,
+    })
+    if (!access.ok) await throwAttachmentAccessError(access.status)
     if (!partitionMatchesScope(partition, input.auth.tenantId, input.auth.orgId)) {
       throw new CrudHttpError(403, { error: 'Attachment partition is not accessible for this scope' })
     }

package/src/modules/attachments/lib/createFromBuffer.ts

@@ -8,6 +8,7 @@ import { buildAttachmentFileUrl } from './imageUrls'
 import { mergeAttachmentMetadata, upsertAssignment } from './metadata'
 import { assertAttachmentScopeInvariant } from './access'
 import { attachmentCrudEvents, attachmentCrudIndexer } from './crud'
+import { ensureAttachmentPartitionProtection } from './access-protection'
 
 /** DataEngine handle whose exact type is derived from `emitCrudSideEffects` (no `any`). */
 type CrudDataEngine = Parameters<typeof emitCrudSideEffects>[0]['dataEngine']
@@ -58,6 +59,8 @@ export async function createAttachmentFromBuffer(input: CreateAttachmentFromBuff
   }
   if (!partition) throw new Error(`[internal] attachment partition "${code}" is not available`)
 
+  await ensureAttachmentPartitionProtection(em, partition)
+
   const driver = await new StorageDriverFactory(em).resolveForPartition(partition.code, {
     tenantId: input.tenantId,
     organizationId: input.organizationId,

package/src/modules/attachments/lib/partitions.ts

@@ -3,6 +3,7 @@ import { AttachmentPartition } from '../data/entities'
 import { resolveDefaultAttachmentOcrEnabled } from './ocrConfig'
 import { parseBooleanToken } from '@open-mercato/shared/lib/boolean'
 import { E } from '#generated/entities.ids.generated'
+import { getDeclaredAttachmentAccessRequirements } from './access-protection'
 
 export type AttachmentPartitionSeed = {
   code: string
@@ -43,7 +44,6 @@ export async function ensureDefaultPartitions(em: EntityManager): Promise<void>
   const existing = await repo.findAll({ fields: ['code'] })
   const existingCodes = new Set(existing.map((entry) => entry.code))
   const pending = DEFAULT_ATTACHMENT_PARTITIONS.filter((seed) => !existingCodes.has(seed.code))
-  if (!pending.length) return
   for (const seed of pending) {
     const record = repo.create({
       code: seed.code,
@@ -51,11 +51,12 @@ export async function ensureDefaultPartitions(em: EntityManager): Promise<void>
       description: seed.description ?? null,
       storageDriver: 'local',
       isPublic: seed.isPublic ?? false,
+      accessResolverRequirements: getDeclaredAttachmentAccessRequirements(seed.code),
       requiresOcr: resolveDefaultAttachmentOcrEnabled(),
     })
     em.persist(record)
   }
-  await em.flush()
+  if (pending.length) await em.flush()
 }
 
 export function sanitizePartitionCode(input: string): string {

package/src/modules/attachments/lib/scoped-upload-service.ts

@@ -8,6 +8,7 @@ import { Attachment, AttachmentPartition } from '../data/entities'
 import { attachmentCrudEvents, attachmentCrudIndexer } from './crud'
 import type { StorageDriverFactory } from './drivers'
 import { buildAttachmentFileUrl } from './imageUrls'
+import { ensureAttachmentPartitionProtection } from './access-protection'
 import { ensureDefaultPartitions, resolveDefaultPartitionCode } from './partitions'
 import { extractAttachmentContent } from './textExtraction'
 import { requestOcrProcessing } from './ocrQueue'
@@ -142,6 +143,7 @@ export class ScopedAttachmentUploadService {
       throw new ScopedAttachmentUploadError('partition_unavailable', 403)
     }
 
+    await ensureAttachmentPartitionProtection(em, partition)
     const driver = await storageDriverFactory.resolveForPartition(partition.code, {
       tenantId: input.tenantId,
       organizationId: input.organizationId,