@open-mercato/documents 0.6.8-develop.7016.1.4ed7b1e49d

package/src/modules/documents/lib/entityRegistry.server.ts

@@ -0,0 +1,267 @@
+import { CrudHttpError, isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import {
+  fetchWithTimeout,
+  type FetchWithTimeoutInit,
+  resolveTimeoutMs,
+  withTimeout,
+} from '@open-mercato/shared/lib/http/fetchWithTimeout'
+import { getSecurityEmailBaseUrl } from '@open-mercato/shared/lib/url'
+import type { DocumentEntityType } from '../data/validators'
+import {
+  getEntityRegistryEntry,
+  readItemsArray,
+  type EntityPickerItem,
+} from './entityRegistry'
+import { isDocumentEntityRegistryModuleEnabled } from './entityRegistryAvailability.server'
+
+export type VerifyEntityRegistrySelectionInput = {
+  entityType: DocumentEntityType
+  entityId: string
+  label: string
+  href: string
+}
+
+export type VerifyEntityRegistryTargetAccessInput = Pick<
+  VerifyEntityRegistrySelectionInput,
+  'entityType' | 'entityId'
+>
+
+export type VerifiedEntityRegistrySelection = EntityPickerItem & {
+  href: string
+  values: Record<string, string | null>
+}
+
+type RegistryFetch = (
+  input: RequestInfo | URL,
+  init?: FetchWithTimeoutInit,
+) => Promise<Response>
+
+const DEFAULT_REGISTRY_LOOKUP_TIMEOUT_MS = 3_000
+const MAX_REGISTRY_RESPONSE_BYTES = 1_000_000
+
+async function readRegistryJsonBody(
+  response: Response,
+  callerSignal: AbortSignal,
+  timeoutMs: number,
+): Promise<unknown> {
+  return withTimeout(async (timeoutSignal) => {
+    const signals = [callerSignal, timeoutSignal]
+    for (const signal of signals) {
+      if (signal.aborted) {
+        throw signal.reason instanceof Error
+          ? signal.reason
+          : new DOMException('Aborted', 'AbortError')
+      }
+    }
+
+    const reader = response.body?.getReader()
+    if (!reader) return null
+    let aborted: unknown = null
+    const listeners = signals.map((signal) => {
+      let handled = false
+      const listener = () => {
+        if (handled) return
+        handled = true
+        aborted = signal.reason instanceof Error
+          ? signal.reason
+          : new DOMException('Aborted', 'AbortError')
+        void reader.cancel(aborted).catch(() => undefined)
+      }
+      signal.addEventListener('abort', listener, { once: true })
+      if (signal.aborted) listener()
+      return { signal, listener }
+    })
+
+    const decoder = new TextDecoder()
+    let decoded = ''
+    let totalBytes = 0
+    try {
+      while (true) {
+        const { done, value } = await reader.read()
+        if (done) break
+        totalBytes += value.byteLength
+        if (totalBytes > MAX_REGISTRY_RESPONSE_BYTES) {
+          await reader.cancel().catch(() => undefined)
+          throw new Error('[internal] Entity registry response exceeded the size limit')
+        }
+        decoded += decoder.decode(value, { stream: true })
+      }
+      if (aborted) throw aborted
+      decoded += decoder.decode()
+    } finally {
+      for (const { signal, listener } of listeners) {
+        signal.removeEventListener('abort', listener)
+      }
+      reader.releaseLock()
+    }
+
+    try {
+      return JSON.parse(decoded) as unknown
+    } catch {
+      return null
+    }
+  }, timeoutMs, 'documents entity-registry response')
+}
+
+function buildForwardedHeaders(request: Request): Headers {
+  const headers = new Headers()
+  const cookie = request.headers.get('cookie')
+  const authorization = request.headers.get('authorization')
+  const apiKey = request.headers.get('x-api-key')
+  if (cookie) headers.set('cookie', cookie)
+  if (authorization) headers.set('authorization', authorization)
+  if (apiKey) headers.set('x-api-key', apiKey)
+  return headers
+}
+
+type RegistryVerificationOptions = {
+  fetchImpl?: RegistryFetch
+  timeoutMs?: number
+  maskTargetAbsence?: boolean
+}
+
+async function verifyEntityRegistryTarget(
+  request: Request,
+  input: VerifyEntityRegistryTargetAccessInput,
+  options: RegistryVerificationOptions = {},
+): Promise<VerifiedEntityRegistrySelection> {
+  const entry = getEntityRegistryEntry(input.entityType)
+  if (!entry) {
+    throw new CrudHttpError(400, { error: 'documents.links.invalidEntityType' })
+  }
+  if (!isDocumentEntityRegistryModuleEnabled(entry)) {
+    throw new CrudHttpError(503, { error: 'documents.links.targetUnavailable' })
+  }
+
+  const timeoutMs = Math.min(
+    resolveTimeoutMs(options.timeoutMs, DEFAULT_REGISTRY_LOOKUP_TIMEOUT_MS),
+    DEFAULT_REGISTRY_LOOKUP_TIMEOUT_MS,
+  )
+  const deadline = Date.now() + timeoutMs
+  let response: Response
+  try {
+    // This request carries the caller's credentials, so its destination must
+    // come from the configured application URL rather than request.url/Host.
+    // getSecurityEmailBaseUrl intentionally has a fixed loopback development
+    // fallback and requires APP_URL in production.
+    const lookupUrl = new URL(entry.searchPath, getSecurityEmailBaseUrl())
+    lookupUrl.searchParams.set('id', input.entityId)
+    lookupUrl.searchParams.set('pageSize', '1')
+    const fetchImpl = options.fetchImpl ?? fetchWithTimeout
+    response = await fetchImpl(lookupUrl, {
+      method: 'GET',
+      headers: buildForwardedHeaders(request),
+      cache: 'no-store',
+      redirect: 'manual',
+      signal: request.signal,
+      timeoutMs,
+    })
+  } catch {
+    throw new CrudHttpError(503, { error: 'documents.links.targetUnavailable' })
+  }
+
+  if (response.status === 404) {
+    throw new CrudHttpError(options.maskTargetAbsence ? 403 : 503, {
+      error: options.maskTargetAbsence
+        ? 'documents.links.targetRestricted'
+        : 'documents.links.targetUnavailable',
+    })
+  }
+  if (response.status >= 500) {
+    throw new CrudHttpError(503, { error: 'documents.links.targetUnavailable' })
+  }
+  if (!response.ok) {
+    throw new CrudHttpError(response.status === 401 ? 401 : 403, {
+      error: 'documents.links.targetRestricted',
+    })
+  }
+
+  let payload: unknown
+  try {
+    payload = await readRegistryJsonBody(
+      response,
+      request.signal,
+      Math.max(1, deadline - Date.now()),
+    )
+  } catch {
+    throw new CrudHttpError(503, { error: 'documents.links.targetUnavailable' })
+  }
+  const rawItem = readItemsArray(payload).find((candidate) => (
+    entry.mapItem(candidate)?.id === input.entityId
+  )) ?? null
+  const mapped = rawItem ? entry.mapItem(rawItem) : null
+  const resolvedHref = mapped ? entry.resolveHref(mapped) : null
+  if (!mapped || !rawItem || !resolvedHref || !entry.isCanonicalHref(mapped, resolvedHref)) {
+    throw new CrudHttpError(options.maskTargetAbsence ? 403 : 400, {
+      error: options.maskTargetAbsence
+        ? 'documents.links.targetRestricted'
+        : 'documents.links.targetMismatch',
+    })
+  }
+  return {
+    ...mapped,
+    href: resolvedHref,
+    values: Object.fromEntries(entry.tokenFields.map((field) => [field.field, field.extract(rawItem)])),
+  }
+}
+
+export async function verifyEntityRegistrySelection(
+  request: Request,
+  input: VerifyEntityRegistrySelectionInput,
+  options: { fetchImpl?: RegistryFetch; timeoutMs?: number } = {},
+): Promise<VerifiedEntityRegistrySelection> {
+  return verifyEntityRegistryTarget(request, input, options)
+}
+
+/**
+ * Verify access to one exact peer record before using its UUID as a reverse
+ * relation filter. Missing and restricted targets intentionally share the same
+ * denial so the Documents collection cannot become a peer-record oracle.
+ */
+export async function verifyEntityRegistryTargetAccess(
+  request: Request,
+  input: VerifyEntityRegistryTargetAccessInput,
+  options: { fetchImpl?: RegistryFetch; timeoutMs?: number } = {},
+): Promise<VerifiedEntityRegistrySelection> {
+  try {
+    return await verifyEntityRegistryTarget(request, input, {
+      ...options,
+      maskTargetAbsence: true,
+    })
+  } catch (error) {
+    if (isCrudHttpError(error) && error.status >= 400 && error.status < 500) {
+      throw new CrudHttpError(403, { error: 'documents.links.targetRestricted' })
+    }
+    throw error
+  }
+}
+
+export async function verifyEntityRegistrySelections(
+  request: Request,
+  inputs: VerifyEntityRegistrySelectionInput[],
+  options: { fetchImpl?: RegistryFetch; concurrency?: number; timeoutMs?: number } = {},
+): Promise<Map<string, VerifiedEntityRegistrySelection>> {
+  const deduped = Array.from(
+    new Map(inputs.map((input) => [`${input.entityType}:${input.entityId}`, input])).values(),
+  )
+  if (deduped.length > 20) {
+    throw new CrudHttpError(400, { error: 'documents.templates.tooManySlots' })
+  }
+
+  const concurrency = Math.max(1, Math.min(4, options.concurrency ?? 4))
+  const verified = new Map<string, VerifiedEntityRegistrySelection>()
+  let nextIndex = 0
+  const workers = Array.from({ length: Math.min(concurrency, deduped.length) }, async () => {
+    while (nextIndex < deduped.length) {
+      const index = nextIndex
+      nextIndex += 1
+      const input = deduped[index]!
+      verified.set(
+        `${input.entityType}:${input.entityId}`,
+        await verifyEntityRegistrySelection(request, input, options),
+      )
+    }
+  })
+  await Promise.all(workers)
+  return verified
+}

package/src/modules/documents/lib/entityRegistry.ts

@@ -0,0 +1,345 @@
+import type { DocumentEntityType } from '../data/validators'
+import {
+  firstSafeDocumentsDisplayLabel,
+  sanitizeDocumentsDisplayLabel,
+} from './displayLabels'
+
+export type { DocumentEntityType } from '../data/validators'
+
+export type EntityPickerItem = {
+  id: string
+  label: string
+  subtitle?: string
+  href?: string
+  archivedAt?: string | null
+}
+
+export type EntityTokenField = {
+  field: string
+  labelKey: string
+  extract: (item: Record<string, unknown>) => string | null
+}
+
+export type EntityRegistryEntry = {
+  type: DocumentEntityType
+  labelKey: string
+  searchPath: string
+  mapItem: (item: Record<string, unknown>) => EntityPickerItem | null
+  href: (id: string) => string
+  tokenFields: EntityTokenField[]
+}
+
+/**
+ * Internal registry contract used by Documents integrations. Keep the
+ * long-standing EntityRegistryEntry shape above assignable for deep-import
+ * consumers while requiring every built-in entry to declare its capability
+ * and canonical-link policy.
+ */
+export type DocumentEntityRegistryEntry = EntityRegistryEntry & {
+  resolveHref: (item: EntityPickerItem) => string | null
+  isCanonicalHref: (item: Pick<EntityPickerItem, 'id' | 'href'>, href: string) => boolean
+  requiredModule: string
+  /**
+   * Module that owns `requiredFeature`. This is usually the same as
+   * `requiredModule`, but catalog offers are rendered by Catalog while their
+   * channel-access feature is owned by Sales. Keeping it explicit lets the
+   * server and ClientBootstrap-backed picker make the same fail-closed choice.
+   */
+  requiredFeatureModule: string
+  requiredFeature: string
+}
+
+function readRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : null
+}
+
+function readString(item: Record<string, unknown>, ...keys: string[]): string | null {
+  for (const key of keys) {
+    const value = item[key]
+    if (typeof value === 'string' && value.trim().length > 0) return value.trim()
+  }
+  return null
+}
+
+/**
+ * Cross-module records are an untrusted display boundary. Their identifiers
+ * remain available to the registry for canonical routing, but a name, status,
+ * SKU, or other rendered value must never fall back to an identifier-shaped
+ * string. Continue through aliases so a malformed preferred field does not
+ * hide a later readable value.
+ */
+function readDisplayString(item: Record<string, unknown>, ...keys: string[]): string | null {
+  return firstSafeDocumentsDisplayLabel(...keys.map((key) => item[key]))
+}
+
+function readNestedString(
+  item: Record<string, unknown>,
+  parentKey: string,
+  ...keys: string[]
+): string | null {
+  const parent = readRecord(item[parentKey])
+  return parent ? readString(parent, ...keys) : null
+}
+
+function readNestedDisplayString(
+  item: Record<string, unknown>,
+  parentKey: string,
+  ...keys: string[]
+): string | null {
+  const parent = readRecord(item[parentKey])
+  return parent ? readDisplayString(parent, ...keys) : null
+}
+
+function readDisplayTextValue(item: Record<string, unknown>, ...keys: string[]): string | null {
+  for (const key of keys) {
+    const value = item[key]
+    const safe = typeof value === 'number' && Number.isFinite(value)
+      ? sanitizeDocumentsDisplayLabel(String(value))
+      : sanitizeDocumentsDisplayLabel(value)
+    if (safe) return safe
+  }
+  return null
+}
+
+function optionalSubtitle(value: string | null): string | undefined {
+  return value ?? undefined
+}
+
+function mapCustomerItem(item: Record<string, unknown>): EntityPickerItem | null {
+  const id = readString(item, 'id')
+  const email = readDisplayString(item, 'email', 'primaryEmail', 'primary_email')
+  const label = readDisplayString(item, 'name', 'displayName', 'display_name') ?? email
+  if (!id || !label) return null
+  return { id, label, subtitle: optionalSubtitle(email) }
+}
+
+function mapDealItem(item: Record<string, unknown>): EntityPickerItem | null {
+  const id = readString(item, 'id')
+  const label = readDisplayString(item, 'title')
+  if (!id || !label) return null
+  return { id, label, subtitle: optionalSubtitle(readDisplayString(item, 'status')) }
+}
+
+function mapProductItem(item: Record<string, unknown>): EntityPickerItem | null {
+  const id = readString(item, 'id')
+  const label = readDisplayString(item, 'title')
+  if (!id || !label) return null
+  return { id, label, subtitle: optionalSubtitle(readDisplayString(item, 'sku')) }
+}
+
+function mapCatalogOfferItem(item: Record<string, unknown>): EntityPickerItem | null {
+  const id = readString(item, 'id')
+  const productId = readString(item, 'productId', 'product_id')
+    ?? readNestedString(item, 'product', 'id')
+  const productTitle = readNestedDisplayString(item, 'product', 'title', 'name')
+  const label = readDisplayString(item, 'title', 'name') ?? productTitle
+  if (!id || !productId || !label) return null
+  const productSku = readNestedDisplayString(item, 'product', 'sku')
+  return {
+    id,
+    label,
+    subtitle: optionalSubtitle(productTitle ?? productSku),
+    href: `/backend/catalog/products/${productId}`,
+  }
+}
+
+function mapSalesDocumentItem(
+  item: Record<string, unknown>,
+  numberKeys: string[],
+): EntityPickerItem | null {
+  const id = readString(item, 'id')
+  const label = readDisplayString(item, ...numberKeys, 'number', 'title')
+  if (!id || !label) return null
+  return { id, label, subtitle: optionalSubtitle(readDisplayString(item, 'status')) }
+}
+
+function mapDocumentItem(item: Record<string, unknown>): EntityPickerItem | null {
+  const id = readString(item, 'id')
+  const label = readDisplayString(item, 'title')
+  if (!id || !label) return null
+  const archivedAt = item.archivedAt ?? item.archived_at
+  return {
+    id,
+    label,
+    archivedAt: typeof archivedAt === 'string' && archivedAt.length > 0 ? archivedAt : null,
+  }
+}
+
+function field(fieldName: string, labelKey: string, keys: string[]): EntityTokenField {
+  return {
+    field: fieldName,
+    labelKey,
+    extract: (item) => readDisplayTextValue(item, ...keys),
+  }
+}
+
+function exactIdPath(pathPrefix: string, id: string): string {
+  return `${pathPrefix}/${id}`
+}
+
+const CATALOG_PRODUCT_HREF_PATTERN =
+  /^\/backend\/catalog\/products\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+function buildIdAddressableEntry(
+  input: Omit<DocumentEntityRegistryEntry, 'resolveHref' | 'isCanonicalHref'>,
+): DocumentEntityRegistryEntry {
+  return {
+    ...input,
+    resolveHref: (item) => input.href(item.id),
+    isCanonicalHref: (item, href) => href === input.href(item.id),
+  }
+}
+
+export function readItemsArray(response: unknown): Record<string, unknown>[] {
+  if (Array.isArray(response)) {
+    return response.map(readRecord).filter((item): item is Record<string, unknown> => item !== null)
+  }
+
+  const record = readRecord(response)
+  const candidates = [record?.items, record?.data]
+  for (const candidate of candidates) {
+    if (Array.isArray(candidate)) {
+      return candidate.map(readRecord).filter((item): item is Record<string, unknown> => item !== null)
+    }
+  }
+  return []
+}
+
+export const DOCUMENT_ENTITY_REGISTRY: DocumentEntityRegistryEntry[] = [
+  buildIdAddressableEntry({
+    type: 'customer-person',
+    labelKey: 'documents.entities.customerPerson',
+    searchPath: '/api/customers/people',
+    mapItem: mapCustomerItem,
+    href: (id) => exactIdPath('/backend/customers/people', id),
+    requiredModule: 'customers',
+    requiredFeatureModule: 'customers',
+    requiredFeature: 'customers.people.view',
+    tokenFields: [
+      field('name', 'documents.entityFields.name', ['name', 'displayName', 'display_name']),
+      field('email', 'documents.entityFields.email', ['email', 'primaryEmail', 'primary_email']),
+      field('phone', 'documents.entityFields.phone', ['phone', 'primaryPhone', 'primary_phone']),
+    ],
+  }),
+  buildIdAddressableEntry({
+    type: 'customer-company',
+    labelKey: 'documents.entities.customerCompany',
+    searchPath: '/api/customers/companies',
+    mapItem: mapCustomerItem,
+    href: (id) => exactIdPath('/backend/customers/companies', id),
+    requiredModule: 'customers',
+    requiredFeatureModule: 'customers',
+    requiredFeature: 'customers.companies.view',
+    tokenFields: [
+      field('name', 'documents.entityFields.name', ['name', 'displayName', 'display_name']),
+      field('email', 'documents.entityFields.email', ['email', 'primaryEmail', 'primary_email']),
+      field('phone', 'documents.entityFields.phone', ['phone', 'primaryPhone', 'primary_phone']),
+    ],
+  }),
+  buildIdAddressableEntry({
+    type: 'deal',
+    labelKey: 'documents.entities.deal',
+    searchPath: '/api/customers/deals',
+    mapItem: mapDealItem,
+    href: (id) => exactIdPath('/backend/customers/deals', id),
+    requiredModule: 'customers',
+    requiredFeatureModule: 'customers',
+    requiredFeature: 'customers.deals.view',
+    tokenFields: [
+      field('title', 'documents.entityFields.title', ['title']),
+      field('status', 'documents.entityFields.status', ['status']),
+      field('value', 'documents.entityFields.value', ['value', 'valueAmount', 'value_amount']),
+      field('valueCurrency', 'documents.entityFields.valueCurrency', ['valueCurrency', 'value_currency']),
+    ],
+  }),
+  buildIdAddressableEntry({
+    type: 'product',
+    labelKey: 'documents.entities.product',
+    searchPath: '/api/catalog/products',
+    mapItem: mapProductItem,
+    href: (id) => exactIdPath('/backend/catalog/products', id),
+    requiredModule: 'catalog',
+    requiredFeatureModule: 'catalog',
+    requiredFeature: 'catalog.products.view',
+    tokenFields: [
+      field('title', 'documents.entityFields.title', ['title']),
+      field('subtitle', 'documents.entityFields.subtitle', ['subtitle']),
+      field('sku', 'documents.entityFields.sku', ['sku']),
+    ],
+  }),
+  {
+    type: 'catalog-offer',
+    labelKey: 'documents.entities.catalogOffer',
+    searchPath: '/api/catalog/offers',
+    mapItem: mapCatalogOfferItem,
+    href: () => '',
+    resolveHref: (item) => {
+      const href = item.href ?? null
+      return href && CATALOG_PRODUCT_HREF_PATTERN.test(href) ? href : null
+    },
+    isCanonicalHref: (item, href) => Boolean(item.href && href === item.href && CATALOG_PRODUCT_HREF_PATTERN.test(href)),
+    requiredModule: 'catalog',
+    requiredFeatureModule: 'sales',
+    requiredFeature: 'sales.channels.manage',
+    tokenFields: [
+      field('title', 'documents.entityFields.title', ['title', 'name']),
+      field('description', 'documents.entityFields.description', ['description']),
+    ],
+  },
+  buildIdAddressableEntry({
+    type: 'quote',
+    labelKey: 'documents.entities.quote',
+    searchPath: '/api/sales/quotes',
+    mapItem: (item) => mapSalesDocumentItem(item, ['quoteNumber', 'quote_number']),
+    href: (id) => exactIdPath('/backend/sales/quotes', id),
+    requiredModule: 'sales',
+    requiredFeatureModule: 'sales',
+    requiredFeature: 'sales.quotes.view',
+    tokenFields: [
+      field('number', 'documents.entityFields.number', ['quoteNumber', 'quote_number', 'number']),
+      field('status', 'documents.entityFields.status', ['status']),
+      field('total', 'documents.entityFields.total', ['grandTotalGross', 'grand_total_gross', 'total']),
+      field('currency', 'documents.entityFields.currency', ['currencyCode', 'currency_code']),
+    ],
+  }),
+  buildIdAddressableEntry({
+    type: 'sales-order',
+    labelKey: 'documents.entities.salesOrder',
+    searchPath: '/api/sales/orders',
+    mapItem: (item) => mapSalesDocumentItem(item, ['orderNumber', 'order_number']),
+    href: (id) => exactIdPath('/backend/sales/orders', id),
+    requiredModule: 'sales',
+    requiredFeatureModule: 'sales',
+    requiredFeature: 'sales.orders.view',
+    tokenFields: [
+      field('number', 'documents.entityFields.number', ['orderNumber', 'order_number', 'number']),
+      field('status', 'documents.entityFields.status', ['status']),
+      field('total', 'documents.entityFields.total', ['grandTotalGross', 'grand_total_gross', 'total']),
+      field('currency', 'documents.entityFields.currency', ['currencyCode', 'currency_code']),
+    ],
+  }),
+  buildIdAddressableEntry({
+    type: 'document',
+    labelKey: 'documents.entities.document',
+    searchPath: '/api/documents',
+    mapItem: mapDocumentItem,
+    href: (id) => exactIdPath('/backend/documents', id),
+    requiredModule: 'documents',
+    requiredFeatureModule: 'documents',
+    requiredFeature: 'documents.view',
+    tokenFields: [
+      field('title', 'documents.entityFields.title', ['title']),
+    ],
+  }),
+]
+
+export function getEntityRegistryEntry(type: string): DocumentEntityRegistryEntry | null {
+  return DOCUMENT_ENTITY_REGISTRY.find((entry) => entry.type === type) ?? null
+}
+
+export function getEntityTokenFieldNames(type: DocumentEntityType): Set<string> {
+  const entry = getEntityRegistryEntry(type)
+  return new Set(entry?.tokenFields.map((tokenField) => tokenField.field) ?? [])
+}

