@open-mercato/core 0.10.1-develop.7717.1.2befe9c634 → 0.10.1-develop.7721.1.b5c4a00a68

package/src/modules/staff/lib/support-ui/portalAttachmentValidation.ts

@@ -0,0 +1,125 @@
+import type { TranslateFn } from '@open-mercato/shared/lib/i18n/context'
+
+export const DEFAULT_ATTACHMENT_MAX_UPLOAD_BYTES = 25 * 1024 * 1024
+
+export const ATTACHMENT_ACCEPT_TYPES = [
+  '.avif',
+  '.bmp',
+  '.csv',
+  '.docx',
+  '.gif',
+  '.jpeg',
+  '.jpg',
+  '.json',
+  '.md',
+  '.pdf',
+  '.png',
+  '.pptx',
+  '.txt',
+  '.webp',
+  '.xlsx',
+  '.zip',
+  'application/json',
+  'application/pdf',
+  'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  'application/zip',
+  'image/avif',
+  'image/bmp',
+  'image/gif',
+  'image/jpeg',
+  'image/png',
+  'image/webp',
+  'text/csv',
+  'text/markdown',
+  'text/plain',
+].join(',')
+
+const BLOCKED_ATTACHMENT_MIME_TYPES = new Set([
+  'application/xhtml+xml',
+  'application/xml',
+  'image/svg+xml',
+  'text/html',
+  'text/xml',
+])
+
+const ACTIVE_CONTENT_ATTACHMENT_EXTENSIONS = new Set([
+  'htm',
+  'html',
+  'svg',
+  'xhtml',
+  'xml',
+])
+
+const DANGEROUS_EXECUTABLE_EXTENSIONS = new Set([
+  'app',
+  'apk',
+  'bat',
+  'cmd',
+  'com',
+  'dll',
+  'exe',
+  'hta',
+  'htm',
+  'html',
+  'jar',
+  'js',
+  'jse',
+  'lnk',
+  'msi',
+  'pif',
+  'ps1',
+  'psm1',
+  'reg',
+  'scr',
+  'sh',
+  'vbe',
+  'vbs',
+  'wsf',
+  'wsh',
+])
+
+function getFileExtensionSegments(fileName: string): string[] {
+  const parts = fileName.trim().split('.').filter(Boolean)
+  if (parts.length < 2) return []
+  return parts.slice(1).map((part) => part.toLowerCase().replace(/[^a-z0-9]/g, '')).filter(Boolean)
+}
+
+async function fileLooksLikeActiveContent(file: File): Promise<boolean> {
+  try {
+    const sniff = (await file.slice(0, 512).text()).trimStart().toLowerCase()
+    return sniff.startsWith('<svg') || sniff.startsWith('<?xml') || sniff.startsWith('<!doctype html') || sniff.startsWith('<html')
+  } catch {
+    return false
+  }
+}
+
+export function resolvePortalMaxUploadBytes(serverMaxBytes: number | null | undefined): number {
+  return typeof serverMaxBytes === 'number' && Number.isFinite(serverMaxBytes) && serverMaxBytes > 0
+    ? serverMaxBytes
+    : DEFAULT_ATTACHMENT_MAX_UPLOAD_BYTES
+}
+
+export async function validateAttachmentFile(
+  file: File,
+  t: TranslateFn,
+  maxBytes: number = DEFAULT_ATTACHMENT_MAX_UPLOAD_BYTES,
+): Promise<string | null> {
+  if (file.size > maxBytes) {
+    return t('attachments.errors.maxUploadSize')
+  }
+  const extensionSegments = getFileExtensionSegments(file.name)
+  const mimeType = file.type.trim().toLowerCase()
+  if (extensionSegments.some((extension) => DANGEROUS_EXECUTABLE_EXTENSIONS.has(extension))) {
+    return t('attachments.errors.dangerousExecutable')
+  }
+  if (
+    extensionSegments.some((extension) => ACTIVE_CONTENT_ATTACHMENT_EXTENSIONS.has(extension)) ||
+    (mimeType && BLOCKED_ATTACHMENT_MIME_TYPES.has(mimeType)) ||
+    await fileLooksLikeActiveContent(file)
+  ) {
+    return t('attachments.errors.activeContentBlocked')
+  }
+  return null
+}

package/src/modules/staff/lib/support-ui/portalPendingUploads.ts

@@ -0,0 +1,49 @@
+import { failedUploadsStorageKey } from './portalSupport'
+
+/**
+ * Files that failed to upload while filing a ticket. The names survive a reload in
+ * `sessionStorage`; the `File` objects themselves can only live in memory, so a retry
+ * is possible for files picked in this browser session and a re-attach otherwise.
+ */
+const retryableFilesByTicket = new Map<string, Map<string, File>>()
+
+export function rememberFailedUploads(ticketId: string, files: readonly File[]): void {
+  if (!files.length) return
+  const current = retryableFilesByTicket.get(ticketId) ?? new Map<string, File>()
+  for (const file of files) current.set(file.name, file)
+  retryableFilesByTicket.set(ticketId, current)
+  writeFailedUploadNames(ticketId, [...new Set([...readFailedUploadNames(ticketId), ...files.map((file) => file.name)])])
+}
+
+export function getRetryableUpload(ticketId: string, fileName: string): File | null {
+  return retryableFilesByTicket.get(ticketId)?.get(fileName) ?? null
+}
+
+export function forgetFailedUpload(ticketId: string, fileName: string): string[] {
+  const files = retryableFilesByTicket.get(ticketId)
+  files?.delete(fileName)
+  if (files && files.size === 0) retryableFilesByTicket.delete(ticketId)
+  const remaining = readFailedUploadNames(ticketId).filter((name) => name !== fileName)
+  writeFailedUploadNames(ticketId, remaining)
+  return remaining
+}
+
+export function readFailedUploadNames(ticketId: string): string[] {
+  try {
+    const raw = window.sessionStorage.getItem(failedUploadsStorageKey(ticketId))
+    if (!raw) return []
+    const parsed: unknown = JSON.parse(raw)
+    return Array.isArray(parsed) ? parsed.filter((entry): entry is string => typeof entry === 'string') : []
+  } catch {
+    return []
+  }
+}
+
+function writeFailedUploadNames(ticketId: string, names: readonly string[]): void {
+  try {
+    if (names.length) window.sessionStorage.setItem(failedUploadsStorageKey(ticketId), JSON.stringify(names))
+    else window.sessionStorage.removeItem(failedUploadsStorageKey(ticketId))
+  } catch {
+    return
+  }
+}

package/src/modules/staff/lib/support-ui/portalSupport.ts