package/src/modules/documents/lib/entityRegistryAvailability.server.ts

@@ -0,0 +1,19 @@
+import { getEnabledModuleIds } from '@open-mercato/shared/security/enabledModulesRegistry'
+import type { DocumentEntityRegistryEntry } from './entityRegistry'
+
+/**
+ * Returns whether the peer module backing a Documents entity-registry entry
+ * is enabled in the running application.
+ *
+ * The bootstrapped module registry is the canonical server-side source. An
+ * empty/unavailable registry therefore fails closed for peer-backed entries;
+ * stale ACL grants (including superadmin wildcards) must never make a disabled
+ * module addressable through Documents.
+ */
+export function isDocumentEntityRegistryModuleEnabled(
+  entry: Pick<DocumentEntityRegistryEntry, 'requiredModule' | 'requiredFeatureModule'>,
+): boolean {
+  const enabledModuleIds = new Set(getEnabledModuleIds())
+  return enabledModuleIds.has(entry.requiredModule)
+    && enabledModuleIds.has(entry.requiredFeatureModule)
+}

package/src/modules/documents/lib/entitySuggestion.ts

@@ -0,0 +1,61 @@
+import { Extension, type Editor } from '@tiptap/core'
+import { Suggestion, type SuggestionProps } from '@tiptap/suggestion'
+import type { EntityRefAttributes } from './editorConfig'
+
+type EntitySuggestionHandlers = {
+  onTrigger: (ctx: { query: string; range: { from: number; to: number } }) => void
+  onClose: () => void
+}
+
+function notifyTrigger(
+  handlers: EntitySuggestionHandlers,
+  props: Pick<SuggestionProps<unknown, unknown>, 'query' | 'range'>,
+): void {
+  handlers.onTrigger({
+    query: props.query,
+    range: {
+      from: props.range.from,
+      to: props.range.to,
+    },
+  })
+}
+
+export function createEntitySuggestionExtension(handlers: EntitySuggestionHandlers): Extension {
+  return Extension.create({
+    name: 'entitySuggestion',
+    addProseMirrorPlugins() {
+      return [
+        Suggestion<unknown, unknown>({
+          editor: this.editor,
+          char: '@',
+          allowSpaces: false,
+          startOfLine: false,
+          items: () => [],
+          command: () => undefined,
+          render: () => ({
+            onStart: (props) => notifyTrigger(handlers, props),
+            onUpdate: (props) => notifyTrigger(handlers, props),
+            onExit: () => handlers.onClose(),
+          }),
+        }),
+      ]
+    },
+  })
+}
+
+export function insertEntityRef(editor: Editor, attrs: EntityRefAttributes): boolean {
+  return editor
+    .chain()
+    .focus()
+    .insertContent([
+      {
+        type: 'entityRef',
+        attrs,
+      },
+      {
+        type: 'text',
+        text: ' ',
+      },
+    ])
+    .run()
+}