@@ -0,0 +1,116 @@
+import type { StatusBadgeVariant } from '@open-mercato/ui/primitives/status-badge'
+import type { TranslateFn } from '@open-mercato/shared/lib/i18n/context'
+
+export type PortalSupportStatus = 'received' | 'in_progress' | 'resolved'
+
+export type PortalSupportTicketListItem = {
+  id: string
+  supportReference: string
+  subject: string
+  category: { value: string; label: string }
+  portalStatus: PortalSupportStatus
+  createdAt: string | null
+  updatedAt: string | null
+  lastActivityAt: string | null
+}
+
+export type PortalSupportTicketList = {
+  items?: PortalSupportTicketListItem[]
+  total?: number
+  page?: number
+  pageSize?: number
+  totalPages?: number
+}
+
+export type PortalSupportOptions = {
+  categories?: Array<{ value: string; label: string }>
+  canCreate?: boolean
+  maxUploadBytes?: number | null
+}
+
+export type PortalSupportMessage = {
+  id: string
+  authorKind: 'staff' | 'customer'
+  authorName: string | null
+  isSelf?: boolean
+  body: string
+  createdAt: string | null
+}
+
+export type PortalSupportTicketDetail = {
+  id: string
+  supportReference: string
+  subject: string
+  description: string
+  category: { value: string; label: string }
+  portalStatus: PortalSupportStatus
+  createdAt: string | null
+  updatedAt: string | null
+  canReply: boolean
+  requester?: { name: string | null; isSelf: boolean }
+  messages: PortalSupportMessage[]
+  attachments?: PortalSupportAttachment[]
+}
+
+export type PortalSupportAttachment = {
+  id: string
+  fileName: string
+  fileSize: number
+  mimeType: string | null
+  downloadUrl: string
+  uploadedByCustomer: boolean
+  canDelete: boolean
+  createdAt: string | null
+}
+
+export const PORTAL_SUPPORT_UPDATED_EVENT = 'staff.support_ticket.portal_updated'
+
+export const PORTAL_SUPPORT_NOT_LINKED_CODE = 'customer_account_not_linked'
+
+/**
+ * A portal account without a company link can never see or file tickets, so the
+ * support screens explain that instead of offering a retry that cannot succeed.
+ */
+export function isPortalSupportAccountNotLinked(call: { status: number; result?: unknown }): boolean {
+  if (call.status !== 403 || !call.result || typeof call.result !== 'object') return false
+  return (call.result as { code?: unknown }).code === PORTAL_SUPPORT_NOT_LINKED_CODE
+}
+
+export const PORTAL_SUPPORT_STATUS_VARIANTS: Record<PortalSupportStatus, StatusBadgeVariant> = {
+  received: 'info',
+  in_progress: 'warning',
+  resolved: 'success',
+}
+
+export function portalSupportStatusLabel(t: TranslateFn, status: PortalSupportStatus): string {
+  if (status === 'resolved') return t('staff.portal.support.status.resolved', 'Resolved')
+  if (status === 'in_progress') return t('staff.portal.support.status.inProgress', 'In progress')
+  return t('staff.portal.support.status.received', 'Received')
+}
+
+export function formatPortalDate(value: string | null | undefined, locale?: string): string {
+  if (!value) return ''
+  const date = new Date(value)
+  if (Number.isNaN(date.getTime())) return ''
+  return date.toLocaleString(locale, { dateStyle: 'medium', timeStyle: 'short' })
+}
+
+export function formatFileSize(t: TranslateFn, bytes: number): string {
+  if (!Number.isFinite(bytes) || bytes <= 0) return t('staff.portal.support.fileSize.bytes', '{size} B', { size: 0 })
+  if (bytes < 1024) return t('staff.portal.support.fileSize.bytes', '{size} B', { size: bytes })
+  if (bytes < 1024 * 1024) {
+    return t('staff.portal.support.fileSize.kilobytes', '{size} KB', { size: (bytes / 1024).toFixed(1) })
+  }
+  return t('staff.portal.support.fileSize.megabytes', '{size} MB', { size: (bytes / (1024 * 1024)).toFixed(1) })
+}
+
+export function failedUploadsStorageKey(ticketId: string): string {
+  return `om:staff:support:failed-uploads:${ticketId}`
+}
+
+export function readPortalTicketIdFromEvent(event: { payload?: Record<string, unknown> } | null | undefined): string | null {
+  const payload = event?.payload
+  if (!payload || typeof payload !== 'object') return null
+  const candidate = payload.ticketId ?? payload.id
+  return typeof candidate === 'string' ? candidate : null
+}

package/src/modules/staff/lib/time-tracking/access.ts

@@ -2,7 +2,7 @@ import type { EntityManager } from '@mikro-orm/postgresql'
 import { authorizeFeatures } from '@open-mercato/shared/security/featurePolicy'
 import { findWithDecryption, findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
 import { StaffTeamMember, StaffTimeProjectMember } from '../../data/entities'
-import { DEFAULT_ASSIGNMENT_GRACE_DAYS, MAX_ASSIGNMENT_GRACE_DAYS } from './settings'
+import { isWithinAssignmentWindow, normalizeAssignmentGraceDays, toDayIndex, toEntryDayIndex } from './projectAssignment'
 
 export const MANAGE_PROJECTS_FEATURE = 'staff.timesheets.projects.manage'
 
@@ -47,67 +47,7 @@ export type ProjectAccess = {
 
 const DENIED: ProjectAccess = { canManageAll: false, projectIds: [], staffMemberId: null }
 
-const MS_PER_DAY = 86_400_000
-const ISO_DATE_PREFIX = /^(\d{4})-(\d{2})-(\d{2})/
-
-export function normalizeAssignmentGraceDays(value: unknown): number {
-  if (typeof value !== 'number' || !Number.isInteger(value)) return DEFAULT_ASSIGNMENT_GRACE_DAYS
-  if (value < 0 || value > MAX_ASSIGNMENT_GRACE_DAYS) return DEFAULT_ASSIGNMENT_GRACE_DAYS
-  return value
-}
-
-/**
- * `assigned_start_date` / `assigned_end_date` are `date` columns, so both bounds
- * are compared as whole days rather than timestamps. Date instances are read
- * through their local calendar fields because the postgres driver materialises a
- * `date` as local midnight, and "today" likewise means the server's local day.
- */
-function toDayIndex(value: unknown): number | null {
-  if (value == null) return null
-  if (value instanceof Date) {
-    if (Number.isNaN(value.getTime())) return null
-    return Date.UTC(value.getFullYear(), value.getMonth(), value.getDate()) / MS_PER_DAY
-  }
-  if (typeof value === 'string') {
-    const match = ISO_DATE_PREFIX.exec(value.trim())
-    if (!match) return null
-    return Date.UTC(Number(match[1]), Number(match[2]) - 1, Number(match[3])) / MS_PER_DAY
-  }
-  return null
-}
-
-/**
- * An entry date is a calendar day the client sent as `YYYY-MM-DD`, which
- * `z.coerce.date()` turns into UTC midnight — so a Date is read through its UTC
- * fields here, the same way the grid addresses a cell (D-8).
- */
-function toEntryDayIndex(value: unknown): number | null {
-  if (value instanceof Date) {
-    if (Number.isNaN(value.getTime())) return null
-    return Date.UTC(value.getUTCFullYear(), value.getUTCMonth(), value.getUTCDate()) / MS_PER_DAY
-  }
-  return toDayIndex(value)
-}
-
-/**
- * A membership only grants access inside its assignment window: from
- * `assigned_start_date` until `assigned_end_date` plus the tenant's grace days.
- * A null end date is open-ended and never expires.
- */
-export function isWithinAssignmentWindow(
-  membership: Pick<StaffTimeProjectMember, 'assignedStartDate' | 'assignedEndDate'>,
-  todayIndex: number,
-  graceDays: number,
-): boolean {
-  if (membership.assignedStartDate != null) {
-    const startIndex = toDayIndex(membership.assignedStartDate)
-    if (startIndex === null || todayIndex < startIndex) return false
-  }
-  if (membership.assignedEndDate == null) return true
-  const endIndex = toDayIndex(membership.assignedEndDate)
-  if (endIndex === null) return false
-  return todayIndex <= endIndex + graceDays
-}
+export { isWithinAssignmentWindow, normalizeAssignmentGraceDays, toDayIndex }
 
 export async function resolveProjectAccess(ctx: ProjectAccessContext): Promise<ProjectAccess> {
   const tenantId = ctx.tenantId ?? null

package/src/modules/staff/lib/time-tracking/listProjectAccess.ts

@@ -0,0 +1,78 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { CrudCtx } from '@open-mercato/shared/lib/crud/factory'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { getTelemetryRuntime } from '@open-mercato/shared/lib/telemetry/runtime'
+import type { ModuleConfigService } from '@open-mercato/core/modules/configs/lib/module-config-service'
+import { resolveFeatureAccess } from './featureAccess'
+import { MANAGE_PROJECTS_FEATURE, resolveProjectAccess, type ProjectAccess } from './access'
+import { readTimeTrackingSettings } from './settings'
+
+const logger = createLogger('staff').child({ component: 'lib/time-tracking/listProjectAccess' })
+
+const DENIED_ACCESS: ProjectAccess = { canManageAll: false, projectIds: [], staffMemberId: null }
+
+type ContainerLike = { resolve: (name: string) => unknown }
+
+type ListAccessCtx = Pick<CrudCtx, 'container' | 'auth' | 'selectedOrganizationId' | 'request'>
+
+/** One access decision per request, shared by every filter that needs it. */
+const accessByRequest = new WeakMap<Request, Promise<ProjectAccess>>()
+
+async function resolveAssignmentGraceDays(container: ContainerLike, tenantId: string): Promise<number | null> {
+  try {
+    const configService = container.resolve('moduleConfigService') as ModuleConfigService
+    const settings = await readTimeTrackingSettings(configService, { tenantId })
+    return settings.access.assignmentGraceDays
+  } catch {
+    // Fail safe to the documented default rather than widening the window.
+    return null
+  }
+}
+
+async function loadProjectAccess(
+  container: ContainerLike,
+  userId: string | null,
+  tenantId: string | null,
+  organizationId: string | null,
+): Promise<ProjectAccess> {
+  if (!tenantId || !organizationId) return { ...DENIED_ACCESS }
+  const scope = { tenantId, organizationId }
+  try {
+    // One lookup, one authority, and a failure that says so. The previous
+    // `catch → []` could not tell "denied" from "could not ask", so an RBAC
+    // hiccup silently demoted a manager to their own memberships.
+    const access = await resolveFeatureAccess(container, userId, [MANAGE_PROJECTS_FEATURE], scope)
+    const em = container.resolve('em') as EntityManager
+    return await resolveProjectAccess({
+      em: em.fork(),
+      userId,
+      tenantId,
+      organizationId,
+      canManageAll: access.allowed,
+      userFeatures: access.grantedFeatures,
+      assignmentGraceDays: await resolveAssignmentGraceDays(container, tenantId),
+    })
+  } catch (err) {
+    logger.error('staff.timesheets.tasks access resolution failed', { err })
+    getTelemetryRuntime()?.reportError(err, { module: 'staff', code: 'staff.task_access_resolution_failed' })
+    return { ...DENIED_ACCESS }
+  }
+}
+
+/**
+ * The project-access decision of the tasks list, memoised per request and failing
+ * closed. Shared by the tasks list route and the task action routes (status move,
+ * claim, release) so a task is only ever reachable through one access rule.
+ */
+export async function resolveListProjectAccess(ctx: ListAccessCtx): Promise<ProjectAccess> {
+  const tenantId = ctx.auth?.tenantId ?? null
+  const organizationId = ctx.selectedOrganizationId ?? ctx.auth?.orgId ?? null
+  const load = () => loadProjectAccess(ctx.container, ctx.auth?.sub ?? null, tenantId, organizationId)
+  const request = ctx.request
+  if (!request) return load()
+  const cached = accessByRequest.get(request)
+  if (cached) return cached
+  const pending = load()
+  accessByRequest.set(request, pending)
+  return pending
+}

package/src/modules/staff/lib/time-tracking/portalRecipients.ts

@@ -1,5 +1,8 @@
 import type { EntityManager } from '@mikro-orm/postgresql'
+import { TableNotFoundException } from '@mikro-orm/core'
 import { createLogger } from '@open-mercato/shared/lib/logger'
+import { getTelemetryRuntime } from '@open-mercato/shared/lib/telemetry/runtime'
+import { authorizeFeatures } from '@open-mercato/shared/security/featurePolicy'
 
 const logger = createLogger('staff').child({ component: 'time-tracking/portal-recipients' })
 
@@ -8,12 +11,20 @@ const logger = createLogger('staff').child({ component: 'time-tracking/portal-re
  * column **names** rather than imports.
  *
  * Staff is slated for extraction into `@open-mercato/staff`, so it may not take a
- * static dependency on `customer_accounts`; `requires` in `index.ts` stays
- * `['planner', 'resources']`. A Kysely query against the string
+ * static dependency on `customer_accounts`; `requires` in `index.ts` never gains it.
+ * A Kysely query against the string
  * `'customer_users'` reads the mapping without an import edge, exactly the way
  * `warranty_claims/commands/claims.ts` does — and if the table is absent because
- * the module is not installed, the query throws and this returns an empty list,
- * which every caller treats as "no portal audience".
+ * the module is not installed, the query throws "relation does not exist" and the
+ * audience is empty, which every caller treats as "no portal audience".
+ *
+ * Each helper comes in two flavours. The `...Strict` variant returns `[]` only for
+ * an expected empty audience (no rows, or the `customer_accounts` tables absent)
+ * and rethrows any other query failure, so a caller that records "the portal was
+ * told" can retry instead of recording a delivery that never happened. The lenient
+ * variant keeps the historical swallow-and-return-`[]` contract and reports the
+ * unexpected failure to telemetry. Both fail closed: neither ever returns an
+ * unfiltered audience.
  *
  * `customer_users.customer_entity_id` is the FK into `customers:customer_entity`,
  * which is the same id `staff_time_reports.customer_id` holds (EP-44 declares that
@@ -42,11 +53,30 @@ export type PortalRecipientScope = {
 /** A broadcast fan-out, not a mailing list — a customer with more portal users than this gets a truncated audience rather than an unbounded query. */
 export const MAX_PORTAL_RECIPIENTS = 100
 
+const UNDEFINED_TABLE_SQLSTATE = '42P01'
+
 function isNonEmpty(value: unknown): value is string {
   return typeof value === 'string' && value.trim().length > 0
 }
 
-export async function resolvePortalRecipientUserIds(
+/** The `customer_accounts` tables are not installed: an expected "no portal audience", not a failure. */
+export function isPortalTableMissingError(error: unknown): boolean {
+  let current: unknown = error
+  for (let depth = 0; depth < 4 && typeof current === 'object' && current !== null; depth += 1) {
+    if (current instanceof TableNotFoundException) return true
+    const candidate = current as { code?: unknown; cause?: unknown }
+    if (candidate.code === UNDEFINED_TABLE_SQLSTATE) return true
+    current = candidate.cause
+  }
+  return false
+}
+
+function reportSwallowedRecipientError(err: unknown, code: string): void {
+  if (isPortalTableMissingError(err)) return
+  getTelemetryRuntime()?.reportError(err, { module: 'staff', code })
+}
+
+export async function resolvePortalRecipientUserIdsStrict(
   em: EntityManager,
   scope: PortalRecipientScope,
 ): Promise<string[]> {
@@ -66,11 +96,149 @@ export async function resolvePortalRecipientUserIds(
       .limit(MAX_PORTAL_RECIPIENTS)
       .execute()
     return rows.map((row) => row.id).filter(isNonEmpty)
+  } catch (err) {
+    if (isPortalTableMissingError(err)) return []
+    throw err
+  }
+}
+
+export async function resolvePortalRecipientUserIds(
+  em: EntityManager,
+  scope: PortalRecipientScope,
+): Promise<string[]> {
+  try {
+    return await resolvePortalRecipientUserIdsStrict(em, scope)
   } catch (err) {
     logger.warn('Could not resolve portal recipients for a time-tracking customer', {
       customerId: scope.customerId,
       err,
     })
+    reportSwallowedRecipientError(err, 'staff.portal_recipients_resolve_failed')
+    return []
+  }
+}
+
+type CustomerAclDb = {
+  customer_user_acls: {
+    user_id: string
+    tenant_id: string
+    features_json: unknown
+    is_portal_admin: boolean
+  }
+  customer_user_roles: {
+    user_id: string
+    role_id: string
+    deleted_at: Date | null
+  }
+  customer_roles: {
+    id: string
+    tenant_id: string
+    organization_id: string
+    deleted_at: Date | null
+  }
+  customer_role_acls: {
+    role_id: string
+    tenant_id: string
+    features_json: unknown
+    is_portal_admin: boolean
+  }
+}
+
+type PortalAclGrant = { features: string[]; isPortalAdmin: boolean }
+
+function readFeatureList(value: unknown): string[] {
+  let parsed: unknown = value
+  if (typeof value === 'string') {
+    try {
+      parsed = JSON.parse(value)
+    } catch {
+      return []
+    }
+  }
+  return Array.isArray(parsed) ? parsed.filter(isNonEmpty) : []
+}
+
+function mergeGrant(grants: Map<string, PortalAclGrant>, userId: string, featuresJson: unknown, isPortalAdmin: boolean): void {
+  const grant = grants.get(userId) ?? { features: [], isPortalAdmin: false }
+  grant.isPortalAdmin = grant.isPortalAdmin || isPortalAdmin === true
+  for (const feature of readFeatureList(featuresJson)) {
+    if (!grant.features.includes(feature)) grant.features.push(feature)
+  }
+  grants.set(userId, grant)
+}
+
+/**
+ * Narrows a portal audience to the customer users holding `requiredFeature`, resolved the
+ * way `customer_accounts`' `CustomerRbacService.loadAcl` does: a per-user ACL row replaces
+ * the user's role ACLs, a portal admin is unrestricted, and grants match wildcard-aware via
+ * `authorizeFeatures`. Read by table name for the same decoupling reason as above. The
+ * strict variant returns `[]` when the module is absent and rethrows any other failure;
+ * neither variant ever returns an unfiltered audience.
+ */
+export async function filterPortalRecipientsByFeatureStrict(
+  em: EntityManager,
+  userIds: string[],
+  scope: { tenantId: string; organizationId: string },
+  requiredFeature: string,
+): Promise<string[]> {
+  const candidates = Array.from(new Set(userIds.filter(isNonEmpty)))
+  if (candidates.length === 0 || !isNonEmpty(scope.tenantId) || !isNonEmpty(scope.organizationId)) return []
+  try {
+    const db = em.getKysely<CustomerAclDb>()
+    const userAclRows = await db
+      .selectFrom('customer_user_acls')
+      .select(['user_id', 'features_json', 'is_portal_admin'])
+      .where('tenant_id', '=', scope.tenantId)
+      .where('user_id', 'in', candidates)
+      .execute()
+    const userGrants = new Map<string, PortalAclGrant>()
+    for (const row of userAclRows) mergeGrant(userGrants, row.user_id, row.features_json, row.is_portal_admin)
+    const roleCandidates = candidates.filter((userId) => !userGrants.has(userId))
+    const roleGrants = new Map<string, PortalAclGrant>()
+    if (roleCandidates.length > 0) {
+      const roleAclRows = await db
+        .selectFrom('customer_user_roles')
+        .innerJoin('customer_roles', 'customer_roles.id', 'customer_user_roles.role_id')
+        .innerJoin('customer_role_acls', 'customer_role_acls.role_id', 'customer_roles.id')
+        .select([
+          'customer_user_roles.user_id as user_id',
+          'customer_role_acls.features_json as features_json',
+          'customer_role_acls.is_portal_admin as is_portal_admin',
+        ])
+        .where('customer_user_roles.user_id', 'in', roleCandidates)
+        .where('customer_user_roles.deleted_at', 'is', null)
+        .where('customer_roles.tenant_id', '=', scope.tenantId)
+        .where('customer_roles.organization_id', '=', scope.organizationId)
+        .where('customer_roles.deleted_at', 'is', null)
+        .where('customer_role_acls.tenant_id', '=', scope.tenantId)
+        .execute()
+      for (const row of roleAclRows) mergeGrant(roleGrants, row.user_id, row.features_json, row.is_portal_admin)
+    }
+    return candidates.filter((userId) => {
+      const grant = userGrants.get(userId) ?? roleGrants.get(userId)
+      if (!grant) return false
+      return authorizeFeatures([requiredFeature], { grantedFeatures: grant.features, unrestricted: grant.isPortalAdmin })
+    })
+  } catch (err) {
+    if (isPortalTableMissingError(err)) return []
+    throw err
+  }
+}
+
+export async function filterPortalRecipientsByFeature(
+  em: EntityManager,
+  userIds: string[],
+  scope: { tenantId: string; organizationId: string },
+  requiredFeature: string,
+): Promise<string[]> {
+  try {
+    return await filterPortalRecipientsByFeatureStrict(em, userIds, scope, requiredFeature)
+  } catch (err) {
+    logger.warn('Could not resolve portal recipient features; treating the audience as empty', {
+      feature: requiredFeature,
+      err,
+    })
+    reportSwallowedRecipientError(err, 'staff.portal_recipients_feature_filter_failed')
     return []
   }
 }